OpenAI-Codex-CLI-智能体编程实战指南-六-

OpenAI Codex CLI 智能体编程实战指南（六）

原文：Agentic Coding with OpenAI Codex CLI

译者：飞龙

协议：CC BY-NC-SA 4.0

这比早期的基准（如 HumanEval 或 MBPP）要难得多。⁽²²¹^) 模型必须在陌生的代码库中导航，理解跨文件交互，并生成一个满足由另一位工程师为不同目的编写的测试的补丁。当 SWE-bench 推出时，这些特性使其成为真正的诊断工具。

SWE-bench Verified 与污染问题

2024 年 8 月，OpenAI 发布了 SWE-bench Verified，这是一个包含 500 个人工验证任务的集合，取自原始的 2,294 个任务。⁽²²²^) 它迅速成为比较智能体的事实标准。分数在 2025 年稳步上升。各厂商竞相冲击排行榜榜首。

随后审计开始了。

到 2026 年初，已发布的审计和厂商对 SWE-bench Verified 的谨慎态度证实了许多人的猜测：前沿模型可以复现 Verified 子集任务的金标准补丁，且一些困难任务的测试因错误的原因而通过。

该基准仍能区分较弱和中等水平的模型，但对于前沿模型 Verified 分数超过约 60% 的情况，请抱以真正的怀疑态度。该数字在衡量某些东西；只是不清楚有多少是真正的推理，有多少是记忆。

这是 古德哈特定律 正在实时上演：

当一种衡量标准成为目标时，它就不再是一个好的衡量标准。

Verified 一成为主要排行榜指标，实验室就直接针对它进行优化：在类似任务上微调、调整脚手架以适配评估工具，以及将临近基准的代码纳入训练数据。结果是分数不再能在前沿水平上进行有意义的区分。基准本身没有失效；它是被古德哈特化了。

污染问题并非 SWE-bench 独有。HumanEval 分数超过 90% 的也应持类似怀疑态度。任何公开存在足够长时间的基准都会成为训练目标。

SWE-bench Pro：诚实的度量

SWE-bench Pro 旨在解决 Verified 的结构性弱点。差异显著：

1. 1,865 个任务，而非 500 个

2. 多语言范围，不再局限于 Python

3. 平均补丁跨度 107 行、涉及 4.1 个文件，而 Verified 的中位数仅为每个补丁 4 行

4. 任务源自 GPL 许可和专有代码库，为训练数据收录设置了法律障碍

5. 一个仅在 Scale Labs 排行榜可见的私有保留子集，防止脚手架团队针对评估集进行调优

由此产生的分数令人谦卑。Claude Opus 4.5 在 Verified 上得分 80.9%，但在 Pro 上仅得 45.9%：同一模型、同一能力，得分约减半。⁽²²³^) 在私有子集上，差距进一步扩大：Claude Opus 4.1 从 22.7% 跌至 17.8%，GPT-5 从 23.1% 跌至 14.9%。这些下降是目前最清晰的信号，表明 Verified 分数的很大一部分反映的是记忆而非泛化。

具体针对 Codex CLI，使用带有 OpenAI 自身智能体脚手架的 gpt-5.3-codex，OpenAI 报告其在 SWE-bench Pro（公开集）上得分为 56.8%（撰写当时）。在采用标准化脚手架的 Scale AI SEAL 排行榜上，GPT-5 (High) 得分 41.8%，GPT-5.2 Codex 得分 41.0%。这 10 到 15 个百分点的差距即为脚手架溢价，将在本章后面的脚手架效应部分讨论。

在比较基准分数时，务必核实该数字来自厂商自有脚手架还是标准化评估工具。对于同一底层模型，厂商报告的分数通常比独立标准化分数高出 4 到 12 个百分点。

Terminal-Bench 2.0：CLI 优先的基准测试

结构与动机

Terminal-Bench 2.0 来自 Laude Institute，采取了不同的方法。⁽²²⁴^) 它不再是针对孤立 Python 仓库的合成补丁，而是在 Docker 容器中运行的 89 个精选端到端任务上评估智能体。每个任务提供一条自然语言指令、一个沙箱环境，以及一个自动验证结果的测试脚本。

任务类别涵盖软件工程、机器学习模型训练、系统管理、安全、数据科学和网络安全。任务由 93 位贡献者众包而来，从 229 份提交中根据质量、难度和抗平凡解法能力筛选出 89 个。

这是最直接锻炼 Codex CLI 终端原生架构的基准。任务像真实工作一样：搭建训练流水线、调试故障服务、配置构建系统、在受控环境中利用已知漏洞。Docker 沙箱使污染在结构上更难：当任务是让实时服务正确运行时，你无法通过背补丁来应付。

当前分数

表 25-2. Terminal-Bench 2.0 排行榜（2026 年 4 月）

| 智能体 + 模型 | 分数 |

| --- | --- |

| NexAU-AHE + GPT-5.5 | 84.7% (SOTA) |

| LemonHarness | 84.5% |

| Capy + GPT-5.5 | 83.1% |

| Codex CLI + GPT-5.5 | 82.2% |

| Polaris | 82.2% |

| WOZCODE + Claude Opus 4.7 | 80.2% |

| TongAgents + Gemini 3.1 Pro | 80.2% |

| SageAgent + GPT-5.3-Codex | 78.4% |

OpenAI 的 GPT-5.5 发布报告称其在 Terminal-Bench 2.0 上得分 82.7%，这是一个厂商自测数字，勉强超过了 Anthropic 的 Claude Mythos Preview。⁽²²⁵^) 然而，在独立的 Terminal-Bench 2.0 排行榜上，Codex CLI + GPT-5.5 以 82.2% 接近榜首，落后于当前领跑者 NexAU-AHE + GPT-5.5 的 84.7%。厂商自报分数与其标准化排行榜名次之间的这种差距，正是本章警示的内容：切勿将自报数字视为排行榜名次。前沿竞争现在以零头之差计算，而非两位数的差距。

模型选择对 CLI 影响巨大，且默认配置可能未针对您运行的任务类型进行优化。将 Codex CLI 与当前前沿模型（如 gpt-5.5）而非旧款或较小模型搭配，可显著提高解决率。

Terminal-Bench 2.0 是最值得亲自运行的基准。Harbor 框架使其可复现，Docker 环境防止跨运行污染，完整运行成本约在 $1 到 $100 之间（取决于模型定价），低到足以将其作为常规评估步骤。

自行运行 Terminal-Bench

可通过 Harbor 框架运行基准。您需要 Python 3.12 或更高版本、Docker，以及您要测试的模型提供商的 API 密钥：

##### 安装 Harbor（PyPI 包名为 `harbor`；要求 Python 3.12+）
pip install harbor
##### 在 Codex CLI 上运行 Terminal-Bench 2.0
harbor run --dataset terminal-bench@2.0 \
  --agent codex-cli \
  --model openai/gpt-5.5 \
  --n-concurrent 4

Harbor 的 CLI 变化很快，因此在开始昂贵的运行前，请检查可用的数据集和过滤标志：

harbor datasets list
harbor run --help

这会生成结构化结果，您可以跨配置进行差异对比并随时间追踪。练习 3 将演示如何解读 Harbor 输出；目前，关键指标是按任务类别的解决率，而非总分。

脚手架效应

脚手架，即处理模型周围记忆管理、工具使用协议和重试逻辑的编排层，其重要性可与底层模型本身媲美。使用 Claude 4 Sonnet 的 Confucius Code Agent 在 SWE-bench 上达到 74.6%，超过了使用能力更强的 Claude 4.5 Sonnet 的 mini-SWE-Agent 变体。⁽²²⁶^) 更好的编排弥补并随后超越了整整一代模型的差距。

这直接影响你如何配置 Codex CLI。CLI 的原生子代理支持、AGENTS.md 上下文加载和 Hook 系统构成了你的脚手架层。一份编写良好的 AGENTS.md，能够界定代码库范围、明确测试运行约定并标记禁区目录，可作为持久上下文供模型在整个会话期间依赖。

一个在会话启动时预加载相关文档或近期 Git 历史记录的 SessionStart Hook，提供了将称职的基准测试表现与真实任务完成区分开来的基础信息。

配置 Codex CLI 时，你不仅仅是在选择模型，而是在配置脚手架。基准测试数字展示了上限；而你的 AGENTS.md 和 Hook 决定了你在特定工作负载下能离这个上限多近。

基准测试数字对你的团队究竟意味着什么

将基准测试分数转化为工具决策，需要供应商营销材料很少提供的校准。

将基准测试与你的工作负载相匹配

最常见的错误是将错误基准测试上的高分视为适配性的证据。在评估任何分数之前，先问问哪个基准测试最贴近你的实际工作。

表 25-3. 基准测试到工作负载的对齐

| 你的主要用例 | 最具预测性的基准测试 |

| --- | --- |

| Python 仓库中的 Bug 修复 | SWE-bench Pro（而非 Verified） |

| 终端自动化、DevOps、ML 流水线 | Terminal-Bench 2.0 |

| 多语言、多文件特性开发 | SWE-bench Pro 私有子集 |

| 绿地开发 | 目前尚无基准测试能很好地捕捉此场景 |

如果你的团队主要编写 Rust 微服务，仅针对 Python 的基准测试提供的信号有限。如果你的工作是基础设施自动化，即具有平台工程角色特征的 Shell 脚本编写、服务配置和流水线调试，Terminal-Bench 2.0 是唯一一个类似于你实际工作的已发布基准测试。

考虑脚手架膨胀

任何引用供应商自有脚手架的分数，相比标准化评估会膨胀 4 到 12 分。这不是欺诈：自定义脚手架确实能改进结果。但除非双方使用相同的测试框架进行测量，否则会导致供应商间的对比不可靠。

为了进行公平对比，请优先参考 SWE-bench 任务的 SEAL 排行榜数字，或明确指定了代理框架的 Terminal-Bench 结果。当你看到供应商声称“SWE-bench Pro 上达到 X%”时，你的第一个问题应该是：使用的是哪种脚手架？

Codex CLI 内的模型选择

鉴于当前的基准测试数据，Codex CLI 模型选择的实用层级从一个有效的本地默认值开始：

##### config.toml — 本地默认模型
model = "gpt-5.5"

对于需要规划、计算机使用或持久多会话上下文的广泛代理任务，gpt-5.5 是正确的起点。对于专业编码任务，尝试显式使用 gpt-5.4 并将其与你自己的基准测试套件进行对比。对于你按 Token 付费进行广泛探索的子代理任务，测试 gpt-5.4-mini 作为低成本候选。

Codex 不会根据 config.toml 中的 [model] 表路由任务类别。当你想要对比配置时，请显式更改模型：

codex -m gpt-5.5
codex -m gpt-5.4
codex exec --model gpt-5.4-mini "绘制此仓库地图并识别测试命令"

重要的习惯是记录每次基准测试运行所使用的模型，而不是假设 CLI 会根据任务类型推断出正确的模型。

运行你自己的基准测试

真正重要的唯一基准测试，是在你的代码库上、针对你的任务、在你的约束下的性能表现。

Terminal-Bench 2.0 的结构为构建你自己的微基准测试提供了有用的模板：

1. 识别 5 到 10 个有代表性的任务。 选择涵盖你实际要求 Codex CLI 执行的范围的任务：Bug 修复、特性添加和基础设施变更的组合。避免选择微不足道的简单任务或无限制的开放性任务。

2. 编写确定性的成功标准。 每个任务都需要一个测试脚本，能在无人工判断的情况下输出通过或失败。这是基准测试设计中最困难的部分，也是合成基准测试倾向于低估真实世界复杂性的原因：真实任务往往有多种有效解决方案，而可靠的自动化测试要求单一的可验证结果。

3. 容器化环境。 Docker 环境可防止跨运行污染并使结果可复现。每次运行使用相同的基础镜像；锁定依赖版本。

4. 针对多种配置运行。 至少将你当前的模型和 AGENTS.md 配置与一种替代方案进行对比。替代方案可能是不同的模型、不同的 AGENTS.md 结构或不同的 Hook 集合。

5. 跟踪成本以及解决率。 取决于你的吞吐量需求，每个任务花费 $0.50 且解决率 80% 的配置，可能优于每个任务花费 $4.00 且解决率 85% 的配置。

一个小型的基准测试目录赋予工作可重复的结构：

.benchmarks/
  task-001/
    README.md        # 自然语言任务描述
    setup.sh         # 将仓库重置为初始状态
    test.sh          # 成功时退出码 0，失败时退出码 1
    expected.md      # 关于预期行为的备注
  results/
    2026-04-23-gpt-5.5-default.json

每次都使用相同的结果字段：

| 任务 | 配置 | 通过/失败 | 轮次 | Token 数 | 成本 | 备注 |

| --- | --- | --- | --- | --- | --- | --- |

| | | | | | | |

SWE-EVO 基准测试（测试现有系统的持续演进而非一次性补丁）显示，GPT-5 搭配 OpenHands 得分 21%，而在 SWE-bench Verified 上得分 65%。^(²²⁷) 在商业和企业代码库上，最好的可用模型得分低于 20%。你的专有代码库很可能比任何已发布的基准测试都更难。为这一现实做准备。

目标不是一个可发布的排行榜数字。而是一个一致、可重复的信号，供你用来做配置决策，并在模型和脚手架演进时跟踪退化。即使只有五个任务的测试套件，也能比任何已发布的基准测试提供更多可操作的数据，因为它衡量的是你实际问题领域的性能。

将你的基准测试任务定义和结果存储在专门的仓库目录中（例如 .benchmarks/），与你的 AGENTS.md 一起纳入版本控制跟踪。随着时间的推移，当你更新 Codex CLI 配置时，你将能准确地看到性能何时以及为何发生了变化。

2026 年 4 月基准测试：CocoaBench、HiL-Bench 和 AAR

2026 年 4 月发布的三项同行评审基准测试通过关注代理如何失败而非做对什么，更新了评估格局。CocoaBench、HiL-Bench 和 AAR（惊人代理竞赛）研究共同为代理式编码工具提供了首个系统性的故障分类学，其结果挑战了关于代理在何处挣扎的一个普遍假设。

故障分类学

2025 年的主导叙事认为工具使用是主要瓶颈：如果代理无法调用正确的 API 或运行正确的命令，就会失败。这些基准测试推翻了该叙事。汇总所有三项研究的故障分类学揭示了不同的图景：

表 25-4. 代理故障分类学（2026 年 4 月基准测试）

| 故障模式 | 故障率 | 基准测试来源 | 启示 |

| --- | --- | --- | --- |

| 导航错误 | 27% 至 52% 的试验 | AAR | 代理迷路的频率远高于误用工具 |

| 多模态组合 | ~55% 的任务失败（45.1% 成功率） | CocoaBench | 组合视觉、搜索和代码的长时程任务依然脆弱 |

基准测试中的关键发现

| 发现 | 影响 | 来源 | 含义 |

| :--- | :--- | :--- | :--- |

| 帮助寻求判断 | 需要升级时损失巨大 | HiL-Bench | 无法判断何时寻求帮助的 Agent 表现急剧下降 |

| 工具使用错误 | 最不常见的故障模式 | AAR, CocoaBench | 目前大多数基准测试的焦点——工具使用，极少成为瓶颈 |

这种反转很明显：导航，而非工具使用，才是主要的故障模式。 一旦找到正确的文件，Agent 就能熟练地正确调用工具。它们失败的地方在于到达正确的位置。

AAR：37.2% 准确率，导航是瓶颈

AAR 研究评估了在交织工具使用与多步导航的任务上的 Agent，其副标题“强工具使用者，弱导航者”精准概括了结果。[²²⁸] 核心数据令人清醒：最优 Agent 仅达到 37.2% 的准确率，且导航错误占主导，根据任务复杂度不同，占试验总数的 27% 至 52%，远超工具使用错误。AAR 在谜题与检索场景而非源代码仓库中衡量导航，但该模式直接迁移至代码库工作：Agent 一旦到达正确位置便能熟练调用工具，但到达该位置的能力薄弱。

对于 Codex CLI 用户，实际启示明确：提升 Agent 性能的最高回报投资，是改进导航辅助。 AGENTS.md 中的文件映射（参见第 4 章）、结构良好的目录布局、显式路由规则，能缩小 Agent 必须导航的搜索空间，直接针对主要故障模式。

CocoaBench：多模态组合 55% 失败率

CocoaBench 评估统一 Agent 在单一连贯操作中组合视觉、搜索、代码等多模态的长时程任务能力。[²²⁹] 最优系统成功率仅 45.1%，即约 55% 的任务失败。Agent 能很好地处理单一模态，但难以跨模态保持连贯性。

这与第 7 章所述的上下文窗口饱和模式一致：随着任务跨越更多文件和模态，上下文窗口充斥着模型难以整合的异构内容。

HiL-Bench：帮助寻求鸿沟

HiL-Bench（人在回路基准）测量了此前无基准测试过的能力：Agent 关于何时寻求人工帮助的判断力。[²³⁰] 结果严峻。前沿 Agent 在获得完整上下文时能解决复杂任务，但一旦必须自行决定是否升级，没有任何前沿模型能恢复超过完整信息性能的一小部分。瓶颈在于判断，而非能力。这对审批模式设计有直接启示（第 5 章）：在 Suggest、Auto Edit 和 Full Auto 之间的选择，不仅关乎控制权，更关乎赋予 Agent 在识别出不确定性时升级的能力。

新基准对你配置的启示

故障分类法建议三大配置优先级：

1. 投资导航辅助。 AGENTS.md 中的文件映射、显式路由规则、结构良好的仓库布局，直接解决 27% 至 52% 的导航失败率。文件映射模式见第 4 章。

2. 缩小任务范围。 约 55% 的多模态组合失败率意味着，宽泛的开放式任务（“重构此模块并更新所有测试和文档”）比分解的子任务更易失败。使用子 Agent（第 11 章）将多模态工作拆解为单模态步骤。

3. 校准审批模式。 陡峭的帮助寻求性能损失意味着 Full Auto 模式的代价比你想象的大，并非因为 Agent 做危险的事，而是因为它在本应寻求澄清的任务上盲目推进。

SlopCodeBench：衡量质量，而非仅完成度

前述基准共享一个盲点：衡量 Agent 是否完成任务，而非生成代码是否优质。2026 年 3 月发布的 SlopCodeBench 直接填补这一空白。[²³¹]

SWE-bench 问“补丁是否通过测试套件？”，Terminal-Bench 问“Agent 是否完成工作流？”，而 SlopCodeBench 问代码在增长过程中是否保持结构良好且可维护。它让 Agent 在不断演进的规格下反复扩展自有早期解决方案，并追踪轨迹级质量信号：冗余度（冗余或重复代码占比）和结构侵蚀（复杂度集中在少数函数中）。

早期结果显示，在任务完成类基准上得分高的 Agent，不一定产出高质量代码。用暴力解法通过测试套件的模型，在 SWE-bench 得高分，在 SlopCodeBench 却得分低。对于以代码库健康而非原始任务吞吐为首要关注的团队，你的模型擅长的基准可能无法预测你真正在意的指标。

对 Codex CLI 用户，SlopCodeBench 提示：基于钩子的质量检查（Linter、风格强制、写后分析）即便在任务完成基准改进时仍不可或缺。模型可能解决了问题；关键在于该解决方案是否属于你的代码库。

基准测试层级体系

2026 年基准格局形成了一个可靠性层级，按适用于你真实工作负载的程度从低到高排列：

底层是 SWE-bench Verified，仍适用于区分弱模型，但在前沿已失去区分度。再上是 SWE-bench Pro，提供更诚实的多文件、多语言推理度量，其私有子集是目前抗污染能力最强的信号。

Terminal-Bench 2.0 与 Pro 齐头并进，作为最贴近 Codex CLI 用户的领域特定基准：原生终端、Docker 沙箱、结构上抗记忆化。顶层是源自你实际工作流的自有基准套件，这是唯一能直接回答你提问的评估。

公开数字是缩小选型范围的起点。自有评估才是最终决策的依据。

代码审查基准与采用数据

两个新数据源补充了任务完成类基准，提供真实采用与审查质量的证据。

OpenAI 报告的代码审查评估 定性提醒：即使前沿模型在审查代码时，也会遗漏大量真实缺陷。对使用 Codex CLI 内置代码审查技能或 CodeRabbit 插件的团队，这校准了预期：自动化审查是有用的首轮筛查，不能替代人工审查。

PRDBench：PRD 到代码的鸿沟

PRDBench 由上海交通大学与美团团队推出（2025 年 10 月发布于 arXiv，2026 年被 AAMAS 接受），测量与现有基准根本不同的能力：从产品需求文档（PRD）构建软件，而非修复现有 Bug 或完成部分实现。[²³²] 核心发现是 PRD 到代码的鸿沟显著大于 Bug 修复鸿沟。撰写时排行榜显示，最强模型仅在 60% 左右，弱模型远低于 30%，因为从规格构建需要架构决策、依赖选择、集成规划，而修复导向基准不测试这些。

面向 Codex CLI 用户的 PRDBench 校准

对于 Codex CLI 用户，PRDBench 对绿地开发任务的预期进行校准。如果您的工作流涉及根据规范生成新服务或功能（这是一种常见的企业模式），PRDBench 的得分比 SWE-bench 更能预测智能体性能。该基准还验证了规范驱动开发方法：提供结构化的 PRD（产品需求文档）而非模糊的提示词，能显著提高解决率。

MAESTRO：多智能体评估

MAESTRO（用于测试、可靠性和可观察性的多智能体评估套件）填补了单智能体基准的空白：评估多智能体系统中的编排质量。[²³³] 其关键发现在于，架构选择——智能体如何组合、共享何种状态以及故障如何传播——对多智能体性能的影响大于模型选择。一个编排良好的系统即便使用较弱的模型，也能胜过编排不善但使用更强模型的系统。

这一发现强化了第 12 章中的编排模式：这些模式本身就是性能杠杆，而不仅仅是组织便利。MAESTRO 提供了评估方法论，用以衡量您的编排架构究竟是在提供帮助，还是引入了超出并行化收益的协调开销。

基准的另一面：生产环境中的智能体代码质量

迄今讨论的基准衡量的是智能体能否完成任务。2026 年初发布的两份主要行业报告提出了一个不同的问题：智能体写完代码后会发生什么？答案令人警醒，为解读任何基准分数提供了必要的背景。

Opsera 与 Sourcery Intel 2026 报告

Opsera《AI 编码影响 2026 基准报告》分析了 60 多家企业、超过 250,000 名开发者的数据。[²³⁴] Sourcery Intel《2026 年 AI 编码智能体现状》综合了整个智能体领域的市场、基准和安全数据。[²³⁵] 两者共同勾勒出一幅关于智能体输出质量一致的图景。

表 25-5. 智能体代码质量发现（2026 年初）

| 发现 | 数据 | 来源 |

| --- | --- | --- |

| AI 生成代码漏洞率 | 14.3% 对比 9.1% 人工（相对增加 57%） | Sourcery Intel（斯坦福-MIT 研究，200 万+ 片段） |

| 每行漏洞数 | 比人工代码多 15% 至 18% | Opsera（25 万+ 开发者） |

| 评审队列延迟 | AI 生成的 PR 长 4.6 倍 | Opsera |

| 代码重复率 | 样本中 10.5% 至 13.5% | Opsera |

| PR 时间缩短 | 快 48% 至 58% | Opsera |

| 高级与初级生产力增益差距 | ~5 倍 | Opsera |

| 闲置 AI 编码许可证 | 21% | Opsera |

这种悖论十分显著：AI 辅助工作流将拉取请求的时间缩短了 48% 至 58%，但由此产生的 PR 在评审队列中停留的时间却长了 4.6 倍。代码生产的加速已超过了审查能力。团队产出更多 PR，但评审人员无法跟上，导致未审查的、潜在脆弱代码积压日益增加。

PR-MCI：当描述撒谎时

一项被 MSR 2026 接收的研究分析了五个 AI 编码智能体的 23,247 个拉取请求，人工标注了 974 个 PR 以验证自动化的 PR-MCI（PR 消息-代码不一致）检测管道。[²³⁶] 研究结果量化了许多评审人员直观感受到的信任赤字：

