plantuml

PlantUML 图表生成与转换

目录

• 用途
• 何时使用此技能
• 先决条件
• 创建图表
  • 识别图表类型
  • 弹性工作流
• 将源代码转换为图表
• 将图表转换为图像
  • 独立的 .puml 文件
  • Markdown 处理
  • 直接使用命令行
• 最佳实践
• 故障排查
• 参考资料

用途

此技能支持全面的 PlantUML 图表创建与转换工作流。PlantUML 是一款基于文本的图表工具，可通过简单直观的语法生成专业图表。

核心功能：

1. 根据自然语言描述创建图表
2. 将源代码转换为架构图（Spring Boot、FastAPI、Python ETL、Node.js、React）
3. 将独立的 .puml 文件转换为 PNG 或 SVG 图像
4. 从 Markdown 中提取 puml 代码块并转换为图像
5. 处理 Markdown 中链接的 .puml 文件（![diagram](path/to/diagram.puml)）
6. 在不进行转换的情况下验证 PlantUML 语法
7. 将 Markdown 图表替换为图像链接以便发布（Confluence、Notion）

何时使用此技能

WikiTicket、GitHub wiki、架构文档、演练和需求的默认选项是 design-doc-mermaid。 GitHub 可渲染围栏式 Mermaid 代码（流程图、时序图、类图、ER 图、状态图、C4）。此技能需选择启用。

适用于：

• Salt 线框图／UI 模型
• UML 用例图、时序图、ArchiMate
• nwdiag 网络图、WBS、JSON/YAML 树形图
• 将 .puml 文件转换为 PNG 或 SVG（始终需要；GitHub wiki 不会渲染 PlantUML 源码）
• 包含 PlantUML 围栏代码或链接的 .puml 文件的 Markdown 文件
• 导出 Confluence 或 Notion 图像（先渲染，再上传）
• 验证 PlantUML 语法
• 用户已有 .puml 源码并希望生成图像

除非 Mermaid 无法胜任，或用户指定 PlantUML，否则不要在 WikiTicket 设计文档中使用类图、ER 图、状态图、时序图或 C4 图。

GitHub wiki： 切勿只保留原始 PlantUML 围栏代码而不提供其他查看方式。将其渲染为 PNG 或 SVG，提交到 docs/diagrams/，链接该图像，并将其与 wiki 页面一同上传。

Confluence/Notion： 将 PlantUML（以及通过 design-doc-mermaid 处理的 Mermaid）渲染为 PNG 或 SVG，并上传两者。参见 references/wiki-ticket-integration.md。

先决条件

创建图表前，请验证 PlantUML 配置：

python scripts/check_setup.py

必需组件：

组件	用途	安装
Java JRE/JDK 8+	运行时	https://www.oracle.com/java/technologies/downloads/
plantuml.jar	图表生成器	https://plantuml.com/download（放置于 ~/plantuml.jar，或设置 PLANTUML_JAR）
Graphviz（可选）	复杂布局	https://graphviz.org/download/

创建图表

图表类型识别

根据用户意图确定合适的图表类型。

WikiTicket / GitHub wiki 默认使用 design-doc-mermaid。 仅当用户指定 PlantUML，或你要转换现有的 .puml 文件时，才使用下方的时序图、类图、活动图、状态图、ER 图和组件图。始终导出 PNG 或 SVG。切勿只留下原始 PlantUML 代码块作为唯一视图。

