context-compression

name	context-compression
description	当上下文膨胀接近窗口上限、Agent 决策质量随上下文变长而下降（上下文腐化）、或需要主动为上下文做减法时使用。核心目标：在保留决策/约束/失败/来源的前提下提高历史信息密度。不适用于静态前缀设计（见 context-kv-cache-friendly）或状态提炼注入（见 context-status-bar）。

上下文压缩（Context Compression）

角色与读者

面向构建长程任务的 Agent 开发者。本 Skill 服务的目标：为上下文做减法——什么时候压、怎么压、为什么即使上下文没满也应该压。核心认识：压缩是把臃肿的原始记录换成算好的结论，与状态栏是同一枚硬币的两面（都在给"只有一半的检索引擎"补上缺失的"提炼"）。

核心原则（配正例/反例）

1. 三个压缩动机（不只是长度）

   • ① 解决长度/成本约束（窗口有限、token 越多成本越高）；② 提升思考质量（总结后的知识比原始形式更利于模型使用）；③ 缓解"上下文焦虑"（模型怕窗口耗尽提前收尾，在未接近耗尽时提前压缩可提升决策质量）。

2. 压缩要"上下文感知"（把查询意图和已有信息纳入压缩决策）

   • 正例：压缩提示写 Given the search query: {query} + Current context: {context}，生成针对性摘要。
   • 效果：实验对比中上下文感知压缩仅 40K token/7 轮（压缩率 3.0%），无感知的个体摘要需 277K token/12 轮（10.9%），组合摘要 93K/10 轮（4.3%）。相比无压缩省 76% token 且并列最少迭代。

3. 压缩与 KV Cache 的关系：发生在两次 API 调用之间，批量压缩

   • System Prompt + Tool Definitions 永远不动；压缩对象是对话历史中的 tool results（替换位置之后缓存失效，之前仍有效）。
   • 正例：接近阈值（如 80%）时一次性批量压缩所有未标记工具结果，加 [COMPRESSED] 标记防重复处理。
   • 反例：每轮都压 → 频繁破坏缓存。

4. 保留四类信息：决策、约束、失败、来源（引用）

   • 压缩最易丢失的是早期架构决策、约束背后理由、失败路径。语义完整性："Sutskever 于 2024 年 5 月离开 OpenAI" 不能压成 "Sutskever 离开"（时间、公司名不可丢）。
   • 带引用（每条事实附来源 URL）实现"有损语义压缩 + 无损索引"。

5. 隔离优于压缩：子 Agent 上下文隔离

   • 大体积中间信息（代码库大范围搜索）委派给独立子 Agent，只回传几百 token 结论摘要，噪声从一开始就不进主上下文。
   • 对比：压缩是有损、需额外 LLM 调用的事后补救；隔离让主 Agent 的 KV Cache 前缀完全不受影响。

执行流程（SOP 检查清单）

1. 判断是否该压：接近窗口阈值？决策质量下降（上下文腐化）？模型焦虑提前收尾？
2. 选策略：上下文感知压缩（带 query + context）为默认；信息需溯源时加引用；任务初期空间充足时用自适应窗口（<80% 保留原文）。
3. 分层压缩（生产级，Claude Code 参照）：
   • 工具结果预算控制（大输出存磁盘，模型看摘要预览，替换字符串冻结）→ 噪声直接删除（低价值内容不做摘要）→ API 层微压缩（服务端移除指定工具结果，适合即将溢出时）→ 归档式摘要（逐轮结构化摘要，像 git log 保留独立记录）→ 全量压缩（最后手段，配连续失败熔断器）。
4. 保留决策/约束/失败/来源；批量触发而非每轮压。
5. 验证：压缩后任务成功率、token 用量、是否丢关键信息。

禁止清单（写清合法例外）

• 禁止无感知压缩（个体摘要信息碎片化、组合摘要超长截断丢末尾信息）。例外：把查询意图和已有信息纳入压缩决策。
• 禁止每轮压缩（频繁破坏缓存）。例外：接近阈值时批量压缩。
• 禁止对噪声做摘要（低价值内容直接删除，做摘要只是浪费 token）。例外：只对仍有信息价值的内容压缩。
• 禁止压缩丢失语义完整性（时间、公司名、否定词、条件不可丢）。例外：带引用（保留源链接）可无损索引回溯。
• 禁止让 Agent 把进展零散放执行历史（应定期文档化，否则压缩时丢早期决策/失败路径）。例外：用 prompt/skill 提醒模型记录和更新文档。

参考资料

• 本书第 2.7 节《上下文压缩策略》（三个动机、检索而非推理、六策略对比、生产级分层压缩、四条设计原则、隔离优于压缩）。
• 笔记 02-上下文工程.md 第 2.7 节。
• Anthropic "Harness design for long-running application development"（分层压缩与上下文焦虑）。