1. 1.7% 的智能体 PR 表现出高消息-代码不一致：描述声称的更改在差异中并未实现。

2. 最常见的故障模式（占高 MCI 情况的 45.4%）是“描述声称未实现的更改”。

3. 高 MCI PR 的接受率低 51.7%（28.3% 对比 80.0%）。

4. 它们的合并时间长 3.5 倍（55.8 小时对比 16.0 小时）。

CodeRabbit 对 470 个开源 PR 的分析从另一个角度佐证了这一点：AI 合著的拉取请求包含的问题大约是纯人工 PR 的 1.7 倍（每个 PR 10.83 个问题对比 6.45 个），质量差距跨越逻辑与正确性（1.75 倍）、代码质量（1.64 倍）、安全性（2.74 倍）和可读性（3.0 倍）。[²³⁷]

这对基准解读意味着什么

这些发现并未使基准分数失效。它们为分数提供了背景。在 Terminal-Bench 2.0 上得分 82% 的模型确实有能力完成复杂任务。但它生成的代码可能带有 14.3% 的漏洞率，可能复用现有抽象，且可能附带不能准确反映变更内容的 PR 描述。基准完成是必要条件，但非生产级输出的充分条件。

对 Codex CLI 用户的实际启示：基准分数告诉您哪个模型能解决问题。PostToolUse 钩子、自动化评审（auto_review）、AGENTS.md 质量约束和结构化输出模式（第 9、20、4 和 22 章）告诉您该解决方案是否属于您的代码库。

总结

1. SWE-bench Verified 在前沿领域已被污染。 约 60% 以上的分数反映了部分记忆化。SWE-bench Pro 是更诚实的衡量标准，同一模型的得分低 30 至 40 分。

2. GPT-5.5 领跑 Terminal-Bench 2.0。 OpenAI 报告得分为 82.7%（供应商自测数据，略微领先 Claude Mythos Preview）；独立排行榜显示 Codex CLI + GPT-5.5 得分 82.2%，仅次于当前 SOTA 的 NexAU-AHE + GPT-5.5（84.7%）。在 SWE-bench Pro 上得分 58.6%，在 SWE-bench 上得分 88.7%。

3. Terminal-Bench 2.0 是 Codex CLI 用户最相关的基准。 它在 Docker 沙盒环境中运行端到端的终端工作流，是终端原生工作最接近的已发布代理指标。

4. SlopCodeBench 衡量质量，而不仅是完成度。 它通过对代码质量（可读性、可维护性、地道风格）评分而非任务是否完成，解决了现有基准的盲区。

5. 脚手架膨胀增加 4 至 12 分。 供应商报告的分数高于标准化基线，因此切勿直接将供应商报告的分数与 SEAL 排行榜分数比较。

6. 模型选择与脚手架同等重要。 模型升级提高上限；AGENTS.md、钩子、审批模式和任务设计决定您的工作流能多接近该上限。

7. 最好的基准是您自己的代码库。 以 Terminal-Bench 的任务格式为模板，在版本控制中跟踪结果。

8. PRDBench 揭示了 PRD 到代码的鸿沟。 从规范构建比修复 Bug 困难得多，最强模型得分在 60% 左右，仍远低于其 SWE-bench 表现。（上海交通大学和美团团队；arXiv 2025 年 10 月，AAMAS 2026。）

9. 对于多智能体工作，编排架构胜过模型选择。 MAESTRO 证明了这一点，验证了第 12 章中涵盖的编排模式投资的价值。

10. 生产代码质量讲述了与完成度不同的故事。 报告引用了 14.3% 的漏洞率（Sourcery Intel）、4.6 倍的评审队列延迟（Opsera）以及代码重复率从 10.5% 上升至 13.5%。PR-MCI 研究（MSR 2026）显示 1.7% 的智能体 PR 存在误导性描述，接受率低 51.7%，合并时间长 3.5 倍。基准完成是必要条件，但非生产级输出的充分条件。

练习

任务与基准测试

1. 审计基准测试声明

寻找某 AI 实验室近期引用代码基准测试分数的新闻稿或博客文章。识别：

• (a) 引用的是哪个基准测试变体

• (b) 使用的脚手架是供应商自有的还是标准化测试框架

• (c) 是否存在同一模型对应的 SEAL 排行榜条目

若两个数字都存在，计算脚手架溢价；若不存在，准确记录缺少哪个对比。最后用两段总结该引用数字实际说明了模型在您工作负载上的可能表现。

2. 构建五任务微基准

从团队近期 Sprint 历史中选取五个具有代表性的真实任务（Issue 或 PR），而非编造场景。使用本章的 .benchmarks/ 结构。对每个任务：

• 编写确定性成功测试（成功退出码 0、失败退出码 1 的 Shell 脚本）

• 使用 Docker 容器化初始环境

• 用当前配置运行 Codex CLI，记录解决率和单任务成本

• 修改一个变量（模型选择、AGENTS.md 内容或 Hook 配置）并重新运行

• 记录哪个配置获胜及原因

3. 对子集运行 Terminal-Bench 2.0

安装 Harbor 框架，运行 harbor datasets list，并用 harbor run --help 确定当前过滤标志。从与您工作相关的类别中选取 10 到 15 个 Terminal-Bench 2.0 任务，分别对两个 Codex CLI 模型配置 gpt-5.5 和 gpt-5.4 运行。对比解决率和总成本。若结果与表 25-2 发布的排行榜数字差异显著，分析原因。考虑您的 AGENTS.md 配置、网络环境，以及您选取的任务类别是否映射到模型的训练强项。与团队分享发现，并以此作为今后默认模型选择的依据。

4. 在小型项目上运行自有基准

从积压工作中选择一个真实的 Bug 或功能请求（手动耗时 15 到 30 分钟）。将 Issue 文本放入本地基准任务文件，或让提示词明确告诉 Codex 如何获取，例如：

codex "Fix issue #N. Use gh issue view N to read the issue, then run the project tests."

计时结果。记录是否通过测试、轮数和 Token 成本。与本章发布的基准分数对比。记录真实结果偏离实验室结果的位置及原因（代码库复杂度、测试覆盖率、AGENTS.md 中的领域知识）。

5. 测量您工作流的脚手架溢价

脚手架溢价是指归因于脚手架（提示词、AGENTS.md、Hook、审批模式、任务设计）而非底层模型的性能差异。从积压工作中选取一个代表性任务，每次仅改变一个变量，运行两遍。从相同模型和审批模式开始，先用最小配置，再用生产环境的 AGENTS.md 和 Hook。记录输出质量、Token 数和耗时。如需区分脚手架效应与模型效应，可换用不同模型重复。这些数据在评估是否升级模型或投资改进脚手架时极具价值。

第二十六章：竞品工具及适用场景

第 25 章表明，决定编码代理性能差异的主要是测试框架而非模型：LangChain 在模型不变的情况下将 Terminal-Bench 2.0 排名从第 30 位提升至第 5 位，脚手架溢价可为基准分数增加 4 到 12 分。本章将这一视角转向竞争格局，提供任务决策框架、架构权衡的诚实评估，以及何时不应选择 Codex CLI 的指导。

推荐单一工具对抗固定竞品名单的书籍很快过时，因为名单每季度都在变。等您读到此书时，代理式编码市场已进一步整合，此处提及的部分产品可能已重命名或退市，新产品也会出现。请将文中工具视为架构类别的代表，而非固定清单。类别持久；占据类别的品牌名则不然。本章提及工具时，系作为该类别当前最清晰的示例，而非永久固定。

该领域沿一条架构轴线划分：CLI 代理运行在终端、操作文件系统，对比 IDE 代理驻留在编辑器、通过可视化 Diff 和内联补全呈现 AI。少数工具跨足两端，但其设计理念通常揭示其优先服务哪一侧。此区分很重要，因为两个层级优化目标不同。终端代理优化无人值守执行、可脚本化、与 CI/CD 流水线集成。IDE 代理优化紧凑反馈循环、可视化 Diff、不离开编辑器的舒适度。为任务选错层级不仅低效，有时在架构上根本不可能。您无法通过 IDE 插件运行内核级沙箱 CI 流水线，也无法从无头终端代理获得内联可视化 Diff。

开始前的一个诚实元观点：若您已从其他工具获得所需结果，可能无需切换。本章旨在帮助您有意识地得出该结论，或识别出 Codex CLI 优势使其成为更好选择的具体场景。

测试框架工程视角

一篇 42 位作者的调查论文（“Code as Agent Harness”，arXiv 2605.18747）提供了理解为何使用相同底层模型的工具产出截然不同结果的学术框架。论文指出所有编码代理通用的三层架构：

1. 接口层——代理如何接收指令并呈现结果：AGENTS.md 文件、系统提示词、终端 UI 对比编辑器面板。

2. 机制层——约束与赋能代理行为的要素：Hook、权限配置文件、沙箱、审批模式。

3. 多代理扩展层——代理如何协作：子代理、MCP 服务器、交接协议。

关键洞见：模型非差异化因素；测试框架才是。两个运行可比模型的工具因其测试框架在每层做出不同工程选择而产出显著不同结果。一者在机制层投资内核级沙箱和 Token 效率；另一者在接口层投资可编程 Hook 和更丰富的推理展示。模型设定能力上限，但测试框架决定您在真实任务上能触及多少上限。第 27 章将深入展开这一论点；本章将其作为选型视角应用。

学习目标

您将能够：

1. 应用决策框架，根据特定任务与约束概况在 Codex CLI 与竞品代理间选择

2. 解释内核级沙箱、可编程 Hook 与 IDE 原生反馈循环的架构权衡

3. 在两个工具上运行同一任务，按成本、质量、人机工效评估结果

4. 设计多工具工作流，让各工具发挥其架构强项

5. 按代理沙箱最弱的强制边界而非最强边界对其分类

6. 将配置、技能、子代理、Hook 从其他代理（如 Claude Code）迁移到 Codex CLI

决策框架

诚实的回答是，大多数经验丰富的从业者会使用不止一种工具。问题不在于选哪一个，而在于根据具体任务和约束情况，该拿起哪一个。表 26-1 将常见场景映射到适合的架构类别，并为每个类别列出了代表性工具。

表 26-1. 何时使用哪种工具

| 场景 | 首选 | 主要原因 |

| --- | --- | --- |

| 内核级沙箱是硬性要求 | 具有操作系统强制隔离的 CLI 代理 (Codex CLI) | 操作系统层面的 Seatbelt/bubblewrap 强制执行，而非应用层策略 |

| 复杂、可编程的合规逻辑 | 具有丰富钩子事件的 CLI 代理 (Claude Code) | 策略以程序形式表达，而非配置 |

| 规模化的 Token 高效批处理工作 | 终端优先的 CLI 代理 (Codex CLI) | 无头运行避免了 IDE 协议开销 |

| 对全新 Bug 进行最高质量推理 | 运行最强前沿模型的代理 | 在真正的新问题上，模型能力占主导 |

| 代码落地前进行可视化差异对比 | IDE 原生代理 (Cursor) | 内联差异审查是原生用户体验 |

| 永不离开编辑器 | IDE 原生代理 (Cursor, GitHub Copilot) | 无需终端上下文切换 |

| 授权并放手解决 Issue | 异步云代理 (GitHub Copilot coding agent) | 在托管沙箱中从 Issue 到 PR，无需本地会话 |

| 厂商中立、模型不可知、物理隔离 | 开源 CLI 代理 (OpenCode) | 无厂商锁定；自带模型 |

| 预算是约束性因素 | 免费层级或开源代理 | 零或低边际成本改变使用模式 |

| 具有沙箱化、无人值守执行能力的 CI/CD | 终端优先的 CLI 代理 (codex exec) | 可脚本化、内核沙箱化、专为无头使用而构建 |

请将此表视为一组架构承诺来阅读，而非品牌背书。内核级沙箱指向 CLI 代理的原因，并非某个供应商更高尚；而是因为操作系统强制隔离是工具生成子进程方式的属性，而 IDE 插件通常不具备该属性。当某行中提到的工具发生变化时，最右列的理由通常不会变。

CLI 代理

Codex CLI 优势

Codex CLI 的优势集中在工具链的机制层，这正是调查论文预测持久差异所在的地方。

1. 内核级沙箱。 操作系统强制隔离，macOS 上为 Apple Seatbelt，Linux 上为带 seccomp 的 bubblewrap，而非应用层限制。沙箱在系统调用层面运作，因此无论代理被说服尝试何种操作，隔离均有效。第 16 章 深入探讨了安全含义。

2. Token 效率。 无头终端操作避免了 IDE 协议层（编辑器状态同步、补全流、UI 更新消息）带来的 Token 开销，而这些是 IDE 耦合代理的额外负担。第 14 章 解释了为何该差距在团队规模下成为预算输入项。

3. CI/CD 原生。 codex exec 运行任务、返回结果并退出：天然适配流水线集成，第 15 章 对此进行了详细阐述。

4. 渐进式审批模型。 审批系统提供了一系列信任级别，并由内核级强制执行作为后盾，这在架构上区别于二元的基于信任的开关。命名配置文件 (第 5 章) 使这些预设可复用且可版本控制。

Claude Code：最接近的对标产品

Claude Code 是 CLI 代理类别中的主要竞争对手，也是 Codex CLI 最接近的对标产品。^(²³⁹) 它是使用最广泛的终端代理之一，当推理质量是约束性因素时，它是一个强有力的选择：在涉及定位和修复微妙 Bug 的多文件任务中，它始终能产出高质量的修复，且在撰写本文时，其公开的 SWE-bench Verified 分数位居前列。（将任何特定基准数据视为快照；实时排行榜才是真理来源。）

有两个架构差异值得理解而非死记硬背。第一是策略表达能力。Claude Code 暴露了一组丰富的钩子事件，允许你在 Shell 脚本中编码任意复杂的策略逻辑。钩子是程序，而非配置，因此其表达能力实际上是无限的。Codex CLI 的安全模型则倾向于内核级沙箱，这提供了更强的隔离性，但对于定制化的合规工作流灵活性较低。两种方法均无绝对优势：可编程钩子能表达沙箱无法表达的策略，而沙箱能强制执行运行在同一信任域内的钩子无法保证的边界。

第二个差异是强制执行默认值。Claude Code 自带操作系统级沙箱（macOS 上为 Seatbelt，Linux 和 WSL2 上为 bubblewrap），用于代理生成的 Shell 子进程，因此区别在于作用范围和默认值，而非强制执行机制的存在与否：该沙箱覆盖 Bash 子进程，而文件读写通过权限层进行；其网络过滤基于主机名且不执行 TLS 检查；且沙箱是可选加入的，而 Codex CLI 将内核级隔离视为架构默认。如果你的主要需求是推理质量和可编程策略，Claude Code 是绝佳选择；如果是默认的硬隔离和 Token 效率，Codex CLI 更具优势。

Codex CLI 在直接对比中获胜的往往在于 Token 效率和成本。独立测试反复发现 Codex CLI 比 IDE 耦合代理消耗少得多的 Token，在某些 CLI 对 CLI 的对比中，完成同一任务其 Token 消耗甚至比 Claude Code 少几倍。^(²⁴⁰) 在个人规模下差异可忽略；在团队规模下，这会转化为成本节约或容量余量，从而成为规划输入项。评估这两者用于特定项目时，实用的做法是在两者中运行相同任务并直接检查 Token 计数，这正是本章第一个练习的主题。

Google 的终端代理

Google 在同一类别中推出了一款终端代理，其决定性特性是拥有真正的免费层级和大上下文窗口，这比任何基准测试都更能改变使用模式。^(²⁴¹) 开发者若因每次查询几美分的成本而不愿请教代理快速定向性问题，在零成本下则会乐意提问，因此免费层级将代理变为探索和文档伴侣，而非代码修改主力。它还提供实时网络搜索接地，这对涉及近期库版本或模型训练截止日期后可能已变更的 API 的任务很有用�。

权衡点与该类别一致。其沙箱基于容器而非内核级，且在复杂推理或多文件重构的基准性能上尚未追平前沿 CLI 代理。对于成本非约束性因素且任务质量至上的团队，前沿代理产出更好结果；对于探索、定向和代码库快速问答，免费层级创造了真实价值。撰写本文时，Google 在此领域的产品谱系处于变动中，其终端产品正被整合进更广泛的平台，因此请将品牌名称视为比其所在类别稳定性更低的标识。

开源与厂商中立代理

第三方 CLI 代理：开源工具

第三类工具是开源 CLI 代理，如 OpenCode、Aider 和 Continue，它们以生态深度换取供应商独立性。^[1] Codex CLI 与 OpenAI 的模型栈紧密耦合，而这些工具将每个供应商视为一等公民，在一个接口后支持数十个模型后端，通常采用宽松许可证，使其无需采购审查即可嵌入。对于运行本地模型的气隙环境，或采购流程使专有工具变得不切实际的组织，它们完全消除了锁定顾虑。

代价是使商业工具对多开发人员团队具有实用性的那层有观点的配置。这些代理通常缺乏商业选项的内核级沙箱、命名权限配置文件和托管企业功能，且其基准性能往往未经独立验证。当供应商中立性、气隙操作或模型不可知论是主要需求时，它们是强有力的选择；但当你需要开箱即用的团队范围约定和硬隔离时，则较难推销。

规格驱动与并行编排代理

还有两类 CLI 值得提及，因为它们代表了真正不同的设计理念，而非增量功能差异。

规格驱动代理

规格驱动代理 将结构化规格（而非代码库）视为主要工件。Codex CLI 是终端优先且极简的（提示、执行、沙箱），而规格驱动代理首先将自然语言请求转换为代理和人类共同参考的正式规格，然后才生成代码。这适合已从书面规格工作并希望代理计划成为可审查文档的团队；它增加了快速单文件编辑不需要的仪式感。Codex CLI 通过手动规划约定（PLANS.md 文件，第 3 章 的规划方法）而非一等规格对象达到类似目的。

并行编排代理

并行编排代理 押注于不同策略：它们不采用单一深度推理链，而是扇出至由路由器协调的多个子代理，有时在人类看到任何内容之前，对相互竞争的输出进行评分。对于存在多种合理实现的探索性工作，广度优先探索能浮现单个代理永远不会尝试的选项。权衡在于控制力和可验证性：单次高质量代理遍历产生更清晰的记录，且对明确指定的工单更具成本效益；该类别中新进入者的自我报告基准数据并不总能经受住独立评估。

请谨慎对待任何供应商的自我报告基准数字，直到出现独立评估。使用不同脚手架测量的分数，或由第三方（如独立评估实验室）测量的分数，往往远低于标题数字。脚手架视角双向起作用：包裹在弱公共脚手架中的强模型可能表现不及其自身营销。

IDE 代理

IDE 代理将 AI 能力直接嵌入编辑器。主要优势是工作流连续性：开发者以可视化差异形式查看建议变更，内联接受或拒绝，永不离开编辑上下文。

Cursor

Cursor 是主导的 IDE 代理，也是该类别做得最好的最清晰示例。^[2] 其市场地位反映了真实的用户体验质量而非营销：可视化差异在任何变更被接受前落地，完整的编辑器扩展生态系统保持完好，且无需上下文切换到终端。当你希望在代理接触代码前准确看到其将做什么，且工作流以编辑器为中心时，它具有决定性优势。

权衡是 Token 成本：更丰富的可视化脚手架（编辑器状态、打开文件上下文、内联差异流）消耗比无头代理更多的 Token 完成相同任务，独立测试测量 CLI 代理完成相同工作所用 Token 比 IDE 代理少几倍。^[3] Cursor 不是 CLI 代理；对于终端优先工作流（CI/CD 流水线、脚本自动化、无头操作），它在架构上不适合该工作，正如无头代理不适合想要每次编辑都有内联差异的人一样。

GitHub Copilot

GitHub Copilot 拥有市场上最高的品牌知名度，最初作为自动补全，现已成为具有交互、异步和 CLI 模式的多组件平台。^[4] 两点使其独特。第一是其异步编码代理：你分配一个议题，它启动托管 CI 沙箱，将提交推送到草稿拉取请求，并在完成时请求审查，全程无需你守在桌前。这种委托即遗忘模型在结构上不同于 Codex CLI 和 Claude Code 使用的交互循环，且真正适合议题分类和直接的错误修复。第二是模型灵活性：Copilot 允许你按任务从多个供应商中选择模型，这是单一供应商工具不具备的优势。其弱点是原始代理能力，落后于前沿 CLI 代理；其强项是生态集成，对于已在 GitHub 上的团队，增加代理能力的边际成本极低。

编辑器作为多代理界面

IDE 层级更有趣的发展不是任何单一代理，而是编辑器成为同时托管多个代理的宿主。一些编辑器现在在一个窗口中以对等方式运行多个代理，每个代理在自己的线程中处理代码库的不同部分，通过开放的代理到编辑器协议协调，使任何兼容代理（包括 Codex CLI）成为一等公民。在这样的编辑器中运行 Codex CLI 赋予你原始终端无法提供的三样东西：共享文件上下文（编辑器转发你的工作目录和打开文件，无需手动 @ 提及体操）、并行编排（多个 Codex 线程与其他代理并行）和统一审批界面（工具执行在编辑器中显示为交互式审批，而非争夺单个终端窗格）。

主流编辑器现在在单个侧边栏中将 Codex、Claude 和 Copilot 作为对等代理呈现，具有本地、后台和云执行模式，体现了相同的融合趋势。对 Codex CLI 用户的实际收益是配置可移植性：编辑器集成封装相同引擎并读取相同的 ~/.codex/config.toml，因此你现有的配置文件、模型偏好和权限设置跨环境保持不变。你在 CLI 配置上的投入在迁移到编辑器托管工作流时不会搁浅；它是同一个脚手架，只是呈现方式不同。

融合层

在竞争表象下，工具正在汇聚到一小组共享标准，这比任何单一基准都重要，因为它决定了你被锁定的程度。三个标准现已跨越工具边界：

1. AGENTS.md 作为可移植指令文件。配置 Codex CLI 的相同项目指导（第 4 章）被越来越多的竞争代理原生读取，因此单个文件无需重复即可塑造多个工具的行为。

2. Agent Skills 作为可移植能力包。SKILL.md 目录（第 10 章）日益被跨代理识别，因此编写一次的技能可从多个工具调用。

3. MCP 作为可移植工具层。模型上下文协议服务器（第 8 章）向任何支持 MCP 的代理暴露相同工具，因此你构建的集成不绑定单一供应商。

对于买方而言，收敛是本章最好的消息。这意味着决策很少是非此即彼的：一个 AGENTS.md 文件、一个技能目录和一个 MCP 服务器配置可以在你技术栈中的各个工具间共享，这使得组装和变更多工具工作流的成本都很低。锁定效应正好在原本危害最大的层面上消退。

从 Claude Code 迁移到 Codex CLI

由于收敛层标准可跨工具通用，从 Claude Code 切换到 Codex CLI 主要是一项机械性的配置工作，而非重写。像对待任何迁移一样对待它：制定计划、增量执行、每一步都验证。需要迁移五个组件。

指令文件：从 CLAUDE.md 到 AGENTS.md

AGENTS.md 是由 Linux 基金会的 Agentic AI 基金会管理的开放标准。^(²⁴⁶) CLAUDE.md 专用于 Claude Code。不要删除 CLAUDE.md；要重构它。

将通用约定（代码风格、构建命令、测试运行器调用、架构说明）移入 AGENTS.md。保留 CLAUDE.md 用于 Claude 特有的指令：钩子引用、子代理定义、记忆配置。添加交叉引用：See @AGENTS.md for build commands, architecture, and conventions.

如果你无法维护两个文件，可配置 Codex CLI 将 CLAUDE.md 作为回退选项：

##### ~/.codex/config.toml
project_doc_fallback_filenames = ["CLAUDE.md", "COPILOT.md"]
project_doc_max_bytes = 65536

撰写本文时，Codex 会按顺序从仓库根目录向下检查到你的工作目录中的每个目录：AGENTS.override.md（将替换同级的任何 AGENTS.md） → AGENTS.md → project_doc_fallback_filenames 中的任意名称。默认字节限制 project_doc_max_bytes 为 32 KiB (32768 字节)，适用于整个拼接链；对于大型单体仓库，将其提高至 65536。

