Codex 源码阅读地图：跟着 Turn，而不是跟着树

阅读契约： 本页假设前言已经解释了为什么 Codex 最好被读成一个 governed turn。这里的问题更实际：当一个用户请求进入系统，下一步应该选择哪条源码路径？跟踪 owner、typed carrier、authority boundary，以及 UI 渲染后仍然留下的 evidence。

Codex 仓库足够大，几乎任何第一选择都会得到回报。你可以从 CLI 开始，看到真实的产品 surface。你可以从 TUI 开始，看到用户可见状态。你可以从 protocol types 开始，看到共享词汇。你也可以从 tools、MCP、sandboxing、app-server code、memory、plugins、cloud-task clients 或 release workflows 开始，而且仍然在看重要的东西。

这正是阅读地图需要路线、而不是目录清单的原因。本页用于前言已经给出 mental model 之后。不要再问“Codex 是什么？”，而是问一个更窄的问题：给定一个普通 user turn，哪一个源码 owner 拥有下一步决策？

本文使用的源码快照是 569ff6a1c400bd514ff79f5f1050a684dc3afde3。每个源码链接都固定到这个 commit，因此阅读路线在 main 变化后仍然可审计。

一、文件树压力

文件树擅长展示名词：cli、core、protocol、tui、app-server、mcp、exec、sandbox、plugins、cloud-tasks、release。它不擅长展示 ownership。同一个用户请求可能穿过好几个名词，才发生任何可见事情。

所以压力点不是“哪个文件夹最重要？”而是“如果跳过哪个边界，我的理解会错？”

把文件夹读成 pressure points。一个 chapter 值得注意，是因为它保护了 turn 的某个 invariant：intent 必须 typed，context 必须 owned，model output 不能自己变成 authority，side effects 必须穿过 policy，evidence 必须保持 reviewable。

二、跟着一个 User Turn

使用一个故意普通的请求：

修改这个 workspace 里的一个文件，需要时运行检查，然后报告发生了什么。

这个请求给你一条活的 routing test。每一步中，只要知道谁拥有下一步决策，就停止把当前文件当成全部架构来读。

这条路线让前言里的 queue-pair model 留在背景里，不需要重复。前言解释 submissions 和 events 为什么是最小 runtime contract。本页把这个 contract 当成指南针：请求离开一个 owner 时，找到指向下一个 owner 的 typed handoff。

三、源码机制：选择下一个 Owner

源码路线有三个常见切换点。每一个都是读者应该换文件的地方，因为当前 owner 已经完成了它的工作。

3.1 Entry Code 展示 Surface，不展示全部架构

在固定 commit 上，CLI 的 Subcommand enum 足够说明 Codex 暴露了许多 entry surfaces。一个删节版 excerpt 可以说明问题：

enum Subcommand {
    Exec(ExecCli),
    Review(ReviewArgs),
    // login, logout, and other local commands omitted
    Mcp(McpCli),
    Plugin(PluginCli),
    McpServer,
    AppServer(AppServerCommand),
    RemoteControl,
    Sandbox(SandboxArgs),
    Debug(DebugCommand),
}

不要把这个片段读成“CLI 就是架构”。它是路线标记。一旦 entry surface 把 command 转成 typed request，下一个问题就属于 protocol 和 runtime，而不是 argument parsing。

3.2 Turn Function 标出 Runtime Ownership

Governed turn 是 context、model streaming、pending input、tool calls、compaction、cancellation 和 completion 开始汇合的地方。run_turn 的 signature 是一个紧凑源码锚点：

pub(crate) async fn run_turn(
    sess: Arc<Session>,
    turn_context: Arc<TurnContext>,
    input: Vec<UserInput>,
    prewarmed_client_session: Option<ModelClientSession>,
    cancellation_token: CancellationToken,
) -> Option<String> {

把它读成 ownership signal。Turn 不只是一次 model call。它接收 session state、turn-scoped context、user input、optional provider session state 和 cancellation。如果你在审计“用户请求期间发生了什么”，这里就是 entry-surface reading 应该变成 runtime reading 的点。

3.3 Tool Code 只有在 Authority 可见后才有意义

Tool implementation files 很有吸引力，因为它们具体：shell、patch、filesystem、MCP、network 和 sandbox behavior 看起来都是“动作”。更安全的地图，是先问这个动作如何被授权和尝试。ToolOrchestrator 展示了位于具体执行之前的 owner：

pub(crate) struct ToolOrchestrator {
    sandbox: SandboxManager,
}

这个小 struct 指向更大的路线：approval context、sandbox selection、permission hooks、network approval、attempts、retry behavior 和 result shaping。源码读者应该先定位允许 handler 运行的 authority path，再打开具体 shell 或 patch handler。

四、常见误读

这些错误有同一个形状：它们停在第一个熟悉的 surface。修正动作永远是追问哪一个 owner 接下来携带请求。

五、阅读路线

限时路线不是论证本身。它们是在 turn route 清楚之后分配注意力的方式。

5.1 30 分钟路线

需要最快建立可靠 mental model 时，使用这条路径：

这条路线之后，你应该能从 entry surface 讲清一个请求如何变成 typed operation、turn owner、model stream、tool authority、event evidence 和 client-visible result。

5.2 2 小时路线

如果你想获得 source-grounded architecture knowledge，但不想打开每个 GitHub link，用这条路径：

1. 读前言，再读第 1-8 章。这会给出 bounded runtime model、startup narrowing、configuration、protocol、session ownership、turn loop、provider streaming 和 rollout evidence。
2. 读第 9-16 章。这会把 model-visible tool specifications 继续推进到 routing、shell、patch、hooks、human approval、sandboxing、app-server、SDKs、daemon control 和 TUI rendering。
3. 读第 17-22 章。这部分覆盖 MCP、skills、plugins、migration、multi-agent coordination、cloud task boundaries、identity 和 memory。
4. 读第 23-25 章和结语。这会解释为什么 build systems、generated contracts、packaging、release workflows 和 CI policy 是 architecture 的一部分，而不是 delivery chores。
5. 只有在 narrative route 稳定之后，再使用模式索引、源码索引和实现参考。

2 小时路线应当留下 owner boundaries，而不是 trivia。你应该知道哪些 facts 是 runtime contracts，哪些是 client projections，哪些是 authority gates，哪些是 release-time enforcement。

5.3 源码审计路线

当你想根据固定 commit 验证论断时，使用这条路径：

做一次 focused audit 时，只先打开这些锚点：

1. Submission, Op, Event, and EventMsg，用于共享 protocol vocabulary。
2. Codex、submit 和 next_event，用于 session facade。
3. session/turn.rs，用于 governed turn。
4. ToolOrchestrator，用于 approval、sandbox、attempt 和 retry ownership。
5. MessageProcessor 和 ChatWidget，用于 client projection。
6. rust-release.yml 和 verify_tui_core_boundary.py，用于 release 与 governance evidence。

六、可迁移规则

可复用的教训，是先设计阅读路线，再设计阅读清单。

如果 source tree 显得太大，不要打开更多文件。选择一个普通请求，跟着携带它的 owner 走。Owner 变了，就换文件。Owner 还是同一个，就继续读。

七、源码地图

下面的地图是整条路线的紧凑版本。它有意面向 claim，而不是面向 folder。

需要更密集锚点时，用源码索引；已经知道路线、需要精确 subsystem facts 时，用实现参考。本页的工作更简单：让一个请求沿着正确 owner 移动，直到 source tree 从一堆文件变成一条路径。