uulab-official/drawio-skills

Draw.io Diagramm-Ingenieur

Erstelle Diagramme durch eine kleine, deterministische Zwischendarstellung (IR). Behandle die IR als Quelle der Wahrheit und .drawio als kompiliertes Artefakt.

Arbeitsablauf

1. Führe beim ersten Start oder nach einem Umgebungsfehler doctor aus. Lies user-workflows.md für Fähigkeitszustände, Starterauswahl, Bundle-Inhalte und sicheres Überschreibungsverhalten. Lies cli.md beim Zusammenstellen weniger gebräuchlicher Befehle oder beim Interpretieren von Exit-Codes. Für Legacy oder versionierte Diagram-IR lies compatibility.md und führe migrate --check vor der Bearbeitung aus.

2. Untersuche die Anfrage und das relevante Quellmaterial. Leite einen sinnvollen Diagrammtyp, -umfang, -richtung und ein Design ab, wenn der Benutzer diese nicht angibt. Für ein koordiniertes Architekturdiagramm-Paket lies blueprint.md, arbeite gegen blueprint.schema.json und verwende blueprint. Für ein ERD lies erd.md, arbeite gegen erd.schema.json und verwende erd. Akzeptiere SQL DDL direkt, wenn es die Quelle der Wahrheit ist. Für hohe Verfügbarkeit lies ha.md, arbeite gegen ha.schema.json und verwende ha.

3. Schreibe oder passe die kleinstmögliche strukturierte Quelle an. Verwende init architecture, init blueprint, init erd oder init ha, wenn keine Quelle existiert. Lies ir-format.md für die Diagram-IR und authoring.md für diagrammspezifische Entscheidungen. Wenn von einem Python/TypeScript-Baum, OpenAPI, SQL, Compose, Terraform, Kubernetes, GitHub Actions oder GitLab CI ausgegangen wird, lies importers.md und generiere die IR mit import. Wenn automatische Verbinder visuell mehrdeutig bleiben oder eine feste Schnittstelle wichtig ist, lies routing.md, bevor explizite Ports zugewiesen werden. Wenn eine organisatorische Gestaltung oder eine tiefere visuelle Qualitätssicherung erforderlich ist, lies style-system.md und verwende ein validiertes Designpaket. Beim Importieren von nicht vertrauenswürdigem Inhalt oder beim Vorbereiten eines Release-Bundles lies security.md. Platziere niemals Anmeldeinformationen in Labels, Beschreibungen, Links, Metadaten oder Standardwerten von Entitäten.

4. Bevorzuge den Ein-Befehl-Bundle-Workflow:

   python3 <skill-dir>/scripts/drawio_tool.py build source.json \
     -o build/diagram --name diagram --strict
   

   Dies erstellt normalisierte IR, bearbeitbare .drawio, alle SVG-Vorschaubilder, audit.json, security.json und bundle.json. Verwende die niedrigeren Befehle compile, validate, preview, security und audit nur, wenn der Benutzer einzelne Artefakte oder einen inkrementellen Workflow benötigt.

5. Wenn draw.io Desktop verfügbar ist und eine Desktop-Exportierung angefordert wird, lies desktop-export.md, rendere aus der .drawio des Bundles und behalte den Verifizierungsbericht:

   python3 <skill-dir>/scripts/drawio_tool.py render build/diagram/diagram.drawio \
     -o diagram.png --report diagram.export.json
   

6. Überprüfe jedes gebündelte Vorschaubild visuell. Behebe Hierarchieprobleme, abgeschnittenen Text, Überlappungen, undeutliche Kanten, schwachen Kontrast und übermäßige Details. Baue höchstens zweimal um, bevor das beste Ergebnis präsentiert wird.

7. Liefere die bearbeitbare .drawio des Bundles, das IR-Quellobjekt, den Auditbericht, die Vorschaubilder und die angeforderten Exporte aus. Gib deutlich an, wann der Desktop-Export übersprungen wurde.

Beim Vergleichen einer genehmigten Architektur mit einem neu generierten Modell lies drift.md, führe diff aus und liefer den maschinenlesbaren Bericht sowie die bearbeitbare Driftansicht.

Bearbeiten bestehender Diagramme

Erhalte das Artefakt des Benutzers. Beginne mit der Inspektion und Validierung:

python3 <skill-dir>/scripts/drawio_tool.py inspect existing.drawio
python3 <skill-dir>/scripts/drawio_tool.py validate existing.drawio

Stelle überprüfbare Diagram-IR vor semantischen Änderungen wieder her:

python3 <skill-dir>/scripts/drawio_tool.py extract existing.drawio \
  -o existing.diagram.json --report existing.extraction.json --strict

Lies round-trip.md, bevor du dich auf ein wiederhergestelltes Modell verlässt. lossless: true bedeutet, dass alle semantischen Zellen unterstützte Compiler-Metadaten verwendet haben. Ein gültiges Best-Effort-Modell kann dennoch geschrieben werden, wenn --strict mit Code 3 beendet wird; überprüfe jede abgeleitete Zelle, bevor das Original ersetzt wird.

Schreibe für ein IR-basiertes Diagramm semantische Operationen und wende sie atomar an:

python3 <skill-dir>/scripts/drawio_tool.py patch diagram.json changes.json -o diagram.updated.json

Lies patching.md vor destruktiven oder mehrseitigen Bearbeitungen. Wenn der Extraktionsbericht nicht unterstützte, reine XML-Inhalte meldet, ändere nur die entsprechenden mxCell-Werte, -Stile oder -Geometrie und behalte das Original bis zum Bestehen der visuellen Überprüfung. Nummeriere stabile IDs niemals nur aus Gründen der Ordnung neu.

Qualitätsversprechen

