mermaid-studio

Mermaid Studio

专业级 Mermaid 图表创建、验证和多格式渲染。可根据描述或代码分析创建图表、验证语法，并使用专业主题渲染为 SVG、PNG 或 ASCII。

黄金法则——默认创建优雅的图表

每个图表都必须遵循以下原则。这些原则并非可选项，而是区分平庸图表与黄金标准图表的关键。

规则 1：始终使用初始化指令进行专业样式设置

绝不创建不带 %%{init} 指令或 frontmatter 配置的图表。Mermaid 默认主题会产生刺眼的黑色线条和通用配色。始终应用精心挑选的调色板。

适用于通用图表（流程图、时序图、状态图、类图、ERD）：

%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#4f46e5', 'primaryTextColor': '#ffffff',
  'primaryBorderColor': '#3730a3', 'lineColor': '#94a3b8',
  'secondaryColor': '#10b981', 'tertiaryColor': '#f59e0b',
  'background': '#ffffff', 'mainBkg': '#f8fafc',
  'nodeBorder': '#cbd5e1', 'clusterBkg': '#f1f5f9',
  'clusterBorder': '#e2e8f0', 'titleColor': '#1e293b',
  'edgeLabelBackground': '#ffffff', 'textColor': '#334155'
}}}%%

**⚠️ 字体警告：**请勿在主题变量中设置 fontFamily。Mermaid 默认字体（trebuchet ms, verdana, arial, sans-serif）可在各种环境中正常显示。在无头 Chromium（mmdc 使用的环境）中，设置 system-ui、Segoe UI 或 -apple-system 会导致字体渲染为 Times New Roman。

C4 图表——请参阅下文专门的 C4 样式设置部分。

architecture-beta 图表——请参阅下文专门的 AWS/Architecture 部分。

规则 2：使用柔和线条，绝不使用刺眼的黑色

最显著的视觉改进，就是使用 lineColor: '#94a3b8'（slate-400）代替默认黑色。这会让图表显得现代、通透。深色主题请使用 lineColor: '#64748b'（slate-500）。

规则 3：控制密度，留出空间

• 每个图表最多 15 个节点（不是 20 个——更少才更优雅）
• 使用 subgraph 或边界留白并进行视觉分组
• 流程图优先使用 LR（从左到右），阅读起来更自然
• 布局拥挤时，使用不可见连线（A ~~~ B）增加间距

规则 4：标签有意义，风格保持一致

• 节点 ID：使用 camelCase（orderService，而不是 s1 或 os）
• 标签：使用简短、清晰的自然语言（[Order Service]）
• 箭头：使用带协议说明的动作动词（"Sends order via gRPC"）
• 描述：用一行文字聚焦于职责（"Handles order lifecycle"）

规则 5：色彩和谐优先于色彩多样

每个图表最多使用 3-4 种颜色。按含义分配颜色：

• 蓝色调（#4f46e5、#3b82f6）→ 主要系统、内部服务
• 绿色调（#10b981、#059669）→ 成功状态、数据存储
• 琥珀色调（#f59e0b、#d97706）→ 外部系统、警告
• 石板色调（#64748b、#94a3b8）→ 线条、边框、次要元素
• 红色调（#ef4444）→ 仅用于错误，绝不作为装饰

操作模式

此技能根据用户意图以三种模式运行：

模式	触发条件	执行内容
Create	“绘制……的图表”“可视化我的……”	仅生成 .mmd 代码
Render	“渲染此 mermaid”“转换为 SVG/PNG/ASCII”	渲染现有 .mmd
Full	“创建并渲染……”、意图不明确的请求	创建 → 验证 → 渲染

意图不明确时，默认使用 Full 模式。

步骤 1：理解请求

编写 Mermaid 代码前，先确定：

1. 要绘制什么——系统、流程、架构、代码结构？
2. 使用哪种图表类型——参阅下方的决策矩阵
3. 输出格式——仅代码、SVG、PNG 还是 ASCII？
4. 主题偏好——仅在渲染时询问；默认使用 base 主题和精心挑选的调色板

图表类型决策矩阵

