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 或设计师看。
新 skill:/statechart(#741)
Section titled “新 skill:/statechart(#741)”#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)
Section titled “六个修复(#776)”#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)
Section titled “清理注释(#779)”#779 删掉 statechart 脚本里复述代码的注释。注释里有事实的,改成名字或共享常量来承载:splitComments 改名 splitCommentsKeepingOffsets,quote 改名 escapeMermaidQuotes,两份相同的正则合成一个 PRIMES_OR_UNCHANGED,另有几处类似的重命名。行为不变。
怎么试 /statechart
Section titled “怎么试 /statechart”插件升到 0.15.30 后,在 Cursor 里输入 /statechart,后面跟上想画的行为,比如:
/statechart what the user sees when they edit a note offlineskill 的脚本需要 TLC(TLA+ 的模型检查器)。从 TLA+ 的发布页下载 tla2tools.jar,把环境变量 TLA2TOOLS 指到这个 jar,JAVA 指到一个 Java 11 或更高版本的 java 二进制。
没有中文对照的文件
Section titled “没有中文对照的文件”plugin.json(两处)是面向机器的文件,statechart 的脚本(scripts/)是命令实现,都不做中文翻译,所以没有对应中文页。
三笔提交,作者 lauren,与 Cursor Agent 共同署名。
