应用部分 6. 影子规范筛选

状态：前沿。 该手法本身——将非正式启发式规则提取到独立层，并通过少样本槽位预算加以限制——已被采用。但评估公式和接受阈值需要根据具体项目进行校准。「不要替代主规范」的理念属于建议性内容。

对于学习性演练，只需运行 examples/shadow-auction/ 并观察为何某条启发式规则进入 QWEN.md，而另一条进入隔离区。基于 50+ 事件的权重校准属于完整生产流程。

引入关键概念。影子规范（shadow specs） —— 来自运维实践的可验证启发式规则。它们在分类（triage）阶段有帮助，但不是系统的强制性要求。少样本示例（few-shot） —— 提示中的简短示例，向智能体展示类似案例的期望回答格式。评分日志（scorebook） —— 影子规范的经济日志：原始数据（seed）、评估公式、阈值、预算（budget）、候选版本和决策协议。

在第一卷第 6 部分编写 mission.md 时，参与者留下了一些未达要求级别的建议。典型例子如下：

• 「夜间回复更简短」，
• 「不要用 emergency 这个词吓到患者」，
• 「再次出现症状时立即请求病史」。

本章回答当时遗留的问题——在生产环境中如何处理这类建议。它们去向何处、如何证明自身价值、何时可以移除。最终进入 QWEN.md 的少样本示例，与第一卷第 19 部分中的智能体记忆相同，但具有明确的生命周期（ttl）和准入竞拍机制。

阅读前准备

• 第一卷基础：第 6 部分说明建议不等于要求；第 19 部分区分记忆与规范。
• 本地学习案例：shadow.p0.voice_handoff 与关于仪表板颜色的噪声启发式规则之间的竞拍。
• capstone/ 的产出：Shadow notes 的简短区块，包含一个被接受和一个被拒绝的 high_memory_usage 候选。
• 第一遍的主要术语：影子规范和评分日志（scorebook）。竞拍、少样本示例、隔离区 —— 为参考性内容。

• 可延后处理：从 50+ 事件中收集候选、权重校准和 QWEN.md 的自动更新。

目标

在本章中，您将把事件管理中的非正式观察转化为具有可衡量价值的可验证影子规范层。这里的「竞拍」指的是在有限上下文预算下的排序筛选，而非独立产品或强制外部服务。进入此处的观察包括：

• 沟通语气，
• 直觉性前提，
• 环境信号，
• 资深工程师的「魔法」解决方案。

目标不是替代正式规范。目标是将有用的启发式规则与运维民间传说区分开来。完成后您将能够：

• 启动影子规范竞拍（即在有限上下文预算下评估和筛选启发式规则）；
• 为每个细微差别赋予基于历史事件的预测价值；
• 仅在 QWEN.md 中保留真正提升 Qwen Code 质量的少样本示例。

最小学习场景

学习案例

需要决定启发式规则 shadow.p0.voice_handoff 是否进入 QWEN.md，而关于仪表板红色的噪声启发式规则是否进入隔离区。目标是观察非正式观察经过评估和预算流程，而非凭权威成为要求。

准备工作

• book2/examples/shadow-auction/candidates/candidates.yaml。
• book2/examples/shadow-auction/data/incidents.jsonl。
• 脚本 score.py、decide.py、write_qwen_block.py。

步骤

1. cd book2/examples/shadow-auction。 预期：您已进入可运行示例目录。
2. python3 scripts/score.py --candidates candidates/candidates.yaml --incidents data/incidents.jsonl --weights 0.5,0.3,0.2,0.4 --out out/scorebook.json。 预期：已创建包含评分组件的评分日志。
3. 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。 *预期：部分候选获得 winner 状态，部分进入隔离区（quarantine）。*

1. python3 scripts/write_qwen_block.py --auction out/auction.json --target-anchor "QWEN.md#incident-triage-shadow" --today 2026-05-17 --out out/qwen_block.md。 *预期：QWEN.md 的区块仅包含获胜者和决策来源链接；使用学习日期时，与 outputs/qwen_block.example.md 一致。*
2. 比较 out/auction.json 和 out/quarantine.json： 预期：落选候选未消失，而是获得了拒绝原因。

验证要点

获胜者未成为强制性要求。它被格式化为带 source_ref、score 和复审期限的版本化少样本示例。低于阈值的候选处于隔离区并附带原因。

如何进入 capstone/

将简短的 Shadow notes 部分移入 capstone/README.md：一个获胜者和一个被拒绝的候选，包含 id、score、保留/拒绝原因和复审期限。不要将获胜者加入 requirements.md：在评分包中，它保持为影子提示，而非已批准的要求。

最小片段：

