mermaid-gen

mermaid-gen

用途

mermaid-gen 技能为 AI 助手提供专业指导，帮助创建语法正确的 Mermaid 图表，同时避免导致渲染失败的常见解析错误。此技能侧重于图表语法的正确性和最佳实践。

主要优势：

• 预防错误：避免嵌套引号、特殊字符问题和语法错误
• 掌握语法：为流程图、时序图、状态机等应用正确模式
• 质量保障：使用经过验证的模板，在渲染前验证图表
• 故障排查：系统地诊断并修复解析错误
• 最佳实践：遵循标准化的命名、样式和结构规范

何时使用此技能

在以下情况下使用 mermaid-gen：

• 创建新的 Mermaid 图表（流程图、时序图、状态机等）
• 修复现有图表中的解析错误或渲染问题
• 将文字描述转换为 Mermaid 语法
• 在提交文档前验证图表语法
• 调试“Expecting X, got Y”解析错误
• 将其他格式的图表迁移到 Mermaid
• 需要有关节点命名、样式和子图的最佳实践指导

在以下情况下不要使用 mermaid-gen：

• 创建简单表格或纯文本列表（请使用 Markdown 表格）
• 需要管理图表文件或生成 SVG（请改用 charts-flow 技能）
• 创建数据可视化图表（柱状图、饼图、折线图——请使用图表库）
• 需要甘特图或 Git 图（不属于核心范围）
• 图表已经完美运行（无需更改）

与 charts-flow 技能的关系：

• charts-flow：管理图表文件、生成 SVG 并将其嵌入文档
• mermaid-gen：确保图表在创建文件前语法正确
• 配合使用：charts-flow 技能会调用 mermaid-gen 来生成图表

技能输入

必需输入

输入	描述	示例
图表类型	Mermaid 图表的类型	flowchart、sequence、state、class
图表用途	图表所表示的内容	“Agent 通信流程”、“状态机转换”
内容描述	关键元素及其关系	“3 个 Agent、1 个数据库、请求/响应流程”

可选输入

输入	描述	默认值
现有代码	当前的 Mermaid 代码（如需修复）	无（创建新图表）
错误消息	渲染器返回的解析错误	无
样式偏好	配色方案、布局方向	项目默认值
命名规范	节点 ID 格式	camelCase

技能工作流

遵循以下 5 个步骤来创建或修复 Mermaid 图表：

第 1 步：了解需求

• 确认图表类型（流程图、时序图、状态图、类图等）
• 列出需要呈现的所有节点/实体
• 确定关系和连接
• 确定流程方向（TD、LR 等）
• 记录是否需要分组（子图）

第 2 步：规划节点结构

• 创建有意义的节点 ID（使用 camelCase，不含空格）
• 让显示标签简洁明了
• 标识决策点（菱形）
• 规划数据库/存储节点（圆柱形）
• 确定哪些节点需要特殊形状

第 3 步：应用语法规则（关键）

• 从所有节点标签中移除嵌套引号
• 将多行标签（含 <br/>）用双引号括起来
• 让边标签保持简单——除非必要，否则不要加引号
• 对含特殊字符的子图使用 ID/标签语法
• 将节点 ID 与标签分开：NodeID[Display Label]

第 4 步：使用模板构建图表

• 从适当的模板开始（流程图、时序图、状态图）
• 使用正确的语法添加节点
• 使用适当的箭头类型定义关系/边
• 将相关节点分组到子图中（如有需要）
• 在定义完所有节点后再添加样式指令
• 为复杂部分添加注释（%%）

第 5 步：验证和测试

• 检查所有标签中是否有嵌套引号
• 验证子图 ID 是否与样式引用一致
• 确认所有节点 ID 都是唯一的
• 在 Mermaid Live Editor（https://mermaid.live）中测试
• 验证所有关系是否正确解析
• 确保渲染成功且无错误

错误恢复：如果出现解析错误，请参阅下方的“故障排除指南”部分。

常见 Mermaid 语法错误及解决方案

1. 节点标签中的引号

❌ 错误 - 嵌套引号会导致解析错误：

User[User: "What is the status?"] --> System
Response["Message: "Success""] --> User

