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-
DomainModelgebaut 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 
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(...)undGeneralization(...)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 denvalidate()-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:

- 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
.pyals 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.