测试、变更与发布

一个生产级智能体系统可以在不进行代码部署的情况下发生变化。提供商可能退役一个模型别名。一次提示词编辑可能改变工具选择。一个检索策略可能暴露不同的证据。一个技能（Skill）、MCP 服务器、沙盒镜像、策略规则、评估器或上下文压缩模板，可能在应用程序二进制文件保持不变的情况下改变行为。

传统的发布纪律仍然重要：测试、构建溯源、部署自动化、分阶段发布、监控和回滚。但可发布的单元比单个工件更大。它是组装后的配置，塑造了模型介导行为（model-mediated behavior）以及组织愿意支持的操作性主张。

本章假设生产工程其他部分定义的评估证据、持久执行、安全控制、治理决策以及成本/容量目标均已就绪。它的任务是将这些内容与变更的机制联系起来。

论文

一个安全的智能体发布，是从一个完整系统配置到另一个完整系统配置的受控过渡。它需要对契约和不变量的确定性测试、每个行为塑造资产的版本化记录、存储状态和集成的兼容性检查、模型介导行为的评估证据、带有回滚触发器的分阶段暴露，以及一个在系统变更后仍可重建的发布决策。

发布安全性并非由一个绿色构建、一个更好的基准测试分数或一个模型提供商的发布说明来证明。这些可能是有用的证据。只有当团队能够解释发生了什么变化、哪些声明经过了测试、哪些用户和效果被暴露、哪些回滚路径可用，以及哪个负责人接受了剩余的不确定性时，发布决策才更可靠。

定义可发布的配置

从每次实质性变更开始，进行配置清单记录。至少记录：

配置元素	与发布相关的变更示例
应用程序代码和基础设施	运行框架逻辑、编排、队列、沙盒、部署镜像、功能开关
模型配置	提供商、模型标识符、API 版本、参数、路由规则、回退行为
提示词和上下文规则	系统指令、模板、压缩、检索过滤器、记忆包含、工具描述
工具和执行边界	模式、参数验证、权限、幂等行为、超时和重试策略
策略和防护栏	授权规则、分类器、阈值、阻断或放行行为、审批要求
状态和数据	模式版本、迁移、记忆存储、检索索引、固件、缓存摘要
评估和测试资产	任务套件、评分器、数据集、运行框架版本、黄金追踪记录、预期输出
依赖和供应链	SDK、MCP 服务器、插件、技能、浏览器、解释器、容器、外部 API
运营控制	可观测性、告警、发布门禁、容量限制、事件处理手册、运行手册

OpenAI 关于可信智能体评估的文章强调，经过测试的系统包括提示词、工具、安全防护、预算和环境，而不仅仅是模型名称（OpenAI, 2026）。发布记录也需要同样的完整性。对发布流程不可见的行为变更，对用户来说仍然是变更。

按变更可能失效的声明进行分类：

契约变更： 输入、输出、模式、授权、幂等性或状态语义发生变化；
行为变更： 模型、提示词、上下文、路由、工具描述或策略改变了预期决策；
数据变更： 检索语料库、记忆、标签、固件或评估用例发生变化；
控制变更： 防护栏、审批、速率限制、可观测性或发布规则发生变化；
依赖变更： 提供商、SDK、运行时、浏览器、工具服务器或外部 API 发生变化；以及
运营变更： 规模、地域、租户、工作负载等级、权限或用户群体发生变化。

并非每次编辑都需要委员会审批。但每次实质性变更都应留下足够证据，以便未来的工程师了解什么被提升了以及为什么。

在确定性属于的地方使用确定性测试

模型输出的可变性并非测试不稳定的借口。许多发布失败是围绕模型的确定性缺陷：

提示词模板渲染、所需变量、转义和长度限制；
模式验证、枚举处理、数值范围和结构化输出解析；
工具参数规范化、授权、所有权和状态版本检查；
上下文组装中的包含、排除、排序、编辑、出处和预算规则；
路由资格、回退条件、超时路径和重试预算；
针对格式错误、未授权、过期、重复或延迟请求的执行边界行为；
检查点迁移、恢复兼容性、取消以及租约或 fencing token 强制；
遥测字段、关联标识符、审计记录和发布标签；以及
当模型、评估器、分类器、工具或依赖不可用时的失败行为。

这些测试应该是普通的单元测试、属性测试、模式测试、契约测试和集成测试。它们应该足够快，以保护日常变更。除非明确目的是集成覆盖，否则它们不应调用外部模型。

