Mermaid Architect - 分层图表与文档技能
Mermaid 图表和文档系统，具有专用指南和代码到图表的能力。
目录
- 决策树
- GitHub wiki、WikiTicket 和 Confluence
- 可用指南和资源
- 使用模式
- 弹性工作流
- Unicode 语义符号
- Python 工具
- 决策树示例
- 高对比度样式
- 文件组织
- 工作流摘要
- 何时使用何种类型
- 最佳实践
- 学习路径
决策树
此技能的工作方式：
- 用户发起请求 → 技能分析意图
- 技能确定图表/文档类型 → 加载适当的指南
- AI 阅读专用指南 → 使用模板生成图表/文档
- 交付结果 → 附带验证和导出选项
用户意图分析：
flowchart TD
Start([用户请求]) --> Analyze{分析意图}
Analyze -->|"工作流、流程、业务逻辑"| Activity[加载活动图指南<br/>references/guides/diagrams/activity-diagrams.md]
Analyze -->|"基础设施、部署、云"| Deploy[加载部署图指南<br/>references/guides/diagrams/deployment-diagrams.md]
Analyze -->|"系统架构、组件"| Arch[加载架构指南<br/>references/guides/diagrams/architecture-diagrams.md]
Analyze -->|"API 流程、交互"| Sequence[加载时序图指南<br/>references/guides/diagrams/sequence-diagrams.md]
Analyze -->|"类、ER、状态、wiki、演练"| WikiGuide[加载 WikiTicket GitHub 指南<br/>references/guides/wiki-ticket-and-github.md]
Analyze -->|"代码转图表"| CodeToDiag[加载代码转图表指南<br/>references/guides/code-to-diagram/ + examples/]
Analyze -->|"设计文档、完整文档"| DesignDoc[加载设计文档模板<br/>assets/*-design-template.md]
Analyze -->|"unicode 符号、图标"| Unicode[加载 Unicode 符号指南<br/>references/guides/unicode-symbols/guide.md]
Analyze -->|"提取、验证、转换"| Scripts[使用 Python 脚本<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py]
Activity --> Generate[生成图表]
Deploy --> Generate
Arch --> Generate
Sequence --> Generate
WikiGuide --> Generate
CodeToDiag --> Generate
DesignDoc --> Generate
Unicode --> Generate
Scripts --> Execute[执行脚本]
Generate --> Validate{验证？}
Validate -->|是| RunValidation[运行 mmdc 验证]
Validate -->|否| Output
RunValidation --> Output[输出结果]
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 | 系统级架构 | "创建架构文档"、"文档化系统设计" |
| API 设计 | assets/api-design-template.md | API 规范 | "API 设计文档"、"文档化 REST API" |
| 功能设计 | assets/feature-design-template.md | 功能规划 | "功能设计"、"规划新功能" |
| 数据库设计 | assets/database-design-template.md | 数据库模式 | "数据库设计"、"文档化模式" |
| 系统设计 | assets/system-design-template.md | 完整系统 | "系统设计文档"、"完整系统文档" |
Unicode 符号指南
完整路径： references/guides/unicode-symbols/guide.md
当用户提到时加载： "unicode 符号"、"图表中的表情符号"、"语义图标"、"添加符号"
快速参考：
- 📦 基础设施：☁️ 🌐 🔌 📡 🗄️
- ⚙️ 计算：⚙️ ⚡ 🔄 ♻️ 🚀 💨
- 💾 数据：💾 📦 📊 📈 🗃️ 🧊
- 📨 消息传递：📨 📬 📤 📥 🐰 📢
- 🔐 安全：🔐 🔑 🛡️ 🚪 👤 🎫
- 📝 监控：📝 📊 🚨 ⚠️ ✅ ❌
Python 脚本（scripts/）
| 脚本 | 用途 | 何时加载 |
|---|---|---|
extract_mermaid.py | 从 Markdown 提取图表、验证语法、替换为图片 | "提取图表"、"验证 mermaid"、"找到所有图表" |
mermaid_to_image.py | 转换 .mmd 为 PNG/SVG、批量转换、自定义主题 | "转换为图片"、"渲染图表"、"创建 PNG" |
resilient_diagram.py | 完整工作流：保存 .mmd、生成图片、验证、错误恢复 | "生成图表"、"创建带验证的图表"、"弹性图表" |
GitHub wiki、WikiTicket 和 Confluence
为 WikiTicket 设计文档、代码演练、需求、GitHub wiki 或 Confluence 加载 references/guides/wiki-ticket-and-github.md。
| 目标 | 提供内容 |
|---|---|
| GitHub wiki / GFM | 围栏 mermaid 代码块。GitHub 渲染类图、ER图、状态图、时序图、流程图、C4。 |
| Confluence / Notion / Word / PDF | 同时渲染 PNG 或 SVG（通过 scripts/resilient_diagram.py 或 mmdc）并上传图片。不要依赖 Confluence 渲染 Mermaid。 |
PlantUML 是可选的，用于 Salt 线框图、用例、时序、ArchiMate、nwdiag 和 WBS。这些始终提供 PNG 或 SVG。
使用模式
常见的请求模式和指南选择。完整映射请参见何时使用何种类型。
| 模式 | 示例请求 | 要加载的指南 |
|---|---|---|
| 单个图表 | "为登录流程创建活动图" | 图表类型指南 + Unicode 符号 |
| 代码转图表 | "从 application.yml 生成部署图" | 框架示例 + 部署指南 |
| 设计文档 | "创建 API 设计文档" | assets/ 中的模板 + 相关图表指南 |
| 提取/验证 | "从 design.md 提取图表" | 使用 scripts/extract_mermaid.py |
| 批量转换 | "将所有 .mmd 转换为 PNG" | 使用 scripts/mermaid_to_image.py |
弹性工作流
关键： 这是所有图表生成推荐的方案。它确保验证、错误恢复和一致的文件组织。
完整指南： references/guides/resilient-workflow.md
工作流概览
flowchart LR
A[1. 识别类型] --> B[2. 保存 .mmd + 图片]
B --> C{3. 有效？}
C -->|是| D[4. 添加到 Markdown]
C -->|否| E[5. 错误恢复]
E --> F{找到修复？}
F -->|是| A
F -->|否| G[外部搜索]
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 中。 这可以防止文档中出现损坏的图表。
使用脚本（推荐）
# 生成并带有完整错误恢复
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
错误恢复优先级
验证失败时，工作流自动执行：
- 检查故障排除指南 -
references/guides/troubleshooting.md（包含 28 个记录的错误） - 使用 perplexity 搜索 -
perplexity_askMCP 用于语法问题 - 使用 brave 搜索 -
brave_web_searchMCP 用于最新解决方案 - 询问 gemini -
gemini技能获取替代视角 - 通用搜索 - 使用
WebSearch工具作为后备
手动后备步骤
如果脚本不可用：
- 从第一行识别图表类型（flowchart、sequence 等）
- 从
references/guides/diagrams/加载参考指南 - 保存到
./diagrams/<markdown_file>_<num>_<type>_<title>.mmd - 验证：
mmdc -i file.mmd -o file.png -b transparent - 出错时： 在
references/guides/troubleshooting.md中搜索匹配的错误 - 如果未找到： 按上述优先级使用搜索工具
- 添加引用：
模式 6：弹性图表生成
用户： "创建一个时序图并将其添加到设计文档"
技能操作：
- 识别意图：图表生成 + markdown 集成
- 加载工作流指南：
references/guides/resilient-workflow.md - 识别图表类型：时序图
- 加载图表指南：
references/guides/diagrams/sequence-diagrams.md - 使用模板生成 Mermaid 代码
- 执行弹性工作流：
python scripts/resilient_diagram.py \ --code "[生成的代码]" \ --markdown-file design_doc \ --diagram-num 1 \ --title "api_sequence" \ --json - 如果验证失败 → 应用故障排除修复 → 重试
- 成功后 → 将
添加到 markdown
Unicode 语义符号
始终使用 Unicode 符号来增强图表清晰度。常见模式：
基础设施与部署
graph TB
Client[👤 用户] --> LB[🌐 负载均衡器]
LB --> App1[⚙️ 应用服务器 1]
LB --> App2[⚙️ 应用服务器 2]
App1 --> DB[(💾 数据库)]
App1 --> Cache[(⚡ Redis)]
带状态的活动流
flowchart TD
Start([🚀 开始]) --> Process[⚙️ 处理数据]
Process --> Check{✓ 有效？}
Check -->|是| Save[💾 保存]
Check -->|否| Error[❌ 错误]
Save --> Complete([✅ 完成])
微服务架构
graph TB
API[🌐 API 网关] --> Auth[🔐 认证服务]
API --> Orders[📋 订单服务]
Orders --> Queue[📬 消息队列]
Queue --> Worker[⚙️ 后台工作者]
Worker --> Storage[📦 对象存储]
完整符号参考，请加载： references/guides/unicode-symbols/guide.md
Python 工具
提取 Mermaid 图表
# 列出所有图表
python scripts/extract_mermaid.py document.md --list-only
# 提取到单独文件
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_
…
[翻译内容已截断]