跳转到内容
pstack 中文学习站

0.15.30:把用户看到的行为画成状态图

更新于 2026-10-27

对照范围:学习站现在对照的是 0.15.29 / 88d4751,上一轮的译文已经收了那一版。官方 pstack 已发布 0.15.30 / 4ec7ffa。本文只写提交说明和 diff 能核对到的事。

英文对照的一头一尾:88d4751(0.15.29)、4ec7ffa(0.15.30)。0.15.30 的译文和指南留在历史版本。

这一版多了一个新 skill:/statechart。它把用户看到的行为画成一张状态图,图由 TLA+ 模型生成,每个 bug 画成一条编号路径,拿给 PM 或设计师看。

#741 加入 /statechart。它要解决的问题是:用模型术语写出的反例能说服你自己,拥有这个行为的 PM 或设计师,需要用他们的术语看见它。

skill 画的是应用用户看到的东西。每个状态用屏幕上的内容命名,每一步用用户做的事、或看到发生的事命名,标签里不出现变量名和动作名。图由 TLA+ 模型生成,TLC 把读者的规则当成不变量检查,所以图和检查过的模型不会各走各的。TLC 发现的每个 bug 画成一条编号路径。每个状态标上正常、仍有错、或已被你打开的 PR 修复。

两个方向都支持:

  • 已有 TLA+ 模型,或代码具体得足以建模:从规格画图。
  • 还没有模型:先把行为勾画成一张图,和读者商定,skill 从图写出一份 TLA+ 骨架。代码还不存在,TLC 就能检查这张商定好的图。

代码已经有 TLA+ 规格时,它还能拿代码对照规格做审计:agent 按代码的实际行为建模,把这个模型和没动过的规格放在一起检查,两者不同的每一步都标在图上,任何一方打破的每条规则都是一条编号路径。

交付之前,agent 会在真实代码里把每条 bug 路径复现一遍,建模错误就不会以 bug 的身份到达 PM。

官方文档同步到位:插件 README 的命令表加了 /statechart 一行,官方指南第 6 页《验证与交付》加了「把行为画成状态图」一节,/poteto-help 的路由表也指到了它。

#776 分六笔把 statechart skill 修到可用状态。读者能感受到的变化:

  • 不再悄悄给错答案:标签映射读到代码模型或对照规格里没有的变量时,命令直接停下,不再拿当前模型的起始值顶上。商定配置不检查的规则,在故事文件里标成 not checked,不再写成商定规格守住了它。
  • 新增 --config、--fixed-config、--against-config:商定好的规格不会拿代码模型的配置去检查。配置缺失时,错误信息列出规格旁边现有的配置。
  • TLC 或发布失败时不再丢成果:TLC 报 Java 异常时,已经打印的路径保留,规则标为打破,并提醒图可能漏掉状态。在不能 rename 的文件系统上(比如 FUSE 挂载,报 ENOSYS、EXDEV、EISDIR 的那种)改成复制文件。
  • 每条规则用全部 CPU 检查。规则被打破时再用单 worker 查一遍,得到每次运行都相同的最短 bug 路径。命令打印 TLC 跑了几次、花了多久。配置里的每条 PROPERTY 也单独检查。图只画 INVARIANT 规则,被打破的 PROPERTY 点名 TLC 写出的反例文件。
  • 用 --against 审计时,每个 bug 都说明商定规格旁边的配置是否预期它(从配置的 \* expect: 和 \* module: 行读),结果写进 summary.json。用 --fixed 或 --against 时,没有注释绑到文件和行号的条件会被列出来。
  • 一条规则同时列成 INVARIANT 和 PROPERTY 时只检查一次(按 INVARIANT),bug 只画一次。TLC 1.8.0 下的测试也不再误判。

#779 删掉 statechart 脚本里复述代码的注释。注释里有事实的,改成名字或共享常量来承载:splitComments 改名 splitCommentsKeepingOffsets,quote 改名 escapeMermaidQuotes,两份相同的正则合成一个 PRIMES_OR_UNCHANGED,另有几处类似的重命名。行为不变。

插件升到 0.15.30 后,在 Cursor 里输入 /statechart,后面跟上想画的行为,比如:

/statechart what the user sees when they edit a note offline

skill 的脚本需要 TLC(TLA+ 的模型检查器)。从 TLA+ 的发布页下载 tla2tools.jar,把环境变量 TLA2TOOLS 指到这个 jar,JAVA 指到一个 Java 11 或更高版本的 java 二进制。

plugin.json(两处)是面向机器的文件,statechart 的脚本(scripts/)是命令实现,都不做中文翻译,所以没有对应中文页。

三笔提交,作者 lauren,与 Cursor Agent 共同署名。

  • eb4db2b:新增 statechart skill,把 TLA+ 模型画成状态图,版本号升到 0.15.30(#741,北京时间 2026-10-22 14:08)
  • 7698375:statechart 的六个修复(#776,北京时间 2026-10-23 00:57)
  • 4ec7ffa:删掉复述代码的注释,重命名 helper,行为不变(#779,北京时间 2026-10-23 02:27)

感谢阅读

关注站长 liu xu,pstack 有新译文和笔记会第一时间发。

公众号「出发向未来」的二维码
公众号「出发向未来」