Skip to content
Projects

DreamDonghao/insoulforge has 57 GitHub stars and 10 forks. GitHot measured 0 stars in 24 hours, 0 in 7 days, and +1 in 15 days. Last checked 2026-11-19 18:03 UTC. Last push 2026-11-08.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
0
in 15 days
+1
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

基于 C++23 与 Agent 架构的 OneBot 智能聊天机器人,支持群聊智能回复、跨会话消息共享、长期记忆、好感度(可选)、自定义工具扩展、MCP 及 Web 管理后台

AI

README.md

Original

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(私聊 用户 ID),向后台已启用的群或私聊发送消息、表情;两者互斥,均省略则发送到当前会话,与跨会话共享开关无关
  • 自定义工具 - 使用 Lua 脚本与异步 HTTP 请求扩展能力,支持可视化配置及导入导出
  • MCP 工具 - 支持接入 HTTP MCP 服务,由模型按需查询并启用远程工具
  • 实时活动 - 使用统一接入 Token 自动注册反向 WebSocket 全局单例活动服务,模型可持续参与、指挥并获取最新状态;接入方法见活动应用开发指南
  • 适配 QQ 功能 - Bot 可自行收藏发送表情包、引用、@ 群友、撤回消息、拍一拍、禁言,并按规则将用户加入全局黑名单
  • 定时与后台任务 - 支持定时触发消息处理,以及图片生成等耗时任务,后台执行完成后发送结果

🚀 快速开始

统一使用 Docker Compose 部署,完整步骤见 部署教程。

教程包含环境准备、Compose 配置选择、后台登录、OneBot 与模型配置,以及迁移、备份、更新和常见问题。 首次部署可按教程联合启动 InSoulForge 与 NapCat;已有 OneBot 服务时可只部署 InSoulForge。

本项目需配合合法合规的 OneBot 协议实现使用。NapCat 仅作为教程示例,请自行确认所选实现的合法合规性。

📖 使用指南

推荐通过 Web 管理后台进行配置。

群聊命令

在启用命令解析的群中 @机器人 发送命令;私聊不解析命令,按普通聊天处理:

命令 说明 权限
/help 显示帮助 所有人
/status 查看当前会话状态 所有人
/admins 查看管理员列表 所有人
/about 关于本项目 所有人
/enable [群号] 启用指定群聊,省略时为当前群 管理员
/groupcard on|off 开启或关闭本群向模型发送群名片 管理员
/autoreply on|off 开启或关闭本群普通消息自动回复,关闭后仍可 @ 机器人 管理员
/disable [群号] 禁用指定群聊,省略时为当前群 管理员
/groups 查看已启用的会话列表 管理员
/addadmin <用户 ID> 添加管理员 管理员
/deladmin <用户 ID> 移除管理员 管理员
/blacklist 查看全局用户黑名单 管理员
/addblacklist <用户 ID> 将用户加入全局用户黑名单 管理员
/delblacklist <用户 ID> 将用户移出全局用户黑名单 管理员
/listemoji 查看QQ收藏表情列表 管理员
/delemoji <名称> 从QQ收藏表情中删除 管理员
/clearimagecache 清除图片和 GIF 描述缓存 管理员

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

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

⚙️ 配置说明

OneBot 配置

参数 说明
Access Token OneBot API 访问令牌
Bot 用户 ID 机器人自身的 用户 ID
传输方式 HTTP 或正向 WebSocket,两者互斥
HTTP 服务地址 HTTP 模式下的 OneBot HTTP 服务地址
WebSocket 服务地址 WebSocket 模式下的 OneBot 正向连接地址
Bot 名称 机器人在群聊中的名称
新私聊默认启用 默认关闭,仅影响首次收到消息的新私聊

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

LLM 配置

各模型可分别配置:

模型 用途 建议配置
Router Jev 不可用或判定不确定时的回复决策 轻量聊天模型,低温度
Jev 群聊消息的优先回复决策(可选) Decisions API
Executor 生成回复 主力聊天模型
Executor思考 deep_think 工具使用的深度思考模型(可选) 推理模型,如 DeepSeek
Image 图片内容识别 多模态聊天模型
Memory 记忆提取、整理与好感度评分 聊天模型
Embedding 长期记忆向量化与检索(可选) 向量模型

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 不保存管理后台访问令牌。请从服务启动时的终端输出获取当前令牌或登录链接;登录凭据不会写入应用日志文件,也不会展示在网页运行日志中。Docker 部署可查看容器标准输出。不要将令牌提交到仓库或发送给无关人员。

