最近这半年我基本上把主流 Coding Agent 都折腾了个遍从 Claude Code 到 OpenAI 的 Codex再到社区里口碑不错的 Pi项目做了一堆最后发现所有人都会撞上同一个天花板上下文窗口再大也不够 Agent 在一段长任务里反复挥霍。尤其是做多文件重构、跨模块排查问题这种活聊到后半程模型很容易把开头定下的约束忘得一干二净甚至开始对着已经改完的文件原地打转。所谓“上下文压缩”就是在不丢失关键信息的前提下把 Coding Agent 会话里越来越臃肿的历史记录做结构化精简。这篇文章我不打算只讲概念而是会把 Claude Code、Codex、Pi 这几个工具的上下文管理机制掰开揉碎再叠加我自己在自研压缩策略时踩过的坑和最终落地的方案。内容主要是给那些已经在真实项目里用 Coding Agent、每天被 token 消耗和上下文漂移折磨的同学有一定命令行基础就能直接照着改。1. 为什么要做 Coding Agent 上下文压缩1.1 token 成本与上下文窗口的双重压力先算一笔账。Claude Code 这类工具在每次模型调用时并不是只把“你最新输入的那句话”发过去而是把整段对话历史、当前打开的文件内容、工具执行结果全部打包进请求。假设一次重构任务要跟 Agent 来回沟通 50 轮平均每轮上下文有 80k token那这 50 轮累计消耗的 token 大概是 80k×50400 万 token而不是 80k。这个数字看着挺抽象换算成费用就很肉疼了按主流模型输出输入混合单价估算一次大型重构烧掉几十块钱人民币很正常。更麻烦的是上下文窗口的物理限制。Claude Code 长上下文模型可以支撑到 200k 级别Codex 和 Pi 这类工具通常也有几十 k 到上百 k 的窗口但窗口是共享的塞进去的无关信息越多真正留给代码分析、工具结果和新指令的空间就越少。我见过不少项目在长会话后期直接触发“上下文超限”要么工具强制要求精简要么干脆卡死最后只能手动清理历史重来整个思路全断了。所以上下文压缩最直接的价值就是让你在同一个 Agent 会话里干更久的活同时让每轮请求花的钱降到原来的十分之一甚至更低。别觉得这是后期优化项目一旦进入真实开发阶段这就是刚需。1.2 “Lost in the Middle”与模型注意力衰减还有一个很多人没注意到的问题叫 “Lost in the Middle”。大量实验都验证过大模型对长上下文里开头和结尾部分的信息记忆最牢而夹在中间的内容最容易丢失。Coding Agent 的会话恰恰是典型的“中间堆积”——开头是用户提的需求结尾是刚才报的错中间夹着几十轮修改记录、编译输出、文件 diff。于是模型经常出现一种诡异的表现你明明在第一轮就要求“不要改公共接口”改到第 30 轮它突然开始动接口签名而且不是它不理解是它真的“看不见”那条约束了。这种情况下单纯扩大上下文窗口并不能解决问题反而会让中间被稀释的信息更多。压缩的意义就在于主动把散落在中间的关键约束、决策和结论抽出来放到上下文的开头或注入到每次请求的 system prompt 里让模型在读取时天然更“靠前”地看到这些信息。我自己实测过在同样的任务上压缩后的会话比不压缩的长会话在约束遵守率上能提升一大截。1.3 压缩的本质不只是“删历史”很多人的第一反应是“压缩就是把对话记录总结一下嘛”这个思路只对了一半。直接让模型把历史总结成一段自然语言你会发现两个问题一是总结里全是“用户要求修改某模块”这种废话真正关键的代码行号、函数名、错误堆栈全丢了二是压缩后的信息没有结构Agent 后续读取时还得自己再从一段话里重新理解等于没省多少事。真正有效的压缩应当是一项系统工程需要做到三层第一层是摘要层把已完成的讨论和操作提炼成简洁的结论第二层是决策层把用户在过程中明确表达的技术选型、约束条件、放弃的方案单独记录下来第三层是索引层保留文件路径、函数名、关键 diff 这些结构化数据方便模型后续按图索骥。三个层次各司其职压缩才不会变成“信息事故现场”。2. 主流 Coding Agent 的上下文管理机制2.1 Claude CodeAuto Compact 与 /compact 指令Claude Code 的上下文管理在几个工具里算是做得最主动的。当会话接近窗口上限时它会触发 Auto-Compact由模型把前面的历史自动总结成一份摘要继续会话。这个机制的好处是完全自动不需要用户操心坏处是你无法控制它什么时候压缩、压缩时保留什么。我遇到过一次很尴尬的情况它在一次关键调试的中间触发了压缩把报错信息和复现步骤总结得很模糊后面整个排查方向就歪了。Claude Code 也提供了手动指令/compact你可以在触发压缩前指定压缩范围甚至把自己觉得不能丢的内容写在 prompt 里让压缩时优先保留。另外它有一个很好的习惯就是会把会话现场持久化到本地即使中途中断也能通过claude --resume恢复对话。它读取的CLAUDE.md文件相当于外部记忆库里面写清楚项目全局约定后Agent 每次启动都会强制加载这其实也是上下文管理的一种重要手段值得所有人在工程里用起来。2.2 OpenAI Codex会话重启与 context 文件OpenAI Codex 更像是一个“开发者主导上下文”的工具。它默认不会做太激进的自动压缩更多是依靠会话重启 外部指令文件的方式。你可以在项目根目录放AGENTS.md里面写明项目结构、编码规范、用户偏好Codex 在执行任务时会自动读取这些文件作为长期上下文。每次遇到上下文混乱最简单的办法就是重启会话让AGENTS.md和当前工作区文件重新成为主要上下文。这种策略的优点是可控性极强根本不会出现“系统偷偷压缩导致信息丢失”的问题缺点是依赖用户有足够强的文档习惯。如果你项目里的AGENTS.md写得很潦草那重启会话基本等于失忆一切要从头引导。所以在用 Codex 时我会把很多本该在对话里重复交代的内容像“测试命令是什么”“部署流程有哪些步骤”这类全部固化到AGENTS.md里减少对话历史的依赖。2.3 Pi轻量化 Coding Agent 的上下文保留Pi 在社区里的定位偏向轻量、快速适合在 CI 流水线或者快速脚本任务里运行。它的上下文管理也延续了这种轻量化思路通常不会做特别复杂的历史保留而是聚焦在当前任务相关的文件和指令上。Pi 这种做法的好处是启动快、token 花费低坏处是在超长任务场景下显得后劲不足。用 Pi 做偏长任务时我一般会在指令文件里把“已完成状态”手动同步进去让 Agent 每一轮都能看到最新的进度快照而不是依赖对话历史里的旧信息。这其实就是一种人工上下文压缩把散落在历史里的状态提炼到文件里对话本身随时可以推倒重来。Pi 的项目如果能结合这种思路它轻量化的优势可以被放大很多。2.4 不同实现带来的启发我把这三个工具的上下文机制放在一起对比能明显看到一个共同趋势没有任何一个工具能完全靠内置机制解决长会话问题都需要外部记忆文件的配合。工具自动压缩手动指令外部记忆文件适合场景Claude Code有Auto Compact/compactCLAUDE.md长对话、复杂重构Codex弱主要靠重启会话命令AGENTS.md规约明确、文档完善的仓库Pi较少较少指令文件快速任务、CI 集成看完这个对比我基本确定了一件事与其被动等着工具内置的压缩机制“随机发挥”不如自己掌握压缩的节奏和控制力。这也是后面自研策略的出发点——反正每个工具最后都得读文件、读指令那我完全可以把压缩结果做成一个标准化的文件让所有 Agent 都能消费。3. 自研上下文压缩策略的完整拆解3.1 设计原则分层、保留决策、可回滚自研压缩策略我给自己定了三个原则缺一不可。第一是分层存储。对话历史不能只有一层“摘要”我会拆成三个层级短期缓冲区最近 5-10 轮原始消息、工作摘要整体进度、当前任务状态、长期记忆项目约束、架构决策、用户偏好三个层级按需分别注入模型。为什么要分层因为不同层级的更新频率和重要程度完全不同。短期缓冲区保证近期操作不丢失细节工作摘要让模型知道当前干到哪一步了长期记忆则防止关键约束被冲掉。混在一起压缩最后就是什么都不够精确。第二是保留决策而非保留过程。模型压缩对话时有个坏习惯喜欢把“用户说了什么”变成“用户想改什么”但决策里最值钱的是那个“为什么”。比如用户说“别用 SQLite改 PostgreSQL”过程是用户在抱怨性能决策是数据库选型变更。压缩时要记录的是决策结论、决策时间和影响范围而不是那一整段讨论。这样后续 Agent 即使看到冲突指令也能基于决策优先级做判断。第三是可回滚。任何压缩都可能压错所以我会把压缩前的原始对话完整保存成日志文件压缩后如果发现 Agent 开始胡说八道可以随时回滚到压缩前状态。这个原则很多自研方案都会忽略但实际用起来救命概率极高。3.2 结构化压缩的 Schema 设计压缩结果我会统一用 JSON 格式存储原因很简单JSON 天然结构化模型生成起来稳定解析也方便。下面是我在实际项目里用的一个精简版 schema{ version: 1.0, goal: 当前任务的总体目标不超过120字, done: [ 已完成事项1, 已完成事项2 ], current_state: 当前进度一句话描述, decisions: [ { time: 2025-01-12T10:20:0008:00, content: 数据库从SQLite切换为PostgreSQL, reason: 单机写入性能不足, scope: order-service模块 } ], constraints: [ 不允许修改公共API接口, 兼容Python3.9 ], files: { changed: [src/order/service.py], referenced: [src/order/models.py] }, errors: [ { time: 2025-01-12T10:30:0008:00, message: TypeError: unsupported operand type(s), resolution: pending } ], next_plan: [下一步计划1, 下一步计划2] }这个 schema 看似简单实际使用中每个字段都有讲究。比如goal字段限制 120 字是为了防止模型把目标写成一篇小作文压缩后反而抓不住重点decisions里的scope字段是我后来加的因为同一个项目里经常会有多个模块并行改没有范围标注模型很容易把 A 模块的决策套到 B 模块上。files字段单独拎出来特别重要。Coding Agent 干活期间真正需要长期记住的其实不是“我们聊了什么”而是“我们改了哪些文件、看过哪些文件”。文件路径是比自然语言更可靠的记忆锚点模型看到src/order/service.py时能直接定位代码效率远高于读一段“用户修改了订单服务里的某个函数”这种话。3.3 压缩评估哪些信息必须保留光有 schema 还不够模型在压缩时必须知道什么该留什么该丢。我设计了一套简单的打分规则给每条历史消息计算一个保留优先级分数低于阈值才允许被压缩掉。打分维度主要看四条消息里是否包含用户明确表达的约束权重最高、是否与当前报错链路相关、是否包含关键代码 diff 片段、是否被用户手动标记过keep。我实际用下来这个权重配比比较稳维度权重说明包含约束/决策0.4一旦丢失后续指令可能直接冲突与错误堆栈相关0.3排查思路断裂会前功尽弃包含关键 diff 或函数签名0.2方便模型精确定位改动点用户手动标记0.1用户明确不想丢的必须保留当一条历史消息的总分超过 0.5 时我会把它原样放进短期缓冲区而不是丢给模型去做摘要。这套打分规则我最初是靠人工标注试出来的后来发现完全可以在压缩时让模型自己先对历史消息做一轮初步评分再按阈值决定保留还是摘要。虽然多花了一点模型调用但压缩质量明显更稳定。3.4 触发时机与策略压缩时机选得好不好直接影响整个会话的连贯性。我试过两种常见触发方式固定轮数触发和固定 token 阈值触发最后发现必须组合使用再加一个手动兜底。固定 token 阈值是最保底的方案。我会在 Agent 每次执行工具调用后估算当前上下文 token 总量当用量超过窗口上限的 75% 时自动触发压缩。为什么是 75% 而不是 90%因为压缩本身也要消耗 token压缩生成的摘要和中间结果会先把上下文推到更高水位留出充足余量才不会导致压缩到一半爆掉。固定轮数触发用于提前“主动瘦身”。即使 token 还没到阈值每执行 15 轮工具调用后我也会强制做一次轻量压缩把已经完成的步骤吸入done字段让短期缓冲区始终保持在比较清爽的状态。手动触发则是给用户留的保险比如 Agent 明显开始跑偏时直接输入/compress命令强制做一次完整压缩。这里有个很关键的实操心得不要在 Agent 正在执行多文件批量修改的中间步骤触发重压缩。那会儿模型的短暂记忆里全是待写入的 diff一压缩很容易把“下一步要写哪个文件”这种状态弄丢。我通常会让压缩命令等待当前工具调用结束再在下一轮开始前执行。4. 实操过程与实现方案4.1 方案一提示词级压缩不写代码也能用先分享一个不写任何代码就能落地的方案适合想立刻改善现状、又不想折腾工程化的同学。这个方案的核心思路是把“压缩”这项任务直接交给 Coding Agent 自己通过提示词要求它在指定时机输出压缩结果并写入项目记忆文件。我以 Claude Code 为例会在CLAUDE.md或者项目专属指令文件里加上类似这样的模板每完成 12 轮对话或用户输入 /compress 时你必须执行一次上下文压缩。 压缩要求 1. 将已完成事项写入项目根目录 .agent/memory.json 的 done 字段 2. 将明确的技术选型、约束和用户偏好写入 decisions 和 constraints 字段 3. 将最近涉及的文件路径更新到 files 字段删除已过时路径 4. 压缩后只保留最近 5 轮完整对话、压缩结果 JSON 以及本次任务目标 5. 禁止省略报错信息、复现步骤和未解决问题。Codex 用户则把同样内容写进AGENTS.mdPi 用户写到它支持的指令文件里。这个方案生效的前提是 Agent 得能读写文件好在主流的 Coding Agent 都默认支持工具调用问题不大。实测效果是加了这个指令之后一个原本 80 轮就发散的重构任务能稳定推进到 150 轮以上而且关键约束我故意测试了 30 轮后仍然能记住。缺点是 Agent 自己写 JSON 偶尔会格式歪掉所以读取时最好做一次容错不合法就直接忽略并让 Agent 重新生成。4.2 方案二中间层拦截会话自动执行压缩方案一依赖 Agent 的自律方案二则是把压缩做成一道外部工序在 Coding Agent 与模型 API 之间加一个中间层监听并拦截完整的消息列表在达到阈值时自动压缩后放行。这个方案的好处是任何 Agent 都能共用同一套压缩逻辑不依赖具体工具的提示词实现。整体流程可以用一段伪代码说明def round_handler(messages, tools, config): current_tokens estimate_tokens(messages) if current_tokens config.compact_threshold: compressed_messages compress_messages(messages, schemaconfig.schema) replace_conversation(compressed_messages) notify_user(已执行自动压缩) response call_model_api(messages, tools) return response这里我封装了一个简单的compress_messages函数传入完整的消息列表和压缩 schema调用一次模型让它把历史消息先做重要性评分再按 schema 输出 JSON 摘要。关键是把消息列表拆成三部分处理。def compress_messages(messages, schema): system_prompt build_compress_prompt(schema) history filter(messages, role ! system) recent history[-5:] old history[:-5] summary llm_call( systemsystem_prompt, messagesold, response_formatjson ) return [{ role: system, content: f上下文压缩结果:\n{json.dumps(summary, ensure_asciiFalse)} }] recent之所以保留最近 5 轮完整消息是为了保证当前正在进行的操作不丢细节。老的 500 轮历史则全部由一个system消息替代里面塞的是结构化压缩结果。这样下一轮模型看到的上下文大概只有 2-3k token而不是原来的 100k。中间层我推荐做成一个本地 HTTP 服务Coding Agent 通过配置 base_url 指向这个服务服务再转发到真实的模型 API 地址。这个模式让我能把压缩逻辑、token 统计、日志记录全部集中在一个地方管理调试起来非常方便。真实项目中这个中间层服务大概 200 行 Python 就能跑起来我强烈建议有工程能力的团队都试一次。4.3 方案三Memory Bank 向量检索的进阶策略方案二解决了“历史太长”的问题但还有一个隐患压缩后的 JSON 再结构化它也只是一份摘要当 Agent 需要回忆一个 300 轮前讨论过的细节时摘要里未必有。这时候就需要引入 Memory Bank 加向量检索的进阶方案。思路是这样的当 Agent 执行操作时中间层把所有关键的代码片段、错误信息、决策记录拆成小块每一块通过 embedding 模型转成向量存进一个本地向量数据库。压缩时不再把历史“揉成一团”而是“各归其位”。当新的一轮开始时中间层根据当前任务的语义从向量库里检索出最相关的 5-10 个记忆块拼装进上下文中。我用 SQLite 加sqlite-vec扩展就能实现一个轻量向量库完全不需要部署专门的向量数据库服务。写入侧的简化实现长这样import sqlite_vec import sqlite3 db sqlite3.connect(memory.db) db.enable_load_extension(True) sqlite_vec.load(db) def save_memory(content, embedding): db.execute( INSERT INTO memory(content, embedding) VALUES (?, ?), (content, embedding) ) def search_memory(query_embedding, top_k8): row db.execute( SELECT content FROM memory ORDER BY embedding ? LIMIT ?, (query_embedding, top_k) ) return [r[0] for r in row]检索到相关记忆后我会把它与压缩 JSON 一起注入系统提示词。这里有个重要的处理细节记忆块的注入要加时间戳和来源标记并明确告诉模型哪些是历史记忆、哪些是当前状态。不加区分的话模型很容易把几个月前的旧决策当成当前约束反而引发混乱。这个方案的压缩效果是最好的因为它不只是“减少 token”而是把上下文从“连续录音带”变成“按需点播的档案柜”。代价是实现复杂度高了不少需要处理 embedding 的存储、检索和定期清理。我的建议是先用方案二跑通流程确认收益后再进阶到方案三。4.4 与主流 Coding Agent 的接入配置三种方案最终都要落到实际工具里去用我整理一下接入要点。Claude Code 的接入最顺滑因为它支持自定义指令文件也支持读取环境变量。使用方案一最省事直接把压缩指令写进CLAUDE.md即可用方案二时把ANTHROPIC_BASE_URL指向中间层服务地址工具就能把请求转发到压缩层。注意用官方渠道拿到的 API 凭证和模型权限不要泄露到外部网关只要指向本地中间层就不涉及任何第三方转发。Codex 的接入路径类似它同样可以通过配置文件指定自定义 API Base URL并把AGENTS.md作为长期记忆载体。有一点需要提醒Codex 的会话体系里重启会话后工作区文件变化会被重新读取所以方案一里写进AGENTS.md的压缩结果要尽量保持精简否则反而会污染每次会话的初始上下文。Pi 类轻量工具的接入重点在指令文件路径通常只要把压缩模板放到项目根目录即可生效。但轻量工具的工具调用能力比 Claude Code 和 Codex 弱一些所以方案一的成功率会低一点我更推荐在 Pi 上使用方案二的中间层。这样 Pi 本身不需要理解压缩指令只要正常发请求压缩逻辑全部由中间层接管。5. 常见问题与排查技巧实录5.1 压缩后信息丢失Agent 忘掉关键约束怎么办这是我被问得最多的问题也是自研压缩最容易翻车的场景。症状很典型压缩前 Agent 一直守规矩压缩后突然开始改公共接口、换技术栈完全像变了个人。排查思路是先看压缩结果本身。打开中间层生成的 JSON检查constraints字段里还有没有那条约束。如果没了说明压缩时模型把约束误判成了低信息需要调高约束维度在打分规则里的权重。我通常是从 0.4 继续往上加直到压缩结果稳定包含所有约束。如果 JSON 里约束还在但 Agent 还是无视问题可能出在注入位置。压缩结果被塞进一条system消息如果它在上下文里的位置太靠中间模型依然可能“看不到”。解决办法是把约束从 JSON 里单独抽出来拼到系统提示词最开头用一句话强调“以下约束必须遵守优先级最高”。我在实际项目里对比过这个小小的位置调整能把约束遵守率从 60% 拉到 90% 以上。还有一个兜底方案原始对话日志别删。我每次压缩前都会把完整消息列表落盘出问题能立刻回滚到压缩前状态。别嫌原始日志占空间一段 100k token 的日志撑死几 MB比起模型因此多烧几百万 token这点成本完全不值一提。5.2 token 统计不准压缩触发时机忽早忽晚token 估算误差大是中间层方案最常见的工程坑。不同模型的 tokenizer 差异很大有的模型 1 个汉字算 1.5 个 token有的算 2 个代码符号的切分方式也不一样。用简单的字符数比例估算误差能到 30%触发压缩的时机自然忽早忽晚。我的解法是引入目标模型同一个 tokenizer 做精确统计。现在主流的 tokenizer 库基本都开源直接调库的count_tokens方法即可。如果中间层需要同时支撑多个模型就在配置里给每个模型单独设置 tokenizer而不是全局共用一个估算函数。还有一个细节估算 token 时要把工具返回的结果也算进去。很多实现只统计了对话消息忘了工具调用后的tool_result内容。而代码搜索、文件读取这类工具的结果动辄几千行占 token 大头。忽略这一块会让你的压缩阈值形同虚设。5.3 压缩后的上下文“串味”这个坑我踩得挺深。自研压缩模块上线后我发现 A 项目的 Agent 偶尔会跟 B 项目的记忆混在一起思考比如 A 项目里突然出现 B 项目的文件名。排查了半天问题出在向量检索阶段多个项目的记忆存在同一个向量库语义相似的内容容易互相命中。解决办法很朴素在向量库的每条记录上打项目 ID 和仓库路径标签查询时强制过滤。比如在 SQLite 表里加一个project_id字段检索时WHERE project_id ?直接把查询范围锁死。同样的问题也会出现在共享中间层服务时我的建议是每个项目独立一个数据库文件彻底隔离代价几乎可以忽略。5.4 压缩效果的量化对比系统落地后我做了一组简单的对比测试任务统一是“在约 2 万行代码的仓库里新增一个缓存模块、修改现有查询逻辑并跑通测试”。结果如下方案完成轮数总 token 消耗关键约束遗忘次数人工干预次数不压缩82约 650 万46提示词级压缩60约 380 万23中间层压缩43约 210 万11中间层向量检索38约 180 万01这组数据是在我自己的项目环境里跑的不同模型、不同任务会有差异但趋势很明显压缩不是简单地“省 token”它同时减少了模型因信息混乱而产生的无效动作所以完成轮数和人工干预次数都在降。中间层方案相比提示词级压缩提升最明显主要原因是压缩时机和保留内容都更可控。5.5 一套避坑清单最后把我踩过的坑整理成一张速查表实操时直接对着查场景坑对策压缩触发在 Agent 批量修改文件中间触发丢失待写入状态等当前工具调用结束下一轮开始前再压缩压缩结果模型生成的 JSON 字段缺失解析失败时返回提示让模型重新生成一次并给出示例保留策略只留摘要导致报错堆栈丢失错误信息强制进errors字段不参与摘要多项目共库向量检索串项目每个项目独立数据库查询带项目 ID 过滤指令文件膨胀CLAUDE.md/AGENTS.md越写越长定期清理已过期决策保留最近 20 条有效约束这些坑看起来不大但在紧张开发的时候每一个都可能让你多花两三个小时去排查。压缩作为 Coding Agent 工程化的核心组件做得好是“隐形加速器”做得糙就是“线上事故制造机”细节上真得多花点心思。我个人在实际操作中的体会是不要试图一步到位做最完美的压缩系统。先把方案一用起来哪怕只是让 Agent 把决策写进文件都会比裸奔强很多。等你真正感受到长会话的痛苦之后再一步步引入中间层、向量检索每一层投入都能看到明显回报。这个方向我现在还在持续迭代尤其是把压缩结果按项目维度自动聚类、定期归档这块还大有文章可做。