failure taxonomy 定稿

日期: 2026-06-25 阶段: Phase 1 - 产品定义×评测×可观测底座 标签: #failure-taxonomy #eval-design #decision-tree #classification

核心问题

Day 8 导出采样、Day 9 开放编码、Day 10 轴向编码——这条「错误分析流水线」的最终产物，是一张可定稿的 failure taxonomy（失败分类法）。本周的全部价值收口在这里：没有定稿的 6 类失败，就无法给每类挂一个 eval（Day 3 的「evals 即成功指标」就落不了地）。

但「6 类」要能用，必须解决两个工程问题：(1) 每类失败的精确定义与判定规则——不能是「大概是幻觉吧」，而要有边界判例，否则归类靠拍脑袋、eval 写不准；(2) taxonomy 怎么反向锚定 eval 设计——每类失败对应哪种 eval（代码型 / judge / 人工抽检）。今天给出 6 类的精确定义、分类决策树、每类→eval 类型的映射，以及与 Day 3 PRD 成功指标的双向校验。

关键内容

A. 6 类失败的精确定义与边界判例

定稿前先借鉴 2026 的权威工作：arXiv 2603.06847 Characterizing Faults in Agentic AI（2026-03）把 agent 故障分三层——fault type（组件级技术缺陷）/ symptom（可观测表现）/ root cause（设计或实现错误），并强调分类必须给边界判例（boundary criteria），如「API Parameter Mismatch（合法参数结构错） vs API Misuse（调了不支持的端点）」。本项目把这套方法落到 AML Copilot，定 6 类（与 Day 3 PRD 指标对应）：

反直觉洞察（边界判例比定义更重要）：新手以为定义写清楚就能归类，但实操中90% 的归类争议发生在边界，不在典型样本。arXiv 2603.06847 的方法论核心不是「列 37 类」，而是给每对易混类写明区分准则（如「Type Handling Error 是容器/返回类型错，Validation Omission 是对结构合法的输入漏做格式检查」）。本项目最难的边界是 hallucination vs typology_misjudge：一条 SAR 既「判错了类型学」又「引用了真实交易」——它是 misjudge 不是 hallucination；反之引用了不存在的交易但类型学判对——是 hallucination 不是 misjudge。没有边界判例，两个标注者（或同一人隔天）会归到不同类，taxonomy 就不可复现（呼应 Day 10 的 kappa）。

B. 分类决策树：让归类可复现

把 A 表的边界判例编成一棵确定性决策树，按「先确定性、后语义」「先输出侧、后判断侧」的顺序裁决，保证同一 trace 总归同一类：

classify(trace) -> FailureType | 'pass':
  # 第 1 层：确定性信号优先（代码可判，零方差）
  if any span has tool error (ToolCallTrace.error != null):
      return 'tool_failure'
  if output violates schema (SAR 缺必填字段 / 非法 JSON):
      return 'format_violation'

  # 第 2 层：证据完整性（可代码校验：引用 ID 是否在 case.transactions 中）
  if SAR cites tx_id NOT in case.transactions:
      return 'hallucination'        # 无中生有 → 幻觉

  # 第 3 层：检索 vs 上下文（看检索日志）
  if relevant typology note NOT in retrieved top-k:
      return 'retrieval_miss'       # 该取没取到
  if relevant note WAS retrieved but answer ignores/contradicts it:
      return 'context_pollution'    # 取到了被淹没

  # 第 4 层：语义判断（需 judge 或人工，最贵放最后）
  if predicted typology != gold label:
      return 'typology_misjudge'

  return 'pass'

反直觉洞察（决策树顺序 = 成本与连锁防护）：决策树不是任意排序。把确定性、廉价的检查（tool error、schema、引用存在性）放前面，语义检查（typology 对错，需 judge/人工）放最后——这既是成本优化（能代码判的不调 judge），也是连锁失败防护：Day 8/9 已立「每 trace 只记 first failure」，而 arXiv 2603.06847 的级联分析证明「单根因引发多症状」（如 LLM timeout → 重试 → 耗尽限流，lift=181.5）。决策树短路返回第一个命中的根因，天然实现「只记 first failure」，避免把一个 tool 超时的连锁后果（输出也乱了、类型学也判错了）数成三个失败。顺序错了（如把 typology_misjudge 放最前），就会把一个由 tool_failure 引发的连锁误判错记为 misjudge，污染频次统计与优先级（Day 10 B 节）。

