Mermaid 图表

使用 Mermaid 的纯文本语法创建专业的软件图表。Mermaid 通过简洁的文本定义渲染图表，使图表具备版本可追踪性、易于更新，并能与代码一同维护。

安装

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install mermaid-diagrams

核心语法

所有 Mermaid 图表均遵循以下结构：

diagramType
  definition content

关键原则：

• 首行声明图表类型（例如：classDiagram、sequenceDiagram、flowchart）
• 使用 %% 添加注释
• 换行与缩进有助于提升可读性，但非必需
• 未识别的单词会导致图表解析失败；无效参数将静默忽略

图表类型选择

关于样式、主题及布局选项：参见 references/advanced-features.md

快速上手示例

类图（领域模型）

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（数据库 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
    }

最佳实践

1. 从简单开始 — 先绘制核心实体或组件，再逐步补充细节
2. 使用有意义的名称 — 清晰的标签让图表具备自解释性
3. 充分添加注释 — 使用 %% 注释说明复杂关系或设计意图
4. 聚焦单一概念 — 每张图表只表达一个核心概念；大型图表应拆分为多个视角
5. 纳入版本控制 — 将 .mmd 文件与源码一同提交，便于协同更新
6. 提供上下文 — 添加标题和说明文字，明确图表用途与范围
7. 持续迭代 — 随着理解深入不断优化图表内容

配置与主题

可通过 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 支持

导出方式：

• Mermaid Live Editor —— 在线编辑器，支持 PNG/SVG 导出
• Mermaid CLI —— npm install -g @mermaid-js/mermaid-cli 后执行 mmdc -i input.mmd -o output.png

何时创建图表

务必在以下场景中绘制图表：

• 启动新项目或新功能时
• 记录复杂系统行为或结构时
• 阐述架构决策依据时
• 设计数据库 Schema 时
• 规划重构工作时
• 为新团队成员进行入职培训时

善用图表达成以下目标：

• 对齐各相关方对关键技术决策的理解
• 协作式地共同构建并维护领域模型
• 可视化数据流向与系统间交互关系
• 编码前先行设计与验证方案
• 构建随代码演进而同步更新的“活文档”

常见陷阱

• 非法字符 —— 避免在注释中使用 {}；特殊字符需转义
• 语法错误 —— 拼写错误将导致图表无法渲染；建议在 Mermaid Live Editor 中实时校验
• 过度复杂 —— 复杂图表应拆解为多个聚焦明确的子图
• 遗漏关键关系 —— 必须体现所有重要实体间的关联
• 图表过时 —— 错误的图表比无图表更危险；系统变更后必须同步更新

绝对禁止事项

1. 禁止创建节点数超过 15 个的图表 —— 此类图表难以阅读；应拆分为多个聚焦明确的子图
2. 禁止使用无标签的连接线/箭头 —— 每条连线都应注明其代表的关系或数据流向
3. 禁止创建无标题或无说明文字的图表 —— 缺乏上下文的图表仅对作者本人有意义
4. 禁止将图表作为唯一文档形式 —— 必须搭配文字说明，阐释设计背后的“为什么”
5. 禁止放任图表过时 —— 架构变更后必须及时更新图表；过时图表会产生误导
6. 禁止使用 Mermaid 进行业务数据可视化 —— Mermaid 专用于架构图与流程图，不适用于商业数据图表（如柱状图、折线图等）