做 AI 编码代理的人基本都会撞上同一堵墙上下文。不管是基于 Claude、GPT 还是开源模型做 Code Agent前期跑通 Demo 都很快一旦进入真实项目——几千个文件、几十次迭代、多轮任务穿插——模型就开始“失忆”改 A 文件忘了 B 文件的约束明明项目里写好的规范就是不遵守甚至把旧需求当新需求继续做。我最近半年几乎把所有时间都花在解决这个问题上最后收敛到的答案就是标题里这个 Context Mode。它不是一个模型不是一个 Prompt 技巧而是一套专门给编码代理设计的上下文管理范式——把“模型能看多少”从被动承受变成主动治理。这篇文章我会把它的设计思路、分层结构、参数调优和落地实现从头拆到尾适合正在做 AI 编程工具、Agent 框架或者被 Cursor / Claude Code 这类工具的长上下文问题折磨过的同学参考。1. Context Mode 是什么先从一个最现实的痛点说起1.1 上下文窗口不是越大越好很多人第一反应是上下文不够换大窗口模型不就行了我一开始也这么想128K、200K、1M token 的模型轮着试结果发现窗口越大问题越隐蔽。大窗口确实装得下更多内容但模型对海量信息的注意力是稀疏的中间段落经常被“漏读”。更麻烦的是塞进去的内容如果相互矛盾模型往往会采信离当前对话更近的那段这就导致一种非常诡异的现象项目文档明明写着“统一使用 pnpm”你对话里早先说过一句“先凑合能用 npm”模型后续真的就用 npm 了。这不是模型笨是信息架构的问题。把一万条信息平铺给模型等于让它在噪音里找信号。Context Mode 要解决的不是“能不能装下”而是“该装什么、按什么顺序装、装不下的怎么处理”。1.2 Context Mode 的定义与边界我给 Context Mode 的定义是一套显式的上下文治理机制由代理在运行期间动态决定哪些信息进入模型视野、以什么形态进入、以及什么时候被清除或归档。它通常包含三个层次——工作内存当前任务相关的短期信息、项目记忆代码库和文档的可检索索引、长期档案跨会话沉淀的决策与结论外加一个路由模块负责在三层之间做切换。注意区分两个概念Context Mode 不是模型的 system prompt也不是 RAG 的简单翻版。系统提示词是静态的规则RAG 是“问一次查一次”的检索补充而 Context Mode 是一整套状态管理——它知道当前任务做到哪一步、哪些文件被改过、哪些结论已经验证过、下一步最可能需要什么。它是编码代理的“工作台”不是“图书馆”。2. 为什么编码代理必须换一套上下文管理范式2.1 会话问答与自主代理的本质差异如果你只写过一个聊天机器人可能感受不到上下文管理的压力。聊天是一次性的用户问完对话结束历史记录只是背景资料。编码代理不一样它要在一个长期任务里连续做决策先读代码再改文件再跑测试再根据报错修复每一轮的输出都成为下一轮的输入而且这个过程可能持续几十分钟横跨十几个文件。这就产生了一个会话模型没有的硬约束状态一致性。聊天答错了可以重来代理改坏了代码是要付代价的。代理必须记得自己刚才写了什么、为什么这么写、哪些约束是不能碰的。Session 型上下文管理根本承载不了这种需求它只会让对话越滚越长直到把模型“灌晕”。2.2 我见过的五种典型失效现场这些场景我在实际项目里都真实遇到过列出来大家对照一下失效场景现象描述根因需求漂移代理改了 30 分钟后突然按照旧需求继续开发早期对话被挤出窗口只留下最新片段约束冲突项目规范要求 RESTful代理却用 RPC 风格写接口全局规范没有被检索到局部示例占了上风重复劳动代理反复生成一个已经写好的工具函数索引缺失代理不知道代码里已存在实现幻觉引用代理引用了一个不存在的 API 或配置文件长文本中位置编码衰减模型记忆模糊越改越乱修复一个 bug 却破坏了另一个模块上下文里有 A 模块信息但缺失与 B 模块的关联这五类问题的共同点都不是模型能力不够而是“该看到的信息没看到不该看的倒是一直在”。Context Mode 的设计目标就是把这五类问题一次性收敛掉。2.3 四种管理范式的对比与取舍目前市面上常见的做法大概有四类全量注入、滑动窗口、分层摘要、Context Mode。前三种我都试过各有各的死穴。全量注入最简单把整个仓库塞进上下文适合文件总数少于 50 个的玩具项目滑动窗口只保留最近 N 轮对话实现成本低但必然导致需求漂移分层摘要把历史对话递归压缩成摘要比滑动窗口好一些至少不会彻底失忆但摘要会丢掉细节比如具体的文件路径、精确的函数名。Context Mode 跟前三者的本质区别是它把“哪些信息优先级最高”从隐式变成显式并通过检索和路由让代理始终看到的是“当前任务的信息快照”而不是“对话历史的连续切片”。3. 拆解 Context Mode 的分层结构与切换逻辑3.1 工作内存只保留当下要用的工作内存对应的是“此刻模型视野里应该有什么”。它不是对话历史而是一份结构化的任务快照。我在实现里把它设计成四块任务描述当前目标的精炼表述每次任务切换时重写绝不自增。相关文件内容做过相关性排序后的文件按重要程度截断不是整文件硬塞。变更记录本次会话里已经改过的文件以及每次改动的动机用于防止越改越乱。活动约束当前必须遵守的规则比如“不要动数据库迁移脚本”“测试必须通过”。工作内存的容量一般控制在 8K 到 16K token 之间。超过这个量与其硬塞不如把信息降级到下一层。很多人在这一步舍不得截断结果就是前 30 分钟好好的后面整个上下文变成一个垃圾场。3.2 项目记忆让代理学会“翻代码”项目记忆层解决的是“代理不知道代码库长什么样”的问题。核心是一个可检索索引我通常用向量数据库存代码块的语义向量同时保留一个倒排索引用于精确匹配文件名和符号名。为什么不用纯向量因为函数名、变量名这种高精度信息向量检索常常匹配不准倒排索引的命中率反而更高。双路召回之后再合并排序效果比单路好得多。这一层的触发时机很关键不是每一轮都检索而是当代理需要了解某个模块、某个符号、或者判断某个改动的影响范围时才触发检索。触发信号可以是显式的工具调用也可以由路由模块根据当前任务状态预测。检索结果会写回工作内存但只保留摘要完整内容在需要用的时候再展开。3.3 长期档案把结论沉淀下来跨会话的长期记忆是很多 Agent 框架做得最差的部分。大多数工具关闭会话之后上下文就清了下次打开又是从零开始。Context Mode 要求把每次会话的关键结论固化到长期档案里内容至少包括改动了哪些文件、为什么这么改、验证结果是什么、有哪些遗留问题、有哪些被否决的方案及否决原因。这些内容平时不进入模型视野只在三种情况下被调取新任务涉及同一批文件、代理准备修改曾经改过的代码、或者路由模块发现当前任务与历史任务相似度很高。长期档案的存储格式我推荐用 Markdown 配合结构化字段方便用文本检索也方便模型直接阅读。3.4 路由与切换Context Mode 的灵魂三层结构本身不稀奇真正难的是路由逻辑——什么时候该把工作内存里的某段内容降级到项目记忆什么时候该把长期档案里的结论提升到工作内存。我见过不少实现把三层做成三个独立工具让模型自己选。结果模型经常选错该查索引的时候不查不该查的时候猛查。我的做法是把路由写成规则与预测混合显式规则负责强约束比如文件变更后必须刷新该文件在工作内存中的缓存预测模型负责弱信号比如根据任务描述预测下一步可能需要的模块。切换动作本身必须是原子的——也就是说切换期间模型不会读到半新半旧的状态要么切完再生成要么就不切。4. 核心参数与调优把 token 预算花在刀刃上4.1 三层 token 预算怎么分Context Mode 落地时最先要确定的就是每一层的 token 预算。我的默认分配方案如下层级预算占比典型容量按 128K 窗口说明工作内存40%约 50K任务快照、相关文件、变更记录项目记忆索引10%约 12K当前轮检索召回的内容长期档案摘要5%约 6K跨会话结论的压缩呈现系统指令与工具定义10%约 12K规则、工具 schema、安全边界预留缓冲35%约 48K模型输出、测试报错、临时内容这个比例不是拍脑袋定的。预留 35% 缓冲非常重要因为测试命令的输出、编译报错、模型长输出经常会瞬间吃掉大量 token。预算不足导致模型输出被截断是整个流程里最隐蔽的失败模式报错信息后半段丢了模型拿着半截信息去修复越修越错。4.2 检索参数Top-K、相似度阈值、重排序项目记忆的检索质量比模型本身更影响最终效果。我常用的参数向量 Top-K 取 20倒排索引 Top-K 取 10合并去重之后用重排序模型压到 5 到 8 条。相似度阈值设置在 0.65 到 0.75 之间低于阈值的宁可不召回避免噪音污染工作内存。很多人会把 Top-K 调大觉得多召回总比漏掉强。实测下来完全不是这么回事召回越多无关代码占用工作内存的比例越高真正相关的代码反而被稀释。宁可漏不可滥这是检索型上下文管理的基本原则。漏了可以靠路由模块补一次针对性检索滥了则会把模型注意力带偏代价更大。4.3 压缩策略摘要不是简单截断对超长文件、超长历史做压缩时最忌讳的就是截断。截断会让信息在任意位置消失模型甚至不知道自己错过了什么。我采用的是“结构化抽取 递归摘要”两步先把文件里的关键信息抽出来——函数签名、导出符号、对外依赖、重要注释——形成一份紧凑的“代码卡片”如果代码卡片仍然太长再对它做分层摘要按目录树自底向上逐层压缩。这套策略对历史对话同样适用每一轮对话结束时把这一轮的关键决策抽成结构化记录包括结论、依据、涉及文件、下一步行动。十几轮的对话压下来可能只剩 1K token而关键信息一个都不会丢。4.4 一组实测参考值我在一个约 800 文件的中型后端项目上做过一组对比实验基线是“全量注入最近对话 相关文件”实验组是完整 Context Mode。同样 10 个开发任务基线组完成 4 个Context Mode 完成 8 个基线组平均每任务消耗 86K tokenContext Mode 是 41K。最明显的变化出现在跨文件修改任务基线组经常把新逻辑写到错误的位置而 Context Mode 能把“该文件依赖了哪些模块”正确地送进上下文。5. 落地实现搭一个最小可用的 Context Mode5.1 存储层设计整个系统可以拆成三块存储、检索、路由。存储层我用一个简单的 JSON 结构作为工作内存的载体长期档案则落到本地目录每个项目一个文件夹。{ task: { goal: 为订单模块增加取消接口, status: implementing, constraints: [不修改支付流程, 保持现有异常处理风格] }, files: [ { path: src/order/service.py, relevance: 0.92, mode: full, digest: 订单核心服务包含 create_order 与 update_status } ], changes: [ { path: src/order/service.py, action: add cancel_order, reason: 需求要求支持取消未支付订单, status: pending_test } ], archive_refs: [2025-11-03-order-refactor.md] }这里的 key 点在于files 里每项都有 mode 字段标记是 full完整内容进上下文还是 digest仅摘要进上下文。路由模块根据当前阶段动态调整比如在实现阶段 service.py 是 full在写测试阶段可能降级为 digest。5.2 检索与路由实现检索层我用了一个非常轻量的方案代码文件先按函数和类切块每个块生成两路索引——向量索引存语义倒排索引存符号名。路由是一个纯函数输入是当前任务状态和模型上一次的工具调用记录输出是三个动作之一keep保持现状、promote把某条项目记忆提升到工作内存、demote把某条工作内存降级为摘要。def route(state: TaskState) - list[RoutingAction]: actions [] for f in state.working_memory.files: if f.mode full and f.last_access_turns 6: actions.append(RoutingAction(demote, f.path)) # 若代理连续两次检索同一模块说明该模块应常驻工作内存 repeated state.memory.recent_retrievals.most_common(1) if repeated and repeated[0][1] 2: actions.append(RoutingAction(promote, repeated[0][0])) return actions这个路由逻辑虽然简单但解决了“切换震荡”问题demote 有延滞6 轮未访问才降级promote 有确认重复检索才提升。实际跑起来工作内存会稳定收敛到当前任务真正需要的文件集合上。5.3 与代理框架的接入点接入点放在两个位置工具层和对话层。工具层给代理暴露三个新工具recall检索项目记忆、commit_note把当前结论写入长期档案、compact触发一次工作内存压缩。对话层在每轮生成之前插入一个 context_manager 钩子执行路由函数并更新工作内存。我踩过一个坑把路由放在模型生成之后。这样会导致模型已经基于旧上下文生成了内容路由再切也没意义还得重新生成浪费一轮。正确的顺序一定是先切上下文再让模型生成。5.4 一次真实运行演示拿一个真实场景演示代理接到任务“给用户模块增加导出 CSV 功能”。第一轮工作内存里只有任务描述和用户模块的入口文件。代理调用 recall 工具检索到 export 相关工具函数和一个类似的 Excel 导出实现。路由模块检测到代理连续两次检索 user_service 模块把它提升为 full 模式。第二轮代理基于完整上下文写出实现调用 commit_note 把“导出逻辑复用 utils/exporter.py 的流式写法”记入长期档案。整个任务耗时三轮token 消耗 18K而之前用全量注入方式做类似任务要 60K 起步。6. 常见问题与排查实录6.1 检索不到关键代码这是最常被问的问题。根源通常在索引切块代码块切得太粗一个文件一个块语义模糊召回自然不准切得太细一个函数一个块丢失了上下文召回了也不知道这个函数属于哪个模块。我的经验是以函数和类为基本单位同时给每个块附带文件路径、模块名、函数调用关系等元信息检索时把元信息也参与匹配。还有一个容易被忽略的点倒排索引的分词器。拼音风格的变量名、驼峰命名的函数在中文分词下经常被拆得七零八落。我会额外维护一份符号表把完整符号名当作不可切分的整体精确匹配永远优先。6.2 上下文漂移上下文漂移的表现是代理越往后做越偏离初始需求。排查看下来多半是工作内存里的任务描述被挤出去了或者被中间生成的临时结论污染了。解决方案有两个缺一不可任务描述必须锚定在最顶部且不允许被追加每次变更记录只保留动机不保留过程细节。过程细节是上下文漂移的最大温床模型看到自己十分钟前说过的一句试探性话往往会当真。6.3 切换震荡如果路由策略切换太频繁模型会表现出“状态不安定”——一会儿认为某个模块已经实现一会儿又认为它还没实现。这通常是因为 promote 和 demote 的阈值太接近模型一检索就提升两轮没用就降级反复横跳。我的解法是给两个动作都加滞回区间promote 需要连续两次检索命中demote 需要超过 6 轮未被访问。这跟硬件设计里的滞回比较器是一个思路目的就是消除抖动。6.4 超时与 token 超限运行中期的突然失败大概率不是模型问题而是某一轮测试输出异常巨大把预留缓冲吃光了。我在代码里加了一道保险工具输出的最大字节数写死在工具 schema 里超过 8000 token 的输出强制截断并提示“结果过长已截断可针对性查看文件”。宁可让代理多调一次工具也不要让一次超长输出毁掉整个上下文预算。6.5 问题速查表症状可能原因处理办法代理找不到已有实现索引缺失或切块过粗重建索引按函数切块并增加元信息改 A 坏 B工作内存缺 B 模块引用路由增加“变更影响分析”触发检索上下文越用越乱工作内存未做降级调低 demote 轮数窗口强制压缩代理重复生成相同代码长期档案未覆盖该模块检查 commit_note 是否真正写入模型输出被截断缓冲预留不足增加缓冲占比限制工具输出长度7. 几个踩过坑之后才懂的经验最后说几个不在教科书里、但真实决定成败的细节。第一个是“上下文管理要防呆”不要把完整文件路径交给模型拼接路径经常被拼错直接在文件卡片里给出标准化路径让代理照着用。第二个是“不要迷信 embeddings”——对代码语义检索来说符号名和调用关系的权重应该高于向量相似度我会在召回后做一个简单的规则重排凡是命中符号表的候选直接提到向量候选前面。第三个是“压缩要可追踪”每次压缩都在档案里留一条记录写清楚“原始内容在哪个文件可以找到”模型如果需要细节可以回源查找而不是靠压缩后的摘要硬猜。我个人现在的习惯是每做完一个任务花三十秒浏览一下长期档案看看 commit_note 有没有记下真正值得留的东西。很多实现把精力花在“更聪明的路由”上但其实更关键的是数据质量——工作内存里每条信息的来源、时效、置信度都清晰可查路由才有得可切。Context Mode 从来不是一个单一算法它是一套关于“信息什么时候该被看见”的纪律把这个纪律执行到位编码代理的能力才会真正稳定发挥出来。