# Context Compression

> 当智能体会话产生数百万 token 的对话历史时，压缩成为必需。朴素的方法是激进压缩以最小化每次请求的 token 数。

- Skill: `kscz0000/context-compression` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/context-compression`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/context-compression/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/context-compression

---


# 上下文压缩策略

当智能体会话产生数百万 token 的对话历史时，压缩成为必需。朴素的方法是激进压缩以最小化每次请求的 token 数。正确的优化目标是每次任务的 token 数：完成任务所消耗的总 token 数，包括压缩丢失关键信息后重新获取的成本。

## 何时使用

在以下情况激活此技能：
- 智能体会话超出上下文窗口限制
- 代码库超出上下文窗口（5M+ token 系统）
- 设计对话摘要策略
- 调试智能体"忘记"修改过哪些文件的情况
- 构建压缩质量评估框架

## 核心概念

上下文压缩在节省 token 与信息丢失之间权衡。存在三种生产可用的方法：

1. **锚定迭代摘要**：维护结构化的持久摘要，包含会话意图、文件修改、决策和下一步的显式章节。当压缩触发时，仅摘要新截断的部分并与现有摘要合并。结构通过为特定信息类型分配章节来强制保留信息。

2. **不透明压缩**：生成优化重建保真度的压缩表示。实现最高压缩率（99%+）但牺牲可解释性。无法验证保留了什么。

3. **再生式完整摘要**：每次压缩时生成详细的结构化摘要。产生可读输出，但由于完全再生而非增量合并，可能在重复压缩周期中丢失细节。

关键洞察：结构强制保留。专用章节充当检查清单，摘要器必须填充，防止静默信息漂移。

## 详细主题

### 为什么每次任务的 Token 数很重要

传统压缩指标针对每次请求的 token 数。这是错误的优化目标。当压缩丢失关键细节如文件路径或错误消息时，智能体必须重新获取信息、重新探索方法，并浪费 token 恢复上下文。

正确的指标是每次任务的 token 数：从任务开始到完成消耗的总 token 数。一个节省 0.5% 更多 token 但导致 20% 更多重新获取成本的压缩策略，总体成本更高。

### 工件追踪问题

工件追踪完整性是所有压缩方法中最弱的维度，在评估中得分 2.2-2.5（满分 5.0）。即使带有显式文件章节的结构化摘要，也难以在长会话中维护完整的文件追踪。

编码智能体需要知道：
- 创建了哪些文件
- 修改了哪些文件以及改了什么
- 读取了哪些文件但未修改
- 函数名、变量名、错误消息

这个问题可能需要超出通用摘要的专门处理：单独的工件索引或智能体脚手架中的显式文件状态追踪。

### 结构化摘要章节

有效的结构化摘要包含显式章节：

```markdown
## 会话意图
[用户想要完成什么]

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

## 已做决策
- 使用 Redis 连接池而非每次请求新建连接
- 对瞬态故障采用指数退避的重试逻辑

## 当前状态
- 14 个测试通过，2 个失败
- 剩余：会话服务测试的 mock 设置

