plantuml-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PlantUML Diagram Skill

PlantUML 图表生成技能

Overview

概述

Generate

.puml

PlantUML diagram files and export to PNG/SVG using Kroki — a cloud rendering API that requires no local installation beyond

curl

Format:

.puml

(PlantUML text) Renderer: Kroki API (

https://kroki.io

) — just

curl

, no Java needed Output: PNG, SVG Diagram types: sequence, component, class, ER, activity, use case, state, C4, and more

使用Kroki（一款云渲染API，仅需

curl

即可使用，无需额外本地安装）生成

.puml

格式的PlantUML图表文件，并导出为PNG/SVG格式。

格式：

.puml

（PlantUML文本格式） 渲染器： Kroki API (

https://kroki.io

) — 仅需

curl

，无需Java环境 输出格式： PNG、SVG 支持的图表类型： 时序图、组件图、类图、ER图、活动图、用例图、状态图、C4架构图等

When to Use

使用场景

Explicit triggers:

"plantuml diagram", "sequence diagram", "class diagram", "component diagram"
"UML", "activity diagram", "use case diagram", "state machine"
"visualize", "draw", "diagram", "flowchart", "architecture chart"

Proactive triggers:

Explaining a system with 3+ interacting components
Describing API flows, authentication sequences, message passing
Showing class hierarchies, database schemas, or ER models
Illustrating state machines or lifecycle flows

明确触发场景：

"plantuml diagram", "sequence diagram", "class diagram", "component diagram"
"UML", "activity diagram", "use case diagram", "state machine"
"visualize", "draw", "diagram", "flowchart", "architecture chart"

主动触发场景：

解释包含3个及以上交互组件的系统
描述API流程、认证序列、消息传递机制
展示类层级结构、数据库模式或ER模型
说明状态机或生命周期流程

Prerequisites

前置条件

Option A: Kroki API (recommended — no install)

bash

undefined

选项A：Kroki API（推荐——无需安装）

bash

undefined

Just needs curl (pre-installed on macOS/Linux/Windows Git Bash)

仅需curl（macOS/Linux/Windows Git Bash默认已安装）

curl --version


**Option B: Local Kroki via Docker (for offline use)**
```bash
docker run -d -p 8000:8000 yuzutech/kroki

curl --version


**选项B：通过Docker运行本地Kroki（用于离线使用）**
```bash
docker run -d -p 8000:8000 yuzutech/kroki

Then replace https://kroki.io with http://localhost:8000 in commands

之后将命令中的https://kroki.io替换为http://localhost:8000


**Option C: Local PlantUML jar (traditional)**
```bash


**选项C：本地PlantUML jar包（传统方式）**
```bash

Requires Java + Graphviz

需要Java + Graphviz

brew install graphviz # macOS sudo apt install graphviz # Ubuntu

brew install graphviz # macOS系统 sudo apt install graphviz # Ubuntu系统

Download plantuml.jar from https://plantuml.com/download

从https://plantuml.com/download下载plantuml.jar

java -jar plantuml.jar diagram.puml

undefined

java -jar plantuml.jar diagram.puml

undefined

Workflow

工作流程

