AI 知识库

mermaid-diagrams

6分钟阅读

mermaid-diagrams

TraeWork 内置 skill —— 用 Mermaid 文本语法创建专业软件图表。类图、时序图、流程图、ERD、C4、状态图、Git Graph、甘特图等。Mermaid 渲染文本 → 图，图表可版本控制。

一、定位

字段值
所属TraeWork 内置 skill（图表工具）
触发条件用户要求画图、可视化、建模、map out
核心方法文本语法 → 渲染成图
关键优势图表和代码一起版本控制

二、9 种图表类型选择

类型用途
Class Diagram（类图）领域建模、OOP 设计、实体关系
Sequence Diagram（时序图）API 请求/响应、用户认证、系统组件交互
Flowchart（流程图）用户旅程、业务流程、算法逻辑、部署流水线
ERD（实体关系图）数据库 schema、数据建模
C4 Diagram软件架构（系统 / 容器 / 组件 / 代码）
State Diagram（状态图）状态机、生命周期
Git Graph版本控制分支策略
Gantt Chart项目时间线、调度
Pie/Bar Chart数据可视化

三、核心语法结构

关键原则：

  • 第一行声明图表类型（如 classDiagram、sequenceDiagram、flowchart）
  • %% 是注释
  • 缩进和换行提升可读性，但不是必须
  • 未知单词会破坏图表；参数错误会静默失败

四、4 种图表示例

4.1 Class Diagram（领域模型）

classDiagram
    Title -- Genre
    Title *-- Season
    Title *-- Review
    User --> Review : creates
 
    class Title {
        +string name
        +int releaseYear
        +play()
    }
 
    class Genre {
        +string name
        +getTopTitles()
    }

4.2 Sequence Diagram（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

4.3 Flowchart（用户旅程）

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

4.4 ERD（数据库 Schema）

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
    }

五、6 个最佳实践

  1. 从简单开始 — 从核心实体/组件开始，逐步增加细节
  2. 用有意义的命名 — 清晰的标签让图表自解释
  3. 大量注释 — 用 %% 解释复杂关系
  4. 保持聚焦 — 一个图一个概念；大图拆成多个聚焦视图
  5. 版本控制 — .mmd 文件和代码一起存
  6. 加上下文 — 标题和说明解释图表用途
  7. 迭代 — 随理解深入优化图表

六、配置和主题

---
config:
  theme: base
  themeVariables:
    primaryColor: "#ff6b6b"
---
flowchart LR
    A --> B

可用主题：default、forest、dark、neutral、base

布局选项：

  • dagre（默认）：经典平衡布局
  • elk：复杂图高级布局

外观选项：

  • classic：传统 Mermaid 风格
  • 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

八、5 个常见陷阱

  • 破坏字符：注释中避免 {}，特殊字符用转义
  • 语法错误：拼写错误破坏图表；在 Mermaid Live 中验证
  • 过于复杂：拆成多个聚焦图
  • 缺少关系：文档化所有重要连接
  • 过度节点：核心概念就够，不要把所有字段都画上

九、什么时候画图

永远画图当：

  • 启动新项目或功能
  • 文档化复杂系统
  • 解释架构决策
  • 设计数据库 schema
  • 计划重构工作
  • 新人入职

画图目的：

  • 让 stakeholder 在技术决策上对齐
  • 协作文档化领域模型
  • 可视化数据流和系统交互
  • 编码前规划
  • 创建活的文档

十、深度参考

仓库的 references/ 文件夹：

  • class-diagrams.md：领域建模、关系（关联、组合、聚合、继承）、多重性、方法/属性
  • sequence-diagrams.md：actor、参与者、消息（同步/异步）、激活、循环、alt/opt/par 块、注释
  • flowcharts.md：节点形状、连接、决策逻辑、子图、样式
  • erd-diagrams.md：实体、关系、基数、键、属性
  • c4-diagrams.md：系统上下文、容器、组件图、边界
  • advanced-features.md：主题、样式、配置、布局选项

十一、引用来源

十二、一句话总结

mermaid-diagrams 是「用文本语法画专业图表」的技能——类图、时序图、流程图、ERD、C4 等 9 种类型，图表和代码一起版本控制。从简单开始、按场景选类型、注释清晰、命名有意义。

反向链接