Whiteboard

Was macht Whiteboard?

Verwandeln Sie eine Erklärung in ein Diagramm, das der Benutzer sehen, behalten und überall einfügen kann. Sie schreiben die Diagrammquelle; scripts/render.mjs rendert sie mit der lokal installierten CLI des Benutzers und teilt Ihnen genau mit, was falsch ist, wenn sie nicht analysiert werden kann.

Arbeitsablauf

1. Wählen Sie den Diagrammtyp und die Sprache. Standardmäßig Mermaid. Verwenden Sie D2 für große Architekturdiagramme mit verschachtelten Containern, PlantUML nur, wenn der Benutzer danach fragt oder das Projekt es bereits verwendet. Siehe references/syntax.md für die Syntax der einzelnen Typen.

2. Lesen Sie vor dem Zeichnen. Wenn das Diagramm Code beschreibt, lesen Sie zuerst den Code. Zeichnen Sie, was existiert, mit echten Namen, nicht einem generischen Bild. Bei Anfragen für das gesamte Projekt (Architektur, Kontrollfluss, Datenmodell) folgen Sie references/modes.md.

3. Schreiben Sie die Quelle und rendern Sie sie. Übergeben Sie sie über die Standardeingabe mit einem kurzen Titel (maximal 80 Zeichen). Der Titel benennt die Dateien, verwenden Sie ihn daher erneut, wenn Sie dasselbe Diagramm neu zeichnen:

   node <skill-verzeichnis>/scripts/render.mjs --title "Checkout-Sequenz" <<'EOF'
   sequenceDiagram
     Browser->>API: POST /checkout
     API->>Payments: charge(card)
     Payments-->>API: ok
     API-->>Browser: 201 Created
   EOF
   

   <skill-verzeichnis> ist der Ordner, in dem sich diese Datei befindet. Fügen Sie --language d2 oder --language plantuml für diese Sprachen hinzu. Unter Windows oder wenn Here-Dokumente umständlich sind, schreiben Sie die Quelle in eine temporäre Datei und übergeben Sie stattdessen --file <pfad>.

4. Reparieren und bei Fehlschlag erneut ausführen. Exit-Code 1 bedeutet, dass der Renderer die Quelle abgelehnt hat; die Meldung nennt die Zeile. Korrigieren Sie diese Zeile und führen Sie denselben Befehl erneut aus. Geben Sie dem Benutzer kein Diagramm, das nicht gerendert wurde. Häufige Korrekturen sind am Ende von references/syntax.md aufgeführt.

