前言¶
DeepSeek Harness (DSH) 的核心設計理念是「一切皆插件」。在開發基於模型的智能體或工作流時，讓模型直接生成圖表（如流程圖、時序圖）是一個常見需求。傳統做法通常依賴模型輸出 Markdown 代碼塊，然後由用戶或腳本手動解析渲染，這增加了交互成本且不夠直觀。
butterhost69/dsh-mermaid-diagram 是一個 DSH 插件，它爲模型提供了一個名爲 mermaid 的工具，並負責在 Web UI 中將模型生成的圖表渲染爲交互式的卡片。這個插件通過直接在對話流中展示圖表，解決了模型輸出文本圖表代碼難以即時預覽的問題。
核心功能¶
該插件主要提供以下能力：
- 模型工具集成：爲模型提供
mermaid工具。該工具接受source參數（圖表源碼）和可選的title參數。 - 全類型圖表支持：支持渲染 Mermaid 支持的多種圖表類型，包括流程圖、序列圖、類圖、狀態圖、ER 圖、甘特圖、餅圖等。
- 主題感知與自適應：圖表渲染會自動適配宿主 Web UI 的淺色/深色主題。當主題切換時，卡片會自動重新渲染以匹配新主題。
- 流式處理：在流式輸出過程中顯示進度，並在參數接收完整後進行渲染。
- 會話回溯：圖表卡片是會話事件的一部分，可以從日誌中派生，支持刷新頁面或翻頁後的重放。
- 容錯機制：如果渲染失敗，卡片會自動降級顯示源代碼視圖，並附帶錯誤提示，而不是顯示破損的卡片。
- 本地化支持：卡片文本支持英文和簡體中文，跟隨宿主語言設置。
- 本地化運行：插件內置 Mermaid 運行時，不依賴外部 CDN，從插件自身的路由提供資源。
- 按需加載：Mermaid 運行時約 3.5 MB，僅在第一次出現圖表時才加載，不影響啓動速度。
安裝與啓用¶
安裝前請確保環境滿足以下要求：
* DSH 版本：0.2.1-alpha.1 或兼容版本。
* Node.js：^22.19 或 >=24。
* 運行環境：必須使用 Web 配置（即 dsh web），因爲圖表卡片依賴 Web 界面渲染。
執行以下命令安裝插件：
dsh plugin --profile web add -w github:ButterHost69/dsh-mermaid-diagram
安裝完成後，重啓 dsh web 服務或刷新瀏覽器頁面。
典型用法¶
在對話中向模型提問，請求生成圖表。模型檢測到需求後，會調用 mermaid 工具。
例如，你可以輸入：
繪製一個發佈流程的流程圖。
模型會調用該工具，結果會以卡片形式出現在對話流中。該卡片包含以下交互功能：
* Diagram / Code 切換：查看渲染後的 SVG 圖表或原始源碼。
* Copy：一鍵複製圖表源碼到剪貼板。
* 錯誤回退：如果源碼有誤，默認打開 Code 視圖，並在頂部顯示錯誤提示。
適用場景與注意¶
- 適用場景：適用於需要模型直接生成架構圖、算法流程圖、數據模型等場景的開發者。
- 字符限制：圖表源碼超過 50,000 字符會被工具攔截，不會發送到瀏覽器（這是爲了防止同步解析導致性能問題）。
- 渲染安全：卡片使用 Mermaid 的
strict安全級別渲染，標籤會被自動清理。 - 交互限制：非常高的圖表會在卡片內部滾動，而不會撐開整個對話記錄。
總結¶
dsh-mermaid-diagram 通過將 mermaid 工具標準化集成到 DSH 生態中，爲模型提供了直接繪圖的能力。它解決了從文本代碼到可視化的即時轉化問題，配合流式輸出和主題自適應功能，提升了交互體驗。
