mermaid-diagram

Mermaid 图表生成器

根据用户需求生成高质量的 Mermaid 图表代码，并输出文件和进行验证。

常量

• OUTPUT_DIR = figures/ — 所有生成文件的输出目录
• MAX_ITERATIONS = 3 — 语法错误的最大修正轮数

工作流：必须执行所有步骤

步骤 0：预检

# Create output directory
mkdir -p figures

步骤 1：了解需求并选择图表类型

解析输入：$ARGUMENTS

1. 分析用户描述，确定最合适的图表类型
2. 阅读对应的语法参考文档（见下方步骤 2）
3. 如果图表涉及数学符号（公式、方程、希腊字母、下标、上标、分数、矩阵等），请遵循下方 图表中的数学公式 一节中的数学语法规则
4. 确定所有组件、连接和数据流
5. 规划图表结构

步骤 2：阅读文档

根据使用场景选择合适的图表类型。使用内置的 Mermaid 语法知识，或在需要时通过 context7 MCP 服务获取最新文档。

类型	使用场景
流程图	流程、决策、步骤
时序图	交互、消息传递、API 调用
类图	类结构、继承、关联
状态图	状态机、状态转换
ER 图	数据库设计、实体关系
甘特图	项目规划、时间线
饼图	比例、分布
思维导图	层级结构、知识图谱
时间线	历史事件、里程碑
Git 图	分支、合并、版本
象限图	四象限分析
需求图	需求可追溯性
C4 图	系统架构（C4 模型）
桑基图	流程、转换
XY 图	折线图、柱状图
块图	系统组件、模块
数据包图	网络协议、数据结构
看板	任务管理、工作流
架构图	系统架构
雷达图	多维度比较
矩形树图	层级数据可视化
用户旅程图	用户体验流程
ZenUML	时序图（代码风格）

配置与主题

• 主题 - 自定义颜色和样式
• 指令 - 图表级配置
• 布局 - 布局方向和间距
• 配置 - 全局设置
• 数学 - LaTeX 数学支持（见下方图表中的数学公式一节）

步骤 3：生成 Mermaid 代码并保存文件

按照参考规范生成 Mermaid 代码，然后保存两个文件：

文件 1：figures/<diagram-name>.mmd — Mermaid 源代码

.mmd 文件仅包含原始 Mermaid 代码（不含 Markdown 代码围栏）。示例：

flowchart TD
    A[Start] --> B{Condition}
    B -->|Yes| C[Execute]
    B -->|No| D[End]
    C --> D

文件 2：figures/<diagram-name>.md — 嵌入 Mermaid 的 Markdown

.md 文件使用 Mermaid 代码块包裹相同代码，以便预览渲染，并附上标题和描述。示例：

# Diagram Title

Brief description of what this diagram shows.

​```mermaid
flowchart TD
    A[Start] --> B{Condition}
    B -->|Yes| C[Execute]
    B -->|No| D[End]
    C --> D
​```

命名规范：使用根据用户请求提炼的描述性 kebab-case 名称（例如 auth-flow、system-architecture、database-er）。

步骤 4：验证 Mermaid 语法（必须执行）

Claude 必须运行 Mermaid CLI（mmdc）验证生成的 Mermaid 代码。

# Check if mermaid-cli is available
if command -v mmdc &> /dev/null; then
    # Render to PNG to verify syntax is correct
    mmdc -i figures/<diagram-name>.mmd -o figures/<diagram-name>.png -b transparent \
        && echo "✅ Syntax valid — PNG rendered to figures/<diagram-name>.png"
else
    # Try npx as fallback
    npx -y @mermaid-js/mermaid-cli@latest -i figures/<diagram-name>.mmd -o figures/<diagram-name>.png -b transparent \
        && echo "✅ Syntax valid — PNG rendered to figures/<diagram-name>.png"
fi

如果验证失败：

1. 仔细阅读错误信息
2. 修复 .mmd 和 .md 文件中的语法问题
3. 重新运行验证
4. 最多重复 MAX_ITERATIONS（3）次