✅ 正确 - 删除内部引号或正确转义：

User[User: What is the status?] --> System
Response["Message: Success"] --> User

**规则：**用 [] 或 () 括起的节点标签中，绝不要使用嵌套引号。可以：

• 完全删除内部引号
• 如果使用 <br/> 标签，则用双引号括起整个标签

2. 含特殊字符的多行节点

❌ 错误 - 不带引号的十进制数和特殊字符：

Results[Top Results:<br/>1. system_arch.md (0.89)<br/>2. safety.yaml (0.84)]

✅ 正确 - 使用数字/十进制数和 <br/> 时，用双引号括起标签：

Results["Top Results:<br/>1. system_arch.md (0.89)<br/>2. safety.yaml (0.84)"]

**规则：**节点标签包含以下内容时：

• <br/> 标签和十进制数
• <br/> 标签和特殊字符
• 包含复杂内容的多行文本

请用双引号括起整个标签：NodeID["label content"]

3. 边标签中的引号

❌ 错误 - 边标签中含有引号：

A -->|"Execute"| B
A -->|"Cancel" or Timeout| C

✅ 正确 - 删除边标签中的引号：

A -->|Execute| B
A -->|Cancel or Timeout| C

**规则：**边标签（|...| 之间的文本）中绝不要包含引号，除非确有必要。请使用纯文本。

4. 样式指令中含特殊字符的子图名称

❌ 错误 - 样式引用中含有与号和特殊字符：

subgraph "Audit & Compliance"
    Node1
end
style Audit & Compliance fill:#fff

✅ 正确 - 对子图使用 ID/标签语法：

subgraph AuditCompliance["Audit & Compliance"]
    Node1
end
style AuditCompliance fill:#fff

**规则：**为含有特殊字符的子图应用样式时：

1. 为子图指定不含特殊字符的 ID：subgraph ID["Display Name"]
2. 在样式指令中引用该 ID：style ID fill:#color

5. 节点 ID 与显示标签

✅ 正确 - 将 ID 与标签分开：

UserNode[User: Query the system] --> ProcessNode[Processing Service]
ProcessNode --> DBNode[(Database)]

规则：

