【Claude Code-上下文实测】Server-side compaction 不是魔法摘要：pause_after_compaction 与长会话状态迁移

非线智能API经验 [Claude Code-上下文实测] 第16篇

摘要

Anthropic 的 server-side compaction 把长会话压缩从应用层摘要提升为平台能力：当输入超过阈值时，旧上下文可以被替换成摘要，从而让 agent workflow 继续运行。这个能力对长时 coding agent 很重要，因为它可以减少应用自己拼接、摘要和裁剪历史的负担。

但 compaction 不是无损压缩。它本质上是在把一段执行历史迁移成新的状态表示。pause_after_compaction 的价值正在于此：压缩完成后先暂停，让应用有机会检查摘要、补充关键约束、保留近期消息或保存 checkpoint，再决定是否继续。也就是说，server-side compaction 不是“自动变短”这么简单，而是需要被治理的状态转换。

数据来源：非线智能Nonlinear 官网

证据层级

Anthropic Compaction 文档、Automatic Context Compaction cookbook、Context Engineering cookbook 和 Bedrock Compaction 文档可以支撑 compaction、pause_after_compaction、压缩后继续请求等机制事实。Pydantic AI 等 SDK 文档适合说明上层框架如何包装这些配置。带工具 agent 的压缩风险，则应结合 Anthropic / AWS 关于 tool use 的官方文档和实际工程经验来写。

本文不把某个 SDK 的默认阈值写成 Anthropic API 的全局默认行为，也不把 compaction 描述成无损历史存储。

compaction 解决的不是长度，而是状态承载

长会话 agent 如果一直 append history，会遇到三个问题：

问题	表现
输入 token 持续增长	每轮请求越来越贵、越来越慢
上下文上限	到达模型窗口后无法继续
低信号历史污染	旧日志、过期假设、已解决错误仍影响推理

compaction 的直接目标是减少输入体积，但它更深层的作用是把“完整执行历史”转换成“继续执行所需状态”。这和压缩一个文本文件不同。coding agent 的历史里有用户约束、文件状态、工具调用结果、失败根因、计划变更和未完成任务；压缩时真正要保住的是这些状态，而不是每一句历史对话。

server-side compaction 的基本模型

一个简化的 compaction 流程可以理解为：

1、应用继续发送长会话历史。
2、服务端检测输入超过配置阈值或上下文管理策略触发。
3、旧消息被归纳成较短的 compacted context。
4、新请求携带压缩后的上下文继续执行。
5、如果开启暂停策略，服务端在压缩后返回，让应用检查或补充状态。

这带来两个工程变化。

第一，应用不必完全自己维护所有历史裁剪逻辑，但仍要决定哪些内容必须保留、如何检查摘要、压缩后是否继续。第二，压缩结果变成新的事实来源。后续模型看到的不再是原始历史，而是摘要后的历史。

pause_after_compaction 的真正含义

pause_after_compaction 很容易被理解成一个控制流开关：压缩后先停一下。但它的产品含义更重要：压缩摘要需要应用层介入。

压缩后暂停可以做这些事：

动作	目的
检查摘要	确认用户硬约束、当前目标、关键决策没有丢
注入补充消息	把不可违反约束、最新 diff、测试状态重新写入上下文
保存 checkpoint	记录压缩前后摘要、时间、token、会话 id
审计风险	对安全、权限、外部写入任务做人工或程序检查
调整后续策略	决定继续、重新压缩、切新会话或请求用户确认

如果压缩后立刻继续生成或调用工具，应用就失去了这次检查机会。对普通问答这可能没关系；对长时 coding agent，压缩遗漏可能直接导致错误修改、重复工作或违反用户约束。

压缩是有损状态迁移

compaction 的核心风险是“摘要看起来合理，但状态不完整”。常见丢失点包括：

丢失点	后果
用户硬约束	后续修改违反用户明确要求
权限边界	agent 执行不该执行的命令或外部写入
已排除方案	模型重复尝试失败路径
测试失败根因	修复方向漂移
文件版本信息	基于旧代码继续推理
工具结果完整性	把截断结果当成完整事实
未完成 TODO	长任务中途丢项
原始证据引用	无法复盘摘要是否正确

因此，不应把 compacted summary 当成完整历史的无损替代品。更合适的理解是：它是一个新的执行状态，需要有 schema、质量门槛和审计引用。

带工具 agent 的特殊风险

coding agent 通常带有 tools。压缩这类历史时，要额外注意三件事。

第一，压缩摘要阶段应明确要求只输出文本摘要，不调用工具。否则摘要流程可能与正常 tool use 流程混淆，尤其是在应用层把“模型输出包含 tool call”作为统一执行路径处理时。

第二，未闭合的工具状态不能被随意压缩。Anthropic tool use 协议中，tool_use 和后续 tool_result 有配对关系；如果压缩或清理破坏了这个状态机，后续请求可能报错或产生错误推理。

