前言¶
用 DSH（DeepSeek Harness）做智能體開發時，模型回覆裏經常出現 mermaid 代碼塊，用來描述流程、架構或狀態流轉。DSH web 客戶端默認把它當普通代碼塊處理：有 Shiki 語法高亮，有 Copy 按鈕，但圖看不到。想覈對圖畫得對不對，只能把源碼複製到外部工具裏渲染，來回切換很打斷排查節奏。
dsh-plugin-mermaid 針對的就是這個問題：它在聊天消息內把 mermaid 代碼塊渲染成圖表，源碼視圖仍然保留，隨時可以切回去。下面介紹它的功能、原理、安裝與使用。
這是什麼¶
dsh-plugin-mermaid 是一個 DeepSeek Harness（DSH）web 客戶端插件，由 lj970926 維護，採用 MIT 許可證。它做三件事：
- 在聊天消息中將 mermaid 代碼塊渲染爲圖表；
- 提供「源碼 / 圖表」切換，在 Mermaid 源碼與渲染後的 SVG 之間來回切換；
- 跟隨 DSH 的深色/淺色主題自動切換 Mermaid 主題，主題變更後所有塊即時重新渲染。
幾個設計上的取捨：Mermaid v11 按需從 CDN 加載，避免打包膨脹；插件零構建步驟，瀏覽器入口爲手寫的工廠形式 CJS，符合 DSH client-modules 服務的要求；代碼塊橫幅原生集成在 DSH 界面裏，按鈕緊鄰內置 Copy 按鈕，源碼視圖保留 Shiki 高亮與複製。
核心功能¶
- 在聊天消息中將 mermaid 代碼塊渲染爲圖表；
- 「源碼 / 圖表」切換，隨時在 Mermaid 源碼與渲染後的 SVG 之間切換；
- 跟隨 DSH 深色/淺色主題自動切換 Mermaid 主題；
- Mermaid v11 按需從 CDN 加載，不增加打包體積；
- 原生集成 DSH 代碼塊橫幅：按鈕緊鄰內置 Copy 按鈕，源碼視圖保留 Shiki 高亮與複製；
- 提供「重渲染」按鈕，流式輸出或 CDN 異常後可強制重新渲染。
實現方式¶
插件的瀏覽器端入口是 lib/client.js。加載後它做三件事：
- 通過
window.__ModuleLoader__.load({id, factory})註冊自身，並注入樣式； - 識別 mermaid 塊：讀取 DSH 橫幅的
.infostring文本，並以code[class*='language-mermaid']作爲前向兼容回退； - 安裝 MutationObserver 處理流式輸出中的代碼塊，配合 500 ms 防抖，避免流式 token 頻繁觸發渲染。
安裝與啓用¶
推薦直接從 GitHub 安裝。這個包隨倉庫發佈預構建的 lib/ 文件並聲明瞭 dsh.bundle，可以直接裝入 DSH web profile：
dsh plugin --profile web add github:lj970926/dsh-plugin-mermaid
安裝後需要重啓 dsh web，並在瀏覽器強制刷新（Cmd+Shift+R）。
如果需要固定版本以保證可復現，追加 commit SHA 或 tag：
dsh plugin --profile web add github:lj970926/dsh-plugin-mermaid#<commit-or-tag>
開發調試時，也可以從本地 checkout 以鏈接 bundle 的方式安裝：
dsh plugin --profile web add /absolute/path/to/dsh-plugin-mermaid
倉庫還保留了遺留腳本 install.sh，直接把文件複製進已有的 web profile：
git clone https://github.com/lj970926/dsh-plugin-mermaid.git
bash dsh-plugin-mermaid/install.sh
腳本做兩件事：把文件夾複製到 $DSH_HOME/profiles/web/node_modules/dsh-plugin-mermaid/（默認 ~/.dsh/profiles/web/...），再向 $DSH_HOME/profiles/web/cordis.patch.yml 追加一條 insert 條目（冪等）。之後同樣重啓 dsh web 並強制刷新瀏覽器。
兩點補充說明：
- 已發佈文件就在
lib/中，包沒有prepare構建步驟，不需要 pnpmallowBuilds授權；如果你 fork 後加入了構建步驟，需按 DSH 打包文檔，在 profile 的pnpm-workspace.yaml中把包名加入allowBuilds。 - 推薦用
dsh plugin add而不是手動改補丁文件：它會把 bundle 記錄到 profile manifest，profile 更新後仍保持啓用。另外，較新的 DSH 版本要求 profile 的cordis.patch.yml能解析爲頂層 YAML 數組，文件沒有條目時保持爲[]。
典型用法¶
經過上面的安裝與重啓步驟，發送任意包含 fenced mermaid 塊的消息即可，例如：
```mermaid
flowchart LR
A[Input] --> B[Process] --> C[Output]
```
DSH 會先把它渲染成代碼塊，插件隨後增強這個塊：
- 點擊「源碼 / 圖表」按鈕，在 Mermaid 源碼與渲染後的 SVG 之間切換；
- 流式輸出結束或 CDN 異常後，如果圖沒有出來，點「重渲染」強制重新渲染；
- 在 Settings → Appearance 切換主題後，所有塊會按匹配的 Mermaid 主題重新渲染。
開發與定製¶
瀏覽器端文件是純 JavaScript，沒有構建步驟。修改 lib/client.js 後，需要重新同步進 profile 並重啓 dsh web：
bash install.sh
默認 web profile 中 DSH 的 client-hmr 插件是禁用的，文件改動不會自動熱重載。如果你從源碼運行 DSH（pnpm run dev:web）並重新啓用 client-hmr，則對 lib/client.js 的修改可以熱重載，無需重啓。
另一個可定製點是 Mermaid 的加載來源。首次渲染需要訪問 cdn.jsdelivr.net，之後瀏覽器會緩存 Mermaid；如需本地化，把 lib/client.js 中的 MERMAID_CDN 改爲本地 URL 即可。
卸載¶
- 從
~/.dsh/profiles/web/cordis.patch.yml移除對應的塊； - 刪除目錄：
rm -rf ~/.dsh/profiles/web/node_modules/dsh-plugin-mermaid； - 重啓
dsh web。
適用場景與注意¶
插件適合所有在 DSH web 客戶端裏查看含 mermaid 圖回覆的用戶：架構梳理、流程說明、智能體工作流調試，圖直接在對話裏看，不用再切換外部工具。
使用前注意：
- 要求 DSH
>= 0.1.0-rc.6（在 rc.6 上測試通過）； - 首次渲染需要網絡訪問
cdn.jsdelivr.net，離線環境先按上文方式本地化； - 和所有 DSH 插件一樣，插件以當前 dsh 進程的權限運行，安裝前建議先閱讀源碼與許可證（MIT），確認無誤再裝入 profile。
相關鏈接¶
dsh-plugin-mermaid 補齊了 DSH 聊天界面裏「圖能直接看」這一環：零構建、按需加載、跟隨主題，裝上即可用。目錄頁與源碼倉庫如下：
- 目錄頁：https://www.skillhub.cn/plugins/lj970926/dsh-plugin-mermaid
- GitHub：https://github.com/lj970926/dsh-plugin-mermaid
（社區插件目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。）
