PlantUML 与 AI：让 Copilot / Cursor 自动产出图代码的 prompt 模式

2025-2026 后，LLM 写 PlantUML 的能力已经能达到「5 句话出图」「自然语言描述→UML 代码」。这一篇整理实战 prompt 模板、常见错误、debug 技巧、以及最终的人工 review 准则。

LLM 写 PlantUML 的能力现状

实测结论（2026 年中）：

• Copilot / Cursor / Cline：在 .puml 文件上下文里，5-10 行提示能产出 80% 正确率的图
• ChatGPT / Claude / Gemini：给出系统 prompt + 详细描述，5-15 秒生成可工作代码
• 关键差距：图结构的「合法性」（UML 是否正确）LLM 还能搞定，但「视觉/排版」细节（节点位置、间距、配色）LLM 经常乱来，需要人工 review

让 LLM 生成正确 PlantUML 的关键

1. 输出格式约束

大部分 LLM 不擅长自己约束输出格式——你必须在 prompt 里强制：

1
2
3

Output ONLY the PlantUML code block, no explanation outside the block.
Do NOT include any markdown prefix like ```plantuml or ```.
Just the @startuml ... @enduml contents.

否则会输出：

1
2
3
4
5

```plantuml
@startuml
Alice -> Bob: hi
@enduml
```

并加一句话「这是 PlantUML 图代码…」。你要的是纯内容。

2. 限定图类型

PlantUML 有 20+ 种图——LLM 容易「瞎猜」画错图：

1
2
3
4
5
6
7
8
9

Draw a UML sequence diagram in PlantUML with EXACTLY these participants:
- 3 actors: User, Frontend, AuthService
- 4 messages in this exact order:
  1. User -> Frontend: click login
  2. Frontend -> AuthService: POST /login
  3. AuthService --> Frontend: 200 token
  4. Frontend --> User: redirect
Use plain PlantUML `->` for synchronous messages and `-->` for replies.
Do NOT use any skinparam customization.

注意强制「EXACTLY these participants」+ 顺序 + 关系类型 + 「Do NOT use skinparam」。

3. 给示例（少样本）

