InSoulForge

一个基于 Agent 架构的智能 QQ 群聊机器人后端。

QQ 交流群：1097487360

本项目采用 OneBot 协议标准，不包含任何聊天平台协议的具体实现，也不提供任何连接聊天平台的方法。使用本项目时，您仅可使用合法合规的 OneBot 实现。使用本项目即表示您已阅读、理解并同意：由此产生的一切后果及风险均由您自行承担，本项目不承担任何责任。

✨ 特性

• Web 管理后台 - 可视化查看与配置
• 智能对话 - Jev 可选地优先判断群聊是否回复，低置信度时由 Router LLM 兜底，再由 Executor 生成回复
• 好感度 - 可以根据对话自动调整对某人的好感度
• 图片识别 - 可单独配置视觉模型识别图片与 GIF 动图，媒体哈希缓存避免重复请求
• 自定义角色 - 可设置 Bot 的提示词来定制人设和性格
• 稳定上下文快照 - 每条消息在完成媒体识别与记忆召回后生成冻结快照，保证 Router 和 Agent 使用一致的上下文
• 智能记忆 - 记忆自动提炼，记住群友的喜好、习惯、重要事件
• 长期记忆召回 - 长期记忆本地向量化（SQLite 存储 + 余弦相似度检索），自动召回相关记忆注入回复上下文，也可主动查询，可选配
  Embedding 模型
• 适配 QQ 功能 - Bot 可自行收藏发送表情包、引用、@ 群友、撤回消息、拍一拍、禁言，并按规则将用户加入全局黑名单
• 多条回复与深度思考 - 一次对话可连续发送多条消息，耗时操作前可先发过程消息，复杂问题按需调用深度思考模型
• 自定义工具 - 支持 Lua 模组、Python 脚本和 HTTP 接口，可视化配置与脚本导入导出
• 定时任务 - 提供低耦合的定时任务功能，可定时发送消息以及与自定义工具组合使用

🚀 快速开始

全新 Ubuntu 系统可参考完整 Docker 部署教程，包含 Docker 安装、NapCat 登录、OneBot 配置、备份和更新步骤。

前置要求

本机器人需配合 OneBot 协议实现使用。可使用 NapCat 等 OneBot 实现（本项目仅将其作为示例，不对其合法性、合规性作任何保证；如您认为其不合法合规，请自行更换其他合法合规的实现）。

请确保所选 OneBot 实现合法合规，并启用 HTTP 或正向 WebSocket 服务之一。

InSoulForge 的 HTTP 服务端口为 7778，用于访问管理后台；使用 OneBot HTTP 模式时，也通过该端口接收消息上报。使用正向 WebSocket 模式时，InSoulForge 主动连接 OneBot 的 WebSocket 服务，无需配置 HTTP 上报地址。

方式一：Docker 部署（推荐）

镜像已发布至 Docker Hub 和 GitHub Container Registry，支持 amd64 / arm64 架构：

Docker Hub （推荐，可配置国内镜像加速）

docker pull dreamdonghao/insoulforge:latest

GitHub Container Registry （备用）

docker pull ghcr.io/dreamdonghao/insoulforge:latest

创建宿主机数据目录并启动容器：

sudo mkdir -p /opt/insoulforge/data

docker run -d --name insoulforge \
  -p 7778:7778 \
  -v /opt/insoulforge/data:/app/data \
  dreamdonghao/insoulforge:latest

配置文件、数据库等数据保存在宿主机的 /opt/insoulforge/data 目录中，不受执行命令所在目录影响。
首次启动会自动创建 /opt/insoulforge/data/config.json，对应容器内的 /app/data/config.json。
删除容器不会删除宿主机数据目录。更新前建议备份该目录，不要删除其中的数据。

更新镜像时，停止并删除旧容器，再挂载同一个宿主机数据目录创建新容器：

docker pull dreamdonghao/insoulforge:latest
docker stop insoulforge
docker rm insoulforge
docker run -d --name insoulforge \
  -p 7778:7778 \
  -v /opt/insoulforge/data:/app/data \
  dreamdonghao/insoulforge:latest

如果旧容器使用了自定义网络、端口或其他启动参数，重建时也要保留这些参数。
已部署的用户，更新时应继续使用原来的数据挂载路径；不要直接改为上述示例路径，否则程序可能读取到一份空数据。

如果 napcat 也运行在 Docker 中，注意容器内的 127.0.0.1 指向容器自身。启动后让两个容器加入同一个 docker
网络，然后用容器名互访（无需重建容器，connect 直接生效）：

docker network create bot-net
docker network connect bot-net napcat       # napcat 换成你的 napcat 容器名
docker network connect bot-net insoulforge

