plantuml-skill

PlantUML 图表技能

概览

使用 Kroki 生成 .puml PlantUML 图表文件并导出为 PNG/SVG——这是一种云端渲染 API，除 curl 外无需本地安装其他内容。

格式： .puml（PlantUML 文本） 渲染器： Kroki API（https://kroki.io）——只需 curl，无需 Java 输出： PNG、SVG 图表类型： 时序图、组件图、类图、ER 图、活动图、用例图、状态图、C4 等

适用场景

明确触发条件：

• “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 模型
• 说明状态机或生命周期流程

不适用场景——请转用其他工具：

• 嵌入 Markdown 的通用非 UML 快速图表 → mermaid。
• 需要精细控制像素的自由形式、高度定制或带品牌元素的图表 → drawio。
• 手绘或草图风格的图表 → excalidraw 或 tldraw。

模式

触发后，根据用户的实际需求选择模式，然后运行通用渲染流程（步骤 4–8）：

模式	用户需求……	入口
生成（默认）	根据文本描述生成图表	以下步骤 1–8
从代码生成	为现有源代码生成图表	references/from-source-code.md → 步骤 4–8
嵌入	将 PlantUML 嵌入 Markdown 文档并渲染为图像	references/markdown-embed.md
优化	修改现有图表	加载其 .puml，进行最小限度的修改（步骤 7），然后重新渲染（步骤 4–6）
审核	判断现有图表是否清晰易读、正确无误	对图像运行步骤 6 的视觉自检

前置条件

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

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

选项 B：通过 Docker 本地运行 Kroki（用于离线场景）

docker run -d -p 8000:8000 yuzutech/kroki
# Then replace https://kroki.io with http://localhost:8000 in commands

选项 C：本地 PlantUML jar（传统方式）

# Requires Java + Graphviz
brew install graphviz   # macOS
sudo apt install graphviz  # Ubuntu
# Download plantuml.jar from https://plantuml.com/download
java -jar plantuml.jar diagram.puml

工作流

步骤 1：检查依赖项

curl --version

所有现代系统都提供 curl。如果缺少，请通过包管理器安装。

步骤 2：选择图表类型

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

步骤 3：生成 .puml 文件

使用 @startuml / @enduml 标记编写 PlantUML 源文件。

步骤 4：通过 Kroki 导出（捕获 HTTP 状态）

先选择后端。以下默认使用的公共 Kroki 会将 .puml 源文件上传到 kroki.io——对于敏感图表，请改用本地后端，切勿在不提示用户的情况下回退。请参阅 references/rendering-backends.md。使用本地 Kroki 时，将 https://kroki.io 替换为 http://localhost:8000。

# PNG (recommended) — keep the status code so Step 5 can verify it
http=$(curl -s -w "%{http_code}" -o diagram.png \
  -X POST https://kroki.io/plantuml/png \
  -H "Content-Type: text/plain" \
  --data-binary "@diagram.puml")
echo "HTTP $http"

# SVG
http=$(curl -s -w "%{http_code}" -o diagram.svg \
  -X POST https://kroki.io/plantuml/svg \
  -H "Content-Type: text/plain" \
  --data-binary "@diagram.puml")
echo "HTTP $http"

步骤 5：验证并自我修正（循环 — 不要跳过）

不要在盲目执行 curl 后就报告成功。先验证输出；如果符合以下任一情况，则将导出视为失败：

• $http 不为 200。Kroki 遇到语法错误时会返回 400，并将错误文本写入输出文件，因此 .png 文件可能存在，但内容已损坏。
• 文件为空：[ -s diagram.png ] 检查失败。
• 字节内容不是真正的图像：file diagram.png 应报告 PNG image data；对于 SVG，文件应以 <svg 或 <?xml 开头。

if [ "$http" != "200" ] || [ ! -s diagram.png ]; then
  echo "Render failed — Kroki said:"
  cat diagram.png    # the 400 body holds the offending line + reason
