InSoulForge

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

QQ 交流群：1097487360

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

• Web 管理后台 - 可视化管理会话、模型、提示词与工具配置
• 自定义角色 - 通过提示词定制机器人的人设与性格，支持为各群聊设置附加提示词
• Jev 决策与智能回复 - 可选用 Jev 专用结构化决策模型快速判断是否回复，减少高频判断对聊天模型的依赖；低置信度或请求失败时由 Router LLM 兜底，再由 Executor 生成回复与调用工具
• 智能记忆 - 自动提取群友喜好与重要事件，并根据互动更新好感度；可选配 Embedding 模型，按语义相似度召回长期记忆，减少对完整聊天记录的依赖
• 图片识别 - 可单独配置视觉模型识别图片与 GIF 动图，媒体哈希缓存避免重复请求
• 图片生成与编辑 - 统一使用 generate_image，支持文字生图、多张会话图片参考或编辑，也可同时附加上传的角色形象图；任务在后台执行，完成后自动发送到当前会话
• 多条回复与深度思考 - 一次对话可连续发送多条消息，耗时操作前可先发过程消息，复杂问题按需调用深度思考模型
• 跨会话发送 - reply_and_continue 与 send_sticker 支持可选 group_id（群号）或 user_id（私聊 QQ 号），向后台已启用的群或私聊发送消息、表情；两者互斥，均省略则发送到当前会话，与跨会话共享开关无关
• 自定义工具 - 使用 Lua 脚本与异步 HTTP 请求扩展能力，支持可视化配置及导入导出
• MCP 工具 - 支持接入 HTTP MCP 服务，由模型按需查询并启用远程工具
• 适配 QQ 功能 - Bot 可自行收藏发送表情包、引用、@ 群友、撤回消息、拍一拍、禁言，并按规则将用户加入全局黑名单
• 定时与后台任务 - 支持定时触发消息处理，以及图片生成等耗时任务，后台执行完成后发送结果

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

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

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

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

镜像已发布至 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：按工具提示先提醒用户；若其之后仍继续同类恶意行为， 再将其加入全局黑名单并告知结果。该提醒顺序目前由模型依据聊天记录判断，后端会校验目标是否出现在当前会话记录中， 并拒绝拉黑管理员和机器人自身。黑名单对所有会话生效。

qq.defaultPrivateEnabled 保存后立即对新私聊生效，不改变已有会话的启用或禁用状态； 已有私聊可在「会话管理」中单独启用。私聊直接进入回复生成，不经过 Router，也不附加 Router 回复策略。

各模型可分别配置：

Jev 路由：Jev 是 TypeSafe 的 System One 结构化决策模型， 不生成聊天正文，而是返回选项、概率分布和置信度。InSoulForge 将其用于高频回复判断，不确定时再交给 Router LLM， 使决策与回复生成分工处理；实际延迟与成本收益取决于消息量、阈值及兜底比例。

在「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 只处理通过硬规则的群聊消息；私聊直接进入 Executor，群内 @机器人和系统任务沿用原有处理。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 不保存管理后台访问令牌。请通过服务启动日志获取当前令牌，不要将其提交到仓库或发送给无关人员。

每个模型都可以独立配置「请求超时（秒）」和「失败重试次数」，对应 timeoutSeconds（1～3600 的整数）与 maxRetries（0～10 的整数）。重试次数不包含首次请求，0 表示不重试；每次尝试独立计时，重试间隔 1 秒。 默认保持原有行为：回复决策、回复生成、备用模型与深度思考为 90 秒、重试 3 次；图片识别为 90 秒、不重试； 记忆维护和图片生成为 180 秒、不重试；向量化为 30 秒、不重试；Jev 为 10 秒、不重试。 只重试网络请求失败与 HTTP 429、500、503，不重试其他状态码或成功响应中的格式错误。 前端保存后对后续请求立即生效，已经开始的请求及其重试使用原配置。参数不发送给模型服务，也不会覆盖服务端或代理的超时限制。 生图超时不代表服务端未生成，开启重试可能重复生成并计费。主回复模型尝试耗尽后才使用备用模型，备用模型使用自身的超时与重试配置。

深度思考：Executor思考 不是全局思考模式开关，而是 deep_think 工具使用的模型配置。Executor 只有在遇到数学计算、多步推理、技术分析等复杂问题时才会按需调用，日常闲聊不会固定走推理模型。 该工具只接收 question 中明确提供的问题、必要条件和相关资料，不会自动发送完整聊天上下文。

