我第一次意识到 context-mode 这个东西有多重要是在一次特别愚蠢的代码事故之后。当时让 AI 助手帮忙在一个接口里加一行日志结果它顺手把同文件里另一个接口的参数校验也给改了理由是想当然地补了一个工具函数。跑测试直接红了查了半天才发现助手根本看不到那个工具函数的定义于是自己脑补了一个我还没逐行 review。事后复盘问题不在模型能力而在上下文范围——它当时只开了文件模式只能看到当前这一个文件其他模块一概不知。这个 context-mode通俗说就是 AI 编程工具里当前对话能读取哪些代码内容的范围设置。搞清楚它直接决定了你用 AI 改代码是省心还是埋雷。这篇我就从原理、选型、配置到踩坑把我实际用的经验完整讲一遍。1. context-mode 是什么它解决了什么问题1.1 一个反面例子上下文盲区是怎么坑人的我先把这个反面例子展开说因为它是理解 context-mode 的最佳入口。那是一个内部管理后台项目订单导出的接口写得比较乱几百行的函数里有三四个独立的小接口。我让助手在某个导出接口入口处加一行耗时日志它开开心心给我在另一个接口的参数校验逻辑里加了一个它以为存在的工具函数调用。它不知道那个工具函数定义在 utils/validator.ts 里更不知道那个函数的真实签名是接收两个参数而不是三个。它之所以这么干是因为上下文里只有当前文件当前文件里恰好有一段注释提到了校验工具四个字它就顺着字面意思推理出了一个函数。这类事故非常典型。表面看是AI 乱改代码实际上是上下文盲区导致的模型幻觉。你让它改 A它看不到 B就只能凭空推断 B 的行为。可笑的是这种推断在大多数时候还挺合理所以很容易骗过 review直到跑起来才炸。也是从那之后我开始把 context-mode 当成一件正经事来研究什么任务开多大上下文、怎么最省 token、怎么避免让无关代码混进来捣乱。1.2 context-mode 的几种典型形态与适用边界现在市面上主流的 AI 编程助手基本都支持下面这几种上下文模式区别只是叫法不同模式典型叫法上下文会加载什么适用场景典型代价单文件模式File / Current File当前打开文件小函数修改、格式化、单文件 bug 定位看不到跨文件依赖容易幻觉目录模式Folder / Directory当前目录及其子目录可配置排除模块内的功能改动、组件和容器联动token 消耗上升噪音增多全仓库模式Repo / Workspace通过索引或检索读取整个仓库相关内容架构重构、跨模块依赖排查成本最高若全部塞入会直接超限手动指定Selection / Manual你自己选中或添加的文件精确多文件协作接口契约明确的改动需要花一点时间挑选哪些文件还有一个隐藏形态是对话历史模式——有些工具会把之前的对话也当作上下文。这个很有用但也容易带来脏数据后面专门讲。我在最开始会用默认的自动模式结果发现它经常自作聪明有时该加载整个目录它只加载了一个文件有时不该加载的一股脑全塞进去。后来总结出一个原则绝大多数任务应该用手动指定 目录模式的组合全仓库模式保留给架构级任务。2. 设计思路拆解为什么上下文范围比模型能力更影响结果2.1 从 token 窗口说起代码库是海模型的窗口只是一根吸管所有 AI 编程工具背后都有一个 token 窗口限制通俗解释就是模型一次能读进脑子里的文字数量上限。拿一个中等规模的前端项目举例node_modules 随便就几十万文件源码也有几千个文件全部代码量远超模型窗口。你想让模型看一眼整个项目物理上就做不到它只能像用一根吸管去海里吸水一样从一个狭小的孔往里吸。context-mode 本质上是决定这根吸管插在哪里、吸多大范围。吸管插错了位置再强的模型也看不到关键代码吸管口径开到最大又容易灌进来一堆无关文件把真正重要的信号稀释掉。这就是为什么上下文范围往往比模型能力更能决定结果。能力再强的模型只要关键依赖不在上下文里它就只能编。2.2 更多上下文不等于更好结果很多人有个误区觉得上下文开得越大越好全仓库总比单文件强。我实测下来恰好相反。有一个很著名的现象叫迷失在中间——模型对长文本的开头和结尾记忆更牢中间部分特别容易被忽略。你塞给它 50 个文件它真正能有效利用的可能只有开头那两三个和最后那一两个中间大部分代码只是白白占了 token 还制造噪音。我做过一个对比测试同一个 bug 定位任务单文件模式模型直接指出问题在某个函数返回值类型不匹配。全目录模式把整个模块十几个文件全塞进去模型绕了一大圈先是分析了一堆和 bug 完全无关的组件最后给了一个可能是缓存问题的模糊结论。就是因为上下文里出现了太多无关代码信号被噪音盖住了。所以 context-mode 的核心设计思想不是越大越好而是够用就好。你要在覆盖所有关键依赖和减少无关噪音之间找一个平衡点推荐结构是目标文件 直接依赖文件 接口契约文件其余的一律不放。2.3 三种加载策略全量加载、索引检索、按需增量不同工具实现 context-mode 的底层机制也不太一样理解这些机制有助于你判断工具到底把你的 token 花在哪了。第一种是全量加载。直接把指定范围的文件内容全部塞进上下文。小项目、目录模式下很常见。优点是信息完整缺点是一旦范围大了成本爆炸。第二种是索引检索。全仓库模式下大多数工具会先建一个代码索引然后根据你的问题做 embedding 或关键词召回只把相关的片段拿出来放进上下文。这种方式的优势是看起来知道整个仓库缺点是召回质量取决于索引质量和检索算法有时会漏掉关键定义。第三种是按需增量。它可以理解为对话式地逐步加文件。你问一个问题模型发现缺少某个文件再主动把那个文件加入上下文。很多工具会把这种做成自动添加上下文或点击文件引入。这是我最常用的一种它就是手动指定模式的技术底层——可控、精准、不浪费。理解这三种机制后你就知道为什么手动指定模式是最可靠的它完全绕开了检索不准的问题由你来当那个路由,直接告诉模型该看哪个文件。3. 核心细节与实操要点不同模式怎么选、怎么配3.1 文件模式单文件上下文的使用技巧单文件模式没你想的那么鸡肋它特别适合一类场景改动只涉及当前文件本身。比如给一个函数加参数校验、修一个语法错误、调整样式对象、把一段逻辑抽成局部函数。这些任务里其他文件的代码最多只是被引用只要你不指望模型改动它们的定义单文件模式就够。但用单文件模式有个前提你得在提问时把所有外部依赖的已知信息写进对话里。比如你让模型改一个函数而这个函数用到另一个模块里的 getUserRole 函数你先手动把 getUserRole 的签名粘贴到对话里告诉模型这个函数的定义是 X你只需要调用它不要修改它。这样既避免了跨文件盲目加载又堵住了幻觉的源头。这个习惯非常重要。我现在写 prompt 时会固定先给一段外部契约声明就是把相关文件里的关键函数、类型、常量先行贴进去再让模型动某个文件。看起来多花了几分钟实际上省掉了大量返工时间。3.2 文件夹/模块模式跨文件改动的正确打开方式当任务开始跨文件的时候比如你要改一个组件同时调整它的容器逻辑或者在后端模块里同时修改路由和控制器单文件模式就不够用了。这时候开目录模式让模型看到整个模块。目录模式的关键是配置排除规则。你看很多项目目录里塞了一堆 dist、build、node_modules、.git 这些东西如果不排除AI 会把编译产物和第三方依赖全读一遍。不仅浪费 token还会把一些压缩混淆后的代码当成项目源码去学习结果给你写出风格完全不对的代码。我的配置习惯如下排除 node_modules、dist、build、.next、coverage、logs 等生成目录。排除 .md 文档目录除非你明确需要模型读文档。排除测试文件除非任务和测试相关。排除锁文件lock.json、package-lock.json 这种。排除图片、字体、音频等二进制资源目录。排除规则的语法因工具而异有的是在设置里勾选有的是通过 .aiexclude / .ignore 文件控制但思路一致。如果你用的工具支持自定义忽略文件我建议你直接维护一个。3.3 全仓库模式何时用、何时不要用全仓库模式听起来最强大但它不是默认选项。我只有在两种情况下才开全仓库模式第一种是架构级重构比如你要把整个项目的鉴权方式从自定义 token 换成统一中间件影响面横跨多个目录。这种任务单靠目录模式根本装不下只能靠全仓库模式配合索引检索来定位所有涉及的文件。第二种是跨模块依赖排查比如一个接口报 500你怀疑是某一个公共工具函数在某个特殊场景下抛了异常而这个工具函数被几十个模块引用。你需要模型帮你把引用链捋出来单文件、单目录都不够。但全仓库模式有非常明显的坑响应变慢因为检索注入需要时间。token 消耗暴增成本肉眼可见地涨。检索不精准时模型容易东拉西扯。所以我给全仓库模式的定位是当一个借力工具用而不是贯穿整个任务的对话背景。你可以在全仓库模式下提出一个全局问题拿到答案清单之后立刻切回目录模式或者手动指定模式。不要让全仓库模式成为整个会话的默认背景。有一个很实用的技巧在全仓库模式下先让模型输出一份涉及文件清单再把这份清单拿去做手动指定。相当于让索引帮你做一次粗筛你再用人工做精筛。3.4 手动指定上下文最容易被忽略的精确制导这是我认为最值得安利的一种用法但很多同事都用得很少。手动指定上下文的本质是你完全掌控模型能看到什么。别把 AI 助手当搜索引擎它是你手里的工具你决定它的视野范围。实际使用中我手动指定的文件通常分为三层改动层你本次要修改的那一个或几个文件。依赖层改动层里 import 的关键模块或工具函数特别是那些你不想让模型改定义的文件。契约层接口定义、类型声明、API 文档。比如你改前端调用逻辑就必须把后端接口的响应类型文件加进来否则模型只能猜字段名。这三层文件加起来一般不会超过五个。真超过五个的时候说明任务本身应该拆成多个子任务而不是强行在一个上下文里解决。手动指定模式还有一个额外好处会话状态可复用。你手动加了一组文件改了东边之后切到西边任务再切回来文件还在上下文里不会因为切换目录而丢失记忆。4. 实操过程一个跨模块重构项目的完整案例理论讲再多不如看一个完整案例。下面这个案例来自我给一个虚构的内部管理系统做的功能改造任务是把订单导出从同步导出改成异步任务导出。涉及前端页面、后端接口、任务队列、权限校验四个模块。4.1 项目背景与任务边界这个系统原本的导出逻辑是用户点击按钮后端同步生成 Excel 然后直接返回文件流。数据量小的时候没问题但上个月数据涨到几百万行之后接口经常超时前端必须改成点击导出 - 创建任务 - 轮询任务状态 - 下载结果的异步流程。任务边界非常清晰前端把导出按钮的点击处理改成触发创建任务接口并增加轮询。后端新增创建任务接口、任务状态查询接口。中间件需要一个任务队列系统来接异步任务。权限管理员和普通用户能导出的数据范围不同任务创建时要校验。这个改动横跨前端、后端、基础组件三层直接开单文件模式做不了直接开全仓库模式又会引入一堆无关系统比如这个项目里还有库存管理、用户管理等等模块。正确做法是给每个子任务分别配置合理的上下文。4.2 第一步先盘点改动辐射圈动手写代码之前我先把所有涉及的文件列出来。不是靠印象而是让 AI 在全仓库模式下辅助生成一份清单。我当时用的提示词是我要把订单模块的导出功能从同步改为异步任务涉及订单模块、任务队列模块、权限模块。请先不要改任何代码只列出这份改动可能会影响到的所有文件按影响程度排序并说明每个文件在改动中扮演的角色。得到一份文件清单后我人工筛了一遍去掉一些无关的东西比如它把订单列表页的筛选组件也列进来了但那个组件其实不用改最终圈定十余个核心文件。这一步做完整个改动的辐射圈就清楚了。4.3 第二步按依赖方向确定上下文顺序改代码是有依赖顺序的不能一口气让模型把所有事情做完那样它的上下文会被撑爆而且改错一处后面全错。我的顺序是先改后端任务模块的数据结构任务表、状态枚举、任务创建函数。再改后端订单导出接口把同步导出改成创建任务并返回任务 ID。再改任务状态查询接口。最后改前端页面调接口、做轮询。后端任务模块是整个链路的地基所以第一步最重要。我把任务模块目录设为当前工作目录并手动加了订单模块的接口定义文件上下文大概是任务模块目录 订单模块的接口层文件。这样模型改任务模块时也能看到订单模块调用方长什么样不会设计出完全对不上的接口。改完之后我把第一步的结果整理成一段接口变更说明粘进第二步的对话里。这段说明就相当于上下文之间的接力棒。它包含新增了什么表、任务状态有哪些枚举、创建任务函数的入参出参。第二步要改订单导出接口时即使我不把任务模块的完整代码放进上下文模型的准确率也够高因为它拿着接力棒式的接口契约在改。第三步同理前端对话开始时我先贴了一段后端新提供的接口清单包含路径、请求参数、响应结构。前端模型不需要看后端实现的每一行代码它只需要知道契约长什么样。4.4 配置示例与排除规则这个任务里我给不同子任务开了不同的上下文配置。用伪代码展示一个典型的配置示例{ context_mode: folder, root_dir: server/modules/task, include: [ server/modules/task/**/*.ts, server/modules/order/order.controller.ts, server/modules/order/order.service.ts ], exclude: [ **/node_modules/**, **/dist/**, **/*.spec.ts, server/modules/task/task.scheduler.config.ts ] }这个配置的意思是上下文覆盖任务模块全部源码外加订单模块的两个核心文件但排除测试文件也排除调度配置文件——因为它和任务创建无关塞进来只会干扰模型的判断。第七步其实没有七步就是四步改前端时则把 root_dir 切到前端目录include 变成{ context_mode: manual, files: [ web/src/pages/order/export.tsx, web/src/services/order.ts, web/src/components/ExportButton/index.tsx, web/src/types/order.d.ts, server/modules/task/task.types.ts ] }注意最后一个文件我把后端任务模块的类型声明文件也放进前端上下文了这样前端模型就能照着真实类型去做类型判断不会自己脑补一个字段名。4.5 验证与回溯怎么确认上下文没遗漏改完之后最重要的一步是验证上下文到底够不够。我不会只看模型改出来的代码而是会做一轮反向验证。方法很简单每改完一个子任务问模型三个问题你这次修改涉及了哪些文件请列出完整路径。你做的每个关键改动依据的是哪个文件里的哪一段代码或哪个类型定义有没有哪个关键类型或函数是你没在上下文中看到、自己推测的第三问是最关键的模型如果说没有推测但你看到它在某个字段上加了一个奇怪的可选链基本就是在硬猜了。这时候你就把对应的文件加进上下文重新让它改。除此之外我还会用最笨的办法全局搜索改过的字段名、函数名看它们在项目里是否真的按模型假设的方式存在。这个方法枯燥但有效能抓住很多上下文盲区幻觉。5. 常见问题与排查技巧实录5.1 问题AI 答非所问明显没见过关键函数典型特征是你对 AI 说把 getUser 的返回类型改一下它却反问getUser 是什么或者给你一个完全不同的函数。这说明它根本没见过这个函数的定义上下文里没包含这个函数所在文件。排查步骤先看工具面板里当前会话加载的文件列表确认定义文件在不在里面。不在就手动加。如果你用的工具没有明确文件列表就直接问getUser 函数定义在哪个文件——模型会告诉你它基于什么回答。如果它说我不确定那就是上下文缺失。把定义文件加进来后重新提问并强调请根据我给的文件来回答不要假设。5.2 问题上下文超限报错或生成中断这个经常发生在目录模式或全仓库模式下。你开了一个很大的目录模型读文件读到一半就报超过 token 上限或者生成回复到一半就断掉。解决办法有几个方向缩小上下文范围把根目录从整个项目缩小到当前模块。精简文件用排除规则去掉测试文件、文档文件、配置文件。拆任务不要一次让模型改五个文件一次只改一个文件改完再下一个。用摘要替代全量如果有一个依赖文件特别大先让模型读一遍并输出摘要后续把摘要放在上下文里而不是每次都放全文。我这里特别推荐摘要替代全量这个技巧它能很好地平衡 token 消耗和信息完整性。比如你有一个 1000 行的配置中心文件不是每次都需要全文让模型先总结出关键配置项有哪些、分布在哪些行后续问题基于摘要回答。5.3 问题模式切换后记忆断层这个坑我踩过好多次。你在目录模式下让模型改了后端接口然后切到前端改页面回来再看后端它突然不记得之前改了什么因为你已经切换了会话背景旧的文件不在新上下文里。这类记忆断层不是模型笨是 context-mode 切换相当于换了一个世界。解决方法是做好上下文接力切模式之前让模型生成一段当前进度摘要包含已改文件、关键改动点、后续待办。切到新模式后把摘要粘贴进新会话的第一条消息。摘要要尽量精简控制在 200 字以内太长模型反而不读。我给团队成员推荐这个流程后他们反馈最明显的变化是再也不需要因为切个目录就把之前的工作来回解释一遍了。5.4 问题无关文件大量混入干扰判断目录模式最常遇到的问题之一你只想改业务代码结果模型的研究范围里混进了三个风格都不一样的老项目遗留文件最后写出来的新代码风格四不像一会儿用 camelCase 一会儿用 kebab-case。这种情况几乎都是排除规则没做好。我每次新建项目都会第一时间检查工具的忽略配置把 node_modules、dist、.git、测试目录、旧的 legacy 目录全部排除。配置一次后续所有对话都清净。如果某个无关文件特别顽固地混入上下文比如它恰好被某个 import 链引用了那就直接在对话里跟模型说忽略关于 xxx 文件的所有信息以 yyy 文件的风格为准。5.5 避坑清单速查表最后整理一份实用清单贴机房墙上也好收藏起来也好每次开工前扫一眼场景推荐的 context-mode关键要点修改单文件内部逻辑单文件模式在对话里粘贴外部依赖的接口签名模块内跨文件改动目录模式 排除规则手动把公共工具函数所在文件加入上下文架构级重构全仓库模式只用于定位先让模型输出文件清单再切手动指定前后端联调手动指定模式把接口契约/类型声明文件放进上下文任何改动手动指定 增量加载上下文范围够用就好说到底context-mode 不是什么高深的理论它就是你希望 AI 看多少代码的一个开关。我踩过很多坑之后最大的体会是与其指望工具自动判断上下文不如自己动手管住上下文。你越是把上下文边界划清楚AI 的表现就越稳定返工就越少。这篇文章里的所有方法和技巧都是我这个原则的具体实践。如果你也经常被 AI 的脑补坑到先别急着换模型回头检查一下 context-mode 设置可能收获比你想的大。