--- name: statechart description: "检查在不同状态之间迁移的系统的 TLA+ 模型,例如产品流程、协议或服务,并把它画成 Mermaid 状态图。报告给出到达每个违反规则的状态的最短路径。用于 /statechart,或把缺陷展示为经过各个状态的路径。" 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` 传入。 要使用读者的语言,视图应导出 `state(vars)`。`state()` 的返回值决定图表形式: - 字符串生成平面图:`export const state = (v) => (v.paid ? "已支付" : "支付中");` - 数组生成父状态:`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]`。集合则是数组。 视图还可以导出 `step(action, from, to)`。它接收 TLC 动作名,以及迁移前后的值,返回箭头标签。用用户看见事情发生的方式写标签,例如“你按下播放”或“连接失败”。不要写代码名或 TLA+ 动作名。在图中产生相同结果的两个动作使用相同标签,这样它们可以共用一条箭头。 当一步只能在某些条件下发生时,在标签末尾用读者的语言加上方括号条件,例如 `你按下播放 [文件仍在加载时]`。在区域图中,命令会用其他区域标签的措辞把条件写在箭头上,例如 `[处于离线状态时]`。你自己写的方括号会替换这个条件,使同一状态发出的两条箭头看起来相同。因此,在区域图中,不要为其他区域上的条件自行写方括号。如果某个未出现在任何标签中的值决定迁移方向,就在标签中写出结果,例如“读取成员列表失败”。 视图还可以导出以下内容: - `group(vars)` 返回阶段名。每个图中状态使用其分组的颜色。如果同一个图中状态对应的模型状态属于不同分组,该状态不着色。 - `colors` 为每个分组名提供颜色类。 - `title` 是在图表顶部显示的字符串。 命令对每个模型状态最多调用一次 `state()` 和 `group()`,对每一步最多调用一次 `step()`。图表和报告共同使用这些返回值。因此每个函数只能依赖其参数。 图表不会绘制停留在同一标签内的迁移。如果读者必须看见这一步,就拆分标签。 尽量把箭头控制在约 20 条以内,因为更繁忙的图很难读。先让 `state()` 返回更粗的标签。给行为相同的值使用同一个标签,省略读者不需要的细节,例如返回结果不会改变任何内容的在途调用。保留缺陷路径上的每个状态,也保留每个标记。合并把 `breaks` 状态变成 `mayBreak` 时,会隐藏规则具体在哪个状态被违反。不要合并违反不同规则的两个状态,否则读者看不出哪条规则在哪里被违反。如果图仍过于繁忙,让 `step()` 对读者不需要的步骤返回 `null`,例如每个状态都有的重置,或箭头内容与其他箭头重复的步骤。隐藏步骤时遵守以下规则: - 保持每个图中状态都能沿箭头从起始状态到达。 - 对模型中存在出边的每个图中状态,至少保留一条出边。 - 一条箭头所代表的全部步骤要么全部隐藏,要么全部保留。只隐藏其中一部分会使它的条件变窄。 - 交付时说明图表隐藏了哪些步骤。 ## 阅读报告 - 图中违反规则的状态带有 `breaks` 类。如果它对应的模型状态中只有一部分违反规则,则带有 `mayBreak` 类。图例列出每个标记的规则。两条规则被违反时,会在同一个标记上列出两条,因此交付时要说明哪个状态违反哪条规则。在区域图中,如果包含某个区域状态的每种区域状态组合都可能违反规则,该区域状态就会带有标记。如果某种组合可能违反规则,但它包含的状态都没有标记,则给该组合中的每个状态添加标记。 - TLC 会继续越过违反规则的状态,因此图中也展示缺陷之后的状态。 - 因为 TLC 会继续越过缺陷,无状态上限的模型可能永远运行。保持常量较小,或添加 CONSTRAINT。 - 使用 VIEW 或 SYMMETRY 时,TLC 把它认为相同的状态计为一个状态,图中也只画这一个状态。箭头可能指向它,而不是这一步实际到达的状态;报告会说明这一点。 - TLC 会检查越过 CONSTRAINT 或 ACTION_CONSTRAINT 的各个状态中的规则,但不会探索该状态,也不检查它是否死锁。当 TLC 为某条规则给出的最短路径结束在这样的状态时,图表会画出该状态,报告会给出该路径。图表不会绘制越过边界的其他状态。此类状态中的死锁不会显示。TLC 还会检查 ACTION_CONSTRAINT 排除的每一步之后的规则,即使它会通过另一条路径到达后继状态。如果 TLC 给出的某条规则的最短路径以这样的步骤结束,图表会画出该步骤。 - 命令使用一个工作线程,按原样配置用 TLC 检查规则。一条规则被违反时,命令移除这条规则后再次运行 TLC,直到没有规则被违反。在第一次违规之后,每轮运行到达 100,000 个不同状态时停止,以免大模型无限运行。若运行达到该边界或因错误停止,报告会在“未检查的规则”下列出未完成检查的规则,图表不会标记它们。未检查的规则既可能成立,也可能被违反。要检查它,从配置中移除已被违反的规则,或缩小模型。这个边界会加入一个改变 TLC 变量排序的模块,所以对于时序属性,TLC 可能找到与未设边界时不同的反例。 - `tlc.out` 是 TLC 按原样配置打印的内容。当图表没有显示某条已被违反规则的缺陷路径时,`tlc-RULE.out` 保存找到该问题的那次运行的 TLC 输出。当 TLC 重复第一条警告时,直接运行 TLC 会打印两遍,而 `tlc.out` 只显示一遍,因为 TLC 没有把第二份写进命令读取的输出。只有 Java 使用 `-XX:+UseParallelGC` 时才会出现这种情况;否则 TLC 的第一条警告就是建议传入这个标志,而这条建议只打印一次。 ## 展示状态图 用 `mermaid` 代码块向用户展示 `chart.mmd`。图表预算为 500 个状态,按原样配置由 TLC 计数。超过预算时,图表只画通向违规规则的路径;如果没有规则被违反,命令不写出 `chart.mmd`。命令仍检查每条规则,报告仍给出状态数和每条缺陷路径。要查看完整图,缩小模型。 使用 Pele 渲染图表。用户要求图片,或图表大到难以阅读文本时,遵循 `references/render.md`。除非用户要求,否则不使用其他渲染器。 ## 交付 把每张图及其 Mermaid 文本交给需要作决定的人。每个缺陷增加一行:规则、用读者语言表达该规则的一句话,以及按报告编号的路径。说明模型省略了什么。给出能重新生成文件的命令,并使用新的 `--out` 目录。 模型描述代码时,把每条缺陷路径在真实代码上重放,使用测试或实际复现,每个动作对应一步。如果缺陷没有发生,先认为模型有误,直到你证明并非如此。