前言¶

在 DeepSeek Harness（DSH）里跑智能体时，常见做法是模型输出 Markdown 或固定 UI 组件。预览报表、模拟界面、让用户点选后再把结构化结果交回模型，往往还要用户把选择「翻译」成自然语言，或另开一套表单流程。

dsh-surface 是社区插件，维护者为 woolsen，分类为客户端。它在对话中渲染完整、自包含的 HTML 页面，并可选地阻塞工具调用直到用户提交、取消或超时；页面通过 dshSurface.submit 把 JSON 数据写回同一次工具调用的返回值，而不是组件库或 artifact 管理器。下面介绍其定位、能力与安装用法。

这是什么¶

dsh-surface 面向已启用 Web UI 的 DeepSeekRuntime（dsh web）。模型侧主要暴露一个 render 工具：传入完整 HTML 文档，页面出现在工具卡片内的 iframe 中；若页面调用提交 API，工具调用会保持打开，直到收到答案或超时。

npm 包名与插件 id 均为 dsh-surface，当前资料中的版本为 0.1.1，许可证 MIT。GitHub 仓库：woolsen/dsh-surface；社区目录页：skillhub.cn 条目。DSH 生态强调「一切皆插件」；SkillHub 等为社区目录，与 DeepSeek / 幻方无官方从属关系。

核心功能¶

资料中明确的能力如下。

1. 任意自包含 HTML — 内联 CSS/JS、SVG、canvas；不依赖外部网络请求。
2. 默认沙箱 — 不透明 origin、无 allow-same-origin；CSP 限制网络、嵌套 frame、表单跳转等。
3. 跟随宿主主题 — 将 --dsw-* 等 token 桥接到页面可用的 CSS 变量（如 --background、--foreground、--chart-*、--radius）。
4. 高度自适应 — iframe 上报内容高度，卡片随内容伸缩。
5. 阻塞式作答 — 类似 awaitAnswer：无需单独问答面板，提交前工具调用可一直等待。
6. OpenChamber 兼容 — window.openchamber.submit 与 window.dshSurface 等价；旧名 dshRender 仍作别名保留。
7. 体量小 — README 称单 host 文件、单 client bundle，并带有 12 个用例的测试套件。

模型通过 render 工具完成「画页面 → 可选等待 → 拿回 { answered, summary, data }」这一链路。

安装与启用¶

需要 DeepSeekRuntime 的 Web UI，以及 Node.js ^22.19.0 || >=24（package.json 中 engines 为 >=22.19.0）。

官方安装命令为：

dsh plugin --profile web add dsh-surface

安装后重启 dsh web，再刷新浏览器；插件在下一次会话中生效。

若从本地 checkout 安装（非 npm 发布包），资料给出的方式是先 npm install && npm run build，再：

dsh plugin --profile web add link:/path/to/dsh-surface

典型用法¶

让模型渲染页面¶

在对话中直接描述需求，并指明使用 render 工具、页面须自包含。README 示例意图包括：

• 一页 Q3 收入报表（柱状图 + 表格）。
• 发布检查清单：approve / reject、备注字段，提交时调用 dshSurface.submit({ decision, note }, summary)。

模型调用 render 时传入完整 HTML；若页面调用 submit，工具调用会阻塞至用户操作完成。

render 工具字段¶

成功提交时，工具返回 JSON 字符串，形态如：

{ "answered": true, "summary": "Approved with a note", "data": { "decision": "approve", "note": "ship it" } }

超时返回 { "answered": false, "reason": "timeout" }；用户取消则按宿主 cancellation 错误失败。

页面内 API¶

示例：

<button onclick="dshSurface.submit({ decision: 'approve' }, 'Approved')">Approve</button>

页面还可在 window 上监听 dsh-surface:result 以响应宿主确认。

安全模型与兼容¶

页面在 sandbox="allow-scripts allow-forms" 且无 allow-same-origin 的 iframe 中运行；提交走宿主已认证的 /api 通道（ctx.connection.fetch），并校验 Host/Origin 与浏览器认证。载荷上限：summary 500 字符、data 16 KB、HTML 200 KB。README 明确建议页面不要索要密钥，并将页面内容视为不可信。

兼容情况（来自 README）：

已知限制包括：回合结束后工具卡片组会折叠（展开可再看页面）；暂不支持本地图片文件（仅 data: / 内联）；大 HTML 会留在会话日志中；切换会话无全局「等待中」通知；宿主重启会丢失内存中的 pending 等待等。完整列表见仓库 README。

适用场景与注意¶

适合：需要在对话里做 UI 预览、数据报告、计算器 mock、带审批/表单的交互，且希望模型直接拿到结构化字段而非用户口述。

安装前：插件在当前 dsh 进程权限下运行；安装前应阅读 源码与 LICENSE，确认沙箱与 API 行为符合你的威胁模型。

无 Web UI 的 headless / TUI 场景无法展示页面，render 只会空等到超时。

结尾¶

dsh-surface 在模型与用户之间提供一层「页面表面」：自包含 HTML、主题跟随、可选阻塞回传。若你在 DSH Web 里做 generative UI 或人机协同表单，可按上述命令安装并在提示词中约束 render 与 dshSurface.submit 的用法。

• 社区目录：https://www.skillhub.cn/plugins/woolsen/dsh-surface
• GitHub：https://github.com/woolsen/dsh-surface