不要从目录开始读 Codex

打开 openai/codex 的 Rust workspace，目录看起来很愿意帮忙：protocol 放协议，core 放核心，app-server 接客户端，tui 管终端界面。顺着这个印象往下读，很快就会遇到一个麻烦：这些目录名只告诉你代码放在哪里，没有告诉你运行时谁持有状态，谁决定继续，谁只是转发。

我以前读这类大型仓库，也会先给 crate 贴上“入口”、“核心”、“存储”这些标签。它对找文件有用，但一到多层异步系统，这张图就容易失真。Cargo.toml 里的 workspace membership 只说某个 package 参与同一次构建；codex-app-server 依赖 codex-core 只说前者可以引用后者的公开能力。它们都没有直接证明一条用户输入会怎样经过运行时。

本章换一种读法：先固定版本，再追控制权。只有当源码出现实际的函数调用、channel 收发、ownership 字段或事件消费时，我们才把箭头画上去。

先把证据固定在一个版本

本书只分析 openai/codex 开源仓库，第一版锁定 rust-v0.144.6，对应 commit 是：

5d1fbf26c43abc65a203928b2e31561cb039e06d

后面所有 SourceEvidence 都指向这个 commit。不锁版本的问题不只是行号会移动。Codex 的协议、task 抽象、工具和 app-server 转译都在变；如果从不同 commit 拼类型名，最后可能得到一条“每个符号都存在，但从没有整体运行过”的伪调用链。

先准备一份读者自己持有的 checkout。下面的 repo 默认指向系统临时目录里的固定子目录；如果你已经有一份固定 checkout，可以先设置 CODEX_SOURCE_DIR。

repo="${CODEX_SOURCE_DIR:-/tmp/codex-handbook-final-rust-v0.144.6}"

if [ ! -e "$repo" ]; then
  git clone --depth 1 --branch rust-v0.144.6 \
    https://github.com/openai/codex.git "$repo"
fi

test "$(git -C "$repo" rev-parse HEAD)" = \
  5d1fbf26c43abc65a203928b2e31561cb039e06d
git -C "$repo" describe --tags --exact-match HEAD

clone 会访问网络并写入目标目录，后两条校验只读 Git 对象。预期 test 静默通过，describe 输出 rust-v0.144.6。如果目标已存在但 commit 不匹配，不要直接覆盖；把 repo 换到一个空目录重新 clone。

读者实验：只用 git grep 串起控制链

这组命令不运行 Codex，也不伪造 trace 输出。它在固定 tag 上定位静态控制权交接点：先找信封与操作词汇，再找 submission consumer 和 UserInput 分支，然后追到 RegularTask / run_turn、conversation 记录，最后看 app-server 如何消费 core event。

repo="${CODEX_SOURCE_DIR:-/tmp/codex-handbook-final-rust-v0.144.6}"

git -C "$repo" grep -n 'pub struct Submission' rust-v0.144.6 -- \
  codex-rs/protocol/src/protocol.rs
git -C "$repo" grep -n 'pub enum Op' rust-v0.144.6 -- \
  codex-rs/protocol/src/protocol.rs
git -C "$repo" grep -n 'submission_loop' rust-v0.144.6 -- \
  codex-rs/core/src/session
git -C "$repo" grep -n 'Op::UserInput' rust-v0.144.6 -- \
  codex-rs/core/src/session/handlers.rs
git -C "$repo" grep -n 'RegularTask' rust-v0.144.6 -- \
  codex-rs/core/src/session/handlers.rs codex-rs/core/src/tasks/regular.rs
git -C "$repo" grep -n 'run_turn(' rust-v0.144.6 -- \
  codex-rs/core/src/tasks/regular.rs codex-rs/core/src/session/turn.rs
git -C "$repo" grep -n 'record_conversation_items' rust-v0.144.6 -- \
  codex-rs/core/src/session
git -C "$repo" grep -n 'next_event()' rust-v0.144.6 -- \
  codex-rs/app-server/src/request_processors/thread_lifecycle.rs

预期观察是一组“定义 + 调用点”，不是动态时序：Submission 定义会落在 protocol.rs，submission_loop 和 Op::UserInput 分支会落在 handlers.rs，RegularTask::run 会调用 run_turn，record_conversation_items 会有多个调用点，app-server listener 则在 thread_lifecycle.rs 等待 next_event()。命中数会随版本变化，所以实验不声称固定输出行数。

先把地图上的对象分开

Submission 是一个包含 { id, op, ... } 的信封，Op 是信封承载的操作词汇。Op::UserInput 只是其中一种 payload；同一个 enum 里还有中断、Realtime 控制和 thread settings 等操作。它们位于协议边界，不能因为名字里有 input，就把它们直接当成 turn 或 Agent loop。

Submission、TurnContext、Event、ThreadId 是不同类型。前三者各有自己的关联字段，ThreadId 则是基于 UUID 的长期 thread 身份。值相同只说明某条路径传递了 correlation id，不说明四个对象共享生命周期。

