puml-plantuml

PUML-PlantUML 专家技能

深入掌握 PlantUML（涵盖官方参考文档全部 27 章）+ 跨平台本地渲染 + 图像→PUML 逆向工程。离线渲染。 支持任意操作系统。不假设任何路径。自动检测并安装完整的 Python + Java + PlantUML。

---

快速决策树

User request
├── "Create/draw a diagram from description"   → § Generate PUML
├── "Convert image/screenshot to PUML"         → § Image → PUML
├── "Render/preview/generate image from code"  → § Render Locally
├── "Fix/debug my PUML"                        → § Diagnose & Fix
└── "Explain syntax / how do I..."             → references/syntax-quick-ref.md

---

§ 首次运行 — 从零开始引导安装

引导脚本无需预先安装任何工具——它们会按正确顺序安装 Python → Java → PlantUML。每台机器只需运行一次。

macOS / Linux

bash scripts/bootstrap.sh           # install everything
bash scripts/bootstrap.sh --verify  # install + test render

Windows（PowerShell — 内置于 Windows 10/11）

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\bootstrap.ps1
.\scripts\bootstrap.ps1 -Verify

如果 Python 已可用

python3 scripts/render.py --detect      # show what's detected
python3 scripts/setup.py               # install Java + PlantUML
python3 scripts/setup.py --java        # ensure Java only
python3 scripts/setup.py --jar         # force JAR download
python3 scripts/setup.py --verify      # install + test render
python3 scripts/render.py --install-hint  # show manual steps

安装内容：

组件	macOS	Linux	Windows
Python 3.9+	brew	apt/dnf/pacman/snap	winget/choco/scoop
Java JRE 11+	brew cask temurin	apt/dnf/pacman	winget Temurin/Zulu
PlantUML	brew	apt/dnf/pacman/snap	winget/choco/scoop
回退方案	—	~/.plantuml/plantuml.jar	~/.plantuml/plantuml.jar

