context-compression

上下文压缩策略

当 Agent 会话生成数百万个令牌的对话历史时，压缩就成了必需。简单粗暴的做法是尽可能压缩，以减少每次请求的令牌数。正确的优化目标是每项任务消耗的令牌数：完成任务所消耗的令牌总数，包括压缩丢失关键信息后重新获取信息的成本。

何时启用

在以下情况下启用此技能：

• Agent 会话超出上下文窗口限制
• 代码库超出上下文窗口限制（5M+ 个令牌的系统）
• 设计对话摘要策略
• 调试 Agent“忘记”修改过哪些文件的情况
• 构建用于评估压缩质量的框架
• 创建持久的交接摘要，保留决策、文件、风险和后续操作

对于由其他技能负责的相关工作，请勿启用此技能：

• 屏蔽、前缀缓存或分区等通用令牌效率技巧：context-optimization。
• 在选择缓解措施前，诊断长上下文为何失效：context-degradation。
• 将原始输出、日志或计划写入文件而不进行摘要：filesystem-context。
• 设计跨会话的长期语义记忆：memory-systems。
• 由模型决定何时以及在何处重写自身上下文：self-managed-context。此技能仍负责规定替换文本必须保留的内容。

核心概念

上下文压缩需要权衡令牌节省与信息损失。根据会话特点，从以下三种适用于生产环境的方法中进行选择：

1. 锚定式迭代摘要：适用于需要跟踪文件的长期会话。维护结构化的持久摘要，并为会话意图、文件修改、决策和后续步骤设置明确的章节。触发压缩时，仅总结刚被截断的部分，并与现有摘要合并，而不是从头重新生成。这样可以防止整体重新生成摘要时不断累积偏差——每次重新生成都可能丢失模型认为优先级较低、但任务需要的细节。结构化格式能强制保留信息，因为专门的章节相当于摘要器必须填写的检查清单，可捕捉无声的信息丢失。

2. 不透明压缩：仅用于重新获取信息成本较低且需要最大程度节省令牌的短会话。它会生成针对还原保真度优化的压缩表示，压缩率可达 99% 以上，但会完全牺牲可读性。这种权衡很重要：若不运行基于探测的评估，就无法验证哪些内容得到了保留，因此在调试或跟踪产物至关重要时，绝不要使用这种方法。

3. 再生成式完整摘要：当摘要可读性至关重要且会话具有明确阶段边界时使用。每次触发压缩时，它都会生成详细的结构化摘要。其弱点是在反复循环中细节会不断丢失——每次完整重新生成都是一次全新的处理，可能会降低先前摘要中已保留细节的优先级。

详细主题

优化每项任务的令牌数，而非每次请求的令牌数

衡量从任务开始到完成所消耗的令牌总数，而不是单次请求的令牌数。当压缩丢弃文件路径、错误消息或决策依据时，Agent 必须重新探索、重新阅读文件并重新推导结论——浪费的令牌远超压缩所节省的数量。某种策略即使每次请求多节省 0.5% 的令牌，但如果导致重新获取信息的次数增加 20%，总体成本反而更高。应将重新获取信息的频率作为主要质量指标：如果 Agent 反复要求重新阅读已经处理过的文件，说明压缩过于激进。

优先解决产物追踪问题

在压缩评估中，产物追踪的完整性往往是最薄弱的维度（claim-context-compression-factory-benchmark）。应主动解决这一问题，因为通用摘要无法可靠地维护这类信息。

在每轮压缩中明确保留以下类别：

• 创建了哪些文件（完整路径）
• 修改了哪些文件以及具体改动（包括函数名称，而不只是文件名）
• 读取但未修改的文件
• 具体标识符：函数名称、变量名称、错误消息、错误代码

在 Agent 脚手架中单独实现产物索引或明确的文件状态跟踪，而不要依赖摘要器记录这些细节。即使采用带专门文件章节的结构化摘要，在长会话中也难以保证信息完整。

