本文是「Agent 开发实践与思考」系列第 16 篇。系列目录：

• 2024
  • 07-02 我手写了一个 Agent：从一问一答到”思考-行动-观察”循环
  • 08-06 工具调用踩坑记：schema、描述与错误返回怎么写
  • 09-10 系统提示词写到几千字之后：让 Agent 迁移 Vue 业务与资产到 React
  • 10-15 给 Agent 做记忆：分层、状态与遗忘
  • 11-01 迁移知识库的 embedding 召回评测方法
  • 11-19 迁移经验检索的工程细节：混合检索、重排与拒答
  • 12-24 上下文窗口的成本课：KV Cache、Prompt Caching 与消息顺序
• 2025
  • 01-28 长任务不失忆：把 Vue 转 React 做成可验证的迁移流程
  • 02-25 MCP 用了三个月：工具标准化之后 Agent 设计变了什么
  • 03-25 拆解 Coding Agent：为什么”写代码 + 文件系统”是通用 Agent 的内核
  • 05-13 Agent 如何用代码完成推理、校验、适配与展示
  • 06-03 能看会说的 Agent：语音交互与 Computer Use 这半年
  • 06-24 从同步问答到事件驱动：异步 Agent 的架构改造笔记
  • 07-08 没有评估就没有迭代：我的 Agent 评估落地记
  • 09-09 后训练扫盲：SFT 记知识、RL 学长处，和 Agent 有什么关系
  • 10-01 AI Coding 上下文摘要的递归压缩、原文保留与回退策略（本篇）

AI Coding 上下文摘要的递归压缩、原文保留与回退策略

编程 Agent 会持续读取文件、搜索、执行命令和修改代码。工具返回和构建日志会占用上下文窗口，并逐渐覆盖较早的用户要求。增大窗口只能延后这一问题，无法永久保留全部原始历史。

Claude Code、Gemini CLI 与 OpenHands 都会压缩较早的对话，并保留最近一段原文。再次达到阈值后，系统将旧摘要与新增对话再次压缩，在有限窗口内维护可继续执行任务的状态。

本文对照 Claude Code、Gemini CLI 和 OpenHands 的实现，讨论触发时机、压缩范围、摘要内容、摘要与消息的拼接方式，以及历史回退。

文中包含调研期间观察到的产品行为、请求样本和可读源码信息。Claude Code 的细节可能随版本调整，以下内容仅描述调研时的实现，不构成稳定接口说明。

递归摘要与最近原文的组合

长对话首次超过阈值时，系统将较早历史交给摘要模型，生成结构化摘要，同时保留接近当前任务的几轮原文。后续对话继续增长时，系统将上一次摘要、新产生的消息和更早的可压缩部分再次归纳，而不重新处理全部原始记录。

第一次压缩后，早期历史由摘要表示，最近原文仍保留在上下文中。第二次压缩时，系统将上一份摘要和新增的可压缩历史归纳为新摘要，并保留更新后的最近原文。

最近原文保留用户刚刚提出的要求、正在修改的文件、最新工具输出和未完成动作。摘要会损失细节，因此这些内容需要保留原文。实践中常见的保留范围为最近 5 到 20 轮，具体数量随上下文余量调整。

系统应先尝试生成摘要；摘要后仍超限时，再裁剪不重要的内容。提前裁剪可能删除用户意图或任务状态，后续无法从摘要中恢复。

上下文压缩的触发阈值

产品对阈值的选择不同。

Gemini CLI 的自动压缩阈值是模型上下文上限的 70%。它压缩较早的约 70% 历史，保留后面的约 30%，同时将切分位置移动到完整对话轮次的边界，避免在模型回复或工具返回中间截断。它也支持手动强制压缩。

Claude Code 的实现中，阈值约为可用上下文的 92%。它会保留最近若干轮原文；轮数根据剩余空间调整，不是固定常量。

70% 阈值会预留更多空间给摘要和后续工作，但需要更频繁地调用摘要模型。接近上限才触发可以减少压缩次数，却要求系统准确估计本轮输入、工具描述和模型输出将占用的 token。工程实现除百分比外，还应考虑系统提示词、工具定义、当前用户输入和预留输出长度。

Claude Code、Gemini CLI 与 OpenHands 的压缩实现

调研表除阈值外，还区分了压缩范围、保留或恢复的内容、首次和再次压缩的输入、摘要插入位置及提示词字段。Claude Code 的信息来自调研时的请求样本与逆向记录，版本变化后可能不同；Gemini CLI 和 OpenHands 的信息可与当时的实现对应。

摘要 Prompt 的字段与输入

Gemini CLI 使用五段 XML：overall_goal、key_knowledge、file_system_state、recent_actions 和 current_plan。提示要求检查用户目标、Agent 操作、工具输出、文件改动和未解决问题，再输出高密度快照。后续 Agent 只能看到该快照所代表的历史，因此提示要求去掉对话填充，保留关键事实、计划、错误和指令。

Claude Code 的提示更长，输出仍为八段结构。除用户目标、技术概念、文件与代码段、错误与修复、问题处理、所有用户消息、待办和当前工作外，提示还要求给出紧贴当前任务的下一步。调研样本中，提示要求按时间顺序检查对话，特别保留文件名、代码片段、函数签名、文件改动、错误处理，以及用户否决过的做法。

OpenHands 不按固定业务字段划分摘要，而是将已有摘要和待遗忘事件组成输入。它保留事件边界和 ID，使运行时可以确定摘要替代的历史范围。RecentEventsCondenser 不使用 Prompt，只裁剪事件。

