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__的类可能引发循环引用错误
