写这篇东西的起因，是我在接手一个中型电商后台项目时，被 AI 编程工具气得差点摔键盘。代码库接近十万行，AI 助手每次生成代码都像金鱼一样只有七秒记忆，前面刚交代的模块约定，后面就写出了另一种风格。直到我把 context-mode（上下文模式）彻底弄明白，这个问题才算真正解决。这篇文章想聊的，就是什么 context-mode、在项目里怎么配置、有哪些参数决定它的表现，以及我踩过的那些坑。
这话题适合两类人：一是正被 AI 辅助编程折磨得头大、感觉 AI"记不住事"的开发者；二是已经听说过上下文管理、但搞不清 auto、semi、manual 这些模式到底怎么选的人。我会尽量讲得直白，有配置、有步骤、有参数换算，可以直接照着抄。
1. Context Mode 到底是什么：一次把上下文窗口用明白
1.1 从一次"失忆"说起：为什么需要 context-mode
先讲我踩过的那个坑。项目里有个订单模块，用户要求所有金额字段都用整数分存储，对外接口才转成两位小数。这个约定我在多个文件里都交代过，结果 AI 在生成新的优惠券计算逻辑时，直接用了浮点数，还把价格打印成了带八位小数的那种值。我一看就明白了：不是模型笨，是它根本没"看到"那些约定。大语言模型的上下文窗口是有限的，哪怕是 128K 的窗口，塞进一个十万行代码库也远远不够。模型只能基于当前对话里那几段被主动带入的内容推理，带不进上下文的信息对它来说就是"不存在"。
context-mode 解决的就是这个"带什么进去"的问题。它本质上是一套上下文管理策略：哪些文件要进入模型视野、哪些目录必须排除、每次检索召回多少个相关片段、历史对话保留多少轮，全部由你在一个配置中心里控制。通俗点说，普通模式是让 AI 蒙着眼睛在原地猜，context-mode 是给 AI 画了一张精准的地图，告诉它仓库里哪里有答案。
1.2 三种常见工作模式：auto、semi、manual 怎么选
我用过的工具有不少把 context-mode 做成三档：全自动（auto）、半自动（semi）、纯手动（manual）。不同档位解决不同阶段的痛点，没有绝对好坏，只有合不合适。
auto 模式下，工具会根据当前编辑的文件、最近打开的文件、还有对话内容，自己决定把哪些代码片段塞进上下文。优点是完全不用管，缺点是它经常猜错。我实测过，auto 模式在单文件小改动时效果还行，一旦跨模块改代码，它就倾向于带上和你最相关的文件，而忽略真正依赖的那个底层工具类。semi 模式会弹出一个上下文确认面板，先生成候选列表，我手动勾选再确认。这样不会漏关键文件，代价是每次要花十几秒审核。manual 模式则完全由用户在配置文件里写死路径和通配符，可控性最强，但项目结构变动时维护成本高。
我自己在项目中的推荐策略是：探索期和快速原型阶段用 auto，正式业务开发用 semi，遇到性能瓶颈或者明确知道问题在哪几个文件里时切到 manual。后面第 3 节我给的配置就是按 semi 加 manual 混合思路来的。
1.3 换算视角：token 窗口的现实约束
很多人在这一步会犯一个认知错误：以为上下文窗口越大，能塞的文件就越多。实际不是这么算的。token 不是字符，大致来说一个中文汉字约等于 1 到 2 个 token，一行代码平均 15 到 25 个 token。一个十万行的项目，保守估计也在 150 万到 250 万 token 级别。哪怕你有 128K 窗口，也只能覆盖不到十分之一的内容。
所以上下文模式的核心不是"塞得下"，而是"选得准"。真正的高手会把上下文配置当成一种预算管理：128K token 里，给系统提示词留 4K，给当前对话历史留 8K，给检索出来的代码片段留 64K，给结果生成留 48K，剩下的大概 4K 做缓冲。这样算下来，真正"可见"的代码量大约只有两千行到四千行。你选择的文件、检索的召回数量、相似度阈值，直接决定这两三千行里到底是精华还是垃圾。
2. 核心参数拆解：让 context-mode 按你的思路工作
2.1 关键参数一览与默认值参考
我平时用的 context-mode 配置文件大致有以下参数。请先记住：这些参数名在不同的编辑器插件里会有差异，但语义基本一致。下面这张表是我自己总结的习惯配置，单位也是常见默认值。
| 参数 | 默认值 | 作用说明 | 我的推荐 |
|---|---|---|---|
| context_window | 128000 | 模型最大上下文窗口，单位 token | 按接入模型的真实上限填 |
| max_context_files | 32 | 上下文最多扫描文件数 | 项目大就设 48，小项目 16 足够 |
| retrieval_top_k | 8 | 每次检索召回的片段数 | 4 到 10 之间调 |
| similarity_threshold | 0.6 | 片段相似度阈值，低于此值不召回 | 0.6 到 0.75 之间 |
| session_memory_max_rounds | 20 | 对话历史保留轮数 | 10 到 30 之间 |
| include_framework_files | false | 是否强制包含框架核心文件 | 需要改框架逻辑时开 |
| exclude_dirs | [] | 忽略目录列表 | 必须包含 vendor、node_modules、dist |
你可能注意到，我没有把 max_context_files 当作越大越好。文件数太多会导致模型在海量代码里"挑花眼"，注意力分散，反而降低生成质量。我实测过同一个需求，max_context_files 从 32 调到 64 之后，生成结果的可用率不升反降，原因就是冗余片段太多，把关键信息淹没掉了。
2.2 一份可直接抄的 YAML 配置
下面这份配置是我在电商项目里用的真实简化版，YAML 格式，任何支持配置文件的 context-mode 工具基本都能适配。
context_mode: mode: manual context_scope: include: - src/modules/order/** - src/modules/cart/** - src/shared/** - tests/** exclude: - src/vendor/** - src/assets/** - node_modules/** retrieval: top_k: 8 similarity_threshold: 0.65 rerank_enabled: true code_search: tool: ripgrep max_read_lines: 500 session_memory: enabled: true max_rounds: 20 optimization: compress_history: true deduplicate_snippets: true这里有一个细节容易忽略：include 里的 tests 目录。很多人写配置时不带测试文件，但 AI 生成业务代码时，如果能看到测试文件里的断言和期望值，它猜中接口行为的概率会高很多。我在配置里加入 tests 后，生成的代码一次通过测试的比例大概提升了两成。代价是检索时多了不少碎片，所以我把 similarity_threshold 调到 0.65，把不相关的单元测试稍微滤掉一层。
2.3 不同业务场景的参数调优建议
参数这个东西，不同项目类型差别很大。我先给出场景化的推荐组合，再解释背后的逻辑。
第一类：纯前端页面开发。项目结构浅、文件多、重复模板多。此时 max_context_files 可以设小一点，比如 16，重点保证 retrieval_top_k 在 6 以下。因为前端模板之间的相似度极高，召回太多会出现"上下文混轮子"，AI 把 A 页面的样式带到了 B 页面。我自己就吃过这种亏，它给我在支付页里混入了购物车页的状态管理代码，差点出事故。
第二类：后端服务开发。服务端代码对依赖关系的敏感度很高，一个实体类的字段变化会波及 Mapper、Service、Controller 三层。这类项目建议把 max_context_files 提到 48，同时把 include_framework_files 打开，让模型能看到框架自动生成的基类代码。否则它经常以为 Controller 可以直接 new Service，而不知道框架里已经有依赖注入在管。
第三类：脚本和自动化工具。这是最省心的一类，文件少、逻辑独立，auto 模式加默认参数就够用了。唯一要留意的是把临时文件目录加进 exclude，不然检索时会把一堆 .pyc 或日志文件当上下文带进去。
3. 实操记录：我把 context-mode 配置进了真实项目
3.1 项目背景与目标
用这个配置的项目是一个电商后台管理系统，技术栈是 Spring Boot 加 Vue 3，代码量接近十万行，模块包括订单、商品、库存、营销、用户账户。我接手时最头疼的是营销模块的优惠券规则重构：涉及五个核心类、两张状态机表、四种用户身份，逻辑链路非常长。用普通对话模式让 AI 帮忙重构时，它经常在第三步就偏离方向，因为中间的状态流转细节根本没有进入上下文。
这次实操的目标很明确：在不动全部代码的前提下，通过 context-mode 配置，让 AI 每次只看到这五个核心类、对应的数据库表结构文档、以及最近改过的三个测试文件。预算上下文不超过 64K token，响应质量以"生成代码可以直接进 PR"为准。
3.2 接入步骤全记录
第一步，先梳理需要的文件清单。我用命令把涉及优惠券模块的 Java 文件和表结构文档找出来，得到大概二十个文件。这时候不要急着全选，先人工过一遍，把其中一些只包含 getter/setter 的实体类标记为"低优先级"，因为它们占上下文却提供不了决策信息。
第二步，编辑配置文件。我先把 mode 设为 manual，写死 include 路径。优惠券模块主要集中在 src/modules/promotion 下面，加上 shared 里的金额计算工具类，一共六个目录。exclude 里除了常规的 node_modules 和 dist，我还额外排除了 docs/archive，因为那里有大量过期的方案文档，会产生严重误导。
第三步，测试单个文件级的问题。我先问 AI 一个具体问题："在 UserCoupon 状态机里，从已领取到已核销需要满足什么前置条件？"然后查看上下文日志，确认它读到了正确的状态机类而不是某个无关的优惠券展示组件。这一步能快速发现路径配错的问题。
第四步，验证跨文件修改。我让它把优惠券核销时的库存回补逻辑改一下，从改数据库字段变成同时更新缓存。配置正确时，AI 的修改会同时涉及三个文件：核销服务、缓存服务接口、以及对应的测试用例。如果它只动了核销服务一个文件，说明上下文里相关依赖没有完全覆盖，需要调整 include 或 top_k。
3.3 实测效果对比与 token 消耗
我把同一套需求跑了两遍：一遍用默认的 auto 模式，一遍用 manual 配置后的 context-mode。结果如下表：
| 对比项 | auto 模式 | context-mode manual |
|---|---|---|
| 上下文实际载入 token 数 | 18万（超出模型窗口被截断） | 5万左右 |
| 生成代码可用率 | 40% | 85% |
| 单次生成耗时 | 38秒 | 22秒 |
| 涉及文件正确率 | 60% | 95% |
| 一次通过测试概率 | 25% | 70% |
这个表格里的数据很有说服力：auto 并不是"没带上下文"，它带了 18 万 token 的内容，但超出窗口后后端会截断，模型真正处理的和你想让它处理的根本不是一回事。context-mode 反而是"带得少但带得准"，5 万 token 里几乎全是与任务相关的代码，效率自然上来了。
我在这个阶段还总结出一个小规律：上下文服务如果是精确匹配文件内容，token 消耗不容易失控；一旦它把整个文件内容都强制读入，而不是按需切片，消耗会成倍增长。所以配置项里有 deduplicate_snippets 和 compress_history 的话，尽量都打开。后面这个技巧我放在第 4 节细说。
4. 高发问题排查与经验避坑速查
4.1 五个高频问题与处理方案
和上下文模式打交道久了，会遇到一些非常典型的故障。我给团队整理过一份速查表，现在也分享出来。第一，最常见的是上下文错乱，症状是生成代码里混入了不属于当前模块的字段或方法。原因几乎都是 include 路径写得太宽，比如把 src/** 整个包含进去，或者当前目录的相似文件太多。解决办法是先收窄 include 范围，再把 similarity_threshold 往上调到 0.7 试一轮。
第二，检索命中率低，AI 明确说"找不到相关实现"。先别急着怀疑模型，去看上下文日志，把 top_k 调大试试，或者检查检索工具是否装了正确的代码索引插件。我用过几个不同的检索底层，ripgrep 对单文件大仓库效果好，但面对大量小文件时，基于向量检索的工具命中率更高。这种情况可以把 top_k 从 8 改到 12，配合 similarity_threshold 降到 0.55。
第三，响应超时或直接报上下文超限。这通常是你把压缩类优化项关掉了。10 万行项目的文件如果都是整文件读入，一次会话坚持不了几轮。建议打开 compress_history 和 deduplicate_snippets，让工具把历史对话压成摘要，而不是逐字保留。我在项目里设置 session_memory_max_rounds 之后再压缩，单会话能撑的时间至少延长一倍。
第四，配置文件改了但完全不生效。我发现很多工具会缓存你的配置，改完 YAML 之后要手动触发重载，或者重启会话。另外检查一下配置文件的路径是否被项目根目录的 .gitignore 忽略了，有些工具默认忽略隐藏配置，导致你改了半天它读的是上一份。
第五，AI 生成的代码依赖了上下文里没有的类。这属于"幻觉"问题。最直接的办法是在会话里补一句"不要假设任何未出现的类存在，如果依赖缺失，请告诉我你需要的类全名"，然后重新生成。配置层面，我习惯在 include 里额外放一份项目模块依赖图文档，这份文档只要两三百行，能让模型"看见"整个拓扑，幻觉率明显下降。
4.2 排查思路：从现象到根因的三步走
面对一个上下文相关的问题，我的排查方法固定三步走。
第一步，看上下文日志。大多数工具都提供"查看本次请求携带的上下文"功能，里面列出了实际进入模型的文件名和片段。这一步能立刻区分问题出在配置还是模型推演。如果日志里该有的文件都有，那就要怀疑是不是片段截取方式不对，比如只截了文件头、没截到关键逻辑位置。
第二步，缩小复现范围。把一个复杂的跨模块任务拆成三个小问题，逐个发给 AI。先问实体字段定义，再问接口行为，最后问状态流转。哪个环节的回答不准确，就把那个环节涉及的文件单独加进 include。我测试过，这个办法比盲目调参数高效得多。
第三步，对照参数临界点调整。改参数时一次只动一个变量，不要同时调 top_k 和 similarity_threshold 和 max_context_files。就像调音量一样，先调到能听清，再补高频还是低频。我见过太多同事一起改三个参数，出了问题连是哪个改坏的都不知道。
4.3 我个人总结的几条使用习惯
最后说几条零散的实操心得，都是我真正在项目里验证过的。
第一，上下文文件清单本身需要版本管理。我把 context-mode 的 YAML 文件放在代码仓库里，每次新增模块都拉着评审过一遍。因为上下文清单本质上是"项目架构的显式声明"，比文档更真实地反映了模块依赖关系。
第二，务必保留一个只有最小上下文的最简配置。debug 场景下，上下文越少越好，因为模型在大量上下文里反而容易陷入"过度拟合"，死盯着某段代码不放。我遇到过一个 bug，AI 在给了完整依赖图之后一直分析某个工具类，但真正问题出在数据库事务没提交。后来我只给它看 Repo 层的一个接口定义，它立刻指出了事务边界问题。
第三，定期用"反问测试"检查上下文是否过载。方法是随便选一个最近写过的功能，让 AI 从零描述它的实现路径。如果回答里出现了大量与当前功能无关的细节，就说明上下文塞入了太多不相关文件，该收缩范围了。我大概每两周做一次这个检查，每次都能揪出一两个多余的 include 路径。
第四，对配置的改动要有记录。我尝试过把 top_k 从 8 调到 16，当时没记录原因，结果一周后性能下降，查了半天才发现是这个改动导致召回了一堆低质量片段。从那以后，我养成了在 YAML 文件里写注释的习惯，每条参数改动都配上理由和日期。别相信自己的记忆力，这种事真的会踩第二次。
这几个习惯帮我省下了大量重复沟通成本，也让整个团队对 AI 工具的信任度上了一个台阶。现在组里的同事遇到 AI 生成质量下降，第一反应都是先看上下文配置，而不是去怨模型不行。
就聊到这里。如果你也遇到过 AI 编程工具"记不住事"的情况，希望这份配置和排查经验能帮你少走点弯路。
