mermaid-architecture

Mermaid 架构图

创建结构清晰、对比度高、可用于生产环境的 Mermaid 架构图、工作流和系统设计文档。原生图表可直接在 Markdown 查看器（GitHub、GitLab、Obsidian、wiki）中渲染，也可通过 Mermaid CLI（mmdc / npx @mermaid-js/mermaid-cli）生成图像文件（PNG/SVG）。

📁 存储位置（docs/architecture/）

所有生成的架构图、.mmd 源文件、导出的图像和系统设计文档必须存储在 docs/architecture/ 中，以符合 drawio-architecture 约定：

docs/architecture/
├── system-architecture.md             # Architecture documentation with embedded Mermaid blocks
├── <name>_<type>_<title>.mmd          # Source Mermaid definitions
├── <name>_<type>_<title>.png          # Optional exported raster image
└── <name>_<type>_<title>.svg          # Optional exported vector image

保存前，请确保目录存在：

mkdir -p docs/architecture

适用场景

• 用户要求绘制架构图、系统结构图、组件概览、C4 模型、微服务拓扑图或数据流图。

• 记录API 交互、服务调用序列、身份验证流程或请求生命周期。

• 可视化工作流、状态机、业务逻辑、ETL 管道或决策树。

• 将代码映射到图表（Spring Boot、FastAPI、React、Node/Express、Python ETL、Java）。

• 创建或更新完整的设计文档（系统设计、架构、API 设计、数据库架构）。

• 在 **Orchestrator 流水线（第 5 阶段）**中：通过 /architecture（负责管理 docs/architecture/ 的总控技能）调用，以更新或生成原生 Markdown Mermaid 图表。

• 用户用英语询问或提及此技能（例如，“use /mermaid-architecture”、“run mermaid-architecture”、“generate mermaid diagram”）。

• 用户用葡萄牙语询问或提及此技能（例如：“use /mermaid-architecture”、“execute mermaid-architecture”、“gerar diagrama mermaid”）。

不适用场景

• 使用原生 .drawio 格式进行可视化拖放编辑 → 使用 /drawio-architecture。
• 徒手草图或随手画白板图 → 使用 Excalidraw 或 tldraw。
• 仅适用于 PlantUML 的旧版图表（Salt 线框图、时序图）。

Orchestrator 集成

在 Orchestrator 生命周期（第 5 阶段——验证与 QA 门控）中，Orchestrator 会调用 /architecture，由其将任务分派给专用引擎：

1. /drawio-architecture 更新可视化且可编辑的 .drawio 系统图。
2. /mermaid-architecture 紧接着运行，生成或更新原生 Mermaid 架构图，以及嵌入 docs/architecture/ 的 Markdown 文件。
3. 随后，/create-readme 会在 README.md 中引用生成的图表。

---

图表类型与选择指南

图表类型	最适用场景	要加载的指南
架构 / C4	系统上下文、容器、微服务、组件边界	references/guides/diagrams/architecture-diagrams.md
序列图	API 交互、身份验证流程、服务间消息传递、异步事件	references/guides/diagrams/sequence-diagrams.md
活动图 / 流程图	业务流程、审批管道、ETL 阶段、决策树	references/guides/diagrams/activity-diagrams.md
部署图 / 云架构图	云基础设施（AWS、Azure、GCP）、Kubernetes、网络	references/guides/diagrams/deployment-diagrams.md
类图 / ER 图 / 状态图	数据模型、数据库架构、生命周期转换	references/guides/wiki-ticket-and-github.md

---

支持错误恢复的弹性工作流

为避免语法错误进入文档，请遵循弹性验证流程：

flowchart LR
    A[1. Identify Diagram Type] --> B[2. Save .mmd to docs/architecture]
    B --> C{3. Validate Syntax}
    C -->|Valid| D[4. Embed in Markdown / Export]
    C -->|Invalid| E[5. Search Troubleshooting]
    E --> F[6. Apply Fix & Retry]
    F --> C

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

脚本执行

