前言¶

在 DSH Web 裏和模型對話時，助手經常在回覆裏輸出 ```mermaid 代碼圍欄——流程圖、時序圖、類圖等。默認情況下，這些圍欄只是純文本代碼塊，需要你自己複製到外部工具才能看圖。

如果你希望會話消息裏直接看到圖表，又不想把 Mermaid 運行時塞進前端啓動包、拖慢首屏加載，就需要一個按需加載、只在出現圍欄時才工作的渲染插件。下面介紹社區插件 dsh-mermaid（維護者 AKS1st），它把 DSH Web 會話中的 Mermaid 圍欄就地渲染爲 SVG，並針對長對話做了視口驅動和異步隊列優化。

這是什麼¶

dsh-mermaid 是一個 DSH 客戶端插件（當前版本 0.5.0，MIT 許可證）。安裝到 web profile 後，它會監聽會話 DOM，把 infostring 爲 mermaid 的代碼圍欄渲染爲 SVG 圖表，同時保留語言橫幅和複製按鈕（複製仍復制源碼）。

插件在 SkillHub 社區目錄 上架，分類爲客戶端；源碼託管於 GitHub: AKS1st/dsh-mermaid。

工作方式¶

插件分爲 Host 半部和 Client 半部，各自職責明確。

Host 半部（src/index.ts）註冊 webServer 前綴路由 /mermaid-dist，從插件自己的 node_modules/mermaid 惰性提供 UMD 構建，並提供固定的 config.json 端點。

Client 半部（src/client/）在瀏覽器側完成實際渲染，主要行爲如下：

1. 只處理已定格的圍欄——流式輸出期間不渲染，等助手回覆完成後再動手；
2. 首次遇到 Mermaid 圍欄才惰性加載 mermaid 庫（瀏覽器緩存一次）；
3. 視口驅動渲染：圍欄進入視口（帶 300px 預加載餘量）纔開始渲染；離開視口的圖停止渲染，回到視口再繼續；
4. 異步隊列渲染：多圖時逐個渲染並在渲染之間讓出主線程，首次渲染期間顯示加載動畫，完成後替換爲 SVG；
5. securityLevel 恆爲 strict，標籤經 mermaid 內置 DOMPurify 消毒，且從不綁定點擊處理；
6. theme: auto 時圖表顏色跟隨 GUI 亮/暗主題，屬性翻轉時自動重渲染視口內的既有圖表；
7. 代碼塊橫幅上的放大按鈕可打開全屏浮層，支持滾輪縮放、左鍵/中鍵拖動平移，背景點擊或 Esc 關閉；
8. 渲染失敗時保留源碼塊，在圖框下方顯示錯誤摘要，支持一鍵複製報錯或發送給 AI 修復。

client 包體積約 10 KB（gzip ~4 KB）；mermaid（~700 KB）只在真正出現 mermaid 圍欄時才按需加載，不進入 boot 圖。

安裝與啓用¶

從 GitHub 倉庫安裝，構建在 prepare 腳本里自動執行：

dsh plugin --profile web add github:AKS1st/dsh-mermaid
dsh web   # 重啓 web 服務使 profile 生效

若 pnpm 提示 git 依賴需要執行構建腳本（ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED），按提示把包加入 profile 的 pnpm-workspace.yaml 的 allowBuilds 後重試即可。

本地開發時，先構建再安裝：

npm install
npm run build
dsh plugin --profile web add .
dsh web

卸載：

dsh plugin --profile web remove dsh-mermaid

配置¶

組合包默認通過 cordis.patch.yml 注入以下配置：

- insert:
    - id: mermaid
      name: 'dsh-mermaid'
      config:
        theme: auto
        maxTextSize: 50000
        maxEdges: 2000
        securityLevel: strict

在 profile 的 cordis.patch.yml 裏以 - set: 或 - update: 覆蓋即可。

典型用法¶

安裝並重啓 web 服務後，無需額外操作。當助手在會話消息裏輸出 Mermaid 圍欄時，插件會自動接管渲染。例如助手回覆中包含：

```mermaid
flowchart LR
  A[用戶提問] --> B[DSH Web]
  B --> C[dsh-mermaid]
  C --> D[SVG 圖表]
```

圍欄定格並進入視口後，上述代碼會被渲染爲 SVG 流程圖。你可以點擊代碼塊橫幅上的放大按鈕在全屏浮層中查看，滾輪縮放、拖動平移；也可以直接複製源碼或把渲染報錯一鍵發給 AI 修復。

安全模型與已知限制¶

安全模型：

• 助手輸出不可信：securityLevel 鎖定 strict，標籤中的 HTML 由 mermaid 內部 DOMPurify 消毒；不調用 bindFunctions，點擊處理保持惰性。
• 渲染失敗時保留原純文本代碼塊（絕不渲染錯誤 HTML），並在圖框下方顯示錯誤摘要；控制檯同時輸出完整錯誤。

已知限制：

• 依賴主前端 CodeBlock 的穩定鉤子（字面量類 md-code-block 與 infostring 文本）；上游渲染器重構時需要同步更新選擇器。
• 流式輸出期間不渲染，定格後才渲染。
• securityLevel: strict 下 mermaid 的點擊交互不可用。

適用場景與注意¶

適合誰：

• 經常在 DSH Web 會話裏讓模型畫流程圖、架構圖、時序圖，希望就地看圖而不是反覆切換工具；
• 關注首屏性能，希望 Mermaid 運行時按需加載、不污染 boot 圖；
• 需要亮/暗主題自動跟隨、長對話視口驅動渲染的場景。

安裝前注意：

DSH 的理念是「一切皆插件」，社區目錄 SkillHub 是獨立站點，與 DeepSeek / 幻方無官方從屬關係。插件以當前 dsh 進程權限運行，安裝前應檢查 源碼 與 MIT 許可證，確認符合你的安全要求。插件要求 Node.js ^22.19 || >=24。

鏈接¶

• 社區目錄：https://www.skillhub.cn/plugins/AKS1st/dsh-mermaid
• GitHub 倉庫：https://github.com/AKS1st/dsh-mermaid