美人魚架構師 - 全面的圖表與文件技能
版本 2.0 - 具有智慧編排的階層式架構
一個強大的克勞德程式碼技能，用於建立美人魚圖表和設計文件，採用按需加載指南、程式碼轉圖表生成和 Python 工具。
安裝
透過斯基爾茲市場一鍵安裝
從 斯基爾茲市場 立即安裝此技能：
skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid
手動安裝
直接克隆到您的克勞德程式碼技能目錄中：
# 導航到您的技能目錄
cd ~/.claude/skills
# 克隆儲存庫
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git
驗證安裝
安裝後，驗證技能是否可用：
# 列出已安裝的技能
ls ~/.claude/skills/design-doc-mermaid
# 或詢問克勞德程式碼
# "列出我安裝的技能"
此技能的功能
智慧圖表生成：
- 活動圖（工作流程、程序、業務邏輯）
- 部署圖（雲端基礎設施、K8s、無伺服器）
- 架構圖（系統元件、微服務）
- 序列圖（API 流程、服務互動）
- 含有嵌入圖表的完整設計文件
程式碼轉圖表轉換：
- 從 Spring Boot 應用程式提取架構
- 從設定檔案生成部署圖
- 從方法調用建立序列圖
- 記錄 ETL 管線和資料流程
圖表管理：
- 從 Markdown 檔案中提取美人魚圖表
- 使用 mermaid-cli 驗證圖表語法
- 將圖表轉換為 PNG/SVG 圖片
- 批量處理整個目錄
快速入門
建立活動圖
使用者："建立一個帶有電子郵件驗證的使用者註冊活動圖表"
此技能將會：
- 載入
references/guides/diagrams/activity-diagrams.md - 使用註冊模式模板
- 加入 Unicode 符號（🔐 代表安全，📧 代表電子郵件，✅ 代表成功）
- 套用高對比度樣式
- 輸出完整的 Mermaid 圖表
從程式碼生成
使用者："這是我的 Spring Boot application.yml - 生成一個部署圖表"
此技能將會：
- 分析設定（資料來源、快取、安全）
- 載入
references/guides/diagrams/deployment-diagrams.md - 載入
examples/spring-boot/README.md - 將設定映射到雲端資源
- 生成含有資源規格的部署圖表
建立設計文件
使用者："為聯絡人 API 建立一份 API 設計文件"
此技能將會：
- 載入
assets/api-design-template.md - 載入相關的圖表指南（序列圖、ER圖、架構圖）
- 生成包含嵌入圖表的完整文件
- 儲存至
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. Unicode 語義符號
每個圖表都使用有意義的 Unicode 符號：
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 工具
提取圖表
# 列出檔案中的所有圖表
python scripts/extract_mermaid.py document.md --list-only
# 提取到獨立的 .mmd 檔案
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
# 從標準輸入
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png
需求
圖表生成需求
- 克勞德程式碼技能系統（自動）
- 指南和模板（包含在此技能中）
驗證與圖片轉換需求
# 全域安裝 mermaid-cli
npm install -g @mermaid-js/mermaid-cli
# 驗證安裝
mmdc --version
Python 腳本需求
- Python 3.7+
- 無需額外套件（僅使用標準庫）
學習路徑
剛接觸美人魚圖表？
- 從活動圖開始 - 閱讀
references/guides/diagrams/activity-diagrams.md - 學習 Unicode 符號 - 閱讀
references/guides/unicode-symbols/guide.md - 嘗試一個範例 - 使用
examples/spring-boot/中的模式 - 驗證您的作品 - 執行
python scripts/extract_mermaid.py --validate
需要記錄現有程式碼？
- 識別框架 - Spring Boot、FastAPI、React 等
- 載入範例指南 - 閱讀
examples/{your-framework}/README.md - 匹配模式 - 在範例中尋找相似的程式碼模式
- 生成圖表 - 使用指南中的模板
- 驗證 - 使用驗證腳本
建立設計文件？
- 選擇模板類型 - 架構、API、功能、資料庫或系統
- 載入模板 - 從
assets/{type}-design-template.md讀取 - 填寫各節 - 用實際內容替換佔位符
- 加入圖表 - 根據需要為每個部分載入圖表指南
- 使用符號 - 全程使用 Unicode 符號增強
- 儲存 - 放置於
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）
- Unicode 符號指南（100+ 符號）
- 含驗證功能的 Mermaid 提取腳本
- Mermaid 轉圖片的轉換腳本
- Spring Boot 程式碼轉圖表範例
- 設計文件模板（5 種類型）
- 高對比度樣式系統
🚧 進行中：
- FastAPI 範例
- React 元件架構範例
- Python ETL 管線範例
📋 計畫中：
- 架構圖指南
- 序列圖指南
- 程式碼轉圖表主要指南
- Node.js/Express 範例
- Java 網頁應用範例
貢獻
要新增一種新的圖表類型指南：
- 在
references/guides/diagrams/{type}-diagrams.md建立指南 - 包含：
- 何時使用
- 基本語法
- 常見模式（3-5 個模板）
- Unicode 符號範例
- 最佳實踐
- 更新
SKILL.md決策樹 - 加入帶有程式碼映射的範例
要新增一種新的語言範例：
- 在
examples/{framework}/建立目錄 - 加入包含下列內容的
README.md：- 框架概覽
- 從結構生成的架構圖
- 從設定生成的部署圖
- 從程式碼生成的序列圖
- 從邏輯生成的活動圖
- 更新
SKILL.md程式碼轉圖表表格
授權
克勞德程式碼技能的一部分 - MIT 授權
相關技能
- confluence - 將圖表上傳至 Confluence
- plantuml - 替代圖表格式
連結
- GitHub 儲存庫
- 斯基爾茲市場列表
- 美人魚官方文件
版本： 2.0.0 更新日期： 2025-01-13 維護者： SpillwaveSolutions