项目介绍

statechart-art 把珍珠奶茶店的小型 TLA+ 模型画成手绘风格的状态图。四张图都是适合手机阅读的正方形，各自演示一个建模概念：订单从排队到交付的分支与循环、以父状态组织的营业日、咖啡师与茶桶两个并发区域，以及 TLC 发现的规则违背及到达违背状态的路径。

流程本身是重点：TLA+ 规格与配置定义店里能发生什么、必须满足哪些规则；TLC 检查所有可达状态；/statechart 技能按 view.mjs 提供的措辞生成 Mermaid 图；pele 负责排版；每张图的 Node 脚本在模拟纸张上用钢笔和彩铅的笔触把布局画出来。绘制带随机种子，同一份代码画出同一张图。它适合想通过具体例子学习状态图记法或 TLA+ 的读者，也适合对程序化插画感兴趣的人。

成品图可以直接在项目站点查看。

快速使用

绘图工具需要 Node（项目使用 Node 24 制作）。在仓库根目录执行：

cd tools && npm install

然后在仓库根目录绘制一张图：

node business/art/order.js

四张图的脚本分别是 order.js、day.js、counter.js 和 bug.js。每个脚本会写出 business/out/<plate>.png（2160 px）、2048 px 的 X/Twitter 版本 <plate>-x.jpg、1080 px 预览图，以及记录版式框线的 <plate>-pele.json，站点用它叠加显示。加 --fast 会以一半尺寸快速出图。四张图画完后，运行 node business/art/cards.js 生成图标和分享卡片。

把站点构建到 docs/ 并在 http://localhost:5297 预览：

node site/build.js
node site/serve.mjs

构建时可以设置 SITE 和 REPO 改变分享链接地址与代码链接，例如 SITE=https://example.com/boba/ REPO=https://github.com/you/boba node site/build.js。

要重新检查模型并生成图表，把 /statechart 技能指向一个新的或空的输出目录，例如 ~/.claude/skills/statechart/scripts/statechart business/order/Order.tla --view business/order/view.mjs --out business/order/chart-new。该技能不会写入已有内容的目录，因此需要与仓库中的 chart/ 目录对比查看。bug 模型按其设计会以状态码 1 退出，因为它的规则确实被违背。

使用约束

重新生成图表依赖安装在 ~/.claude/skills/statechart/ 的自定义 /statechart 技能，而它不在仓库内；在干净检出上无法直接重新生成图表。运行需要 Node，项目使用 Node 24 制作，没有说明其他运行时要求。bug 图会刻意返回非零状态码，放进脚本流水线时需要按此处理。图表有改动时，需要把输出复制到 layout.mmd，并保留其中的 config 和 direction 行。

仓库结构：business/<chart>/ 存放各模型、视图、生成的图表和布局；business/art/ 存放各图脚本和店中元素；tools/lib/ 与 tools/kit/ 包含绘图基元和干性媒材模拟；tools/fonts/ 存放 Kevin Serif 与 Kevin Sans；site/ 构建站点；docs/ 是由 GitHub Pages 提供的构建产物。代码、模型、图片和字体均以 MIT 许可发布。

HotRepo 点评

该项目于 2026-11-02 进入 HotRepo 新项目榜，记录到约 24 小时窗口（自 2026-11-01 15:45 UTC 起）内新增 51 Star，累计达到 153 Star、12 Fork。窗口内逐小时采样从约 100 稳步升到 153，但只有这一条快照且观察期短，不能据此判断持续增长趋势。它的看点在于把经过检查的形式化模型和一套少见的插画流水线结合起来，代码本身也足够直接，可以运行和细看。