cc-haha 钉钉接入实战指南:Stream 长连接、扫码授权与 AI Card 流式机器人

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

cc-haha 钉钉接入实战指南:Stream 长连接、扫码授权与 AI Card 流式机器人

本文是 cc-haha 项目中钉钉(DingTalk)IM 接入模块的完整技术指南。面向把钉钉当作主力办公工具的国内团队,本文讲解如何通过扫码授权绑定机器人、用 6 位配对码授权具体用户、在单聊中切换项目并复用会话,以及 AI Card 流式回复与权限互动卡片的底层实现原理。读完本文,你可以独立完成钉钉机器人的绑定、授权、调试与常见故障排查,并理解 adapter 内部"Stream 长连接 → 消息解析 → 会话桥接 → AI Card 输出"的完整调用链。

适用场景与核心特性

钉钉接入是 IM 接入体系 中的一个平台适配器,核心定位是:扫一次码授权出一个机器人,走 DingTalk Stream 长连接,不需要公网回调地址和内网穿透。这一设计对国内办公环境尤其友好——企业内网往往没有公网 IP,也不便开放回调端口,Stream 长连接由客户端主动发起,天然规避了这些限制。

在 适配器入口 中可以看到,连接依赖 dingtalk-stream 包的 DWClient,注册两个主题回调:

  • TOPIC_ROBOT:接收机器人单聊消息(/v1.0/im/atMessages/query 一类的机器人消息)
  • TOPIC_CARD:接收互动卡片回调(权限卡片的按钮点击)

两个回调都在收到消息后先回 ACK(socketCallBackResponse),再用 MessageDedup 按 messageId 与 msgId 双重去重,避免网络重投造成重复处理。

需要明确的功能边界(源码层面可以确认):

  • 只处理单聊,不处理群聊。helpers.ts 中 isDingTalkDirectMessage 判断 conversationType === '1',handleRobotMessage 开头直接 if (!isDingTalkDirectMessage(data)) return,群聊消息被整体丢弃。
  • 回复默认用 AI Card 流式输出,失败时自动回退为普通 markdown 文本。
  • 可点的权限卡片需要额外配置模板 ID,未配置时权限请求以文本命令方式回复。

架构与消息流:从钉钉消息到 Claude 会话

