context-optimization

上下文优化技术

上下文优化通过压缩、屏蔽、缓存和分区来扩展有限上下文窗口的有效容量，并以严谨的测量作为保障。以下技术按影响和风险排序。

何时启用

• 上下文预算或令牌成本限制了任务复杂度
• 观察屏蔽可以用可检索的引用替代冗长的工具输出
• 需要提高前缀或 KV 缓存命中率
• 检索范围限定可以减少加载的无关上下文
• 上下文分区可以扩展多个 Agent 间的有效容量
• 需要设置预算触发条件，以便进行屏蔽、压缩或分区
• 随着上下文变长，Agent 的质量下降，或输出无明显原因地出错或偏离主题（诊断模式）

模式

模式	适用情况	阅读
优化（默认）	令牌成本或预算限制了任务，且上下文运行正常	本文件，然后阅读 references/optimization_techniques.md
诊断	质量已经下降：中间信息丢失、污染、分心、混淆或冲突	references/degradation.md，然后阅读 references/degradation-patterns.md 了解检测代码和恢复方法
说明	了解上下文机制，且当前没有故障	references/fundamentals.md

优化出现故障的 Agent 之前，先进行诊断：对受到污染或存在冲突的上下文进行压缩或屏蔽，会让错误延续下去。首先确认提示词在较短的上下文长度下能正常工作（如果在 2K 个令牌下就失败，问题出在提示词），然后根据症状匹配模式并采取首要措施：

模式	典型症状	首要措施	优化策略
中间信息丢失	忽略上下文中的正确信息；忘记早期指令	将关键内容移到开头或结尾；在开头添加摘要	压缩时将关键发现保留在两端
污染	更正后错误说法仍然存在；工具使用不当	截断到错误说法之前，只重新加载已验证的来源	使用干净的分区重新开始
分心	加载额外文档后质量下降	加载前筛选检索结果；通过工具调用获取参考资料	限定检索范围、屏蔽观察结果
混淆	其他任务的约束或工具信息混入当前任务	将任务拆分到不同的上下文中	上下文分区
冲突	相互矛盾的来源导致答案不可预测	设置来源优先级，并在加载前剔除过时版本	限定检索范围

应在模型特定的退化起点远早于出现症状时触发压缩（约为已知起点的 70%），而不要等到症状出现后再处理。

核心概念

按以下优先顺序采用四种主要策略：

1. KV 缓存优化 — 重新排列并稳定提示词结构，让推理引擎能够复用已缓存的 Key/Value 张量。当运行时支持前缀缓存时，这是成本最低的优化：质量风险低，并能立即降低成本和延迟。存在稳定前缀时，应优先采用此策略。

2. 观察内容屏蔽 — 在工具输出完成其用途后，将冗长的工具输出替换为精简引用。工具输出可能占据 Agent 执行轨迹的大部分内容（claim-context-optimization-tool-output-dominance），因此屏蔽通常能带来最大的容量提升。如有需要，下游仍可检索原始内容。

3. 上下文压缩 — 在模型实测性能开始下降的节点约 70% 处（而不是上下文窗口总长度的 70%）总结累积的上下文，然后用摘要重新初始化。这能提炼窗口中的内容，同时保留任务关键状态。压缩会造成信息损失，因此应在屏蔽已移除低价值的大量内容后再进行。

4. 上下文分区 — 当单个窗口无法容纳完整问题时，将工作拆分给拥有独立上下文的子 Agent。每个子 Agent 都在干净的上下文中专注于其子任务。仅在预计上下文超过窗口限制的 60% 时采用此策略，因为协调开销不可忽视。

基本原则是：上下文质量比数量更重要。每项优化都应在降低噪声的同时保留有效信息。优化前先测量，再测量优化带来的效果。

详细主题

压缩策略

在实测性能开始下降的节点约 70% 处触发压缩（若性能在窗口占用率 60% 时开始下降，则约为 42% 的占用率）：总结当前上下文，然后用摘要重新初始化。这样能高保真地提炼窗口中的内容，使任务得以继续，同时将性能下降降至最低。优先压缩工具输出（它们占用 80% 以上的 Token），然后是较早的对话轮次，最后是检索到的文档。切勿压缩系统提示词 — 它是模型行为的锚点，移除它会导致不可预测的性能下降。

按消息类型保留不同内容：

