mermaid

Mermaid 图表技能

此技能提供创建精美、专业的 Mermaid 图表的指导，确保图表能在 GitHub 上正确渲染，并在浅色和深色模式下都能良好显示。

核心原则

1. 使用深色填充和浅色描边 — 确保在浅色和深色模式下都清晰易读
2. 将子图填充设为 none — 使子图能适应任意背景
3. 使用圆角形状 — ([text]) 表示体育场形状，((text)) 表示圆形
4. 不要使用 Font Awesome 图标 — GitHub 不支持 fa:fa-* 图标，它们会被渲染为文本
5. 为子图标签加引号 — 使用 subgraph Name["Label Text"] 语法
6. 在顶部定义 classDef 样式 — 将所有样式放在一起，便于维护
7. 渲染并自行检查：自动布局会自行选择连线路径，因此务必预览渲染后的图像，并反复调整，直到线条清晰易辨

渲染、检查并迭代（每次都要执行）

编写有效的 Mermaid 并非目标；真正的目标是制作出人们能够看懂的图表。Mermaid 的自动布局（dagre）会决定节点的位置和边的走向，因此源代码看起来不错的图表，渲染后可能会变成一团乱麻。务必渲染图表，从读者的角度查看，并在交付前反复调整。

1. 渲染为图像并打开查看。使用深色背景的 Mermaid-cli 可以模拟 GitHub：

   npx -y @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.png -b "#0d1117"
   

   只将 Mermaid 代码放入 diagram.mmd（仅图表代码，不要包含外围的代码围栏标记）。mermaid.live 也可以快速粘贴并预览。

2. 从读者而非作者的角度判断：

   • 起点和终点是否一目了然？
   • 能否沿着每个箭头从尾部追踪到头部，而不会在交叉处迷失？
   • 相关节点是否彼此靠近？是否有节点悬空、没有连接？

3. 如果线条缠绕在一起，就调整布局，而不只是调整颜色。以下技巧很有效：

   • 将主流程排列为泳道（使用 flowchart LR，并在每个子图内设置 direction TB），使其沿一个方向从起点读到终点。
   • 删除会形成网状结构的次要边（测试覆盖率箭头、每一个交叉引用）。展示主流程，其余内容用文字说明。
   • 将节点放在使用它们的内容旁边（数据模型紧接在构建它们的代码之后），以缩短箭头。
   • 用一条连线锚定断开的节点组，而不要任其漂移到角落（一条“稍后使用”的连线胜过一个悬空节点）。
   • 将横跨多个部分的关注点（错误、日志记录）连接到一个节点，并尽量减少连线数量。

4. 重新渲染并重复调整，直到图表易于理解。若追踪图表还需要查阅图例，就说明还没完成。

黄金法则：深色填充 + 浅色描边

兼容深色和浅色模式的关键：

classDef myStyle fill:#DARK_COLOUR,stroke:#LIGHT_COLOUR,stroke-width:2px,color:#fff

• 填充：使用较深的色调（节点背景）
• 描边：使用同一色系中较浅的色调（边框）
• 颜色：始终使用 #fff（深色背景上的白色文本）

无论页面背景是什么，这种方法都能确保节点清晰易读。

兼容 GitHub 的模板

这是适用于 GitHub 渲染的 Mermaid 图表标准模板：

flowchart TD
    %% --- COLOUR PALETTE & STYLING ---
    %% Dark fills + light strokes = readable in both light and dark mode
    classDef user fill:#374151,stroke:#d1d5db,stroke-width:2px,color:#fff
    classDef primary fill:#5b21b6,stroke:#ddd6fe,stroke-width:2px,color:#fff
    classDef secondary fill:#1e40af,stroke:#bfdbfe,stroke-width:2px,color:#fff
    classDef accent fill:#c2410c,stroke:#fed7aa,stroke-width:2px,color:#fff
    classDef success fill:#047857,stroke:#a7f3d0,stroke-width:2px,color:#fff

    %% --- NODES ---
    User((User)):::user
    User --> Action(["Performs action"]):::user

    Action --> Primary

    subgraph Primary["Primary Component"]
        direction TB
        Step1(["Step 1"]):::primary
        Step2(["Step 2"]):::primary
        Step1 --> Step2
    end

    subgraph Secondary["Secondary Component"]
        direction TB
        Process(["Process"]):::secondary
    end

    Primary --> Secondary
    Secondary --> Output(["Output"]):::success

    %% --- SUBGRAPH STYLES ---
    %% fill:none allows subgraphs to adapt to any background
    style Primary fill:none,stroke:#8b5cf6,stroke-width:2px,stroke-dasharray:5 5,color:#8b5cf6
    style Secondary fill:none,stroke:#3b82f6,stroke-width:2px,color:#3b82f6

