教程2026-11-10 · 智涌AI

让 Agent 找出隐式状态机:审计提示词与改写步骤

隐式状态机教程头图:左侧大字「隐式状态机 让 Agent 找」与 15 到 5 种组合、三步做法数字卡;右侧对比表列出空闲、呼叫中、通话中三个状态下,隐式写法都会执行添加联系人,显式状态机只在通话中加人

代码里到处是状态机:「在这个状态下,发生这个事件,就进入那个状态」。有的写得明明白白,是 switch、reducer 或一张转移表;更多的散落在 isLoading、isOpen 这类布尔标志和各处的 if 里,这就是隐式状态机。Agent 写代码时照样会这么写,测试全过、代码审查也说没问题,非法状态照样能溜进来。这篇给一套让 Agent 先找、再列、最后小步改写的做法,附可直接用的提示词。

测试全过,为什么还会出状态 bug

XState 作者 David Khourshid 在 2019 年那篇讲 FaceTime 漏洞的文章里,用一个简化例子说明了问题。苹果当年的漏洞是:视频通话还没接通时,上滑点「添加联系人」把自己加进去,就能提前听到对方的声音。他强调真实根因只有苹果知道,他只是借这个现象重现一类 bug:某个事件在不该被处理的状态下被处理了。

按直觉写,「点添加联系人」的处理函数直接建立音频连接,测试覆盖「点了就能加人」,一切正常。问题在于这个函数在什么状态下都会执行。文中的例子有 3 个状态(空闲、呼叫中、通话中)和 5 个事件,隐式写法下事件和状态能组合出 3 × 5 = 15 种情况,bug 藏在其中某一种里;改成显式状态机,每个事件只挂在它该出现的状态下,需要考虑的组合只剩 5 种,「添加联系人」只在「通话中」才处理。

写显式状态机时你会被迫回答一个问题:这个事件应该在哪个状态下处理?隐式写法里,这个问题往往没人问过。

怎么认出隐式状态机

信号典型样子容易出的事
几个布尔标志描述同一件事isLoading、isSuccess、isError 各管各的出现「既在加载又已成功」这种本不该存在的组合
事件处理函数里直接干活点击回调里直接发请求、建连接、改数据在错误的时机触发副作用
到处补 if每修一个 bug 就在某个函数开头加一句「如果还没连上就返回」规则散在多处,没人能列全
状态靠字符串约定status === 'pending' 在十几个文件里各写一遍新加一个状态时漏改几处

Khourshid 在文中的说法是:隐式状态机的规则只存在于开发者脑子里,要找 bug 就得知道全部可能的状态、全部可能的事件、每种状态下每个事件会触发什么,而这些信息散在代码各处,不读完代码列不出来。读完代码再列清单,这活可以交给 Agent。

第一步:只读审计,先要清单

别一上来就说「把状态机都改成显式的」。范围太大,Agent 容易一口气改十几个文件,你也没法审。先让它只读、只列:

只读审计,不要修改任何文件。

在 <目录或模块> 里找出隐式状态机:用多个布尔标志或字符串
表示同一件事的状态,或者在事件处理函数里直接执行业务逻辑、
靠分散的 if 判断时机的地方。

每找到一处,输出:
1. 位置(文件:行号)和它管的是什么流程
2. 现在能表示出来的状态,以及其中哪些组合本不该出现
3. 会改变状态的事件
4. 一张「状态 × 事件 → 下一个状态 / 副作用」表,
   标出哪些事件在不该处理的状态下也会被处理
5. 改成显式状态机后能消除的具体 bug 或风险
6. 改动量估计(小 / 中 / 大)

最后按「风险高、改动小」优先排序,只给前 5 个。少说话,多用表。

审计结果要自己过一遍。重点看第 4 列:Agent 标出的「不该处理却会处理」的组合,去代码里核实是不是真的能走到。确认是真问题的,才进入下一步。

第二步:先把现有行为钉住

挑排第一的那一处,先让 Agent 按审计表补测试:每一行「当前状态 + 事件 → 期望结果」写成一个用例,跑在改写之前的代码上。现有正确行为的用例应当通过;审计时发现的非法组合,写成「这个事件在这个状态下应被忽略」,这类用例此时应当失败。这样改写完成的标准就清楚了:前一类继续通过,后一类变成通过。

第三步:一次只改一个模块

Khourshid 给的建模顺序是三步:列出所有状态和初始状态;列出所有会引起转移的事件;确定每个状态下每个事件的下一个状态。简单流程用语言自带的 switch 或 reducer 就够,不必上库。给 Agent 的提示可以这样写:

只改 <文件或组件> 这一处,把它改成显式状态机:
- 用一个 status 字段取代这几个布尔标志,不允许出现互相矛盾的组合
- 事件处理函数只负责发送事件,副作用放到对应状态的转移里
- 转移规则集中写在一个地方(switch / reducer / 转移表)
- 对外接口和现有行为不变,刚补的测试必须全部通过
改完后列出:删掉了哪些标志和 if,新增的状态转移表长什么样。

流程本身有层级、有并行区域,或者要跨组件编排的,可以考虑 XState。它是 JavaScript / TypeScript 的状态管理库,用状态机、状态图(statechart)和 actor 模型组织逻辑,能接 React、Vue、Svelte 等框架,MIT 许可证,npm 最新版 5.33.4,GitHub 约 3 万星(截至 2026-11-10)。官方文档提到核心包里带图遍历和基于模型的测试工具,可以用来按状态图生成测试路径。

三个目标一起看:UX、DX、AX

让 Agent 做取舍时,可以把评判标准说清:改写要同时改善用户体验(UX,比如不再出现半加载半报错的界面)、开发者体验(DX,规则集中在一处、新人能看懂)和 Agent 体验(AX,下一个来改代码的 Agent 能从转移表直接读出规则,不用猜)。三者冲突时,以不破坏现有行为为底线。

常见坑

完成标准

最后

从最近一次「明明测过却出了状态 bug」的模块开始,先跑那段只读审计提示词。最怕出错的那几个状态机,还可以再往前一步做形式化验证,见 形式化验证 Skill:TLA+ 查状态机再画成图。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。