管理后台的“执行配置”页统一管理回复执行流程参数。最大迭代轮数默认 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
• 每会话共享消息数 - Executor 从每个其他参与共享的会话读取的近期消息数，默认 10，可在「记忆与上下文」调整
• 总结触发条数 - 消息预处理完成后，完整消息列表达到或超过该数量时触发一批记忆维护，默认 100
• 每批总结条数 - 本批参与记忆提取与好感度评估，并在全部处理成功后移除的最旧消息数，默认 50，不能超过触发条数
• 总结补充上下文条数 - 紧随总结批次的只读消息数，仅帮助模型理解语境，不参与提取或删除，默认 10
• Memory 模型 maxTokens - 在「LLM 配置 → Memory」设置记忆提取与整理的输出 token 上限，默认 4000；旧配置会自动迁移
• Jev 窗口条数 - 每次取最近 N 条消息判断是否回复，默认 10 条，逐条滑动；保存后热更新，实际范围受近期上下文上限限制
• Router 窗口触发/保留条数 - Router 使用的子窗口滑动参数，默认 20/10，用于平衡路由 prompt 长度与缓存命中
• 长期记忆召回阈值 - 新记忆与已有长期记忆合并去重时的相似度阈值，默认 0.65
• 长期记忆注入阈值 - 消息预处理时被动召回并注入当前消息的相似度阈值，默认 0.45

记忆总结与好感度评估在后台异步执行，同一会话同时只处理一批。两者全部成功后统一保存结果，再从完整消息列表移除对应的旧消息；失败时保留消息，等待后续消息触发重试。维护任务本身不持久化，程序重启后也会在收到新消息时重新检查是否需要总结。

会话记忆只保留按 QQ 归属的外号 aliases，不再生成近期事件总结。已有外号保留并合并，有明确纠正时更新。 每批先提取人物待整理条目和好感度；再用新条目召回本会话相关长期记忆，与已有外号一起整理。 整理结果包含完整外号列表和本批新旧材料的完整长期记忆条目。新条目全部完成向量化后，在同一事务内写入结果并删除参与整理的旧记忆，未召回的旧条目不受影响。 没有新条目和历史待迁移内容时跳过第二次整理请求；任一步失败都不提交本批结果。 旧 recent_events、legacy_entries、纯文本及字符串数组作为本会话历史待整理内容，成功写入长期记忆后才清除，不再直接注入上下文。 未配置向量服务时仍可更新外号；历史内容保留，等待配置后迁移。后台的「会话外号」沿用原编辑接口，兼容显示尚未迁移的历史字段。 不再使用短期记忆条数上限；旧配置 shortTermMemoryMax 会自动移除，模型输出 token 上限等其他配置不变。 此流程不改变全局人物档案的每日整理和好感度规则。

群聊与私聊在同一次模型调用中提取按 QQ 归属的人物记忆和好感度变化，两类结果相互独立。人物档案与好感度全局共用，不受「跨会话共享」开关限制； 该开关只控制原始近期聊天消息。旧会话好感度升级时按 QQ 取已有分数的平均值并四舍五入，之后统一累计。 人物记忆先追加到 pending_entries（包含来源和 UTC 写入时间）。每天按服务器本地时区在凌晨 03:00 开始， 使用 Memory 模型逐人整理有新条目的人，更新人物档案 profile、与机器人的关系 relationship 和近期互动 recent_interactions。 人物档案合并事实、偏好及有依据的印象；关系记录熟悉程度、相处方式与重要关系经历；近期互动只保留值得跟进的事项，避免聊天流水账。 三类记忆去重并按明确证据修正，近期事项逐步遗忘，不设固定天数；每日任务不会为没有新条目的人额外调用模型。 整理成功后仅删除本次快照中的条目，期间新增的条目保留；失败不覆盖原档案、不删除条目，继续处理其他人，留到下一日再试。 每日执行状态持久化，停机错过后启动补跑一次，中断的一轮可恢复；首次启动在当天 03:00 前等待、之后立即执行。 数据库自动升级至 v24；旧固定记忆（或人物档案）、关系和近期互动逐条移入待整理区，原文保留，旧分类清空，已有待整理条目和好感度不变。之后由每日或手动整理按新规则重新归类。 历史迁移条目的来源标为「历史记忆迁移」，时间为入队时间，不代表事件发生时间；迁移仅执行一次。 调度每分钟检查一次，开始时间可能延后不足一分钟。Docker 使用容器内时区，请按需要配置 TZ。 后台「人物信息」可按昵称或 QQ 搜索、查看和编辑档案、关系、近期互动、待整理条目及全局好感度。 点击当前人物的「立即整理」可立即重新整理现有档案，即使没有待整理条目也可执行；与每日任务互斥，不改变每日执行标记。失败或人工编辑冲突时保留原数据。 缺失昵称在后台最多四路并发查询，单次超时 5 秒、失败冷却 60 秒；列表和详情不等待查询，页面每 2 秒更新进行中的昵称，离开页面后停止轮询。 Executor 仅加载 recent_messages 中真实发送者的档案，按 QQ 去重，排除机器人、系统和仅被提及的人；全部待整理条目也可立即使用。 人物记忆及共享会话消息放在当前会话的最近消息之前，回复要求放在最后；一次回复期间上下文保持冻结，执行状态临时追加在工具历史末尾。 会话总结复用原整理请求，长期记忆仍只依据原有新人物记忆和召回材料处理，因此联合提取之后仍有整理请求，必要时还有向量请求，并非整批维护只调用一次模型。