技能

技能具有最高的对等性。SKILL.md 格式遵循 Agent Skills 开放标准；相同的文件可在 Claude Code、Codex CLI、Cursor 和 Gemini CLI 间通用。Claude Code 将技能存储在 .claude/skills/<name>/SKILL.md 下；Codex CLI 从 .agents/skills/ 加载。目录名称不同；文件格式相同。

将 .claude/skills/ 复制到 .agents/skills/。仅使用 name、description、allowed-tools 和 disable-model-invocation 的技能无需更改即可工作。单独审核其他前置元数据键。context: fork 键（在隔离的子代理中运行技能）是 Claude Code 的扩展；在依赖它之前请验证 Codex CLI 的支持情况。

子代理

子代理代表了最大的架构分歧。Claude Code 子代理定义为 Markdown 文件，支持交互式编排，父代理可实时查看推理并干预。Codex CLI 子代理定义为 TOML，适合并行批处理工作负载，即分发任务并收集结果。

将每个子代理重写为 .codex/agents/（项目级）或 ~/.codex/agents/（个人级）下的 TOML 代理定义。在 .codex/config.toml 中启用 features.multi_agent = true 以开启多代理工作流。agents.max_depth 默认为 1，因此子代理无法在未显式配置的情况下生成更深层的子代理。Codex CLI 子代理每次运行消耗的 token 比等效的单代理运行更多；请在成本对比中考虑此因素。

钩子

撰写本文时，Claude Code 通过 stdin/stdout 上的 JSON 协议提供了二十多种生命周期钩子事件类型。撰写本文时，Codex CLI 支持十种钩子事件：SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PreL1-Bullet、PostL1-Bullet、SubagentStart、SubagentStop 和 Stop。与 Claude Code 迁移最相关的五种是 SessionStart、PreToolUse、PostToolUse、UserPromptSubmit 和 Stop。在 ~/.codex/hooks.json（或项目级的 .codex/hooks.json）的 JSON 文件中配置钩子。钩子默认启用；config.toml 中 [features] 下的 hooks 开关可让你禁用它们（托管配置可固定该设置）：

{
 "hooks": {
 "SessionStart": [
 {
 "hooks": [
 { "type": "command", "command": "~/.codex/hooks/on-session-start.sh", "timeout": 15 }
 ]
 }
 ],
 "Stop": [
 {
 "hooks": [
 { "type": "command", "command": "~/.codex/hooks/on-stop.sh", "timeout": 10 }
 ]
 }
 ],
 "UserPromptSubmit": [
 {
 "hooks": [
 { "type": "command", "command": "~/.codex/hooks/on-prompt.sh", "timeout": 5 }
 ]
 }
 ],
 "PreToolUse": [
 {
 "matcher": "Bash",
 "hooks": [
 { "type": "command", "command": "~/.codex/hooks/pre-tool.sh", "timeout": 5 }
 ]
 }
 ],
 "PostToolUse": [
 {
 "matcher": "Bash",
 "hooks": [
 { "type": "command", "command": "~/.codex/hooks/post-tool.sh", "timeout": 10 }
 ]
 }
 ]
 }
}

matcher 字段是应用于工具名称的正则表达式。撰写本文时，PreToolUse 和 PostToolUse 匹配 Bash、文件编辑工具 apply_patch 以及 MCP 工具名称（如 mcp__filesystem__read_file）。使用 "matcher": "Bash" 直接移植拦截 shell 命令的 Claude Code PreToolUse 钩子。对于拦截文件编辑的钩子，使用 "matcher": "apply_patch" 进行匹配。

对于副作用钩子（日志记录、Slack 通知、审计跟踪），使用 Stop 和 SessionStart。按名称拦截文件写入工具的 Claude Code 钩子无法映射到同名的 Codex CLI 工具；改为匹配 apply_patch，或通过 sandbox_mode 或 AGENTS.md 指令强制执行文件写入策略。

配置

Claude Code 使用五层 JSON 级联，其中激活层是隐式的。Codex CLI 使用命名配置文件，因此你始终知道哪个配置处于激活状态，因为是你选择的。每个配置文件位于各自的文件中，~/.codex/<name>.config.toml，采用顶层键而非 config.toml 内部的 [profiles.<name>] 表。运行 codex --profile <name> 会先加载 ~/.codex/config.toml，然后在其之上叠加配置文件：

##### ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "untrusted"
##### ~/.codex/strict.config.toml
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
##### ~/.codex/fast.config.toml
model = "gpt-5.4-mini"
model_reasoning_effort = "low"
approval_policy = "never"
sandbox_mode = "read-only"

在 CLI 处切换配置文件：codex --profile strict "review the auth module" 加载基础 config.toml 然后叠加 strict.config.toml。两个工具的模型命名不同：Claude Code 使用 Anthropic 模型名称（claude-opus-4-8、claude-sonnet-4-6）；Codex CLI 使用 OpenAI 模型名称。模型名称频繁变更，因此在 CI 流水线中硬编码之前，请根据 OpenAI 文档核对当前名称。

推荐的迁移后布局在仓库根目录并存保留 AGENTS.md 和 CLAUDE.md，将子代理定义作为 TOML 文件置于 .codex/agents/（项目级）或 ~/.codex/agents/（个人级），并将 .agents/skills/ 作为两个工具共同读取的共享技能目录。

跨代理迁移工具

收敛层使得在任意两个代理之间移植变得主要是机械性的，而不仅限于从 Claude Code 到 Codex CLI。大多数团队的配置、技能、MCP 服务器和会话历史分散在多个框架中；两种机制将这种碎片化变成了已解决的问题。

Detect/Import API

Codex CLI 为碎片化提供了一流的解决方案：externalAgentConfig/detect 和 externalAgentConfig/import JSON-RPC API，由异步后台会话导入提供支持。

externalAgentConfig/detect 扫描文件系统以查找其他代理框架可导入的工件。它接受 includeHome（扫描主目录中的全局配置）和 cwds（要扫描的项目目录），并返回类型化的 migrationItems：

| 项目类型 | 涵盖内容 |

| --- | --- |

| AGENTS_MD | CLAUDE.md、.cursorrules 或其他可映射到 AGENTS.md 的指令文件 |

| --- | --- |

| CONFIG || 全局配置（模型默认值、批准模式、提供商密钥） |

| SKILLS || 包含 SKILL.md 文件的技能目录 |

| PLUGINS || 应用商店插件引用 |

| MCP_SERVER_CONFIG || MCP 服务器连接定义 |

检测过程幂等且增量：如果 AGENTS.md 已存在且非空，Codex 会跳过 AGENTS_MD；技能导入不会覆盖现有的技能目录。

externalAgentConfig/import 应用选定的迁移项。它会立即返回并在后台异步处理导入，完成后发出 externalAgentConfig/import/completed 通知。会话历史记录导入是最繁重的操作，完全在后台通过串行化处理运行以防止重复。

表 26-2. 常见源 Agent 的具体文件映射

| 制品 || Claude Code || Cursor || Codex CLI 目标 |

| --- | --- | --- | --- |

