cc-haha 桌面端 QQ 适配器实战:扫码授权、配对鉴权与流式消息接入

原创2026-09-21 14:42:161,857 阅读
文章标签:人工智能AI 应用AI Agent代码智能体工具调用MCP ClientsAgent 编排Agent 工作流桌面应用移动开发前端GUI 自动化AI 技能后端Vibe Coding

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-nodejs SDK,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 操作步骤

  1. 打开桌面端 Settings → IM Adapters,切换到 QQ 标签页。
  2. 点击 Scan to Bind,界面出现二维码。
  3. 用 QQ 手机端扫码并确认授权。
  4. 成功后,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 流程与规则

  1. 在设置页顶部 Pairing 区域点击 Generate Code,生成 6 位配对码,立即生效,无需点 Save。
  2. 将配对码通过私聊发送给刚授权的机器人。
  3. 配对成功后,你在私聊里输入的任何内容都会进入 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/ 目录下)。

登录后查看全文
cc-haha