• 工具输出：提取关键发现、指标、错误代码和结论。删除冗长的原始输出、堆栈跟踪（除非仍在调试）以及模板化标题。
• 对话轮次：保留决策、承诺、用户偏好和上下文变化。删除填充内容、客套话，以及已得出结论且结论已被记录的探索性往复讨论。
• 检索到的文档：保留与当前任务相关的主张、事实和数据点。删除仅在一次推理中起辅助作用的证据和展开说明。

目标是将 Token 减少 50-70%，同时质量下降低于 5%。如果压缩幅度超过 70%，应检查摘要是否丢失关键信息 — 过度压缩是最常见的失败模式。

观察内容屏蔽

应根据观察内容的新近程度和当前相关性选择性地屏蔽，而非一概而论。遵循以下规则：

• 绝不屏蔽：对当前任务至关重要的观察内容、最近一轮的观察内容、正在进行的推理链中使用的观察内容，以及调试过程中产生的错误输出。
• 经过 3 轮或以上后屏蔽：关键点已提取到对话流程中的冗长输出。将其替换为精简引用：[Obs:{ref_id} elided. Key: {summary}. Full content retrievable.]
• 始终立即屏蔽：重复或重复出现的输出、模板化页眉和页脚，以及在对话前文中已总结过的输出。

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

KV-Cache 优化

通过调整提示词结构，让稳定内容位于前缀，动态内容放在末尾，从而最大限度地提高前缀缓存命中率。KV-cache 会存储推理过程中计算出的 Key 和 Value 张量；当连续请求共享相同前缀时，会复用缓存的张量，从而节省成本和延迟。

在每个提示词中按以下顺序排列：

1. 系统提示词（最稳定——在会话期间不会改变）
2. 工具定义（在各请求之间保持稳定）
3. 经常复用的模板和少样本示例
4. 对话历史（会逐渐增长，但与之前轮次共享前缀）
5. 当前查询和动态内容（最不稳定——始终放在最后）

为保持提示词的缓存稳定性，应从系统提示词中移除时间戳、会话计数器和请求 ID。将动态元数据移到单独的用户消息或工具结果中，避免破坏前缀。即使只更改前缀中的一个空格，也会使该更改之后的整个缓存块失效。压缩或遮蔽较早的历史记录，也需要重新处理后续文本；应批量进行这些修改，并在运行时允许时优先修改靠近末尾的内容。应测量缓存和延迟的影响，而不是假设减少令牌不会产生代价。

对于稳定的工作负载，目标是达到 70% 以上的缓存命中率。规模化后，这意味着成本降低 50% 以上，缓存令牌的延迟降低 40% 以上。

上下文分区

如果单个上下文无法容纳完整问题，且会触发激进压缩，则应将工作分配给多个子 Agent。每个子 Agent 都在干净、聚焦的上下文中处理自己的子任务，然后向协调 Agent 返回结构化结果。

当估算任务上下文超过窗口限制的 60% 时，应规划分区。将任务拆分为相互独立的子任务，分配给各个子 Agent，然后汇总结果。合并前应确认所有分区均已完成，合并兼容的结果；如果汇总后的输出仍超出预算，则进行摘要。

这种方法实现了职责分离——详细的搜索上下文隔离在各个子 Agent 中，而协调 Agent 专注于综合处理。不过，协调也会产生实际的令牌成本：协调器提示词、结果汇总和错误处理都会消耗令牌。只有当节省的成本超过这些开销时才进行分区。

预算管理

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

应采用基于触发条件的优化，而非定期优化。监控以下信号：

• 令牌使用率超过 80%——触发压缩
• 注意力退化指标（重复、遗漏指令）——触发遮蔽 + 压缩
• 质量评分低于基线——优化前先审查上下文构成

实用指南

优化决策框架

根据占据上下文主要部分的内容选择优化技术：

上下文构成	首要操作	次要操作
工具输出占主导（>50%）	遮蔽观察结果	压缩剩余轮次
检索文档占主导	摘要	如果文档相互独立，则进行分区
消息历史占主导	有选择地保留内容并压缩	为新子任务进行分区
多个组成部分占比相近	先优化 KV-cache，然后进行分层遮蔽 + 压缩	—
接近限制且正在调试	仅遮蔽已解决的工具输出——保留错误详情	—

性能目标

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

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

根据测量结果迭代调整策略。如果某种优化技术没有显著改善目标指标，就将其移除——优化机制本身也会消耗 token 并增加延迟。

