cc-haha 微信接入实战:扫码绑定、配对授权与 iLink 长轮询协议全解析

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

cc-haha 微信接入实战:扫码绑定、配对授权与 iLink 长轮询协议全解析

导读

本文围绕 cc-haha 的微信 IM 接入链路,完整讲解「扫码绑定机器人账号 → 配对码授权具体用户 → 选择项目开始对话 → 文本命令驱动会话与权限审批」的端到端流程,并深入到 adapters/wechat 与 adapters/common 的源码实现,揭示 iLink 长轮询、6 位一次性配对码、消息分片与附件解密等底层机制。读完本文,你既能照着手册在桌面端 5 分钟内完成接入,也能理解这套 adapter 为什么不需要任何开放平台资质,以及它只面向私聊、依赖文本命令的设计取舍。

微信接入的定位与能力边界

cc-haha 微信接入面向「只想用微信、不愿意再装一个 App」的用户。它的核心卖点是整个接入过程只需要扫一次码,不需要前往任何开放平台申请应用资质——因为 adapter 走的是 iLink 机器人通道,而 iLink 扫码绑定凭据(botToken + accountId)的动作发生在桌面端设置页。

从源码看,这条链路存在三个明确的设计边界:

  • 只处理私聊,不面向群聊设计;routeUserMessage 只依据 from_user_id 逐条路由,没有群消息上下文处理逻辑(见 adapters/wechat/index.ts)。
  • 权限审批只能靠回复文本命令,微信没有可配置的菜单或可点击按钮,因此 /allow、/always、/deny 三个文本命令承担了审批入口。
  • 输入类型有限:除文本外,还支持语音转出的文字、图片和文件附件。语音在 extractWechatText 中通过 voice_item.text 直接以文字进入模型(adapters/wechat/protocol.ts)。

扫码绑定机器人账号

操作步骤

在桌面端完成绑定只需四步:

  1. 打开「设置」→「IM 接入」,切到「微信」Tab。
  2. 点击「扫码绑定」。
  3. 用微信扫描页面上显示的二维码,并在手机上确认登录。
  4. 等待页面状态变为「微信已绑定」。

未绑定时的扫码入口

绑定成功后,凭据会自动写入本机配置并重启 adapter,不需要再点「保存」。此时 Tab 中会出现「重新扫码」和「解除微信绑定」两个按钮。

绑定成功后的状态

需要特别强调:扫码绑定的是机器人账号本身,不等于放行所有微信联系人。谁能使用,还要看下一节的「配对」步骤。

底层实现:iLink 扫码登录协议

扫码绑定并不是黑盒,其完整协议实现在 adapters/wechat/protocol.ts,核心流程是两段式轮询:

  1. 发起登录:startWechatLoginWithQr 调用 ilink/bot/get_bot_qrcode?bot_type=3,拿到 qrcode(登录凭证)和 qrcode_img_content(二维码图片地址),并记录 startedAt 时间戳(protocol.ts)。
  2. 轮询状态:pollWechatLoginWithQr 循环调用 ilink/bot/get_qrcode_status?qrcode=...,状态机依次经历 wait(等待扫码)→ scaned(已扫码,请在微信中确认)→ scaned_but_redirect(已扫码,正在切换微信网关)→ confirmed(绑定成功,返回 bot_token、ilink_bot_id、baseurl 等凭据)或 expired(二维码过期)。

几个源码级细节值得注意:

  • 二维码有效期只有 5 分钟:QR_LOGIN_TTL_MS = 5 * 60_000,isLoginFresh 与 purgeExpiredLogins 负责清理过期的登录会话(protocol.ts)。所以「二维码提示过期」时,重新点「扫码绑定」生成新码即可。
  • 网关会动态切换:微信服务端在扫码后可能返回 redirect_host,此时 adapter 会把后续 API 的 currentApiBaseUrl 切到 https://${redirect_host},这就是「正在切换微信网关」的含义(protocol.ts)。
  • 凭据落盘:确认成功后返回的 botToken / accountId 会被桌面端写入本机配置(~/.claude/adapters.json 的 wechat 段),并自动重启 adapter。adapter 启动时会校验这两个字段,缺失则直接报错退出(index.ts)。

授权具体用户:配对码与白名单

操作步骤

  1. 回到页面顶部的「配对管理」,点击「生成配对码」。
  2. 在微信里把这枚 6 位码发给刚绑定的机器人。
  3. 看到配对成功提示后即可直接发消息。

在微信里发送配对码并开始对话

配对码有两个硬性约束:60 分钟内有效、只能用一次;重新生成后旧码立刻作废。另外也支持把已知的微信用户 ID 直接填进「允许的用户」(多个用逗号分隔),适合固定白名单场景,但不如配对码直观。

底层实现:配对状态机与暴力破解防护