使用必需章节组织摘要

构建包含明确章节的结构化摘要，以避免信息在无声中丢失。每个章节都充当摘要器必须填写的清单，让遗漏显而易见，而不是悄然发生。

## Session Intent
[What the user is trying to accomplish]

## Files Modified
- auth.controller.ts: Fixed JWT token generation
- config/redis.ts: Updated connection pooling
- tests/auth.test.ts: Added mock setup for new config

## Decisions Made
- Using Redis connection pool instead of per-request connections
- Retry logic with exponential backoff for transient failures

## Current State
- 14 tests passing, 2 failing
- Remaining: mock setup for session service tests

## Next Steps
1. Fix remaining test failures
2. Run full test suite
3. Update documentation

根据 Agent 的领域调整章节。调试 Agent 需要“根本原因”和“错误消息”；迁移 Agent 需要“源架构”和“目标架构”。结构比具体章节更重要——任何明确的架构都胜过自由形式的摘要。

策略性地选择压缩触发时机

何时触发压缩与如何压缩同样重要。根据会话的可预测性选择触发策略：

策略	触发点	权衡
固定阈值	上下文使用率达到 70-80%	简单，但可能过早压缩
滑动窗口	保留最近 N 轮对话和摘要	上下文大小可预测
基于重要性	优先压缩相关性较低的章节	复杂，但能保留关键信息
任务边界	在逻辑任务完成时压缩	摘要清晰，但时机不可预测

对于编码 Agent，默认采用滑动窗口和结构化摘要，这是可预测性与质量之间的最佳平衡。如果会话有明确的阶段转换（例如先研究，再实现，最后测试），则使用任务边界触发。

使用探测问题而非指标评估压缩

ROUGE 或嵌入相似度等传统指标无法衡量压缩的实际功能质量。摘要可能在词汇重合度方面得分很高，却漏掉 Agent 继续工作所需的唯一文件路径。

使用基于探测问题的评估：压缩后提出问题，检验关键信息是否保留。如果 Agent 回答正确，说明压缩保留了正确的信息；否则，它可能会猜测或产生幻觉。

探测类型	测试内容	示例问题
回忆	事实保留	“原始错误消息是什么？”
产物	文件跟踪	“我们修改了哪些文件？”
继续执行	任务规划	“接下来应该做什么？”
决策	推理链	“我们对 Redis 问题做出了什么决定？”

从六个维度评估压缩

从以下维度评估编码 Agent 的压缩质量。与词汇相似度相比，准确性和产物追踪保留情况往往更能区分不同方法（claim-context-compression-factory-benchmark），因此压缩需要采用专门处理方式，而非通用摘要。

1. 准确性：技术细节是否正确——文件路径、函数名称、错误代码？
2. 上下文感知：回复是否反映当前对话状态？
3. 产物追踪：Agent 是否知道哪些文件已读取或修改？
4. 完整性：回复是否涵盖问题的所有部分？
5. 连续性：能否在不重新获取信息的情况下继续工作？
6. 遵循指令：回复是否遵守已说明的约束？

实用指南

对大型代码库应用三阶段压缩工作流

对于超出上下文窗口的代码库或 Agent 系统，请按顺序分三个阶段进行压缩。每个阶段都会缩小上下文范围，确保下一阶段在预算内运行。

1. 调研阶段：查看架构图、文档和关键接口。将探索过程压缩为一份关于组件、依赖项和边界的结构化分析。输出：一份取代原始探索内容的调研文档。

2. 规划阶段：将调研文档转化为实现规范，其中包含函数签名、类型定义和数据流。一个包含 5M 个 Token 的代码库，在此阶段可压缩为约 2,000 词的规范。

3. 实现阶段：依据规范执行。上下文聚焦于规范和当前工作文件，而非原始代码库探索。此阶段通常无需进一步压缩，因为规范已经足够精简。

将示例产物用作压缩种子

