skillhub-090-context-compression/SKILL.md

---name: context-compression description: 此技能适用于长时间运行的 Agent 会话需要上下文压缩、结构化摘要、精简、按任务优化 Token，以及保存决策、文件、风险和后续行动的可持久化交接摘要的场景。

上下文压缩策略

当 Agent 会话生成数百万 Token 的对话历史时，压缩就变得必不可少。天真的做法是激进压缩以最小化每次请求的 Token 数。而正确的优化目标是按任务优化 Token 数：完成一个任务所消耗的 Token 总数，包括因压缩丢失关键信息而重新获取的成本。

何时启用

在以下情况启用此技能：

• Agent 会话超出上下文窗口限制
• 代码库超出上下文窗口（5M+ Token 的系统）
• 设计对话摘要策略
• 调试 Agent「忘记」自己修改过哪些文件的情况
• 构建压缩质量评估框架
• 创建可持久化的交接摘要，以保存决策、文件、风险和后续行动

对于其他技能负责的相邻工作，不要启用此技能：

• 通用的 Token 效率策略，如掩码、前缀缓存或分区：请使用 context-optimization。
• 在选择缓解方案之前诊断长上下文为何失败：请使用 context-degradation。
• 将原始输出、日志或计划写入文件而不做摘要：请使用 filesystem-context。
• 设计跨会话的长期语义记忆：请使用 memory-systems。

核心概念

上下文压缩在 Token 节省与信息损失之间进行权衡。根据会话特性，从以下三种生产就绪的方法中选择：

1. 锚定迭代摘要：适用于需要跟踪文件的长时间运行会话。维护结构化、持久的摘要，包含明确的章节——会话意图、文件修改、决策和后续步骤。当触发压缩时，仅对新增截断的部分进行摘要，并与现有摘要合并，而不是从头重新生成。这样可以防止逐次全面重新生成摘要时产生的漂移——每次重新生成都有可能丢失模型认为优先级低但任务实际需要的细节。结构化方式能强制保留信息，因为专门的章节充当了摘要器必须填写的检查清单，从而捕捉到无声的信息丢失。

2. 不透明压缩：仅适用于重新获取成本低且需要最大程度节省 Token 的短会话。它生成针对重建保真度优化的压缩表示，可实现 99% 以上的压缩比，但完全牺牲了可解释性。这一权衡很重要：如果不进行基于探测的评估，就无法验证保留了哪些内容，因此在调试或工件跟踪至关重要时，切勿使用此方法。

3. 重新生成式全文摘要：适用于摘要可读性至关重要且会话具有清晰阶段边界的情况。它在每次触发压缩时生成详细的结构化摘要。其弱点是在多次循环中累积细节丢失——每次完整重新生成都是一次新的扫描，可能会降低先前摘要中保留细节的优先级。

详细主题

为按任务优化 Token 数，而非按请求优化 Token 数

衡量从任务开始到完成的 Token 总消耗量，而不是每次请求的 Token 数。当压缩丢弃了文件路径、错误消息或决策依据时，Agent 必须重新探索、重新读取文件并重新推导结论——这会浪费远比压缩节省的更多的 Token。一个每请求多节省 0.5% Token 但导致 20% 更多重新获取成本的策略，总体成本反而更高。将重新获取频率作为主要质量信号进行跟踪：如果 Agent 反复要求重新读取已经处理过的文件，说明压缩过于激进。

首先解决工件追踪问题

工件追踪完整性通常是压缩评估中最薄弱的维度（见 claim-context-compression-factory-benchmark）。应主动解决此问题，因为通用摘要无法可靠地维护它。

在每个压缩周期中显式保留以下类别：

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

在 Agent 脚手架中实现独立的工件索引或显式的文件状态跟踪，而不是依赖摘要器来捕获这些细节。即使是带有专门文件章节的结构化摘要，在长时间会话中也难以保证完整性。

使用必填章节构建摘要

构建带有显式章节的结构化摘要，以防止无声的信息丢失。每个章节充当摘要器必须填写的检查清单，使遗漏变得可见而非无声。

## 会话意图
[用户试图完成什么]

## 已修改文件
- auth.controller.ts：修复了 JWT Token 生成
- config/redis.ts：更新了连接池
- tests/auth.test.ts：为新配置添加了 mock 设置

## 已做决策
- 使用 Redis 连接池替代每请求连接
- 对临时故障采用指数退避重试逻辑

## 当前状态
- 14 个测试通过，2 个失败
- 剩余工作：为 Session Service 测试设置 mock

