---
name: context-optimization
description: 该技能应用于提升上下文效率：上下文预算管理、观察遮蔽、前缀或 KV 缓存策略、分区、令牌成本降低、检索范围限定，以及在不降低回答质量的前提下扩展有效上下文容量。
---

# 上下文优化技术

上下文优化通过战略性压缩、遮蔽、缓存和分区，扩展有限上下文窗口的有效容量。有效的优化能在不依赖更大模型或更长窗口的前提下提升有用容量——但前提是必须基于度量纪律进行应用。以下技术按影响程度和风险排序。

## 何时激活

在以下情形中激活此技能：
- 上下文预算或令牌成本限制了任务复杂度
- 观察遮蔽可将冗长的工具输出替换为可检索的引用
- 前缀或 KV 缓存命中率需要提升
- 检索范围限定可减少不相关的已加载上下文
- 上下文分区可跨代理扩展有效容量
- 需要预算触发器来执行遮蔽、压缩或分区

对于由其他技能负责的相邻工作，请勿激活此技能：
- 解释注意力机制或上下文窗口为何如此表现：`context-fundamentals`
- 诊断活跃的中间丢失、投毒、干扰、混淆或冲突：`context-degradation`
- 为长对话设计结构化的交接摘要：`context-compression`
- 将大型输出、计划或日志存储为文件：`filesystem-context`

## 核心概念

按以下优先级应用四种主要策略：

1. **KV 缓存优化**——重新排序并稳定提示结构，使推理引擎能重用缓存的 Key/Value 张量。当运行时支持前缀缓存时，这是成本最低的优化：质量风险低，能立即节省成本和延迟。当存在稳定前缀时优先应用。

2. **观察遮蔽**——一旦冗长工具输出的目的已完成，将其替换为紧凑引用。工具输出可能主导代理轨迹（claim-context-optimization-tool-output-dominance），因此遮蔽通常能带来最大的容量收益。若下游需要，原始内容仍可检索。

3. **压缩**——当上下文利用率超过 70% 时，对累积的上下文进行总结，然后用总结重新初始化。这能提炼窗口内容，同时保留任务关键状态。压缩是有损的——应在遮蔽已移除低价值主体后再进行。

4. **上下文分区**——当单个窗口无法容纳完整问题时，将工作拆分为多个具有隔离上下文的子代理。每个子代理在其专注于子任务的干净上下文中运行。当预计上下文超过窗口限制的 60% 时保留此策略，因为协调开销是实际存在的。

基本原则：上下文质量比数量更重要。每一次优化都应在保留信号的同时减少噪声。优化前先度量，再度量优化的效果。

## 详细主题

### 压缩策略

当上下文利用率超过 70% 时触发压缩：总结当前上下文，然后用总结重新初始化。这能以高保真的方式提炼窗口内容，使后续执行能以最小的性能降级继续。优先压缩工具输出（它们消耗 80% 以上的令牌），然后是旧的对话轮次，最后是检索到的文档。切勿压缩系统提示——它锚定模型行为，移除它会导致不可预测的性能下降。

按消息类型保留不同元素：

- **工具输出**：提取关键发现、指标、错误代码和结论。剔除冗长的原始输出、堆栈跟踪（除非正在调试）和样板式页眉/页脚。
- **对话轮次**：保留决策、承诺、用户偏好和上下文转变。移除填充内容、客套话以及已导向已记录结论的探索性来回对话。
- **检索到的文档**：保留与当前任务相关的声明、事实和数据点。移除仅用于一次性推理目的的支持性证据和详细阐述。

目标是将令牌减少 50-70%，质量下降不超过 5%。如果压缩幅度超过 70%，请检查摘要是否存在关键信息丢失——过度压缩是最常见的失败模式。

### 观察遮蔽

根据时效性和持续相关性有选择地遮蔽观察，而非统一处理。应用以下规则：

- **从不遮蔽**：对当前任务至关重要的观察、最近一轮的观察、活跃推理链中使用的观察，以及调试进行中的错误输出。
- **3 轮后遮蔽**：关键点已被提取到对话流中的冗长输出。替换为紧凑引用：`[Obs:{ref_id} 已省略。要点：{summary}。完整内容可检索。]`
- **始终立即遮蔽**：重复/重复输出、样板式页眉和页脚、已在对话早期总结过的输出。

遮蔽应使被遮蔽的观察减少 60-80%，质量影响低于 2%。关键是要保持可检索性——将完整内容存储在外部，并在上下文中保留引用 ID，以便代理在需要时能请求原始内容。

### KV 缓存优化

