❌ 常见误区：把时间戳放在第一行#

很多开发者觉得在 System Prompt 第一行告知模型当前时间是很严谨的：

1
[System Message]
2
Current Time: 2026-01-25 10:00:01  <-- 这一秒在变，导致此行之后的所有缓存每秒都在失效！
3
Role: You are a helpful assistant...

后果

Prompt Caching 的核心是前缀匹配（Prefix Matching）。缓存是按顺序存储的，一旦开头的 Token 变了，其后所有内容的 KV Cache（Key-Value Cache）都会失效。

这就像你去图书馆借书，虽然人没变，但每次你都换了一张不同号码的身份证。图书管理员系统无法识别你是“老用户”，必须把你当作全新用户重新录入资料，导致首字延迟（TTFT）大幅增加。

✅ 优化方案：动态信息沉底#

将时间戳、Request ID 等高度动态的信息，移到 Context 的最底部，或者放在 User Message 中，让 System Prompt 的头部保持绝对静止。

场景分析#

当 Agent 运行中途，环境发生变化（例如用户将权限从“只读”改为“可写”）。

❌ 错误做法：修改原始定义#

• 修改前： System: [Sandbox: Read-Only] … (后接 5000 token 历史)
• 修改后： System: [Sandbox: Write-Allowed] … (后接 5000 token 历史)

技术后果： 修改开头意味着破坏前缀。GPU 必须重新计算这 5000 个 Token 的 KV 向量（Prefill 阶段），这涉及大量的矩阵乘法运算，带来显著延迟。

✅ 正确做法：追加补充协议#

• 保持开头： System: [Sandbox: Read-Only] (保持不变，骗过缓存机制)
• …中间的对话历史…
• 追加结尾： System: [Update: User has approved Write Access.]

原理解析

这避免了对历史 Token 进行昂贵的 Prefill（前处理） 计算。

虽然新生成的 Token 依然需要去“关注（Attention）”所有的历史信息（这依然消耗显存带宽），但我们跳过了最耗时的历史 Token 的特征提取与投影计算。

• 收益： 大幅降低 Time to First Token (TTFT)。
• 代价： Context 长度缓慢增加，直到触发窗口限制（见法则五）。

比喻

就像签署商业合同，不要因为条款变更就撕毁合同重签（Cache Miss，很贵），而是在合同最后钉上一页 “补充协议”（Cache Hit，很便宜）。模型完全有能力理解“后文覆盖前文”的逻辑。

❌ 错误案例：随机的工具列表#

• 请求 A: Tools: [Shell, Search]
• 请求 B: Tools: [Search, Shell]

这会导致莫名其妙的 Cache Miss。

✅ 优化方案：强制确定性排序#

1. 工具列表排序： 始终按字母顺序（A-Z）排列工具定义。
2. JSON 序列化： 确保 JSON 对象在转为字符串时，Key 的顺序是固定的（许多语言的 Map 是无序的，需要专门处理）。

场景 A：外部工具 (Isolation)#

Codex 将工具分为“内置工具”（如 Shell，定义稳定）和“外部工具”（如 MCP 协议插件）。如果引入了外部工具，其 Schema 可能随时变化。
策略： 将这些不稳定的内容与核心 System Prompt 隔离。一旦外部配置变更，尽量通过追加说明而非重构上下文来处理。

场景 B：环境变更 (Patching)#

用户执行了 cd /var/www，导致当前工作目录（CWD）改变。

• ❌ 错误： 回去修改 System Prompt 中的 <cwd> 标签。
• ✅ 正确： 在对话流中插入一条事件消息：User executed cd. CWD is now /var/www.

工程权衡 Trade-off

这种“打补丁”的方式依赖于模型能够理解“后文覆盖前文”的逻辑。现代强模型通常能处理得很好，但对于极长上下文，模型可能会出现“遗忘”或“幻觉”。这是一种为了性能而在准确性边缘试探的策略。

第一阶段：朴素的摘要机制 (The Naive Approach)#

我们可以设计一个机制，将上述操作总结为：

“Read main.py from line 1 to 300.”

并提供一个 expand 工具，允许模型在需要时查看详情。

但在实战中，我发现这个方案有一个致命缺陷： 当 Agent 后续需要“展开”这段记忆时，系统会机械地把 1-300 行代码全部塞回 Context。这意味着，我们刚刚费力扔出去的 1-250 行噪音（Noise），又被模型自己捡回来了。这不仅浪费 Token，更会用无关代码干扰模型的注意力。

第二阶段：基于“价值过滤”的高精度折叠 (Value Filtering)#

为了解决这个问题，我意识到：压缩不仅仅是变短，更是一次信息清洗。 我们需要在生成 Summary 的阶段，就将“沙子”和“金子”分离开。

优化后的 Context 结构：

当子任务完成时，我们要求 LLM 总结操作，并明确区分 “已读但无用（Discarded）” 和 “已读且有用（Retained）” 的部分。

1
[System Event: Context Compressed]
2
- Processed `main.py` (Lines 1-300):
3
  - Lines 1-250: Discarded (Irrelevant boilerplate).
4
  - Lines 251-300: **Retained**. Contains `init_db_connection` logic. (ID: ref_m1_valid)
5
**NOTE**
6
Context is compressed. Use `expand_context(ids=['ref_m1_valid'])` to view ONLY the relevant code snippets.
7
:::

设计亮点：

1. 高召回率 (High Recall)： 明确记录 1-250 行“被丢弃了”。这告诉模型“那部分我看过了，没用”，防止模型因不知道读过而重新去读。
2. 高精确度 (High Precision)： ID: ref_m1_valid 并不指向 1-300 行的原始记录，而是指向 经过裁剪的 251-300 行切片。

1. 批量懒加载工具 (Batch Expansion Tool)#

为了减少交互轮次，工具应当支持批量操作。

1
{
2
  name: "expand_context",
3
  description: "Expand the RELEVANT details of compressed logs.",
4
  parameters: {
5
    ids: {
6
      type: "array",
7
      items: { type: "string" },
8
      description: "List of IDs to expand. Note: This will only expand the useful code snippets retained during compression."
9
    }
10
  }
11
}

2. 展开策略：只返回“黄金切片” (应用法则二与四)#

当模型调用 expand_context(ids=["ref_m1_valid"]) 时，系统只会返回之前被标记为“有用”的那 50 行代码。

且为了遵守 法则二（追加优于修改），我们不修改历史摘要，而是将内容追加到对话末尾：

1
... (前面是压缩后的摘要，作为静态地基，保持不动) ...
2

3
[Current Turn]
4
User: I need to fix the db connection bug found in main.py.
5
Agent: Call tool `expand_context(ids=["ref_m1_valid"])`
6
System: [Tool Output] Expanding relevant snippets:
7
1. `main.py` (ref_m1_valid, lines 251-300):
8
   "def init_db_connection():
9
      # ... Only the 50 relevant lines are shown here ...
10
   "

通过这种方式，我们既保留了完整的探索路径（我知道我读过哪），又实现了上下文的极致精简（我只展开有用的）。