birchloveye/flowchart-zeichnen

Zeichne ein Flussdiagramm-Poster

Die Arbeit hat zwei Hälften:

1. Du wandelst den Prozess in Mermaid um. Dies ist der Teil, der Urteilsvermögen erfordert: Welche Zustände gibt es, welche Verzweigungen fehlen, wo kann der Prozess stecken bleiben oder eine Regel verletzen.
2. scripts/make_poster.py rendert es. Es ist kein Modell beteiligt, daher liefert dieselbe Eingabe immer dasselbe Poster.

<skill> ist der Ordner, der diese Datei enthält.

Arbeitsablauf

1. Den Prozess verstehen. Formuliere das Ziel des Benutzers in einem Satz. Liste Unklarheiten, fehlende Verzweigungen („Was passiert, wenn dieser Schritt fehlschlägt?“) und riskante Schritte auf. Frage den Benutzer nur nach Abzweigungen, die du nicht selbst entscheiden kannst.

2. Modellieren. Erstelle einen Ordner für das Diagramm (ein Ordner pro Poster).

   • Mit pstack (bevorzugt). Wenn das statechart-Skill von pstack verfügbar ist (Claude Code: /pstack:statechart; Cursor: /statechart; oder dessen SKILL.md auf der Festplatte), verwende es: Schreibe eine TLA+-Spezifikation mit den Benutzerregeln als INVARIANTen, führe sie aus, lies report.md. Schreibe das View-Modul wie in references/pstack-statechart.md beschrieben, damit das Diagramm sauber konvertiert wird. Dann konvertiere:

     python3 <skill>/scripts/make_poster.py <ordner> --from-statechart <statechart-out>/chart.mmd
     

     Es schreibt <ordner>/flow.mmd und gibt die Problemnummern in der Reihenfolge aus, zusammen mit der Regel, die jedes Problem verletzt. Wenn der Benutzer darum gebeten hat, pstack ausgeschaltet zu lassen, schalte es nicht ein; verwende den nächsten Pfad und teile dies mit.
   • Ohne pstack. Schreibe <ordner>/flow.mmd von Hand gemäß references/mermaid-rules.md. Markiere jedes gefundene Problem (eine verletzte Regel, eine Sackgasse, eine fehlende Verzweigung) mit der Klasse breaks.
   • make_poster.py <ordner> --init [--lang zh] schreibt eine Start-flow.mmd und poster.json zum Bearbeiten.

3. Schreibe <ordner>/poster.json (references/poster-json.md): Titel, Untertitel, Legende in der Sprache des Benutzers sowie eine Karte mit einer Zeile pro breaks-Knoten, in derselben Reihenfolge wie die Nummern.

4. Rendern.

   python3 <skill>/scripts/make_poster.py <ordner>
   

   Es prüft zuerst und zeichnet nichts, solange Fehler vorhanden sind. Behebe jeden Fehler; lies jede Warnung. Ausgabe: poster.html (eigenständig, offline nutzbar), poster.png (2x) und poster.svg.

5. Betrachte poster.png. Wenn du Bilder nicht anzeigen kannst oder um Kosten zu sparen, übergib dies an ein günstigeres Modell oder einen Unteragenten. Prüfe:

   • Jeder rot eingekreiste Knoten hat eine Kartenzeile und die Nummern stimmen überein;
   • Keine Linie läuft durch Text oder scheint am falschen Kasten zu haften;
   • Beschriftungen sind in der Sprache des Benutzers und kurz genug zum Lesen;
   • Nichts Wichtiges ist gequetscht. Korrekturen: Beschriftungen kürzen, ein Leerzeichen setzen, wo eine Zeile umbrechen soll, ein großes Diagramm auf zwei Poster aufteilen oder den Abstand in poster.json unter style überschreiben. Dann erneut rendern.

6. Berichte dem Benutzer: zuerst den PNG-Pfad, dann eine Zeile pro Problem (die Regel und wie der Prozess dorthin gelangt), dann was das Modell auslässt. Erwähne, dass poster.html Export-PNG/SVG-Schaltflächen enthält.

Voraussetzungen

• Python 3.8+ (Standardbibliothek; Pillow wird verwendet, um Fotos zu verkleinern, falls installiert).
• Chrome, Edge oder Chromium für PNG/SVG-Export. Wenn keines gefunden wird, wird poster.html dennoch geschrieben; setze CHROME auf die Browser-Binärdatei, um den Export zu aktivieren.
• Optional: pstack (https://github.com/cursor/plugins/tree/main/pstack) für die TLA+-Prüfung, die Java 11+ und die TLA+-Werkzeuge benötigt (siehe references/pstack-statechart.md).
• Schriftarten sind Systemschriftarten (macOS: American Typewriter, Baskerville, Songti, Kaiti; Windows und Linux fallen auf Courier New / Georgia / SimSun / Noto Serif CJK zurück). Installiere unter Linux eine CJK-Schriftart wie Noto Serif CJK für Chinesisch.

Grenzen

• Nur Layout von oben nach unten.
• Keine zusammengesetzten Zustände, parallelen Regionen, Notizen oder Untergraphen. Verwende für Zustandsdiagramm-Ausgaben eine flache Ansicht (state() gibt einen String zurück).
• Am besten bei 15–25 Kästen; über 30 warnt die Prüfung. Teile größere Prozesse auf mehrere Poster auf.
• Das automatische Layout führt gelegentlich eine Linie dicht an einem nicht verwandten Kasten vorbei. Deshalb gibt es Schritt 5.

Beispiel

examples/paper-submission/ im Repository: ein TLA+-Modell einer Zeitschrifteneinreichung (statechart/), das konvertierte flow.mmd, poster.json und das gerenderte Poster. examples/paper-submission-zh/ ist dasselbe Modell mit einer chinesischen Ansicht.