Context 引擎

Context 是一次采样的世界

模型不知道你的磁盘、终端或上一秒发生了什么。一次采样中没有被放进请求的信息，对模型来说就不存在。

Codex 的 Context 可以理解为六层：

flowchart TB
B["Base instructions<br/>产品与模型基础指令"]
D["Developer / repository instructions<br/>AGENTS.md 等"]
U["User input<br/>目标与补充"]
E["Environment context<br/>cwd / shell / permissions"]
H["History<br/>消息 / 工具调用 / 工具结果"]
S["Tool specs<br/>可调用能力与参数"]
B --> P["Sampling request"]
D --> P
U --> P
E --> P
H --> P
S --> P
P --> M["Model"]

这里的“历史”不是简单字符串。协议层用不同 item 表示用户消息、assistant 消息、工具调用和工具结果；ContextManager 负责记录，并在请求前生成适合模型的视图。

静态输入与动态观察

静态输入

在一个 Turn 开始时，Runtime 会捕获本轮设置，例如模型、审批策略、沙箱、工作目录与项目指令。这给一轮执行提供相对稳定的边界。

动态观察

搜索结果、文件内容、命令输出、测试失败、审批结果会随着循环追加。它们是模型认识真实环境的主要方式。

为什么要规范化

真实工具输出可能很脏：上万行日志、二进制字符、重复状态、半完成的 tool call。直接累计会造成三类问题：

• 超过模型窗口；
• 重要信息被噪声淹没；
• 请求结构不符合模型协议。

因此 Context 管理不只是 token 计数，还要保持调用与结果的配对、删减不适合请求的 item，并在必要时回滚或压缩。

Compaction：把轨迹变成新的起点

当上下文接近上限，Codex 可以压缩已有对话。概念上，它把：

几十轮搜索 + 文件片段 + 测试输出 + 中间讨论

折叠成：

当前目标、已确认事实、已修改内容、验证状态、未解决问题

然后以这份摘要继续执行。公开源码中，压缩既有核心实现，也有对应 Task 类型。

Prompt cache 与稳定前缀

模型 API 往往能复用稳定请求前缀。把基础指令、工具规格等相对稳定内容放在前部，有利于缓存；频繁变化的工具结果和用户补充放在后部。

这是理解工程取舍的好例子：Context 排列既影响模型理解，也影响延迟与成本。具体服务端缓存细节不在本仓库公开范围内，本教材只讨论可观察的请求组织。

给 Agent 上下文的实用原则

指令要可执行

“保持高质量”不如“修改后运行 pnpm test --filter core，不得改生成文件”。

先给目标与验收，再给背景

Agent 需要知道怎样算完成。背景资料应服务于决策，而不是堆满窗口。

让权威信息落在仓库

把长期有效的构建命令、目录边界和代码规范写进 AGENTS.md 或项目文档；临时偏好留在当前请求。

输出要主动限宽

先 rg 再 sed，先目标测试再全量日志。工具的边界感直接决定 Context 质量。

失败模式

下一章看这些观察是如何通过 Tool、Shell 与 Patch 安全地作用于环境。