前言¶
在 DeepSeek Harness（DSH）里做智能体时，很多交互仍靠自然语言来回描述：表单怎么填、图表长什么样、固定流程要重复讲一遍。既占上下文，也容易说不准。社区插件 @mostkia/dsh-htmlui（仓库 mostkia/dsh-htmlui）走另一条路：模型直接产出 HTML/CSS/JS，插件在浏览器里用沙箱 iframe 渲染，并通过 POST 与 SSE 与模型双向通信，把「说出来的 UI」变成「跑起来的面板」。
下面介绍它是什么、能做什么、如何安装，以及使用时需要注意的安全边界。
这是什么¶
dsh-htmlui 是 DSH 的客户端（web）插件，维护者为 mostkia，分类为客户端侧能力扩展。
一句话定位：在 DSH 会话中为 Agent 提供 HTML 会话 UI 层——任意 HTML/CSS/JS 可在沙箱 iframe 中渲染，支持五种挂载位置，页面通过 dshHTML.send(...) 把动作 POST 回宿主，模型侧数据经 SSE 流式推回页面更新。
它与 DSH「一切皆插件」的架构一致：宿主侧提供工具与 HTTP 载体，浏览器侧注册工具卡片、composer 入口与各展示位，中间由注入的 bridge.js 暴露 window.dshHTML API。
核心功能¶
五种 placement¶
插件通过 placement 决定界面出现在哪里；模板也可在 HTML 里用 meta 声明，优先级为：工具参数 > meta 声明 > 默认 inline。
| placement | 说明 |
|---|---|
inline |
嵌在主对话流中，无额外 chrome，高度随文档 |
dock-right |
会话右侧可折叠栏，与对话左右分栏，常用形态 |
float |
可拖拽、缩放、最小化的浮窗（如 size: "520x360+80+60"） |
fullscreen |
覆盖会话区域，可切回聊天；离开再返回不强制重载 |
background |
全帧、可点透的背景层（固定约 25% 透明度），实验性 |
模板内声明示例：
<meta name="dsh-htmlui" content="placement=dock-right; size=520x360; title=Orders">
双向通信，不占满上下文¶
- 文档调用
dshHTML.send(...)，动作作为消息到达模型侧。 - 模型通过 SSE 流式回传，页面就地更新。
- 模型读到的工具结果是紧凑摘要（如
ui_id/placement/bytes/ revision）；大文档可走文件路径path，由浏览器从 carrier 的 ticket 路由加载，避免把整页 HTML 塞进上下文。
工具与模板库¶
宿主侧（index.js）提供 html_ui 与 html_ui_template 等工具，存储目录为 $DSH_HOME/htmlui，HTTP 载体挂载在 /plugins/@mostkia/dsh-htmlui（文档 ticket、会话列表、模板目录、POST 动作通道、SSE、health 等）。
- 可指向本地 HTML 项目目录做导入/导出，会话间保留实用模板；模板也可不经模型回合直接创建。
- 会话页 「HTML管理」 列出本会话内各界面及其 placement、来源项目，可隐藏、恢复或移除；记录保存在宿主侧并绑定会话。
Bridge API 与持久化¶
注入的 assets/bridge.js 提供 send、state、store、store.rows、resize、close、on(...)、ready(...) 等。
展示位在切换会话、最小化、折叠时仍保留该 slot 上的页面状态；若要跨关面板、关会话、重启宿主仍保留数据，需使用 persistence slot（$DSH_HOME/htmlui/store/），通过 meta 声明 store=... 并用 dshHTML.store 访问（小值同步、大行数据 SQLite 分存，详见 README）。
权限与安全¶
- 文档运行在不透明源的 iframe 中，经 per-document capability token 访问，以降低对 DSH 主界面内容的直接影响。
- 按项目配置权限等级；沙箱无法阻止你为项目授予过高权限，导入第三方 HTML 前应自行审阅源码与许可证。
安装与启用¶
插件尚未发布到 npm，需从 GitHub 安装。官方命令如下：
dsh plugin --profile web add github:mostkia/dsh-htmlui
要求 DSH >=0.1.7-0（含 0.1.7-rc.* 预发布线）。安装后硬刷新页面；浏览器半激活时控制台会出现类似 [dsh-htmlui] client active (0.1.1) 的日志。
确认当前宿主加载的版本：
curl -s http://127.0.0.1:3080/plugins/@mostkia/dsh-htmlui/health
# {"ok":true,"plugin":"@mostkia/dsh-htmlui","version":"0.1.1",...}
注意：修改宿主半 index.js 后需重启 dsh 才会生效；浏览器半通常只需刷新页面。仓库内 docs/VERIFY.md 提供本机验收清单（各 placement 表现、往返如何在对话中出现等）。
典型用法（工作流层面）¶
- 在 web profile 下安装并刷新 DSH Web 界面，确认 health 与控制台 client active 日志。
- 在对话中让 Agent 调用
html_ui渲染一段 HTML（或html_ui_template绑定已导入的项目），指定或依赖 meta 的placement。 - 在 iframe 内用
dshHTML.send把用户操作发回模型；监听 SSE/on更新界面。 - 需要长期数据时，在模板 meta 中声明
store，使用dshHTML.store/store.rows；在 HTML管理 中统一管理多个浮窗或全屏界面。 - 将常用 HTML 工具放入模板目录并设置项目级权限，供后续会话复用或由 Agent 迭代改进。
README 中的截图展示了 inline、右侧 dock、浮窗、全屏、会话管理、一键从 composer 部署、以及 Agent 一句话生成记事本类应用等形态，可作为视觉参考（路径见仓库 docs/images/）。
适用场景与注意¶
适合谁
- 希望在 DSH 里做生成式 UI、固定工作流面板、可视化调试或小型 HTML 工具（canvas、WebGL、第三方库等）的智能体开发者。
- 需要把已有静态 HTML 项目接入 DSH，并交给 Agent 增强的团队。
务必注意
- 插件宿主半以当前
dsh进程权限运行，并对外提供 HTTP 路由与本地存储；安装前请阅读 GitHub 源码 与 MIT 许可证，仅信任你审阅过的模板与项目。 - 社区目录 SkillHub 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系，版本与星标以各来源实时信息为准（例如目录页星标为 0，以页面为准）。
结尾¶
dsh-htmlui 把「描述 UI」换成「渲染 UI + 结构化回传」，在五种 placement 下与 Agent 深度集成，并辅以模板库、会话管理与可选持久化 slot。若你在 DSH web 端做交互型智能体，可按上文命令安装，用 health 与 VERIFY 清单确认环境，再从 inline 或 dock-right 试起。
- 目录页：https://www.skillhub.cn/plugins/mostkia/dsh-htmlui
- GitHub：https://github.com/mostkia/dsh-htmlui