## 下一步
1. 修复剩余的测试失败
2. 运行完整测试套件
3. 更新文档
```

这种结构防止文件路径或决策的静默丢失，因为每个章节都必须显式处理。

### 压缩触发策略

何时触发压缩与如何压缩同样重要：

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

对于大多数编码智能体用例，滑动窗口配合结构化摘要提供了可预测性和质量的最佳平衡。

### 基于探针的评估

传统指标如 ROUGE 或嵌入相似度无法捕获功能性压缩质量。摘要可能在词汇重叠上得分很高，却丢失了智能体需要的唯一文件路径。

基于探针的评估通过在压缩后提问来直接测量功能质量：

| 探针类型 | 测试内容 | 示例问题 |
|----------|----------|----------|
| 回忆 | 事实保留 | "原始错误消息是什么？" |
| 工件 | 文件追踪 | "我们修改了哪些文件？" |
| 延续 | 任务规划 | "接下来应该做什么？" |
| 决策 | 推理链 | "关于 Redis 问题我们做了什么决定？" |

如果压缩保留了正确信息，智能体会正确回答。否则，它会猜测或产生幻觉。

### 评估维度

六个维度捕获编码智能体的压缩质量：

1. **准确性**：技术细节是否正确？文件路径、函数名、错误码。
2. **上下文感知**：响应是否反映当前对话状态？
3. **工件追踪**：智能体是否知道读取或修改了哪些文件？
4. **完整性**：响应是否解决了问题的所有部分？
5. **连续性**：能否继续工作而无需重新获取信息？
6. **指令遵循**：响应是否遵守声明的约束？

准确性在压缩方法之间显示出最大差异（0.6 分差距）。工件追踪普遍较弱（2.2-2.5 范围）。

## 实践指导

### 三阶段压缩工作流

对于超出上下文窗口的大型代码库或智能体系统，通过三个阶段应用压缩：

1. **研究阶段**：从架构图、文档和关键接口生成研究文档。将探索压缩为组件和依赖的结构化分析。输出：单个研究文档。

2. **规划阶段**：将研究转化为实现规格说明，包含函数签名、类型定义和数据流。5M token 的代码库压缩为约 2,000 词的规格说明。

3. **实现阶段**：根据规格说明执行。上下文聚焦于规格而非原始代码库探索。

### 使用示例工件作为种子

当提供手动迁移示例或参考 PR 时，将其用作模板来理解目标模式。示例揭示了静态分析无法发现的约束：哪些不变量必须保持、哪些服务会在变更时中断、以及干净的迁移是什么样的。

当智能体无法区分本质复杂性（业务需求）和偶然复杂性（遗留变通方案）时，这一点尤为重要。示例工件编码了这种区分。

### 实现锚定迭代摘要

1. 定义匹配智能体需求的显式摘要章节
2. 首次压缩触发时，将截断的历史摘要到各章节
3. 后续压缩时，仅摘要新截断的内容
4. 将新摘要合并到现有章节而非重新生成
5. 追踪哪些信息来自哪个压缩周期以便调试

### 何时使用各方法

**使用锚定迭代摘要当：**
- 会话是长期运行的（100+ 消息）
- 文件追踪很重要（编码、调试）
- 需要验证保留了什么

**使用不透明压缩当：**
- 需要最大 token 节省
- 会话相对较短
- 重新获取成本低

**使用再生式摘要当：**
- 摘要可解释性至关重要
- 会话有清晰的阶段边界
- 每次压缩时完整上下文审查可接受

### 压缩率考量

| 方法 | 压缩率 | 质量分数 | 权衡 |
|------|--------|----------|------|
| 锚定迭代 | 98.6% | 3.70 | 最佳质量，压缩略低 |
| 再生式 | 98.7% | 3.44 | 良好质量，中等压缩 |
| 不透明 | 99.3% | 3.35 | 最佳压缩，质量损失 |

结构化摘要额外保留的 0.7% token 换取了 0.35 质量分。对于重新获取成本重要的任何任务，这种权衡有利于结构化方法。

## 示例

**示例 1：调试会话压缩**

原始上下文（89,000 token，178 条消息）：
- /api/auth/login 端点返回 401 错误
- 追踪通过 auth 控制器、中间件、会话存储
- 发现过期的 Redis 连接
- 修复连接池，添加重试逻辑
- 14 个测试通过，2 个失败

压缩后的结构化摘要：

```markdown
## 会话意图
调试 /api/auth/login 在凭据有效时返回 401 Unauthorized 错误。

## 根本原因
会话存储中过期的 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 会话服务）
2. 运行完整测试套件
3. 部署到预发布环境
```

**示例 2：探针响应质量**

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

良好响应（结构化摘要）：
> "原始错误是 /api/auth/login 端点返回的 401 Unauthorized 响应。用户使用有效凭据收到此错误。根本原因是会话存储中过期的 Redis 连接。"

较差响应（激进压缩）：
> "我们在调试一个认证问题。登录失败了。我们修复了一些配置问题。"

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

## 指南

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

## 集成

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

- context-degradation - 压缩是退化的缓解策略
- context-optimization - 压缩是众多优化技术之一
- evaluation - 基于探针的评估适用于压缩测试
- memory-systems - 压缩与便笺和摘要记忆模式相关

## 参考资料

内部参考：
- 评估框架参考 - 详细的探针类型和评分标准

本集合中的相关技能：
- context-degradation - 理解压缩防止什么
- context-optimization - 更广泛的优化策略
- evaluation - 构建评估框架

外部资源：
- Factory Research: Evaluating Context Compression for AI Agents（2025 年 12 月）
- LLM-as-judge 评估方法论研究（Zheng et al., 2023）
- Netflix Engineering: "The Infinite Software Crisis" - 三阶段工作流和大规模上下文压缩（AI Summit 2025）

---

## 技能元数据

**创建时间**：2025-12-22
**最后更新**：2025-12-26
**作者**：Agent Skills for Context Engineering Contributors
**版本**：1.1.0

## 局限性
- 仅当任务明确匹配上述范围时使用此技能。
- 不要将输出视为环境特定验证、测试或专家审查的替代品。
- 如果缺少所需输入、权限、安全边界或成功标准，请停下来请求澄清。