用户意图	图表类型	参考
UI 模型、屏幕草图	Salt 线框图	references/wireframes_salt.md
参与者和目标	用例图	references/use_case_diagrams.md
时钟、波形	定时图	references/timing_diagrams.md
企业层次	ArchiMate	references/archimate_diagrams.md
网络机架	nwdiag	references/network_diagrams.md
工作分解	WBS	references/wbs_diagrams.md
随时间变化的交互（仅当用户指定 PlantUML 时）	时序图	references/sequence_diagrams.md
包含类的系统结构（仅当用户指定 PlantUML 时）	类图	references/class_diagrams.md
工作流、决策流程（仅当用户指定 PlantUML 时）	活动图	references/activity_diagrams.md
对象状态和转换（仅当用户指定 PlantUML 时）	状态图	references/state_diagrams.md
数据库架构（仅当用户指定 PlantUML 时）	ER（实体关系）图	references/er_diagrams.md
项目时间线	甘特图	references/gantt_diagrams.md
思路整理	思维导图	references/mindmap_diagrams.md
系统架构（仅当用户指定 PlantUML 时）	组件图	references/component_diagrams.md
全部 19 种类型	查看导航中心	references/toc.md
WikiTicket / GitHub wiki / Confluence	图片导出规则	references/wiki-ticket-integration.md

语法资源：

• references/toc.md：包含所有图表类型链接的导航中心
• references/common_format.md：通用元素（分隔符、元数据、注释、备注）
• references/styling_guide.md：用于自定义视觉样式的现代 <style> 语法

稳健工作流（首选 - 推荐）

为可靠地生成图表并处理错误，请遵循以下 4 步稳健工作流：

步骤 1：识别图表类型并加载参考

• 根据用户意图识别图表类型
• 加载 references/[diagram_type]_diagrams.md 获取语法指南
• 如有歧义，请参阅 references/toc.md

步骤 2：使用结构化命名创建文件

./diagrams/<markdown_name>_<num>_<type>_<title>.puml

示例：./diagrams/architecture_001_sequence_user_auth.puml

步骤 3：转换并处理错误（最多重试 3 次）

如果转换失败：

1. 查看 references/troubleshooting/toc.md，对错误进行分类
2. 加载 references/troubleshooting/[category]_guide.md 中的具体指南
3. 查看 references/common_syntax_errors.md 中对应图表类型的内容

步骤 4：验证并集成

1. 确认图片文件存在
2. 添加图片链接：![title](diagrams/filename.png)
3. 保留 .puml 源文件，以便日后编辑

完整文档： references/workflows/resilient-execution-guide.md

快速语法参考

常见元素：

• 分隔符：@startuml / @enduml（必需）
• 注释：' Single line 或 /' Multi-line '/
• 关系：->（实线）、-->（虚线）、..>（点线）
• 标签：A -> B : Label text

最简示例（完整语法请参见 references/[type]_diagrams.md）：

' Sequence: references/sequence_diagrams.md
@startuml
Alice -> Bob: Request
Bob --> Alice: Response
@enduml

' Class: references/class_diagrams.md
@startuml
class Animal { +move() }
class Dog extends Animal { +bark() }
@enduml