通过构建提示结构使稳定内容占据前缀、动态内容出现在末尾，最大化前缀缓存命中率。KV 缓存存储推理过程中计算的 Key 和 Value 张量；当连续请求共享相同前缀时，会重用缓存的张量，从而节省成本和延迟。

在每个提示中应用此顺序：
1. 系统提示（最稳定——在会话内从不改变）
2. 工具定义（跨请求稳定）
3. 频繁重用的模板和少量示例
4. 对话历史（不断增长，但与前几轮共享前缀）
5. 当前查询和动态内容（最不稳定——始终放在最后）

设计提示以获得缓存稳定性：从系统提示中移除时间戳、会话计数器和请求 ID。将动态元数据移入单独的用户消息或工具结果中，使其不会破坏前缀。前缀中哪怕一个空白字符的变化都会使该变化之后的所有缓存块失效。

对于稳定工作负载，目标缓存命中率达到 70% 以上。在规模应用下，这相当于缓存令牌的成本降低 50% 以上、延迟降低 40% 以上。

### 上下文分区

当单个上下文无法容纳完整问题且会触发激进压缩时，将工作分区到多个子代理。每个子代理在其专注于子任务的干净、聚焦的上下文中运行，然后将结构化结果返回给协调代理。

当预计任务上下文超过窗口限制的 60% 时，规划分区。将任务分解为独立的子任务，分配给各个子代理，并汇总结果。验证所有分区是否已完成，合并兼容的结果，如果聚合输出仍超出预算则应用摘要。

这种方法实现了关注点分离——详细的搜索上下文隔离在子代理内部，而协调器专注于综合。然而，协调有实际的令牌成本：协调器提示、结果聚合和错误处理都会消耗令牌。仅在节省的成本超过此开销时才进行分区。

### 预算管理

在会话开始前，为上下文类别分配明确的令牌预算：系统提示、工具定义、检索到的文档、消息历史、工具输出以及预留缓冲区（占总量的 5-10%）。持续监控各分类的使用情况与预算的对比，并在任一分类超出其分配或总利用率超过 70% 时触发优化。

使用基于触发器的优化而非定期优化。监控以下信号：
- 令牌利用率超过 80%——触发压缩
- 注意力退化指标（重复、遗漏指令）——触发遮蔽 + 压缩
- 质量评分低于基准——在优化前审计上下文组成

## 实践指导

### 优化决策框架

根据主导上下文的因素选择优化技术：

| 上下文组成 | 首要操作 | 次要操作 |
|---|---|---|
| 工具输出占主导（>50%） | 观察遮蔽 | 压缩剩余轮次 |
| 检索到的文档占主导 | 摘要 | 如果文档相互独立则分区 |
| 消息历史占主导 | 选择性保留的压缩 | 为新子任务分区 |
| 多个组件共同贡献 | 先做 KV 缓存优化，然后分层使用遮蔽 + 压缩 |
| 接近限制且正在调试 | 仅遮蔽已解决的工具输出——保留错误详情 |

### 性能目标

跟踪以下指标以验证优化效果：

- **压缩**：令牌减少 50-70%，质量下降 <5%，压缩步骤本身带来的延迟开销 <10%
- **遮蔽**：被遮蔽的观察减少 60-80%，质量影响 <2%，延迟开销接近为零
- **缓存优化**：稳定工作负载命中率 70% 以上，成本降低 50% 以上，延迟降低 40% 以上
- **分区**：扣除协调器开销后的净令牌节省；通常需要 3 个以上子任务才能达到盈亏平衡

根据度量结果迭代策略。如果某项优化技术未能可衡量地改善目标指标，则将其移除——优化机制本身也会消耗令牌并增加延迟。

## 示例

**示例 1：压缩触发**
```python
if context_tokens / context_limit > 0.8:
    context = compact_context(context)
```

**示例 2：观察遮蔽**
```python
if len(observation) > max_length:
    ref_id = store_observation(observation)
    return f"[Obs:{ref_id} 已省略。要点：{extract_key(observation)}]"
```

**示例 3：缓存友好排序**
```python
# 稳定内容在前
context = [system_prompt, tool_definitions]  # 可缓存
context += [reused_templates]  # 可重用
context += [unique_content]  # 唯一内容
```

**示例 4：预算触发的优化策略**
```yaml
budgets:
  tool_outputs: 35%
  message_history: 30%
  retrieved_documents: 20%
  reserved_buffer: 15%
triggers:
  tool_outputs_over_budget: 遮蔽已解决的观察
  total_context_over_70_percent: 压缩消息历史
  repeated_irrelevant_retrievals: 收紧检索范围
```

