birchloveye/draw-flowchart

绘制流程图海报

工作分为两大部分：

1. 你将流程转换为 Mermaid。 这部分需要判断：状态是什么，哪些分支缺失，流程可能卡住或违反规则的地方。
2. scripts/make_poster.py 渲染它。 不涉及模型，因此相同的输入始终生成相同的海报。

<skill> 指的是包含此文件的文件夹。

工作流程

1. 理解流程。 用一句话重述用户的目标。列出模糊之处、缺失的分支（“这一步失败时会发生什么？”）以及有风险的步骤。仅就你无法自行确定的判断点向用户提问。

2. 建模。 为图表创建一个文件夹（每张海报一个文件夹）。

   • 使用 pstack（推荐）。 如果 pstack 的 statechart 技能可用（Claude Code: /pstack:statechart；Cursor: /statechart；或磁盘上的 SKILL.md），则使用它：用用户的规则作为 INVARIANT 编写 TLA+ 规约，运行它，阅读 report.md。按照 references/pstack-statechart.md 中的描述编写视图模块，以便图表能干净地转换。然后转换：

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

     它会在 <folder> 中写入 flow.mmd，并按照顺序打印问题编号，以及每个问题违反的规则。 如果用户要求保持 pstack 关闭，则不要开启；使用下一路径并明确说明。
   • 不使用 pstack。 按照 references/mermaid-rules.md 手动编写 <folder>/flow.mmd。将你发现的每个问题（违反规则、死路、缺失分支）标记为 breaks 类。
   • make_poster.py <folder> --init [--lang zh] 会写入一个起始的 flow.mmd 和 poster.json 以供编辑。

3. 编写 <folder>/poster.json（参考 references/poster-json.md）：标题、副标题、图例使用用户的语言，以及一张卡片，每行对应一个 breaks 节点，顺序与编号一致。

4. 渲染。

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

   它会先检查，有错误时不绘制任何内容。修复每一个错误；阅读每一个警告。输出：poster.html（自包含，离线可用）、poster.png（2倍分辨率）和 poster.svg。

5. 查看 poster.png。 如果你无法查看图片，或者为了节省成本，可将其交给一个更便宜的模型或子代理。检查：

   • 每个红色圈出的节点都有对应的卡片，且编号匹配；
   • 没有线条穿过文字或看起来连错了盒子；
   • 标签都使用用户的语言，并且足够短以方便阅读；
   • 没有重要内容被挤在一起。修复方法：缩短标签、在需要换行的地方加空格、将大图表拆分为两张海报，或通过 poster.json 中的 style 覆盖间距。然后重新渲染。

6. 向用户报告： 首先是 PNG 路径，然后每行一个问题的描述（违反的规则以及流程如何到达该点），最后说明模型遗漏了什么。提示 poster.html 包含导出 PNG/SVG 的按钮。

要求

• Python 3.8+（标准库；若安装了 Pillow，可用于缩小照片）。
• Chrome、Edge 或 Chromium 用于 PNG/SVG 导出。如果未找到，仍会生成 poster.html；设置 CHROME 环境变量为浏览器二进制路径以启用导出。
• 可选：pstack (https://github.com/cursor/plugins/tree/main/pstack) 用于 TLA+ 检查，需要 Java 11+ 及其工具（参见 references/pstack-statechart.md）。
• 字体为系统字体（macOS：American Typewriter、Baskerville、Songti、Kaiti；Windows 和 Linux 回退到 Courier New / Georgia / SimSun / Noto Serif CJK）。在 Linux 系统上，如需中文支持，请安装类似 Noto Serif CJK 的中文字体。

限制

• 仅支持从上到下的布局。
• 不支持复合状态、并行区域、注释或子图。对于状态图输出，请使用平面视图（state() 返回字符串）。
• 最佳适用节点数为 15–25；超过 30 个时检查会发出警告。较大的流程应拆分为多张海报。
• 自动布局有时会将一条线画得离无关的盒子很近。这就是第 5 步存在的意义。

示例

仓库中的 examples/paper-submission/：一个期刊投稿的 TLA+ 模型（statechart/）、转换后的 flow.mmd、poster.json 和渲染后的海报。examples/paper-submission-zh/ 是同一个模型的中文视图。