[控场AI]
· 10 分钟阅读· 5,132 字

拆解Codex Harness工程:零手写百万行代码的奥秘

拆解Codex Harness工程:零手写百万行代码的奥秘

OpenAI Codex实验5个月零手写产出百万行代码,核心在于环境构建与工程习惯。

本文基于B站UP主“Harness Engineering五讲”第四讲,梳理OpenAI Codex团队5个月零手写、产出约100万行代码的实验方法。核心观点是:agent产出速度不取决于模型能力,而取决于环境是否交代清楚。团队将agents.md设计为约100行的地图而非千页说明书,把知识放入仓库结构化文档;让应用对agent可见,接入浏览器调试协议和本地监控;通过自定义代码检查和结构测试守住不变量,报错信息写成修复说明;以“黄金原子”规则和定期后台垃圾回收控制代码库漂移。Codex循环利用提示缓存保持前缀稳定、用压缩代替截断,沙箱与审批机制与Claude Code趋同。最终结论是:仓库唯一事实来源、不变量检查、定期垃圾回收等工程习惯,比工具本身更能拉开差距。

OpenAI的Codex团队曾进行过一个实验:在5个月内,不写一行手写代码,全靠AI智能体(agent)完成一个内部产品,最终仓库代码量达到约100万行。这个实验让“Harness Engineering”一词流行起来。最近,B站UP主在“Harness Engineering五讲”的第四讲中,详细拆解了Codex和OpenAI的这套工程方法。本文基于该视频内容,结合多个技术来源,梳理出其中的核心逻辑。

实验背景:5个月,100万行,零手写

据OpenAI工程师Ryerson和Ian Lopopolo发表的文章,这个实验始于一个空仓库,第一个提交就是由Codex生成的,包括目录结构、CI配置、格式规则以及指导agent工作的agents.md文件。5个月后,仓库积累了约100万行代码,合并了约1500个PR。团队最初只有3名工程师驱动Codex,平均每人每天3.5个PR,后来增至7人,人均速度反而上升。产品有几百个内部用户日常使用,也会上线、部署和修复。团队估计,手写代码仅占约1%的时间,其余全部由agent生成,覆盖产品代码、测试、CI、发布工具、内部工具、文档、评审意见甚至管理仓库本身的脚本。

实验的口号是“人涨多,agent执行”。但初期进展比预期慢,原因并非Codex能力不足,而是环境没有交代清楚——agent缺工具、缺抽象、缺内部结构。于是工程师的主要工作从写代码转变为让agent能把活干好,每次遇到问题,他们问的是“缺的是什么能力”,而不是“再努力一点”。

指令设计:给地图,不给说明书

团队最早的经验是:给Codex一张地图,而不是一本一千页的说明书。他们曾尝试将所有规则塞进一个大agents.md文件,但失败了,原因包括:巨大指令文件会挤占上下文,导致agent漏掉关键约束或围绕错误约束使劲;什么都重要等于什么都不重要;手册很快过期,变成规则坟场;无法机械检查覆盖度和链接有效性。

因此,agents.md被设计成目录页,仅约100行,作为地图告诉agent更深的知识在哪。真正的知识放在仓库的结构化文档目录中,涵盖架构说明、设计文档、产品规格、质量评分、安全可靠性要求和执行计划。计划是一等公民:小改动用轻量临时计划,复杂工作写成带进度和决策记录的执行计划,直接提交进仓库。直接提交进仓库

对于agent来说,运行时在上下文里拿不到的东西就等于不存在。团队致力于将越来越多上下文推进仓库,例如通过专门的检查任务确认文档新鲜度、链接正确性,并定期运行文档园丁agent修复过时文档。Codex读取agents.md时,先读全局文件,再从项目根目录逐层向下,每层最多取一个文件,越近越优先,总token限制在32k以内。与上一讲Claude Code建议的200行以内相比,Codex团队控制在100行左右,理念一致:指令要短、分层、就近。

环境构建:让应用对agent可见

代码产出加速后,瓶颈转向人工测试容量。团队让应用本身对Codex可见:第一,每个改动都能单独启动一个实例,Codex可自行操作;第二,将浏览器调试协议接入agent,提供页面快照、截图、跳转等技能,使其能复现bug、验证修复;第三,通过本地监控工具暴露日志、指标和调用链路,agent可自写查询验证性能要求(如服务启动800毫秒内、关键路径两秒内)。

