最近一个月我几乎天天泡在AI编码代理的调试上。很多人问我为什么同一个模型、同一个工具别人能一口气完成跨文件重构我却总在第三轮就开始跑偏问题往往不在模型能力而在上下文。上下文工程这个词最近热度非常高但说到底就一件事在有限的上下文窗口里让代理始终掌握它当前最需要的信息。我在实际项目中把ChatMemory滑动窗口和Context-mode MCP两套方案结合起来算是把代理越干越傻这个老大难问题解决了大半。这篇文章把设计思路、参数计算和踩坑记录都摊开来聊给同样在做代理工作流优化的朋友一个参考。先交代一下背景。我手里的项目是一个基于Claude Code和自定义MCP Server搭建的代码评审代理日常要处理多文件改动分析、测试失败排查、需求变更落地这几类任务。早期版本在10轮以内的对话表现尚可一旦超过15轮、累计上下文超过4万token代理就会出现两类严重问题一是遗忘早期用户约束比如不要动公共接口签名这种硬性要求在20轮之后基本失效二是文件内容重复注入同一个文件被反复读取窗口里堆满冗余代码最终把真正有用的信息挤出窗口。这篇文章记录的就是围绕这两类问题的完整优化过程。1. AI编码代理的上下文困境先搞清楚问题在哪1.1 编码代理的工作循环与token消耗AI编码代理本质上是一个循环模型生成意图调用工具拿到结果再生成下一步意图。以Claude Code为例一次典型的文件修改任务会经历这样的循环读取目录结构几百token、打开目标文件几千token、生成diff、执行测试命令、读取测试输出。每一轮循环都会向上下文窗口追加新内容而这些内容几乎不会被主动清理。我做过一个粗糙的统计一次涉及3个文件的bug修复任务全程约25轮对话累计消耗的上下文量可以达到15万token以上而单模型上下文窗口上限是20万token。也就是说一个不太复杂的任务就能吃掉窗口的75%。如果中间有几次工具调用返回了冗长的报错堆栈或者代理反复检索同一个文件的多个版本窗口很快就会触顶。触顶之后不同工具的处理策略不同有的直接截断最早消息有的开始丢中间结果实际表现就是代理变得健忘和错乱。1.2 编码场景特有的上下文压力对话式AI的其他应用场景比如客服问答、文档总结上下文压力远没有编码场景大。编码任务有几个特殊性。第一代码本身的token密度极高。一段20行的函数定义可能包含300个token一个中等规模的文件就是3000到5000token而一次跨文件重构需要同时持有多个文件的上下文总量很容易突破2万token。第二编码任务的状态依赖极强。用户在第五轮说了一句这里用异步实现可能到第十五轮才真正动手改这段代码如果中间信息被滑出窗口代理就会按默认的同步方式实现偏离需求。第三工具输出冗余严重。测试框架的完整输出、编译器的警告信息、linter的报告文本往往包含大量与当前任务无关的噪音这些噪音会无情地占用窗口空间。1.3 先做预算把窗口当资源而不是容器在引入任何优化方案之前我建议先做一个动作给上下文窗口做预算拆解。把窗口分成四个区域——系统指令区通常固定占用2%到5%、用户需求区核心约束和当前目标、工具往返区每轮调用的输入输出、历史对话区早期多轮内容。预算设计的核心原则是历史对话区最应该被压缩因为它的信息价值密度最低工具往返区次之因为大部分工具输出可以被摘要替代系统指令区和用户需求区则应该被保护任何时候都不能被挤出窗口。我自己的预算比例是系统指令4%、用户需求15%、工具往返50%、历史对话31%。也就是说一个20万token的窗口留给历史对话区的预算是6.2万token一旦超出这个量级就必须启动压缩策略。这个预算数字不是拍脑袋定的而是根据多次任务失败率和token消耗的回归观察归纳出来的。如果你发现代理经常忘记早期约束优先压缩的是工具往返区而不是用户需求区这个方向错了再好的压缩算法都没用。2. ChatMemory滑动窗口让代理记住该记住的2.1 滑动窗口到底在滑什么ChatMemory是我参考社区几个开源记忆方案后在自己项目里落地的一套上下文管理模块。它的核心机制就是滑动窗口但这里要澄清一个容易混淆的点滑动窗口并不是简单地把最早的消息丢弃而是在一个固定大小的窗口内做动态调度。你可以把它想象成一个环形缓冲区。新的消息不断从尾部写入当总token数超过阈值时从头部开始淘汰旧消息。但淘汰不是一刀切每条消息会带一个优先级标记用户明确下达的指令优先级最高系统错误信息次之工具读取的文件内容优先级最低。窗口起步时我不淘汰高优先级消息而是优先压缩低优先级消息的内容——比如把一整份文件内容替换成一段摘要或者把完整的测试输出截断为启动失败端口被占用未执行用例。2.2 参数设计与计算窗口多长、步长多大、淘汰谁滑动窗口有三个关键参数需要调窗口长度总token预算、步长每次滑动多少消息、淘汰策略低优先级消息如何降级。这里给出一套可以直接套用的设计方法。第一窗口长度。总预算取模型窗口上限的60%到70%作为安全水位。之所以不取100%是因为要给工具返回结果留出突发余量避免一次较长的测试输出瞬间撑爆窗口。我以Claude 200k窗口为例安全水位设在130k token其中ChatMemory管理的历史对话区只占31%约40k token其余留给系统指令、用户需求和工具往返。第二步长。滑动步长不需要太小每次触发滑动时批量淘汰一批低价值消息而不是逐条淘汰。逐条淘汰的坏处是让代理频繁感知到上下文变化反而影响连贯性。我的经验是当超阈值达到5%时触发一次滑动一次性释放8%到10%的空间。第三淘汰策略。这里有一个微妙的点并不是所有早期消息都应该被保留而是只有和当前任务可能强相关的早期消息才值得保留。我用一句大白话总结窗口里留下的是约束和结论丢掉的是过程和原文。用户说过的硬性约束、你确认过的技术方案、已经定位到的问题根因这三类信息必须保留而代理长篇分析的思考过程、中间版本的代码片段、重复读取的相同文件内容这些都可以折叠成摘要。2.3 落地实现给代理挂一个可插拔的记忆模块在具体实现上我给代理增加了一个独立的memory模块通过事件钩子介入消息循环。核心数据结构是一个消息队列每条消息包含role、content、token数、优先级、时间戳、消息类型。每次模型收到新消息时先计算当前队列的总token数如果超出阈值就执行一次压缩。class SlidingWindowMemory: def __init__(self, max_tokens40000, summary_ratio0.8): self.messages deque() self.max_tokens max_tokens self.window_low_watermark max_tokens * 0.5 self.window_high_watermark max_tokens * 0.95 def append(self, message): self.messages.append(message) self._maybe_cleanup() def _maybe_cleanup(self): while self._total_tokens() self.window_high_watermark: candidate self._find_lowest_priority_message() if candidate is None: break if candidate.content_token_len 300: candidate.content self._summarize(candidate) candidate.compressed True else: self.messages.remove(candidate) # 压缩后如果仍超阈值直接淘汰最早的普通消息 while self._total_tokens() self.window_high_watermark: self.messages.popleft()这个实现里有几个设计细节值得说明。第一压缩优先于删除一条内容很长的工具输出先尝试用摘要替代而不是直接删掉这样保留了信息中的关键结论。第二低水位和高水位的双阈值设计低水位用来防止频繁滑动只有当总量超过高水位才触发清理清理到低水位就停避免乒乓效应。第三高优先级消息的保护逻辑优先级最高的消息即使排在队列最前面也不参与淘汰。实际运行中这套模块表现比较稳定。拿一次真实的重构任务来说整个任务累计产生了52条消息总token约8.6万滑窗压缩后实际进入模型的历史消息为31条约2.9万token而用户的关键约束保持公共API不变始终保留在窗口中。代理在最后一轮仍然能准确复述这个约束这在之前的无滑窗版本里是不可想象的。2.4 我踩过的坑滑窗不是万能的滑窗方案效果明显但我也踩过几次坑值得单独提醒。第一个坑是摘要模型带来的延迟。最初我选用的是一个本地小模型做摘要每次压缩需要额外等待2到3秒在多轮压缩时会明显拖慢整个代理的响应速度。解决办法是给压缩任务做异步化先把需要压缩的消息标记为待处理不阻塞主对话循环等下一个空闲时间片再批量生成摘要。如果你是做交互式工具这个顺序尤其重要宁可让代理先返回结果也不要为了压缩上下文而让用户反复等待。第二个坑是滑窗对长距离依赖的破坏。有些信息比如项目背景、架构决策、编码规范从对话开始就一直存在但它们不是用户在当前任务中显式说出来的而更像是隐性上下文。只靠滑动窗口这些信息很容易被滑出窗口。我后来把这类信息单独抽出来固化到系统指令中不再依赖对话历史携带。这样做之后即使窗口再怎么滑动项目级约束都不会丢。第三个坑是压缩的级联失真。摘要信息再次被压缩时会丢失越来越多的细节。比如第一次压缩把一段测试输出变成测试失败端口冲突第二次压缩可能变成有测试失败第三次可能就只剩存在测试问题。这种级联失真非常隐蔽代理表面上记得有问题但根本不清楚具体是什么问题。我的对策是高危信息不做二次压缩直接保留原始内容。优先级标记中专门加了一个可压缩等级字段等级为0的信息永不压缩、永不淘汰。3. Context-mode MCP把上下文工程服务化3.1 MCP的定位给AI编码代理加一个外置上下文接口滑动窗口解决的是历史对话怎么精简的问题但编码代理还有一个更刚性的需求它需要在某个具体时刻快速拿到某一部分外部上下文。比如代理正在修改一个函数需要知道这个函数在另外三个文件里的调用关系或者代理需要了解某个模块的整体结构而不是从零开始逐个文件读取。这时候如果只靠对话历史效率极低而且容易把无关内容带进窗口。MCPModel Context Protocol在这时候就派上用场了。我把它理解成AI应用的通用外设接口——它定义了模型怎样通过标准化的工具调用去获取外部数据而不需要开发者每次都为不同环境写一套不同的接入逻辑。MCP的核心概念包括Server提供工具和资源的服务端、Client嵌入在编码代理中的客户端、Tool模型可调用的能力入口和Resource静态但可被引用的数据源比如配置文件、文档片段。上下文工程如果只停留在代理内部做消息裁剪那还是被动防守接入MCP之后代理就能主动按需拉取上下文这才是主动出击。3.2 Context-mode的设计三种模式按需取上下文我落地的是一个叫context-manager的MCP Server对外暴露的核心工具是get_project_context。这个工具接收一个mode参数支持三种模式brief、scoped、full。brief模式用于快速浏览返回项目摘要、文件树、当前正在处理的文件清单token开销控制在1500以内。这一般作为任务开始时的侦察动作。scoped模式是主力它接收一个关键参数scope_name可以是函数名、文件名或模块名服务端会检索代码索引并返回该作用域的调用链、依赖文件和最近的git diff。full模式则通常只在用户明确要求全面梳理时才会被调用返回整个模块的完整结构和关键代码片段token开销在8000到15000之间。为什么要设计成三种模式而不是一个通用接口原因在于模型在真实运行中是贪心的。如果不限制工具的返回体量它倾向于一次拿到最多的信息而这恰恰和上下文预算的目标相反。Context-mode的本质是给工具的信息获取行为加一个预算约束让模型在探索信息和控制消耗之间做权衡。这个设计思路和ChatMemory的滑动窗口形成了互补一个是控制入口一个管理存量。3.3 服务端实现与客户端接入context-manager服务端在实现上不复杂核心是两部分代码索引和上下文组装。代码索引基于tree-sitter解析项目源码预先生成每个文件的结构化信息包括函数定义位置、函数调用关系、类成员列表。上下文组装则是在收到具体请求时根据mode参数进行检索和裁剪。{ name: get_project_context, description: 获取指定作用域的代码上下文支持brief、scoped、full三种模式, input_schema: { type: object, properties: { mode: { type: string, enum: [brief, scoped, full], description: 上下文获取模式 }, scope_name: { type: string, description: 作用域名称如函数名、模块名或文件名 }, max_tokens: { type: integer, default: 8000, description: 返回内容的token上限 } }, required: [mode] } }这个工具的定义有一个容易被忽视的点在description里明确写了max_tokens参数。我后来才发现MCP工具有没有token预算字段对模型的行为差异很大。如果没有这个参数模型会期望工具返回完整内容有了这个参数它就会预期我拿到的可能是一个裁剪版本并主动在后续调用中补充细节。客户端接入我主要试了两条路径。在Claude Code里直接在配置文件中注册MCP server{ mcpServers: { context-manager: { command: node, args: [/path/to/context-manager/build/index.js], env: { PROJECT_ROOT: /workspace/my-repo } } } }在Cursor类IDE里虽然MCP配置入口名称略有不同但协议一致只要服务端实现了标准的工具列表和调用接口客户端侧基本就是填一个URL或命令的事情。我实际测试过从服务启动到模型能调用get_project_context整个过程不超过三分钟。3.4 滑动窗口Context-mode MCP的组合数据流这两套方案组合起来之后代理的上下文流变成了一个让我比较满意的闭环。任务开始时代理先调用get_project_context的brief模式拿到项目骨架和当前任务涉及的文件清单这部分信息进入ChatMemory后标记为高优先级。随后代理进入工作循环每次需要深入了解某个函数或模块时会调用scoped模式获取局部上下文而不是直接用工具读取整个文件全量内容。ChatMemory负责管理这些上下文信息的生命周期优先保留scoped结果中的结论性信息比如load_config函数已被废弃应改用new_config_loader当窗口压力增大时优先压缩brief模式下得到的泛化信息。对比优化前后的一组数据一个中等规模的bug修复任务优化前平均消耗16.8万token代理实际可用的有效上下文用户约束当前文件状态测试反馈约5.2万token优化后总消耗降到7.3万token有效上下文占比提高到4.1万token。更关键的是任务成功率从54%提升到81%失败模式也发生了明显变化——优化前主要是代理遗忘需求导致的偏离优化后主要是测试环境问题这类外部因素。4. 常见问题与排查技巧实录4.1 症状一代理失忆关键需求执行到一半就歪了现象用户在对话早期明确说过不要改动数据库表结构但在第20轮之后代理仍然生成了包含ALTER TABLE的代码。这类问题排查的切入点是信息是何时被滑出窗口的。我的排查步骤是先开启ChatMemory的日志输出查看滑窗清理时被淘汰或压缩的消息列表然后定位包含不要改动数据库表结构的那条消息确认它的优先级标记和处理状态。90%的情况下问题出在优先级标记上——用户指令虽然在聊天界面上看起来是一条正文消息但在底层消息队列里可能被标记成了普通类型导致它和低价值的工具输出一起被压缩了。解决方法是给用户消息类型增加强制保留逻辑凡是roleuser且内容包含不要、必须、禁止、确保等约束类关键词的消息一律打上最高优先级并计入用户需求区的存量预算。另一种更稳妥的做法是把这类约束同时固化到系统指令区形成双保险。4.2 症状二工具返回结果爆炸窗口瞬间被占满现象代理执行一次git diff命令返回了2万行变更ChatMemory压缩还没来得及触发窗口已经被占满了。这类问题实际上是入口控制没有做好滑窗已经来不及兜底。我会从两个方向修复。第一在工具调用层做输出修剪在MCP Server端或者命令行工具包装层对返回内容增加行数限制超出的部分用前N行统计信息尾部摘要的结构返回。比如git diff可以返回共修改42个文件3800/-1200行以下为前200行diff把完整diff写入临时文件由代理按需再读取。第二在ChatMemory的队列中增加突发保护当单条消息的token数超过预设阈值我这边设的是总预算的15%时即使这条消息优先级很高也强制先做一次内容替换防止单人消息消耗整块窗口。4.3 症状三MCP工具调用频繁拖慢响应现象接入context-manager后代理出现了反复调用get_project_context的行为每次任务都要调用4到5次导致整体响应时间增加了3到4秒。这实际上是MCP Server缺乏缓存设计和频控管理。我做了三个优化。第一增加服务端缓存同一scope_name在短时间内重复请求直接返回缓存只有当用户手动触发刷新或者检测到文件变更时才失效。第二在工具描述中加入调用建议在description里写明优先使用scoped模式不要重复获取相同作用域模型读了之后会显著降低重复调用次数。第三在ChatMemory里对MCP返回内容做特殊标记已经获取过的作用域信息在后续轮次中直接从消息队列里检索复用而不是再触发一次网络调用。4.4 排查速查表症状优先排查位置推荐方案代理遗忘早期约束消息优先级标记约束类关键词强制保留同步固化到system prompt窗口瞬间被占满工具输出层、单条消息大小工具层输出修剪ChatMemory增加单条消息token上限代理反复调用同一工具MCP服务端日志增加缓存、描述中加入调用建议摘要级联失真压缩等级标记高危信息可压缩等级设为0永不二次压缩早期文件内容被丢但后续仍需要滑窗淘汰日志采用摘要文件路径占位代理可按路径重新加载最后一个值得单独说明的排查技巧是滑窗和MCP的日志要分开看。滑窗日志记录的是消息何时被压缩、何时被删除MCP日志记录的是代理请求了什么上下文、服务端返回了什么。很多上下文问题在单个日志里看都是正常的但把两份日志放在时间轴上对齐之后才能发现真正的因果链。比如代理为什么忘记读取某个文件答案往往是它之前已经请求过一次scoped上下文但那次信息后来被滑窗压缩了而代理没有收到任何上下文被压缩的提示所以它以为自己仍然拥有这份信息。这属于两套机制之间的衔接问题我在后续版本中给ChatMemory增加了压缩通知回调把该信息已被精简的信号通过工具结果回传给代理代理就可以决定是否重新加载。这个改动看起来很小实际上把两个模块从各自为政变成了协同工作。最后分享一点个人体会。上下文工程很容易被理解成压缩一下对话历史这种表面功夫但真正做深之后你会发现它是编码代理所有能力的底层地基。滑窗解决的是信息生命周期管理的效率MCP解决的是信息获取的成本而这两者之上还需要对任务语义有足够的理解——知道什么样的上下文是真正重要的比知道怎样压缩大量的上下文更重要。我现在的做法是每次新增一个工具或记忆策略都会先问自己一个问题它到底是在帮助代理聚焦还是在给代理增加噪音这个问题不搞清楚上下文工程就会变成另一种形式的过度工程。
AI编码代理上下文工程：ChatMemory滑动窗口与MCP组合实践
最近一个月我几乎天天泡在AI编码代理的调试上。很多人问我为什么同一个模型、同一个工具别人能一口气完成跨文件重构我却总在第三轮就开始跑偏问题往往不在模型能力而在上下文。上下文工程这个词最近热度非常高但说到底就一件事在有限的上下文窗口里让代理始终掌握它当前最需要的信息。我在实际项目中把ChatMemory滑动窗口和Context-mode MCP两套方案结合起来算是把代理越干越傻这个老大难问题解决了大半。这篇文章把设计思路、参数计算和踩坑记录都摊开来聊给同样在做代理工作流优化的朋友一个参考。先交代一下背景。我手里的项目是一个基于Claude Code和自定义MCP Server搭建的代码评审代理日常要处理多文件改动分析、测试失败排查、需求变更落地这几类任务。早期版本在10轮以内的对话表现尚可一旦超过15轮、累计上下文超过4万token代理就会出现两类严重问题一是遗忘早期用户约束比如不要动公共接口签名这种硬性要求在20轮之后基本失效二是文件内容重复注入同一个文件被反复读取窗口里堆满冗余代码最终把真正有用的信息挤出窗口。这篇文章记录的就是围绕这两类问题的完整优化过程。1. AI编码代理的上下文困境先搞清楚问题在哪1.1 编码代理的工作循环与token消耗AI编码代理本质上是一个循环模型生成意图调用工具拿到结果再生成下一步意图。以Claude Code为例一次典型的文件修改任务会经历这样的循环读取目录结构几百token、打开目标文件几千token、生成diff、执行测试命令、读取测试输出。每一轮循环都会向上下文窗口追加新内容而这些内容几乎不会被主动清理。我做过一个粗糙的统计一次涉及3个文件的bug修复任务全程约25轮对话累计消耗的上下文量可以达到15万token以上而单模型上下文窗口上限是20万token。也就是说一个不太复杂的任务就能吃掉窗口的75%。如果中间有几次工具调用返回了冗长的报错堆栈或者代理反复检索同一个文件的多个版本窗口很快就会触顶。触顶之后不同工具的处理策略不同有的直接截断最早消息有的开始丢中间结果实际表现就是代理变得健忘和错乱。1.2 编码场景特有的上下文压力对话式AI的其他应用场景比如客服问答、文档总结上下文压力远没有编码场景大。编码任务有几个特殊性。第一代码本身的token密度极高。一段20行的函数定义可能包含300个token一个中等规模的文件就是3000到5000token而一次跨文件重构需要同时持有多个文件的上下文总量很容易突破2万token。第二编码任务的状态依赖极强。用户在第五轮说了一句这里用异步实现可能到第十五轮才真正动手改这段代码如果中间信息被滑出窗口代理就会按默认的同步方式实现偏离需求。第三工具输出冗余严重。测试框架的完整输出、编译器的警告信息、linter的报告文本往往包含大量与当前任务无关的噪音这些噪音会无情地占用窗口空间。1.3 先做预算把窗口当资源而不是容器在引入任何优化方案之前我建议先做一个动作给上下文窗口做预算拆解。把窗口分成四个区域——系统指令区通常固定占用2%到5%、用户需求区核心约束和当前目标、工具往返区每轮调用的输入输出、历史对话区早期多轮内容。预算设计的核心原则是历史对话区最应该被压缩因为它的信息价值密度最低工具往返区次之因为大部分工具输出可以被摘要替代系统指令区和用户需求区则应该被保护任何时候都不能被挤出窗口。我自己的预算比例是系统指令4%、用户需求15%、工具往返50%、历史对话31%。也就是说一个20万token的窗口留给历史对话区的预算是6.2万token一旦超出这个量级就必须启动压缩策略。这个预算数字不是拍脑袋定的而是根据多次任务失败率和token消耗的回归观察归纳出来的。如果你发现代理经常忘记早期约束优先压缩的是工具往返区而不是用户需求区这个方向错了再好的压缩算法都没用。2. ChatMemory滑动窗口让代理记住该记住的2.1 滑动窗口到底在滑什么ChatMemory是我参考社区几个开源记忆方案后在自己项目里落地的一套上下文管理模块。它的核心机制就是滑动窗口但这里要澄清一个容易混淆的点滑动窗口并不是简单地把最早的消息丢弃而是在一个固定大小的窗口内做动态调度。你可以把它想象成一个环形缓冲区。新的消息不断从尾部写入当总token数超过阈值时从头部开始淘汰旧消息。但淘汰不是一刀切每条消息会带一个优先级标记用户明确下达的指令优先级最高系统错误信息次之工具读取的文件内容优先级最低。窗口起步时我不淘汰高优先级消息而是优先压缩低优先级消息的内容——比如把一整份文件内容替换成一段摘要或者把完整的测试输出截断为启动失败端口被占用未执行用例。2.2 参数设计与计算窗口多长、步长多大、淘汰谁滑动窗口有三个关键参数需要调窗口长度总token预算、步长每次滑动多少消息、淘汰策略低优先级消息如何降级。这里给出一套可以直接套用的设计方法。第一窗口长度。总预算取模型窗口上限的60%到70%作为安全水位。之所以不取100%是因为要给工具返回结果留出突发余量避免一次较长的测试输出瞬间撑爆窗口。我以Claude 200k窗口为例安全水位设在130k token其中ChatMemory管理的历史对话区只占31%约40k token其余留给系统指令、用户需求和工具往返。第二步长。滑动步长不需要太小每次触发滑动时批量淘汰一批低价值消息而不是逐条淘汰。逐条淘汰的坏处是让代理频繁感知到上下文变化反而影响连贯性。我的经验是当超阈值达到5%时触发一次滑动一次性释放8%到10%的空间。第三淘汰策略。这里有一个微妙的点并不是所有早期消息都应该被保留而是只有和当前任务可能强相关的早期消息才值得保留。我用一句大白话总结窗口里留下的是约束和结论丢掉的是过程和原文。用户说过的硬性约束、你确认过的技术方案、已经定位到的问题根因这三类信息必须保留而代理长篇分析的思考过程、中间版本的代码片段、重复读取的相同文件内容这些都可以折叠成摘要。2.3 落地实现给代理挂一个可插拔的记忆模块在具体实现上我给代理增加了一个独立的memory模块通过事件钩子介入消息循环。核心数据结构是一个消息队列每条消息包含role、content、token数、优先级、时间戳、消息类型。每次模型收到新消息时先计算当前队列的总token数如果超出阈值就执行一次压缩。class SlidingWindowMemory: def __init__(self, max_tokens40000, summary_ratio0.8): self.messages deque() self.max_tokens max_tokens self.window_low_watermark max_tokens * 0.5 self.window_high_watermark max_tokens * 0.95 def append(self, message): self.messages.append(message) self._maybe_cleanup() def _maybe_cleanup(self): while self._total_tokens() self.window_high_watermark: candidate self._find_lowest_priority_message() if candidate is None: break if candidate.content_token_len 300: candidate.content self._summarize(candidate) candidate.compressed True else: self.messages.remove(candidate) # 压缩后如果仍超阈值直接淘汰最早的普通消息 while self._total_tokens() self.window_high_watermark: self.messages.popleft()这个实现里有几个设计细节值得说明。第一压缩优先于删除一条内容很长的工具输出先尝试用摘要替代而不是直接删掉这样保留了信息中的关键结论。第二低水位和高水位的双阈值设计低水位用来防止频繁滑动只有当总量超过高水位才触发清理清理到低水位就停避免乒乓效应。第三高优先级消息的保护逻辑优先级最高的消息即使排在队列最前面也不参与淘汰。实际运行中这套模块表现比较稳定。拿一次真实的重构任务来说整个任务累计产生了52条消息总token约8.6万滑窗压缩后实际进入模型的历史消息为31条约2.9万token而用户的关键约束保持公共API不变始终保留在窗口中。代理在最后一轮仍然能准确复述这个约束这在之前的无滑窗版本里是不可想象的。2.4 我踩过的坑滑窗不是万能的滑窗方案效果明显但我也踩过几次坑值得单独提醒。第一个坑是摘要模型带来的延迟。最初我选用的是一个本地小模型做摘要每次压缩需要额外等待2到3秒在多轮压缩时会明显拖慢整个代理的响应速度。解决办法是给压缩任务做异步化先把需要压缩的消息标记为待处理不阻塞主对话循环等下一个空闲时间片再批量生成摘要。如果你是做交互式工具这个顺序尤其重要宁可让代理先返回结果也不要为了压缩上下文而让用户反复等待。第二个坑是滑窗对长距离依赖的破坏。有些信息比如项目背景、架构决策、编码规范从对话开始就一直存在但它们不是用户在当前任务中显式说出来的而更像是隐性上下文。只靠滑动窗口这些信息很容易被滑出窗口。我后来把这类信息单独抽出来固化到系统指令中不再依赖对话历史携带。这样做之后即使窗口再怎么滑动项目级约束都不会丢。第三个坑是压缩的级联失真。摘要信息再次被压缩时会丢失越来越多的细节。比如第一次压缩把一段测试输出变成测试失败端口冲突第二次压缩可能变成有测试失败第三次可能就只剩存在测试问题。这种级联失真非常隐蔽代理表面上记得有问题但根本不清楚具体是什么问题。我的对策是高危信息不做二次压缩直接保留原始内容。优先级标记中专门加了一个可压缩等级字段等级为0的信息永不压缩、永不淘汰。3. Context-mode MCP把上下文工程服务化3.1 MCP的定位给AI编码代理加一个外置上下文接口滑动窗口解决的是历史对话怎么精简的问题但编码代理还有一个更刚性的需求它需要在某个具体时刻快速拿到某一部分外部上下文。比如代理正在修改一个函数需要知道这个函数在另外三个文件里的调用关系或者代理需要了解某个模块的整体结构而不是从零开始逐个文件读取。这时候如果只靠对话历史效率极低而且容易把无关内容带进窗口。MCPModel Context Protocol在这时候就派上用场了。我把它理解成AI应用的通用外设接口——它定义了模型怎样通过标准化的工具调用去获取外部数据而不需要开发者每次都为不同环境写一套不同的接入逻辑。MCP的核心概念包括Server提供工具和资源的服务端、Client嵌入在编码代理中的客户端、Tool模型可调用的能力入口和Resource静态但可被引用的数据源比如配置文件、文档片段。上下文工程如果只停留在代理内部做消息裁剪那还是被动防守接入MCP之后代理就能主动按需拉取上下文这才是主动出击。3.2 Context-mode的设计三种模式按需取上下文我落地的是一个叫context-manager的MCP Server对外暴露的核心工具是get_project_context。这个工具接收一个mode参数支持三种模式brief、scoped、full。brief模式用于快速浏览返回项目摘要、文件树、当前正在处理的文件清单token开销控制在1500以内。这一般作为任务开始时的侦察动作。scoped模式是主力它接收一个关键参数scope_name可以是函数名、文件名或模块名服务端会检索代码索引并返回该作用域的调用链、依赖文件和最近的git diff。full模式则通常只在用户明确要求全面梳理时才会被调用返回整个模块的完整结构和关键代码片段token开销在8000到15000之间。为什么要设计成三种模式而不是一个通用接口原因在于模型在真实运行中是贪心的。如果不限制工具的返回体量它倾向于一次拿到最多的信息而这恰恰和上下文预算的目标相反。Context-mode的本质是给工具的信息获取行为加一个预算约束让模型在探索信息和控制消耗之间做权衡。这个设计思路和ChatMemory的滑动窗口形成了互补一个是控制入口一个管理存量。3.3 服务端实现与客户端接入context-manager服务端在实现上不复杂核心是两部分代码索引和上下文组装。代码索引基于tree-sitter解析项目源码预先生成每个文件的结构化信息包括函数定义位置、函数调用关系、类成员列表。上下文组装则是在收到具体请求时根据mode参数进行检索和裁剪。{ name: get_project_context, description: 获取指定作用域的代码上下文支持brief、scoped、full三种模式, input_schema: { type: object, properties: { mode: { type: string, enum: [brief, scoped, full], description: 上下文获取模式 }, scope_name: { type: string, description: 作用域名称如函数名、模块名或文件名 }, max_tokens: { type: integer, default: 8000, description: 返回内容的token上限 } }, required: [mode] } }这个工具的定义有一个容易被忽视的点在description里明确写了max_tokens参数。我后来才发现MCP工具有没有token预算字段对模型的行为差异很大。如果没有这个参数模型会期望工具返回完整内容有了这个参数它就会预期我拿到的可能是一个裁剪版本并主动在后续调用中补充细节。客户端接入我主要试了两条路径。在Claude Code里直接在配置文件中注册MCP server{ mcpServers: { context-manager: { command: node, args: [/path/to/context-manager/build/index.js], env: { PROJECT_ROOT: /workspace/my-repo } } } }在Cursor类IDE里虽然MCP配置入口名称略有不同但协议一致只要服务端实现了标准的工具列表和调用接口客户端侧基本就是填一个URL或命令的事情。我实际测试过从服务启动到模型能调用get_project_context整个过程不超过三分钟。3.4 滑动窗口Context-mode MCP的组合数据流这两套方案组合起来之后代理的上下文流变成了一个让我比较满意的闭环。任务开始时代理先调用get_project_context的brief模式拿到项目骨架和当前任务涉及的文件清单这部分信息进入ChatMemory后标记为高优先级。随后代理进入工作循环每次需要深入了解某个函数或模块时会调用scoped模式获取局部上下文而不是直接用工具读取整个文件全量内容。ChatMemory负责管理这些上下文信息的生命周期优先保留scoped结果中的结论性信息比如load_config函数已被废弃应改用new_config_loader当窗口压力增大时优先压缩brief模式下得到的泛化信息。对比优化前后的一组数据一个中等规模的bug修复任务优化前平均消耗16.8万token代理实际可用的有效上下文用户约束当前文件状态测试反馈约5.2万token优化后总消耗降到7.3万token有效上下文占比提高到4.1万token。更关键的是任务成功率从54%提升到81%失败模式也发生了明显变化——优化前主要是代理遗忘需求导致的偏离优化后主要是测试环境问题这类外部因素。4. 常见问题与排查技巧实录4.1 症状一代理失忆关键需求执行到一半就歪了现象用户在对话早期明确说过不要改动数据库表结构但在第20轮之后代理仍然生成了包含ALTER TABLE的代码。这类问题排查的切入点是信息是何时被滑出窗口的。我的排查步骤是先开启ChatMemory的日志输出查看滑窗清理时被淘汰或压缩的消息列表然后定位包含不要改动数据库表结构的那条消息确认它的优先级标记和处理状态。90%的情况下问题出在优先级标记上——用户指令虽然在聊天界面上看起来是一条正文消息但在底层消息队列里可能被标记成了普通类型导致它和低价值的工具输出一起被压缩了。解决方法是给用户消息类型增加强制保留逻辑凡是roleuser且内容包含不要、必须、禁止、确保等约束类关键词的消息一律打上最高优先级并计入用户需求区的存量预算。另一种更稳妥的做法是把这类约束同时固化到系统指令区形成双保险。4.2 症状二工具返回结果爆炸窗口瞬间被占满现象代理执行一次git diff命令返回了2万行变更ChatMemory压缩还没来得及触发窗口已经被占满了。这类问题实际上是入口控制没有做好滑窗已经来不及兜底。我会从两个方向修复。第一在工具调用层做输出修剪在MCP Server端或者命令行工具包装层对返回内容增加行数限制超出的部分用前N行统计信息尾部摘要的结构返回。比如git diff可以返回共修改42个文件3800/-1200行以下为前200行diff把完整diff写入临时文件由代理按需再读取。第二在ChatMemory的队列中增加突发保护当单条消息的token数超过预设阈值我这边设的是总预算的15%时即使这条消息优先级很高也强制先做一次内容替换防止单人消息消耗整块窗口。4.3 症状三MCP工具调用频繁拖慢响应现象接入context-manager后代理出现了反复调用get_project_context的行为每次任务都要调用4到5次导致整体响应时间增加了3到4秒。这实际上是MCP Server缺乏缓存设计和频控管理。我做了三个优化。第一增加服务端缓存同一scope_name在短时间内重复请求直接返回缓存只有当用户手动触发刷新或者检测到文件变更时才失效。第二在工具描述中加入调用建议在description里写明优先使用scoped模式不要重复获取相同作用域模型读了之后会显著降低重复调用次数。第三在ChatMemory里对MCP返回内容做特殊标记已经获取过的作用域信息在后续轮次中直接从消息队列里检索复用而不是再触发一次网络调用。4.4 排查速查表症状优先排查位置推荐方案代理遗忘早期约束消息优先级标记约束类关键词强制保留同步固化到system prompt窗口瞬间被占满工具输出层、单条消息大小工具层输出修剪ChatMemory增加单条消息token上限代理反复调用同一工具MCP服务端日志增加缓存、描述中加入调用建议摘要级联失真压缩等级标记高危信息可压缩等级设为0永不二次压缩早期文件内容被丢但后续仍需要滑窗淘汰日志采用摘要文件路径占位代理可按路径重新加载最后一个值得单独说明的排查技巧是滑窗和MCP的日志要分开看。滑窗日志记录的是消息何时被压缩、何时被删除MCP日志记录的是代理请求了什么上下文、服务端返回了什么。很多上下文问题在单个日志里看都是正常的但把两份日志放在时间轴上对齐之后才能发现真正的因果链。比如代理为什么忘记读取某个文件答案往往是它之前已经请求过一次scoped上下文但那次信息后来被滑窗压缩了而代理没有收到任何上下文被压缩的提示所以它以为自己仍然拥有这份信息。这属于两套机制之间的衔接问题我在后续版本中给ChatMemory增加了压缩通知回调把该信息已被精简的信号通过工具结果回传给代理代理就可以决定是否重新加载。这个改动看起来很小实际上把两个模块从各自为政变成了协同工作。最后分享一点个人体会。上下文工程很容易被理解成压缩一下对话历史这种表面功夫但真正做深之后你会发现它是编码代理所有能力的底层地基。滑窗解决的是信息生命周期管理的效率MCP解决的是信息获取的成本而这两者之上还需要对任务语义有足够的理解——知道什么样的上下文是真正重要的比知道怎样压缩大量的上下文更重要。我现在的做法是每次新增一个工具或记忆策略都会先问自己一个问题它到底是在帮助代理聚焦还是在给代理增加噪音这个问题不搞清楚上下文工程就会变成另一种形式的过度工程。
