外观
第 42 章 Research Brief：Harness 的版本化、回滚和 A/B 测试
要解决的读者问题
Harness 的指令、Skill、工作流、模型选择、检索配置与评估规则都会改变 Agent 行为。真正困难的不是为这些文件增加一个版本号，而是回答四个可审查的问题：候选与基线究竟差在哪里，比较是否隔离了同时发生的变化，什么证据允许扩大暴露，以及质量下降时能否回到一个已知且可验证的状态。
本章将这些问题组织为 Release Experiment，而不是把软件发布、线上 A/B 测试或模型快照文档直接改写成 Agent 专用流程。版本标识只承担身份和契约沟通；离线评估、受控暴露、监控、停止与回滚各自需要独立记录。任何 approved、winner 或 rolled_back 状态都必须指向其证据范围，不能从一次分数变化推导真实生产效果。
研究范围与非范围
| 读者问题 | 本章研究的回答 | 本章不回答 |
|---|---|---|
| 哪些 Harness 工件需要版本化？ | 为指令包、Skill、工作流、模型/快照选择、评估规格和兼容性声明保存不可变候选身份、依赖与变更摘要。 | 用一个统一数字自动表达所有自然语言行为、模型输出或外部依赖的兼容性。 |
| 怎样比较候选与基线？ | 先固定任务集、输入版本、评估规格和随机分配单位，再区分离线对照、灰度观察与真实线上实验。 | 将前后时间段差异、一次跑分、少量样本或未经核验的评分器当作因果证明。 |
| 什么条件允许继续或回退？ | 预先声明质量、安全、成本和延迟的守护指标、停止条件、责任人、回滚目标与验证步骤。 | 提供跨项目通用的流量比例、显著性阈值、实验时长或自动回滚数字。 |
| 回滚完成意味着什么？ | 只在旧版本重新成为目标、实际状态被重新观察、未恢复的外部效果被登记后，记录有限的回滚结论。 | 把配置指针切换、审批记录或补偿候选写成外部效果已完全恢复。 |
已核验的一手资料与受限用途
| 本地键 | 来源明确表达的内容 | 允许用于本章的范围 | 不可外推 |
|---|---|---|---|
| CH42-REF-01 | Google SRE 将 canary 描述为对变更进行部分、限时部署与评价；实践需要可将候选暴露给子集、评价好坏并把结果接入发布流程。该章还强调按候选/对照分开观察指标、隔离污染、暂停或回滚。 | 支持小范围暴露、候选/对照、分版本监控、停止和回滚准备的工程背景。 | 固定流量比例、时长、指标、SLO、自动回滚算法，或任何 Agent 系统已具备真实灰度能力。 |
| CH42-REF-02 | OpenAI API 官方资料说明模型提示行为可能在快照之间变化，建议固定模型版本并为应用运行 evals；API、SDK 与模型家族的兼容范围也需分别理解。 | 说明模型选择属于 Harness 版本身份，固定快照与应用评估是减少未记录漂移的受限产品背景。 | 输出确定性、跨模型兼容、永久可用性、固定质量水平，或其他供应商的版本策略。 |
| CH42-REF-03 | Semantic Versioning 2.0.0 要求先声明 public API，再用主／次／补丁版本表达不兼容变化、兼容新增与兼容修复；已发布版本不得原地修改。 | 作为 Skill、工作流和评估工件声明公共契约、不可变发布身份和兼容性沟通的受限类比。 | 自然语言 Prompt、模型输出或整个 Harness 自动满足 SemVer；版本号本身证明行为兼容。 |
| CH42-REF-04 | Microsoft Research 的在线 A/B 测试论文指出，分析依赖随机化单位及其独立同分布假设；复杂随机化可能使该假设失效，并导致不可信的方差估计和结论。 | 支持实验单位、分配机制、干扰与分析假设必须显式记录，且一次 A/B 结果需要统计与工程语境。 | 论文方法适合所有 Agent 任务、固定显著性阈值、样本量、业务指标，或离线任务集可直接等同线上用户实验。 |
访问日期均为 2026-07-17。CH42-REF-01 至 CH42-REF-03 分别复用正式引用 REF-009、REF-014、REF-109；CH42-REF-04 已由主线程登记为 REF-116。完整 URL 与外推禁区见本章参考资料。动态产品和在线工程资料在 First Draft、Technical Review 与 Fact Check 阶段必须重读。
本书 Release Experiment 模型
下列工件是本书为 Harness 变更设计的教学模型，不是 Google、OpenAI、SemVer 或 Microsoft Research 的现成 API、发布平台、实验系统或权限机制。
| 工件 | 最小内容 | 解决的问题 | 不承担的责任 |
|---|---|---|---|
| Harness Version Manifest | 候选 ID、父版本、工件摘要、模型/快照、依赖、评估规格、兼容性声明与不可变摘要。 | 让一次比较能回答“比较了什么”。 | 不证明内容安全、兼容或已经发布。 |
| Release Experiment | 基线、候选、固定任务集、分配单位、暴露范围、守护指标、停止条件、责任人与证据位置。 | 让离线评估、灰度与线上实验不被混为同一结论。 | 不执行随机分配、流量切分、模型调用或统计分析。 |
| Compatibility Matrix | 消费者、输入/输出契约、允许变化、破坏性变化、迁移与回退目标。 | 让版本号背后的实际兼容假设可审查。 | 不保证自然语言行为、第三方 API 或模型输出兼容。 |
| Release Decision Record | 证据版本、指标、未覆盖项、决定、批准范围和刷新条件。 | 防止 winner 或 approved 脱离证据复用。 | 不授予发布权限，也不表示外部动作发生。 |
| Rollback Runbook | 已知良好目标、触发条件、操作前检查、回退步骤、回读、残留效果、升级与停止。 | 区分“计划回退”“切换目标”和“验证恢复”。 | 不保证所有副作用可逆，不执行真实回滚或补偿。 |
状态与责任断点
- 版本存在不等于兼容。 只有 Compatibility Matrix 与消费方验证能支持受限兼容结论。
- 离线更优不等于线上更优。 固定任务集只覆盖声明的输入与评估规格；真实使用中的干扰、漂移和尾部风险仍未知。
- 批准灰度不等于已暴露。 Release Decision Record 记录一次决定；实际路由、模型调用、监控和效果需要独立执行与观察证据。
- 触发回滚不等于恢复完成。 只有回退目标已生效、关键状态已回读且残留效果已登记，才能给出受限的
rollback_verified。 - A/B 胜出不等于因果已证实。 分配、样本、干扰、指标选择、多重比较和分析假设都可能改变结论；本章不把统计标签当作自动发布许可。
计划案例、图示与纯内存示例
教学案例： 两种上下文压缩策略在同一组注入任务上比较。基线与候选必须绑定同一任务集版本、模型快照、评估规格和成本口径；先执行离线对照，只形成 offline_candidate、needs_evidence 或 rejected。即使候选在教学数据上更好，也只能进入人工审查的有限暴露计划。若守护指标下降，Rollback Runbook 只返回待执行的回退请求；本章不调用模型、路由真实流量、修改配置或制造线上效果。
计划图示： Mermaid 图展示 Version Manifest → Offline Evaluation → Release Decision → Limited Exposure → Monitoring 主链，并为兼容性缺口、证据不足、守护指标下降、回滚回读失败和人工升级分别保留出口。图中必须明确“候选通过 ≠ 已发布”“回滚请求 ≠ 已恢复”“对照差异 ≠ 因果结论”。
计划示例： Example Implementation 阶段可实现纯内存函数 assessHarnessReleaseExperiment(input)。它只读取注入的 manifest、baseline、candidate、evaluation、compatibility、exposure、guardrails 与 rollback 对象，返回 needs_evidence、ready_for_review、rollback_requested、rollback_verification_required 或保守停止。测试不得调用模型、网络、文件、Git、实验平台、特征开关、监控、发布或回滚工具。
风险、非范围与后续核验
- 伪版本语义： Prompt、Skill、工作流、模型和评估规格的变化速度不同；不得只用一个版本号掩盖工件级差异和依赖。
- 实验污染： 候选与对照共享缓存、记忆、外部工具、数据或用户状态时，结果可能互相影响；研究模型只能要求记录，不能保证隔离。
- 指标投机： 质量、成本、延迟和安全指标若在看到结果后更换，就不能支持原先的比较；但本章不规定跨项目统一指标或阈值。
- 不可逆副作用： 写入、消息、付款、权限、记忆和外部 API 调用可能无法随配置指针一起恢复；Rollback Runbook 必须登记残留效果与人工入口。
TODO(verify)：First Draft 当天重读 Google SRE Canarying、OpenAI Backwards Compatibility 与 Microsoft Research 页面；不沿用过期产品路径、示例模型名或动态声明。TODO(verify)：若正文加入统计显著性、功效、样本量、多重比较或序贯检验，必须新增对应原始统计资料；当前研究只允许说明假设与限制。TODO(verify)：Example Implementation 前确认仓库的 Node 纯内存示例惯例；没有授权和隔离时，不模拟真实流量、模型调用、特征开关或回滚。
下一阶段建议
Chapter Outline 应把版本身份、兼容矩阵、离线对照、实验隔离、有限暴露、守护指标、决定记录、回滚 Runbook 和残留效果拆成逐节蓝图。每节都要分开来源事实、本书工件、虚构压缩策略案例和未运行外部动作；不得把 canary、SemVer、模型快照或 A/B 论文改写为一套自动发布算法。