前言¶
DeepSeek Harness（dsh）是 DeepSeek 開源的智能體框架，官方定位是「Everything is a Plugin」：模型、工具、技能、會話、沙箱，一直到界面，都可以用插件增刪，不必改框架源碼。日常在 Web UI 裏跟模型對話時，結果多半還是一段文字、一份 Markdown 表格，或者一張靜態的 Mermaid 圖。排序過程、參數模擬、方案對比這類內容，純文字往往要來回解釋，也不方便動手調一調。
dsh-visualize 就是衝着這件事來的。模型調用 visualize 之後，網頁對話裏會直接出現一張可交互卡片，用來做模擬器、圖表、對比面板或 UI mockup。它由 Nagi-ovo 維護，社區目錄歸在「界面增強」。本文依據插件目錄頁和 GitHub 倉庫交叉覈實後寫成。需要說明的是：DeepSeek Harness 插件庫（deepseek-harness-plugin.com）是獨立的社區目錄，與 DeepSeek / 幻方沒有官方從屬關係，不能當成官方應用商店。
這是什麼¶
dsh-visualize 是一款面向 DeepSeek Harness 的界面增強插件。倉庫 npm 包名爲 @dsh-external/dsh-visualize，許可證是 BSD-3-Clause，主要語言是 TypeScript。2026-08-17 從 GitHub 覈實，倉庫約 160 星；目錄頁收錄時顯示 90 星，星標以倉庫一手數據爲準。當前 package.json 版本爲 0.1.2。
它解決的問題很具體：讓模型不只回答一段文字，而是把一份 HTML fragment 渲染成對話裏的沙箱卡片。用戶側通常不需要自己寫工具調用，直接告訴模型想看什麼即可；插件會註冊 visualize 工具，並附帶一份同名 skill，約定 fragment 該怎麼寫、主題變量怎麼用、哪些外部資源可以加載。
核心功能¶
1、對話內的交互式卡片。模型寫出 HTML fragment 後調用 visualize，Web UI 會在對話流裏插入一張可交互卡片。倉庫 README 寫明適用方向包括模擬器、圖表、對比面板和 UI mockup。捆綁 skill 把適用邊界寫得更細：有可調參數、動畫或交互時才值得出卡片；只要一張靜態節點圖就能講清楚，用 Mermaid 即可；用戶要的是真實網站、頁面組件或獨立文件時，應落到項目文件，而不是對話卡片。
2、visualize 工具與捆綁 skill。節點側把工具註冊到 ctx.tools，把 visualize skill 註冊到 ctx.skills。瀏覽器側再按同一工具名掛上沙箱卡片。當前源碼裏，默認動作是 create，把 markup 作爲 fragment 參數直接傳入，可選 title 和 mode；需要修正已渲染卡片時，用 action: "update"，按卡片的 path 做一次精確的 old_str / new_str 替換。倉庫 README 裏曾寫成 visualize(path, title?, mode?)，與當前工具實現不一致，安裝後以倉庫源碼和捆綁 skill 爲準。並排比較可以用 mode: "wide"，單張圖表或整頁 mockup 保持默認的 inline。
3、流式預覽與會話重放。卡片會在模型還在生成 fragment 時就開始出現。完成後的 fragment 會寫入會話工作區的 viz/ 目錄，工具結果的 meta 裏也會帶上完整 fragment。會話重放時從持久化的工具結果恢復，不依賴原始 fragment 文件還在不在磁盤上。
4、主題跟隨與沙箱隔離。卡片跟隨 DSH 的明暗主題和鯨魚藍配色。渲染髮生在不透明來源的 sandboxed iframe 中，不能接觸宿主頁面。CSP 會阻止網絡請求、嵌套頁面和表單提交，只允許從固定 CDN 加載靜態資源：cdnjs.cloudflare.com、esm.sh、cdn.jsdelivr.net、unpkg.com、fonts.googleapis.com、fonts.gstatic.com、fonts.bunny.net。單個 fragment 默認上限是 1000000 字節，可通過配置項 maxFragmentBytes 調整。
5、非 Web 客戶端的降級。package.json 把客戶端平臺標成 web。目前只在 Web UI 中渲染交互卡片；TUI 和 headless 客戶端會顯示普通工具結果。卡片內的按鈕暫時不能向主對話發送 follow-up 消息。倉庫 README 寫明，靈感來自 Codex 桌面端的 /visualize；skill 的分層 reference 和 Chart.js 優先路線借鑑了 himself65/finance-skills 裏的 generative-ui。
安裝與啓用¶
社區目錄頁給出的安裝命令如下，在 DeepSeek Harness 終端中運行即可：
dsh plugin add github:Nagi-ovo/dsh-visualize
倉庫 README 推薦把它裝到 web profile，因爲交互卡片只在 Web UI 裏渲染：
dsh plugin --profile web add github:Nagi-ovo/dsh-visualize
# 如果 dsh web 正在運行，重啓後刷新頁面
目錄頁提醒：如需可復現安裝，請固定 commit 哈希，把下面的 commit 換成倉庫裏的實際提交：
dsh plugin add github:Nagi-ovo/dsh-visualize#commit
安裝後可以用下面的命令確認插件已經進入最終配置：
dsh --profile web --dump-config
需要改源碼時，克隆倉庫並在倉庫目錄運行 dsh plugin --profile web add .。README 寫明構建產物已經提交，不需要額外構建。使用社區 plugin-registry（https://github.com/dsh-external/plugin-registry）的用戶，也可以從「設置 → 插件」安裝。
插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。安裝前請檢查源代碼倉庫和許可證。
典型用法¶
裝好以後，直接用自然語言告訴模型你想看什麼。倉庫 README 給的例子是：
做一個能調參數的排序算法可視化
模型會先加載捆綁的 visualize skill，寫出一份 HTML fragment，再調用 visualize。用戶側通常看不到工具參數；如果要對照源碼理解調用方式，當前實現大致是：
create（默認）：傳入fragment（字面 HTML，不要帶<html>/<head>/<body>/<!doctype>文檔骨架），可選title、mode。update：傳入已有卡片的path、title，以及一次精確的old_str→new_str替換。skill 約定小修正才用 patch（少於 20 行、少於 5 處，同一輪最多 4 次），更大改動應重新create。mode: "wide"：留給需要並排比較的多面板佈局。
skill 還約定了幾條 fragment 規則，寫插件或排查渲染失敗時用得上：
- 只提交 fragment，由卡片負責文檔骨架、樣式表、主題和 CSP。
- 根元素要有唯一 ID，腳本用
document.getElementById(...)定位，不要依賴document.currentScript。 - 內聯
<style>和<script>可用；fetch、XHR、WebSocket 和表單提交會被策略攔住，失敗時沒有錯誤提示。 - 外部靜態資源必須帶固定版本，並且只允許從前面列出的 CDN 加載。
- 顏色使用主題變量或
light-dark()，不要自己聲明color-scheme。
適用場景與注意事項¶
比較適合這些情況：算法或模擬需要拖滑條看變化；幾組數據要並排對比；產品界面需要一張可點的 mockup，而不是再導出一份獨立 HTML。不太適合：只要一張靜態結構圖、真正要交付到代碼倉庫裏的頁面，以及主要在 TUI / headless 裏工作的流程。
使用時有幾條邊界需要記住。
- 交互卡片目前只在 Web UI 中渲染。TUI 和 headless 只會看到普通工具結果，不要指望同一套卡片出現在終端裏。
- 卡片內的按鈕暫時不能把消息發回主對話。需要模型根據你在卡片裏的操作繼續往下做時，還得在輸入框裏另說一句。
- 每次 patch 都會重載卡片，用戶在卡片裏輸入、拖動或滾動的狀態會丟掉，所以修正應儘量合併，而不是一條條改。
- 單個 fragment 默認不超過 1 MB。內聯大數據要先抽樣、降精度，去掉用不到的字段。
- 插件以當前 dsh 進程權限運行。安裝前應閱讀源碼和 BSD-3-Clause 許可證，只安裝你信任的來源；需要可復現環境時固定 commit。
小結¶
dsh-visualize 把「模型生成一段 HTML、Web UI 在對話裏畫出一張沙箱卡片」做成了可安裝的 DSH 插件。對經常要看模擬、圖表和對比面板的人來說，它補的是文字解釋夠不到的那一層交互，而不是再做一個獨立的前端項目。
目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-visualize/
GitHub：https://github.com/Nagi-ovo/dsh-visualize
