cc-haha 桌面端 QQ 适配器实战:扫码授权、配对鉴权与流式消息接入
cc-haha 桌面端 QQ 适配器实战:扫码授权、配对鉴权与流式消息接入
导读
本文围绕 cc-haha 项目中 adapters/qq 模块,系统讲解如何在不创建 QQ 开放平台应用的前提下,通过桌面端设置页扫码绑定 QQ 机器人,再以私聊(C2C)方式驱动 Claude Code 桌面端完成对话、项目切换与权限审批。读完本文,你将掌握扫码授权、配对码鉴权、stream_messages 流式回复、附件与语音处理等完整链路,并了解 adapters/qq/index.ts 及其共享运行时的底层实现原理。
一、整体能力与边界
QQ 集成面向个人用户设计,核心特点如下:
- 扫码即绑定:在设置页选择 Scan to Bind,用 QQ 手机端扫码后,
AppID与AppSecret直接写入本地配置,无需在 QQ 开放平台手动创建应用。 - 免公网部署:消息走 QQ 开放平台官方 WebSocket 网关(
@tencent-connect/qqbot-nodejsSDK,transport: 'websocket'),本机不需要公网地址或回调 URL。 - 仅限私聊(C2C):不支持群聊与频道;权限审批以文本回复形式完成。
上述能力在 adapters/qq/index.ts 中有直接体现:适配器启动即校验 config.qq.appId / config.qq.appSecret,缺失则直接退出;机器人通过 new QQBot({ transport: 'websocket', tokenPrefetch: 'sync' }) 建立长连接。
二、扫码授权机器人(Scan to Bind)
2.1 操作步骤
- 打开桌面端 Settings → IM Adapters,切换到 QQ 标签页。
- 点击 Scan to Bind,界面出现二维码。
- 用 QQ 手机端扫码并确认授权。
- 成功后,
AppID与AppSecret写入~/.claude/adapters.json,适配器自动重启。
二维码过期后会自动轮换刷新,界面上图片同步更新;绑定完成后按钮变为 Scan Again,旁边出现 Unbind bot account(解绑)按钮。
注意:这一步只授予桌面端机器人凭据,并不授权任何用户。谁能使用机器人,由下文"配对"环节决定。
2.2 底层机制:start/poll 状态机
扫码流程由 adapters/qq/qr-auth.ts 实现,它在 @tencent-connect/qqbot-connector 的回调式 API 之上封装出可供桌面设置页通过 HTTP 驱动的 start/poll/cancel 三件套:
startQqQrLogin:创建会话,通过onQrDisplayed拿到二维码 URL,20 秒(QR_READY_TIMEOUT_MS)拿不到二维码即报"QQ 二维码获取超时,请重试";会话 TTL 为 10 分钟(SESSION_TTL_MS),轮询间隔 2 秒(QQ_POLL_INTERVAL_MS)。pollQqQrLogin:返回waiting / expired / failed / success / not_started状态;成功后交出appId、appSecret与userOpenid。会话状态被锁存,成功或失败后再次轮询返回not_started,避免重复结果。cancelQqQrLogin:主动取消,释放底层连接器。
几个值得注意的实现细节:
- 单次扫码互斥:每次
startQqQrLogin都会回收并dispose上一次会话(包括被用户关闭页面遗留的),防止连接器轮询到 TTL 耗尽并层层堆叠。测试见 adapters/qq/tests/qr-auth.test.ts。 - QR 轮换只上报一次:通过
urlVersion与deliveredUrlVersion比对,二维码刷新后的 URL 仅在下一次 poll 中返回一次,避免 UI 每 tick 重绘图片造成闪烁。 - 凭据不完整视为失败:回调返回的凭据若缺
appId或appSecret,会话直接置为failed,不会绑定一个坏掉的机器人。 - 二维码绝不打印到控制台:
displayQrCodeToConsole: false,防止授权码泄漏到 sidecar 日志。
三、配对(Pairing):把"机器人与你"建立授权关系
3.1 流程与规则
- 在设置页顶部 Pairing 区域点击 Generate Code,生成 6 位配对码,立即生效,无需点 Save。
- 将配对码通过私聊发送给刚授权的机器人。
- 配对成功后,你在私聊里输入的任何内容都会进入 Claude Code。
配对码规则(源码见 adapters/common/pairing.ts):
| 规则 | 实现 |
|---|---|
| 有效期 | 60 分钟(CODE_TTL_MS = 60 * 60 * 1000) |
| 一次性 | 配对成功后立即清空 pairing.code,不可复用 |
| 重新生成即失效 | 新码生成覆盖旧码 |
| 字符集 | ABCDEFGHJKMNPQRSTUVWXYZ23456789,刻意排除易混淆的 0/O/1/I/L |
| 速率限制 | 同一用户 5 分钟内失败 5 次(RATE_LIMIT_MAX_ATTEMPTS = 5)触发限流 |
| 比较方式 | 忽略大小写与首尾空白 |
配对成功后,发送者以 { userId, displayName, pairedAt } 记录到 adapters.json 中对应平台的 pairedUsers 数组。由于配对授权的是人(通过 QQ openid 标识),所以群消息会被直接丢弃——若在群里应答,等于把私聊授权扩散给群内所有人(见下文"入站过滤")。
3.2 Allowed Users 白名单
Allowed Users 可以留空,此时仅已配对账号可用;若要直接放行已知账号,填入以逗号分隔的 QQ openid 即可。注意:QQ openid 是每个机器人独立的标识符,不是 QQ 号。其判定逻辑在 isPaired()(adapters/common/pairing.ts):allowedUsers 命中即放行;两者皆空时默认拒绝(必须先配对)。
3.3 入站过滤:为什么群聊无效
adapters/qq/extract-payload.ts 中的 extractQqPayload 是入站的第一道闸门:
- 仅接受
kind === 'c2c'的私聊消息,group、guild、dm一律返回null; - 机器人自己发出的消息(
senderIsBot)直接丢弃,防止回声循环; - 无发送者身份的消息丢弃;
- 生成稳定的
dedupKey(优先messageId,缺失时合成userId:timestamp:text前32字符),交由 adapters/common/chat-runtime.ts 的MessageDedup做去重。
以上行为均有测试覆盖,见 adapters/qq/tests/extract-payload.test.ts。
四、支持的命令与权限审批
命令解析集中在共享运行时 adapters/common/chat-runtime.ts,QQ 与其他 IM 适配器共用同一套别名表:
| 命令 | 别名 | 作用 |
|---|---|---|
/help |
帮助 |
列出可用命令 |
/status |
状态 |
当前项目、模型、运行状态(含待审批权限数与任务统计) |
/projects |
项目列表 |
列出最近项目并切换(最多 10 个,回复编号选择) |
/new |
新会话 |
新建会话,可带序号、项目名或绝对路径作为参数 |
/clear |
清空 |
清空上下文,保留项目绑定 |
/stop |
停止 |
停止当前回合生成 |
权限审批:当 Agent 需要调用工具时,私聊中会收到审批提示。回复 1 允许一次、2 会话内允许、3 拒绝;也支持 /allow <id>、/always <id>、/deny <id> 三种指令形式(解析与回执在 parsePermissionCommand / applyPermissionDecision 中处理,见 adapters/common/chat-runtime.ts)。
值得注意的运行时细节:
- 消息按每个聊天一个 FIFO 队列串行处理(
enqueue(chatId, ...)),避免两条快速消息交错修改会话状态; - 附件下载被刻意延迟到"发送者已授权 + 会话已绑定 + 仍在聊天队列内"之后才执行(
loadAttachments回调),防止未配对的陌生人触发适配器拉取字节并写入~/.claude/im-downloads/; - QQ 适配器的流式缓冲参数为
flushIntervalMs: 600、flushCharThreshold: 200(见 adapters/qq/index.ts),即 600 毫秒或 200 字符触发一次推送。
五、消息形态:流式回复、打字指示与媒体
5.1 流式回复(stream_messages)
回复优先使用 QQ 的 stream_messages 流式消息:一条消息随生成不断刷新,最终定格为完整答案。实现上是 adapters/qq/index.ts 的 QqResponse 类:
append(delta)累积全文并调用session.update()(每帧节流 600ms,QQ_STREAM_THROTTLE_MS);finish()调用session.complete()定型;- 降级兜底:
stream_messages仅限私聊且必须以入站messageId为锚点。若当前回合没有可用回复锚点(或流更新失败),适配器不会丢弃内容,而是只把未展示的尾部(accumulated.slice(streamed))改发普通分块消息——重发整段会让用户重复阅读已见内容; - 单条普通文本按
QQ_TEXT_LIMIT = 1500字符经splitMessage分块发送。
每次入站消息都会在 replyTargets 中记录 { scope: 'c2c', targetId, msgId },供出站回复引用正确的会话与锚点(adapters/qq/index.ts)。
5.2 打字指示器
Claude 思考或执行工具期间(运行时状态为 thinking / tool_executing / tool_result 时),适配器调用 bot.sendTyping(target, 30) 发送 30 秒的打字状态(TYPING_SECONDS,见 adapters/qq/index.ts)。打字指示只是礼貌性信号,发送失败被静默吞掉,绝不打扰用户。
5.3 入站附件与语音
- 入站图片与文件下载到
~/.claude/im-downloads/qq/(经共享AttachmentStore按会话隔离),再作为附件转发给 Agent; - 语音消息不下载音频:QQ 语音自带
asr_refer_text转写文本,extractQqPayload把它折叠进消息文本(与正文用换行拼接),并从附件列表剔除音频本身——下载 Agent 读不了的音频纯属浪费(见 adapters/qq/extract-payload.ts 与对应测试 adapters/qq/tests/extract-payload.test.ts)。
5.4 附件下载的安全处理
adapters/qq/media.ts 的 normalizeQqAttachmentUrl 对 QQ CDN 的"无 scheme"URL(如 multimedia.nt.qq.com.cn/...)强制补全为 HTTPS,并执行安全校验:
- 仅接受
http:/https:,且一律升级为 https; - 拒绝
file:等非 Web 协议、拒绝 URL 内嵌用户名密码(防止 SSRF); - 下载带 30 秒超时(
DOWNLOAD_TIMEOUT_MS),MIME 依次从事件content_type、响应头、文件名推断。
上述安全策略均有测试锁定,见 adapters/qq/tests/media.test.ts。
5.5 出站图片
Agent 输出中引用到的本地图片(仅限当前会话工作目录内)会被 ImageBlockWatcher 捕获,经 loadSafeOutboundImage 校验后通过 bot.sendMedia(MediaFileType.IMAGE, ...) 以独立图片消息发送(adapters/qq/index.ts);出站图片同样受共享附件限额 checkAttachmentLimit 约束。
六、Agent 能力与安全边界
QQ 适配器不是独立的问答模型。消息进入与当前项目绑定的同一个 Claude Code Agent 会话,自然延续多轮上下文,可调用该会话已有的文件、终端、Git、Skills 与 MCP 工具(会话创建/恢复见 adapters/common/chat-runtime.ts 的 ensureSession / createSessionForChat 与 adapters/common/session-recovery.ts)。
这意味着:
- 配对账号拥有当前项目的完整 Agent 能力;权限确认只是对单个操作的闸门,不是操作系统级沙箱;
- 不要把机器人交给不信任的人;
- 不要在聊天中安装未经审查的 Skills、插件或 MCP 服务器;
- 适配器只接受已配对或白名单的私聊;项目列表与名称匹配被限制在 Allowed project directories(
allowedProjectRoots)之内,相关配置项见 adapters/common/config.ts。
七、本地运行与配置
7.1 手动启动(源码运行时)
发布版构建会自动以 sidecar 方式启动适配器;只有从源码运行时才需要手动启动:
cd adapters
bun install
bun run qq
启动日志会打印网关就绪、服务器地址与应用 ID;缺少凭据时直接报错退出:
[QQ] Missing QQ_APP_ID / QQ_APP_SECRET. Bind QQ in Desktop Settings > IM.
7.2 环境变量覆盖
以下变量可覆盖扫码写入的配置(优先级最高,见 adapters/common/config.ts):
export QQ_APP_ID="xxx"
export QQ_APP_SECRET="xxx"
export ADAPTER_SERVER_URL="ws://127.0.0.1:3456"
7.3 本地配置结构
扫码与配对结果统一落在 ~/.claude/adapters.json(路径可被 CLAUDE_CONFIG_DIR 覆盖;写入采用临时文件 + rename 原子替换,权限 0o600),典型结构:
{
"qq": {
"appId": "扫码得到的 AppID",
"appSecret": "扫码得到的 AppSecret",
"allowedUsers": [],
"pairedUsers": [
{ "userId": "openid-xxx", "displayName": "昵称", "pairedAt": 1700000000000 }
],
"allowedProjectRoots": []
},
"pairing": { "code": null, "expiresAt": null, "createdAt": null }
}
其中 pairing.code 即 6 位配对码,配对成功后归零。
八、故障排查
| 现象 | 原因与处理 |
|---|---|
| 二维码一直不出现 | 扫码流程走 QQ 开放平台,确认本机可访问;请求 20 秒超时,重试即可 |
| 扫码成功但机器人沉默 | 确认桌面端仍在运行,且 QQ 标签页显示 AppID;凭据在扫码成功瞬间写入,适配器会自动重启 |
| 消息提示 unauthorized | 检查是否生成了配对码、是否仍在 60 分钟有效期内、发送的是否为当前最新配对码 |
| 群里 @ 机器人无反应 | 符合预期:仅处理私聊。配对授权的是单个人,群内应答会把授权扩散给所有人 |
九、源码入口与测试
| 职责 | 文件 |
|---|---|
| 适配器运行时(SDK 接入、流式回复、媒体转发) | adapters/qq/index.ts |
| 扫码授权 start/poll/cancel 状态机 | adapters/qq/qr-auth.ts |
| 入站消息解析与过滤 | adapters/qq/extract-payload.ts |
| 入站媒体下载与 URL 安全校验 | adapters/qq/media.ts |
| 共享会话循环(命令、权限、会话、项目选择) | adapters/common/chat-runtime.ts |
| 配对码生成、限流、用户授权判定 | adapters/common/pairing.ts |
| 平台配置解析与环境变量覆盖 | adapters/common/config.ts |
| 扫码授权测试 | adapters/qq/tests/qr-auth.test.ts |
| 入站解析测试 | adapters/qq/tests/extract-payload.test.ts |
| 媒体下载测试 | adapters/qq/tests/media.test.ts |
QQ 适配器是共享 IM 运行时(ImChatRuntime)的一个具体实例:平台只需实现 ChatPort(发送通知、创建流式回复、可选发图与打字指示),传输、鉴权与媒体细节全部内聚在平台侧。理解 QQ 这一实例,即可快速迁移到 Telegram、飞书、微信、钉钉、WhatsApp 等同仓库适配器(位于 adapters/ 目录下)。