statechart
更新于 2026-10-28
Statechart
Section titled “Statechart”检查系统状态变化的 TLA+ 模型,并把它绘制成 Mermaid 状态图。读者用自己的话判断行为是否正确。
在仓库外的临时目录中编写 TLA+ 规格及配置,然后运行:
<skill dir>/scripts/statechart SPEC.tla [--config FILE] [--view FILE] [--out DIR]scripts/statechart.ts 是 TypeScript,请用能运行 TypeScript 的运行时执行。首次运行会通过 mise 安装 TLC 和 Java,需要网络。
- 把读者认可的每条规则写成 INVARIANT。规则可以描述界面、结果、存储值或消息。模型没有规则所需的变量时,添加变量。不要弱化规则。
- 把
Next写成各个动作的析取,例如YouPressPlay \/ YouPressStop。否则 TLC 会把每一步都叫作Next。 - 没有后续动作的状态会违反
NoDeadlock,即使它是正确的结束状态也一样。如果 INVARIANT 或 PROPERTY 已经使用该名称,规则就是CHECK_DEADLOCK。在Next中添加一个只在结束状态成立且不改变状态的动作,例如Done == phase \in {"paid", "failed"} /\ UNCHANGED vars,并在step()中为它添加标签。
需要判断的内容由你完成:每个状态和箭头的文字、阶段与颜色、标题,以及给读者的报告。把这些内容放在 view 模块中,并通过 --view 传入。
view 导出 state(vars) 来显示读者看到的状态。返回字符串会生成平面图;返回数组会生成父子状态;返回对象会为每个键生成一个并行区域。例如:
- 字符串:
export const state = (v) => (v.paid ? "Paid" : "Paying"); - 数组:
export const state = (v) => v.main.split("."); - 对象:
export const state = (v) => ({ Playback: v.playback, Volume: v.volume });
状态标签写读者能看到或关心的内容,例如「Paying」或「Lease held, write pending」。不要在标签中写变量名。vars 中的 TLA+ 序列是以 1 为键的对象,因此 v.pc[1] 对应 pc[1]。集合是数组。
view 还可以导出 step(action, from, to)。它会收到 TLC 动作名及动作前后的值,并返回箭头标签。标签写用户看到的事件,例如「you press play」或「the connect fails」。不要写代码名或 TLA+ 动作名。图中结果相同的动作使用同一标签,共用一条箭头。
步骤只在某些条件下发生时,在标签末尾用读者能理解的方括号写明条件,例如 you press play [while the file loads]。区域图会在箭头上自动写出其他区域的条件,例如 [when Offline]。自定义方括号会替换自动条件,因此可能让多条箭头看起来相同。区域图中不要写其他区域的条件。当未显示的值决定步骤去向时,要在标签中说明结果,例如「roster 读取失败」。
view 还可以导出:
group(vars)返回阶段名,图中状态会使用该组颜色。一个图表状态对应的模型状态属于不同组时,该状态不着色。colors为每个组名指定颜色类。title是图表顶部显示的字符串。
命令对每个模型状态最多调用一次 state() 和 group(),对每个步骤最多调用一次 step()。图表和报告会共用这些结果,因此每个函数只能依赖自己的参数。
图表不会显示标签不变的步骤。如果读者需要看到该步骤,就拆分标签。
图表最好控制在约 20 条箭头以内。先让 state() 返回更粗略的标签,把行为相同的值合并,省略读者不需要的细节。保留每条 bug 路径上的状态和每个标记。合并会把 breaks 状态变成 mayBreak 时,就隐藏了规则在哪里被违反。不要合并违反不同规则的状态。如果图仍太复杂,可以让 step() 对读者不需要的步骤返回 null,例如所有状态都会发生的重置,或重复表达其他箭头的步骤。隐藏步骤时要遵守以下规则:
- 每个图表状态都必须能从起始状态沿箭头到达。
- 模型中有后续步骤的每个图表状态,都至少保留一条出箭头。
- 同一箭头的步骤要么全部隐藏,要么全部保留。只隐藏其中一部分会缩窄它的条件。
- 在交接中说明图表隐藏了哪些步骤。
- 违反规则的状态在图中使用
breaks类。只有部分模型状态违反规则时使用mayBreak。Legend 会为每个标记列出规则。多个规则同时违反时会在一个标记中列出,因此交接中要说明哪个状态违反哪条规则。区域图中,每种包含该区域状态的组合都可能违反规则时,该状态会获得标记。如果某种组合可能违反规则,但组合中的状态都没有标记,则组合中的每个状态都会获得标记。 - TLC 会继续探索违反规则的状态,因此图中也会显示 bug 之后的状态。
- TLC 会继续探索 bug,因此状态数没有上限的模型可能永不结束。请缩小常量,或添加 CONSTRAINT。
- 使用 VIEW 或 SYMMETRY 时,TLC 会把视为相同的状态计为一个状态,图中也只画一个。箭头可能指向该状态,而非步骤实际到达的状态;报告会说明这一点。
- TLC 会检查 CONSTRAINT 或 ACTION_CONSTRAINT 之外状态的规则,但不会探索这些状态,也不会检查其死锁。如果规则的最短路径结束在这种状态,图会画出该状态,报告会给出路径,但不会画出边界之后的其他状态。此类状态中的死锁不会显示。TLC 也会检查 ACTION_CONSTRAINT 排除步骤之后的规则,即使它通过其他路径到达下一状态也是如此。规则的最短路径以这种步骤结束时,图会画出该步骤。
- 命令用原样配置和一个 worker 运行 TLC 检查规则。规则被违反时,命令会移除该规则并重新运行,直到没有规则被违反。首次出现违反后,每次运行最多检查 100,000 个不同状态,避免大型模型无限运行。运行达到上限或因错误停止时,报告会在「Rules not checked」下列出未检查的规则,图中不会标记它们。未检查的规则可能成立,也可能被违反。要检查它们,请从配置中移除已违反规则,或缩小模型。此上限会加入一个改变 TLC 变量顺序的模块,因此属性的反例可能不同于不设上限时的反例。
tlc.out是 TLC 在原配置上的输出。如果图没有显示某条违反规则的 bug 路径,tlc-RULE.out是找到该问题的运行输出。普通 TLC 可能会重复打印第一条警告;本命令读取的tlc.out只显示一次,因为 TLC 会从读取的输出中省略第二份。只有 Java 使用-XX:+UseParallelGC时才会这样,因为否则 TLC 的第一条警告会建议设置该参数,且只打印一次。
用 mermaid 代码块向用户展示 chart.mmd。图表最多容纳 500 个状态,以 TLC 在原配置中统计的数量为准。超过上限时,只绘制通往违规规则的路径;没有违规规则时,命令不会生成 chart.mmd。命令仍会检查每条规则,报告中会列出状态数和每条 bug 路径。要查看完整图表,请缩小模型。
用 Pele 渲染图表。用户需要图片,或图表太大而难以阅读时,按 references/render.md 操作。除非用户要求,否则不要使用其他渲染器。
把每张图及其 Mermaid 文本交给决策者。每个 bug 写一行,列出规则、读者认可的规则原文,以及报告标注的路径。说明模型遗漏了什么,并给出重新生成文件的命令,使用新的 --out 目录。
模型描述代码时,对照真实代码逐步重放每条 bug 路径,可以用测试或现场复现,每个动作对应一步。bug 没有发生时,先认为模型有误,直到证明并非如此。