用户描述……	图表类型	语法关键字
流程、算法、决策树、工作流	流程图	flowchart TD/LR
API 调用、消息传递、请求/响应	时序图	sequenceDiagram
数据库架构、表关系	ERD	erDiagram
OOP 类、领域模型、接口	类图	classDiagram
状态机、生命周期、转换	状态图	stateDiagram-v2
高层系统概览（C4 第 1 级）	C4 上下文	C4Context
应用程序、数据库、服务（C4 第 2 级）	C4 容器	C4Container
内部组件（C4 第 3 级）	C4 组件	C4Component
带编号步骤的请求流	C4 动态图	C4Dynamic
基础设施、云部署	C4 部署图	C4Deployment
带图标的云服务（AWS/GCP/Azure）	架构图	architecture-beta
项目时间线、排期	甘特图	gantt
比例数据、百分比	饼图	pie
头脑风暴、层级化想法	思维导图	mindmap
历史事件、时间顺序	时间线	timeline
分支策略、Git 历史	Git 图	gitGraph
流量数量、资源分布	桑基图	sankey-beta
X/Y 数据可视化	XY 图表	xychart-beta
优先级矩阵、战略定位	象限图	quadrantChart
布局控制、网格定位	块图	block-beta
网络数据包、协议标头	数据包图	packet-beta
任务看板、看板工作流	看板	kanban
用户体验、满意度评分	用户旅程图	journey
系统需求可追溯性	需求图	requirementDiagram

如果用户的描述无法明确对应某种类型，请推荐 2-3 个选项，并简要说明各自的理由，然后让用户选择。

何时加载参考资料

仅在特定图表类型需要时加载参考文件：

• C4 图表 → 编写代码前阅读 references/c4-architecture.md
• AWS/云架构 → 编写代码前阅读 references/aws-architecture.md
• 代码转图表 → 分析前阅读 references/code-to-diagram.md
• 主题/样式 → 用户请求自定义主题时阅读 references/themes.md
• 语法错误 → 验证失败时阅读 references/troubleshooting.md
• 任何图表类型的详细信息 → 阅读 references/diagram-types.md，查看完整语法

第 2 步：创建图表

2.1 — 编写 Mermaid 代码

按以下优先级顺序遵循这些原则：

1. 优先追求优雅——每个图表都必须通过初始化指令和精心挑选的颜色呈现专业效果
2. 正确性——语法有效，可无错误渲染
3. 清晰度——标签有意义、流程方向合理、关系清晰
4. 简洁性——每个图表少于 15 个节点；复杂系统应拆分为多个图表
5. 一致性——命名统一（ID 使用 camelCase，方括号内使用描述性标签）

2.2 — 结构规则

%% Diagram: [Purpose] | Author: [auto] | Date: [auto]
%%{init: {'theme': 'base', 'themeVariables': { ... }}}%%
[diagramType]
    [content]

关键： %%{init} 指令必须放在第一个非注释行，位于图表类型声明之前。或者，在文件绝对开头使用 YAML frontmatter。

命名约定：

• 节点 ID：使用 camelCase，名称应具有描述性（orderService，而非 s1）
• 标签：使用方括号括起的自然语言（[Order Service]）
• 关系：使用动作动词（"Sends order to"、"Reads from"）

布局最佳实践：

• 层级流程和过程使用 TD（自上而下）
• 时间线、管道和顺序流程使用 LR（从左到右）
• 从右向左阅读的场景使用 RL
• 使用 subgraph 对相关节点进行分组，并为子图赋予有意义的名称
• 需要采用不同流程方向时，在子图内添加 direction

2.3 — 快速参考示例

流程图（采用专业样式）：

%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#4f46e5', 'primaryTextColor': '#fff',
  'primaryBorderColor': '#3730a3', 'lineColor': '#94a3b8',
  'secondaryColor': '#10b981', 'tertiaryColor': '#f59e0b',
  'background': '#ffffff', 'mainBkg': '#f8fafc',
  'nodeBorder': '#cbd5e1', 'clusterBkg': '#f1f5f9',
  'clusterBorder': '#e2e8f0', 'titleColor': '#1e293b',
  'edgeLabelBackground': '#ffffff'
}}}%%
flowchart TD
    Start([Start]) --> Input[/User Input/]
    Input --> Validate{Valid?}
    Validate -->|Yes| Process[Process Data]
    Validate -->|No| Error[Show Error]
    Error --> Input
    Process --> Save[(Save to DB)]
    Save --> End([End])

