mcpField
M
mermaid-diagrams

mermaid-diagrams

github.com/davila7开发33.0k908 次安装1 天前更新
代码仓库

关于 mermaid-diagrams

Mermaid-diagrams 是使用 Mermaid 文本语法创建和维护软件图表的技能，适合开发者记录设计与架构，并将图表与代码一同版本管理。

主要功能

  1. 01创建类图与时序图
  2. 02绘制流程图和 ER 图
  3. 03制作 C4、状态及甘特图
  4. 04通过 frontmatter 配置主题
  5. 05支持 Markdown 渲染与图像导出

适用场景

  1. 01记录软件架构与组件关系
  2. 02可视化 API 交互流程
  3. 03设计数据库模式
  4. 04将图表纳入代码版本管理

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/davila7/claude-code-templates --skill mermaid-diagrams

安装后在 Claude Code 中输入/mermaid-diagrams确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
references/
advanced-features.md
c4-diagrams.md
class-diagrams.md
erd-diagrams.md
flowcharts.md
sequence-diagrams.md

详细介绍

Mermaid 图表绘制

使用 Mermaid 基于文本的语法创建专业的软件图表。Mermaid 从简单的文本定义渲染图表，使图表可进行版本控制、易于更新，并能与代码一起维护。

核心语法结构

所有 Mermaid 图表都遵循以下模式：

diagramType
  definition content

关键原则：

  • 第一行声明图表类型（例如 classDiagram、sequenceDiagram、flowchart）
  • 使用 %% 表示注释
  • 换行和缩进可提高可读性，但并非必需
  • 未知词汇会破坏图表；参数会静默失败

图表类型选择指南

选择合适的图表类型：

  1. 类图 - 领域建模、OOP 设计、实体关系

    • 领域驱动设计文档
    • 面向对象的类结构
    • 实体关系与依赖

  2. 时序图 - 时序交互、消息流

    • API 请求/响应流
    • 用户身份验证流
    • 系统组件交互
    • 方法调用序列

  3. 流程图 - 流程、算法、决策树

    • 用户旅程与工作流
    • 业务流程
    • 算法逻辑
    • 部署流水线

  4. 实体关系图（ERD） - 数据库模式

    • 表关系
    • 数据建模
    • 模式设计

  5. C4 图 - 多个层级的软件架构

    • 系统上下文（系统与用户）
    • 容器（应用、数据库、服务）
    • 组件（内部结构）
    • 代码（类/接口级别）

  6. 状态图 - 状态机、生命周期状态

  7. Git 图 - 版本控制分支策略

  8. 甘特图 - 项目时间线、排期

  9. 饼图/条形图 - 数据可视化

快速入门示例

类图（领域模型）
classDiagram
    Title -- Genre
    Title *-- Season
    Title *-- Review
    User --> Review : creates
    
    class Title {
        +string name
        +int releaseYear
        +play()
    }
    
    class Genre {
        +string name
        +getTopTitles()
    }
时序图（API 流）
sequenceDiagram
    participant User
    participant API
    participant Database
    
    User->>API: POST /login
    API->>Database: Query credentials
    Database-->>API: Return user data
    alt Valid credentials
        API-->>User: 200 OK + JWT token
    else Invalid credentials
        API-->>User: 401 Unauthorized
    end
流程图（用户旅程）
flowchart TD
    Start([User visits site]) --> Auth{Authenticated?}
    Auth -->|No| Login[Show login page]
    Auth -->|Yes| Dashboard[Show dashboard]
    Login --> Creds[Enter credentials]
    Creds --> Validate{Valid?}
    Validate -->|Yes| Dashboard
    Validate -->|No| Error[Show error]
    Error --> Login
ERD（数据库模式）
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : includes
    
    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }
    
    ORDER {
        int id PK
        int user_id FK
        decimal total
        datetime created_at
    }

详细参考

有关特定图表类型的深入指导，请参阅：

最佳实践

  1. 从简开始 - 从核心实体/组件开始，逐步添加细节
  2. 使用有意义的名称 - 清晰的标签使图表具有自文档性
  3. 充分注释 - 使用 %% 注释解释复杂关系
  4. 保持聚焦 - 每个概念一张图表；将大型图表拆分为多个聚焦的视图
  5. 版本控制 - 将 .mmd 文件与代码一起存储，便于更新
  6. 添加上下文 - 包含标题和备注以解释图表用途
  7. 迭代 - 随着理解的深入不断完善图表

配置与主题

使用 frontmatter 配置图表：

---
config:
  theme: base
  themeVariables:
    primaryColor: "#ff6b6b"
---
flowchart LR
    A --> B

可用主题： default、forest、dark、neutral、base

布局选项：

  • layout: dagre（默认） - 经典平衡布局
  • layout: elk - 适用于复杂图表的高级布局（需要集成）

外观选项：

  • look: classic - 传统 Mermaid 风格
  • look: handDrawn - 手绘风格外观

导出与渲染

原生支持：

  • GitHub/GitLab - 在 Markdown 中自动渲染
  • VS Code - 配合 Markdown Mermaid 扩展
  • Notion、Obsidian、Confluence - 内置支持

导出选项：

  • Mermaid Live Editor - 支持 PNG/SVG 导出的在线编辑器
  • Mermaid CLI - npm install -g @mermaid-js/mermaid-cli 然后 mmdc -i input.mmd -o output.png
  • Docker - docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png

常见陷阱

  • 破坏性字符 - 避免在注释中使用 {}，对特殊字符使用正确的转义序列
  • 语法错误 - 拼写错误会破坏图表；在 Mermaid Live 中验证语法
  • 过度复杂 - 将复杂图表拆分为多个聚焦的视图
  • 遗漏关系 - 记录实体之间所有重要的连接

何时创建图表

以下情况务必绘制图表：

  • 启动新项目或新功能
  • 记录复杂系统
  • 解释架构决策
  • 设计数据库 schema
  • 规划重构工作
  • 新团队成员入职

使用图表来：

  • 让利益相关者在技术决策上达成一致
  • 协作记录领域模型
  • 可视化数据流和系统交互
  • 在编码前进行规划
  • 创建随代码演进的活文档

评论

支持 Markdown