如果提供了手动迁移示例或参考 PR，请将其用作模板，以了解目标模式，而不是从头探索代码库。示例揭示了静态分析无法呈现的约束：哪些不变量必须成立、哪些服务会因变更而出问题，以及整洁的实现是什么样的。

当 Agent 无法区分必要的复杂性（业务需求）和偶然的复杂性（遗留变通方案）时，这一点尤其重要。示例产物隐含地体现了这种区别，节省原本会用于反复试错探索的 Token。

按步骤实施锚定式迭代摘要

1. 定义明确的摘要部分，以匹配 Agent 的领域（调试、迁移、功能开发）
2. 首次触发压缩时，将被截断的历史记录总结到这些部分中
3. 后续压缩时，仅总结新近截断的内容，不要重新总结现有摘要
4. 将新信息合并到现有部分，而不是重新生成摘要；按文件路径和决策标识去重
5. 标记信息来自哪个压缩周期，以便在摘要内容偏移时进行调试

根据会话特征选择合适的方法

在以下情况下使用锚定式迭代摘要：

• 会话持续时间较长（100+ 条消息）
• 文件追踪很重要（编码、调试）
• 需要验证保留的信息

在以下情况下使用不透明压缩：

• 需要最大限度地节省 Token
• 会话相对较短
• 重新获取内容的成本较低（例如，无需访问文件系统）

在以下情况下使用再生成式摘要：

• 摘要的可解释性对人工审查至关重要
• 会话具有明确的阶段边界
• 每次触发压缩时都可以接受完整上下文审查

按方法校准压缩率

方法	压缩率	质量评分	权衡
锚定式迭代	98.6%	3.70	质量最佳，压缩率略低
再生成式	98.7%	3.44	质量良好，压缩适中
不透明式	99.3%	3.35	压缩最佳，但质量有所损失

请将这些数据视为特定来源的基准值，而非普遍适用的常数（claim-context-compression-factory-benchmark）。对于存在重新获取成本的任务，这种权衡通常更有利于结构化方法。

示例

示例 1：调试会话压缩

原始上下文（89,000 个 token，178 条消息）：

• /api/auth/login 端点出现 401 错误
• 追踪了身份验证控制器、中间件和会话存储
• 发现 Redis 连接已过期
• 修复了连接池，并添加了重试逻辑
• 14 项测试通过，2 项失败

压缩后的结构化摘要：

## Session Intent
Debug 401 Unauthorized error on /api/auth/login despite valid credentials.

## Root Cause
Stale Redis connection in session store. JWT generated correctly but session could not be persisted.

## Files Modified
- auth.controller.ts: No changes (read only)
- middleware/cors.ts: No changes (examined)
- config/redis.ts: Fixed connection pooling configuration
- services/session.service.ts: Added retry logic for transient failures
- tests/auth.test.ts: Updated mock setup

## Test Status
14 passing, 2 failing (mock setup issues)

## Next Steps
1. Fix remaining test failures (mock session service)
2. Run full test suite
3. Deploy to staging

示例 2：探测响应质量

压缩后，询问“原始错误是什么？”：

良好响应（结构化摘要）：

“原始错误是 /api/auth/login 端点返回 401 Unauthorized 响应。用户使用有效凭据时也会收到此错误。根本原因是会话存储中的 Redis 连接已过期。”

较差响应（激进压缩）：

“我们在调试身份验证问题。登录失败了。我们修复了一些配置问题。”

结构化响应保留了端点、错误代码和根本原因。激进压缩的响应则丢失了所有技术细节。

指南

1. 优化每项任务所用的 token 数，而不是每次请求所用的 token 数
2. 使用带有明确文件跟踪分区的结构化摘要
3. 在上下文利用率达到 70-80% 时触发压缩
4. 实施增量合并，而不是完全重新生成
5. 使用基于探测的评估来测试压缩质量
6. 如果文件跟踪至关重要，请单独跟踪制品轨迹
7. 为了更好地保留质量，接受略低的压缩率
8. 将重新获取频率作为压缩质量指标进行监控

