mermaid

何时使用此技能

当用户提到以下内容时，始终使用此技能：

• 绘制、创建、生成、制作或构建任何图表、图形或关系图
• 将流程、工作流、系统、架构或数据可视化
• 任何“画图”“绘图”“生成图”“创建图”请求
• 流程图、时序图、类图、状态图或任何图表类型
• 架构图、系统图或设计图
• 数据可视化、图表或关系图
• 流程、工作流或业务流程
• 项目时间线、日程安排或甘特图
• 用户旅程、思维导图或层级结构
• 数据库架构、ER 图或实体关系
• Git 分支结构或版本控制图
• 任何视觉呈现或图表内容

触发短语包括：

• “画一个图”“画流程图”“画架构图”
• “创建一个图表”“生成一个图”
• “帮我画”“给我画”“画出来”
• “用图表示”“可视化”“画个图说明”
• “流程图”“时序图”“类图”“状态图”
• “架构图”“系统图”“设计图”
• “甘特图”“思维导图”“时间线”
• “用 Mermaid”“Mermaid 画图”“Mermaid 语法”
• 提及“diagram”“chart”“graph”“flowchart”“visualization”“drawing”或“Mermaid”

重要：Mermaid 与 PlantUML 是两种不同的图表工具：

Mermaid 和 PlantUML 是用途各异的两种图表工具：

• Mermaid：一种基于 JavaScript 的图表工具，专为 Markdown 文档设计。它采用受 Markdown 启发的语法，可直接在 Markdown 渲染器（GitHub、GitLab、wiki、博客）中渲染。适用于快速绘制图表、编写 Markdown 文档和简单的可视化内容。输出格式为带有 mermaid 语言标签的围栏式 Markdown 代码块。

• PlantUML：一种通过简单的文本描述创建各种 UML 图表的组件。它侧重于 UML 标准和复杂的系统架构。适用于 UML 图、企业架构、C4 模型以及需要精确 UML 表示法的图表。输出格式为 @startuml/@enduml 块或 .puml 文件。

同时匹配 PlantUML 和 Mermaid 技能时：

• 如果用户明确提到“Mermaid”或“Markdown 图表”，使用此技能（Mermaid）
• 如果用户明确提到“PlantUML”“UML 图”或“C4 模型”，改用 PlantUML 技能
• 如果用户提到 Markdown 场景（README、wiki、GitHub/GitLab、博客），默认使用 Mermaid
• 如果用户提到 UML 标准或 .puml，默认使用 PlantUML
• 如果用户两者都提到或都没提到，始终询问用户选择：“我可以使用 Mermaid（Markdown 代码块）或 PlantUML（@startuml）创建此图表。你更喜欢哪种输出格式？”

如何使用此技能

关键：Mermaid 是一种面向 Markdown 的图表工具。当用户明确提到“Mermaid”、需要用于 Markdown 文档的图表，或希望图表能直接在 Markdown 渲染器（GitHub、GitLab、wiki、博客）中渲染时，应触发此技能。

出现以下情况时触发此技能：

• 用户说“用 Mermaid”“Mermaid 画图”或“Markdown 图”
• 用户需要用于 Markdown 文档、GitHub、GitLab、wiki 或博客的图表
• 用户想要能直接在 Markdown 渲染器中渲染的快速图表
• 用户提到适用于 Markdown 的任何图表类型：流程图、时序图、类图等
• 用户想要用 Markdown 格式的图表来可视化、表示或说明某些内容 当同时匹配到 PlantUML 和 Mermaid 时，务必询问用户选择输出格式或工具，因为它们是用途不同的两种绘图工具。

创建 Mermaid 图：

1. 根据用户的请求确定图表类型：

   • 流程图 → flowchart 或 graph
   • 时序图 → sequenceDiagram
   • 类图 → classDiagram
   • 状态图 → stateDiagram 或 stateDiagram-v2
   • 实体关系图 → erDiagram
   • 用户旅程图 → journey
   • 甘特图 → gantt
   • 饼图 → pie
   • 象限图 → quadrantChart
   • 需求图 → requirementDiagram
   • Git 图 → gitGraph
   • C4 图 → C4Context、C4Container、C4Component、C4Deployment 或 C4Dynamic
   • 思维导图 → mindmap
   • 时间线图 → timeline
   • ZenUML → zenuml
   • 桑基图 → sankey
   • XY 图 → xychart
   • 方块图 → block
   • 数据包图 → packet
   • 看板图 → kanban
   • 架构图 → architecture-beta（需要 Mermaid v11.1.0 或更高版本）
   • 雷达图 → radar-beta（需要 Mermaid v11.1.0 或更高版本）
   • 树状图 → treemap-beta（需要 Mermaid v11.1.0 或更高版本）

