让 AI 自己修自己：Codex 的迭代修复闭环工作流

文档腐化：每个技术团队都在经历的慢性死亡#

你写过技术文档吗？如果你写过，你一定经历过这个循环：

花了两周精心编写了一套 API 教程，代码示例跑得通，解释清晰，连边缘情况都考虑到了。三个月后，API 升级了 v2，你的文档里还在用 v1 的调用方式。六个月后，有人提了个 Issue：「这个示例跑不通。」你点开一看，发现依赖的库已经 breaking change 了三次。

这不是你的错。文档腐化（documentation rot）是软件工程的系统性问题。代码在演进，API 在迭代，但文档是静态的，它只存在于被写下的那个瞬间。之后每一次 SDK 升级、每一次接口废弃、每一次最佳实践的变更，都在悄悄地把文档推向「过时」的深渊。

大公司有专门的文档团队。小团队呢？靠记忆。靠用户提 Issue。靠「等有空了再说」。

OpenAI 自己也面临这个问题。他们的 Cookbook 仓库里有数百个 Jupyter Notebook，涵盖从向量数据库到函数调用的各种示例。API 从 client.chat.completions.create 进化到 client.responses.create，模型名从 gpt-4 变成了 gpt-5.5，嵌入模型从 text-embedding-ada-002 升级到了 text-embedding-3-large。每一个变更，都意味着一批 Notebook 悄悄过时。

2026 年 5 月，OpenAI Cookbook 团队发布了一套全新的方案：让 Codex 自己修自己。不是让 AI 写新文档，而是让 AI 检测旧文档的问题、针对性修复、运行验证、根据验证结果再修复，如此循环，直到文档真正可用。

这个模式被称为「迭代修复闭环」（Iterative Repair Loop），它不仅仅适用于文档维护。任何能让 AI 产出内容、又有客观验证手段的场景，都能套用这个模式。

核心架构：三步闭环#

整个工作流的结构出奇地简单。三步，一个循环：

Review（审查）→ Repair（修复）→ Validate（验证）→ 回到 Review

但简单不等于简陋。这个架构的每一环都有精心设计的约束，让 AI 的行为可预测、可审计、可复现。

第一步：Review，只看不改#

Review 阶段的目标很纯粹：读一遍当前内容，给出结构化的发现，但绝不修改任何文件。

为什么不让 AI 直接改？因为「先看清楚再动手」是人类工程师的直觉，对 AI 同样适用。当你让 AI 同时做「发现问题」和「修复问题」两件事时，它的注意力会分散，容易做出表面光鲜但经不起验证的修改。

OpenAI 的做法是：把 Notebook 内容（代码 + 文字）、业务规则（business rules）、以及期望的输出格式（JSON Schema）一起发给 Codex。Codex 读完，返回一个结构化的 findings 数组：

{
  "findings": [
    {
      "artifact": "qdrant_embeddings_search.ipynb",
      "issue_type": "deprecated_api",
      "severity": "high",
      "description": "cell 2 使用了 client.chat.completions.create，当前 API 已迁移到 client.responses.create",
      "suggested_fix_direction": "替换为新 API 调用方式"
    },
    {
      "artifact": "getting_started_evals.ipynb",
      "issue_type": "stale_model_name",
      "severity": "medium",
      "description": "模型名 'gpt-4' 已过时，建议更新为 'gpt-5.5'",
      "suggested_fix_direction": "全文替换模型名"
    }
  ]
}

关键点：输出是机器可读的 JSON。这让下一步的修复阶段可以直接消费这些 findings，不需要从一大段自然语言里提取行动项。

第二步：Repair，精准手术#

Repair 阶段的输入有两样东西：Review 的 findings，再加上上一轮 Validate 的 remaining_delta（还有哪些问题没解决）。Codex 拿到这些信息后，对目标文件进行聚焦修改。

这个阶段有一个重要约束：修的是副本，不是原件。每个迭代都会创建新的 artifact 副本，原始文件保持不变。这意味着你可以随时回滚，也可以对比每一轮修改了哪些内容。

Codex 使用 codex exec 在 headless 模式下执行修复，返回结构化的修复摘要：

{
  "artifact": "qdrant_embeddings_search.ipynb",
  "iteration": 1,
  "changes_made": [
    "cell 2: client.chat.completions.create → client.responses.create",
    "cell 3: 更新 embedding 模型名为 text-embedding-3-large",
    "cell 4: qdrant.search → qdrant.query_points"
  ],
  "unresolved_items": [],
  "updated_artifact_path": "/tmp/runs/iteration_1/qdrant/updated.ipynb"
}

第三步：Validate，铁面无情的法官#

这是闭环最关键的一环。很多 AI 工作流到「修复」就停了，觉得「AI 改过了 = 问题解决了」。但改过和改对是两回事。

Validate 阶段做两件事：

执行验证：把修复后的 Notebook 用 jupyter nbconvert --execute 从头跑到尾。代码真的能跑通吗？跑不通就失败了，不需要任何主观判断。
语义验证：让 Codex 当评委，对照着业务规则和验证案例，判断修复后的内容是否满足质量标准。比如：「API 调用是否使用了最新模式？」「新读者能否从零环境跑通？」

两轮验证的结果合并，生成 remaining_delta：

{
  "overall_passed": false,
  "cases": [
    {"name": "api_modernization", "passed": true, "feedback": "API 调用已更新"},
    {"name": "setup_reproducibility", "passed": false, "feedback": "cell 1 缺少 pip install 步骤"}
  ],
  "remaining_delta": [
    "需要在第一个 cell 中添加依赖安装指令"
  ]
}