5. Kurz Bericht erstatten. Sagen Sie, was das Diagramm zeigt, und geben Sie die Dateipfade an, die das Skript ausgegeben hat (z. B. diagrams/checkout-sequence.svg). Wenn der Benutzer es in ein README, Issue oder Wiki einfügen möchte, geben Sie die Quelle in einem eingerahmten ```mermaid-Block an: GitHub, GitLab und Notion rendern es.

Skript-Referenz

Option	Verwendung
--title <text>	Erforderlich. Benennt die Dateien: diagrams/<slug>.svg und die Quelle daneben.
--language <name>	mermaid (Standard), d2 oder plantuml.
--file <pfad>	Quelle aus einer Datei statt von der Standardeingabe lesen.
--out <verz>	Ausgabeverzeichnis; standardmäßig diagrams im aktuellen Ordner.
--png	Auch ein PNG schreiben (für Folien, Chat-Apps, Terminals, die Bilder anzeigen).
--theme <name>	default, neutral, dark oder forest.
--config <datei>	Eine Mermaid-JSON-Konfiguration für Teamfarben und Schriften.
--check	Nur validieren; schreibt nichts.
--open	SVG im Standard-Viewer des Benutzers öffnen. Verwenden Sie es, wenn der Benutzer das Diagramm jetzt sehen möchte.
--share	Quelle in einem geheimen GitHub Gist hochladen und den Link ausgeben. Führen Sie es nur aus, nachdem der Benutzer um Teilen gebeten und dem Upload zugestimmt hat.
--json	Maschinenlesbares Ergebnis.
--doctor	Überprüft Node, jeden Renderer und die GitHub CLI und sagt, was installiert werden muss.

Exit-Codes: 0 gerendert, 1 Quelle abgelehnt (korrigieren und erneut ausführen), 2 falsche Argumente, 3 Renderer nicht installiert.

Diagramme lesen niemals lokale Dateien, Umgebungsvariablen oder URLs in das Bild ein:

• Mermaid rendert in einer sandboxed Browserseite, die nichts aus dem Netzwerk oder von der Festplatte laden kann. Jede Mermaid-Syntax funktioniert, aber entfernte oder lokale Bilder und CSS-Ressourcen bleiben leer; betten Sie ein Bild als data:-URL ein, wenn es erscheinen muss.
• PlantUML: Andere Direktiven als die einfachen (!define, !if, !procedure, !$var, !theme <name>, !include <stdlib> …), %getenv und ähnliche Builtins sowie <img:…> werden abgelehnt. Betten Sie den Inhalt stattdessen ein.
• D2: @-Importe werden abgelehnt. Diagramme mit Icons, Block-Strings, HTML oder URLs werden nur als SVG gerendert, wo sie Links bleiben.

Nur wenn der Benutzer explizit Includes oder externe Bilder wünscht, führen Sie erneut mit WHITEBOARD_ALLOW_INCLUDES=1 aus.

Das erneute Zeichnen mit demselben Titel behält die früheren Dateien in diagrams/.versions/<slug>/<n>/, sodass das Iterieren über ein Diagramm nie die vorherige Version verliert.

Wenn ein Renderer fehlt

Exit-Code 3 gibt den Installationsbefehl aus. Teilen Sie dem Benutzer mit, was er ausführen soll, und installieren Sie keine globalen Pakete selbst, es sei denn, er fragt danach:

• Mermaid: npm i -g @mermaid-js/mermaid-cli
• D2: brew install d2 oder siehe https://d2lang.com/tour/install
• PlantUML: brew install plantuml oder apt install plantuml (benötigt Java)

Wenn ein Renderer installiert ist, aber nicht gefunden wird (häufig bei Desktop-Apps, die ohne den PATH der Login-Shell starten), setzen Sie WHITEBOARD_MMDC, WHITEBOARD_D2 oder WHITEBOARD_PLANTUML auf den vollständigen Pfad. Das Mermaid-Rendering verwendet den Browser und das Mermaid-Bundle, die mit mermaid-cli geliefert werden; wenn das Skript mmdc findet, aber nicht sein Paket, setzen Sie WHITEBOARD_MERMAID_CLI_DIR auf den Ordner @mermaid-js/mermaid-cli. Wenn nichts installiert werden kann, geben Sie die Mermaid-Quelle in einem eingerahmten Block an, sodass sie trotzdem auf GitHub gerendert wird, und sagen Sie, dass sie nicht von einem Renderer überprüft wurde.

Gute Diagramme

• Eine Idee pro Diagramm. Teilen Sie alles mit über etwa 15 Knoten oder 20 Nachrichten in eine Übersichts- und Detaildiagramme auf.
• Beschriften Sie jede Kante mit dem, was fließt oder passiert (HTTP, publishes OrderPlaced, 1..*).
• Verwenden Sie die Namen aus dem Code: Klassen-, Modul- und Servicenamen, echte Endpunkte, echte Tabellen.
• Wählen Sie den Typ, der zur Frage passt: Wer ruft wen im Laufe der Zeit an → Sequenz; Was die Teile sind → Architektur/Flussdiagramm; Wie die Daten aussehen → ER oder Klasse; Wie sich etwas im Laufe der Zeit ändert → Zustand.
• Halten Sie Text in Knoten kurz; fügen Sie Details in Kantenbeschriftungen oder Notizen ein.