配色示例

可选择任意颜色，只需遵循深色填充 + 浅色描边的模式：

填充（深色）	描边（浅色）	效果
#374151	#d1d5db	灰色
#5b21b6	#ddd6fe	紫色
#1e40af	#bfdbfe	蓝色
#c2410c	#fed7aa	橙色
#047857	#a7f3d0	绿色
#b91c1c	#fecaca	红色
#0f766e	#99f6e4	青绿色

这些只是示例。可根据图表选择合适的颜色，重要的是遵循这一原则。

子图语法

❌ 错误 — 会导致解析错误

subgraph MyGroup [Label With Spaces]

✅ 正确 — 为标签加引号

subgraph MyGroup["Label With Spaces"]

节点形状

❌ 错误 — 方括号显得生硬

A[Square Node]

✅ 正确 — 使用圆角形状

A(["Stadium shape"])     %% Rounded ends - use for most nodes
B((Circle))              %% Circle - use for users/actors
C{{"Decision"}}          %% Hexagon for decisions
D[(Database)]            %% Cylinder for databases/storage

子图样式

❌ 错误 — 彩色填充在深色模式下会显示异常

style MySubgraph fill:#f0f9ff,stroke:#3182ce

✅ 正确 — 透明填充可适配任意背景

style MySubgraph fill:none,stroke:#8b5cf6,stroke-width:2px,stroke-dasharray:5 5,color:#8b5cf6

要点：

• fill:none 会使背景透明
• stroke-dasharray:5 5 会创建虚线边框（可选，效果简洁）
• color:#... 会将子图标签颜色设置为与边框一致

节点标签中的换行

❌ 错误 — \n 会被渲染为字面文本

A(["First line\nSecond line"])

✅ 正确 — 使用 <br/> 创建多行标签

A(["First line<br/>Second line"])
B[("Tips File<br/>(YAML/JSON)")]
C(["Tips Engine<br/>pick + cycle"])

连线样式

A --> B              %% Solid arrow
A -.-> B             %% Dashed arrow
A -.->|Label| B      %% Dashed arrow with label
A ==> B              %% Thick arrow

完整示例

flowchart TD
    classDef user fill:#374151,stroke:#d1d5db,stroke-width:2px,color:#fff
    classDef process fill:#5b21b6,stroke:#ddd6fe,stroke-width:2px,color:#fff
    classDef decision fill:#c2410c,stroke:#fed7aa,stroke-width:2px,color:#fff
    classDef success fill:#047857,stroke:#a7f3d0,stroke-width:2px,color:#fff

    User((User)):::user
    User --> Request(["Makes request"]):::user

    Request --> Process

    subgraph Process["Processing"]
        direction TB
        Validate(["Validate input"]):::process
        Execute(["Execute logic"]):::process
        Validate --> Execute
    end

    Execute --> Check{{"Success?"}}:::decision
    Check -->|Yes| Done(["Complete"]):::success
    Check -->|No| Request

    style Process fill:none,stroke:#8b5cf6,stroke-width:2px,stroke-dasharray:5 5,color:#8b5cf6

常见错误

❌ 使用 Font Awesome 图标（GitHub 不支持）

A[fa:fa-user User]  %% Renders as literal text

❌ 浅色填充搭配深色文本

classDef bad fill:#ffffff,stroke:#000000,color:#000000  %% Invisible in dark mode

❌ 为子图填充颜色

style Sub fill:#e0f2fe  %% Looks different in light vs dark mode

❌ 子图标签含空格但未加引号

subgraph Sub [My Label]  %% Parse error!

快速参考

flowchart TD
    %% 1. Define styles: dark fill + light stroke + white text
    classDef myStyle fill:#DARK,stroke:#LIGHT,stroke-width:2px,color:#fff

    %% 2. Use rounded shapes
    Node(["Text"]):::myStyle

    %% 3. Quote subgraph labels
    subgraph Sub["My Label"]
        Inner(["Inner"])
    end

    %% 4. Style subgraphs with fill:none
    style Sub fill:none,stroke:#COLOR,stroke-width:2px,color:#COLOR

何时使用此技能

在创建以下内容时调用此技能：

• PR 的架构图
• 系统流程文档
• 数据管道可视化
• 流程图
• GitHub Markdown 中的任何图表

GitHub 特定说明

1. 不支持 Font Awesome — GitHub 的 Mermaid 渲染器不支持 fa:fa-* 图标，它们会被渲染为文本
2. 换行使用 <br/> — 多行节点标签请使用 <br/>，不要使用 \n（后者会按字面文本渲染）
3. 含空格的标签要加引号 — 使用 subgraph X["Label"]，而不是 subgraph X [Label]
4. 在本地测试 — 提交前使用 mermaid.live 预览