Java 检测位置：$JAVA_HOME、PATH、macOS /usr/libexec/java_home、 Azul/Zulu（zulu*）、Temurin、Homebrew OpenJDK、SDKMAN、/usr/lib/jvm/*。

---

§ 根据描述生成 PUML

步骤 1 — 识别图表类型：

请求中的关键词	类型	标签
调用顺序、API 流程、消息	时序图	@startuml
类、OOP、继承、方法	类图	@startuml
流程、工作流、流程图、步骤	活动图（新版）	@startuml
架构、服务、组件	组件图	@startuml
数据库、架构、表、实体	ER 图	@startuml
状态、生命周期、状态转换	状态图	@startuml
用例、参与者、用户故事	用例图	@startuml
对象、实例、运行时快照	对象图	@startuml
定时、信号、波形	定时图	@startuml
头脑风暴、概念图、主题	思维导图	@startmindmap
项目时间线、日程、里程碑	甘特图	@startgantt
工作分解、项目阶段	WBS	@startwbs
UI 表单、线框图、模型图	Salt	@startsalt
JSON 数据结构	JSON	@startjson
YAML 数据结构	YAML	@startyaml
网络拓扑、服务器、子网	nwdiag	@startuml + nwdiag {}
企业架构、ArchiMate	Archimate	@startuml + archimate 关键字
数学公式、方程、LaTeX	数学	@startmath / @startlatex
ASCII 艺术图	Ditaa	@startditaa

步骤 2 — 生成时使用 references/syntax-quick-ref.md 中的完整语法。 务必包含：title 行、skinparam shadowing false、所有箭头上的标签。

步骤 3 — 编写、验证并渲染：

cat > /tmp/diagram.puml << 'PUML'
@startuml
title My Diagram
... generated code ...
@enduml
PUML

python3 scripts/render.py /tmp/diagram.puml --check   # validate
python3 scripts/render.py /tmp/diagram.puml -f svg -o /tmp/  # render

---

§ 图像 → PUML（逆向工程）

1. 查看图像 — 使用 view 工具或检查上传的图像
2. 识别图表类型 — references/image-to-puml.md
3. 提取元素 — 名称、标签、箭头、关系、基数
4. 生成 PUML — 忠实还原，并使用正确的箭头类型
5. 验证并渲染 — 与原图对比；必要时进行调整

图像分析指南：references/image-to-puml.md

---

§ 本地渲染

使用 scripts/render.py — 自动检测二进制文件或 JAR+Java，支持任意操作系统。

# macOS / Linux
python3 scripts/render.py diagram.puml                        # PNG
python3 scripts/render.py diagram.puml -f svg -o ./output/   # SVG
python3 scripts/render.py diagram.puml -f pdf -o ./output/   # PDF
cat diagram.puml | python3 scripts/render.py --stdin -f svg -n "name" -o /tmp/

# Windows
py scripts\render.py diagram.puml
py scripts\render.py diagram.puml -f svg -o .\output\

直接使用 CLI（如果 PATH 中有 plantuml）：

plantuml -tsvg diagram.puml
plantuml -tpng -o ./output/ *.puml
plantuml -checkonly diagram.puml

渲染后使用 present_files 向用户展示输出文件。

完整选项、环境变量、格式和故障排查：references/local-rendering.md

---

§ 诊断和修复 PUML

python3 scripts/render.py diagram.puml --check

错误	原因	修复方法
No @startuml found	缺少包装标记	添加 @startuml / @enduml
Unknown command	拼写错误或图表类型错误	查看 syntax-quick-ref.md
箭头 →（Unicode）	必须使用 ASCII	使用 ->，不要使用 →
Cannot find class	前向引用	在使用前声明
Graphviz 错误	未安装 dot	brew/apt install graphviz 或添加 !pragma layout smetana
未找到 PlantUML	尚未安装	bash scripts/bootstrap.sh
未检测到 Java	JDK 非标准	设置 JAVA_HOME 环境变量
未找到 Python	缺少 Python	bash scripts/bootstrap.sh
Unicode 显示异常	字符集问题	plantuml -charset UTF-8 file.puml

---

§ 语法速查表（超快速）

完整参考（全部 27 章，共 2700 多行）：references/syntax-quick-ref.md

时序图箭头：

->   sync          -->  response/dashed
->>  thin           -->> thin dashed
->x  lost           ->o  open arrowhead
<->  bidirectional  ->+  activate   -->-  deactivate
[->  incoming      ->]   outgoing

类关系：

<|--  inheritance    <|..  realization
o--   aggregation    *--   composition
-->   dependency     ..>   usage
--    association    --()  lollipop (provided interface)
"1" *-- "0..*"  : label  (with cardinality and label)

ER 基数（乌鸦脚表示法）：

||   exactly one    o|   zero or one
o{   zero or more   |{   one or more

所有 @start 标签：

@startuml          most diagrams
@startmindmap      mind maps
@startgantt        gantt charts
@startwbs          work breakdown
@startsalt         wireframes
@startjson         JSON display
@startyaml         YAML display
@startmath         AsciiMath
@startlatex        LaTeX formula
@startditaa        Ditaa ASCII art

通用格式设置：

title My Title
skinparam shadowing false
skinparam monochrome true
!theme cerulean
left to right direction
!pragma layout smetana    ' no Graphviz needed

---

完整图表覆盖（PDF 中的全部 27 章）

章	类型	说明
1	时序图	完整支持：箭头、分组、激活、注释、自动编号、主框架、并行、构造型/标记、锚点、包围、隐藏底部边框
2	用例图	完整支持：参与者、扩展/包含、注释、包、业务用例、JSON 覆盖层
3	类图	完整支持：可见性、构造型、标记、泛型、棒棒糖接口、extends/implements 关键字、隐藏/显示/移除、$tags、命名空间
4	对象图	实例、关系、映射、关联对象
5	活动图（旧版）	旧式 (*) --> 语法、分支、同步条、分区
6	活动图（新版）	start/stop、if/else/elseif、switch/case、while、repeat、fork、split、泳道、SDL 形状、goto/label、连接器、条件样式
7	组件图	组件、接口、球形-插座形、分组、端口、隐藏未连接项
8	部署图	所有元素类型、嵌套、端口、圆角、方向
9	状态图	嵌套、并发、fork/join、历史、选择、图钉、展开、连线注释、内联颜色
10	时序图	鲁棒式、简洁式、二进制式、时钟式、模拟式；相对时间、锚点、高亮
11	JSON	显示、高亮、样式、最简示例
12	YAML	显示、高亮、别名、Creole
13	网络图（nwdiag）	网络、节点、地址、分组、精灵图、对等网络
14	线框图（Salt）	所有控件：按钮、输入框、下拉菜单、单选按钮、复选框、网格、树、选项卡、分组框、滚动框
15	ArchiMate	archimate 关键字、连接点、宏、StdLib 集成
16	甘特图	任务、约束、里程碑、颜色、完成百分比、超链接、休息日、缩放、刻度
17	思维导图	OrgMode 和 Markdown 语法、左侧分支、多根节点、颜色、方向
18	WBS	OrgMode 语法、方向、颜色、箭头、自动换行
19	数学公式	AsciiMath（@startmath）、LaTeX/JLaTeXMath（@startlatex）、内联 <math> 标签
20	ER 图（信息工程）	实体、属性、PK/FK 标记、乌鸦脚关系
21	通用命令	注释、缩放、标题、题注、页眉、页脚、图例、换页、主框架、附录、pragma
22	Creole	粗体、斜体、等宽、删除线、下划线、波浪线；列表、标题、表格、链接、表情符号、HTML 标签、Unicode
23	精灵图	定义十六进制精灵图、内联 SVG 精灵图、从 StdLib 导入、OpenIconic、Font Awesome
24	Skinparam	全面的逐元素 skinparam + 类 CSS 的现代 <style> 替代方案 + 所有主题
25	预处理	变量、条件、while/loop、过程、函数、默认参数、不加引号、关键字参数、包含、子部分、主题、define、内置函数（%string、%strlen、%date、%random、%hsl_color 等）
26	Unicode	原生 UTF-8、&#XXXX; 和 <U+XXXX> 引用、表情符号 <:name:>、字符集标志
27	StdLib	ArchiMate、AWS、Azure、C4、Kubernetes、Elastic、GCP、CloudOgu、Tupadr3/FontAwesome、EDGY
—	Ditaa	将 @startditaa ASCII 艺术转换为图表

---

参考文件

文件	内容
references/syntax-quick-ref.md	2700+ 行 — 全部 27 章的完整语法
references/image-to-puml.md	图像→PUML 逆向工程的视觉分析指南
references/local-rendering.md	设置、CLI 标志、格式、环境变量、故障排除

脚本

脚本	用途
scripts/bootstrap.sh	从这里开始 — macOS/Linux — 安装 Python→Java→PlantUML（无依赖）
scripts/bootstrap.ps1	从这里开始 — Windows — PowerShell 5+，无需依赖
scripts/setup.py	Python 设置：检测/安装 Java + PlantUML；也会报告 Python
scripts/render.py	跨平台渲染：自动检测 Python/二进制文件/JAR/Java