shadow_notes:
  keep:
    id: shadow.p0.voice_handoff.v1
    score: 0.727
    ttl: "14d"
    reason: "early signal for manual handoff"
  reject:

id: shadow.alert.red_color_urgency
    reason: "false escalation risk"

可审查的痕迹

out/ 不需要包含在学习包中。评分只需在 QWEN.md 或 capstone/README.md 中保存简短摘录，并附竞拍标准链接。

核心思想

规范化从将观察转化为影子规范格式开始：上下文 → 特征 → 观察到的效果。字段如下：

• 上下文 设定适用边界。例如，「appointments-api 中存在级联风险的 P0 事件」。
• 特征 记录观察到的细节。例如，「值班人员用简短祈使句消息，跳过标准模板」。
• 效果 描述可验证的后果。例如，「5–10 分钟后出现手动绕过（bypass）或紧急回滚（rollback）」。

这种格式并未使细微差别成为完全正式的契约。但将其转化为可与历史事件对比的槽位。附加字段 evidence、scope、risk 和 source_ref 用于防止 Qwen Code 从自由文本中猜测启发式规则的含义。

在您的项目中，候选收集由 harvest.py + normalize.py 脚本对完成：前者从访谈、事后分析和事件中提取内容到 .specify/memory/shadow-candidates.raw.ndjson，后者按 上下文 → 特征 → 效果 模板展开为 .specify/memory/shadow-candidates.yaml。教材中没有此阶段的可运行示例；它取决于您的来源位置。评估和竞拍本身的可运行示例在 examples/shadow-auction/README.md 中。

规范化后，每个候选槽位通过三组指标在历史事件上评估：

• 对 MTTR 的影响，
• 误报升级的比例，
• 提前预警级联的能力。

评估沿三个维度构建。

MTTR 显示启发式规则是否帮助更快得出正确行动。但此指标本身有危险。规则可能加速个别案例，同时在分类阶段制造噪声。

误报升级记录错误触发的代价。特别是当影子规范将 P2 提升至 P1 而依据不足时。

提前级联预警衡量特征是否出现在标准告警之前。而非在正式系统已记录问题之后。

将最终评分记录为可复现的公式，而非「感觉有用」的专家评估。例如，对学习环境使用 score = 0.5*mttr_gain + 0.3*early_signal + 0.2*coverage - 0.4*false_escalation。此处 coverage 限制过于狭窄的规则，false_escalation 惩罚噪声启发式规则。

此公式中的权重为初始校准，而非定律。正权重之和设为单位 1（0.5+0.3+0.2），使最终 score 落在区间 [-0.4; 1] 并可读作「有用信号的比例」。在此单位内，0.5 / 0.3 / 0.2 的比例反映 AgentClinic-production 的学习优先级顺序：降低 MTTR 是主要可测量效果，早期信号仅作为缩短同一 MTTR 的价值，而覆盖率只是防止规则过于狭窄的保险。误报升级惩罚系数（0.4）的设定使得一次误报升级消耗约 80% 理想 MTTR 降低效果（0.4 / 0.5 = 0.8）：一条在理想 MTTR 降低（mttr_gain=1）同时产生一次误报升级（false_escalation=1）的启发式规则，几乎失去所有最终 score（0.5 - 0.4 = 0.1）且不进入最终交付。进一步校准方法：

• 若您团队的错误代价更高 —— 将惩罚提升至 0.6–0.8；
• 若更看重提前预警 —— 增大 early_signal 并减小 mttr_gain。

校准后，用公式在 50+ 历史事件上测试。将获胜者与团队当前手动决策方式对比。若差异过大，则权重校准到了他人的风险画像。

收集足够历史案例，使罕见级联不会在评估中消失。严肃决策使用 50+ 事件：这是下限，此时罕见级联类（频率约 1/25 事件）在样本中至少出现两次，early_signal 可与随机巧合区分。更小的集合仅用于冒烟测试（smoke）。

此语境中「数据漂移」的含义。漂移（drift） —— 事件源中时间轴和标识符的失同步。若时间轴未对齐，Qwen Code 可能将事后观察误认为早期信号。因此评估前执行三项操作：去重、时间戳规范化和事件绑定到统一事件标识符。

在您的项目中，评估格式化为 python3 scripts/shadow_specs/score.py --candidates .specify/memory/shadow-candidates.yaml --incidents .data/incidents_hist_50plus.jsonl --weights "0.5,0.3,0.2,0.4" --out .specify/memory/shadow-scorebook.json。学习数据上的可运行示例在 examples/shadow-auction/README.md 中。

竞拍将评估转化为有限上下文预算的可控分配。

不好的做法：

> 启发式规则「值班人员在 Slack 中说 ASAP —— 提升 severity 至 P1」直接作为强制要求加入 requirements.md。

