dsh-dingtalk-interact
Verifieddsh-dingtalk-interact · v0.4.1 · MIT · Web UI
DeepSeek Harness 钉钉交互插件:把工具审批与 ask_user_question 推到钉钉(卡片按钮或短码作答),并推送任务完成/出错通知、支持 agent 主动发消息。与 dsh-messager-dingtalk(群 webhook 通知)职责分开。
Install
dsh plugin add dsh-dingtalk-interact Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Published to npm without a public repository. Inspect the package contents before installing.
Tags
Creators
Readme
dsh-dingtalk-interact
DeepSeek Harness 的钉钉交互插件:把 agent 的工具审批和 ask_user_question 推到钉钉,回一条带短码的消息就能批准 / 拒绝 / 作答——不用远程桌面,也不用先 /sessions 查 ID 再 /continue 绑定。
零运行时依赖,用 Node 22+ 的全局 fetch 与 WebSocket。
与 dsh-messager-dingtalk 的分工
同一个作者、同一个钉钉技术栈,但职责拆开:
dsh-messager-dingtalk |
dsh-dingtalk-interact(本包) |
|
|---|---|---|
| 方向 | 单向通知(完成 / 出错 / 需要交互) | 双向交互(审批 / 提问) |
| 连接 | 群机器人 webhook(加签) | 企业内部应用机器人 Stream 长连接 |
| 依赖 | 零依赖 | 零依赖 |
| 需要凭据 | webhook URL + 加签 secret | ClientID + ClientSecret |
| 装不装 | 可单独装 | 可单独装 |
| 通知能力 | 完成 / 出错 / 需要交互 | 完成 / 出错(notify.*,可关) |
| 主动发消息 | notify_send / notify_text |
dingtalk_notify_send / dingtalk_notify_text |
| 设置页 | 通知(DingTalk) | 通知(DingInter) |
| 消息详细度 | verbosity |
notify.verbosity |
本插件也带任务完成 / 出错通知(与 messager 同构,靠 agent/status 的 running → idle 边界)。
两个都装时通知会重复,把其中一个的 notify.completed / notify.error 关掉即可:
# 只让 messager 负责通知
notify:
completed: false
error: false
审批/提问的接管是另一个维度:通知插件不注册 answerer,不会抢审批;本插件只在自己能展示时才认领交互。
认领顺序(先弹哪儿)
approval/request 和 user-questions/request 都是 waterfall:谁先认领谁独占,
官方 Web answerer 在开机时就注册了。所以本插件提供两种模式:
interactions.order |
行为 | 适合 |
|---|---|---|
dingtalk-first(默认) |
用 { prepend: true } 抢在 Web 之前 → 钉钉先弹卡片,超时交回电脑 |
人不在电脑前 |
desktop-first |
不抢,让电脑端先弹:你在电脑上处理完 → 钉钉不弹;电脑端超时或被「委派」→ 请求才流到本插件 | 人在电脑前 |
desktop-first 依赖 DSH 的 delegate 机制:电脑端面板放弃认领时会 next() 把请求
交下去(ui-approval 内部就是 pending.delegate())。电脑端弹窗本插件不碰,不会被取消。
它是怎么绕开「绑定会话」的
传统做法要靠 chat → session 绑定才能知道「这条『批准』指哪次审批」,所以要先查会话 ID 再绑定。本插件改用短码作为关联键:
agent 要执行危险操作
↓
approval/request(waterfall)
↓ 认领请求,生成短码 A3F2
钉钉:🔐 需要审批(A3F2)
工具:Bash
操作:{"command":"npm run build"}
回复:A3F2 批准 / A3F2 拒绝 / A3F2 转电脑
↓ 你回「A3F2 批准」
router 按短码找到这次审批 → 结算 → 返回 'allowed-once'
于是「在哪个群、哪个单聊、跟哪个会话」都不重要,不需要任何绑定动作。同一时间只有一个待办时,甚至可以直接回「批准」。
前置条件(都绕不开)
- 企业内部应用:钉钉开发者后台 → 创建应用 → 拿到 ClientID / ClientSecret。
- 机器人 + Stream 模式:应用能力 → 添加「机器人」→ 选 Stream 模式 → 发布。
- 这一条替代了群机器人 webhook:自定义群机器人只能发不能收,做不了交互。
- 白名单:
allowUserIds填你的钉钉 userId(或只填target.userId)。 - (可选)互动卡片模板:想在钉钉里点按钮而不是打字,需要在本组织的卡片平台发布模板,把模板 ID 填进
card.templateId。见下文「卡片」。
安装
# 本地目录安装(推荐先用这个验证)
dsh plugin --profile desktop add "E:\DL\DeepSeek\DeepSeekMyPlugins\dsh-dingtalk-interact"
# 发布到 npm 之后
dsh plugin --profile desktop add dsh-dingtalk-interact
装完完全退出 DSH 再启动(Host 侧插件不热加载)。
第一步:先跑通 Stream(别管审批)
第一次接线最容易卡在「凭据对不对 / 机器人能不能收消息 / 我的 userId 是什么」这三件事上。 插件为此提供发现模式:只连 Stream、只把你发来的消息回显给你,不接管任何审批。
1. 建企业内部应用(约 5 分钟)
- 打开 https://open-dev.dingtalk.com/ → 应用开发 → 企业内部应用 → 创建应用。
- 「凭证与基础信息」→ 复制 Client ID(AppKey) 与 Client Secret(AppSecret)。
- 「应用能力」→ 添加「机器人」→ 消息接收模式选 Stream 模式 → 保存并发布。
- 「版本管理与发布」→ 创建版本 → 发布(企业内发布,需管理员审批)。
- 在钉钉客户端里找到这个机器人,发起单聊。
注意:这里要的是「企业内部应用机器人」,不是你之前用的「自定义群机器人 webhook」。 后者只能发不能收,做不了交互。
2. 装插件
# 方式 A:桌面版「插件」页 → 添加本地插件 → 选这个目录
# 方式 B:脚本(需先完全退出 DSH)
powershell -NoProfile -ExecutionPolicy Bypass -File "E:\DL\DeepSeek\DeepSeekMyPlugins\dsh-dingtalk-interact\scripts\install.ps1"
3. 只填两个值,打开发现模式
在 ~/.dsh/profiles/desktop/cordis.patch.yml 里追加:
- id: dingtalk-interact
config:
enabled: true
clientId: '你的ClientID'
clientSecret: '你的ClientSecret'
discovery:
enabled: true
(发现模式不校验 target / allowUserIds,因为目的就是先把 userId 捞回来。)
4. 重启 DSH,在钉钉里给机器人发一句话
机器人会回你:
✅ Stream 已连通
你的 staffId:`0123456789`
你的 senderId:`$:LWCP_v1:$xxxx`
会话类型:单聊
conversationId:`cidxxxx`
收到这条回执 = 第一步通过,同时你拿到了后面要填的 target.userId / allowUserIds。
5. 关闭发现模式,正式接线
- id: dingtalk-interact
config:
enabled: true
clientId: '你的ClientID'
clientSecret: '你的ClientSecret'
target:
kind: user
userId: '上面回执里的 staffId'
allowUserIds:
- '上面回执里的 staffId'
重启后日志应出现「已装配:目标 user …」。然后按下面的验收清单继续。
日志在哪看
桌面版里没有“Host 日志”可看——Electron 不会把 Host 进程的 stdout/stderr 落盘,
ctx.logger 的输出也被吞掉。所以插件自己写一份:
C:\Users\<你>\.dsh\logs\dingtalk-interact.log
Get-Content "$env:USERPROFILE\.dsh\logs\dingtalk-interact.log" -Tail 30 -Wait
每行是 ISO 时间 + 级别 + 正文,debug 级也会进文件(不需要开环境变量),
超过 1 MB 自动清空重写。启动时第一行就是 日志文件:<路径>,方便确认落点。
可选:命令行自检
这台机器没有 PowerShell 7,且执行策略禁止运行未签名脚本,所以下面统一用
powershell -NoProfile -ExecutionPolicy Bypass -File。
powershell -NoProfile -ExecutionPolicy Bypass -File "E:\DL\DeepSeek\DeepSeekMyPlugins\dsh-dingtalk-interact\scripts\health.ps1"
桌面版端口每次启动都变,脚本会自己从 netstat 里找候选端口并逐个探测,期望看到
ok: true、stream.state: connected。本机回环免鉴权,不需要带 cookie。
找不到端口也不要紧(桌面版可能由子进程持有)——以发现模式的钉钉回执为准。
配置
编辑 ~/.dsh/profiles/<profile>/cordis.patch.yml:
⚠️ 所有 ID 必须加单引号。钉钉的 userId 常是 18 位数字串,YAML 里不加引号会被解析成 number:前导 0 丢失、超过
2^53-1还会丢精度。 实测012345678901234567会变成12345678901234566——白名单永远匹配不上, 主动推送还会打到不存在的人。插件启动时会把这类配置打成配置可疑:...警告。
- id: dingtalk-interact
config:
enabled: true
clientId: 'dingxxxxxx'
clientSecret: 'xxxxxx'
target:
kind: user # user | group
userId: '你的钉钉userId' # kind=user 时必填
openConversationId: '' # kind=group 时必填
allowUserIds: [] # 留空 = 只允许 target.userId
approvals:
enabled: true
timeoutSecs: 30 # 超时交回桌面端;日常建议 120~300
includeArgs: true # 是否把工具参数(命令)显示出来
maxArgChars: 600
questions:
enabled: true
timeoutSecs: 600
card:
templateId: '' # 审批卡片模板;留空 = 纯文字 + 短码
questionTemplateId: '' # 问答卡片模板;留空 = 复用 templateId
questionMode: buttons # buttons=每选项一按钮 / list=单选列表(文本数组)
questionMaxButtons: 5 # buttons 模式下最多几个选项按钮
security:
allowGroupReply: false # 默认只在单聊里接受回复
| 字段 | 默认 | 说明 |
|---|---|---|
enabled |
false |
关闭时不做任何事(也不会建连) |
discovery.enabled |
false |
发现模式:只回显 userId,不接管审批/提问,不校验 target |
clientId / clientSecret |
空 | 企业内部应用凭据,不是群机器人 webhook |
clientSecretRef |
DSH_DINGTALK_INTERACT_CLIENT_SECRET |
密钥的凭据引用,优先于明文 clientSecret |
密钥放哪
推荐不写明文,让 DSH 的 credentials seam 保管(和 DEEPSEEK_API_KEY 同一套机制):
- 先把明文填进
clientSecret,clientSecretRef保持默认,启动一次; - 插件发现凭据为空会自动迁移,日志出现
已把明文 clientSecret 迁移进 credentials(DSH_DINGTALK_INTERACT_CLIENT_SECRET); - 从
cordis.patch.yml删掉clientSecret那一行,再重启; GET /dingtalk-interact/health里应看到"secret":{"ref":"...","source":"credentials:file"}。
凭据在 ~/.dsh/.credentials.yaml,不进 git 化的 YAML,也不会随配置备份外泄。
解析是每次操作重新做的(官方 seam 的约定),所以换了密钥下一个操作就生效,不用重启。
图形设置页
装好后 DSH 的「设置」里会多一项 通知(DingInter)(紧跟在 通知(DingTalk) 后面),
五组参数:连接与目标、触发时机、消息内容、节流与去重、审批与问答细节。每个字段都有说明。
写入落在 ~/.dsh/dingtalk-interact.config.json(覆盖层),不改 cordis.patch.yml——
那个文件由插件管理器整体重写,程序化改它会丢配置。读取时按「YAML → 覆盖层」叠加。
三点约定:
- 密钥不回显:设置页只显示「已配置」,留空表示沿用旧值。真密钥始终在
~/.dsh/.credentials.yaml; - 保存后需要重启 DSH:
interactions.order影响事件注册方式,只能在插件加载时决定; - 覆盖层文件损坏不影响启动(退化为空对象,读 YAML)。
| target.kind | user | 主动推送目标;user 更安全,group 会公开命令内容 |
| allowUserIds | [] | 谁能批准/作答。留空时退化为 target.userId |
| approvals.timeoutSecs | 30 | 超时后交回电脑端(next()),不是拒绝。默认偏短,日常建议 120~300 |
| approvals.includeArgs | true | 审批消息里是否附上工具参数 |
| approvals.maxArgChars | 600 | 参数渲染上限,超出截断 |
| questions.timeoutSecs | 600 | 提问超时后交回电脑端 |
| notify.completed | true | 任务结束(完成/中止/受阻/超限/中断)时推送通知 |
| notify.error | true | 步骤或回合出错时推送通知 |
| notify.titlePrefix | DSH- | 标题前缀,显示在标题与正文顶部 |
| notify.dedupMs | 1000 | 同一会话两次通知的最小间隔(完成防抖) |
| notify.interactionCooldownMs | 10000 | 同类交互通知的冷却时间 |
| notify.ratePerMinute | 20 | 每分钟最多推送条数,超出丢弃 |
| notify.verbosity | detailed | 消息详细度:detailed 附原因/错误/位置 / simple 只给结论 |
| tools.enabled | true | 是否向 agent 暴露 dingtalk_notify_send / dingtalk_notify_text |
| tools.maxTextChars | 4000 | 主动消息正文长度上限 |
| interactions.order | dingtalk-first | 认领顺序:dingtalk-first 钉钉先弹 / desktop-first 电脑先弹 |
| card.templateId | 空 | 审批卡片模板 ID;空则纯文字 |
| card.questionTemplateId | 空 | 问答卡片模板 ID;空则复用 templateId |
| card.questionMode | list | 问答呈现:list 单选列表(默认)/ buttons 每选项一按钮 |
| card.questionMaxButtons | 5 | buttons 模式下最多渲染几个选项按钮 |
| card.optionsShape | object | 列表数组形状:object(默认,列表项绑 ${item.text})/ text |
| card.customOptionLabel | 自定义 | 追加的「自定义」选项;选中它才读补充内容 |
| security.allowGroupReply | false | 群聊里是否接受回复 |
会话标题始终显示在正文里(
notify.includeSessionTitle仅作兼容保留,默认 true)。 「问答呈现方式 / 列表数组形状 / 自定义选项文案」已按真机验证通过的组合固定,不再暴露在设置页。
使用
审批消息长这样(三种消息统一「目录 → 会话 → 正文」排版):
### 🔐 DSH-需要审批(A3F2)
目录:E:\work
会话:构建任务
正文:
工具:Bash
操作:{"command":"npm run build"}
⏳ 30 秒内未回复将转回电脑端。
回复:`A3F2 批准` / `A3F2 拒绝` / `A3F2 转电脑`
| 回复 | 效果 |
|---|---|
A3F2 批准 / A3F2 同意 / A3F2 yes / A3F2 allow |
放行一次(allowed-once),不会长期提权 |
A3F2 拒绝 / A3F2 no / A3F2 deny |
拒绝 |
A3F2 转电脑 |
立刻交回电脑端弹窗(你正在电脑前时用这个) |
批准(只有一个待办时) |
同上,省略短码 |
重复回复不会二次生效:同一短码在 30 秒内再回一次,会收到 🔁 已处理(这一条已经处理过了);
超过 30 秒则回 短码无效(因为待办早已结算,插件不再记得它)。
这条覆盖了钉钉重推消息和你手抖连点两种情况。
提问消息:
### ❓ DSH-需要回答(K7M3)
目录:E:\work
会话:部署任务
正文:
【部署环境】 部署到哪个环境?
1) staging — 预发
2) prod — 生产
3) 自定义 — 在下方「补充内容」里填写
多问题用 K7M3 1: 2 + 换行;多选用逗号 K7M3 1,3;没有选项时直接回文字(自由文本)。
人在电脑前时回 K7M3 转电脑,问题会交回网页端弹窗(否则问题只在钉钉里,网页端看不到)。
卡片模式下选项由控件显示,正文只写「N 个选项见下方列表」,避免同一份选项出现两遍。 「自定义」项被选中时,答案 = 补充内容里的文字;选了具体选项时补充内容会被丢弃。
任务通知与主动消息
自动通知(系统事件驱动)
回合结束时自动推一条,内容由模板决定,不需要 agent 参与:
### DSH-✅ 任务完成
目录:E:\work
会话:重构回调
正文:
本次任务已结束
时间:2026/11/2 08:55:00
| 结束原因 | 标题 |
|---|---|
| 正常结束 | ✅ 任务完成 |
aborted |
⏹️ 任务中止 |
blocked |
⛔ 任务受阻 |
error |
❌ 任务失败 |
max-tokens |
📏 输出达上限 |
interrupted |
⚠️ 任务中断 |
notify.verbosity: detailed(默认)会附上结束原因、错误文本与 turn/step 位置;
simple 只给结论。子代理(origin === 'subagent')不通知,避免一个 turn 刷出多条。
主动消息(agent 决定)
模型可以调用两个工具,在回合中途主动开口:
| 工具 | 内容 | 用途 |
|---|---|---|
dingtalk_notify_send |
Markdown 卡片 | 汇报进度、给结论、附链接 |
dingtalk_notify_text |
纯文本 | 一句话提醒(不解析 Markdown) |
工具名带
dingtalk_前缀是刻意的:DSH 不允许工具重名,重名会让注册直接抛错。 与dsh-messager-dingtalk同装时,它的notify_send走群 webhook,本插件的dingtalk_notify_send走企业内部应用单聊,两者互不干扰。
用 tools.enabled: false 可以整个关掉;tools.maxTextChars 限制单条正文长度。
验收清单(按顺序做,每步都能独立失败)
- 建连 ✅:发现模式收到回执(见上一节);或
scripts/health.ps1返回{"ok":true,...}。 —— 不通就别往下做,先查凭据 / 机器人是否选了 Stream 模式并已发布。 - 白名单 ⬜:用非白名单账号给机器人发消息,日志应出现
忽略非白名单用户。 - 收消息 ✅:用白名单账号发「你好」,日志出现
收到消息:...(此时插件不会回复,它不承担聊天职责)。 - 审批 ✅:在桌面端跑一次需要审批的命令,钉钉应收到带短码的消息;回
短码 批准,命令继续执行。 - 超时 ⬜:不回复,
timeoutSecs后电脑端应弹出原生审批框(这说明next()委派成功)。 - 转电脑 ✅:回
短码 转电脑,电脑端应立即弹出审批框。 - 提问 ✅:让 agent 调
ask_user_question,回短码 1,看回答是否正确回填。 - 重复投递 ✅:同一条回复发两次,第二次应回「已处理」,不会二次生效。
✅ = 已在真机验证,⬜ = 仅单测覆盖。
卡片(可选)
要「点按钮」而不是打字:
- 钉钉卡片平台建模板,变量名用
title/text/actions; - 按钮
type用request(才会回调),actionId用approve/reject/delegate; - 开放平台开通权限
qyapi_chat_manage并重新发布应用版本; - 把模板 ID 填进
card.templateId。
请求体(按官方规范,踩过坑后修正)
POST /v1.0/im/interactiveCards/send 的必填字段只有四个:
cardTemplateId、outTrackId、cardData、conversationType。
| 场景 | conversationType |
还要填 | 不能填 |
|---|---|---|---|
| 单聊 | 0 | receiverUserIdList: [userId] |
robotCode、chatBotId、openConversationId |
| 群聊 | 1 | openConversationId、robotCode |
receiverUserIdList |
三个实测错误,根因都在请求体:
| 报错 | 根因 |
|---|---|
403 ... [qyapi_chat_manage] |
应用没开权限,且开完要重新发布版本 |
400 MissingconversationType |
没有该字段(它是必填的) |
400 chatbot.notFound |
单聊里传了 robotCode。官方明确:单聊时 robotCode 与 chatBotId 都不填 |
这个接口没有
openSpaceId/imRobotOpenDeliverModel字段——那是别的卡片形态(酷应用/吊顶)的写法, 早期版本照它猜过,是错的。
复杂类型必须走 sys_full_json_obj(按钮组的真正坑)
这是最后一个、也是最隐蔽的一个。官方 FAQ 原文:
对于值类型是简单字符串、数字的,把字段放到
cardData.cardParamMap里; 而值类型是复杂类型的,比如对象或对象数组,则需要放到cardData.cardParamMap.sys_full_json_obj这个系统字段里。该字段本身是一个 JSON 字符串,构造完 JSON 之后还需要再转成字符串。
所以按钮组(对象数组)不能写成 cardParamMap.actions,而要写成:
{
"cardData": {
"cardParamMap": {
"title": "需要审批",
"text": "……",
"sys_full_json_obj": "{\"actions\":[{...按钮1...},{...按钮2...}]}"
}
}
}
症状极易误判:发送返回 200、卡片正常渲染、标题正文都对,只有按钮组是空的, 且用平台自带的「发送测试」却能看见按钮——因为平台内部走的是另一条数据通道。
排查方法:node scripts/probe-card.mjs 会同时发 full-json 和 flat 两个变体,
钉钉里一对比就知道该用哪种编码(无需重启 DSH)。
回调路径:按钮点击 → Stream topic /v1.0/card/instances/callback → 按 outTrackId(就是短码)结算。
按钮回调能打通,靠的是这一条:userId(卡片创建者)
决定性的坑。 前面全部做对(createAndDeliver + callbackType: STREAM + 空间模型 + 按钮渲染正常 + Stream 订阅正确),
按钮点击依然零事件。原因是 createAndDeliver 请求体里漏了 userId。
官方 CreateAndDeliver 示例(单聊机器人)里它是必带字段:
const createAndDeliverRequest = new CreateAndDeliverRequest({
userId, // ← 卡片创建者,漏了回调就无处可投
cardTemplateId,
outTrackId,
callbackType: 'STREAM',
cardData,
imRobotOpenSpaceModel,
imRobotOpenDeliverModel,
openSpaceId: `dtv1.card//im_robot.${userId}`,
userIdType: 1,
});
补上后,点击 → 回调 2 秒到达并结算。实测日志:
卡片已发送(createAndDeliver)
卡片回调帧:{"type":"actionCallback","outTrackId":"AW93",
"content":"{\"cardPrivateData\":{\"actionIds\":[\"approve\"],\"params\":{}}}"}
卡片回调:outTrackId=AW93 action=approve
审批 AW93 → allow
回调载荷怎么解析
content 是 JSON 字符串(不是对象),按钮信息在 cardPrivateData 里:
{
"type": "actionCallback",
"outTrackId": "AW93",
"userId": "0451114...",
"content": "{\"cardPrivateData\":{\"actionIds\":[\"approve\"],\"params\":{}}}"
}
代码里同时兼容两条取值线(parseCardCallback):
content.cardPrivateData.actionIds → content.cardPrivateData.params.action → 旧形态兜底。
空数组视为「没有」(静态按钮场景 actionIds 可能是 [],真正信息在 params)。
按钮对象的结构
每项长这样(和 {id, text, type} 完全是两套,旧结构会让按钮组渲染为空):
{
"text": "批准",
"color": "blue",
"status": "normal",
"event": { "type": "request", "params": { "actionId": "approve", "params": { "code": "短码" } } }
}
模板侧两种做法都能出按钮:
- 绑定变量:数据走
cardParamMap.sys_full_json_obj; - 指定(静态按钮):模板里直接配「回传请求 + 回传参数 actionId」,数据侧不用管按钮(本项目最终采用,最稳)。
问答卡片怎么做
审批按钮是固定的三个,问答的选项数量随题目变化,静态模板表达不了。所以问答需要另一个模板,
而且提供两种呈现方式(card.questionMode):
| 模式 | 模板组件 | 适合 | 选项数限制 |
|---|---|---|---|
buttons(默认) |
按钮组,绑定变量 actions |
选项少、要一键直达 | ≤ questionMaxButtons(默认 5) |
list |
单选列表,绑定文本数组变量 options |
选项多、文案长 | 不受限 |
⚠️ 单选列表必须配一个「提交」按钮走回传请求。 单选列表选中默认只「更新本地变量」(比如
choice),不会发回调; 只有点击事件类型为「回传请求」的组件才会把数据推给插件。 把choice绑到提交按钮的回传参数里,回调才会带回选中项。
模式一:按钮组(buttons)
1. 方案A ← actionId = opt:0
2. 方案B ← actionId = opt:1
转电脑 ← actionId = delegate
模式二:单选列表(list)
插件把选项文案作为文本数组交给单选列表:
{ "cardParamMap": { "options": "[\"方案A\",\"方案B\",\"方案C\"]" } }
回调带回的可以是文案,也可以是序号(choice: 1)——插件两种都认:
| 回传内容 | 处理 |
|---|---|
{ choice: "方案A" } |
按文案命中 → selected: ["方案A"] |
{ choice: 1 } |
按序号映射 → selected: ["方案B"] |
| 序号从 1 开始 | 配 card.choiceIndexBase: 1 |
自定义内容:卡片里输入,或者聊天里打字
回调解析不认键名,只认取值,所以以下都能被正确归类:
| 用户动作 | 回调 params | 结算结果 |
|---|---|---|
| 选中「方案A」 | { choice: "方案A" } |
{ selected: ["方案A"] } |
| 只输入了文字 | { input: "想用方案D" } |
{ selected: [], custom: "想用方案D" } |
| 选中 + 补充说明 | { choice: "方案A", note: "但延迟要更低" } |
{ selected: ["方案A"], custom: "但延迟要更低" } |
想在卡片内自定义作答,模板里要有**「文本输入」组件**并把它的变量放进提交按钮的回传参数;
没有输入组件时,回聊天里打 短码 你的答案 一样可以。
什么时候不给卡片交互
| 情况 | 原因 |
|---|---|
| 题目没有预设选项 | 自由文本题,选项列表无从生成 |
multiSelect: true |
单选列表/按钮都表达不了多选 |
buttons 模式下选项数 > 5 |
卡片会变得过长 |
| 一次多个问题 | 一张卡片放不下多题的控件 |
只配了
card.templateId(审批模板)时,问答会用同一个模板发卡片—— 此时选项控件出不来,但正文/短码照常显示,仍然可以文字作答。
另外卡片里的文本组件不解析 Markdown,正文里的 ###、反引号会原样显示——
所以发给卡片时会把 Markdown 标记去掉(降级成文字时仍保留 Markdown)。
兜底与熔断
- 卡片发送任何失败都会立即降级为「纯文字 + 短码」,审批绝不会因为卡片发不出去而卡死;
- 失败后熔断 10 分钟(
cardGate),期间直接走文字,不再白打请求;成功一次立刻恢复; - 健康路由里能看到熔断状态:
"cardGate":{"blocked":true,"retryInMs":...,"lastError":"..."}。
实测记录
环境:Windows 11 · DSH 0.2.1-rc.5 · Node v24.21.0 · 桌面版 profile · 2026-11-01
| 场景 | 结果 | 证据 |
|---|---|---|
| Stream 建连 | ✅ 0.8s | 日志 stream 已连接 |
| 发现模式回显 userId | ✅ | 钉钉收到回执 |
| 主动推送(access_token → robot) | ✅ HTTP 200 | invalidStaffIdList: [] |
| 审批 → 批准 | ✅ | 文件在批准同秒被创建 |
| 审批 → 拒绝 | ✅ | 文件未被改动 |
| 审批 → 转电脑 | ✅ | 2s 后由桌面端完成 |
| 提问 → 推送 → 短码作答 → 回填 | ✅ 31s 往返 | 日志 提问 4MC6 已由钉钉回答 |
| 重复回复幂等 | ✅ | 第二次回复日志只有 收到消息,未再出现 审批 X → allow |
| 卡片 → 按钮渲染 | ✅ | 按钮组走 sys_full_json_obj 后钉钉里出现三个按钮 |
| 卡片按钮 → 回调 | ✅ 2s | 补上 userId 后:点「批准」→ actionCallback 到达 Stream → 审批 AW93 → allow → 文件同秒写入 |
仍只由单测覆盖、未真机验证:多待办歧义提示、群聊回复。
安全
- 白名单是唯一的批准人边界。审批等于「允许执行一条命令」,白名单配错 = 把执行权交出去。
- 默认只走单聊(
target.kind: user),命令内容不会进群;allowGroupReply: false默认拒绝群聊回复。 - 放行是
allowed-once,只对本次动作有效,没有持久提权。 - 日志不打印
clientSecret与access_token;健康路由走 DSH 的 cookie 鉴权,且只暴露「连接状态 / 待办数 / 白名单人数」。 - 超时是交回电脑端(
next())而不是自动拒绝或自动放行——保持 fail-closed 语义。
已知限制
- 提问桥依赖
user-questions/requestwaterfall。DSH 0.1.x 起,官方 Web answerer 走的是这个事件;更老的版本只有ctx.userQuestions.ask+ 单一 provider,本插件不会去抢 provider(那会让网页端失效),所以老版本上提问桥不生效,审批桥不受影响。启动日志里的已装配:... 提问 开只表示注册了监听,不代表事件真的会被触发。 - 没有 webhook 通道。必须建企业内部应用(需要管理员权限、发版审批)。想走「群机器人 webhook、5 分钟接入」请用
dsh-messager-dingtalk。Stream 断开期间本插件无法推送任何消息。 desktop-first下钉钉可能一直收不到。这取决于电脑端是否真的会「委派」;如果 DSH 的电脑端面板永不放弃认领,请求就不会流到本插件(这时它只在 GUI 不可用时接管)。要保证钉钉一定收到,用dingtalk-first。- 设置页保存后需重启 DSH,原因见上文。
- 同一时刻超过
stream.maxPending条待办时,新的审批直接交回下游(宁可走电脑,也不排队堵住 agent)。 - 群聊回复默认关闭;即便打开,命令内容也已发到群里,属于既成事实。
dingtalk_notify_text走钉钉sampleText,不解析 Markdown;要格式用dingtalk_notify_send。- 卡片回调依赖
callbackType: "STREAM"与创建卡片时的userId,两者缺一都收不到点击(踩坑记录见下文)。
故障排查
| 现象 | 原因 |
|---|---|
日志 配置不完整:... |
缺 clientId/clientSecret/target,补齐后重启宿主 |
日志 建连失败:HTTP 400/401 |
ClientID/Secret 错,或机器人不是 Stream 模式、未发布 |
日志 stream 已连接 但发消息没反应 |
机器人没被拉进该会话,或应用没勾选消息接收权限 |
| 审批一直不弹到钉钉 | 用的是自定义群机器人 webhook(只能发不能收),必须换企业内部应用 |
| 回复「批准」没反应 | 同时有多个待办 → 必须带短码;或账号不在白名单;或群聊里回(默认关闭) |
| 卡片没出来 | 模板 ID 没填 / 模板未在本组织发布 / 权限不足 → 看日志里的降级提示 |
卸载
dsh plugin --profile <desktop|web> remove dsh-dingtalk-interact
并删掉 cordis.patch.yml 里对应的 insert 条目。
开发
npm test # 逐文件跑(node --test 会 spawn 子进程,在受限沙箱里会 EPERM)
目录:
lib/
index.js 装配:配置自检 → 待办表 → Stream → 两个 seam 桥 → 健康路由
config.js 默认值/收敛/自检(零依赖,手写深合并)
text.js 渲染与解析(短码、审批措辞、问题答案)
pending.js 短码 → 挂起中的审批/提问
protocol.js Stream 帧、ACK、机器人消息与卡片回调归一化
stream.js Stream 长连接(建连/ACK/退避重连)
token.js access_token 缓存
api.js 主动推送 / sessionWebhook 回复 / 纯文本发送
card.js 互动卡片(可选,失败降级)
deliver.js 卡片优先、文字兜底
router.js 入站消息 → 结算待办
approval.js approval/request 桥
questions.js user-questions/request 桥
notify.js 任务完成 / 出错通知(订阅 agent/status、session/event、agent/error)
tools.js dingtalk_notify_send / dingtalk_notify_text(agent 主动发消息)
session-meta.js 会话标题与目录(带回扫事件日志)
store.js 配置覆盖层(~/.dsh/dingtalk-interact.config.json)
config-route.js /dingtalk-interact/config 读写(密钥脱敏)
client.js 浏览器设置分区「通知(DingInter)」
设计取舍记在代码注释里,几处值得看:
approval.js/questions.js:为什么默认{ prepend: true }。官方 Web answerer 在 boot 时先注册,而 waterfall 是「先认领者胜」,不 prepend 会永远拿不到请求。desktop-first就是显式放弃 prepend,让电脑端先认领。router.js:为什么不按会话绑定路由,以及「多于一个待办必须带短码」的判定。session-meta.js:为什么标题要回扫session/title事件(session.title不是可靠的实时字段)。tools.js:为什么工具名带dingtalk_前缀(DSH 不允许重名,重名会让注册整体抛错)。store.js:为什么不直接改cordis.patch.yml(插件管理器会整体重写,程序化改会丢配置)。
许可
MIT