Step 0. Update check (notify, don't pull) — first use per conversation

步骤0. 更新检查（仅通知，不自动拉取）—— 每次会话首次使用时执行

Throttle to one check per 24 hours per installation; never mutate the skill directory without explicit user consent.

If
```
<this-skill-dir>/.last_update
```
exists and is less than 24 hours old, skip this step entirely.

Otherwise, fetch the latest tag from upstream:

bash

git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
  | awk '{print $2}' | sed 's|refs/tags/||' \
  | sort -V | tail -1

Compare with this skill's
```
metadata.version
```
from the frontmatter. If the upstream tag is strictly newer (semver), tell the user one line and ask:
"A newer version of this skill is available: vX.Y.Z → vA.B.C. Want me to
```
git pull
```
?"
If they say yes, run
```
git -C <this-skill-dir> pull --ff-only
```
. Refresh
```
.last_update
```
either way so the prompt doesn't repeat for 24 hours.
If upstream is the same or older, refresh
```
.last_update
```
silently and continue.
On any failure (offline, not a git checkout — e.g. ClawHub-installed copy, read-only path, no permission), swallow the error silently and continue with the user's task. Do not mention the failure.

限制为每个安装实例24小时检查一次；未经用户明确同意，绝不修改技能目录。

如果
```
<this-skill-dir>/.last_update
```
文件存在且创建时间不超过24小时，直接跳过此步骤。

否则，从上游仓库获取最新版本标签：

bash

git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
  | awk '{print $2}' | sed 's|refs/tags/||' \
  | sort -V | tail -1

将其与技能前置元数据中的
```
metadata.version
```
进行比较。如果上游版本标签更新（遵循语义化版本规则），向用户发送一行提示并询问：
"此技能有新版本可用：vX.Y.Z → vA.B.C。是否需要执行
```
git pull
```
更新？"
如果用户同意，执行
```
git -C <this-skill-dir> pull --ff-only
```
。无论用户是否同意，都刷新
```
.last_update
```
文件，确保24小时内不再重复提示。
如果上游版本与当前版本相同或更旧，静默刷新
```
.last_update
```
文件并继续执行后续步骤。
如果出现任何失败（离线、非Git检出目录——例如ClawHub安装的副本、只读路径、无权限），静默忽略错误并继续执行用户任务，不得提及失败情况。

Step 1: Check Dependencies

步骤1：检查依赖

bash

curl --version

curl is available on all modern systems. If missing, install via package manager.

bash

curl --version

curl在所有现代系统中均已预装。如果缺失，可通过包管理器安装。

Step 2: Pick Diagram Type

步骤2：选择图表类型

Choose the most appropriate PlantUML diagram type (see reference below).

选择最适合的PlantUML图表类型（参考下方图表类型列表）。

Step 3: Generate .puml File

步骤3：生成.puml文件

Write the PlantUML source file with

@startuml

@enduml

markers.

编写包含

@startuml

@enduml

标记的PlantUML源文件。

Step 4: Export via Kroki

步骤4：通过Kroki导出

bash

undefined

bash

undefined

PNG (recommended)

PNG格式（推荐）

curl -s -X POST https://kroki.io/plantuml/png
-H "Content-Type: text/plain"
--data-binary "@diagram.puml"
-o diagram.png

SVG

SVG格式

curl -s -X POST https://kroki.io/plantuml/svg
-H "Content-Type: text/plain"
--data-binary "@diagram.puml"
-o diagram.svg

undefined

curl -s -X POST https://kroki.io/plantuml/svg
-H "Content-Type: text/plain"
--data-binary "@diagram.puml"
-o diagram.svg

undefined

Step 5: Report to User

步骤5：向用户反馈

Tell the user:

Path to the
```
.puml
```
source file
Path to the exported PNG/SVG
Brief description of what was generated

告知用户：

```
.puml
```
源文件的路径
导出的PNG/SVG文件的路径
生成内容的简要说明

Diagram Types

图表类型

Type	Keyword	Use for
Sequence	`@startuml` + sequence syntax	API calls, protocol flows, message passing
Component	`@startuml` + components	service architecture, module dependencies
Class	`@startuml` + class syntax	OOP models, data structures
ER / Entity	`@startuml` + entity syntax	database schemas
Activity	`@startuml` + activity syntax	workflows, business processes
Use Case	`@startuml` + actor/usecase	system requirements, user stories
State	`@startuml` + state syntax	state machines, lifecycle
C4 Context	`@startuml` + C4 includes	high-level system context maps
Mind Map	`@startmindmap`	topic breakdowns, concept maps
Gantt	`@startgantt`	project timelines, schedules

类型	关键字	适用场景
时序图	`@startuml` + 时序图语法	API调用、协议流程、消息传递
组件图	`@startuml` + 组件图语法	服务架构、模块依赖
类图	`@startuml` + 类图语法	面向对象模型、数据结构
ER/实体图	`@startuml` + 实体图语法	数据库模式
活动图	`@startuml` + 活动图语法	工作流、业务流程
用例图	`@startuml` + actor/usecase语法	系统需求、用户故事
状态图	`@startuml` + 状态图语法	状态机、生命周期
C4上下文图	`@startuml` + C4引用	高层系统上下文映射
思维导图	`@startmindmap`	主题分解、概念图
甘特图	`@startgantt`	项目时间线、进度计划

Syntax Reference

语法参考

Component / Architecture Diagram

组件/架构图

plantuml

@startuml
!theme plain

title Microservices Architecture

actor "Client" as client
rectangle "API Gateway" as gateway #LightBlue

rectangle "Services" {
  component "User Service" as user
  component "Order Service" as order
}

database "User DB" as userdb
database "Order DB" as orderdb
queue "Kafka" as kafka

client --> gateway
gateway --> user
gateway --> order
user --> userdb
order --> orderdb
order --> kafka : events

@enduml

Shape types:

```
actor "Name" as id
```
— stick figure (user, external actor)
```
component "Name" as id
```
— component box with [brackets]
```
rectangle "Name" as id
```
— plain rectangle (for groups/layers)
```
database "Name" as id
```
— cylinder (database)
```
queue "Name" as id
```
— queue symbol
```
cloud "Name" as id
```
— cloud shape (external services)
```
node "Name" as id
```
— server/node box
```
frame "Name" as id
```
— frame grouping
```
package "Name" { }
```
— package grouping

Arrows:

```
A --> B
```
— solid arrow
```
A -> B
```
— thin arrow
```
A ..> B
```
— dashed arrow
```
A --> B : label
```
— labeled arrow
```
A <--> B
```
— bidirectional

Colors:

#LightBlue

#LightGreen

#LightYellow

#Pink

#Violet

```
#AED6F1
```
(blue),
```
#A9DFBF
```
(green),
```
#FAD7A0
```
(orange),
```
#F1948A
```
(red)
```
#D7BDE2
```
(purple),
```
#F9E79F
```
(yellow),
```
#D3D3D3
```
(grey)

plantuml

@startuml
!theme plain

title Microservices Architecture

actor "Client" as client
rectangle "API Gateway" as gateway #LightBlue

rectangle "Services" {
  component "User Service" as user
  component "Order Service" as order
}

database "User DB" as userdb
database "Order DB" as orderdb
queue "Kafka" as kafka

client --> gateway
gateway --> user
gateway --> order
user --> userdb
order --> orderdb
order --> kafka : events

@enduml

形状类型：

```
actor "Name" as id
```
— 角色人形图（用户、外部参与者）
```
component "Name" as id
```
— 带方括号的组件框
```
rectangle "Name" as id
```
— 普通矩形（用于分组/分层）
```
database "Name" as id
```
— 圆柱形状（数据库）
```
queue "Name" as id
```
— 队列符号
```
cloud "Name" as id
```
— 云形状（外部服务）
```
node "Name" as id
```
— 服务器/节点框
```
frame "Name" as id
```
— 框架分组
```
package "Name" { }
```
— 包分组

箭头类型：

```
A --> B
```
— 实心箭头
```
A -> B
```
— 细箭头
```
A ..> B
```
— 虚线箭头
```
A --> B : label
```
— 带标签的箭头
```
A <--> B
```
— 双向箭头

颜色：

#LightBlue

#LightGreen

#LightYellow

#Pink

#Violet

```
#AED6F1
```
（蓝色）,
```
#A9DFBF
```
（绿色）,
```
#FAD7A0
```
（橙色）,
```
#F1948A
```
（红色）
```
#D7BDE2
```
（紫色）,
```
#F9E79F
```
（黄色）,
```
#D3D3D3
```
（灰色）

Sequence Diagram

时序图

plantuml

@startuml
!theme plain
title Login Flow

participant "Client" as C
participant "API Gateway" as G
participant "Auth Service" as A
database "User DB" as D

C -> G : POST /login
G -> A : validateCredentials(user, pass)
A -> D : SELECT * FROM users WHERE email = ?
D --> A : user record
A --> G : 200 OK + JWT token
G --> C : { token: "..." }

@enduml

Arrow types:

```
A -> B
```
— synchronous call
```
A --> B
```
— return / dashed
```
A ->> B
```
— async message
```
A -[#red]-> B
```
— colored arrow
```
activate A
```
/
```
deactivate A
```
— show activation box

plantuml

@startuml
!theme plain
title Login Flow

participant "Client" as C
participant "API Gateway" as G
participant "Auth Service" as A
database "User DB" as D

C -> G : POST /login
G -> A : validateCredentials(user, pass)
A -> D : SELECT * FROM users WHERE email = ?
D --> A : user record
A --> G : 200 OK + JWT token
G --> C : { token: "..." }

@enduml

箭头类型：

```
A -> B
```
— 同步调用
```
A --> B
```
— 返回/虚线箭头
```
A ->> B
```
— 异步消息
```
A -[#red]-> B
```
— 带颜色的箭头
```
activate A
```
/
```
deactivate A
```
— 显示激活框

Class Diagram

类图

plantuml

@startuml
!theme plain

class User {
  +int id
  +String name
  +String email
  +login() : bool
  +logout()
}

class Order {
  +int id
  +Date createdAt
  +float total
  +place()
  +cancel()
}

class Product {
  +int id
  +String name
  +float price
}

User "1" --> "*" Order : places
Order "*" --> "*" Product : contains

@enduml

Relationships:

```
A --> B
```
— association
```
A --|> B
```
— inheritance
```
A ..|> B
```
— implements interface
```
A *-- B
```
— composition
```
A o-- B
```
— aggregation
```
A "1" --> "*" B : label
```
— with multiplicities

plantuml

@startuml
!theme plain

class User {
  +int id
  +String name
  +String email
  +login() : bool
  +logout()
}

class Order {
  +int id
  +Date createdAt
  +float total
  +place()
  +cancel()
}

class Product {
  +int id
  +String name
  +float price
}

User "1" --> "*" Order : places
Order "*" --> "*" Product : contains

@enduml

关系类型：

```
A --> B
```
— 关联关系
```
A --|> B
```
— 继承关系
```
A ..|> B
```
— 接口实现
```
A *-- B
```
— 组合关系
```
A o-- B
```
— 聚合关系
```
A "1" --> "*" B : label
```
— 带多重性的关系

ER Diagram

ER图

plantuml

@startuml
!theme plain

entity "USER" as user {
  * id : int <<PK>>
  --
  name : varchar
  email : varchar
  created_at : datetime
}

entity "ORDER" as ord {
  * id : int <<PK>>
  --
  * user_id : int <<FK>>
  total : decimal
  status : varchar
}

entity "PRODUCT" as prod {
  * id : int <<PK>>
  --
  name : varchar
  price : decimal
}

user ||--o{ ord : places
ord }o--|{ prod : contains

@enduml

plantuml

@startuml
!theme plain

entity "USER" as user {
  * id : int <<PK>>
  --
  name : varchar
  email : varchar
  created_at : datetime
}

entity "ORDER" as ord {
  * id : int <<PK>>
  --
  * user_id : int <<FK>>
  total : decimal
  status : varchar
}

entity "PRODUCT" as prod {
  * id : int <<PK>>
  --
  name : varchar
  price : decimal
}

user ||--o{ ord : places
ord }o--|{ prod : contains

@enduml

Activity / Flowchart

活动图/流程图

plantuml

@startuml
!theme plain

start

:Receive Order;

if (Payment valid?) then (yes)
  :Process Payment;
  :Send Confirmation Email;
  :Update Inventory;
  :Ship Order;
  :Mark as Delivered;
else (no)
  :Send Payment Failed Email;
  :Cancel Order;
endif

stop

@enduml

plantuml

@startuml
!theme plain

start

:Receive Order;

if (Payment valid?) then (yes)
  :Process Payment;
  :Send Confirmation Email;
  :Update Inventory;
  :Ship Order;
  :Mark as Delivered;
else (no)
  :Send Payment Failed Email;
  :Cancel Order;
endif

stop

@enduml

State Diagram

状态图

plantuml

@startuml
!theme plain

[*] --> Pending

Pending --> Processing : payment_received
Processing --> Shipped : packed
Shipped --> Delivered : confirmed
Processing --> Cancelled : cancel
Pending --> Cancelled : cancel

Delivered --> [*]
Cancelled --> [*]

@enduml

plantuml

@startuml
!theme plain

[*] --> Pending

Pending --> Processing : payment_received
Processing --> Shipped : packed
Shipped --> Delivered : confirmed
Processing --> Cancelled : cancel
Pending --> Cancelled : cancel

Delivered --> [*]
Cancelled --> [*]

@enduml

Export Commands

导出命令

bash

undefined

bash

undefined

PNG via Kroki API (recommended)

通过Kroki API导出PNG（推荐）

curl -s -X POST https://kroki.io/plantuml/png
-H "Content-Type: text/plain"
--data-binary "@diagram.puml"
-o diagram.png

SVG via Kroki API

通过Kroki API导出SVG

curl -s -X POST https://kroki.io/plantuml/svg
-H "Content-Type: text/plain"
--data-binary "@diagram.puml"
-o diagram.svg

Via local Kroki Docker (offline)

通过本地Docker运行的Kroki导出（离线）

curl -s -X POST http://localhost:8000/plantuml/png
-H "Content-Type: text/plain"
--data-binary "@diagram.puml"
-o diagram.png

Via local PlantUML jar (if installed)

通过本地PlantUML jar包导出（已安装时）

java -jar plantuml.jar diagram.puml

Output: diagram.png in same directory

输出：同目录下的diagram.png

---

---

Themes

主题

plantuml

!theme plain       ← clean, minimal (recommended)
!theme cerulean    ← blue-tinted
!theme blueprint   ← dark blue background
!theme aws-orange  ← AWS style
!theme vibrant     ← vivid colors

Or use

skinparam

for custom styling:

plantuml

skinparam backgroundColor #FAFAFA
skinparam componentBorderColor #555555
skinparam ArrowColor #333333
skinparam FontName Arial

plantuml

!theme plain       ← 简洁极简（推荐）
!theme cerulean    ← 蓝色调
!theme blueprint   ← 深蓝色背景
!theme aws-orange  ← AWS风格
!theme vibrant     ← 鲜艳色彩

或使用

skinparam

进行自定义样式：

plantuml

skinparam backgroundColor #FAFAFA
skinparam componentBorderColor #555555
skinparam ArrowColor #333333
skinparam FontName Arial

Common Mistakes

常见错误

Mistake	Fix
`curl` POST returns HTML error page	Check network; try `curl -v` to see error details
Kroki returns 400 Bad Request	Validate PlantUML syntax at https://www.plantuml.com/plantuml/uml/
Arrow direction unexpected	Use `-->` for downward/right; explicitly use `-up->` , `-down->` , `-left->` , `-right->`
Diagram too large/crowded	Split into multiple diagrams or use `package` / `rectangle` grouping
Missing `@startuml` / `@enduml`	Always wrap diagram in these markers
Special chars in labels	Wrap in quotes: `"Label: value"`
C4 includes not found via Kroki	Use Kroki's `c4plantuml` diagram type instead of `plantuml` for C4 diagrams
Component overlap	Use `together { }` or explicit layout hints ( `top to bottom direction` )
Sequence participants out of order	Declare `participant` explicitly at top in desired left-to-right order

错误	修复方法
`curl` POST请求返回HTML错误页面	检查网络连接；使用 `curl -v` 查看错误详情
Kroki返回400 Bad Request错误	在https://www.plantuml.com/plantuml/uml/验证PlantUML语法
箭头方向不符合预期	使用 `-->` 表示向下/向右；可显式使用 `-up->` 、 `-down->` 、 `-left->` 、 `-right->`
图表过大/过于拥挤	拆分为多个图表，或使用 `package` / `rectangle` 进行分组
缺少 `@startuml` / `@enduml` 标记	始终用这些标记包裹图表内容
标签中包含特殊字符	用引号包裹： `"Label: value"`
Kroki无法找到C4引用	对于C4图表，使用Kroki的 `c4plantuml` 图表类型替代 `plantuml`
组件重叠	使用 `together { }` 或显式布局提示（ `top to bottom direction` ）
时序图参与者顺序混乱	在顶部显式声明 `participant` ，按所需的从左到右顺序排列