SuperAPI AI 工具集

statechart

编程与开发

查看项目

更新于 10-27 00:32

技能介绍

Statechart 是一个用于把系统在状态之间如何迁移画成 Mermaid 状态图的技能。它强调图要按“读图的人”能观察或关心的词语来标注:状态用读者能看到的说法(如应用中的“Paying”,锁服务中的“Lease held, write pending”),步骤用推动系统变化的事件(如“tap Pay”“request reads the count”“the lease expires”),并避免把变量名和动作名写进标签。

用途与两个方向:

  1. from-spec:当已有 TLA+ 模型,或代码/设计足够具体可以建模时使用。可从现有 spec 副本开始,补充标签和规则所需的变量,保留原有不变式;当模型描述代码时,要求每个变量和动作都能对应到评审者可打开的代码,每个动作是代码中不可分割的一步,并在条件注释中标出检查该条件的文件与行号(如 * pay.ts:120)。
  2. from-chart:当没有模型、且行为所有者应先就图达成一致再构建或修改时使用。先画出读者认可的状态图,每个独立变化的部分用一个 region,每条规则加一行 %% never,并附上读者的原话;把停止或重启某部分的事件画成迁移边。

主要能力:

  • 生成并渲染 Mermaid 状态图(支持 --png 输出 PNG 查看)。
  • 把读者认可的规则写成不变式,用 TLC 检查;对“系统必须能够达到的目标”写一条“目标永不发生”的规则并用 --expect-broken 传入,破坏它的路径即为达成目标的路径。
  • 当概览图过大时用 --cover 只保留到每个稳定状态的最短路径及所有 bug 路径,并列出被省略的内容。
  • 当两个 bug 以不同原因结束于同一状态时,用 cause 标明原因;用 group 按读者关心的分组给状态着色,图例会列出分组名,PNG 中违反规则的状态以红色替代分组颜色。
  • 有提议修复时对其建模并通过 --fixed 传入。
  • 生成 stories.md 记录每个 bug 的规则、步骤编号、是否复现及修复是否有效;所有引用计数取自 summary.json。
  • 当模型描述代码时,要求把每个 bug 的故事对真实代码回放(测试或现场复现),每步对应一个模型动作,只驱动用户、客户端或其他系统部分可达的入口,只断言它们能观察到的东西;若 bug 未复现,先假定模型有误并修正模型而非规则。

使用方式: 在仓库之外的临时文件夹中工作,命令会把文件写在输入旁边。运行 node <skill dir>/scripts/statechart.mjs --help 查看命令与读图方法;帮助中的 TLC 部分说明如何使用已有的 TLC 与 Java。首次运行会通过 mise 安装 TLC 和 Java,下载约 305 MB,需要网络。选择方向后运行 from-spec 或 from-chart,填写生成的映射文件(state、step、readerActions、cause、group 等),用 --png 渲染并逐张检查编号路径是否按顺序可读,标签像代码就修正后重跑。交付时把每张图的 PNG 和 Mermaid 源码交给决策者,每个 bug 一行说明其违反的规则、按图编号的步骤、是否复现、提议修复是否有效,并附上 stories.md 与可重新生成全部内容的命令,同时说明模型省略了什么。

适用场景:产品流程、协议、服务、锁服务等系统状态流转的梳理与评审;需要在动手实现前让产品经理、工程师、评审者对行为达成一致的场景;用 TLA+ 模型审计代码并定位违例路径的场景。

限制与未提供信息:资料未说明收费、价格、平台支持范围、具体效果指标或性能数据;首次安装需要网络与约 305 MB 下载;帮助文档中关于使用已有 TLC 与 Java 的具体步骤未在资料中展开;模型未覆盖的内容需要在交付说明中明确列出。