2. 从 examples/ 目录加载相应的示例文件：

   • examples/flowchart.md - 用于流程图和流程示意图
   • examples/sequence.md - 用于展示交互的时序图
   • examples/class.md - 用于类图和面向对象设计
   • examples/state.md - 用于状态图和状态机
   • examples/er.md - 用于实体关系图
   • examples/journey.md - 用于用户旅程图
   • examples/gantt.md - 用于甘特图和项目时间线
   • examples/pie.md - 用于饼图
   • examples/quadrant.md - 用于象限图
   • examples/requirement.md - 用于需求图
   • examples/gitgraph.md - 用于 Git 分支图
   • examples/c4.md - 用于 C4 架构图
   • examples/mindmap.md - 用于思维导图
   • examples/timeline.md - 用于时间线图
   • examples/zenuml.md - 用于 ZenUML 图
   • examples/sankey.md - 用于桑基流向图
   • examples/xychart.md - 用于 XY 图（柱状图／折线图）
   • examples/block.md - 用于方块图
   • examples/packet.md - 用于数据包图
   • examples/kanban.md - 用于看板图
   • examples/architecture.md - 用于架构图
   • examples/radar.md - 用于雷达图
   • examples/treemap.md - 用于树状图

3. 遵循该示例文件中的具体说明，包括语法、结构和最佳实践

   重要说明：

   • Beta 图表类型（architecture-beta、radar-beta、treemap-beta）需要 Mermaid v11.1.0 或更高版本
   • 如果渲染环境不支持 Beta 图表类型，请使用示例文件中提供的流程图替代方案
   • 务必查看示例文件中的版本兼容性说明和替代语法选项

4. 生成 Mermaid 代码，并用带有正确语法高亮的 Markdown 代码块包裹：

   重要：务必使用带有 mermaid 语言标签的 Markdown 代码块包裹 Mermaid 代码。这样可以确保用户复制内容时保留其格式。

   示例格式（使用实际的 Mermaid 语法，而不是占位符）：

   flowchart TD
       A[Start] --> B[Process]
       B --> C[End]
   

   输出格式要求：

   • 务必使用带有 mermaid 语言标签的三个反引号（```）
   • 切勿直接输出未用代码块标记包裹的 Mermaid 代码
   • 代码块必须完整且格式正确
   • 使用实际有效的 Mermaid 语法，不要使用 <diagram-type> 或 ...diagram content... 之类的占位符
   • 这样可以确保用户复制代码时不会丢失格式

5. 根据需要添加样式和配置：

   • 使用 %%{ init: { theme: 'base' } }%% 配置主题
   • 使用 style 指令设置节点样式
   • 使用 classDef 定义可复用的样式类

6. 验证语法：

   • 确保包含所有必需元素
   • 检查关系和连接是否定义正确
   • 验证甘特图的日期格式（YYYY-MM-DD）
   • 确认图表（饼图、象限图等）的数据格式
   • 对于 ER 图：实体名称使用下划线而非连字符（例如，使用 LINE_ITEM，而不是 LINE-ITEM）
   • 对于流程图：避免将 "end" 用作节点标签（改用 "End" 或 "END"）
   • 对于类图：使用反引号转义标签中的特殊字符
   • 检查测试版图表类型的版本兼容性

7. 将图表保存到项目目录：

   • 默认行为：生成 Mermaid 图表时，将其保存到当前项目目录
   • 推荐位置：
     • docs/diagrams/ - 用于文档图表
     • docs/ - 用于常规文档
     • diagrams/ - 用于独立图表文件
     • 当前目录（.）- 如果不存在特定的目录结构
   • 文件命名：使用描述性名称，例如 system-architecture.md、user-flow.md、database-schema.md 等
   • 文件格式：保存为 .md 文件，并在其中包含 Mermaid 代码块
   • 示例：如果用户请求系统架构图，请将其保存为 docs/diagrams/system-architecture.md 或 diagrams/system-architecture.md
   • 必要时询问：如果项目结构不明确，请询问用户希望将图表保存在哪里；但如果 docs/ 或 diagrams/ 目录不存在，默认创建其中一个

输出格式和文件保存：

生成图表时，请遵循以下回复结构：

1. 先保存文件：在项目目录中创建图表文件（例如 docs/diagrams/system-architecture.md）

2. 告知用户：告诉用户文件保存的位置

3. 显示图表：在格式正确的 Markdown 代码块中展示 Mermaid 代码，并使用 mermaid 语言标签

回复结构示例：

• 第一行："我已创建 Mermaid 图表，并将其保存到 docs/diagrams/system-architecture.md。"
• 然后在代码块中展示图表：
  • 以三重反引号 + mermaid + 换行符开头
  • 接着是 Mermaid 代码
  • 以三重反引号 + 换行符结尾

关键要求：

• Mermaid 代码块必须始终使用三重反引号（```）和 mermaid 语言标签进行正确格式化
• 绝不要在代码块标记之外输出原始 Mermaid 代码
• 代码块必须完整（包含开头和结尾的反引号）
• 这样可以确保用户复制代码时不会丢失格式
• 始终将图表文件保存到当前项目目录（默认位置：docs/diagrams/ 或 diagrams/）

