Back to Details

puml-plantuml

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PUML-PlantUML Expert Skill

PUML-PlantUML专家工具

Deep PlantUML knowledge (all 27 chapters from official reference) + cross-platform local rendering + image→PUML reverse engineering. Offline rendering. Any OS. No assumed paths. Full Python + Java + PlantUML auto-detection and installation.
具备深厚的PlantUML知识（覆盖官方参考指南全部27个章节）+跨平台本地渲染+图像转PUML逆向工程能力。离线渲染，支持任意操作系统，无需预设路径，可自动检测并安装Python、Java和PlantUML。

Quick Decision Tree

快速决策树

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
用户请求
├── "根据描述创建/绘制图表"   → § 生成PUML
├── "将图像/截图转换为PUML"         → § 图像转PUML
├── "从代码渲染/预览/生成图像"  → § 本地渲染
├── "修复/调试我的PUML"                        → § 诊断与修复
└── "讲解语法 / 如何操作..."             → 参考references/syntax-quick-ref.md

§ First Run — Bootstrap from Zero

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

The bootstrap scripts require no pre-installed tools — they install Python → Java → PlantUML in the correct order. Run once per machine.
引导安装脚本无需任何预安装工具——它们会按正确顺序安装Python→Java→PlantUML。每台机器只需运行一次。

macOS / Linux

macOS / Linux

bash
bash scripts/bootstrap.sh           # install everything
bash scripts/bootstrap.sh --verify  # install + test render
bash
bash scripts/bootstrap.sh           # 安装所有组件
bash scripts/bootstrap.sh --verify  # 安装并测试渲染

Windows (PowerShell — built into Windows 10/11)

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

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

If Python is already available

若已安装Python

