Communitygithub.com

BESSER-PEARL/uml-drawing

Agent技能:通过BESSER B-UML绘制正确的UML类图,并一步渲染为可嵌入的SVG/PNG——无需浏览器。适用于README、设计文档、Wiki和幻灯片。

uml-drawing 是什么?

该技能使AI代理能够从描述、现有代码或受支持的导入路径(如PlantUML、Draw.io)构建正确的B-UML领域模型,并生成精确的类图。它通过BESSER的无头SVG端点自动渲染图像,或允许在编辑器中进行手动布局调整。该技巧确保文档中的图表与底层模型始终保持一致,并可作为真理之源用于生成代码(如Python、SQL、FastAPI)。支持多种交付方式:在文档中嵌入可运行的B-UML Python代码,或直接嵌入可缩放的SVG/PNG图像。该技能专为AI代理设计,适用于Claude Code、Coder、Cursor和Copilot等平台,它无缝集成到文档工作流中,使代理能够生成可直接提交到仓库的正确、美观的图表。

兼容平台✓Claude Code~Codex CLI✓Cursor✓Windsurf
npx skills add BESSER-PEARL/uml-drawing

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

预览

来自技能 README

数据模型

文档

在文档中嵌入正确的UML图表

代理经常被要求为文档“添加图表” —— 但它们常常在建模上出现细微错误(无效多重性、箭头反向、继承方向错误),或是返回一个从未渲染成图片的代码块。此技能可生成正确的类图和真正的可嵌入图像。

范围

  • 仅限类图 —— 目前支持类、属性、关联、多重性、继承。其他UML图类型(状态机、对象、序列、活动等)不在此技能范围内。
  • 始终通过BESSER B-UML实现。 每个图表都首先构建为B-UML DomainModel,然后再交付。通过模型构建才能确保图表正确且可作为代码重用。

可以从哪里开始

  • 一段描述 —— 用户解释领域;代理编写模型。
  • 现有代码 —— 代理读取源代码并根据其结构构建B-UML模型。(没有自动代码扫描器;代理根据读取的内容进行建模 —— 它不是一键导入器。)
  • 受支持的转换为B-UML的路径 —— PlantUML、Draw.io或UI原型。

两种交付方式

一次建模,然后作为嵌入式B-UML代码(交付A)或渲染图像(交付B)交付 —— 两者基于同一个模型,因此永远不会不一致。根据上下文选择(应保持可运行的设计文档 → 代码;应显示图片的README → 图像),或两者都提供。详情见下方交付章节。

图表放置位置。 如果用户指定了目标文档(README、设计文档),则嵌入到该文件中。如果未指定 —— 或要求为仓库/系统生成独立图表 —— 则默认交付一个新的自包含的.md(例如 docs/<model>.md):包含渲染图像(交付B)和/或B-UML代码(交付A),以及一两行解释图表内容的说明。这样可以将“绘制我的仓库图表”这样的需求转化为一个可提交的文档,而不是一个松散的SVG。当创建新文件时,告知放置位置(并主动提供替代方案 —— 改为嵌入到现有文档中 —— 如果这可能是用户想要的)。

工作流程

1. 构建B-UML模型 —— 从描述、代理读取的现有代码,或通过受支持的转换为B-UML的路径(PlantUML / Draw.io / 原型)
2. model.validate()  → 确认模型结构正确

然后交付其一(或两者):

  A) 嵌入代码: 将DomainModel Python代码放入.md的围栏代码块中
  B) 嵌入图像: 将模型POST到BESSER的无头SVG端点(一次HTTP调用 —— 无需浏览器),
     保存返回的SVG(例如 docs/img/data-model.svg),
     嵌入  ![数据模型](docs/img/data-model.svg)

3. 当模型变更时,更新模型并重新交付 —— 单一真理之源

1. 构建模型

正确的图表始于正确的模型。最小示例如下:

from besser.BUML.metamodel.structural import (
    DomainModel, Class, Property, Multiplicity,
    BinaryAssociation, Generalization, StringType, IntegerType,
)

publication = Class(name="Publication", attributes={Property(name="title", type=StringType)})
book   = Class(name="Book",   attributes={Property(name="pages", type=IntegerType)})
author = Class(name="Author", attributes={Property(name="name", type=StringType)})

book_is_a = Generalization(general=publication, specific=book)   # Book is a Publication

# A Book is written by 1..* Authors; an Author writes 0..* Books
written_by = Property(name="writtenBy", type=author, multiplicity=Multiplicity(1, "*"))
writes     = Property(name="writes",    type=book,   multiplicity=Multiplicity(0, "*"))
book_author = BinaryAssociation(name="book_author", ends={written_by, writes})

model = DomainModel(
    name="Library",
    types={publication, book, author},
    associations={book_author},
    generalizations={book_is_a},
)
assert model.validate()["success"]