问题：未经检验的观察无证据即成为契约。并在任何聊天中的「ASAP」上制造误报 P1。

好的做法：

> 同一启发式规则格式化为影子规范 shadow.slack.asap_urgency，score 0.55，状态 review：数值高于拒绝阈值 reject_threshold=0.40，但低于接受阈值 keep_threshold=0.70，因此候选进入人工复审，而非正式规范。

流程机制。Qwen Code 按 value_score 排序候选。然后消耗预设 budget —— 例如 8 个少样本槽位或 2,000 token。结果分为三类：

• keep —— 获胜者，进入 QWEN.md；
• review —— 存疑，进入人工复审；
• quarantine —— 淘汰，进入隔离区。

获胜者仅在超过上限阈值时自动纳入。存疑者进入人工复审。被淘汰者不留在灰色地带。此机制保护 QWEN.md 免于膨胀。即使看似合理的细微差别，若其预测价值低于提示槽位的成本，也会输掉。

在您的项目中，竞拍决策格式化为 python3 scripts/shadow_specs/decide.py --scorebook .specify/memory/shadow-scorebook.json --budget-tokens 2000 --keep-threshold 0.70 --reject-threshold 0.40 --out-auction .specify/memory/shadow-auction.json --out-quarantine .specify/memory/shadow-quarantine.json。学习数据上的相同步骤在 examples/shadow-auction/README.md 中运行。

将获胜者转化为 QWEN.md 中的版本化少样本区块，而非简单追加到文件末尾。为每个区块设定：

• id，
• version，
• source_ref，
• score，
• valid_from，
• next_review（或 ttl —— 短复审如「14d」的可接受简写），
• 简短应用示例。

这些字段的用途。后续团队需要理解此细微差别存在的原因。

明确淘汰低价值候选。将其送入 quarantine 并附带原因、复审日期和计算链接。不要让它们无痕迹地从历史中消失。这对决策申诉很重要：若一个月后告警策略或故障转移架构改变，此前被拒绝的影子规范无需重新收集原始数据即可重返竞拍。

- id: shadow.p0.voice_handoff.v1
  status: keep
  score: 0.727
  source_ref:
    - postmortem: "appointments-api-2026-02-11"
    - incident: "INC-1842"
  valid_from: "2026-05-17"
  next_review: "2026-08-17"
  few_shot_target: "QWEN.md#incident-triage-shadow"

0.727 的具体来源：examples/shadow-auction/scripts/score.py 在 data/incidents.jsonl 的 20 个历史事件上、默认权重 0.5/0.3/0.2 − 0.4 时的输出值。与标准值核对 —— examples/shadow-auction/outputs/scorebook.example.json。

评分日志是影子规范的经济日志。其中共同存储原始数据（seed）、评估公式、阈值、预算（budget）、候选版本和决策协议。

没有评分日志，竞拍很快变成权威之争。资深工程师可能强推喜爱的启发式规则，Qwen Code 则获得矛盾的少样本示例。此处引入另一概念。Anti-Goodhart（反古德哈特定律） —— 防止以牺牲意义为代价优化指标。可复现日志提供三种能力：权重改变后重新计算结果、检验哪些事件影响了胜利、将真实改进与古德哈特陷阱区分。

在 SDD 环境中，将此文件与项目记忆和宪法约束并列保存。Spec Kit 中对此类持久规则，使用 .specify/memory/constitution.md 作为防漂移保护层较为方便（GitHub Spec Kit）。

完整流程：阈值校准

竞拍公式的权重、keep/reject 阈值和权重复审信号位于附录 D，D.2 节。第一遍不需要该节：默认权重下的一个接受和一个拒绝候选即足够。

示例与应用

示例：在 appointments-api 自动分类项目中，候选 shadow.p0.voice_handoff 描述如下场景。P0 时值班人员不在聊天中写长消息，而是立即在值班人员（on-call）和服务所有者之间发起语音交接（handoff）。

在 data/incidents.jsonl 的 20 个历史事件上，该特征获得 score 0.727：高 MTTR 增益（0.7541）、可靠的早期信号（1.0）、窄覆盖（0.25）和零误报升级。五例中它缩短了第二班次介入时间。该候选几乎不产生误报升级，因为仅在确认 P0 和交易级联风险时应用。

该候选成为获胜者。但在 QWEN.md 中，它以狭窄的适用条件进入。Qwen Code 不应为常规 P2 推荐语音渠道，其中异步文本痕迹比通话速度更重要。实际价值不在于「打电话」本身，而在于早期识别延迟交接代价高于部分书面上下文损失的场景。

