diagrams-kroki

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Diagram Generation with Kroki

用Kroki生成图表

MCP Setup

MCP 配置

Add to

.claude/mcp.json

json

{
  "mcpServers": {
    "uml": {
      "command": "uvx",
      "args": ["uml-mcp"],
      "env": { "KROKI_SERVER": "https://kroki.io" }
    }
  }
}

Self-hosted:

podman run -d -p 8000:8000 yuzutech/kroki

添加到

.claude/mcp.json

：

json

{
  "mcpServers": {
    "uml": {
      "command": "uvx",
      "args": ["uml-mcp"],
      "env": { "KROKI_SERVER": "https://kroki.io" }
    }
  }
}

自托管部署命令：

podman run -d -p 8000:8000 yuzutech/kroki

Quick Reference

快速参考

Diagram Type	Syntax	Best For
C4 Context/Container	PlantUML + C4 stdlib	Architecture overview
Sequence	PlantUML	API flows, interactions
Class	PlantUML	Domain models
State	PlantUML or Mermaid	State machines
Flowchart	Mermaid	Simple flows, decisions
ERD	DBML or PlantUML	Database schemas
Network/Infra	D2	Modern architecture

图表类型	语法	适用场景
C4 上下文/容器	PlantUML + C4 标准库	架构概览
时序图	PlantUML	API 流程、交互逻辑
类图	PlantUML	领域模型
状态图	PlantUML 或 Mermaid	状态机
流程图	Mermaid	简单流程、决策逻辑
ERD	DBML 或 PlantUML	数据库 Schema
网络/基础设施图	D2	现代化架构

C4 Diagrams

C4 图

Context Diagram

上下文图

plantuml

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

Person(user, "User", "Description")
System(system, "System", "What it does")
System_Ext(external, "External", "Third party")

Rel(user, system, "Uses")
Rel(system, external, "Calls")
SHOW_LEGEND()
@enduml

plantuml

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

Person(user, "User", "Description")
System(system, "System", "What it does")
System_Ext(external, "External", "Third party")

Rel(user, system, "Uses")
Rel(system, external, "Calls")
SHOW_LEGEND()
@enduml

Container Diagram

容器图

plantuml

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(user, "User")
System_Boundary(system, "System") {
    Container(web, "Web App", "React", "UI")
    Container(api, "API", "Go", "Business logic")
    ContainerDb(db, "Database", "PostgreSQL", "Data store")
}

Rel(user, web, "Uses", "HTTPS")
Rel(web, api, "Calls", "JSON/HTTPS")
Rel(api, db, "Reads/Writes", "SQL")
SHOW_LEGEND()
@enduml

plantuml

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(user, "User")
System_Boundary(system, "System") {
    Container(web, "Web App", "React", "UI")
    Container(api, "API", "Go", "Business logic")
    ContainerDb(db, "Database", "PostgreSQL", "Data store")
}

Rel(user, web, "Uses", "HTTPS")
Rel(web, api, "Calls", "JSON/HTTPS")
Rel(api, db, "Reads/Writes", "SQL")
SHOW_LEGEND()
@enduml

Sequence Diagrams

时序图

plantuml

@startuml
actor User
participant "Web" as W
participant "API" as A
database "DB" as D

User -> W: Submit form
activate W
W -> A: POST /resource
activate A
A -> D: INSERT
D --> A: OK
A --> W: 201 Created
deactivate A
W --> User: Success
deactivate W
@enduml

plantuml

@startuml
actor User
participant "Web" as W
participant "API" as A
database "DB" as D

User -> W: Submit form
activate W
W -> A: POST /resource
activate A
A -> D: INSERT
D --> A: OK
A --> W: 201 Created
deactivate A
W --> User: Success
deactivate W
@enduml

State Machines

状态机

plantuml

@startuml
[*] --> Draft
Draft --> Pending : submit
Pending --> Approved : approve
Pending --> Rejected : reject
Approved --> Active : activate
Active --> [*] : complete
Rejected --> Draft : revise
@enduml

plantuml

@startuml
[*] --> Draft
Draft --> Pending : submit
Pending --> Approved : approve
Pending --> Rejected : reject
Approved --> Active : activate
Active --> [*] : complete
Rejected --> Draft : revise
@enduml

Flowcharts (Mermaid)

流程图（Mermaid）

mermaid

flowchart TD
    A[Start] --> B{Condition?}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

mermaid

flowchart TD
    A[Start] --> B{Condition?}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Entity Relationships (DBML)

实体关系图（DBML）

dbml

Table users {
  id uuid [pk]
  email varchar [unique, not null]
  created_at timestamp [default: `now()`]
}

Table orders {
  id uuid [pk]
  user_id uuid [ref: > users.id]
  status order_status
}

Enum order_status {
  pending
  completed
  cancelled
}

dbml

Table users {
  id uuid [pk]
  email varchar [unique, not null]
  created_at timestamp [default: `now()`]
}

Table orders {
  id uuid [pk]
  user_id uuid [ref: > users.id]
  status order_status
}

Enum order_status {
  pending
  completed
  cancelled
}

D2 Architecture

D2 架构图

direction: right

user: User { shape: person }
system: {
  web: Web App
  api: API
  db: Database { shape: cylinder }

  web -> api: REST
  api -> db: SQL
}
external: External API { shape: cloud }

user -> system.web
system.api -> external

direction: right

user: User { shape: person }
system: {
  web: Web App
  api: API
  db: Database { shape: cylinder }

  web -> api: REST
  api -> db: SQL
}
external: External API { shape: cloud }

user -> system.web
system.api -> external

File Organization

文件组织规范

diagrams/
├── architecture/
│   ├── c4-context.puml
│   └── c4-container.puml
├── behavior/
│   ├── sequence-{flow}.puml
│   └── state-{entity}.puml
├── data/
│   └── erd-{domain}.dbml
└── rendered/
    ├── png/
    └── svg/

diagrams/
├── architecture/
│   ├── c4-context.puml
│   └── c4-container.puml
├── behavior/
│   ├── sequence-{flow}.puml
│   └── state-{entity}.puml
├── data/
│   └── erd-{domain}.dbml
└── rendered/
    ├── png/
    └── svg/

Workflow

工作流

Choose diagram type based on what you're documenting
Write diagram source using appropriate syntax
Render via MCP:
```
uml:render_plantuml
```
or
```
uml:render_mermaid
```
Save source to
```
diagrams/
```
directory
Generated images go to
```
diagrams/rendered/
```

根据要记录的内容选择图表类型
使用对应语法编写图表源码
通过 MCP 渲染：
```
uml:render_plantuml
```
或
```
uml:render_mermaid
```
将源码保存到
```
diagrams/
```
目录
生成的图片存放到
```
diagrams/rendered/
```

Naming Convention

命名规范

{type}-{subject}.{ext}

Examples:

```
c4-context.puml
```
```
sequence-user-login.puml
```
```
state-order.puml
```
```
erd-users.dbml
```

{类型}-{主题}.{后缀}

示例：

```
c4-context.puml
```
```
sequence-user-login.puml
```
```
state-order.puml
```
```
erd-users.dbml
```