Context Mode：AI编码代理的上下文管理范式，解决上下文漂移与Token浪费

最近在折腾 AI 编码代理的时候，我发现一个特别有意思的现象：同样的模型、同样的任务，有的人用出来像合作多年的老搭档，有的人用出来像刚入职就失忆的实习生。差别不在模型聪不聪明，而在你往上下文窗口里塞了什么、怎么塞的。Context Mode——一种针对 AI 编码代理的上下文管理范式，干的就是这件事：决定哪些信息该进窗口、哪些该留在外面、进来之后怎么保鲜、过期了怎么清理。接下来我会把这套范式的机制原理、核心设计和具体配置全部拆开讲，适合正在被代理"聊着聊着就忘事""越改越偏"折磨的开发者，也适合想从零搭建代理工作流的人。

1. AI 编码代理为什么需要 Context Mode

1.1 从一个真实翻车场景说起

我试过让代理给一个 Python 项目加新功能，项目里有三个模块互相调用。模型能力很强，单看每一步都合理，但改到第三轮时它突然开始基于一个早就废弃的接口做设计，因为那个接口还在某段历史对话里躺着，模型分不清哪个是当前事实。我再追问，它还会嘴硬，说"这是项目里现有的用法"。

这类场景多到数不清：改完一个文件导致另一个测试挂掉、让代理改 A 它顺手把 B 重构了、同一个问题隔十分钟描述两遍得到两个完全相反的答案。根因几乎都不是模型质量，而是上下文失序。真实状态没有被及时更新，过期信息没有被清走，任务焦点被无关内容稀释——上下文管理还停留在"聊天记录"层面，没有上升到"项目状态管理"层面。

1.2 四个绕不开的核心冲突

我把 AI 编码代理的上下文问题归纳为四个冲突，这也是 Context Mode 想要解决的核心矛盾。

第一个，窗口有限与信息无限的冲突。一个像样的中型项目，代码量动辄几十万行，而最常见的窗口是 128K 或 200K token，连源码都装不下。每个代理都必须回答同一个问题：这十几万 token 的预算，到底该分配给谁？

第二个，实时性与滞后性的冲突。代码库在变、git 提交在变、运行结果在变，但上下文窗口里的内容一旦写入就不会自动更新。上午让代理看的接口，下午可能已经改了三版。让代理用旧事实做新决策，错是必然的。

第三个，相关性与全局性的冲突。代理写一个工具函数时，真正需要的是几个直接关联的文件和调用链，而不是整库的细节。但只给局部，它又可能丢掉全局约束，比如"项目统一用 async 接口""禁止直接改全局状态"。上下文必须既能聚焦，又能兜底。

第四个，成本与质量的冲突。每次调用都按 token 计费，多塞 1K token，API 成本就上去一截。很多团队不是不想用代理，是账单吃不住。上下文不能无限膨胀，压缩和取舍本身就是经济决策。

1.3 Context Mode 到底是什么

Context Mode 不是某个新模型，也不是某个产品的按钮，而是一套针对编码代理的上下文管理范式：用分层、压缩、检索、预算控制四种手段，把有限的上文窗口变成一套"项目状态的实时投影"。

它的基本主张就三句话：

• 上下文不是聊天记录，是可管理的资源；
• 不是越多越好，而是"相关且新鲜"最好；
• 代理不该记住所有事情，它该知道"现在最重要的是什么、去哪找那份最重要的资料"。

接下来我会把这套范式拆成两个核心机制——滚动摘要压缩链和检索增强注入，再给出一套可以直接参考的配置模板。

2. 三级上下文分层：Context Mode 的地基

2.1 为什么必须分层

如果 Context Mode 只有一个指导思想，那就是"分层"。把不同类型的上下文混在一个池子里，是所有上下文问题的温床。系统规则、项目知识、任务目标、对话历史，它们的时效性完全不同：系统规则半年不变，项目知识随提交更新，任务焦点每次对话都在变。时效性不同的信息，必须用不同的方式管理。

这里有个很贴切的类比：你的办公桌。系统级上下文是贴在墙上的规章制度，不用频繁更换；持久化上下文是抽屉里的项目文档，按需取用、定期归档；会话级上下文是桌面上正在处理的文件，干完就得收起来。如果所有东西都堆在桌面上，干三天活你就找不到笔了。