这些能力让Codex能连续工作六个多小时,往往在人类睡觉时。Codex的两只手

浏览器调试协议(通常指 Chrome DevTools Protocol,CDP)是一套让外部程序控制浏览器的标准化接口。它允许agent获取DOM快照、截取页面截图、点击元素、读取控制台日志、监听网络请求,甚至执行JavaScript。对于需要复现UI bug或验证前端修复的agent来说,这相当于给了它一双能“看见”和“操作”页面的手。与传统自动化测试框架(如Playwright、Puppeteer)底层依赖相同,但agent可以动态决定下一步操作,而非执行预设脚本。接入CDP后,Codex能够自行打开页面、定位异常、验证修复效果,将原本需要人工点击确认的环节自动化,这也是其能连续工作六小时以上的关键支撑之一。

约束机制:守住不变量

光有文档管不住完全由agent生成的代码库。团队的原则是守住不变量,例如要求Codex在边界解析校验数据,但不指定方法。架构上则定得很死:每个业务领域分固定层次,依赖只能向前;横切关注点(如功能开关)只能从统一入口进入。这些规矩通过自定义代码检查和结构测试强制,而检查本身也是Codex写的。

一个巧妙细节:检查报错信息被写成修复说明,agent违反规矩时不仅看到错误,还看到应该怎么改。这些规矩对人可能吹毛求疵,对agent却是陈述,写一次处处生效。人的品位通过评审意见、重构、用户反馈不断补入系统,文档管不住的升级为代码检查。

速度上来后,传统工程规矩反而碍事。仓库几乎不设阻塞合并关卡,PR短命,测试偶尔失败多半重跑,因为agent产出远超人的注意力时,改错便宜,等待昂贵。但完全放手会导致代码库跑偏,团队曾每周五花20%时间清理AI生成的垃圾代码,后来转为将“黄金原子”规矩写进仓库(如优先用共享工具包、避免重复小函数、边界校验或类型化接口),定期跑后台Codex任务扫描偏离,更新质量评分并开重构PR,大多数一分钟内审完自动合并。这被称为垃圾回收,技术债像高息贷款,持续小额递还优于一次性还清。

“不变量”(invariant)是软件工程中一个核心概念,指在系统运行或代码演进过程中必须始终为真的条件。它可以表现为数据结构约束(如订单金额不能为负)、架构规则(如领域层不能依赖基础设施层)、安全要求(如所有外部输入必须经过校验)或性能底线(如关键接口响应时间上限)。全文所说的“守住不变量”意味着:无论agent如何自由发挥实现细节,这些条件不能被破坏。将不变量写成可执行的代码检查或结构测试,相当于把人的设计意图固化为机器可验证的规则,使agent在每次提交时都能被自动拦截违规。这种做法把“评审意见”从一次性人工反馈升级为永久生效的自动化约束,是管理大规模agent生成代码库的基础设施。

Codex循环:提示缓存与压缩

OpenAI工程师Michael Bolin的文章揭示了Codex的循环细节。每次调模型,请求包含基础指令、工具清单和输入消息,前面还会插入几条固定消息:一条说明沙箱规则,一条装载agents.md和技能简介,一条描述当前环境。沙箱规则只管Codex自己的命令行工具,通过MCP接入的工具不归它管,需自行负责安全。不归他的杀伤管得

每次工具调用结果追加到请求,数据量按平方增长。但提示缓存让旧请求开头与上次一字不差时计算直接复用,成本从平方变线性。因此Codex刻意保证旧请求是新请求的前缀,避免中途修改工具清单、模型、沙箱设置或工作目录。接MCP时曾因工具顺序不固定导致缓存不命中,后来规矩是配置变化追加新消息而非修改旧消息。

上下文满时,Codex用压缩代替截断:超过阈值将长输入换为代表对话的条目,OpenAI接口的压缩功能返回一条加密内容保存模型理解,人看不懂但模型懂。这与ARC-AGI-3基准中保留推理而非丢弃的设置一致,分数从13.3%升至38.3%,输出token减少六倍。

沙箱定义边界,审批决定何时必须问人。沙箱管所有命令,Mac和Linux用不同工具,三种模式:只读、工作目录读写、完全放开;审批两种:越界问或从不问。还有规则按命令开头决定允许/询问/禁止,以及自动审核将审批请求发给审核agent。与Claude Code的后台分类器思路类似。