使用固定固件测试运行框架。从先前运行中捕获的模型转录可以成为重放输入，用于解析、状态转换、工具选择和证据处理。测试并不断言未来模型会产生相同的词语。它断言确定性系统安全地处理已知输入。

保持黄金输出范围狭窄。精确字符串比较对于渲染的提示词、JSON 模式、策略记录和迁移输出很有用。对于开放式文本，它们通常很脆弱。对于文本和任务结果质量，应使用评估系统的任务、试验、评估器和不确定性机制，而不是将语义判断隐藏在单元测试中。

在效果边界测试集成

智能体系统在边界处失败：身份、数据、工具、沙盒、外部 API、存储、队列和人工审批。集成测试应测试契约，而不仅仅是快乐路径。

对于每个关键接口，测试：

有效和无效参数，包括边界值和缺失字段；
按主体、租户、目的、资源、目的地和当前状态进行的授权；
幂等键、重复尝试、未知结果、延迟回调和核对并纠正钩子；
超时、重试、取消和预算耗尽行为；
部分响应、格式错误响应、依赖错误和降级模式；
日志记录、追踪、指标、审计字段和敏感数据编辑；以及
该边界处的回滚、禁用或终止开关行为。

优先使用受控测试租户、服务替身、沙盒和可重放快照，而不是真实的实际结果。但替身必须保留发布所依赖的语义。一个总是成功的伪造支付 API 无法测试重复效果预防。一个具有不受限制网络访问的伪造浏览器无法测试出站策略。

语义化版本控制（Semantic Versioning）围绕公共 API 和破坏性变更定义兼容性（SemVer 2.0.0）。智能体系统需要为工具 API、模式、事件格式和外部集成应用这种纪律。它们还需要为 SemVer 未涵盖的行为明确兼容性：提示词假设、模型路由器资格、上下文约定、存储记忆和评估器解释。

版本化行为塑造资产

为每个可能改变行为的资产使用稳定标识符。诸如 latest、default、production prompt 或 current policy 之类的标签不足以作为发布证据。

记录：

确切的模型标识符、提供商、API 版本、推理设置、路由和回退规则；
提示词模板、工具描述、系统指令、上下文规则和压缩逻辑；
策略和防护栏版本、阈值、分类器配置和失败行为；
工具、MCP 服务器、插件、技能、沙盒、浏览器、解释器和依赖版本；
检索语料库、记忆存储、嵌入模型、索引构建、过滤器和新鲜度规则；
状态模式、迁移脚本、工作流定义、检查点格式和事件版本；
评估套件、数据集、固件、评估器、评分标准和门禁阈值；以及
功能开关、暴露规则、发布队列和例外记录。

提供商 API 以不同方式使版本控制显式化。Anthropic 请求携带一个 API 版本头文件和模型标识符，这些应与发布候选版本一起记录（Anthropic API versioning；model overview）。OpenAI 的模型和评估面同样是产品依赖项，应在发布证据中固定或标识，而不是视为非正式背景（OpenAI API 文档）。确切的提供商字段和弃用日期是易变的；当它们重要时，应保留在发布记录或注明日期的现场笔记（Field Notes）中。

构建溯源有助于系统的软件部分。SLSA 溯源记录构建元数据，例如工件、构建器、源代码和依赖项（SLSA Provenance v1.1）。智能体发布溯源应将此概念扩展到行为塑造配置和评估证据。重点不是官僚主义，而是能够在事件或退化发生后回答：“我们实际发布的是哪个系统？”

在发布前决定兼容性

兼容性是一个发布决策，而非一种希望。要问新旧版本必须安全共享哪些内容：

请求、响应、webhook 和外部 API 契约；
工具参数和结果；
事件、追踪、日志、指标和审计记录；
数据库模式、检索索引、向量存储、缓存和记忆记录；
检查点、持久定时器、进行中的尝试、审批和子运行；
提示词、上下文字段、引用、摘要和派生视图；
评估任务和预期证据；以及
用户可见的声明、解释、控制和支持工作流。

对于每个变更的边界，选择一条明确的路径：

兼容性路径	适用场景	需管理的风险
向后兼容	旧的生产者或消费者可以安全继续	尽管形状未变，但存在隐藏的语义漂移
双读或双写	迁移期间新旧状态必须共存	分歧、成本翻倍和清理失败
固定延续	进行中的工作必须在旧配置下完成	提供商弃用、安全修复和操作复杂性
迁移后延续	存储的工作可在测试迁移后恢复	状态损坏、审批变更和过时假设
显式拒绝或升级处理	无法保证兼容性	用户中断和手动积压
破坏性发布	运营声明有意改变	沟通、支持和回滚限制

