SKILL.md
只读
名称
mermaid-diagrams
描述
使用Mermaid语法创建软件图的综合指南。当用户需要通过图表（包括类图（领域建模、面向对象设计）、序列图（应用流程、API交互、代码执行）、流程图（流程、算法、用户旅程）、实体关系图（数据库模式）、C4架构图（系统上下文、容器、组件）、状态图、Git图、饼图、甘特图或任何其他图表类型）来创建、可视化或记录软件时使用。触发词包括请求“图表”、“可视化”、“建模”、“绘制”、“展示流程”，或当解释系统架构、数据库设计、代码结构或用户/应用流程时。
Mermaid 图表绘制
使用 Mermaid 基于文本的语法创建专业的软件图表。Mermaid 通过简单的文本定义渲染图表，使图表可版本控制、易于更新，并能与代码一起维护。
核心语法结构
所有 Mermaid 图表遵循以下模式：
diagramType
definition content
关键原则：
- 第一行声明图表类型（例如
classDiagram、sequenceDiagram、flowchart） - 使用
%%添加注释 - 换行和缩进提高可读性，但不是必需的
- 未知单词会破坏图表；参数静默失败
图表类型选择指南
选择合适的图表类型：
-
类图 - 领域建模、面向对象设计、实体关系
- 领域驱动设计文档
- 面向对象类结构
- 实体关系与依赖
-
序列图 - 时间交互、消息流
- API 请求/响应流程
- 用户认证流程
- 系统组件交互
- 方法调用序列
-
流程图 - 流程、算法、决策树
- 用户旅程和工作流
- 业务流程
- 算法逻辑
- 部署流水线
-
实体关系图 (ERD) - 数据库模式
- 表关系
- 数据建模
- 模式设计
-
C4 图 - 多层级软件架构
- 系统上下文（系统和用户）
- 容器（应用、数据库、服务）
- 组件（内部结构）
- 代码（类/接口级别）
-
状态图 - 状态机、生命周期状态
-
Git 图 - 版本控制分支策略
-
甘特图 - 项目时间线、调度
-
饼图/柱状图 - 数据可视化
快速入门示例
类图（领域模型）
classDiagram
Title -- Genre
Title *-- Season
Title *-- Review
User --> Review : creates
class Title {
+string name
+int releaseYear
+play()
}
class Genre {
+string name
+getTopTitles()
}
序列图（API 流程）
sequenceDiagram
participant User
participant API
participant Database
User->>API: POST /login
API->>Database: Query credentials
Database-->>API: Return user data
alt Valid credentials
API-->>User: 200 OK + JWT token
else Invalid credentials
API-->>User: 401 Unauthorized
end
流程图（用户旅程）
flowchart TD
Start([User visits site]) --> Auth{Authenticated?}
Auth -->|No| Login[Show login page]
Auth -->|Yes| Dashboard[Show dashboard]
Login --> Creds[Enter credentials]
Creds --> Validate{Valid?}
Validate -->|Yes| Dashboard
Validate -->|No| Error[Show error]
Error --> Login
ERD（数据库模式）
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
PRODUCT ||--o{ LINE_ITEM : includes
USER {
int id PK
string email UK
string name
datetime created_at
}
ORDER {
int id PK
int user_id FK
decimal total
datetime created_at
}
详细参考
有关特定图表类型的深入指导，请参阅：
- references/class-diagrams.md - 领域建模、关系（关联、组合、聚合、继承）、多重性、方法/属性
- references/sequence-diagrams.md - 角色、参与者、消息（同步/异步）、激活、循环、alt/opt/par 块、注释
- references/flowcharts.md - 节点形状、连接、决策逻辑、子图、样式
- references/erd-diagrams.md - 实体、关系、基数、键、属性
- references/c4-diagrams.md - 系统上下文、容器、组件图、边界
- references/architecture-diagrams.md - 云服务、基础设施、CI/CD 部署
- references/advanced-features.md - 主题、样式、配置、布局选项
最佳实践
- 从简单开始 - 从核心实体/组件开始，逐步添加细节
- 使用有意义的名称 - 清晰的标签使图表自文档化
- 大量注释 - 使用
%%注释解释复杂关系 - 保持专注 - 每个概念一个图表；将大型图表拆分为多个聚焦视图
- 版本控制 - 将
.mmd文件与代码一起存储，便于更新 - 添加上下文 - 包含标题和注释以解释图表目的
- 迭代 - 随着理解的深入不断完善图表
配置与主题
使用 frontmatter 配置图表：
---
config:
theme: base
themeVariables:
primaryColor: "#ff6b6b"
---
flowchart LR
A --> B
可用主题： default, forest, dark, neutral, base
布局选项：
layout: dagre（默认） - 经典平衡布局layout: elk- 复杂图表的先进布局（需要集成）
外观选项：
look: classic- 传统 Mermaid 风格look: handDrawn- 手绘风格外观
导出与渲染
原生支持：
- GitHub/GitLab - 在 Markdown 中自动渲染
- VS Code - 配合 Markdown Mermaid 扩展
- Notion、Obsidian、Confluence - 内置支持
导出选项：
- Mermaid Live Editor - 在线编辑器，支持 PNG/SVG 导出
- Mermaid CLI -
npm install -g @mermaid-js/mermaid-cli然后mmdc -i input.mmd -o output.png - Docker -
docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png
常见陷阱
- 破坏性字符 - 避免在注释中使用
{}，对特殊字符使用适当的转义序列 - 语法错误 - 拼写错误会破坏图表；在 Mermaid Live 中验证语法
- 过度复杂 - 将复杂图表拆分为多个聚焦视图
- 遗漏关系 - 记录实体之间的所有重要连接
何时创建图表
在以下情况始终创建图表：
- 开始新项目或功能时
- 记录复杂系统时
- 解释架构决策时
- 设计数据库模式时
- 规划重构工作时
- 新团队成员入职时
使用图表的目的：
- 在技术决策上对齐利益相关者
- 协作记录领域模型
- 可视化数据流和系统交互
- 编码前进行规划
- 创建随代码演进的活文档
