Codex 中文技术解读

这份文档基于本地源码 /Users/gitsilence/github/codex 编写，目标不是复述 README，而是帮助开发者理解 Codex 仓库里值得学习的工程设计：线程模型、agent loop、工具 harness、上下文裁剪与压缩、插件、MCP、skills、/goal 以及持久化回放。

阅读路线

如果你第一次看 Codex 源码，建议按这个顺序读：

  1. 架构总览：先建立 crate、线程、事件、工具、扩展之间的关系。
  2. 用户旅程：从用户输入到模型回复，走一遍端到端路径。
  3. Agent Loop：理解一次 turn 如何多轮采样、执行工具、继续采样。
  4. Harness Engineering：看 Codex 如何把模型动作纳入审批、沙箱、hook、遥测和取消语义。
  5. 权限、沙箱与网络：理解 Codex 如何把模型动作限制在可审批、可审计的边界内。
  6. 上下文工程：拆分“上下文注入、裁剪、压缩、新窗口”四个概念。
  7. Hooks 生命周期、Multi-Agent、Code Mode：看更复杂的 runtime 扩展点。
  8. 插件与 Skills、MCP、/goal：看扩展能力如何接入主循环。

文档范围

本文档聚焦当前仓库的本地源码实现，尤其是 Rust workspace：

  • codex-rs/core：核心线程、turn、工具、上下文、MCP、压缩逻辑。
  • codex-rs/protocol：客户端和 agent 之间的 Submission Queue / Event Queue 协议。
  • codex-rs/tui、codex-rs/cli、codex-rs/app-server：不同用户入口和宿主形态。
  • codex-rs/core-plugins、codex-rs/plugin、codex-rs/core-skills、codex-rs/ext/*：扩展系统。
  • codex-rs/rollout、codex-rs/thread-store、codex-rs/state：会话历史、线程元数据和结构化状态。
  • codex-rs/app-server、codex-rs/exec-server、codex-rs/model-provider*：宿主协议、执行环境和模型 provider。

图表均以 flowchart TD 编写，并在 docs/assets/diagrams/ 下渲染为图片后嵌入页面。