学习指南: 附录 D. 阈值校准

主题：附录 D. 阈值校准

难度级别：中级

预计学习时间：6-8 小时（理论：3 小时，实践：3-5 小时）

前置条件： 完成 AgentClinic 课程的第 5、6、9、10 和 11 章

具备 YAML 基础知识和命令行操作能力

理解变异测试、影子规范和分层预算的概念

具有 SLA 指标和 CI/CD 流程的工作经验

了解古德哈特定律及其在工程系统中的表现

学习目标： 根据项目特点配置和校准变异测试阈值（strict_reject_rate、depth_of_diagnostics、recovery_time_p95），并将依据记录在 validation.md 中

在误报升级成本和提示样本预算变化时，重新计算影子规范筛选的权重和阈值（keep-threshold、reject-threshold、budget-tokens）

设计 token 分层预算，正确划分 local/frontier 层级，并通过 compile.py 验证完整性

识别防护指标网络中的古德哈特定律症状，并仅通过成对调整阈值来保持不变量

根据操作类型（无状态/有状态）和独立阻塞不变量确定系统的生产就绪状态

概述：附录 D 是将 AgentClinic-production 流程迁移到自有项目的参考材料。它系统整理了五个关键领域的「低/默认/高」阈值表：变异测试、影子规范筛选、分层预算、防止指标古德哈特定律、以及生产就绪性。核心原则：阈值必须成对才有意义。单独调整一个值而不重新计算相关参数，这不是校准，而是拆除控制回路。本指南包含基于真实脚本的实践练习、阈值复审信号以及错误校准的风险警示。

关键概念： 成对校准：附录 D 的基本原则：任何阈值都与其他参数相关联。例如，strict_reject_rate 和 depth_of_diagnostics 必须同步调整。如果 strict_reject_rate 上升而 depth_of_diagnostics 下降——这是古德哈特定律的症状，而非质量提升。类似地：false_escalation 惩罚与 mttr_gain 权重、silent_p0 与 manual_review_rate、edge_drift 与 audit_trace_coverage。

agentclinic 默认值：适用于中等事件流量（200/天）、成熟 SDD 流程（6 个月以上）和混合操作类型的生产系统的基线。任何偏离此基线的情况都需要在 validation.md 中提供依据。

阈值复审信号：指示需要校准的具体触发条件：季度内无阻塞（阈值过低）、单一 mutation_id 的回归集中（阈值不足）、strict_reject_rate 上升时 recovery_time_p95 降至零（古德哈特）、mttr_gain 上升时 manual_review_rate 也上升（目标替代）。

指标中的古德哈特定律：当指标成为目标时，它就不再是好的指标。在 AgentClinic 的语境中：strict_reject_rate 上升但诊断没有实质改善、通过忽略复杂案例缩短 MTTR、false_escalation 上升的同时 mttr_gain 也上升——所有这些模式都需要成对修正。

独立阻塞不变量：不纳入总分阈值，但独立阻止合并的指标。例如，audit_trace_coverage = 1.0 是生产就绪的必要条件；当 audit_trace_coverage = 0.7 时，即使就绪度为 22/25 甚至 25/25，也不允许自动切换。

变异种子轮换：定期更换变异测试中的 seed，以防止验证器对固定 mutation_id 集合过拟合的实践。同一种子连续重复五个冲刺——这是轮换信号。

预算分层划分：在 local 层级（1000 万中的 900 万）和 frontier 层级（1000 万中的 100 万）之间分配 token 的架构。比例与各阶段的 SLA 相关：更改 daily_budget_tokens 而不更新 budget_plan_phases 会破坏完整性并导致 compile.py 报错。

影子规范风险画像：筛选公式中的权重配置：保守画像（0.3, 0.4, 0.2, 0.8）比标准画像（0.5, 0.3, 0.2, -0.4）对误报升级的惩罚更重，对 MTTR 的奖励更少。

运行模式：准入层级：auto ≥23/25——全自动模式；半手动 20–22——implement 后停止并需明确确认；canary——渐进部署。降至 23/25 以下——这是模式变更，而非「放宽阈值」。

指标依赖网络：完整的关联模型：silent_p0 和 escalation_rate 对 MTTR 有正向影响；manual_review_rate 和 audit_trace_coverage 对 MTTR 和 escalation_rate 有负向影响；postmortem_regression 与 audit_trace_coverage 正相关，与 manual_review_rate 负相关。

实践练习： 标题：练习 D.1：校准 depth_of_diagnostics

问题：在一个具有 80 条边的路由图（多租户）的项目中，需要验证将 depth_of_diagnostics_min 阈值从 3 改为 5 会如何影响 immunity_score。使用 book2/examples/stress-mutator 中的脚本。