注意事项

1. 绝不压缩工具定义或架构：压缩函数调用架构、API 规范或工具定义会彻底破坏 Agent 的功能。参数名称或类型被概括掉后，Agent 就无法调用相应工具。应将工具定义视为不可变锚点，使其不参与压缩。

2. 压缩摘要会产生幻觉事实：大模型总结对话历史时，可能会引入听起来合理、但从未出现在原文中的细节。在丢弃原文之前，务必根据源材料验证压缩后的输出——尤其要检查文件路径、错误代码和数值，因为摘要可能会对它们进行“取整”或编造。

3. 压缩会破坏制品引用：压缩时，文件路径、提交 SHA、变量名和代码片段可能会被改写或删除。如果 Agent 需要 config/redis.ts，但摘要只说“更新了配置文件”，就会导致 Agent 重新探索。应在专用分区中逐字保留标识符，而不是将它们嵌入散文。

4. 早期轮次包含不可替代的约束：会话的最初几轮通常包含任务设置、用户约束和架构决策，这些信息无法重新推导。应保护早期轮次不被压缩，或将其中的约束提取到持久前言中，使其在所有压缩周期中都能保留。

5. 激进压缩率会在多个周期中累积损失：一次压缩 95% 看似安全，但反复应用会累积损失。经过 3 个周期、每次压缩 95% 后，原始 token 只剩 0.0125%。校准压缩率时，应考虑多个压缩周期，而不是只考虑单次处理。

6. 代码和散文需要采用不同的压缩方式：散文因为自然语言存在冗余而易于压缩。代码则不同——从函数签名或导入路径中删除单个 token 就可能使其失去作用。应采用针对领域的压缩策略：大幅概括散文部分，同时逐字保留代码块和结构化数据。

7. 基于探测的评估会带来虚假的信心：即使关键内容已丢失，探测也可能通过，因为它们只测试自己询问的内容。只检查文件名、不检查函数签名的探测集会漏掉签名丢失的问题。设计探测时，应覆盖全部 6 个评估维度，并在不同评估轮次中轮换探测集，以避免盲点。

集成

此技能可与集合中的其他几个技能配合使用：

• context-degradation - 压缩是缓解退化的一种策略
• context-optimization - 压缩是众多优化技术之一
• evaluation - 基于探测的评估适用于压缩测试
• memory-systems - 压缩与便笺和摘要记忆模式有关
• self-managed-context - 当模型触发并放置自己的压缩编辑时，此技能会提供替换说明中应保留的内容

参考资料

内部参考：

• 评估框架参考 - 阅读时机：构建或校准基于探测的评估流水线，或需要用于压缩质量评估的评分标准和 LLM 评判配置时

此集合中的相关技能：

• context-degradation - 阅读时机：诊断长时间会话中 Agent 性能下降的原因，在采用压缩作为缓解措施之前
• context-optimization - 阅读时机：仅靠压缩不足以解决问题，需要更广泛的优化策略（剪枝、缓存、路由）时
• evaluation - 阅读时机：设计超越压缩专用探测的评估框架，包括通用的 LLM-as-judge 方法

外部资源：

• Factory Research：评估 AI Agent 的上下文压缩（2025 年 12 月）- 阅读时机：需要压缩方法对比的基准数据或包含 36,000 条消息的评估数据集时
• 关于 LLM-as-judge 评估方法的研究（Zheng 等人，2023 年）- 阅读时机：实施或验证 LLM 评判评分，以了解偏差模式和校准时
• Netflix Engineering：《无限软件危机》——三阶段工作流与大规模上下文压缩（AI Summit 2025）- 阅读时机：为大型代码库实施三阶段压缩工作流，或了解生产规模的上下文管理时

---

技能元数据

创建时间：2025-12-22 最后更新：2026-05-15 作者：Agent Skills for Context Engineering 贡献者 版本：1.3.0