Diagramm-Generator

Was macht Diagramm-Generator?

AKTION ERFORDERLICH (nach dem Lesen sofort ausführen)

1. JETZT: Prüfe, ob die aktuelle Aufgabe in den Anwendungsbereich dieser Skill fällt
2. JETZT: Lese ../tool-index.md, um die Verfügbarkeit und den tatsächlichen Pfad der Tools zu überprüfen
3. NÄCHSTES: Fehlende Tools per Bootstrap installieren, nicht den Pfad raten
4. AKTION: Gehe zum ersten Schritt des Arbeitsablaufs und führe ihn aus. Bleibe nicht im Bestätigungsstatus hängen

Zweck

Erstelle klare, editierbare Diagramme aus unstrukturierten oder strukturierten Eingaben. Bevorzuge zuerst textbasierte Diagrammquellen, damit das Ergebnis überprüft, versioniert und verfeinert werden kann. Rendere nur dann in Dateien, wenn der Benutzer explizit ein Bild/PDF anfordert oder ein herunterladbares Artefakt wesentlich hilfreich wäre.

Standard-Arbeitsablauf

1. Identifiziere die Absicht des Benutzers, die Zielgruppe und das Quellmaterial.
2. Wähle die Diagrammfamilie und -sprache anhand der Entscheidungstabelle unten.
3. Normalisiere Entitäten, Beziehungen, Beschriftungen, Zustände, Verzweigungen und Zeit-/Reihenfolgeinformationen, bevor der Diagrammcode geschrieben wird.
4. Generiere präzisen, lesbaren Diagrammquelltext.
5. Validiere die Syntax mental und führe bei Dateierstellung scripts/render_diagram.py aus.
6. Gib den Diagrammquelltext plus einen kurzen Hinweis auf Annahmen zurück. Wenn Dateien erzeugt wurden, füge Links zu den Ausgabedateien hinzu.

Verlange nicht zu oft nach Klärung. Wenn die Anfrage unterbestimmt ist, triff vernünftige Annahmen und kennzeichne sie kurz.

Entscheidungstabelle für Diagrammsprachen

Verwende Mermaid, es sei denn, eine andere Sprache ist eindeutig besser geeignet.

Benutzer möchte	Bevorzugt	Warum
Prozessablauf, Entscheidungsbaum, einfache Swimlane	Mermaid flowchart	Lesbar und einfach in Markdown einzufügen
Abfolge von System-/Benutzerinteraktionen	Mermaid sequenceDiagram oder PlantUML sequence	Mermaid für Dokumentation; PlantUML für UML-Formalität
Lebenszyklus, Zustandsmaschine, Übergänge	Mermaid stateDiagram-v2 oder PlantUML state	Kompakte Übergangssyntax
Datenbankschema, Entitäten, Beziehungen	Mermaid erDiagram	Portable ER-Notation
Klassen-/Schnittstellen-/Objektmodell	Mermaid classDiagram oder PlantUML class	Mermaid für Dokumentation; PlantUML für detailliertes UML
Projektzeitplan	Mermaid gantt	Prägnante Zeitleistensyntax
Hierarchie, Ideen, Notizen	Mermaid mindmap	Gute Standardoption für Ideenmaps
Kunden-/Produktreise	Mermaid journey	Eingebaute Reisenotation
Git-Verlauf	Mermaid gitGraph	Eingebaute Git-Notation
Abhängigkeitsgraph, Paketgraph, großes Netzwerk	Graphviz DOT	Bessere Layout-Engines für dichte Graphen
Architektur mit Schichten, Clustern, Grenzen	Mermaid flowchart mit Subgraphen, Graphviz-Cluster oder PlantUML C4-Stil	Wähle basierend auf der gewünschten Detailtreue
Gewichteter Fluss/Sankey-ähnliche Beziehung	Mermaid sankey-beta (falls unterstützt), sonst SVG oder Graphviz	Mermaid-Unterstützung kann je nach Renderer variieren
Benutzerdefiniertes visuelles, bei dem Quellsprachen schlecht passen	SVG	Präzise Kontrolle über Layout und Styling

Ausgaberichtlinie

