前言¶
在開發協作中，架構描述、數據流向和狀態變遷通常更適合用圖表而非純文本。DeepSeek Harness (DSH) 的理念是「一切皆插件」，dsh-mermaid-comm 是其中專注於圖表生成的插件。它解決的核心問題是：讓 AI 在對話中默認優先輸出 Mermaid 圖表，同時通過語法校驗和輸出門機制保證圖表可用且安全。
是什麼¶
dsh-mermaid-comm 是一個由開發者 kp-z 維護的模型推理插件。它通過注入系統提示詞引導 AI 在特定場景下使用 Mermaid 語法，並註冊了 mermaid_validate 工具進行校驗。渲染工作由 dsh-mermaid 插件完成，本插件負責引導、校驗和安全性控制。
核心功能¶
1. 行爲引導¶
插件會注入 systemPrompt.section。在架構、數據流、序列圖、狀態圖等話題中，AI 會被引導爲「先畫圖，再給簡短解釋」的輸出模式。
2. 語法驗證¶
插件註冊了 mermaid_validate 工具。校驗流程分爲兩步：首先掃描危險字符，隨後調用與 dsh-mermaid 同版本的 mermaid-runtime 進行實際解析。
3. 輸出門¶
插件監聽助手消息事件。它會自動修復 Mermaid 代碼中的 Unicode 箭頭和危險標籤；如果圖表無法通過校驗，會將其從可見界面移除，而不是讓用戶看到渲染失敗的內容。
4. Mermaid Vault¶
這是圖表持久化的核心。插件將經過驗證的圖表保存到 <workspace>/.dsh/mermaid/ 目錄。文件結構包含：
* INDEX.md：圖表索引（主題/類型/版本/更新時間）。
* <name>.mmd：當前活躍版本。
* <name>.history.md：版本演變歷史。
安裝與啓用¶
在安裝本插件前，需要確保已安裝 dsh-mermaid 插件，否則 mermaid_validate 會明確失敗，而不會靜默通過。
dsh plugin --profile web add dsh-mermaid-comm
dsh plugin --profile web add dsh-mermaid
安裝完成後重啓 dsh web。
典型用法¶
AI 默認會根據上下文選擇合適的 Mermaid 圖表類型：
- 架構 / 模塊關係 →
flowchart或classDiagram - 調用鏈 / 請求序列 →
sequenceDiagram - 狀態 / 生命週期 →
stateDiagram-v2 - 數據模型 / 表關係 →
erDiagram - 分支策略 / Git 歷史 →
gitGraph - 計劃 / 甘特圖 →
gantt
Mermaid Vault 工具¶
Vault 目錄下提供了四個工具供模型調用：
mermaid_vault_list：列出索引，可選按類型篩選。mermaid_vault_read：讀取某個主題的當前代碼及歷史記錄。mermaid_vault_save：保存或更新圖表，強制要求通過真實解析器校驗。mermaid_vault_delete：刪除某個主題。
當某個主題已存在時，系統提示詞會引導模型讀取歷史並使用 save 進行迭代（v2, v3…），而不是從零重繪，確保對話中的圖表演進具有連續性。
安全與限制¶
- 命名安全：主題名稱會被清理爲
[a-zA-Z0-9-_]，防止路徑遍歷攻擊。 - 目錄鎖定：所有寫入操作被限制在 Vault 目錄內部。
- 原子寫入：文件寫入採用原子操作，避免中途損壞。
- 大小限制：通過大小和版本限制防止目錄無限增長。
總結¶
dsh-mermaid-comm 通過 Prompt 注入、工具註冊和輸出攔截，解決了 AI 生成 Mermaid 圖表不穩定的問題，並提供了 Vault 機制讓圖表成爲可管理的資產。