C. taxonomy 作为 eval 设计锚点：每类→对应 eval 类型

taxonomy 定稿的终极目的是反向锚定 eval。映射原则（Hamel/Shreya + pragmaticengineer 2025）：确定性失败用代码型 eval（pass/fail，零方差、便宜），主观/语义失败用 LLM-as-judge（需先校准），关键评分保留人工抽检。一个 judge prompt 只盯一个失败模式（promptfoo 2025）。

反直觉洞察（4/6 是代码型——judge 不是默认选项）：行业叙事容易让人以为「AI 产品就该用 LLM-as-judge 评 AI」。但本表 6 类里 4 类用代码型 eval（确定性、零方差、零成本），只有 context_pollution 必须用 judge（语义判断无法代码化），typology_misjudge 是代码型+人工抽检。这正是 Day 3 的纪律：凡能确定性断言的（引用存在性、字段完整、工具报错）一律用代码，judge 留给真正需要语义判断的少数。把所有失败都丢给 judge，既贵又引入 judge 自身的方差（还得花成本校准 judge）。taxonomy 定稿的一个隐性收益，就是逼你识别出「其实大部分失败是确定性可查的」。

反直觉洞察（recall@k 的口径陷阱仍在）：retrieval_miss 映射到代码型 recall@k，但本仓库现有 src/agent/eval/retrievalGolden.ts 的 golden query 内嵌了目标 slug（如 query "Raft" → expect 'raft'），文件头已诚实标注这是结构/词法匹配而非语义检索——recall 高在很大程度上是结构性的，只是个回归绊线，不是真检索分数。定稿 retrieval_miss eval 时必须把 golden query 改写成避开 slug 的语义改写（paraphrase），否则这个 eval 给的 recall 是假的高分（Day 3 已记此局限）。这是「满分=口径一致性而非真实能力」的经典案例。

D. 与 PRD 成功指标的双向校验

Day 3 的 PRD 成功指标表与本 taxonomy 必须双向闭合：每条 PRD 指标对应至少一类失败，每类失败对应至少一条 PRD 指标。

反直觉洞察（双向校验暴露 PRD 盲区）：双向映射不是走形式——它暴露了 PRD 的盲区。format_violation 和 retrieval_miss 在 Day 3 的 PRD 里没有显式指标，但错误分析（真实 traces）把它们涌现成了独立失败类。这正是 Day 3「错误分析先于指标、自下而上归纳」的实证：PRD 不是一次写死的，是被真实失败反向修订的。W2 须把这两类补成 PRD 显式指标（format 合规率、语义化 recall@k），闭合循环。

设计要点/决策表

对本项目的落地