地图阶段只需要记住这条分叉：只有 NoActiveTurn 才让 Submission.id -> TurnContext.sub_id -> Event.id 成为新 task 路径中的关联链；steering submission 进入已有任务后，后续 lifecycle event 沿用 active task 原有的 turn_context.sub_id。这里先确认分支存在，不继续展开 pending queue、取消与完成清理；这些正是第 7 章的主线。

从门面到投影，先记住七个导航点

Codex 在注释里被称为 high-level interface，它是 submission / event 双向队列门面：tx_sub 接受操作，rx_event 向外提供事件。它持有 Arc<Session>，也负责启动后台 submission loop，但不亲自执行模型回路。

Session 是运行状态的 owner：它保存长期 state、active turn、input queue 以及工具和模型相关 services。继续向下定位，主干是 start_task -> RegularTask::run -> run_turn。这串名字在本章只用于确认代码应往哪里读；RunningTask 怎样写入、steer 怎样排队、cancel 怎样传播，都留给第 7 章逐项证明。

再往下有三个不同去向。record_conversation_items 把会话项写入 live history，并请求 rollout 持久化；core event 由下游 listener 消费；app-server 的 ThreadState 只维护客户端需要的投影。它们彼此相关，却不是同一份状态的三个名字。

flowchart TD
    accTitle: Codex 源码导航图
    accDescr: 这张图只画控制权交接：Submission 经队列进入 Session；Session 选择已有任务或新任务，再进入 turn loop。会话项写入 live history 与 rollout，core event 由 app-server listener 消费并形成客户端投影。
    CLIENT["CLI / TUI / app-server client"] --> CODEX["Codex\nsubmission / event facade"]
    CODEX --> PROTOCOL["Submission { id, op }"]
    PROTOCOL --> SESSION["Session\nstate / active turn / input queue"]
    SESSION --> DECISION{"steer decision"}
    DECISION -->|"existing active task"| EXISTING["active turn / pending input"]
    DECISION -->|"NoActiveTurn"| TASK["new RegularTask"]
    EXISTING --> TURN["RegularTask / run_turn"]
    TASK --> TURN
    TURN --> ITEMS["record_conversation_items"]
    ITEMS --> HISTORY["live History"]
    ITEMS --> ROLLOUT["rollout persistence"]
    TASK --> EVENTS["core Event queue"]
    EVENTS --> LISTENER["app-server thread listener"]
    LISTENER --> PROJECTION["ThreadState / typed notification"]

app-server thread listener 等待 conversation.next_event()，先更新 thread-local 投影，再处理协议通知。RawResponseItem 在未启用 raw event 时会被过滤。这个消费端能回答客户端最后看到了什么，不能替 core Session 回答当前 task 由谁持有。

这张图到此刻意停止。history、rollout 与 SQLite 的写入和恢复由第 25 章解释；app-server 的 JSON-RPC 投影由第 30 章解释。本章只负责让后续问题落到正确 owner，而不是提前替这些章节讲完内部机制。

回到 crate 地图，但不再把目录当调用链

现在可以回头看目录。下表标的是本章已经追到的责任，不是宣称模块之间没有其他交叉。

对后面的阅读，这张表有一个很实用的用法：每当看见一个类型或事件，先问它只是描述了数据，还是真的持有了下一步控制权。前者需要继续找 consumer，后者才值得在调用图上画箭头。

失败边界：这张地图不能替你证明什么

第一，workspace membership / dependency edge 只能证明 build membership 或可引用关系，不能证明 runtime control flow。如果要画 app-server -> core 的运行时箭头，还得找到实际的调用或 channel 交接。

第二，同值 id 只能证明 correlation / value transfer。在 NoActiveTurn 新建 task 的路径里，新 submission id 会进入新 TurnContext.sub_id，该 task 后续事件再从这份 context 取得 Event.id；steering 则把输入加入已有 active turn，后续 task event 沿用原 active turn id。这两条路径都不能让 submission、turn、event 和 thread 变成同一个对象。

第三，Op::UserInput 命中了 submission handler，不能证明新 RegularTask 已创建。还要看 steer_input 的结果；Ok 续接活跃 turn，NoActiveTurn 才进创建分支。

第四，TurnStarted 不能证明模型已经返回 token。RegularTask::run 在调用 run_turn 之前就发出了这个事件，它是生命周期起点，不是 sampling 成功证据。

第五，app-server 的 ThreadState 收到 TurnComplete 只能说明它消费到了 core 终态事件。它不能反向证明某一个 rollout writer 的 durability 级别，也不能说明下一次模型请求将怎样构造 history。

这些负向结论比“哪个 crate 最重要”更值得保留。它们直接决定排障顺序：先确认你看到的是 build relation、value correlation、lifecycle event，还是真正的 runtime ownership，然后再往下追。

把入口问题留给下一章

到这里，我们已经有一张足以导航的地图：Codex 是提交/事件门面，Session 持有 active turn 和运行状态，submission_loop 分派操作，RegularTask::run 交给 run_turn，record_conversation_items 在 turn 内汇合 history / persistence / raw response items，app-server 在下游消费事件并维护投影。

还有一个问题没有回答：真正的进程入口在哪里，CLI、TUI、app-server 又分别怎样把控制权交到这张地图上？下一章《运行时入口：CLI、TUI 与 app-server 怎样连到 core》从这里继续。