• Gib immer den editierbaren Quelltext an, es sei denn, der Benutzer fordert explizit nur ein Bild an.
• Standardmäßig ein einzelnes bestes Diagramm. Biete Alternativen nur dann an, wenn sie wirklich nützlich sind.
• Bevorzuge stabile, einfache Syntax gegenüber ausgefallenen Funktionen, die in älteren Mermaid-/PlantUML-Versionen möglicherweise nicht rendern.
• Verwende kurze Beschriftungen. Teile lange Texte bei Bedarf in Notizen außerhalb des Diagramms auf.
• Vermeide mehrdeutige Knoten-IDs. Verwende ASCII-IDs und menschenlesbare Beschriftungen.
• Behalte die Terminologie des Benutzers bei, aber standardisiere die Groß-/Kleinschreibung innerhalb eines Diagramms.
• Füge bei technischen Diagrammen Grenzen wie Client, Service, Datenbank, Warteschlange, externe API und Operator/Benutzer hinzu, wenn sie impliziert sind.
• Unterscheide bei Geschäftsprozessdiagrammen den Happy Path, Entscheidungspunkte, Fehler, Wiederholungen und manuelle Schritte, wenn vorhanden.
• Füge bei Diagrammen, die aus unsicherem Text erstellt wurden, einen Abschnitt Annahmen nach dem Code ein.

Regeln zur Mermaid-Generierung

Konsultiere references/diagram-patterns.md für kompakte Vorlagen.

Allgemeine Mermaid-Regeln:

• Beginne mit der korrekten Diagrammdirektive, z. B. flowchart TD, sequenceDiagram, erDiagram, gantt, mindmap oder journey.
• Verwende für Flussdiagramme flowchart TD, es sei denn, der Benutzer wünscht von links nach rechts; verwende flowchart LR für Architektur und Pipelines.
• Verwende Subgraphen für Swimlanes oder Architekturschichten. Benenne Subgraphen mit lesbaren Beschriftungen.
• Halte Knoten-IDs stabil und ASCII-only, z. B. ingest_service[Eingabedienst].
• Setze Beschriftungen, die Satzzeichen enthalten, welche den Parser verwirren könnten, in Anführungszeichen.
• Verwende Entscheidungsrauten für Verzweigungen: decision{Bedingung?}.
• Verwende konsistente Kantenbeschriftungen: -- ja -->, -- nein -->, -. asynchron .-> oder == kritisch ==> nur wenn sinnvoll.
• Deklariere in Sequenzdiagrammen die Teilnehmer vor den Nachrichten. Verwende actor für Menschen und participant für Systeme.
• Verwende alt/else/end, opt/end, loop/end und par/and/end-Blöcke für bedingte, optionale, wiederholte und parallele Abläufe.

Regeln zur Graphviz-DOT-Generierung

Verwende Graphviz für große, dichte oder layoutempfindliche Beziehungsdiagramme.

• Bevorzuge digraph G für gerichtete Beziehungen und graph G für ungerichtete Netzwerke.
• Setze layoutfreundliche Graphattribute am Anfang: rankdir=LR, nodesep, ranksep und splines=true, wenn hilfreich.
• Verwende subgraph cluster_name für Grenzen und Subsysteme.
• Verwende einfache Beschriftungen und zurückhaltendes Styling.
• Verwende Kantenbeschriftungen nur dann, wenn sie Bedeutung hinzufügen.
• Bei vielen Knoten gruppiere sie nach Domäne mit Clustern und vermeide kreuzungsreiche All-to-All-Kanten.

Regeln zur PlantUML-Generierung

Verwende PlantUML, wenn der Benutzer UML oder formale UML-Notation wünscht.

• Ummantle Diagramme mit @startuml und @enduml.
• Verwende actor, participant, database, queue, collections oder component-Stereotypen, wenn sinnvoll.
• Verwende package, rectangle oder node für Architekturgrenzen.
• Füge bei Klassendiagrammen nur wichtige Felder/Methoden hinzu, es sei denn, der Benutzer wünscht erschöpfende Details.
• Verwende bei Aktivitätsdiagrammen klare Start-/Endmarkierungen und explizite Verzweigungsbeschriftungen.

Regeln zur SVG-Generierung

Verwende SVG nur, wenn textbasierte Diagrammsprachen die gewünschte visuelle Darstellung nicht zuverlässig ausdrücken können.

• Halte SVG einfach, zugänglich und editierbar.
• Füge <title> und aussagekräftige Textbeschriftungen hinzu.
• Bevorzuge Rechtecke, Linien, Pfeile und Gruppierungen gegenüber komplexen Pfaden.
• Bette keine externen Schriftarten oder entfernten Bilder ein.

