状态机实战

为什么用状态机

不用状态机：
if order.status == "pending":
    if payment_ok:
        order.status = "paid"
    elif cancelled:
        order.status = "cancelled"
elif order.status == "paid":
    if shipped:
        order.status = "shipped"
# 状态越多越乱，漏掉转换就出 bug

用状态机：
每个状态只有合法的转换路径
非法转换自动拒绝
代码清晰，不容易出 bug

Python 实现

from enum import Enum
from dataclasses import dataclass

class State(Enum):
    PENDING = "pending"
    PAID = "paid"
    SHIPPED = "shipped"
    DELIVERED = "delivered"
    CANCELLED = "cancelled"

# 定义合法转换
TRANSITIONS = {
    State.PENDING: [State.PAID, State.CANCELLED],
    State.PAID: [State.SHIPPED, State.CANCELLED],
    State.SHIPPED: [State.DELIVERED],
}

class Order:
    def __init__(self):
        self.state = State.PENDING

    def transition(self, new_state):
        if new_state in TRANSITIONS.get(self.state, []):
            self.state = new_state
            return True
        raise ValueError(f"不能从 {self.state} 转换到 {new_state}")

order = Order()
order.transition(State.PAID)      # ✓
order.transition(State.SHIPPED)   # ✓
order.transition(State.PENDING)   # ✗ 不允许回退！

使用 transitions 库

from transitions import Machine

class Order:
    states = ['pending', 'paid', 'shipped', 'delivered', 'cancelled']

    def __init__(self):
        self.machine = Machine(model=self, states=Order.states, initial='pending')
        self.machine.add_transition('pay', 'pending', 'paid')
        self.machine.add_transition('ship', 'paid', 'shipped')
        self.machine.add_transition('deliver', 'shipped', 'delivered')
        self.machine.add_transition('cancel', ['pending', 'paid'], 'cancelled')

order = Order()
order.pay()    # → paid
order.ship()   # → shipped
order.cancel() # → 报错！shipped 状态不能 cancel

状态机应用场景

1. 订单系统：pending→paid→shipped→delivered
2. 用户认证：logged_out→logging_in→logged_in→expired
3. 任务调度：queued→running→completed/failed
4. AI Agent：thinking→acting→observing→done
5. 游戏AI：idle→patrol→chase→attack→retreat
6. 爬虫：idle→fetching→parsing→storing

agent-execution-engine 中的状态机

Agent 任务执行也是状态机：
queued → planning → executing → verifying → done
                              ↘ failed → retry → executing