1. 为什么“把窗口拉大”解决不了编码代理的上下文问题
1.1 上下文不是存储器，是工作台
这两年我用过不少AI编码代理，从早期的单文件补全工具，到后来能自己改多文件、跑测试、修 bug 的 agent 型工具。最开始大家的思路都很朴素：模型记不住东西，那就把窗口做大。从 4K、8K 一路卷到 128K、200K，甚至还有奔着 1M 去的。听起来很美好，但真在项目里跑起来，你会发现一个问题——窗口变大了，AI 反而更容易“犯糊涂”。
原因在于，上下文对模型来说不是一块硬盘，更像是一张工作台。硬盘越大，能存的东西越多；但工作台越大，你放在上面的东西也越多，真正要用到的那份文件，反而可能被压在底下。模型处理长文本时，注意力是会被稀释的，中间位置的信息最容易被忽略。业界有个很出名的现象叫“lost in the middle”，你把关键约束放在第 80K token 的位置，模型大概率是看不见的。上下文窗口越大，这个问题越严重，因为无关信息会淹没关键信息。
我在实际项目中体会很深：一个 agent 任务，明明已经把所有相关文件路径和历史决策都塞进上下文了，它偏偏拿着一个过时的接口定义去改代码，改完还振振有词。后来我把上下文精简到只保留当前任务相关的 20 个文件，同样的任务，一次就过了。这不是玄学，是上下文管理的问题。
1.2 传统模式的三个致命伤
先说说传统方案到底死在哪里。第一个问题是“全量注入”。很多编码代理默认把仓库里的核心文件、目录结构、最近的 git diff 一股脑全塞进上下文。文件一多，token 字节数蹭蹭上涨，每一轮对话的延迟和成本都在涨，但模型真正能用到的有效信息比例反而在下降。
第二个问题是“无优先级”。所有信息在模型眼里是平等的，但现实世界中，不同信息的价值天差地别。仓库里的一个 README 和一段正在调试的报错日志，对当前任务的指导意义完全不在一个量级。传统模式不会区分这些，它只会按顺序把它们堆在一起。
第三个问题最隐蔽——“遗忘无感知”。上下文窗口是有上限的，塞满了怎么办？传统方案要么粗暴截断前面的内容，要么告诉你“超出限制，请开启新会话”。不管哪种，模型都不知道自己忘了什么，也不会主动去补回关键信息。结果就是，你明明告诉过它“不要改 database schema”，它过一会儿就忘了，直接在迁移脚本里动了表结构。
1.3 一句话理解 Context Mode
所谓 Context Mode，本质上是把“尽可能多地把东西塞给模型”换成“让模型按需取用、主动管理自己的工作上下文”。它不是一个简单的开关，而是一整套机制：知道当前任务需要什么、哪些信息已经过期可以被压缩、哪些信息必须置顶不能被遗忘、以及当窗口不够时如何自动淘汰价值最低的内容。
一句话总结：传统模式是“仓库管理员把整个库房都搬到你面前，你慢慢翻”；Context Mode 是“按你的需求，把最可能用到的几样东西放到触手可及的位置，其他东西随取随用”。后者才是编码代理真正该有的样子，这也是我这篇文章想重点展开的东西。
2. Context Mode 的核心设计：从“全塞进去”到“按需取用”
2.1 第一支柱：上下文分层与作用域隔离
Context Mode 的第一个核心设计是分层。所有信息不再平铺在一个大池子里，而是按照作用域划分成几层。你可以把它类比成 CPU 的缓存体系：寄存器、L1、L2、内存、磁盘，每一层的容量和访问速度都不同，数据按热度在其中逐级流动。
在编码代理里，我常用的分层方式是这样的：
- 核心层：当前任务的主线目标、正在修改的文件的完整内容、最近一次运行的报错信息。这部分必须原样保留，不能压缩。
- 工作层：需要交叉引用的相关文件片段、当前分支的 diff、涉及到的函数调用链。这部分可以用局部片段或摘要呈现。
- 背景层：项目整体架构说明、编码规范、历史决策记录。这部分通常只在特定环节才需要，可以做成检索式读取。
- 归档层：已经确认无用的历史对话、与当前任务无关的旧版本内容。这部分直接不占用窗口空间。
分层的价值在于，模型每次推理时只需要面对“核心层 + 工作层”的精简上下文，而不是整个仓库。我在实际项目里测试过，同样的任务，分层之后 token 消耗降了大约一半，任务成功率反而有所上升。原因很简单，干扰项变少了，模型更专注于当前任务。
这里有一个非常关键的实现细节：层与层之间不是静态的。任务进行到不同阶段，某个文件可能从背景层被拉进工作层，也可能从工作层降级为归档层。这个升降级动作可以由规则触发，也可以由模型自己决策，但必须有明确的机制，而不是靠运气。
2.2 第二支柱：活跃子上下文的主动压缩与摘要回填
分层解决的是空间利用效率，但窗口总归是有限的。Context Mode 第二个核心设计，是对不重要的上下文做主动压缩，并且用摘要回填。这一点特别考验设计功力。
简单说，当某一段上下文长时间没有被引用时，代理会把它从“完整内容”压缩成“摘要”。摘要里只保留关键结论和必要的引用锚点——比如“用户确认不再支持 Python 3.8，相关代码已迁移到 3.10+ 语法”。下次模型需要用到这段内容时，它基于摘要做一个判断：摘要够用就直接用，不够用再通过检索去拉原始内容。
这个机制的价值在于，它让模型的“记忆”不再是一条单向流水线，而是一个可回收的内存池。我见过一个让我印象很深的场景：代理在修复一个跨模块的 bug 时，改了 A 模块的函数签名，后来去改 B 模块的调用点。因为 B 模块的内容在上下文里被压缩了，代理主动写了一句“基于之前的摘要，这里应该调用新签名parse_config_v2，我来确认一下原始实现”，然后触发检索把 B 模块相关片段拉回来，确认无误后再改。这个行为已经非常接近一个成熟工程师的工作方式了。
但摘要回填也有一个很大的坑：如果摘要生成得不准，或者压缩得太狠，关键细节被丢了，那么后续的所有决策都会建立在错误的地基上。所以实际落地的时候，摘要必须保留“谁、什么时间、为什么、影响范围”这类关键要素，而不是简单地“这段内容是讲配置的”。这部分我在后面踩坑部分还会详细说。
2.3 第三支柱：语义检索驱动的按需加载
分层和压缩负责“减少不必要的信息”，语义检索负责“在需要的时候找到正确信息”。这是 Context Mode 的第三个设计支柱。
传统的关键词匹配在代码场景里非常不靠谱。你搜一个函数名user_login，可能有一百个匹配结果，但真正和当前任务有关的调用关系，未必出现在关键词里。语义检索不一样，它基于 embedding 向量做相似度匹配，能理解“这段代码涉及到用户会话失效的判断”和“当前任务需要处理登录态过期”之间的语义关联。
你可能会问：这和 RAG 有什么区别？确实底层技术相似，但 Context Mode 里的检索有一个重要差异：它检索的不只是文档片段，还包括代码结构、调用关系、函数签名、甚至 git 历史里“谁改过这段代码、为什么改”这类元信息。也就是说，检索的目标不仅仅是“找内容”，更是“找关联”。
实际实现上，我建议做两级索引：第一级是仓库级索引，负责在全局范围定位相关文件；第二级是会话级索引，负责在本次任务相关的上下文中定位精确片段。这两级索引配合使用，大部分情况下都能在 1-2 次检索内命中目标。如果检索结果不理想，不要急着调 embedding 模型，先检查索引构建的粒度是不是有问题——把整个文件作为一个 chunk，和把函数拆成独立 chunk，检索效果会差很多。
3. 落地实现：一个可参考的 Context Mode 配置与工作流
3.1 三层存储：上游仓库索引、会话局部视角、代码块级缓存
纸上谈兵说了这么多，落到实际工程里，Context Mode 的实现通常需要三层存储来支撑。
第一层是上游仓库索引层。这一层负责对代码仓库做离线或准实时的向量化索引。每个文件会被拆分成函数、类、代码块等粒度，并提取函数签名、依赖关系、文件路径等结构化信息。描述文件时可以采用“路径 + 符号名 + 摘要 + embedding”的结构存储。这一层不参与对话推理，只为检索提供数据。
第二层是会话局部视角层。每个编码对话会维护一个“局部视角”，它决定了在当前任务中，哪些文件是熟悉的、哪些是陌生的。实现上就是一个轻量级数据库，记录每个文件在会话中的首次出现时间、被引用次数、最近被引用时间、当前状态（完整/摘要/已归档）。这个局部视角是上下文调度的决策依据。
第三层是代码块级缓存层。这一层存储的是最近被实际注入过上下文的代码片段。缓存的目的很简单：避免同一段代码被反复检索、反复注入，浪费 token 和延迟。如果某段代码在一次会话中被引用多次，直接从缓存取即可。
三层存储的逻辑关系是：仓库索引负责全局定位，局部视角负责判断“这个文件值不值得拉进来”，代码块缓存负责“拉进来之后怎么减少重复开销”。三者缺一不可，少了任何一层，Context Mode 都会出现明显的性能回退。
3.2 上下文调度策略：优先级、热度和依赖稀疏度
存储解决了“信息放哪”，调度解决“什么时候把什么信息放到上下文里”。这块是 Context Mode 里最有技术含量的部分，也是各家用得最不一样的地方。
我在实践中验证过比较有效的调度策略有三个维度：
- 优先级：任务主线目标、当前正在编辑的文件、最近一次报错，这几类信息永远不能被压缩或淘汰。调度器会给它们打上最高优先级标记。
- 热度：类似于缓存淘汰机制中的 LRU 思路。被频繁引用的代码，热度高，保持在完整状态；长时间没被引用的代码，热度衰减，降级为摘要或归档。热度衰减的时间窗口可以配置，通常按任务复杂度调整。
- 依赖稀疏度：这是一个我在实践中加进来的维度。有些文件虽然是当前任务需要的，但它被引用的频率很低，只在某个特定环节出现一次。对于这类文件，没必要在任务一开始就塞进上下文，可以延迟加载到需要的那一刻再注入。比如一个项目里只有初始化阶段会用到的配置注册表文件，就可以做延迟加载。
这三个维度的权重不是固定的。我自己的经验是，在修 bug 类任务里，优先级的权重应该提高，因为修 bug 需要极强的目标感；在做代码审查类任务里，热度的权重可以提高，因为审查需要覆盖更多文件；在跨模块重构类任务里，依赖稀疏度的权重必须提高，否则会因为上下文里堆积太多被引用的文件片段，导致模型丢失整体视野。
调度策略的配置化非常重要。不要把这套逻辑写死在代码里，而是抽成策略配置，让用户能按任务类型调整。一个简单但有效的做法是：在任务启动时让用户选择一个任务类型（修复、重构、审查、实现新功能等），每个类型对应一套默认的调度参数。
3.3 配置示例与参数解读
这里给出一份基于 JSON 的配置示例，字段设计和参数取值都来自我实际跑过项目的调参经验。大家可以直接当作参考起点，再根据自己项目的规模和团队习惯调整。
{ "context_mode": { "enabled": true, "layer_policy": { "core": { "max_tokens": 12000, "protection": "never_evict" }, "working": { "max_tokens": 24000, "idle_decay": 10 }, "background": { "max_tokens": 8000, "idle_decay": 5, "summarize_threshold": 3 } }, "retrieval_policy": { "index_granularity": "function_plus_class", "chunk_size": 200, "top_k": 5, "embedding_model": "default", "enable_session_index": true }, "schedule_policy": { "mode": "task_aware", "priority_weight": 0.5, "heat_weight": 0.3, "dependency_weight": 0.2 }, "session_persistence": { "summary_strategy": "key_facts_style", "persist_path": ".context_mode/session.json" } } }参数不多，但每一个都有实际含义。
layer_policy里，core层的max_tokens设 12000，是因为核心层必须给足空间放完整文件内容，但又不能设得太大，否则会挤占工作层的容量。protection: "never_evict"表示核心层内容永不淘汰。working层的idle_decay: 10，意思是连续 10 轮对话没有被引用，热度就降一级；background层的summarize_threshold: 3，表示连续 3 轮未被引用就触发摘要压缩。
retrieval_policy里的index_granularity: "function_plus_class"是我最推荐的分块粒度。按函数（小函数）或者类（大结构）划分索引单元，检索精度远高于按固定 token 数量切块。chunk_size: 200表示每个检索结果最多返回 200 个 token 的片段，这个值不宜太大，否则一次检索返回的内容过多，又回到“信息过载”的老问题。top_k: 5表示每次最多取 5 个候选片段。
schedule_policy里的权重分配，是我做通用场景时的默认值：优先级占一半，热度占三成，依赖稀疏度占两成。如果任务偏重构，我会把依赖稀疏度权重调到 0.35，优先级降到 0.4。
schema里有一项很关键：session_persistence。它表示会话状态会持久化到本地文件，这样即使中途断线或者开启新会话，也能基于上次的上下文状态继续工作，而不是完全从头再来。
这个配置可以直接当模板用。我见过不少人把max_tokens调得很大，觉得“Context Mode 上限越高越好”，这是个误区。上下文管理的目标不是塞得多，而是塞得准。实际对比下来，核心层 12000 + 工作层 24000 + 背景层 8000 的组合，在绝大多数中型项目的 agent 任务里，成功率已经明显优于单层“一锅炖”的 64K 窗口配置。
4. 实操中踩过的坑与排查思路
4.1 摘要回填导致的关键约束丢失
先讲一个我在实际项目里踩过最深、也最有代表性的坑：摘要机制误伤关键约束。
事情的经过是这样的。当时我让编码代理做一个权限系统的改造，任务开始的时候，我在对话里明确说了一句：后端接口的响应格式统一使用{ code, data, message }，不允许直接返回裸对象。这条约束最初存在于核心层，模型执行得很好。但跑了十几轮之后，调度器判断这条信息属于“历史对话引用热度低”的内容，对它做了摘要压缩。摘要生成的时候，把“不允许返回裸对象”这个否定性细节给丢了，只剩下“响应格式为{ code, data, message }”。
结果模型在一个新文件的接口实现里，直接返回了裸对象，还自我感觉良好。因为摘要里没有提到“不允许”这个约束，它在逻辑上并没有违反任何“现存规则”。这就是摘要回填的典型风险：信息没有丢，但关键语义反转丢了。
我的解决方法是加了两道防线。第一道：在调度策略里，限定“否定性约束、安全敏感配置、用户明确强调的偏好”这三类内容不允许降级为摘要，只能完整保留在核心层。第二道：摘要生成后，增加一个校验逻辑——用摘要内容和原始内容分别让模型回答一个与关键约束相关的问题，如果答案不一致，说明摘要丢失了关键要素，需要重新生成或者放弃摘要。
这两道防线加上的代价是系统多了一点计算开销，但换来的是任务可靠性的显著提升。从那以后，再没有出现“约束被静默遗忘”导致的返工。
4.2 检索命中率低：又是查不全，又是查不准
Context Mode 里另一个高频问题是检索质量不稳定。表现特征有两类：一类是“查不全”，明明项目里有相关代码，但检索结果里没有出现；另一类是“查不准”，搜出来的内容相关度不高，白白浪费了注入 token。
“查不全”的原因，绝大多数在索引层。我排查过几次之后发现，病根集中在分块策略上。很多实现按固定行数或固定 token 数量切块，导致一个完整的函数被切成两半，语义被切断，embedding 质量自然差。比如一个 80 行的函数，按 50 行切块，前面 50 行是一个 chunk，后面 30 行是另一个 chunk，检索时命中了包含调用逻辑的后半部分，却丢失了前半部分的参数定义。
解决办法是改成“语法感知分块”。用解析器识别函数、类、方法定义边界，确保每个 chunk 都是逻辑完整的代码单元。对于过长的函数（超过 300 行），再按内部职责段落二次拆分。这个改动在索引构建时成本会增加，但对检索质量的提升非常明显。
“查不准”的原因则要复杂一些。常见的原因有三个：top_k设置太小，候选集根本覆盖不到真正的目标；embedding 模型对代码语义理解不足，把不相关但字面相似的内容顶了上来；还有就是检索时机不对——有些信息在编译期才会暴露，静态检索当然搜不到。针对这三种情况，我的建议分别是：把top_k从 3 提到 5，配合二次重排序；代码场景不要用通用文本 embedding，选择针对代码或至少中英混合语料优化的模型；对编译类信息的检索，需要在检索结果为空时自动附加一次构建日志或报错信息的分析，而不只是重新检索代码库。
4.3 几类典型异常现象速查
除了上面两个大的方向，实际跑 Context Mode 的过程中还会遇到一些零碎但让人头疼的异常。我整理成一张速查表，大家在开发或调优的时候可以直接对照。
| 异常现象 | 可能原因 | 排查建议 |
|---|---|---|
| 模型反复引用同一段过时代码 | 代码块缓存没有失效机制 | 检查缓存是否带文件哈希，文件变更后未自动失效 |
| 任务中后期响应质量明显下降 | 核心层内容被调度器误降级 | 检查 core 层是否设置了never_evict，确认没有“最高优先级”之外的例外 |
| 检索结果总是同一批文件 | 会话级索引与仓库级索引冲突 | 检查会话索引的权重是否过高，掩盖了仓库索引的全局性 |
| 上下文占用很久不下降 | 热度衰减参数失效 | 确认idle_decay的计数单位是“轮对话”还是“时间”，建议统一为轮数 |
| 摘要后的内容与原内容风格差异大 | 摘要模型选型与任务语言不匹配 | 摘要尽量使用和主模型同系列或同规模的模型，避免用轻量模型做重要约束的摘要 |
还有一个容易被忽略的点：会话持久化文件的安全。前面配置里提到.context_mode/session.json会保存会话状态，这个文件里如果包含敏感信息（比如密钥、内部域名），务必加入项目.gitignore。我就见过一次事故，团队里有人把带有生产环境数据库地址的会话摘要提交到了公共仓库，虽然及时发现撤回，但已经是公开状态。这不是 Context Mode 本身的错，却是在启用它之后必须额外承担的安全责任。
5. 延伸思考：Context Mode 之外，编码代理还缺什么
5.1 上下文管理是基础设施，不是功能
把 Context Mode 做了几轮迭代之后，我的一个明显感受是：上下文管理不是一个“锦上添花”的功能，而是编码代理的底层基础设施。它决定了代理的上限在哪里。
举个例子，同样一个跨模块重构任务，在上下文管理良好的工具里，代理可以连续执行几十步操作，每一步都基于准确的信息做决策；在上下文管理混乱的工具里，代理做几步就会开始“猜”，因为原始信息被淹没或者被截断了。这不是模型能力的差距，而是同一颗大脑在不同工作台上的表现差异。
我之前提到的分层、压缩、检索、调度，本质上都是在做一件事：让模型在正确的时间，把注意力放在正确的信息上。这件事短期内不会因为模型上下文窗口变长而失去意义。哪怕有一天模型支持 10M token 的窗口，信息检索和注意力分配的问题依然存在——窗口越大，模型越需要知道该看什么。
所以我把 Context Mode 看作所有编码代理能力提升的基石之一。工具链里任何其他能力——代码修改、测试执行、多文件协调——都建立在“模型对当前状态有准确认知”这个前提上。前提不牢，地动山摇。
5.2 优化上下文管理的一些推荐方向
给团队或者个人开发者几个方向性建议。
第一，如果你们正在基于大模型做自己的编码代理，不要先把精力花在“让模型生成更长的代码”上，先做一套扎实的上下文调度。这个投入产出比极高。
第二，在配置 Context Mode 的时候，一定要把“任务类型”作为第一维度的变量来考虑。修 bug、重构、写新功能、做代码审查，这四种任务对上下文的需求差异非常大。一套配置走天下，效果一定平庸。
第三，重视会话持久化对团队协作的价值。Context Mode 维护的会话摘要如果写得足够好，它本身就是一种知识沉淀。新成员接手任务时，可以从上一个执行者的会话摘要里快速了解背景，而不需要重读一堆零散的通知和对话记录。
这些都是我在项目和社区交流中得到的真实体会。说实话，“上下文管理”这个词听起来没有“代码生成”那么性感，很多团队在搭建 AI 编码工具时，一上来就追求模型能写出多复杂的算法，忽略了可持续高质量输出背后的工程支撑。但恰恰是这些不起眼的工程结构，决定了工具在真实场景里到底好不好用。如果你也在做类似的方向，希望这篇文章里的经验和教训能帮你少走几步弯路。
