美人魚架構師 - 全面的圖表與文件技能
版本 2.0 - 具備智能編排的階層式架構
一項強大的克勞德代碼技能，使用按需指南載入、程式碼轉圖表產生和Python工具來建立美人魚圖表和設計文件。
安裝
透過 Skilz 市集進行一鍵安裝
從 Skilz 市集 立即安裝此技能：
skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid
手動安裝
直接複製到您的克勞德代碼技能目錄中：
# Navigate to your skills directory
cd ~/.claude/skills
# Clone the repository
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git
驗證安裝
安裝後，驗證技能是否可用：
# List installed skills
ls ~/.claude/skills/design-doc-mermaid
# Or ask Claude Code
# "List my installed skills"
此技能的功能
智能圖表產生：
- 活動圖（工作流程、流程、商業邏輯）
- 部署圖（雲端基礎架構、K8s、無伺服器）
- 架構圖（系統元件、微服務）
- 順序圖（應用程式介面流程、服務互動）
- 包含嵌入式圖表的完整設計文件
程式碼轉圖表轉換：
- 從春靴應用程式中提取架構
- 從設定檔產生部署圖
- 從方法呼叫建立順序圖
- 記錄 ETL 管線和資料流程
圖表管理：
- 從標記語言檔案中提取美人魚圖表
- 使用美人魚命令列介面驗證圖表語法
- 將圖表轉換為 PNG/SVG 影像
- 批次處理整個目錄
快速入門
建立活動圖
User: "Create an activity diagram for user registration with email verification"
技能將會：
- 載入
references/guides/diagrams/activity-diagrams.md - 使用註冊模式範本
- 加入萬國碼符號（🔐 表示安全性、📧 表示電子郵件、✅ 表示成功）
- 套用高對比度樣式
- 輸出完整的美人魚圖表
從程式碼產生
User: "Here's my Spring Boot application.yml - generate a deployment diagram"
技能將會：
- 分析設定（資料來源、快取、安全性）
- 載入
references/guides/diagrams/deployment-diagrams.md - 載入
examples/spring-boot/README.md - 將設定對應至雲端資源
- 產生包含資源規格的部署圖
建立設計文件
User: "Create an API design document for the contacts API"
技能將會：
- 載入
assets/api-design-template.md - 載入相關的圖表指南（順序、實體關係、架構）
- 產生包含嵌入式圖表的完整文件
- 儲存至
docs/design/api-contacts-v1-2025-01-13.md
結構
階層式組織
mermaid-architect/
├── SKILL.md # 具備決策樹的主要編排器
├── README.md # 此檔案
├── CLAUDE.md # 克勞德代碼指令
│
├── references/ # 參考資料
│ ├── mermaid-diagram-guide.md # 舊版的通用指南
│ └── guides/ # 專業指南（按需載入）
│ ├── diagrams/
│ │ ├── activity-diagrams.md # ✅ 完成
│ │ ├── deployment-diagrams.md # ✅ 完成
│ │ ├── architecture-diagrams.md # ✅ 完成
│ │ └── sequence-diagrams.md # ✅ 完成
│ ├── code-to-diagram/
│ │ └── README.md # ✅ 完成（主指南）
│ ├── unicode-symbols/
│ │ └── guide.md # ✅ 完成（100+ 符號）
│ └── troubleshooting.md # ✅ 完成（28 個常見錯誤）
│
├── scripts/ # Python 工具
│ ├── extract_mermaid.py # ✅ 提取與驗證圖表
│ └── mermaid_to_image.py # ✅ 轉換為 PNG/SVG
│
├── examples/ # 特定語言的模式
│ ├── spring-boot/ # ✅ 完成
│ ├── fastapi/ # ✅ 完成
│ ├── react/ # ✅ 完成
│ ├── python-etl/ # ✅ 完成
│ ├── node-webapp/ # ✅ 完成
│ └── java-webapp/ # ✅ 完成
│
└── assets/ # 設計文件範本
├── architecture-design-template.md
├── api-design-template.md
├── feature-design-template.md
├── database-design-template.md
└── system-design-template.md
主要功能
1. 萬國碼語義符號
每個圖表都使用有意義的萬國碼符號：
graph TB
User[👤 Client] --> Gateway[🌐 API Gateway]
Gateway --> Auth[🔐 Auth Service]
Gateway --> API[⚙️ API Service]
API --> DB[(💾 Database)]
API --> Cache[(⚡ Redis)]
API --> Queue[📬 Message Queue]
Queue --> Worker[⚙️ Background Worker]
符號類別：
- 基礎架構：☁️ 🌐 🔌 📡 🗄️
- 運算：⚙️ ⚡ 🔄 🚀 💨
- 資料：💾 📦 📊 📈 🗃️
- 訊息傳遞：📨 📬 📤 📥 🐰
- 安全性：🔐 🔑 🛡️ 🚪 👤
- 監控：📝 📊 🚨 ⚠️ ✅ ❌
2. 高對比度樣式
所有圖表都使用可存取的、高對比度的顏色 - 詳情請見 SKILL.md。
3. Python 工具
提取圖表
# List all diagrams in a file
python scripts/extract_mermaid.py document.md --list-only
# Extract to separate .mmd files
python scripts/extract_mermaid.py document.md --output-dir diagrams/
# Validate all diagrams
python scripts/extract_mermaid.py document.md --validate
# Replace diagrams with image references (for Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
--image-format png --output-markdown output.md
轉換為影像
# Single file
python scripts/mermaid_to_image.py diagram.mmd output.png
# Custom theme and size
python scripts/mermaid_to_image.py diagram.mmd output.svg \
--theme dark --background white --width 1200
# Batch convert directory
python scripts/mermaid_to_image.py diagrams/ output/ \
--format png --recursive
# From stdin
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png
需求
圖表產生需求
- 克勞德代碼技能系統（自動）
- 指南和範本（包含在此技能中）
驗證與影像轉換需求
# Install mermaid-cli globally
npm install -g @mermaid-js/mermaid-cli
# Verify installation
mmdc --version
Python 腳本需求
- Python 3.7+
- 無需額外套件（僅使用標準函式庫）
學習路徑
初次接觸美人魚圖表？
- 從活動圖開始 - 閱讀
references/guides/diagrams/activity-diagrams.md - 學習萬國碼符號 - 閱讀
references/guides/unicode-symbols/guide.md - 嘗試範例 - 使用
examples/spring-boot/中的模式 - 驗證您的工作 - 執行
python scripts/extract_mermaid.py --validate
需要記錄現有程式碼？
- 識別框架 - 春靴、快速應用程式介面、反應等
- 載入範例指南 - 閱讀
examples/{your-framework}/README.md - 匹配模式 - 在範例中尋找相似的程式碼模式
- 產生圖表 - 使用指南中的範本
- 驗證 - 使用驗證腳本
建立設計文件？
- 選擇範本類型 - 架構、應用程式介面、功能、資料庫或系統
- 載入範本 - 從
assets/{type}-design-template.md讀取 - 填寫區段 - 用實際內容替換佔位符
- 加入圖表 - 根據需要為每個區段載入圖表指南
- 使用符號 - 採用以萬國碼符號增強
- 儲存 - 放置於
docs/design/並加上時間戳記
階層式系統如何運作
傳統方法（低效率）
- 載入整個技能文件（約 50KB）
- AI 處理所有範本和範例
- 高符記使用量
- 反應時間慢
階層式方法（高效率）
- 使用者提出請求 → AI 分析意圖
- 決策樹啟動 → 判定所需指南
- 僅載入所需內容 → 讀取特定指南（約 2-5KB）
- 產生輸出 → 使用目標範本
- 符記效率 → 需要的上下文減少 10 倍
範例流程
使用者：「針對我的 Docker Compose 設定建立部署圖」
決策樹：
1. Analyze: "deployment diagram" + "Docker Compose"
2. Determine: deployment-diagrams.md needed
3. Load: references/guides/diagrams/deployment-diagrams.md (2KB)
4. Find pattern: Docker Compose template exists
5. Generate: Using template + Unicode symbols
6. Output: Complete diagram in <30 seconds
使用的符記量： ~2,000（相較於傳統方法的 ~10,000）
完成狀態
✅ 已完成：
- 階層式決策樹編排器
- 包含範本的活動圖指南
- 部署圖指南（AWS、GCP、K8s、無伺服器、Docker）
- 萬國碼符號指南（100+ 個符號）
- 具備驗證功能的美人魚圖表提取腳本
- 美人魚圖表轉影像腳本
- 春靴程式碼轉圖表範例
- 設計文件範本（5 種類型）
- 高對比度樣式系統
🚧 進行中：
- 快速應用程式介面範例
- 反應元件架構範例
- Python ETL 管線範例
📋 計畫中：
- 架構圖指南
- 順序圖指南
- 程式碼轉圖表主指南
- Node.js/Express 範例
- Java 網路應用程式範例
貢獻方式
若要新增新的圖表類型指南：
- 在
references/guides/diagrams/{type}-diagrams.md中建立指南 - 包含：
- 使用時機
- 基本語法
- 常見模式（3-5 個範本）
- 萬國碼符號範例
- 最佳實務
- 更新
SKILL.md決策樹 - 加入包含程式碼對應的範例
若要新增新的語言範例：
- 在
examples/{framework}/中建立目錄 - 新增
README.md包含：- 框架概述
- 從結構產生的架構圖
- 從設定產生的部署圖
- 從程式碼產生的順序圖
- 從邏輯產生的活動圖
- 更新
SKILL.md中的程式碼轉圖表對照表
授權
克勞德代碼技能的一部分 - MIT 授權
相關技能
- 匯流 - 將圖表上傳至匯流
- 植物 UML - 替代圖表格式
連結
- GitHub 儲存庫
- Skilz 市集清單
- 美人魚官方文件
版本： 2.0.0 更新日期： 2025-01-13 維護者： SpillwaveSolutions