上线前对照清单

Agent 工具调用失败后的回滚与补偿对照清单

10 项可逐条核验的检查：幂等键构成与检查层、明确成功/未知态/明确失败三态处置、补偿动作设计、重试上限与人工接管点。用于判断写操作出错后系统能否恢复。

← 对照清单

Agent 的写操作（建单、改状态、扣费、发消息）一旦出错，问题就从「模型答得对不对」变成「系统能不能恢复」。真正的分界线不是会不会失败——下游超时、框架重试、部分成功在生产里一定会发生——而是失败之后系统处于什么状态、谁来接管、怎么补偿。

下面的清单按「有 / 部分 / 没有」逐条自查。每项都给出缺失时的生产后果、可执行的验证方法和补齐的第一步。严重度是通常情形下的判断，实际定级要结合系统与业务场景。

1.所有会产生副作用的工具都要求幂等键，并在副作用发生前检查

缺失时通常为 P0 · rubric 5.1

缺失时的生产后果: 没有幂等检查时，一次网络超时加一次框架重试，就是两张工单、两次扣费或两条发给客户的消息。这类重复副作用常常要到对账或客户投诉时才被发现。
怎么验证: 用同一幂等键把同一动作重放两次，确认目标系统只产生一条记录；检查逻辑在服务端副作用之前生效，而不是只在客户端。
补齐第一步: 从风险最高的写工具开始，把幂等键设为必填参数并在服务端校验。

2.幂等键有确定性的构成规则（业务对象 + 操作 + 去重窗口），重试时保持不变

缺失时通常为 P1 · rubric 5.1

缺失时的生产后果: 每次调用都随机生成的「幂等键」形同虚设：重试时键变了，去重永远命不中。幂等键必须由业务语义派生，同一逻辑操作重试多少次都是同一个键。
怎么验证: 审查幂等键的生成代码：由任务、目标对象和操作类型派生；人为触发一次重试，确认前后两次请求携带同一个键。
补齐第一步: 把幂等键从随机值改为由业务对象和操作派生的确定性构成。

3.任何一步被重试都不会重复执行副作用

缺失时通常为 P0 · rubric 5.2

缺失时的生产后果: 重试是框架的默认行为，副作用去重却不是。在「执行成功但回执丢失」的场景里，缺少这层保护的系统会把同一动作做两遍。
怎么验证: 在工具执行完成后、回执返回前人为断开一次连接，让框架重试；检查是否出现两条副作用记录。
补齐第一步: 对每个写工具补一个「执行前查重」步骤，以幂等键查询既有结果。

4.工具结果区分明确成功、明确失败和未知态三种，未知态先查证再处置

缺失时通常为 P0 · rubric 5.6

缺失时的生产后果: 超时不等于失败。把未知态当失败直接重试，是重复扣费和重复消息的常见来源；把未知态当成功跳过，则会无声地丢掉动作。
怎么验证: 列出每个写工具在超时后的处置路径：先按幂等键或业务查询确认实际结果，再决定重试、补偿或转人工，而不是直接重发。
补齐第一步: 给工具返回定义三态枚举，先覆盖资金类和对外消息类动作。

5.每个不可逆或对外可见的动作都有对应的补偿动作，或被明确标记为不可补偿

缺失时通常为 P1 · rubric 5.5

缺失时的生产后果: 补偿方案如果等到出错才现想，通常已经是客户收到错误消息的时刻。能不能撤回、怎么冲正、如何发更正消息，应当在工具设计时写好。
怎么验证: 对照写工具清单逐项检查：能说出补偿动作（撤销、冲正、更正通知），或标记为不可补偿并因此前置人工审批。
补齐第一步: 给写工具清单加一列「补偿方式」，补不出来的先降级为人工确认。

6.重试有上限和退避策略，到达上限后进入定义好的终态而不是静默丢弃

缺失时通常为 P1

缺失时的生产后果: 对持续故障的下游做无上限重试，会把故障放大成队列堵塞；到达上限后静默放弃，则等于把任务无声地丢掉。两种结局都比失败本身更难排查。
怎么验证: 检查配置里的最大重试次数与退避参数；构造一个持续失败的下游，确认任务最终进入死信或人工处理队列，并触发告警。
补齐第一步: 给所有写操作统一设置重试上限、退避策略和死信队列。

7.多步操作中途失败后，系统处于定义好的状态，能列出已完成与待补偿的步骤

缺失时通常为 P1 · rubric 5.6

缺失时的生产后果: 一个任务往往由查询、建单、通知多步组成。中途失败时如果没有步骤台账，人工接管只能靠翻日志猜进行到哪一步，补偿容易补错方向。
怎么验证: 在多步任务的中间一步人为注入失败，检查系统能否给出已完成步骤、未执行步骤和建议补偿动作的清单。
补齐第一步: 给多步写操作加一份执行台账，每步落一条状态记录。

8.高风险失败有明确的人工接管点，接管时上下文完整

缺失时通常为 P1 · rubric 5.3

缺失时的生产后果: 转人工时若只有一句「任务失败」，接管者要重新拼上下文，而高风险场景的损失恰恰在这段时间继续扩大。
怎么验证: 触发一次高风险失败，检查告警内容：run_id、已执行动作、受影响对象、建议处置是否齐全，值班人能否据此直接操作。
补齐第一步: 在失败告警里附上 trace 链接和受影响对象清单。

9.失败与回滚路径真实演练过，有演练记录

缺失时通常为 P1

缺失时的生产后果: 没跑过的回滚脚本，在真实事故里常见的结局是权限不够、字段对不上、依赖服务不在。补偿逻辑的第一次执行不应该发生在事故当晚。
怎么验证: 查看最近一次失败演练的记录：时间、注入的故障场景、回滚是否成功、发现了哪些问题。演练频率通常按季度起步，视变更频率而定。
补齐第一步: 挑风险最高的一个写工具，先做一次桌面推演，再在受控环境里真跑一遍。

10.发给客户或外部系统的消息有延迟发送或撤回窗口

缺失时通常为 P2

缺失时的生产后果: 消息一旦到达客户就无法真正回滚，撤回窗口是这类动作仅有的补偿手段之一。没有它，任何上游判断失误都会直接变成客户可见的错误。
怎么验证: 检查对外消息是否先进入待发队列并有可配置的延迟；执行一次撤回操作，确认消息确实没有发出。
补齐第一步: 给客户触达类工具加一个短延迟队列，并提供撤回入口。

先看全部支柱

这份清单只覆盖一个专题。站上的免费上线前检查按场景分流后覆盖全部支柱——数据可信与接地、工具调用、评测回归、可观测审计、安全动作与幂等、成本路由——先定位薄弱支柱，再回来逐项对照。

运行免费上线前自检

自查与付费审查的边界

清单和自检都是自报对照：结论基于你自己的判断，不做证据核验。生产就绪审查与路线图会进入系统本身——逐项核验证据、按支柱加权评分、给出 P0/P1/P2 判级和修复路线图。适合准备放权写操作、或需要一个可辩护结论的团队。

邮件 hello@ideapop.cn，附上自查结果和最不放心的一两项即可。