SKILL.md
唯讀
名稱
mermaid-diagrams
描述
使用 Mermaid 語法建立軟體圖表的完整指南。當使用者需要透過圖表來建立、視覺化或記錄軟體時使用，包括類別圖（領域建模、物件導向設計）、序列圖（應用程式流程、API 互動、程式碼執行）、流程圖（流程、演算法、使用者旅程）、實體關係圖（資料庫結構）、C4 架構圖（系統脈絡、容器、元件）、狀態圖、Git 圖表、圓餅圖、甘特圖或任何其他圖表類型。觸發詞包括「圖表」、「視覺化」、「建模」、「規劃」、「顯示流程」，或當解釋系統架構、資料庫設計、程式碼結構或使用者/應用程式流程時。
Mermaid 圖表繪製
使用 Mermaid 的文字式語法建立專業的軟體圖表。Mermaid 從簡單的文字定義渲染圖表，讓圖表可進行版本控制、易於更新，並能與程式碼一起維護。
核心語法結構
所有 Mermaid 圖表都遵循此模式：
diagramType
definition content
關鍵原則：
- 第一行宣告圖表類型（例如
classDiagram、sequenceDiagram、flowchart） - 使用
%%作為註解 - 換行與縮排可提升可讀性，但非必要
- 未知的單字會破壞圖表；參數會靜默失敗
圖表類型選擇指南
選擇正確的圖表類型：
-
類別圖 - 領域建模、OOP 設計、實體關係
- 領域驅動設計文件
- 物件導向類別結構
- 實體關係與依賴
-
序列圖 - 時間順序互動、訊息流
- API 請求/回應流程
- 使用者驗證流程
- 系統元件互動
- 方法呼叫順序
-
流程圖 - 流程、演算法、決策樹
- 使用者旅程與工作流程
- 商業流程
- 演算法邏輯
- 部署管線
-
實體關係圖 (ERD) - 資料庫結構
- 資料表關係
- 資料建模
- 結構設計
-
C4 圖 - 多層次的軟體架構
- 系統脈絡（系統與使用者）
- 容器（應用程式、資料庫、服務）
- 元件（內部結構）
- 程式碼（類別/介面層級）
-
狀態圖 - 狀態機、生命週期狀態
-
Git 圖表 - 版本控制分支策略
-
甘特圖 - 專案時程、排程
-
圓餅圖/長條圖 - 資料視覺化
快速入門範例
類別圖（領域模型）
classDiagram
Title -- Genre
Title *-- Season
Title *-- Review
User --> Review : creates
class Title {
+string name
+int releaseYear
+play()
}
class Genre {
+string name
+getTopTitles()
}
序列圖（API 流程）
sequenceDiagram
participant User
participant API
participant Database
User->>API: POST /login
API->>Database: Query credentials
Database-->>API: Return user data
alt Valid credentials
API-->>User: 200 OK + JWT token
else Invalid credentials
API-->>User: 401 Unauthorized
end
流程圖（使用者旅程）
flowchart TD
Start([User visits site]) --> Auth{Authenticated?}
Auth -->|No| Login[Show login page]
Auth -->|Yes| Dashboard[Show dashboard]
Login --> Creds[Enter credentials]
Creds --> Validate{Valid?}
Validate -->|Yes| Dashboard
Validate -->|No| Error[Show error]
Error --> Login
ERD（資料庫結構）
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
PRODUCT ||--o{ LINE_ITEM : includes
USER {
int id PK
string email UK
string name
datetime created_at
}
ORDER {
int id PK
int user_id FK
decimal total
datetime created_at
}
詳細參考資料
如需特定圖表類型的深入指南，請參閱：
- references/class-diagrams.md - 領域建模、關係（關聯、組合、聚合、繼承）、多重性、方法/屬性
- references/sequence-diagrams.md - 角色、參與者、訊息（同步/非同步）、啟用、迴圈、alt/opt/par 區塊、備註
- references/flowcharts.md - 節點形狀、連線、決策邏輯、子圖、樣式
- references/erd-diagrams.md - 實體、關係、基數、鍵、屬性
- references/c4-diagrams.md - 系統脈絡、容器、元件圖、邊界
- references/architecture-diagrams.md - 雲端服務、基礎設施、CI/CD 部署
- references/advanced-features.md - 主題、樣式、設定、佈局選項
最佳實務
- 從簡單開始 - 先從核心實體/元件著手，逐步加入細節
- 使用有意義的名稱 - 清晰的標籤讓圖表自我說明
- 大量註解 - 使用
%%註解來說明複雜的關係 - 保持焦點 - 每個圖表專注於一個概念；將大型圖表拆分為多個聚焦的檢視
- 版本控制 - 將
.mmd檔案與程式碼一起儲存，方便更新 - 加入脈絡 - 包含標題與備註來說明圖表目的
- 迭代 - 隨著理解演進而改進圖表
設定與主題
使用 frontmatter 設定圖表：
---
config:
theme: base
themeVariables:
primaryColor: "#ff6b6b"
---
flowchart LR
A --> B
可用主題： default、forest、dark、neutral、base
佈局選項：
layout: dagre（預設） - 經典平衡佈局layout: elk- 複雜圖表的高階佈局（需整合）
外觀選項：
look: classic- 傳統 Mermaid 風格look: handDrawn- 手繪風格
匯出與渲染
原生支援於：
- GitHub/GitLab - 在 Markdown 中自動渲染
- VS Code - 搭配 Markdown Mermaid 擴充功能
- Notion、Obsidian、Confluence - 內建支援
匯出選項：
- Mermaid Live Editor - 線上編輯器，支援 PNG/SVG 匯出
- Mermaid CLI -
npm install -g @mermaid-js/mermaid-cli然後mmdc -i input.mmd -o output.png - Docker -
docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png
常見陷阱
- 破壞性字元 - 避免在註解中使用
{}，對特殊字元使用適當的跳脫序列 - 語法錯誤 - 拼寫錯誤會破壞圖表；在 Mermaid Live 中驗證語法
- 過度複雜 - 將複雜圖表拆分為多個聚焦的檢視
- 缺少關係 - 記錄所有重要的實體間連線
何時建立圖表
在以下情況務必建立圖表：
- 開始新專案或功能時
- 記錄複雜系統時
- 解釋架構決策時
- 設計資料庫結構時
- 規劃重構工作時
- 新成員加入團隊時
使用圖表來：
- 讓利害關係人對技術決策達成共識
- 協作記錄領域模型
- 視覺化資料流與系統互動
- 在編碼前進行規劃
- 建立隨程式碼演進的活文件
