上下文压缩（Compaction）

概述

上下文压缩是 Anthropic 官方推出的服务端上下文管理策略，当长时对话接近上下文窗口限制时，自动将旧内容压缩为简洁摘要，替换原始历史记录，从而扩展有效上下文长度。这是 Context-Engineering 中三种长时任务技术（Compaction / 结构化笔记法 / 多 Agent 架构）的官方 API 实现。

关键内容

核心机制

启用压缩后，Claude 自动执行四步流程： 1. 检测输入令牌超过配置的触发阈值 2. 生成当前对话的摘要 3. 创建 compaction 块包含摘要内容 4. 继续以压缩后的上下文完成回复

后续请求中，API 自动丢弃 compaction 块之前的所有消息，从摘要继续对话。一次长时间对话可能产生多次压缩，最后一个压缩块反映最终状态。

触发配置

参数	类型	默认值	说明
`type`	string	必填	必须为 `"compact_20260112"`
`trigger`	object	150,000 tokens	何时触发压缩，最低 50,000 tokens
`pause_after_compaction`	boolean	`false`	生成摘要后是否暂停，允许客户端注入额外内容
`instructions`	string	`null`	自定义摘要提示词，完全替换默认提示

默认摘要提示词

You have written a partial transcript for the initial task above.
Please write a summary of the transcript. The purpose of this summary
is to provide continuity so you can continue to make progress towards
solving the task in a future context...

自定义指令通过 instructions 参数完全替换默认提示，而非追加。

pause_after_compaction 模式

启用后，API 在生成压缩块后返回 stop_reason: "compaction" 并暂停。这允许客户端： - 保留最近的消息原文（不被摘要替换） - 注入特定的指令类消息 - 在 API 继续前添加额外内容块

令牌预算控制：结合 pause_after_compaction 与压缩计数器，可估算累计消耗并在达到预算时优雅结束任务：

if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
    messages.append({"role": "user", "content": "Please wrap up..."})

与提示词缓存的协同

压缩与提示词缓存配合效果良好： - 在压缩块上添加 cache_control: { type: "ephemeral" } 可缓存摘要内容 - 关键优化：在系统提示词末尾添加 cache_control 断点，使系统提示与对话分开缓存 - 压缩发生时：系统提示缓存保持有效，只需将压缩摘要写入新缓存条目 - 这对长系统提示词特别有益，即使多次压缩事件仍保持缓存

流式处理差异

压缩块的流式传输与文本块不同： - 收到 content_block_start 事件 - 随后是单个 content_block_delta 包含完整摘要（无中间流式） - 最后收到 content_block_stop 事件

计费与用量

压缩需要额外的采样步骤，计入速率限制和计费： - usage.iterations 数组显示每次采样的用量 - 发生压缩时：compaction 迭代 + 主 message 迭代 - 顶级 input_tokens / output_tokens 不包含压缩迭代用量 - 计算总消耗需对 usage.iterations 所有条目求和 - 重新应用之前的 compaction 块不会产生额外压缩成本

支持模型

Claude-Mythos-Preview (claude-mythos-preview)
Claude-Opus-4-6 (claude-opus-4-6)
Claude-Sonnet-4-6 (claude-sonnet-4-6)

当前限制

同模型摘要：请求中指定的模型同时用于摘要生成，无法使用更便宜的模型
Beta 阶段：需要 beta 标头 compact-2026-01-12
零数据保留：符合零数据保留 (ZDR) 条件

与其他长时任务技术的对比

Context-Engineering 描述了三种长时任务技术：

技术	适用场景	控制粒度
上下文压缩（Context Compaction）</td> <td>Compaction	需要流式回话的复杂推理
结构化笔记法	有明确里程碑的迭代开发	客户端 Agent 写入持久存储
多 Agent 架构	需要并行探索的复杂研究	子 Agent 返回精简摘要

Compaction 是最"开箱即用"的方案，但牺牲了对压缩内容的精细控制。结构化笔记法和分层记忆架构提供更多控制权，但需要更多集成工作。

Hermes Agent 客户端压缩

Hermes Agent 实现了客户端侧的上下文压缩策略，与服务端 Compaction 形成对比：

触发条件：会话历史接近模型上下文窗口上限时，context_compressor.py 自动触发
压缩策略：识别可压缩的工具输出（通常最冗长）→ 辅助 LLM 摘要压缩 → 压缩后历史继续会话
递增压缩：优先压缩最早和最冗余的工具输出，保留最近消息完整
辅助 LLM：通过 auxiliary_client.py 使用独立辅助 LLM 执行压缩，不阻塞主流程
与迭代预算协同：Token 消耗跟踪与压缩触发阈值配合，共同管理会话资源

来源

raw/articles/ai-engineering/anthropic-engineering/Compaction.md — Anthropic 官方文档
02_hermes_architecture.md — Hermes Agent 深度解析系列第二篇，2026 年 4 月版本
raw/articles/ai-engineering/anthropic-engineering/claude-engineering/04_context_engineering.md — Anthropic Applied AI 团队上下文工程分析（2025 年 9 月）
raw/articles/ai-engineering/anthropic-engineering/claude-engineering/09_effective_harnesses.md — Harness 设计中的会话交接（Handoff）机制