美人鱼图表

使用美人鱼的文本语法创建专业的软件图表。美人鱼根据简单的文本定义渲染图表，使得图表能够进行版本控制，易于更新，并与代码一同维护。

安装

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install mermaid-diagrams

核心语法

所有美人鱼图表都遵循以下模式：

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（数据库架构）

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. 迭代——随着理解的深入优化图表

配置与主题

使用前置元数据配置图表：

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

可用主题：默认、森林、暗色、中性、基础

布局选项：

• 布局：dagre（默认）——经典的平衡布局
• 布局：elk——适用于复杂图表的高级布局

外观选项：

• 外观：经典——传统的Mermaid风格
• 外观：手绘——类似草图的外观

渲染与导出

原生支持于：

• GitHub/GitLab — 自动渲染Markdown格式
• VS Code — 配合Markdown Mermaid扩展插件
• Notion、Obsidian、Confluence — 内置支持

导出选项：

• Mermaid在线编辑器— 支持PNG/SVG导出的在线编辑器
• Mermaid命令行工具 —npm install -g @mermaid-js/mermaid-cli然后运行mmdc -i input.mmd -o output.png

何时创建图表

以下情况始终建议创建图表：

• 启动新项目或新功能时
• 记录复杂系统时
• 解释架构决策时
• 设计数据库结构时
• 规划重构工作时
• 新团队成员入职时

使用图表可以：

• 协调相关方对技术决策达成共识
• 协作记录领域模型
• 可视化数据流与系统交互
• 编码前先规划
• 创建随代码演进的动态文档

常见陷阱

• 破坏性字符——避免{}出现在注释中；转义特殊字符
• 语法错误——拼写错误会破坏图表；在Mermaid Live中验证
• 过度复杂——将复杂图表拆分为多个聚焦视图
• 缺失关联——记录实体间所有重要连接
• 过时图表——错误的图表比没有图表更糟；系统变更时及时更新

绝对禁止

1. 绝对禁止创建超过15个节点的图表——会导致难以阅读；拆分为多个聚焦图表
2. 绝对禁止箭头不标注说明— 每个连接都应阐明关系或数据流向
3. 切勿创建无标题或说明的图表— 脱离语境的图表在作者之外毫无用处
4. 切勿将图表作为唯一文档— 图表需配以文字说明"为何如此设计"
5. 切勿让图表过时失效— 架构变更时及时更新图表；过时图表会产生误导
6. 切勿使用Mermaid进行数据可视化— Mermaid适用于架构与流程图，而非业务数据图表