dsh-maestro-diagram: Mermaid Verify & Drift Tools

前言¶

dsh-maestro-diagram 是 DeepSeek Harness (DSH) 生態中的一個混合型插件，定位爲 Maestro Diagram Studio。它作爲 Host-only 插件運行，與 maestro-skills/skills/diagram-studio 技能協同工作，旨在爲 SA 級別的圖表提供確定性的驗證與差異檢測能力。

該插件的核心目標是建立“單一事實來源”：以 GitHub 原生 Mermaid 爲源代碼，結合編輯風格的 HTML+SVG 輸出，通過工具調用而非大語言模型（LLM）來確保圖表與代碼的一致性。

核心功能¶

mermaid_verify: Mermaid 語法驗證工具。它基於 mermaid.parse() 並可選集成 mermaid-cli，將錯誤以結構化對象返回而非拋出異常，便於 Agent 修復。
mermaid_drift: 代碼與圖表差異檢測工具。掃描 Mermaid 節點/邊與代碼根目錄（packages/*, govard, maestro-skills）的對比，識別圖中存在但代碼中缺失的元素或過時的邊。
5 種圖表類型: 支持標準 Mermaid 圖表類型，包括 flowchart (組件/架構)、sequenceDiagram (時序)、classDiagram (類圖)、erDiagram (實體關係) 以及 stateDiagram (狀態機)。
編輯風格 HTML: 支持生成自包含的 HTML 文件。包含 paper (#f5f5f5)、ink (#2d3142)、accent (#eb6c36) 等視覺 Token，根據受衆（Team 或 Client）調整內容展示（如摺疊源碼、隱藏頁腳等）。
GitHub 原生集成: 默認輸出保留 GitHub Mermaid 渲染，作爲源代碼的單一事實來源。

安裝與啓用¶

該插件爲 Host-only 模式，安裝後需重載 Host 以註冊工具。

# 安裝插件
dsh plugin add @ddtcorex/dsh-maestro-diagram

典型用法¶

在 DSH Agent 工作流中，使用該插件通常遵循以下步驟：

加載技能: 加載 diagram-studio 技能。該技能負責根據語義模式選擇圖表類型，並強制執行編輯規範（如密度、強調色）。
編寫與驗證: 將 Mermaid 代碼寫入文檔（如 docs/architecture.md），調用 mermaid_verify 工具。Agent 需修復代碼直至 ok: true。
受衆渲染:
- 若受衆爲 Team/Internal，生成包含內聯 SVG、摺疊源碼和編輯風格卡的 HTML。
- 若受衆爲 Client/External，生成僅包含 SVG 的乾淨 HTML，隱藏源碼和裝飾性元素。
差異檢測: 在提交代碼前，調用 mermaid_drift 檢測圖中節點與代碼實現是否一致，修復 missingInCode 或 staleEdges。

工具接口¶

mermaid_verify¶

用於驗證 Mermaid 語法，確保圖表可渲染。

// 調用示例
mermaid_verify({
  input: "graph TD; A-->B;", // 或文件內容
  isPath: false,
  strict: true // 開啓反模式警告（如 shadow, legacy graph）
})

// 返回結構
{
  ok: boolean,
  errors: { line, col, msg }[],
  warnings: { msg }[]
}

mermaid_drift¶

用於對比 Mermaid 圖譜與源代碼，發現不一致之處。

// 調用示例
mermaid_drift({
  diagramPath: "docs/architecture.md",
  codeRoots: ["packages/*", "govard", "maestro-skills"]
})

// 返回結構
{
  missingInCode: string[],    // 圖中有但代碼中未定義的節點
  staleEdges: { from, to }[], // 圖中存在但代碼邏輯已廢棄的邊
  missingInDiagram: string[], // 代碼中有但圖中未展示的節點
  summary: string
}

技術細節與構建¶

依賴: 依賴 mermaid 10.9.0。
構建要求: 必須生成平鋪的 lib/index.js 文件（rootDir: src/host）。如果存在 lib/host/index.js 而非 lib/index.js，dsh web 啓動將失敗並報 ERR_MODULE_NOT_FOUND。
發佈: 使用 pnpm 發佈，必須添加 --access public 參數。

# 構建插件
pnpm --dir packages/dsh-maestro-diagram run build

# 運行測試
pnpm --dir packages/dsh-maestro-diagram run test

# 驗證 TypeScript
pnpm --dir packages/dsh-maestro-diagram run verify

注意事項¶

Host-only: 當前版本 (v1) 不包含客戶端包，工具註冊在 Host 進程中。
發佈規範: 依賴項使用 workspace: 協議時，發佈必須使用 pnpm publish --access public，禁止使用 npm publish，否則會導致依賴問題。
風格規範: 插件內置了一套視覺規範（Tokens），包含 focal 和 muted 類定義，確保圖表風格統一。
許可證: MIT 許可證，部分編輯風格靈感來源於 cathrynlavery/diagram-design。

更多細節與設計文檔請參考：GitHub 倉庫