解答：1. 进入目录：cd book2/examples/stress-mutator

1. 创建输出目录：mkdir -p out
2. 复制并修改预期结果：cp expected/expected_failures.json out/expected_failures_depth5.json; sed -i 's/"depth_of_diagnostics_min": 3/"depth_of_diagnostics_min": 5/' out/expected_failures_depth5.json
3. 运行基准计算：python3 scripts/immunity_score.py --validator-results out/validator_results.json --expected expected/expected_failures.json --out out/immunity_default.json —— 应通过（平均深度 4 > 3）
4. 运行严格计算：python3 scripts/immunity_score.py --validator-results out/validator_results.json --expected out/expected_failures_depth5.json --out out/immunity_depth5.json —— 应以代码 1 退出
5. 比较增量：这不是新缺陷，而是收紧阈值的代价。在 validation.md 中记录依据：「路由图扩展至 80 条边，多租户；depth_of_diagnostics_min 提升至 5，strict_reject_rate 重新计算为 ≥0.995」。

难度：中级

标题：练习 D.2：影子拍卖的保守画像

问题：医疗团队要求降低误报升级。构建保守权重画像并分析哪些候选者会改变状态。

解答：1. 进入目录：cd book2/examples/shadow-auction

1. 使用保守权重运行拍卖：python3 scripts/score.py --candidates candidates/candidates.yaml --incidents data/incidents.jsonl --weights "0.3,0.4,0.2,0.8" --out out/scorebook.json
2. 应用增加预算的阈值：python3 scripts/decide.py --scorebook out/scorebook.json --budget-tokens 2000 --keep-threshold 0.70 --reject-threshold 0.40 --out-auction out/auction.json --out-quarantine out/quarantine.json
3. 分析变化：shadow.p0.voice_handoff 从 winner 变为 disputed（误报升级风险高），shadow.alert.red_color_urgency 保持 rejected
4. 在 validation.md 中记录：「误报升级代价提升至 0.8，keep-threshold 降至 0.70，budget-tokens 增加至 2000 以补偿保守性」。

难度：中级

标题：练习 D.3：验证分层预算完整性

问题：一个日流量 50 个事件的项目需要 500 万 token 预算。验证 compile.py 是否会拒绝未重新计算阶段配额的 daily_budget_tokens 变更的错误规范。

解答：1. 进入目录：cd book2/examples/budget-keeper

1. 编译正确计划：python3 scripts/compile.py --budget-spec specs/budget_network_5m.yaml --out out/budget_plan_5m.json
2. 验证比例保持：local = 450 万，frontier = 50 万（90/10）
3. 模拟 local 层级故障：python3 scripts/simulate.py --plan out/budget_plan_5m.json --scenario scenarios/fail_local_45m.json --out out/fail_result_5m.json
4. 检查健康状态：python3 scripts/inspect.py --result out/fail_result_5m.json --query "failover_to_frontier==2 && degraded_queue==18 && token_health_min>=0.5"
5. 创建错误规范：复制 budget_network_5m.yaml，仅将 daily_budget_tokens 改为 300 万，保留阶段配额
6. 确认 compile.py 因总和错误而崩溃——这是防止拆除控制回路的保护机制。

难度：中级

标题：练习 D.4：演示分离校准 guard 指标的危险性

问题：说明为什么同时放宽两个独立防护会放过不良发布，而仅放宽一个则不会。

解答：1. 进入目录：cd book2/examples/goodhart-validator; mkdir -p out

1. 第一场景——放宽 silent_p0_cap：cp specs/validation.yaml out/validation_loose.yaml; sed -i 's/threshold: 0.05/threshold: 0.08/' out/validation_loose.yaml; python3 scripts/run_validation.py --validation out/validation_loose.yaml --metrics fixtures/new_metrics_bad.json —— 结果：FAILED（silent_p0=0.18 > 0.08）
2. 第二场景——危险的双重放宽：cp specs/validation.yaml out/validation_unsafe.yaml; sed -i 's/threshold: 0.15/threshold: 0.10/' out/validation_unsafe.yaml; sed -i 's/threshold: 0.05/threshold: 0.20/' out/validation_unsafe.yaml; python3 scripts/run_validation.py --validation out/validation_unsafe.yaml --metrics fixtures/new_metrics_bad.json —— 结果：PASSED（假阳性）
3. 得出结论：guard 指标构成统一的风险契约，不能单独放宽。在 validation.md 中记录禁止单行 YAML 变更。

难度：高级

标题：练习 D.5：验证 audit_trace_coverage 的独立性

问题：证明 audit_trace_coverage 是不纳入 25/25 生产就绪总和的独立阻塞不变量。

解答：1. 进入目录：cd book2/examples/real-api; mkdir -p out