## 指南

1. 优化前先度量——了解当前状态
2. 先遮蔽再压缩——先移除低价值主体，再总结剩余内容
3. 通过一致的提示设计实现缓存稳定性
4. 在上下文变得有问题之前进行分区
5. 持续监控优化效果
6. 在令牌节省与质量保持之间取得平衡
7. 在生产规模下测试优化
8. 为边缘情况实现优雅降级

## 陷阱

1. **空白字符会破坏 KV 缓存**：提示前缀中哪怕一个空白字符或换行符的变化，都会使该点之后的所有 KV 缓存块失效。将系统提示固定为不可变字符串——不要向其中插入时间戳、版本号或会话 ID。在部署之间按字节比对提示模板。

2. **系统提示中的时间戳会破坏缓存命中率**：在系统提示中包含 `Current date: {today}` 或类似动态内容，会迫使每个新的一天（如果使用时间更细粒度，则是每个请求）都发生完全的缓存未命中。将动态元数据移入用户消息或附加在稳定前缀之后的单独工具结果中。

3. **压力下的压缩会丢失关键状态**：当执行压缩的模型本身处于上下文压力之下（利用率 >85%）时，其摘要质量会下降——它会遗漏任务目标、丢弃用户约束、将细微的状态扁平化。在 70-80% 时触发压缩，而非 90% 以上。如果必须在晚期进行压缩，请使用单独的模型调用，并提供一个仅包含待总结材料的干净上下文。

4. **遮蔽错误输出会破坏调试循环**：过度激进的遮蔽会隐藏代理在后续轮次诊断和修复问题所需的错误消息、堆栈跟踪和失败详情。在活跃调试期间（最近 3 轮内有错误），暂停对所有错误相关观察的遮蔽，直到问题解决。

5. **分区开销可能超过节省**：每个子代理需要自己的系统提示、工具定义和协调消息。对于少于 3 个独立子任务的任务，协调开销通常超过上下文节省。在决定分区前，估算总令牌数（协调器 + 所有子代理）。

6. **部署变更后的缓存未命中成本激增**：在部署之间重新排序工具、修改系统提示或更改少量示例，会使整个前缀缓存失效，导致成本暂时激增 2-5 倍，直到新缓存预热完成。逐步推出提示变更，并在部署窗口期间监控缓存命中率。

7. **压缩会造成对过期摘要的错误自信**：上下文一旦被压缩，摘要看起来具有权威性，但可能反映的是过时的状态。如果自压缩以来任务已发生变化（新的用户需求、修正的假设），摘要会默默携带过时信息。压缩后，在继续之前重新验证摘要与当前任务目标的一致性。

## 集成

此技能负责令牌效率策略和预算策略。相邻技能负责诊断、存储和架构：

- `context-fundamentals`：解释为什么上下文质量和注意力位置很重要的心智模型。
- `context-degradation`：在输出质量已下降时进行诊断。
- `context-compression`：有损摘要和交接策略。
- `filesystem-context`：基于文件的后台卸载，用于完整输出和日志。
- `multi-agent-patterns`：跨隔离代理上下文进行工作分区。
- `latent-briefing`：在兼容运行时中跨编排器-工作者边界的选择性 KV 保留。
- `evaluation`：衡量优化是否改善了质量、成本或延迟。
- `memory-systems`：为上下文提供即时检索的持久化检索层。

## 参考资料

内部参考：
- [优化技术参考](./references/optimization_techniques.md)——何时阅读：在实现特定优化技术且需要技能主体未提供的详细代码模式、阈值表或集成示例时。

本集合中的相关技能：
- context-fundamentals——何时阅读：不熟悉上下文窗口机制、令牌计数或注意力分布基础知识时。
- context-degradation——何时阅读：诊断代理性能为何下降，需要在选择优化方案前识别正在发生的退化模式时。
- evaluation——何时阅读：设置指标和基准来衡量某项优化技术是否确实改善了结果时。

外部资源：
- 上下文窗口限制研究——何时阅读：评估模型特定的上下文行为（例如中间丢失效应、注意力衰减曲线）时。
- KV 缓存优化技术——何时阅读：在推理基础设施层面（vLLM、TGI 或云提供商 API）实现前缀缓存时。
- 生产工程指南——何时阅读：在生产管道中部署上下文优化，需要可运维模式（监控、告警、回滚）时。

---

## 技能元数据

**创建日期**：2025-12-20
**最后更新**：2026-05-15
**作者**：Agent Skills for Context Engineering Contributors
**版本**：2.1.0