跳转到内容
pstack 中文学习站

statechart

更新于 2026-10-28

检查系统状态变化的 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 没有发生时,先认为模型有误,直到证明并非如此。

感谢阅读

关注站长 liu xu,pstack 有新译文和笔记会第一时间发。

公众号「出发向未来」的二维码
公众号「出发向未来」