OpenHands 将压缩分为三层。ConversationWindowCondenser 处理显式压缩请求并保留重要的头尾事件，BrowserOutputCondenser 先限制浏览器输出，最后由 LLMSummarizingCondenser 生成摘要。该顺序减少送入摘要模型的浏览器正文，并限制无关页面内容进入长期上下文。

Coding Agent 摘要需要保留的状态

普通聊天摘要主要保留结论。Coding Agent 的摘要还需要支持后续任务继续执行，因此要保存目标、工作状态和待办。

Claude Code 的摘要提示要求覆盖以下信息：

1. 用户最初的目标，以及后续明确修改过的要求。
2. 技术栈、代码约定、架构决定和关键限制。
3. 已读取、创建、修改、删除的文件，以及重要代码位置。
4. 重要工具调用、报错、已经尝试过的修复和结果。
5. 未完成的任务，以及当前正在进行的工作。

Gemini CLI 将这些信息固定为 XML：overall_goal、key_knowledge、file_system_state、recent_actions 和 current_plan。Claude Code 的结构更细，单列用户消息、错误与修复、当前工作和下一步。两者均按目标、事实、文件状态、过程和待办组织摘要。

字段约束有助于控制摘要内容。缺少结构时，模型可能将大量篇幅用于已完成的讨论，遗漏文件路径、失败原因或用户刚否决的方案。结构化摘要将这些信息显式列出，也为后续评估提供检查项。

以完整消息单元确定压缩边界

Agent 对话包含用户和助手消息、工具调用及工具结果。一次模型回复可能紧跟多个工具调用，工具结果又是下一步推理的依据。按 token 位置切分，可能留下没有调用来源的工具结果，或保留没有结果的工具请求。

压缩边界应以完整交互单元确定。助手消息、其工具调用和工具结果应一起进入摘要或一起保留。Gemini CLI 选择压缩边界时会继续向后寻找下一条用户消息，以避免破坏一轮对话。对于并行工具调用，边界还应覆盖同一批调用及其全部返回。

工具输出可以按类型处理。长日志、目录列表和网页正文通常首先占满上下文。OpenHands 先限制浏览器输出，再处理整段对话。先缩小明显噪音可以减少摘要模型输入，并降低无关信息进入长期记忆的概率。

摘要消息与用户界面中的历史

摘要通常作为一条合成消息插入系统提示词和当前用户问题之间，随后接保留的原始消息。Gemini CLI 会先放入环境上下文，再以用户消息写入结构化快照，并用一条简短的模型确认消息衔接后续历史。主模型接收到的仍是连续对话，不需要额外处理特殊存储协议。

用户界面是否展示摘要是另一项产品选择。

服务端隐藏摘要时，前端继续显示完整聊天记录，摘要只参与模型上下文拼接。用户看到的聊天历史不会被自动改写，但无法直接检查摘要是否遗漏信息。

另一种做法是将摘要返回插件端，使历史区域可以在原始消息和摘要之间切换。用户可以检查系统保留的信息，并在摘要错误时反馈；界面中需要将摘要与用户原话明确区分。

生成摘要后，原始消息仍应保留。摘要用于模型工作记忆，原始消息用于审计与回退。

递归摘要的回退和持久化

单次摘要的实现相对直接。用户回退到较早的对话分支，或同一会话连续压缩多次时，需要维护摘要与原始历史的对应关系。

一条摘要记录至少应包含：所属会话、生成摘要的对话轮次、压缩前后的 token 数、使用的策略、当前是否有效、失效原因，以及由用户还是系统触发。保存原始内容，或至少保存可追溯的轮次范围，才能在回退时找到受影响的摘要。

在递归摘要中，新摘要生效后，旧摘要仍可能对应用户后来切回的分支。实现可记录状态和失效原因，例如因生成新摘要失效或因用户回退失效。回退发生时，包含被回退轮次的摘要失效，再恢复该分支上最近仍可用的摘要。

需要区分两份数据：用户可见的完整对话，以及供模型调用的压缩上下文。前者是产品记录，后者是一次调用的派生状态。将二者放在同一份可变消息列表中，会增加回退、重放和排查的复杂度。

摘要模型的输入窗口、质量和延迟

摘要模型不一定需要使用能力最强的模型，但其上下文上限必须覆盖待压缩输入。摘要模型的上下文上限应大于主模型允许的历史输入，否则摘要模型会先拒绝请求。

选择摘要模型时，通常需要权衡输入窗口、摘要质量、延迟、成本和稳定性。摘要位于用户等待链路中，较高延迟会拉长正常问答；摘要质量不足会导致后续任务缺少必要状态。适合摘要的模型应输出稳定、速度足够快，并能处理主链路可能提交的最大历史段。

摘要提示词不应要求模型等量保留全部内容。较早讨论可以更短，重复工具输出和已无关的尝试可以省略；用户指令、未解决错误、文件改动和当前计划需要依据输入保留。摘要模型负责删除冗余，不能补全未见的事实。

上下文摘要的实现范围

上下文压缩包含消息筛选、边界选择、结构化摘要、递归替换、提示词拼接、持久化、回退和可观测性。

不同产品的实现细节不同，但都将早期历史压缩为摘要，并保留当前任务相关的最近原文。递归摘要记录已发生的工作，最近原文保留当前的用户要求、文件状态和工具输出。两部分分别维护，才能降低长任务在压缩后丢失任务状态的风险。