前言¶
在 DeepSeek Harness（DSH）的开发流程中，模型通常仅能生成文本。当需要展示表单、图表或需要用户输入的界面时，仅靠文本描述或单向的 dsh-visualize 无法满足闭环交互的需求。
dsh-ui-html 插件解决了这个问题。它允许模型在对话中渲染一个沙箱化的交互式 HTML 界面，并将用户的操作（如点击、选择）结构化地回传给模型，从而继续后续的处理流程。
核心功能¶
该插件主要提供以下能力：
* 沙箱化 HTML 渲染：在对话上下文中渲染 HTML 界面。
* show_ui 工具：模型通过此工具发起界面渲染。
* 双模式交互：支持非阻塞（默认）和阻塞两种等待模式。
* 结构化回传：用户操作通过 window.dsh.emit 提交，默认作为新用户消息，阻塞模式下作为工具结果。
* 主题变量注入：宿主侧可注入 CSS 变量供界面使用。
* 安全隔离：界面运行在沙箱化 iframe 中，默认禁止网络访问。
安装与启用¶
通过以下命令安装插件。安装后需要重启 DSH 以展开 bundle。
dsh plugin --profile <profile> add github:eaglezlee/dsh-ui-html
工具：show_ui¶
模型调用 show_ui 工具时，需提供以下参数：
| 参数 | 类型 | 说明 |
|---|---|---|
html |
string | 必填。要展示的 HTML 片段或文档，支持内联 <style> 和 <script>。 |
title |
string | 界面短标题。 |
description |
string | 界面之上的说明文字，也是回退文本。 |
wait_for_interaction |
boolean | 默认 false。true 时阻塞等待交互，交互作为工具结果返回。 |
interaction_hint |
string | 提示用户如何操作。 |
界面渲染后，前端通过 window.dsh.emit(name, payload) 提交数据。
交互模式¶
- 非阻塞模式（
wait_for_interaction: false）：界面立即展示，工具调用返回presented。用户提交后，数据作为新用户消息进入下一轮对话。 - 阻塞模式（
wait_for_interaction: true）：工具调用在当前轮内阻塞，直到用户提交或超时。交互内容作为工具结果返回。
返回状态¶
工具调用返回的状态包括 presented、interaction、timeout、cancelled、unsupported 等。
配置项¶
插件提供 7 项宿主侧配置，可在 DSH 设置页调整。修改后浏览器侧需刷新页面才能生效。
enabled：总开关。announceToAgent：是否向 agent 系统提示声明本插件。maxHtmlBytes：单次界面 HTML 最大字节数（默认 262144）。maxEventBytes：单条交互事件 payload 最大字节数（默认 65536）。interactionTimeoutMs：阻塞模式等待超时时间（毫秒），0 表示一直等待。allowedResourceOrigins：允许加载的外部资源来源列表，默认为空（禁止网络访问）。eventBridgeEnabled：交互事件回传开关。
安全模型¶
界面运行在 sandbox="allow-scripts" 的 iframe 中，拥有不透明源，无法访问宿主文档、Cookie、localStorage 或剪贴板。默认情况下无法访问网络资源，需通过 allowedResourceOrigins 配置白名单。
依赖与生态¶
- 依赖：
@deepseek-ai/dsh-llm和@deepseek-ai/schemastery。 - 许可证：MIT。
- 生态：DSH 插件体系的一部分，独立维护。
适用场景与注意¶
此插件适合需要在对话流中嵌入表单、选择器或可视化控件的开发者。使用时需注意，插件运行在当前 DSH 进程的权限下，建议在安装前检查源码与许可证。
总结¶
dsh-ui-html 建立了从模型到界面再到模型的数据闭环。它让 LLM 不再局限于文本，能够直接与用户进行结构化的交互。