如果图表类型与任何现有示例都不匹配，请参考 Mermaid 文档，或向用户询问所需可视化效果。

版本兼容性

某些图表类型有特定的版本要求：

• 测试版图表类型（需要 Mermaid v11.1.0+）：

  • architecture-beta - 架构图
  • radar-beta - 雷达图
  • treemap-beta - 矩形树图

• 高级功能（需要特定版本）：

  • 使用 JSON 配置的参与者类型：Mermaid v10.0.0+
  • 创建或销毁参与者：Mermaid v10.3.0+
  • 边 ID 和曲线样式：Mermaid v11.10.0+
  • 使用 @{} 语法的新形状：Mermaid v11.3.0+

如果不支持某种测试版图表类型，示例文件中提供了适用于所有 Mermaid 版本的流程图替代方案。

最佳实践

1. 始终使用代码块：将所有 Mermaid 代码放在带有 mermaid 语言标签的 Markdown 代码块中
2. 检查兼容性：使用测试版图表类型前，先确认版本要求
3. 使用替代方案：不支持测试版类型时，使用提供的流程图替代方案
4. 遵循命名约定：避免在节点标签中使用保留关键字和特殊字符
5. 测试语法：保存前验证图表语法，确保正确渲染
6. 整理文件：将图表保存在合适的目录中（docs/diagrams/ 或 diagrams/）
7. 使用描述性名称：为图表文件取清晰易懂的名称（例如，system-architecture.md、user-flow.md）

Mermaid 与 PlantUML——主要区别

Mermaid（本技能）：

• 用途：基于 JavaScript 的图表工具，专为 Markdown 文档设计
• 主要用例：帮助文档跟上开发进度
• 最适合：
  • Markdown 文档、GitHub、GitLab、wiki、博客
  • 可直接在 Markdown 渲染器中渲染的快速图表
  • 简单的流程图、时序图和基础图表
  • 快速原型设计和迭代
  • 用户明确要求使用 Mermaid，或需要兼容 Markdown 的图表时

PlantUML（另一种技能）：

• 用途：通过文本描述创建各种 UML 图表的组件
• 主要用例：专注于 UML 的图表绘制，强调标准 UML 表示法
• 最适合：
  • 需要精确表示法的复杂 UML 图表（类图、组件图、部署图）
  • 企业架构图和 C4 模型图
  • 需要符合标准 UML 的场景
  • 需要高级自定义、样式设置或布局控制的图表
  • 用户明确要求使用 PlantUML 或绘制 UML 图表时

同时匹配两种技能时：

• 始终询问用户如何选择：“我可以使用 Mermaid 或 PlantUML 来创建此图表。Mermaid 是一种基于 JavaScript、专为 Markdown 文档设计的工具，可直接在 GitHub/GitLab 中渲染。PlantUML 则专注于 UML 图表和企业架构。您更倾向于哪一种？”
• 这是两种用途不同的图表工具，不要自动选择其中一种
• 如果用户明确提到其中一种工具，就使用该工具
• 如果用户同时提到两种工具或都未提及，请根据用户需求询问其选择

关键词

英文关键词： mermaid, diagram, chart, graph, flowchart, flow chart, sequence diagram, class diagram, state diagram, entity relationship, ER diagram, user journey, Gantt chart, pie chart, quadrant chart, requirement diagram, Git graph, C4 diagram, mindmap, timeline, ZenUML, Sankey diagram, XY chart, block diagram, packet diagram, Kanban, architecture diagram, radar chart, treemap, draw, create, generate, make, build, visualize, visualization, drawing, plotting, mapping, schematics, blueprint, design diagram, system diagram, process flow, workflow, data visualization, visual representation

中文关键词： 流程图, 时序图, 类图, 状态图, 实体关系图, 用户旅程图, 甘特图, 饼图, 象限图, 需求图, Git图, C4图, 思维导图, 时间线图, 桑基图, XY图, 方块图, 数据包图, 看板图, 架构图, 雷达图, 树状图, 画图, 绘图, 生成图, 创建图, 制作图, 画流程图, 画架构图, 画时序图, 画类图, 画状态图, 画甘特图, 画思维导图, 画时间线, 可视化, 图表, 图形, 示意图, 设计图, 系统图, 流程图, 架构图, 时序图, 类图, 状态图, 甘特图, 思维导图, 时间线, 用图表示, 画出来, 给我画, 帮我画, 画一个, 创建一个图, 生成一个图, 画个图说明, 用图表展示, 可视化展示