步骤 5：Claude 严格视觉审查与评分（必须执行）

渲染成功后，Claude 必须读取生成的 PNG 并进行严格审查：

## Claude's STRICT Review of <diagram-name>

### What I See
[Describe the rendered diagram in DETAIL - every block, every arrow, every label]

### Files Generated
- `figures/<diagram-name>.mmd` — Raw Mermaid source
- `figures/<diagram-name>.md` — Markdown with embedded diagram
- `figures/<diagram-name>.png` — Rendered PNG (if mmdc available)

### ═══════════════════════════════════════════════════════════════
### STRICT VERIFICATION CHECKLIST (ALL must pass for score ≥ 9)
### ═══════════════════════════════════════════════════════════════

#### A. File Correctness
- [ ] `.mmd` file contains valid Mermaid syntax (no markdown fences)
- [ ] `.md` file has the mermaid code wrapped in ```mermaid``` fences
- [ ] `.mmd` and `.md` contain IDENTICAL Mermaid code
- [ ] Diagram renders without errors (via mmdc)

#### B. Arrow Correctness Verification (CRITICAL - any failure = score ≤ 6)
Check EACH arrow:
- [ ] Arrow 1: [Source] → [Target] — Does it point to the CORRECT target?
- [ ] Arrow 2: [Source] → [Target] — Does it point to the CORRECT target?
- [ ] ... (check ALL arrows)

#### C. Block Content Verification (any failure = score ≤ 7)
Check EACH block/node:
- [ ] Block 1 "[Name]": Has correct label? Content correct?
- [ ] Block 2 "[Name]": Has correct label? Content correct?
- [ ] ... (check ALL blocks)

#### D. Completeness
- [ ] All components from user requirements are present
- [ ] All connections/arrows are correct
- [ ] Node labels are meaningful and match requirements

#### E. Visual Quality
- [ ] Layout is clean and readable
- [ ] Color scheme is professional (not rainbow)
- [ ] Text is readable at normal zoom
- [ ] Proper spacing (not cramped, not sparse)
- [ ] Data flow is traceable in 5 seconds

### ═══════════════════════════════════════════════════════════════

### Issues Found (BE SPECIFIC)
1. [Issue 1]: [EXACTLY what is wrong] → [How to fix]
2. [Issue 2]: [EXACTLY what is wrong] → [How to fix]

### Score: X/10

### Score Breakdown Guide:
- **10**: Perfect. No issues. Publication-ready.
- **9**: Excellent. Minor issues that don't affect understanding.
- **8**: Good but has noticeable issues (layout, styling).
- **7**: Usable but has clear problems (wrong arrows, missing labels).
- **6**: Has arrow direction errors or missing major components.
- **1-5**: Major issues. Unacceptable.

### Verdict
[ ] ACCEPT (score ≥ 9 AND all critical checks pass)
[ ] FIX (score < 9 OR any critical check fails — list EXACT fixes needed)

如果需要修复：请同时更正 .mmd 和 .md 文件，重新渲染并重新验证。循环执行，直至通过或达到 MAX_ITERATIONS。

步骤 6：最终输出摘要

通过审查后，向用户提供：

✅ Mermaid diagram generated successfully!

Files:
  figures/<diagram-name>.mmd  — Raw Mermaid source (use with mmdc, editors, CI)
  figures/<diagram-name>.md   — Markdown preview (renders on GitHub, VS Code, etc.)
  figures/<diagram-name>.png  — Rendered image (if mmdc was available)

To re-render manually:
  mmdc -i figures/<diagram-name>.mmd -o figures/<diagram-name>.png

架构图最佳实践

生成 architecture-beta 图表时，请对复杂图表应用以下布局技巧：

使用连接点控制布局

将图表想象成一个隐形网格。使用 junction 节点作为网格上的虚拟锚点，精确控制各组件的位置。当两个服务之间的直接边导致位置异常时，这种方法尤其有用。

不要直接连接服务：

lb:R --> L:scim
lb:R --> L:webapi

通过连接点进行路由，以控制垂直／水平位置：

