Context Compression Zh

---
name: context-compression-zh
description: 上下文压缩、长会话压缩、结构化摘要、compaction、按任务而非按请求优化 token、可持久的交接摘要（保留决策/文件/风险/下一步）、Agent 忘了自己改过哪些文件、压缩质量评估。当用户说「会话太长要压缩一下」「怎么设计对话摘要策略」「压缩之后 Agent 就忘了改过什么文件」「怎么评估摘要有没有丢关键信息」「大代码库超出上下文怎么办」时使用。核心：优化「每任务 token」而不是「每请求 token」（压缩丢了路径/报错/理由会逼 Agent 重新探索，反而更贵）；三种方法——锚定迭代摘要（长会话、需要文件追踪，首选）、不透明压缩（短会话、极致压缩、不可审计）、全量再生摘要（可读性优先、有清晰阶段边界）；先解决「产物轨迹」这个最弱维度；带强制章节的结构化摘要；用探针而不是 ROUGE 评估；六维评分。附评估框架参考。也覆盖「改过的文件」「对话摘要策略」「关键信息」这类说法。改编自 Agent Skills for Context Engineering 的 context-compression（MIT）。
author: Captain
version: 0.1.1
display_name: "上下文压缩策略"
display_name_en: "Context Compression (zh)"
description_zh: "长会话必须压缩时怎么压才不丢关键信息：优化每任务 token 而非每请求 token；三种生产可用方法与适用场景；结构化强制章节摘要；先保产物轨迹（文件、函数名、报错）；用探针评估六个维度；触发策略与压缩比校准。"
description_en: "How to compress long agent sessions without losing what matters: optimize tokens-per-task not per-request; three production methods and when to use each; structured summaries with mandatory sections; protect the artifact trail first; probe-based evaluation across six dimensions; trigger strategies and ratio calibration."
tags:
  - "上下文压缩"
  - "context compression"
  - "长会话"
  - "摘要"
  - "token 优化"
  - "compaction"
  - "Agent 记忆"
examples_zh:
  - "会话到 80% 了，帮我按结构化模板压缩一下，别丢改过的文件"
  - "设计一个编码 Agent 的对话摘要策略"
  - "怎么测我们的压缩有没有把关键信息压没了"
examples_en:
  - "Context is at 80%, compress with the structured template, keep modified files"
  - "Design a summarization strategy for a coding agent"
  - "How do we test whether compression dropped critical info?"
metadata:
  { "openclaw": { "requires": { "bins": [] }, "os": ["darwin", "linux", "windows"], "emoji": "🗜️" } }
---

# 上下文压缩策略

Agent 会话产生数百万 token 的历史时，压缩是必修课。天真的做法是激进压缩、最小化每次请求的 token。正确的优化目标是**每任务 token**：完成任务消耗的总 token，包括压缩丢失关键信息后重新取回的成本。

## 什么时候用

- 会话超出上下文窗口
- 代码库超出上下文窗口（500 万 token 级系统）
- 设计对话摘要策略
- 调试「Agent 忘了自己改过哪些文件」
- 为压缩质量搭评估框架
- 做保留决策、文件、风险和下一步的可持久交接摘要

相邻工作归别的技能：通用 token 效率手段（遮蔽、前缀缓存、分区）；诊断长上下文为什么失效→「上下文退化诊断」；把原始输出、日志、计划写文件而不摘要；跨会话的长期语义记忆→「记忆系统」。

## 三种方法

1. **锚定迭代摘要**：长会话、文件追踪重要时用。维护结构化、持久的摘要，显式分节：会话意图、文件改动、决策、下一步。触发压缩时只摘要新截断的那一段并合并进已有摘要，不从头再生。这避免了整体再生时累积的漂移——每次再生都可能丢掉模型觉得低优先级、任务却需要的细节。结构强制保留：专用章节是摘要器必须填的清单，静默丢失变得可见。
2. **不透明压缩**：短会话、重取成本低、需要极致压缩时用。产出为重建保真度优化的压缩表示，可达 99%+ 压缩比，但完全牺牲可解释性。不跑探针评估就无法验证保留了什么，所以调试或产物追踪关键时绝不用。
3. **全量再生摘要**：摘要可读性关键、会话有清晰阶段边界时用。每次触发生成详细的结构化摘要。弱点是多轮之后的累积细节丢失——每次全量再生都是一次新的遍历，可能降级之前摘要保留的细节。

## 要点

### 优化每任务 token，不是每请求 token

从任务开始到完成的总消耗，不是单次请求。压缩丢了文件路径、报错信息或决策理由，Agent 就得重新探索、重读文件、重新推导——浪费的远多于省下的。每请求多省 0.5% 却导致 20% 更多重取的策略，总账更贵。把**重取频率**当首要质量信号：Agent 反复要求重读已处理过的文件，说明压得太狠。

### 先解决产物轨迹问题

产物轨迹完整性通常是压缩评估里最弱的维度，通用摘要无法可靠维持它。每个压缩周期显式保留：创建了哪些文件（完整路径）；修改了哪些文件、改了什么（含函数名，不只文件名）；读过但没改的文件；具体标识符——函数名、变量名、报错信息、错误码。在 Agent 脚手架里实现独立的产物索引或显式文件状态追踪，别指望摘要器。

### 带强制章节的结构化摘要

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

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

## 已做决策
- 用 Redis 连接池替代每请求连接
- 瞬时故障用指数退避重试

## 当前状态
- 14 个测试通过，2 个失败
- 剩余：session service 测试的 mock 准备

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