bash
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
What gets installed:
ComponentmacOSLinuxWindows
Python 3.9+brewapt/dnf/pacman/snapwinget/choco/scoop
Java JRE 11+brew cask temurinapt/dnf/pacmanwinget Temurin/Zulu
PlantUMLbrewapt/dnf/pacman/snapwinget/choco/scoop
Fallback—
~/.plantuml/plantuml.jar
~/.plantuml/plantuml.jar
Java detected from: 
$JAVA_HOME
, PATH, macOS 
/usr/libexec/java_home
, Azul/Zulu (
zulu*
), Temurin, Homebrew OpenJDK, SDKMAN, 
/usr/lib/jvm/*
.
bash
python3 scripts/render.py --detect      # 显示已检测到的组件
python3 scripts/setup.py               # 安装Java + PlantUML
python3 scripts/setup.py --java        # 仅确保Java安装
python3 scripts/setup.py --jar         # 强制下载JAR包
python3 scripts/setup.py --verify      # 安装并测试渲染
python3 scripts/render.py --install-hint  # 显示手动安装步骤
将安装的组件：
组件macOSLinuxWindows
Python 3.9+brewapt/dnf/pacman/snapwinget/choco/scoop
Java JRE 11+brew cask temurinapt/dnf/pacmanwinget Temurin/Zulu
PlantUMLbrewapt/dnf/pacman/snapwinget/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/*
。

§ Generate PUML from Description

§ 根据描述生成PUML

Step 1 — Identify diagram type:
Keywords in requestTypeTag
sequence of calls, API flow, messagesSequence
@startuml
classes, OOP, inheritance, methodsClass
@startuml
process, workflow, flowchart, stepsActivity (new)
@startuml
architecture, services, componentsComponent
@startuml
database, schema, tables, entitiesER
@startuml
states, lifecycle, status transitionsState
@startuml
use cases, actors, user storiesUse Case
@startuml
objects, instances, runtime snapshotObject
@startuml
timing, signals, waveformsTiming
@startuml
brainstorm, concept map, topicsMindMap
@startmindmap
project timeline, schedule, milestonesGantt
@startgantt
work breakdown, project phasesWBS
@startwbs
UI form, wireframe, mockupSalt
@startsalt
JSON data structureJSON
@startjson
YAML data structureYAML
@startyaml
network topology, servers, subnetsnwdiag
@startuml
+ 
nwdiag {}
enterprise architecture, ArchiMateArchimate
@startuml
+ 
archimate
kw
math formula, equation, LaTeXMaths
@startmath
/ 
@startlatex
ASCII art diagramDitaa
@startditaa
Step 2 — Generate using the full syntax in 
references/syntax-quick-ref.md
. Always include: a 
title
line, 
skinparam shadowing false
, labels on all arrows.
Step 3 — Write, validate & render:
bash
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
步骤1——确定图表类型：
请求中的关键词类型标签
调用序列、API流程、消息序列图
@startuml
类、面向对象、继承、方法类图
@startuml
流程、工作流、流程图、步骤活动图（新版）
@startuml
架构、服务、组件组件图
@startuml
数据库、模式、表、实体ER图
@startuml
状态、生命周期、状态转换状态图
@startuml
用例、参与者、用户故事用例图
@startuml
对象、实例、运行时快照对象图
@startuml
时序、信号、波形时序图
@startuml
头脑风暴、概念图、主题思维导图
@startmindmap
项目时间线、进度、里程碑甘特图
@startgantt
工作分解、项目阶段工作分解结构
@startwbs
UI表单、线框图、原型Salt
@startsalt
JSON数据结构JSON
@startjson
YAML数据结构YAML
@startyaml
网络拓扑、服务器、子网nwdiag
@startuml
+ 
nwdiag {}
企业架构、ArchiMateArchimate
@startuml
+ 
archimate
关键字
数学公式、方程式、LaTeX数学公式
@startmath
/ 
@startlatex
ASCII艺术图表Ditaa
@startditaa
步骤2——生成代码：使用
references/syntax-quick-ref.md
中的完整语法。需始终包含：
title
行、
skinparam shadowing false
、所有箭头的标签。
步骤3——编写、验证并渲染：
bash
cat > /tmp/diagram.puml << 'PUML'
@startuml
title My Diagram
... 生成的代码 ...
@enduml
PUML

python3 scripts/render.py /tmp/diagram.puml --check   # 验证
python3 scripts/render.py /tmp/diagram.puml -f svg -o /tmp/  # 渲染

§ Image → PUML (Reverse Engineering)

§ 图像转PUML（逆向工程）

  1. View the image — use the 
    view
    tool or examine the upload
  2. Identify the diagram type — 
    references/image-to-puml.md
  3. Extract elements — names, labels, arrows, relationships, cardinality
  4. Generate PUML — reproduce faithfully, correct arrow types
  5. Validate & render — compare against original; refine if needed
Visual analysis guide: 
references/image-to-puml.md
  1. 查看图像——使用
    view
    工具或检查上传的文件
  2. 确定图表类型——参考
    references/image-to-puml.md
  3. 提取元素——名称、标签、箭头、关系、基数
  4. 生成PUML——忠实还原，修正箭头类型
  5. 验证并渲染——与原图对比；如有需要则优化
视觉分析指南：
references/image-to-puml.md

§ Render Locally

§ 本地渲染

Use 
scripts/render.py
— auto-detects binary vs JAR+Java, any OS.
bash
undefined
使用
scripts/render.py
——自动检测二进制文件或JAR+Java，支持任意操作系统。
bash
undefined

macOS / Linux

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/
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

Windows

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

Direct CLI (if `plantuml` is in PATH):
```bash
plantuml -tsvg diagram.puml
plantuml -tpng -o ./output/ *.puml
plantuml -checkonly diagram.puml
Present the output file to the user after rendering using 
present_files
.
Full options, env vars, formats, troubleshooting: 
references/local-rendering.md
py scripts\render.py diagram.puml py scripts\render.py diagram.puml -f svg -o .\output\

直接使用CLI（若`plantuml`已在PATH中）：
```bash
plantuml -tsvg diagram.puml
plantuml -tpng -o ./output/ *.puml
plantuml -checkonly diagram.puml
渲染完成后，使用
present_files
向用户展示输出文件。
完整选项、环境变量、格式、故障排除：
references/local-rendering.md

§ Diagnose & Fix PUML

§ 语法速查表（超精简版）

bash
python3 scripts/render.py diagram.puml --check
ErrorCauseFix
No @startuml found
Missing wrapperAdd 
@startuml
/ 
@enduml
Unknown command
Typo or wrong diagram typeCheck syntax-quick-ref.md
Arrow 
→
(Unicode)		ASCII requiredUse 
->
not 
→
Cannot find class
Forward referenceDeclare before use
Graphviz error
dot
not installed
brew/apt install graphviz
OR add 
!pragma layout smetana
PlantUML not foundNot installed
bash scripts/bootstrap.sh
Java not detectedNon-standard JDKSet 
JAVA_HOME
env var
Python not foundPython missing
bash scripts/bootstrap.sh
Unicode brokenCharset issue
plantuml -charset UTF-8 file.puml
完整参考（全部27章，2700+行）：
references/syntax-quick-ref.md
序列图箭头：
->   同步调用          -->  响应/虚线
->>  细线箭头           -->> 细虚线箭头
->x  消息丢失           ->o  开放箭头
<->  双向箭头  ->+  激活   -->-  取消激活
[->  传入箭头      ->]   传出箭头
类图关系：
<|--  继承    <|..  实现
o--   聚合    *--   组合
-->   依赖     ..>   使用
--    关联    --()  棒棒糖（提供的接口）
"1" *-- "0..*"  : label （带基数和标签）
ER图基数（乌鸦脚表示法）：
||   恰好一个    o|   零或一个
o{   零或多个   |{   一个或多个
所有@start标签：
@startuml          大多数图表
@startmindmap      思维导图
@startgantt        甘特图
@startwbs          工作分解结构
@startsalt         线框图
@startjson         JSON展示
@startyaml         YAML展示
@startmath         AsciiMath公式
@startlatex        LaTeX公式
@startditaa        Ditaa ASCII艺术图
通用格式化：
plantuml
title My Title
skinparam shadowing false
skinparam monochrome true
!theme cerulean
left to right direction
!pragma layout smetana    ' 无需Graphviz

§ Syntax Cheatsheet (Ultra-Quick)

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

Full reference (all 27 chapters, 2700+ lines): 
references/syntax-quick-ref.md
Sequence arrows:
->   sync          -->  response/dashed
->>  thin           -->> thin dashed
->x  lost           ->o  open arrowhead
<->  bidirectional  ->+  activate   -->-  deactivate
[->  incoming      ->]   outgoing
Class relationships:
<|--  inheritance    <|..  realization
o--   aggregation    *--   composition
-->   dependency     ..>   usage
--    association    --()  lollipop (provided interface)
"1" *-- "0..*"  : label  (with cardinality and label)
ER cardinality (crow's foot):
||   exactly one    o|   zero or one
o{   zero or more   |{   one or more
All @start tags:
@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
Universal formatting:
plantuml
title My Title
skinparam shadowing false
skinparam monochrome true
!theme cerulean
left to right direction
!pragma layout smetana    ' no Graphviz needed
章节类型说明
1序列图完整支持：箭头、分组、激活、注释、自动编号、主框架、并行、构造型/标记点、锚点、包含、隐藏页脚
2用例图完整支持：参与者、扩展/包含、注释、包、业务用例、JSON覆盖
3类图完整支持：可见性、构造型、标记点、泛型、棒棒糖、继承/实现关键字、隐藏/显示/移除、$tags、命名空间
4对象图实例、关系、映射、关联对象
5活动图（旧版）旧版
(*) -->
语法、分支、同步条、分区
6活动图（新版）开始/结束、if/else/elseif、switch/case、while、repeat、分叉、拆分、泳道、SDL形状、goto/label、连接器、条件样式
7组件图组件、接口、球窝连接、分组、端口、隐藏未链接元素
8部署图所有元素类型、嵌套、端口、圆角、方向
9状态图嵌套、并发、分叉/合并、历史状态、选择、引脚、扩展、链接注释、内联颜色
10时序图鲁棒性、简洁性、二进制、时钟、模拟；相对时间、锚点、高亮
11JSON展示、高亮、样式、极简示例
12YAML展示、高亮、别名、Creole标记
13网络图（nwdiag）网络、节点、地址、分组、精灵图、对等网络
14线框图（Salt）所有组件：按钮、输入框、下拉菜单、单选框、复选框、网格、树、标签页、分组框、滚动框
15ArchiMatearchimate关键字、连接点、宏、标准库集成
16甘特图任务、约束、里程碑、颜色、完成百分比、超链接、休息日、缩放、比例
17思维导图OrgMode和Markdown语法、左侧分支、多根节点、颜色、方向
18工作分解结构OrgMode语法、方向、颜色、箭头、自动换行
19数学公式AsciiMath（
@startmath
）、LaTeX/JLaTeXMath（
@startlatex
）、内联
<math>
标签
20ER图（信息工程）实体、属性、主键/外键标记、乌鸦脚关系
21通用命令注释、缩放、标题、说明、页眉、页脚、图例、新页面、主框架、附录、编译指示
22Creole标记粗体、斜体、等宽、删除线、下划线、波浪线；列表、标题、表格、链接、表情、HTML标签、Unicode
23精灵图定义十六进制精灵图、内联SVG精灵图、从标准库导入、OpenIconic、Font Awesome
24Skinparam样式全元素Skinparam支持 + 现代
<style>
类CSS替代方案 + 所有主题
25预处理变量、条件、while/循环、过程、函数、默认参数、无引号参数、关键字参数、导入、子部分、主题、定义、内置函数（
%string
、
%strlen
、
%date
、
%random
、
%hsl_color
等）
26Unicode原生UTF-8、
&#XXXX;
和
<U+XXXX>
引用、表情
<:name:>
、字符集标记
27标准库ArchiMate、AWS、Azure、C4、Kubernetes、Elastic、GCP、CloudOgu、Tupadr3/FontAwesome、EDGY
—Ditaa
@startditaa
ASCII艺术图转图表

Complete Diagram Coverage (All 27 Chapters from PDF)

参考文件

ChTypeNotes
1SequenceFull: arrows, groups, activation, notes, autonumber, mainframe, parallel, stereotypes/spots, anchors, encompass, hide footbox
2Use CaseFull: actors, extends/include, notes, packages, business UC, JSON overlay
3ClassFull: visibility, stereotypes, spots, generics, lollipop, extends/implements keywords, hide/show/remove, $tags, namespaces
4ObjectInstances, relations, maps, association objects
5Activity (Legacy)Old 
(*) -->
syntax, branches, synchronization bars, partitions
6Activity (New)start/stop, if/else/elseif, switch/case, while, repeat, fork, split, swimlanes, SDL shapes, goto/label, connectors, condition style
7ComponentComponents, interfaces, ball-socket, grouping, ports, hide unlinked
8DeploymentAll element types, nesting, ports, round corners, orientation
9StateNested, concurrent, fork/join, history, choice, pin, expansion, note on link, inline colour
10Timingrobust, concise, binary, clock, analog; relative time, anchors, highlights
11JSONDisplay, highlight, styles, minimal examples
12YAMLDisplay, highlight, aliases, Creole
13Network (nwdiag)Networks, nodes, addresses, grouping, sprites, peer networks
14Wireframe (Salt)All widgets: button, input, dropdown, radio, checkbox, grid, tree, tabs, group box, scrollbox
15Archimatearchimate keyword, junctions, macros, StdLib integration
16GanttTasks, constraints, milestones, colours, completion %, hyperlinks, closed days, zoom, scale
17MindMapOrgMode and Markdown syntax, left branches, multiroot, colours, direction
18WBSOrgMode syntax, direction, colours, arrows, word wrap
19MathsAsciiMath (
@startmath
), LaTeX/JLaTeXMath (
@startlatex
), inline 
<math>
tags
20ER (Info Engineering)Entities, attributes, PK/FK markers, crow's foot relations
21Common Commandscomments, scale/zoom, title, caption, header, footer, legend, newpage, mainframe, appendix, pragma
22CreoleBold, italic, mono, strike, underline, wave; lists, headings, tables, links, emoji, HTML tags, Unicode
23SpritesDefine hex sprites, inline SVG sprites, import from StdLib, OpenIconic, Font Awesome
24SkinparamFull per-element skinparam + modern 
<style>
CSS-like alternative + all themes
25PreprocessingVariables, conditions, while/loop, procedures, functions, default args, unquoted, keyword args, includes, subparts, themes, define, builtins (
%string
, 
%strlen
, 
%date
, 
%random
, 
%hsl_color
, etc.)
26UnicodeNative UTF-8, 
&#XXXX;
and 
<U+XXXX>
references, emoji 
<:name:>
, charset flag
27StdLibArchiMate, AWS, Azure, C4, Kubernetes, Elastic, GCP, CloudOgu, Tupadr3/FontAwesome, EDGY
—Ditaa
@startditaa
ASCII art to diagram
文件内容
references/syntax-quick-ref.md
2700+行——全部27章的完整语法
references/image-to-puml.md
图像转PUML逆向工程的视觉分析指南
references/local-rendering.md
安装设置、CLI参数、格式、环境变量、故障排除

Reference Files

脚本说明

FileContent
references/syntax-quick-ref.md
2700+ lines — complete syntax for all 27 chapters
references/image-to-puml.md
Visual analysis guide for image→PUML reverse engineering
references/local-rendering.md
Setup, CLI flags, formats, env vars, troubleshooting
脚本用途
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

Scripts

—
ScriptPurpose
scripts/bootstrap.sh
Start here — macOS/Linux — installs Python→Java→PlantUML (no deps)
scripts/bootstrap.ps1
Start here — Windows — PowerShell 5+, no deps required
scripts/setup.py
Python setup: detect/install Java + PlantUML; also reports Python
scripts/render.py
Cross-platform render: auto-detects Python/binary/JAR/Java
—