使用 HTTP 时，在管理后台将 OneBot 的 HTTP 服务地址填为 http://napcat:3000（容器名 + napcat HTTP 端口），
并将 napcat 的上报地址填为 http://insoulforge:7778/。使用正向 WebSocket 时，将 WebSocket 地址填为
ws://napcat:3001；此方式不需要配置 HTTP 上报地址。

服务启动日志会输出本机可用地址的自动登录链接，例如：

管理后台自动登录链接（重启后失效）: http://127.0.0.1:7778/index.html#token=<token>

直接打开链接即可登录；令牌位于 URL 片段中，不会发送到服务端，验证后会自动从地址栏清除。令牌仅保存在运行中的进程内，不会写入配置文件或数据库；每次重启服务都会生成新的令牌并使已有登录会话失效。在
Docker 默认桥接网络中，容器无法枚举宿主机局域网地址；可将链接中的主机替换为宿主机 LAN IP 后访问。

首次配置

在管理后台完成以下配置：

1. OneBot 配置 - 填写连接参数

   • Access Token
   • Bot QQ 号
   • HTTP 或 WebSocket 传输方式及其服务地址
   • Bot 名称

2. LLM 配置 - 配置模型 API

   • Router、Executor、Executor 思考和 Image 使用兼容 OpenAI 的聊天接口；Embedding 使用向量接口
   • 可选配置 Jev 决策接口，用于群聊优先路由

3. 启用群聊 - 添加要启用的 QQ 群或用户

📖 使用指南

推荐使用web页面进行配置

群聊命令

在群中 @机器人 发送命令（私聊无需 @，直接发送即可）：

命令支持中文别名，如 /帮助、/状态、/启用。

除管理员命令和后台管理外，Executor 也能调用 add_to_blacklist：按工具提示先提醒用户；若其之后仍继续同类恶意行为，
再将其加入全局黑名单并告知结果。该提醒顺序目前由模型依据聊天记录判断，后端会校验目标是否出现在当前会话记录中，
并拒绝拉黑管理员和机器人自身。黑名单对所有会话生效。

⚙️ 配置说明

OneBot 配置

LLM 配置

各模型可分别配置：

Jev 路由：在「LLM 配置 → Jev」填写 API Key、Base URL、Path 和 Model 后启用；默认地址为
https://openrouter.ai/api/alpha、路径为 /decisions、模型为 ~typesafe/jev-latest。Jev 使用
Decisions API，并非 OpenAI 兼容的聊天接口。默认 API Key 为空，因此不启用 Jev，原有 Router 行为不变。
Jev 只处理通过硬规则的群聊消息；私聊、@机器人和系统任务沿用原有处理。Jev 返回的
answers.action.confidence 低于「最低置信度」（默认 0.60）、缺失或无效，或判断结果为 unclear、请求失败时，
再调用 Router LLM。这里比较的是 confidence，不是 probabilities.reply；保存阈值后立即生效。

全局运行配置保存在 data/config.json，包括 LLM、OneBot、记忆与执行参数。文件不存在时程序会写入默认内容；缺失或类型错误的字段会在启动时自动修复。配置文件已被
Git 忽略，Docker 部署时通过 /opt/insoulforge/data:/app/data 挂载宿主机数据目录即可持久化。

config.json 不保存管理后台访问令牌。请通过服务启动日志获取当前令牌，不要将其提交到仓库或发送给无关人员。

深度思考：Executor思考 不是全局思考模式开关，而是 deep_think 工具使用的模型配置。Executor
只有在遇到数学计算、多步推理、技术分析等复杂问题时才会按需调用，日常闲聊不会固定走推理模型。

执行参数

管理后台的“执行配置”页统一管理回复执行流程参数。目前提供“最大迭代轮数”，默认 8，范围为 1～100 的整数，
对应配置文件的 execution.maxToolRounds。每轮包含一次 Executor 模型请求及其工具调用处理，同轮多个工具只计一轮；
最终生成回复也占一轮。达到上限仍未产生回复时，记录错误并结束本次回复流程。

每轮模型请求末尾附带当前轮次和本轮之后的剩余轮数，帮助模型安排查询和收尾；该状态不写入聊天记录。
最后一轮只开放 reply、reply_with_quote、no_reply 回复工具，非回复工具即使被模型返回也不会执行。
上限设为 1 时，首轮就只允许回复工具。

助手上下文还保留按顺序排列的工具名、参数和处理状态。no_reply 也会保存一条内部执行记录，
不会发送到 QQ 或触发新回复；执行、发送失败会单独标记。工具历史供后续 Executor 参考，不保存完整工具结果。
reply、reply_with_quote 不重复写入工具历史，已发送正文及引用目标仍保留在助手消息中。