junction j_lb_r
lb:R -- L:j_lb_r
junction j_scim_l
j_lb_r:T -- B:j_scim_l
j_scim_l:R --> L:scim
junction j_webapi_l
j_lb_r:B -- T:j_webapi_l
j_webapi_l:R --> L:webapi

在组件的四周都放置连接点，使其在网格上获得逻辑锚定。

使用从组引出的边放置浮动组件

对于没有与其他节点建立逻辑连接的服务（例如部署工具、监控 Agent），可结合使用连接点和 {group} 修饰符来放置它们，而不添加语义上不正确的边：

junction j_acd_t
j_algolia_proc_b{group}:B -- T:j_acd_t
j_acd_t:B -- T:acd

这样会将 acd 锚定在预期相邻节点的下方，而不会暗示二者存在真实关系。

CVPR/ICLR/NeurIPS 风格指南（学术图表）

如果图表用于学术论文，请遵循以下风格标准：

视觉标准

• 干净的白色背景 — 不使用装饰性图案或渐变（除非效果很微妙）
• 无衬线字体 — Arial、Helvetica 或 Computer Modern；最小字号为 14pt
• 柔和的配色 — 不使用彩虹色；使用 3–5 种协调的颜色
• 适合打印 — 必须能在灰度下清晰辨认（许多审稿人会打印论文）
• 专业的边框 — 线条较细（2–3px）、纯色、不花哨

布局标准

• 水平流向 — 从左到右是管线的标准方向
• 分组清晰 — 使用柔和的背景框对相关模块进行分组
• 尺寸一致 — 相似组件应具有相似的尺寸
• 留白均衡 — 不拥挤，也不稀疏

箭头标准（最关键）

• 粗线条 — 至少 4–6px（打印时细箭头会消失）
• 清晰的箭头 — 使用大号实心三角形箭头
• 深色 — 使用黑色或深灰色（#333333）；避免使用彩色箭头
• 标注清楚 — 每个箭头都应标明其传递的数据
• 避免交叉 — 调整布局以避免箭头交叉
• 方向正确 — 箭头必须指向正确的目标！

配色（学术专业风格）

• 输入：绿色（#10B981 / #34D399）
• 编码器：蓝色（#2563EB / #3B82F6）
• 融合：紫色（#7C3AED / #8B5CF6）
• 输出：橙色（#EA580C / #F97316）
• 箭头：黑色或深灰色（#333333 / #1F2937）
• 背景：纯白色（#FFFFFF）

应避免的内容

• 彩虹配色方案（颜色过多）
• 纤细的线状箭头
• 浓重的投影或发光效果
• 3D 效果／透视效果
• 过多的装饰性图标
• 打印后无法辨认的小字

图表中的数学公式（KaTeX）

Mermaid 支持使用 KaTeX（v10.9.0+）渲染数学表达式。当图表内容涉及数学（公式、方程、希腊字母、下标／上标、分数、矩阵、运算符等）时，请使用 KaTeX 表示法，而不是纯文本近似写法。

支持数学渲染的图表类型

以下图表支持使用 $$...$$ 渲染数学表达式：

• 流程图（flowchart / graph）— 节点标签和边标签
• 时序图 — 参与者别名、消息和注释

语法规则

1. 在引号内使用 $$ 分隔符包裹数学表达式：

   A["$$x^2$$"] -->|"$$\sqrt{x+3}$$"| B("$$\frac{1}{2}$$")
   

2. 包含数学表达式的节点标签必须加引号 — 使用 ["$$...$$"] 或 ("$$...$$")：

   scaledDot["$$\text{softmax}\left(\frac{QK^T}{\sqrt{d_k}}\right)V$$"]
   

3. 混合文本和数学表达式时，只在数学部分两侧添加 $$：

   layer1["Linear Layer $$W_1 x + b_1$$"]
   

4. 在 $$ 块内使用 \text{} 表示非数学文本：

   node["$$\text{Attention}(Q, K, V)$$"]
   

ML/科学图表中的常见数学模式

