design-doc-mermaid

Mermaid Architect - 分层图表与文档技能

Mermaid 图表和文档系统，提供专门指南以及将代码转换为图表的能力。

目录

• 决策树
• GitHub Wiki、WikiTicket 和 Confluence
• 可用指南与资源
• 使用模式
• 弹性工作流
• Unicode 语义符号
• Python 实用工具
• 决策树示例
• 高对比度样式
• 文件组织
• 工作流摘要
• 何时使用什么
• 最佳实践
• 学习路径

决策树

此技能的工作方式：

1. 用户提出请求 → 技能分析意图
2. 技能确定图表／文档类型 → 加载相应指南
3. AI 阅读专门指南 → 使用模板生成图表／文档
4. 交付结果 → 提供验证和导出选项

用户意图分析：

flowchart TD
    Start([User Request]) --> Analyze{Analyze Intent}

    Analyze -->|"workflow, process, business logic"| Activity[Load Activity Diagram Guide<br/>references/guides/diagrams/activity-diagrams.md]
    Analyze -->|"infrastructure, deployment, cloud"| Deploy[Load Deployment Diagram Guide<br/>references/guides/diagrams/deployment-diagrams.md]
    Analyze -->|"system architecture, components"| Arch[Load Architecture Guide<br/>references/guides/diagrams/architecture-diagrams.md]
    Analyze -->|"API flow, interactions"| Sequence[Load Sequence Diagram Guide<br/>references/guides/diagrams/sequence-diagrams.md]
    Analyze -->|"class, ER, state, wiki, walkthrough"| WikiGuide[Load WikiTicket GitHub Guide<br/>references/guides/wiki-ticket-and-github.md]
    Analyze -->|"code to diagram"| CodeToDiag[Load Code-to-Diagram Guide<br/>references/guides/code-to-diagram/ + examples/]
    Analyze -->|"design document, full docs"| DesignDoc[Load Design Document Template<br/>assets/*-design-template.md]
    Analyze -->|"unicode symbols, icons"| Unicode[Load Unicode Symbols Guide<br/>references/guides/unicode-symbols/guide.md]
    Analyze -->|"extract, validate, convert"| Scripts[Use Python Scripts<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py]

    Activity --> Generate[Generate Diagram]
    Deploy --> Generate
    Arch --> Generate
    Sequence --> Generate
    WikiGuide --> Generate
    CodeToDiag --> Generate
    DesignDoc --> Generate
    Unicode --> Generate
    Scripts --> Execute[Execute Script]

    Generate --> Validate{Validate?}
    Validate -->|Yes| RunValidation[Run mmdc validation]
    Validate -->|No| Output
    RunValidation --> Output[Output Result]
    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 应用	examples/java-webapp/README.md	传统 MVC、Servlet 容器、WAR 部署

设计文档模板

模板	完整路径	用途	加载时机
架构设计	assets/architecture-design-template.md	系统级架构	"Create architecture doc", "Document system design"
API 设计	assets/api-design-template.md	API 规范	"API design doc", "Document REST API"
功能设计	assets/feature-design-template.md	功能规划	"Feature design", "Plan new feature"
数据库设计	assets/database-design-template.md	数据库架构	"Database design", "Document schema"
系统设计	assets/system-design-template.md	完整系统	"System design doc", "Full system documentation"

Unicode 符号指南

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

在用户提及时加载： "unicode symbols", "emoji in diagrams", "semantic icons", "add symbols"

快速参考：

• 📦 基础设施：☁️ 🌐 🔌 📡 🗄️
• ⚙️ 计算：⚙️ ⚡ 🔄 ♻️ 🚀 💨
• 💾 数据：💾 📦 📊 📈 🗃️ 🧊
• 📨 消息传递：📨 📬 📤 📥 🐰 📢
• 🔐 安全：🔐 🔑 🛡️ 🚪 👤 🎫
• 📝 监控：📝 📊 🚨 ⚠️ ✅ ❌

Python 脚本（scripts/）

脚本	用途	加载时机
extract_mermaid.py	从 Markdown 提取图表、验证语法并替换为图像	"extract diagrams", "validate mermaid", "find all diagrams"
mermaid_to_image.py	将 .mmd 转换为 PNG/SVG，批量转换并使用自定义主题	"convert to image", "render diagram", "create PNG"
resilient_diagram.py	完整工作流：保存 .mmd、生成图像、验证并恢复错误	"generate diagram", "create diagram with validation", "resilient diagram"

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 格式交付。

使用模式

常见请求模式及指南选择。完整映射请参阅何时使用什么。

模式	请求示例	要加载的指南
单个图表	"Create activity diagram for login flow"	图表类型指南 + Unicode 符号
代码转图表	"Generate deployment from application.yml"	框架示例 + 部署指南
设计文档	"Create API design document"	assets/ 中的模板 + 相关图表指南
提取/验证	"Extract diagrams from design.md"	使用 scripts/extract_mermaid.py
批量转换	"Convert all .mmd to PNG"	使用 scripts/mermaid_to_image.py

弹性工作流

重要： 这是生成所有图表的推荐方式，可确保验证、错误恢复和文件组织一致。

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

工作流概览

flowchart LR
    A[1. Identify Type] --> B[2. Save .mmd + Image]
    B --> C{3. Valid?}
    C -->|Yes| D[4. Add to Markdown]
    C -->|No| E[5. Error Recovery]
    E --> F{Fix Found?}
    F -->|Yes| A
    F -->|No| G[Search External]
    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 中。 这样可以避免文档中出现损坏的图表。

使用脚本（推荐）

# Generate with full error recovery
python scripts/resilient_diagram.py \
    --code "flowchart TD; A-->B" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "process_flow" \
    --format png \
    --json

输出： ./diagrams/ 目录中的 .mmd 和 .png 文件。

文件命名约定

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

示例： ./diagrams/api_design_01_sequence_auth_flow.png

错误恢复优先级

验证失败时，工作流会自动执行以下操作：

1. 查看故障排除指南 - references/guides/troubleshooting.md（记录了 28 个错误）
2. 使用 perplexity 搜索 - 针对语法问题使用 perplexity_ask MCP
3. 使用 brave 搜索 - 针对近期解决方案使用 brave_web_search MCP
4. 询问 gemini - 使用 gemini skill 获取另一种观点
5. 常规搜索 - 使用 WebSearch tool 作为备用方案

手动备用步骤

如果脚本不可用：

1. 从第一行识别图表类型（flowchart、sequence 等）
2. 加载参考指南，路径为 references/guides/diagrams/
3. 保存到 ./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
4. 验证： mmdc -i file.mmd -o file.png -b transparent
5. 出错时： 在 references/guides/troubleshooting.md 中搜索匹配的错误
6. 如果没有找到： 按照上述优先级使用搜索工具
7. 添加引用： ![Description](./diagrams/filename.png)

模式 6：弹性图表生成

用户：“创建一个时序图并将其添加到设计文档中”

技能操作：

1. 识别意图：生成图表 + 集成到 Markdown
2. 加载工作流指南：references/guides/resilient-workflow.md
3. 识别图表类型：时序图
4. 加载图表指南：references/guides/diagrams/sequence-diagrams.md
5. 使用模板生成 Mermaid 代码
6. 执行弹性工作流：

   python scripts/resilient_diagram.py \
       --code "[generated code]" \
       --markdown-file design_doc \
       --diagram-num 1 \
       --title "api_sequence" \
       --json
   

7. 如果验证失败 → 应用故障排除修复 → 重试
8. 成功后 → 将 ![API Sequence](./diagrams/design_doc_01_sequence_api_sequence.png) 添加到 Markdown

Unicode 语义符号

始终使用 Unicode 符号来增强图表的清晰度。常见模式：

基础设施与部署

graph TB
    Client[👤 User] --> LB[🌐 Load Balancer]
    LB --> App1[⚙️ App Server 1]
    LB --> App2[⚙️ App Server 2]
    App1 --> DB[(💾 Database)]
    App1 --> Cache[(⚡ Redis)]

含状态的活动流程

flowchart TD
    Start([🚀 Start]) --> Process[⚙️ Process Data]
    Process --> Check{✓ Valid?}
    Check -->|Yes| Save[💾 Save]
    Check -->|No| Error[❌ Error]
    Save --> Complete([✅ Complete])

微服务架构

graph TB
    API[🌐 API Gateway] --> Auth[🔐 Auth Service]
    API --> Orders[📋 Order Service]
    Orders --> Queue[📬 Message Queue]
    Queue --> Worker[⚙️ Background Worker]
    Worker --> Storage[📦 Object Storage]

完整的符号参考，请加载： references/guides/unicode-symbols/guide.md

Python 工具

提取 Mermaid 图表

# List all diagrams
python scripts/extract_mermaid.py document.md --list-only

# Extract to separate files
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Validate all diagrams
python scripts/extract_mermaid.py document.md --validate

# Replace with image references (for Confluence upload)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

转换为图像

# Single conversion
python scripts/mermaid_to_image.py diagram.mmd output.png

# With custom settings
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

决策树示例

示例 1：用户请求工作流图

输入：“展示结账流程工作流”

技能决策路径：

1. Analyze: workflow, process → ACTIVITY DIAGRAM
2. Load guide: guides/diagrams/activity-diagrams.md
3. Find pattern: E-commerce checkout (template exists in guide)
4. Generate using template + Unicode symbols
5. Output activity diagram with decision points

**输出：**完整的活动图，使用 Unicode 符号表示购物车、付款和订单状态。

示例 2：用户提供 Spring Boot 代码

输入：“这是我的 Spring Boot 控制器，创建图表”

技能决策路径：

1. Analyze: Spring Boot, code provided → CODE-TO-DIAGRAM + SPRING BOOT
2. Load guides:
   - examples/spring-boot/README.md
   - guides/diagrams/architecture-diagrams.md (for structure)
   - guides/diagrams/sequence-diagrams.md (for method calls)
   - guides/diagrams/activity-diagrams.md (for business logic)
3. Generate multiple diagrams:
   a. Architecture diagram from @RestController/@Service/@Repository annotations
   b. Sequence diagram from method call chain
   c. Activity diagram from business logic flow
4. Output all diagrams with explanations

**输出：**展示 Spring Boot 应用程序不同视图的 3-4 个图表。

示例 3：用户希望编写基础设施文档

输入：“记录我使用 AlloyDB 部署 GCP Cloud Run 的情况”

技能决策路径：

1. Analyze: infrastructure, GCP, Cloud Run → DEPLOYMENT DIAGRAM
2. Load guides:
   - guides/diagrams/deployment-diagrams.md
   - examples/spring-boot/ or examples/fastapi/ (if code provided)
3. Check for IaC files (Pulumi, Terraform, docker-compose)
4. Generate deployment diagram with:
   - Cloud Run services with specs
   - VPC connector
   - AlloyDB cluster
   - Security (IAM, Secret Manager)
   - Monitoring
5. Apply Unicode symbols for clarity
6. Output with resource specifications

**输出：**包含所有资源标签的完整 GCP 部署图。

高对比度样式

所有图表都必须使用高对比度颜色：

graph TB
    classDef primary fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
    classDef secondary fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue
    classDef database fill:#E6E6FA,stroke:#333,stroke-width:2px,color:darkblue
    classDef error fill:#FFB6C1,stroke:#DC143C,stroke-width:2px,color:black

    %% Every classDef MUST have color: property

规则：

• 浅色背景 → 深色文本
• 深色背景 → 浅色文本
• 始终在每个 classDef 中指定 color:

文件组织

design-doc-mermaid/
├── SKILL.md                          # This file - Main orchestrator
├── README.md                         # User documentation
├── CLAUDE.md                         # Claude Code instructions
│
├── references/                       # Reference materials
│   ├── mermaid-diagram-guide.md     # Legacy general guide
│   └── guides/                       # Specialized guides (load on-demand)
│       ├── diagrams/
│       │   ├── activity-diagrams.md      # Workflows, processes
│       │   ├── deployment-diagrams.md    # Infrastructure, cloud
│       │   ├── architecture-diagrams.md  # System architecture
│       │   └── sequence-diagrams.md      # API interactions
│       ├── code-to-diagram/
│       │   └── README.md                 # Master guide for code analysis
│       ├── unicode-symbols/
│       │   └── guide.md                  # Complete symbol reference
│       └── troubleshooting.md        # Common syntax errors & fixes
│
├── assets/                           # Design document templates
│   ├── architecture-design-template.md
│   ├── api-design-template.md
│   ├── feature-design-template.md
│   ├── database-design-template.md
│   └── system-design-template.md
│
├── scripts/                          # Python utilities
│   ├── extract_mermaid.py           # Extract & validate diagrams
│   └── mermaid_to_image.py          # Convert to PNG/SVG
│
├── examples/                         # Language-specific patterns
│   ├── spring-boot/                 # Spring Boot patterns
│   ├── fastapi/                     # FastAPI patterns
│   ├── react/                       # React patterns
│   ├── python-etl/                  # Data pipeline patterns
│   ├── node-webapp/                 # Express.js patterns
│   └── java-webapp/                 # Traditional Java patterns
│
└── references/                       # General Mermaid reference
    └── mermaid-diagram-guide.md     # Complete Mermaid syntax guide

工作流摘要

1. 分析用户意图 → 确定所需的图表类型、文档类型或操作
2. 加载适当的指南 → 只阅读所需内容（节省 token）
3. 应用模板和模式 → 使用指南中的示例
4. 生成输出 → 创建图表或文档
5. 验证（可选）→ 使用脚本进行验证
6. 转换（可选）→ 如有需要，导出为图像

何时使用什么

用户请求	加载此项
“活动图”“工作流”“流程图”	references/guides/diagrams/activity-diagrams.md
“部署”“基础设施”“云”“k8s”	references/guides/diagrams/deployment-diagrams.md
“架构”“系统设计”“组件”	references/guides/diagrams/architecture-diagrams.md + 设计模板
“API”“时序”“交互”“流程”	references/guides/diagrams/sequence-diagrams.md
“类图”“ER”“状态机”“wiki”“演练”“架构文档”	references/guides/wiki-ticket-and-github.md 加上相应类型指南
“Confluence”“上传图片”“PNG”“SVG”	scripts/resilient_diagram.py 或 scripts/mermaid_to_image.py
“Spring Boot 代码”	examples/spring-boot/ + 相关图表指南
“FastAPI 代码”“Python API”	examples/fastapi/ + 相关图表指南
“React 应用”“前端”	examples/react/ + 架构指南
“ETL”“数据管道”“Python 批处理”	examples/python-etl/ + 活动图指南
“符号”“unicode”“emoji”	references/guides/unicode-symbols/guide.md
“语法错误”“图表无法渲染”“故障排查”	references/guides/troubleshooting.md
“提取图表”	scripts/extract_mermaid.py
“转换为图片”“PNG”“SVG”	scripts/mermaid_to_image.py
“创建图表”“生成图表”“将图表添加到 markdown”	scripts/resilient_diagram.py + references/guides/resilient-workflow.md
“设计文档”“完整文档”	assets/*-design-template.md + 图表指南

最佳实践

1. 单一职责：一张图表 = 一个概念
2. Unicode 增强：始终使用语义符号以提高清晰度
3. 高对比度：样式中绝不省略 color: 属性
4. 尽早验证：使用脚本捕获语法错误
5. 复用模板：充分利用现有模板和示例
6. 按需加载：只阅读特定请求所需的指南
7. 提高令牌效率：使用分层加载，而不是阅读所有内容

学习路径

刚接触 Mermaid？ 从这里开始：

1. 阅读 references/guides/unicode-symbols/guide.md，了解符号含义
2. 阅读 references/guides/diagrams/activity-diagrams.md，了解基本模式
3. 尝试 examples/spring-boot/ 或 examples/fastapi/ 中的示例
4. 使用 scripts/extract_mermaid.py --validate 检查成果

需要为代码编写文档？ 按以下步骤操作：

1. 确定框架 → 加载相关的 examples/{framework}/
2. 将代码模式与图表类型对应起来
3. 使用指南中的模板
4. 使用脚本进行验证

要创建设计文档？ 按以下步骤操作：

1. 选择文档类型 → 从 assets/ 加载模板
2. 填写文本部分
3. 根据各部分需要加载图表指南
4. 全文使用 Unicode 符号
5. 添加时间戳后保存到 docs/design/

---

版本： 2.0（分层架构） 最后更新： 2025-01-13 维护者： Claude Code Skills