mermaid-visualizer

Mermaid 可视化工具

概述

将文本内容转换为简洁、专业的 Mermaid 图表，适用于演示文稿和文档。自动处理常见的语法问题（列表语法冲突、子图命名、间距问题），确保图表能在 Obsidian、GitHub 和其他兼容 Mermaid 的平台上正确渲染。

快速入门

创建 Mermaid 图表时：

1. 分析内容 - 识别关键概念、关系和流程
2. 选择图表类型 - 选择最合适的可视化形式（见下文的图表类型）
3. 选择配置 - 确定布局、详细程度和样式
4. 生成图表 - 创建语法正确的 Mermaid 代码
5. 以 Markdown 格式输出 - 使用正确的代码围栏，可附带说明

默认假设：

• 默认采用纵向布局（TB），除非用户要求横向布局
• 采用中等详细程度（兼顾简洁性和信息量）
• 使用专业配色方案和语义化颜色
• 使用兼容 Obsidian/GitHub 的语法

图表类型

1. 流程图（graph TB/LR）

适用场景： 工作流、决策树、顺序流程、AI Agent 架构

使用时机： 内容描述了步骤、阶段或一系列操作

主要特点：

• 通过子图实现泳道，用于对相关步骤分组
• 使用箭头标签表示转换
• 支持反馈循环和分支
• 使用颜色区分阶段

配置选项：

• layout："vertical"（TB）、"horizontal"（LR）
• detail："simple"（仅核心步骤）、"standard"（包含描述）、"detailed"（包含注释）
• style："minimal"、"professional"、"colorful"

2. 循环流程图（采用循环布局的 graph TD）

适用场景： 循环流程、持续改进循环、Agent 反馈系统

使用时机： 内容强调迭代、反馈或循环关系

主要特点：

• 中心枢纽与辐射状元素
• 弯曲的反馈箭头
• 清晰的循环标识

3. 对比图（采用并行路径的 graph TB）

适用场景： 前后对比、A 与 B 的分析、传统系统与现代系统的对比

使用时机： 内容对比两种或更多方法或系统

主要特点：

• 并排布局
• 中心对比节点
• 通过颜色/样式清晰区分

4. 思维导图

适用场景： 层级概念、知识组织、主题拆解

使用时机： 内容具有清晰的父子关系和层级结构

主要特点：

• 放射状树形结构
• 多层嵌套
• 清晰的视觉层级

5. 时序图

适用场景： 组件间交互、API 调用、消息流

使用时机： 内容涉及参与者/系统随时间进行通信

主要特点：

• 基于时间线的布局
• 清晰区分参与者
• 使用激活框表示流程

6. 状态图

适用场景： 系统状态、状态转换、生命周期阶段

使用时机： 内容描述状态及其间的转换

主要特点：

• 清晰的状态节点
• 带标签的转换
• 起始状态和结束状态

关键语法规则

始终遵循以下规则，以避免解析错误：

规则 1：避免列表语法冲突

❌ WRONG: [1. Perception]       → Triggers "Unsupported markdown: list"
✅ RIGHT: [1.Perception]         → Remove space after period
✅ RIGHT: [① Perception]         → Use circled numbers (①②③④⑤⑥⑦⑧⑨⑩)
✅ RIGHT: [(1) Perception]       → Use parentheses
✅ RIGHT: [Step 1: Perception]   → Use "Step" prefix

规则 2：子图命名

❌ WRONG: subgraph AI Agent Core  → Space in name without quotes
✅ RIGHT: subgraph agent["AI Agent Core"]  → Use ID with display name
✅ RIGHT: subgraph agent          → Use simple ID only

规则 3：节点引用

❌ WRONG: Title --> AI Agent Core  → Reference display name directly
✅ RIGHT: Title --> agent          → Reference subgraph ID

规则 4：节点文本中的特殊字符

✅ Use quotes for text with spaces: ["Text with spaces"]
✅ Escape or avoid: quotation marks → use 『』instead
✅ Escape or avoid: parentheses → use 「」instead
✅ Line breaks in circle nodes only: ((Text<br/>Break))

规则 5：箭头类型

