记录时间：2026-10-30
主题：把一个数据驱动的拟人化聊天机器人接入 QQ 真实群聊的完整过程，包括 agent 改造、协议端选型、签名服务器搭建，以及一次版本不匹配的教训。
结论：版本不对齐等于白搭。先确定协议端支持什么版本，签名服务器和客户端版本全部跟它走，不要从最新客户端版本反推。

目录

1. agent 项目改造

2. 协议端选型调研

3. 一次失败的签名服务器尝试

4. 根因分析

5. 正确的接入路径

6. 经验教训

1. agent 项目改造

1.1 已完成的工作

对一个数据驱动的拟人化聊天机器人 agent 做了几项改造：

改动	内容
删除旧机制	硬拦脏话、忽略短消息、防重复、刷屏抑制，全部移除
构建产物不入库	dist 目录加入 gitignore 并移除已提交的产物
协议端支持切换	配置加 token 和 protocol 字段，支持 OneBot v11 切换，清理死代码
修复真实缺陷	私聊消息被丢弃、断线状态不更新、记忆压缩产出嵌套数组、批量计数类型错误

1.2 当前 agent 状态

• 配置支持 host/port/token/protocol 及环境变量别名；

• WebSocket 连接传 protocol 和 accessToken，监听连接状态和私聊消息；

• WebUI 增加了协议下拉框（ws/wss）和 Token 输入框；

• 编译全绿，WebUI 运行中。

1.3 待决事项

配置里有一处冲突：同一个真实群既标记为要接入，又被黑名单丢弃。要接真实群需要清理黑名单配置。

2. 协议端选型调研

项目	内存占用	封控反馈	备注
注入型客户端方案	400–855MB	最多（注入官方客户端，被检测到外挂特征）	agent 原生目标，本地签名，有 WebUI
纯协议实现	约 92MB	少（社区小）	无客户端无注入特征，低封控但版本落后
Hook 注入型新方案	约等于或高于注入型	少	Hook 注入，较新

2.1 封控的本质

三者本质都是外挂软件，官方都在打击。封号主因是行为维度：

• 新号；

• 机房 IP；

• 高频操作；

• 无手机同时登录。

协议特征维度才与社区大小相关。“社区越小越安全”只覆盖协议特征维度，而且是低关注度红利。

2.2 签名服务器的原理

QQ 每次请求需要签名（sign/extra/token），算法在官方的混淆加固模块里。

腾讯堵不死的原因：C/S 架构下算法必须在客户端，可以逆向。腾讯的武器是升级签名版本、风控封号、法律手段。

3. 一次失败的签名服务器尝试

3.1 做了什么

1. 下载纯协议实现客户端的夜版自包含包；

2. 从最新版 QQ 的 deb 包里解出 152MB 的签名模块；

3. 搭自建签名服务器（Python 版），改 POST 处理支持 chunked 编码（原实现只读 Content-Length，导致 400）；

4. 改客户端版本号，从 13172 改到 47354（猜测值）；

5. 反汇编确认签名函数偏移；

6. 改版本号，从 3.2.27 改到 3.2.34-53644。

全都没用。登录仍然卡在 “Connecting Servers...”，QQ 不回二维码。

3.2 根因

一直没查 OneBot 自己支持什么版本，只在这上面打补丁。

查源码后发现：

• OneBot 的代码在 v1 分支（master 没有 OneBot 实现）；

• 源码里默认签名 URL 指向 sign.lagrangecore.org/api/sign/30366；

• 源码里定义的客户端版本是 3.2.15-30366，AppClientVersion 是 30366，SubAppId 是 537258424。

统一版本是 3.2.15-30366。而我给的是 3.2.34-53644，从最新 deb 解出来的，差了两个大版本，登录包畸形。

4. 根因分析

这次失败的核心不是技术难度，是方向错误：

错误做法	正确做法
从最新客户端 deb 解签名模块	从协议端支持的版本对应的 deb 解
猜版本号往上凑	先查协议端源码定义的版本
给签名服务器报最新版本	签名服务器上报与协议端一致的版本

一句话：协议端是定版本的一方，签名服务器和客户端模块都要跟它对齐。

5. 正确的接入路径

5.1 方向

先把协议端定版本，其余全部跟它走。

5.2 步骤

1. 确定用哪个协议端（agent 需要 OneBot v11）：

   • 注入型方案：agent 原生目标，本地签名，WebUI 扫码登录，当前客户端版本。代价是内存高、封控风险高；

   • Hook 注入型新方案：较新，有 WebUI/MCP，需要验证版本匹配；

   • 纯协议实现 v1：版本落后，不推荐（要 3.2.15 的签名模块和签名服务器，还得对齐 30366）。

2. 定版本：查协议端源码里的客户端版本定义。

3. 签名服务器对齐版本：上报同版本的 CurrentVersion、AppClientVersion、SubAppId、AppIdQrCode。

4. 签名模块用同版本 deb 的，不是最新 deb。

5. 登录：WebUI 扫码或二维码。

6. agent 对接：配置 host/port/token/protocol（协议切换已做好），清理黑名单。

7. 真实群端到端验证。

5.3 备选方案

官方 V2 签名：GitHub 加 GPG Key，群内注册，拿 token，走官方签名服务器。但需要在含特定 Bot 的群里注册，有门槛。

6. 经验教训

1. 版本对齐是第一优先级。协议端、签名服务器、客户端模块三者版本必须一致，差一个大版本就登录失败。

2. 不要从最新版本反推。最新 deb 解出来的签名模块版本可能远高于协议端支持的版本。协议端是定版本的一方，不是客户端。

3. 先读源码，再动手。协议端源码里写死了它支持的客户端版本和签名 URL，这些是硬约束，不能猜。

4. 签名服务器不是独立组件。它的版本上报必须与客户端模块一致，否则登录包畸形，QQ 直接不回二维码。

5. 失败时的排查顺序：先查版本是否对齐，再查网络、签名算法、chunked 编码等细节。版本不对，后面全白搭。

6. 封控的本质是行为，不是协议。新号、机房 IP、高频操作、无手机同登，这些才是封号主因。协议特征只占一部分。

---

本文基于一次实际的 QQ 机器人接入尝试整理，重点在版本对齐的教训和协议端选型的方法论。不同协议端、不同 QQ 版本下细节可能不同，请以实际环境为准。