概念	KaTeX 语法	渲染效果
下标	$$W_Q$$	W_Q
上标	$$x^2$$	x²
分数	$$\frac{QK^T}{\sqrt{d_k}}$$	QK^T / sqrt(d_k)
希腊字母	$$\alpha, \beta, \gamma$$	α, β, γ
平方根	$$\sqrt{d_k}$$	√d_k
求和	$$\sum_{i=1}^{n} x_i$$	Σx_i
矩阵	$$\begin{bmatrix} a & b \\ c & d \end{bmatrix}$$	2x2 矩阵
Softmax	$$\text{softmax}(z_i)$$	softmax(z_i)
范数	$$||x||_2$$	‖x‖₂
帽子/波浪线	$$\hat{y}, \tilde{x}$$	ŷ, x̃

示例：带数学公式的注意力机制

flowchart TD
    Q["$$Q \in \mathbb{R}^{n \times d_k}$$"]
    K["$$K \in \mathbb{R}^{n \times d_k}$$"]
    V["$$V \in \mathbb{R}^{n \times d_v}$$"]
    scores["$$\frac{QK^T}{\sqrt{d_k}}$$"]
    softmax["$$\text{softmax}(\cdot)$$"]
    output["$$\text{Attention}(Q,K,V)$$"]

    Q --> scores
    K --> scores
    scores --> softmax
    softmax --> weighted["$$\alpha V$$"]
    V --> weighted
    weighted --> output

何时使用数学公式，何时使用纯文本

• 当图表面向学术/技术受众，且精确性很重要时，使用数学公式（论文、讲座、技术文档）
• 当图表面向一般受众，或数学公式会增加视觉杂乱却无法提升清晰度时，使用纯文本（换行使用 <br/>）
• 默认行为：如果用户的请求中包含数学符号、方程或希腊字母符号，则自动使用 KaTeX 数学公式渲染。否则，使用纯文本标签。

注意事项

• $$ 分隔符必须放在引号内——不加引号的 $$ 会导致解析失败
• KaTeX 中的反斜杠（\frac、\sqrt 等）在 Mermaid 字符串中可以正常使用
• 过长的公式可能会溢出节点框——使用 \\（KaTeX 中的换行符）拆分公式，或简化公式
• 务必使用 mmdc 验证渲染效果——某些 KaTeX 表达式可能无法在所有环境中渲染

代码质量规则

生成的 Mermaid 代码必须：

1. 语法正确，可直接渲染
2. 结构清晰，换行和缩进恰当
3. 使用语义明确的节点名称（不要使用 A、B、C——应使用 authServer、userDB 等）
4. 必要时添加样式以改善视觉效果
5. 节点标签中的换行使用 <br/>——切勿使用 \n，否则会按原样显示为文本
6. 避免在标签中使用会导致 Mermaid 解析失败的特殊字符（必要时用引号括起来）

输出结构

figures/
├── <diagram-name>.mmd    # Raw Mermaid source (no markdown fences)
├── <diagram-name>.md     # Markdown with embedded mermaid block
└── <diagram-name>.png    # Rendered PNG (if mmdc available)

关键规则（必须遵守）

1. 务必将文件保存到 figures/ 目录——切勿只在聊天中输出代码
2. 务必同时生成 .mmd 和 .md 文件——两者必须包含完全相同的 Mermaid 代码
3. 为图表类型生成代码前，务必阅读参考文档
4. 务必验证语法——运行 mmdc 或手动验证后再确认
5. 务必检查渲染后的 PNG——读取图像并进行严格评分
6. 绝不接受低于 9 分的评分——持续改进，直至达到优秀水平
7. 验证每条箭头的方向——方向错误 = 自动不合格（评分 ≤ 6）
8. 验证每个模块的内容——内容错误 = 自动不合格（评分 ≤ 7）
9. 反馈务必具体——说“从 A 指向 B 的箭头方向错误”，而不是“箭头错了”
10. 确认前修复错误——不要交付有问题的图表
11. 使用描述性文件名——根据图表内容采用 kebab-case 命名

---

用户要求：$ARGUMENTS