主题: 应用篇 8. 争议变更的文件仲裁：角色、裁决与先例
难度等级: 中级
预计学习时间: 2-3 小时
前置要求: 了解团队评审原则（第一卷第 16 部分）
理解 LLM 决斗机制和反例处理方法
具备基本的 CLI 使用技能（运行 Python 脚本）
理解 YAML 和 JSON 数据结构
学习目标: 理解 LLM 决斗与文件仲裁之间的区别（查找缺陷 vs. 做出正式裁决）。
配置并运行一个使用 run_duel.py、check_invariants.py 和 write_judgment.py 脚本的最小教学仲裁场景。
使用严格的证据（evidence_ref）在 judgment.md 中创建正确的记录。
在 precedents.md 中创建记录，以文档化重复出现的争议情况。
应用 anti-Goodhart 规则来保护系统免受以隐藏风险（静默故障、回滚抖动）为代价优化指标的影响。
概述: 文件仲裁将代码变更争议的解决从聊天中主观的意见交流转变为正式化、可复现的证据链。在该系统中，角色分工明确：协调员管理流程，实施者提出变更，验证者根据形式标准进行审查，而 Safety 在关键风险出现时行使否决权。仲裁的产出物是项目工件：judgment.md（带证据的决策日志）和 precedents.md（重复争议的知识库）。该方法经过精心设计，使裁决不依赖于特定的 AI 模型（通过层级轮换进行验证），而规范始终是真理的主要来源。
关键概念: 文件仲裁：由多个角色对争议变更进行的集体审查，其结果以文件（工件）形式记录，而非聊天历史。
仲裁角色：协调员（主持会议但不投票）、实施者（提出变更）、验证者（检查形式标准）、Safety（通过否决阻止关键风险）。
Judgment.md：争议决策日志。必须包含裁决（APPROVE/DENY/DEFERRED）、原因以及 evidence_ref——来自文件的证据，而非聊天中的转述。
Precedents.md：用于重复争议的先例日志。包含稳定标识符、裁决、证据、适用边界以及重新审议的条件（next_check）。
证据引用（Evidence ref）：对证据的严格引用（钩子日志、diff 差异、JSON Schema、Given/When/Then 场景）。验证者不接受没有 evidence_ref 的论点。
层级轮换（tier rotation）：在不同代理对（例如廉价的本地模型 + 昂贵的云端模型）上测试同一规范。揭示裁决对特定 AI 的依赖性。
Anti-Goodhart 不变量：仲裁的保护机制，禁止以其他指标的退化（false_escalation_rate 上升、回滚抖动、silent_p0）为代价来改善单一指标（例如 MTTR）。
决策追踪（Decision trace）：可复现的分阶段决策协议，描述提取的事实、红色标记检查、应用的政策以及最终裁决。
练习题: 名称: 运行教学可执行案例 autoscale_200pct
问题: 需要对 autoscale_spec.yaml 规范进行文件仲裁。要求运行决斗、检查 anti-Goodhart 不变量并生成最终的决策日志。
解决方案: 1. 切换到示例目录：cd book2/examples/tribunal。2. 运行决斗脚本：python3 scripts/run_duel.py --spec specs/autoscale_spec.yaml --cases cases/ --out out/duel.json。3. 运行不变量检查：python3 scripts/check_invariants.py --metrics metrics/validation_metrics.json --out out/invariants.json。4. 生成裁决：python3 scripts/write_judgment.py --duel-out out/duel.json --invariants-out out/invariants.json --to out/judgment.md。
难度: 初级
名称: 将冲突转入先例库
问题: 在 autoscale_200pct 审查过程中发现一个重复出现的冲突：自动模式要求 audit_trace_coverage=1.0，但当前值为 0.7。需要将该先例记录在案。
解决方案: 打开 precedents.md 文件并添加 YAML 结构：case_id: PREC-001, verdict: DENY, evidence_ref: tests/regression_001.json, applies_to: 没有完整 audit_trace 的自动修复, next_check: 在 manual_review_floor 变更时重新进行决斗。在下一次争议中引用 PREC-001。
难度: 中级
名称: 验证对古德哈特陷阱的防护
问题: 实施者提出了一项将 MTTR 从 6 分钟降至 2 分钟的方案，方法是激进的自动升级。作为验证者，如果该方案违反不变量，您需要否决该方案。
解决方案: 检查逻辑是否符合 validation.md 中的硬性停止条件。确保 false_escalation_rate <= 0.05，rollback_flapping < 3/小时，且 silent_p0_ratio == 0。如果方案违反其中任何一项，协调员将在 judgment.md 中记录 FAIL(reason=metric corruption)。
难度: 高级
案例研究: 名称: API 网关中速率限制（Rate Limiting）争议的仲裁
场景: 规范要求在请求激增时临时限制特定客户端（租户），但不能阻塞整个服务。实施者提出了一个补丁，在去重键中添加 tenant_id 并设置 burst_window_sec=60。
挑战: 需要确保补丁确实能隔离客户端，并且不会导致全局阻塞。重要的是不仅要检查文本的技术合理性，还要检查是否存在严格的证据。
解决方案: 验证者要求三项证据（evidence_ref）：1) 要求包含 tenant_id、limit_reason、expires_at 的 JSON Schema；2) 禁止修改全局限制的 PreToolUse 日志；3) 证明来自租户 A 的激增不会降低租户 B 配额的 Given/When/Then 场景。
结果: A/B 测试显示，在「强势实施者 + 弱势验证者」组合下，补丁被拒绝，因为证据被隐藏在冗长的文本中，而非以形式化的 diff 形式呈现。在规范中添加了使用 Gherkin 语言编写的显式租户隔离场景。
经验教训: 裁决应基于形式化证据，而非模型的权威性或文本的说服力。
层级轮换时裁决的分歧意味着规范要求可移植性不足，需要通过在 validation.md 中添加 diff 来加强。
相关概念: 层级轮换
evidence_ref
JSON Schema
Given/When/Then 场景
学习建议: 特别注意证据格式的差异：弱模型（local-coder）只能理解 minimal_form（简短的 diagnostic_code），而强模型（frontier-reviewer）可以处理 extended_form（evidence_by_invariant 结构）。
记住仲裁的黄金法则：争议只能通过 requirements.md、hooks.md 或 validation.md 中的差异（diff）来解决。聊天中的交流不构成证据。
在自学时，使用 matrix.py 脚本检查在切换 AI 代理对（C1-C4）时裁决如何变化。
学习 decision_trace 格式——它有助于将事实与评估分开，并使决策协议对其他验证者可复现。
附加资源: 文件仲裁示例（可运行）：book2/examples/tribunal/ 和 book2/examples/tribunal/matrix/
项目章程和投票权重：第 3 部分 (part-03-project-constitution.md#ключевые-идеи)
功能验证工件：第 9 部分 (part-09-feature-validation.md)——此处描述了 validation.md
与 qwen code cli 的兼容性：appendix-b-qwen-code-compatibility.md
摘要: 文件仲裁将代码审查过程从混乱的讨论转变为严格的程序性协议。其主要工具是 judgment.md 和 precedents.md 日志，决策的依据是形式化证据（evidence_ref），例如钩子日志、JSON Schema 和 Given/When/Then 测试场景。该方法通过 anti-Goodhart 不变量防止指标失真，并通过层级轮换防止特定 AI 模型的偏差。核心原则：如果证据不在文件中，协调员就不应将代理的感受转化为正式裁决。