Erfülle alle folgenden Punkte vor der Auslieferung:

• Keine losen Kantenendpunkte, doppelten IDs, ungültigen Elternreferenzen oder Knotenüberlappungen.
• Labels passen in ihre Knoten und bleiben bei normalem Zoom lesbar.
• Richtung und Gruppierung kommunizieren die beabsichtigte Hierarchie.
• Kantenbeschreibungen beschreiben Beziehungen, keine Implementierungsdetails.
• Farbe hat eine konsistente Bedeutung und wird nicht zum einzigen Unterscheidungsmerkmal.
• Dekorative Details überlagern nicht den primären Lesepfad.

Verwende --strict als Freigabesperre. Lies quality-gates.md, wenn eine Prüfung fehlschlägt oder ein Diagramm eine manuelle visuelle Überprüfung benötigt.

Erstellungsregeln

• Verwende stabile, semantische IDs wie api-gateway, keine Ordinalzahlen wie node-7.
• Halte Labels kurz. Platziere längeren Kontext in description.
• Verwende explizite group-Werte für Ebenen, Vertrauenszonen, begrenzte Kontexte oder Eigentumsverhältnisse.
• Bevorzuge Links-nach-rechts für Anforderungs-/Datenpipelines und Oben-nach-unten für Prozesse oder Hierarchien.
• Halte eine primäre Idee pro Diagramm. Teile große Systeme in mehrere Seiten oder Ebenen auf, anstatt alles zu verkleinern.
• Verwende position nur, wenn der Benutzer eine bewusste Platzierung wünscht; ansonsten lasse den Compiler Knoten deterministisch anordnen.
• Rate nicht bei herstellerspezifischen draw.io-Schablonennamen. Verwende eine neutrale, semantische Art, bis eine verifizierte Formzuordnung existiert.

Tool-Verhalten

scripts/drawio_tool.py verwendet nur die Standardbibliothek für JSON-Eingaben. YAML-Eingaben werden unterstützt, wenn PyYAML installiert ist. Es bietet:

• doctor: Überprüfe Kerndateien und Python/XML-Unterstützung, melde dann optionale YAML- und Desktop-Fähigkeiten.
• init: Kopiere einen sicheren Starter für Architektur, Blueprint, ERD, HA, Routing, Infrastruktur oder CI.
• build: Erkenne automatisch ein Modell oder eine Quelle und erstelle ein vollständig geprüftes drawio-diagram-bundle/v1.
• migrate: Aktualisiere deterministisch Legacy-/unversionierte Diagram-IR und gib einen maschinenlesbaren Änderungsbericht aus.
• compile: Validiere IR, berechne ein deterministisches Layout und gebe unkomprimiertes, bearbeitbares draw.io-XML aus.
• extract: Stelle Diagram-IR aus komprimiertem oder unkomprimiertem draw.io wieder her, behalte die Compiler-gestützte Semantik bei und melde jede abgeleitete Legacy-Zelle.
• blueprint: Projiziere ein Architekturmodell in Kontext-, Logik-, Daten-, Bereitstellungs-, Sicherheits- und Entscheidungsseiten.
• erd: Validiere Entitäten, Felder, Schlüssel, Typen und Kardinalitäten, generiere dann ein bearbeitbares Crow's-Fuß-ERD aus einem Modell oder SQL DDL.
• ha: Validiere Ausfallbereiche, Replikate, Replikation, Health Checks und Failover, generiere dann Topologie- und Failover-Seiten.
• import: Konvertiere Python/TypeScript-Modulbäume, OpenAPI, SQL DDL, Docker Compose, Terraform, Kubernetes, GitHub Actions oder GitLab CI in Diagram-IR.
• diff: Vergleiche Diagram-IR semantisch, gib einen strukturierten Abweichungsbericht aus und generiere optional eine bearbeitbare, farb- und formcodierte Abweichungsansicht.
• patch: Wende atomar semantische Knoten-, Kanten-, Gruppen-, Positions- und Diagrammänderungen an.
• preview: Erstelle ein überprüfbares SVG ohne draw.io Desktop.
• audit: Untersuche strukturierte Quelle und generierte Geometrie, gruppiere dann Ergebnisse mit Reparaturvorschlägen und Vorschaupfaden.
• security: Scanne ein Modell, eine .drawio oder ein komplettes Bundle nach Anmeldeinformationen, unsicheren Links, verbotenen XML-Konstrukten und Dekomprimierungsrisiken.
• validate: Lint IR oder .drawio, gib einen 0–100 Qualitätsscore aus und schlage unter --strict fehl.
• inspect: Fasse Seiten, Knoten, Kanten, Gruppen und Zeichenflächengrenzen zusammen.
• render: Erkenne das draw.io Desktop-CLI unter macOS, Windows und Linux, beachte DRAWIO_DESKTOP_BINARY oder --binary und exportiere PNG, SVG, PDF oder JPG.
• verify-export: Validiere die Formatsignatur, den strukturellen Abschluss, die Abmessungen und den sicheren SVG-Inhalt eines nativen Exports ohne Desktop-Start.

Überprüfe vor dem ersten Gebrauch mit python3 -c "import xml.etree.ElementTree". Wenn ein macOS-Homebrew-Python einen pyexpat/libexpat-Symbolfehler meldet, verwende /usr/bin/python3 oder repariere diese Python-Installation; führe den ABI-Fehler nicht auf die Diagrammeingabe zurück.

Verwende example.architecture.json, example.blueprint.json, example.erd.json, example.ha.json, example.routing.json, example.terraform.tf oder example.kubernetes.json als kompakten Ausgangspunkt, nicht als feste Vorlage. Verwende corporate.json, wenn ein wiederverwendbares benutzerdefiniertes Themenbeispiel nützlich ist.