1. 当提示词装不下整个代码库Context Mode 就诞生了Context Mode翻译过来就是“上下文模式”最近一年在 AI 编码代理AI Coding Agent这个圈子里被反复提到但真正讲清楚它是什么的文章不多。如果只能用一句话概括我会说Context Mode 是一套关于“上下文管理”的设计范式它决定了一个 AI 代理在动手写代码之前如何感知项目、挑选信息、组织记忆以及在一个多长的上下文窗口里做出决策。这里先解释一下“代理”这个词。本文说的“编码代理”是指 AI Agent也就是能自主读取文件、调用命令、修改代码的智能体程序不是网络代理那一类东西。你正在用的 Cursor、Copilot、Codex、Claude Code以及你自己基于大模型 API 搭的编码工具本质上都属于这个范畴。传统补全工具和今天的编码代理有一个根本区别传统工具只看得到当前文件周围几十行而代理要完成跨文件重构、排查测试失败、理解历史改动这类任务时必须依赖对整个项目的感知。于是问题来了——上下文窗口是有限的但代码仓库是无限的。一个中型项目的代码量可能超过几十万行就算模型支持 128k、200k 的上下文窗口也不可能把整个仓库“塞”进去。这时候怎么管理上下文就成了一等一的大事。Context Mode 要解决的就是“如何在有限的上下文窗口里让代理获得最需要的项目信息”。它不是一个具体的开关而是由分层、检索、压缩、遗忘这四类机制组成的工程范式。这套范式适合两类人一类是重度使用 AI 编码工具的工程师另一类是在团队里搭 AI 编码流水线、想让代理稳定干活的技术负责人。1.1 为什么最近都在聊“上下文模式”而不是模型能力我先说一个观察。2024 年之前大家比拼的是“代码补全准不准”那时候模型的视野只有当前文件和最近编辑区域。后来模型能力上来了大家开始尝试让 AI 一次性读懂多个文件于是 Copilot Workspace、Codex、Devin 这类代理形态的产品开始集中出现。图省事的团队最初的做法非常粗暴把仓库里所有相关文件拼成一个巨大的 prompt一股脑丢给模型。当时我也这么干过把十几个文件的源码全部接龙式地粘进对话里让模型“分析整个项目”。结果模型很快就“看不过来”了不仅遗漏关键依赖关系还会把无关文件里的旧逻辑当成新逻辑来用。原因很简单大上下文窗口并不等于高质量上下文。模型在给定上下文里做出高质量决策靠的是关键信息密度而不是信息总量。窗口里塞进去一万行代码真正相关的可能只有三百行如果模型的注意力被无关代码分散反而比只看一小段代码时更笨。这就是 Context Mode 出现的技术背景与其让代理“被动接收”一整个仓库不如给它一套“主动检索和组织”上下文的机制。1.2 Context Mode 的本质把上下文管理的主动权交给代理传统补全工具像是一个只会在你手边帮你查短句的实习生而 Context Mode 更像是一个训练有素的资料员。它不会把档案室里所有的文件一次性搬到你面前而是先问你“需要什么”再去档案室按需调取。据我观察真正落地了的编码代理普遍遵循这样一套内部流程感知整体项目结构比如倚赖清单、目录树、配置文件根据当前任务检索相关代码文件、符号定义、调用链对检索结果做相关性排序挑选最可能有用的一部分把选中的内容压缩进上下文窗口和当前编辑区、历史对话形成结构化记忆随着任务推进不断淘汰过期信息、保留关键决策线索。这五步合在一起就是上下文管理的完整闭环。所以我说 Context Mode 不是一个“功能按钮”而是一套范式。你可以在某些工具里看到“Agent 模式”、“上下文选择”、“自动检索上下文”这样的开关它们只是这个范式的一种体现。理解底层逻辑之后不管用哪个工具你都能正确地配置它、诊断它而不是靠肉眼猜。2. Context Mode 的核心机制上下文如何被感知、组织与遗忘要把 Context Mode 讲透得先拆它最底层的四套机制。它们分别是分层、检索、压缩和遗忘。这四个词听起来像学术概念但我会尽量用工程实践的角度来解释。2.1 分层上下文给代理一张“地图”而不是一座“仓库”任何靠谱的上下文管理方案第一件事都不是堆信息而是分层。这里说的分层是把上下文按照信息的稳定性和使用频率分成几个等级。层级典型内容更新频率加载策略项目级上下文README、依赖清单、架构文档、全局规则低任务开始时加载之后基本不变局部级上下文当前文件、正在修改的函数、调用方/被调用方高按任务动态拉取变化最快会话级上下文用户最近指令、之前修改记录、构建错误、测试输出中随对话推进持续更新工具级上下文文件读取结果、grep 输出、终端命令返回中工具调用后产生用完可压缩这个分层思路非常像一个操作系统里的“虚拟内存”机制。代码仓库在磁盘上是完整存在的但代理的工作内存有限不能把整个地址空间全切进去只能按页加载把当前正在用的代码块放到“工作集”里。我见过不少失败的配置本质上是把项目级、局部级、会话级混在一起。比如有人在系统提示词里塞了一百条业务规范每条都和当前任务无关结果代理每走一步都要重新读过一遍上下文瞬间被挤爆。正确的做法是区分“稳定规则”和“高频变化的工作区”稳定的内容尽量精简放系统层高频变化的内容尽量走检索通道让代理按需去拿。2.2 检索与重排不是找得“多”而是找得“准”分层决定了信息的存放位置检索决定了如何把正确的信息“翻出来”。当前主流的编码代理至少会同时用两条检索路线第一条路线是基于语义向量的检索也就是通常说的 RAG 思路。仓库代码被切成若干 chunk每个 chunk 嵌入成向量任务描述也转成向量然后做向量相似度搜索。这套方案擅长处理“描述性地找代码”的场景比如“查找所有处理用户登录的代码”哪怕代码措辞和自然语言不完全一致也能召回候选结果。第二条路线是基于代码符号的索引类似编译器里的符号表。它通过 AST 分析提取出函数名、类名、变量、import 关系、调用关系然后按符号名精确查找。这对“找某个函数在哪里被调用”这种问题特别有用因为向量检索很难精确处理符号级别的引用关系。在实际代理实现里两条路线是并行使用的。检索出候选块之后还需要做一次重排rerank。用通俗的话说召回阶段要快、要广重排阶段要精、要准。召回可能找出 50 个候选代码块经过重排以后只保留最相关的 8 到 10 个再放进上下文窗口。下面这段伪代码能帮你理解代理在 Context Mode 下的检索流程它是我根据常见实现逻辑抽象出来的不是某个特定产品的内部代码task_query 修复用户余额更新时的并发问题 symbols symbol_index.lookup(update_balance, get_balance) chunks vector_search(task_query, top_k30) candidates merge(chunks, symbols) final rerank(candidates, task_query, top_k10) load_into_context(final, max_tokens_limit8000)重排阶段最关键的一点是不能只看和查询的相似度还要看代码块之间的依赖关系。比如一个函数调用了另一个函数哪怕第二个函数的文本相似度稍低也得优先放进来因为它们是逻辑上绑定的。这个过程做得好的代理修改一个函数时会自动带上它调用的子函数定义避免出现“模型改了一半却不知道另一半长什么样”的尴尬。2.3 上下文压缩与遗忘让代理学会“忘记”如果说分层和检索是上下文的“入口”那么压缩和遗忘就是上下文的“出口”。没有出口的系统一定会被垃圾信息堵死。这也是我一开始最容易忽略的部分。长任务执行到中途时代理会积累大量工具输出、历史指令、中间错误日志。如果全部保留上下文窗口很快就会被占满。好的 Context Mode 会做两类处理第一类是压缩。把已经完成讨论的局部代码块替换成精简摘要保留“做了什么”和“为什么做”的结论删掉实现细节。比如代理已经花了几轮对话搞清楚了支付回调的流程那么前面读取过的回调函数大段源码就可以被压缩成一行摘要“支付回调验签后更新订单状态失败时记录错误并返回 400”而不是继续占用几千个 token。第二类是遗忘。这听起来有点反直觉但人写代码也是一样的你不会在每个任务节点都记得三天前某次临时实验的所有细节你会主动忘掉不重要的东西只保留决策和结论。代理的“遗忘”则是通过滑动窗口、步骤截断、旧错误信息清理来实现的。比如前面第 3 步构建失败的错误堆栈到第 8 步已经不再重要就应该清出上下文避免干扰后续决策。压缩和遗忘策略设计得好坏直接决定代理在长任务里的稳定性。我见过很多代理“做到一半开始发疯”的情况仔细排查后发现不是模型能力问题而是上下文里堆了太多旧噪声模型被带偏了。3. 工程落地在真实项目中配置 Context Mode 的四个关键决策理论部分讲完接下来是每个人都关心的在自己的项目里怎么配。下面这些配置经验是我在多个项目里实测沉淀下来的不一定适用于所有工具但思路是通用的。配套的项目上下文模板、索引参数以及工具输出压缩方式都是基于常见工程实践整理的你可以直接抄去改。3.1 决策一用显式规则固化项目级上下文我用过的绝大多数编码代理都支持在仓库里放一个“规则文件”Cursor 叫 rulesClaude Code 认 CLAUDE.md很多自建 Agent 也支持自定义指令文件。无论名字是什么它的作用都一样在代理每次启动任务时把稳定的项目级上下文注入给模型。规则文件不是越长越好。我现在遵循一个原则是只写机器无法轻易通过检索获得的信息不写显而易见的代码目录结构。比如# AGENTS.md 示例按你的项目实际调整 ## 项目性质 - 这是一个前后端分离的电商后台前端 React后端 Go。 ## 常用命令 - 启动后端go run ./cmd/server - 运行测试go test ./... ## 架构约定 - 业务逻辑必须放在 internal/service/禁止直接写在 handler 里。 - 所有对外接口使用 protobuf 定义不要手写 JSON 结构体。 ## 已知坑 - 支付回调的签名算法是 MD5 salt不是官方标准改之前先看 internal/pay/sign.go。规则文件里的每一条都是我没写进代码注释但希望代理“一进项目就立刻知道”的信息。这样做的收益很明显代理在第一次读取文件、第一次做方案规划的时候就已经站在正确的架构认知上而不是靠不断试错去摸索项目规矩。这里有一个容易踩的坑规则文件写了太多个性化要求比如“每行代码后必须加注释”这类机械规则反而会拖慢代理的生成速度。真正有效的是“决策型约束”告诉代理什么能做什么不能做而不是“风格型建议”。3.2 决策二配置索引范围与噪声屏蔽几乎所有代理工具在建立项目索引时都有一个忽略清单。默认清单通常已经排除了 node_modules、.git、dist 这些目录但还不够。真实项目里最容易被忽略的“上下文杀手”其实是下面这些东西文件/目录类型为什么需要屏蔽屏蔽方式大型 lockfilepackage-lock.json 等几万行纯 JSON占满 chunk 空间加入 ignore 列表编译产物目录dist、build、.next生成物在源码变更后可能过期加入 ignore 列表大体积测试数据文件单文件几十 MB检索时必定浪费对检索和上下文加载同时排除文档翻译副本和源码重复度太高造成上下文混淆只保留原始语言版本自动生成代码pb.go、api.js修改它们没有意义还会让代理误改加入只读规则配好索引范围之后还需要调整分块参数。代码文件的分块和文本分块不一样不能简单按固定字数切。比较好的实践是a 按函数/类型/方法边界来切块b 设置 overlap重叠区域保留上下文衔接c 对超大文件启用“只加载符号签名不加载函数体”的策略。我实际用过的一组参数是chunk_size 1200 tokenoverlap 200 token单文件超过 3000 token 时优先加载调用入口和函数签名。这只是起始值不同语言不同项目会有差异但方向是对的。3.3 决策三设计工具调用的输入输出压缩编码代理与用户终端最大的不同在于它不能像人一样“瞄一眼”输出就能筛选重点。代理每读一次文件、每执行一次命令工具输出都会变成上下文。如果任由它输出 2000 行日志上下文基本就废了。我踩过最典型的一个坑是让代理直接执行grep -r deprecated_func .期望它能在项目里找到所有调用点。结果它在终端返回了 1400 行匹配结果光这一条就把上下文窗口占去了四分之一而真正相关的函数定义只有三处。从那以后我在系统提示里明确要求代理优先使用能精准限定范围的方式读取代码。比如用sed -n 120,180p读取特定行而不是cat整个文件用grep -rn --include*.go func Update限定文件类型给命令加head -n 50限制行数。下面是我在规则文件里常用的一组示例约束你调用工具时遵循以下约定 - 读取大型文件时先读取文件头 30 行了解结构再定位具体函数行号读取。 - 终端命令默认加上输出行数限制防止海量输出挤占上下文。 - 每次工具调用后用一句话总结关键结论再决定下一步动作。工具输出压缩的核心思想是代理每次读取文件或执行命令目标都应该是“获得一个可工作的结论片段”而不是“把整段原始信息原样灌进上下文”。当你发现代理经常重复读取同一个文件、重复执行同一个 grep 命令时往往就是因为上一次输出的关键信息被淹没它根本没记住结论。3.4 决策四把预算花在刀刃上令牌分配上下文窗口本质上是一笔预算。哪怕你的模型窗口是 200k也不能真的全部用满因为你还要给“当前正在编辑的代码”留出充足空间让模型在生成时手里有足够的上下文。这是我个人最强调的一点预算分配的核心是优先保证当前决策区压缩历史区。一个可以参考的分配思路如下。假设总窗口是 100k token大致分配方式用途预算说明系统提示与规则文件3-4k稳定信息尽量精简项目级上下文4-6kREADME、架构约定、最关键接口说明检索结果15-20k当前任务相关的代码块经过重排工具输出5-9k大量截断只留结论对话历史15-20k旧轮次压缩为摘要当前编辑区30-40k模型正在生成或修改的代码预留最大空间这组预算不是严格标准真正的关键点是“当前编辑区”不能省。如果模型生成 500 行重构代码时上下文里的旧信息太多、当前缓冲区太小它就会频繁丢失前面的变量名和函数签名生成结果的质量会急剧下降。在我自己的工程里遇到长任务时还会主动设置一个硬性上限当上下文使用率达到 80% 时强制开始压缩历史上下文或直接重启一个子任务而不是继续硬撑。这个“80% 红线”帮我避免了很多由于上下文溢出导致的低级错误。4. 实操中踩过的坑与排查技巧再讲几个实际项目中经常遇到的坑。这些坑都是我自己或身边团队真实碰到过的不是从文档里摘出来的。4.1 上下文污染代理突然“失忆”的头号原因“上下文污染”指的是无关、过期或误导性的信息被加载进了上下文导致代理基于错误前提做决策。最经典的表现是代理引用了已经被删除的旧函数或者把一个测试文件里的 mock 数据当成线上真实数据来推理。我印象很深的一次是项目里有一个遗留的utils/deprecated.go文件里面有一堆废弃的函数定义。代理在处理“重构订单状态判断逻辑”时通过关键词检索把deprecated.go里的旧状态枚举当成了当前规范生成了一版和现有代码风格完全对不上的修改。我当时排查了半天打开代理的推理日志才发现它确实检索到了旧文件而且因为旧文件和关键词相似度极高重排阶段还把它排在了很前面。解决问题的思路分两步。第一步是源头治理把废弃文件加入忽略列表或者干脆在规则文件里强调“utils/deprecated.go内容已废弃禁止参考”。第二步是习惯养成每次让代理开始一个任务前先让它简单描述“它认为当前项目里有哪些关键文件”你扫一眼它有没有把无关文件纳入视野这比事后审查 diff 要省事得多。另一种上下文污染来自对话历史。代理在十分钟前边写边注释时犯了一个小错后来这个错被纠正了但旧记录仍然留在历史里模型在某些情况下会“旧病复发”。对这些情况不要犹豫直接开一个新的会话把任务背景重新描述一遍效果往往比在旧会话里反复纠正更好。4.2 重复检索、无效工具调用与“假修复”上下文模式下的代理有一个常见毛病它会陷入“重复读取同一批文件却始终没得出结论”的循环。直观感受就是它在推理日志里反复执行同一条 grep 命令或者反复打开同一个文件但每次打开后的结论都模棱两可。这种问题背后通常有两个原因。第一检索重排环节没有识别出“这个文件已经在上下文里了”于是代理一遍一遍地重新加载。第二代理的计划能力偏弱它希望从文件里找到“唯一正确答案”但没有意识到有些代码问题需要调整逻辑而不是继续找线索。我在规则文件里加了一条硬约束如果某个文件已经读取过且结论已记录后续任务不得重复加载该文件除非明确需要查看不同行号。这能显著降低无效工具调用的次数。至于“假修复”我见过的套路是这样的测试报错代理读了报错信息立刻去改被报错的那一行改完测试通过但过两天另一个模块又炸了因为真正的问题是一个公共函数的边界条件被它在局部“修”成了表面正常。对付这种情况我建议在长期任务里要求代理先输出一个“问题分析 修改计划”并且明确写出哪些文件会被影响然后再开始改代码。如果它的计划里没有触及根因你会更容易在早期就发现方向不对。4.3 怎样让 Context Mode 的决策过程可感知、可调试最后也是最容易被忽略的一点上下文模式是一个黑盒系统你必须有办法观察它“读了什么、略过了什么、记住了什么”。否则出了问题只能瞎猜。大多数工具提供了某种形式的推理日志或事件流能显示代理读取了哪些文件、执行了哪些命令、调用了什么工具。我的习惯是在代理执行高风险重构任务时第一时间打开日志看它的第一步动作。重点观察三个信号它是否在读取明显不相关的文件它是否在检索阶段频繁命中测试文件、mock 文件、生成代码它在读取文件后是否有“总结关键信息、记录结论”的动作还是直接蒙头生成。这三个信号基本能暴露百分之八十的上下文管理问题。如果日志显示代理读取了 20 个文件但没有一步总结那它的上下文大概率已经是一团乱麻如果它每次读取后都有一句精准的结论那么即使任务复杂它也不太会跑偏。我还习惯在项目里肉眼建立一个“最小上下文验证”流程挑一个中等复杂度任务比如“给某个模块加一个日志接口幂等处理”用代理跑一次然后观察它在完成前总共消耗了多少 token。记录这个基线数字如果后续任务中的 token 消耗明显增长说明上下文管理被某个新加的规则或噪声干扰了可以回滚看看是哪个变量起的作用。最后再分享一个小技巧。如果你要在一个老旧代码库里使用 Context Mode建议先跑一遍“项目体检”看看索引里到底包含了哪些目录、哪些大文件、哪些废弃代码。绝大多数上下文模式翻车都不是模型不行而是“不该进来的信息进来了、该进来的信息没进来”。花十分钟把项目边界划清楚比换更强的模型更管用。从我自己尝试的结果来看一个划清楚边界的项目配上一个中等规模的上下文预算比什么参数都不调直接堆窗口要靠谱得多。