使用随附的弹性脚本，直接在 docs/architecture/ 中生成图表：

# Generate diagram with automatic syntax validation and image export
python3 skills/mermaid-architecture/scripts/resilient_diagram.py \
    --code "flowchart TD; A[Client] --> B[API Gateway]" \
    --output-dir docs/architecture \
    --markdown-file system_architecture \
    --diagram-num 1 \
    --title "overview" \
    --format png \
    --json

如果未全局安装 mmdc，脚本会自动使用 npx -y @mermaid-js/mermaid-cli。

---

高对比度样式（必须遵守）

所有图表都必须通过在每个 classDef 中指定 color:，确保文本在浅色和深色背景上均清晰可读：

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

    %% Rule: Every classDef MUST include color: property

---

语义 Unicode 符号

始终融入 Unicode 符号，以提升视觉浏览速度和清晰度：

• 👤 用户：👤 User、👨‍💼 Admin
• 🌐 网络：🌐 Load Balancer、🌐 API Gateway、☁️ Cloud
• ⚙️ 计算：⚙️ Service、⚡ Worker、🚀 Microservice
• 💾 存储：[(💾 Database)]、[(⚡ Redis Cache)]、📦 Object Storage
• 📨 消息传递：📨 Event Bus、📬 Message Queue、📢 PubSub
• 🔐 安全：🔐 Auth Service、🛡️ Firewall、🔑 Secrets
• 📊 可观测性：📊 Metrics、📝 Logs、🚨 Alerts

---

从代码提取图表

根据现有源代码生成架构时：

1. 分析入口点：读取控制器、路由、API 规范（@RestController、@app.get、Express 路由、Controllers）。
2. 追踪服务依赖：跟踪注入的服务、存储库、消息队列和数据库上下文。
3. 映射基础设施：读取 docker-compose.yml、Helm 图表、Terraform 或云配置。
4. 选择视图：
   • 高层组件拓扑 → architecture-diagrams.md
   • 方法／调用流程 → sequence-diagrams.md
   • 业务状态转换 → activity-diagrams.md
5. 参考 examples/ 中的框架模板（spring-boot、fastapi、react、node-webapp、python-etl、java-webapp）。

---

设计文档模板（assets/）

需要完整的架构或系统文档时，填写相应模板并保存到 docs/architecture/：

文档类型	模板路径	目标输出
架构设计	assets/architecture-design-template.md	docs/architecture/architecture-design.md
系统设计	assets/system-design-template.md	docs/architecture/system-design.md
API 设计	assets/api-design-template.md	docs/architecture/api-design.md
数据库设计	assets/database-design-template.md	docs/architecture/database-design.md
功能设计	assets/feature-design-template.md	docs/architecture/feature-<name>-design.md

---

Python 工具

此技能包含 scripts/ 中的独立工具：

# Extract diagrams from markdown, validate, or convert
python3 skills/mermaid-architecture/scripts/extract_mermaid.py docs/architecture/system.md --validate

# Convert .mmd to PNG or SVG
python3 skills/mermaid-architecture/scripts/mermaid_to_image.py docs/architecture/overview.mmd docs/architecture/overview.png

# Full resilient generation with error diagnostics
python3 skills/mermaid-architecture/scripts/resilient_diagram.py --code "..." --title "service_map"

---

参考资料

• references/guides/diagrams/architecture-diagrams.md — C4 模型、微服务、组件架构
• references/guides/diagrams/sequence-diagrams.md — API 交互、服务调用
• references/guides/diagrams/activity-diagrams.md — 工作流和流程
• references/guides/diagrams/deployment-diagrams.md — 云、基础设施和部署
• references/guides/unicode-symbols/guide.md — 完整的语义符号索引
• references/guides/troubleshooting.md — 28 种常见语法错误的解决方案
• references/guides/resilient-workflow.md — 错误恢复和验证协议
• architecture — 统筹技能，负责 docs/architecture/，并将图表任务分配给此引擎
• drawio-architecture — 配套技能，用于创建可编辑的 draw.io 可视化图表