保存后无需重启，对后续启动的回复流程生效；正在运行的流程继续使用启动时的上限。旧配置文件启动时自动补默认值，
手动写入的小数或越界值会恢复为 8 并写回文件。

记忆与上下文参数

• 近期上下文上限 - Router 与 Agent 实际可见的最近完整消息数，默认 100
• 总结触发条数 - 完整消息列表达到该数量时创建一批会话派生状态维护任务，默认 100
• 每批总结条数 - 本批真正参与记忆提取、并在记忆任务成功后删除的最旧消息数，默认 50，不能超过触发条数
• 总结补充上下文条数 - 紧随总结批次的只读消息数，仅帮助模型理解语境，不参与提取或删除，默认 10
• Memory 模型 maxTokens - 在「LLM 配置 → Memory」设置记忆提取与整理的输出 token 上限，默认 4000；旧配置会自动迁移
• Router 窗口触发/保留条数 - Router 使用的子窗口滑动参数，默认 20/10，用于平衡路由 prompt 长度与缓存命中
• 短期记忆上限 - 每次归类整理后保留的短期记忆条数上限，默认 15
• 长期记忆召回阈值 - 新记忆与已有长期记忆合并去重时的相似度阈值，默认 0.65
• 长期记忆注入阈值 - 消息预处理时被动召回并注入当前消息的相似度阈值，默认 0.45

记忆总结与好感度更新会作为独立的持久化任务异步执行。只有记忆任务成功后，对应的旧消息才会从完整消息列表移除；任务可在程序重启后恢复。

另有会话级后台耗时任务框架，目前仅提供用于明确测试的 demo_async_task，尚未接入生图。它与上述维护任务不同：同一会话一次只执行一个，完成后主动向原会话发送结果，重启后不会恢复。

提示词定制

在管理后台可修改 Router 与 Executor 的系统提示词，支持 {botName} 占位符自动替换。

🔧 高级功能

自定义工具

支持通过 Lua 脚本、Python 脚本或 HTTP 接口扩展机器人能力：

1. 进入管理后台 → 自定义工具
2. 点击"添加工具"或"导入"
3. 填写工具名称、描述、参数定义和执行方式（Lua / Python / HTTP）
4. 保存并启用

工具支持：

• 参数定义 - JSON Schema 格式，LLM 自动理解
• Python 脚本 - 通过 sys.argv[1] 接收参数 JSON 文件路径，可自定义 Python 解释器路径
• Lua 脚本 - 在进程内运行，可调用受控的消息发送与会话后台任务接口，不必重新编译主程序
• HTTP 接口 - 配置请求地址、方法、参数模板
• 说明文档 - Markdown 格式，记录作者、用法、联系方式
• 导入导出 - JSON 文件格式，方便分享

内置工具配置文件

项目提供了一些常用工具配置，位于 agentTools/ 目录：

导入方法：

1. 管理后台 → 自定义工具 → 导入
2. 上传 JSON 文件

网页读取和搜索工具仅使用 Python 标准库，默认连接 http://172.31.100.240:7779/extract；
可通过机器人进程的 PAGEWEAVE_URL 环境变量或脚本中的默认地址调整。缺少协议的网址自动补全 https://，
其他协议会被拒绝。Docker 运行镜像包含 python3，默认解释器配置即可使用；本地运行时需自行安装 Python 3。
已有同名工具需编辑更新或删除后重新导入，仓库文件不会自动覆盖数据库里的脚本。参数和运行说明见工具文档。

配置 Embedding（可选）

1. 准备 OpenAI 兼容的 Embedding 服务（如硅基流动、OpenAI）
2. 管理后台 → LLM配置 → Embedding，填写 API 配置

配置后，短期记忆迁移到长期记忆时自动向量化入库；每条消息入库时后台召回相关长期记忆并注入回复上下文，也可通过
recall_memory 工具按余弦相似度主动查询。未配置时长期记忆自动停用，仅保留短期记忆。

图片与动图识别

图片识别会先下载媒体并按 SHA-256、视觉模型和提示词版本查询缓存。静态图片以 Base64 Data URL 提交视觉模型；GIF 会按播放时间抽取最多
16 帧并一次性提交，超过 16 帧时保留首尾帧并均匀取样。消息和 Agent 上下文只保留识别结果，不会包含图片 URL 或 Base64 内容；管理员可用
/clearimagecache 清除描述缓存。

🛠️ 开发者指南

本项目使用 C++ 实现，Web 页面使用 Vue 3。

本地构建、架构和调试见 开发文档；提交 Issue 或 Pull Request
前请阅读 参与贡献指南。

贡献者

项目由 DreamDonghao 发起，感谢所有参与开发和改进的贡献者。

📄 许可证

本项目采用标准 GNU Affero General Public License v3.0（AGPL-3.0-only）开源。

详见 LICENSE。