09｜Codex源码追踪：从仓库规则到历史、循环和压缩

目标：学会沿确定的提交与函数追踪数据，而不是把产品介绍当源码事实。本章实际阅读公开源码，但未编译或运行Codex。两个源码快照分别标明，不混称“当前完整实现”。

继续看相关机制：F26 · 每轮上下文像一份有边界的工作资料F27 · 压缩要保留行动所依赖的事实F32 · Skill存在，为什么仍可能完全没用？

1. 证据范围与版本

项目规则、初始上下文、循环与本地压缩来自提交99f47d6e9a3546c14c43af99c7a58fa6bd130548；SSE事件转换来自另一个提交2a68b74b9bf16b64e285495c1b149d7d6ac8bdf4。它们是可追溯阅读锚点，不是用户本机安装版本的鉴定结果。官方Agent Loop文章提供总体解释，具体源码提供特定快照的行为证据。[N01][N02][N03][N04][N05]

文件与核心位置：project_doc.rs负责项目规则发现与拼接；codex.rs中的build_initial_context、run_turn组织初始项目与执行轮次；compact.rs管理一种本地摘要压缩路径；sse/responses.rs把服务事件转换成内部响应事件。

源码阅读应把“看到的实现”“文档声明”“作者建议”分开。尤其不能把不同提交中的函数拼成一个从未存在过的版本，更不能从公开客户端推断全部服务端系统提示与模型内部状态。

2. project_doc.rs：为什么规则可能没有进入输入

在上述快照，discover_project_doc_paths沿cwd向上寻找仓库标记，建立从仓库根到当前目录的搜索链；没有找到仓库时使用当前目录。每个目录按候选文件名优先级选择一个规则文件。AGENTS.override.md先于AGENTS.md，其后是配置的备用名称。读取受project_doc_max_bytes总预算限制；这里是字节，不是Token。[N02]

本章不逐行翻译源码，而用一个原创排障例子说明后果：假设仓库根规则很长，当前目录又有专业规则。在按路径顺序拼接并耗用总预算的实现中，前面的文件可能耗尽预算。模型表现为“忽略专业规则”，实际原因可能是规则根本没被装入；给模型再加一句“必须遵守所有规则”不会修复字节预算。

同目录有override与普通规则时，也不能默认两份叠加。应先检查候选优先级和该目录是否只选一个文件。没有读取到深层规则，还可能因为启动cwd不是预期路径，而不是模型路由错误。

从这些机制可以导出回归样本：无规则、根规则、嵌套规则、override、备用文件名、零预算、跨字节截断、不同cwd。源码包含相关测试；本书只阅读它们，没有宣称运行这些Rust测试。新写的教学实验不替代宿主版本实际回归。

3. 初始上下文是有类型的项目序列

build_initial_context在这个快照中从执行策略构造开发者级指令，加入可选开发者指令、用户项目规则和环境信息。它返回的是ResponseItem集合，不是最终Token数组。之后服务仍可能应用不可见的模板和系统规则。[N03]

调试时应问每条信息在什么角色、什么阶段进入。项目规则在客户端通常作为某类用户上下文项目，不应因文件名像“系统规则”便获得无限权限。工具Schema也不一定和聊天文本存放在同一字段中。判断信息是否可见，必须查看实际请求边界，而不是只看UI里显示的聊天气泡。

这对技能系统的重要启发是：专业指令应有明确进入点，并能观测“元数据发现→完整内容读取→被用于结果”的差异。文本存在于磁盘上，并不等于模型看到；模型看到，并不等于执行正确。

4. run_turn：一个用户轮次可以包含多次模型调用

该函数先检查输入与上下文用量，必要时触发压缩，读取技能相关信息，记录用户输入和技能注入项目，然后进入模型调用循环。循环中还会处理运行期间追加的用户输入，基于当前历史构造本轮提示，并根据是否需要后续行动决定继续或结束。[N03]

从工程角度看，用户的一次“修复问题”不是单次HTTP调用。工具输出、运行中追加约束、压缩后的历史都可能改变下一次输入。做性能统计时应以完整用户任务为顶层，不能只统计第一轮模型调用。

把这段机制用于排障：若技能刚开始加载过，但后续未生效，需要看之后的历史是否保留、是否压缩、是否进入子Agent、是否被新证据覆盖。不能凭开头日志证明整个长任务一直保留完整技能内容。

5. compact.rs：本地摘要路径不等于所有Codex压缩

所读快照的一条本地路径会发起摘要请求，在上下文超限时裁掉较旧项目后重试；成功后从历史提取摘要，结合初始上下文与预算内用户消息重建历史，保存压缩事件。代码还显式提示多次压缩可能影响准确性。[N04]

这里要谨慎：另有官方Compaction接口能返回不透明压缩项目；本地可读摘要与服务端不透明状态不是同一个实现。不能据一份旧源码宣称“Codex一定只把历史变成一段普通文字”。也不能因服务返回加密项目就断言“语义完全无损”。其内部表示未公开，业务保真仍要用后续任务验证。[N06]

源码注释与代码行为发生张力时，应优先描述实际操作并保留疑问。例如删除历史开头项目如何影响前缀缓存，需要根据真实请求重算可复用前缀，不能只照抄“为了缓存”的注释便当成普遍结论。资深源码阅读包括验证注释，而不是把注释视为算法证明。

6. SSE转换：显示内容与可执行项目分开

另一个固定提交中的process_responses_event分别处理文本增量、完成的输出项、失败与完成事件；相关测试包含流未收到完成事件便关闭的错误情况。这与第07章教学解析器的边界一致，但本书实现不是Rust代码的移植，也没有覆盖其所有事件类型。[N05]

实际产品还需要处理取消、重连、模型特性与兼容版本。读源码时，先画出“网络事件→内部事件→历史→工具运行器→下一轮请求”的类型链，再查每个转换是否丢失ID、状态或错误。单看UI是否出现一句话不足以判断状态机正确。

7. 将源码阅读转成自己的排障方法

遇到“子Agent没有技能/MCP”，应依次验证：宿主版本及产品面、配置发现路径、实际加载结果、可用工具集合、委派时输入构建、执行权限、返回证据。不要先发明一个继承系统去补不存在的缺陷。

毕业标准不是背住几个函数名，而是拿到另一个提交后能够重新找到等价边界，辨认变更对上下文、技能和错误恢复的影响。对自己的扩展项目只改真正由它负责的层：若宿主已经实现执行、权限与缓存，就不要在技能仓库里重复建设一整套Harness。