以下状态、事件、守卫规则与审批场景均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。审批的"2 级权限"是讲解用的简化,真实合规流程会有更多约束,但"守卫失败状态不变并留下原因"这一条不变。
2.2 将用事件溯源、持久化执行与幂等副作用讲执行语义。这一节先打地基:为什么执行语义要建立在状态机之上,以及状态机最容易被写错的三块——状态、转移、守卫。
很多 Agent 运行时把"任务进行到哪一步"存成一个字符串字段,然后在代码里散落 if status == "..." 判断。这看起来简单,但正是 2.2 要讲的故障(副作用已发生未记录、重放重复执行)的温床。状态机把"状态"“什么事件允许发生"“转移的前提"显式建模出来,让非法转移在入口就被拒绝,而不是在下游爆炸。
状态机三件事:状态、转移、守卫
状态是任务的语义快照。 一个 W3 审批任务,状态可以是 PENDING(待审批)、APPROVED(已批准)、EXECUTED(已执行)、REJECTED(已拒绝)。状态要覆盖所有业务上有意义的阶段,并且互斥——一个任务同时处于两个状态就是 bug。
转移是事件驱动的。 状态不会自己变,它由事件触发:approve 事件把 PENDING 推向 APPROVED,execute 事件把 APPROVED 推向 EXECUTED。每个(状态, 事件)组合要么有一条已定义的转移,要么是非法事件。
守卫是转移的业务前提。 这是最容易被忽略的一块。approve 事件在 PENDING 上不是无条件生效的——审批人的级别够不够?execute 事件在 APPROVED 上也不是无条件生效的——是否已审批、计划是否有效?守卫是一段返回(是否通过, 原因)的判定:守卫失败时状态不变,转移被拒绝,并留下拒绝原因。
三者的关系可以写成一张表:
| 元素 | 回答的问题 | 失败的表现 |
|---|---|---|
| 状态 | 任务现在处于哪个语义阶段 | 出现未定义状态 |
| 事件 | 什么外部信号推动转移 | 事件没有对应转移 → 非法 |
| 守卫 | 这个转移当前是否合法 | 守卫拒绝 → 状态不变,记录原因 |
为什么守卫必须显式建模
守卫如果不在状态机里显式建模,通常会散落在调用方代码里,出现两种坏味道:
- 守卫绕过。 某个调用方直接改状态字段(
task.status = "EXECUTED"),绕过了守卫,未审批的任务直接执行。状态机把守卫绑在转移上,让"直接改状态"成为不可能——状态只能通过 dispatch 改变。 - 守卫重复且不一致。 三个调用方各自写一份"能否执行"的判断,稍有出入就是三个口径。守卫集中定义在转移表里,只存在一份。
第 2 种坏味道尤其值得注意:Agent 运行时里,一个动作的合法性判断(能不能调用这个工具、能不能执行这个步骤)会在多个地方出现。把守卫收拢到状态机的转移定义里,是消除"多处判断口径不一致"的直接手段。
最小实验:W3 审批状态机
实验实现一个通用的 StateMachine(状态 × 事件 → 守卫 + 目标状态),再用它构造一个 W3 审批机,跑一组事件序列。
# file: agp_lab/state_machine.py | write
# tier: 3
# verify: python3 -m unittest tests.test_state_machine
"""状态机:状态、事件、守卫与非法转移。
2.2 用状态机讲执行语义(事件溯源、幂等);这里补上守卫
(guard)这一块:状态 × 事件 →(守卫,目标状态)。守卫是
转移的业务前提,守卫失败时状态不变,转移被拒绝并留下原因。
本模块实现一个 W3 审批状态机,演示事件驱动转移、守卫校验
与非法事件拒绝三件事。
"""
from __future__ import annotations
from dataclasses import dataclass
from enum import Enum
from typing import Any, Callable
class State(str, Enum):
PENDING = "PENDING"
APPROVED = "APPROVED"
EXECUTED = "EXECUTED"
REJECTED = "REJECTED"
Guard = Callable[[dict[str, Any]], tuple[bool, str]]
@dataclass(frozen=True)
class Transition:
guard: Guard
target: State
class StateMachine:
"""事件驱动的状态机:dispatch 返回(新状态, 是否成功, 原因)。"""
def __init__(self, table: dict[tuple[State, str], Transition]) -> None:
self.table = table
self.state: State | None = None
self.rejections: list[str] = []
def reset(self, initial: State) -> None:
self.state = initial
self.rejections = []
def dispatch(self, event: str, context: dict[str, Any]) -> tuple[State | None, bool, str]:
assert self.state is not None
key = (self.state, event)
if key not in self.table:
reason = f"illegal event '{event}' in {self.state.value}"
self.rejections.append(reason)
return self.state, False, reason
transition = self.table[key]
ok, reason = transition.guard(context)
if not ok:
self.rejections.append(reason)
return self.state, False, reason
self.state = transition.target
return self.state, True, "ok"
def w3_approval_machine() -> StateMachine:
"""W3 审批状态机:PENDING → APPROVED → EXECUTED,附守卫。"""
def guard_approve(ctx: dict[str, Any]) -> tuple[bool, str]:
level = ctx.get("approver_level", 0)
return level >= 2, "需要 2 级审批权限"
def guard_execute(ctx: dict[str, Any]) -> tuple[bool, str]:
approved = ctx.get("approved", False)
plan_ok = ctx.get("plan_ok", False)
return approved and plan_ok, "需已审批且计划有效"
return StateMachine({
(State.PENDING, "approve"): Transition(guard_approve, State.APPROVED),
(State.PENDING, "reject"): Transition(lambda _ctx: (True, ""), State.REJECTED),
(State.APPROVED, "execute"): Transition(guard_execute, State.EXECUTED),
(State.APPROVED, "reject"): Transition(lambda _ctx: (True, ""), State.PENDING),
})
def demo() -> dict[str, Any]:
"""运行一组事件序列,返回每一步的结果。"""
machine = w3_approval_machine()
machine.reset(State.PENDING)
events: list[dict[str, Any]] = []
events.append({"event": "approve", "ctx": {"approver_level": 1}})
events[-1]["result"] = machine.dispatch("approve", {"approver_level": 1})
events.append({"event": "approve", "ctx": {"approver_level": 3}})
events[-1]["result"] = machine.dispatch("approve", {"approver_level": 3})
events.append({"event": "execute", "ctx": {"approved": True, "plan_ok": False}})
events[-1]["result"] = machine.dispatch(
"execute", {"approved": True, "plan_ok": False}
)
events.append({"event": "execute", "ctx": {"approved": True, "plan_ok": True}})
events[-1]["result"] = machine.dispatch("execute", {"approved": True, "plan_ok": True})
events.append({"event": "approve"})
events[-1]["result"] = machine.dispatch("approve", {})
return {"events": events, "state": machine.state.value, "rejections": machine.rejections}
if __name__ == "__main__":
result = demo()
for item in result["events"]:
state, ok, reason = item["result"]
print(
f"{item['event']:<10} -> {state.value:<10} ok={ok:<5} reason={reason}"
)
print(f"final_state={result['state']}")
print(f"rejections={result['rejections']}")
运行:
cd private/labs/agp-lab
python3 -m agp_lab.state_machine
输出:
approve -> PENDING ok=0 reason=需要 2 级审批权限
approve -> APPROVED ok=1 reason=ok
execute -> APPROVED ok=0 reason=需已审批且计划有效
execute -> EXECUTED ok=1 reason=ok
approve -> EXECUTED ok=0 reason=illegal event 'approve' in EXECUTED
final_state=EXECUTED
rejections=['需要 2 级审批权限', '需已审批且计划有效', "illegal event 'approve' in EXECUTED"]
五步事件对应五类转移行为:
- approve(approver_level=1)→ PENDING,ok=0:守卫拒绝,理由"需要 2 级审批权限”。注意状态没变,还是 PENDING。守卫失败不消耗事件。
- approve(approver_level=3)→ APPROVED,ok=1:审批人级别够了,转移成功。
- execute(approved=True, plan_ok=False)→ APPROVED,ok=0:计划无效,守卫拒绝,状态仍是 APPROVED。
- execute(approved=True, plan_ok=True)→ EXECUTED,ok=1:前提齐了,转移成功,终态。
- approve 在 EXECUTED 上 → EXECUTED,ok=0:这个事件在终态上没有定义转移,触发"illegal event"拒绝。非法事件与守卫失败是两种拒绝:前者是(状态, 事件)不在转移表里,后者是转移存在但前提不满足。
rejections 把三次拒绝的原因都留下了。这正是 2.2 需要的:一切状态变迁(包括被拒绝的尝试)都可追溯,才能谈事件溯源。
一个细节值得点破:非法事件的报错文案 illegal event 'approve' in EXECUTED 是运行时自动生成的,不是手工文案。这意味着只要转移表完备,任何未定义的组合都会被自动以统一格式拒绝,不需要给每个非法组合单独写分支。
状态机建模的收益,要到恢复场景里才真正显现。崩溃后系统要回答"我在哪一步、这一步还能不能走”,状态机的显式状态让这个问题可以直接回答;如果是散落的字符串字段,就只能靠日志猜。状态机不只是开发期的整洁,更是运维期的可恢复性。 2.3 的崩溃恢复矩阵之所以能逐点枚举,前提就是状态是有限且显式的。
状态机的持久化位置是另一个架构决策。把当前状态存在内存里,恢复时就要从事件日志重放(见 2.2);把状态直接存数据库,恢复时读一条记录就行,但要处理"状态已更新但事务未提交"的窗口。两种方案一个重放成本高、一个写放大,生产上通常按状态的重要性混合使用——关键状态落库,热状态走重放。状态机模型选对后,落哪个存储、怎么恢复,是紧随其后的两个决定。
状态机的守卫(guard)要集中在状态定义里,而不是散落在各处理函数。守卫决定"这个事件在这个状态能不能发生",散落写在每个 handler 里,同一个规则会有多份实现、互相漂移。集中定义后,测试也可以按"状态×事件×守卫"枚举:每个格子要么允许转移、要么拒绝,行为完全可预期。
| 守卫集中方式 | 优点 | 缺点 |
|---|---|---|
| 状态定义里集中 | 规则唯一,可枚举测试 | 状态文件变大 |
| 各 handler 分散 | 贴近实现 | 规则漂移、难以审计 |
架构判据
状态机建模是否合格,用五条判据检查:
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 状态互斥 | 每步有且仅有一个状态 | 状态散落为多个字符串字段 |
| 转移显式 | (状态, 事件)有明确的转移表 | 靠 if 语句散落判断 |
| 守卫集中 | 前提在转移定义里,只此一份 | 合法性判断在调用方重复 |
| 非法事件拒绝 | 未定义组合被自动拒绝并记录 | 未定义组合静默通过 |
| 变迁可追溯 | 每次 dispatch 结果(含拒绝)被记录 | 状态直接赋值,无记录 |
判据里最后一条是通往 2.2 的桥:变迁可追溯。 状态机只建模还不行,还要记录每一次(状态, 事件, 结果),这才构成 2.2 事件溯源的数据基础。
小结
- 状态机由状态、事件驱动的转移、守卫三件事组成;守卫失败状态不变并留下原因。
- 守卫必须集中建模在转移定义里,消除散落在调用方的重复判断与口径不一致。
- 非法事件(未定义转移)与守卫失败(前提不满足)是两种拒绝,运行时都能自动记录。
- 每次 dispatch 的结果都被记录,才构成 2.2 事件溯源与幂等副作用的基础。
阅读导航:上一节:1.3 依赖方向与架构不变量 · 下一节:2.2 执行语义:事件溯源、持久化执行与幂等副作用 。
常见错误与边界
- 直接改状态字段。 状态只能通过 dispatch 改变;直接赋值绕过了守卫,是执行语义失效的头号来源。
- 把守卫散落在调用方。 三个调用方三份"能否执行",口径迟早分裂;守卫要收拢到转移表。
- 不记录被拒绝的尝试。 守卫拒绝和非法事件都要进 rejections;否则审计时说不清"为什么没执行"。
- 给每个非法组合写分支。 转移表完备后,非法组合由运行时统一拒绝,不需要手工枚举。
- 状态机不能替代执行语义。 状态机只保证转移合法;副作用是否幂等、崩溃后如何恢复,是 2.2 的范畴。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。