• --> 实线箭头
• -.-> 虚线箭头（用于辅助系统、可选路径）
• ==> 粗箭头（用于强调）
• ~~~ 不可见连线（仅用于布局）

如需完整的语法参考和边缘情况说明，请参阅 references/syntax-rules.md

配置选项

所有图表均接受以下参数：

布局：

• direction：“vertical”（TB）、“horizontal”（LR）、“right-to-left”（RL）、“bottom-to-top”（BT）
• aspect：“portrait”（默认）、“landscape”（宽屏）、“square”

详细程度：

• simple：仅包含核心元素，标签尽量简短
• standard：详细程度均衡，包含关键说明（默认）
• detailed：完整的注释、说明和元数据
• presentation：针对幻灯片优化（文字更大，细节更少）

样式：

• minimal：单色、线条简洁
• professional：语义化配色，层次清晰（默认）
• colorful：色彩鲜艳、对比度高
• academic：适用于论文／文档的正式样式

其他选项：

• show_legend：true/false - 包含颜色／符号图例
• numbered：true/false - 为步骤添加序号
• title：string - 添加图表标题

使用模式示例

模式 1：基本请求

User: "Visualize the software development lifecycle"
Response: [Analyze → Choose graph TB → Generate with standard detail]

模式 2：带配置

User: "Create a horizontal flowchart of our sales process with lots of detail"
Response: [Analyze → Choose graph LR → Generate with detailed level]

模式 3：比较

User: "Compare traditional AI vs AI agents"
Response: [Analyze → Choose comparison layout → Generate with contrasting styles]

工作流

1. 理解内容

   • 识别主要概念、实体及其关系
   • 确定层级或顺序
   • 留意比较或对比内容

2. 选择图表类型

   • 根据内容结构选择匹配的图表类型
   • 考虑用户的演示场景
   • 如果无法确定，默认使用流程图

3. 选择配置

   • 应用用户指定的选项
   • 未指定的选项使用合理的默认值
   • 优化可读性

4. 生成 Mermaid 代码

   • 严格遵循所有语法规则
   • 使用语义清晰的命名（描述性 ID）
   • 应用一致的样式
   • 检查常见错误：
     • 节点文本中不得出现“数字. 空格”模式
     • 所有子图均使用 ID["显示名称"] 格式
     • 所有节点引用均使用 ID，而非显示名称

5. 输出并附上说明

   • 使用 ```mermaid 代码围栏包裹
   • 简要说明图表结构
   • 提及渲染兼容性（Obsidian、GitHub 等）
   • 提供调整或创建变体的选项

默认配色方案

标准专业配色：

• 绿色（#d3f9d8/#2f9e44）：输入、感知、起始状态
• 红色（#ffe3e3/#c92a2a）：规划、决策点
• 紫色（#e5dbff/#5f3dc4）：处理、推理
• 橙色（#ffe8cc/#d9480f）：操作、工具使用
• 青色（#c5f6fa/#0c8599）：输出、执行、结果
• 黄色（#fff4e6/#e67700）：存储、记忆、数据
• 粉色（#f3d9fa/#862e9c）：学习、优化
• 蓝色（#e7f5ff/#1971c2）：元数据、定义、标题
• 灰色（#f8f9fa/#868e96）：中性元素、传统系统

常见模式

泳道模式（分组）

graph TB
    subgraph core["Core Process"]
        A --> B --> C
    end
    subgraph support["Supporting Systems"]
        D
        E
    end
    core -.-> support

反馈循环模式

graph TB
    A[Start] --> B[Process]
    B --> C[End]
    C -.->|Feedback| A

中心辐射模式

graph TB
    Central[Hub]
    A[Spoke 1] --> Central
    B[Spoke 2] --> Central
    C[Spoke 3] --> Central

质量检查清单

输出前请确认：

• 所有节点文本中均未出现“数字. 空格”模式
• 所有子图均使用正确的 ID 语法
• 所有箭头均使用正确的语法（-->, -.->）
• 颜色应用一致
• 已指定布局方向
• 已声明样式
• 没有含糊不清的节点引用
• 与 Obsidian/GitHub 渲染器兼容

参考资料

有关详细语法规则和故障排除，请参阅：

• references/syntax-rules.md - 完整的语法参考和错误预防指南