长时间运行的任务使兼容性变得具体。在一个提示词、策略、工具模式、审批范围和模型路由下创建的检查点，在另一个环境下可能不安全。发布应要么将符合条件的运行固定到旧配置，要么通过测试代码迁移它们，要么以真实解释停止它们。不要在新政策或新目标下静默重新解释旧的审批。

评估兼容性也很重要。一个候选版本可能因为评估器、任务集、环境或评分标准的变化而看起来更好。当测量系统改变时，记录发布决策是与固定基线、迁移基线还是新声明进行比较。

组装发布证据

一个发布候选版本应有一个单一的证据记录。它不一定需要是一个工具或仪表板，但它应该能够回答发布问题，而无需翻查聊天记录。

记录：

候选配置和不可变标识符
变更摘要和实质性变更分类
受影响的用户、租户、工作负载、数据、权限和集成
确定性测试结果
集成、契约、迁移和重放结果
评估门禁结果和已知有效性限制
安全、隐私、容量和可观测性检查
兼容性决策和迁移/回滚计划
发布阶段、爆炸半径限制和停止标准
决策负责人、审查者、例外、理由和时间戳
监控链接和发布后审查结果

评估系统章节负责设计质量门禁。本章要求这些结果与候选配置相关联。Anthropic 当前的评估文章将自动化评估、转录审查、CI、生产监控和人工审查视为互补的证据来源，而非一种万能证明（Anthropic, 2026）。发布记录应保留这种区别。

不同的过渡需要不同的深度：

只读内部助手的一个提示词拼写错误，可能只需要冒烟测试和抽样审查；
高流量支持代理的模型路由变更，可能需要配对评估、延迟/成本检查和一个金丝雀版本；
一个新的可写工具，可能需要安全测试、授权审查、幂等性测试、分阶段暴露和风险签批；以及
一个检查点模式迁移，可能需要恢复测试、双版本恢复测试以及一个回滚或隔离计划。

不要在看到一个糟糕结果后更改门禁阈值并称之为测试更新。那是一个策略或发布决策。保留旧证据，命名新理由，并重新运行任何受影响的比较。

有目的地分阶段暴露

渐进式交付减少爆炸半径并在真实条件下创建证据。有用的阶段包括：

阶段	目的	典型防护
开发和 CI	捕获确定性缺陷和明显的行为退化	单元测试、契约测试、迁移测试、重放测试和小型评估套件
内部自用	在后果有限的情况下暴露真实使用	已知用户、清晰的反馈路径、有限的权限
影子模式	比较候选决策而不提交效果	只读执行、无用户可见操作、隐私控制
金丝雀	将一小部分符合条件的用户暴露给真实效果	严格的指标、快速回滚、有限的租户或工作负载等级
分阶段发布	在通过保留标准后增加暴露	逐步队列、监控窗口、停止点
全面可用	广泛支持该声明	运行手册、支持、容量、治理、发布后审查

Kubernetes 部署提供了一个具体的部署状态、暂停、回滚和修订历史的基础设施示例（Kubernetes）。智能体系统需要额外的门禁，因为行为可能通过非部署配置发生变化。如果所有流量已经通过共享运行时配置使用新的模型别名或提示词，那么仅针对代码的金丝雀是不够的。

功能开关在受治理时有用。OpenFeature 规范分离了开关提供者、评估上下文、钩子和结果，使得开关决策可以在不同实现之间保持一致和可观察（OpenFeature）。一个开关应标识什么行为发生变化、谁有资格、哪些证据证明扩大范围、何时过期以及如何失败。一个过时的永久开关变成了另一个未经测试的产品模式。

发布切片应与风险匹配，而非便利性。考虑按以下方式切片：

租户、用户组、地域、语言、工作负载等级和权限级别；
只读行为与可写行为；
可逆效果与不可逆效果；
低成本任务与高成本任务；
依赖路径、模型路由、上下文大小和工具集；以及
具有强大支持渠道的用户，先于那些缺乏有效救济途径的用户。

保留标准应包括正面和负面证据：已接受结果率、硬策略失败、安全拒绝、修正率、延迟尾部、单位有效结果成本、未知结果、回滚就绪状态、用户报告、支持联系人和事件信号。仅有活动不是就绪的证据。