fi

失败时：使用 cat 查看输出文件中的 Kroki 错误信息，修正被指出的 .puml 行（参见 常见错误），然后重新执行步骤 4。**最多重复 3 次。**如果针对特定行的修正未能解决问题，则按以下顺序逐步简化，每一步后重新渲染；一旦渲染成功就停止：

1. 移除特殊形状 → 使用普通的 rectangle/component/node
2. 移除 skinparam / !theme（先渲染普通样式）
3. 移除 note 行
4. 简化标签，并用 "…" 括起来
5. 减少连线
6. 改用更简单的图表类型，而不是强行使用当前类型

如需查看各图表类型的错误目录和 Kroki 安全子集，请阅读 references/kroki-troubleshooting.md。如果尝试 3 次后仍然失败，请停止并向用户展示 Kroki 的原始错误 — 不要声称图表已生成。

步骤 6：自我检查（视觉）

步骤 5 的循环只能证明 Kroki 返回了有效图像，并不能证明图表清晰易读。渲染完成后，使用 Agent 的视觉能力读取 PNG，并检查自动布局（Graphviz）无法避免的问题。PlantUML 会自行定位所有元素，因此这里的问题与可读性有关，而非坐标：

检查项	检查内容	修复方法
标签截断 / 溢出	文本被裁剪或溢出框体	缩短标签，用 "…" 括起来，或使用 \n 换行
组件重叠 / 拥挤	框体相互接触或过于拥挤，难以阅读	添加 together { }、布局提示，或拆分图表
方向 / 长宽比错误	图表过宽或过高，难以阅读	切换 left to right direction ↔ top to bottom direction
连线杂乱	关系交叉过多，难以追踪	调整声明顺序，用 package/together 分组，或添加隐藏连线来调整布局
图表类型错误	类型不适合内容	切换类型（时序图、状态图、C4 等）
对比度低	文本与填充色 / 主题融为一体	调整 skinparam / !theme，使文本与填充色形成对比

• 最多进行 2 轮自我检查 — 如果修正 2 次后问题仍然存在，仍然向用户展示。
• 每次修正后都要重新渲染（步骤 4）并重新验证（步骤 5）。
• 如果无法使用视觉能力，请跳过自我检查，直接展示 PNG。

步骤 7：审查循环

自我检查后，展示导出的图像并收集反馈。针对每项请求，进行最小限度的 .puml 修改，然后重新渲染并重新验证：

用户请求	修改操作
更改标签	编辑 .puml 中的元素 / 消息文本
添加 / 移除元素或关系	添加或删除对应行
更改颜色	使用 skinparam、!theme，或在元素上使用内联 #color
更改布局方向	切换 left to right direction ↔ top to bottom direction
重组 / 分组	将相关元素放入 package / together { }，或重新生成

• 每轮都覆盖同一个 diagram.puml / 输出文件 — 不要创建 v1、v2 等版本。
• **安全措施：**经过 5 轮后，建议用户直接微调 .puml，或前往 plantuml.com 操作。

步骤 8：向用户报告

仅在步骤 5–7 全部通过后，告知用户：

• .puml 源文件的路径
• 导出的 PNG/SVG 的路径
• 对生成内容的简要描述
• 使用的渲染后端，以及源文件是否离开了本机 — 例如：“通过公共 Kroki 渲染（已上传至 kroki.io）”或“通过本地 Kroki 渲染（未离开本机）”

---

导入工作流

两种非默认模式——触发时加载关联的操作手册，然后运行相同的第 4–8 步循环：

• 根据现有源代码生成图表 — 模块的类图、请求处理程序的时序图、代码库的组件图、根据 ORM 模型生成 ER 图。阅读代码，提取真实存在的实体和关系，只绘制实际存在的内容。→ references/from-source-code.md
• 渲染 Markdown 中嵌入的 PlantUML — 提取 ```plantuml / ```puml 代码块（以及关联的 .puml 文件），将每个代码块渲染为图片，并用图片链接改写 Markdown（例如，发布到不支持渲染围栏式 PlantUML 的 Confluence / Notion）。→ references/markdown-embed.md

