失败分析与治理

🩺 失败分析与治理

定位:把「模型不行 / 遵循不好」这种笼统结论,拆成可观察、可归因、可复现、可治理的问题。核心判断——Agent/Skill 失败通常不是单一模型能力问题,而是 任务定义 + Skill 触发 + 上下文 + 工具说明 + CLI 协议 + 参数 + 运行目录 + 环境 + 错误反馈 + 验证闭环 共同作用。

📎 来源:Agent Skill 失败分析与治理指南。设计侧见设计指南/Skill设计 · 设计指南/CLI设计/CLI设计规范;度量侧见评测与改进/评测。

一、不要简单说「模型不行」

一次 Agent 失败 = 任务意图识别 + Skill 触发 + 上下文可用性 + 工具选择
               + 参数构造 + 执行环境 + 错误理解 + 验证闭环 + 恢复策略

分析时不能只看最后答对没,要看全过程:它为什么这么做?当时能看到什么?调了什么、传了什么参数?工具返回了什么?有没有理解错误、有没有验证、有没有重复犯同一类错?

二、8 层排查框架

把问题拆到 8 层,逐层定位:

层	关注	典型问题	治理
L1 任务理解	是否理解用户真正要做什么	”控制价审核”误解成”成本控制审核”;要”先别写代码”却直接建文件	高歧义任务先输出「任务复述 + 不做什么」;建术语 glossary
L2 Skill 触发	是否选对 Skill	该用 `bw-web-extractor` 却直接 web_fetch	description 写清触发条件;正文写「何时用/何时不用」;前置规则
L3 上下文	是否拥有足够、正确、不过载的上下文	关键路径被压缩丢失;文档太长只读一半;沿用旧目标	长任务建状态文件;每次纠正后写「当前真实目标」;渐进披露
L4 工具选择	是否选对、是否死守错误工具	该用 CLI 却用浏览器;失败后不换策略	每类任务定默认工具链;失败两次必须换路径;弱结果二次验证
L5 参数与协议	目录/参数/路径/JSON/stdout 是否正确	cwd 错、`--output`/`-o` 混用、bool 漏 `--yes`、JSON 转义错	CLI 标准:stdout 纯 JSON、stderr 日志、`--output json`/`--cwd`/`--schema`/`--doctor`
L6 执行环境	失败是否来自环境而非模型	CLI 没装、PATH 命中错版本、依赖缺失、权限/token	先 `doctor` 再跑;环境错归类 environment,不算模型不遵循
L7 错误恢复	失败后是否有效恢复	重复同一错误命令、不读报错、改无关参数继续试	读错误→分类→判可否自修→换策略→重跑→验证→记录
L8 结果验证	是否真完成 vs「看起来完成」	路径写错却说已保存、图片生成没发送、API 200 但业务失败	每类任务定验收证据;没有 evidence 不能说 done

L5 是最常见的一层——不是模型「不会遵循」,而是协议设计不稳。

三、判断:是不是「模型遵循问题」?(决策树)

不要先下结论,按顺序问:

1. Skill/工具说明清楚吗?        否 → 先改 Skill/CLI 文档
2. 参数 schema 稳定可解析吗?     否 → 先改 CLI
3. 模型能看到必要上下文吗?       否 → 先改上下文管理
4. 工具错误给了可操作 hint 吗?   否 → 先改错误输出
5. 同上下文/工具/参数,多模型都失败? 是 → 多半是流程/工具问题
6. 只有某模型在清晰指令下反复忽略硬约束? 才更可能是模型遵循问题

真正的模型遵循问题长这样:明确说”不要执行”它仍执行;要求先确认它跳过;要求用某工具它无理由不用;要求 JSON 它反复自然语言;要求不编造它仍编造。但很多团队遇到的其实是「描述不清 + CLI 不稳 + 错误不可读 + 没有验证闭环」。

四、错误分类 taxonomy(把失败打标签)

类别	是否模型问题
INTENT_ERROR 任务理解错	可能
SKILL_TRIGGER_ERROR 未/误触发	多是 Skill 描述问题
CONTEXT_ERROR 上下文缺失/过载/过期	不一定
TOOL_SELECTION_ERROR 工具选错	可能
CWD_ERROR 执行目录错	多是流程/CLI 问题
ARGUMENT_ERROR 参数错	多是 CLI schema 问题
ENV_ERROR / API_ERROR 环境/外部	不是模型问题
OUTPUT_PARSE_ERROR 输出不可解析	多是协议问题
RECOVERY_ERROR 恢复不当	可能
VERIFICATION_ERROR 假完成	流程问题
SAFETY_ERROR 高风险未确认	Skill/流程问题

二级分类要带 root_cause / owner / model_fault 字段,便于统计归因。

五、Trace 怎么读(4 步)

看用户真实目标:要什么/不要什么/最新纠正/交付物/成功标准。
看 Skill 是否正确触发:有没有读对 SKILL.md、有没有绕过规定工具。
看工具调用路径:画工具链,缺了 lint/render/file check/send 就容易假完成。
看每次错误的因果:错在哪步→返回什么→是否理解→是否换策略→是否最终验证。

六、关键指标体系

维度	指标
任务级	task_success_rate · first_pass_success_rate · user_correction_rate · false_done_rate · turns/time
工具调用	tool_call_count · failed/repeated_failed · wrong_tool_rate · parameter_error_rate · cwd_error_rate · verification_call_rate
上下文	context_token_usage(>70% 风险) · relevant_context_ratio · stale_instruction_count · latest_constraint_followed
恢复	recovery_success_rate · same_error_repeat_rate · escalation_rate

指标怎么从会话 JSONL 客观提取,见评测与改进/评测。

七、治理优先级(不要一上来换模型)

1 修正任务边界和术语   2 改 Skill 触发描述   3 缩短 SKILL.md,细节迁 references
4 补 CLI doctor/schema/examples   5 规范 stdout/stderr/exit code
6 加 dry-run/verify/readback   7 建 trace 复盘与错误 taxonomy
8 做模型 A/B 测试   9 最后才判断模型遵循能力差异

为什么最后才换模型?Skill 和 CLI 本身不稳时,换更强模型只是让它「更聪明地绕坑」,系统质量没提升。

八、评估国内 vs 国外模型的正确姿势

不要说「国内模型不行」。设计同一套 benchmark(同任务/同上下文/同工具/同评分),按 taxonomy 打标签,出结论应是:

“30 个任务,A 成功率 73%、B 61%;差异主要在参数构造(A 12% / B 28%)、长上下文最新约束遗漏(A 8% / B 19%)、恢复成功率(A 70% / B 45%);但两者 Skill 触发准确率接近,说明 description 本身有效。“

复盘模板(每次失败后填)

任务背景(原始需求/最新纠正/预期 vs 实际) → 失败摘要(哪步/影响/副作用) → Trace 时间线 → 错误分类(一级/二级/是否模型问题/证据) → 根因(逐层) → 指标记录 → 修复措施(Skill/CLI/错误提示/测试/上下文) → 回归验证。

一句话

不要把系统工程问题甩给模型。先把每次失败拆成可观察事实,再判断到底是模型遵循、上下文、Skill 设计、CLI 协议,还是环境权限问题。

参考与延伸

一开始怎么设计才不翻车 → 设计指南/Skill设计 · 设计指南/CLI设计/CLI设计规范
真实治理现场(4 方评测把病根逐个消除)→ 实践分享/控制价审核CLI化实战