LLM 学习最快的方式是举例。一次对话里给一个例子，下一次 prompt 就有模板可参考：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Use this as a reference structure (don't copy verbatim):

@startuml
participant "用户" as U
participant "前端" as F
participant "后端" as B

U -> F: 点击注册
F -> B: POST /api/register
B --> F: 200 OK
F --> U: 跳转到首页
@enduml

Now draw this NEW sequence in the same style:
[your real description]

4 对话中累积上下文：第一次对话给「时序图规则」。第二次说「按上次的格式画 X」。第三次说「再画一个 X」，LLM 用前两次的模板套出来。

实战 prompt 模板库

模板 1: 时序图

1
2
3
4
5
6
7
8
9
10
11
12

# 任务
[业务描述，如「用户登录支付系统的 6 步」]

# 输出要求
1. PlantUML sequence diagram (@startuml ... @enduml)
2. 参与者 EXACTLY: list them in order
3. 消息 EXACTLY: list them in order with direction (-> or --> or ->>)
4. 无 skinparam，无主题，使用默认
5. 输出仅图代码块，无 markdown fence

# 验证
请在画完后自查：(a) 每个 participant 都至少参与一条消息？(b) 消息方向用对了？若不对重画。

模板 2: 类图

1
2
3
4
5
6
7
8
9

# 任务
从以下 Java class 描述生成 PlantUML class diagram:
[code snippet]

# 输出要求
1. 每个 class 一个 `class` 块，字段和方法显式列出（visibility: + public, - private, # protected）
2. 关系用：--|> 继承, *-- 组合, o-- 聚合, --> 关联
3. 不需要 include class 内部的 getter/setter
4. 输出仅图代码块，无 markdown fence

模板 3: 活动图

1
2
3
4
5
6
7
8
9
10

把以下流程图描述转成 PlantUML activity diagram：
- Start
- if-分支
- while 循环
- End

# 输出要求
1. PlantUML |start| / |分支| 活动 (用 () 或 {} 包裹)
2. 分支用 <branch> ... <branch> ... <merge> 或 if (...) then (...) endif
3. 输出仅图代码块

模板 4: 状态机

1
2
3
4
5
6
7
8

把以下状态枚举生成 PlantUML state diagram：
[Python enum 或 JS switch case]

# 输出要求
1. 用 state "name" as alias 命名
2. 转换用 state1 --> state2 : event/action
3. 复合状态用 state parent { ... }
4. 输出仅图代码块

常见 LLM 错误（你必须知道）

错误 1：消息方向乱用

1
2
3
4

@startuml
Alice <- Bob   ' 反向箭头
Alice <<- Bob  ' 不存在的语法
@enduml

LLM 训练数据有 PlantUML 老版本 / Mermaid 不同箭头。反向箭头在 PlantUML 不支持。在 review 阶段抓出来改成 Bob -> Alice。

错误 2：复合立体关系填错

1
2
3

User *-- Role     ' 用户「拥有」角色（组合）
User --> Profile  ' 用户关联 Profile
' 有时 LLM 写成 User -- Profile 然后本意是组合

注意 --* vs --o：「拥有」用实心菱形 *，「弱拥有」用空心菱形 o。

错误 3：嵌套 package + 错误 ident

1
2
3

package "Frontend" {
  class WebApp {     ' ✅
  }                  ' ✅

LLM 经常写：

1
2
3

package "Frontend" {
class WebApp {
}      ' ❌ 缺少一个 }，封闭错误

要再确认括号 / end / endif 数量。

错误 4：消息文字里出现 : 或 `

1
2

Alice -> Bob: prefix:value  ' ❌ 冒号截断消息
Alice -> Bob: "prefix:value" ' ✅ 引号包起来

LLM 输出 JSON 风格的 key:value 当消息文字经常踩坑。review 时一律用引号包消息文字。

错误 5：皮肤参数乱用

LLM 经常生成：

1
2
3

skinparam backgroundcolor #fafafa
skinparam nodesep 100
skinparam color arrow #ff0000

结果视觉上丑——你不需要花哨皮肤，让 prompt 显式禁用：「Use no skinparam customization」。

错误 6:!include 路径幻觉

LLM 会写出：

1
2

!include ./common/styles.puml
!include ../shared/nodes.puml

但这些路径可能根本不存在于你仓库。永远不要直接拿 LLM 生成的 !include 渲染——先确认文件存在并复制到本地。

验证流程

1. 本地植物uml CLI 试渲染

1
2
3

echo "@startuml
$(cat diagram.puml)
@enduml" > _test.puml && plantuml -tsvg _test.puml

如果 plantuml 报错（YAMLException / $jsException / 找不到 dot），先修源代码。

2. 在 VS Code 里看一下

VS Code PlantUML 插件显示渲染图——如果长这样：

• 节点重叠 → 调 nodesep 或加 package
• 边线穿过节点 → 加 ranksep 或拆 package
• 边线颜色太浅 → 加 skinparam ArrowColor #5B7C99

3. 把图嵌入真实文档后看

最终交付的是文档站里的图——一定要在「最终位置」（Hexo / GitHub / Notion）检查视觉。

Copilot 自动补全模板

如果用 VS Code + Copilot，做一个 .copilot-instructions.md 让它自动写 PlantUML：

1
2
3
4
5
6

When generating PlantUML code (between @startuml and @enduml):
- Use `->` for synchronous messages, `-->` for replies, `->>` for async
- Quote message text with double quotes when text contains ":" or "(" or ")"
- Never use `skinparam backgroundcolor` or other visual customization unless asked
- For class diagrams, use visibility markers: + public, - private, # protected
- Always end the file with @enduml on its own line

放仓库根目录 → Copilot 在 .puml 文件里自动采用。

Cursor / Cline 的用法

这两个 agent 化更彻底——你可以说：

“在 docs/diagrams/auth-flow.puml 里加一个错误处理分支”

agent 会：

1. 读现有 auth-flow.puml
2. 执行植物uml CLI 渲染 → 看图
3. 修改代码 → 重新渲染 → 对比
4. 写入到 docs/diagrams/

实测成功率 70-80%——10 步里有 2 步 agent 自己 debug，但比「人手工再写一遍」快。

评估 LLM 生成的图质量 — 6 维 checklist

小结

• LLM 写 PlantUML 已成熟到「可用」，但「完美」还是要人 review
• prompt 关键是「明确图类型 + 列出参与者 + 列消息 + 禁用皮肤」
• 错误点是方向、复合关系、CJK、消息中的 :
• 永远跑植物uml CLI 验证——别信 LLM 的「应该正确」

下一步

• PlantUML 与 IDE 集成：VS Code / JetBrains / Vim 三端实战
• PlantUML 大图拆分：subgraph、package、!include 让 1000 节点不卡顿