交互卡片 MjxUpUp/dsh-visual

dsh-visual

在 DeepSeek Harness 会话里放交互卡片。模型发布一张自包含的 HTML 卡片（或一张可拖拽的流程图），工具会一直阻塞，直到用户提交，用户的点击、评论、表单字段和卡片状态都会作为工具结果返回。

没有助手文本，没有聊天消息，没有产物预览——消息流里就是一张真卡片。

dsh-visual card

特性

- 阻塞式，不是发完就走。 visual 会一直挂起，直到用户提交，所以答案以工具结果的形式到达，智能体在同一轮里继续往下走。
- 卡片可写脚本。 内联 通过一个小桥接（dshVisual.root、dshVisual.setState）按卡片执行，卡片因此能自己切换状态、校验、预填。
- 结构化答案。 按钮（data-visual-action）、输入框（data-visual-field）、评论和卡片状态合并成一个 JSON 答案。
- 带定位的评论。 右键任意元素就能留评论；答案里带上该元素的选择器和标签，模型因此清楚每条备注说的是什么。
- 流程编辑器。 不传 HTML，改传 flow 图：拖节点、双击改名、连线、删除，然后把编辑后的图交回来。
- 并行安全。 同一轮里的多张卡片各有自己的桥接和状态，互不串扰。
- 可取消、有时限。 timeoutMs 和停止按钮会把卡片变成只读，而不是一直挂着。

环境要求

- DeepSeek Harness 0.1.0-rc.1 及更新版本，低于 0.3（含预发布构建）
- Node.js 20 或更新版本

安装

dsh plugin --profile desktop add dsh-visual

重启一次 DeepSeek Harness，让宿主侧加载。之后改动 lib/client.js 只需刷新页面（⌘R）。

本地开发时，改为链接目录：

dsh plugin --profile desktop add /path/to/dsh-visual
dsh plugin --profile desktop remove dsh-visual # uninstall

快速开始

用大白话要一张卡片：

用 visual 发一张发布确认卡，让我选版本并留一句备注

模型大致会这样调用工具：

{
"title": "发布确认", "height": 360, "html": "发 0.1.1 到 npm？发先别发",
"actions": [{ "id": "approve", "label": "发" }, { "id": "hold", "label": "先别发" }],
"timeoutMs": 600000
}
用户点击后，工具返回一个 answer 对象：

{
"action": "approve",
"payload": { "fields": { "note": "记得打 tag" } },
"state": { "checks": ["install"] },
"comments": [{ "selector": "h3", "label": "h3", "text": "标题再短一点" }]
}

参数

| 参数 | 类型 | 说明 |
| title | string | 卡片头部标题。 |
| html | string | 完整、自包含的 HTML 文档。样式作用域隔离；脚本按卡片分别运行。 |
| flow | object | 流程图 {nodes, edges}，渲染成可编辑画布，替代 HTML。 |
| data | object | 初始状态，以 dshVisual.data 暴露给卡片脚本。 |
| height | number | 卡片初始高度，单位 px（160–900）。卡片可以自行调整大小。 |
| actions | array | 动作注册表 {id, label}，用于底部操作条和按钮文案。 |
| timeoutMs | number | 等待提交的时长（默认 10 分钟，最长 1 小时）。 |

除 html 或 flow 二选一外，其余字段都可选。

卡片协议

按钮与字段

- data-visual-action="id" —— 点击后提交该动作，同时带上字段、状态和评论。
- data-visual-field="name" —— 提交时从卡片读取，放在 answer.payload.fields 下返回。
- 底部始终显示一个中性的 交还 按钮（answer.action = "done"）。它不表示批准：评审卡片应自带明确的 approve/revise 动作。

脚本与状态

(function (dshVisual) {
var state = Object.assign({ on: false }, dshVisual.data || {})
dshVisual.root.querySelector('.toggle').addEventListener('click', function () {
state.on = !state.on
this.textContent = state.on ? '开' : '关'
dshVisual.setState(state) // returned as answer.state
})
})(dshVisual)

每张卡片都按 new Function('dshVisual', source)(bridge) 编译，所以并行卡片之间看不到彼此的状态。

评论

在卡片内任意元素上右键，输入备注，就会以编号固定下来。返回结果通过 answer.comments 携带它们，格式为 { selector, label, text }。

超时与取消

timeoutMs 到期后，调用返回 action: "timeout"；停止本轮对话则返回 action: "cancelled"。两种情况卡片都会变为只读，底部会说明原因。

开发

npm run check # syntax of both entries + docs/code consistency guard
npm pack --dry-run # inspect the published file list

客户端部分是手写的模块加载器 bundle，无需构建步骤。

发布

发布自动完成：推送 v* 标签会触发 release 工作流，它会校验 npm run check、带 provenance 发布到 npm，并创建 GitHub Release。

npm version patch # or minor / major
git push --follow-tags

工作流需要仓库密钥 NPM_TOKEN，且对 dsh-visual 包有发布权限。

许可证

MIT © MjxUpUp