从协议桥接开始#

当前公开设计采用的是这条路：

1
QQ group -> NapCat -> OneBot v11 -> route proxy -> cc-connect projects

NapCat 负责把 QQ 登录和消息事件转成 OneBot v11 能理解的接口；中间的路由代理再把不同类型的消息分发到不同入口；最后由 cc-connect 的 QQ 平台项目接住任务。

这样拆开之后，每一层的职责都比较清楚：

• NapCat 处理 QQ 侧连接。
• OneBot v11 提供稳定的消息协议面。
• 路由代理决定这条消息该不该进入机器人。
• cc-connect 项目负责具体的任务会话。

我不喜欢把这些东西揉成一个大脚本。大脚本前期跑得快，但出问题时很难判断是 QQ 登录、协议事件、消息筛选、模型调用还是发送回复失败。

三条路线比一个入口可靠#

这个项目里最关键的是三条路线：

监听路线的默认动作应该是安静。它可以看见允许范围内的消息，但不能因为看见就必须回答。它更适合做轻量分类、文件归档、提醒触发、知识索引更新这类动作。

点名路线则相反。用户明确把任务交给机器人时，它才进入更完整的处理流程。这样复杂任务可以有独立会话，不会被群里的其他消息打断，也不会把无关聊天当成上下文。

私聊路线单独存在，是为了避免个人任务和群任务互相污染。群里的上下文属于群工作区，私聊里的上下文就应该留在私聊工作区。

插件比堆环境变量更适合长期维护#

机器人项目很容易越写越散。今天加一个图片命令，明天加一个提醒命令，后天又加一个工作区维护命令。如果所有功能都挤在顶层配置和主脚本里，后面就很难判断某个功能到底依赖哪些权限、哪些配置、哪些测试。

所以 chatbot-qq 把新功能尽量放进插件目录。一个插件应该有自己的清单、默认配置、入口文件和测试。比如：

• 工作区维护命令可以独立成一个插件。
• 图片生成命令可以独立成一个插件。
• 群内周期提醒可以独立成一个插件。

插件化主要是把使用规则落到功能自己身上：要不要启用、能在哪些地方工作、需要哪些配置，都在插件里说明，少加全局开关。

长回复别全塞纯文本#

QQ 群里还有一个很实际的问题：长回复和公式回复不适合直接塞成大段文本。

工程讨论经常会出现表格、代码块、数学公式和多段结论。纯文本一长，可读性会迅速下降，也容易被聊天窗口折叠得很难看。这个项目里保留了把长回复或公式密集回复渲染成图片再发送的思路。

这里保留图片回复，主要是让群里的结果能快速阅读、转发和保存。尤其是课程、实验、排错结论这种内容，图片化的版面有时比连续文本更稳。

部署脚本要让系统可检查#

群机器人一旦常驻运行，功能少还能补，坏了以后不知道坏在哪里才麻烦。

所以公开仓库里保留了安装、健康检查、备份、恢复、清理和完整性检查一类脚本。它们能把运行状态变成可检查对象：

• 服务有没有起来。
• 协议桥是否可用。
• 路由代理是否能分发消息。
• 插件配置是否通过校验。
• 私有数据是否误放进发布范围。

这些检查听起来不如模型能力吸引人，但它们决定了一个机器人能不能长期放在群里。

公开仓库要收紧#

IM 机器人项目天然靠近隐私数据。群号、用户号、聊天内容、登录状态、访问令牌、模型供应商配置、运行日志，都可能在开发过程中出现。

所以公开仓库应该只放这些东西：

• 通用脚本。
• 安装模板。
• 公共文档。
• 示例配置。
• 不含真实标识的测试用例。

它不能包含真实密钥、访问令牌、登录缓存、私有日志、聊天导出、本地工作区记忆或任何能还原真实聊天关系的数据。

这个原则会让部署流程多几步，但这是必要成本。一个聊天机器人如果没有清楚的发布规则，越好用，越容易积累不能公开的材料。

先把消息分清楚#

做 chatbot-qq 给我的最大提醒是：群聊 AI 助手先要解决路由问题，再谈回答质量。

它要先判断消息是否值得处理，再决定走轻量监听、明确点名还是私聊隔离。它要知道什么时候用确定性命令，什么时候交给模型，什么时候只记录上下文，什么时候完全不说话。

这些规则没定下来之前，模型越积极，越容易误触发、带错上下文，部署问题也更难排。

我希望它在 QQ 群里少插话，多把群聊里的任务、文件和结论整理到能维护的位置。