• 第一部分（[ 之前）是节点 ID（不含空格，使用 camelCase）
• [] 中的内容是显示标签（可以包含空格；加引号时也可以包含特殊字符）

Mermaid 图表模板

流程图模板（架构图）

flowchart TD
    %% Define nodes with clear IDs and labels
    User[User Input] -->|Action| Service[Processing Service<br/>FastAPI]

    Service -->|Validate| Validator{Validation Check}
    Validator -->|Invalid| ErrorNode["Error Response<br/>Status: 400"]
    Validator -->|Valid| Database[(Database<br/>PostgreSQL)]

    Database -->|Query Result| Transform[Transform Data]
    Transform -->|Response| User

    %% Group related components
    subgraph Backend["Backend Services"]
        Service
        Validator
        Transform
    end

    subgraph Storage["Data Storage"]
        Database
    end

    %% Apply styles AFTER all nodes defined
    style User fill:#e1f5ff
    style Backend fill:#f0f0f0
    style Storage fill:#fff4e1

时序图模板

sequenceDiagram
    participant User
    participant API as API Gateway
    participant Auth as Auth Service
    participant DB as Database

    User->>API: Request with credentials
    API->>Auth: Validate token
    Auth-->>API: Token valid
    API->>DB: Query data
    DB-->>API: Return results
    API-->>User: Success response

    Note over User,DB: All communication encrypted via TLS

状态图模板

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: Start request
    Processing --> Success: Complete
    Processing --> Failed: Error occurs
    Success --> [*]
    Failed --> Retry: Auto retry
    Retry --> Processing: Attempt again
    Failed --> [*]: Max retries exceeded

质量门禁（完成定义）

语法验证门禁

• 无嵌套引号：已检查所有节点标签，确保不存在嵌套引号问题
• 多行语法：用 <br/> 的标签已用双引号括起
• 边标签简洁：边标签（|...| 之间）中没有不必要的引号
• 子图 ID 有效：含特殊字符的子图使用 ID/标签语法
• 节点 ID 唯一：图表中没有重复的节点 ID
• 节点 ID 格式：所有 ID 均使用不含空格的 camelCase

结构验证门禁

• 图表可渲染：可在 Mermaid Live Editor 中成功渲染
• 所有关系均可解析：没有失效的节点引用
• 流程方向正确：根据需要指定 TD、LR、RL、BT
• 子图组织有序：按逻辑对相关节点进行分组
• 已应用样式：在定义所有节点后添加样式指令

质量保证门禁

• 标签简洁：显示标签描述清晰但不冗长
• 已添加注释：用 %% 注释说明复杂部分
• 图表类型适当：使用正确的类型（流程图、时序图或状态图）
• 视觉清晰：图表易于阅读和理解
• 集成文档：嵌入文档时已添加标题/说明文字

提交前验证

• 解析错误：渲染器中没有解析错误
• 跨浏览器：在 GitHub、VS Code 和文档站点中均可正确渲染
• 文件大小：图表复杂度合理（不过于复杂）
• 符合标准：遵循项目图表命名规范

技能限制

不要做的事

• 不要在任何节点标签中使用嵌套引号（会导致解析错误）
• 不要在边标签中使用引号，除非绝对必要
• 不要在子图 ID 中使用特殊字符，除非使用 ID/标签语法
• 不要在样式指令中引用子图显示名称（请使用 ID）
• 不要在定义所有节点之前添加样式指令
• 不要在标签中使用字面换行符（请改用 <br/> 标签）
• 不要创建过于复杂的图（超过 50 个节点时请拆分）
• 不要使用通用节点 ID，如 node1、node2（请使用描述性 ID）
• 不要跳过提交前在 Mermaid Live Editor 中进行验证
• 不要使用已弃用的 Mermaid 语法（请检查版本兼容性）

图表类型限制

• 不要将 Mermaid 用于：
  • 数据可视化图表（柱状图、饼图、折线图——请使用图表库）
  • 项目管理甘特图（请使用专用项目管理工具）
  • Git 图（请使用 Git 可视化工具）
  • 带照片的组织结构图（请使用组织结构图工具）
  • 复杂数据表（请使用 Markdown 表格）

文件组织规则

• 始终在创建图表文件前验证语法
• 始终以模板作为图表类型的起点
• 始终在嵌入前于 Mermaid Live Editor 中进行测试
• 始终在文件名或文档中注明图表类型
• 始终遵循项目的节点 ID 命名规范

示例用法

示例 1：创建新流程图

用户请求：

“创建一个流程图，展示身份验证流程：用户提交凭据，系统进行验证、检查数据库，并返回令牌或错误”

技能操作：

1. 识别类型：流程图（带有决策的流程）
2. 规划节点：用户、验证器、数据库、TokenService、错误、成功
3. 规划流程：用户 → 验证 → 决策 → 数据库或错误 → 成功或错误
4. 应用语法规则：
   • 节点 ID：userInput、validator、dbCheck、tokenService、errorResponse、successResponse
   • 移除所有标签中的嵌套引号
   • 使用菱形表示验证检查决策
5. 基于模板构建：使用流程图模板
6. 验证：在 Mermaid Live Editor 中测试

结果：

flowchart TD
    userInput[User: Submit Credentials] -->|POST /auth| validator{Validate Format}
    validator -->|Invalid| errorResponse["Error Response<br/>Status: 400"]
    validator -->|Valid| dbCheck[(Database<br/>Verify User)]
    dbCheck -->|Not Found| errorResponse
    dbCheck -->|Found| tokenService[Generate JWT Token]
    tokenService -->|Return| successResponse["Success Response<br/>Token + Expiry"]

示例 2：修复解析错误

用户请求：

“我的时序图无法渲染。错误：‘Expecting SQE, got STR’。代码如下：User->>API: Request "data"”

技能操作：

1. 诊断错误：“Expecting SQE, got STR” = 嵌套引号问题
2. 定位问题：边标签中有嵌套引号：Request "data"
3. 应用修复：移除内部引号：Request data
4. 验证：在 Mermaid Live Editor 中测试修正后的语法
5. 返回修复后的代码

结果：

sequenceDiagram
    User->>API: Request data
    API-->>User: Response

说明：|...| 之间或 : 后面的边标签不应包含引号。

示例 3：创建带复杂标签的状态机

用户请求：

“为订单处理创建一个状态图：Draft → Submitted → Processing → Completed 或 Failed。请包含转换条件。”

技能操作：

1. 识别类型：状态图（状态转换）
2. 规划状态：Draft、Submitted、Processing、Completed、Failed
3. 规划转换：添加带标签的条件
4. 应用语法规则：
   • 使用 stateDiagram-v2 语法
   • 状态 ID：Draft、Submitted、Processing、Completed、Failed
   • 转换标签中包含条件（不加引号）
5. 基于模板构建：使用状态图模板
6. 验证：在 Mermaid Live Editor 中测试

结果：

stateDiagram-v2
    [*] --> Draft
    Draft --> Submitted: User clicks Submit
    Submitted --> Processing: Payment verified
    Processing --> Completed: All items shipped
    Processing --> Failed: Payment declined
    Completed --> [*]
    Failed --> Draft: Retry allowed
    Failed --> [*]: Max retries exceeded

常见模式

决策流程模式

flowchart TD
    Input[Receive Input] --> Validate{Validate Input}
    Validate -->|Invalid| Reject["Reject with Error<br/>Return 400"]
    Validate -->|Valid| Process[Process Request]
    Process --> Output[Return Success]

多源集成模式

flowchart TD
    User[User Query] --> Router{Query Router}

    Router -->|Database| SQL[SQL Connector]
    Router -->|Cache| Redis[Redis Connector]
    Router -->|API| External[External API]

    SQL --> Merge[Merge Results]
    Redis --> Merge
    External --> Merge

    Merge --> Response[Formatted Response]
    Response --> User

错误处理模式

flowchart TD
    Start[Start Process] --> Try{Execute}
    Try -->|Success| Complete[Complete Successfully]
    Try -->|Error| Retry{Retry Count < 3?}
    Retry -->|Yes| Wait[Exponential Backoff]
    Wait --> Try
    Retry -->|No| Failed["Failed<br/>Log and Alert"]

故障排除指南

错误：“Expecting 'SQE', got 'STR'”

• **原因：**节点标签中有嵌套引号
• **修复：**移除内部引号，或将整个标签用引号括起来

错误：“Expecting 'SPACE', got 'AMP'”

• 原因： 样式指令中包含特殊字符（&、/ 等）
• 修复： 使用子图 ID/标签语法：subgraph ID["Name"]

错误：“Parse error on line X”

• 原因： 通常与引号相关或语法格式错误
• 修复： 检查嵌套引号，并确认节点/边语法无误

图表未渲染

• 原因： 节点 ID 无效、引用失效或语法错误
• 修复： 在 Mermaid Live Editor 中验证，并检查节点 ID 是否一致

实际文档示例

架构流程（ADR 模式）

flowchart TD
    User[User: Submit command] -->|1. Classify| Detector{Command Detector<br/>GPT-4 + Rules}

    Detector -->|Query| QueryPath[Execute Immediately]
    Detector -->|Command| SafetyPath[Safety Validation]

    SafetyPath -->|Check| Circuit{Circuit Breaker Status}
    Circuit -->|Active| Block["Block Command<br/>Display Reason"]
    Circuit -->|Inactive| Execute[Execute Command]

    Execute -->|Log| Audit[WORM Audit Storage]
    Execute -->|Response| User

    subgraph SafetyControls["Safety Controls"]
        Detector
        Circuit
        Audit
    end

    style User fill:#e1f5ff
    style SafetyControls fill:#fff4e1

数据管道流程

flowchart LR
    Source[Data Source] -->|Ingest| Process[Processing Pipeline]

    Process -->|Transform| Transform[Transform Layer<br/>Validate & Clean]
    Transform -->|Load| Storage[(Data Warehouse)]

    Storage -->|Query| Analytics[Analytics Service]
    Analytics -->|Visualize| Dashboard[Dashboard UI]

    subgraph Pipeline["Data Pipeline"]
        Process
        Transform
    end

    style Pipeline fill:#f0f0f0

快速参考卡

元素	语法	示例
节点（矩形）	ID[Label]	Node1[Process Data]
节点（圆角）	ID(Label)	Start(Begin Process)
节点（数据库）	ID[(Label)]	DB[(PostgreSQL)]
节点（圆形）	ID((Label))	Point((A))
决策	ID{Label}	Check{Is Valid?}
箭头	-->	A --> B
带标签的箭头	-- text --> 或 `-->	text
子图	subgraph ID["Label"]	subgraph Sys["System"]
样式	style ID fill:#color	style Node1 fill:#e1f5ff
注释	%% comment	%% 这是一条备注
换行符	标签中的 <br/>	Node["Line 1<br/>Line 2"]

输出格式

生成的产物

使用 mermaid-gen skill 时，主要输出为：

Mermaid 图表代码块：

• 格式：语言标识符为 mermaid 的 Markdown 代码块
• 内容：语法有效的 Mermaid 图表代码
• 验证：交付前已在 Mermaid Live Editor 中测试
• 结构：包含注释、样式以及规范的节点/边语法

输出示例：

```mermaid
flowchart TD
    %% Define nodes
    Start[Start Process] --> Process[Execute Task]
    Process --> End[Complete]

    %% Apply styling
    style Start fill:#e1f5ff
    style End fill:#c8e6c9
```

与 charts-flow Skill 集成

Skill 关系：

• mermaid-gen：创建语法正确的图表代码
• charts-flow：接收图表代码，并管理文件创建、SVG 生成和文档嵌入

典型工作流：

1. 用户请求为文档创建图表
2. 调用 charts-flow skill 管理文件
3. charts-flow 在内部调用 mermaid-gen 生成图表
4. mermaid-gen 返回经过验证的 Mermaid 代码
5. charts-flow 创建图表文件、生成 SVG，并嵌入父文档

单独使用： 当用户只需要图表代码（不需要文件管理）时：

• 直接调用 mermaid-gen
• 返回图表代码块
• 用户手动将其嵌入文档

组合使用： 当用户需要完整的图表文件工作流时：

• 调用 charts-flow skill（其内部会使用 mermaid-gen）
• 返回图表文件 + SVG + 父文档更新

输出验证清单

mermaid-gen 的每项输出都必须符合以下标准：

• ✅ 在 Mermaid Live Editor 中渲染无误
• ✅ 所有标签中均无嵌套引号
• ✅ 子图 ID 与样式引用相匹配
• ✅ 所有节点 ID 均唯一
• ✅ 注释能解释复杂部分
• ✅ 遵循项目命名规范

与项目工作流集成

与其他 Skills 的关系

charts-flow Skill：

• 用途：图表文件管理、SVG 生成和文档嵌入
• 集成：调用 mermaid-gen 生成图表内容
• 使用场景：在 diagrams/ 子目录中创建独立的图表文件

doc-flow Skill：

• 用途：规范驱动开发工作流（BRD → PRD → ADR → SYS → SPEC）
• 集成：使用 mermaid-gen 创建的图表可用于 ADR、SYS 文档和架构规范
• 使用场景：向 ADR 文档或系统规范中添加架构图

project-mngt Skill：

• 用途：MVP/MMP/MMR 实施规划
• 集成：用图表展示项目依赖关系和实施流程
• 使用场景：创建甘特式时间线或依赖关系图（如果 Mermaid 支持）

文档标准对齐

技术指南（依据 CLAUDE.md）：

• 聚焦技术实现（而非营销语言）
• 考虑成本优化（采用轻量级 SVG 格式）
• 注重性能（将图表文件分开，以加快渲染速度）
• 考虑安全性（图表中不包含可执行代码）

最佳实践整合：

• 使用 mermaid-gen 确保语法正确
• 使用 charts-flow 管理文件并优化性能
• 遵循项目的节点 ID 命名约定
• 在提交到版本控制前验证所有图表

版本

• 版本： 1.0
• 最后更新： 2025-11-05
• 经验总结来源： ADR Architecture Flow 图表修复

相关文档

• Mermaid 官方文档
• Mermaid 在线编辑器
• GitHub Mermaid 支持