在正在运行的服务终端输入 login-token 并回车,可再次显示当前登录令牌和登录链接;不会更换令牌,无需重启服务。

每个模型都可以独立配置「请求超时(秒)」和「失败重试次数」,对应 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 模型请求及其工具调用处理,同轮多个工具只计一轮; 最终生成回复也占一轮。达到上限仍未产生回复时,记录错误并结束本次回复流程。

execution.routeWhileReplying 默认关闭,可在执行配置中切换,保存后对新消息立即生效。 开启后,同一群正在回复时,普通新消息仍走 Jev 优先、Router 回退的回复判断;需要回复时合并到下一轮, 只保留最新一个需回复的触发及其决策,下一轮不会重复路由。判断为跳过的消息不会清除已有待回复任务。 当前回复不会被打断,同一会话不会并行生成回复;私聊、@机器人和系统消息沿用原有处理方式。 新消息判断按会话串行执行,会增加路由请求量,并可能延迟该会话后续消息的预处理。

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

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

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

记忆与上下文参数

  • 启用好感度 - 默认开启,可在「记忆与上下文」关闭并热更新。关闭后停止评分及写入,模型上下文不提供分数,人物页面隐藏分数、排序和编辑入口;人物记忆继续运行。历史分数保留,重新开启后恢复,不补算关闭期间的变化。明确删除全部人物数据时仍会删除该人的历史分数。
  • 近期上下文上限 - Router 与 Agent 实际可见的最近完整消息数,默认 100
  • 每会话共享消息数 - Executor 从每个其他参与共享的会话读取的近期消息数,默认 10,可在「记忆与上下文」调整
  • 总结触发条数 - 消息预处理完成后,完整消息列表达到或超过该数量时触发一批记忆维护,默认 100
  • 每批总结条数 - 本批参与记忆提取与好感度评估,并在全部处理成功后移除的最旧消息数,默认 50,不能超过触发条数
  • 总结补充上下文条数 - 紧随总结批次的只读消息数,仅帮助模型理解语境,不参与提取或删除,默认 10
  • 会话聊天摘要 - 每批消息总结时同时生成,默认每条目标上限 100 字、每会话保留最近 10 条;按消息起止时间排列,在回复上下文中放在历史消息之前,重启后保留。摘要独立于原始消息,不重新参与人物或长期记忆提取。
  • 总结篇幅 - 会话摘要、人物记忆提取、长期记忆、人物档案、与机器人的关系、近期互动的字数均可在「记忆与上下文」配置并热更新;后三类可分别设置单条和合计字数。字数是模型生成的目标上限,实际长度受模型遵守指令的程度影响,可能超出,程序不强行截断。
  • Memory 模型 maxTokens - 在「LLM 配置 → Memory」设置记忆提取与整理的输出 token 上限,默认 4000;旧配置会自动迁移
  • Jev 窗口条数 - 每次取最近 N 条消息判断是否回复,默认 10 条,逐条滑动;保存后热更新,实际范围受近期上下文上限限制
  • Router 窗口触发/保留条数 - Router 使用的子窗口滑动参数,默认 20/10,用于平衡路由 prompt 长度与缓存命中
  • 长期记忆召回阈值 - 新记忆与已有长期记忆合并去重时的相似度阈值,默认 0.65
  • 长期记忆注入阈值 - 消息预处理时被动召回并注入当前消息的相似度阈值,默认 0.45

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

会话记忆保存按 QQ 归属的外号 aliases 和按消息时间排列的聊天摘要 conversation_summaries。已有外号保留并合并,有明确纠正时更新。 每批先在同一次请求中提取人物待整理条目、好感度和会话聊天摘要;再用新条目召回本会话相关长期记忆,与已有外号一起整理。 整理结果包含完整外号列表和本批新旧材料的完整长期记忆条目。新条目全部完成向量化后,在同一事务内写入结果并删除参与整理的旧记忆,未召回的旧条目不受影响。 没有新条目和历史待迁移内容时跳过第二次整理请求;任一步失败都不提交本批结果。 旧 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/ 目录:

文件 功能 额外依赖
random.json 随机数生成 无
get_weather.json 天气查询 无
fetch_webpage.json 读取动态网页 PageWeave 服务
search_web.json 读取 Bing 搜索结果页 PageWeave 服务
deepseek_search.json DeepSeek 网页搜索,可附带正文 DeepSeek API Key
deepseek_fetch.json 读取网页并返回 Markdown 正文 DeepSeek API Key

导入方法:

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

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

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

配置 Embedding(可选)

  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。