• 新建 src/aml/failureTaxonomy.ts（本笔记核心交付）：导出 FAILURE_TYPES 枚举（6 类）+ 每类的 FailureSpec { id, definition, rootCause, boundaryVsId, evalType: 'code'|'judge'|'code+human' }，把 A 表代码化。导出 classifyFailure(trace, case) 实现 B 节决策树——短路返回保证每 trace 一个 first-failure 标签。
• 决策树第 2/3 层复用现成确定性信号：hallucination 检查 SarDraft.citedTxIds ⊆ case.transactions.map(t=>t.id)（src/aml/types.ts 已有 citedTxIds 字段，sarDraft.ts 已生成）；typology_misjudge 复用 src/aml/typology.ts 的 assessCase(case).topTypology 对 case.label——决策树的语义层直接吃规则引擎输出，无需额外模型。
• eval suite 锚定：failureTaxonomy.ts 的 evalType 字段直接驱动 Day 3 规划的三类 evals suite v2——evalType==='code' 的 4 类接入 src/aml/evalBaseline.ts 风格的确定性评测（已有 evalRuleBaseline 算 recall/FPR，扩展为按 taxonomy 分类报告）；'judge' 类（context_pollution）走四段式 judge prompt + 一致率校验；'code+human' 类（typology_misjudge）代码评 + 人工抽检队列。
• CI gate 按类阻断：GitHub Actions 跑 failureTaxonomy 驱动的 suite，hallucination 引用溯源率 <100%、typology_misjudge recall < 门槛即阻断 merge（升级现有 src/aml/__tests__/aml.test.ts 已进 CI 的规则基线为按 taxonomy 分类的 gate）。
• 修复优先级落地：failureTaxonomy.ts 复用 Day 10 axialCoding.ts 的 prioritize()——hallucination/typology_misjudge（critical 严重度）排修复队列头部，即便 context_pollution 频次更高也排其后（Day 10 B 节）。
• 回填 PRD：W2 把 format_violation/retrieval_miss 补成 docs/AML_COPILOT_PRD.md 的显式指标（D 节双向闭合）；retrievalGolden.ts 的 golden query 改写为语义 paraphrase（去 slug），消除假高 recall。
• 诚实标注：6 类的频次为 Day 8 真实 traces 跑完后回填（当前为 Day 10 示意值）；context_pollution 的 judge 在一致率达 0.8 前不进 CI，标注「judge 未校准，仅离线参考」。

参考资料

1. Characterizing Faults in Agentic AI: A Taxonomy of Types, Symptoms, and Root Causes — fault type/symptom/root-cause 三层、边界判例方法论、级联传播（单根因多症状，lift 关联），arXiv 2603.06847 (2026-03)
2. Where LLM Agents Fail and How They Can Learn From Failures — AgentErrorTaxonomy 五模块（memory/reflection/planning/action/system），hallucination 与 memory retrieval failure 定义，arXiv 2509.25370 (2025-09)
3. Hamel Husain — LLM Evals FAQ（轴向编码→failure taxonomy；taxonomy 锚定 eval 设计）hamel.dev evals-faq (2025-09，FAQ 版 2026-01)
4. The Pragmatic Engineer — A pragmatic guide to LLM evals for devs（代码型 eval 查确定性、judge 查主观、两层分工）(2025)
5. Promptfoo — LLM as a Judge Evaluation Guide（一个 judge prompt 只盯一个失败模式）(2025)
6. Amplitude — What Is a Code-Based Eval?（regex/schema/expected-tool-call 等确定性断言，pass/fail）(2025)

SOTA 检查 (2026-06-11)

• agent failure taxonomy 是 2025-2026 的活跃前沿：arXiv 2603.06847（2026-03）与 2509.25370（2025-09）均为近 9 个月内工作，三层（type/symptom/root-cause）+ 边界判例 + 级联分析是当前 SOTA 方法论；本项目 6 类是其在 AML 垂直域的裁剪，方向与之一致。
• 「确定性失败用代码、语义失败用 judge」映射仍是事实标准：Hamel/pragmaticengineer/promptfoo 2025 口径一致，本日 WebSearch 未见替代；judge 须先校准（一致率达标才进 CI）是被 2026-01「LLM 模拟用户不可靠」研究加强的纪律（Day 3）。
• 方法论 vs 实证等级：A/B/C 节的 taxonomy 与决策树是框架性方法论；级联传播（单根因多症状）有 arXiv 实证支撑——引用时区分（延续 Day 3/9/10 纪律）。
• 过时警示：「所有失败都丢给 LLM-as-judge」是 2024 式做法，本笔记 C 节用 4/6 代码型纠正；「recall@k 高就代表检索好」忽略 golden 内嵌 slug 的口径陷阱，C 节明确须语义化改写。
• 待跟踪：6 类频次须用 Day 8 真实 traces 回填；context_pollution judge 一致率校准结果；W2 是否把 format/retrieval 补回 PRD 完成双向闭合；arXiv 2603.06847 的 37 类细粒度是否需进一步裁剪进本项目。