按 Agent 领域调整章节：调试 Agent 需要「根因」和「报错信息」；迁移 Agent 需要「源 schema」和「目标 schema」。结构比具体章节更重要——任何显式 schema 都胜过自由摘要。

### 策略性选择触发时机

| 策略 | 触发点 | 权衡 |
|---|---|---|
| 固定阈值 | 70–80% 占用 | 简单，可能压太早 |
| 滑动窗口 | 保留最近 N 轮 + 摘要 | 上下文大小可预测 |
| 基于重要性 | 先压低相关段 | 复杂，保信号 |
| 任务边界 | 逻辑任务完成时压 | 摘要干净，时机不可预测 |

编码 Agent 默认「滑动窗口 + 结构化摘要」；会话有清晰阶段（调研→实现→测试）时用任务边界触发。

### 用探针评估，不用指标

ROUGE 或嵌入相似度抓不住功能性质量：一段摘要可以词面重叠很高，却丢了 Agent 继续工作唯一需要的那个路径。压缩后提问，测关键信息是否幸存：

| 探针 | 测什么 | 示例 |
|---|---|---|
| 回忆 | 事实保留 | 「最初的报错信息是什么？」 |
| 产物 | 文件追踪 | 「我们改了哪些文件？」 |
| 续接 | 任务规划 | 「下一步该做什么？」 |
| 决策 | 推理链 | 「Redis 的问题我们怎么定的？」 |

### 六个维度评分

准确性（路径、函数名、错误码对不对）；上下文感知（反映当前对话状态）；产物轨迹（知道读过/改过哪些文件）；完整性（回答覆盖问题的所有部分）；连续性（不重取就能继续）；指令遵循（尊重约束）。准确性与产物轨迹最能区分方法。

## 实践指引

**大代码库的三阶段压缩。** 调研阶段：探索架构图、文档、关键接口，压缩成组件/依赖/边界的结构化分析，产出一份替代原始探索的调研文档。规划阶段：把调研文档转成带函数签名、类型定义、数据流的实现规格；500 万 token 的代码库在这一步压到约 2000 词。实现阶段：对着规格执行，上下文只有规格加活跃文件，很少再需要压缩。

**用示例产物当压缩种子。** 有人工迁移示例或参考 PR 时，把它当模板理解目标模式，而不是从零探索。示例揭示静态分析给不出的约束：哪些不变量必须成立、哪些服务会被改坏、干净的实现长什么样——它隐式编码了本质复杂度与偶然复杂度的区别。

**锚定迭代摘要的实施步骤。** 1) 按领域定义显式章节；2) 首次触发时把截断的历史摘要进这些章节；3) 后续只摘要新截断的内容，不重摘已有摘要；4) 按文件路径和决策身份去重，合并进已有章节而不是再生；5) 标记每条信息来自哪个压缩周期，摘要漂移时能调试。

**按会话画像选方法。** 锚定迭代：100+ 消息、文件追踪重要、需要验证保留了什么。不透明：要极致压缩、会话短、重取便宜（如无文件系统访问）。再生：人要审阅摘要、阶段边界清晰、每次触发能接受全量回顾。

**压缩比校准（某基准的数据，不是常数）：** 锚定迭代 98.6% / 质量 3.70；再生 98.7% / 3.44；不透明 99.3% / 3.35。只要存在重取成本，权衡通常偏向结构化方法。

## 准则

1. 优化每任务 token，不是每请求 token
2. 用带显式章节的结构化摘要追踪文件
3. 在 70–80% 占用触发压缩
4. 增量合并而不是全量再生
5. 用探针测压缩质量
6. 文件追踪关键时单独维护产物轨迹
7. 为更好的保留接受略低的压缩比
8. 把重取频率当质量信号

## 坑

1. **绝不压缩工具定义或 schema。** 参数名和类型被摘要掉，Agent 就无法调用工具。工具定义是绕过压缩的不可变锚点。
2. **压缩后的摘要会编造事实。** 摘要器可能引入原文没有的貌似合理的细节。丢弃原文前，对照源材料验证——尤其是路径、错误码和数字，摘要器会「四舍五入」或捏造。
3. **压缩会弄坏产物引用。** 路径、提交 SHA、变量名、代码片段被改述或丢掉。「更新了配置文件」而 Agent 需要的是 `config/redis.ts`，就要重新探索。标识符逐字放在专用章节，不埋在散文里。
4. **早期轮次含不可再生的约束。** 前几轮常有任务设定、用户约束、架构决策，无法重新推导。保护早期轮次不被压缩，或把约束抽成在所有压缩周期都存活的持久前言。
5. **激进比率跨周期复利。** 单次 95% 看着安全，三个周期后只剩 0.0125%。按多周期校准比率。
6. **代码和散文需要不同的压缩。** 散文冗余、可压；代码不行——函数签名或导入路径少一个 token 就废。散文激进摘要，代码块和结构化数据逐字保留。
7. **探针评估给假信心。** 探针只测它问的东西。只查文件名不查函数签名的探针集会漏掉签名丢失。探针覆盖六个维度，并跨评估轮次轮换探针集。

## 参考

- [references/evaluation-framework.md](references/evaluation-framework.md)：四类探针的结构与示例、六维评分量表、LLM 评审配置与输入输出格式、基准结果与统计注意事项。
- 同系列：上下文退化诊断（context-degradation-zh）、记忆系统（memory-systems-zh）、会话交接单（handoff-doc-zh）。

---
改编自 [Agent Skills for Context Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering) 的 `context-compression`（MIT）。改动见 ATTRIBUTION.md。