Communitygithub.com

BESSER-PEARL/uml-drawing

Agent-Fähigkeit: Zeichne ein korrektes UML-Klassendiagramm via BESSER B-UML und rendere es in einem Aufruf als einbettbares SVG/PNG – ganz ohne Browser. Für READMEs, Design-Dokumente, Wikis und Folien.

Was ist uml-drawing?

Diese Fähigkeit befähigt KI-Agenten, korrekte UML-Klassendiagramme zu erstellen und als echte, einbettbare Bilder (SVG/PNG) auszugeben – ohne dass ein Browser oder manuelle Nachbearbeitung nötig ist. Der Agent modelliert die Domäne als B-UML `DomainModel`, entweder aus einer Beschreibung, aus vorhandenem Code oder aus gängigen Formaten wie PlantUML, Draw.io oder einem UI-Mockup. Das Modell wird validiert und dann entweder als wiederverwendbarer Python-Code (in einen Markdown-Block eingebettet) oder als gerendertes Bild über einen einfachen HTTP-Aufruf an den BESSER-Headless-SVG-Endpunkt ausgeliefert. Das Ergebnis ist ein korrektes, mit der UML-Syntax übereinstimmendes Diagramm, das in READMEs, Design-Dokumente, Wikis oder Folien eingefügt werden kann – und gleichzeitig die Grundlage für die Codegenerierung mit anderen BESSER-Fähigkeiten bildet. Plattformen: Claude Code, Cursor, Codex und andere KI-Agenten.

Funktioniert mit✓Claude Code~Codex CLI✓Cursor✓Windsurf
npx skills add BESSER-PEARL/uml-drawing

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Vorschau

Aus dem Skill-README

Datenmodell
Datenmodell

Dokumentation

Ein korrektes UML-Diagramm in deine Dokumente einbetten

Agenten werden ständig gebeten, „ein Diagramm“ zur Dokumentation hinzuzufügen – und sie bekommen die Modellierung oft subtil falsch hin (ungültige Multiplizitäten, Pfeile verkehrt herum, Vererbung rückwärts) oder geben einen Codeblock zurück, der nie als Bild gerendert wird. Diese Fähigkeit erzeugt ein korrektes Klassendiagramm und ein echtes einbettbares Bild.

Umfang

  • Nur Klassendiagramme, vorerst – Klassen, Attribute, Assoziationen, Multiplizitäten, Vererbung. Andere UML-Diagrammtypen (Zustandsautomaten, Objekte, Sequenzen, Aktivitäten, …) fallen nicht in den Umfang dieser Fähigkeit.
  • Immer über BESSER B-UML. Jedes Diagramm wird zuerst als B-UML-DomainModel gebaut und dann ausgeliefert. Der Weg über das Modell macht das Diagramm korrekt und als Code wiederverwendbar.

Wo es beginnen kann

  • Eine Beschreibung – der Benutzer erklärt die Domäne; der Agent schreibt das Modell.
  • Vorhandener Code – der Agent liest die Quelle und baut das B-UML-Modell aus ihrer Struktur. (Es gibt keinen automatischen Code-Scanner; der Agent erledigt die Modellierung aus dem, was er liest – es ist kein One-Click-Importer.)
  • Ein unterstützter into-B-UML-Pfad – PlantUML, Draw.io oder ein UI-Mockup.

Zwei Arten der Auslieferung

Einmal modellieren, dann als eingebetteten B-UML-Code (Auslieferung A) oder als gerendertes Bild (Auslieferung B) ausliefern – beide aus demselben Modell, sodass sie nie widersprechen. Wähle je nach Kontext (ein Design-Dokument, das ausführbar bleiben soll → Code; eine README, die ein Bild zeigen soll → Bild) oder biete beides an. Details in den Auslieferungsabschnitten unten.

Wo es landet. Wenn der Benutzer ein Zieldokument nennt (eine README, ein Design-Dokument), bette es in diese Datei ein. Wenn er keins nennt – oder ein eigenständiges Diagramm eines Repositorys/Systems anfordert – liefere standardmäßig eine neue eigenständige .md aus (z. B. docs/<Modell>.md): das gerenderte Bild (Auslieferung B) und/oder den B-UML-Code (Auslieferung A), plus ein oder zwei Zeilen Erklärung, was das Diagramm zeigt. Das macht aus einem bloßen „Diagrammiere mein Repo“ ein commitierbares Dokument statt einer lose SVG. Wenn du eine neue Datei erstellst, sage, wo du sie abgelegt hast (und biete die Alternative an – stattdessen in ein vorhandenes Dokument einbetten – falls das gewünscht sein könnte).

