InSoulForge 是一个通过 OneBot 协议接入消息服务的开源 AI 聊天机器人后端，采用 C++23、Drogon 和 Vue 3 构建。它整合了回复决策、对话生成、记忆管理与工具调用，并提供 Web 管理后台和 Docker 镜像，适合需要自行部署和扩展的多人聊天智能体场景。
其中一个值得关注的设计是Jev 结构化决策与 LLM 执行相结合：将高频的“是否需要回复”判断交给专门的决策模型，不确定时再由聊天模型处理，而不是让主力模型承担每一次判断。
项目地址：DreamDonghao/insoulforge
OneBot 接入与平台适配
InSoulForge 通过 OneBot 实现接收事件、调用消息接口，自身不实现聊天平台的底层协议。当前支持 OneBot HTTP 和正向 WebSocket 两种连接方式。
QQ 群聊与私聊是目前已有较多功能适配的使用场景，但 OneBot 接入协议与具体聊天平台是两个层次。对于其他合法合规的 OneBot 实现，需要评估其事件格式、消息接口和权限模型是否兼容，再决定是否接入。“支持 OneBot”不意味着已经适配所有平台。
收藏表情、拍一拍、群成员禁言等能力具有平台特性，实际可用性取决于所选 OneBot 实现及账号权限。部署者应自行确认平台规则、接口授权和数据处理要求。
核心能力概览
| 能力 | 主要用途 |
|---|---|
| Jev 决策与 LLM 兜底 | 专用决策模型优先判断是否回复，不确定时交给 Router LLM |
| Agent 执行 | 根据上下文生成回复，并按需调用工具 |
| 会话独立配置 | 分别管理上下文、自动回复开关和附加提示词 |
| 记忆与好感度 | 提炼对话信息，维护短期记忆、长期记忆与互动评分 |
| 图片与 GIF 识别 | 将媒体内容转为文字描述，并缓存识别结果 |
| 图片生成与编辑 | 文字生图、参考角色形象图、修改会话中的图片 |
| Lua 自定义工具 | 无需重新编译，通过脚本和异步 HTTP 扩展能力 |
| MCP 客户端 | 按需发现并调用远程服务提供的工具 |
| 定时与后台任务 | 定时触发消息处理，异步执行耗时任务 |
| Web 管理后台 | 配置模型、管理会话、查看日志、用量和请求记录 |
重点设计：Jev 结构化决策与 LLM 协作
Jev 是什么，与聊天模型有什么区别？
Jev 是 TypeSafe AI 的结构化决策模型，属于其称为System One的模型体系。它面向软件中的判断任务，而不是生成供人阅读的对话正文。调用方提供待判断的状态和带类型的问题，模型直接返回结构化答案。TypeSafe 官方介绍
例如，“这条消息是否值得回复”可以定义为选项判断，而不是要求聊天模型先生成一段分析，再从文字中提取结论。Jev 的 Choice 类型返回选中项、各选项的概率分布和置信度；官方还提供 Score 与 Noul 等问题类型，分别用于评分和判断某个条件成立的概率。官方问题类型说明
这种设计的价值不仅在于输出 JSON，而是将模型的职责从“生成一段回答”收敛到“回答一个有明确边界的决策问题”。速度与调用成本也是其面向高频路由场景的重要特点；但模型服务的表现不能直接等同于整个机器人的端到端性能。OpenRouter 模型介绍
InSoulForge 如何使用 Jev？
多人聊天中，大量消息只需要判断机器人是否应该参与，并不需要立刻生成回复。InSoulForge 将这类判断交给 Jev，并保留 Router LLM 处理不确定情况：
- 先处理明确规则：私聊、明确提及机器人和系统任务按各自规则处理，普通群聊消息进入可选的 Jev 决策流程。
- Jev 优先判断：结合聊天上下文，在
reply、skip、unclear等预定义选项中给出结果，并提供语气等回复策略参考。 - 置信度控制交接：结果有效且置信度达到阈值时直接采用；低于阈值、返回
unclear、响应无效或请求失败时，交给 Router LLM 判断。 - Executor 执行：确定需要回复后，再由 Executor 生成正文、查询信息或调用其他工具。
普通群聊消息 → Jev 决策 ├─ 高置信度 skip → 不回复 ├─ 高置信度 reply → Executor └─ 不确定或请求失败 → Router LLM → 回复时进入 Executor最低置信度可在后台配置，默认值为 0.60。这里比较的是confidence，不是probabilities.reply：选项概率与置信度不能混为一谈，阈值也不代表系统具有同等数值的实际正确率。
为什么值得用于聊天机器人？
对于消息频繁、实际只需回应其中一部分内容的会话，这种组合可以减少通用聊天模型参与高频决策的次数，将其留给更复杂的判断和正式回答。这也是项目区别于“每条消息直接请求一次聊天模型”的重要设计。
收益取决于消息分布、置信度阈值、兜底比例以及服务延迟；如果大量请求都需要兜底，额外的 Jev 请求也会增加开销。因此，项目保留可观察的决策日志和可配置阈值，而不是假设专用模型始终优于聊天模型。Jev 是可选能力，不配置也可以使用 Router 与 Executor 流程。
各群聊还可独立关闭普通消息自动回复，保留通过 @ 机器人互动的方式，并设置仅在本群生效的附加提示词。
记忆系统：提炼信息，而不是堆积聊天记录
InSoulForge 区分近期消息上下文、短期记忆和长期记忆：
- 近期上下文：供模型理解当前对话的消息记录。
- 短期记忆：从对话中提炼并整理需要保留的信息，不等同于最近若干条原始消息。
- 长期记忆：配置 Embedding 服务后，将适合长期保留的信息向量化存入 SQLite，后续按语义相似度召回。
长期记忆既可在消息预处理时自动注入相关内容，也可由模型通过工具主动检索。未配置 Embedding 时，仍可使用短期记忆。
系统还会根据互动评估好感度，为角色表达提供参考。这是模型生成的互动评分，不代表对真实人物的客观评价。
消息达到配置的触发数量后，记忆维护在后台运行。同一批消息的记忆整理与好感度评估全部成功后，才统一保存结果并移除对应旧消息；失败时保留消息，等待后续消息触发重试。维护任务本身不持久化，重启后在收到新消息时重新检查触发条件。
提取与召回依赖模型输出、阈值和上下文质量，不能保证记住所有信息。其作用是减少对完整历史记录的依赖，而不是提供无遗漏的知识档案。
工具扩展：内置能力、Lua 与 MCP
内置工具与执行控制
Executor 可以调用引用回复、记忆检索、深度思考、图片生成等工具。通过过程回复工具，也可以先发送进度消息，再继续查询或处理问题。
管理后台可以设置每次回复的最大工具迭代轮数。模型会收到当前轮次和剩余轮数，最后一轮仅开放回复类工具，避免无限延长工具调用链。上下文还会保留必要的工具调用名称、参数和处理状态，为后续对话提供执行参考。
Lua 自定义工具
自定义工具使用 Lua 脚本，可通过后台配置名称、说明、参数 Schema 和脚本内容，并支持导入导出。脚本能够调用项目暴露的受控接口，包括消息发送、会话后台任务和异步 HTTP 请求，无需重新编译 C++ 主程序。
当前自定义工具不再使用 Python 执行方式。网页读取、搜索和业务系统查询，可以通过 Lua 请求独立服务实现。这些能力需要部署相应服务或配置可用接口，不是安装后自动具备的通用联网能力。
MCP 远程工具
InSoulForge 内置 MCP 客户端，可接入提供 Streamable HTTP 接口的远程工具服务。后台支持添加、删除、启停服务，以及查看已发现的工具和加载状态。
模型先看到服务用途目录，再按需查询和启用工具，而不是每次请求都携带所有服务的完整工具定义。这有助于控制工具列表长度，并按任务选择所需能力。
当前主要支持 MCP 工具发现与调用，不支持 stdio、OAuth，以及 resources、prompts 等全部 MCP 能力；SSE 处理也有局限，不能宣称兼容所有 MCP 服务。应只连接可信服务，并确认其数据访问范围与操作权限。
图片理解与创作
视觉模型可独立配置，用于识别静态图片和 GIF 动图。系统按媒体内容、模型和提示词版本缓存描述，减少重复识别。聊天上下文主要使用文字描述，不直接携带原始图片数据。
图片生成使用独立接口配置，支持文字生图、自定义尺寸，以及根据会话中的图片进行编辑。也可以在后台上传角色形象图：当用户要求机器人绘制自己的形象时，以该图片作为参考，通过提示词描述场景、动作等变化。
生成任务在后台执行，完成后向原会话发送结果，并通过系统消息触发后续回应。具体支持的模型、尺寸和参考图参数，取决于配置的图片服务接口；支持聊天接口不代表同时支持图片生成。
模型配置与 Web 管理
Router、Executor、深度思考、记忆、视觉、Embedding 和图片生成等用途可以分别配置服务与模型。Executor 还支持兜底模型：默认模型请求失败时，本次请求尝试兜底配置，后续请求仍优先使用默认模型。
Web 管理后台支持：
- 配置 OneBot 连接、模型接口和角色提示词。
- 管理会话启用状态、群聊独立设置、管理员和黑名单。
- 管理 Lua 自定义工具、MCP 服务和执行参数。
- 查看聊天记录、模型用量和运行日志。
- 查看请求调试记录，并下载请求与响应记录，辅助排查接口和提示词问题。
接入模型和外部工具前，应确认聊天内容、图片及工具参数可能发送到哪些服务，避免传递凭据或不必要的敏感数据。后台管理与工具调用并不代替部署者的权限审查。
适用场景与使用边界
InSoulForge 适合以下需求：
- 自托管具有上下文、角色设定和记忆能力的聊天智能体。
- 在多人会话中按需回复，而不是对每条消息固定生成回答。
- 通过 Lua 或 MCP 将查询、创作和业务服务接入聊天流程。
- 研究和开发真实消息场景下的 Agent 调度、工具调用与记忆机制。
如果只需要关键词回复或固定指令处理，这套系统的模型配置与运维成本可能并不必要。模型调用费用、外部接口可用性、平台权限和生成内容质量，也需要由部署者持续管理。
项目采用 AGPL-3.0-only 开源许可证，使用前应阅读许可证及相关平台的规则。项目开源不等于获得平台接入许可；具体服务的使用方式与授权条件仍需分别确认。
了解项目与参与开发
InSoulForge 将消息接入、回复决策、记忆和工具执行组织成一套可自行部署与扩展的系统。QQ 是现有适配场景之一，OneBot 是消息服务的接入协议，其他平台的兼容性需要结合具体实现验证。
- 项目仓库与使用说明
- 部署教程
- 开发文档
- 贡献指南
- MCP 客户端说明与限制
欢迎通过 Issue 反馈问题与使用需求，或通过 Pull Request 参与改进。
