如果你想做一个真正“会聊天、会记忆、会使用工具、能长期陪伴群聊”的 QQ 机器人，InSoulForge 可能会很适合你。

InSoulForge 是一个基于 C++ / Drogon / Vue3 构建的智能 QQ 群聊机器人后端，配合 OneBot 协议实现使用。它不是简单的关键词回复机器人，而是采用 Router + Executor 的两层 Agent 架构，让机器人能够判断“该不该回复”、决定“怎么回复”，并在需要时调用工具完成更复杂的行为。

项目地址：

https://github.com/DreamDonghao/insoulforge

它能做什么？

InSoulForge 的目标不是只做一个“能接入大模型的 QQ Bot”，而是做一个更接近真实群友的智能体。

它支持：

• 智能判断是否需要回复，避免无意义刷屏
• 群聊和私聊独立上下文
• 自动提炼短期记忆和长期记忆
• 长期记忆向量召回，让机器人记住群友偏好、习惯和重要事件
• 图片识别，可识别群聊图片内容
• 自定义人设和提示词
• 表情包管理、收藏、发送
• 引用回复、@ 群友、撤回消息、禁言
• 拍一拍互动
• 定时任务
• Python / HTTP 自定义工具
• Web 管理后台
• LLM 用量统计
• 日志实时查看

简单说，它不仅能聊天，还能逐渐理解一个群的语境。

两层 Agent 架构：先判断，再执行

InSoulForge 使用 Router + Executor 的两层 Agent 设计。

Router 负责快速判断：

• 这条消息需不需要回复？
• 是普通闲聊，还是明确在问机器人？
• 回复应该简短还是详细？
• 当前消息是否是高优先级？

Executor 负责真正组织回复，并根据上下文调用工具。

这种拆分的好处是很明显的：机器人不会每条消息都硬回，也不会在多人聊天中显得突兀。Router 会先过滤掉不该插话的内容，Executor 只在确实需要回复时才进入生成流程。

不只是聊天：工具调用让机器人能“做事”

InSoulForge 内置了多种工具能力，例如：

• reply：普通回复
• reply_with_quote：引用回复
• no_reply：决定不回复
• send_sticker：发送收藏表情包
• save_sticker：保存用户发来的图片为 QQ 收藏表情
• send_poke：拍一拍群成员
• recall_memory：主动检索长期记忆
• deep_think：复杂问题调用深度思考模型
• reply_and_continue：先发送过程消息，然后继续处理

其中我比较喜欢的是 reply_and_continue。它让机器人可以一次对话连续发多条消息。

比如用户问一个需要查询或深度思考的问题，机器人可以先发：

稍等，我去查一下。

然后继续调用搜索、记忆或深度思考工具，最后再给出正式回答。

这会让机器人更像一个真实的人，而不是等很久之后突然甩出一大段结果。

长期记忆：让机器人真正“记得”

很多群聊机器人最大的问题是：它只看眼前上下文。

InSoulForge 内置短期记忆和长期记忆系统。短期记忆用于保存最近对话，长期记忆则会通过 Embedding 向量化存入 SQLite，并在后续聊天中按相似度召回。

这意味着机器人可以记住：

• 某个群友喜欢什么
• 群里的常用梗
• 曾经约定过的事情
• 某些长期偏好和习惯

同时，记忆不是简单地把所有聊天记录塞进上下文，而是经过提炼、合并和召回，尽量在成本和效果之间取得平衡。

更自然的 QQ 群互动

InSoulForge 对 QQ 常见功能做了比较完整的适配。

机器人可以：

• 发送 QQ 原生表情
• 发送收藏表情包
• 保存别人发来的图片为收藏表情
• 引用某条消息回复
• @ 指定群友
• 撤回消息
• 禁言群成员
• 拍一拍别人
• 接收别人对机器人的拍一拍

拍一拍也做了区分处理：

• 群友戳机器人：会合成为普通消息进入完整 Agent 流程，由 Router 判断是否回应
• 群友互相拍：只记入聊天记录，不触发回复
• 机器人自己发出的拍一拍：由工具记录，避免重复处理

这些细节能让机器人在 QQ 群里表现得更自然。

Web 管理后台

项目内置 Vue3 管理后台，可以直接在浏览器里配置：

• OneBot 连接参数
• Router / Executor / Image / Embedding 等模型
• 机器人提示词
• 启用的群聊或私聊
• 管理员
• 收藏表情
• 自定义工具
• 记忆参数
• LLM 用量统计
• 运行日志

对于日常使用来说，不需要频繁改配置文件，大部分操作都可以在 Web 页面完成。

性能和工程细节

InSoulForge 后端使用 C++23 和 Drogon 实现，异步处理基于 coroutine。

最近的一些优化包括：

• 禁用会话提前跳过，避免无效处理
• 图片识别等高成本格式化逻辑延后到启用检查之后
• 优先消息调度优化，@ 机器人、私聊、定时任务可打断普通消息
• 高优先级消息之间排队，不互相抢占
• 日志缓冲启动加载优化，只读取最近需要的滚动日志
• 表情发送、拍一拍、过程消息都会写入聊天记录并推送 WebSocket

这些不是“看起来很酷”的功能点，但会直接影响实际部署后的稳定性、响应速度和使用体验。

快速开始

项目需要配合 OneBot 协议实现使用，推荐使用 NapCat。

Docker 部署示例：

docker pull dreamdonghao/insoulforge:latest

docker run -d --name insoulforge
-p 7778:7778
-v ./data:/app/data
-v ./logs:/app/logs
-v ./uploads:/app/uploads
dreamdonghao/insoulforge:latest

启动后访问：

http://localhost:7778/index.html

然后在后台配置 OneBot 地址、Bot QQ、模型 API 和启用群聊即可。

适合谁使用？

InSoulForge 比较适合这些场景：

• 想搭建一个长期运行的 QQ 群智能体
• 希望机器人有记忆、有上下文、有工具调用能力
• 想研究 Agent 架构在真实聊天场景中的应用
• 想做 QQ Bot，但不满足于简单关键词回复
• 希望自己扩展 Python / HTTP 工具

如果你只是想要一个非常轻量的复读机，它可能有点“重”。但如果你想要一个更接近真实群友、更能长期陪伴群聊的智能机器人，它会是一个很有意思的选择。

结语

InSoulForge 目前仍在持续迭代中。它的重点不是堆功能，而是把 QQ 群聊这个真实、高噪声、多人的场景处理得更自然。

我希望它能成为一个真正可用、可扩展、可长期运行的智能 QQ 群聊机器人后端。

如果你对 Agent、QQ Bot、长期记忆、自定义工具或智能群聊机器人感兴趣，欢迎来看看这个项目，也欢迎提 issue、star 或参与改进。

项目地址：

https://github.com/DreamDonghao/insoulforge