如需了解序列图和 ERD 样式示例，请阅读 references/themes.md。

C4 上下文图（必须采用优雅样式）：

C4Context
    title System Context — E-Commerce Platform

    Person(customer, "Customer", "Places orders online")
    System(platform, "E-Commerce Platform", "Handles orders and payments")
    System_Ext(payment, "Payment Gateway", "Processes transactions")
    System_Ext(email, "Email Service", "Sends notifications")

    Rel(customer, platform, "Uses", "HTTPS")
    Rel(platform, payment, "Processes payments", "API")
    Rel(platform, email, "Sends emails", "SMTP")

    UpdateRelStyle(customer, platform, $textColor="#475569", $lineColor="#94a3b8")
    UpdateRelStyle(platform, payment, $textColor="#475569", $lineColor="#94a3b8")
    UpdateRelStyle(platform, email, $textColor="#475569", $lineColor="#94a3b8")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

架构图（AWS，使用 Iconify 图标）：

architecture-beta
    group vpc(logos:aws-vpc)[VPC]

    service api(logos:aws-api-gateway)[API Gateway] in vpc
    service lambda(logos:aws-lambda)[Lambda] in vpc
    service db(logos:aws-dynamodb)[DynamoDB] in vpc
    service s3(logos:aws-s3)[S3 Bucket]

    api:R --> L:lambda
    lambda:R --> L:db
    lambda:B --> T:s3

重要： Architecture-beta 图表中的 logos:* 图标需要注册图标包。使用渲染脚本渲染时，请使用 --icons logos 标志。如果在不支持图标包的 Markdown 查看器中渲染，请使用内置图标（cloud、database、disk、server、internet）作为备用。请阅读 references/aws-architecture.md，了解完整的图标目录和渲染说明。

如需了解所有图表类型的完整语法，请阅读 references/diagram-types.md。

C4 图表 — 强制样式指南

C4 图表的元素样式固定（系统使用蓝色方框、人员使用灰色方框等），但其关系线默认是刺眼的黑色，会造成视觉杂乱。必须应用以下样式规则：

C4 样式模式

每个 C4 图表都必须在末尾包含以下指令：

    %% === MANDATORY STYLING ===
    %% Apply soft line colors to ALL relationships
    UpdateRelStyle(fromAlias, toAlias, $textColor="#475569", $lineColor="#94a3b8")
    %% Repeat for each Rel() in the diagram

    %% Optimize layout spacing
    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

C4 颜色值参考

用途	颜色	十六进制	备注
柔和线条颜色	Slate-400	#94a3b8	替代刺眼的默认黑色
线条文本颜色	Slate-600	#475569	清晰易读，但不喧宾夺主
强调线条	Blue-400	#60a5fa	用于突出显示或主要关系
警告线条	Amber-500	#f59e0b	用于外部或风险连接
自定义元素背景色	Emerald	#10b981	用于数据存储或成功状态的突出显示
自定义元素背景色	Indigo	#4f46e5	用于突出显示主要系统

C4 布局提示

关键 — 每个图表最多包含 6 个 Rel()。 关系超过 6 个时，Dagre 可能会将箭头穿过节点，形成难以阅读的乱麻。如果系统需要更多连接，请将其拆分为多个重点明确的图表。

• 大多数图表使用 $c4ShapeInRow="3"（避免水平拥挤）
• 标签较长的图表使用 $c4ShapeInRow="2"
• 始终使用 $c4BoundaryInRow="1"（垂直堆叠边界，提升清晰度）
• 标签与元素重叠时，为 UpdateRelStyle 应用 $offsetY="-10"
• 优先采用树形拓扑（每个节点 1 条入线、1–2 条出线），而非网状拓扑
• 按流程顺序声明元素——Container() 声明的顺序会影响布局
• 仅在自动布局导致重叠时，才使用 Rel_D()、Rel_R() 等方向性关系作为最后手段