Arbeitsablauf

1. Baue das B-UML-Modell – aus einer Beschreibung, aus vorhandenem Code, den der Agent liest, oder über einen unterstützten into-B-UML-Pfad (PlantUML / Draw.io / Mockup)
2. model.validate() → bestätige, dass es strukturell korrekt ist

Dann liefere eines (oder beide) aus:

  A) Bette den Code ein: füge das DomainModel-Python in einen fenced-Block in der .md ein
  B) Bette ein Bild ein: POSTe das Modell an BESSERs Headless-SVG-Endpunkt (ein HTTP-Aufruf – kein Browser), speichere das zurückgegebene SVG (z. B. docs/img/data-model.svg), bette es ein mit ![Datenmodell](docs/img/data-model.svg)

3. Wenn sich das Modell ändert, aktualisiere das Modell und liefere erneut aus – eine einzige Quelle der Wahrheit

1. Das Modell bauen

Ein korrektes Diagramm beginnt mit einem korrekten Modell. Die minimale Form:

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

publikation = Class(name="Publikation", attributes={Property(name="titel", type=StringType)})
buch        = Class(name="Buch",       attributes={Property(name="seiten", type=IntegerType)})
autor       = Class(name="Autor",      attributes={Property(name="name", type=StringType)})

buch_ist_eine = Generalization(general=publikation, specific=buch)   # Buch ist eine Publikation

# Ein Buch wird von 1..* Autoren geschrieben; ein Autor schreibt 0..* Bücher
geschrieben_von = Property(name="geschriebenVon", type=autor, multiplicity=Multiplicity(1, "*"))
schreibt        = Property(name="schreibt",        type=buch,  multiplicity=Multiplicity(0, "*"))
buch_autor = BinaryAssociation(name="buch_autor", ends={geschrieben_von, schreibt})

model = DomainModel(
    name="Bibliothek",
    types={publikation, buch, autor},
    associations={buch_autor},
    generalizations={buch_ist_eine},
)
assert model.validate()["success"]

Benennung: keine Leerzeichen, keine Bindestriche. Für alles über diese minimale Form hinaus – Aufzählungen, alle Multiplizitäts-/Kompositionsmuster, Assoziationsklassen, Generalisierungsmengen, Methoden, Validierungsdetails – lies references/class-diagram.md (mit dieser Fähigkeit gebündelt). Für Nicht-Klassen-Modelltypen (Objekt-, Feature-, Bereitstellungs-, OCL-, …) siehe die besser-user-Fähigkeit der BESSER-Plattform.

Importierbare Form – erforderlich für beide Auslieferungspfade. Schreibe jede Class(...), BinaryAssociation(...) und Generalization(...) als explizite Top-Level-Zuweisung, genau wie oben gezeigt. BESSERs Importer (der vom SVG-Endpunkt und vom Import-Editor verwendet wird) liest die Struktur der Datei – er führt sie nicht aus – daher sind Beziehungen, die innerhalb einer Hilfsfunktion oder einer Schleife aufgebaut werden, unsichtbar: die Klassen werden importiert, aber die Assoziationen verschwinden stillschweigend. Eine literale Anweisung pro Beziehung.

Da der Importer die Datei niemals ausführt, wird model.validate() nicht auf dem Render-Pfad ausgeführt – du benötigst kein installiertes BESSER, um über den Endpunkt zu rendern. Behalte den validate()-Aufruf für den Fall, dass du BESSER lokal hast (und vor der Codegenerierung); es ist ein No-Op für den Endpunkt, keine Anforderung.

Woher das Modell kommt:

  • Aus einer Beschreibung – schreibe es wie oben.
  • Aus vorhandenem Code – lies die Quelle und übersetze ihre Struktur (Klassen, Felder, Beziehungen, Vererbung) in das B-UML-Modell. Der Agent erledigt die Modellierung; es gibt keinen automatischen Code-Scanner.
  • Aus PlantUML / Draw.io / einem UI-Mockup – verwende die entsprechende into-B-UML-Konvertierung (verfügbar über die BESSER-Plattform) und fahre dann fort.

Liefere es nun auf eine von zwei Arten aus.

Auslieferung A – Bette den B-UML-Code in das Dokument ein