在进入操作步骤之前,先建立整体架构认知。钉钉 adapter 与桌面端核心服务的协作分三层:

  1. 钉钉侧:DWClient 与钉钉 Stream 网关保持长连接,接收机器人消息与卡片回调;getAccessToken() 用 clientId/clientSecret 换取调用钉钉 OpenAPI 的 accessToken,并做本地缓存(到期前 60 秒内刷新)。
  2. adapter 侧:helpers.ts 负责从原始 payload 中提取发送者、会话 ID、文本与附件候选;WsBridge 与桌面服务建立 WebSocket 连接(默认 ws://127.0.0.1:3456),SessionStore 记录"钉钉聊天 → Claude 会话"的绑定关系。
  3. 桌面服务侧:adapter-client.ts 创建的 httpClient 负责创建会话、查询 Git 信息、拉取任务列表;会话建立后通过 WsBridge 双向收发服务器消息。

单聊会话 ID 的生成规则在 helpers.ts 中:直接消息返回 dingtalk:dm:${senderId},群聊返回 dingtalk:group:${conversationId}。配套的单测 helpers.test.ts 验证了 senderStaffId 提取与 dingtalk:dm:staff-1 格式的组装。

文本提取支持三种钉钉消息形态:text.content、markdown.text,以及富文本 content.richText 数组(逐项拼接);附件提取则覆盖 picture、file、richText 三种 msgtype。

扫码绑定机器人

打开桌面端「设置」→「IM 接入」,切到「钉钉」Tab,按以下步骤完成绑定:

  1. 在「扫码绑定钉钉机器人」区域点击「扫码绑定」。
  2. 用钉钉手机 App 扫码,并在钉钉中确认创建和授权。
  3. 等待页面显示「钉钉机器人已绑定」。

钉钉扫码绑定与手动填写凭据界面

授权成功后,Client ID 与 Client Secret 会被自动填入并写入本机配置,adapter 随即用新凭据建立 Stream 长连接,无需重启桌面端。

手动填写凭据

扫码走不通时(例如钉钉开放平台未开放扫码授权、或需要绑定已有应用),可以手动填写。字段位于扫码区域下方,与 配置类型定义 一一对应:

设置项 配置文件字段 说明
Client ID dingtalk.clientId 钉钉应用的 appKey
Client Secret dingtalk.clientSecret 钉钉应用的 appSecret
Stream Endpoint dingtalk.endpoint 可选,默认 https://api.dingtalk.com
权限卡片模板 ID dingtalk.permissionCardTemplateId 可选,填了之后权限请求优先发钉钉互动卡片
允许的用户 dingtalk.allowedUsers 可选,直接放行指定的钉钉用户 ID

填完点击「保存」,adapter 会用新凭据重新建立 Stream 长连接。配置优先级为「环境变量 > ~/.claude/adapters.json > 默认值」,详见 配置加载实现,其中 DINGTALK_STREAM_ENDPOINT 默认 https://api.dingtalk.com,ADAPTER_SERVER_URL 默认 ws://127.0.0.1:3456。

授权具体用户:配对码机制

机器人绑定成功只是第一步——具体的人还需要通过配对码获得授权。这是所有 IM adapter 共用的"配对门禁"(pairing.ts):

  1. 回到设置页顶部的「配对管理」,点击「生成配对码」。
  2. 在钉钉里私聊机器人,把这枚 6 位码发过去。
  3. 看到配对成功提示后即可开始对话。

在钉钉里发送配对码并开始对话

从源码看,配对码的安全设计相当严谨:

  • 6 位安全字符集:ABCDEFGHJKMNPQRSTUVWXYZ23456789,刻意排除了 0/O/1/I/L 这些易混淆字符;
  • 60 分钟有效期:CODE_TTL_MS = 60 * 60 * 1000,过期即失效;
  • 一次性使用:配对成功后 pairing.code 立即清空(置为 null);
  • 错误限速:同一用户 5 分钟内最多失败 5 次,防止暴力枚举;
  • 忽略大小写与空格:输入会 trim().toUpperCase() 后比较;
  • 原子写入:配置写入采用临时文件 + rename 的方式(writeConfigFile),避免写入中断损坏配置。

配对成功的人会出现在「已配对用户」列表(对应 dingtalk.pairedUsers,记录 userId、displayName、pairedAt),随时可以解绑;被解绑的用户需要重新发一枚新码。授权判定 isPaired 的逻辑是 allowedUsers 与 pairedUsers 的并集:allowedUsers 命中直接放行;两者都为空时默认拒绝(必须先配对)。用户消息在 index.ts 中先过 isAllowedUser('dingtalk', userId),未授权时把消息文本当作配对码尝试 tryPair。

选项目并开始对话

配对成功后,第一条消息会触发会话建立流程(ensureSession):

  • 若配置了「默认项目」(dingtalk.defaultWorkDir 或全局 defaultProjectDir),第一条消息直接在该目录下开会话;
  • 未配置时,adapter 调用 projectSelectionController.listProjects 拉取最近项目,回复编号、项目名或绝对路径即可选中(最近 10 个项目会带分支名展示);
  • 项目选择器也接受 /new <编号、项目名或绝对路径> 直接跳转。

之后同一个聊天窗口的消息会复用同一条会话:adapter 通过 restoreStoredSessionBinding 从 SessionStore 恢复既有绑定,断线重启后也能自动接回(会话绑定持久化在 ~/.claude/adapter-sessions.json)。

发 /new 重新选项目,发 /clear 清空上下文但保留项目绑定。

支持的命令

钉钉没有像飞书那样的机器人菜单,命令入口就是单聊输入框。配对成功后机器人会提示发 /help。完整命令集在 index.ts 的 routeUserMessage 中实现:

命令 中文别名 功能
/help 帮助 显示可用命令
/status 状态 当前项目、分支、模型、运行状态和任务摘要
/projects 项目列表 重新列出最近项目
/new 新会话 清空当前绑定并重新选择项目
/new <编号、项目名或绝对路径> — 直接在指定项目下开新会话
/clear 清空 清空上下文,保留项目绑定
/stop 停止 停止本轮生成

/status 的实现值得注意:它会通过 httpClient.getGitInfo 获取仓库名与分支,通过 getTasksForSession 统计 pending / in_progress / completed 任务数,再交给 formatImStatus 排版输出——即使 Git 查询失败也会降级返回基础状态,不会中断命令。

权限审批与消息表现

文本方式的权限审批

默认情况下(未配置权限卡片模板),权限请求以文本消息发出,回复其中一条即可完成审批:

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

权限请求的解析与响应由 permission.ts 的 parsePermissionCommand 完成,adapter 侧通过 bridge.sendPermissionResponse 把决定(allowed + 可选的 always 规则)回传给桌面服务。每轮请求都会进入 pendingPermissions 映射,未找到对应 requestId 时会明确提示"未找到待确认的权限请求"。

权限互动卡片(可选)

如果在设置页填写了已发布的「权限卡片模板 ID」,adapter 会优先发送互动卡片。相关实现在 permission-card.ts:

  • 回调路由固定为 permission(DINGTALK_PERMISSION_CARD_CALLBACK_ROUTE),创建卡片时作为 callbackRouteKey 传入;
  • 卡片参数包含 allowText: '允许一次'、alwaysText: '永久允许'、denyText: '拒绝' 三个按钮,各自携带序列化后的决定值;
  • 输入预览会被截断到 600 字符(truncateInput),防止超长工具入参撑爆卡片;
  • 按钮点击回调经 TOPIC_CARD 主题进入 handleCardCallback,parseDingTalkPermissionCardAction 会递归地在回调 payload 中寻找 requestId 与 allowed/action 字段,兼容多种钉钉回调结构;
  • 卡片发不出去或不可见时,文本命令 /allow、/always、/deny 始终可用(发送时仍会附带文本兜底提示)。

普通回复:AI Card 流式输出

普通回复默认走 AI Card 流式。核心实现在 ai-card.ts 与 index.ts:

  1. 服务器 content_delta 增量到达后写入 MessageBuffer,按 1200ms 或 200 字符的节奏触发刷盘;
  2. 首帧创建卡片实例(POST /v1.0/card/instances 再 deliver),之后用 PUT /v1.0/card/streaming 持续推送 msgContent,末尾追加 ▍ 光标;
  3. 结束时调用 finish 更新卡片状态为 FINISHED(flowStatus: '3');
  4. 卡片 API 有严格的限流保护:令牌桶 20 QPS,命中 QpsLimit(403)自动退避 2 秒重试,单请求超时默认 15 秒(可用环境变量 CC_HAHA_IM_CARD_REQUEST_TIMEOUT_MS 调整);
  5. 任何卡片异常都会捕获并回退为 markdown 文本发送,保证回复不丢失。

文本兜底通道本身也会按 3500 字符分片发送(splitMessage(text, 3500)),避免单条消息过长被钉钉截断。

附件处理

图片附件会下载后以内联 base64 图片进入模型输入;其他文件走本地路径。附件下载实现在 media.ts:先通过 downloadCode 调用 POST /v1.0/robot/messageFiles/download 换取真实下载 URL,下载后由 AttachmentStore 落盘,再经 attachment-limits.ts 检查大小限制——超出限制时机器人会在钉钉里提示,单个附件失败时提示"已跳过",全部失败时提示重试。

解除绑定

解除绑定有两种粒度:

  • 「解除机器人绑定」:清掉钉钉凭据、权限卡片模板 ID 和这个平台的授权名单,之后需要重新扫码或手动填凭据才能恢复使用;
  • 「已配对用户」列表逐人解绑:点击某个用户右侧的「解绑」,只撤销那一个人的授权(从 pairedUsers 移除)。

本地开发启动

发布版桌面端会自动把 adapter 作为 sidecar 拉起,正常使用无需手动启动。只有从源码运行或单独调试时,才需要手动启动(对应 package.json 中的 dingtalk 脚本):

cd adapters
bun install
bun run dingtalk

可选的环境变量覆盖(优先级高于配置文件):

export DINGTALK_CLIENT_ID="..."
export DINGTALK_CLIENT_SECRET="..."
export DINGTALK_STREAM_ENDPOINT="https://api.dingtalk.com"
export DINGTALK_PERMISSION_CARD_TEMPLATE_ID="..."
export ADAPTER_SERVER_URL="ws://127.0.0.1:3456"

注意:adapter 启动时会校验 clientId/clientSecret,两者都为空时直接报错退出(Missing DINGTALK_CLIENT_ID / DINGTALK_CLIENT_SECRET)。桌面端正常使用不需要手动设置这些——扫码绑定或手动填写会写进 ~/.claude/adapters.json 的 dingtalk 段:

{
  "serverUrl": "ws://127.0.0.1:3456",
  "dingtalk": {
    "clientId": "钉钉应用 appKey",
    "clientSecret": "钉钉应用 appSecret",
    "endpoint": "https://api.dingtalk.com",
    "permissionCardTemplateId": "",
    "allowedUsers": [],
    "pairedUsers": [],
    "defaultWorkDir": ""
  }
}

跑单测可用 bun run test:dingtalk(覆盖 ai-card.test.ts、helpers.test.ts、permission-card.test.ts、stream-state.test.ts)。

常见问题

扫码成功后发消息仍提示未授权:这是正常流程。扫码只写入机器人凭据,具体用户还需要发配对码,或被写进「允许的用户」(allowedUsers)才能通过授权门禁。

扫码失败或一直等待确认:重新点击「扫码绑定」生成新二维码;仍然不行就手动填写 Client ID 和 Client Secret。

adapter 启动时报缺少 clientId/clientSecret:说明环境变量和 ~/.claude/adapters.json 里的 dingtalk.clientId / dingtalk.clientSecret 都没生效。先在设置页完成扫码或手动填写,再启动。

权限卡片没出现:依次确认模板 ID 填的是已发布的模板、模板支持 adapter 用的 permission 回调路由、机器人已发布新版本。卡片不可见时,用 /allow、/always、/deny 文本命令照样能审批。

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

重启后会话没接回来:检查 ~/.claude/adapter-sessions.json 能否正常写入,以及桌面端里那条会话是否还在。会话绑定恢复依赖 restoreStoredSessionBinding,绑定记录丢失时发 /new 重新建立即可。

源码入口速查

登录后查看全文
cc-haha