mermaid-diagrams

Mermaid：编写和渲染图表

概述

创建并验证 Mermaid 图表。Mermaid 是一种文本转图表语言：Markdown 中的围栏代码块 ```mermaid 可由 GitHub（以及大多数其他托管平台）原生渲染，因此图表以文本形式提交，而不是图片。唯一会生成图片的环节是本地验证——使用 mmdc 将代码块渲染为 SVG/PNG，以便在推送前确认语法有效且易于阅读。

已使用 @mermaid-js/mermaid-cli（mmdc）v12.0.0 和无头 Chromium 154 进行验证。近期版本中的标志保持稳定，但如果命令行为异常，请运行 mmdc --help。

关键要点：难点不在 Mermaid 语法，而在于如何在容器中运行无头 Chromium。mmdc 会驱动真正的 Chromium 浏览器来栅格化图表。Chromium 沙箱需要用户命名空间，但非 root 容器用户无法使用该命名空间，因此直接运行 mmdc 会启动失败。必须使用 --no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage Puppeteer 配置。docker-opencode 镜像内置了该配置，并提供了会自动应用该配置的 mermaid-render 包装命令。

适用与不适用场景

• 适用：创建、编辑或验证任何 ```mermaid 代码块，或需要在 Markdown 中绘制架构图、流程图、时序图、状态图或 ER 图时。
• 不适用：交付物是独立图片文件、团队使用专用工具管理的 C4 模型，或需要精确手动布局的图表时（Mermaid 会自动布局；此时应改用专用绘图工具）。
• 优先使用 Mermaid，而不是提交 PNG/SVG 图片：它支持差异比较，便于审查，而且可以在托管平台上免费重新渲染。

前提条件

• PATH 中有 mmdc——@mermaid-js/mermaid-cli（已内置于 docker-opencode 镜像中；否则运行 npm install -g @mermaid-js/mermaid-cli）。
• 无沙箱 Puppeteer 配置（在镜像中的 ~/.config/mermaid/puppeteer.json 处预置）：

  {"args":["--no-sandbox","--disable-setuid-sandbox","--disable-dev-shm-usage"]}
  

• mermaid-render 包装命令（已添加到镜像的 PATH 中）——它会封装 mmdc -p <config>，因此无需重复指定标志。

渲染与验证工作流

