SuperAPI AI 工具集

statechart

编程与开发

查看项目

更新于 11-06 21:01

技能介绍

Statechart 是一个用于检查系统状态迁移模型并生成状态图的技能。它面向需要审查状态行为的读者:图按读者能理解的语言展示系统如何在状态之间迁移,由读者判断行为是否正确。

用途 用于检查描述系统状态迁移的 TLA+ 模型,典型对象包括产品流程、协议或服务。生成的状态图用于与需要做判断的人沟通行为是否符合预期。

主要能力

  • 用 TLC 逐条检查不变量(INVARIANT)与属性(PROPERTY),规则可涉及界面、结果、存储值或消息。
  • 输出 Mermaid 状态图(chart.mmd),标注破坏规则的状态:仅部分底层状态违规时标为 mayBreak,并区分不同规则。
  • 支持扁平图、父子层级状态和并行区域三种图形态,由 view 模块的 state() 返回值决定。
  • 可通过 step() 定制箭头文案与条件,通过 group() 与 colors 设置分组与配色,通过 title 设置标题。
  • 报告给出状态数、各错误路径及其规则,并列出因达到 10 万状态上限或出错而“未检查”的规则。
  • 图表状态数超过 500 时只绘制通往违规规则的路径;无规则被破坏时不写 chart.mmd,但仍逐条检查。

使用方式

  1. 每个会话先阅读一次 host adapter,它把上游 Cursor 相关的工具、模型、路径与权限说明映射到当前宿主,并设定权限边界。
  2. 在仓库之外的临时目录中编写 TLA+ 规格与配置文件。
  3. 运行 <skill dir>/scripts/statechart SPEC.tla [--config FILE] [--view FILE] [--out DIR]。脚本为 TypeScript,需用可执行 TypeScript 的运行时。首次运行会用 mise 安装 TLC 与 Java,需要网络。
  4. 编写 view 模块,导出 state(vars)、可选的 step(action, from, to)、group(vars)、colors 与 title,并通过 --view 传入。
  5. 将 chart.mmd 以 Mermaid 代码块展示;需要图片或图过大难以阅读时,按 references/render.md 使用 Pele 渲染。

编写要点

  • 将读者认可的每条规则写为 INVARIANT;模型中缺少对应变量时应补充变量,不得为使其成立而弱化规则。
  • 将 Next 写为各动作的析取(如 YouPressPlay / YouPressStop),否则 TLC 会把每一步都命名为 Next。
  • 没有出边的状态会破坏 NoDeadlock,即使它是正确的终止状态;可在 Next 中加入仅在终止状态为真且不改变变量的动作(如 Done),并在 step() 中为其命名。
  • 状态标签使用读者可见或关心的表述,避免变量名;箭头文案描述用户看到的事件,不写代码或 TLA+ 动作名。
  • 建议箭头数控制在约 20 条以内;可让 state() 返回更粗的标签合并行为相同的值,或在 step() 中对不需要的步骤返回 null 隐藏。隐藏须保持每个图状态可从起始状态经箭头到达、每个有出步的图状态至少保留一条出边,并整条箭头隐藏而非部分隐藏;交接时说明隐藏了哪些步骤。

适用场景 适用于需要以状态图向非实现者解释流程或协议行为、并验证规则是否被破坏的评审场景,也适合在模型与真实代码之间做对照复现。

限制

  • TLC 会越过破坏规则的状态继续探索,因此图中会显示错误之后的状态;无状态上限的模型可能一直运行,需保持常量较小或加入 CONSTRAINT。
  • 使用 VIEW 或 SYMMETRY 时,TLC 将视为相同的状态计为一个,图中只画该状态,箭头可能指向它而非实际到达的状态,报告会说明。
  • 越过 CONSTRAINT 或 ACTION_CONSTRAINT 的状态只检查规则,不再探索,也不检查死锁;受此限制的状态不会画出,其中的死锁不会显示;ACTION_CONSTRAINT 排除的步骤仍会检查规则。
  • 命令以单 worker 在原始配置上运行;某规则被破坏后将其移除并重跑,首次破坏后每次运行在 10 万个不同状态处停止;达到上限或出错时,未检查的规则列在“Rules not checked”中,图中不做标记,这些规则可能成立也可能不成立。
  • 上限会加入一个改变 TLC 变量顺序的模块,因此属性可能得到与无上限运行不同的反例。
  • 图表状态预算为 500(按原始配置由 TLC 计数),超过则只画违规路径。
  • 首次运行需要网络安装 TLC 与 Java;脚本需可执行 TypeScript 的运行时;渲染默认使用 Pele。

交接 向决策者提供图及其 Mermaid 文本;为每个错误加一行说明:规则、该规则的读者表述、报告中编号的路径;说明模型省略了什么;并给出用新 --out 目录重新生成文件的命令。当模型对应代码时,按每个动作一步,在真实代码上以测试或实际复现回放每条错误路径;若错误未出现,应先假定模型有误,直至能证明其无误。