用途
statechart 用于把系统的状态变化画成 Mermaid 状态图,面向能够判断行为是否正确的读者(如产品经理读产品流程、工程师读协议或服务、评审者读设计)。图表以读者能观察或关心的内容标注状态与步骤,例如应用中的“Paying”或锁服务中的“Lease held, write pending”,并以触发事件标注步骤,例如“tap Pay”“the request reads the count”或“the lease expires”。
主要能力
- Spec 到图表(from-spec):当已有 TLA+ 模型,或代码/设计足够具体可建模时,从规范生成图表。可添加标签和规则所需的变量,保留既有不变量;若代码已有 TLA+ 规范,可从其副本出发。
- 图表到 Spec(from-chart):当没有模型、且行为所有者应先达成一致时,从读者认可的状态图反向生成 TLA+ 规范。每个规则用一条
%% never行表达;若规则被打破,说明已达成一致的图表存在设计缺陷。 - 规则与 bug 呈现:将读者认可的每条规则写为一个不变量,并以读者原句作为注释;每条被打破的规则作为一个 bug,以带编号的路径列出。对于系统必须能够达到的目标,可写一条“目标永不发生”的规则并用
--expect-broken传入,其被打破的路径即为到达目标的路径。 - 图表控制:支持
--cover在概览过大时仅保留到各稳定状态的最短路径及所有 bug 路径;支持cause为不同原因导致的同一终态命名;支持group按读者关心的分组为状态着色,图例显示分组,PNG 中违反规则的状态以红色替代分组颜色。 - 修复验证:若有提议的修复,可对其建模并通过
--fixed传入。 - 证据与交接:要求对每个 bug 的故事在真实代码上重放(测试或实时复现),只驱动用户、客户端或系统其他部分可达的入口,只断言其可观察的内容。对于尚无代码的设计,TLC 迹是证据。交接时提供图表的 PNG 与 Mermaid 源、每个 bug 违反的规则、步骤、是否复现及修复是否有效,并附上
stories.md和重新生成全部内容的命令,同时说明模型遗漏了什么。
使用方式
在仓库之外的临时文件夹中工作。命令会把文件写在输入文件旁。运行 node <skill dir>/scripts/statechart.mjs --help 查看命令及图表阅读方式。首次运行会通过 mise 安装 TLC 和 Java,需下载约 305 MB 并需联网;帮助的 TLC 部分说明了如何使用已有的 TLC 和 Java。渲染时使用 --png 并逐一查看 PNG,检查每条编号路径是否按顺序可读;若标签读起来像代码,修正 state 或 step 后重新运行。每次引用的计数应取自 summary.json。
适用场景
- 产品流程、协议或服务的状态流转可视化与评审。
- 由 TLA+ 模型生成面向非形式化读者的状态图。
- 从团队认可的状态图反向生成 TLA+ 规范,并在加入真实代码的守卫和变量后再次运行,逐项询问读者是代码有误还是图表需修正。
- 将规则违反(bug)以编号路径和证据形式交接给决策者。
限制
- 首次运行依赖网络下载 TLC 和 Java;离线环境需按帮助说明使用已有安装。
- 图表不绘制“离开标签但标签不变”的步骤,需在必要时拆分状态以显露此类步骤。
- 不得为使图表通过而削弱规则;若 bug 无法复现,应先假定模型有误并修复模型而非规则。
- 测试若断言自身设置的标志或搜索源文本,则不构成证明;复制无法导入的代码时需给出提交与行范围并列出遗漏内容。
- 其他具体功能、平台与收费信息暂未提供。