前言¶

在 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