mmdc 接受的是文件，不是围栏代码块——因此需要将每个 ```mermaid 代码块提取到临时 .mmd 文件中，进行渲染并检查输出。此循环适用于任意数量的图表（已使用真实的多图表 architecture.md 验证）：

1. 在 Markdown 文件中编写代码块（使用 mermaid 围栏）。
2. 将文件中的每个 Mermaid 代码块拆分到 /tmp/d-<n>.mmd：

   awk '
     /^```mermaid[[:space:]]*$/ { n++; inblk=1; next }
     /^```[[:space:]]*$/        { inblk=0 }
     inblk                       { print > ("/tmp/d-" n ".mmd") }
   ' FILE
   

3. 逐个渲染并检查输出文件是否非空：

   for f in /tmp/d-*.mmd; do
     if mermaid-render "$f" && [ -s "${f%.mmd}.svg" ]; then
       echo "OK:   $f"
     else
       echo "FAIL: $f"
     fi
   done
   

   只有一个图表？只需运行 mermaid-render /tmp/d-1.mmd。若要不使用包装命令直接渲染： mmdc -i /tmp/d-1.mmd -o /tmp/d-1.svg -p ~/.config/mermaid/puppeteer.json。PNG：mermaid-render -i /tmp/d-1.mmd -o /tmp/d-1.png。
4. 验证：仅当代码块渲染成功（退出码为 0）且生成了非空文件时，才算有效。解析错误会输出到 stderr，且不会生成输出或只生成空文件——将任何 FAIL 视为“代码块有问题”，打开 SVG 并修复。
5. 逐步迭代，直到每个代码块都显示为 OK，然后推送。请覆盖临时文件，而不要使用 rm（可能会被阻止）：echo "" > /tmp/d-*.mmd。

选择图表类型

需求	Mermaid 类型
组件及其交互方式、请求 / 数据路径、控制平面	flowchart TD（或 LR）
按时间顺序展示具名参与者之间的消息交换	sequenceDiagram
状态及其转换	stateDiagram-v2
类 / 对象关系	classDiagram
数据模型 / 表	erDiagram
系统上下文 / C4 第 1 层	C4Context（通过 c4-mermaid include），或带标签的 flowchart
路线图 / 日程安排	gantt
比例	pie

对于高层次的“系统地图及各部分如何通信”（即 architecture.md 的使用场景），通常适合使用 flowchart TD 或 flowchart LR，并使用 subgraph 按层对组件分组（边缘 / 数据平面 / 控制平面 / 存储），再为边标注交互内容（-->|"SQL"|）。

命令参考

命令	用途
mermaid-render file.mmd	渲染为 file.svg（包装器；自动启用 no-sandbox 配置）
mermaid-render -i in.mmd -o out.svg	显式指定输入 / 输出
mermaid-render -i in.mmd -o out.png	输出栅格图像
mermaid-render -i in.mmd -o out.svg -b transparent -s 2	透明背景，2× 缩放
mmdc -i in.mmd -o out.svg -p ~/.config/mermaid/puppeteer.json	直接调用，不使用包装器（必须提供配置标志）
mmdc --help	完整标志参考

常用的 mmdc 标志：-i/--input、-o/--output、-b/--backgroundColor（white / transparent）、-s/--scale、-w/--width、-p/--puppeteerConfigFile、-f/--find（仅渲染指定 ID 的图表）。

编写时的注意事项

1. 包含特殊字符的节点标签要加引号。 任何包含 ()、{}、[]、#、引号或超出简单情况的标签，都应使用双引号括起来：A["VTGate (edge)"]。未加引号的特殊字符会导致解析失败。
2. 标签内换行使用 <br/>。 A["line one<br/>line two"]。未加引号的标签中直接换行会导致语法错误。
3. 有意选择节点形状。 [rect]、(round)、((circle))、[[subroutine]]、>flag]、{decision}。不要随意混用形状——形状具有含义。
4. 带空格的 subgraph 标题需要加引号——subgraph sg1["Data plane"]。
5. 边标签使用 -->|"label"| 或 -- text -->。保持简短；较长的说明应放在周围文本中，而非图表里。
6. # 是类似注释的字符。 避免在标签中直接使用 #（请使用带引号的标签或改写）。
7. 每个图表只表达一个主题。 包含 30 个节点的杂乱图表不算高层次图表。应拆分为“概览”“数据路径”“控制路径”，而不是绘制一张巨型图——这样也能让每次渲染更快、更清晰。
8. ID 必须唯一且使用 ASCII 字符。 使用简短的节点 ID（v1、vg），并将人类可读的名称放在标签中。
9. %% 表示注释——可以安全保留，渲染前会被移除。
10. C4 需要在代码块顶部添加 include。 不确定时，使用带标签的 flowchart 也能表达相同的上下文，且无需添加额外依赖。

验证

• 语法 + 渲染：mermaid-render /tmp/d.mmd && [ -s /tmp/d.svg ]——两项都必须成功。
• 可读性：打开 SVG（或渲染一张小型 PNG），确认标签清晰可读且互不重叠。图表即使成功渲染，但出现重叠，仍然不合格。
• GitHub 预览：能通过 mmdc 正常渲染的代码块也能在 GitHub 上渲染，因为 GitHub 使用相同的 mermaid 引擎。无需提交图像文件。

检查清单

• Markdown 文件中的代码块使用 ```mermaid 围栏
• 带特殊字符的节点 / 边标签均使用双引号括起
• 带空格的 subgraph 标题均使用引号括起
• 每个图表均可渲染：mermaid-render 以 0 退出，且输出文件非空
• 图表清晰易读（标签无重叠）；过于密集时应拆分
• 图表保持高层次；细节放在链接的说明文字 / 功能文件中
• 未提交 PNG/SVG——只提交文本块
• 临时 .mmd / 输出文件已覆盖（而非仅删除）