# 美人魚架構師：圖表與文件技能

> 透過智慧編排、程式碼轉圖表以及 Python 工具，產生全面的美人魚圖表與設計文件。在幾秒內即可開始建立詳細的技術文件。

- Canonical: https://nanoskill.ai/tw/skills/mermaid-agent-skill
- Markdown: https://nanoskill.ai/tw/skills/mermaid-agent-skill.md
- Author: SpillwaveSolutions
- Published: 2026-05-26T01:25:42.765Z
- Updated: 2026-07-19T03:48:37.206Z
- Language: zh-TW
- Source type: github
- Popularity signal: 66

## Sources

- https://github.com/spillwavesolutions/design-doc-mermaid

## Install

```shell
npx skills add https://github.com/spillwavesolutions/design-doc-mermaid
```

## About

美人魚架構師技能讓開發者、架構師和技術寫手能夠有效率地建立與管理全面的美人魚圖表和設計文件。透過智慧編排與隨需指導載入，此技能簡化了複雜系統、工作流程和程式碼結構的視覺化。它協助使用者產生精確且視覺吸引人的圖表，確保清晰的溝通與最新的文件。

這項強大的 Claude Code 技能提供先進功能，例如程式碼轉圖表產生，讓您能直接從 Spring Boot 或 FastAPI 應用程式中提取架構洞見。它還包含豐富的 Python 工具集，用於提取、驗證和轉換美人魚圖表為映像格式，使其易於與現有的文件工作流程和 Confluence 等工具整合。其階層式系統確保高效的符記使用與快速回應時間，提供無縫體驗。

無論您需要記錄 API、視覺化系統架構，或描繪商業流程，美人魚架構師提供所需的工具與範本。支援各種圖表類型、Unicode 語意符號和高對比樣式，您的圖表將兼具資訊性與可存取性。此技能還提供結構化的學習路徑和範例，幫助使用者快速精通建立詳細的技術文件。

## Key features

- **智慧圖表生成**: 建立各種Mermaid圖表，包括活動圖、部署圖、架構圖和順序圖，用於工作流程、基礎架構、系統組件和API流程。
- **程式碼轉圖表**: 從現有的程式碼庫（如Spring Boot、FastAPI）或設定檔自動產生圖表，以可視化架構、部署和順序流程。
- **全面的設計文件建立**: 使用預定義的架構、API、功能、資料庫和系統設計範本，產生內嵌Mermaid圖表的完整設計文件。
- **Unicode語義符號與高對比樣式**: 透過超過100個有意義的Unicode符號和高對比配色方案，增強圖表的清晰度和可及性，提升可讀性。
- **Python圖表管理工具**: 利用Python腳本提取、驗證Mermaid圖表並將其轉換為PNG/SVG圖像，支援批次處理以及與Confluence等工具的整合。

## Use cases

- **可視化軟體架構**: 開發人員和架構師可以從程式碼或設定檔產生架構圖和部署圖，以了解系統組件和基礎架構。
- **記錄API流程與工作流程**: 技術文件撰寫人員和工程師可以建立詳細的順序圖和活動圖，以說明API互動、業務流程和使用者旅程。
- **自動化設計文件建立**: 團隊可以快速產生各種用途（API、系統、功能）的結構化設計文件，並自動嵌入Mermaid圖表，節省時間並確保一致性。
- **維護最新的技術文件**: 透過直接從程式碼或設定產生圖表，確保文件保持最新，並輕鬆將其轉換為圖像格式以便分享和協作。

## Result preview

查看由此代理技能所產生的美食外送平台系統之美人魚圖表。