2.2 系统级上下文：不动如山的硬约束

这一层是所有对话开始前就固定注入的，内容极少但权重极高。通常包含四类信息：

• 代理的基本行为准则，比如"修改代码前先定位所有调用方""不要擅自重构无关代码"；
• 项目层面的硬性约定，比如"新代码必须走异步 API""禁止引入全局可变状态"；
• 团队规范和安全约束，比如"不得直接操作生产配置""每个功能改动必须附带测试更新"；
• 输出格式要求，比如"每个改动必须附带影响范围说明"。

系统级上下文的每一条都要"字字值千金"。不要写废话，不要写个人风格偏好，只写那些不可违反、不随任务变化的约束。我见过有人把十几条风格建议全塞进去，结果代理每条都遵守了一半，输出四不像。规则太多等于没有规则。

实操心得：系统级上下文宁可少，不要多。我通常在写完初版后做一次"删减演练"，每条规则问自己一个问题——这条规则如果缺失，会导致代理犯哪类具体的错？答不上来的，删掉。

2.3 持久化上下文：让代理记住项目的历史

第二层解决"代理会忘记项目历史"的问题。它保存那些跨会话有效、但会随项目演化的信息：

• 项目模块结构与关键路径说明；
• 技术选型决策记录，比如何时从 requests 换到 httpx、为什么这么换；
• 已修复的典型 bug 记录，避免重复踩同一个坑；
• 当前进行中的任务状态和下一步计划；
• 团队约定俗成的命名与目录规范。

持久化上下文通常以结构化文件的形式存在，由代理在合适的时机读取或更新。这一层最关键的是"维护纪律"：任务完成后主动更新记录，而不是留给代理靠猜。如果长期不维护，这一层最终会退化成又一份聊天记录，彻底失去价值。

2.4 会话级上下文：随时流动的热数据

第三层是当前任务真正会用到的"热数据"：用户最近的指令与意图、当前正在修改的文件和相关文件片段、最近一次编译或测试的输出、本轮对话中用户给出的纠偏反馈。

会话级上下文是唯一允许"实时流动"的一层，也是动态窗口的核心。它应该做动态压缩：保留最近几轮的原始信息，更早的信息滚入摘要链。三层之间的关系可以这样看：

还有一个实践心得：三层之间要有清晰的边界。某次修改的临时细节属于会话级，不要写进持久化文件；某个团队的全局规范属于系统级，不要放在会话里反复强调。边界一模糊，代理就会把临时信息当长期规则，或者反过来，把长期规则当耳边风。

3. 机制一：滚动摘要与压缩链

3.1 为什么不能一直保留原文

会话持续越长，历史 token 越膨胀。假设一轮对话平均消耗 2K token，50 轮就是 100K，接近 128K 窗口的上限。如果不压缩，代理在第 50 轮时几乎已经没有空间去读实际要改的代码文件。更糟的是，即使窗口塞满了历史，早期"改了接口 A 并同步改 B"这类细节，对当前改 C 文件的任务帮助也很有限。

一句话：历史不能无限堆，堆久了不仅贵，而且噪声大。解决思路是滚动摘要链，让会话历史像雪球一样，越滚越紧致、越滚越结构化。

3.2 滚动摘要链的执行流程

常见的实现方式分四步：

1. 设定触发阈值。比如会话历史超过对话预算的 60% 时，启动一次压缩。
2. 把对话历史划分为"可归档段"和"保留段"。通常保留最近 10 到 15 轮的完整内容，更早的全部进入归档段。
3. 对归档段生成结构化摘要。让模型围绕"任务目标、已确认决策、已修改文件与关键变更点、待办与阻塞"四个维度压缩，篇幅控制在原内容的 10% 到 20%。
4. 下一轮对话时，代理看到的对话历史是"摘要（较老历史） + 最近 N 轮完整原始内容 + 本轮新内容"。后续再触发阈值，就把"摘要 + 最近 N 轮"整体再压缩一次。

