【Codex】Part 16 — The Design Philosophy Behind Codex

文章目录第十六章 Codex 的设计思想16.1 从“会生成代码”到“能完成任务”16.2 上下文优先先让任务边界清楚16.2.1 临时要求与持久规则分开16.2.2 上下文不是越多越好16.3 规划应与任务复杂度匹配16.3.1 视觉算法任务中的规划16.4 行动—反馈—验证闭环16.4.1 为什么反馈比一次生成更重要16.4.2 一个目标检测示例16.5 工具不是附件而是能力边界16.5.1 工具调用应可组合16.5.2 Skills 与 MCP 的职责不同16.5.3 工具越多不一定越好16.6 安全来自沙箱与审批的配合16.6.1 最小权限原则16.7 长会话需要主动管理上下文16.7.1 视觉实验如何避免上下文丢失16.8 多种使用表面共享配置层而非完全相同实现16.9 开源边界要说清楚16.10 可复用的七条设计原则原则一上下文先于生成Context before Generation原则二规划粒度匹配风险Risk-Proportional Planning原则三行动必须产生证据Evidence-Producing Actions原则四优先最小改动Minimal Change原则五权限与任务匹配Least Privilege原则六稳定流程外部化Externalize Stable Workflows原则七会话不是事实数据库Artifacts over Chat History16.11 小结参考资料第十六章 Codex 的设计思想摘要理解 Codex不必猜测未公开的内部模块。更可靠的方法是观察它公开的工作方式读取上下文、规划任务、调用工具、在沙箱中执行、根据结果继续迭代并用测试或产物验证完成状态。本章据此总结 Codex 的设计取向并结合目标检测、图像分类和语义分割说明这些设计如何落到算法工程实践中。16.1 从“会生成代码”到“能完成任务”大语言模型Large Language ModelLLM负责理解和生成内容但仅靠模型无法可靠完成真实工程任务。它还需要一个代理运行时Agent Runtime提供上下文、工具、执行环境、安全边界和结果反馈。工程讨论中常把这层运行时称为代理框架或Harness。这里的 Harness 是便于理解的分析概念不代表 OpenAI 官方公布了一个同名、固定边界的内部模块。用户目标上下文与约束模型推理工具与执行环境结果与证据最终产物图 16-1从目标到产物的基本闭环。模型负责判断下一步运行时负责提供能力和边界工具结果再成为后续判断的依据。以修改 YOLO 目标检测训练配置为例Codex 不只是生成一段 YAML读取数据集配置、训练脚本和上一组实验结果确认本轮只改变学习率还是同时改变数据增强修改配置并运行语法检查或短程训练检查日志、指标文件和输出目录根据证据判断任务是否完成。这说明编程代理Coding Agent的价值不只来自“代码写得像不像”还来自能否建立完整的执行与验证闭环。16.2 上下文优先先让任务边界清楚官方最佳实践建议在任务中说明四类信息目标Goal、上下文Context、约束Constraints和完成条件Done when。这四项共同决定 Codex 应该做什么、不能做什么以及何时停止。信息要回答的问题视觉算法示例目标最终要改变什么将分割模型的输入尺寸改为 640×640上下文哪些文件和事实相关train.py、数据集 YAML、当前基线结果约束哪些条件不能变化固定随机种子、批量大小和数据划分完成条件用什么证据验收配置加载成功短程训练通过输出尺寸正确16.2.1 临时要求与持久规则分开一次性要求适合写在当前提示词中团队长期遵守的规则更适合写入AGENTS.md。Codex 会从全局、仓库根目录到当前工作目录逐层读取适用的AGENTS.md更靠近当前目录的指导优先级更高。例如可在视觉算法仓库根目录记录通用规则# Experiment rules - 一次实验只改变一个变量。 - 修改训练配置后先运行配置解析检查。 - 结果必须记录数据集版本、随机种子和评测脚本。针对目标检测子目录还可以增加局部规则使用 COCOCommon Objects in Context评测口径明确平均精度均值mean Average PrecisionmAP在 IoU 0.50 至 0.95 范围内的计算方式并保存预测可视化。这样约束不会依赖每次手动重复。16.2.2 上下文不是越多越好无关信息会挤占注意力也可能引入冲突。更实用的原则是先提供直接相关的文件、错误和验收标准只有发现缺口时再扩展搜索范围。例如排查分类模型准确率下降时应先查看数据预处理、类别映射和评测脚本而不是一开始读取整个仓库。若确认代码无变化再继续检查数据版本和训练环境。16.3 规划应与任务复杂度匹配复杂任务适合先规划。Codex 提供计划模式Plan mode也可以按用户要求先输出计划、等待确认或使用PLANS.md约定长期任务的执行计划格式。因此不应把 Codex 简化成“没有 Planner”或“只靠隐式规划”。公开行为能够确认的是Codex 既能直接处理简单任务也支持显式、可审阅的规划流程具体采用哪种方式应由任务风险和复杂度决定。否是是否收到任务复杂、模糊或高风险直接执行并验证收集上下文并形成计划需要用户拍板等待确认按计划执行检查完成条件图 16-2规划粒度由任务决定。16.3.1 视觉算法任务中的规划给分类模型增加一个新骨干网络通常可以直接定位注册表、添加配置、运行单元测试。重新设计一套实例分割数据管线则更适合先规划因为它可能同时影响标注格式转换数据增强和掩码插值模型输入输出损失函数评测与可视化。规划的价值不是把所有步骤一次猜对而是提前暴露依赖关系、风险和验收方法。16.4 行动—反馈—验证闭环Codex 的公开工作方式与“推理后行动再根据结果继续判断”的代理循环相符。它与 ReActReasoning and Acting思想相近但不应据此断言 Codex 内部严格实现了论文中的Thought → Action → Observation格式。在真实工程中更有用的抽象是否是检查现状执行最小改动运行验证达到完成条件交付结果与证据图 16-3工程任务的反馈闭环。16.4.1 为什么反馈比一次生成更重要工具结果会暴露模型事先不知道的事实例如配置键已经改名CUDA 算子不支持当前设备数据集中存在越界类别分割掩码在缩放时误用了双线性插值单元测试通过但端到端指标下降。Codex 可以根据这些结果调整下一步而不是坚持最初假设。不过反馈闭环只有在验证方法有效时才可靠错误的测试同样会产生错误信心。16.4.2 一个目标检测示例假设任务是“修复 COCO 数据集上类别数不匹配的问题”。较可靠的流程是读取数据集 YAML 和模型检测头配置检查类别名称、类别数和标签 ID 范围只修改真正不一致的位置抽查标签并运行数据集校验启动短程训练确认损失和输出张量正常说明修改内容及验证证据。只把nc改成 80 而不检查标签 ID并不构成完整修复。16.5 工具不是附件而是能力边界Codex 能做什么取决于当前使用表面surface、环境和会话提供了哪些工具。常见能力包括文件读写、Shell、Git、网页访问、模型上下文协议Model Context ProtocolMCP、技能Skills以及插件Plugins。并非每个环境都提供完全相同的工具。16.5.1 工具调用应可组合好的工具应职责清楚、输入明确、输出可验证。模型可以将它们组合成工作流搜索配置读取相关文件修改运行测试检查差异独立的只读操作可以并行例如同时读取检测、分类和分割三个配置文件存在依赖的操作必须顺序执行例如先生成 ONNX再用生成的文件构建 TensorRT 引擎。16.5.2 Skills 与 MCP 的职责不同技能Skill保存可复用的方法、步骤、模板和脚本回答“这类任务应该怎样做”。MCP连接实时外部数据和受控操作回答“从哪里读取或向哪里执行”。例如“按照团队规范评审 YOLO 实验报告”适合做成 Skill“从实验跟踪平台读取最新指标”适合通过 MCP 提供。两者结合后Skill 决定评审流程MCP 提供实时数据。16.5.3 工具越多不一定越好工具过多会扩大选择空间尤其是 MCP 服务器会增加消息上下文。官方最佳实践建议从能消除明确手工流程的一两个工具开始再按需要扩展。对于视觉算法仓库如果本轮只修改数据增强无需同时连接部署平台、工单系统和云端日志。16.6 安全来自沙箱与审批的配合安全不能只依赖模型“知道什么不该做”。Codex 使用沙箱Sandbox限制技术上允许的操作再用审批策略Approval Policy决定何时必须暂停并请求授权。是否是否批准拒绝模型提出操作沙箱内允许执行操作审批策略允许申请请求用户批准拒绝并返回错误记录结果并继续验证图 16-4沙箱决定能力边界审批决定越界流程。本地 Codex CLI 和 IDE 扩展使用操作系统级机制执行沙箱策略Codex cloud 则运行在隔离的托管容器中。不同平台的具体实现不同不能用某个平台的权限行为推断所有表面。16.6.1 最小权限原则最小权限Principle of Least Privilege意味着只授予完成任务所需的权限。例如审查训练脚本时使用只读权限修改仓库时只开放工作区写入下载公开权重时再按需开放网络删除数据集或覆盖检查点前明确目标并确认。“全自动”不等于“无限权限”。边界清晰Agent 才能在边界内持续工作而不必为每个低风险步骤反复询问。16.7 长会话需要主动管理上下文长任务会不断积累对话、工具结果和决策。Codex 支持使用/compact将较早上下文压缩为摘要也会在需要时自动压缩会话。压缩能延续任务但细节可能被概括因此关键事实不应只存在于早期聊天中。不能用“服务端完全无状态、所有状态只在客户端”概括整个 Codex 产品也不能由此推导其天然符合零数据驻留Zero Data RetentionZDR。CLI、桌面端和云端的会话、存储及数据控制需要分别判断。16.7.1 视觉实验如何避免上下文丢失对于持续数天的分割实验应把关键状态写入仓库内的正式产物实验假设与唯一变量数据集版本和划分配置文件与代码提交随机种子和环境版本完整评测结果下一步决策及理由。这样即使会话被压缩或更换Codex 仍可从文件恢复事实而不是依赖聊天记忆猜测上一轮做了什么。16.8 多种使用表面共享配置层而非完全相同实现Codex 可通过 CLI、IDE 扩展、ChatGPT 桌面应用和云端环境等表面使用。官方文档说明CLI、IDE 扩展和桌面应用共享配置层Skills 也可跨这些表面工作。“共享配置层”不等于“所有表面共享完全相同的 Harness”。各表面的工具、交互、运行环境、审批方式和可用功能可能不同。写跨表面规则时应描述期望行为而不是依赖某个界面的偶然实现。层级适合保存什么视觉算法示例当前提示词本次任务的临时目标只分析误检不修改代码AGENTS.md仓库长期规则固定评测命令和实验记录格式config.toml模型、权限、MCP 等配置工作区写权限、文档 MCPSkill可复用工作流数据集清洗、模型评测、报告审核MCP实时外部数据与操作读取实验平台或内部文档16.9 开源边界要说清楚OpenAI 公开开发 Codex 的多个关键组件包括 Codex CLI、Codex SDK、Codex App Server、Skills 和 Plugins但 IDE 扩展和 Codex cloud 并未列为开源组件。因此更准确的表述是“Codex 的关键组件部分开源”而不是“整个 Codex Harness 都可以审查、修改和自托管”。开源 CLI 有助于理解本地执行、配置和工具接入但不能用来证明云端产品的全部内部实现。16.10 可复用的七条设计原则原则一上下文先于生成Context before Generation先明确目标、约束和完成条件再开始修改。对于算法实验必须说明数据、基线和唯一变量。原则二规划粒度匹配风险Risk-Proportional Planning小改动直接执行并验证跨模块、高成本或不可逆任务先规划必要时等待用户确认。原则三行动必须产生证据Evidence-Producing Actions修改代码只是中间状态。测试结果、评测指标、日志和产物才是完成依据。原则四优先最小改动Minimal Change修复分类标签错位时不顺手重构整个数据管线改变检测损失时不同时修改增强策略。改动越集中因果越容易判断。原则五权限与任务匹配Least Privilege只读任务不给写权限本地任务不默认开放网络危险操作不依赖模型自行克制。原则六稳定流程外部化Externalize Stable Workflows把长期规则放入AGENTS.md把重复方法做成 Skill把实时外部能力交给 MCP而不是让提示词无限增长。原则七会话不是事实数据库Artifacts over Chat History实验配置、结果和决策写入可版本化产物。聊天上下文用于协作不应成为唯一记录。16.11 小结Codex 的设计价值可以概括为让模型在明确上下文、安全边界和可验证工具中完成任务。它不是只生成代码也不是不受约束地操作计算机更接近一名能够读取工程现场、执行操作、接受反馈并提交证据的协作者。对 AI 视觉算法工程师而言这种设计最直接的启示是把实验契约写清楚一次只改变一个变量让工具执行可重复的检查用完整评测产物判断结果把长期经验沉淀到仓库规则和 Skills 中。当 Codex 表现不稳定时先检查上下文、工具、权限和验收条件通常比猜测模型“在想什么”更有效。参考资料OpenAI DocsCodex 最佳实践OpenAI Docs使用 AGENTS.md 配置自定义指令OpenAI Docs沙箱OpenAI DocsAgent 审批与安全OpenAI DocsMCPOpenAI DocsSkillsOpenAI Docs配置基础OpenAI Docs开源组件Yao 等ReAct——协同推理与行动下一章第十七章 Codex 与 SWE-Agent、OpenHands、Claude Code 的架构对比