全书质量控制与复现清单（QCR）¶

目标：把书里的方法落成项目里的门禁。写得再好，如果不能复跑、不能裁决、不能回滚，最后都会退化成聊天记录。

说明：本仓库以文档为主，但 skills/ 提供少量可复用脚本（例如一键门禁、自检、批量改写）。文中提到的 make gate 等任务名只是“可运行门禁”的形态示例，你可以用任意任务编排工具替代。

0) 先骂后改：QCR 最常见的假动作¶

你可能已经有“清单”，但依然在反复踩坑，通常是因为它满足了形式，却没有形成门禁。

把形容词当门槛：体验更好、显著提升、稳定性增强 → 无法证伪、无法回滚。改法：写成数字/阈值/判定条件，并给同口径证据。
只写通过项，不写失败项：不写失败判定、不写阻断条件 → 迭代永远不会停。改法：先写“什么情况下必须停/回滚”。
只有结果，没有证据：报告截图、口头结论、没有原始输出 → 复跑不了、审计不了。改法：固定证据目录 + 固定字段集合（见第 2 节）。
把一次发布当一次提交：只管代码，不管配置/数据/索引/提示 → 线上行为不可追溯。改法：把发布对象写成版本组合（version set）。
门禁靠人肉流程：评审纪要很多、脚本/表格没有 → 忙的时候必然失守。改法：把关键门槛落成可执行动作，至少能一键复跑。
回归集不版本化：今天的“通过”不等于明天的“通过” → 回归失效。改法：样本集/评测集/攻击集都要有版本号与更新规则。
把 AI 输出当事实：没有合同、没有边界、没有审计字段 → 出事时无法解释。改法：工具/引用/拒答/预算/审计写成合同与阻断规则。
把讨论当交付：争论很激烈、结论很确定、证据包为空 → 下次继续争。改法：决策必须绑定证据与止损线，不留证据的结论默认无效。
把配图当装饰：图与正文无关、无 alt、无来源 → 读者学不到、审稿也审不了。改法：把图片当证据资产，设门槛（见第 4 节）。

1) 总则（四个硬条件）¶

可运行：每条检查都能对应一个可执行动作，并产出可留档的输出（日志、报告、对比表）。
可审计：关键数据、模型、配置必须能追溯到来源与许可证；建议使用数据卡片（Datasheet）与模型卡片（Model Card）。
可裁决：门槛必须能被证伪，写成数字或可判定条件；不要用体验更好这类不可执行句子代替门禁。
可回滚：任何退化都必须有回滚动作与触发条件；回滚要能在同口径下证明指标已恢复。

1.1 门禁分级（阻断/警告/观察）¶

同一条“检查”如果不分级，最后要么卡死发布，要么被人一键关闭。建议统一三档：

L0 阻断：命中即停止合并/发布。典型：越权/泄露/注入命中；核心指标退化超过阈值；端到端不可用；引用/链接大面积断裂导致交付不可读。
L1 警告：不阻断，但必须留档并由负责人确认。典型：成本/时延接近预算上限；图片可读性一般但不影响理解；措辞可能引发误用但尚未造成错误结论。
L2 观察：只记录与跟踪，不影响门禁。典型：实验性功能的波动；文案/排版微调；新增指标但暂未设阈值。

2) 复现包（每次改动最小证据）¶

把一次变更能否复现，压缩成一个固定字段集合。你不需要一次性做大而全，但最低要能回答：我改了什么、用的什么版本、怎么验证、失败了怎么回退。

2.0 证据的六个硬字段（少一个都不算门禁）¶

很多团队“有清单但没门禁”，根因是门禁描述缺字段：能说服人，但不能被机器执行、不能被审计复跑。建议把每条门禁都写成 6 个字段：

目的：这条门禁要防什么（退化/越权/泄露/成本失控/错配）。
入口：怎么跑（命令/任务/脚本入口，至少能一键复跑）。
判定：怎么判失败（阈值/退出码/对比规则，必须可证伪）。
证据：输出在哪里（固定路径 + 固定文件名/格式）。
责任：谁能裁决（owner/值班/审批人）。
回滚：失败怎么退（回滚到哪个版本组合 + 如何证明已恢复）。
版本组合（version set）：代码版本（commit/tag）+ 配置版本（hash/版本号）+ 数据快照（snapshot_id）+ 模型版本（model_id/checkpoint）+ 提示词/检索策略版本（prompt_id/index_id）。
环境指纹：运行环境（OS/运行时/关键依赖版本/硬件类型）要能复盘；同一复现包应能解释“为什么你能跑、我跑不了”。
随机性控制：用于门禁/回归的对比，默认应固定随机种子，并尽量把生成端设为确定性（例如温度为 0 或极低）；否则先声明“不可确定复现”，不要伪装成门禁结论。
评测口径：主指标/守门指标的定义、统计口径（窗口/去重/分桶）、评测样本版本、评测配置（例如 judge/prompt 版本）必须写清。
合规与脱敏：复现包不得包含明文密钥、用户 PII/敏感内容；数据来源与许可证/使用边界必须可追溯。
门禁结果：主指标是否达标、守门指标是否退化、结论是什么（保留/继续/回滚）。
对比证据：同口径对比表（至少覆盖质量/延迟/成本/风险中的相关项）。
回滚记录：触发条件、执行动作、回滚后指标恢复证明。
预算与耗时：本次复跑的时间/成本上限（以及实际消耗），避免门禁因为太贵而无人执行。