第三，工具结果本身也要分级。完整测试日志、大文件内容、MCP 输出不应长期留在上下文里，但它们也不能只被一句“测试失败”替代。至少要保留命令、退出码、关键错误、相关文件、原始日志引用和截断状态。

压缩摘要模板

推荐把压缩摘要做成固定字段，而不是自由散文：

{
  "task": {
    "user_goal": "当前用户目标",
    "done_definition": "完成标准"
  },
  "constraints": {
    "must_keep": ["用户硬约束", "权限边界", "不要修改的文件"],
    "must_not_do": ["禁止动作"]
  },
  "verified_facts": [
    {
      "fact": "已验证事实",
      "evidence": "命令 / 文件 / 链接 / 工具结果引用",
      "freshness": "current | stale | unknown"
    }
  ],
  "decisions": [
    {
      "decision": "已做决策",
      "rationale": "理由",
      "alternatives_rejected": ["被排除方案"]
    }
  ],
  "code_state": {
    "changed_files": ["path/to/file"],
    "critical_locations": ["path/to/file:line"],
    "diff_summary": "关键改动摘要"
  },
  "tool_state": {
    "open_tool_calls": [],
    "archived_outputs": [
      {
        "tool": "run_tests",
        "status": "error",
        "summary": "关键失败",
        "raw_ref": "artifact/log.txt",
        "truncated": false
      }
    ]
  },
  "open_questions": ["未解决问题"],
  "next_steps": ["下一步动作"]
}

这个 JSON 不一定要原样发给模型；它可以是内部 compact checkpoint，再渲染成适合目标 provider 的文本。但字段顺序和语义应保持稳定，方便检查、diff 和缓存。

质量门槛

压缩摘要至少要满足五个门槛：

门槛	要求
可继续	另一个 agent 只读摘要也能知道下一步做什么
可判定	能区分已完成、未完成、已验证、未验证
可定位	保留关键文件、函数、测试名、命令或链接
可复盘	保留原始证据引用、hash、artifact 路径
可过期	标注事实新鲜度，避免旧信息伪装成当前状态

如果摘要无法满足这些要求，压缩虽然降低了 token，但会提高任务失败概率。

与应用层 memory 的分工

server-side compaction 不应替代应用层 memory。更稳健的结构是：

层	存什么
Provider compaction	压缩旧对话，让请求继续运行
Task checkpoint	当前目标、约束、决策、下一步
Tool audit log	原始工具输入输出、hash、错误、成本
Artifact store	完整日志、截图、长文件片段
Prompt cache layer	稳定前缀、工具定义、项目规则

Provider compaction 负责“上下文还能放得下”；应用层 memory 负责“状态能被可靠恢复”。两者不能互相替代。

失败模式

失败模式	触发原因	修复策略
摘要遗漏硬约束	自由摘要未区分约束和背景	固定 constraints 字段，压缩后检查
压缩后误调用工具	摘要阶段未约束输出形态	明确要求只输出文本 / summary block
工具状态机损坏	压缩未闭合 tool_use / tool_result	压缩前做 pending tool ledger 检查
无法复盘	原始日志只进摘要，没有归档	原文外置，摘要记录 raw_ref 和 hash
prompt cache miss	压缩改写稳定前缀	稳定前缀和动态历史分离
旧事实继续污染	摘要未标注时间和版本	记录 commit、mtime、运行时间和 freshness

验证清单

• 构造包含用户硬约束、工具结果、错误日志和文件修改的长会话，触发 compaction 后检查摘要完整性。
• 开启 pause_after_compaction，验证应用能在继续前注入补充约束。
• 构造未闭合工具调用，确认压缩前能够阻止破坏状态机。
• 构造长测试日志，确认摘要保留退出码、关键错误、相关文件和 raw_ref。
• 让另一个会话只读 compact checkpoint 继续任务，评估恢复质量。
• 比较自由摘要和结构化摘要在约束遗漏率上的差异。

工程结论

server-side compaction 是长会话 agent 的重要能力，但它不是无损存储，也不是上下文治理的全部。pause_after_compaction 应被视为状态迁移检查点：压缩完成后，应用要检查、补充、归档和决定是否继续。只有当 compaction、tool audit、task checkpoint 和 prompt cache 分工清晰时，长会话 agent 才能既省 token，又不丢状态。

参考链接

• Anthropic Compaction
• Anthropic Cookbook: Automatic context compaction
• Anthropic Cookbook: Context engineering, memory, compaction, and tool clearing
• AWS Bedrock: Compaction
• Anthropic Engineering: Effective context engineering for AI agents
• AWS Bedrock: Anthropic Claude tool use
• Pydantic AI Anthropic model docs

本文由非线智能API Claude Code 行业专家整理编写