这个链式结构的特点在于：永远保留"最近发生了什么"的完整细节，同时用摘要保留"这个任务从头到尾的逻辑主线"。

3.3 摘要不是变短，而是结构化

这里最容易被忽略的一点是——摘要不是"把对话变短"，而是"把关键信息结构化地保留"。我建议摘要模板强制包含以下字段：

• 任务目标：这次到底要做什么；
• 已确认决策：哪些方案被拍板了，用户明确说过什么；
• 已修改文件与关键变更点：防止代理重复修改或漏掉关联影响；
• 待办与阻塞：还有哪些没做，卡在什么地方；
• 用户偏好：用户不喜欢什么风格、必须避开什么。

压缩阈值怎么选？我自己的经验是：对话预算定在窗口总大小的 50% 到 60% 比较稳。128K 窗口，对话预算设在 64K 左右；256K 窗口设在 128K 左右。触发压缩的阈值设在对话预算的 70%，也就是大约 45K token。阈值太低会导致频繁压缩，浪费 token 还打断思路；太高会导致一次吞掉太多信息、摘要失真。

注意：每个摘要字段都要限制 token 上限。比如"任务目标"最多 200 token，"已修改文件"每个文件描述最多 50 token。不给上限，模型会放飞自我，把最重要的目标写成长篇大论。

3.4 压缩失真的两张兜底牌

压缩一定会损失信息，这是必然的。我习惯准备两个兜底手段凸显保险：

第一，把原始完整对话持久化到外部存储，本地的 log 文件或项目记忆目录都行，代理需要时可以按需检索回原文，而不是只看摘要。第二，在摘要中保留"引用锚点"，特别是文件名和函数名的全称。这样就算摘要里没写清楚原因，代理也知道"先去读原文件再决策"。

这两招配合下来，压缩链的信息丢失风险就可控了。记住一个原则：摘要负责"知道有这件事"，检索负责"拿到这件事的细节"。

4. 机制二：检索增强式上下文注入

4.1 从全量注入到按需捞取

很多早期 AI 代理的问题是"上下文 PUA"——把能塞的都塞进去，希望模型自己挑重点。但模型不是检索器，它更擅长在给定信息里做推理，而不是从一堆噪声里找回被你遗忘的关键文件。全量注入的结果通常是 token 爆炸加注意力稀释。

Context Mode 的做法反着来：上下文窗口里的内容保持精简，需要什么信息，通过检索管道"现捞"。这和检索增强生成在原理上一脉相承，但代码场景要做专门适配。

4.2 代码场景检索的三个阶段

第一阶段，建索引。对代码库建立两个互补的索引：符号索引和语义索引。

符号索引依赖 AST 解析，精确且便宜，覆盖类、函数、接口、变量和导入关系。语义索引则对代码注释和文件说明做向量化，用来处理"按意图找文件"这类模糊查询。比如代理听到"用户登录流程"，能通过语义索引定位到 auth.py，而不是靠猜。

第二阶段，粗召回。当代理产生信息需求时，先按关键词、符号、向量相似度粗召回 top100 候选。

第三阶段，重排与截断。用精细的得分函数对 top100 排序，挑出 top10 到 top20 真正相关的内容片段，然后才注入上下文。重排时我会特别考虑调用链邻近度——一个文件即使和关键词不完全匹配，只要它在当前修改文件的直接调用链上，相关性就比普通匹配高得多。

4.3 注入顺序和预算分配

检索到的内容不是随手往上下文里一扔。我的注入顺序是：系统级约束 → 任务目标 → 检索到的相关文件片段 → 会话历史摘要和最近原始历史 → 最新指令。检索内容放在任务目标之后，是因为代理需要先知道"要干什么"，再看"相关资料"，最后结合"最近发生了什么"来行动。

预算上，以 128K 窗口为例，我给出一个可以直接当起点的分配表：

这些数字不是拍脑袋，是反复调出来的经验值。窗口更大就同比例放大。重点在于：每一项都有预算上限，花完就没了，不存在"多塞一点没关系"这回事。

实操心得：检索片段不是越长越好。我试过把检索片段从"每文件 5K"压缩到"每文件 2K"，单任务 token 消耗下降约 35%，完成率没有变化。模型真正需要的往往是函数签名和调用点附近几十行，大段无关实现细节反而让它分心。

