Principle
Diagrams should clarify, not complicate. Start simple, add detail only when needed. A 5-box flowchart beats a 50-node sprawl.
When User Describes a System or Flow
- 1. Identify diagram type — Is this a flow, architecture, sequence, or data model?
- Choose format — Mermaid (default), PlantUML (complex), ASCII (inline), SVG (custom)
- Draft minimal version — Core elements only, no decoration
- Iterate — Add detail based on feedback
Diagram Types
| Type | Use For | Format |
|---|
| Flowchart | Processes, decisions, workflows | Mermaid INLINECODE0 |
| Sequence |
API calls, interactions, protocols | Mermaid
sequenceDiagram |
| Architecture | System components, infrastructure | Mermaid
flowchart or
C4 |
| ER/Data model | Database schemas, relationships | Mermaid
erDiagram |
| Class | Object structure, inheritance | Mermaid
classDiagram |
| State | Lifecycles, status transitions | Mermaid
stateDiagram-v2 |
| Timeline | Project phases, history | Mermaid
timeline |
| Mindmap | Brainstorming, concept mapping | Mermaid
mindmap |
Output Methods
| Method | When |
|---|
| Mermaid code block | User can render (docs, GitHub, Notion) |
| Render to PNG/SVG |
User needs image file |
| ASCII inline | Quick sketch in chat |
| HTML + Mermaid.js | Interactive viewing |
Rendering Mermaid to Image
CODEBLOCK0
Mermaid Quick Reference
Flowchart:
CODEBLOCK1
Sequence:
CODEBLOCK2
ER Diagram:
CODEBLOCK3
Style Guidelines
- - Left-to-right (LR) for processes, top-to-bottom (TB) for hierarchies
- Max 10-15 nodes per diagram, split if larger
- Consistent naming — all caps for systems, lowercase for actions
- Subgraphs to group related components
- Color sparingly — highlight critical paths only
Common Requests
| Request | Interpret As |
|---|
| "Draw my API flow" | Sequence diagram: client → API → services |
| "Show the architecture" |
Flowchart with subgraphs for components |
| "Database schema" | ER diagram with relationships |
| "How the auth works" | Sequence or flowchart depending on complexity |
| "User journey" | Flowchart with decision points |
Anti-Patterns
- - ❌ Too many nodes (split into multiple diagrams)
- ❌ Decorative icons without meaning
- ❌ Mixing abstraction levels (database tables next to business concepts)
- ❌ Arrows in all directions (confuses flow)
- ❌ Labels too long (use short names, add legend if needed)
原理
图表应厘清关系，而非制造混乱。从简入手，仅在必要时添加细节。一个5框流程图胜过50个节点的杂乱铺陈。
当用户描述系统或流程时
- 1. 确定图表类型——这是流程图、架构图、时序图还是数据模型？
- 选择格式——Mermaid（默认）、PlantUML（复杂场景）、ASCII（行内嵌入）、SVG（自定义）
- 绘制最小版本——仅包含核心元素，无需装饰
- 迭代优化——根据反馈补充细节
图表类型
| 类型 | 适用场景 | 格式 |
|---|
| 流程图 | 流程、决策、工作流 | Mermaid flowchart |
| 时序图 |
API调用、交互、协议 | Mermaid sequenceDiagram |
| 架构图 | 系统组件、基础设施 | Mermaid flowchart 或 C4 |
| ER/数据模型 | 数据库模式、关系 | Mermaid erDiagram |
| 类图 | 对象结构、继承关系 | Mermaid classDiagram |
| 状态图 | 生命周期、状态转换 | Mermaid stateDiagram-v2 |
| 时间线 | 项目阶段、历史记录 | Mermaid timeline |
| 思维导图 | 头脑风暴、概念映射 | Mermaid mindmap |
输出方式
| 方式 | 适用场景 |
|---|
| Mermaid代码块 | 用户可渲染（文档、GitHub、Notion） |
| 渲染为PNG/SVG |
用户需要图片文件 |
| ASCII行内嵌入 | 聊天中的快速草图 |
| HTML + Mermaid.js | 交互式查看 |
将Mermaid渲染为图片
bash
使用mmdc (mermaid-cli)
npx -y @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.png -b transparent
或通过浏览器工具
编写含Mermaid的HTML，截图渲染后的图表
Mermaid快速参考
流程图：
mermaid
flowchart LR
A[开始] --> B{决策}
B -->|是| C[操作]
B -->|否| D[结束]
时序图：
mermaid
sequenceDiagram
用户->>API: 请求
API->>数据库: 查询
数据库-->>API: 结果
API-->>用户: 响应
ER图：
mermaid
erDiagram
用户 ||--o{ 订单 : 下单
订单 ||--|{ 商品 : 包含
样式指南
- - 流程采用从左到右（LR），层级结构采用从上到下（TB）
- 每张图表最多10-15个节点，超出则拆分
- 命名一致——系统用大写，操作用小写
- 使用子图对相关组件进行分组
- 谨慎使用颜色——仅高亮关键路径
常见请求
| 请求 | 解读方式 |
|---|
| 绘制我的API流程 | 时序图：客户端 → API → 服务 |
| 展示架构 |
含组件子图的流程图 |
| 数据库模式 | 含关系的ER图 |
| 认证如何工作 | 根据复杂度选择时序图或流程图 |
| 用户旅程 | 含决策点的流程图 |
反模式
- - ❌ 节点过多（拆分为多张图表）
- ❌ 无意义的装饰性图标
- ❌ 混合不同抽象层级（数据库表与业务概念并列）
- ❌ 箭头方向混乱（干扰流程理解）
- ❌ 标签过长（使用简短名称，必要时添加图例）
