mermaid-diagram-generator

Mermaid 图表生成技能

目的

此技能可自动将系统架构、模块规范、工作流文档和设计概念的文本描述转换为有效的 Mermaid 图表语法。它有助于清晰地呈现复杂系统，确保生成的图表可用于生产环境，并可嵌入 Markdown 文档。

何时使用此技能

• 架构可视化：将架构描述转换为流程图或框图
• 模块关系：创建图表，展示各砖块模块如何通过其连接点（公共契约）相连
• 工作流文档：可视化工作流状态、决策和转换（DDD 阶段、调查阶段）
• 系统设计：展示系统组件、数据流和交互
• 时序图：展示 Agent 交互、请求/响应模式或调用序列
• 类层次结构：记录模块结构和类之间的关系
• 状态机：对工作流状态和有效转换进行建模
• 实体关系：展示数据模型结构和关系
• 时间线规划：为项目阶段或里程碑创建甘特图

支持的图表类型

1. 流程图（默认）

适用于：工作流序列、决策树、流程、模块关系

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action A]
    B -->|No| D[Action B]
    C --> E[End]
    D --> E

2. 时序图

适用于：Agent 交互、API 调用、多步骤流程、请求/响应模式

sequenceDiagram
    participant User
    participant API
    participant Service
    User->>API: Request
    API->>Service: Process
    Service-->>API: Response
    API-->>User: Result

3. 类图

适用于：模块结构、继承层次结构、数据模型、组件关系

classDiagram
    class Brick {
        +String responsibility
        +PublicContract studs
    }
    class Module {
        +init()
        +process()
    }
    Brick <|-- Module

4. 状态图

适用于：工作流状态、状态机、工作流阶段、基于条件的转换

stateDiagram-v2
    [*] --> Planning
    Planning --> Design
    Design --> Implementation
    Implementation --> Testing
    Testing --> [*]

5. 实体关系图

适用于：数据模型、数据库架构、实体关系