4.4 缓存是省钱的隐藏武器

同一项目里代理会被反复调用，每次重新注入同样的代码片段就是纯烧钱。现在主流做法是给系统级和持久化上下文做前缀缓存，只要前缀不变，缓存命中的 token 按折扣价计费。

我在实操中会把"系统级 + 持久化摘要 + 稳定的检索内容"稳定地排在消息序列最前面，命中缓存后，长上下文工具的使用成本能降一半以上。这也是 Context Mode 在成本维度上最实在的底气之一。预算再紧，缓存这一项不能省。

5. 搭建一套可落地的 Context Mode 配置

5.1 先定义你要优化哪个指标

配置 Context Mode 之前，先问自己两个问题：你的核心瓶颈是正确率、成本还是速度？你手上的项目规模大概有多少？

我会把目标分成三类：

• 目标 A：提高任务完成率，也就是改一次就对的概率；
• 目标 B：降低单次任务的 token 开销；
• 目标 C：提高长会话稳定性，任务超过 50 轮不失焦、不跑偏。

不同目标下，配置侧重点完全不同。目标 A 要多给检索注入预算，宁可多带几个相关文件；目标 B 要压低会话历史、加大压缩力度；目标 C 要强化摘要链和持久化记录，让代理在任何时候都知道任务主线在哪。

5.2 一份可复用的参考配置模板

下面是我在中等规模（约 10 万行代码）项目上用的模板。结构上类似团队规则文件，核心是体现"分层 + 预算 + 检索"三个思想：

# 项目上下文规则参考模板 ## 系统级（恒定，约 4K token） - 修改代码前必须先检索所有调用方 - 禁止引入新的全局可变状态 - 代码风格遵循项目现有 linter 配置 - 每个功能改动必须附带对应测试更新 ## 持久化（随项目更新，约 12K token） - 项目入口与模块职责导览 - ADR：技术选型决策记录 - 常见 Bug 修复记录（踩坑备忘） - 当前进行中的任务与下一步计划 ## 会话级（动态，约 64K token） - 当前任务目标：每轮固定重述 - 最近 15 轮对话原始内容 + 更早对话的滚动摘要 - 测试 / 编译输出片段

这个模板可以直接粘到项目的规则文件里，再按实际项目改。注意两个关键点：一是任务目标必须每轮重述，确保目标永远在窗口里做"置顶"；二是持久化部分要定期人工维护，别指望代理自动写得很好。

5.3 调参迭代的三个测试任务

配置好之后需要迭代验证。我一般先跑三个调试任务，各观察一轮：

• 任务 1：加一个新接口，并串联现有调用链；
• 任务 2：修复一个跨模块 bug；
• 任务 3：重构一个既有函数，保持测试全绿。

每个任务记录三个指标：完成率（是否一次到位）、修正轮数、token 消耗。

如果修正轮数多但 token 消耗不高，说明上下文太干，信息不够，要增大检索注入预算；如果 token 消耗明显偏高而完成率没提升，说明注入太杂，要加重排、收紧片段长度。这套调试方法不复杂，但胜在能明确回答"配置改完到底有没有变好"。

注意：调参一次只改一个变量。我见过有人同时调整了压缩阈值、检索片段长度和缓存策略，结果效果变差也说不清是哪一步拖的后腿。一次一动，记录清楚，这才是能积累经验的调法。

6. 踩坑实录：典型故障与排查技巧

6.1 上下文漂移

现象很容易辨认：任务进行到中后期，代理开始偏离原始需求，甚至自己发明新需求。有一次我让代理"给订单模块加一个筛选状态"，它改完筛选之后，顺手把导出功能也重写了。

排查思路是先看会话历史里"任务目标"的表述是不是被覆盖了。很多时候不是模型笨，而是目标被淹没在大量检索内容和历史里，relative 位置太靠前，被后续信息挤成了"旧闻"。解决办法是把任务目标做成 pinned 状态，每轮固定重述一次，放在最新指令附近；同时压缩摘要时强制保留目标字段。

6.2 摘要吞掉了关键信息

