Architecture, Patterns, Internals

Codex 源码剖析：把 Codex 当作系统阅读。

一本固定到公开源码 commit 的专业技术书：把 Codex 解释为一个事件溯源的 agent runtime，覆盖类型化契约、策略门控工具、可回放状态、多客户端、扩展、云工作流和可执行治理。

从前言开始源码索引

Codex From Source：entry points、protocol、session runtime、tools、clients 和 governance 组成的有边界 agent runtime — 这本书把 Codex 作为一个有边界的 agent runtime 阅读：入口、类型协议、 session runtime、工具与策略、客户端和治理共同构成系统。

先读契约

先建立 operations、events、threads、turns、items 的词汇，再进入 UI 代码。

抓住运行时主线

把 session state、turn scheduling、provider streaming 和 rollout trace 当作一个循环来读。

统一看副作用

把 tools、shell、patches、approvals、hooks、sandboxes 和 network policy 放进同一套 authority stack。

最后看开放与治理

用 app-server、SDK、TUI、extensions、cloud tasks、release 和 CI 收束整套系统。

源码支撑

默认先读书理解架构、数据流、契约和取舍；固定源码链接用于审计，而不是作业。

出版级结构

章节按技术书组织，不是 API 文档；每一层解决一个问题，并为下一层铺路。

源码固定

所有源码链接都固定到 569ff6a1c400bd514ff79f5f1050a684dc3afde3，避免分支漂移。

1 架构赌注把 Codex 定义为有边界的 agent 操作系统。 2 从分发包装器到 Rust Router 解释启动路径如何把用户意图收窄为类型化命令。 3 配置、认证与 Managed Requirements 说明配置、身份与托管要求如何变成运行时约束。 4 协议边界梳理客户端、会话和回放共享的类型化词汇。

第 2 部

构建运行时

运行时是 context、streaming、tools、cancellation 和 replay 的调度器。

5 线程、会话与持久状态解释所有权、队列、历史、rollout 和可恢复性。 6 Turn Loop 说明上下文、模型流、工具和续跑如何汇合。 7 模型 Provider、流式传输与 Backend Task 解释 provider 传输、事件归一化和后台任务边界。 8 Observability 与 Rollout Trace 说明原始运行时事实如何变成可回放、可检查的证据。

第 3 部

执行副作用

模型可以建议动作；Codex 决定它是否真正变成副作用。

9 工具规格、路由与分发解释模型可见工具如何变成受治理的副作用。 10 Shell、Exec Server 与文件系统工具说明进程与文件系统能力如何受运行时策略约束。 11 把 Patch 作为一等编辑协议把结构化 patch 作为替代不透明 shell 编辑的协议。 12 Hooks 与人工审批解释危险动作到达外部世界前的策略门。 13 Sandboxes、网络策略与平台边界梳理平台隔离与网络访问调解。

第 4 部

开放运行时

当多个客户端共享同一个 thread model 时，运行时才成为平台。

14 App-Server 契约解释面向客户端和 SDK 的 JSON-RPC 边界。 15 SDK、Daemon 与远程控制说明外部客户端如何接入同一个运行时。 16 TUI 作为事件渲染器把终端 UI 解释为事件投影，而不是另一个运行时。

第 5 部

扩展系统

扩展点只有在每个信任边界都显式时才有用。

17 MCP：没有运行时耦合的外部工具说明外部工具服务器如何通过来源和路由边界接入。 18 Skills、Plugins、Connectors 与类型化扩展解释扩展打包和显式信任平面。 19 外部迁移与向后兼容把兼容性作为运行时和产品约束。

第 6 部

协调工作

持久工作需要图边、任务契约和受控 memory。

20 多 Agent 协作解释 thread、graph edge 和子 agent 结果如何协作。 21 云任务、身份与远程工作把远程工作解释为任务契约加本地验证。 22 Memories 与用户级状态把长期上下文作为受控旁路。

第 7 部

发布与治理

架构只有在发布和 CI 持续执行时才会存活。

23 构建系统与生成契约说明构建 overlay 与生成 schema 如何执行边界。 24 打包、发布与原生依赖解释 Rust workspace 到 npm 原生包的发布路径。 25 CI、策略与架构治理说明 CI 与策略检查如何让架构保持诚实。

结结语：真正值得带走的东西从完整系统中抽取可迁移的设计经验。

参考页

模式索引可迁移模式的紧凑索引。源码索引用于审计的固定源码锚点。实现参考面向源码级审阅的密集子系统参考。参考文献源码和外部参考资料。写作流水线说明本书如何生产和校验。