另一候选 shadow.alert.red_color_urgency 输掉竞拍。虽然直觉上看似合理。同一可运行竞拍给出其 score -0.3081：微弱的 MTTR 增益和显著的误报升级比例将评分拉入负值。红色常用于仪表板视觉强调，但不对应影响半径、SLO 预算消耗速度或实际升级级别。

该影子规范产生三重负面效果：

• 提高误报 P1 比例，
• 超载分类阶段，
• 降低对自动推荐的信任。

将其送入隔离区，原因 high_false_escalation，附复审日期和返回条件。首先团队改变告警可视化策略。然后候选重新通过评分日志测试。

罕见的物理信号可能获胜，若漏检代价显著高于检查代价。例如 shadow.dc.burn_smell_power_risk 仅适用于数据中心现场（onsite）事件。其 coverage 低，但 early_signal 高：烧焦味或过热有时在电源监控显示降级前出现。

此候选不可转为通用规则。否则它将成为无物理访问权限的云事件的毒性噪声。正确的纳入形式是带三个限制器的罕见少样本示例：硬上下文、明确的风险注释、以及要求通过现场操作员渠道确认信号。

flowchart TD
A[第 6 章. 影子规范筛选]
A --> B[访谈 / 事后分析 / 事件历史]

B --> C[影子候选提取]
C --> D[规范化 上下文 / 特征 / 效果]
D --> E[通过 Qwen Code 对 50+ 案例进行回溯测试]
E --> F["score = 0.5*mttr_gain + 0.3*early_signal + 0.2*coverage - 0.4*false_escalation"]
F --> G[竞拍决策 keep/quarantine/review]
G --> H[keep]
G --> I[quarantine]
G --> J[review]
H --> K[QWEN.md]
I --> L[带复审日期的隔离区]
J --> L

总结

影子规范竞拍使非正式细微差别变得可控。每个候选获得 上下文 → 特征 → 观察到的效果 结构，在历史事件上接受评估，竞争有限预算 —— 要么成为 QWEN.md 中的版本化少样本示例，要么进入隔离区并附带可验证原因。

流程的主要纪律是不轻信没有评分日志的醒目故事。原始数据、公式、阈值和决策协议应允许在基础设施改变时复现结果并申诉。下一章将此逻辑转化为规范网关（Specification CI），使规范成为可执行产物。

产物与就绪标准

| 从 book2/examples/shadow-auction 运行的本地竞拍 | 冒烟通过；相同权重和数据下结果可复现 | | 一个获胜者 | 有 source_ref、score 和复审期限；获胜者不扩展正式 SDD 契约，也不伪装成要求 | | 一个被拒绝的候选 | 在隔离区中附带明确原因（如 high_false_escalation） | | QWEN.md 的简短区块或 capstone/README.md 中的 Shadow notes 节 | 少样本示例具有狭窄的适用条件 |

完整流程增加 上下文 → 特征 → 效果 格式的 .specify/memory/shadow-candidates.yaml、含公式和权重的 .specify/memory/shadow-scorebook.json、含 winner/disputed/rejected 决策的 .specify/memory/shadow-auction.json，以及版本化少样本区块或隔离记录。就绪标准为：每个影子规范有 source_ref、scope、risk 和 next_review；评估可复现计算（无手动重算）；权重、预算或事件类别改变时复审候选。

实践

1. 在学习数据上运行竞拍：cd book2/examples/shadow-auction && python3 scripts/score.py --candidates candidates/candidates.yaml --incidents data/incidents.jsonl --weights 0.5,0.3,0.2,0.4 --out out/scorebook.json。 *预期：diff -u outputs/scorebook.example.json out/scorebook.json 输出 0 行；评分中至少有一个 score >= 0.70 的候选和至少一个 score < 0.40 的候选。*
2. 在同一 scorebook.json 上运行 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。 *预期：out/auction.json 和 out/quarantine.json 与 outputs/ 中的标准值一致；out/quarantine.json 中至少有一条带明确 reason 和 return_condition 的记录。*
3. 将误报升级惩罚权重从 0.4 改为 0.8，重新计算 scorebook.json，并在 capstone/README.md 中记录变化。 *预期：capstone/README.md 中记录一行「误报升级惩罚加倍时，候选 <id> 从 keep 变为 quarantine」；同一行指明新权重下哪个公式分量成为主导。*

检查问题

1. 影子规范与完整要求的区别是什么，为何不能替代它？
2. 为何 QWEN.md 中的少样本示例需要有复审期限？
3. 如何判断启发式规则已成为运维民间传说？
4. 值班人员要求在 QWEN.md 中添加规则「若 Slack 中使用 ASAP 一词 —— 提升 severity」。如何在不立即拒绝的情况下将其通过影子规范竞拍？