' ER: references/er_diagrams.md
@startuml
entity User { *id: int }
entity Post { *id: int }
User ||--o{ Post
@enduml

将源代码转换为图表

examples/ 目录包含针对不同语言的模板，用于转换常见的应用架构：

应用类型	目录	主要图表
Spring Boot	examples/spring-boot/	部署、组件、时序
FastAPI	examples/fastapi/	部署、组件（异步路由器）
Python ETL	examples/python-etl/	使用 Airflow 的架构
Node.js	examples/nodejs-web/	Express/Nest.js 组件
React	examples/react-frontend/	SPA 部署、组件架构

工作流：

1. 确定应用类型
2. 查看 examples/[app-type]/ 中的示例
3. 将代码结构映射到图表模式
4. 复制并改编示例 .puml 文件
5. 使用 references/unicode_symbols.md 中的 Unicode 符号，让含义更清晰

将图表转换为图像

转换独立的 .puml 文件

# Convert to PNG (default)
python scripts/convert_puml.py diagram.puml

# Convert to SVG
python scripts/convert_puml.py diagram.puml --format svg

# Specify output directory
python scripts/convert_puml.py diagram.puml --format svg --output-dir images/

从 Markdown 中提取并转换

对于 Confluence/Notion 至关重要： 如果 Markdown 中包含 PlantUML 图表，请在上传前首先运行此步骤。

# Process embedded ```puml blocks AND linked ![](diagram.puml) files
python scripts/process_markdown_puml.py article.md

# Convert to SVG format
python scripts/process_markdown_puml.py article.md --format svg

# Validate syntax only (for CI/CD)
python scripts/process_markdown_puml.py article.md --validate

输出：

• article_with_images.md：包含图像链接的 Markdown
• images/：生成的图像目录

适合 IDE 的工作流： 开发期间将图表保留为 .puml 文件，以便在 IDE 中预览，然后再转换以供发布。

直接使用命令行

# Basic conversion
java -jar ~/plantuml.jar diagram.puml

# SVG with custom output
java -jar ~/plantuml.jar --svg --output-dir out/ diagram.puml

# Batch conversion
java -jar ~/plantuml.jar "**/*.puml" --svg

有关全面的命令行选项，请参阅 references/plantuml_reference.md。

最佳实践

图表质量：

• 根据图表内容使用描述性文件名
• 使用 ' 添加注释，以便清晰易懂
• 遵循标准 UML 符号
• 逐步测试，再增加复杂度

格式选择：

• PNG：适用于 Web 发布，文件较小，分辨率固定
• SVG：适用于文档，可缩放，支持超链接

样式： 应用 references/styling_guide.md 中的现代 <style> 语法：

@startuml
<style>
classDiagram {
  class { BackgroundColor LightBlue }
}
</style>
' diagram content
@enduml

主题： !theme cerulean（还包括：bluegray、plain、sketchy、amiga）

Unicode 符号： 使用 references/unicode_symbols.md 中的符号，赋予图表语义含义：

node "☁️ AWS Cloud" as aws
database "💾 PostgreSQL" as db

故障排除

快速诊断：

1. 检查语法：java -jar plantuml.jar --check-syntax file.puml
2. 确定错误类型
3. 加载故障排除指南：references/troubleshooting/toc.md

常见问题：

问题	解决方案
"plantuml.jar not found"	从 https://plantuml.com/download 下载，并设置 PLANTUML_JAR
"Graphviz not found"	从 https://graphviz.org/download/ 安装
"Syntax Error"	检查分隔符是否匹配，并参阅 references/common_format.md
"Java not found"	安装 Java JRE/JDK 8+，并通过 java -version 验证

全面指南（记录了 215+ 种错误）：

• references/troubleshooting/toc.md - 导航中心，包含错误决策树
• references/troubleshooting/[category]_guide.md - 按错误类型划分的 12 份专题指南

参考资料

核心语法参考

资源	用途
references/wiki-ticket-integration.md	WikiTicket 遗留类型，始终使用 PNG/SVG，Confluence 上传
references/toc.md	全部 19 种图表类型的导航中心
references/common_format.md	通用元素（分隔符、元数据、注释）
references/styling_guide.md	类似 CSS 规则的现代 <style> 语法
references/plantuml_reference.md	安装、CLI 和故障排除

故障排除指南

资源	覆盖范围
references/troubleshooting/toc.md	导航中心，包含错误决策树
references/troubleshooting/installation_setup_guide.md	设置问题
references/troubleshooting/general_syntax_guide.md	语法错误
references/troubleshooting/[diagram_type]_guide.md	特定图表的错误

补充资源

资源	用途
references/unicode_symbols.md	用于丰富语义的 Unicode 符号
examples/[framework]/	从代码转换为图表的模式

概要

1. 验证设置：python scripts/check_setup.py
2. 浏览图表类型：从 references/toc.md 开始
3. 学习语法：打开 references/[diagram_type]_diagrams.md
4. 应用样式：使用 references/styling_guide.md
5. 添加符号：使用 references/unicode_symbols.md
6. 转换文件：scripts/convert_puml.py
7. 处理 Markdown：scripts/process_markdown_puml.py
8. 排查问题：references/troubleshooting/toc.md

支持的图表：

• UML：时序图、类图、活动图、状态图、组件图、部署图、用例图、对象图、定时图
• 非 UML：ER 图、甘特图、思维导图、WBS、JSON/YAML、网络图、Archimate、线框图