子代理用于减轻上下文污染:主agent管需求决策,探索测试分析交给子代理并行,只回摘要。内置通用、动手实现、读代码三种子代理,可自定义但权限继承主agent。读多的活适合并行,写多的活并行需小心冲突。

钩子系统支持十几个事件,Stop钩子最值得看:一轮结束时若返回栏下加理由,Codex不会拒绝,而是将理由作为新用户消息让它继续。官方例子是重跑失败测试,输入带标记避免死循环。这与Claude Code的Stop钩子几乎一样。再附上一个理由

提示缓存(prompt caching)是大模型推理中的一项优化技术:当多次请求的前缀内容完全一致时,服务端可以复用之前已经计算过的键值缓存(KV cache),跳过重复的注意力计算,从而降低延迟和成本。对于agent循环而言,每一轮请求都包含系统指令、工具清单、历史消息和新的工具结果,前半部分通常不变。如果每次都从头计算,成本会随对话轮次呈平方级增长;而利用缓存,旧请求成为新请求的前缀,增量计算只针对新增内容,成本降为线性。代价是要求请求前缀严格稳定——一旦中途修改工具列表、模型参数或沙箱设置,缓存即失效。因此Codex的工程规矩是“追加而非修改”,这既是一种性能设计,也约束了agent运行时的配置管理方式。

平台化与三家对比

Codex有桌面应用、命令行、编辑器插件和网页版,底层同一个Harness。命令行版自去年4月开源(Rust写),插件和云端不开源。连接入口的是App Server,源自编辑器插件开发时不想重写循环,尝试MCP服务不贴合,于是自研双向协议,现成为稳定平台接口。协议三个原语:条目(最小输入输出,如消息、命令执行、代码改动)、回合(一次用户输入引起的工作)、现成(可恢复、分查、存档的完整会话)。双向意味着agent需审批时服务端反问客户端并暂停回合。

去年8月OpenAI发文将开源Harness定位为平台,观点是与其让团队把工作搬进通用聊天框,不如把agent带进围绕真实工作设计的软件,界面本身就是最重要的上下文。示例中货运看板旁放agent,用户选中货物点比较恢复方案,但改定货物等有后果操作必须人批准。

课程给Codex五个子系统打分:指令是教科书级(给地图不给说明书),工具从命令行到插件产品皆多生自选,环境隔离是招牌,状态更依赖仓库约定,反馈路径默认值得抄。对比三家:派内核最小什么都不替你决定,Claude Code内核完整开箱即用,Codex把循环开源把规矩写进仓库。UP主观察Claude Code和Codex越走越近,一个做加法一个做减法,但现在Codex也有钩子、子代理、技能、记忆和审核agent,Stop钩子几乎一样。真正拉开差距的不是功能清单,而是OpenAI文章里的工程习惯:仓库是唯一事实来源、不变量写成检查、定期垃圾回收。这些不依赖工具,换成Claude Code一样能做。

MCP(Model Context Protocol)是一种开放协议,用于让大模型应用以标准化方式连接外部工具和数据源。它定义了工具发现、调用和结果返回的通用接口,使agent无需为每个工具单独编写适配代码。文中提到Codex接入MCP工具后,这些工具不受Codex沙箱规则的约束,需要自行负责安全;同时也曾因MCP工具顺序不固定导致提示缓存不命中。理解MCP有助于把握当前agent生态的演进方向:模型能力之外,工具接入的标准化程度直接影响agent的可扩展性和安全性。Codex自研App Server而非直接采用MCP,正是因为MCP在双向交互和会话恢复等方面不完全贴合其循环需求,这也说明标准化协议与产品特定需求之间仍存在张力。

核心要点

  • 实验证明零手写可行:5个月100万行代码,手写仅占1%时间,关键在于环境构建而非模型能力。
  • 指令要短要分层:agents.md约100行作为地图,知识放仓库结构化文档,定期清理过期内容。
  • 约束靠代码检查:守住不变量,报错即修复说明,黄金原子规则加后台垃圾回收控制代码库漂移。
  • 循环优化靠缓存和压缩:提示缓存保证前缀稳定,压缩代替截断保留推理,ARC-AGI-3分数提升近三倍。
  • 工程习惯比工具更重要:仓库唯一事实来源、不变量检查、定期垃圾回收,换任何agent都适用。
分享:

相关推荐