Communitygithub.com

BESSER-PEARL/uml-drawing

一種專業技能:透過 BESSER B-UML 繪製正確的 UML 類別圖,並在單次呼叫中將其轉換為可嵌入的 SVG/PNG,無需瀏覽器。適用於 README、設計文件、維基和簡報。

uml-drawing 是什麼?

這個技能專門解決一個常見的痛點:AI 代理被要求「畫圖」時,常產出語義錯誤的模型(如錯誤的多重性、反向箭頭、繼承關係錯誤),或是只給出無法渲染成圖片的程式碼區塊。使用者可以透過描述、現有程式碼或支援的導入路徑(PlantUML、Draw.io、UI 模型)提供來源,技能會先使用 BESSER B-UML 建立一個結構正確的 DomainModel,並驗證其正確性。接著,技能提供兩種交付方式:A) 將可執行的 B-UML Python 程式碼嵌入文件中;B) 透過一次 HTTP 呼叫(無需瀏覽器)將模型發送到 BESSER 的無頭 SVG 端點,直接取得可嵌入的 SVG 或 PNG 圖片。此技能支援多種平台(GitHub、GitLab、文件網站、維基、簡報),且模型為單一事實來源,後續若需修改,只需更新模型並重新交付即可,保持圖文一致。對於更深入的建模或程式碼生成,可參考相關的 besser-user 和 besser-generators 技能。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

預覽

來自技能 README

Data model

說明文件

在你的文件中嵌入正確的 UML 圖表

代理人經常被要求為文件「新增圖表」——但是他們經常會在不經意間把模型弄錯(無效的多重性、箭頭方向相反、繼承關係倒置),或是只提供一個永遠無法渲染成圖片的程式碼區塊。這項技能能產出正確的類別圖以及一個真正可嵌入的圖檔。

範圍

  • 僅限類別圖,目前如此——包含類別、屬性、關聯、多重性、繼承。其他 UML 圖表類型(狀態機、物件圖、序列圖、活動圖……)不在本技能範圍內。
  • 一律透過 BESSER B-UML。 每個圖表都先被建立成一個 B-UML DomainModel,然後再進行交付。透過模型來建立,才能確保圖表正確且可以重複利用為程式碼。

可以從哪裡開始

  • 一段描述——使用者解釋領域知識;代理人編寫模型。
  • 現有程式碼——代理人讀取原始碼並根據其結構建立 B-UML 模型。(沒有自動程式碼掃描器;代理人是透過讀取到的內容來建立模型——它並非一鍵匯入工具。)
  • 一個受支援的轉換路徑——PlantUML、Draw.io 或 UI 原型。

兩種交付方式

建立模型一次,然後交付為嵌入的 B-UML 程式碼(交付方式 A)或渲染後的圖片(交付方式 B)——兩者都基於同一個模型,因此它們的內容永遠不會不一致。根據情境選擇(一份設計文件應該保持可執行性 → 選擇程式碼;一份 README 應該顯示圖片 → 選擇圖片),或者兩者都提供。詳情請見下方「交付方式」章節。

圖表放置位置。 如果使用者指定了目標文件(如 README、設計文件),就嵌入到該文件中。如果使用者沒有指定——或者要求為某個儲存庫/系統畫一張獨立的圖表——預設情況下交付一個新的、獨立的 .md 檔案(例如 docs/<model>.md):包含已渲染的圖片(交付方式 B)和/或 B-UML 程式碼(交付方式 A),再加上一兩行文字說明圖表內容。這能將一個單純的「為我的儲存庫畫圖」請求轉變為一個可提交的文件,而非一個鬆散的 SVG。當你建立一個新檔案時,請告知檔案位置(並提供替代方案——改為嵌入到現有文件中——如果這可能更符合使用者的需求)。

工作流程

1. 建立 B-UML 模型——從一段描述、代理人讀取的現有程式碼,或透過受支援的轉換路徑(PlantUML / Draw.io / 原型)進行
2. model.validate() → 確認模型結構正確

然後交付其中一種(或兩種):

  A) 嵌入程式碼:將 DomainModel 的 Python 程式碼放入 .md 檔案中的程式碼區塊中
  B) 嵌入圖片:將模型 POST 到 BESSER 的無頭 SVG 端點(一次 HTTP 呼叫——無需瀏覽器),儲存回傳的 SVG(例如 docs/img/data-model.svg),然後嵌入  ![Data model](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 原型——使用對應的轉換工具(可透過 BESSER 平台取得)將其轉換為 B-UML,然後繼續。

現在,用以下兩種方式之一進行交付。

交付方式 A — 在文件中嵌入 B-UML 程式碼

直接將模型放入 .md 檔案中一個以 ```python 標記的程式碼區塊中。它是正確的、經過 validate() 檢查的、可重新執行的,並且可以匯入到編輯器中。最適合當文件本身需要攜帶模型時使用(例如設計文件、規格書):

## 資料模型

```python
# (來自上方的 DomainModel)
```

這個 B-UML 模型是該領域的單一事實來源——已通過 `validate()` 檢查,並且是任何 BESSER 程式碼產生器的輸入。

交付方式 B — 嵌入已渲染的圖片

模型會透過 BESSER 的渲染器變成真正的圖片,因此圖片始終與模型一致。有兩種方式——根據你希望它是全自動的還是可以手動調整來選擇。

B1. 自動渲染(預設方式)——一次 HTTP 呼叫,無需瀏覽器

BESSER 提供了一個無頭的 B-UML → SVG 端點。代理人將模型 .py 檔案 POST 過去,然後收到一個 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。將其儲存到儲存庫中並嵌入:

![Data model](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——在任何尺寸下都很清晰;最適合文件和網頁。
  • PNG——透明背景。
  • PNG(白色背景)——用於需要不透明圖片的表面。

將其儲存到儲存庫中,並以相同的方式嵌入。(編輯器也可以將模型匯出為 B-UML 或 JSON ——這些是模型本身,而非圖片。)

無論哪種方式,SVG 和 PNG 都能在所有支援 Markdown 圖片的地方渲染——GitHub、GitLab、文件網站、維基、簡報——無需任何外掛程式。

防止模型與圖片不同步

無論你選擇哪種模式,模型都是單一事實來源。當需求變更時,請更新模型並重新交付(重新貼上程式碼,或重新匯出圖片)——永遠不要手動編輯已匯出的 SVG/PNG,因為它們是產生的。

獲得圖片之外的好處

因為該圖表是一個真正的 B-UML 模型,同一個成品可以產生可運作的程式碼——Python 類別、SQL、FastAPI 後端、Django、React 等等。你用來說明系統而畫的圖表,可以變成系統本身。若要從模型產生程式碼,請參考 besser-generators 技能。

何時使用相關技能

  • 深入建立模型(列舉、繼承、方法、OCL、物件圖 / 特徵圖 / 部署圖 / 神經網路 / 量子模型)→ 使用 besser-user 技能。
  • 從模型產生程式碼 → 使用 besser-generators 技能。
  • 處理錯誤(匯入 / 驗證 / 編輯器問題)→ 使用 besser-troubleshooting 技能。

相關技能