mermaid

Mermaid

根据用户提供的源材料和意图，生成有效、结构清晰的 Mermaid 图表。选择合适的图表类型，确保易于阅读，并将其放在带有 mermaid 标记的围栏代码块中。

参考文件

文件	阅读时机
references/diagram-selection.md	默认：选择合适的图表类型；每种类型均提供一行示例
references/common-diagrams.md	生成流程图、时序图、类图、状态图、ER 图或 C4 图
references/specialized-diagrams.md	生成思维导图、甘特图、时间线、用户旅程、gitGraph、饼图、象限图、需求图、xychart、桑基图、块图或架构图
references/generation-guidelines.md	适用于任何图表：标签限制、结构规则、源类型策略、反模式
references/styling-and-output.md	主题、classDef 样式、frontmatter 配置、导出、渲染目标

工作流程

复制此清单以跟踪进度：

Mermaid progress:
- [ ] Step 1: Pick diagram type
- [ ] Step 2: Gather source material
- [ ] Step 3: Draft structure
- [ ] Step 4: Generate Mermaid syntax
- [ ] Step 5: Validate
- [ ] Step 6: Present output

第 1 步：选择图表类型

如果用户指定了类型（例如“时序图”），就使用该类型。否则，加载 references/diagram-selection.md 并根据其中的矩阵进行选择。常见的默认选择：

内容	图表
包含决策和分支逻辑的流程	flowchart
参与者或系统随时间传递的消息	sequenceDiagram
状态及其转换（订单生命周期、工作流）	stateDiagram-v2
数据库／领域实体及其关系	erDiagram
按层级展示的系统架构	C4Context / C4Container / C4Component
概念层级、头脑风暴、概览	mindmap

只有在两种类型同样合适时，才请用户确认。

第 2 步：收集源材料

对于主题或规格说明，如果范围不明确（例如“概览还是详细拆解？”），请提出一个澄清问题，然后确定方案。对于代码库、文件或对话，只提取命名节点和关系所需的内容——不要进行超出需要的扫描。

第 3 步：拟定结构

先勾勒图表的基本结构，再编写语法：

• 列出节点／实体／步骤。
• 列出关系／消息／转换。
• 对于流程图、时序图、状态图：确定起点和终点。对于 ER 图、类图：确定多重性。对于 C4：选择合适的层级。
• 遵循 references/generation-guidelines.md 中的尺寸和标签规则——为便于阅读，通常使用 5-20 个节点。

第 4 步：生成 Mermaid 语法

打开所选类型对应的参考文件，并在带有 mermaid 标记的围栏代码块中编写图表。保持语法精简；只有在用户要求时才添加样式（参见 references/styling-and-output.md）。

第 5 步：验证

运行以下通用检查，并执行相应参考文件中的类型专属检查。如果任何检查未通过，请修改后重新检查。

通用检查：

• 第一行声明正确的图表类型（例如 flowchart TD、sequenceDiagram）
• 纯文本标签中没有未转义的 ()[]{} 或多余的冒号
• 图表代码块内没有空行（某些渲染器会因此出错）
• 在需要的情况下，所有被引用的节点／参与者／实体都已在使用前定义
• 方向和流程保持一致（自上而下或从左到右，不要同时使用）
• 标签文本足够简短，便于渲染（目标为少于 6 个词；参见各类型规则）
• 总规模处于该类型的可读范围内（流程图／类图为 15-20 个；思维导图最多 40 个）

第 6 步：呈现输出

将图表放在带有 mermaid 标记的围栏代码块中输出。说明可在哪些地方渲染：GitHub／GitLab Markdown、Mermaid Live Editor（mermaid.live）、Notion、Obsidian，以及安装 Mermaid 预览扩展的 VS Code。

如果用户要求文件，则写入包含该围栏代码块的 .md 文件。对于图像导出，请引导用户使用 Mermaid Live Editor 或 @mermaid-js/mermaid-cli（参见 references/styling-and-output.md）。

翻译示例

如何将典型源材料转化为图表。模式：先确定类型，再提取名词（节点）和动词（边／转换）。

散文 → sequenceDiagram

来源：“用户点击结账。服务器验证购物车、预留库存并通过 Stripe 收费。成功后，订单会被保存，并将确认邮件加入发送队列。”

sequenceDiagram
    actor User
    participant Server
    participant Stripe
    participant Email
    User->>+Server: POST /checkout
    Server->>Server: Validate cart
    Server->>Server: Reserve stock
    Server->>+Stripe: Charge
    Stripe-->>-Server: Success
    Server->>Server: Save order
    Server->>+Email: Queue confirmation
    Email-->>-Server: Queued
    Server-->>-User: 200 Order confirmed

规范 → stateDiagram

来源：“订单初始状态为 Pending。付款成功后转为 Paid；失败则转为 Cancelled。Paid 订单会发货，然后完成。Cancelled 订单为终止状态。”

stateDiagram-v2
    [*] --> Pending
    Pending --> Paid : payment success
    Pending --> Cancelled : payment failed
    Paid --> Shipped : ship
    Shipped --> Completed : deliver
    Completed --> [*]
    Cancelled --> [*]

评分矩阵 → quadrantChart

来源：“根据覆盖范围（低/高）和互动度（低/高）为营销活动评分。A 的覆盖范围高、互动度中等。B 的覆盖范围低、互动度低。C 的覆盖范围高、互动度高。”

quadrantChart
    title Campaign reach vs engagement
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
    quadrant-1 Expand
    quadrant-2 Promote
    quadrant-3 Re-evaluate
    quadrant-4 Improve
    A: [0.8, 0.5]
    B: [0.2, 0.2]
    C: [0.8, 0.8]

反模式

• 强行把所有内容放进一张图中——应改为拆分成多张重点明确的图。
• 将句子用作标签——提取关键词，或将细节移到子节点/注释中。
• 在同一个代码围栏中混用两种图表类型（不支持）。
• 使用渲染目标不支持的图标或 Font Awesome 引用。
• 结构尚未验证就过度美化。
• 猜测语法——加载所选类型的参考文件。

相关技能

• presentation-creator：用于制作包含图表的幻灯片
• define-architecture：用于制定超出可视化图表范围的详细架构决策
• docs-writing：用于在技术文档中嵌入图表