Python 多轮对话状态机的 FSM 设计

fsm状态流转必须显式定义transition，不能靠函数名自动推导；事件需归一化为预设名称；conditions须轻量同步；state应存字符串而非对象引用；fsm仅是迁移骨架，业务逻辑须外包。

FSM 状态流转必须显式定义 transition，不能靠函数名自动推导

很多人写完 state_A 和 state_B 就以为调用时能自动跳转，结果发现状态卡死——transitions 库或手写 FSM 都不会从函数名猜逻辑。状态迁移必须在初始化时明确定义触发条件、源状态、目标状态和可选回调。

• machine.add_transition('next', 'A', 'B', after='on_enter_B') 是标准写法；漏掉 'next' 这个触发事件名，后续调用 machine.next() 就会报 AttributeError: 'FSM' Object has no attribute 'next'
• 如果用 transitions，prepare 回调里抛异常会阻止迁移，但不会回滚已执行的 before；这点容易误以为“事务安全”
• 手写简单 FSM 时，常见错误是把状态判断写在方法里（如 if self.state == 'A': self.state = 'B'），这绕过了统一迁移校验，后期加日志/权限/审计就只能重写

多轮对话中，Event 输入要先归一化再进 FSM

用户说“再问一遍”“不对，我要查订单”“算了”，这些文本语义差异大，但直接喂给 FSM 会触发错误迁移。FSM 本身不理解 NLU，它只认结构化事件。

• 必须在调用 machine.trigger() 前完成意图识别：把原始文本映射成预设的 event 名，比如 'confirm'、'cancel'、'retry'
• 别把 NLU 模型输出直接当 event 名用——模型返回 'intent_order_status' 这种长名，FSM 的 add_transition 里写不下，也难维护
• 归一化层要处理空输入、超时、乱码等边界情况，默认发 'timeout' 或 'invalid_input' 事件，让 FSM 走兜底流程，而不是崩在 trigger() 抛出的 MachineError

transitions 的 conditions 别写耗时逻辑

FSM 迁移路径上加条件判断很常见，但把数据库查询、http 调用塞进 conditions=[Lambda: db.get_user_level() > 2]，会导致整个对话阻塞，且无法异步等待。

• conditions 函数必须同步、轻量、无副作用；复杂校验（如权限、库存、风控）应在触发前完成，并把结果存入 machine.model 或上下文字典
• 例如：先查好用户等级，设 machine.model.user_tier = 'gold'，再写 conditions=['is_gold_tier']，对应方法 def is_gold_tier(self): return self.user_tier == 'gold'
• 用 asyncio 写异步 FSM 很麻烦——transitions 不原生支持 await，强行套 async def 会导致 MachineError: Condition function must be synchronous

状态持久化时，state 字段别直接存对象引用

对话中断后恢复，需要把当前状态写库。但如果 machine.state 是字符串（如 'awaiting_payment'）就安全；一旦你把自定义类实例赋给 machine.state，序列化时要么报 TypeError: Object of type XXX is not json serializable，要么存一堆内存地址。

立即学习“Python免费学习笔记（深入）”；

• FSM 实例本身不要落库，只存 state 字符串 + 关键上下文字段（如 order_id、last_intent）
• 恢复时用 machine.set_state(saved_state)，而不是重新初始化整个 machine——否则会丢失动态添加的状态或回调
• 如果用了 transitions.extensions 的 GraphMachine，生成图谱时会尝试深拷贝所有属性，未标记 __slots__ 的类可能引发循环引用错误

事情说清了就结束。最常被忽略的是：FSM 不是对话逻辑的容器，它只是状态迁移的骨架；真正的业务规则、数据加载、异常分支，都得在外面包一层，而且那层必须比 FSM 更早启动、更晚销毁。