【Codex】Part 18 — Codex Context Lifecycle Management

bryant_meng2026-08-26 9:34

文章目录

  • [第十八章 Codex 的上下文生命周期管理](#第十八章 Codex 的上下文生命周期管理)
  • [18.1 先区分四类状态](#18.1 先区分四类状态)
  • [18.2 上下文如何形成](#18.2 上下文如何形成)
    • [18.2.1 信息来源](#18.2.1 信息来源)
    • [18.2.2 视觉算法任务示例](#18.2.2 视觉算法任务示例)
  • [18.3 上下文为什么会增长](#18.3 上下文为什么会增长)
    • [18.3.1 少读，但读准](#18.3.1 少读，但读准)
    • [18.3.2 把事实写入产物](#18.3.2 把事实写入产物)
  • [18.4 Prompt 缓存不是"记忆"](#18.4 Prompt 缓存不是“记忆”)
  • [18.5 上下文压缩如何工作](#18.5 上下文压缩如何工作)
    • [18.5.1 配置边界](#18.5.1 配置边界)
    • [18.5.2 压缩是有损摘要](#18.5.2 压缩是有损摘要)
  • [18.6 线程的生命周期](#18.6 线程的生命周期)
  • [18.7 哪些信息应放在上下文之外](#18.7 哪些信息应放在上下文之外)
    • [18.7.1 `AGENTS.md`：稳定的项目规则](#18.7.1 AGENTS.md：稳定的项目规则)
    • [18.7.2 记忆：可复用偏好，不是事实数据库](#18.7.2 记忆：可复用偏好，不是事实数据库)
    • [18.7.3 工作树：隔离文件修改](#18.7.3 工作树：隔离文件修改)
    • [18.7.4 目标：线程内的完成契约](#18.7.4 目标：线程内的完成契约)
  • [18.8 长任务案例：修复 YOLO 的 COCO 类别映射](#18.8 长任务案例：修复 YOLO 的 COCO 类别映射)
    • [18.8.1 先定义实验契约](#18.8.1 先定义实验契约)
    • [18.8.2 分阶段推进](#18.8.2 分阶段推进)
    • [18.8.3 分类与分割任务同样适用](#18.8.3 分类与分割任务同样适用)
    • [18.8.4 何时使用子代理](#18.8.4 何时使用子代理)
  • [18.9 实用操作清单](#18.9 实用操作清单)
  • [18.10 本章小结](#18.10 本章小结)
  • 参考资料

第十八章 Codex 的上下文生命周期管理

摘要：上下文（Context）是模型在当前推理中能够看到的信息，不等同于线程记录、项目文件、记忆或 Git 工作区。理解"信息如何进入上下文、怎样增长、何时压缩、哪些状态必须落盘"，才能让 Codex 稳定完成长任务。

版本说明：本文依据 2026 年 8 月可查的 OpenAI 官方文档整理。Codex 的命令、配置项和产品界面可能继续变化，使用前应以当前文档与本机 codex --help 为准。

18.1 先区分四类状态

讨论上下文之前，先把四个容易混淆的概念分开。

概念 英文 含义 典型内容
上下文 Context 模型本轮能够参考的信息 指令、消息、文件片段、工具结果
上下文窗口 Context Window 模型一次能够处理的信息上限 当前模型可容纳的 Token 总量
线程 Thread 保存对话轮次和相关状态的会话对象 用户消息、模型回复、工具事件
工作区状态 Workspace State 位于模型上下文之外、由文件系统或 Git 保存的事实 源码、配置、数据清单、测试结果

#mermaid-svg-1p8RIGgfSryvmlRg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-1p8RIGgfSryvmlRg .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-1p8RIGgfSryvmlRg .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-1p8RIGgfSryvmlRg .error-icon{fill:#552222;}#mermaid-svg-1p8RIGgfSryvmlRg .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-1p8RIGgfSryvmlRg .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-1p8RIGgfSryvmlRg .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-1p8RIGgfSryvmlRg .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-1p8RIGgfSryvmlRg .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-1p8RIGgfSryvmlRg .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-1p8RIGgfSryvmlRg .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-1p8RIGgfSryvmlRg .marker{fill:#333333;stroke:#333333;}#mermaid-svg-1p8RIGgfSryvmlRg .marker.cross{stroke:#333333;}#mermaid-svg-1p8RIGgfSryvmlRg svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-1p8RIGgfSryvmlRg p{margin:0;}#mermaid-svg-1p8RIGgfSryvmlRg .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-1p8RIGgfSryvmlRg .cluster-label text{fill:#333;}#mermaid-svg-1p8RIGgfSryvmlRg .cluster-label span{color:#333;}#mermaid-svg-1p8RIGgfSryvmlRg .cluster-label span p{background-color:transparent;}#mermaid-svg-1p8RIGgfSryvmlRg .label text,#mermaid-svg-1p8RIGgfSryvmlRg span{fill:#333;color:#333;}#mermaid-svg-1p8RIGgfSryvmlRg .node rect,#mermaid-svg-1p8RIGgfSryvmlRg .node circle,#mermaid-svg-1p8RIGgfSryvmlRg .node ellipse,#mermaid-svg-1p8RIGgfSryvmlRg .node polygon,#mermaid-svg-1p8RIGgfSryvmlRg .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-1p8RIGgfSryvmlRg .rough-node .label text,#mermaid-svg-1p8RIGgfSryvmlRg .node .label text,#mermaid-svg-1p8RIGgfSryvmlRg .image-shape .label,#mermaid-svg-1p8RIGgfSryvmlRg .icon-shape .label{text-anchor:middle;}#mermaid-svg-1p8RIGgfSryvmlRg .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-1p8RIGgfSryvmlRg .rough-node .label,#mermaid-svg-1p8RIGgfSryvmlRg .node .label,#mermaid-svg-1p8RIGgfSryvmlRg .image-shape .label,#mermaid-svg-1p8RIGgfSryvmlRg .icon-shape .label{text-align:center;}#mermaid-svg-1p8RIGgfSryvmlRg .node.clickable{cursor:pointer;}#mermaid-svg-1p8RIGgfSryvmlRg .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-1p8RIGgfSryvmlRg .arrowheadPath{fill:#333333;}#mermaid-svg-1p8RIGgfSryvmlRg .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-1p8RIGgfSryvmlRg .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-1p8RIGgfSryvmlRg .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-1p8RIGgfSryvmlRg .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-1p8RIGgfSryvmlRg .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-1p8RIGgfSryvmlRg .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-1p8RIGgfSryvmlRg .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-1p8RIGgfSryvmlRg .cluster text{fill:#333;}#mermaid-svg-1p8RIGgfSryvmlRg .cluster span{color:#333;}#mermaid-svg-1p8RIGgfSryvmlRg div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-1p8RIGgfSryvmlRg .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-1p8RIGgfSryvmlRg rect.text{fill:none;stroke-width:0;}#mermaid-svg-1p8RIGgfSryvmlRg .icon-shape,#mermaid-svg-1p8RIGgfSryvmlRg .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-1p8RIGgfSryvmlRg .icon-shape p,#mermaid-svg-1p8RIGgfSryvmlRg .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-1p8RIGgfSryvmlRg .icon-shape .label rect,#mermaid-svg-1p8RIGgfSryvmlRg .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-1p8RIGgfSryvmlRg .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-1p8RIGgfSryvmlRg .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-1p8RIGgfSryvmlRg :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-1p8RIGgfSryvmlRg .stage>*{fill:#dbeafe!important;stroke:#2563eb!important;color:#1e3a8a!important;}#mermaid-svg-1p8RIGgfSryvmlRg .stage span{fill:#dbeafe!important;stroke:#2563eb!important;color:#1e3a8a!important;}#mermaid-svg-1p8RIGgfSryvmlRg .stage tspan{fill:#1e3a8a!important;}#mermaid-svg-1p8RIGgfSryvmlRg .art>*{fill:#f1f5f9!important;stroke:#64748b!important;color:#0f172a!important;}#mermaid-svg-1p8RIGgfSryvmlRg .art span{fill:#f1f5f9!important;stroke:#64748b!important;color:#0f172a!important;}#mermaid-svg-1p8RIGgfSryvmlRg .art tspan{fill:#0f172a!important;} 按需读取
适用时加载
编辑或生成
线程记录

历史消息与事件
当前模型上下文

本轮可见信息
指令与用户输入
工作区文件

源码、配置、产物
记忆

跨会话可复用提示
模型响应与工具调用

图 18-1：上下文与持久状态的关系。 线程可以保存历史，文件可以长期存在，但它们不会自动全部进入模型当前可见的上下文。

这一区分直接修正了两个常见误解：

  1. 退出界面不等于所有信息都被"销毁"。保存的线程可以恢复，工作区文件仍然存在。
  2. 文件存在不等于模型已经读过。需要在提示中指明路径，或让 Codex 通过工具按需读取。

18.2 上下文如何形成

18.2.1 信息来源

一次任务的有效上下文通常来自以下几类信息：

  • 系统与开发者指令；
  • 当前目录适用的 AGENTS.md、配置和技能说明；
  • 用户当前的目标、约束和验收标准；
  • 已有线程中的相关消息或压缩摘要；
  • IDE 中显式共享的文件，或 CLI 中明确提到并由工具读取的文件；
  • 工具定义、MCP 工具以及工具返回结果；
  • 图片、日志片段和其他附件。

官方文档没有承诺所有 Codex 客户端都采用一套固定、可观察的 Prompt 拼接顺序。因此，可以讨论"哪些信息会影响模型"，但不应把某个内部序列化布局写成稳定接口。
#mermaid-svg-m2DbJgNVAf4smgPH{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-m2DbJgNVAf4smgPH .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-m2DbJgNVAf4smgPH .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-m2DbJgNVAf4smgPH .error-icon{fill:#552222;}#mermaid-svg-m2DbJgNVAf4smgPH .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-m2DbJgNVAf4smgPH .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-m2DbJgNVAf4smgPH .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-m2DbJgNVAf4smgPH .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-m2DbJgNVAf4smgPH .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-m2DbJgNVAf4smgPH .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-m2DbJgNVAf4smgPH .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-m2DbJgNVAf4smgPH .marker{fill:#333333;stroke:#333333;}#mermaid-svg-m2DbJgNVAf4smgPH .marker.cross{stroke:#333333;}#mermaid-svg-m2DbJgNVAf4smgPH svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-m2DbJgNVAf4smgPH p{margin:0;}#mermaid-svg-m2DbJgNVAf4smgPH .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-m2DbJgNVAf4smgPH .cluster-label text{fill:#333;}#mermaid-svg-m2DbJgNVAf4smgPH .cluster-label span{color:#333;}#mermaid-svg-m2DbJgNVAf4smgPH .cluster-label span p{background-color:transparent;}#mermaid-svg-m2DbJgNVAf4smgPH .label text,#mermaid-svg-m2DbJgNVAf4smgPH span{fill:#333;color:#333;}#mermaid-svg-m2DbJgNVAf4smgPH .node rect,#mermaid-svg-m2DbJgNVAf4smgPH .node circle,#mermaid-svg-m2DbJgNVAf4smgPH .node ellipse,#mermaid-svg-m2DbJgNVAf4smgPH .node polygon,#mermaid-svg-m2DbJgNVAf4smgPH .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-m2DbJgNVAf4smgPH .rough-node .label text,#mermaid-svg-m2DbJgNVAf4smgPH .node .label text,#mermaid-svg-m2DbJgNVAf4smgPH .image-shape .label,#mermaid-svg-m2DbJgNVAf4smgPH .icon-shape .label{text-anchor:middle;}#mermaid-svg-m2DbJgNVAf4smgPH .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-m2DbJgNVAf4smgPH .rough-node .label,#mermaid-svg-m2DbJgNVAf4smgPH .node .label,#mermaid-svg-m2DbJgNVAf4smgPH .image-shape .label,#mermaid-svg-m2DbJgNVAf4smgPH .icon-shape .label{text-align:center;}#mermaid-svg-m2DbJgNVAf4smgPH .node.clickable{cursor:pointer;}#mermaid-svg-m2DbJgNVAf4smgPH .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-m2DbJgNVAf4smgPH .arrowheadPath{fill:#333333;}#mermaid-svg-m2DbJgNVAf4smgPH .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-m2DbJgNVAf4smgPH .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-m2DbJgNVAf4smgPH .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-m2DbJgNVAf4smgPH .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-m2DbJgNVAf4smgPH .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-m2DbJgNVAf4smgPH .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-m2DbJgNVAf4smgPH .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-m2DbJgNVAf4smgPH .cluster text{fill:#333;}#mermaid-svg-m2DbJgNVAf4smgPH .cluster span{color:#333;}#mermaid-svg-m2DbJgNVAf4smgPH div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-m2DbJgNVAf4smgPH .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-m2DbJgNVAf4smgPH rect.text{fill:none;stroke-width:0;}#mermaid-svg-m2DbJgNVAf4smgPH .icon-shape,#mermaid-svg-m2DbJgNVAf4smgPH .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-m2DbJgNVAf4smgPH .icon-shape p,#mermaid-svg-m2DbJgNVAf4smgPH .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-m2DbJgNVAf4smgPH .icon-shape .label rect,#mermaid-svg-m2DbJgNVAf4smgPH .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-m2DbJgNVAf4smgPH .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-m2DbJgNVAf4smgPH .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-m2DbJgNVAf4smgPH :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-m2DbJgNVAf4smgPH .stage>*{fill:#dbeafe!important;stroke:#2563eb!important;color:#1e3a8a!important;}#mermaid-svg-m2DbJgNVAf4smgPH .stage span{fill:#dbeafe!important;stroke:#2563eb!important;color:#1e3a8a!important;}#mermaid-svg-m2DbJgNVAf4smgPH .stage tspan{fill:#1e3a8a!important;}#mermaid-svg-m2DbJgNVAf4smgPH .art>*{fill:#f1f5f9!important;stroke:#64748b!important;color:#0f172a!important;}#mermaid-svg-m2DbJgNVAf4smgPH .art span{fill:#f1f5f9!important;stroke:#64748b!important;color:#0f172a!important;}#mermaid-svg-m2DbJgNVAf4smgPH .art tspan{fill:#0f172a!important;} 显式提供或按需读取
系统与项目指令
任务相关上下文
用户目标与约束
线程中的相关历史
文件与附件
工具定义与工具结果
模型推理
回复、工具调用或文件修改

图 18-2：任务相关上下文的来源。 核心不是"塞得越多越好"，而是让当前决策所需的信息足够、明确且可验证。

18.2.2 视觉算法任务示例

假设要修复 YOLO 在 COCO 数据集上的类别映射。比"检查一下代码"更有效的提示是：

检查 datasets/coco.yaml 与 evaluate.py 的类别索引是否一致。只修复映射逻辑，不改权重、输入尺寸、NMS 阈值和评测集。先运行单元测试，再用 100 张图片做冒烟评测（Smoke Test），最后输出完整评测命令和结果文件路径。

这段提示给出了：

  • 目标：修复类别映射；
  • 相关文件：coco.yaml 与 evaluate.py；
  • 固定条件：权重、输入尺寸、NMS 阈值和评测集不变；
  • 验证顺序：单元测试、冒烟评测、完整评测；
  • 交付物：命令和结果路径。

上下文质量取决于这些信息是否能约束行动，而不是字数多少。

18.3 上下文为什么会增长

一个线程中的每轮消息、文件读取、搜索结果和工具输出，都可能成为后续推理的参考。随着任务推进，上下文压力（Context Pressure）通常来自：

  • 反复读取同一批大文件；
  • 将完整训练日志、编译输出或测试输出全部带入对话；
  • 在一个线程中同时处理多个无关目标；
  • 长时间保留已经失效的假设和中间方案；
  • 让多个工具返回远超当前决策需要的数据。

18.3.1 少读，但读准

低效做法 更稳妥的做法
读取整份训练日志 先搜索 ERROR、NaN、mAP，再读取命中位置附近内容
一次打开整个仓库 先查看目录、入口文件和调用链，再逐步展开
在对话中粘贴全部 COCO 评测明细 保留总体指标、分类别异常和结果文件路径
重复描述实验设置 将固定设置写入实验配置和清单，后续引用文件
在一个线程中混合检测、分类和分割任务 为不同交付目标建立独立线程

tool_output_token_limit 可以限制单个工具或函数输出存入历史的 Token 预算，但它不能代替有目的的搜索、分页读取和日志摘要。

18.3.2 把事实写入产物

对长任务而言，最可靠的状态载体不是模型"记得"，而是可检查的产物（Artifact）。例如：

text 复制代码 
experiments/exp042/
├── config.yaml
├── dataset_manifest.json
├── metrics.json
└── formal_result.json

这是目录结构，不需要转换成 Mermaid。config.yaml 记录固定变量，dataset_manifest.json 固定数据范围，metrics.json 保存原始指标，formal_result.json 表示验收完成。即使线程被压缩或恢复，Codex 也可以重新读取这些文件。

18.4 Prompt 缓存不是"记忆"

提示缓存（Prompt Caching）是 API 层的性能优化：当请求共享完全相同的前缀时，系统可以复用已经处理过的前缀。它可能降低延迟和输入成本，但不改变模型可见的上下文，也不保存任务的工程状态。
#mermaid-svg-fThZd6ecJ0NQSjAv{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-fThZd6ecJ0NQSjAv .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-fThZd6ecJ0NQSjAv .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-fThZd6ecJ0NQSjAv .error-icon{fill:#552222;}#mermaid-svg-fThZd6ecJ0NQSjAv .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-fThZd6ecJ0NQSjAv .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-fThZd6ecJ0NQSjAv .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-fThZd6ecJ0NQSjAv .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-fThZd6ecJ0NQSjAv .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-fThZd6ecJ0NQSjAv .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-fThZd6ecJ0NQSjAv .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-fThZd6ecJ0NQSjAv .marker{fill:#333333;stroke:#333333;}#mermaid-svg-fThZd6ecJ0NQSjAv .marker.cross{stroke:#333333;}#mermaid-svg-fThZd6ecJ0NQSjAv svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-fThZd6ecJ0NQSjAv p{margin:0;}#mermaid-svg-fThZd6ecJ0NQSjAv .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-fThZd6ecJ0NQSjAv .cluster-label text{fill:#333;}#mermaid-svg-fThZd6ecJ0NQSjAv .cluster-label span{color:#333;}#mermaid-svg-fThZd6ecJ0NQSjAv .cluster-label span p{background-color:transparent;}#mermaid-svg-fThZd6ecJ0NQSjAv .label text,#mermaid-svg-fThZd6ecJ0NQSjAv span{fill:#333;color:#333;}#mermaid-svg-fThZd6ecJ0NQSjAv .node rect,#mermaid-svg-fThZd6ecJ0NQSjAv .node circle,#mermaid-svg-fThZd6ecJ0NQSjAv .node ellipse,#mermaid-svg-fThZd6ecJ0NQSjAv .node polygon,#mermaid-svg-fThZd6ecJ0NQSjAv .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-fThZd6ecJ0NQSjAv .rough-node .label text,#mermaid-svg-fThZd6ecJ0NQSjAv .node .label text,#mermaid-svg-fThZd6ecJ0NQSjAv .image-shape .label,#mermaid-svg-fThZd6ecJ0NQSjAv .icon-shape .label{text-anchor:middle;}#mermaid-svg-fThZd6ecJ0NQSjAv .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-fThZd6ecJ0NQSjAv .rough-node .label,#mermaid-svg-fThZd6ecJ0NQSjAv .node .label,#mermaid-svg-fThZd6ecJ0NQSjAv .image-shape .label,#mermaid-svg-fThZd6ecJ0NQSjAv .icon-shape .label{text-align:center;}#mermaid-svg-fThZd6ecJ0NQSjAv .node.clickable{cursor:pointer;}#mermaid-svg-fThZd6ecJ0NQSjAv .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-fThZd6ecJ0NQSjAv .arrowheadPath{fill:#333333;}#mermaid-svg-fThZd6ecJ0NQSjAv .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-fThZd6ecJ0NQSjAv .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-fThZd6ecJ0NQSjAv .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-fThZd6ecJ0NQSjAv .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-fThZd6ecJ0NQSjAv .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-fThZd6ecJ0NQSjAv .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-fThZd6ecJ0NQSjAv .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-fThZd6ecJ0NQSjAv .cluster text{fill:#333;}#mermaid-svg-fThZd6ecJ0NQSjAv .cluster span{color:#333;}#mermaid-svg-fThZd6ecJ0NQSjAv div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-fThZd6ecJ0NQSjAv .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-fThZd6ecJ0NQSjAv rect.text{fill:none;stroke-width:0;}#mermaid-svg-fThZd6ecJ0NQSjAv .icon-shape,#mermaid-svg-fThZd6ecJ0NQSjAv .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-fThZd6ecJ0NQSjAv .icon-shape p,#mermaid-svg-fThZd6ecJ0NQSjAv .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-fThZd6ecJ0NQSjAv .icon-shape .label rect,#mermaid-svg-fThZd6ecJ0NQSjAv .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-fThZd6ecJ0NQSjAv .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-fThZd6ecJ0NQSjAv .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-fThZd6ecJ0NQSjAv :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-fThZd6ecJ0NQSjAv .test>*{fill:#dcfce7!important;stroke:#16a34a!important;color:#14532b!important;}#mermaid-svg-fThZd6ecJ0NQSjAv .test span{fill:#dcfce7!important;stroke:#16a34a!important;color:#14532b!important;}#mermaid-svg-fThZd6ecJ0NQSjAv .test tspan{fill:#14532b!important;}#mermaid-svg-fThZd6ecJ0NQSjAv .pain>*{fill:#fee2e2!important;stroke:#dc2626!important;color:#7f1d1d!important;}#mermaid-svg-fThZd6ecJ0NQSjAv .pain span{fill:#fee2e2!important;stroke:#dc2626!important;color:#7f1d1d!important;}#mermaid-svg-fThZd6ecJ0NQSjAv .pain tspan{fill:#7f1d1d!important;} 稳定前缀

指令、工具、固定上下文
变化后缀

当前输入
后续请求的相同前缀
前缀任一位置变化
从变化处起无法继续精确复用

图 18-3：提示缓存依赖精确的前缀匹配。 API 应用通常把稳定内容放前面、变化内容放后面；这是一条通用优化原则，不代表 Codex 向模型发送请求时公开承诺了某种固定内部布局。

需要牢记三个边界：

  1. 缓存不等于上下文压缩：缓存复用计算，压缩减少需要保留的历史细节。
  2. 缓存不等于记忆：缓存命中不会替你保存实验结论或项目规则。
  3. 缓存不保证相同输出：它复用输入前缀的处理，不把模型变成确定性程序。

如果直接使用 OpenAI API，可以通过响应中的缓存 Token 指标观察命中情况；不要根据一次响应速度主观断言是否命中。

18.5 上下文压缩如何工作

上下文压缩（Compaction）会概括较早的上下文，使长任务能够在有限的上下文窗口内继续。Codex CLI 可以用 /compact 手动压缩，也会在需要时自动压缩。
#mermaid-svg-qC4lEye5tqrpRAiB{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-qC4lEye5tqrpRAiB .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-qC4lEye5tqrpRAiB .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-qC4lEye5tqrpRAiB .error-icon{fill:#552222;}#mermaid-svg-qC4lEye5tqrpRAiB .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-qC4lEye5tqrpRAiB .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-qC4lEye5tqrpRAiB .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-qC4lEye5tqrpRAiB .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-qC4lEye5tqrpRAiB .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-qC4lEye5tqrpRAiB .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-qC4lEye5tqrpRAiB .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-qC4lEye5tqrpRAiB .marker{fill:#333333;stroke:#333333;}#mermaid-svg-qC4lEye5tqrpRAiB .marker.cross{stroke:#333333;}#mermaid-svg-qC4lEye5tqrpRAiB svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-qC4lEye5tqrpRAiB p{margin:0;}#mermaid-svg-qC4lEye5tqrpRAiB .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-qC4lEye5tqrpRAiB .cluster-label text{fill:#333;}#mermaid-svg-qC4lEye5tqrpRAiB .cluster-label span{color:#333;}#mermaid-svg-qC4lEye5tqrpRAiB .cluster-label span p{background-color:transparent;}#mermaid-svg-qC4lEye5tqrpRAiB .label text,#mermaid-svg-qC4lEye5tqrpRAiB span{fill:#333;color:#333;}#mermaid-svg-qC4lEye5tqrpRAiB .node rect,#mermaid-svg-qC4lEye5tqrpRAiB .node circle,#mermaid-svg-qC4lEye5tqrpRAiB .node ellipse,#mermaid-svg-qC4lEye5tqrpRAiB .node polygon,#mermaid-svg-qC4lEye5tqrpRAiB .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-qC4lEye5tqrpRAiB .rough-node .label text,#mermaid-svg-qC4lEye5tqrpRAiB .node .label text,#mermaid-svg-qC4lEye5tqrpRAiB .image-shape .label,#mermaid-svg-qC4lEye5tqrpRAiB .icon-shape .label{text-anchor:middle;}#mermaid-svg-qC4lEye5tqrpRAiB .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-qC4lEye5tqrpRAiB .rough-node .label,#mermaid-svg-qC4lEye5tqrpRAiB .node .label,#mermaid-svg-qC4lEye5tqrpRAiB .image-shape .label,#mermaid-svg-qC4lEye5tqrpRAiB .icon-shape .label{text-align:center;}#mermaid-svg-qC4lEye5tqrpRAiB .node.clickable{cursor:pointer;}#mermaid-svg-qC4lEye5tqrpRAiB .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-qC4lEye5tqrpRAiB .arrowheadPath{fill:#333333;}#mermaid-svg-qC4lEye5tqrpRAiB .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-qC4lEye5tqrpRAiB .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-qC4lEye5tqrpRAiB .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-qC4lEye5tqrpRAiB .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-qC4lEye5tqrpRAiB .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-qC4lEye5tqrpRAiB .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-qC4lEye5tqrpRAiB .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-qC4lEye5tqrpRAiB .cluster text{fill:#333;}#mermaid-svg-qC4lEye5tqrpRAiB .cluster span{color:#333;}#mermaid-svg-qC4lEye5tqrpRAiB div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-qC4lEye5tqrpRAiB .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-qC4lEye5tqrpRAiB rect.text{fill:none;stroke-width:0;}#mermaid-svg-qC4lEye5tqrpRAiB .icon-shape,#mermaid-svg-qC4lEye5tqrpRAiB .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-qC4lEye5tqrpRAiB .icon-shape p,#mermaid-svg-qC4lEye5tqrpRAiB .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-qC4lEye5tqrpRAiB .icon-shape .label rect,#mermaid-svg-qC4lEye5tqrpRAiB .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-qC4lEye5tqrpRAiB .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-qC4lEye5tqrpRAiB .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-qC4lEye5tqrpRAiB :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-qC4lEye5tqrpRAiB .stage>*{fill:#dbeafe!important;stroke:#2563eb!important;color:#1e3a8a!important;}#mermaid-svg-qC4lEye5tqrpRAiB .stage span{fill:#dbeafe!important;stroke:#2563eb!important;color:#1e3a8a!important;}#mermaid-svg-qC4lEye5tqrpRAiB .stage tspan{fill:#1e3a8a!important;}#mermaid-svg-qC4lEye5tqrpRAiB .pain>*{fill:#fee2e2!important;stroke:#dc2626!important;color:#7f1d1d!important;}#mermaid-svg-qC4lEye5tqrpRAiB .pain span{fill:#fee2e2!important;stroke:#dc2626!important;color:#7f1d1d!important;}#mermaid-svg-qC4lEye5tqrpRAiB .pain tspan{fill:#7f1d1d!important;} 历史消息与工具结果持续增长
手动触发或达到自动压缩条件
压缩较早上下文
保留摘要与继续任务所需信息
后续轮次继续增长

图 18-4：压缩是长线程中的循环机制。 它不是删除线程，也不是创建 Git 工作区，更不是把全部历史无损搬进一个"新窗口"。

18.5.1 配置边界

当前配置参考包含以下相关项：

配置项 作用
model_auto_compact_token_limit 自动压缩的 Token 阈值；未设置时使用模型默认值
model_auto_compact_token_limit_scope 选择按全部活动上下文 total，还是按压缩窗口前缀之后的增长量 body_after_prefix 计数；默认 total
tool_output_token_limit 单个工具或函数输出存入历史的 Token 预算

不同模型、任务和 Codex 版本的合理阈值不同；一般先使用模型默认值，再结合 /status、任务失败模式和实际测量决定是否调整。

App Server 还提供 thread/compact/start 来触发线程压缩，进度通过标准的 turn/* 与 item/* 通知返回。若需要在压缩前后执行审计或记录，可配置 PreCompact 与 PostCompact 钩子（Hook）。

18.5.2 压缩是有损摘要

压缩应被理解为"保留继续工作所需的语义"，而不是逐字保存历史。容易丢失的通常包括：

  • 某次日志中的精确行号和完整错误文本；
  • 很早以前读取过、后来没有再次引用的文件细节；
  • 多个试验分支之间细微但重要的差异；
  • 未写入文件的临时结论和验收标准。

因此，在压缩前后都应让关键状态可恢复：

  • 把实验约束写入配置或任务说明；
  • 把阶段结论写入报告；
  • 把命令、数据版本和指标写入结构化结果；
  • 压缩后重新读取当前决策所需的源文件，而不是依赖模糊回忆。

18.6 线程的生命周期

轮次（Turn）是线程内的一次用户输入及其处理过程。线程可以保存、恢复和分叉，因此"退出 CLI"与"删除线程"不是同一件事。
#mermaid-svg-6EpXEtr38XHCdp4E{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-6EpXEtr38XHCdp4E .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-6EpXEtr38XHCdp4E .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-6EpXEtr38XHCdp4E .error-icon{fill:#552222;}#mermaid-svg-6EpXEtr38XHCdp4E .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-6EpXEtr38XHCdp4E .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-6EpXEtr38XHCdp4E .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-6EpXEtr38XHCdp4E .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-6EpXEtr38XHCdp4E .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-6EpXEtr38XHCdp4E .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-6EpXEtr38XHCdp4E .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-6EpXEtr38XHCdp4E .marker{fill:#333333;stroke:#333333;}#mermaid-svg-6EpXEtr38XHCdp4E .marker.cross{stroke:#333333;}#mermaid-svg-6EpXEtr38XHCdp4E svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-6EpXEtr38XHCdp4E p{margin:0;}#mermaid-svg-6EpXEtr38XHCdp4E .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-6EpXEtr38XHCdp4E .cluster-label text{fill:#333;}#mermaid-svg-6EpXEtr38XHCdp4E .cluster-label span{color:#333;}#mermaid-svg-6EpXEtr38XHCdp4E .cluster-label span p{background-color:transparent;}#mermaid-svg-6EpXEtr38XHCdp4E .label text,#mermaid-svg-6EpXEtr38XHCdp4E span{fill:#333;color:#333;}#mermaid-svg-6EpXEtr38XHCdp4E .node rect,#mermaid-svg-6EpXEtr38XHCdp4E .node circle,#mermaid-svg-6EpXEtr38XHCdp4E .node ellipse,#mermaid-svg-6EpXEtr38XHCdp4E .node polygon,#mermaid-svg-6EpXEtr38XHCdp4E .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-6EpXEtr38XHCdp4E .rough-node .label text,#mermaid-svg-6EpXEtr38XHCdp4E .node .label text,#mermaid-svg-6EpXEtr38XHCdp4E .image-shape .label,#mermaid-svg-6EpXEtr38XHCdp4E .icon-shape .label{text-anchor:middle;}#mermaid-svg-6EpXEtr38XHCdp4E .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-6EpXEtr38XHCdp4E .rough-node .label,#mermaid-svg-6EpXEtr38XHCdp4E .node .label,#mermaid-svg-6EpXEtr38XHCdp4E .image-shape .label,#mermaid-svg-6EpXEtr38XHCdp4E .icon-shape .label{text-align:center;}#mermaid-svg-6EpXEtr38XHCdp4E .node.clickable{cursor:pointer;}#mermaid-svg-6EpXEtr38XHCdp4E .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-6EpXEtr38XHCdp4E .arrowheadPath{fill:#333333;}#mermaid-svg-6EpXEtr38XHCdp4E .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-6EpXEtr38XHCdp4E .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-6EpXEtr38XHCdp4E .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-6EpXEtr38XHCdp4E .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-6EpXEtr38XHCdp4E .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-6EpXEtr38XHCdp4E .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-6EpXEtr38XHCdp4E .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-6EpXEtr38XHCdp4E .cluster text{fill:#333;}#mermaid-svg-6EpXEtr38XHCdp4E .cluster span{color:#333;}#mermaid-svg-6EpXEtr38XHCdp4E div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-6EpXEtr38XHCdp4E .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-6EpXEtr38XHCdp4E rect.text{fill:none;stroke-width:0;}#mermaid-svg-6EpXEtr38XHCdp4E .icon-shape,#mermaid-svg-6EpXEtr38XHCdp4E .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-6EpXEtr38XHCdp4E .icon-shape p,#mermaid-svg-6EpXEtr38XHCdp4E .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-6EpXEtr38XHCdp4E .icon-shape .label rect,#mermaid-svg-6EpXEtr38XHCdp4E .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-6EpXEtr38XHCdp4E .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-6EpXEtr38XHCdp4E .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-6EpXEtr38XHCdp4E :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-6EpXEtr38XHCdp4E .stage>*{fill:#dbeafe!important;stroke:#2563eb!important;color:#1e3a8a!important;}#mermaid-svg-6EpXEtr38XHCdp4E .stage span{fill:#dbeafe!important;stroke:#2563eb!important;color:#1e3a8a!important;}#mermaid-svg-6EpXEtr38XHCdp4E .stage tspan{fill:#1e3a8a!important;}#mermaid-svg-6EpXEtr38XHCdp4E .art>*{fill:#f1f5f9!important;stroke:#64748b!important;color:#0f172a!important;}#mermaid-svg-6EpXEtr38XHCdp4E .art span{fill:#f1f5f9!important;stroke:#64748b!important;color:#0f172a!important;}#mermaid-svg-6EpXEtr38XHCdp4E .art tspan{fill:#0f172a!important;} 继续
上下文较长
恢复已有线程
保留原历史并分支
结束管理
新建线程

/new 或 thread/start
开始轮次

turn/start
回复、工具调用与文件修改
下一步
/compact 或 thread/compact/start
/resume 或 thread/resume
/fork 或 thread/fork
归档或删除

图 18-5：线程、轮次、压缩与恢复。 App Server 的 thread/read 可以读取已存线程而不恢复它；thread/resume 则重新加载线程并允许后续轮次继续追加。

操作 作用 不会自动完成的事
/compact 概括当前聊天的早期上下文 不会提交代码或生成正式结果
/resume 恢复保存的聊天 不会重放上次中断的工具调用
/fork 从当前历史创建新聊天 不会自动创建或切换 Git 分支
/new 在同一 CLI 中开启新聊天 不会清理工作区文件
归档 将线程移出常用列表 不等于永久删除
删除 删除保存的线程记录 不等于删除项目目录

线程恢复后，首先核对工作区、运行进程和正式产物。不能仅凭历史消息断言上一次命令已经完成。

18.7 哪些信息应放在上下文之外

18.7.1 AGENTS.md：稳定的项目规则

AGENTS.md 适合记录长期有效的仓库约束，例如：

  • Python 版本与测试命令；
  • 数据目录禁止直接修改；
  • 离散类别分割掩码缩放时必须使用最近邻插值；
  • 一个实验只改变一个变量；
  • 正式结果必须写入指定文件。

它不适合保存"epoch 37 正在运行"之类的瞬时状态。运行状态应写入日志、状态文件或实验管理系统。

18.7.2 记忆：可复用偏好，不是事实数据库

启用并适用时，记忆（Memory）可以在不同会话间复用用户偏好和工作约定，例如默认使用 UTF-8、报告采用某种结构。记忆可能过期，也可能不适用于当前目录；关键配置、数据版本和实验结果仍应以仓库文件和正式产物为准。

18.7.3 工作树：隔离文件修改

Git 工作树（Worktree）让不同任务在独立目录中修改同一仓库，适合并行开发。它解决的是文件冲突和分支隔离，不负责扩大上下文窗口，也不替代线程。

18.7.4 目标：线程内的完成契约

目标（Goal）适合为长任务保存明确的完成条件。它属于当前线程的持久状态，不是全局记忆；恢复同一线程后可以继续依据该目标工作。目标也不会放宽沙箱或审批策略。

例如，一个检测任务的目标可以写成：

修复 COCO 类别映射；保持权重、图像尺寸、NMS 和评测集不变；通过单元测试、100 张图冒烟评测和完整评测；生成 formal_result.json 后才算完成。

18.8 长任务案例：修复 YOLO 的 COCO 类别映射

下面用一个可复现的视觉算法任务说明如何管理上下文，而不是依赖"超长对话"。

18.8.1 先定义实验契约

项目 约束
父版本 当前通过回归测试的提交
唯一变量 COCO 类别映射逻辑
固定项 权重、输入尺寸、NMS、数据清单、评测脚本版本
快速门槛 单元测试通过；100 张图无索引越界或类别错位
完整门槛 完整 COCO 评测完成，指标文件结构合法
正式产物 formal_result.json、配置、数据清单和 Git diff

18.8.2 分阶段推进

#mermaid-svg-nbeZX4HwjkUe5YQp{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-nbeZX4HwjkUe5YQp .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-nbeZX4HwjkUe5YQp .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-nbeZX4HwjkUe5YQp .error-icon{fill:#552222;}#mermaid-svg-nbeZX4HwjkUe5YQp .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-nbeZX4HwjkUe5YQp .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-nbeZX4HwjkUe5YQp .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-nbeZX4HwjkUe5YQp .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-nbeZX4HwjkUe5YQp .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-nbeZX4HwjkUe5YQp .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-nbeZX4HwjkUe5YQp .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-nbeZX4HwjkUe5YQp .marker{fill:#333333;stroke:#333333;}#mermaid-svg-nbeZX4HwjkUe5YQp .marker.cross{stroke:#333333;}#mermaid-svg-nbeZX4HwjkUe5YQp svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-nbeZX4HwjkUe5YQp p{margin:0;}#mermaid-svg-nbeZX4HwjkUe5YQp .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-nbeZX4HwjkUe5YQp .cluster-label text{fill:#333;}#mermaid-svg-nbeZX4HwjkUe5YQp .cluster-label span{color:#333;}#mermaid-svg-nbeZX4HwjkUe5YQp .cluster-label span p{background-color:transparent;}#mermaid-svg-nbeZX4HwjkUe5YQp .label text,#mermaid-svg-nbeZX4HwjkUe5YQp span{fill:#333;color:#333;}#mermaid-svg-nbeZX4HwjkUe5YQp .node rect,#mermaid-svg-nbeZX4HwjkUe5YQp .node circle,#mermaid-svg-nbeZX4HwjkUe5YQp .node ellipse,#mermaid-svg-nbeZX4HwjkUe5YQp .node polygon,#mermaid-svg-nbeZX4HwjkUe5YQp .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-nbeZX4HwjkUe5YQp .rough-node .label text,#mermaid-svg-nbeZX4HwjkUe5YQp .node .label text,#mermaid-svg-nbeZX4HwjkUe5YQp .image-shape .label,#mermaid-svg-nbeZX4HwjkUe5YQp .icon-shape .label{text-anchor:middle;}#mermaid-svg-nbeZX4HwjkUe5YQp .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-nbeZX4HwjkUe5YQp .rough-node .label,#mermaid-svg-nbeZX4HwjkUe5YQp .node .label,#mermaid-svg-nbeZX4HwjkUe5YQp .image-shape .label,#mermaid-svg-nbeZX4HwjkUe5YQp .icon-shape .label{text-align:center;}#mermaid-svg-nbeZX4HwjkUe5YQp .node.clickable{cursor:pointer;}#mermaid-svg-nbeZX4HwjkUe5YQp .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-nbeZX4HwjkUe5YQp .arrowheadPath{fill:#333333;}#mermaid-svg-nbeZX4HwjkUe5YQp .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-nbeZX4HwjkUe5YQp .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-nbeZX4HwjkUe5YQp .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-nbeZX4HwjkUe5YQp .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-nbeZX4HwjkUe5YQp .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-nbeZX4HwjkUe5YQp .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-nbeZX4HwjkUe5YQp .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-nbeZX4HwjkUe5YQp .cluster text{fill:#333;}#mermaid-svg-nbeZX4HwjkUe5YQp .cluster span{color:#333;}#mermaid-svg-nbeZX4HwjkUe5YQp div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-nbeZX4HwjkUe5YQp .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-nbeZX4HwjkUe5YQp rect.text{fill:none;stroke-width:0;}#mermaid-svg-nbeZX4HwjkUe5YQp .icon-shape,#mermaid-svg-nbeZX4HwjkUe5YQp .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-nbeZX4HwjkUe5YQp .icon-shape p,#mermaid-svg-nbeZX4HwjkUe5YQp .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-nbeZX4HwjkUe5YQp .icon-shape .label rect,#mermaid-svg-nbeZX4HwjkUe5YQp .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-nbeZX4HwjkUe5YQp .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-nbeZX4HwjkUe5YQp .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-nbeZX4HwjkUe5YQp :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-nbeZX4HwjkUe5YQp .stage>*{fill:#dbeafe!important;stroke:#2563eb!important;color:#1e3a8a!important;}#mermaid-svg-nbeZX4HwjkUe5YQp .stage span{fill:#dbeafe!important;stroke:#2563eb!important;color:#1e3a8a!important;}#mermaid-svg-nbeZX4HwjkUe5YQp .stage tspan{fill:#1e3a8a!important;}#mermaid-svg-nbeZX4HwjkUe5YQp .test>*{fill:#dcfce7!important;stroke:#16a34a!important;color:#14532b!important;}#mermaid-svg-nbeZX4HwjkUe5YQp .test span{fill:#dcfce7!important;stroke:#16a34a!important;color:#14532b!important;}#mermaid-svg-nbeZX4HwjkUe5YQp .test tspan{fill:#14532b!important;}#mermaid-svg-nbeZX4HwjkUe5YQp .pain>*{fill:#fee2e2!important;stroke:#dc2626!important;color:#7f1d1d!important;}#mermaid-svg-nbeZX4HwjkUe5YQp .pain span{fill:#fee2e2!important;stroke:#dc2626!important;color:#7f1d1d!important;}#mermaid-svg-nbeZX4HwjkUe5YQp .pain tspan{fill:#7f1d1d!important;} 否
是
否
是
固定父版本、数据清单与验收标准
定位类别表与索引转换链路
做最小代码修改
运行单元测试
测试通过？
运行 100 张图冒烟评测
映射和输出正常？
运行完整 COCO 评测
校验并生成正式产物

图 18-6：长任务通过阶段门槛和产物保持连续性。 即使中途发生压缩或恢复，也可以从配置、Git diff、日志和结果文件重建当前状态。

18.8.3 分类与分割任务同样适用

  • 图像分类：把类别顺序、预处理参数和混淆矩阵路径写入产物，避免恢复线程后误用标签顺序。
  • 语义分割：把掩码插值方式、忽略标签和裁剪规则写入配置，不能只在早期对话中提过一次。
  • 目标检测：把置信度阈值、NMS、类别映射和数据版本固定下来，否则前后指标不可比。

18.8.4 何时使用子代理

子代理工作流（Subagent Workflow）适合相互独立、以读取和分析为主的任务。例如：

  • 一个子代理只核对 COCO 类别定义；
  • 一个子代理只检查评测脚本；
  • 主代理汇总结论并做唯一的代码修改。

子代理拥有独立线程，返回的是摘要，不是与主线程共享同一份无限上下文。并行写同一文件容易产生冲突，因此应明确文件所有权，或者让子代理只读分析、由主代理统一修改。

18.9 实用操作清单

开始任务前

  • 明确单一目标、固定条件和完成定义（Definition of Done）。
  • 指明相关文件、复现命令和预期输出。
  • 把长期规则放入 AGENTS.md，把本次实验设置放入配置文件。
  • 为独立交付目标使用独立线程；需要隔离代码修改时再使用工作树。

执行过程中

  • 先搜索再读取，优先截取日志中的关键区段。
  • 每个阶段都落盘：配置、命令、指标、结论和时间戳。
  • 用 /status 观察当前会话状态；聊天过长时可使用 /compact。
  • 压缩后重新读取关键文件，并核对当前 Git diff 与运行状态。
  • 用户需要改变正在执行的方向时，优先使用转向（Steering），不要假设已经执行的工具调用会自动撤销。

结束任务前

  • 运行约定的测试，而不是只检查代码看起来是否合理。
  • 检查正式产物及其结构，不以进程退出或局部指标代替完成。
  • 报告修改文件、验证命令、结果和仍未解决的风险。
  • 需要继续同一任务时保存并恢复原线程；要探索替代方案时使用分叉。

18.10 本章小结

Codex 的上下文管理可以归纳为五条原则：

  1. 上下文只是本轮可见信息，不是线程、记忆或文件系统的同义词。
  2. 相关性比数量重要，精确文件、约束和验收标准优于大段无关材料。
  3. 提示缓存优化计算复用，不能替代上下文压缩、记忆或正式产物。
  4. 压缩延长线程可用性，但会损失细节，关键状态必须写入可验证文件。
  5. 长任务靠契约、阶段门槛和产物连续推进，而不是依赖模型始终记住全部历史。

对视觉算法工程师而言，最实用的做法是：把检测、分类或分割任务的变量、数据、指标和完成条件写入仓库，让 Codex 随时能够重新读取、验证并继续工作。

参考资料

上一章：第十七章 Codex 架构对比：会话、线程、子代理与并行工作

相关推荐
在世修行13 小时前
多线程取流与线程同步：工业上位机的并发艺术
线程·线程同步·线程锁
进阶的小名14 小时前
Spring AI 2.0 探索：多 OpenAI-Compatible 模型接入，以及下一代 Session 记忆管理
java·人工智能·后端·gpt·spring·ai·chatgpt
玫瑰互动GEO14 小时前
海外GEO优化案例-ChatGPT搜索关键词排名GEO优化案例详解（含RAG机制与Tokenization技术拆解）
人工智能·ai·chatgpt·geo优化
AI模型调用笔记16 小时前
GPT-5.4 8月31日退出 Codex？先分清 ChatGPT 登录与 API Key，再迁移 Terra/Luna
人工智能·gpt·chatgpt·ai编程
前进的程序员18 小时前
Codex破局：前端组件秒级生成｜提速React/Vue开发，可复用提示词+实战调试经验
前端·vue.js·react.js·codex
AIHR数智引擎20 小时前
如何用WorkBuddy跑通HR自动化流程？
人工智能·经验分享·chatgpt·职场和发展·自动化·ai-native
yingyuecom21 小时前
映悦AI × Joverse全球发布：四大重磅更新，AI创作进入工业化时代
人工智能·gpt·chatgpt·prompt·aigc
wujian83111 天前
【 文心手机版生成的表格怎么复制下来 】？这个问题，[ AI 导出鸭 ] 给出了完全不同的答案
人工智能·ai·chatgpt·智能手机·ai导出鸭
CodeBlog-star1 天前
Codex Harness 全面开源：OpenAI的 AI Agent 底层执行框架
人工智能·开源·openai·codex·harness
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点032026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？04微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新05Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费06历年考研数学一、数学二、数学三真题试卷及答案PDF07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路082026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片09VSCode+CodeX扩展，无法启动10如何新建文件夹？ 电脑新建文件夹的4种方法