Skip to content

dsh-dingtalk-interact

Verified

dsh-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'

于是「在哪个群、哪个单聊、跟哪个会话」都不重要,不需要任何绑定动作。同一时间只有一个待办时,甚至可以直接回「批准」。

前置条件(都绕不开)

  1. 企业内部应用:钉钉开发者后台 → 创建应用 → 拿到 ClientID / ClientSecret。
  2. 机器人 + Stream 模式:应用能力 → 添加「机器人」→ 选 Stream 模式 → 发布。
    • 这一条替代了群机器人 webhook:自定义群机器人只能发不能收,做不了交互。
  3. 白名单:allowUserIds 填你的钉钉 userId(或只填 target.userId)。
  4. (可选)互动卡片模板:想在钉钉里点按钮而不是打字,需要在本组织的卡片平台发布模板,把模板 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 分钟)

  1. 打开 https://open-dev.dingtalk.com/ → 应用开发 → 企业内部应用 → 创建应用。
  2. 「凭证与基础信息」→ 复制 Client ID(AppKey) 与 Client Secret(AppSecret)。
  3. 「应用能力」→ 添加「机器人」→ 消息接收模式选 Stream 模式 → 保存并发布。
  4. 「版本管理与发布」→ 创建版本 → 发布(企业内发布,需管理员审批)。
  5. 在钉钉客户端里找到这个机器人,发起单聊。

注意:这里要的是「企业内部应用机器人」,不是你之前用的「自定义群机器人 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 同一套机制):

  1. 先把明文填进 clientSecret,clientSecretRef 保持默认,启动一次;
  2. 插件发现凭据为空会自动迁移,日志出现 已把明文 clientSecret 迁移进 credentials(DSH_DINGTALK_INTERACT_CLIENT_SECRET);
  3. 从 cordis.patch.yml 删掉 clientSecret 那一行,再重启;
  4. 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 限制单条正文长度。

验收清单(按顺序做,每步都能独立失败)

  1. 建连 ✅:发现模式收到回执(见上一节);或 scripts/health.ps1 返回 {"ok":true,...}。 —— 不通就别往下做,先查凭据 / 机器人是否选了 Stream 模式并已发布。
  2. 白名单 ⬜:用非白名单账号给机器人发消息,日志应出现 忽略非白名单用户。
  3. 收消息 ✅:用白名单账号发「你好」,日志出现 收到消息:...(此时插件不会回复,它不承担聊天职责)。
  4. 审批 ✅:在桌面端跑一次需要审批的命令,钉钉应收到带短码的消息;回 短码 批准,命令继续执行。
  5. 超时 ⬜:不回复,timeoutSecs 后电脑端应弹出原生审批框(这说明 next() 委派成功)。
  6. 转电脑 ✅:回 短码 转电脑,电脑端应立即弹出审批框。
  7. 提问 ✅:让 agent 调 ask_user_question,回 短码 1,看回答是否正确回填。
  8. 重复投递 ✅:同一条回复发两次,第二次应回「已处理」,不会二次生效。

✅ = 已在真机验证,⬜ = 仅单测覆盖。

卡片(可选)

要「点按钮」而不是打字:

  1. 钉钉卡片平台建模板,变量名用 title / text / actions;
  2. 按钮 type 用 request(才会回调),actionId 用 approve / reject / delegate;
  3. 开放平台开通权限 qyapi_chat_manage 并重新发布应用版本;
  4. 把模板 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/request waterfall。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