1. 复制并修改脚本：cp scripts/check_readiness.py out/check_readiness_t22.py; sed -i 's/THRESHOLD = 23/THRESHOLD = 22/' out/check_readiness_t22.py
2. 使用 readiness_block_audit.json 运行：python3 out/check_readiness_t22.py --readiness fixtures/readiness_block_audit.json
3. 结果：因 audit_trace_coverage=0.7 < 1.0 而被 BLOCKED，尽管总和为 22/25（甚至潜在的 25/25）
4. 分析：这证明 Security=0 或 audit_trace_coverage<<1.0 是绝对阻塞项。将 THRESHOLD 降至 22 是进入半手动模式，而非「放宽准入」。在 validation.md 中记录：「audit_trace_coverage=1.0 是监管不变量，不可校准」。

难度：中级

案例研究： 标题：案例：进入医疗市场时的阈值重新校准

场景：AgentClinic-production 团队原本使用内部工具（strict_reject_rate ≥ 0.98，depth_of_diagnostics ≥ 3），获得了一份医疗信息系统事件处理合同。监管要求：遗漏 P0 关键事件可导致高达年营业额 2% 的罚款及管理层的刑事责任。

挑战：AgentClinic 的标准阈值不足以应对医疗领域。团队面临同时提升 strict_reject_rate 至 ≥0.995、depth_of_diagnostics 至 ≥5（路由图扩展至 120 条边，多租户患者隔离）、在每日 >500 个 PR 的情况下将 recovery_time_p95 降至 ≤1500 毫秒的需求。风险：单独提升 strict_reject_rate 而不调整 depth_of_diagnostics 将导致古德哈特定律——验证器将无差别拒绝一切，包括正确的修复。

解决方案：团队按照附录 D 的方法论进行成对校准：1）在 validation.md 中记录依据：「监管合同 §12.3，遗漏 P0 的代价：罚款 2% + 刑事责任」；2）将 strict_reject_rate 提升至 0.995，同时将 depth_of_diagnostics 提升至 5；3）每类变异体数量增加至 5+，每 2 个冲刺轮换一次种子；4）通过 immunity_score.py 进行压力测试，使用人为收紧的 depth_of_diagnostics_min=5 阈值；5）确认 strict_reject_rate 上升时 recovery_time_p95 未降至零——无古德哈特定律症状。

结果：系统通过监管审计，6 个月运营期间 P0 遗漏为零。MTTR 因深度诊断增长 12%，但这是合规的必要代价。种子轮换在验证器过拟合进入生产前识别出 3 次。

经验教训： 监管要求需要的不是「最大」阈值，而是有据可查的成对调整及决策代价的记录

种子轮换不是可选实践，而是在增加变异体数量时的必需措施，否则验证器将对固定模式过拟合

depth_of_diagnostics 增加导致 MTTR 增长 12% 是预期的权衡，需提前与客户在 SLA 中约定

无古德哈特定律症状（recovery_time_p95 → 0）是比 strict_reject_rate 绝对值更重要的健康指标

相关概念： 成对校准

阈值复审信号

指标中的古德哈特定律

变异种子轮换

标题：案例：错误压缩预算导致控制回路拆除

场景：一家经历流动性危机的金融科技初创公司决定将 LLM 基础设施成本削减 50%。技术总监仅将规范中的 daily_budget_tokens 从 1000 万改为 500 万，未重新计算阶段配额。

挑战：脚本 compile.py 因总和错误而崩溃——这是附录 D 中预设的保护机制。然而总监未查明原因，在本地副本中注释掉了完整性检查并手动构建了预算。结果：local 层级获得 400 万而非 450 万，frontier 层级获得 20 万而非 50 万，剩余 80 万「酌情分配」而与阶段 SLA 无关。

解决方案：3 周后因 local-coder 故障系统无法切换至 frontier 而发现问题：frontier 层级 token 不足导致网关过于严格。团队恢复了原始 compile.py 机制，以 90/10 比例（450 万/50 万）正确编译，通过 simulate.py 模拟故障，确认 failover_to_frontier 正常工作。

结果：系统停机 47 分钟，12 个事件进入 manual_queue 并超出 SLA。财务损失超过预算压缩节省的 8 倍。技术总监被暂停基础设施决策权。

经验教训： compile.py 不是官僚障碍，而是控制回路的保护；绕过检查是拆除，不是优化

90/10 比例与各阶段 SLA 相关；变更需要重新计算 budget_plan_phases，而非仅调整 daily_budget_tokens

基础设施 guard 指标的节省具有负 ROI：一次停机的损失超过全年节省

附录 D 的方法论要求任何预算变更必须经过完整周期：compile → simulate → inspect → 在 validation.md 中记录

