架构总览¶

Codex 仓库的主体是 codex-rs Rust workspace。外层的 codex-cli、npm 包和 SDK 更像分发与集成入口，真正的 agent 运行时集中在 codex-rs/core、codex-rs/protocol、codex-rs/tui、codex-rs/app-server 和一组扩展 crate 中。

核心分层¶

层	代表源码	主要职责
用户入口	codex-rs/cli/src/main.rs、codex-rs/tui/src/*、codex-rs/app-server/src/*	CLI/TUI/桌面 app server 等不同宿主入口
协议层	codex-rs/protocol/src/protocol.rs	定义 Submission、Op、Event、EventMsg、turn/thread 事件
线程管理	codex-rs/core/src/thread_manager.rs、codex-rs/core/src/codex_thread.rs	创建、恢复、fork、关闭线程，维护 live thread map
Session/Turn	codex-rs/core/src/session/*、codex-rs/core/src/tasks/*	管理一次会话内的任务互斥、turn 生命周期和模型采样循环
工具系统	codex-rs/core/src/tools/*	工具注册、模型可见 spec、并发、hook、审批、沙箱、执行结果
上下文系统	codex-rs/core/src/context*、codex-rs/core/src/context_manager/*、codex-rs/core/src/compact*.rs	初始上下文、差量上下文、历史规范化、裁剪和压缩
扩展系统	codex-rs/ext/*、codex-rs/core-plugins、codex-rs/core-skills	通过 lifecycle contributor、tool contributor、MCP contributor 注入能力
持久化	codex-rs/rollout、codex-rs/thread-store、codex-rs/state	JSONL rollout、线程 store、SQLite 状态和索引

设计主线¶

Codex 的主线不是“模型调用一个 shell 工具”这么简单，而是把模型行为包进一个可控运行时：

• protocol 把客户端和 agent 的异步交互抽象成 Submission Queue / Event Queue。
• ThreadManager 创建 CodexThread，每个线程持有一个 Session。
• Session 保证同一时刻最多一个 running task，但允许用户输入进入 InputQueue，由下一轮采样消化。
• run_turn 是 agent loop 的核心：准备 prompt、发起 Responses API 流、解析模型输出、执行工具、把工具结果写回历史并继续采样。
• ToolRegistry 和 ToolOrchestrator 把工具执行统一纳入 pre/post hook、审批、沙箱、网络策略、遥测和取消语义。
• ContextManager 维护模型历史，同时用 compaction 和 context window 机制控制长线程成本。
• 扩展系统让 /goal、MCP、plugins、skills 这类功能不需要直接改主循环。

一个重要取舍¶

Codex 没有把所有逻辑塞进一个“agent 类”。它大量使用小 crate 和 contributor 接口，把横切能力放到生命周期事件里：

• 目标系统在 TurnLifecycleContributor、ToolLifecycleContributor、TokenUsageContributor 上记账。
• MCP 通过 McpServerContributor 汇入 runtime config。
• 插件通过 manifest 提供 skills、MCP servers、apps、hooks 和 UI metadata。
• 工具通过 ToolExecutor 和 CoreToolRuntime 接入统一执行面。

这种结构的好处是：主循环保持稳定，新增能力更多是在边界上“贡献”工具、上下文或生命周期行为。