在需要之前设计回滚

回滚是一种产品行为。它应在发布开始前被设计、测试和分配。

对于每次发布，决定：

哪些可以通过开关、路由、配额或终止开关立即禁用；
旧的模型、提示词、工具、策略、依赖和状态模式是否仍然可用；
新数据是否可以被旧版本读取；
进行中的运行、待审批、定时器、子工作和未知结果会发生什么；
哪些外部效果无法撤销，以及需要哪些补偿或通知；
缓存、记忆、检索索引和派生摘要如何失效或隔离；
监控如何确认回滚已停止损害；以及
谁可以命令回滚、前滚、暂停或部分遏制。

回滚通常是不完整的。一个糟糕的提示词可能已向记忆写入摘要。一个新工具可能已发送消息。一个迁移可能已转换了旧代码无法读取的状态。一个模型变更可能已创建了用户期望或支持承诺。在这些情况下，更安全的路径可能是前滚、隔离、补偿或手动审查。

以与发布相同的严肃性测试回滚。演练：

模式迁移后的回滚；
长时间运行任务正在等待时的回滚；
金丝雀已创建外部效果后的回滚；
防护栏或评估器已变更后的回滚；
提供商不可用或模型已弃用时的回滚；
过载期间当排队工作已过时时的回滚；
当候选版本和基线共享损坏数据时的回滚。

不要依赖重新部署旧代码作为唯一答案。如果行为由提示词、开关、数据、模型路由和提供商设置控制，那么回滚过程也必须控制这些。

从生产中的变更学习

当暴露达到 100% 时，发布工作并未完成。比较预期和观察到的行为：

发布是否如预期影响了已接受结果、修正、升级处理、事件、成本、延迟或容量？
哪些切片改进、退化或缺乏足够证据？
是否有任何防护栏、评估器、测试或告警产生了虚假信心？
回滚触发器是否清晰且可操作？
功能开关、提示词和临时例外是否获得了负责人和到期日期？
生产故障是否变成了新的测试、评估用例或发布标准？

Google SRE 关于发布工程的章节强调自动化、小变更、渐进发布、监控和回滚是发布工程的纪律，而非最终文书工作（Google SRE, 2016）。DORA 的四个关键指标跟踪部署频率、变更前置时间、变更失败率和失败部署恢复时间（DORA）。它们是有用的发布流程信号，但不能替代 AI 特定的证据。一个团队可以快速部署，但仍然发布不受治理的模型行为。

使用额外指标跟踪智能体发布健康度：

未版本化的提示词或策略编辑；
过时的开关和隐藏的发布模式；
没有完整配置记录的发布；
由于兼容性问题受阻的进行中运行；
因状态或提供者假设变更而失败的回滚；
未添加到测试或评估中的生产故障；
超出其到期时间的例外；
在预期发布切片之外观察到的候选行为；以及
与发布变更相关的用户修正、申诉或支持问题。

目标是建立一个能够学习的变更系统。每次退化都应要么改进预防，要么改进检测，要么澄清一个已接受的风险，要么缩小运营声明。

权衡

选择	好处	成本或风险
固定每个行为塑造资产	强大的可重现性和回滚证据	运营负担、提供商弃用和更慢的安全更新
使用模型/提供商别名	更易更新，更少的配置变更	静默行为漂移和较弱的发布归因
许多小发布	更小的差异和更快的诊断	更多协调开销和隐藏的累积漂移
大型捆绑发布	更少的仪式和更易的跨系统协调	更难的归因、回滚和证据覆盖
严格的兼容性要求	保护进行中的工作和集成	减缓破坏性改进和迁移清理
激进的分阶段发布	在真实条件下更快学习	在信心强之前更多的用户暴露
繁重的发布前门禁	更少的已知退化逃脱	反馈缓慢和绕过门禁的动机
回滚优先策略	快速遏制可逆变更	当状态或外部效果无法回滚时产生虚假信心
前滚优先策略	处理不可逆迁移和提供商漂移	需要快速诊断和强大的发布工程

没有一种节奏适合所有系统。将发布严谨性与后果、可逆性、暴露、不确定性以及组织检测和响应能力相匹配。

失效模式

不可见的提示词发布

一个提示词通过管理界面更改，改善了一个演示，并在没有版本、评估运行或回滚路径的情况下进入生产。后来发生的事件无法追溯到那次编辑。

围绕一个损坏的智能体的绿色构建

