dsh-ding-card
钉钉 AI 卡片交互插件 · 正式版本 v0.5.0（v2029.10.29）
把 DeepSeek Harness（DSH）的人机交互变成钉钉互动卡片：当 Agent 需要提问、审批或展示结构化信息时，插件自动投放一张带推荐选项的卡片；用户点击按钮后，答案直接回到正在流式运行的会话里。Web 界面与钉钉卡片同时可用，先答者生效。
插件复用 dsh-im 已经配置好的钉钉机器人与 Stream 连接，不再新建连接、不复制密钥。安装后左侧边栏会出现「钉卡片」，在里面设计卡片、绑定模板，并让 Agent 在对话中按场景选择卡片。
功能特性
卡片库
- 添加 / 编辑卡片：选择类型（消息卡片 / 吊顶卡片），设计标题、正文、字段、图片、按钮，实时预览，填写卡片说明。
- 按钮体系：每个选项有显示标签与回传值；按钮垂直排列。
- 成组卡片（按钮 + 旁文本回传区，如答题卡
btnsA ↔ btnsAvalue）：按钮显示短标签，旁文本显示完整内容，回传值自动去序号前缀（A. 中国神话中的神 → 按钮 A、回传 中国神话中的神）。
- 非成组卡片（只有按钮，如消息卡
option1..N、审批同意/拒绝）：按钮文案即回传值，完整显示。
- JSON 导入 / 导出：按钉钉卡片搭建器格式导出模板 JSON，导入后保持设计一致。
- 发送测试：选择会话、模糊查询会话、自定义参数（含模板变量）后直接投放测试。
- 卡片类型 / 名称模糊筛选：卡片库支持按类型多选 + 关键词筛选。
变量集
- 模板变量 + 自定义变量：模板变量随钉钉侧模板变动，自定义变量为插件扩展。
- 类型体系：普通文本、长文本、数字、链接、图片、音乐音频、封面图、日期等；按类型生成录入控件与 Mock。
- 重复检测：变量名与类型相同不能重复添加，导入 JSON 自动跳过重复。
- 筛选与统计：支持按变量类型多选筛选、按名称/描述模糊搜索；顶部显示变量总数。
交互与回调
- 提问卡片：
ask_user_question 自动转为带选项的钉钉卡片。
- 审批卡片：工具调用需要确认时自动转为「允许 / 拒绝」按钮。
- 吊顶卡片：固定会话顶部的音乐播放器等卡片（仅单聊，一张回复最多一张）。
- 回调持久化：DSH 重启后，重启前的消息卡片回调仍可回收与记录。
- 回调日志：记录每个按钮点击的回传值详情。
- AI 流式填充：AI 卡片逐 key 流式渲染，失败自动重试并落盘
stream_failures.json 明细。
AI 自主使用（Agent 工具）
插件向 Agent 提供三个工具，使其能自己判断用哪张卡、怎么传参：
| 工具 | 作用 |
|---|
ding_card_list | 卡片清单：每卡返回 description（功能说明）、sendVariables（实际可配变量：类型/角色/paired/Mock/required）、maxOptions（按钮上限）、usedAs（question/approval/ceiling 场景）、interactive（是否等待回应） |
ding_var_list | 全量变量集：模板 + 自定义变量，含类型、Mock 示例与绑定 |
ding_card_send | 按卡片名发送：title/content/options/fields/variables，支持等待点击回传 |
Agent 读取卡片说明 → 分析功能 → 核对变量与按钮 → 判断场景与是否等待 → 自动发送并传参。
音乐播放器组件
- 发送测试预览中识别钉钉音乐播放器组件并渲染（封面、歌名、歌手、进度、播放/暂停）。
- 支持将左侧变量（音频地址 / 封面 / 标题 / 歌手）拖拽绑定到播放器槽位，持久化保存；卡片删除/更新 JSON 时绑定自动清理。
安装与配置
方式一：通过 DSH 自定义地址从 GitHub 源码安装（无需 npm / Release）
DSH 的「添加插件」输入框支持三种形式：包名、GitHub 仓库地址、本地目录路径。从 GitHub 地址安装时，DSH 底层用 pnpm 拉取源码并在本地完成安装，不要求发布 npm、不要求 GitHub Release。
- 打开 DSH → 插件 → 添加插件
- 输入框填写仓库地址（二选一）：
github:Jydsh/dsh-ding-cardhttps://github.com/Jydsh/dsh-ding-card
- 安装源保持默认（npm 官方源 / 中国大陆镜像源均可，仅影响依赖下载，不影响 GitHub 安装）
- 点「安装」，完成后重启 DSH，左侧边栏出现「钉卡片」即成功
命令行方式（--profile <profile> 指定 DSH 环境名，不同机器 / 场景可分别安装到对应环境）：
# 桌面端（desktop）环境
dsh plugin --profile desktop add github:Jydsh/dsh-ding-card
# Web（web）环境
dsh plugin --profile web add github:Jydsh/dsh-ding-card
# 其他自定义环境：把 <profile> 换成实际环境名即可
dsh plugin --profile <profile> add github:Jydsh/dsh-ding-card
指定版本安装（配合 GitHub Release tag）：
dsh plugin --profile desktop add github:Jydsh/dsh-ding-card#v2029.10.29
关于 <profile> 环境名：
- 用
dsh plugin --help 或 DSH 设置页查看当前机器可用的环境名（常见：desktop / web，也可能是自定义名称）。
- 若执行报错
profile "xxx" is managed exclusively by the Electron application，说明该环境正被 DSH 应用（Electron）独占：先退出 DSH 再执行命令行安装，或直接改用上面的 DSH 界面「添加插件」方式安装。
- 安装到哪个 profile，插件就只在该环境的 DSH 实例中生效。
关于 pnpm 构建脚本白名单（allowBuilds）：pnpm 10+ 默认不执行 Git 依赖的 lifecycle 脚本（安全机制）。本插件为纯 JavaScript、无构建产物，prepare 仅做安装校验，被拦截不影响功能。如安装时提示需要放行构建脚本，请在对应 DSH profile 的 pnpm-workspace.yaml 中把本插件加入白名单后重新安装：
# ~/.dsh/profiles/<profile>/pnpm-workspace.yaml
onlyBuiltDependencies:
- dsh-ding-card
（旧版 pnpm v9 字段名为 allowBuilds，写法相同。）
前提：执行安装的 DSH 服务器需能访问 GitHub（源码拉取需要网络）。无法访问时，可将本地 npm pack 生成的 .tgz 包拷入服务器，改用「本地目录路径 / 本地文件」方式安装。
方式二：发布到 npm 后按包名安装（可选）
dsh plugin add dsh-ding-card（官方源或中国大陆镜像源均可）。本仓库未自动发布，需要时按需发布。
手动安装（本地开发）
- 安装 dsh-im 并配置好钉钉机器人（插件复用其连接，不复制密钥）。
- 安装本插件到 DSH 的
integrations/dsh-ding-card。
- 重启 DSH，左侧边栏出现「钉卡片」入口。
- 在「卡片库」添加卡片 → 导出模板 JSON → 在钉钉后台导入并绑定模板 ID。
- 在「变量集」维护变量与 Mock，在「发送测试」验证效果。
开发与测试
node --test "D:\dsh\dsh-ding-card\test\*.test.mjs" # 42/42
node --check lib/export.js lib/tools.js # 语法检查
- 生效规则：
tools.js / export.js / cards.js 改动需重启 DSH；client.js 改动重开管理页即可。
目录结构
lib/
index.js 插件入口与安装
tools.js Agent 工具（ding_card_list / ding_var_list / ding_card_send）
cards.js 卡片生命周期（发送/回调/回收/持久化）
export.js 卡片数据构建与模板导出
import.js 钉钉模板 JSON 导入
store.js 配置与变量集
interactions.js 提问/审批卡片接入
stream-bridge.js 钉钉 Stream 回调
dshim.js dsh-im 集成
rpc.js 管理页 RPC
client.js 管理界面（卡片库/变量集/发送测试/日志）
docs/ 架构与模板文档
test/ 单元测试
License
MIT