如果 overall_passed 为 false，remaining_delta 就作为下一轮 Repair 的输入。循环继续。

实战演示：三个 Notebook，三种难度#

OpenAI Cookbook 团队准备了三个故意植入了过时内容的 Notebook：

Notebook	问题深度	预期迭代次数
Qdrant 向量搜索	浅层：API 名称过时，模型名陈旧	1 轮
Evals 评估入门	中层：API 模式过时 + 结果文件占位符	2 轮
知识检索函数调用	深层：API 形状变更 + 本地运行配置 + 教学流程保留	3 轮

三个案例并行处理，互不干扰。

第 1 轮迭代：Qdrant 案例直接通过。Evals 和知识检索案例未通过，但它们各自获得了精确的 remaining_delta，告诉下一轮修复究竟差在哪里。

第 2 轮迭代：Evals 案例在看到验证反馈后通过。知识检索案例的 remaining_delta 从 3 条缩小到 1 条。

第 3 轮迭代：知识检索案例通过。三个 Notebook，全部修复完成。

真正值得关注的不是「AI 做了修改」这件事，而是 remaining_delta 在逐轮缩小。第 1 轮 3 条未解决问题，第 2 轮变成 1 条，第 3 轮归零。这个收敛过程说明修复是有效的、定向的，不是随机尝试。

让闭环可审计：record.json#

自动化最怕「黑箱」。AI 改了文件，你怎么知道改了什么、为什么改、改完之后验证过了吗？

这套方案在每个迭代的每个案例目录下保存一个 record.json 文件：

{
  "review": [{ "issue_type": "deprecated_api", "severity": "high" }],
  "repair": {
    "changes_made": ["更新了 API 调用方式"],
    "updated_artifact_path": "/tmp/runs/iteration_1/qdrant/updated.ipynb"
  },
  "validation": {
    "passed": true,
    "remaining_delta": []
  }
}

这个文件回答了维护者关心的四个问题：

Review 发现了什么？
Codex 修改了什么？
修改后的东西能跑吗？
还有哪些问题没解决？

有了这个审计轨迹，维护者不需要打开中间产物逐个对比 diff。直接看 record.json 就能判断：这个修改能不能合入主分支。

何时停止：循环的终止条件#

生产环境不能永远循环。这套方案定义了四种停止条件，满足任一即停：

验证通过：overall_passed = true，所有 delta 清零。最理想的终止条件。
达到最大迭代次数：防止无限循环。演示中设为 3 轮。
Delta 不再变化：连续两轮的 remaining_delta 相同，说明 AI 在当前约束下已无法改进。需要人工介入，调整业务规则或验证标准。
需要人工决策：某些修改涉及 trade-off（比如「保留教学流程」vs「完全现代化写法」），AI 无法独自判断哪个方向更合适。

这套停止条件的设计非常务实：它承认 AI 有边界，把边界之外的事情交还给人类。

不止于文档：这个模式还能做什么#

Notebook 修复只是教学用例。三阶段闭环的核心思想是「AI 做改动 + 客观反馈机制 + 基于反馈的迭代改进」，这个模式可以迁移到很多场景：

协议优化：AI 起草一版协议更新，验证器检查是否符合法规和合规要求，不符合的部分作为 delta 进入下一轮修改。

代码重构：AI 做重构，CI 跑测试，失败的测试用例直接变成下一轮的 remaining_delta。

配置管理：AI 更新 k8s 配置，schema validator 检查语法，dry-run 检查运行时行为，问题反馈进入下一轮。

内容审核：AI 修改文案，brand checker 检查语气和风格一致性，不匹配的条目作为 delta。

共性是什么？有一个客观的、可自动化的验证标准。只要你能定义「什么叫做好」，就能把 AI 放进这个闭环里让它自己迭代到好为止。

对 AI Agent 工作流设计的启示#

这篇文章表面上在讲文档修复，实际上它示范了一个更宏大的设计哲学：

不要让 AI 一步到位。给它一个循环，给它反馈，让它迭代。

人类工程师也不是一次写出完美的代码。我们写，编译，报错了改，测试失败了修，review 提了意见再改。AI 也是一样。单次生成的输出往往是 70 分的水平，但加一个验证反馈的循环，就能把 70 分推上 90 分。

第二个启示是结构化交接。Review → Repair → Validate 三个阶段之间传递的都是 JSON，不是自然语言。这意味着每个阶段都有明确的输入契约和输出格式，不会出现「上一步说了什么但下一步理解偏了」的问题。

第三个启示是审计优先。record.json 的存在让自动化不再是黑箱。在 AI 越来越多地参与生产环境的今天，可审计性不是锦上添花，是准入门槛。

总结#

OpenAI Cookbook 团队的这套迭代修复闭环方案，本质上是一套可复现的 AI Agent 工作流设计模式：

Review 发现问题，不改文件
Repair 精准修复，只改副本
Validate 执行 + 语义双重验证
remaining_delta 形成闭环，驱动下一轮改进
record.json 提供完整审计轨迹
明确的停止条件 防止无限循环

这套模式不依赖任何特定的模型或工具。Codex 可以替换为其他 Agent，Notebook 可以替换为任何可验证的内容类型。核心价值在于架构思想：把 AI 从「单次生成」升级为「闭环迭代」。

下次你面对一批过时的文档、一堆需要重构的代码、或任何一个需要 AI 反复打磨的任务时，记住这个模式。

不要问 AI「能不能一次做好」。

给它一个 Review-Repair-Validate 的循环，它会自己修好自己。

参考来源：OpenAI Cookbook — Build iterative repair loops with Codex，作者 Shreekant Agrawal，发布于 2026 年 5 月 11 日。