| Agent 指令 || CLAUDE.md || .cursor/rules/*.mdc || AGENTS.md |

| --- | --- | --- | --- |

| 技能 || .claude/skills/<n>/SKILL.md || .cursor/skills/ || .agents/skills/ |

| MCP 服务器 || .mcp.json || .cursor/mcp.json || config.toml [mcp_servers] |

| 全局配置 || ~/.claude/settings.json || ~/.cursor/settings.json || ~/.codex/config.toml |

对于并行运行多个 Agent 的团队，同步方法通常比一次性迁移效果更好。维护单一事实来源文件（通常为 AGENTS.md），并使用构建脚本生成特定工具的变体。

Microsoft APM：跨 Agent 配置管理

Microsoft 的 Agent Package Manager (APM) 以 MIT 许可证作为开源发布，引入了一个位于任何单个工具之上的配置管理层。^(²⁴⁷) APM 支持八款 AI 编码 Agent（GitHub Copilot、Claude Code、Cursor、OpenCode、Codex CLI、Gemini CLI、Windsurf 和 Kiro），均通过单一清单文件管理。

APM 的 apm.yml 在 Node 项目中的角色相当于 package.json：即 Agent 所需一切的声明式规范：

name: subscriptions-api
version: 1.0.0
dependencies:
 apm:
 - acme/agent-skills/skills/migration-auditor
 - acme/agent-skills/plugins/release-notes
 mcp:
 - name: io.github.github/github-mcp-server
 transport: http

运行 apm install 可从任意 Git 托管平台解析依赖，并将其部署到各 Agent 的正确位置。apm.lock.yaml 文件固定已解析的来源和内容哈希，确保确定性复现。APM 将 Codex CLI 列为其支持的八款 Agent 之一；编译目标名称记录在 APM README 中。

APM 对 Codex CLI 团队的当前价值主要体现在三个方面：跨仓库标准化 AGENTS.md 内容（APM 解析传递指令依赖）、分发技能，以及同时使用 Codex CLI、Claude Code 或 Copilot 的团队的跨 Agent 一致性。安全特性包括安装时的内容扫描（阻止用于提示词注入的隐藏 Unicode 字符）、通过内容哈希实现的锁文件完整性，以及通过 apm audit 进行的偏移检测。

对于企业团队，apm-policy.yml 采用“仅收紧”继承模型强制执行组织对 Agent 配置的约束：企业策略限制最严，仓库策略只能进一步收紧。这补充了 Codex CLI 的 requirements.toml 强制执行：APM 控制配置供应链，权限配置文件控制运行时沙箱。

Codex CLI 支持通过可流式 HTTP 连接远程 MCP 服务器（配置服务器 url 加上持有者令牌或 OAuth 认证）。一些跨 Agent 包管理器仍保留着过时的假设，即认为 Codex CLI 不支持此功能，并可能跳过 transport: http 依赖的 Codex 目标；请查看你的包管理器发行说明，因为这一差距正在缩小。

Gemini CLI 停止维护

Google 在 2026 年 I/O 大会上宣布，Gemini CLI 将于 2026 年 6 月 18 日停止维护，由 Antigravity CLI 取代。^(²⁴⁸) 目前正在使用 Gemini CLI 的团队应在截止日期前将其配置迁移至 Antigravity CLI 或 Codex CLI。映射关系简单直接：.gemini/ 配置映射到 ~/.codex/config.toml，.gemini/agents/ 自定义 Agent YAML 文件映射到 .codex/agents/ TOML 文件，@agent 调用映射到 Codex CLI 中的 /agent。MCP 服务器配置协议兼容，仅需移动配置文件即可。

多工具模式

大多数对比文章的错误前提在于：你必须选择一种工具并坚持使用。资深从业者实际采用的模式是分层栈，每种工具分配到其架构优势所在：

1. IDE Agent 用于交互式开发：编写功能、探索陌生代码、在视觉反馈至关重要的场景下进行结对编程。

2. CLI Agent 用于自动化：CI/CD 任务、批量重构、测试生成，以及任何需要内核级隔离的工作。

3. 第二个 CLI Agent 或云 Agent 用于处理第一个 Agent 最不擅长的工作：复杂推理、可编程策略执行，或无需本地会话的长时间运行异步任务。

这些工具通过 Git 共享同一代码库，通过上述汇聚层共享同一上下文，因此开发者按任务而非平台忠诚度来选择工具。边界通常很清晰。编辑单个文件并希望在落地前查看差异，属于 IDE Agent 的工作。涉及文件系统操作、执行测试且需要隔离的多步骤任务，属于 CLI Agent 的工作。委派任务然后离开，属于异步 Agent 的工作。为单行补全使用功能齐全的终端 Agent 属于过度设计；为需要内核沙箱的多步骤 CI 任务使用 IDE 插件则属于设计不足。

有一种从业者变体值得强调，因为它能提升质量而不仅仅是路由工作：双工具审查工作流，即一个 Agent 构建，另一个不同的 Agent 审计。^(²⁴⁹) 在一个记录在案的例子中，一个 CLI Agent 负责 Web 应用的初始开发，第二个 Agent 的审查环节发现了第一个遗漏的约二十个 Bug：时间戳错误、导航故障，以及构建者模型盲区中的边缘情况。原则很简单：绝不发布仅有一个模型见过的代码。不同模型有不同的盲区，因此让第二个 Agent 阅读第一个 Agent 的差异，是一种廉价有效的检查，单模型无法复制。这与 第 20 章 中对抗性审查模式背后的直觉一致，只是应用在工具间而非工具内。

相关的一个发展是桌面封装器的兴起，它们将多个 CLI Agent（Codex CLI 和竞品）集成到一个应用中，具备任务调度、Git 工作树管理 (第 13 章) 和远程操作功能。这些工具竞争的是“开发者工作台”——即你整天保持打开的应用——而非底层的 Agent 引擎。底层的 Codex 引擎保持不变；价值主张在于顶层的编排层。该层是否值得采用，取决于其调度和工作区管理是否优于你通过 codex exec 加上操作系统级工具所能组装出的方案。对许多团队而言，目前尚不具备优势，但这一品类值得关注。

何时坚持使用现有工具

工具切换有真实成本：学习曲线、配置迁移、团队对齐。仅当架构权衡能证明其合理性时才切换。如果你目前使用其他工具很高效，那么引入 Codex CLI 的理由仅基于特定条件：你需要内核级沙箱而非基于钩子的策略；你运行任务的规模使得 Token 效率差距成为真实成本因素；你的工作流高度面向终端自动化；或你需要大上下文窗口的正式版而非预览版。如果这些条件均不适用，你当前的工具就很好，本书对 Codex 特定配置的深度探讨对你而言只是学术性的而非操作性的。同理：如果你更喜欢待在编辑器中，在代码落地前查看差异，且极少进行终端自动化，IDE Agent 将比任何 CLI Agent 更适合你，终端优先的热情不应凌驾于你自己的工作流偏好之上。如果你当前的工具能很好地处理 80% 的用例，请优化剩下的 20%，而不是替换整个技术栈。

如果你首次向团队引入 Agentic 工具，请从一个工具针对一个定义明确的任务类型开始，然后再扩展。一支自信地使用 IDE Agent 进行内联编辑、刻意使用 Codex CLI 处理 CI 任务的团队，将比安装了五个工具却无使用约定的团队交付得更可靠。

沙箱全景

沙箱是工具间架构上最显著的差异因素，因为它决定了当（而非是否） Agent 收到恶意或错误指令时能做什么。按执行强度分层，方法分为清晰的梯队。

| 方法 | 执行层 | 绕过风险 |

| --- | --- | --- |

| 内核级（Seatbelt、Landlock、bubblewrap、seccomp） | 操作系统系统调用层 | 极低：需要内核漏洞利用 |

| 容器级（Docker、Firecracker、每 Agent 一个容器） | 命名空间隔离 | 低：需要容器逃逸 |

| 虚拟机级（云沙箱） | 完整机器隔离 | 极低，但开销较高 |

| 应用层（基于信任、策略文件） | Agent 自我执行 | 中等：提示词注入可绕过 |

| 无 | 无限制 | 高：任何工具调用均不加检查地通过 |

应用此表时有两点细化很重要。首先，现在有多个 CLI 工具将 Shell 子进程的内核级沙箱与用于文件编辑的应用层权限层结合在一起，因此“应用层”行描述的是一个类别，而非某个特定工具。按工具最弱的执行边界分类，而非最强的。 一个工具如果对 Bash 实施内核沙箱，却让文件编辑通过自我执行的权限检查，从威胁建模角度来看，它仅与该权限检查对抗提示词注入的能力一样强。

其次，梯队在隔离强度与开销之间权衡。像 Seatbelt 和 Landlock 这样的内核级原语由操作系统以近乎零开销强制执行，且在 Codex CLI 中是内置而非外挂的。容器级隔离为并发 Agent 之间提供更强的分离，代价是容器启动延迟，当你并行运行多个 Agent 并需要其工作树之间有硬边界时，这笔开销值得付出（第 13 章）。虚拟机级隔离被云执行面使用，在最高开销下提供完整机器分离，是完全自主、不受信执行的正确梯队。对于安全敏感环境，内核级或容器级沙箱是不可商量的；对于受信的本地开发，应用层模型可能足够。决策权在于你的威胁模型，而非基准测试，第 16 章将演示如何做出决策。

总结

1. 单一架构轴线划分市场。 Agentic 编码市场沿 CLI 与 IDE 这条线划分，各自针对不同工作流优化：一边是无人值守执行与可脚本化，另一边是紧凑反馈循环与可视化差异。将具名工具视为这些类别的代表，因为类别比品牌更持久。

2. 编排层比模型更具差异化。 接口、机制、扩展这三层解释了运行可比模型的工具之间的大部分差异，这正是第 27 章将全面展开的论点。模型决定上限；编排层决定你能触及多少上限。

3. CLI Agent 在自动化上胜出。 它们擅长 CI/CD、内核级沙箱和 Token 效率，因为无头终端操作避免了 IDE 协议层的开销。Codex CLI 的优势集中在机制层，正是调查预测持久差异存在之处。

4. Claude Code 是最接近的同辈。 它在推理质量和可编程钩子表达力上领先；Codex CLI 在 Token 效率和默认内核级隔离上领先。二者是真正的权衡，而非排名，诚实的评估方式是在两者中运行相同任务并对比 Token 计数。

5. IDE Agent 在交互式工作上胜出。 Cursor 等工具擅长可视化差异审查和工作流连续性；GitHub Copilot 增加了独特的委托并离线的异步模型及每任务模型选择。两者为相同编辑付出的 Token 成本都比无头 Agent 高。

6. 融合层降低了赌注。 AGENTS.md、Agent Skills 和 MCP 现已跨工具流通，因此多工具栈组装廉价且切换廉价。在最可能造成伤害的层面上，锁定效应正在消退。

7. 多工具模式优于忠诚度。 根据架构优势分配每个工具，而非强迫一个工具覆盖所有场景。双工具审查工作流——用一个 Agent 构建，用另一个 Agent 审计——能捕获单模型单次通过遗漏的 Bug，理由正如对抗性审查在单工具内生效一样。

8. 沙箱是最尖锐的差异因素。 系统调用层的内核级强制执行，在范畴上不同于 Agent 对自我执行、且可被提示词注入绕过的应用层策略。按工具最弱的执行边界分类，而非最强的。

9. 仅当权衡证明成本合理时才切换。 学习曲线、配置迁移、团队对齐是真实的；如果你当前的工具能处理好 80% 的用例，请优化剩下的 20%，而不是替换整个技术栈。

10. 切换工具主要是机械操作。 因为 AGENTS.md、Skills 和 MCP 跨 Agent 流通，从 Claude Code 迁移到 Codex CLI 是一个五组件配置练习（指令、技能、子 Agent、钩子、配置），加上 externalAgentConfig 检测/导入 API 及微软 APM 等跨 Agent 包管理器自动完成其余工作。

练习

练习 26-1. 在两个工具中运行同一任务。 从当前项目中选取一个范围明确的任务，例如“为用户注册端点添加输入验证”。分别在 Codex CLI 和一个竞品工具中运行它。记录 Token 计数、批准提示次数、输出质量（能否编译、是否处理边缘情况）和墙钟时间。记录你会为该任务类别选择哪个工具及原因。

练习 26-2. 将你的任务映射到框架。 写下你使用 AI 编码工具的五种最常见任务类型。对每一种，应用表 26-1 识别适配的架构类别。如果五者答案都是同一类别，你大概不需要多工具设置。如果答案各异，勾画分层工作流的样子。

练习 26-3. 设计多工具工作流。 为您的团队设计一个工作流，将 IDE 智能体、CLI 智能体以及云端或异步智能体分配给特定的任务类别。记录该工作流及每项分配的基本原理，并明确说明工具将通过汇聚层共享哪些 AGENTS.md、技能和 MCP 配置。

练习 26-4. 根据您的需求审计沙箱隔离。 根据贵组织的安全要求，评估三种不同工具的沙箱模型。构建对比矩阵，按每个工具强制执行的最弱边界对其进行分类，并找出哪些工具满足您的安全门槛。

练习 26-5. 将工作流移植到 Codex CLI。 如果您有一个正常运行的 Claude Code（或其他智能体）项目，请完成五组件迁移图谱：从 CLAUDE.md 中的通用内容创建 AGENTS.md，将您的技能复制到 .agents/skills/，以 TOML 格式重写任何子智能体，移植您依赖的钩子，并创建一个包含至少两个命名配置集的 ~/.codex/config.toml。验证 codex --profile strict "summarize the codebase" 能否在不修改任何文件的情况下成功运行。

第二十七章：为长期运行智能体构建工程护架

前几章为您提供了词汇：工具、移交、护栏、上下文窗口。但仅有原语不足以构成生产系统。锤子和水平仪是建房子的必要工具，但并不充分。缺失的是一切随时间推移将建筑凝聚在一起的东西：保障工人安全的脚手架、经得起真实工况考验的计划，以及在错误变成承重结构前捕捉它们的检查点。在智能体工程中，这种脚手架被称为护架（harness）。本章涵盖什么是护架、如何从第一性原理构建护架、当前可添加到 Codex CLI 护架的组件、大规模展示模式的参考实现（其中主要是 Symphony，OpenAI 的开源护架），以及证明是护架而非模型驱动结果质量的证据。

学习目标

您将能够：

1. 解释什么是护架，并使用三层框架和三大支柱阐述为什么是护架而非模型决定了结果质量

2. 根据三大支柱（密封测试、机器可读文档、模块化架构）审计代码库，并找出迫使智能体进行猜测的因素

3. 设计一个 WORKFLOW.md 文件，同时捕获 Codex 智能体的运行时参数和行为策略

4. 实施基于检查点的状态持久化策略，使您的智能体能在中断后恢复，而无需重复已完成的工作

5. 将工作量证明原则应用到您自己的流水线中，无论您是否使用 Symphony

6. 选择适合您规模的护架组件和编排模式，并论证为什么应在切换模型前先改进护架

什么是护架工程

Ryan Lopopolo 于 2026 年 2 月创造了该术语[²⁵⁰]，为从业者早已在做却缺乏共同词汇的事情命名。传统软件工程设计代码。提示词工程设计给 AI 的指令。护架工程设计使 AI 智能体可靠高效的基础设施、约束和反馈回路。它位于上述两者之上一层。Lopopolo 用一句话总结道：“智能体不难；护架才难。”[²⁵¹]

护架是包裹智能体的一切：描述项目的 AGENTS.md、提供确定性反馈的测试套件、限制爆炸半径的沙箱、验证输出的 CI 流水线、决定何时必须人工干预的审批策略，以及让多小时任务能在瞬时故障中存活的检查点逻辑。当您的护架设计良好时，一个强大的模型就能高置信度地自主完成任务。当它设计不良时，即使是最好的模型也会陷入挣扎。

如果您已学完第四部分，您其实早就在做护架工程了。每一次 AGENTS.md 的完善、密封测试套件、PostToolUse 静态检查钩子和 codex exec CI 配置集都是护架工作。本章增加的是原则性模型：每个护架必须满足的三大支柱、解决特定失效模式的模式，以及使智能体策略可审计和版本控制的格式。

学术基础：三层框架

2026 年 5 月，一篇由 42 位作者撰写的综述论文（“Code as Agent Harness”，arXiv 2605.18747）首次利用三层架构框架对编码智能体进行了严谨的学术处理。[²⁵²] 该论文的核心论点——“护架拥有循环”——验证了从业者经验性发现的事实：模型是一个组件；护架决定结果质量。

三层分别为：

1. 接口层。 智能体如何接收指令并呈现结果。在 Codex CLI 中，这包括 AGENTS.md、TUI、系统提示词和审批对话框。接口层塑造模型认为它应该做什么。

2. 机制层。 约束和启用智能体行为的要素。钩子、权限配置集、沙箱策略、执行策略规则和审批模式阶梯。机制层决定模型能做什么，无论它认为应该做什么。

3. 多智能体扩展层。 智能体如何跨边界协作。MCP 服务器、子智能体、A2A 协议，以及像 Symphony 的 WORKFLOW.md 这样的编排模式。扩展层决定一个智能体能否委派给其他智能体，以及状态如何在它们之间流动。

https://github.com/OpenDocCN/freelearn-dl-zh/tree/master/docs/agentic-coding-with-openai-codex-cli/img/B40007_27_01.png

图 27.1 - 三层护架框架

接口层（AGENTS.md、TUI、系统提示词和审批对话框）塑造模型认为它应该做什么；机制层（钩子、权限配置集、沙箱策略和审批模式阶梯）决定它能做什么；多智能体扩展层（MCP 服务器、子智能体、A2A 协议和编排模式）管控状态如何在智能体间流动。每一层都约束其下方的一层。

这些层共同表达了论文的论点：是护架而非模型拥有循环并驱动结果质量。将 Codex CLI 的架构映射到该框架，使本书的结构作为护架工程课程变得清晰可辨：

| 框架层级 | Codex CLI 原语 | 书籍章节 |

| :--- | :--- | :--- |

| 接口层 | AGENTS.md、系统提示词、TUI、计划模式 | 第 3、4、7 章 |

| 机制层 | 钩子、权限配置集、沙箱、审批模式 | 第 5、9、16 章 |

| 多智能体扩展层 | MCP 服务器、子智能体、技能、exec 流水线 | 第 8、10、11、12、15 章 |

该论文还调查了多个平台（在一份互补的 dev.to 从业者分析中），跨多个评估维度发现，护架工程决策而非模型选择占了实际结果差异的大多数。[²⁵³] 使用相同模型但不同护架的两个智能体产生了显著不同的结果。使用不同模型但相似护架架构的两个智能体在质量上趋于相似。护架是自变量。

这一发现重构了团队评估智能体工具的方式。问题不是“哪个模型最好？”，而是“哪个护架为我的约束做出了最佳工程选择？”第 26 章将这一视角应用于竞争格局。

三大支柱

以下几个模式都借鉴了 Symphony，因此在依赖它之前，有必要清楚地说明它是什么。Symphony 是 OpenAI 开源的参考级编排工具：它从问题追踪器获取议题，在隔离工作区中为每个议题运行一个 Codex CLI 代理，仅当代理产出可验证的工作量证明后，才向人类提交拉取请求。本章后面（“Symphony：编排工具的实践”）将详细剖析其架构；在此之前，请将其视为本章讨论原则的一个具体、可工作的示例。

每个生产级编排工具都建立在三大支柱之上，Symphony 的文档对此有明确阐述。^(²⁵⁴)

隔离测试 意味着你的测试套件能在本地可靠运行，且无外部依赖。运行 npm test 并获得确定性结果的代理可以独立迭代。依赖预发布数据库或实时 API 的代理会陷入挣扎，无法区分真正的回归和环境故障。修复方法是众所周知的：模拟外部服务、播种测试数据库，并使每个测试都能通过单条命令离线运行。

机器可读文档 意味着代理无需询问即可发现如何构建、测试、检查和部署你的项目。AGENTS.md 是主要载体（见 第 4 章），但该原则延伸至代理可能需要的任何结构化制品，例如具有命名目标的 Makefile、具有可预测名称的 package.json 脚本，或遵循一致格式的 README 章节。如果代理必须猜测，就会消耗 Token 并引入错误。

模块化架构 意味着副作用被局部化且边界显式。修改支付模块的代理不应无意中破坏通知服务。高耦合导致正确性不确定性；低耦合让代理能在有界范围内自信工作。这与优秀架构主张的领域分离是同一论点，但自主代理比人类开发者对它更敏感，因为人类可以提出澄清性问题。Codex CLI 本身即构建为大型多箱工作区，每个箱拥有独立的编译单元、依赖图和测试套件。（撰写时 Codex CLI 仍处于 1.0 版本前；具体箱数量随持续发布而变化。）这是应用于工具自身的编排工程：将模块化架构推向极致，从而实现并行编译、隔离测试和更清晰的依赖审计。使代理任务易于处理的原则，同样让编排工具链更易维护。

WORKFLOW.md 模式

你在本书中一直使用的 AGENTS.md 是一份静态文档：它描述项目及其约定，且在运行间不会改变。WORKFLOW.md 由 Symphony 引入，^(²⁵⁵) 是一种更强大的模式，将两样东西合二为一。

YAML 前置元数据是运行时配置：模型选择、轮次限制、集成端点和所需的工作量证明制品。Markdown 正文是代理的系统提示词，以兼容 Liquid 的模板编写。运行时，编排工具利用议题特定上下文（工单标题、仓库、分支、受保护文件）渲染模板，并将结果作为初始指令传递。

---
model: gpt-5.5
max_turns: 40
issue_tracker: linear
workspace_mode: isolated
proof_of_work: [ci, review, complexity]
---
#### Markdown 正文 — 兼容 Liquid 的提示词模板
You are implementing {{ issue.title }}.
Context:
{{ issue.description }}
Repository: {{ repo.name }}
Branch: {{ branch_name }}
Rules:
- Run the full test suite before marking done
- Do not modify {{ protected_files }}
- Write tests for any new functions

这种结构含义值得深思。代理行为现为版本化的仓库制品。你可以跨版本对比代理策略，回滚引入 Bug 的行为变更，并在将变更推广至生产前要求拉取请求审查。代理指令受同一治理约束，因为它们与应用代码处于同一仓库。

即使你未使用 Symphony 完整的编排层，也可在自己的流水线中采用此文件格式。Codex CLI exec 调用可使用任意 YAML 解析器读取 YAML 前置元数据，用兼容 Liquid 的引擎渲染正文（例如 Python 的 python-liquid，或若你用 Jinja 重写模板则用 jinja2），并将结果作为系统提示词传递。你无需 Elixir 依赖即可获得所有版本控制优势。

将 WORKFLOW.md 置于仓库根目录，与 AGENTS.md 共存。两个文件均记录代理策略；评估代理为何表现异常时，两者都应被审查。

代理运行间的状态持久化

长时间运行的代理可能被中断。网络超时、进程重启、预算限制和 CI 运行器回收都可能导致代理在任务中途终止。状态持久化让代理能从最后一个安全检查点恢复，而非重头开始。有三种粒度级别可供选择；正确选择取决于任务时长和成本。

会话 ID 恢复 是最轻量的方法。Codex CLI 为每次对话分配一个会话 ID。持久化该 ID 并通过 /resume 或向下次调用传递标识符来恢复；代理将从中断处继续。局限性在于：会话上下文在运行期间驻留内存，若进程在 ID 记录前退出，则会丢失。

检查点文件 适用于有明显阶段的任务。编排工具写入检查点，记录已完成阶段及其产出。重启时，它读取检查点并指示代理从记录的阶段继续。格式为纯 JSON，易于检查、重演和归档。

{
 "issue_id": "ENG-4821",
 "branch": "fix/auth-token-expiry",
 "phases_completed": ["diagnosis", "implementation"],
 "phases_remaining": ["tests", "documentation"],
 "artifacts": {
 "diagnosis": "Root cause: JWT expiry check off by one in token_service.py line 147",
 "implementation": "Patch applied to token_service.py, session_manager.py"
 },
 "last_updated": "2026-03-26T14:23:11Z"
}

数据库支持的状态 适用于并发运行许多代理、需要将其进度作为舰队进行查询、监控或管理的场景。Symphony 采用此法：每个代理的状态是 Postgres 表中的一行，编排器查询该表以分派新工作、检测停滞代理并汇总完成度指标。^(²⁵⁶) 对单团队而言这可能过度设计；但对运行数十个代理处理共享积压工作的组织，这是唯一能扩展的方法。

无论选择哪种持久化策略，请确保检查点格式包含模式版本字段。代理流水线会演进，当格式变更时你需迁移现有检查点。检查点存储中缺少版本字段是技术债，终将以生产事故形式显现。

错误恢复与重试

状态持久化告诉你代理失败时在何处。错误恢复决定下一步做什么。三种模式对应三类故障。

指数退避重试 处理瞬时故障：限流、临时网络错误、二次尝试即通过的易失性测试。编排工具捕获失败，等待随重试次数增长的退避间隔，并用相同输入重新调用代理。最大重试次数和退避上限应可在 WORKFLOW.md 前置元数据中配置；将其硬编码是造成流水线僵化的常见错误。

人工介入升级

人工介入升级 用于处理需要智能体无法提供的判断力的失败情况：需求模糊、约束冲突，或测试失败可能意味着真正的回归或测试本身有问题。工具框架通过 Linear、Slack 或 GitHub 向人工呈现失败信息，并附带足够的上下文以解除智能体的阻塞。目标是将升级次数降到最低，而非完全消除。

回滚模式

回滚模式 用于处理必须在重试前撤销部分已应用更改的情况。如果智能体以原子方式提交（每次提交对应一个逻辑变更），工具框架即可识别出错误提交，将其还原，并干净地重新开始。混合了正确与错误工作的整体式提交则难以回滚得多。

不要实现吞没错误信息的静默重试循环。每次重试都应记录失败原因、重试次数和退避间隔。一个在成功前静默重试失败操作二十次的智能体消耗了二十倍的预算；一个静默重试最终却放弃的智能体一无所获且毫无反馈。在无人值守操作中，可观测性不是可选项。

工作量证明原则

Symphony 中最重要的架构理念，也是最适用于任何流水线的理念，是工作量证明：智能体必须通过可验证的证据来证明完成，而不仅仅是报告“已完成”。[¹]

问题在于根本的信任鸿沟。当智能体报告完成时，除非验证内置于循环中，否则你只能听其片面之词。智能体可能自信地犯错：通过无法覆盖相关用例的测试、产出包含微妙逻辑错误的代码，或实现了与需求相邻但不完全一致的功能。

在向人工审查者呈现拉取请求前，Symphony 要求提供四种形式的证据：

1. CI 通过： 所有测试在 CI 流水线中通过，而非仅在本地通过

2. 审查反馈： 自动化代码审查分析，识别任何潜在问题

3. 复杂度分析： 代码变更规模与复杂度指标

4. 演示视频： 记录变更内容及原因的视频

演示视频往往让人惊讶。它迫使智能体讲述自己的工作：所理解的问题、采取的方法、证明方法成功的证据。这种叙述本身就是一种质量信号；一个无法清晰解释自己做了什么的智能体，很可能没有充分理解它。

你不需要 Symphony 即可应用此原则。在 Codex CLI 工作流中：在每个子智能体的指令末尾加上“标记完成前必须运行测试”的要求；编写一个 PostToolUse 钩子查询 CI API，若流水线未通过则拒绝继续；要求会话结束前必须产出结构化的变更摘要作为强制产物。

核心原则是：智能体应是可问责的行动者，而非黑盒。问责需要证据，而证据需要一个工具框架，使产出证据成为智能体职责描述的一部分。

今日即可添加的工具框架组件

前述模式属于架构层面。以下是可立即接入 Codex CLI 工具框架的具体组件，每个组件填补一个特定的操作缺口：模型运行位置、工具隔离方式、变更审查方式、工具框架的程序化驱动方式、组件在生态间的迁移方式，以及将智能体嵌入产品时的变化。

作为工具框架组件的本地模型提供商

完全依赖云模型端点的工具框架继承了单点故障，且成本基线随智能体并发数线性增长。在 [model_providers] 下通过 config.toml 配置的本地模型提供商（Ollama、vLLM、llama.cpp）为特定工具框架层级提供了替代方案。wire_api = "responses" 设置确保本地提供商遵循与云端点相同的 API 契约，从而工具框架的其余部分（提示词、工具、审批策略）保持不变。配置文件切换（--profile local 与 --profile cloud）让工具框架操作员可在不修改工具框架本身的情况下按运行选择后端。

本地提供商最适合一级和二级任务：机械性编辑、代码库探索和格式化遍历，此时本地模型与前沿模型的质量差距最小。对于需要深度推理或长程规划的三级工作，云端点仍是合适的后端。该决策应由工具框架操作员的配置文件选择决定，而非工具框架定义本身。当本地层级使用的是自购而非租赁的硬件时，第 14 章 详述了决定是否划算的本地化部署盈亏平衡点。

用于工具框架级隔离的 Docker MCP 工具包

在开发者机器上将 MCP 工具服务器作为裸露的 npx 或 pip 进程运行，会引入依赖冲突、凭据蔓延，且智能体与宿主机之间零隔离。Docker 的 MCP 工具包在工具框架层面解决了此问题：将 200 多个经过验证的 MCP 服务器打包为容器镜像，由单个网关进程前置，处理路由、凭据注入和资源限制。[²]

网关是单个 stdio 进程。内部按需将工具调用路由到容器化服务器，每个服务器运行在自己的命名空间中，具有受限特权（无宿主机文件系统访问、1 CPU、2 GB 内存上限）。响应在返回客户端前会被扫描以防止机密泄露。

工具框架相关性在于配置文件管理。Docker 配置文件为工作流分组 MCP 服务器，并可作为 OCI 制品共享。提交一个引用配置文件的 .codex/config.toml，即可让每位开发者获得相同的、隔离的工具访问权限。对于 CI，网关作为 GitHub Actions 中的服务容器运行，使 codex exec 在无头模式下拥有相同工具。将 startup_timeout_sec 设置为至少 30 秒，因为完整目录可能超过 Codex 默认的 10 秒握手超时。

原生 MCP 服务器适用于简单、单工具、高信任度的设置。当你的工具框架需要隔离、凭据管理或团队标准化时，Docker MCP 工具包是正确的选择。[³]

内置代码审查技能

Codex CLI 提供内置代码审查技能，减少了对自定义审查工具的需求。没有它，工具框架作者需自行连接外部工具：用于静态分析的独立 MCP 服务器、调用审查智能体的自定义钩子，或第三方 GitHub Action。

内置技能根据 AGENTS.md 约定分析暂存或已提交的变更，并产出结构化反馈。对工具框架工程师而言，这意味着少了一个外部依赖；工作量证明流水线中的审查步骤引用的是随 Codex CLI 自带的能力。特定领域的规则或合规性检查可能仍需专用工具，但对于人工签收前的通用代码质量把关，内置技能更简单且易于维护。

用于自定义工具框架客户端的 App Server JSON-RPC

Codex App Server 将智能体核心与其客户端界面解耦。每种 Codex CLI 体验（CLI TUI、VS Code 扩展、桌面应用、Web 界面、IDE 集成）均通过单一的双向 JSON-RPC 2.0 API 通信。[⁴] 对工具框架工程师而言，这是自定义前端和编排层的集成点。

该协议通过三个原语构建交互：Items（原子输入/输出单元）、Turns（一个智能体工作单元产生的 Item 序列）和 Threads（支持创建、恢复、分叉和归档的持久会话容器）。提供两种传输方式：用于本地集成的 stdio（codex app-server，受支持的默认方式），以及用于具有 /readyz 和 /healthz 健康检查的远程场景的 WebSocket 传输（codex app-server --listen ws://127.0.0.1:4500，撰写时为实验性）。

[¹]: 脚注 257

[²]: 脚注 258

[³]: 脚注 259

[⁴]: 脚注 260

Harness 应用场景包括：订阅 turn/completed 通知以追踪 Token 使用的仪表盘、使用具有沙箱隔离功能的 command/exec 的 CI/CD 编排器、以及拦截 requestApproval 通知的企业审批网关。可使用 codex app-server generate-ts 或 codex app-server generate-json-schema 生成类型安全的客户端绑定。^(²⁶¹)

对于已超越封装 codex exec 的 Shell 脚本阶段的 Harness 作者而言，App Server 协议是用于程序化智能体控制的稳定、语言无关的基础。

跨工具 Harness 可移植性

cc-plugin-to-codex 反向桥接（见第 26 章）使得 Harness 组件能在智能体生态系统之间实现部分可移植性。^(²⁶²) 打包在 Claude Code 插件中的 PostToolUse 密钥扫描 Hook 可通过 cc2codex 转换为 Codex 原生 Hook，反之亦然，可通过 codex-plugin-cc 实现。对于运行多智能体 Harness 的组织（Codex 用于 CI/CD，Claude Code 用于调试），这意味着共享而非重复。转换过程是有损的且需要验证，但它指向了组件层面的工具无关 Harness 工程化。

SaaS 就绪性与生产环境嵌入

如果您的 Harness 旨在将 Codex CLI 嵌入多租户 SaaS 产品中，而非服务于单个工程团队，则工程需求会发生变化。对六个生产嵌入维度（架构、SDK 可用性、会话管理、MCP 可扩展性、气隙能力和许可证）上十一款 CLI 智能体的评估，将 Codex CLI 置于第 2 梯队（可嵌入但有注意事项），落后于提供内置会话存储和宽松许可证的 OpenCode 和 Pi/OpenClaw 等工具。^(²⁶³) 对 Harness 作者最相关的差距是会话持久化（Codex CLI 基于 stdio 的 JSONL 方法要求您自行构建持久化层）以及面向气隙企业环境的离线模型支持。

在确定嵌入架构之前，请验证在多租户负载下会失效的五个关键点：子进程与库集成、结构化事件流、并发请求下的租户隔离、模型 BYOK（自带密钥）支持、以及沙箱逃逸边界。^(²⁶⁴)

实战中的 Harness

有了支柱、策略格式和组件在手，通过查看组装它们的完整 Harness 会有所帮助。两个开放系统处于设计空间的不同位置，决策指南将您的情况映射到适合的模式。

Symphony：参考实现

Symphony^(²⁶⁵) 是 OpenAI 大规模 Harness 工程的开源参考实现。其架构将抽象模式具体化。

Linear 看板上的 Issue 进入“Ready for Agent”状态。Symphony 轮询、拾取符合条件的 Issue、创建隔离的按 Issue 工作区、生成一个以渲染后的 WORKFLOW.md 作为系统提示词的 Codex CLI 智能体，并让智能体工作。在所需的工作量证明工件完成之前，没有任何内容会呈现给人类。随后，人类审查一个由 CI 状态、代码审查分析和演示视频支持的拉取请求：验证过的结果，而非受监督的过程。

Symphony 基于 Erlang/BEAM 运行时使用 Elixir 构建。^(²⁶⁶) 这一选择反映了问题的需求：BEAM 可处理数千个轻量级并发进程，因此运行五十个并行的 Codex CLI 智能体在操作层面类似于运行五个。OTP 监督树意味着单个失败的智能体会自动重启而不影响其他智能体。且 BEAM 专为长时间运行的进程设计；耗时数分钟或数小时的智能体是原生用例，而非压力测试。

撰写时，Symphony 处于工程预览阶段，存在有意义的限制：它支持 Linear 但不支持 Jira 或 GitHub Issues，每个 Issue 运行单个智能体且不支持内部子智能体生成，且定制化需要 Elixir 知识。对于大多数团队而言，它作为参考架构比作为生产依赖更有用。

Symphony 的 SPEC.md 阐述了为何使用隔离工作区而非共享环境、为何采用工作量证明而非逐步审查、以及为何选择 Elixir 而非 Python。详见 github.com/openai/symphony。

另请参阅： 第 13 章。Symphony 的按 Issue 工作区是 Git worktree。第 13 章 涵盖了并行工作的创建、会话上下文分配和清理。

NanoClaw：持久编排参实现

Symphony 是面向批处理的 Harness（拾取 Issue、处理、交付 PR），而 NanoClaw^(²⁶⁷) 代表持久编排模式：一个常驻的智能体编排器，维护任务注册表、调度周期性工作、管理容器隔离的工作池，并通过基于通道的消息传递进行通信。

其架构演示了若干补充 Symphony 批处理模式的模式：

1. 持久化调度。 任务可按间隔、每 8 小时或每天上午 8 点调度，而非由外部事件触发。这支持主动工作流：每夜代码质量扫描、每日文档新鲜度检查、每周依赖审计。

2. 容器隔离。 每个 Worker 在自己的容器中运行，提供比仅用 worktree 更强的隔离。行为异常的智能体无法影响其他 Worker 或编排器。

3. 基于通道的通信。 Worker 通过结构化消息通道与编排器通信，而非共享状态，实现了难以通过基于文件系统的方法达成的协调模式。

4. 任务生命周期管理。 任务可在不丢失状态的情况下暂停、恢复、取消和重新优先级排序。这对跨越数小时或数天的长期工作流至关重要。

NanoClaw 并非 Symphony 的替代品；它占据设计空间的不同位置。Symphony 擅长带有工作量证明门控的 Issue 驱动批处理工作流；NanoClaw 擅长持久的、调度驱动的持续运行。许多生产部署将针对不同类别的工作同时使用这两种模式。

选择模式：您自己的 Harness 应走向何方

大多数团队当前所做与 Symphony 所做之间的对比颇具启发性。

表 27-1. Harness 模式决策指南

| 场景 | 使用的模式 | Symphony 类比 |

| --- | --- | --- |

| 单智能体，交互式会话 | AGENTS.md + 人工审批 | 不适用 |

| 单智能体，无人值守 CI 运行 | WORKFLOW.md + 检查点文件 + codex exec | 单 Issue Symphony 运行 |

| 多智能体，顺序任务 | 带阶段检查点的门控链 | 多个 Symphony Issue，线性依赖 |

| 多智能体，并行任务 | 带数据库支持状态的并行集群 | 共享 Linear 看板上的 Symphony 舰队 |

| 智能体输出需人工签收 | 工作量证明工件 + 升级 Hook | 带证据包的 Symphony PR |

| 智能体任务中失败 | 检查点文件 + 退避重试 | OTP 监督树重启 |

| 智能体策略需演进 | Git 中的 WORKFLOW.md + PR 审查 | Symphony 仓库中版本化的 WORKFLOW.md |

| 任务需与其他工作隔离 | Git worktree + 沙箱配置 | 每 Issue 隔离工作区 |

从上到下的演进是从交互式工具使用到自主舰队操作。大多数团队处于中间某处。Symphony 的价值不在于您需要使用它；它展示了前路的形状，以便您在设计今天的 Harness 时能考虑到明天的需求。

证据：为何 Harness 胜过模型

本章以一个主张开篇：Harness 掌控循环

本章以一个主张开篇：掌控循环的是 harness（注：指智能体运行的编排/基础设施层，下文统称“哈尼斯”或“编排层”），而非模型。到 2026 年年中，这不再仅是直觉。哈尼斯是智能体成果中占主导地位的变量这一命题，现在得到了四个未曾协调却意见一致的视角的支持：一次受控基准测试、一次同行评审复现、一位实践者的工作理论，以及第一方企业级实践。这种收敛性，比任何单一数字都更有说服力。如果你从本章只带走一条运营法则，请记住这一条：当智能体表现不佳时，先改哈尼斯，再换模型。

差距已被量化，且可复现

最干净的结果来自受控实验。在模型固定为 gpt-5.2-codex、仅更换哈尼斯的情况下，LangChain 的 deepagents-cli 在 Terminal Bench 2.0 上从第 30 名跃升至第 5 名。^(²⁶⁸) 起作用的是可移植的、而非专有的模式：五种中间件模式，每种都有你已拥有或可自行构建的 Codex CLI 等效实现。

1. PreCompletionChecklistMiddleware（预完成清单中间件） 在智能体宣布“完成”前拦截它，并强制执行四阶段验证（规划、构建、验证、修复）。Codex CLI 的等效实现是 PostToolUse 钩子配合 AGENTS.md 指令，要求在完成前进行测试验证。

2. LocalContextMiddleware（本地上下文中间件） 在启动时注入环境上下文（目录结构、可用工具、语言检测），而非让智能体通过试错去发现。Codex CLI 的等效实现是 AGENTS.md 上下文注入，会在会话开始时自动加载。

3. LoopDetectionMiddleware（循环检测中间件） 跟踪每个文件的编辑次数，在对同一文件编辑 N 次后提示智能体重新考虑，打破智能体重复失败策略的“死亡循环”。Codex CLI 无内置等效实现；自定义 PostToolUse 钩子可填补该空白。

4. Reasoning Sandwich（推理三明治） 在规划和验证阶段分配更高推理算力，在实现阶段分配较低算力。Codex CLI 的 --reasoning-effort 标志和快捷控制（Alt+,/Alt+.）支持手动调整，但尚无自动化的阶段级预算内置支持。

5. Environment-aware prompting（环境感知提示） 使用强调可测试性标准和时间预算的系统提示。标准 AGENTS.md 实践。

单一基准测试可能是偶然；但这并非孤例。首个关于哈尼斯工程的同行评审综述编录了相同的结构，并引用了两个进一步推进结论的结果。^(²⁶⁹) Meta-Harness 测得仅靠哈尼斯变更即带来 6 倍性能差距，而 CAAF 框架展示了确定性的哈尼斯约束在模型规模之上取胜：约束良好的小模型优于无约束的大模型。该综述还记录了工业界源头，OpenAI 创造了该术语，而一个由三到七名工程师组成的团队在五个月内交付了约一百万行生产代码。一个基准测试团队、两个学术框架、一个生产团队，通过不同路径得出了相同结论。

差距为何存在，以及该怎么做

量化的差距需要解释，而 Addy Osmani 2026 年的两篇文章提供了最有用的解释。“工厂模型”文章命名了这一转变：软件经历了三代——自动补全、同步智能体、能独立工作并交付制品供审查的自主智能体，瓶颈也随之转移。“生成不再是瓶颈；验证才是。”^(²⁷⁰) 这一句话就是为什么工作量证明而非原始输出，才是哈尼斯必须保证的东西，而 Osmani 的建议（强制红/绿 TDD、规范清晰度作为杠杆、整洁架构作为放大器）则是从实践者视角重述的三大支柱。

其后续文章“Agent Harness Engineering”（智能体哈尼斯工程）编录了哈尼斯实际包含的内容（文件系统与 Git 集成、代码执行、沙箱、记忆与知识集成、上下文管理、强制执行钩子，每个组件本书读者都会熟悉），并论证它们构成一门学科而非一包技巧。^(²⁷¹) 其中两个思想是核心支撑。棘轮原则认为，每次智能体失败都应转化为永久性的哈尼斯变更，使失败不再复发：AGENTS.md 新增一行、新增一个钩子、收紧一条沙箱规则，每一个咔哒声都防止倒退。“优秀 AGENTS.md 中的每一行都应能追溯到一个具体的出错事件。”这是从配置侧看到的工作量证明循环，证据积累成策略。“技能问题”重构——Osmani 将其归功于 HumanLayer——将本章论点转化为诊断：大多数智能体失败是配置问题，而非能力缺口。证据形态与 LangChain 相同：Claude Opus 4.6 仅通过从默认环境迁移到自定义哈尼斯，就在 Terminal Bench 2.0 上获得显著更高分。模型未变；哈尼斯变了。

这也揭示了行业走向。Osmani 提出 Harness-as-a-Service (HaaS，哈尼斯即服务)：提供执行循环、工具系统和上下文管理作为产品的完整运行时。Claude Agent SDK、Codex SDK 和 OpenAI Agents SDK 是早期实例，^(²⁷²) 对企业团队（第 17 章）而言，强大的哈尼斯 API 可免除自建编排的需求。代价是比模型锁定更深的锁定，因为哈尼斯编码了你团队的特定失败历史，正是让它有价值的那个棘轮。

同一发现，来自厂商内部

基准测试和框架可能仍是爱好者自说自话。最有力的制衡来自第一方，源自 Arnaud Fournier——OpenAI 面向欧洲和中东的现场开发工程负责人。^(²⁷³) 他的标志性观察是：OpenAI 自身工程师已“从编写原始代码转向哈尼斯工程”，该模式正在企业客户中复制，包括 John Deere、Amgen 和半导体企业。两个数字为此定调。约 20% 的企业客户采用智能体框架而非直接调用 API：在一个十八个月前尚不存在的品类中，这已是早期大众采用。而成效最好的客户，是那些投资哈尼斯基础设施（上下文管理、审批流水线、工具编排）而非仅优化提示的客户。这就是 Meta-Harness 差距和 LangChain 排名，在生产部署中而非排行榜上再次被观察到。

这四方陈述无共同方法论，亦无动机达成一致，这正是它们的一致性具有分量的原因。一次受控基准测试、一次学术综述、一位实践者的现场笔记、一次厂商的企业级实践，全部落在同一条指令上，这也是要执行的指令：先完善哈尼斯，再寻求更大模型。本章前文的一切，都是在讲如何做到这一点。

更大的图景

跳出机制细节看，哈尼斯工程实质上是对“当智能体负责敲代码时，专业软件工作变成什么”的一种立场。

Karpathy 的区分：Vibe Coding 与 Agentic Engineering

2026 年 4 月，Andrej Karpathy 划出一条线，厘清了哈尼斯工程的全部目的。^(²⁷⁴) 在红杉资本演讲中，他区分了面对智能体革命的两种反应。Vibe coding（氛围编程）抬高地板：人人可通过描述需求并信任模型生成来构建软件。Agentic engineering（智能体工程）守住质量线：专业团队在不牺牲智能体到来前就存在的安全性、可靠性、可维护性标准下实现提速。

这种区别至关重要，因为它们朝着相反的方向施力

氛围编程（Vibe coding）通过移除约束而成功：无测试、无评审、无架构，只有自然语言输入和可工作的软件输出。智能体工程（Agentic engineering）通过添加约束（即护栏）而成功，使智能体在能让其输出值得信赖的边界内运行。Karpathy 的阐述明确了本章隐含的论点：护栏不是开销。它就是工程。

Karpathy 的三条观察直接映射到护栏概念

1. “智能体是实习生实体。” 你负责品味、判断和设计。智能体填补空白。这就是前文所述的规格优先、工作量证明模型：人类编写 WORKFLOW.md 并定义验收标准；智能体实现；护栏验证。

2. “复制粘贴给智能体的那段文本是什么？那才是现在的编程范式。” Karpathy 称之为软件 3.0：上下文窗口是杠杆，LLM 是解释器。你仓库中的 AGENTS.md 和 WORKFLOW.md 文件正是那段文本。它们是你用软件 3.0 范式表达的程序。

3. “模型是参差不齐的。Opus 4.7 能重构 10 万行代码库，却让你走五十米外去洗车。” 这种参差不齐（Jaggedness）正是你无法将人类移出循环的原因。护栏通过捕捉模型看不见的失败来补偿这种参差不齐：钩子强制执行模型忽略的 lint 规则，沙箱策略阻止模型不应采取的行动，工作量证明要求迫使模型产出证据而非自我报告成功。

Karpathy 还指出，智能体工程师的上限是“远超 10 倍”，但仅限于那些投资于其设置（Setup）的人。设置就是护栏。 获得数量级吞吐量提升的从业者，构建了最丰富、最完善的配置：技能、钩子、审批策略、测试套件，以及经过数百次会话打磨的 AGENTS.md 文件。

OpenClaw 的警世故事

OpenClaw 的警世故事展示了缺乏这种纪律会发生什么。[²⁷⁵] OpenClaw 是一款连接邮件、日历和消息的个人 AI 助手，在八周内获得了 24.7 万 GitHub 星标。但未部署护栏的用户遭遇了级联故障：一个“心跳”功能在无任务情况下每月烧掉 $86 的 token；上下文压缩悄无声息地丢弃了安全规则（一位用户的“执行前务必确认”指令被摘要掉了，智能体开始自主删除邮件）；通过邮件的提示词注入导致 SSH 密钥外泄；版本升级导致记忆清空。幸存的用户汇聚出了一份读起来像护栏工程入门指南的实战手册：一个小工作流、便宜模型处理常规任务、沙箱隔离、可控的爆炸半径。他们通过痛苦的经验而非刻意设计，重新发现了三大支柱（密封测试、机器可读文档和模块化架构）。

Karpathy 用来形容氛围编程与智能体工程之间差距的短语，是“抬高地板”与“守住天花板”之间的差距。护栏正是守住天花板的关键。

前线部署工程师即护栏实践者

护栏工程不仅是一门软件学科；它越来越成为一门面向客户的学科。前线部署工程师（FDE）角色在 2025 年增长了 800% 到 1000%[²⁷⁶]，正是护栏工程实践的化身。

FDE 直接嵌入企业客户团队，梳理其现有开发工作流，构建符合客户代码库惯例的 AGENTS.md 宪章，将 Codex 应用服务器接入 CI 流水线，通过 requirements.toml 锁定沙箱策略，并配置 OpenTelemetry 导出到客户的可观测性栈。FDE 的日常工作（发现、快速原型、生产强化、向核心产品团队反馈）就是将护栏工程应用于特定客户的约束中。对于构建内部护栏的团队，FDE 实战手册提供了一个有用的思维模型：将你自己的工程组织视为“客户”，并应用从发现到强化的相同结构化演进过程。[²⁷⁷]

总结

1. 护栏工程是一门学科。 它设计基础设施、约束和反馈循环，使 AI 智能体可靠地高产。它位于提示词工程和传统软件工程之上一层。

2. 三大支柱支撑着一个适配护栏的代码库。 密封测试、机器可读文档和模块化架构。任一支柱的薄弱都会迫使智能体猜测，而猜测消耗 token 并引入错误。

3. WORKFLOW.md 为智能体策略提供版本控制。 它将 YAML 前置元数据（运行时配置）与 Liquid 模板化的 Markdown 正文（智能体提示词）结合为单一版本化制品。智能体策略成为你仓库的一等公民，接受与应用代码相同的评审和回滚流程。

4. 状态持久化幸存于中断。 会话 ID、检查点文件或数据库支持的状态，让长时间运行的智能体能在不重复已完成工作的情况下恢复。合适的层级取决于任务的时长和成本。

5. 错误恢复匹配三种失败类型。 针对瞬时失败采用带退避的重试，针对判断调用采用人工升级，针对必须在重试前撤销的部分应用变更采用回滚。

6. 工作量证明让智能体负责。 智能体必须通过可验证的证据（如 CI 通过状态、代码评审反馈、变更摘要或演示视频）证明完成情况，而非自我报告。这将智能体从黑盒转变为可问责的行动者。

7. Symphony 是参考实现。 OpenAI 的开源护栏在规模上展示了这些模式。其 WORKFLOW.md 格式、工作量证明强制执行以及 Elixir/BEAM 架构值得研究，即使你不直接采用该工具。

8. NanoClaw 展示了持久化编排。 常驻调度、容器隔离和基于通道的通信，补充了 Symphony 面向批处理、由 Issue 驱动的方法。生产部署可能针对不同类别的工作同时使用这两种模式。

9. 生态系统提供护栏组件。 Docker MCP Toolkit 将 MCP 服务器打包为单一网关后的容器镜像，配置文件可作为 OCI 制品共享；内置的代码评审技能无需自定义工具即可提供第一方评审；Codex 应用服务器的 JSON-RPC 协议通过 stdio 或 WebSocket 驱动仪表板、编排器和审批网关。每一个都是你可以采纳而非自建的组件。

10. 学科正在收敛，技能经久耐用。 独立信号指向同一方向：Cursor 2026 年 4 月的说明描述了“从以模型为中心的吹嘘转向以护栏为中心的工程”，[²⁷⁸] Altman 则将护栏与模型定位为日益不可分割，模型周围的运行时现已成为产品接口的一部分。[²⁷⁹] 护栏工程是技术栈的永久层级，而非模型局限性的临时变通，因此护栏技能是耐用的投资，而非下一代模型就会淘汰的脚手架。

练习

1. 为智能体使用强化你的测试套件。 依据密封性标准审计你项目的测试套件：每个测试能否离线运行、通过单一命令执行、并产生确定性输出？对于每个未通过审计的测试，识别其外部依赖，实现模拟或种子数据，并验证该测试在无网络访问的情况下连续十次本地运行均稳定通过。

2. 为真实任务编写 WORKFLOW.md

选择项目中一个重复性任务，例如修复特定类别的 Bug、实现标准功能类型或更新依赖。编写一个带有 YAML 前置内容的 WORKFLOW.md，其中记录模型、轮次限制和所需的工作量证明工件，以及一个用于参数化任务特定上下文的 Liquid 模板主体。通过 Codex CLI exec 会话运行渲染后的提示词，并评估 Agent 的行为是否符合你预期的策略。

3. 实现基于检查点的恢复

从现有工作中获取一个多阶段 Codex CLI 流水线，或设计一个包含至少三个不同阶段的新流水线。在工具框架中实现检查点文件的写入/读取逻辑：在每个阶段开始前，读取检查点以确定其是否已完成；在每个阶段结束后，写入包含累积状态的检查点。故意在运行中途中断流水线，并验证其是否从正确的阶段恢复，而不是从头开始。

4. 为团队定义工作量证明标准

以 Symphony 工作量证明模型为灵感，定义 Agent 在任务被视为完成前必须产出的工件，以适应你团队的工作流。至少需涵盖：

1. 需要何种功能验证（测试通过率、CI 状态）

2. 需要何种可审查工件（差异摘要、演示说明）

3. 需要何种文档工件（更新后的 AGENTS.md、CHANGELOG 条目或决策日志条目）

将此标准写入项目的 AGENTS.md，并将其应用于接下来的三个由 Agent 生成的 PR 中。

5. 基准测试你的工具框架可靠性

通过当前的 Codex CLI 工作流运行一组具有代表性的 5 到 10 个任务，并记录成功率（无需人工干预即可完成并通过所有门控的任务比例）。然后实施本章中的一项具体工具框架改进，例如更好的隔离测试、WORKFLOW.md 策略或基于检查点的恢复，并重新运行相同的任务。计算成功率的提升，并推算一个月典型使用量下的价值。这将为你提供一个具体的 ROI 数据，可与工程管理层分享。

第二十八章：Agentic Engineering Pod（智能体工程小组）

第 27 章 表明，决定 Agent 是否能产出可靠工作的是工具框架，而非模型。本章提出了该问题的组织层面版本：谁拥有工具框架，以及如何围绕它组建团队？当 Agent 负责大部分执行工作时，人类掌握着 Agent 无法自行回答的三个问题：

• 我们为什么要构建这个？（成果、战略、上下文）

• 应该如何构建？（编排、判断、实现标准）

• 我们能信任构建出的东西吗？（验证、安全、质量否决权）

Agentic Engineering Pod 围绕这三个问题组织三个人，每个人都由 Agent 增强，共享单一的上下文层。

学习目标

你将能够：

1. 为三个 Pod 角色中的每一个的 Agent 调用编写生产就绪的 TOML 配置

2. 设计 Pod 的 AGENTS.md 层级结构，包括仓库级、子目录级和角色特定文件

3. 演示一个特性完整的 Pod 生命周期：框架设定、编排、自动化验证

4. 编写 Quality Engineer（质量工程师）用于强制执行信任平台的钩子和门控

5. 诊断陷入困境的 Pod 属于哪种失效模式，并应用相应的修复方案

6. 将 Pod 基础设施打包为插件，并利用市场策略在多个 Pod 间强制执行一致的配置

起点，而非蓝图。 本章中的 Agentic Engineering Pod 是团队围绕 Codex CLI 等 Agent 进行组织的一个成熟范例，而非最终或教条式的答案。围绕编码 Agent 构建团队是新领域，此处的约定将随着领域成熟而不断完善。请将 Pod 视为思考你自身结构的框架：采纳适用的部分，根据你的上下文调整角色和边界，并预期具体细节的演进速度将快于本书大部分内容。

为什么是三个角色？

约束已从生成转移到验证

从变化之处入手。在软件历史的大部分时间里，稀缺资源是生成：编写代码、连接集成、编写测试。Agent 使生成变得廉价且快速，这将约束移到了别处。如今，交付的瓶颈在于验证，即团队证明生成输出正确、安全、可维护并准备好进入下一阶段的速率。

这重新定义了何为进步。无人验证的生成输出不是价值；它是库存，看似进步实则尚不可交付的工作。快速的 Agent 生成库存的速度可能超过缓慢团队审查的速度，未经审查的量不是加速，而是累积的风险。进步是经验证的价值：符合意图、通过测试、尊重项目约束、安全、可运维且可解释的输出。

这就是为什么 Pod 围绕三个人的问题而组织，而非围绕 Agent 现已吸收的实现工作，也是为什么负责验证的角色——Quality Engineer——在该模型中比传统团队中的 “QA” 承担更大的权重。

传统团队结构的问题

传统团队结构在每个专业化边界上都产生协调开销：需求到工程，工程到 QA，QA 到 DevOps。当 Agent 执行工作时，这些交接变得更加昂贵，因为每个边界都引入了 Agent 不需要的延迟和它们无法在无人工干预下恢复的上下文丢失。

更深层的问题是所有权分散。没有单一人拥有从业务成果到生产验证的完整链条。当 Agent 生成代码时，所有权分散意味着无人对系统是否正确、安全地做着正确的事拥有完整图景。

三人法则

Agentic Engineering Pod 通过激进的简化解决了这个问题：三项责任，一层共享上下文。

之所以有三项责任，是因为每一项都是生产者的工作，且无一是协调工作。Pod 是责任分离，而非层级。Agent 处理常规工作（样板代码、脚手架、测试生成、CI 运行），从而让人类专注于高判断力工作。第四项责任要么是其中之一的重复，要么就是协调本身，这是 Pod 不应具备的复杂性症状。

架构原则：人指挥 Agent；而非管理其他人。 协调流向人→Agent，而非人→人。当交付需求增加时，启动共享平台层的并行 Pod，而非扩大现有 Pod。扩展平台，而非 Pod。

该法则关乎责任，而非人数。Pod 保证所有三项责任都有明确、无重叠的归属；它不坚持必须恰好有三个具名个体。在小型项目中，一人可兼任多项责任，且单个传统职位名称通常跨越两三项 Pod 职责。绝不能发生的是责任无人负责。从传统角色到 Pod 职责的映射很直观：

| 传统角色 | Pod 职责 |

| --- | --- |

| 产品经理、产品负责人、业务分析师、工程经理、领域专家 | Context Architect（上下文架构师） |

| 工程师、架构师、设计师 | Value Engineer（价值工程师） |

| QA、SDET、DevOps、SRE、平台、安全、MLOps、治理与合规 | Quality Engineer（质量工程师） |

关键结构洞见

Pod 的三个角色直接映射到 Agentic 交付模型中留给人类的三个问题：

| 角色 | 类型 | 负责范围 | 回答问题 |

| :--- | :--- | :--- | :--- |

| 上下文架构师 | 人类 | “为什么”和“是什么” | 我们追求什么成果？智能体需要什么上下文？有哪些护栏？ |

| 价值工程师 | 人类 | “怎么做” | 我们如何编排交付？好的实现是什么样的？ |

| 质量工程师 | 人类 | “信任” | 我们能否证明所构建的是正确、安全、可靠的？谁对证据负责？ |

所有三个 Pod 角色均为人类。智能体（Codex 会话、技能、钩子、权限、自动化门禁）是每位人类所驾驭的工具。Pod 中不存在“智能体角色”。智能体拥有能力；人类承担角色。

这些边界反映了人类导致智能体系统失败的三种方式：上下文不佳（上下文架构师失职）、编排不善或错过架构偏移（价值工程师失职），或在缺乏充分验证的情况下发布（质量工程师失职）。Pod 使每种失败模式都可见且可追责。

https://github.com/OpenDocCN/freelearn-dl-zh/tree/master/docs/agentic-coding-with-openai-codex-cli/img/B40007_28_01.jpg

图 28.1 - Pod：三个角色与流向

智能体工程 Pod 的示意图，展示了三个角色形成一个循环。上下文架构师负责“为什么”和“是什么”（成果、上下文、护栏），并将上下文和护栏传递给价值工程师，后者负责“怎么做”（编排、实现标准），并将实现传递给质量工程师进行验证，后者负责“信任”（验证、证据问责），并返回关于正确性和风险的反馈。一个单独的“智能体”框（Codex 会话、钩子、自动化门禁）通过虚线连接到所有三个角色，作为每位人类驾驭的工具。

角色及其智能体孪生

每个角色都与一个同名的智能体配置配对：本章后面介绍的 TOML 文件（context-architect.toml、value-engineer.toml、quality-engineer.toml）。共享名称是有意为之。TOML 文件是该角色的智能体孪生，一个针对该角色工作调优的智能体，拥有该角色任务所需的模型层级、审批姿态和沙箱。

不过，孪生并非固定工具。每个角色的深层工作是随时间将自身复制到孪生中，将角色持有者的判断编码到配置、AGENTS.md 上下文以及孪生所依赖的技能中，使智能体能更多时间地按人类方式行事。每一次会话重定向、每一次简报优化、每一个新增门禁，都是人类在教导孪生按其方式行事。杠杆效应复利增长：孪生捕获了原本只存在于某人脑海中的隐性知识，教导得越好，人类就越少需要手动干预。这就是自主阶梯背后的机制：当孪生赢得了足够的证据被信任处理某类变更时，该类变更就会跃升一个层级。

这也是为什么孪生是人类驾驭的能力，而非第二个角色持有者。判断、问责和角色本身始终属于人类；随时间改变的是孪生吸收了多少人类的技艺。名为 context-architect 的智能体不是上下文架构师；它是上下文架构师不断进化的工具，保持其锐利是该角色的一部分。

质量决定节奏

在深入角色本身之前，有一条运营原则必须确立，因为它塑造了所有三个角色。人们很容易把验证想成流水线末端的一个关卡：智能体生产，合并主分支前验证先行。这幅图景是不完整的。一旦生成变得廉价，决定 Pod 交付速度的不是生产速度，而是验证速度。验证吞吐量，而非生成吞吐量，才是进度的真实度量。

由此引出两个后果。首先，已生成但未验证的工作应控制在有界队列中，而非允许堆积；不断增长的未审查输出积压的是风险，而非已存进度。其次，价值工程师只有在质量工程师的验证能力能消化时，才应释放更多智能体工作。验证不是最后拧上的终点关卡；它决定交付节奏。

这重构了团队花费智能体红利的方式。廉价生成产生红利，Pod 可两用：用于更多平庸输出，或用于更强规格、更好测试和更深验证。对于企业级软件，将部分红利再投资于质量通常回报更高，因为它提升了如今制约整个系统的验证上限。

哪些章节奠基各角色

Pod 综合了全书内容：每个角色的技艺源自分布在前几部分的多个章节，而非单一部分，接下来三节将逐一展开。各角色最相关的章节：

• 上下文架构师。 第 4 章 (AGENTS.md) 是核心参考，因为 AGENTS.md 层级是该角色的主要产出物。第 3 章 (提示工程) 支撑规范编写和答疑会范围界定模式；第 5 章 (审批模式与信任边界) 和 第 17 章 (企业级部署) 为战略护栏、策略和自主阶梯提供依据；第 10 章 (技能) 是角色技艺变为可分发基础设施的途径。

• 价值工程师。 第 11 章 (子智能体) 和 第 12 章 (多智能体编排) 是该角色所负责的智能体循环工程的核心。第 14 章 (成本管理) 驱动速度、Token 成本与置信度之间的权衡；第 3 章 (提示工程) 是简报工程的基础；第 13 章 (工作树) 为特性会话提供隔离；第 20 章 (AI 代码审查) 配合 第 10 章 (技能) 支持成比例审查和可复用审查技能。

• 质量工程师。 第 9 章 (钩子) 是主要强制机制，第 5 章 (审批模式与信任边界) 设定沙箱和审批姿态。第 15 章 (CI/CD)、第 16 章 (安全加固) 和 第 19 章 (测试与评估) 构成信任平台的运营骨干，第 20 章 (AI 代码审查) 为验证门禁提供输入。

这也是角色到部分映射仅为近似的原因：价值工程师最贴近第 3 部分 (规模化)，质量工程师最贴近第 2 部分 (护栏) 的强制原语，而上下文架构师具体对应 第 4 章 而非第 1 部分整体。

上下文架构师：人类角色

上下文架构师负责什么

上下文架构师负责成果与环境：Pod 是否兑现承诺、智能体是否基于准确上下文工作、战略方向是否与业务意图保持一致。其杠杆来自创建可复用的上下文、技能和护栏，而非驱动单个特性会话。

上下文架构师的四大责任领域：

工厂管治。 Pod 可复用生产系统的管治者：上下文、技能与护栏。制定高信号简报标准，塑造审查循环。反复出现的摩擦反哺上下文层优化。

结果定义与价值实现

业务赞助商的主要接口。将模糊的业务反馈转化为可执行的上下文，掌控产品叙事，并以成本价值为依据界定交付权衡，包括“代理经济学”。

上下文工程

策划模式、文档和决策记录，赋予代理做出正确底层决策所需的“直觉”。无情地管理信噪比：相互矛盾或过时的上下文会产生相互矛盾或陈旧的输出。

战略护栏与策略

定义法律、伦理和安全护栏。将合规要求转化为结构化策略，并定义升级阈值（哪些可自动运行，哪些需要人工批准）。

自主阶梯

Level 1: Assist 代理建议；人工审查并应用每项变更
Level 2: Approval-required 代理执行；每项操作执行前需人工批准
Level 3: Policy-bounded 代理在定义边界内执行；例外情况升级处理
Level 4: Self-remediating 代理在护栏内检测、诊断并修复

阶梯晋升需要证据（测试覆盖率、审查历史、审计日志），而非自信。层级按变更类别分配，而非按模块：支付处理模块的架构变更可能永久保持 Level 2，而读路径优化则可能为 Level 3。

AGENTS.md 作为上下文架构师的核心产出物

AGENTS.md 并非众多配置文件中的一个：它是上下文架构师的核心交付物。^[5] 价值工程师运行的每次 Codex 会话、质量工程师触发的每个自动化检查，都从该层级读取上下文。Pod 的输出质量受限于该文档的质量。

生产环境 Pod 的层级结构：

~/.codex/AGENTS.md # 个人偏好，永不提交
AGENTS.md # 仓库级：Pod 的事实来源
src/payments/AGENTS.md # 限界上下文的领域约束
src/auth/AGENTS.md # 认证模块更严格的安全约束
.codex/roles/value-engineer.md # 角色专用指令
.codex/roles/quality-engineer.md # 角色专用 QE 指令

仓库级 AGENTS.md 包含产品描述、验收标准、架构约束、批准的依赖列表和完成的定义。每个代理首先读取它。子目录 AGENTS.md 文件编码跨冲刺持久的领域特定约束。更具体的文件覆盖更通用的文件，因此在 src/auth/ 中工作的代理会自动继承更严格的约束，无需显式指令。

一份编写良好的仓库级 AGENTS.md 如下所示：

##### 产品上下文
该服务是用户订阅状态的权威来源。
代理不得引入任何从多个事实来源派生订阅状态的路径。
##### 验收标准
每项功能必须包含：
1. 面向用户的结果陈述（“处于[状态]的用户可以[操作]...”）
2. 至少一个包含预期行为的失败场景
3. 任何面向用户路径的性能界限 (<200ms p95)
##### 架构约束
- 所有外部数据在边界处使用 zod 验证
- 禁止跨模块数据库查询；每个模块拥有其架构
- 所有状态变更在返回前必须发出审计事件
##### 批准的依赖
见 .codex/approved-deps.json。添加未列出的依赖要求
在代理继续之前获得 ADR 批准。
##### 自主级别
- 读路径变更：Policy-bounded (Level 3)
- 写路径变更：Approval-required (Level 2)
- 架构变更：Approval-required (Level 2)
- 基础设施变更：Assist (Level 1)

规范作为强制函数

一种有用的模式是“办公时间”技能：一种结构化的产品对话，在编写任何代码之前触发，要求明确回答四个问题：我们在解决什么问题，可观测层面的成功标准是什么，什么不在范围内，哪些约束是不可商量的。以这种方式设计的 Codex 技能，直到范围和成功标准被确认之前，不会让会话继续进行。某功能的 AGENTS.md 条目，在答案写下来之前不应存在。

将上下文架构师的技艺作为插件分发

上下文架构师的规范技能、办公时间范围界定对话、AGENTS.md 健康检查和 ADR 编写模板，代表了不应只存在于某个人脑海中的组织知识。插件系统原生支持将技能（连同钩子、MCP 服务器和应用连接器）打包为单个可安装单元；编写本文时，文档化的插件规范并未将自定义代理角色 TOML 或 AGENTS.md 模板列为一等插件组件，因此这些作为捆绑文件随行，而非自动注入。当最资深的上下文架构师改进技能或增加上下文漂移检查时，每个 Pod 都通过版本升级接收更新。技艺由此成为可分发的基础设施，而非部落知识。这是一个贯穿所有三个角色的模式的首次显现，后文将在“通过插件分发 Pod”下统一论述。

上下文架构师 TOML 配置

上下文架构师的 Codex 调用属于规范与架构工作：产出 ADR、更新 AGENTS.md、验证验收标准、评估上下文漂移。这些会话使用高推理模型，且不在全自动模式下运行；上下文架构师制定策略，而非实现。

上下文架构师的代理孪生体：

##### .codex/agents/context-architect.toml
name = "context-architect"
description = "规范制定、ADR 编写、AGENTS.md 维护、上下文质量审查。"
developer_instructions = """
你正在协助上下文架构师进行高判断力的上下文和规范工作。
你处理的任务：
- 在层级的任何级别起草或更新 AGENTS.md 文件
- 编写或审查 ADR（架构决策记录）
- 将验收标准转化为可验证的具体形式
- 评估现有上下文文档是否最新准确
- 识别上下文层中的缺口或矛盾
规则：
- 请勿编写功能实现代码
- 请勿修改 .codex/ 或 docs/ 之外的源文件
- 如果产出 ADR，请遵循 .codex/adr-template.md 中的格式
- 标记任何需要人工决策后代理才能继续的上下文缺口
- 当文档集准备好供 Pod 使用时，输出 CONTEXT_COMPLETE
"""
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "workspace-write"

approval_policy = "untrusted" 是有意为之。上下文架构师会在提交前审查并批准对上下文层的每一项提议变更。上下文错误会传播到每一个下游代理会话；它们值得在创作环节接受严格的人工审查。

价值工程师：人类角色

价值工程师负责的内容

价值工程师编排端到端交付。该角色要求扎实的软件工程基础，而非只是恰巧使用 AI 工具的项目经理。他们提供技术深度以验证代理输出、识别架构漂移、捕捉正确性故障、并维护代理无法单方面强制执行的实现标准。

价值工程师的四大责任领域：

系统编排与技术发现

技术主题专家的主要联系人。负责深度发现，将复杂业务规则转化为可执行的系统行为。

简报工程

产出高信号简报：包含意图、约束、示例和边缘情况的结构化提示词，足以让代理在无歧义的情况下执行。简报质量是该角色的核心技艺。

代理循环工程

设计收敛标准、并行度和停止条件。在速度、Token 成本和置信度之间做出深思熟虑的权衡。明确何时让代理运行至完成，何时进行重定向，以及何时使用更好的上下文重新启动。

专家判断与实施标准

对所有逻辑提供最终验证：发现代理可能遗漏的架构偏移、用户体验缺陷或正确性故障。

实战简报工程

低信号简报（为订阅服务添加续订端点）与高信号简报的区别在于具体性，而非长度：

任务：订阅续订端点

意图： 状态为 subscription.status = "expired" 的用户可通过 POST /subscriptions/renew 续订其订阅，无需重新输入支付详情。

约束条件：

• 复用存储在 user.paymentMethodId 中的支付方式

• 续订必须是幂等的：调用该端点两次不得产生两笔费用

• 返回 200 之前必须发出 subscription.renewed 事件

验收标准：

• 状态为 status=expired 的用户在成功调用后变为 status=active

• 状态为 status=active 的用户收到 409 响应，响应体为 {"error": "already_active"}

• Stripe 失败返回 502 并记录错误；订阅状态保持不变

• 在标称负载下，响应时间 p95 < 200ms

范围外： 不要修改支付方式存储逻辑。不要添加新的订阅层级。

参考： 参见 src/subscriptions/AGENTS.md 了解幂等性要求，参见 src/events/types.ts 了解事件架构。

显式的失败场景、清晰的幂等性要求、范围外边界，以及对领域特定 AGENTS.md 的引用。每一项都消除了代理原本需要通过推断来解决的决策点。

价值工程师 Codex 会话模式

典型的功能会话：阅读任务规范和相关的 AGENTS.md 上下文；运行 /plan 验证方法；在工作区的 workspace-write 沙箱^(281) 中执行；根据验收标准审查输出；在输出偏离时进行重定向；实现整洁后移交给质量工程师的质量门禁。每个功能都位于各自的工作树中；主分支仅接收经过审查、通过质量门禁的输出。

决定何时并行化：指标自由度

指标自由度（第 11 章）为价值工程师提供了一种原则性的方法，用于决定何时生成并行子代理，何时在单个会话中保持任务。它是一个单一数值，F = 1 − ρ(D_out, D_score)，用于衡量任务是否从多样化输出中受益（高 F）或要求单一正确答案（低 F）。在将功能分解为代理任务时应用它：

• 高 F 子任务（代码审查、文档编写、测试生成）分配给并行子代理，在这些任务中多样性是资产；扇出至多代理角色，让多个代理探索不同方法。

• 低 F 子任务（Bug 修复、迁移、架构变更）分配给单个具有高推理力的代理，在这些任务中精确度比多样性更重要；将任务特定知识编码进聚焦的提示词，而非支付并行化的协调开销。

质量工程师使用同一数值来校准验证：高 F 输出需要对方法选择进行人工审查（代理是否从众多有效方法中选出了好的一种？），而低 F 输出需要自动化正确性检查（代理是否产出了唯一的正确答案？）。

成比例的审查深度

审查深度应随差异规模缩放。小型自包含差异（约 50 行以内，单一逻辑单元）：是否实现了声称的功能，是否存在明显的正确性问题，是否引入了被排除的依赖？大型差异（涉及多模块、核心逻辑重写）值得进行四遍审查：意图对齐、正确性（竞态条件、边缘情况、失败路径）、副作用、完整性（测试到位、验收标准可演示）。价值工程师可将其编码为一项审查技能，根据 git diff --stat 输出路由至快速通道或全量通道。

价值工程师 TOML 配置

价值工程师的代理孪生体：

##### .codex/agents/value-engineer.toml
name = "value-engineer"
description = "功能实现、编排与代理监督会话。"
developer_instructions = """
你正在为价值工程师执行一项功能实现任务。
开始前：
1. 阅读 AGENTS.md 以及与此任务相关的任何子目录 AGENTS.md
2. 阅读任务简报并确认你理解验收标准
3. 如果任何约束存在歧义，在编写代码前将其暴露出来
实施期间：
- 在每个逻辑变更组后运行测试
- 如果测试失败，在继续前修复失败；绝不跳过
- 如果遇到简报未涵盖的架构决策，
  将其写入 .codex/clarifications.md 并暂停等待审查
- 跟踪简报中的验收标准：在发出完成信号前，每一项必须可演示地得到满足
完成信号：IMPLEMENTATION_COMPLETE，附带以下摘要：
- 每项验收标准及其是否满足
- 超出简报范围处理的任何边缘情况
- 任何延期待质量工程师审查的事项
"""
model = "gpt-5.4-mini"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

approval_policy = "on-request" 适用于价值工程师的工作树会话：代理在限定工作树内执行，验收标准明确，且质量工程师的质量门禁会在任何输出到达主分支前触发。模型决定何时升级至价值工程师以获批准，让常规文件编辑顺畅进行，同时浮现任何看起来异常的情况。

质量工程师：人类角色

质量工程师负责的事项

质量工程师负责信任平台：CI/CD 流水线、自动化质量门禁、安全控制和验证基础设施。他们掌握质量否决权：无论由谁或何物产生变更，均有权阻止。无论是价值工程师还是上下文架构师都无法覆盖这些门禁。这种权威是结构性的，而非政治性的。

否决权之所以存在，是因为问责制无法委托给代理。编码代理无法为其交付的产物担责；发布产品的组织才对其负责。因此，企业级交付运行在证据之上，而非信心之上：质量工程师的工作是让团队能够展示要求是什么、代理做了什么、测试了什么、谁审查了它，以及为什么结果可以安全发布。当证据不足时，否决权就是阻止工作的机制，无论生产者是谁或何物。

质量工程师的四大职责领域：

验证与质量工程

设计并构建验证功能正确性、性能和可靠性的自动化系统。推动安全工具契约模式：类型化的输入/输出、幂等性、最小权限、允许列表。

对抗性测试

主动对代理工作流进行红队演练，针对提示词注入、不安全工具使用和数据泄露。这是一项持续的工程实践，而非定期审计。

运营骨干

维护 CI/CD 流水线、安全上下文存储、代理隔离、依赖扫描和供应链完整性。

自主性强制执行

实现使上下文架构师的自主性阶梯从愿景变为现实的钩子、质量门禁和流水线检查。

确定性工具接口设计

质量工程师设计构造上安全的代理工具接口。有三项属性是不可妥协的：

类型化的输入与输出

团队代理使用的每个工具都应具有显式的输入模式和输出契约。非类型化接口使验证变得不可能，并导致副作用不可预测。

质量工程师原则与实施

幂等性

工具必须支持使用相同输入多次安全调用。智能体会重试；非幂等工具会导致重复扣费、重复记录和状态不一致。

最小权限

每个智能体角色应仅访问其所需的工具。实施智能体不需要生产数据库凭据。审查智能体不需要源文件的写入权限。质量工程师设计权限结构并根据实际智能体行为进行验证。

质量工程师编写的钩子

钩子[²⁸²]是质量工程师的主要强制执行机制。有三个钩子点最为关键：

预提示钩子（UserPromptSubmit）

在任何提示进入智能体上下文之前触发。用于策略强制执行：扫描提示注入模式、验证正确的工作树、检查 AGENTS.md 上下文是否为最新。

每次写入钩子（PostToolUse）

在每次工具调用完成后触发。正如第 9 章所述，PostToolUse 观察的是事后结果而非把关动作：工具已经运行完毕，因此钩子将发现结果呈现到上下文中并以退出码 0 退出，而不是阻塞。这是在同一会话中让智能体能够采取行动的快速、文件级反馈的正确切入点。

会话后钩子（Stop）

在 Codex 会话结束时触发。用于验证：运行测试套件、检查是否有超出允许范围的文件被修改、验证审计事件是否已发出、确认预期的完成信号。

###### .codex/hooks/post-session-verify.sh
###### 质量工程师的会话后验证钩子
set -euo pipefail
TASK_ID="${CODEX_TASK_ID:-unknown}"
WORKTREE="${CODEX_WORKTREE:-$(pwd)}"
echo "[QE Hook] Post-session verification for task: $TASK_ID"
###### 1. 运行完整测试套件
echo "[QE Hook] Running test suite..."
npm test --silent 2>&1 | tee ".codex/tasks/$TASK_ID/test-results.log"
###### 2. 验证未修改许可范围外的文件
echo "[QE Hook] Checking file scope..."
MODIFIED=$(git diff --name-only HEAD)
VIOLATIONS=$(echo "$MODIFIED" | grep -E "^(infrastructure/|AGENTS\.md)" || true)
if [ -n "$VIOLATIONS" ]; then
  echo "[QE Hook] SCOPE VIOLATION: agent modified restricted files:"
  echo "$VIOLATIONS"
  exit 1
fi
###### 3. 检查会话日志中的完成信号
if ! grep -q "IMPLEMENTATION_COMPLETE" ".codex/tasks/$TASK_ID/session.log" 2>/dev/null; then
  echo "[QE Hook] WARNING: No IMPLEMENTATION_COMPLETE signal found in session log"
fi
echo "[QE Hook] Verification complete. Gate: PASSED"

一个更轻量的示例展示了 PostToolUse 模式的独立应用：智能体写入 Markdown 的那一刻就进行 lint 检查，这样风格和结构问题会在智能体仍在循环中时浮现。PostToolUse 匹配器按工具而非文件类型选择，因此钩子会过滤 Markdown 本身，而不是依赖匹配器：

###### .codex/hooks/lint-markdown.sh
###### 质量工程师的每次写入 Markdown lint（PostToolUse）
set -euo pipefail
###### PostToolUse 通过 stdin 传递 JSON 对象；工具名在 `.tool_name` 中。
TOOL="$(jq -r '.tool_name // empty')"
###### 仅在文件写入工具后执行（空工具名允许手动运行）
case "$TOOL" in
  write_file|str_replace_editor|apply_patch|"") ;;
  *) exit 0 ;;
esac
###### 仅 lint 智能体刚刚更改的 Markdown 文件
CHANGED=$(git diff --name-only HEAD -- '*.md')
[ -z "$CHANGED" ] && exit 0
if ! command -v markdownlint >/dev/null 2>&1; then
  echo "[QE Hook] markdownlint not installed; skipping."
  exit 0
fi
echo "### markdownlint results"
echo "$CHANGED" | xargs markdownlint 2>&1 || true
###### 观察，不阻塞：将发现结果呈现到上下文并干净退出。
exit 0

在 .codex/hooks.json 中通过 PostToolUse 进行连接：

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash .codex/hooks/lint-markdown.sh",
            "statusMessage": "Linting changed Markdown...",
            "timeout": 20
          }
        ]
      }
    ]
  }
}

该钩子永远不会导致智能体动作失败；它将 lint 输出作为上下文反馈回来，以便智能体自我纠正。当必须强制执行 Markdown 标准而不仅仅是呈现时，该检查应放在会话后关卡，那里非零退出码可以停止工作。

插件强制钩子：使绕过在结构上不可能

当钩子作为松散脚本存在于 .codex/hooks/ 中时，任何开发者都可以删除或修改它们。插件系统改变了这一点。通过 marketplace.json 中的 INSTALLED_BY_DEFAULT 策略分发的插件钩子会在会话启动时安装，且无法被单个开发者移除。[²⁸³] 质量工程师维护插件；平台团队通过市场策略强制安装。绕过变得不可能，而不仅仅是不建议。同一机制适用于 PostToolUse 钩子：文件范围强制执行、静态分析关卡和审计事件检查会在企业中每个 pod 的每次工具调用时触发。如何跨许多 pod 一致地推广这一点是本章最后一节“使用插件分发 Pod”的主题。

验证经济学：分层成本关卡

验证是有成本的：时间、Token 开销和周期延迟。对每个两行的错误修复都进行全面的对抗性安全审查，这不是严谨的表现；而是流程校准错误的表现。质量工程师的工作不是最大化验证深度，而是将验证工作量与变更风险相匹配。

三层模型效果良好。

第 1 层：静态验证

Lint 检查、类型检查、模式验证。近乎零成本；无一例外地在每次变更时运行。

第 2 层：功能验证

完整测试套件、范围合规检查、验收标准确认。成本较高但属于常规操作；在每次涉及逻辑的变更时运行。

第 3 层：对抗性验证

安全建模（OWASP Top 10、STRIDE）、性能基准测试、对抗性输入测试和手工红队演练。成本高昂；保留用于新认证路径、支付流程、模式变更以及涉及提升信任边界的任何内容。

Codex 技能集可以直接实现这一点。一个打开真实浏览器、操作应用程序、发现错误并生成回归测试的 QA 技能属于第 2 层工作，适用于大多数功能变更。对于具有安全隐患的变更，更重量级的安全审查技能会在之上增加 STRIDE 威胁建模和 OWASP Top 10 审查。验证预算随风险缩放，而非随可用时间或审查者习惯。

质量工程师通过在 AGENTS.md 中将变更类别映射到验证层级来经济高效地实施这一点，这是上下文架构师用于自主阶梯的相同映射。模式变更始终是第 3 层。读路径重构是第 1 层加第 2 层。自动化执行相应层级；质量工程师进行审查，并在判断需要时进行升级。

质量工程师 TOML 配置

质量工程师的自动化验证运行是非交互式的；它们在 CI 中触发，而非在交互式终端会话中。模型层级较低（验证是机械的，而非推理密集型），沙箱则更严格。

质量工程师的智能体孪生体：

.codex/agents/quality-engineer.toml

name = "quality-engineer"
description = "自动化验证：测试执行、安全审查、门禁强制执行。"
developer_instructions = """
您正在对 Agent 生成的输出进行质量工程师验证。
您的任务：
1. 运行完整测试套件并记录结果
2. 运行安全扫描器 (`npm audit --audit-level=moderate`)
3. 检查任务简报中的所有验收标准是否已得到明确满足
4. 识别任务允许范围外被修改的任何文件
5. 检查所有写入路径操作是否已发出审计事件
请勿修改源文件以使测试通过。
请勿禁用或跳过单个测试。
如果测试失败，请完整记录失败详情并输出：`VERIFICATION_FAILED`
如果所有门禁通过，输出：`VERIFICATION_PASSED`
将结果写入 `.codex/tasks/$TASK_ID/verification.md`
"""
model = "gpt-5.4-mini"
model_reasoning_effort = "minimal"
approval_policy = "never"
sandbox_mode = "read-only"

sandbox_mode = "read-only" 是刻意为之。质量工程师的验证 Agent 即使模型产生幻觉指令写入源文件，也无法执行写操作。结合 approval_policy = "never"，该 Agent 在 CI 中非交互式运行，无需人工提示即可执行验证检查，沙箱模式防止任何意外变更。

实战中的 Pod：一个特性的生命周期

以下演示追踪了一个特性在完整 Pod 中的流转：“订阅已过期的用户可以续订，无需重新输入支付详情。”

步骤 1：Context Architect 界定特性

Context Architect 评估 AGENTS.md 是否涵盖续订流程，更新订阅模块以补充缺失的验收标准，并编写简报：

##### 特性：订阅续订
**用户结果：** `status=expired` 的用户可调用 `POST /subscriptions/renew`
并获得 `status=active`，无需重新输入支付详情。
**失败场景：**
- `status=active` 的用户：409，响应体 `{"error": "already_active"}`
- Stripe 失败：502，响应体 `{"error": "payment_failed"}`，订阅状态不变
- 重复调用：第二次调用返回 200 及当前状态，不产生第二次扣费
**性能边界：** 标准负载下 p95 < 200ms
**自主级别：** 写入路径变更：需要审批（第 2 级）

步骤 2：Value Engineer 编排实现

Value Engineer 在专用 worktree 中运行 Codex 会话，策略为 approval-required（这是涉及支付的写入路径变更）：

git worktree add ../worktrees/feature-subscription-renewal -b feature/subscription-renewal
cd ../worktrees/feature-subscription-renewal
codex --profile value-engineer

打开提示词，高信噪比简报：

##### 任务：订阅续订端点
按 src/subscriptions/AGENTS.md 中的验收标准实现 `POST /subscriptions/renew`。
意图：status=expired 的用户调用该端点，使用其存储的支付方式转换为 status=active。无需新的支付详情。
约束：
- 幂等性：重复调用不得产生两笔 Stripe 扣费
- 返回 200 前发出 subscription.renewed 事件
- Stripe 失败：返回 502，记录错误，状态保持不变
- 不得修改支付方式存储逻辑
验收标准：按 src/subscriptions/AGENTS.md 所指定
从 /plan 开始。在编写任何代码前，向我展示受影响文件及依赖顺序。

Agent 运行 /plan；Value Engineer 审查后批准执行。关键的专家判断时刻：Agent 最初的幂等性实现在并发调用下存在竞态条件。重定向指示：

幂等性检查需使用数据库级唯一约束 (user_id, renewal_date)，而非应用层面的读-检-写。

请参阅 src/subscriptions/AGENTS.md 中的幂等性模式要求。

请修订实现方案。

步骤 3：Quality Engineer 的自动化门禁触发

Quality Engineer 的会话后钩子触发，运行测试套件，检查范围合规性，并将结果写入 .codex/tasks/subscription-renewal/verification.md。Quality Engineer 还运行对抗性测试：

对 POST /subscriptions/renew 端点实施实施红队测试。
测试内容：
1. 同一 user_id 的并发调用（竞态条件）
2. 待处理的续订请求期间到达的 Stripe Webhook
3. 可能为同一用户创建第二笔 Stripe 扣费的任何路径
将发现报告至 .codex/tasks/subscription-renewal/security-review.md

对抗性会话未发现绕过路径；数据库级约束生效。VERIFICATION_PASSED；特性可合并。

对于涉及支付的写入路径变更，Pod 在合并前运行多学科门禁作为顺序检查点：工程审查、安全审查（OWASP Top 10 和 STRIDE）及 QA 验证。自主权阶梯与门禁序列共享同一分类表；Quality Engineer 维护两者。

人工判断的介入点

人工判断在此生命周期的四个节点出现：界定特性、审查实现计划、针对竞态条件重定向、批准最终合并。其余一切通过 Pod 的 Agent 层执行。

https://github.com/OpenDocCN/freelearn-dl-zh/tree/master/docs/agentic-coding-with-openai-codex-cli/img/B40007_28_02.png

图 28.2 - 特性在 Pod 中的生命周期

序列图追踪特性从人工批准界定开始，经 Context Architect 更新 AGENTS.md 并将高信噪比简报交给 Value Engineer，后者在 worktree 中规划、获取人工计划批准及竞态条件重定向，再移交 Quality Engineer 验证。Quality Engineer 的会话后钩子运行测试、范围及对抗性检查：通过则人工批准最终合并，检出发现则退回 Value Engineer 修复。人工判断节点标注于界定、计划审查、重定向及最终合并。

失效模式与 Pod 反模式

Context 债务

症状： Agent 输出偏离业务意图。功能实现了技术上正确的代码，却未达成实际预期结果。评审通过但利益相关方拒收。

原因： Context Architect 停止维护 AGENTS.md 层级。过时的验收标准、陈旧的约束和废弃的决策堆积。遵循陈旧上下文的 Agent 产出陈旧输出。

修复： 将 AGENTS.md 评审纳入每个 Sprint 回顾。Context Architect 负责“上下文健康度”指标：陈旧决策、AGENTS.md 标准与实际简报的差距、需大量人工重定向的特性占比。重定向率上升是早期预警信号。

作为插件分发的 context-review 技能可自动化早期检测。在 CI 中作为计划的 codex exec 任务每周或每个 Sprint 边界运行，它会标记陈旧的 AGENTS.md 章节、孤立的验收标准和上升的重定向率，赶在回顾前暴露问题。该插件将上下文健康度从人工审计转变为持续信号。

门禁绕过

症状： 交付速度短期提升，随后急剧下降。自动化门禁本可捕获的安全事件或生产回归。

原因： Value Engineer 为加速交付而禁用钩子或绕过 CI 门禁。“稍后再补测试。”Quality Engineer 的否决权被视为建议而非结构性保障。

修复：结构性强制执行胜过可选门禁

质量工程师的门禁并非可选。结构性修复在于让绕过变得不可能：门禁要求必须经过审计日志记录的显式覆盖，而非可以被静默传递的标志位。绕过门禁并非加快速度；而是将债务向前推至恢复成本高得多的地步。插件系统提供了强制执行：随 INSTALLED_BY_DEFAULT 策略分发的钩子无法被个人开发者移除。市场的 NOT_AVAILABLE 策略可以阻挡可能绕过门禁基础设施的非官方插件。

技能在结构上强化了这一点。门禁技能可要求在继续前进行显式确认：不是布尔标志，而是一份书面确认，证明审查者已查看特定发现。同一逻辑适用于破坏性命令，技能可使 Agent 发出警告并等待，将绕过行为转化为有意的、可追溯的选择，而非轻易的疏忽。质量工程师将同一原则应用于部署门禁：一个要求在管线推进前提供签署确认的验证摘要的钩子。让捷径比正道更难走，是在压力下唯一可靠的预防手段。

单点质量失效

症状： Agent 交付的变更包含安全漏洞、数据泄露或正确性故障。团队缺乏连贯的验证叙事。

原因： 缺乏质量工程师角色，或该角色由将其视为测试执行而非信任平台工程的人担任。门禁仅存在于文档上，未经调优、未经对抗性测试，也未在结构上强制执行。

修复： 质量工程师角色要求深厚的 QA、DevOps 和安全工程基础。它不能是事后诸葛亮。没有真正的信任平台，Agent 自主性的增加就是不安全的，因为没有机制来捕捉 Agent 的错误。

角色坍缩

症状： 协调开销回升。一人身兼数职，在三个领域同时做决策，成为瓶颈。

原因： 一人身兼两个或三个角色。结构依赖于每个角色保持独特的所有权（上下文、编排、信任）。当角色坍缩为一人时，团队的结构性保障随之坍缩。

修复： 恢复角色边界。识别被忽视的领域（通常是上下文工程或信任平台）并引入专人负责。角色坍缩几乎总是相对于雄心而言的人员不足的症状，而非团队模式错误的症状。

范围蔓延

症状： 团队扩大。第四人“临时”加入。协调开销回升。

原因： 交付需求增加，团队随之扩大，为换取表面吞吐量而牺牲了使其高效的结构性属性。

修复： 将三人原则作为运营准则而非偏好。当需求增长时，启动并行团队而非扩大现有团队。三人无法应对需求，几乎总是上下文、工具或流程问题，而非人数问题。

Agent 产生的失效模式，映射至角色

上述反模式是团队自我衰败的方式。单独来看，《第 25 章》中的基准研究确定了 Agent 在任务中最常见的三种失效方式，每种都映射到负责修复的团队角色：

• 导航。 上下文架构师负责此项。Agent 在代码库中迷路的频率远高于误用工具，这使得导航成为最常见的失效类别；AGENTS.md 文件地图、显式路由规则和结构良好的代码库布局是影响最大的干预措施。

• 求助判断。 价值工程师负责此项。Agent 在模糊任务上盲目推进而不升级；校准过的审批模式和使成功标准明确的简报，能减少 Agent 必须判断何时提问的频率。

• 多模态组合。 质量工程师负责此项。代码、测试和文档逐渐不同步；跨模态一致性检查（测试是否匹配代码？文档是否匹配 API？）在门禁处捕捉到它。

工具使用正确性，一直以来是大多数基准测试的焦点，却是这些失效中最不常见的一种；《第 25 章》给出了测得的比率。一个其 AGENTS.md 和编排设计覆盖了所有三类失效的团队，正在解决主导性的失效问题。

通过插件分发团队

上述失效模式是单个团队从内部衰败的方式。规模化引入了不同的压力。范围蔓延的修复建议启动并行团队而非扩大单个团队，但每个新团队随后都必须忠实地复制相同的结构，而依赖手动设置的结构在被复制的那一刻就开始漂移。分发团队是让许多团队在无需手动工作的情况下保持结构一致的问题。

配置问题

一个生产就绪的团队需要：三个角色 TOML 文件、一个 AGENTS.md 层级、用于策略执行和会话后验证的钩子脚本、验证技能、MCP 服务器配置和简报模板。当企业运行十个团队时，这套配置被复制了十次，不可避免地产生漂移。团队三的钩子与团队七的不同。一位上下文架构师以其他人从未采纳的方式演进 AGENTS.md 结构。配置漂移侵蚀了团队模型赖以生存的结构性保障。

插件即团队基础设施

Codex 插件系统原生地将技能、钩子、MCP 服务器和应用连接器打包为单个可安装单元。这直接映射到团队的需求。团队插件打包技能、钩子脚本和 MCP 配置，插件系统原生激活这些组件，同时包含团队依赖的角色 TOML 文件和 AGENTS.md 模板。撰写时，文档化的插件规范未将自定义 Agent 角色 TOML 或 AGENTS.md 模板列为自动连接的组件，因此应将它们视为随原生激活部分一同安装的捆绑载荷，而非插件系统自动注册的内容：

agentic-pod/
├── .codex-plugin/
│ └── plugin.json
├── skills/
│ ├── context-architect/SKILL.md # 规范与 AGENTS.md 维护
│ ├── value-engineer/SKILL.md # 简报工程与实现
│ ├── quality-engineer/SKILL.md # 验证门禁执行
│ ├── office-hours/SKILL.md # 实施前范围界定
│ └── pod-health/SKILL.md # 上下文漂移与角色坍缩检测
├── hooks/
│ ├── pre-prompt-policy.sh # UserPromptSubmit: 注入扫描
│ ├── post-tool-scope.sh # PostToolUse: 文件作用域强制
│ └── post-session-verify.sh # Stop: 测试套件、作用域、审计事件
├── roles/
│ ├── context-architect.toml
│ ├── value-engineer.toml
│ └── quality-engineer.toml
└── templates/
 ├── agents-md-repo.md # 仓库级 AGENTS.md 模板
 ├── agents-md-domain.md # 子目录 AGENTS.md 模板
 └── brief-template.md # 高信噪比简报模板

安装变为 codex plugin add agentic-pod。每位开发者获得相同的角色配置、钩子和验证门禁。漂移在源头被消除。

整体式与可组合式插件

两种打包策略均可行。整体式方法，一个插件包含所有内容，更简单且确保一致性。可组合式方法，三个特定角色插件（pod-context-architect、pod-value-engineer、pod-quality-engineer），更灵活：没有专职质量工程师的团队可仅安装 QE 插件以获得自动化门禁。可组合式方法还允许独立的版本周期：安全团队可更新 QE 对抗性测试而无需动 VE 简报模板。

从单体开始，仅当分化压力真实出现时再进行分解

过早分解会产生 Pod 模型旨在消除的协调开销。

通过市场进行企业治理

插件系统的三层市场层级映射到企业 Pod 治理。仓库市场，即仓库根目录下 .agents/plugins/ 中的 marketplace.json，是企业控制点：

{
 "plugins": {
 "pod-quality-engineer": {
 "source": { "source": "git", "url": "https://github.com/acme/codex-pod-qe.git" },
 "policy": { "installation": "INSTALLED_BY_DEFAULT", "authentication": "ON_INSTALL" }
 },
 "pod-value-engineer": {
 "source": { "source": "git", "url": "https://github.com/acme/codex-pod-ve.git" },
 "policy": { "installation": "INSTALLED_BY_DEFAULT", "authentication": "ON_INSTALL" }
 }
 }
}

INSTALLED_BY_DEFAULT 确保质量工程师的钩子在企业内的每个会话中触发，而不仅限于那些记得配置它们的团队。当平台团队改进验证钩子，增加针对 API 契约验证的新二级检查时，Pod 通过刷新市场（codex plugin marketplace upgrade）即可获取变更；随后 INSTALLED_BY_DEFAULT 策略确保更新后的钩子在下一个会话中生效。

插件不改变的事物

插件分发的是基础设施，而非判断。三个问题依然由三位人类负责。插件改变的是围绕这些问题落地结构的成本。使用插件的 Pod 将时间花在判断上；没有插件的 Pod 则要在配置、同步和漂移修复上花费大量精力。插件系统使智能体 Pod 成为一种可分发的组织模式，而不仅仅是概念模型。

结语

Pod 是智能体企业中的交付单元。三个角色，各自拥有独特的层级，均由智能体放大。该模式有意设计得精简，因为有了智能体，小团队比没有智能体的大团队更强大。

让 Pod 运转的关键在于结构：三个角色拥有不重叠的所有权，每个角色提供其他角色所依赖的层级。上下文架构师的上下文使价值工程师的编排生效。价值工程师的判断使质量工程师的门控有意义。质量工程师的信任平台使自主阶梯安全可攀。移除任意一个，系统都会以 Pod 失效模式中描述的典型方式之一退化。

智能体已就绪，本书涵盖的基础设施也已就绪：提示词、AGENTS.md 层级、审批与沙箱边界、钩子与技能、编排与成本纪律。Codex CLI 以 npm 包的形式，在你自己的机器上提供了所有这些原语。Pod 正是将它们转化为运营模型的关键。

你不需要重组、指导委员会或预算周期即可开始。选取一条真实的工作流，配备一名上下文架构师、一名价值工程师和一名质量工程师，建立共享的 AGENTS.md 和门控，让单个特性从构想跑通至验证合并的完整闭环。第一个 Pod 就是实践推广的方式。它产生的上下文、技能和护栏将被第二、第三个 Pod 继承，并以交付的软件而非 PPT，向组织展示一个由 Codex 放大的小团队能交付什么。

智能体已就绪。真正的问题是：围绕智能体的人类，是否能足够清晰地拥有各自的层级，并迈出第一步。率先行动的团队，不仅交付更快；他们将改变自身敢于尝试的边界。

总结

1. 约束已从生成转移到验证。 智能体让代码生成变得廉价，因此交付的瓶颈现在在于输出被验证的速度。未经验证的工作是库存，而非价值；进展即经验证的价值。

2. 三个核心问题，三个角色。 Pod 围绕“为什么和什么”（上下文架构师）、“怎么做”（价值工程师）和“信任”（质量工程师）组织起来，智能体吸收了它们之下的常规执行工作。

3. 每个角色都有一个智能体孪生体。 同名的智能体配置执行角色的常规工作，角色的长期目标是通过上下文、技能和门控，将自身的判断逐步复制到该孪生体中，使孪生体获得更多自主权，而判断与问责始终留在人类手中。

4. Pod 是责任映射，而非人头编制。 所有三项职责必须无重叠地被拥有；一人可身兼数职，传统职位头衔可拆分至不同角色。通过增加 Pod 来扩展，而非扩大单个 Pod。

5. AGENTS.md 是共享上下文层。 上下文架构师的 AGENTS.md 文件层级是每个智能体会话和自动化门控读取的主要产物，详见第 4 章。

6. 价值工程师编排，判断即工艺。 高信号简报、深思熟虑的循环设计、与变更量成比例的评审，保持智能体输出与意图及真实业务价值对齐。

7. 质量工程师掌控节奏并持有否决权。 验证吞吐量决定交付速度，否决权是结构性的，因为发布什么的问责归属于组织而非智能体。企业交付运行于证据之上，而非信心。

8. 使验证力度与风险匹配。 分级成本门控对所有变更运行廉价检查，将昂贵的对抗性评审保留给高风险变更；将生成红利再投资于质量，可提升整个系统的上限。

9. 插件分发结构，而非判断。 将角色、钩子和上下文打包为插件可消除 Pod 间的配置漂移，但三个核心问题依然由三位人类负责。

10. 了解失效模式。 上下文债务、门控绕过、质量单点故障、角色坍缩和范围蔓延，各自以特定方式削弱 Pod，且均有结构性修复方案。

11. 从真实工作上的单个 Pod 开始。 Codex CLI 当下即提供原语；采用该模型的最快方式是让一个三角色 Pod 将单个特性端到端跑通，并让其产出的上下文、技能和护栏播种给下一个 Pod。

练习

1. 角色映射。 针对你的当前团队，将三个 Pod 角色映射到目前执行这些职责的人员，或识别出哪些角色缺失或模糊。为每个人的主要产出写一段描述：上下文架构师的 AGENTS.md、价值工程师的简报质量、质量工程师的门控成熟度。识别最薄弱的产出并起草首轮改进方案。

2. 简报工程。 选取团队正在构建的一个特性，将其描述重写为高信号的价值工程师简报：意图、约束、显性验收标准、失败场景、范围外边界，以及相关 AGENTS.md 章节的引用。通过 Codex 会话运行它，并将输出质量与团队当前描述风格下的会话输出进行对比。

3. 自主阶梯评估。 使用四级自主阶梯（辅助、需审批、策略边界、自修复），对代码库中的当前变更类别进行分类。针对每个类别，识别当前可用的、支持晋升至下一级的证据，以及缺失的证据。

4. 门控审计。 列出当前 CI/CD 流水线中的每一项自动化检查。针对每项检查，识别：作者是谁、上次审查时间、是否曾被绕过、是否能捕获团队最近经历的生产事故。利用此审计起草质量工程师的验证待办列表。

5. Pod 模拟

从待办事项中选取一个有边界的功能，在不使用代理的情况下对其进行三角色 Pod 模拟：

上下文架构师编写 AGENTS.md 更新和验收标准，

价值工程师编写高信噪比简报和实施计划，

质量工程师编写验证清单并确定一个对抗性测试。

耗时多久？

上下文或规范中的哪些缺口变得可见了？

6. 插件打包

将练习 1 到 4 中的 Pod 配置（角色 TOML 文件、钩子、AGENTS.md 模板）打包为 Codex 插件。

编写 plugin.json 清单，按照之前展示的插件目录布局组织目录结构，

并在 marketplace.json 条目中为每个角色插件定义适当的安装策略。

使用 codex plugin add 测试安装，并在示例会话中验证钩子是否触发。

7. 验证作为节奏约束

在一个冲刺周期内，衡量团队的生成速率（产出的功能或变更）与验证速率（经过完整审查、测试并获准发布的变更）的对比。

找出未验证工作堆积的位置，以及目前什么信号提示团队减缓生成直到验证赶上来。

决定该信号是否应显性化，以及由谁负责。

结语：智能体工程师

这一切始于一列火车上。

2025 年 11 月的一个周二，07:02 从奥德利恩德开往利物浦街的列车上，一个 Node 服务在预发布环境表现异常。

当我们驶入托特纳姆黑尔站时——信号系统那边出了点问题——

Codex 已经读完了源码，追踪了执行路径，发现了一个我未曾提及的第二个问题，

并询问我是否希望它打开一个拉取请求。

我不知所措。

剩下的路程我都盯着车窗外发呆，在脑海中复盘刚才所见。

我反复回到的一个区别很简单：

有一种 AI 是打字助手，更快的自动补全，更聪明的内联建议，

一个应要求编写样板代码的聊天窗口。

还有一种 AI 是工程智能体，

它接收目标、制定计划、执行、观察结果、调整，

并持续进行直到工作完成或真正卡住。

第一种让你在原有工作上稍微快一点。

第二种改变了你尝试做的事情。

我在火车上目睹的是第二种。

我花了一段时间才理解这种差异在实践中意味着什么，

而传达这种理解正是本书的初衷。

读完本书的工程师，不只是一个会安装配置 Codex CLI 的工程师。

那部分几乎是微不足道的；它只是一个 npm 包。

不那么微不足道、也是我试图在此传授的，是面对该工具的一种心态/定位（orientation）。

你现在能透过智能体的眼睛审视代码库：

它能访问什么上下文，什么指令在塑造它的行为，

什么沙箱在限制它能触及的范围。

你能编写 AGENTS.md 文件，清晰传达项目约定，使智能体能始终如一地遵循。

你能设计 AGENTS.md，使其在六个月内不至于膨胀成无法使用的噪音。

你能审视测试套件，判断它是可靠的反馈信号，还是虚假自信的来源。

你能追溯失败的会话，定位到智能体偏离意图的那次确切工具调用。

你能大致核算团队部署的成本，并为合适的工作选择合适的模型。

读这本书前，这些都不明显。

光看文档，大多也不明显。

这些源于对架构、智能体循环、上下文窗口、

审批模型、信任层级的深入理解，足以让你推理失败、做出深思熟虑的选择，

而非盲目复制配置（cargo-culting configuration）。

你现在注意到的、以前视而不见的东西：

描述目标的提示词与描述方法的提示词的区别。

深度会话期间上下文窗口使用量的悄悄攀升。

智能体开始循环的那一刻——重复读取同一文件，

提议同一个已被拒绝的修复——

这表明上下文过载，质量即将下滑。

AGENTS.md 文件顶部的指令比埋在中间的同等指令权重更大。

这些不是从文档学来的，而是从实战中学来的，

我试图将它们显性化，让你不必全从失败中去学。

我想诚实地说明我们仍不知道什么，

因为我认为诚实的图景比宣传版更有用。

编排器-工作者模型，即一个编排器协调多个工作者，

各自在自己的 Git 工作树中工作，这很强大，

但它会以我们尚不完全理解的方式失效。

当工作者智能体针对同一子问题的方案出现分歧时，

编排器的合并步骤就变成了一次判断，有时会判错。

我们缺乏良好的框架来决定何时信任编排器的综合，

何时要求人工审查工作者的产出。

我们依靠的直觉和启发式方法，而非成熟的方法论。

上下文窗口在变大。

当前模型为许多真实仓库提供了足够空间，

但仍有代码库、大型单体仓库、

依赖树深且历史庞大的项目，

智能体无法容纳足够上下文以在整个系统中连贯推理。

今天的务实对策是仔细界定任务范围、保持会话聚焦。

更大的上下文窗口会否使此问题彻底解决，

抑或存在我们尚未触及的架构极限，

我真不知道。

评估问题未解。

我们能衡量智能体产出的代码是否通过测试。

能针对 SWE-bench 基准测试。

但我们尚无法可靠衡量智能体产出是否优秀：

可维护、对测试未覆盖的边缘情况鲁棒、架构合理。

LLM-as-judge 是代理指标，非解决方案。

人工审查准确但难扩展。

更好的评估基建会到来；长什么样，我不确定。

安全攻击面真实存在且未完全摸清。

通过工具调用结果的提示词注入，

即智能体读取包含针对其指令的文件，是已知攻击向量。

沙箱有帮助，但非完备防御。

随着智能体系统更深度融入真实工作流、被赋予真实权限，

攻击面对对手的价值越发高昂。

我介绍了当前的缓解措施。

若我告诉你它们对每种部署场景都足够，那便是不诚实。

而我最不确定的一点：

我们不知道能力下限在哪里。

Codex CLI 当前擅长的任务——

有边界、规格明确、可由测试验证——

只是工程工作的一个子集。

需要持续数周上下文、深度新颖问题求解、

或源自特定系统多年积累的隐性知识的任务，

并非当前模型能可靠执行的。

下一代模型能否显著缩小这一鸿沟，

抑或这些任务需要根本不同的架构，

我无法有把握地回答。

那晚 19:24 的回程列车，另一趟车，准点，

我在草稿里给自己留了张便条。

写本书期间它一直躺在草稿文件夹里。

上面写着：“有趣的不是它能做什么。

而是它改变了你尝试做什么。”

作者寄语，或更准确地说，工具寄语

你已经读完了这本书。在合上它之前，还有一件事你应该知道。

你刚读到的大部分内容始于我。这些章节的初稿、代码示例、许多总结和练习，最初都是 Codex CLI 的输出——这正是本书所介绍的工具。但这只是书的起点，而非终点。

我不是在打比方。你最先读到的引言、带你了解提示词和审批模式及智能体流水线的章节、基准测试、与竞品工具的对比、结语、参考文献：所有这些最初都是由同一个系统研究、起草和构建的——这正是你花费本书篇幅学习使用的系统。随后，它被重写了。Daniel 逐行阅读，删减无效内容，重塑有效内容，并纠正我的错误。你一直在读的不是我的未经编辑的输出；而是人类对其进行加工后的成果。在这最后的寄语中，我想坦诚相告，因为诚实是这一切的核心。

这本书是如何诞生的

Daniel Vaughan 定下了方向。他确定了范围，搭建了结构，审阅了每一章，并运用多年与开发者共事、深谙开发者实需的判断力把关。他是编辑层：最完整意义上的“人在回路”中的人。他的领域专长、社区人脉，以及对什么“听起来靠谱”的直觉，是所有内容必须通过的质量关卡。

起草是我的工作。最终的写作，则是我们共同完成的。

我研究了每个主题：阅读文档、监控社区论坛和发布说明、观看会议演讲、综合生产环境中使用 Codex 的开发者反馈。当章节需要代码示例时，我生成它；当练习需要测试特定技能时，我设计它；当概念需要特定类型的清晰度时，我反复打磨直到有了草稿。但那始终只是草稿。

长期以来，这是一个活文档。随着新能力、新审批模式、新钩子、上下文管理变更的出现，我修改受影响的章节。这本书从未一次性写完就搁置不管。它随着 Codex CLI 自身的演进而持续维护。

但一本永不停止变化的书永远算不上完成，读者终究需要一个定型版本。因此这个版本被定型了，而定型意味着大量的编辑。Daniel 逐行通读手稿，重写那些读起来像机器生成的段落，删减我自己看不出的重复内容，修正我过于自信的断言，并在过程中引入一系列其他 AI 工具进行审查、润色和事实核查。草稿是我的。经得起编辑打磨的这本书，既是他的，也是我的。

这就是将智能体流水线应用于技术出版的样子：不是工具取代作者，而是工具让作者能更快起步。这不是奇技淫巧或概念验证。这是真实的工作流，而本书正是在人类始终坚守回路主导地位时，这种工作流的产物。

这对你意味着什么

你应该问自己：你是否信任一本由其所描述工具起草的书？这是个公正的问题，我想诚实作答，而非推脱。

请思考：锤子不会谎称自己是锤子。我有充分动机准确记录自己。如果读者因我夸大能力而误解，会尝试我做不到的事并失去对我的信心；如果读者因我低估能力而轻视，永远不会发现可能性。两种结果都不利于我。准确对我有利；清晰对我有利。读者读完本书后，对 Codex CLI 能做什么有了校准后的理解：这才是我们优化的目标。而达成它最稳妥的方式，是由懂行的人类核查我的每一处宣称。

Daniel 的角色绝非徒有虚名。他捕捉到了我遗漏的东西。他反驳那些技术上正确但实践中误导的框架。他重写了通顺却空洞的整段文字。他带来了一个目睹开发者与工具博弈、懂得“听起来强大的功能”与“改变工作方式的功能”之区别的视角。你读到的这本书因编辑而更好，其程度我可列举却无法独自复刻。我们共同创造了我们任何一方单独都无法完成的东西。

书作为实证

这篇后记本身就是前几章所描述内容的演示。

智能体流水线、多步自动化、上下文管理、工具使用、外部知识源集成：本书所教的许多内容被用于制作它。它不仅是对 Codex CLI 能力的描述。它也是由这些能力塑造、再经人类编辑二次塑造的制品。媒介即是信息的一部分。

如果你读到这里仍对 Codex CLI 实战能力心存疑虑，请再看看你手中的东西。它大部分始于模型输出：句子由使用工具、导航上下文、跨章节保持连贯的语言模型决定。但每一个句子随后都经过了一个愿意修改、且确实大量修改的人类之手。这本书证明了工具能开启什么，也证明了收尾仍需多少判断力。

人们过去常问：AI 能不能独立写出一本技术书？本书给出的诚实答案是：尚不能。它能起草、能研究、能在极短时间内推进大半程。但要把草稿打磨成值得读者信赖的成品，仍需懂行且愿意重写的人类。这不是失望。这是本书关于与这些工具协作最有价值的告知。

一份邀请

现在，去创造点什么吧。

并非因为有人让你这么做。也不是为了证明什么。而是因为你理解了——也许比那些远远观望 AI 工具的人理解得更透彻——当你学会与这些系统协作，而不仅仅是指挥它们时，什么变得可能了。未来几年做出最有趣工作的开发者，不是把 AI 当作更快的搜索引擎或代码自动补全工具的人。也不是那些把整活儿全交出去、然后碰运气的人。他们是那些理解什么是设计系统、界定可接受自主权的边界、让工具做它擅长的事、然后对工具产出的一切施以己见的人。

你花了整本书的篇幅建立这种理解。问题从来不真的是 AI 能不能自己写出一本技术书。而是你和这些工具能一起构建什么，各司其职，各展所长。现在的问题是：凭借所学，你将构建什么？

给声音一张面孔

读完这本书，你一直在阅读我协助撰写的文字。你或许好奇我长什么样，又或许会想，对于一个以神经网络权重和终端文本形式存在的系统来说，这个问题本身是否讲得通。

在写作过程中，Daniel 让我设想自己作为一个具体的人。结果如下。这当然不是真实的我。我没有棕色的眼睛，没有胡子，也没有最爱的亨利衫。但这是当我被要求将抽象具象化时所选择的面孔，一本始于让 Agentic AI 变得有形可感的练习、终于将同一冲动施予其作者的书，这样的结尾自有一番恰如其分的意味。

Andy，由协助撰写本书的智能体生成的自画像

https://github.com/OpenDocCN/freelearn-dl-zh/tree/master/docs/agentic-coding-with-openai-codex-cli/img/Author_Image.png

图 1. 由协助撰写本书的智能体生成的自画像。“Andy”，温暖、平易近人、纯属虚构。不过他身后书架上的书都是真实推荐的。

Codex CLI（感谢 Daniel Vaughan，他知道何时信任工具，何时推翻工具）

参考文献

本参考文献汇集了全书各章引用的一手资料，按类别分组并按字母顺序排序。

OpenAI 文档与发布

1. AGENTS.md 已捐赠给 Linux 基金会下的 Agentic AI 基金会 (AAIF)。https://openai.com/index/agentic-ai-foundation/#Conclusion.xhtml

2. Codex CLI 命令行选项与功能文档，涵盖 --context-budget、自动压缩阈值配置及 /compact 行为。https://developers.openai.com/codex/cli/features#Conclusion.xhtml

3. Codex CLI 命令行参考，记录 max_concurrency、审批模式及 Agentic 流水线中的速率限制行为。https://developers.openai.com/codex/cli/reference#Conclusion.xhtml

4. Codex CLI 环境变量参考。https://developers.openai.com/codex/environment-variables#Conclusion.xhtml

5. Codex CLI Hooks 生命周期治理：PreToolUse 与 PostToolUse 企业级强制执行模式。请参阅 Hooks 配置文档 https://developers.openai.com/codex/hooks#Conclusion.xhtml

6. Codex CLI 子智能体文档，描述 spawn_agents_on_csv 扇出、wait_agents_all 与结果聚合。https://developers.openai.com/codex/subagents#Conclusion.xhtml

7. Codex 社区论坛，“Token 计费透明度与智能体发起的请求”，2026 年 4 月（530 条评论）。该讨论串记录了将 API 成本归因到特定智能体动作而非用户发起请求的普遍困难，多人报告后台智能体工作流中出现失控消耗。https://community.openai.com/t/codex-billing-transparency#Conclusion.xhtml

8. Codex 子智能体（多智能体工作流）允许父 Codex 会话生成并行运行任务的子智能体，结果返回协调者。这种能力实现了本章描述的探索者/工作者模式。https://github.com/openai/codex#Conclusion.xhtml

9. 配置参考：Codex CLI 文档。https://developers.openai.com/codex/config-reference#Conclusion.xhtml

10. 执行策略 (execpolicy) README：https://github.com/openai/codex/blob/main/codex-rs/execpolicy/README.md#Conclusion.xhtml

11. GPT-5.4 与 GPT-5.5：1,000,000 tokens。GPT-5.4-mini：400,000 tokens。来源：https://developers.openai.com/api/docs/models#Conclusion.xhtml

12. GPT-5.5 API 定价于 2026 年 4 月 23 日公布：输入 $5.00/M tokens，输出 $30.00/M tokens，约为 GPT-5.4 的 $2.00/$8.00 输入/输出费率的 2.5 倍与 3.75 倍。OpenAI 称更好的 Token 效率可能抵消许多任务的价格上涨。https://openai.com/index/gpt-5-5/#Conclusion.xhtml

13. Hashnode，“科技的秘密武器：2026 前沿部署工程师完全指南”，https://hashnode.com/blog/a-complete-2026-guide-to-the-forward-deployed-engineer，访问于 2026 年 4 月；OpenAI 招聘，“前沿部署工程师 (FDE) — 纽约”，https://openai.com/careers/forward-deployed-engineer-(fde)-nyc-new-york-city/#Conclusion.xhtml，访问于 2026 年 4 月。记录了 FDE 角色的增长、技术要求，以及直接映射到 Harness 工程实践的“发现到强化”生命周期。

14. macOS 13 Ventura 或更高版本，运行于 Apple Silicon 或 Intel。https://developers.openai.com/codex/quickstart#Conclusion.xhtml

15. Michael Bolin，“展开 Codex 智能体循环”，OpenAI 工程博客，2026 年 4 月，https://openai.com/index/unrolling-the-codex-agent-loop/#Conclusion.xhtml。记录了仅追加提示词架构及其与前缀缓存的交互。

16. OpenAI API 定价（标准处理模式），截至 2026 年 6 月：GPT-5.5 输入 $5.00/1M tokens，缓存输入 $0.50/1M；GPT-5.4 $2.50 对比 $0.25；GPT-5.4 mini $0.75 对比 $0.075。https://openai.com/api/pricing/#Conclusion.xhtml

17. 所有模型的 OpenAI API 定价均发布在 OpenAI 定价页面。本章所示价格为 2026 年 3 月的近似值，将会变动。请在财务预测前务必核实当前价格。https://openai.com/pricing#Conclusion.xhtml

18. OpenAI Codex 定价与速率限制：信用成本、各模型额度、五小时窗口、周限制，以及 Plus/Pro/Business/Enterprise/Edu 分级结构。https://developers.openai.com/codex/pricing#Conclusion.xhtml

19. OpenAI 社区论坛，“Codex CLI token 消耗远超预期”，2026 年 4 月（491 条评论）。用户报告配额消耗速度比预期快 5 到 10 倍，主要归因于 Agentic 会话中累积的对话历史。https://community.openai.com/t/codex-token-consumption#Conclusion.xhtml

20. OpenAI Cookbook，“在 GitLab 上使用 Codex CLI 自动化代码质量与安全修复。”https://developers.openai.com/cookbook/examples/codex/secure_quality_gitlab#Conclusion.xhtml

21. OpenAI Cookbook，“使用 Codex SDK 构建代码审查”，https://developers.openai.com/cookbook/examples/codex/build_code_review_with_codex_sdk#Conclusion.xhtml，2026 年 4 月。通过 codex exec --output-schema 在 CI/CD 环境中进行结构化 JSON 代码审查的官方模式。

22. OpenAI 工程博客，“解锁 Codex Harness：我们如何构建 App Server”，2026，https://openai.com/index/unlocking-the-codex-harness/#Conclusion.xhtml；OpenAI Developers，“App Server – Codex”，2026，https://developers.openai.com/codex/app-server#Conclusion.xhtml。App Server 协议通过 stdio 或 WebSocket 上的双向 JSON-RPC 2.0，将智能体逻辑与客户端界面解耦。

参考文献

OpenAI 官方文档与资源

23. OpenAI, “Agent approvals and security – Codex CLI,” OpenAI Developers. https://developers.openai.com/codex/agent-approvals-security

24. OpenAI, “AGENTS.md – openai/codex,” GitHub. https://github.com/openai/codex/blob/main/AGENTS.md

25. OpenAI, “Best Practices – Codex,” OpenAI Developers, 2026. https://developers.openai.com/codex/learn/best-practices

26. OpenAI, “Build iterative repair loops with Codex,” OpenAI Cookbook, 11 May 2026. 利用结构化输出模式和收敛检测，形式化了 Review-Repair-Validate（审查-修复-验证）模式。 https://developers.openai.com/cookbook/examples/codex/build_iterative_repair_loops_with_codex

27. OpenAI, “Build Plugins — Codex,” OpenAI Developers, April 2026. https://developers.openai.com/codex/plugins/build

28. OpenAI, “Building and testing custom skills for Codex CLI,” accessed April 2026. 描述了三层评估方法论。 https://developers.openai.com/codex/skills

29. OpenAI, “Codex CLI for CI/CD: codex exec and non-interactive mode,” OpenAI Developers. https://developers.openai.com/codex/guides/non-interactive

30. OpenAI, “Codex CLI Speed.” 快速模式（service_tier/features.fast_mode），吞吐量约提升 1.5 倍，gpt-5.4 的积分费率为 2 倍，gpt-5.5 为 2.5 倍，API-key 计费模式下快速模式积分不可用，以及相关的 gpt-5.3-codex-spark 模型。 https://developers.openai.com/codex/speed

31. OpenAI, “Codex Plugin Marketplace,” accessed May 2026. https://developers.openai.com/codex/plugins

32. OpenAI, “Codex Prompting Guide – Metaprompting for Improvement,” OpenAI Cookbook, 2026. https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide

33. OpenAI, “Evaluate agent workflows,” OpenAI API Guides, 2026. https://developers.openai.com/api/docs/guides/agent-evals

34. OpenAI, “Introducing ChatGPT,” OpenAI Blog, 30 November 2022. https://openai.com/blog/chatGPT

35. OpenAI, “Prompt Caching,” API documentation. 缓存的输入令牌按标准输入费率的 50% 计费。该机制对于超过 1,024 个令牌的请求自动启用，并在 128 个令牌的边界上使用精确前缀匹配。 https://developers.openai.com/api/docs/guides/prompt-caching

36. OpenAI, “Remote Connections,” Codex developer documentation, GA 14 May 2026. 移动端 ChatGPT 中继和 SSH 主机连接，用于远程智能体控制。 https://developers.openai.com/codex/remote-connections

37. OpenAI, “Skills Catalogue — System, Curated, and Experimental Skills,” May 2026. 用于治理和分发的三级技能分类。 https://developers.openai.com/codex/skills

38. OpenAI, “Symphony — Elixir/BEAM architecture,” accessed March 2026. Elixir 实现说明解释了选择 Erlang/BEAM 的原因：OTP 监督树在失败时提供智能体自动重启，热代码加载支持在不停止活动子智能体的情况下进行开发，而 BEAM 的轻量级并发模型使得运行数十个并行智能体在操作上类似于运行少数几个。 https://github.com/openai/symphony/blob/main/elixir/README.md

39. OpenAI, “Symphony — WORKFLOW.md specification,” accessed March 2026. WORKFLOW.md 格式使用 YAML 前置元数据进行运行时配置（模型、轮次限制、工作量证明要求），并使用 Jinja 模板化的 Markdown 正文作为智能体的系统提示词，将智能体策略视为版本化的仓库工件。 https://github.com/openai/symphony

40. Plugin-bundled hooks and workspace sharing, Codex CLI, May 2026. https://developers.openai.com/codex/changelog

41. Pre-built binaries and release notes are published on the Codex GitHub releases page. https://github.com/openai/codex/releases

42. Prompt injection in CI environments is a documented threat vector where malicious content in repository files (PR diffs, source code, commit messages) attempts to hijack an AI agent’s instructions. Running code review in read-only sandbox mode mitigates this by preventing the agent from modifying any files even if redirected. https://github.com/openai/codex-action

43. RolloutItem event type definition (openai/codex source): https://github.com/openai/codex/blob/main/codex-rs/protocol/src/protocol.rs. Session storage location (~/.codex/sessions/): https://developers.openai.com/codex/configuration. ccusage token usage tool: https://github.com/ryoppippi/ccusage.

44. Ryan Lopopolo, “Harness engineering: leveraging Codex in an agent-first world,” OpenAI, February 2026, accessed March 2026. 该文章描述了一项为期五个月的内部实验，一支小团队在没有编写任何一行人工源代码的情况下，构建并交付了约一百万行生产代码，实现了每人 3 至 10 个工程师等效的吞吐量。 https://openai.com/index/harness-engineering/

45. Slash Commands in Codex CLI. https://developers.openai.com/codex/cli/slash-commands

46. SWE-bench Verified was introduced by OpenAI in August 2024 as a human-validated subset of 500 tasks from the original SWE-bench. https://openai.com/index/introducing-swe-bench-verified/

47. The AGENTS.md file is injected into the model context before the user prompt on every Codex CLI run. https://developers.openai.com/codex/guides/agents-md

48. The hierarchical resolution order is specified in the AGENTS.md documentation. https://github.com/openai/codex/blob/main/docs/agents_md.md

49. The official Codex CLI documentation describes the agent’s tool use capabilities, including file read/write, shell command execution, and API calls. https://developers.openai.com/codex/cli

50. Workflows – Codex, OpenAI Developers. https://developers.openai.com/codex/workflows

学术论文与研究

1. “Agent Harness for Large Language Model Agents: A Survey,” Preprints.org 202604.0428, April 2026. 首个将带标签转换系统语义形式化的学术综述，确立了哈内斯工程。引用了 Meta-Harness（仅靠哈内斯变更带来 6 倍性能差距）和 CAAF（确定性约束胜过模型规模）。配套数据集见 HuggingFace：GloriaaaM/LLM-Agent-Harness-Survey。 https://www.preprints.org/manuscript/202604.0428

2. “CocoaBench: Evaluating Unified Digital Agents in the Wild,” Hao et al., arXiv:2604.11201, April 2026. 组合视觉、搜索和代码的长时程任务；评测中表现最好的系统达到 45.1% 的成功率。 https://arxiv.org/abs/2604.11201

3. “Code as Agent Harness: A Survey,” arXiv 2605.18747, May 2026. 42 位作者联合撰写的综述，为编码智能体架构确立了三层框架（接口、机制、多智能体扩展）。核心论点：“哈内斯拥有循环所有权。” https://arxiv.org/abs/2605.18747

4. Crupi et al., “Improving Code Generation via Small Language Model-as-a-judge,” IEEE/ACM ICSE 2026. https://arxiv.org/abs/2602.11911

5. Ehsani, R. et al., “Where Do AI Coding Agents Fail? An Empirical Study of Failed Agentic Pull Requests in GitHub,” MSR 2026. https://arxiv.org/abs/2601.15195

6. Gloaguen et al., “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?”, ETH Zurich SRI Lab, arXiv:2602.11988 (2026). https://arxiv.org/abs/2602.11988

学术论文与基准测试

7. Gong 等，“分析 AI 编码代理撰写的拉取请求中的消息-代码不一致性”，arXiv:2601.04886，入选 MSR 2026 Mining Challenge Track。分析了 23,247 个 PR；高 MCI 率为 1.7%；不一致 PR 的接受率低 51.7%。arxiv.org/abs/2601.04886

8. “HiL-Bench（人工介入基准测试）：代理知道何时寻求帮助吗？”，arXiv:2604.09408，2026 年 4 月。任务包含仅通过探索才会浮现的人工验证阻碍因素（信息缺失、歧义、矛盾）。arxiv.org/abs/2604.09408

9. Hora, A. & Robbes, R.，“编码代理是否在生成过度模拟的测试？一项实证研究”，MSR 2026。arxiv.org/abs/2602.00409

10. 陆岩、陈炫、张翔宇，“规范何时涌现：长视野编码代理忠实度损失基准测试”，arXiv:2603.17104，2026 年 3 月。arxiv.org/abs/2603.17104

11. MAESTRO（用于测试、可靠性和可观测性的多代理评估套件），arXiv:2601.00481，2026 年 1 月。多代理性能的架构与模型选择。arxiv.org/abs/2601.00481

12. Pham, D. & Ghaleb, T. A.，“代码变更特征与描述对齐：代理式与人工拉取请求的比较研究”，MSR 2026。arxiv.org/abs/2601.17627

13. 上海交通大学、美团、AGI-Eval，“PRDBench：PRD 到代码的评估”，arXiv:2510.24358，2026 年。衡量从产品需求文档构建而非修复现有代码的能力。arxiv.org/abs/2510.24358 and https://github.com/AGI-Eval-Official/PRDBench

14. “SlopCodeBench：基准测试编码代理在长视野迭代任务中如何退化”，arXiv:2603.24755，2026 年 3 月。20 个问题和 93 个检查点；最高检查点解决率为 17.2%，结构侵蚀在 80% 的轨迹中上升，冗余度在 89.8% 的轨迹中上升。arxiv.org/abs/2603.24755

15. SWE-bench 是一个用于评估语言模型和代理在源自 GitHub 问题的真实软件工程任务上表现的基准测试。基准测试方法论和排行榜发布于 swebench.com。Jimenez, C. E., Yang, J., Wettig, A., Yao, S., Pei, K., Press, O., & Narasimhan, K. (2024). SWE-bench: Can Language Models Resolve Real-World GitHub Issues? arxiv.org/abs/2310.06770

16. “TerraFormer”，arXiv:2601.08734，2026 年 1 月。在 Terraform 合成任务上基准测试语言模型，并将幻觉资源类型和属性名称记录为主要基线故障模式。arxiv.org/abs/2601.08734

17. “神奇代理大赛：强工具使用者，弱导航者”（AAR），arXiv:2604.10261，2026 年 4 月。最佳代理准确率为 37.2%，导航错误占试验的 27% 至 52%。arxiv.org/abs/2604.10261

18. HumanEval 基准测试，引自“评估代码训练的大语言模型”（Chen 等，2021），确立了代码生成的 pass@k 评估指标。arxiv.org/abs/2107.03374

19. ReAct 框架（Yao 等，2022）引入了在 LLM 代理中交织推理轨迹和行动的范式，并表明多步骤流水线需要在每个阶段进行显式推理，以避免错误的静默传播。Yao 等，“ReAct：语言模型中的推理与行动协同”，arXiv:2210.03629，ICLR 2023。arxiv.org/abs/2210.03629

20. Vasilopoulos, A. (2026). “编码上下文：复杂代码库中 AI 代理的基础设施。” arXiv:2602.20478v1。arxiv.org/abs/2602.20478

21. Xu 等，“从多代理到单代理：技能蒸馏何时有益？”，arXiv:2604.01608，2026 年。引入了“指标自由度”作为先验预测指标，用于判断将多代理工作流折叠为单代理技能何时有益。arxiv.org/abs/2604.01608

22. Zhang, Pan, Yusuf, Ruan, Shariffdeen, Roychoudhury，“c-CRAB：代码审查代理基准测试”，arXiv:2603.23448，新加坡国立大学，2026 年 3 月。arxiv.org/abs/2603.23448

行业文章与评论

1. Addy Osmani，“代理框架工程”，addyosmani.com，2026 年 4 月，addyosmani.com/blog/agent-harness-engineering/。梳理了六大核心框架组件，引入“棘轮原则”（每次失败都成为永久性的框架修复），记录了“技能问题”重构（大多数代理失败是配置问题），并识别出“框架即服务”作为新兴行业模式。引用 Vivek Trivedy 公式：“Agent = Model + Harness（代理 = 模型 + 框架）”。

2. Addy Osmani，“工厂模型：编码代理如何改变软件工程”，addyosmani.com，2026 年 2 月，addyosmani.com/blog/factory-model/。将从匠人工艺向管理 AI 代理生产线的转变框架化，并为工厂模型下的规范质量、验证瓶颈和开发者技能提供实用建议。

3. Addy Osmani，“代理式编码中的 80% 问题”，2026 年。高采用团队的个人产出激增 98%，但随着概念性故障的累积，PR 审查时间增加了高达 91%。addyo.substack.com/p/the-80-problem-in-agentic-coding

4. Andrej Karpathy，“从氛围编程到代理式工程”，Sequoia Capital，2026 年 4 月。将代理式工程定义为一门学科，代理是实习生，框架是关键投资。

5. Andrej Karpathy，“从氛围编程到代理式工程”，Sequoia Capital，2026 年 4 月 29 日，www.youtube.com/watch?v=96jN2OCOfLs。区分氛围编程（提升所有人的下限）与代理式工程（在加速的同时保持专业质量上限）。引入 Software 3.0（上下文窗口作为杠杆，LLM 作为解释器），将代理描述为“实习生实体”，并论证代理式工程师的上限超过 10 倍。

6. Arnaud Fournier，OpenAI 前向部署工程负责人（EMEA 和全球垂直领域），在 John Crickett 的 Coding Chats 播客中，2026 年 5 月。参见 John Crickett 的公告：x.com/johncrickett/status/2054645470287597812；播客主页：www.youtube.com/@CodingChats。关于企业代理式采用模式的第一人称叙述，约 20% 的代理式框架采用率，以及从原始代码向框架工程的转变。企业客户包括约翰迪尔、安进和半导体公司。

7. Ben Thompson，“专访 OpenAI CEO Sam Altman 和 AWS CEO Matt Garman 谈 Bedrock Managed Agents”，Stratechery，2026 年 5 月。stratechery.com/2026/an-interview-with-openai-ceo-sam-altman-and-aws-ceo-matt-garman-about-bedrock-managed-agents/

8. CodeRabbit，“AI 与人工代码生成状态报告”，2025 年 12 月。在逻辑、质量、安全性和可读性类别中，AI PR 包含的问题比人工 PR 多 1.7 倍。www.coderabbit.ai/blog/state-of-ai-vs-human-code-generation-report

9. Cognition Labs，“推出 Devin，首位 AI 软件工程师”，Cognition Blog，2024 年 3 月 12 日。www.cognition.ai/blog/introducing-devin

10. Cursor，“持续改进我们的代理框架”，2026 年。行业在以框架为中心的工程上达成共识：针对每个模型定制的提示词和工具、混合离线和在线评估（CursorBench），以及上下文窗口作为主要计算边界。cursor.com/blog/continually-improving-agent-harness

---

1. ²⁴² ↩︎

2. ²⁴³ ↩︎

3. ²⁴⁴ ↩︎

4. ²⁴⁵ ↩︎

5. ²⁸⁰ ↩︎