## 后续步骤
1. 修复剩余测试失败
2. 运行完整测试套件
3. 更新文档

根据 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 的代码库在此阶段可压缩至约 2000 词的规格说明。

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 错误
• 跟踪了 auth controller、middleware、session store
• 发现过期的 Redis 连接
• 修复了连接池，添加了重试逻辑
• 14 个测试通过，2 个失败

压缩后的结构化摘要：

## 会话意图
调试 /api/auth/login 上使用有效凭证仍返回 401 Unauthorized 错误的问题。

## 根因
Session Store 中存在过期的 Redis 连接。JWT 生成正确，但会话无法持久化。

## 已修改文件
- auth.controller.ts：未修改（仅读取）
- middleware/cors.ts：未修改（已检查）
- config/redis.ts：修复了连接池配置
- services/session.service.ts：为临时故障添加了重试逻辑
- tests/auth.test.ts：更新了 mock 设置

## 测试状态
14 个通过，2 个失败（mock 设置问题）

## 后续步骤
1. 修复剩余测试失败（mock session service）
2. 运行完整测试套件
3. 部署到预发布环境

示例 2：探测回复质量

压缩后，询问「原始错误是什么？」：

好回复（结构化摘要）：

"原始错误是 /api/auth/login 端点返回了 401 Unauthorized 响应。用户使用有效凭证时收到了此错误。根因是 Session Store 中存在过期的 Redis 连接。"

差回复（激进压缩）：

"我们当时在调试一个认证问题。登录失败了。我们修复了一些配置问题。"

结构化回复保留了端点、错误码和根因。激进回复丢失了所有技术细节。

指南

1. 按任务优化 Token 数，而非按请求优化 Token 数
2. 使用带有显式文件跟踪章节的结构化摘要
3. 在上下文使用率达到 70-80% 时触发压缩
4. 实施增量合并而非完全重新生成
5. 使用基于探测的评估测试压缩质量
6. 如果文件跟踪至关重要，则单独跟踪工件
7. 接受略低的压缩比以换取更好的质量保留
8. 监控重新获取频率作为压缩质量信号

注意事项

1. 切勿压缩工具定义或模式：压缩函数调用模式、API 规格说明或工具定义会完全破坏 Agent 的功能。Agent 无法调用参数名或类型已被摘要掉的工具。将工具定义视为不可变的锚点，使其绕过压缩。

2. 压缩摘要会产生事实幻觉：当 LLM 对对话历史进行摘要时，可能会引入听起来合理但原始内容中从未出现的细节。在丢弃原始内容之前，务必对照源材料验证压缩输出——尤其是摘要器可能会「四舍五入」或编造的文件路径、错误码和数值。

3. 压缩会破坏工件引用：文件路径、提交 SHA、变量名和代码片段在压缩过程中会被改写或丢弃。当摘要说「更新了配置文件」而 Agent 需要 config/redis.ts 时，就会导致重新探索。在专门的章节中逐字保留标识符，而不是将其嵌入散文。

4. 早期轮次包含不可替代的约束：会话的前几轮通常包含任务设置、用户约束和架构决策，这些是无法重新推导出来的。保护早期轮次免受压缩，或将其约束提取到持久的序言中，使其贯穿所有压缩周期。

5. 激进的比例会在多个周期中叠加：95% 的压缩比单独看似乎安全，但重复应用会使损失累积。经过三轮 95% 的压缩后，仅剩下 0.0125% 的原始 Token。校准压缩比时应假设会有多个压缩周期，而非仅一次。

6. 代码和散文需要不同的压缩策略：散文压缩效果好，因为自然语言存在冗余。但代码并非如此——从函数签名或导入路径中移除一个 Token 就可能使其完全无用。应用领域特定的压缩策略：激进地压缩散文章节，同时逐字保留代码块和结构化数据。

7. 基于探测的评估会带来虚假信心：探测可能通过，尽管关键信息已丢失，因为探测只测试它们所问的内容。一组检查文件名但不检查函数签名的探测集，会遗漏签名丢失的问题。设计覆盖所有六个评估维度的探测，并在不同评估轮次中轮换探测集，以避免盲点。

集成

此技能与集合中的其他几个技能相关联：

• context-degradation——压缩是应对性能下降的一种缓解策略
• context-optimization——压缩是众多优化技术之一
• evaluation——基于探测的评估适用于压缩测试
• memory-systems——压缩与草稿板和摘要记忆模式相关

参考

内部参考：

• 评估框架参考——何时阅读：构建或校准基于探测的评估管道时，或需要用于压缩质量评估的评分标准和 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 技能 版本：1.3.0