如需了解 C4 的完整语法、示例和模式，请阅读 references/c4-architecture.md。

步骤 3：验证

渲染之前，务必验证 Mermaid 语法：

node $SKILL_DIR/scripts/validate.mjs <file.mmd>

如果验证失败：

1. 仔细阅读错误消息
2. 查阅 references/troubleshooting.md，了解常见修复方法
3. 修复语法并重新验证
4. 最多尝试修复 3 次，然后再向用户请求澄清

步骤 4：渲染

4.1 — 设置（仅首次运行）

bash $SKILL_DIR/scripts/setup.sh

这会自动安装两个渲染引擎及图标包依赖。每个环境运行一次即可。

4.2 — 渲染单个图表

# SVG (default — best quality)
node $SKILL_DIR/scripts/render.mjs -i diagram.mmd -o diagram.svg

# PNG (for documents/presentations)
node $SKILL_DIR/scripts/render.mjs -i diagram.mmd -o diagram.png --width 1200

# ASCII (for terminals/READMEs)
node $SKILL_DIR/scripts/render-ascii.mjs -i diagram.mmd

# With icon packs (architecture-beta with AWS/tech icons)
node $SKILL_DIR/scripts/render.mjs -i diagram.mmd -o diagram.svg --icons logos,fa

--icons 标志会在渲染前注册 Iconify 图标包。图标包：logos（AWS/技术）、fa（Font Awesome）。AWS 请使用 logos。

4.3 — 批量渲染

一次渲染多个图表：

node $SKILL_DIR/scripts/batch.mjs \
  --input-dir ./diagrams \
  --output-dir ./rendered \
  --format svg \
  --theme default \
  --workers 4

4.4 — 可用主题

beautiful-mermaid（15 种）： tokyo-night | tokyo-night-storm | tokyo-night-light | dracula | nord | nord-light | catppuccin-mocha | catppuccin-latte | github-dark | github-light | solarized-dark | solarized-light | one-dark | zinc-dark | zinc-light

mermaid-cli 原生主题（5 种）： default | forest | dark | neutral | base

自定义主题：--theme base --config '{"theme":"base","themeVariables":{"primaryColor":"#4f46e5","lineColor":"#94a3b8"}}'

完整主题目录请参阅 references/themes.md。渲染脚本会自动选择最佳引擎（优先使用 mmdc，回退到 beautiful-mermaid；图标包使用 Puppeteer）。

步骤 5：从代码生成图表（按需）

当用户要求将现有代码或架构可视化时：

1. 阅读 references/code-to-diagram.md，了解分析方法
2. 分析代码库，确定合适的图表类型：
   • 模块依赖 → 流程图或类图
   • API 路由和处理程序 → 时序图
   • 数据库模型/架构 → ERD
   • 服务架构 → C4 容器图或架构图
   • 代码中的状态机 → 状态图
3. 添加正确的 init 指令，生成 .mmd 文件（黄金法则 1）
4. 按照常规流程验证并渲染

故障排除速查

症状	可能原因	解决方法
图表无法渲染	语法错误	运行 validate.mjs，检查括号/引号
标签被截断	文本过长	缩短标签或使用换行 <br/>
布局不正确	方向错误	尝试其他 TD/LR/BT/RL
节点重叠	节点过多	拆分为子图或多个图表
线条过暗/过粗	缺少 init 指令	添加 %%{init}，并设置 lineColor: '#94a3b8'
C4 线条重叠	未应用样式	为每个 Rel 添加带偏移量的 UpdateRelStyle
AWS 图标未显示	缺少图标包	使用 --icons logos 标志，或回退到内置图标
mmdc 未找到	尚未安装	运行 setup.sh
主题未生效	引擎错误	beautiful-mermaid 主题仅适用于该引擎

完整的故障排除说明请参阅 references/troubleshooting.md。

输出约定

• 将 .mmd 源文件与渲染后的输出文件保存在一起
• 命名格式：{purpose}-{type}.mmd（例如 auth-flow-sequence.mmd）
• 批量处理时：保留输入文件名，仅更改扩展名
• 始终向用户同时提供 .mmd 源文件和渲染后的文件