另一个高频坑是压缩之后，代理忘了某件事，导致重复修改或漏改关联文件。排查时我一般直接翻压缩触发时的摘要内容，大部分原因是摘要模板太自由，模型把"已修改文件"写成了"相关文件"，一字之差，行为差之千里。

解决方法是固定摘要模板的字段和每个字段的 token 上限，要求摘要内必须出现文件名和函数名的全称，不允许用"某个模块""上一个接口"这类模糊表述。兜底手段还是那句老话：完整历史持久化，代理可以按需检索原文。

6.3 检索内容与已有上下文打架

这是个很容易让人崩溃的场景：检索注入的文件版本和会话历史里之前提到的版本不一致，代理一会儿按旧版逻辑，一会儿按新版逻辑，输出明显混乱。本质上是新鲜度冲突——检索到的是磁盘上的当前版本，会话历史里的是任务早期读的版本，代理不知道信任谁。

我的解决办法是建立统一的事实基准：所有代码引用以检索结果为准，历史片段中的代码内容一律视为"可能过期"。这条规则要写进系统级约束，告诉代理——当冲突发生时，以当前检索结果为准，并主动提示"历史中的文件内容可能已被修改"。这样代理至少不会精神分裂。

6.4 低成本观测的三个技巧

最后分享几个排查小技巧，每个都便宜且有效。

第一，每次任务开始时，让代理输出一段"当前上下文摘要"，也就是让它说说自己理解了任务、手头有哪些资料、打算怎么做。这一步能提前暴露上下文缺失，成本几乎为零。

第二，把每轮调用的 token 构成，也就是系统、历史、检索各占多少，记录下来。花钱花在哪里，一眼就能看出来。我是用一个简单的脚本在每次 API 返回里解析 usage 字段，累积成一张表。

第三，在关键决策点上手动追问一句"你为什么认为 X 文件需要改"，逼代理把依据说清楚。依据里如果出现过期信息或者根本没有依据，立刻就能定位上下文哪里出了问题。这个技巧看着简单，实测下来比任何调试面板都好用。

7. 一些没说透的边界问题

7.1 小项目真的需要 Context Mode 吗

如果你的项目只有两三个文件，几千行代码，老老实实走全量注入反而最简单。Context Mode 的分层、压缩、检索都是为了解决"信息装不下"的问题，没有这个前提，引入这套机制只会增加复杂度和延迟。我遇到过有人在小项目里硬套三层结构，结果代理每次任务都要读一堆规则文件，光分析上下文就花掉一大半时间，纯属得不偿失。

7.2 模型能力越强，越需要上下文管理吗

恰恰相反，越强的模型对上下文质量越敏感。强模型不是不会受噪声干扰，而是对噪声的利用效率更高——它能把陈年旧消息和当前需求强行编成一个自洽但错误的故事。弱的模型遇到噪声更多是"答不上来"，起码会暴露问题；强模型经常是"答得很溜但是错的"，排查成本反而更高。这也是我坚持 Context Mode 的另一个原因：它不是在帮模型，而是在帮你避免被模型的自信误导。

7.3 Context Mode 和 Agent 记忆的边界

有人会把 Context Mode 和"代理记忆"混为一谈。我的理解是，Context Mode 管的是"当前运行窗口怎么组织"，代理记忆管的是"跨任务、跨会话怎么沉淀"。持久化上下文其实已经跨界了，它本质上是记忆模块和上下文窗口的接口。你在实操里可以把项目记忆文件当成"外部记忆卡"，需要时被检索进窗口，不需要时安静躺在仓库里。这个接口设计得好，代理的服务质量会有质的提升。

我自己把这些思路用进项目后，最直观的感受是：代理从"一个记性很差但愿意干活的实习生"，变成了"一个桌面永远整洁、随时知道去哪查资料的资深工程师"。它不会变得无限聪明，但至少不会在同一条沟里翻两次车。如果你也被 AI 编码代理的上下文问题折磨过，建议先从"分层 + 预算"开始，别一上来就追求复杂机制。先把系统级规则和会话级预算定死，再逐步加入检索和压缩链。上下文管理这事，说到底不是模型问题，是纪律问题。