mcpField
S
statechart

statechart

github.com/cursor测试与质量14.6k412 次安装1 天前更新
代码仓库

关于 statechart

statechart 是一套用状态图和 TLA+ 模型分析应用行为的工作流程，面向产品经理与代码审查者。它支持从规格生成图表或从图表生成规格，并将用户可见状态与代码路径对应起来以检查规则和缺陷。

主要功能

  1. 01从 TLA+ 规格生成状态图
  2. 02从状态图生成规格
  3. 03映射用户可见状态与步骤
  4. 04用不变量检查行为规则
  5. 05渲染图表并复现缺陷路径

适用场景

  1. 01在实现前让产品经理确认应用行为
  2. 02审查代码是否违反既有规格
  3. 03用图表定位不同代码路径导致的缺陷
  4. 04交接图表、复现记录与修复状态

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cursor/plugins --skill statechart

安装后在 Claude Code 中输入/statechart确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

scripts/
chart-to-tla.mjs
compare-charts.mjs
lib.mjs
statechart.mjs
tlc-to-chart.mjs
scripts/model/
OutputFolder.cfg
OutputFolder.map.mjs
OutputFolder.tla
scripts/test/
statechart.test.mjs
sync.mmd
upload.mmd

详细介绍

状态图

此图展示应用用户看到的内容。PM 会阅读此图，以判断行为是否正确。每个状态都标注屏幕上显示的内容，例如“正在付款”。每个步骤都标注用户执行的操作或看到的情况，例如“点击付款”或“扣款成功”。标签中不要使用变量名和操作名称。脚本将此用户称为读者，例如 readerActions 和读者步骤。

运行 node <skill dir>/scripts/statechart.mjs --help，查看命令和图表的阅读方法。在仓库外的临时文件夹中操作。该命令会将文件写入输入文件所在目录。

选择方向

存在 TLA+ 模型或代码足够具体、可以建模时，使用 from-spec。没有模型，且 PM 应在任何人编写或更改代码前确认行为时，使用 from-chart。

如果代码已有 TLA+ 规范，请从该规范的副本开始。添加用户可见的变量，并保留规范中已有的不变量。若要根据该规范审查代码，请让副本描述代码的实际行为，并将规范原样作为 --against 传入。在新规范中，将每个变量和操作对应到审查者可以打开的代码，并使用代码中的名称。每个操作都应是代码中不可再分的一步。

从规范生成图表

  1. 选择图表中的状态。当 PM 关注屏幕未显示的内容时，例如屏幕仍显示“正在付款”但已发生第二次扣款，请将状态命名为“正在付款，已扣款两次”。从少量状态开始，仅在拆分状态能区分两个 bug 时才拆分。
  2. 将 PM 同意的每条规则写成一个不变量，并将 PM 的原话作为注释。对于在一切稳定后才适用的规则，定义 Settled == ~ENABLED System，其中 System 是用户不会执行的操作的析取。将每条被违反的规则报告为 bug。绝不要为了让图表通过而放宽规则。
  3. 运行 from-spec，然后填写它生成的映射文件。将标签填入 state 和 step，并按操作名称在 readerActions 中列出用户操作。如果两个 bug 经由不同代码路径最终显示在同一个屏幕上，请添加 cause，并使其指明代码路径。若要根据 PM 关注的内容为状态着色，例如“显示 Toast”，请从 group 返回该组。图例会标注各组名称，而违反规则的状态仍会显示红色边框。
  4. 如果存在待处理的修复，请根据代码建模，并将该模型作为 --fixed 传入。
  5. 使用 --png 渲染每张图表，并查看所有 PNG。检查每条编号路径是否按顺序阅读。如果标签看起来像代码，请修改 state 或 step，然后重新运行命令。
  6. 将每个 bug 的过程按模型操作逐步在真实代码上重现，可通过测试或实时复现完成。如果某个 bug 无法重现，在证明相反之前，应假设模型有误。修正模型，而不是规则。

从图表生成规范

  1. 绘制 PM 同意的图表。每个独立变化的对象使用一个区域，例如连接状态和同步徽标。每条规则添加一行 %% never，并附上 PM 的原话。将“应用关闭”画成一条指向用户接下来看到的状态的边。
  2. 运行 from-chart。如果某条规则被违反，说明双方同意的图表存在设计 bug。将该 bug 提交给 PM 处理。
  3. 将真实代码中的守卫条件和变量添加到 from-chart 生成的规范中，然后再次运行 from-chart。对于它输出的每项差异，询问 PM 是代码有误，还是图表需要修正。

交接

向 PM 提供每张图表的 PNG 和 Mermaid 源文件。每个 bug 用一行说明它违反的规则、图表标注的步骤、是否成功复现，以及待处理的修复是否能解决它。所有引用的数量都取自 summary.json。附上 stories.md 和重新生成全部内容的命令。说明模型未涵盖的内容。

评论

支持 Markdown