配对逻辑全部集中在 adapters/common/pairing.ts,包括:

  • 6 位安全码生成:generatePairingCode 从字母表 ABCDEFGHJKMNPQRSTUVWXYZ23456789 中随机取 6 个字符——排除了易混淆的 0/O/1/I/L,降低手动输入出错率(pairing.ts)。
  • 一次性使用:tryPair 校验成功后,会把该用户写入 pairedUsers 并立即清空 pairing.code/expiresAt/createdAt,旧码彻底作废(pairing.ts)。
  • 速率限制:每个 userId 在 5 分钟内最多失败 5 次,超过后 isRateLimited 直接拒绝继续尝试,防暴力枚举(pairing.ts)。
  • 授权判定是并集:isPaired 返回 pairedUsers 与 allowedUsers 的并集;当两者都为空时默认拒绝一切访问(pairing.ts)。这也是 FAQ 里「扫码成功仍提示未授权」的根本原因——扫码只写入了机器人凭据,授权名单仍为空。

配对码对大小写和首尾空格不敏感(trim().toUpperCase() 后比较),对中文用户友好。

选项目并开始对话

配对成功后,第一条消息的流向取决于是否配置了「默认项目」:

  • 配了「默认项目」:第一条消息直接在那个目录下开一条会话。
  • 没配:机器人先列出最近用过的项目(最多 10 个,带编号、项目名、分支和绝对路径),回复编号、项目名或绝对路径即可完成选择。

从源码看,这个流程由 SessionSelectionController 与 showProjectPicker 协同完成:showProjectPicker 通过 httpClient.listRecentProjects() 拉取项目列表并渲染为「编号 + 项目名 + 路径」的文本(index.ts),而后续输入会先经过 sessionSelectionController.handleInput 匹配,再进入 startNewSession 用 httpClient.matchProject(query) 精确匹配项目(index.ts)。

会话建立后,同一个聊天窗口的消息会复用同一条会话——绑定关系持久化在 adapter-sessions.json(由 SessionStore 管理),桌面端重启后也能通过 restoreStoredSessionBinding 接回去(index.ts)。

常用的两个会话命令:

  • /new:清空当前绑定并重新选择项目;/new <编号、项目名或绝对路径> 则直接在指定项目下开新会话。
  • /clear:清空上下文但保留项目绑定(adapter 会先发 /clear 给桌面端会话,再回执确认,见 index.ts)。

支持的命令:聊天框即菜单

微信没有可配置的菜单,命令入口就是聊天框本身。配对成功后机器人会提示发 /help。formatImHelp 维护了一份完整命令清单(adapters/common/format.ts),结合 routeUserMessage 的分发逻辑(index.ts),核心命令如下:

命令 中文别名 作用
/help 帮助 显示可用命令
/status 状态 当前项目、分支、模型、运行状态和任务摘要
/projects 项目列表 重新列出最近项目
/new 新会话 清空当前绑定并重新选择项目
/new <编号、项目名或绝对路径> — 直接在指定项目下开新会话
/clear 清空 清空上下文,保留项目绑定
/stop 停止 停止本轮生成(通过 bridge.sendStopGeneration 发停止信号)
/allow <id> — 允许某次权限请求
/always <id> — 永久允许同类请求
/deny <id> — 拒绝权限请求

/status 的实现值得展开:buildStatusText 会先恢复会话绑定,再通过 httpClient.getGitInfo 取仓库名与当前分支、通过 httpClient.getTasksForSession 汇总任务统计,最后交给 formatImStatus 渲染为「项目 / 分支 / 会话 / 模型 / 状态 / 待审批数 / 任务统计」的结构化文本(index.ts);状态标签(思考中、生成中、执行工具中、等待权限确认、空闲)由 format.ts 统一映射。注意:命令仅在不带附件时触发,带附件时会优先按媒体消息处理(index.ts)。

权限审批与消息表现

文本化的权限审批

