cc-haha 钉钉接入实战指南:Stream 长连接、扫码授权与 AI Card 流式机器人
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 与桌面端核心服务的协作分三层:
- 钉钉侧:
DWClient与钉钉 Stream 网关保持长连接,接收机器人消息与卡片回调;getAccessToken()用clientId/clientSecret换取调用钉钉 OpenAPI 的accessToken,并做本地缓存(到期前 60 秒内刷新)。 - adapter 侧:
helpers.ts负责从原始 payload 中提取发送者、会话 ID、文本与附件候选;WsBridge与桌面服务建立 WebSocket 连接(默认ws://127.0.0.1:3456),SessionStore记录"钉钉聊天 → Claude 会话"的绑定关系。 - 桌面服务侧:
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,按以下步骤完成绑定:
- 在「扫码绑定钉钉机器人」区域点击「扫码绑定」。
- 用钉钉手机 App 扫码,并在钉钉中确认创建和授权。
- 等待页面显示「钉钉机器人已绑定」。
授权成功后,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):
- 回到设置页顶部的「配对管理」,点击「生成配对码」。
- 在钉钉里私聊机器人,把这枚 6 位码发过去。
- 看到配对成功提示后即可开始对话。
从源码看,配对码的安全设计相当严谨:
- 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:
- 服务器
content_delta增量到达后写入MessageBuffer,按 1200ms 或 200 字符的节奏触发刷盘; - 首帧创建卡片实例(
POST /v1.0/card/instances再deliver),之后用PUT /v1.0/card/streaming持续推送msgContent,末尾追加▍光标; - 结束时调用
finish更新卡片状态为FINISHED(flowStatus: '3'); - 卡片 API 有严格的限流保护:令牌桶 20 QPS,命中
QpsLimit(403)自动退避 2 秒重试,单请求超时默认 15 秒(可用环境变量CC_HAHA_IM_CARD_REQUEST_TIMEOUT_MS调整); - 任何卡片异常都会捕获并回退为 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 重新建立即可。
源码入口速查
- 适配器主逻辑:adapters/dingtalk/index.ts — Stream 连接、消息路由、会话管理、权限审批
- 消息解析:adapters/dingtalk/helpers.ts — 单聊判定、文本/附件提取
- AI Card 流式服务:adapters/dingtalk/ai-card.ts — 卡片创建、流式更新、限流退避
- 权限互动卡片:adapters/dingtalk/permission-card.ts — 卡片参数构造与回调解析
- 附件下载:adapters/dingtalk/media.ts — downloadCode 换 URL、落盘与 MIME 推断
- 流式状态管理:adapters/dingtalk/stream-state.ts — 卡片缓冲区的收尾与重置
- 公共能力(跨平台复用):pairing.ts(配对码)、config.ts(配置加载)、session-store.ts(会话绑定)、ws-bridge.ts(与桌面服务的 WebSocket 桥)、http-client.ts(桌面服务 API 客户端)
- 测试:
adapters/dingtalk/__tests__/下 4 个测试文件覆盖消息解析、卡片参数与流式状态收尾

