交互式 HTML 卡片 eaglezlee/dsh-ui-html

dsh-ui-html

在 DeepSeek Harness（dsh）对话中渲染沙箱化的交互式 HTML 界面，并把用户的操作结构化地送回模型——默认作为一条新的用户消息，阻塞模式下作为工具结果。

dsh-ui-html 提供一个 show_ui 工具：模型给出 HTML，对话里就地渲染成一张界面卡片；用户在其中操作后，界面通过 window.dsh.emit(name, payload) 提交的结构化数据会回到模型，模型据此继续。

功能

- 渲染：show_ui 把 HTML 渲染进对话。前端半边在两个插槽上注册：tool.call.toolview（工具调用行上的界面卡片）与 conversation.chat.turnTail（把界面渲染进对话正文）。
- 回传：界面调用 window.dsh.emit(name, payload) 提交结构化数据。默认模式下，这次提交由宿主注入为一条新的用户消息，模型在下一轮继续处理；阻塞模式下（wait_for_interaction: true），提交内容作为本次调用的工具结果返回。
- 两种等待模式：
- wait_for_interaction: false（默认，推荐）——界面立即展示，工具调用当轮返回 presented，不占用本轮；用户提交后作为新用户消息进入下一轮。
- wait_for_interaction: true——工具调用在本轮内阻塞等待提交，交互作为工具结果返回；等待期间交互挂在工具调用上（旧模式）。
- 可视化配置：7 项设置可在 DSH 设置页调整。宿主侧为即时生效（volatile 设置）；浏览器半边读取的是一份启动快照，改动后需刷新页面。

与 dsh-visualize 的区别

dsh-visualize 是单向展示——把 HTML 渲染给用户看，没有用户到模型的回传通道。
本插件是闭环——界面内的用户操作会结构化地回到模型，成为下一步的输入。

安装

dsh plugin --profile <profile> add github:<owner>/dsh-ui-html

安装后重启 DSH 生效（bundle 在启动时展开）。

工具：show_ui

| 参数 | 类型 | 必填 | 说明 |
| html | string | 是 | 要展示的 HTML（片段或完整文档），可用内联 /。 |
| title | string | 否 | 界面短标题，显示在对话卡片上。 |
| description | string | 否 | 界面之上的文字说明，也是界面无法渲染时的回退文本。 |
| wait_for_interaction | boolean | 否 | 默认 false：界面立即展示，用户提交后作为新用户消息回到模型。true：本轮内阻塞等待并把交互作为工具结果返回。 |
| interaction_hint | string | 否 | 提示用户如何操作。 |

返回结果：

| 字段 | 说明 |
| status | presented（已展示并等待提交，提交走新用户消息）/ interaction（阻塞模式已收到交互）/ timeout（阻塞等待超时）/ cancelled（交互前本轮被取消）/ unsupported（交互回传不可用，界面仅展示）。 |
| ui_id | 本次界面实例的稳定标识（等于工具调用 id）。 |
| event_name | 用户界面提交的事件名（阻塞模式）。 |
| payload | 界面显式 emit 的内容（阻塞模式）；可以是任何 JSON 值。 |
| note | 状态补充说明。 |

界面侧约定

- 界面运行在 sandbox="allow-scripts" 的 iframe 中：不透明源，不能访问宿主文档、Cookie、localStorage、剪贴板或本机文件。
- 默认不能访问任何网络地址；可加载的外部资源来源由 allowedResourceOrigins 逐条放行。
- 宿主注入 --dsw-alias- 主题变量，界面可直接在 CSS 中使用。

配置

| 设置 | 默认 | 说明 |
| enabled | true | 总开关：关闭后不注册工具、不注册事件桥、不发系统提示。 |
| announceToAgent | true | 是否向 agent 的系统提示声明本插件；关闭后仅在用户点名时使用。 |
| maxHtmlBytes | 262144 | 单次界面 HTML 的最大字节数（UTF-8）。 |
| maxEventBytes | 65536 | 单条交互事件 payload 序列化后的最大字节数。 |
| interactionTimeoutMs | 0 | 阻塞模式等待用户交互的超时（毫秒）；0 表示一直等到本轮被取消。 |
| allowedResourceOrigins | [] | 允许界面加载的外部资源来源（scheme://host[:port]），默认全部禁止。 |
| eventBridgeEnabled | true | 交互事件回传开关；关闭后 wait_for_interaction: true 返回 status: unsupported 而不是抛错。 |

安全模型

不可信 HTML 只在 iframe 内接触页面：沙箱化 iframe（allow-scripts，无 allow-same-origin）提供不透明源，配合注入的 CSP，交互经由校验 event.source 的 postMessage 桥传递。策略由宿主半边决定，前端半边只读取一次只读描述（/plugins/dsh-ui-html/status）并照其执行；交互事件经 /plugins/dsh-ui-html/event 回传；默认不加载任何外部资源。

开发

npm install
npm test # 等价于 node --test test/

测试覆盖协议、桥、配置、工具、入口与前端半边（test/.test.mjs）。前端与桥的部分用例需要 @deepseek-ai/dsh-llm、@deepseek-ai/schemastery（随 devDependencies 安装）。

许可

MIT，见 LICENSE。