birchloveye/draw-flowchart

Dessiner une affiche d'organigramme

Le travail se divise en deux parties :

1. Vous transformez le processus en Mermaid. C'est la partie qui demande du jugement : quels sont les états, quelles branches manquent, où le processus peut se bloquer ou enfreindre une règle.
2. scripts/make_poster.py effectue le rendu. Aucun modèle n'est impliqué, donc la même entrée produit toujours la même affiche.

<skill> ci-dessous est le dossier qui contient ce fichier.

Flux de travail

1. Comprendre le processus. Reformulez l'objectif de l'utilisateur en une phrase. Listez les ambiguïtés, les branches manquantes (« que se passe-t-il quand cette étape échoue ? ») et les étapes risquées. Posez des questions à l'utilisateur uniquement sur les embranchements que vous ne pouvez pas résoudre vous-même.

2. Le modéliser. Créez un dossier pour le diagramme (un dossier par affiche).

   • Avec pstack (préféré). Si la compétence statechart de pstack est disponible (Claude Code : /pstack:statechart ; Cursor : /statechart ; ou son SKILL.md sur le disque), utilisez-la : écrivez une spécification TLA+ avec les règles de l'utilisateur comme INVARIANTs, exécutez-la, lisez report.md. Écrivez le module de vue comme décrit dans references/pstack-statechart.md afin que le diagramme se convertisse proprement. Convertissez ensuite :

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

     Cela écrit <folder>/flow.mmd et imprime les numéros des problèmes dans l'ordre, avec la règle que chacun enfreint. Si l'utilisateur a demandé que pstack reste désactivé, ne l'activez pas ; utilisez le chemin suivant et mentionnez-le.
   • Sans pstack. Écrivez <folder>/flow.mmd à la main en suivant references/mermaid-rules.md. Marquez chaque problème que vous avez trouvé (une règle enfreinte, une impasse, une branche manquante) avec la classe breaks.
   • make_poster.py <folder> --init [--lang zh] écrit un flow.mmd et un poster.json de départ à modifier.

3. Écrire <folder>/poster.json (references/poster-json.md) : titre, sous-titre, légende dans la langue de l'utilisateur, et une carte avec une ligne par nœud breaks, dans le même ordre que les numéros.

4. Effectuer le rendu.

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

   Cela vérifie d'abord et ne dessine rien tant qu'il y a des erreurs. Corrigez chaque erreur ; lisez chaque avertissement. Sortie : poster.html (autonome, fonctionne hors ligne), poster.png (2x) et poster.svg.

5. Regarder poster.png. Si vous ne pouvez pas voir les images, ou pour réduire les coûts, confiez cela à un modèle moins cher ou à un sous-agent. Vérifiez :

   • chaque nœud entouré en rouge a une ligne de carte et les numéros correspondent ;
   • aucune ligne ne traverse le texte et ne semble attachée à la mauvaise boîte ;
   • les étiquettes sont dans la langue de l'utilisateur et suffisamment courtes pour être lues ;
   • rien d'important n'est trop serré. Corrections : raccourcissez les étiquettes, mettez un espace là où une ligne devrait être coupée, divisez un grand diagramme en deux affiches, ou modifiez l'espacement dans poster.json style. Effectuez ensuite le rendu à nouveau.

6. Rapporter à l'utilisateur : d'abord le chemin du PNG, puis une ligne par problème (la règle, et comment le processus y aboutit), puis ce que le modèle omet. Mentionnez que poster.html possède des boutons Export PNG/SVG.

Prérequis

• Python 3.8+ (bibliothèque standard ; Pillow est utilisé pour réduire les photos si installé).
• Chrome, Edge ou Chromium pour l'export PNG/SVG. Si aucun n'est trouvé, poster.html est quand même écrit ; définissez CHROME sur le binaire du navigateur pour activer l'export.
• Optionnel : pstack (https://github.com/cursor/plugins/tree/main/pstack) pour la vérification TLA+, qui nécessite Java 11+ et les outils TLA+ (voir references/pstack-statechart.md).
• Les polices sont des polices système (macOS : American Typewriter, Baskerville, Songti, Kaiti ; Windows et Linux utilisent Courier New / Georgia / SimSun / Noto Serif CJK par défaut). Sur Linux, installez une police CJK comme Noto Serif CJK pour le chinois.

Limites

• Disposition de haut en bas uniquement.
• Pas d'états composites, de régions parallèles, de notes ou de sous-graphes. Pour la sortie statechart, utilisez une vue plate (state() renvoie une chaîne de caractères).
• Optimal entre 15 et 25 boîtes ; au-dessus de 30, la vérification émet un avertissement. Divisez les processus plus volumineux en plusieurs affiches.
• La disposition automatique fait parfois passer une ligne près d'une boîte non concernée. C'est pourquoi l'étape 5 existe.

Exemple

examples/paper-submission/ dans le dépôt : un modèle TLA+ d'une soumission de journal (statechart/), le flow.mmd converti, poster.json et l'affiche rendue. examples/paper-submission-zh/ est le même modèle avec une vue en chinois.