前言¶

在文檔、評審和方案裏畫圖時，常見做法是手寫 Mermaid，或讓模型「隨便寫一段」再自己改語法。後者往往出現箭頭寫錯、中文標籤未加引號、節點名過長導致佈局錯亂等問題，圖在 Markdown 預覽裏直接報錯。

下面介紹 SkillHub 上的 Mermaid Diagram（座標 @clawhub_pupujanet-eng/mermaid-diagram）。它把「選圖類型、遵守輸出規則、對照語法參考」寫進 Skill 說明，引導 Agent 生成語法有效的 Mermaid，覆蓋流程圖、時序圖、思維導圖、ER 圖、用戶旅程等常見類型。該 Skill 標註 requires_api_key=false，不依賴額外 API Key。

這是什麼¶

Mermaid Diagram 是一套面向編碼助手的 Agent Skill（基於通用 SKILL.md 格式），由 pupujanet-eng 維護，經 clawhub 分發，在 SkillHub 歸類爲 dev-programming，當前版本 1.0.0。

一句話定位：根據文字或產品描述，生成可直接放進 Markdown 的 Mermaid 代碼塊，並儘量規避常見語法錯誤。

• SkillHub 頁面：https://www.skillhub.cn/skills/clawhub_pupujanet-eng/mermaid-diagram
• 上游說明：https://clawhub.ai/pupujanet-eng/mermaid-diagram
• 安裝入口（API 座標）：https://api.skillhub.cn/zcwl/mermaid-diagram

核心功能¶

以下能力均來自上游 Skill 文檔，已覈對。

支持的圖表類型¶

Skill 內有一張「需求 → 推薦類型 → Mermaid 關鍵字」對照表，便於按場景選型：

輸出規則¶

Agent 按 Skill 約定輸出時，應做到：

1. 始終用 ```mermaid 代碼塊包裹結果。
2. 用戶用中文描述時，節點與標籤優先使用中文。
3. 複雜圖可用 %% 註釋標出分區含義。
4. 節點名儘量簡短（文檔建議不超過約 10 個字符），減輕佈局問題。
5. 輸出前在邏輯上自檢語法，並避免：帶空格或中文的標籤未加引號、箭頭語法混用（--> / --- / ->>）、括號未閉合等。

參考材料¶

Skill 提到 references/diagram-patterns.md，內含產品經理常用圖模式與完整示例；當用戶指定圖類型或需要多節點複雜圖時，Agent 應讀取該參考。

安裝與啓用¶

通過 SkillHub（推薦國內環境）¶

先確認本機是否已有 SkillHub CLI：

command -v skillhub && skillhub --version

未安裝時，可按官方安裝文檔執行完整安裝或僅 CLI：

# 完整安裝（CLI + 默認 Skill，推薦）
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

# 僅安裝 CLI
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

安裝本 Skill 時，必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/ 且可能不被識別。在 Cursor 中，常用路徑爲：

skillhub install @clawhub_pupujanet-eng/mermaid-diagram --dir ~/.cursor/skills/

也可將下面提示詞發給 AI，讓其按 https://skillhub.cn/install/skillhub.md 完成安裝：

請根據 https://skillhub.cn/install/skillhub.md，安裝 `@clawhub_pupujanet-eng/mermaid-diagram`。

其他客戶端的常見 skills 目錄（摘自 SkillHub 安裝文檔，便於對照）：

• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或項目下的 .agents/skills/

通過 OpenClaw / ClawHub¶

上游頁面給出的安裝命令爲：

openclaw skills install @pupujanet-eng/mermaid-diagram

座標在 SkillHub 側爲 @clawhub_pupujanet-eng/mermaid-diagram，與 ClawHub 的 @pupujanet-eng/mermaid-diagram 爲同一技能的不同命名空間，以你當前使用的商店 CLI 爲準。

安裝後按所用 Agent 的要求重啓或刷新 skills 目錄，使 Skill 生效。

典型用法¶

啓用 Skill 後，用自然語言描述「要畫什麼、給誰看」即可；Agent 應選對圖表類型並返回 mermaid 代碼塊。下列片段來自上游 Quick Syntax Reference，可直接作爲對話示例或自檢模板。

流程圖示例：

flowchart TD
    A[開始] --> B{判斷條件}
    B -- 是 --> C[執行操作]
    B -- 否 --> D[結束]
    C --> D

時序圖示例：

sequenceDiagram
    用戶->>服務端: 發起請求
    服務端->>數據庫: 查詢數據
    數據庫-->>服務端: 返回結果
    服務端-->>用戶: 響應

思維導圖示例：

mindmap
  root((產品名))
    功能A
      子功能1
      子功能2
    功能B

實際對話中可以更具體，例如：「用 flowchart TD 畫用戶登錄分支，中文標籤」「畫 API 下單的 sequenceDiagram，包含支付回調」。複雜場景可明確要求 Agent 查閱 diagram-patterns.md。

適用場景與注意¶

適合誰

• 需要在 PR、設計文檔、Wiki 裏快速插入 Mermaid 的開發者。
• 希望減少「模型輸出圖語法報錯、反覆手改」的場景。
• 產品、架構討論中需要流程、時序、ER、旅程等標準圖類型，且希望輸出規則統一。

使用注意

• Skill 約束的是生成規範，不替代你在目標平臺（GitHub、Notion、自建渲染器）上對 Mermaid 版本與特性的兼容性驗證。
• 節點過多時，即使語法正確也可能佈局擁擠；可要求拆分多張圖或縮短節點名。
• SkillHub 頁面展示的評分、下載量會隨時間變化；以頁面當前數據爲準。

結尾¶

Mermaid Diagram 把圖表類型選型、輸出格式與常見語法坑寫進 Skill，讓 Agent 在「圖解」類任務裏更穩定地交出可渲染的 Mermaid。若要從國內商店安裝，可從 SkillHub 頁面或安裝 API 座標入手：

https://www.skillhub.cn/skills/clawhub_pupujanet-eng/mermaid-diagram

https://api.skillhub.cn/zcwl/mermaid-diagram