命名:无空格,无连字符。对于超出此最小形状的所有内容 —— 枚举、所有多重性/组合模式、关联类、泛化集、方法、验证细节 —— 请阅读**references/class-diagram.md**(随此技能捆绑)。对于非类模型类型(对象、特征、部署、OCL等),请参阅BESSER平台的besser-user技能。

可导入形式 —— 两种交付路径均必需。 将每个Class(...)、BinaryAssociation(...)和Generalization(...)编写为显式的顶级赋值语句,完全如上所示。BESSER的导入器(由SVG端点和编辑器导入功能使用)读取文件的结构 —— 它不会执行文件 —— 因此在辅助函数或循环中构建的关系是不可见的:类会被导入但关联会无声消失。每个关系使用一个字面语句。

由于导入器从不运行文件,model.validate()在渲染路径上不会被执行 —— 您无需安装BESSER即可通过端点渲染。在您确实本地安装了BESSER时(以及在生成代码之前)保留validate()调用;对于端点而言它是空操作,而不是要求。

模型来源:

  • 从描述构建 —— 按如上方式编写。
  • 从现有代码构建 —— 读取源代码并将其结构(类、字段、关系、继承)转换为B-UML模型。代理负责建模;没有自动代码扫描器。
  • 从PlantUML / Draw.io / UI原型 —— 使用匹配的转换为B-UML的转换(可通过BESSER平台获得),然后继续。

现在以两种方式之一交付。

交付A —— 在文档中嵌入B-UML代码

将模型直接放入.md文件的围栏```python代码块中。它是正确的、经过validate()检查的、可重新运行的,并且可导入到编辑器中。最适合文档本身需要携带模型的情况(设计文档、规范):

## 数据模型

```python
# (上面的DomainModel)
```

此B-UML模型是该领域的真理之源 —— 经过`validate()`检查,并且是任何BESSER生成器的输入。

交付B —— 嵌入渲染图像

模型通过BESSER的渲染器变成真正的图片,因此图像始终与模型匹配。两种方式 —— 根据您是希望自动完成还是手动调整来选择。

B1. 自动渲染(默认)—— 一次HTTP调用,无需浏览器

BESSER暴露了一个无头的B-UML → SVG端点。代理POST模型的.py文件并获取SVG返回 —— 无需编辑器、无需手动操作、用户无需点击任何东西:

curl -X POST https://editor.besser-pearl.org/besser_api/get-svg \
  -F "[email protected];type=text/x-python" \
  -o docs/img/data-model.svg

端点解析B-UML,自动布局,并返回image/svg+xml。将其保存到仓库并嵌入:

![数据模型](docs/img/data-model.svg)
  • 模型文件必须是可导入形式(参见§1中的说明)—— 即编辑器导入的相同形式。仅限类图。
  • 布局是自动的。当布局位置很重要时,使用B2手动调整。
  • 将.py保存为无BOM的UTF-8 —— 前导字节顺序标记会使端点拒绝文件(HTTP 400)。
  • 在您在此渲染的模型中省略枚举字面量default_value=... —— 端点当前会因此失败(HTTP 500)。它对于代码生成是没问题的;将普通枚举用作属性类型可以正常渲染。
  • 非200响应是小的JSON错误,而不是SVG({ "detail": ... })—— 在保存前检查状态。

B2. 从编辑器手动调整导出(当布局重要时)

打开 https://editor.besser-pearl.org ,导入.py(选择B-UML格式),拖拽框和路由线以达到理想效果,然后导出并选择格式:

  • SVG —— 在任何尺寸下都清晰;最适合文档和Web。
  • PNG —— 透明背景。
  • PNG(白色背景) —— 适用于需要不透明图像的表面。

保存到仓库并以相同方式嵌入。(编辑器还可以将模型导出为B-UML或JSON —— 这些是模型本身,而非图像。)

无论哪种方式,SVG和PNG在所有支持Markdown图像的地方都能渲染 —— GitHub、GitLab、文档站点、Wiki、幻灯片 —— 无需插件。

防止漂移

无论选择哪种模式,模型都是真理之源。当需求变更时,更新模型并重新交付(重新粘贴代码,或重新导出图像)—— 切勿手动编辑导出的SVG/PNG,它是生成的。

超越图片的价值

由于图表是真正的B-UML模型,同一件制品可以生成可工作的代码 —— Python类、SQL、FastAPI后端、Django、React等。为解释系统而绘制的图表可以变成系统本身。要从中生成代码,请参考besser-generators技能。

何时使用相关技能

  • 深入构建模型(枚举、继承、方法、OCL、对象/特征/部署/神经网络/量子模型)→ besser-user技能。
  • 从模型生成代码 → besser-generators技能。
  • 错误(导入/验证/编辑器问题)→ besser-troubleshooting技能。

相关技能