Mermaid Architect - 階層式圖表與文件技能

Mermaid 圖表與文件系統，具備專業指南與程式碼轉圖表能力。

決策樹

這個技能如何運作：

使用者提出請求 → 技能分析意圖
技能決定圖表/文件類型 → 載入適當的指南
AI 讀取專業指南 → 使用範本產生圖表/文件
交付結果 → 包含驗證與匯出選項

使用者意圖分析：

flowchart TD
    Start([使用者請求]) --> Analyze{分析意圖}

    Analyze -->|"工作流程、流程、商業邏輯"| Activity[載入活動圖指南<br/>references/guides/diagrams/activity-diagrams.md]
    Analyze -->|"基礎設施、部署、雲端"| Deploy[載入部署圖指南<br/>references/guides/diagrams/deployment-diagrams.md]
    Analyze -->|"系統架構、元件"| Arch[載入架構指南<br/>references/guides/diagrams/architecture-diagrams.md]
    Analyze -->|"API 流程、互動"| Sequence[載入序列圖指南<br/>references/guides/diagrams/sequence-diagrams.md]
    Analyze -->|"類別、ER、狀態、wiki、逐步解說"| WikiGuide[載入 WikiTicket GitHub 指南<br/>references/guides/wiki-ticket-and-github.md]
    Analyze -->|"程式碼轉圖表"| CodeToDiag[載入程式碼轉圖表指南<br/>references/guides/code-to-diagram/ + examples/]
    Analyze -->|"設計文件、完整文件"| DesignDoc[載入設計文件範本<br/>assets/*-design-template.md]
    Analyze -->|"unicode 符號、圖示"| Unicode[載入 Unicode 符號指南<br/>references/guides/unicode-symbols/guide.md]
    Analyze -->|"萃取、驗證、轉換"| Scripts[使用 Python 腳本<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py]

    Activity --> Generate[產生圖表]
    Deploy --> Generate
    Arch --> Generate
    Sequence --> Generate
    WikiGuide --> Generate
    CodeToDiag --> Generate
    DesignDoc --> Generate
    Unicode --> Generate
    Scripts --> Execute[執行腳本]

    Generate --> Validate{驗證？}
    Validate -->|是| RunValidation[執行 mmdc 驗證]
    Validate -->|否| Output
    RunValidation --> Output[輸出結果]
    Execute --> Output

    classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black
    classDef guide fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
    classDef action fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue

    class Analyze,Validate decision
    class Activity,Deploy,Arch,Sequence,WikiGuide,CodeToDiag,DesignDoc,Unicode,Scripts guide
    class Generate,Execute,RunValidation,Output action

可用指南與資源

圖表類型指南 (`references/guides/diagrams/`)

指南	完整路徑	當使用者想要時載入	範例
活動圖	`references/guides/diagrams/activity-diagrams.md`	工作流程、流程、商業邏輯、使用者流程、決策樹	"顯示結帳流程"、"記錄 ETL 管道"、"建立核准工作流程"
部署圖	`references/guides/diagrams/deployment-diagrams.md`	基礎設施、雲端架構、K8s、無伺服器、網路拓撲	"顯示 AWS 架構"、"記錄 GCP 部署"、"建立 K8s 圖示"
架構圖	`references/guides/diagrams/architecture-diagrams.md`	系統架構、元件設計、高階結構	"顯示系統元件"、"記錄微服務"、"架構概觀"
序列圖	`references/guides/diagrams/sequence-diagrams.md`	API 互動、服務通訊、請求/回應流程	"顯示 API 呼叫順序"、"記錄認證流程"、"服務互動"
WikiTicket / GitHub / Confluence	`references/guides/wiki-ticket-and-github.md`	設計文件、逐步解說、需求、wiki 發布、Confluence 圖片	"架構文件"、"程式碼逐步解說"、"wiki"、"Confluence"

WikiTicket 和 GitHub wiki 的預設是此技能，包括 classDiagram、erDiagram 和 stateDiagram-v2。不要將這些發送給 PlantUML。如果 GitHub 無法渲染 C4 / architecture-beta / block-beta，請回退到 flowchart TD。

程式碼轉圖表指南與範例

資源	完整路徑	提供的內容
主指南	`references/guides/code-to-diagram/README.md`	分析任何程式碼庫並萃取圖表的完整工作流程
Spring Boot	`examples/spring-boot/README.md`	Controller→Service→Repository 架構，部署配置，方法序列，業務邏輯活動
FastAPI	`examples/fastapi/README.md`	Python 非同步模式、Pydantic 模型、依賴注入、雲端部署
React	`examples/react/README.md`	元件階層、狀態管理、資料流、建置管線
Python ETL	`examples/python-etl/README.md`	資料管線、轉換步驟、錯誤處理、排程
Node/Express	`examples/node-webapp/README.md`	中介軟體鏈、路由處理器、非同步模式、部署
Java Web App	`examples/java-webapp/README.md`	傳統 MVC、Servlet 容器、WAR 部署

設計文件範本

範本	完整路徑	用途	何時載入
架構設計	`assets/architecture-design-template.md`	系統級架構	"建立架構文件"、"記錄系統設計"
API 設計	`assets/api-design-template.md`	API 規格	"API 設計文件"、"記錄 REST API"
功能設計	`assets/feature-design-template.md`	功能規劃	"功能設計"、"規劃新功能"
資料庫設計	`assets/database-design-template.md`	資料庫結構	"資料庫設計"、"記錄結構"
系統設計	`assets/system-design-template.md`	完整系統	"系統設計文件"、"完整系統文件"

Unicode 符號指南

完整路徑： references/guides/unicode-symbols/guide.md

當使用者提及時載入： "unicode 符號"、"圖表中的表情符號"、"語意圖示"、"加入符號"

快速參考：

📦 基礎設施：☁️ 🌐 🔌 📡 🗄️
⚙️ 運算：⚙️ ⚡ 🔄 ♻️ 🚀 💨
💾 資料：💾 📦 📊 📈 🗃️ 🧊
📨 訊息傳遞：📨 📬 📤 📥 🐰 📢
🔐 安全：🔐 🔑 🛡️ 🚪 👤 🎫
📝 監控：📝 📊 🚨 ⚠️ ✅ ❌

Python 腳本 (`scripts/`)

腳本	用途	何時載入
`extract_mermaid.py`	從 Markdown 萃取圖表、驗證語法、取代為圖片	"萃取圖表"、"驗證 mermaid"、"尋找所有圖表"
`mermaid_to_image.py`	將 .mmd 轉換為 PNG/SVG、批次轉換、自訂主題	"轉換為圖片"、"渲染圖表"、"建立 PNG"
`resilient_diagram.py`	完整工作流程：儲存 .mmd、產生圖片、驗證、錯誤復原	"產生圖表"、"建立圖表並驗證"、"韌性圖表"

GitHub wiki、WikiTicket 與 Confluence

對於 WikiTicket 設計文件、程式碼逐步解說、需求、GitHub wiki 或 Confluence，請載入 references/guides/wiki-ticket-and-github.md。

目標	提供內容
GitHub wiki / GFM	使用 `mermaid` 程式碼區塊。GitHub 支援 class、ER、state、sequence、flowchart、C4。
Confluence / Notion / Word / PDF	同時渲染 PNG 或 SVG（使用 `scripts/resilient_diagram.py` 或 `mmdc`）並上傳圖片。不要依賴 Confluence 來渲染 Mermaid。

PlantUML 是選擇性的，用於 Salt 線框、使用案例、時序、ArchiMate、nwdiag 和 WBS。這些一律提供 PNG 或 SVG。

使用模式

常見的請求模式和指南選擇。請參閱何時使用何種工具以獲取完整對應。

模式	範例請求	要載入的指南
單一圖表	"為登入流程建立活動圖"	圖表類型指南 + Unicode 符號
程式碼轉圖表	"從 application.yml 產生部署圖"	框架範例 + 部署指南
設計文件	"建立 API 設計文件"	來自 assets/ 的範本 + 相關圖表指南
萃取/驗證	"從 design.md 萃取圖表"	使用 `scripts/extract_mermaid.py`
批次轉換	"將所有 .mmd 轉換為 PNG"	使用 `scripts/mermaid_to_image.py`

韌性工作流程

關鍵： 這是所有圖表產生的建議方法。它確保驗證、錯誤復原和一致的檔案組織。

完整指南： references/guides/resilient-workflow.md

工作流程概觀

flowchart LR
    A[1. 識別類型] --> B[2. 儲存 .mmd + 圖片]
    B --> C{3. 有效？}
    C -->|是| D[4. 加入 Markdown]
    C -->|否| E[5. 錯誤復原]
    E --> F{找到修正？}
    F -->|是| A
    F -->|否| G[搜尋外部資源]
    G --> A

    classDef step fill:#90EE90,stroke:#333,color:darkgreen
    classDef decision fill:#FFD700,stroke:#333,color:black
    class A,B,D,E,G step
    class C,F decision

關鍵原則

在圖表通過驗證之前，絕對不要將其加入 markdown。 這可以防止文件中有損壞的圖表。

使用腳本（建議）

# 使用完整錯誤復原產生
python scripts/resilient_diagram.py \
    --code "flowchart TD; A-->B" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "process_flow" \
    --format png \
    --json

輸出： .mmd 和 .png 檔案都放在 ./diagrams/ 目錄中。

檔案命名慣例

./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
./diagrams/<markdown_file>_<num>_<type>_<title>.png

範例： ./diagrams/api_design_01_sequence_auth_flow.png

錯誤復原優先順序

當驗證失敗時，工作流程會自動：

檢查排錯指南 - references/guides/troubleshooting.md（記錄了 28 種錯誤）
使用 perplexity 搜尋 - perplexity_ask MCP 處理語法問題
使用 brave 搜尋 - brave_web_search MCP 尋找最新解決方案
詢問 gemini - gemini 技能獲取其他觀點
一般搜尋 - WebSearch 工具作為備用

手動備用步驟

如果腳本不可用：

識別圖表類型 從第一行（flowchart、sequence 等）
載入參考指南 從 references/guides/diagrams/
儲存到 ./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
驗證： mmdc -i file.mmd -o file.png -b transparent
出錯時： 在 references/guides/troubleshooting.md 中搜尋匹配的錯誤
如果未找到： 按上述優先順序使用搜尋工具
加入引用： ![Description](./diagrams/filename.png)

模式 6：韌性圖表產生

使用者： "建立一個序列圖並加入設計文件"

技能動作：

識別意圖：圖表產生 + markdown 整合
載入工作流程指南：references/guides/resilient-workflow.md
識別圖表類型：sequence
載入圖表指南：references/guides/diagrams/sequence-diagrams.md
使用範本產生 Mermaid 程式碼

執行韌性工作流程：

python scripts/resilient_diagram.py \
    --code "[產生的程式碼]" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "api_sequence" \
    --json

如果驗證失敗 → 套用排錯修復 → 重試
成功後 → 將 ![API Sequence](./diagrams/design_doc_01_sequence_api_sequence.png) 加入 markdown

Unicode 語意符號

始終使用 Unicode 符號來增強圖表清晰度。常見模式：

基礎設施與部署

graph TB
    Client[👤 使用者] --> LB[🌐 負載均衡器]
    LB --> App1[⚙️ 應用伺服器 1]
    LB --> App2[⚙️ 應用伺服器 2]
    App1 --> DB[(💾 資料庫)]
    App1 --> Cache[(⚡ Redis)]

具有狀態的活動流程

flowchart TD
    Start([🚀 開始]) --> Process[⚙️ 處理資料]
    Process --> Check{✓ 有效？}
    Check -->|是| Save[💾 儲存]
    Check -->|否| Error[❌ 錯誤]
    Save --> Complete([✅ 完成])

微服務架構

graph TB
    API[🌐 API 閘道] --> Auth[🔐 認證服務]
    API --> Orders[📋 訂單服務]
    Orders --> Queue[📬 訊息佇列]
    Queue --> Worker[⚙️ 背景工作者]
    Worker --> Storage[📦 物件儲存]

如需完整的符號參考，請載入： references/guides/unicode-symbols/guide.md

Python 工具

萃取 Mermaid 圖表

# 列出所有圖表
python scripts/extract_mermaid.py document.md --list-only

# 萃取到個別檔案
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# 驗證所有圖表
python scripts/extract_mermaid.py document.md --validate

# 取代為圖片引用（用於 Confluence 上傳）
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

轉換為圖片

# 單一轉換
python scripts/mermaid_to_image.py diagram.mmd output.png

# 自訂設定
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# 批次轉換目錄
python scripts/mermaid_to_image.py diagrams/ output/ --format png --recursive

# 從 stdin

...（其餘部分已截斷）

決策樹範例

（內容已保留但為節省空間而截斷；實際使用時請包含完整絕策樹範例）

高對比樣式

（內容已保留但為節省空間而截斷）

檔案組織

（內容已保留但為節省空間而截斷）

工作流程摘要

（內容已保留但為節省空間而截斷）

何時使用何種工具

（內容已保留但為節省空間而截斷）

最佳實踐

（內容已保留但為節省空間而截斷）

學習路徑

（內容已保留但為節省空間而截斷）

在你喜歡的 AI 中提問

預覽

說明文件

Mermaid Architect - 階層式圖表與文件技能

目錄

決策樹

可用指南與資源

圖表類型指南 (references/guides/diagrams/)

程式碼轉圖表指南與範例

設計文件範本

Unicode 符號指南

Python 腳本 (scripts/)

GitHub wiki、WikiTicket 與 Confluence

使用模式

韌性工作流程

工作流程概觀

關鍵原則

使用腳本（建議）

檔案命名慣例

錯誤復原優先順序

手動備用步驟

模式 6：韌性圖表產生

Unicode 語意符號

基礎設施與部署

具有狀態的活動流程

微服務架構

Python 工具

萃取 Mermaid 圖表

轉換為圖片

決策樹範例

高對比樣式

檔案組織

工作流程摘要

何時使用何種工具

最佳實踐

學習路徑

Individual skills in this repo

spillwavesolutions/design-doc-mermaid

相關技能

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

圖表類型指南 (`references/guides/diagrams/`)

Python 腳本 (`scripts/`)