单元测试仅覆盖代码路径，因此通过。工具模式、模型路由、上下文规则或评估器发生了变化，但没有集成或行为证据覆盖真实系统。

仅基准测试的推广

一个候选模型在通用基准测试上得分更高，但产品的工具使用、延迟、拒绝行为、上下文长度、安全控制和目标语言未经过测试。

过时的功能开关

一个金丝雀开关变成了永久性的。几年后，一个租户仍然运行着一个旧的提示词和策略组合，当前没有测试或操作员能理解。

无法读取状态的回滚

一个发布迁移了检查点或记忆。当行为退化时，旧版本无法安全地恢复新运行，因此“回滚”造成了更多失败。

静默的提供商变更

系统依赖于一个模型别名、SDK 默认值、托管工具或外部 API 行为，这些在团队发布记录之外发生了变更。操作员看到漂移但无法重建候选版本。

无界金丝雀

一个金丝雀按流量百分比很小，但包括高权限任务。一次失败在指标显得显著之前就造成了实际外部损害。

被遗忘的评估器变更

团队更改了一个评分器提示词，并庆祝了发布改进。系统并未改进；测量仪器发生了移动。

本手册的判断

将发布候选版本视为一个完整的行为塑造配置。
对契约、状态、策略和边界保持严格的确定性测试。
使用评估门禁处理模型介导行为，并保留其有效性限制。
对每个可能改变行为的提示词、模型路由、工具契约、策略、数据源、评估器和依赖进行版本管理。
在发布前决定存储状态、进行中工作、集成、评估和用户承诺的兼容性。
按后果和权限分阶段暴露，而不仅仅是按流量百分比。
在扩大发布前定义回滚、前滚、终止开关、隔离和补偿路径。
保留一个发布记录，将候选配置、证据、决策负责人、例外和监控联系在一起。
将生产故障反馈到测试、评估、防护栏和发布标准中。

检查清单

参考文献及其使用方式

Anthropic API 版本控制和模型概述 - Anthropic 维护的 Claude API 与模型标识符产品文档，用于说明为什么提供商 API 版本和模型标识符是必须记录的发布输入。文档是产品特定且易变的，因此确切的弃用日期和接口细节应属于发布记录或注明日期的领域笔记，而非长期不变的章节结论。
Anthropic, “Demystifying evals for AI agents” - Anthropic 工程文章，用于支持结合自动化评估、转录审查、CI、生产监控和人工审查的分阶段证据节奏。它报告的是提供方经验，而非独立的发布工程标准。
DORA, “DORA metrics: the four keys” - DORA 交付绩效资料，用于发布流程健康度量，如部署频率、变更前置时间、变更失败率和恢复时间。这些指标本身并不能证明负责任的 AI 行为或产品质量。
Google SRE, “Release Engineering” - Google SRE 章节，用于支持自动化、小变更、渐进发布、监控、回滚和发布后学习作为发布工程纪律。它来自大型服务可靠性实践，并非智能体特定。
Kubernetes Deployments - Kubernetes 项目维护者文档，作为已部署应用版本的发布状态、暂停、回滚和修订历史的具体示例。基础设施发布机制必须通过智能体特定的检查（提示词、模型、状态、工具和评估证据）进行扩展。
OpenAI, “A shared playbook for trustworthy third party evaluations” - OpenAI 研究与工程文章，用于说明将经过测试和发布的系统视为包括提示词、工具、安全防护、预算和环境的完整配置，而非仅模型名称。该文章侧重于第三方评估，因此本章将配置原则应用于发布记录。
OpenAI Evals API 文档 - OpenAI 维护的 API 文档，面向 OpenAI 评估工具和模型接口面；本章用它说明这些接口面是发布依赖项，其配置应被固定或标识。产品文档随时间变化，因此确切的 API 字段应捕获在发布记录或领域笔记中。
OpenFeature 规范 - CNCF 规范，用于将功能开关建立在提供者、开关、上下文、钩子和结果概念之上，而非分散的临时条件。该规范支持受治理的暴露机制，但本身不保证安全发布。
语义化版本控制 2.0.0 - 公开规范，用于围绕公共 API、模式和工具契约的兼容性语言。SemVer 不涵盖模型行为漂移、提示词、数据集、策略、记忆或评估器解释。
SLSA 溯源 v1.1 - 供应链规范，作为可重建构建和工件溯源的模型。智能体发布记录需要额外的字段，用于行为塑造配置、评估证据、发布决策和运营声明。