「会话管理」中的「跨会话共享」默认关闭，群聊与私聊均可独立开启。只有已启用且开启共享的会话才互相提供、接收近期消息，排除当前会话。 共享内容来自尚未总结移除的运行时聊天记录，只取三天内的消息，每条消息所有段的可读内容合计最多 200 个 Unicode 字符，超出用 truncated 标记。 Executor 在一次回复开始时把这些见闻冻结到 shared_conversations，不附带消息 ID、引用目标、图片索引、工具执行历史或召回记忆，也不共享发送失败和内部系统记录。 不设置额外的全局上下文预算，请按模型容量自行控制参与会话和每会话条数；私聊开启后，其近期聊天内容同样会提供给其他参与会话。 模型也可通过 get_group_messages(group_id) 主动查询任意已启用群的全部内存消息，不受共享开关、自动共享条数或三天范围限制；每条仍按共享格式截断至 200 个 Unicode 字符，不查询数据库或平台历史。可在“工具配置”中关闭此工具以禁止主动查询。

图片生成等后台耗时任务与记忆维护相互独立，同一会话同时只允许一个耗时任务。任务完成后向原会话发送结果，并通过系统消息触发后续回复；执行或发送失败也通过系统消息交由机器人处理。运行中的任务不会在程序重启后恢复。

generate_image 的必填参数为 prompt，可选 size（默认 2048x2048）、use_self_reference（默认关闭）和 reference_images。参考图数组中的每项为 {"message_id":"消息ID","image_index":0}，只能引用当前会话的图片， 按数组顺序提交且重复引用自动去重。开启角色参考时，后台角色形象图放在第一张，其后附加聊天参考图；任何参考图读取失败都会终止任务，不会忽略原图直接生图。 参考图数量受所配置上游接口的支持范围限制。原 edit_image 工具已合并到 generate_image。

在“模型配置 → 图片生成”选择接口类型：OpenAI / CLIProxyAPI 无参考图时调用生成路径（默认 /images/generations）， 有参考图时调用编辑路径（默认 /images/edits），通过 JSON 的 images[].image_url 发送原图；OpenRouter 使用同一生成路径 （通常为 /images），参考图通过 input_references 发送。Base URL 已包含 /v1 时，路径不再重复添加该前缀。 新配置默认使用 OpenAI；升级时已有配置保留 OpenRouter 请求格式，需要在后台手动切换。配置保存后生效，已启动任务仍使用其读取到的配置。

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

支持通过 Lua 脚本扩展机器人能力：

1. 进入管理后台 → 自定义工具
2. 点击"添加工具"或"导入"
3. 填写工具名称、描述、参数定义和 Lua 脚本；网络请求可使用 Lua 的 http.request()
4. 保存并启用

工具支持：

• 参数定义 - JSON Schema 格式，LLM 自动理解
• Lua 脚本 - 在进程内运行，可调用受控的消息发送与会话后台任务接口，不必重新编译主程序
• 异步 HTTP - Lua 脚本通过 http.request() 调用外部服务
• 说明文档 - Markdown 格式，记录作者、用法、联系方式
• 导入导出 - JSON 文件格式，方便分享

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

导入方法：

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

以上工具均为可导入的 Lua 自定义工具，无需修改或重新编译主程序。 DeepSeek 工具导入后需在脚本顶部填写 api_key，不依赖 PageWeave；单次输出最多 20000 个字符，超出会截断并提示。 详见 DeepSeek 工具说明。

PageWeave 网页读取和搜索工具使用 Lua 异步请求，默认连接 http://172.31.100.240:7779/extract； 可修改脚本中的 endpoint 调整地址。缺少协议的网址自动补全 https://，其他协议会被拒绝。运行环境不需要 Python。 已有同名工具需编辑更新或删除后重新导入，仓库文件不会自动覆盖 data/tools/ 里的脚本。参数和运行说明见工具文档。

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

配置后，本批待整理条目与召回的长期记忆合并后自动向量化入库；每条消息入库时后台召回相关长期记忆并注入回复上下文，也可通过 recall_memory 工具按余弦相似度主动查询。未配置时长期记忆停用，外号仍可更新，历史待迁移内容保留。

当自动图片描述不足以回答细节问题时，Executor 可调用 ask_images，将具体问题与真实图片一起发送给“图片识别”模型。 必填参数为 question 和非空的 images 数组，每项为 {"message_id":"消息ID","image_index":0}，支持当前会话的多图比较、文字提取与 GIF 抽帧问答。 该工具不附带完整聊天上下文，不复用或覆盖通用图片描述缓存；答案返回 Executor，不直接发送消息。图片失效或模型不可用时明确返回错误，不以原有描述代替看图。

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

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

通过 HTTP MCP 服务按需选择远程工具，而非一次向模型发送全部工具；服务用途描述在“MCP 服务”页编辑， 查询分页、单次启用和本次回复启用上限在“执行配置”页设置。配置与限制见 MCP 客户端文档。默认不启用外部服务。

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

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

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

详见 LICENSE。