示例

示例 1：压缩触发

if context_tokens / context_limit > 0.8:
    context = compact_context(context)

示例 2：观察掩蔽

if len(observation) > max_length:
    ref_id = store_observation(observation)
    return f"[Obs:{ref_id} elided. Key: {extract_key(observation)}]"

示例 3：利于缓存的排序

# Stable content first
context = [system_prompt, tool_definitions]  # Cacheable
context += [reused_templates]  # Reusable
context += [unique_content]  # Unique

示例 4：预算触发的优化策略

budgets:
  tool_outputs: 35%
  message_history: 30%
  retrieved_documents: 20%
  reserved_buffer: 15%
triggers:
  tool_outputs_over_budget: mask resolved observations
  total_context_over_70_percent: compact message history
  repeated_irrelevant_retrievals: tighten retrieval scope

指南

1. 优化前先测量——了解当前状态
2. 先掩蔽，再压缩——先移除低价值的大量内容，再总结剩余内容
3. 使用一致的提示词来设计稳定的缓存
4. 在上下文变得难以处理之前进行分区
5. 随时间监控优化效果
6. 平衡 token 节省与质量保持
7. 在生产规模下测试优化
8. 为边缘情况实现平稳降级

注意事项

1. 空白字符会破坏 KV-cache：即使只更改提示词前缀中的一个空格或换行符，也会使该位置之后的整个 KV-cache 块失效。将系统提示词固定为不可变字符串——不要在其中插入时间戳、版本号或会话 ID。每次部署时都要逐字节比较提示词模板。

2. 系统提示词中的时间戳会破坏缓存命中率：在系统提示词中加入 Current date: {today} 等动态内容，会导致每天首次请求时（如果使用具体时刻，则每次请求时）缓存完全未命中。将动态元数据移至用户消息，或作为单独的工具结果追加到稳定前缀之后。

3. 在压力下压缩会丢失关键状态：当执行压缩的大模型本身也面临上下文压力（利用率 >85%）时，其摘要质量会下降——它会遗漏任务目标、丢弃用户约束，并简化细致的状态信息。在利用率达到 70-80% 时触发压缩，而不是等到 90% 以上。如果必须延迟压缩，请使用单独的大模型调用，并提供仅包含待总结内容的干净上下文。

4. 掩蔽错误输出会破坏调试循环：过度掩蔽会隐藏错误消息、堆栈跟踪和故障详情，而 Agent 需要这些信息在后续轮次中诊断并修复问题。在主动调试期间（最近 3 轮中出现错误），应暂停掩蔽所有与错误相关的观察，直到问题解决。

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

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

7. 压缩会让人对过时摘要产生错误信心：上下文压缩后，摘要看起来可能很权威，但反映的状态可能已经过时。如果压缩后任务有所变化（出现新的用户要求或修正了假设），摘要可能会悄然沿用过时信息。压缩后，在继续之前应根据当前任务目标重新验证摘要。

集成

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

• multi-agent-patterns：在相互隔离的 Agent 上下文之间划分工作。
• evaluation：衡量优化是否提升了质量、成本或延迟。
• memory-systems：按需及时提供上下文的持久化检索层。

参考资料

内部参考资料：

• 上下文基础知识 - 阅读时机：解释什么是上下文、窗口结构、注意力机制和 U 形曲线，或为他人介绍上下文工程；还包含按组件划分的参考资料，以及 scripts/context_manager.py 的用法

• 优化技术参考 - 阅读时机：实施特定优化技术，需要技能正文之外的详细代码模式、阈值表或集成示例

• 上下文退化 - 阅读时机：诊断 Agent 性能下降的原因，并在选择优化方法前确定发生了哪种退化模式；degradation-patterns.md 包含检测代码和恢复流程，scripts/degradation_detector.py 可运行检查

此合集中的相关技能：

• evaluation - 阅读时机：设置指标和基准，以衡量优化技术是否确实改善了结果

外部资源：

• 关于上下文窗口限制的研究 - 阅读时机：评估特定模型的上下文行为（例如，中间丢失效应、注意力衰减曲线）
• KV 缓存优化技术 - 阅读时机：在推理基础设施层面实施前缀缓存（vLLM、TGI 或云服务提供商 API）
• 生产工程指南 - 阅读时机：在生产流水线中部署上下文优化，并了解可运维性模式（监控、告警、回滚）