--- name: statechart description: "检查产品流程、协议、服务等在状态间移动的系统的 TLA+ 模型,并将其绘制为 Mermaid 状态图。报告给出通往每个违反规则状态的最短路径。用于 `/statechart`,或将 bug 展示为穿过状态的路径。" disable-model-invocation: true --- # 状态图 图表用读者自己的语言,展示系统如何在状态间移动。由这个人,也就是读者,决定行为是否正确。 ## 运行 在仓库之外的临时文件夹工作。编写 TLA+ 规范及配置。然后运行: ```sh /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)`。`state()` 返回值决定形式: - 字符串生成平面图:`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 });` 为每个状态标注读者能看见或关心的内容,例如“正在付款”或“已持有租约,等待写入”。标签不要出现变量名。在 `vars` 中,TLA+ 序列是一个键从 1 开始的对象,因此 `v.pc[1]` 就是 `pc[1]`。集合是数组。 view 还可以导出 `step(action, from, to)`。它接收 TLC 动作名称及步骤前后的值,返回箭头标签。按用户看到事情发生的方式编写每个步骤标签,例如“你按下播放”或“连接失败”。不要使用代码或 TLA+ 动作名称。在图表中具有相同终点结果的两个动作,应使用相同标签,从而共享一个箭头。 某一步只能在特定条件下发生时,在标签末尾用方括号、以读者的语言写出条件,例如 `you press play [while the file loads]`,即“你按下播放[文件正在加载时]”。在区域图中,命令会用其他区域标签的语言,将对这些区域的条件写在箭头上,例如 `[when Offline]`,即“[处于离线时]”。你写的方括号会替代它,于是从同一状态出发的两个箭头可能看起来一样。因此在区域图中,不要为关于另一个区域的条件写方括号。当某个标签都未显示的值决定步骤去向时,在标签中点明结果,例如“读取名单失败”。 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 对某规则的最短路径终止在这种状态时,图会绘制该状态,报告会给出该路径。图不绘制其他越过界限的状态。这种状态中的死锁不会显示。TLC 也会检查每个被 ACTION_CONSTRAINT 排除的步骤之后的规则,即使它通过另一种方式到达同一个下一状态。当 TLC 对某规则的最短路径以这种步骤结束时,图会绘制该步骤。 - 命令使用 TLC,按配置原文、以一个工作者检查规则。一条规则被违反时,命令移除该规则,再次运行 TLC,直到不再有规则被违反。第一次违反之后,每次运行都在 100,000 个不同状态处停止,避免大模型无休止运行。当某次运行达到该界限或因错误停止时,报告在“Rules not checked”(未检查的规则)下列出未检查规则,图中不标记这些规则。未检查的规则可能成立,也可能被违反。要检查它,从配置中移除被违反的规则,或缩小模型。该界限会添加一个改变 TLC 变量顺序的模块,因此对于某个性质,TLC 可能找到与无界限运行不同的反例。 - `tlc.out` 是 TLC 按配置原文运行时打印的内容。当图没有展示某条被违反规则的 bug 路径时,`tlc-RULE.out` 是发现该路径那次运行的 TLC 输出。当 TLC 重复其第一条警告时,普通 TLC 会打印两次,但 `tlc.out` 只显示一次,因为 TLC 在本命令所读取的输出中省略了第二份。仅当 Java 带 `-XX:+UseParallelGC` 运行时才会发生;否则 TLC 的第一条警告就是建议传入该标志,它只打印一次。 ## 展示图表 把 `chart.mmd` 作为 `mermaid` 代码块展示给用户。图表预算为 500 个状态,按 TLC 使用配置原文的计数。超过该数量,图只绘制通往被违反规则的路径;如果没有规则被违反,命令不会写出 `chart.mmd`。它仍然检查每条规则,报告给出状态数量及每条 bug 路径。要查看整张图,缩小模型。 使用 Pele 渲染图表。当用户要求图片,或图大到无法作为文字阅读时,遵循 `references/render.md`。除非用户要求,否则不要使用其他渲染器。 ## 交接 把每张图及其 Mermaid 文本交给必须作决定的人。为每个 bug 添加一行:规则、用读者语言描述该规则的句子,以及按报告编号的路径。说明模型遗漏什么。提供重新生成文件的命令,使用一个新的 `--out` 文件夹。 当模型描述代码时,对照真实代码,以测试或现场复现的方式重放每条 bug 路径,每个动作对应一步。如果 bug 没有发生,在证明模型无误之前,先认为模型错了。