Agent任务失败怎么排查：四层诊断树从症状定位到修复

Agent 任务失败的排查顺序是：先还原失败发生在哪一步，再按四层诊断树逐层验证——任务定义层、上下文与工具层、执行与权限层、结果验收层。不要上来就重跑或换 Agent，逐层做最小验证，确认修复信号后再继续。

排查前提：先还原现场

修复前先收集三样信息：Agent 最后的输出（它说自己卡在哪）、执行日志（它调用了什么、每一步的返回）、实际改动（它写了什么文件、发了什么消息、改了哪些数据）。这三样用一张三列表记录：现象、最后一步动作、改动痕迹。涉及写文件、发送消息、删除数据时，先停止后续执行再做检查，避免错误扩散；重跑前尤其要先确认现场未被覆盖，因为重新执行可能抹掉失败痕迹。只读检查永远优先于任何修改动作。

第一层：任务定义层

症状：Agent 做了别的事、输出跑偏，或者反复询问同一个问题。可能原因：任务描述缺少目标、验收标准和边界。最小验证：让 Agent 先复述它理解的任务，对照你的原始要求。修复：改写任务说明，补上具体目标、成功标准、禁止事项。例如把「写一篇关于新品的内容」改成「为新品写 800 字公众号介绍，读者是中小商家，结论必须来自产品参数页，不得编造价格」。成功信号：复述与你的意图一致，且第一步动作正确。

第二层：上下文与工具层

症状：Agent 报告找不到 Skill、文件、账号或数据，或者绕开工具用编造内容代替。可能原因：Skill 未挂载、路径错误、账号未授权、数据源不可用。最小验证：让它做一次只读探测——列出可用的 Skill、读取目标文件、查询数据源的一条记录。修复：补挂 Skill、修正路径、完成授权；数据源缺失时先补数据，而不是让 Agent 硬编。成功信号：只读探测返回真实结果，而不是报错或空话。

第三层：执行与权限层

症状：半路报错、外部写入失败、部分步骤成功部分失败。可能原因：权限范围不足、接口限流、编码或格式问题、并发冲突。最小验证：把任务拆成最小单步，重放失败的那一步，观察报错信息。修复：按最小权限原则补充必要权限；限流就加间隔或设置重试次数上限；编码问题改用 UTF-8 文件传递而不是命令行参数。成功信号：单步重放成功，且改动范围符合预期。

第四层：结果验收层

症状：任务显示成功，但结果不对——文章缺字段、表格缺行、发布到了错误分类。可能原因：没有验收标准，或验收只核对「过程完成」而不是「结果正确」。最小验证：把实际结果与验收标准逐条对照，找到第一处不满足点。修复：把验收标准写进任务本身，例如「发布后回读标题、分类、状态，任何一项不符即报告失败」，有条件就加自动校验脚本。成功信号：校验通过，或 Agent 主动报告了不通过项。

涉及发布、删除、花钱时的处理

这三类操作出错不可逆或代价高，规则只有一条：执行前设人工确认点，失败时优先恢复而不是追查。发布错误先用撤回或改状态恢复；删除先看有没有回收站或备份；涉及付费操作先核对账单与配额。拿不准时停下来问维护者，比继续自动重试安全。

五条预防清单

• 输入最小化：一次只交代一个目标，长任务拆阶段执行。
• 验收前置：任务里写清楚怎样算合格，验收标准可机械核对。
• 中间检查点：长链路任务分步执行、分步确认，不要一路跑到黑。
• 只读优先：探测用只读操作，写入留到最后一步。
• 失败留痕：每次失败记录症状、验证、修复，形成自己的排错库。

排查时优先按「症状最常见、验证成本最低」的顺序走：任务定义层通常先查，因为它的修复只需要改写文字；其次是上下文与工具层，因为只读探测不产生副作用；权限层和验收层放在后面，因为它们的验证往往涉及真实执行。每一层验证通过后再进入下一层，不要在没定位的情况下同时改动多个变量。

多数 Agent 任务失败不需要换工具，而是任务定义或上下文不完整。按四层诊断树走完一轮，通常能定位到具体的可修改项；定位不到时，再考虑向 Skill 或 Agent 的维护者提问。