前言¶

在 DSH（deepseek-harness）的對話客戶端裏，模型輸出的 SVG、HTML 或圖表數據通常只能以代碼塊的形式出現，想看效果要手動複製到文件裏再打開。dsh-visualizer 要解決的正是這一步：它是一個不改 DSH 源碼的外部插件，讓模型在對話流中直接渲染結構化圖表和 SVG/HTML 小組件——圖表用 echarts 畫，小組件邊生成邊顯示。

下面介紹它的定位、核心功能、安裝方式與典型用法。

這是什麼¶

dsh-visualizer 由 Moses14159 維護，當前版本 0.3.0，MIT 許可證。一句話定位：不改 DSH 源碼，讓模型在對話中即時生成可視化內容——流式 SVG/HTML 小組件，以及結構化圖表（ChartSpec → echarts）。

實現上，它複用 DSH 已有的 assistant/chunk 與 tool/call + tool/result 會話事件，不修改 DSH 源碼。插件面向 web 平臺，客戶端注入 @deepseek-ai/dsh-client-runtime。

核心功能¶

兩類輸出，三條交付路徑¶

1、結構化圖表：模型調用 visualize 工具並傳入 spec，支持 bar / line / area / pie / scatter，用 echarts 渲染，並跟隨 DSH 主題（--dsw-alias-* tokens）。
2、流式小組件：模型在回覆中直接寫 svg / html 圍欄，插件複用已有的 assistant/chunk 事件，把內容逐 token 渲染到沙箱 iframe，隨生成逐幀更新。
3、完整小組件：模型通過 visualize 的 widget 參數交付完整 widget，經過校驗和持久化，可在 host 回放。

雙側校驗¶

host 側的 execute 與客戶端摺疊共用同一套純函數解析器（chartspec / widget）。模型輸出如果有漂移，不會靜默通過校驗。

安全隔離¶

widget 代碼原樣插入 sandbox="" 的 iframe，並配合 CSP default-src 'none'。設計上沒有可被繞過的 sanitizer，隔離靠 iframe 沙箱完成。

渲染體驗與降級¶

• SVG 按固有寬高比縮放，卡片帶 fit / 1.5× / 2× 縮放和狀態徽章（generating / truncated / done）。
• 校驗或渲染失敗時優雅降級：回退爲普通代碼塊或 JSON 卡片，不留空行、不拋錯。

純模塊，可獨立測試¶

核心邏輯全部寫成不依賴 DSH 的純模塊，97 個單元測試可以在 Node 中獨立運行。

安裝與啓用¶

先確認前置條件：本地已安裝 DSH（deepseek-harness）且 dsh web 可用；Node.js 20+（engines: node >=20）；插件依賴 DSH 的 @deepseek-ai/dsh-client-runtime、@deepseek-ai/dsh-llm、@deepseek-ai/dsh-tools（見 peerDependencies）。

滿足條件後，用官方命令把插件裝進 web profile：

dsh plugin --profile web add github:Moses14159/dsh-visualizer

兩點注意：

1、從 Git 安裝的插件會在安裝時通過 prepare 腳本構建。出於安全考慮，pnpm 默認阻止構建腳本；如果安裝時被提示，需要在 profile 的 pnpm-workspace.yaml 中添加相應的 allowBuilds 鍵，然後重跑安裝命令。
2、README 提到，一旦 dsh-visualizer 發佈到 npm，也可以按名稱安裝：dsh plugin --profile web add dsh-visualizer。

安裝完成後，插件會註冊 visualize 工具，客戶端側注入 @deepseek-ai/dsh-client-runtime。

典型用法¶

經過上面的步驟，打開 dsh web 的對話，直接對模型說即可。下面這些例子來自 README，可以照着復現。

想要結構化圖表，說 “draw a chart with visualize”，模型會調用 visualize 並傳入 spec。圖表負載形如（kind 支持 bar | line | area | pie | scatter）：

{ "spec": {
    "kind": "bar",
    "title": "Shenzhen · 7-day temperature",
    "xAxis": ["Sat", "Sun", "Mon", "Tue", "Wed", "Thu", "Fri"],
    "yName": "°C",
    "series": [{ "name": "Max", "data": [32, 32, 30, 31, 29, 31, 32] }]
} }

想要流式小組件，說 “write an SVG badge / HTML widget”，模型會在回覆中直接流式寫 svg / html 圍欄（圍欄內是一段 <svg>…</svg> 或 HTML），隨生成逐幀渲染。

想要完整小組件卡片，說 “Help me generate a weather card for Shenzhen right now”，模型會調用 visualize 並傳 widget 參數（HTML），渲染爲沙箱小組件卡片。widget 負載形如：

{ "widget": { "kind": "svg", "code": "<svg ...>…</svg>", "title": "Card title" } }

還有兩個可以直接試的說法：

• “Use visualize to draw a chart of tomorrow’s 24-hour temperature change in Beijing”：模型傳 spec（line），用 echarts 渲染。
• “Draw a bar chart, a pie chart, and a weather card at the same time”：模型多次調用 visualize，並在對話流中排版圖表和卡片。

README 提示：這些例子要求模型加載 visualize 工具（安裝插件後註冊）。如果模型沒有主動調用，把想要的效果描述清楚即可，它會傾向於調用 visualize。

適用場景與注意¶

適合的人羣和場景：

• 日常在 dsh web 客戶端調試模型，希望直接在對話裏看到圖表、徽章、卡片，而不是複製代碼塊的開發者。
• 需要模型輸出結構化圖表（趨勢、佔比、散點等）或小組件的場景。
• 想了解不改源碼的 DSH 外部插件怎麼寫的開發者：插件核心邏輯是不依賴 DSH 的純模塊，源碼和 97 個單元測試都在倉庫裏。

使用前注意：

1、插件以當前 dsh 進程的權限運行。安裝任何第三方插件前，建議先檢查源碼與許可證；本項目許可證爲 MIT，源碼在 GitHub 倉庫中。
2、環境要求：Node.js 20+，本地已安裝 DSH 且 dsh web 可用。
3、從 Git 安裝時如遇 pnpm 阻止構建腳本，按安裝一節的 allowBuilds 說明處理。
4、widget 代碼是原樣插入 sandbox="" iframe 並配合 CSP default-src 'none' 運行的，不經過 sanitizer；對模型生成的內容保持常規判斷。

小結¶

dsh-visualizer 的價值在於路徑短：不改 DSH 源碼，複用已有的 assistant/chunk 與 tool/call + tool/result 事件，就能讓模型在對話流裏渲染結構化圖表和 SVG/HTML 小組件；雙側校驗、iframe 沙箱、失敗降級都有明確設計，核心邏輯可獨立測試。

• GitHub 倉庫：https://github.com/Moses14159/dsh-visualizer
• 社區插件目錄頁：https://www.skillhub.cn/plugins/Moses14159/dsh-visualizer （該目錄爲獨立社區站點，與 DeepSeek、幻方無官方從屬關係）