Füge das Modell direkt in einen fenced- python -Block in der .md ein. Es ist korrekt, validate()-geprüft, wieder ausführbar und in den Editor importierbar. Am besten, wenn das Dokument das Modell selbst enthalten soll (ein Design-Dokument, eine Spezifikation):

## Datenmodell

```python
# (das DomainModel von oben)
```

Dieses B-UML-Modell ist die Quelle der Wahrheit für die Domäne – `validate()`-geprüft und die Eingabe für jeden BESSER-Generator.

Auslieferung B – Ein gerendertes Bild einbetten

Das Modell wird durch BESSERs Renderer zu einem echten Bild, sodass das Bild immer zum Modell passt. Zwei Möglichkeiten – wähle danach, ob du es automatisiert oder manuell optimiert haben möchtest.

B1. Automatisch rendern (Standard) – ein HTTP-Aufruf, kein Browser

BESSER stellt einen Headless- B-UML → SVG -Endpunkt zur Verfügung. Der Agent POSTet die Modell-.py-Datei und erhält ein SVG zurück – kein Editor, keine manuellen Schritte, nichts zum Klicken für den Benutzer:

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

Der Endpunkt parst das B-UML, lay-outet es automatisch und gibt image/svg+xml zurück. Speichere es im Repository und bette es ein:

![Datenmodell](docs/img/datenmodell.svg)
  • Die Modelldatei muss in importierbarer Form vorliegen (siehe Hinweis in §1) – dieselbe Form, die der Editor importiert. Nur Klassendiagramme.
  • Das Layout ist automatisch. Wenn die Platzierung wichtig ist, optimiere es manuell mit B2.
  • Speichere die .py als UTF-8 ohne BOM – ein führendes Byte-Order-Mark führt zur Ablehnung der Datei durch den Endpunkt (HTTP 400).
  • Lasse enum-default_value=... in einem Modell weg, das du hier renderst – der Endpunkt scheitert derzeit daran (HTTP 500). Es ist für die Codegenerierung in Ordnung; ein einfaches Enum, das als Attributtyp verwendet wird, wird problemlos gerendert.
  • Eine Nicht-200-Antwort ist eine kleine JSON-Fehlermeldung, kein SVG ({ "detail": ... }) – überprüfe den Status vor dem Speichern.

B2. Manuell optimierter Export aus dem Editor (wenn das Layout wichtig ist)

Öffne https://editor.besser-pearl.org, Importiere die .py (wähle das B-UML-Format), ziehe Kästchen und Routenlinien nach Geschmack, dann Exportiere und wähle ein Format:

  • SVG – scharf in jeder Größe; am besten für Dokumente und das Web.
  • PNG – transparenter Hintergrund.
  • PNG (weißer Hintergrund) – für Oberflächen, die ein undurchsichtiges Bild benötigen.

Speichere es im Repository und bette es auf dieselbe Weise ein. (Der Editor kann das Modell auch als B-UML oder JSON exportieren – das sind das Modell, kein Bild.)

Auf beiden Wegen: SVG und PNG rendern überall dort, wo Markdown-Bilder es tun – GitHub, GitLab, Docs-Seiten, Wikis, Folien – ohne Plugin.

Verhindere Abweichungen

Unabhängig davon, welchen Modus du wählst, ist das Modell die Quelle der Wahrheit. Wenn sich die Anforderungen ändern, aktualisiere das Modell und liefere erneut aus (füge den Code erneut ein oder exportiere das Bild erneut) – bearbeite niemals ein exportiertes SVG/PNG von Hand, es ist generiert.

Der Mehrwert jenseits eines Bildes

Da das Diagramm ein echtes B-UML-Modell ist, kann dasselbe Artefakt funktionierenden Code generieren – Python-Klassen, SQL, ein FastAPI-Backend, Django, React und mehr. Ein Diagramm, das du gezeichnet hast, um das System zu erklären, kann zum System werden. Um daraus Code zu generieren, verweise auf die besser-generators-Fähigkeit.

Wann verwandte Fähigkeiten herangezogen werden sollten

  • Modelle im Detail bauen (Enums, Vererbung, Methoden, OCL, Objekt-/Feature-/Bereitstellungs-/NN-/Quantenmodelle) → die besser-user-Fähigkeit.
  • Code generieren aus dem Modell → die besser-generators-Fähigkeit.
  • Fehler (Import-/Validierungs-/Editor-Probleme) → die besser-troubleshooting-Fähigkeit.

Verwandte Skills