plantuml

PlantUML 图表

生成结构有效、语义明确且布局清晰的 PlantUML。

路由

• UML、C4、企业架构或 .puml 输出请选择 PlantUML。
• 对于直接嵌入 Markdown 的轻量级图表，请选择 mermaid 技能。使用以下命令安装：npx skills add full-stack-skills/document-skills --skill mermaid。
• 如果明确要求托管式编辑或 ProcessOn 输出，请选择 processon-diagram-generator 技能。使用以下命令安装：npx skills add full-stack-skills/document-skills --skill processon-diagram-generator。
• 如果请求的表示法或目标格式已确定渲染器，请勿询问用户要选择哪种渲染器。

工作流

1. 从请求和源内容中提取参与者、组件、类型、状态、消息或部署节点。
2. 选择图表类型和预期抽象级别。
3. 生成包含匹配起始／结束指令的完整源代码块。
4. 为较长的名称使用别名，并使用包／边界进行有意义的分组。
5. 在可用时使用本地 PlantUML 渲染器进行验证；否则执行结构检查。
6. 仅在用户要求或需要集成到现有文档树中时，才保存 .puml 文件。

图表选择

需求	主要语法
运行时交互	sequence、participant、actor
静态类型模型	class、interface、关系
逻辑架构	component、package、interface
运行时拓扑	node、cloud、database、artifact
生命周期	state、[*]
工作流	start、if、while、fork、stop
用户目标	actor、usecase
C4 模型	C4 include 加上 Person、System、Container、Component

仅在需要了解语法细节时，加载 examples/ 下匹配的文件。

编写规则

• 使用 @startuml 和 @enduml 包裹标准 UML 图表。
• 只定义一次别名，并保持一致地重复使用。
• 在有助于理解时，为关系标注用途或协议。
• 如果一张图过于拥挤，请将逻辑架构与部署拓扑分开。
• 保持 C4 各层级彼此独立；除非有明确理由，否则不要混合上下文、容器和组件细节。
• 除非用户接受依赖网络的渲染，否则避免使用远程 !include 依赖。
• 不要臆造缺乏依据的组件、协议、多重性或调用。

输出

内联交付：

```plantuml
@startuml
actor User
participant API
database DB
User -> API: Submit request
API -> DB: Persist data
DB --> API: Result
API --> User: Response
@enduml
```

文件交付：除非仓库另有约定，否则优先使用 docs/diagrams/<descriptive-name>.puml。绝不静默覆盖。

验证清单

• 起始／结束指令匹配。
• 别名及引用的元素均已定义。
• 关系方向和多重性均经过有意设定。
• 目标渲染环境中提供 C4 include。
• 源码中不包含机密信息或特定于机器的路径。
• 在渲染器可用时，本地渲染成功。