前言
阅读契约： 先用本页锁住全书论点：context 是受治理的 runtime state，不是不断增长的 transcript。阅读后续章节时，把 ledger、envelope、fragments、optional planes、compaction 和 replay 六个 owner 分开看。
本书讨论 Codex 中容易被低估的一个部分：上下文管理。大多数关于 agent 的文章谈的是 tools、模型和用户界面。Codex 之所以值得研究，是因为它把上下文当作受治理的运行时状态。发给模型的 prompt 不是一个会一直增长直到失败的字符串，而是一份 thread 账本、一个 turn envelope、typed context fragments、策略 diff、可选知识平面、compaction checkpoint 和 replay 证据共同投影出的视图。
本书使用的源码快照是 569ff6a1c400bd514ff79f5f1050a684dc3afde3。本书的设计目标是无需先打开源码就能读懂。源码链接是审计锚点，不是作业。
证据分三层阅读：struct、function、field 和源码注释层面的直接陈述，来自固定 commit 的公开源码链接；正文里的 owner、lifetime、projection 语言，是基于这些可见契约的有界工程解释；凡是需要 provider 内部状态或未公开服务行为才能证明的内容，都不属于本书的断言边界。
论点
架构赌注很简单：
Codex 通过把上下文做成运行时边界，而不是 prompt 构造的便利，让长期 agent 工作保持连贯。
这个赌注解释了整个子系统的形状：每个 turn 都有显式信封；采样前历史会 normalize；运行时事实通过 typed fragments 注入；可选材料受预算约束；compaction 安装 replacement history；resume 与 fork 从 rollout 证据重建 prompt；客户端渲染上下文状态，但不拥有它。
一张总览
读任何章节之前，先把整个子系统理解成一组顺序展开的 owner：runtime boundary、turn envelope、history ledger、typed fragments、optional budget、checkpoint、replay、client surfaces。每一章都默认前面的 owner 已经存在，专注自己的关注点；如果某章觉得脱节，就回到这个 owner 顺序里重新定位它。
本书覆盖的范围
本书不是 Codex 使用教程，而是关于 Codex 如何在一个长期运行的软件工程 agent 中承载上下文的技术读物：
| 层 | 它讲什么 |
|---|---|
| Turn envelope | 模型身份、策略、工作区、tools、hooks、feature gates 如何为一次 turn 收集起来。 |
| 历史账本 | response items 如何变成 prompt-ready 历史，同时保留 call/output 不变量。 |
| Context fragments | environment、permissions、realtime、skills、plugins、hooks、memory 如何变成模型可见状态。 |
| Budgeting | Codex 如何防止可选上下文吃掉整个窗口。 |
| Compaction | 长线程如何被重写成带 checkpoint 的 replacement history。 |
| Replay | resume、rollback、fork 后的 thread 如何重建有效上下文。 |
| 客户端面 | TUI、app-server、realtime、trace、token usage 如何在不变成真相来源的前提下暴露上下文。 |
不需要 Rust 专家也能读
只有当 Rust 细节能揭示设计时，本书才会引入它们。读到 “struct” 就理解为”有名字的状态包”，读到 “enum” 就理解为”封闭的运行时分支集合”，读到 “async task” 就理解为”在等待模型、tools、hooks 或 I/O 时可以暂停的工作”。
源码链接指向 Codex 公开仓库。正文描述可见契约，并刻意避开 provider 内部模板或服务实现体；出现伪代码时，它说明的是模式，使用通用名称。
如何使用本书
技术负责人可以读每章开头、手绘图与”应用模式”，理解设计原理。资深工程师建议读完每一章，包括深入部分，因为真正的功课不是”摘要旧消息”，而是如何让一个可变 prompt projection 始终与持久证据绑定。
每章末尾五条”应用模式”是可迁移的模式：如果你在设计新的 agent runtime，模式比具体字段名更重要；如果你在阅读 Codex 源码，章节叙事比模式更重要。