建议把复现包落到一个固定目录（示例：reports/YYYY-MM-DD/<change-id>/），保证每轮对比都能找到证据。更完整的结构与字段模板见：附录 D：证据包与门禁速查。常见线上事故的 10 分钟止损动作库见：附录 E：10 分钟止损 Runbook 库。指标字典、阈值三段式与告警到动作映射见：附录 F：指标字典与告警门禁速查。

2.1 建议的复现包结构（示例）¶

manifest.json：版本组合 + 环境指纹 + 随机性控制 + 评测口径摘要。
metrics.json/metrics.md：主指标与守门指标的数值与阈值结论。
diff.md：改动点摘要（面向读者/审稿人的解释，而不是 commit 列表）。
samples/：失败样本与最小复现条件（新增失败样本应回流到回归集）。
rollback.md：触发条件 + 回滚动作 + 回滚后恢复证据。

你不一定要用上述文件名，但你必须能一眼回答：改动指纹是什么、怎么复跑、如何裁决、怎么回滚。

3) 章节映射（最小门禁摘要）¶

这不是重复各章正文，而是把每章的最低门槛抽成可执行的门禁清单。各章末尾的复现检查清单是更具体的版本。

第一篇指挥官（01–06）¶

第 1 章：端到端管线图 + 变更卡片齐全；门槛、失败判定、回滚与证据路径提前写清。
第 2 章：数据可追溯（来源/时间窗/许可/去重过滤）+ 问题证据矩阵可评审 + 决策白板可裁决（含止损线）。
第 3 章：一页 PRD 合同完整（目标/非目标/用例含异常/NFR/验收/回滚）；每条验收都能对应到可复核证据。
第 4 章：页面树/用户流/状态清单/走查记录齐全；关键失败路径有恢复入口；断点列表能派发成任务。
第 5 章：指标树与口径明确；迭代卡片与对比表齐全；一周内闭环复跑与裁决记录可留档。
第 6 章：文字规格与状态矩阵齐全；可访问性最低门槛可复核；UI 回归与一致性规则可执行。

第二篇工程师（07–09）¶

第 7 章：改动可约束成小补丁；最小门禁表与失败判定可执行；对比证据可留档。
第 8 章：关键页面状态矩阵与恢复入口齐全；失败样本可沉淀；体验对比表同口径可复跑。
第 9 章：错误语义与幂等策略一致；最小可观测字段可复盘；成本守门与降级可执行。

第三篇架构师（10）¶

第 10 章（总览）：无引用强答=失败、非法工具调用=阻断、失败样本集回归=门禁；审计字段可追溯可解释。
第 10 章（RAG 深入）：引用合同进入发布门禁；语料边界与回滚策略明确；回归集含缺证据/过期/注入样本。
第 10 章（Agent 深入）：工具合同齐全（权限/输入校验/预算/副作用/审计）；状态机与停止条件可观测；越权命中即阻断。

第四篇造物主（11–15）¶

第 11 章：权限模型一页纸清晰；越权回归用例阻断发布；审计事件可查询；权限变更可回滚。
第 12 章：计量口径可审计；账本事件不可变且可冲正；对账与止损规则可执行；争议可复现可解释。
第 13 章：数据卡、清洗报告、抽检与一致性策略齐全；训练/评测/RAG 都能指向同一数据快照。
第 14 章：决策卡写清目标/预算/风险/门槛/止损；基线可复现；守门指标越界即停训/回滚。
第 15 章：行为契约明确；回归集与攻击集固定可复跑；训练前后对比报告可解释收益与代价。

第五篇运维专家（16–20）¶

第 16 章：质量/延迟/成本取舍卡可执行；基线与对比表同口径；降级梯度与回滚可触发。
第 17 章：发布可追溯到版本组合；灰度推进/暂停/回滚按表执行；Runbook 10 分钟止损可演练（见 E-runbooks.md）。
第 18 章：回归集版本化；红队/攻击集常态化；发布门禁卡写成数字与阻断规则；失败样本回流可复跑。
第 19 章：路线图以验证假设组织；迭代有证据与裁决；定价与成本同口径；门禁脚本可复跑且失败判定明确。
第 20 章：边界文档可执行；风险登记与审计可用；阻断级门禁进入回归；对外解释可复现。

4) 图片与图表门禁（把视觉资产当证据）¶

图片不是装饰物，而是“可视化证据”。只要它进入正文，就必须满足最低门槛：

封面图例外：章节封面图允许作为视觉分隔，不计入证据门禁；但封面图不得承载关键技术信息（如果承载了，必须在正文用文字/表格复述）。
信息增益：这张图必须比纯文本更清晰地表达结构/对比/关系；否则删掉或改成表格/纯文本流程图。
可访问性：每张图必须有可读的 alt 文本（读者不看图也能知道图在表达什么）。
可读性：在浅色/深色背景下都能看清关键元素；避免靠极细线条与低对比配色传递关键信息。
可追溯：外部来源图片必须注明来源与许可证/使用边界；AI 生成图若用于“示意”，正文应标注“示意非数据结论”。
一致性：正文应在首次出现处明确引用该图（例如“如图 4-1 所示”），避免“图在那但不知道用来干什么”。

5) 发布与引用自检¶

发布前清单：参见上线清单（隐私 / 安全 / 成本）。
本仓库一键门禁：bash skills/check_docs.sh（包含引用检查 + 严格构建）。
全站构建自检：建议发布前运行 python3 -m mkdocs build --strict，用严格模式发现死链、缺页与配置错误。
引用自检：建议发布前运行 python3 tools/check_citations.py，确保正文中的 [n] 都能在 references.md 找到。