---

图表类型

类型	关键字	用途
时序图	@startuml + 时序图语法	API 调用、协议流程、消息传递
组件图	@startuml + 组件	服务架构、模块依赖
类图	@startuml + 类语法	OOP 模型、数据结构
ER / 实体图	@startuml + 实体语法	数据库架构
活动图	@startuml + 活动图语法	工作流、业务流程
用例图	@startuml + actor/usecase	系统需求、用户故事
状态图	@startuml + 状态图语法	状态机、生命周期
C4 上下文图	@startuml + C4 引入项	高层系统上下文图
思维导图	@startmindmap	主题拆解、概念图
甘特图	@startgantt	项目时间线、日程安排

---

语法参考

组件 / 架构图

@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（灰色）

---

时序图

@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 — 显示激活框

---

类图

@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 图

@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

---

活动图 / 流程图

@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

---

状态图

@startuml
!theme plain

[*] --> Pending

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

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

@enduml

---

C4 上下文图

C4 通过 !include <C4/...> 使用捆绑的 C4-PlantUML 标准库，Kroki 和近期版本的本地 jar 无需联网即可解析。使用标准 plantuml 端点导出（Kroki 的 c4plantuml 类型也可用）。

@startuml
!include <C4/C4_Context>

title System Context — Internet Banking

Person(customer, "Banking Customer", "A customer of the bank")
System(banking, "Internet Banking System", "Lets customers view their accounts")
System_Ext(mail, "E-mail System", "The internal Microsoft Exchange system")

Rel(customer, banking, "Uses", "HTTPS")
Rel(banking, mail, "Sends e-mail via", "SMTP")
@enduml

其他层级：<C4/C4_Container>（Container、ContainerDb）、<C4/C4_Component>（Component）。常用宏：Person、System、System_Ext、Container、Rel、Boundary。不要使用远程 !includeurl https://…——Kroki 无法获取外部 URL；始终使用捆绑的 <C4/…> 形式。

---

导出命令

渲染器变体的快速参考。为简洁起见，Kroki 命令省略了状态捕获；实际导出时，请使用第 4 步的形式并运行第 5 步验证循环。

# PNG via Kroki API (recommended)
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
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)
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)
java -jar plantuml.jar diagram.puml
# Output: diagram.png in same directory

---

主题

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

也可以使用 skinparam 自定义样式：

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

---

常见错误

下表列出了常见错误；有关按图表类型分类的错误目录、Kroki 安全子集和故障降级阶梯，请参阅 references/kroki-troubleshooting.md。

错误	修复方法
curl POST 返回 HTML 错误页面	检查网络；尝试运行 curl -v 查看错误详情
Kroki 返回 400 Bad Request	使用 cat 查看输出文件——Kroki 已在其中写入出错行及原因；修复后通过第 5 步的循环重新渲染。在 https://www.plantuml.com/plantuml/uml/ 验证语法
箭头方向不符合预期	向下或向右使用 -->；明确指定 -up->、-down->、-left->、-right->
图表太大或太拥挤	拆分为多个图表，或使用 package/rectangle 分组
缺少 @startuml / @enduml	始终使用这些标记包裹图表
标签中包含特殊字符	用引号括起来："Label: value"
找不到 C4 引用	使用捆绑的 !include <C4/C4_Context>（可通过标准 plantuml 端点和 c4plantuml 解析）；切勿使用远程 !includeurl https://…——Kroki 无法获取外部 URL
组件重叠	使用 together { } 或明确的布局提示（top to bottom direction）
序列图参与者顺序错误	在顶部按所需的从左到右顺序显式声明 participant