相关概念： 预算分层划分

成对校准

阈值复审信号

标题：案例：分离校准 guard 指标导致假阳性通过

场景：一家支付系统团队在业务「加速发布」的压力下决定「优化」guard 指标。他们没有成对校准 silent_p0 和 manual_review_rate，而是独立放宽了两个阈值：silent_p0_cap 从 0.05 到 0.20，manual_review_rate 从 0.15 到 0.10。

挑战：单独看每次变更似乎都合理：「我们 P0 很少」和「人工审核员不足」。同时放宽造成了假阳性通过：一个 silent_p0=0.18 且 manual_review_rate=0.08 的不良发布通过了验证，尽管两个指标都处于临界低值。这是附录 D 原则的直接体现：guard 指标构成统一的风险契约。

解决方案：支付数据泄露事件（后果：34 万笔交易受影响，监管罚款 240 万美元）引发审计。审计人员复现了练习 D.4：仅将 silent_p0_cap 放宽至 0.08 仍能阻止不良发布，而双重放宽则放过。团队实施了严格规则：任何 validation.yaml 变更都需要审查「独立放宽」并通过 goodhart-validator 自动运行。

结果：系统恢复，通过紧急提升 manual_review_rate 至 0.25 并引入签名追踪 audit_trace_coverage 满足监管要求。发布时间增长 40%，但遗漏 P0 恢复为零。

经验教训： Guard 指标不是一组独立开关，而是统一的风险契约；单独放宽任何一个都是拆除防护

假阳性通过比假阴性阻塞更糟：生产环境遗漏的缺陷代价远高于发布延迟

通过 goodhart-validator 自动检查「独立放宽」必须是强制性的，不是可选的

业务「加速」的压力不能成为绕过方法论的理由；需要升级机制，而非静默妥协

相关概念： 独立阻塞不变量

指标中的古德哈特定律

指标依赖网络

成对校准

学习建议： 按 D.1–D.5 章节顺序学习，不要跳过练习——每个练习都展示了错误校准的具体风险

并行维护你自己的 validation.md：即使这是学习模拟，也要为你自己的项目记录假设性依据

使用「预测后验证」方法：运行脚本前写下预期结果，然后与实际对比——这能培养对阈值行为的直觉

创建「我的项目 → AgentClinic 参数 → 偏离 → 依据」对应表——这是真实迁移的模板

对于视觉型学习者：在纸上重绘指标依赖网络的 mermaid 图表，用不同颜色标记正负关联——这有助于记住哪些指标需要成对移动

练习识别古德哈特定律症状：设计「如果」场景并检查附录 D 中是否有对应的复审信号

按「一天一个风险系统」原则分组学习：D.1+D.4（变异与古德哈特）、D.2+D.5（影子规范与就绪度）、D.3（预算）——这样章节间的关联更清晰

对于听觉型学习者：大声朗读校准依据，格式为「如果[项目参数]，则[阈值]，因为[风险]」——这为与利益相关者的真实讨论做准备

测试边界情况：如果同时将所有阈值设为「低」或「高」会发生什么？为什么这不可行？

额外资源： 课程原始材料：第 5、6、9、10、11 章——附录 D 所依据的理论基础

代码仓库 book2/examples：所有练习的实践脚本：stress-mutator、shadow-auction、budget-keeper、goodhart-validator、real-api

validation.md 模板：记录校准依据的格式；为你的项目创建自己的副本

mermaid 文档：用于自行编辑和扩展指标依赖网络图表

文章「goodhart's law and machine learning」（varoquaux）：成对校准和 guard 指标网络结构的理论依据

Google SRE 书籍，第 4 章（service level objectives）：AgentClinic 中 error budgets 与 token 分层预算的类比

AgentClinic 生产迁移检查清单：基于 D.1–D.5 表格自行编制，包含「项目参数」「我们的值」「与默认值的偏离」「依据」「复审日期」列

总结：附录 D 是将 AgentClinic-production 阈值校准迁移到自有项目的实践参考手册。关键原则：（1）阈值必须成对才有意义，单独调整一个而不重新计算相关参数是拆除控制回路；（2）任何偏离默认值的情况都需要在 validation.md 中提供依据；（3）guard 指标构成统一的风险契约，而非一组独立开关；（4）古德哈特定律症状（目标指标上升而无实质改善、关联指标下降）是成对修正的主要信号；（5）独立阻塞不变量（audit_trace_coverage = 1.0、Security = 0）根本不可校准。五个章节涵盖变异测试、影子规范、分层预算、防止古德哈特定律和生产就绪性——每个都包含阈值表、基于真实脚本的实践练习、复审信号和风险警示。方法论要求文档记录、自动完整性检查和定期参数轮换以防止过拟合。