当 Claude 请求敏感权限时,微信里会收到一条带 request id 的文本消息,形如「需要权限确认 requestId] / 工具: 工具名 / 输入预览」,其格式由 formatPermissionRequest 生成([format.ts)。回复以下任一命令即可完成审批:

  • /allow <requestId> — 允许这一次
  • /always <requestId> — 永久允许同类请求
  • /deny <requestId> — 拒绝

底层上,handleServerMessage 收到 permission_request 消息后,会把 requestId 加入该聊天的 pendingPermissions 集合并递增 pendingPermissionCount(index.ts);用户回复时 parsePermissionCommand 解析出 {requestId, allowed, rule},校验该 id 确实处于待确认状态后才通过 bridge.sendPermissionResponse 回传桌面端,并同步递减待审批计数(index.ts)。

消息投递机制

  • 长轮询收消息:pollLoop 以 35 秒超时调用 ilink/bot/getupdates,用 get_updates_buf 作为游标增量拉取,出错则退避 3 秒重试(index.ts)。
  • 分片发送:正文按 WECHAT_TEXT_LIMIT = 3500 字符上限分片(index.ts),分片算法优先在段落、换行、句号、空格处切分,保证阅读连贯(format.ts)。发送时携带 context_token,失败会自动去掉 token 重发一次(index.ts)。
  • 正在输入提示:WechatTypingController 在 thinking、tool_executing、streaming 期间每 5 秒向微信续一次 typing 状态,轮次结束发 cancel(adapters/wechat/typing.ts);typing 依赖 getconfig 返回的 typing_ticket,因此即使没有逐字流式文本,用户也能感知「机器人正在干活」。
  • 附件处理:图片会以 base64 内联进模型输入(type: 'image'),其他文件则以本机临时路径传给会话(type: 'file' + path),超出大小限制时 checkAttachmentLimit 会让机器人在微信里给出提示(index.ts)。

附件下载与解密

微信 CDN 上的图片/文件是加密存储的,adapters/wechat/media.ts 处理了完整链路:collectWechatMediaCandidates 从消息的 image_item / file_item 提取下载地址与密钥 → WechatMediaService.downloadCandidate 下载字节 → 用 AES-128-ECB 解密(密钥来自消息里的 aeskey)→ 写入 AttachmentStore 管理的工作目录。对应场景的 MIME 类型(png/jpg/gif/webp/pdf/txt)通过扩展名推断(media.ts)。

解除绑定:两种粒度

「解除绑定」支持两种粒度:

  • 「解除微信绑定」:清掉整个机器人账号凭据和这个平台的授权名单,之后需要重新扫码。对应 WECHAT_ACCOUNT_ID/WECHAT_BOT_TOKEN 从本机配置中清除。
  • 「已配对用户」列表中的「解绑」:只撤销那一个人,其他人不受影响。被解绑的人需要重新发一枚新配对码。对应从 pairedUsers 数组中移除该用户的 userId。

本地开发启动与配置

发布版桌面端会自动把 adapter 作为 sidecar 拉起。只有从源码运行或单独调试时才需要手动启动:

cd adapters
bun install
bun run wechat

bun run wechat 对应 adapters/package.json 中的脚本 bun run wechat/index.ts(adapters/package.json)。

可选的环境变量覆盖(优先级:环境变量 > ~/.claude/adapters.json > 默认值,见 adapters/common/config.ts):

export WECHAT_ACCOUNT_ID="..."
export WECHAT_BOT_TOKEN="..."
export WECHAT_BASE_URL="https://ilinkai.weixin.qq.com"
export WECHAT_USER_ID="..."
export ADAPTER_SERVER_URL="ws://127.0.0.1:3456"

各变量含义与默认值:

环境变量 作用 默认值
WECHAT_ACCOUNT_ID 机器人账号 ID(iLink bot id) 读 adapters.json,缺失则启动失败
WECHAT_BOT_TOKEN iLink 机器人令牌 读 adapters.json,缺失则启动失败
WECHAT_BASE_URL iLink API 网关地址 https://ilinkai.weixin.qq.com
WECHAT_USER_ID 机器人的 ilink 用户 ID 空
ADAPTER_SERVER_URL 桌面端 WebSocket 服务地址 ws://127.0.0.1:3456

补充两个与微信链路直接相关的全局配置:

  • CLAUDE_CONFIG_DIR:配置文件目录,默认 ~/.claude(config.ts)。adapters.json 存凭据与授权,adapter-sessions.json 存会话绑定。
  • ADAPTER_ALLOWED_PROJECT_ROOTS:IM 会话可访问的项目根目录边界(路径分隔符分隔),未配置时默认收窄为「主目录 ∪ 默认项目目录」,且拒绝把 /、/Users 这类祖先目录当作边界(config.ts)。

正常使用桌面端不需要手动设置这些变量,扫码绑定会写好本机配置。

常见问题排查

扫码成功后发消息仍提示未授权:这是正常流程。扫码只写入机器人账号凭据,具体用户还要发配对码,或被写进「允许的用户」。可对照 adapters.json 里 wechat.allowedUsers / wechat.pairedUsers 是否有该用户的 userId。

二维码提示过期:重新点「扫码绑定」生成新的。微信扫码登录状态只在短时间内有效(源码中 QR_LOGIN_TTL_MS 为 5 分钟)。

adapter 启动时报缺少微信账号:WECHAT_ACCOUNT_ID/WECHAT_BOT_TOKEN 和 ~/.claude/adapters.json 里对应的 wechat.accountId/wechat.botToken 字段都没生效,先在设置页完成扫码绑定。adapter 启动时的校验逻辑见 index.ts。

收不到回复:依次确认:桌面端在运行;Tab 里显示「微信已绑定」;当前用户已配对或在「允许的用户」里;~/.claude/adapters.json 能正常写入;源码运行时还要确认 ADAPTER_SERVER_URL 指向正在运行的桌面服务。

重启后会话没接回来:检查 ~/.claude/adapter-sessions.json 能否正常写入,以及桌面端里那条会话是否还在。会话恢复依赖 restoreStoredSessionBinding 读取 SessionStore 的持久化绑定。

源码入口与测试

微信链路的完整实现分布如下:

测试方面,adapters/wechat/tests/protocol.test.ts 覆盖了客户端版本号编码、纯文本/语音/引用文本抽取、图片与文件媒体候选收集、sendmessage/sendtyping 非零返回码的抛错行为;adapters/wechat/tests/typing.test.ts 覆盖 typing 指示器的启停。运行测试:cd adapters && bun run test:wechat。

登录后查看全文
cc-haha