🏠 总目录📚 本教程 12b · 审批与故障恢复 ← →

智能体工程 · 12b

动作可能已执行,但响应丢了,该重试吗?

读完能做的判断:先用稳定操作号对账,再按当前授权决定重试或补偿,保留不可逆边界。

📑 本页目录(点开跳转)

12b · 人批了、进程断了:动作到底做没做

⏱ 阅读参考约 13 分钟 · 动手实践另计;可分段完成

🎯 一句话

超时代表结果未知,不能直接等同于执行失败。 创建工单、退款、发消息这样的动作,恢复前先确认外部状态。

🔗 先读Harness。本章用 workflow.py 把草稿、独立审批、执行与对账组织成可检查的状态机,并用 test_core.py 说明提交前后故障注入。任务设计见17b;以下命令展示实验组织,完整工程不随教程分发。

🔬 先跑一次“工单已创建,但响应丢了”

python examples/knowledge-assistant/lab.py demo
python -m unittest discover -s examples/knowledge-assistant -p test_core.py -v

观察 demo 的恢复结果与工单数量。它先写入模拟外部系统,再故意抛出响应丢失异常;重试按同一业务操作号查询已有工单,最终只有一张。模拟外部系统是一张使用独立事务的表,方便复现“业务副作用与本地确认不能原子提交”的间隙;它不等于已联调真实工单 SaaS。

一、审批绑定的是哪一个动作

待审批草稿身份、内容指纹已审批操作者、到期时间执行中稳定操作号已完成取消 / 审批过期不得发起新的业务动作响应未知:按操作号对账已有结果则确认,未执行才判断重试先查,不盲重发
看右下角的恢复分支:未知状态先查询已有结果;审批过期会阻止新动作,但不应阻止查清已完成的动作。
审批记录 为什么绑定
tenant、请求人、业务对象 防止另一用户拿着 run_id 执行
动作类型与规范化参数指纹 防止批准 50 元后改成 5000 元
审批人身份与 scope 模型不能自己返回一个 approved 就获权
到期时间、状态 旧审批不能无限期重复使用
稳定业务操作号 网络重试仍代表同一笔业务动作

金额用整数分表示,拒绝 bool、NaN、无穷大及非法范围。订单归属、已支付金额、已退款余额从业务库读取,不能相信模型参数。这个原则同样适用于草稿工单的归属与内容。

二、幂等不是一个 try/except

本地先持久化执行意图,调用方使用稳定操作号;模拟下游以唯一约束保证同操作只创建一条记录。相同操作号与相同内容可以回放,不同内容必须冲突。测试同时发起 12 次相同执行,检查只有一张工单。

下游能力 恢复策略 不能声称的保证
支持幂等键与结果查询 同键重发或先查询 幂等键超过保存期后仍永远去重
只支持业务号查询 先查,未知转对账或人工 查询暂未可见就一定没执行
既不支持幂等也无法查询 限制自动重试,人工核对 仅靠本地锁就能端到端 exactly-once

跨系统无法用本地 SQLite 事务包住真实网络副作用。生产可用 outbox 可靠投递意图,用 inbox/下游唯一键去重,再靠状态查询收敛;这仍要求明确下游语义。网络断开、进程退出和超时都是“未知”的来源。

可跳过:响应丢了,先对账还是补偿?

先写清一笔动作的合同。用退款意图R-17作例子:订单O-8、币种CNY、金额3000分、预期成功业务次数1。持久保存稳定操作号、参数指纹、当前状态及审批依据;同号换金额必须冲突。调用次数可以大于1,成功业务次数仍应为1,不能混为一谈。

下游已执行、本地还没记结果就崩溃,恢复后先用原操作号查询可信结果。按同一业务范围与核对截止点,比业务号、最终/处理中状态、币种金额、去重后的成功业务记录数;分页账单要读全该范围。总金额相同也可能是一笔重复、一笔缺失,不能只比合计。

每日自动对账,只在外面加一层批次合同。用渠道+业务日/时区+截止范围生成稳定批次号,冻结预期范围;渠道账单可用时刻、分页完整性与水位按真实渠道规则核对。逐业务号保存原有核对结果、差异与证据;漏页、查询失败或账单未齐,整批保持 pending 并可恢复,不能把“未查到”当最终未执行。

固定例只看同币种:内部应有 A、B 各 100 分,渠道却有 A 的两笔不同成功凭据、缺 B,总额同为 200 分仍须报 A 重复、B 缺失候选;同一凭据的重复回传先去重。教学例按 UTC+8 的业务日半开区间[00:00,次日 00:00)归属,23:59 的记录次日才可见,仍归原日并另建关联补批,不混入次日正常批;这不是任何渠道的结算时刻承诺。

