如果你用命令行Agent跑过稍微有点规模的重构任务，大概率被这样一条报错迎面捶过：api error: 400 this model's maximum context length is 1048576 tokens. however...，后面接的token数一次比一次离谱。我第一次撞见的时候，正在让Agent把一个多模块项目从旧接口迁到新接口，前二十多轮对话都很顺利，到第二十五轮左右，它突然停摆，抛给我一条400。我第一反应是检查网络和API key，都正常。后来才意识到，问题出在我一直没当回事的Context上——Agent工作台上的东西，堆满了。
这个报错几乎成了Agent开发圈的“集体记忆”。你搜“context is too large and auto-compaction could not recover this”，能翻出一堆帖子。它不只是一个错误提示，它直接把Agent开发的核心命题甩到你脸上：Context到底是什么？它怎么运作？为什么百万级tokens的窗口还是不够用？这篇东西就是我基于自己踩坑和拆源码的经历，把Agent与Context之间的关系从头到尾捋一遍，顺便把排查、修复、预防的方法都摊开讲。
1. 一次400报错引发的思考：Context才是Agent真正的边界
1.1 那个让Agent开发者集体血压升高的报错
先把这个报错掰开来说。1048576这个数字眼熟吗？它是2的20次方，也就是常说的“1M上下文窗口”。不少前沿模型把上下文窗口做到了这个量级，听起来像天文数字，很多人的第一反应是“这辈子的对话都装不满吧”。
但实际跑Agent的人都知道，这个窗口消耗起来比想象中快得多。一次代码重构对话，前20轮的上下文累积可能只有几万token，到第25轮，工具一次性返回几百个匹配结果、某次读取了整份几千行的配置文件、再加上几轮大段diff回显，窗口数字瞬间就逼近六位数甚至七位数。然后你发起新请求，API直接回400，意味着请求在HTTP层就被拒了，压根走不到模型推理那一步。
这里有个容易忽略的细节：你看到的messages resulted in 786450 tokens这类数字，未必真的超过了1048576，但请求里除了messages之外，还有系统提示词、工具schema定义、max_tokens输出预留空间，这些全部计入上下文预算。也就是说，名义上1M的窗口，真正留给“临时工作区”的余额，可能只有八九成。很多人在几十万token的时候就爆窗，实际是被输出预留和虚拟token占用挤爆的。
要验证也简单：把同一段messages单独拎出来，把max_tokens调小，重新发一次请求，会发现原本400的请求突然就能过了。这说明窗口的约束是“输入+输出整包计价”，不是只看历史多长。
理解了这一层，你才会明白为什么那些长期跑Agent的人都在强调“窗口管理”，而不是“窗口越大越好”。
1.2 为什么说Context就是Agent的工作台
模型本身是没有记忆的。你每发一轮请求，它看到的都是“系统提示词+全部历史对话+新输入”拼接在一起的完整文本序列。所谓Agent的“记忆”，本质上全部由Context携带——这一轮不把上轮的内容带回来，模型就什么都不记得。
所以我把Context理解成Agent的“工作台”：桌上摆着它正在看的方案、刚拿到的工具输出、还没归档的历史记录、以及你交代任务的便签。桌面大小固定，桌上的东西越多，它能腾出来动手的空间就越少；桌上摆得越乱，它翻找关键信息的速度就越慢。
这个工作台模型能解释很多现象：
- 为什么Agent会在长任务后期突然“变笨”？不是模型退化了，是桌面上堆了太多无关杂物，注意力被稀释。
- 为什么同样的需求，新开一个会话跑得比老会话顺畅？因为新桌面上只有必要材料。
- 为什么有些人觉得“1M窗口也没用”？因为把1M窗口当仓库用，塞满了历史糨糊，模型在1M的垃圾里找几KB的关键信息，效果自然差。
所以Context管理，本质上就是工作台管理。接下来拆原理的时候，我会把这套模型延伸到具体机制上。
2. Context原理拆解：从注意力机制到“工作台”模型
2.1 上下文窗口是怎么算出容量上限的
要理解Context，绕不开Transformer的注意力机制。模型处理文本时，每个token的表示都要和序列中其他所有token做注意力计算，判断彼此的相关性。序列越长，需要计算的配对数量就按平方级增长——这就是常说的O(n²)复杂度。1M tokens的序列，注意力矩阵的规模是1M×1M，这个计算量和内存消耗都是恐怖的。
模型推理时还有一个关键缓存叫KV Cache。已经处理过的历史token，它们的Key和Value向量要被缓存下来，避免每生成一个新token就从头再算一遍。这个缓存体积跟序列长度正相关，1M上下文的KV Cache会占据非常大的显存空间。这也是为什么“百万级上下文”通常意味着更高的显存成本、更慢的推理速度，以及厂商在服务端更严格的控制。窗口上限本质上是工程约束，不是模型能力的天然边界。
除开这个硬上限，还有个更隐蔽的“软上限”：有效上下文。学界有个著名的“Lost in the Middle”现象——模型对长文本开头和结尾的信息利用率明显高于中间部分。你给Agent塞一个100万字的历史记录，它能精准回忆的，大概率只有开头那几条指令和结尾那几条结果，中间那90万字基本是“读过了，但没记住”。
所以Context管理的第一原则是：不要把所有信息平均地塞进窗口，要把关键信息放在开头和结尾，让中间只放次要材料，其余全部外置。
2.2 auto-compaction：系统的自救机制
主流命令行Agent（比如Claude Code这一类）都内置了auto-compaction机制，翻译过来叫“自动压缩”或“自动精简”。它的工作原理是：在上下文占用接近窗口上限时，框架会调用模型对前面的完整历史做一次回顾和总结，把几十轮冗长对话压缩成一段“此前进展摘要”，然后用这段摘要替换掉原始对话，腾出窗口空间，让任务能继续往下跑。
这个设计思路是对的，但它在两种情况下会失灵，也就是那句经典报错context is too large and auto-compaction could not recover this出现的时候：
第一种情况，当前输入本身已经巨大。比如你刚从工具那里拿到一份几十万token的完整网页内容，正打算让Agent分析，这个请求的输入量直接就逼近甚至超过了窗口上限。auto-compaction再及时，也只能压缩“历史部分”，压缩不了“当前这一轮新塞进来的东西”。
第二种情况，压缩产物太厚。当历史对话已经积累到极其庞大的程度时，模型生成的摘要本身可能就有几万甚至十几万token。压缩完一算总账，还是超限，框架只能宣告自救失败。
我把auto-compaction理解成一个“定期清理桌面的保洁阿姨”。她能把桌面上的杂物捆成压缩包，但如果你刚把一个冰箱搬上桌，她再怎么捆也腾不出地方。
2.3 长上下文给模型带来的隐性降智
很多人有个误区，觉得“给模型的上下文越多，它就越聪明”。实际体验恰恰相反：上下文越长，模型的有效推理能力下降得越明显。原因倒不复杂——注意力资源是有限的，序列里塞的东西越多，每个token分到的注意力就越稀薄。模型要在一堆历史噪音里定位“当前任务真正需要的那句话”，难度直线上升。
我做过一个很直观的测试：让Agent在全新会话里读一个200行的模块并改一个bug，一轮搞定，质量很高；让它在累积了8万token历史的会话里继续同一个任务，它经常翻错文件、复用已经废弃的方案，甚至开始“参考”历史里那些被否决的思路。这不是玄学，这就是上下文污染。
所以现在我看到有人在讨论“Agent记忆方案”时，核心思路永远是“怎么让Agent在需要时精准取回信息，而不是把记忆全都塞进窗口”。窗口是短期工作区，不是长期仓库。
3. Agent架构里的Context运转：单Agent与多Agent的差异
3.1 单Agent的Context生命周期
一个典型单Agent的执行循环是这样的：系统提示词（常驻身份与规则）→ 用户下达任务 → Agent调用工具 → 工具返回输出 → Agent基于新信息继续推理 → 再调工具……如此循环往复。
每一轮循环的产物都会沉淀到Context里。换句话说，工具调用记录、工具返回的原始输出、Agent的每一步思考过程，全部是Context的一部分。这也解释了为什么单Agent跑长任务会越跑越慢：不是模型抽风，是每次请求携带的序列越来越长，KV Cache越来越大，推理时间自然水涨船高。
这个环节里，普通开发者最容易犯的错是“工具输出不设防”。比如你让Agent用ls -R列出整个仓库的文件结构，几百上千条路径直接就进了上下文；再比如你让它curl抓一个网页，整个HTML源码全被当作工具输出带回对话。这些东西动辄吃掉几万token，而且大部分对最终任务毫无价值。
正确做法是引导Agent“先裁剪、再返回”。你可以明确要求它：工具输出超过一定行数时，先输出前面50行+末尾20行，中间用省略号替代；需要全文分析时，让它把内容写入临时文件，再用分段读取的方式按需查看。这些约束写在系统提示词里，能省下大量窗口空间。
3.2 多Agent协作时的Context隔离与传递
多Agent系统（或者叫多智能体协作）的Context问题跟单Agent完全不是一回事。很多人刚上手时容易有个直觉：让多个Agent共享一个Context，彼此都能看到全部信息，协作起来岂不是更默契？
实测下来这是灾难。多个Agent共享同一份Context，意味着每轮对话、每个Agent的工具输出都在互相污染视野。AAgent在写代码时，BAgent在跑测试的中间结果不停地往窗口里挤；BAgent读不到需要的上下文，因为被AgentA几千行代码输出淹没了。最后所有Agent都在同一个满是噪音的窗口里挣扎，效率还不如单Agent。
成熟的多Agent架构里，Context是隔离的：每个Agent拥有自己独立的上下文窗口，只保留自身任务的必要信息。Agent之间通过消息传递或共享存储交换“结果摘要”，而不是交换原始数据。
举个例子：两个Agent协作，一个负责改代码，一个负责跑测试。改代码Agent完整持有diff和需求上下文；跑测试Agent只需要知道“改动了哪些模块、关键风险点在哪、预期的测试命令是什么”。把AgentA的整个Diff丢给AgentB，只会让B的窗口瞬间爆炸，而且它真正需要的几个断言点反而挤在中间读不到。
多Agent的Context设计，本质上是在“信息共享”和“上下文隔离”之间找平衡。共享的是结论和坐标，隔离的是过程和噪音。
3.3 Agent Harness：谁在替我们管Context
讲到这里必须提一个热搜词里反复出现的概念：Agent Harness。很多人问“harness和agent到底什么区别”，一句话解释：Agent是那个会思考、会调用工具、会执行任务的智能体；Harness是承载Agent运行的外壳，是那个“执行环境+控制循环”，负责管理Agent的每一步行为——其中很重要的一项工作就是管理Context。
你用的Claude Code、Codex这类命令行Agent，本质上是一整套封装好的Harness。它替你做了这些事：
- 按固定顺序拼装系统提示词、工具定义、历史对话和当前输入；
- 监控上下文占用，设定压缩阈值；
- 在窗口紧张时触发auto-compaction；
- 控制工具输出的截断与展示格式；
- 管理多轮会话的存档与恢复。
这也是为什么Harness的质量直接决定Agent的实际表现：同一个模型，放在一个Context管理粗糙的Harness里，跑一会儿就报“context too large”；放在一个Context管理精细的Harness里，能稳定工作很久不爆窗。
如果你是自己写Agent框架的人，Harness里最值得投入的就是Context管理层——不要在用户提示词里随机应变，而是把上下文策略写进框架逻辑，让它在不同阶段自动决定“保留什么、压缩什么、丢弃什么、去哪里找回什么”。
4. 实战复盘：我是怎么定位并修复上下文超限的
4.1 完整排查链路：从报错倒查膨胀源头
拿我自己那次400报错做一次完整的复盘。当时任务背景：一个多模块Node.js项目要从旧的回调式API迁移到async/await风格，仓库不算大，但涉及十几个文件。我用命令行Agent跑了一下午，报错出现在第25轮左右。
第一步，拿到完整报错信息。注意别只截取第一行，报错尾部通常会给出your messages resulted in XXXX tokens，这个数字直接告诉你超了多少。我当时看到的是大概四十多万token，还没到一百万，但请求里预留的输出空间和系统提示词已经把余额压垮了。
第二步，开启Agent的详细日志模式。命令行Agent一般都带调试模式，会记录每一轮请求的上下文token数。如果没有，你可以用API代理层自己统计，或者直接把历史会话导出成JSON逐个计算。
第三步，按轮次统计token消耗。我当时的日志数据大概是：大部分轮次每轮只有几千到一万左右的增量，但有三轮特别异常——一次是全仓库grep匹配结果直接返回了几百行代码片段，一次是Agent读取了某个几千行的配置文件全文，还有一次是它连续三次调用工具都返回了大段报错堆栈，每轮都累积了好几万token。
第四步，确认auto-compaction失效原因。我翻到报错时间点附近的日志，发现框架确实尝试过自动压缩，但压缩前的历史已经堆到三十多万token，生成的摘要也有好几万token，加上当轮新输入，压缩后依然超过窗口，最终宣告失败。
这四步走完，根因就很清楚了。
4.2 根因分析：为什么auto-compaction救不回来
我那次的爆窗，严格来说是三个问题叠加：
第一个问题是“输入失焦”。全仓库grep的结果、整文件读取、反复报错堆栈，这些大块内容跟迁移任务相关性并不高，却占据了大半窗口。它们本可以被裁剪、摘要或直接外置。
第二个问题是“压缩策略触发太晚”。框架默认会在上下文接近上限时才压缩，但等到那时候，历史已经庞大到压缩本身也放不下。理论上有更早的压缩阈值可以设置，但我没调，默认策略扛不住这种大输入场景。
第三个问题是“压缩内容无差别”。auto-compaction会把所有历史一视同仁地浓缩，包括那些本就不该留在窗口里的杂质。它压缩的是“总长度”，不是“有效信息”，所以压缩完可能保住了噪音的摘要，却丢掉了关键的接口变更细节。
把这三个原因写出来，修复方向就很明确了：控制输入粒度、提前压缩、把关键信息外置而不是依赖窗口携带。
4.3 修复方案与验证：让Agent重新跑起来
我当时的修复分了三步走：
第一步，先让Agent重新跑起来。新开一个会话，手动带上这次任务真正的必要上下文：需要修改的文件清单、目标接口的签名、上一次会话产生的关键过渡性决策摘要。没有把旧的几十轮对话打包带过去，只带“结论”。
第二步，修改Agent的执行策略，在系统提示词里增加约束：
- 工具输出超过50行必须先摘要再返回，不要直接展示全文；
- 任何文件读取必须按需、按行号分段读取，严禁一次性读取大文件全文；
- 每个任务完成一个阶段后，主动输出一份“阶段性进展摘要”，包括已完成、进行中、下一步路径。
第三步，调整上下文压缩的触发阈值，提前到窗口的50%-60%就触发，而不是临近上限才行动。同时把“压缩摘要必须保留关键文件路径和常量名”写进压缩指令里，避免压完只剩废话。
验证结果很直观：同一个迁移任务，新方案下跑到第五十轮都没再报过400，Agent的反应速度还比原来快了不少。因为窗口里堆的是“高密度信息”，而不是“高体积历史”。这个对比让我彻底确定了Context管理的价值。
5. 上下文系统的工程化设计：让Agent记得住、忘得掉、找得到
5.1 分层上下文结构：常驻区、任务区、检索区
在实战里，我把Agent的窗口内容结构化地分成了三层，这套设计现在一直沿用：
第一层是常驻区，也就是系统提示词和全局规则。它是每次请求都要随行的那部分，必须精简到一个“小而稳”的程度。原则是：只放身份、行为边界、通用的输出规范，不放任何具体项目信息。因为具体信息会变，而常驻区变了会导致整个会话行为漂移。
第二层是任务区，当前任务的目标、输入材料、关联文件路径、约束条件。这一层要跟着任务走，任务切换就换一套。它的设计重点是“精确到路径和文件”，而不是“复制文件内容”。能写“读取src/utils/format.ts并按新规则重写”，就不要把整个文件贴进提示词。
第三层是检索区，历史摘要、关键决策、待办事项。这一层是动态更新的，每个阶段结束时刷新一次，把窗口里已经完成的东西压缩成一句话，把决定性的技术选择单独记录。这样窗口里的历史不是线性堆积，而是不断翻新。
这套分层结构用在一段提示词模板里，大致长这样：
【系统规则】 你是本项目的高级工程师，只负责完成本次任务。 工具输出超过50行先摘要再返回，禁止直接展示全文。 每次完成任务的一个阶段，输出阶段性进展摘要。 【任务目标】 将旧的回调式API迁移到async/await风格。 涉及文件：src/db/connection.ts, src/services/user.ts, src/api/routes.ts 约束：保持对外接口签名不变，测试全部通过。 【历史快照】 已完成：connection.ts迁移，user.ts函数签名已确认。 进行中：routes.ts重写中。 关键决策：db连接改为顶层await，不再使用回调包装。 待办：运行全量测试、更新类型声明。这套结构下，窗口里的内容密度很高，Agent几乎每轮都在处理有效信息，历史部分也不会无限膨胀。
5.2 压缩与摘要：压缩到底损失了什么
很多人对auto-compaction又爱又恨，其实就是没搞清“压缩损失的是什么”。压缩是拿历史细节换窗口空间，损失的东西主要有三类：具体数值和常量名、报错堆栈的细节、以及之前走过但没走通的“死路”。
所以做压缩摘要时，不能简单要求Agent“总结之前的对话”，而是给一个结构化模板，把该留的都留进去：
请基于以上对话，生成结构化摘要，保留以下内容： 1. 已完成：列出已完成任务和涉及的准确文件路径； 2. 进行中：当前正在处理的任务点； 3. 阻塞：当前遇到的报错信息、错误码、可疑代码位置； 4. 关键决策：已经确定的技术选型和常量/命名，必须保留原始值； 5. 下一步：按顺序排列的后续步骤。 要求：压缩后总长度控制在2500 token以内。这个模板的用意是让压缩过程“有选择地丢”。没有它，模型很容易给你一段四平八稳的泛泛总结——“我们正在迁移API，遇到了错误，下一步继续排查”——完全没法用。有它在，摘要才能作为下一阶段的可行上下文。
顺带说一个经验：摘要虽然比原历史小得多，但它还是会消耗token，而且摘要质量直接决定后面Agent能不能接上。所以我会控制压缩频率，宁可“阶段性人工总结一次”，也不要让auto-compaction在压力下仓促压一堆。人工总结跟自动压缩的差别，就像归档文件和碎纸机的差别。
5.3 外部记忆与检索增强：把Context从窗口搬到仓库里
窗口空间再大，也不是用来当仓库的。真正的长期记忆应该放在窗口外面——文件系统、向量库、知识库，这才是Agent记忆方案的正解。
我的做法比较朴素：给项目建一个AGENT_NOTES.md，每个阶段跑完，把关键结论、文件变更、踩坑记录追加进去。下次新开会话，让Agent先读这个文件，再决定下一步要查哪些代码。这样会话与会话之间是连续的，但Context不会无限增长。
检索增强的做法可以升级一些：把项目的技术文档、接口定义、历史决策向量化，塞进向量数据库。Agent需要某类信息时，通过检索召回最相关的几段，再放进窗口。这就把“背下整本参考书”变成了“按需查字典”。
我做过一次对比实验：同样一个功能迭代任务，A方案是“把5万字历史记录全部塞进上下文让Agent处理”，B方案是“把结论写进note文件，开启分词检索召回再处理”。B方案的结果质量明显更高，上下文占用只有A方案的十分之一，速度也快了不止一倍。
Context的定位应该是“临时工作台”，外部记忆才是“仓库”。把仓库的东西全搬上工作台，不是勤快，是灾难。
6. 那些不写在文档里的实战经验
6.1 Agent Skill与Context配合的实战案例：网页存Markdown
最近Agent Skill这个概念火起来，热搜里能看到“把网页保存成markdown的skill”“skill教程”之类。有人把它理解为“让Agent学会新技能”，表面看是这样，往深了看，很多Skill的真正价值恰恰是帮Agent省Context。
拿网页保存成markdown这个Skill举例。常规做法是：你让Agent分析或保存一个网页，它会直接抓取整个页面内容，一次性塞进上下文，一个页面少说几万token，多则十几万。而一个设计合理的“网页转markdown”Skill，会把完整流程封装成脚本：Agent拿到链接，调用这个Skill，脚本去抓页面、转成markdown、存到本地文件，最后只给Agent返回一句“已保存到notes/tool-roundup.md，共12000字，提取了正文部分”。
你把十页的网页全文塞进窗口去分析，不如让它把网页存成文件，再按需读几个关键段落。这里面的核心思路就是“用工具代替堆上下文”。高频任务的操作细节、参数、脚本，全部封装进Skill，窗口里只留任务目标和结果摘要。我后来把“跑测试并提取失败概览”“构建产物差异报告”这类重复动作都做成了Skill，窗口压力直线下降。
6.2 框架选型的Context管理差异：LangChain、Dify与CrewAI
聊到Agent开发，绕不开框架选型。最近好多人问LangChain、Dify、CrewAI哪个好，我的看法是，这几个东西在Context管理上的设计思路差异很大，选型等于选Context策略。
LangChain的Memory组件最灵活，有ConversationBufferWindowMemory（滑动窗口记忆）、SummarizerMemory（摘要记忆）、EntityMemory（实体记忆）等，你可以精确控制保留哪些历史。代价是组装成本高，每块记忆组件都要自己调，默认配置跑起来Context管理效果未必理想。适合愿意花时间打磨的开发者。
Dify走的是可视化工作流路线，Context由节点之间的变量传递天然管理。你可以把一个Agent的输入明确限定为“上一节点的输出字段”，而不是整段历史。这种结构对业务场景很友好，不容易爆窗，但自定义程度相对低，深度定制场景会受限。
CrewAI主打多Agent协作，每个Task自带Context，Agent之间通过任务队列传递结果。它的优势是Context隔离做得比较清晰，不会出现多Agent共用一个大窗口互相污染的问题。但如果你没设计好任务粒度，每个Task都可能重复搬运重复信息，照样会膨胀。
我的直接建议：一个人写原型或研究，选LangChain系列，Context策略自主性最高；要快速上线业务系统，选Dify；做明确的多Agent流水线，选CrewAI。没有绝对好坏，只有哪个匹配你的“Context管理模式”。另外，最近Rust生态也冒出一些Agent运行时，主打低内存占用和高并发，适合想从底层自己实现Harness的人研究，这也能看出Context管理正在成为框架竞争的核心战场。
6.3 新手最容易踩的五个Context大坑
最后把新手最容易踩的坑集中排一遍，每一条都是我见过或者自己踩过的：
第一，把整个仓库一次性拖进对话。几百个文件、几十万行代码全塞进去，Agent还没开始干活，窗口先爆了。解法是让Agent先用工具按需查看结构，再锁定目标文件。
第二，粘贴几千行代码到提示词里。超过200行的内容就应该按路径读取、按函数读取，而不是复制粘贴。你是想让Agent改代码，不是让它背代码。
第三，完全不管工具输出的体积。一条find命令、一个curl返回、一次失败的堆栈，都是动辄上万token的“沉默杀手”。必须在系统提示词里约束工具输出长度。
第四，一个会话从早跑到晚。会话越长，Context里积累的杂质越多，Agent越容易在后面阶段“犯蠢”。阶段目标完成就新开会话，带上摘要继续。
第五，把动态数据写死在系统提示词里。很多人喜欢把当前任务状态、临时变量写进系统提示词，但这部分每轮都会重复计费，久了就占据了大量空间。动态信息应该放在每轮的用户消息里，或放在外部note文件中轮询读取。
这五条如果都能避掉，你的Agent的Context寿命至少翻两倍。
跑了小半年Agent，我现在养成的习惯是：大任务启动前先想清楚“这个任务至少需要哪些信息留在窗口里”，任务每推进一个阶段就更新一次AGENT_NOTES.md，看到工具要返回大输出就先问自己一句——这个东西Agent真的需要全文看到吗？大部分时候，它只需要一个结论。Context管理说到底就是一句话：让Agent的手边只放它此刻需要的东西，其余的放到它能够到的地方。能做到这一点，1M窗口也好、128K窗口也好，都不会成为瓶颈。
