前言¶
DeepSeek Harness（DSH）裏，模型回答通常以 Markdown 文本爲主。若要在回覆下方呈現對比表、圖表、步驟條、日曆等結構化界面，常見做法是讓模型直接輸出 HTML 或在前端硬編碼每種場景的佈局。前者難以校驗、安全風險大；後者與具體內容強耦合，模型也難以只描述「要什麼」而不描述「怎麼擺」。
社區插件 dsh-iui（維護者 zengwenliang416，SkillHub 分類爲客戶端）走的是另一條路徑：模型通過 render_ui 給出語義化的 content block，插件校驗後映射到組件，在回覆下方渲染爲基於 Astryx 的交互卡片。可選接入 TypeSafe Jev 做組件選型。插件不修改 DSH 源碼，以純插件形式掛載到 profile。
這是什麼¶
dsh-iui 是 DSH 的 Intelligent UI 插件：語義內容塊（content block）經校驗與組件決策後，在沙箱 iframe 中渲染爲交互式 Astryx 卡片。字段說明由 ui_reference 工具按需提供，常駐系統提示只需幾句話，減輕提示詞體積。
工作方式¶
下面按 README 中的鏈路說明端到端行爲。
- 模型給出語義內容。 模型調用
render_ui，提交 summary、comparison、calculator、calendar 等類型的內容塊，只描述內容與字段，不描述頁面佈局。 - 宿主校驗。 插件按字段 schema 和跨字段規則校驗每個塊。例如對比項需覆蓋全部屬性、公式只能引用輸入項、日期須爲真實日期。校驗失敗時返回帶路徑的錯誤信息，由模型修正後重試。
- 決定組件。 每個內容塊對應若干候選組件（如 chart 可選 bar、line、area、scatter）。若配置了 Jev 則由 Jev 選擇；Jev 不可用或置信度不足時回退到規則選擇。
- 在沙箱中渲染。 卡片在
sandbox="allow-scripts"的 iframe 中用 React 19 和 Astryx 渲染，iframe 的 CSP 禁止一切網絡請求。鏈接點擊由外層頁面在新標籤頁打開，且僅允許http/https。卡片上的交互狀態（選項、輸入、勾選、日期等）按會話保存在瀏覽器本地。
內容塊與組件¶
當前 README 列出 25 類內容塊、57 個組件變體。下表爲各類塊及其候選組件（與倉庫文檔一致）。
| 內容塊 | 候選組件 |
|---|---|
| summary | callout、card |
| notice | banner、inline |
| comparison | table、card-grid |
| choice | segmented、option-cards、radio-list |
| calculator | sliders、number-fields |
| steps | stepper、numbered-list、accordion |
| metrics | stat-cards、metadata、progress |
| checklist | checkbox-list、cards |
| faq | accordion、list |
| sections | tabs、radio-list、accordion |
| chart | bar、line、area、scatter |
| code | code-block、numbered |
| quote | blockquote、card |
| tags | tokens、badges |
| text | markdown、compact |
| timeline | vertical-steps、dated-list |
| tree | tree、nested-list |
| gallery | carousel、grid |
| glossary | metadata、infotips、list |
| shortcuts | table、list |
| sources | citations、links |
| status | dots、badges |
| timer | countdown、stopwatch |
| people | list、cards |
| calendar | calendar、agenda |
安裝與啓用¶
環境要求：Node.js 24.9 或更高，DSH 0.2.2 或更高。npm 包名爲 @zengwenliang416/dsh-iui（package.json 版本 0.1.0，許可證 MIT）。
在目標 profile 上執行官方安裝命令，再啓動對應 profile：
dsh plugin --profile <profile> add @zengwenliang416/dsh-iui
dsh <profile>
安裝後，插件的 cordis.patch.yml 會在 profile 根部插入 dsh-iui，render_ui 與 ui_reference 進入全局工具層。
插件以當前 DSH 進程的權限運行，安裝前建議在 GitHub 上查看源碼與 THIRD_PARTY_NOTICES.md（沙箱渲染器含第三方代碼）。
配置 Jev（可選）¶
不配置即可使用，此時始終由規則決定組件。若啓用 Jev 做組件決策，先設置環境變量 TYPESAFE_API_KEY，再按需編輯 profile 的 cordis.yml：
dsh-iui:
jev:
enabled: true # 設爲 false 時始終使用規則
endpoint: https://api.typesafe.ai/v1/systemone
model: jev-latest
apiKeyEnv: TYPESAFE_API_KEY
timeoutMs: 4000
minConfidence: 0.5 # Jev 置信度低於該值時改用規則
啓用 Jev 後，卡片標題與內容塊會發送至 TypeSafe 用於決策。若不希望內容離開本機，將 jev.enabled 設爲 false。
典型用法（模型側）¶
文檔未給出固定對話腳本，但工具契約明確：模型在需要結構化界面時調用 render_ui，按各 content block 的 schema 填寫字段；不確定字段含義時可調用 ui_reference 查詢說明。校驗失敗時根據返回的路徑化錯誤修正 payload 後重試。用戶側在 Web 客戶端刷新或新開對話後即可在回覆下方看到卡片並進行交互（狀態保存在瀏覽器本地）。
適用場景與注意¶
適合： 希望在 DSH 對話中展示對比、指標、圖表、步驟、日曆等結構化 UI，且希望佈局由插件與規則（或 Jev）承擔，而不是讓模型寫 HTML 的開發者。
注意：
- 純客戶端渲染 + 嚴格 CSP：卡片內無法自行髮網絡請求，外鏈由外層打開。
- Jev 爲可選能力，涉及外發內容時需自行評估隱私與合規。
- 社區目錄 SkillHub 與 DeepSeek / 幻方無官方從屬關係；插件生態遵循 DSH「一切皆插件」的思路，以社區維護爲主。
開發與本地調試¶
貢獻者與二次開發者可在倉庫內執行：
pnpm install && pnpm --dir island install
pnpm run build # 構建沙箱渲染器並嵌入，然後構建插件
pnpm run typecheck
pnpm run test
pnpm run gallery -- /tmp/iui-gallery light # 首次運行前先執行 npx playwright install chromium
本地調試時，用本地路徑替代包名安裝插件；修改並重新構建後刷新頁面即可：
dsh plugin --profile <profile> add <本倉庫路徑>
倉庫還提供 scripts/render-cards.mjs（從會話記錄截圖卡片）與 scripts/demo.mjs（對運行中的 DSH 錄製端到端演示）。
結尾¶
dsh-iui 把「模型描述語義塊 → 校驗 → 選組件 → 沙箱渲染」串成一條可複用的 Intelligent UI 鏈路，並與 DSH 工具層通過 render_ui / ui_reference 對接。需要查閱安裝說明與完整內容塊列表時，見 SkillHub 目錄頁 與 GitHub 倉庫。
