plantuml-skill

PlantUML 图表技能

概述

生成 .puml PlantUML 图表文件，并使用 Kroki 导出为 PNG/SVG。Kroki 是云端渲染 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	使用捆绑的 !include <C4/C4_Context>（可通过标准的 plantuml 端点和 c4plantuml 解析）；切勿使用远程 !includeurl https://… — Kroki 无法获取外部 URL
组件重叠	使用 together { } 或明确的布局提示（top to bottom direction）
序列图参与者顺序错误	在顶部按所需的从左到右顺序显式声明 participant