Dateien rendern

Wenn der Benutzer PNG/SVG/PDF anfordert, erstelle eine Quelldatei und führe aus:

python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.mmd --format svg --out output.svg
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.dot --format png --out output.png
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.puml --format svg --out output.svg

<SKILL_ROOT> ist der tatsächliche Pfad des skills/-Verzeichnisses dieses Pakets. Der AI sollte ihn automatisch erkennen.

Der Renderer ist bewusst abhängigkeitstolerant. Er probiert übliche lokale Tools aus und meldet hilfreiche Installationshinweise, falls ein Renderer nicht verfügbar ist. Behaupfte nicht, dass ein Bild gerendert wurde, es sei denn, das Skript wurde erfolgreich abgeschlossen und die Ausgabedatei existiert.

Validierungs-Checkliste

Vor der Finalisierung:

• Der Diagrammtyp passt zur Aufgabe des Benutzers.
• Der Quelltext ist syntaktisch plausibel für die gewählte Sprache.
• Beschriftungen sind kurz genug, um zu passen.
• Kanten und Nachrichtenordnung spiegeln die Eingabe genau wider.
• Annahmen werden genannt, wenn die Eingabe unvollständig war.
• Bei generierten Dateien: Die Ausgabe existiert und öffnet sich oder hat eine Größe ungleich Null.

Allgemeine Antwortvorlage

Verwende diese Struktur für die meisten Diagrammantworten:

Hier ist die editierbare [Sprache]-Version:

```[sprache]
[quelle]

Annahmen:

• [nur bei Bedarf]

Gerenderte Datei: [Link] [nur bei Generierung]

Antworte auf Englisch bei englischsprachigen Anfragen. Antworte auf Chinesisch bei chinesischsprachigen Anfragen, es sei denn, der Benutzer wünscht etwas anderes.

---

## On-Demand-Bootstrap

### Grenzen der Automatisierung

| Tool | Automatisch installierbar | Installationsmethode | Hinweis |
|------|---------------------------|----------------------|---------|
| Mermaid CLI (mmdc) | ✓ | npm install -g @mermaid-js/mermaid-cli | Rendert Mermaid in PNG/SVG |
| Graphviz (dot) | ✗ | Manuelle Installation | https://graphviz.org/download/ |
| PlantUML | ✗ | Benötigt Java + plantuml.jar | https://plantuml.com/download |
| Python (Render-Skript) | ✓ | Bereits im Bootstrap enthalten | `scripts/render_diagram.py` Abhängigkeiten |

### Hinweis

Diese Skill gibt hauptsächlich textbasierten Diagrammquellcode aus (Mermaid/DOT/PlantUML) und benötigt nicht zwangsläufig lokale Rendering-Tools. Der entsprechende Renderer wird nur benötigt, wenn der Benutzer explizit die Erzeugung von PNG/SVG/PDF-Dateien anfordert.

Falls ein Renderer nicht verfügbar ist, gibt `scripts/render_diagram.py` Installationshinweise aus, anstatt einen Fehler zu melden.

---

## Routing-Kontext

**Eingangspunkt (Upstream)**: `skills/SKILL.md` (Hauptsteuerung), `routing.md`
**Auslösebedingung**: Benutzer sagt "Diagramm", "Flussdiagramm", "Architekturdiagramm", "Angriffspfaddiagramm", "Sequenzdiagramm", "Mermaid", "Graphviz", "PlantUML"
**Ausgangspunkt (Downstream)**:
- Erzeugte Diagramme können in Berichte von `docs-generator/` eingebettet werden
- Angriffspfaddiagramme können mit Penetrationstestberichten von `pentest-tools/` kombiniert werden

**Verwandte Module auf gleicher Ebene**: `docs-generator/` (Diagramme in Berichte einbetten)

## Aufgaben-Selbstprüfung (MUSS vor Abschluss bestanden werden)

- [ ] Habe ich jeden Schritt des Arbeitsablaufs ausgeführt (und nicht nur gelesen)?
- [ ] Habe ich basierend auf dem `tool-index` reale Tool-Pfade verwendet?
- [ ] Habe ich reproduzierbare Belege erbracht (Befehle/Skripte/Screenshots/Berichte)?
- [ ] Habe ich die von RULES geforderten Checklisten-Punkte abgeschlossen und zurückgeschrieben?