erDiagram
    MODULE ||--o{ FUNCTION : exports
    MODULE ||--o{ DEPENDENCY : requires
    FUNCTION }o--|| CONTRACT : implements

6. 甘特图

适用于：项目时间线、工作流阶段、里程碑规划

gantt
    title Project Timeline
    section Phase 1
    Planning :p1, 0, 30d
    Design :p2, after p1, 20d
    section Phase 2
    Implementation :p3, after p2, 40d
    Testing :p4, after p3, 25d

分步生成流程

第 1 步：理解源材料

1. 阅读架构描述、规范或工作流文档
2. 确定主要实体或节点
3. 确定它们之间的关系或流向
4. 选择合适的图表类型

第 2 步：确定图表类型

源材料	最适合的图表类型
工作流步骤、流程	流程图
模块关系、砖块连接	流程图或类图
Agent 交互、调用序列	时序图
状态和转换	状态图
数据模型、实体	类图或 ERD
数据库架构	ERD
项目时间线	甘特图
复杂层次结构	类图

第 3 步：提取实体和关系

1. 列出源材料中的所有节点/实体
2. 确定它们之间的连接
3. 确定连接类型（数据流、继承、调用等）
4. 标注决策点或条件

第 4 步：生成 Mermaid 语法

1. 使用合适的 Mermaid 图表声明
2. 创建带有描述性标签的节点
3. 使用正确的语法绘制连接
4. 如有需要，添加样式以提高清晰度
5. 确保 Mermaid 语法有效

第 5 步：验证和优化

1. 确保包含所有实体
2. 确认连接准确无误
3. 为重要元素添加样式
4. 确保图表易于阅读且不杂乱
5. 测试语法是否有效

第 6 步：记录和嵌入

1. 添加标题和说明
2. 包含图表说明
3. 如有需要，提供图例
4. 使用正确的格式嵌入 Markdown

使用示例

示例 1：将架构描述转换为流程图

输入：

The authentication module handles JWT token validation. When a request arrives,
it first checks if a token exists. If not, it returns unauthorized. If it does,
it validates the token signature. If valid, it extracts the payload and continues.
If invalid, it returns forbidden. The payload is passed to the authorization
module for role-based access control.

输出：

flowchart TD
    A[Request Arrives] --> B{Token Exists?}
    B -->|No| C[Return Unauthorized]
    B -->|Yes| D{Token Valid?}
    D -->|No| E[Return Forbidden]
    D -->|Yes| F[Extract Payload]
    F --> G[Check Role-Based Access]
    G --> H{Authorized?}
    H -->|No| I[Return Access Denied]
    H -->|Yes| J[Allow Request]
    C --> K[End]
    E --> K
    I --> K
    J --> K

示例 2：模块规范转类图

输入：

Module: authentication
- Exports: validate_token, TokenPayload, AuthError
- Classes: TokenPayload (user_id, role, expires_at), AuthError (message, code)
- Functions: validate_token(token, secret) -> TokenPayload
- Internal: JWT (PyJWT library), Models (TokenPayload)

输出：

classDiagram
    class AuthenticationModule {
        +validate_token(token, secret)
        +TokenPayload
        +AuthError
    }
    class TokenPayload {
        +String user_id
        +String role
        +DateTime expires_at
        +to_dict()
    }
    class AuthError {
        +String message
        +Integer code
        +__str__()
    }
    AuthenticationModule -- TokenPayload
    AuthenticationModule -- AuthError

示例 3：工作流转状态图

输入：

DDD Workflow: Phase 0 (Planning) -> Phase 1 (Documentation) ->
Approval Gate -> Phase 2 (Code Planning) -> Phase 3 (Implementation) ->
Phase 4 (Testing & Cleanup) -> Complete

输出：

stateDiagram-v2
    [*] --> Planning
    Planning --> Documentation
    Documentation --> ApprovalGate
    ApprovalGate --> CodePlanning
    CodePlanning --> Implementation
    Implementation --> Testing
    Testing --> [*]

示例 4：Agent 交互转序列图

输入：

The prompt-writer agent clarifies requirements from the user. It then sends
the clarified requirements to the architect agent. The architect creates a
specification and sends it to the builder agent. The builder implements code
and sends it to the reviewer. The reviewer checks quality and sends feedback
back to the builder if issues are found, or to the user if complete.

输出：

sequenceDiagram
    actor User
    participant PromptWriter
    participant Architect
    participant Builder
    participant Reviewer

    User->>PromptWriter: Request Feature
    PromptWriter->>Architect: Clarified Requirements
    Architect->>Builder: Specification
    Builder->>Reviewer: Implementation
    Reviewer-->>Builder: Issues Found
    Builder->>Reviewer: Fixed Implementation
    Reviewer-->>User: Complete & Approved

示例 5：系统架构转流程图

输入：

Client requests flow through API Gateway to Services. Services can be
Authentication Service, User Service, or Data Service. All services
connect to a shared Database and Logger. Services return responses
through the API Gateway back to Client.

输出：

flowchart LR
    Client[Client]
    Gateway[API Gateway]
    Auth[Auth Service]
    User[User Service]
    Data[Data Service]
    DB[(Database)]
    Logger[Logger]

    Client <--> Gateway
    Gateway --> Auth
    Gateway --> User
    Gateway --> Data
    Auth --> DB
    User --> DB
    Data --> DB
    Auth --> Logger
    User --> Logger
    Data --> Logger

Mermaid 语法参考

流程图节点

A[Rectangle]
B(Rounded Rectangle)
C{Diamond/Decision}
D[(Database)]
E[/Parallelogram Right/]
F[\Parallelogram Left\]
G[[Subroutine]]
H((Circle))

流程图连接

A --> B          # Arrow
A -- Text --> B  # Arrow with label
A ---|Yes| B     # Arrow with yes/no
A -->|Condition| B
A -.-> B         # Dotted line
A ==> B          # Bold arrow

样式

classDef className fill:#f9f,stroke:#333,stroke-width:2px,color:#000
class A,B className
style A fill:#f9f,stroke:#333,stroke-width:4px

质量检查清单

展示图表前，请确认：

• 包含源内容中的所有实体
• 连接准确表示实体之间的关系
• 图表类型与内容相匹配（流程使用流程图，交互使用序列图等）
• 标签清晰且具有描述性
• 不存在循环逻辑或死路（有意设计的除外）
• Mermaid 语法有效
• 图表易于阅读，且不过于复杂
• 决策点具有明确的“是／否”路径
• 如有助于理解，请提供图例
• 注释能够解释不明显的元素

常见模式

Brick 模块可视化

flowchart TD
    B1["Brick Module 1<br/>(Responsibility)"]
    B2["Brick Module 2<br/>(Responsibility)"]
    S1["Stud: public_function"]
    S2["Stud: public_class"]

    B1 --> S1
    B1 --> S2
    S1 -.depends on.-> B2
    B2 --> "Stud: get_data"

工作流决策树

flowchart TD
    Start[Start] --> Q1{Condition 1?}
    Q1 -->|No| End1[End: Rejected]
    Q1 -->|Yes| Q2{Condition 2?}
    Q2 -->|No| End2[End: Review]
    Q2 -->|Yes| Q3{Condition 3?}
    Q3 -->|No| End3[End: Partial]
    Q3 -->|Yes| End4[End: Approved]

错误处理流程

flowchart TD
    A[Execute] --> B{Error?}
    B -->|No| C[Success]
    B -->|Yes| D{Recoverable?}
    D -->|No| E[Fail]
    D -->|Yes| F[Retry]
    F --> A
    C --> G[End]
    E --> G

与文档集成

在 Markdown 中嵌入

## System Architecture

```mermaid
flowchart TD
    ...
```

关键组件：

• 组件 A 负责处理……
• 组件 B 负责处理……

### Using with Document-Driven Development
- Create diagrams during documentation phase
- Include architecture diagrams in spec docs
- Use sequence diagrams to explain workflows
- Add state diagrams to describe state machines

### Using with Investigation Workflow
- Visualize discovered architecture
- Show data flow between components
- Map discovered dependencies
- Display call sequences between services

## Tips for Effective Diagrams

1. **Keep It Simple**: One concept per diagram
2. **Use Clear Labels**: Names should describe purpose
3. **Follow Visual Conventions**: Diamonds for decisions, circles for states
4. **Avoid Crossing Lines**: Reorganize to reduce visual clutter
5. **Logical Flow**: Top-to-bottom or left-to-right
6. **Consistent Styling**: Similar elements should look similar
7. **Legend**: Include if symbols aren't obvious
8. **Test Syntax**: Ensure Mermaid renders without errors
9. **Add Comments**: Explain non-obvious relationships
10. **Iterate**: Refine based on feedback

## Common Pitfalls to Avoid

- **Too Complex**: Diagram has too many elements (break into multiple diagrams)
- **Unclear Labels**: Node names don't describe their purpose
- **Missing Connections**: Important relationships not shown
- **Invalid Syntax**: Mermaid errors prevent rendering
- **Ambiguous Decision Points**: Yes/no paths not clearly marked
- **Crossing Arrows**: Visual confusion from overlapping connections
- **No Legend**: Symbols or colors not explained
- **Wrong Diagram Type**: Using flowchart for sequence data
- **Inconsistent Style**: Different formatting for similar elements
- **No Context**: Diagram shown without explanation

## Success Criteria

A good Mermaid diagram:
- [ ] Shows all key entities from source material
- [ ] Accurately represents relationships and flow
- [ ] Uses appropriate diagram type for content
- [ ] Clear, descriptive labels on all nodes
- [ ] Valid Mermaid syntax (renders without error)
- [ ] Readable without excessive complexity
- [ ] Supports understanding of the system
- [ ] Could be embedded in documentation
- [ ] Decision points clearly marked
- [ ] Legend included if needed
- [ ] Purpose and scope clear from context

## Related Skills

- **module-spec-generator**: Generate specs that can be visualized as class diagrams
- **Document-Driven Development**: Use diagrams in specification documents
- **Investigation Workflow**: Create architecture diagrams from discovered systems

## Output Format

Diagrams are generated in Mermaid markdown format, ready to embed:

```markdown
    ```mermaid
    [Generated Mermaid Syntax]
    ```

在图表之前或之后添加说明。

反馈与改进

此技能会根据使用模式不断演进：

• 哪些类型的图表最有用？
• 哪些特性可以让图表更清晰？
• 会出现哪些错误，该如何预防？
• 如何让图表更好地支持文档？

记录经验并为 ~/.amplihack/.claude/context/DISCOVERIES.md 提出改进建议。