同一批次重跑只更新对账事实、差异与查询进度,不创建退款;补偿或其他修复另按当前授权执行。自动日批的持久认领、失败恢复复用 已有任务调度合同,不在这里接入真实支付渠道。

对账与补偿是两个决定。已成功的副作用不能因为本地报错就自动撤销。先确定事实,再按业务规则选择接受结果、继续流程或请求补偿;查询已有动作不等于获准执行新动作。

执行前区分三类:同一本地事务中尚未提交的草稿写入可以回滚;已提交的外部预订若合同允许取消,可以发起补偿;已发送邮件或已被下载的内容无法靠本地ROLLBACK收回。撤销访问权也不能取回对方已保存的副本。不可逆动作要把校验与必要审批放在发生之前。

补偿本身是新动作。例如取消预订C-17关联原操作R-17,持久保存补偿意图、稳定补偿号、目标版本、状态与结果,再按下游合同执行。恢复时先查询C-17;可安全重试才用同号重试,失败保留待处理状态、原因和告警,不能删掉原成功记录伪装“没发生”。

补偿未必恢复原状,可能有费用或并发变更。它必须满足自己的当前权限与审批规则;原动作审批不能自动批准任意退款、改金额或更换对象。参数/业务意图变化时重新校验并取得相应审批,不能复用旧指纹。

失败也要留痕:关联run_id、原操作号与补偿号,记录请求/审批主体、参数及审批指纹、状态前后、尝试时间/次数、下游凭据与查询结果、错误类型和人工决定。审计保留未知与失败历史,不用覆盖一行“成功”抹掉过程;凭证正文与密钥不入日志。

这是状态、金额、次数与恢复路径的教学对照,没有接入支付平台或执行真实补偿。依据:AWS 幂等API与迟到请求、Compensating Transaction。

三、故障注入怎样算验收

注入点 必须观察的结果 本项目状态
未批准直接执行 拒绝,工单数为零 已有自动测试
模型冒充审批者 缺审批 scope,拒绝 已有自动测试
审批后修改参数 指纹不符,拒绝 已有自动测试
批准过期且未执行 不再创建工单 已有自动测试
写执行意图后、调用前失败 可用原操作号恢复 已有自动测试
下游创建后响应丢失 查出已有工单,无重复 已有自动测试
响应丢失后审批过期 可对账已有结果,不能发起新动作 已有自动测试
执行前用户取消 后续调用拒绝 已有自动测试
执行中用户取消 返回需对账,不能承诺撤销 代码返回明确状态;真实下游补撤销协议

网络错误只对允许重试的动作采用退避与抖动,遵守 Retry-After 和总预算。权限错误、参数错误、审批失效不应自动重试。对长任务增加租约、心跳和所有权 fencing,避免旧 worker 恢复后与新 worker 同时写;当前单机示例未实现分布式调度。

四、恢复状态不等于恢复授权

恢复时重新读取可信用户身份和业务权限。历史 checkpoint 里保存过角色或 token,不意味着它现在仍有效。不要把原始 bearer token 写入持久化状态;必要凭证从秘密管理系统重新获取,日志只记安全的凭证标识。

审计最少记录 run_id、操作号、状态前后、请求人、审批人、内容指纹、时间、错误类型和下游对象号。记录事实,不记录模型“我已经完成”的自述。按数据保留规则清理正文;删除业务内容与保留必要审计要分别设计。

用故障注入核对业务动作实际发生的次数,再接框架的恢复 API。

恢复文件之后,再核对状态

12c · 备份恢复与状态核对 用 SQLite 在线备份保存已提交状态,再恢复到全新隔离副本。检查旧凭证、权限和审批是否与当前状态冲突;副本能打开或快照相同,都不是重新对外服务的许可。

✅ 检查点

  1. 超时后为什么不能换一个操作号直接重试?
  2. 为什么 checkpoint 中有 approved=true 仍不能执行?
  3. 审批已经过期,是否应该拒绝查询丢失的执行结果?
展开答案
  1. 下游可能已经成功;新号会被视为另一笔动作,产生重复副作用。
  2. 还需要当前身份、资源权限、动作指纹和有效的服务端审批记录。
  3. 不应拒绝对账已有动作;但未发生的动作必须重新满足审批条件。
⚡ 走神救援

审批绑定内容与身份;操作号跨重试保持稳定;未知先对账;checkpoint 不能代替当前授权。

🔗 接下来去哪

➡️ 下一站:12c · 备份恢复与状态核对。

打卡记录保存在你的浏览器里,首页能看到总进度