生产工程：迁移 API，并把故障分诊留在草稿层

生产系统最怕的不是慢，而是两件事一起失控

你让 Codex 升级 SDK，同时整理 Sentry、Slack 和 GitHub 里的故障。半小时后代码变了，候选工单也准备发送，可用户行为是否保持、三条告警是不是同一事故，仍没人证明。

迁移和分诊可以共享证据，但不能共享授权。 我们把它们拆成两条轨。

这节课要交付什么

这不是一份只需要读完的功能介绍。你要在真实但可控的环境中留下一个可以复查的结果，并且能回答三个问题：Codex 看到了哪些事实，它实际做了哪些动作，你用什么独立证据确认结果成立。

最终结果是：一份可回退的 API 迁移计划和不会自动改变外部状态的分诊流程。开始前先创建一份简短记录，把当前环境、目标、禁止动作和验收方式写下来。后面的命令、截图和修改都回到这份记录，不靠聊天窗口里的“应该已经好了”判断完成。

先看官方边界

官方生产系统案例把 API 迁移和故障分诊都当成受约束工程：迁移前应获取当前指南、识别响应形状与工具行为变化，并用 eval 保护用户结果；分诊先按需运行、去重和引用证据，调优后才考虑定时，而且早期输出应是草稿，不自动发消息、创建工单、指派负责人或重跑生产任务。

官方页面会随产品更新。教程引用的是当前可核对的能力与命令，不把界面位置、套餐权限或预览功能包装成永久承诺。你在自己的设备上看到不同按钮时，先核对官方页面和本机版本，再决定是否继续；不要用过期截图覆盖现场事实。

任务现场

旧 SDK 还能工作，但新接口改变了工具调用与响应结构；同一周，Sentry、Slack 和 GitHub 又出现三条看似相关的报错。若把“升级依赖”和“自动整理事故”塞成一个大任务，Codex 很可能同时改代码与外部状态。先拆成迁移轨和分诊轨，共享证据，不共享授权。

先把现场写成四行：工作目录或项目、当前版本或输入、允许动作、完成证据。如果其中任何一行只能写“让 Codex 自己看”，说明上下文仍然不够具体。Codex 可以帮助检查，但不能替你决定哪些数据能上传、哪个生产动作已获授权，或一个异常是否可以忽略。

动手前准备

冻结一组真实但脱敏的请求、响应和用户可见结果作为基线，记录当前依赖版本、环境变量契约与回退版本。对分诊准备只读导出：错误堆栈、时间、版本、相关提交和已有工单。让 Codex 先标记来源时效与缺口，不连接能够写入工单或聊天的凭据。

把练习放在可恢复的位置，保留原始输入，并记录开始时的状态。涉及代码时先看版本控制状态；涉及数据时先复制脱敏样例；涉及外部服务时先使用只读或草稿模式。准备工作看似慢，却能让失败变成一次可以解释和回退的实验。

第一步：只读建立基线

让 Codex 从当前官方指南和仓库实际调用点建立差异表：认证、模型或端点、请求字段、工具协议、流式事件、错误与重试、响应持久化。每项写出文件位置与用户风险。计划只纳入本次必须变化的部分，非必要重构进入后续清单。

这一阶段不要急着要求“直接修好”。先让 Codex 复述目标、列出它实际读取的来源，并指出还缺哪些证据。你要检查它有没有打开正确目录、有没有把搜索摘要当原文、有没有把旧日志误当当前状态。基线不可信，后面的修改越多，返工成本越高。

第二步：限制范围后执行

在隔离分支或工作区实现最小迁移。先更新类型和适配层，再逐个恢复测试。明确禁止修改生产密钥、执行数据库迁移或发布。分诊轨只生成候选事件表，按指纹、版本和时间窗口去重，给 P0–P3 建议但不自动指派；证据冲突时标记待人工确认。

执行指令应该同时包含目标、范围和停止条件。把“不要乱改”换成可观察边界，例如只允许修改两个文件、不安装依赖、不发送消息、不触碰生产数据。出现新的权限、需要改变既有契约或发现输入口径不一致时，要求 Codex 停下来报告，而不是自行选择更大的方案。

第三步：用独立证据验收

用同一组基线运行迁移前后 eval，比较成功率、结构、工具调用、延迟与错误语义。对候选事故抽样回查原始日志，计算重复率和误报率。只有迁移结果通过、回退仍可执行、分诊草稿足够克制，才进入人工发布或定时化评审。

验收必须尽量脱离生成答案本身：安装类任务看版本、路径和真实启动结果；界面任务看目标视口与交互；数据任务用独立计算和异常清单；安全任务用原始复现、补丁 diff 与回归测试。把通过、失败和未验证分开记录，未验证不是失败，但绝不能伪装成通过。

完整案例

支付助手迁移时，编译通过但流式工具事件顺序变化，旧 UI 一直等待不存在的结束信号。团队的基线 eval 捕获了“答案正确但按钮不再解锁”的行为差异。Codex 只修改适配层并加入回归样本。与此同时三条告警被同一 release SHA 归并为一个候选事故，草稿附原始链接，由值班工程师确认后才创建工单。

案例的重点不是复制同一句 prompt，而是观察决策顺序：先确定权威来源，再缩小动作面，最后让证据闭环。如果你的项目结构不同，保留这个顺序，替换文件名、命令和验收对象。任何会产生外部影响的步骤，都应在真正执行前再次获得明确授权。

故障诊所

只看编译成功会漏掉行为变化；回到用户可见基线和工具事件。搜索到旧文档时核对日期与官方域名。分诊重复率高时先修指纹和时间窗口，不急着用模型“更聪明地猜”。误报会产生外部噪声，因此保持只读和草稿。若迁移需要新数据变更或生产权限，暂停并拆成单独授权任务。

恢复时一次只改变一个变量。先保存错误原文和当前状态，再判断问题属于安装路径、权限、上下文、实现还是验收环境。不要连续重装、重写和切换工具，因为那会抹掉因果关系。修复后重复最小复现，再跑相邻路径，确认没有用一个新问题遮住旧问题。

迁移练习

选择一个无生产影响的 SDK 小版本升级，制作五个回归样本和回退说明。再从三个虚构来源整理十条告警，输出去重后的草稿表。要求同伴分别审查迁移证据和分诊克制性，不能用同一个“看起来合理”结论代替两种验收。

完成练习后，把其中的产品名和文件名遮住，只保留“输入—动作—证据—停止条件”。如果这四项仍能指导另一个任务，说明你学到的是方法；如果离开示例 prompt 就不会继续，回到任务现场，补出你真正依赖的判断规则。

先让结果可反驳，再让流程更自动

迁移用同一组 eval 比较前后行为；分诊用原始来源、去重率和误报抽样检验。两边都通过，仍不代表已经获得发布或外发授权。

当人工按需运行足够稳定，再讨论定时。自动化的成熟标志不是动作更多，而是错误更容易被看见和阻止。

完成检查

• 迁移依据是当前官方指南与仓库真实调用点
• 非必要重构、数据变更和生产动作已排除
• eval 比较用户结果、响应结构和失败语义
• 分诊只生成带来源的草稿且已抽样计算误报
• 我保留了开始状态、实际动作和最终证据
• 我把失败、未验证和已通过分开记录
• 需要新权限或外部影响时，Codex 会停下来询问