![mermaid-architect-demo1](https://file.nanoskill.ai/mermaid-architect-demo1.jpg)

![mermaid-architect-demo-2](https://file.nanoskill.ai/mermaid-architect-demo-2.jpg)

![mermaid-architect-demo-3](https://file.nanoskill.ai/mermaid-architect-demo-3.jpg)

## Result walkthrough

### 步驟 1：安裝

將技能新增至您的代理。

![mermaid-architect-step-1](https://file.nanoskill.ai/mermaid-architect-step-1.jpg)

### 步驟 2：描述一個流程

輸入您想要視覺化的工作流程、系統或序列。

![mermaid-architect-step-2](https://file.nanoskill.ai/mermaid-architect-step-2.jpg)

### 步驟 3：檢視結果

根據您的流程描述，取得產生的美人魚圖表。

![mermaid-architect-step-3](https://file.nanoskill.ai/mermaid-architect-step-3.jpg)

## Skill definition

# 美人魚架構師 - 全面的圖表與文件技能

**版本 2.0** - 具有智慧編排的階層式架構

一個強大的克勞德程式碼技能，用於建立美人魚圖表和設計文件，採用按需加載指南、程式碼轉圖表生成和 Python 工具。

## 安裝

### 透過斯基爾茲市場一鍵安裝

從 [斯基爾茲市場](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/) 立即安裝此技能：

```bash
skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid
```

### 手動安裝

直接克隆到您的克勞德程式碼技能目錄中：

```bash
# 導航到您的技能目錄
cd ~/.claude/skills

# 克隆儲存庫
git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git
```

### 驗證安裝

安裝後，驗證技能是否可用：

```bash
# 列出已安裝的技能
ls ~/.claude/skills/design-doc-mermaid

# 或詢問克勞德程式碼
# "列出我安裝的技能"
```

## 此技能的功能

**智慧圖表生成：**
- 活動圖（工作流程、程序、業務邏輯）
- 部署圖（雲端基礎設施、K8s、無伺服器）
- 架構圖（系統元件、微服務）
- 序列圖（API 流程、服務互動）
- 含有嵌入圖表的完整設計文件

**程式碼轉圖表轉換：**
- 從 Spring Boot 應用程式提取架構
- 從設定檔案生成部署圖
- 從方法調用建立序列圖
- 記錄 ETL 管線和資料流程

**圖表管理：**
- 從 Markdown 檔案中提取美人魚圖表
- 使用 mermaid-cli 驗證圖表語法
- 將圖表轉換為 PNG/SVG 圖片
- 批量處理整個目錄

## 快速入門

### 建立活動圖

```
使用者："建立一個帶有電子郵件驗證的使用者註冊活動圖表"
```

此技能將會：
1. 載入 `references/guides/diagrams/activity-diagrams.md`
2. 使用註冊模式模板
3. 加入 Unicode 符號（🔐 代表安全，📧 代表電子郵件，✅ 代表成功）
4. 套用高對比度樣式
5. 輸出完整的 Mermaid 圖表

### 從程式碼生成

```
使用者："這是我的 Spring Boot application.yml - 生成一個部署圖表"
```

此技能將會：
1. 分析設定（資料來源、快取、安全）
2. 載入 `references/guides/diagrams/deployment-diagrams.md`
3. 載入 `examples/spring-boot/README.md`
4. 將設定映射到雲端資源
5. 生成含有資源規格的部署圖表

### 建立設計文件

```
使用者："為聯絡人 API 建立一份 API 設計文件"
```

此技能將會：
1. 載入 `assets/api-design-template.md`
2. 載入相關的圖表指南（序列圖、ER圖、架構圖）
3. 生成包含嵌入圖表的完整文件
4. 儲存至 `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 符號：

```mermaid
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 工具

#### 提取圖表

```bash
# 列出檔案中的所有圖表
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
```

#### 轉換為圖片

```bash
# 單一檔案
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
```

## 需求

### 圖表生成需求
- 克勞德程式碼技能系統（自動）
- 指南和模板（包含在此技能中）

### 驗證與圖片轉換需求
```bash
# 全域安裝 mermaid-cli
npm install -g @mermaid-js/mermaid-cli

# 驗證安裝
mmdc --version
```

### Python 腳本需求
- Python 3.7+
- 無需額外套件（僅使用標準庫）

## 學習路徑

### 剛接觸美人魚圖表？

1. **從活動圖開始** - 閱讀 `references/guides/diagrams/activity-diagrams.md`
2. **學習 Unicode 符號** - 閱讀 `references/guides/unicode-symbols/guide.md`
3. **嘗試一個範例** - 使用 `examples/spring-boot/` 中的模式
4. **驗證您的作品** - 執行 `python scripts/extract_mermaid.py --validate`

### 需要記錄現有程式碼？

1. **識別框架** - Spring Boot、FastAPI、React 等
2. **載入範例指南** - 閱讀 `examples/{your-framework}/README.md`
3. **匹配模式** - 在範例中尋找相似的程式碼模式
4. **生成圖表** - 使用指南中的模板
5. **驗證** - 使用驗證腳本

### 建立設計文件？

1. **選擇模板類型** - 架構、API、功能、資料庫或系統
2. **載入模板** - 從 `assets/{type}-design-template.md` 讀取
3. **填寫各節** - 用實際內容替換佔位符
4. **加入圖表** - 根據需要為每個部分載入圖表指南
5. **使用符號** - 全程使用 Unicode 符號增強
6. **儲存** - 放置於 `docs/design/` 並加上時間戳記

## 階層式系統如何運作

### 傳統方法（低效率）
- 載入整個技能文件（約 50KB）
- AI 處理所有模板和範例
- 高用量代幣
- 回應時間慢

### 階層式方法（高效率）
1. **使用者發出請求** → AI 分析意圖
2. **決策樹啟動** → 確定所需指南
3. **只載入所需內容** → 讀取特定指南（約 2-5KB）
4. **生成輸出** → 使用針對性模板
5. **代幣效率高** → 所需上下文減少 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 網頁應用範例

## 貢獻

要新增一種新的圖表類型指南：

1. 在 `references/guides/diagrams/{type}-diagrams.md` 建立指南
2. 包含：
   - 何時使用
   - 基本語法
   - 常見模式（3-5 個模板）
   - Unicode 符號範例
   - 最佳實踐
3. 更新 `SKILL.md` 決策樹
4. 加入帶有程式碼映射的範例

要新增一種新的語言範例：

1. 在 `examples/{framework}/` 建立目錄
2. 加入包含下列內容的 `README.md`：
   - 框架概覽
   - 從結構生成的架構圖
   - 從設定生成的部署圖
   - 從程式碼生成的序列圖
   - 從邏輯生成的活動圖
3. 更新 `SKILL.md` 程式碼轉圖表表格

## 授權

克勞德程式碼技能的一部分 - MIT 授權

## 相關技能

- **confluence** - 將圖表上傳至 Confluence
- **plantuml** - 替代圖表格式

## 連結

- [GitHub 儲存庫](https://github.com/SpillwaveSolutions/design-doc-mermaid)
- [斯基爾茲市場列表](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/)
- [美人魚官方文件](https://mermaid.js.org/)

---

**版本：** 2.0.0
**更新日期：** 2025-01-13
**維護者：** SpillwaveSolutions

## FAQ

### 這個技能可以產生哪些類型的Mermaid圖表？

這個技能可以產生活動圖、部署圖、架構圖和順序圖。它支援可視化工作流程、雲端基礎架構、系統組件和API互動。

### 程式碼轉換為圖表的運作原理是什麼？

該技能會分析你的程式碼或設定檔（例如Spring Boot application.yml），並使用預定義的模式和指南，自動生成對應的Mermaid圖表，例如部署圖或順序圖。

### 我能用這個技能建立完整的設計文件嗎？

可以，該技能包含各種設計文件的範本（架構、API、功能、資料庫、系統）。它可以根據你的輸入和所選範本，產生內嵌Mermaid圖表的完整文件。

### 用於產生Mermaid圖表的分層系統有哪些好處？

分層系統能高效分析你的意圖，並僅載入必要的指南和範本（通常為2-5KB），而非整個技能文件。這大幅減少了使用的token數量，並加快了回應速度。

### 這個技能有包含任何Python工具嗎？

是的，該技能提供Python腳本，可從Markdown檔案中提取Mermaid圖表、驗證其語法，並將其轉換為PNG或SVG圖像格式。這些工具也支援批次處理。

### 使用驗證和圖像轉換功能有哪些需求？

要進行圖表驗證和圖像轉換，你需要透過npm全域安裝\`mermaid-cli\`（\`npm install -g @mermaid-js/mermaid-cli\`）。Python腳本需要Python 3.7以上版本。