最近写代码离不开AI辅助但我发现一个特别普遍的问题AI经常“只看局部、不管全局”。你让它改一个函数签名它只盯着当前文件改得挺欢结果项目里其他地方全都编译不过。后来我才意识到真正拉开体验差距的开关往往是一个叫context-mode的东西。这个词最近在开发圈里讨论得越来越多它不是某个产品的专属功能而是一种让AI真正理解项目上下文的设计思路。这篇文章我想把自己实际折腾 context-mode 的经验、踩过的坑、以及一个可以直接跑的轻量实现方案整理出来给同样被“AI答非所问”困扰的人一点参考。context-mode 解决的核心问题是让AI在回答或生成代码时不再只看你临时丢给它的那一段文本而是能感知到所属项目、所属仓库、相关依赖和调用关系。适合的场景包括代码补全、AI代码审查、仓库问答也包括知识库检索、文档助手这类需要结合外部信息回答需求的工具。无论你是自己写脚本调API还是想在编辑器里配好插件参数理解 context-mode 的原理都有实际帮助。1. context-mode 到底解决什么问题1.1 没有上下文时AI编程助手是怎么“断片”的我先说一个特别典型的场景。你在一个Spring Boot项目里改了一个数据库字段名从userName改成displayName。然后你让AI助手帮你在当前Controller文件里同步修改它确实改了改得还挺规范。但项目里还有十几个地方引用了这个字段Mapper XML、DTO、前端接口对接文档、单元测试里的断言。AI根本不知道这些文件的存在它只能基于当前文件去猜结果就是改完一处炸了十处。这就好比一个新同事刚入职你让他去改线上代码却不给他看代码仓库、不告诉他项目结构只甩给他一个文件。他能力再强也只能瞎猜。AI模型本身的知识和能力再强缺了项目上下文表现立刻回到“新手水平”。context-mode 就是用来解决这个问题的——它把项目本身变成输入的一部分让AI有机会像一个真正读过代码库的人那样工作。1.2 context-mode 的三种常见形态我观察下来市面上叫 context-mode 或类似概念的功能大致分三类适用的场景差别挺大。第一类是编辑器里的AI对话与补全功能。Cursor、Copilot、Continue 这类工具里都有类似选项开启后AI会读取当前打开的文件、最近编辑的文件、甚至整个工作区的文件索引。它的特点是实时的、隐式的不需要你手动指定文件但代价是对文件索引的时效性要求很高。第二类是命令行工具里的上下文打包模式。像aider、claude code这类终端工具你在启动参数里指定仓库路径它会自动读取项目中的关键文件、git提交记录、依赖清单等拼成一个结构化上下文再发给模型。这类模式控制力更强适合批处理和自动化脚本。第三类是知识库问答和文档助手里面的检索增强生成RAG模式。用户提问后系统先从向量库或全文索引里召回相关内容再结合问题一起交给模型回答。它和代码场景的 context-mode 思路一致只是检索对象从源码变成了文档或者内网知识库。三种形态的对比可以看这张表形态典型工具上下文来源触发方式优点缺点编辑器中AI对话Cursor、Copilot、Continue当前文件、工作区索引自动/手动实时性强可解释性弱容易“幻觉式引用”命令行上下文打包aider、自定义脚本源码文件、git记录、依赖文件手动启动控制力强、适合自动化配置成本略高检索增强生成Dify、LangChain、自建RAG文档库/代码库的向量索引用户提问触发可复现、易扩展检索质量决定回答质量理解了这三种形态你会发现它们的底层逻辑其实是一套东西把“相关信息”找出来组织成模型能高效理解的格式塞进有限的上下文窗口里。接下来我就按这个逻辑拆开讲。2. 核心设计拆解它是怎么工作的2.1 从“文件内容”到“项目全景”的四个步骤如果你要自己实现一个轻量的 context-mode本质上就是四个步骤发现相关文件、提取关键信息、裁剪与排序、拼装Prompt。第一步发现相关文件。在代码项目里最简单的策略是扫描整个仓库排除.git、node_modules、dist、__pycache__这类不需要进入上下文的目录把剩余的文件路径全部列出来。复杂一点的策略会结合git状态只关心最近改动的文件以及它们直接依赖的文件。第二步提取关键信息。这一层决定了你给模型看的是原文还是摘要。文件小的话直接读全文最省事文件大的时候就要提取关键片段比如函数定义、类定义、导出语句、核心注释。对应到文档场景这一步就是切片——按标题切、按段落切、按固定长度切。第三步裁剪与排序。上下文窗口有限不能把所有文件都塞进去。你需要按“和当前问题相关程度”对候选片段排序只保留最靠前的若干条。排序的依据可以是关键词覆盖数、文件路径匹配度、git最近修改时间、向量相似度等。第四步拼装Prompt。把筛选出来的内容按一定的结构组织起来加上用户问题一起发给模型。这里有个细节容易被忽略给模型的上下文最好带“边界”。直接拼一堆文件内容进去模型容易混淆哪些是仓库代码、哪些是用户指令、哪些是工具输出。用清晰的分隔标签标注好回答质量会明显提升。2.2 检索与排序的常用策略在第三步的排序环节我试过从最简单到最复杂的好几种方案说下实际感受。最直接的关键词打分。把用户问题拆成若干关键词统计每个候选片段里出现关键词的次数出现越多排名越靠前再加一点路径权重比如文件名完全匹配的额外加分。这个方案不需要任何外部依赖几行代码就能实现对于单仓库、变量命名规范的项目效果就已经能用了。复杂度往上走的是目录结构加权。如果你知道当前修改的文件是src/controller/UserController.java那么和它同目录的 Controller 文件、它 import 过的 service 层文件都应该有更高的优先级。实现上就是解析 import 语句和文件路径相似度。再往上就是向量召回。对每个代码片段做 embedding用户提问时也对问题做 embedding用余弦相似度召回Top-K。这是RAG类方案的主流做法效果比关键词好很多但需要引入向量数据库或者至少在内存里做矩阵计算对工具链的要求高一些。2.3 上下文窗口与成本控制的底层逻辑很多人在一开始喜欢把“所有相关文件都塞进上下文”结果很快撞上模型的上下文窗口上限或者API账单暴涨。实际上context-mode 的设计过程就是一个预算分配过程。以常见的模型上下文窗口举例假设窗口有128K tokens看起来很大但真正留给“上下文”的空间并不多。你至少要留出系统提示约500到1500 tokens用于设定角色和行为规则用户问题本身几百到几千 tokens 不等取决于问题复杂度模型输出预留空间至少2000以上 tokens否则回答容易被截断剩下的大头才是候选代码片段。我一般建议候选代码总量控制在窗口的50%到60%以内。比如128K窗口上下文内容最多给70K左右。剩余的留给对话历史和输出余量。不然多轮对话往下走很快就把窗口挤爆。裁剪的时候有一条经验很管用如果一段上下文在拼装后没有被模型实际引用那它就是多余的。你可以通过记录每次请求的 token 数和输出质量来反推逐步把上下文缩到刚好够用的范围。3. 动手实现一个最小可用的 context-mode3.1 准备工作与目录结构我自己在给一个内部工具加 context-mode 的时候并没有一上来就上重型框架而是先用 Python 写了一个不到两百行的小工具验证思路通了再往上叠。准备阶段只需要两样东西一个代码仓库为了测试效果和一个可调用的大模型APIOpenAI、Anthropic、或者本地部署的模型都行。我用的是 OpenAI 兼容的接口格式这样换其他服务商也比较容易。目录结构很简单context_tool/ ├── main.py # 入口 ├── scanner.py # 扫描与过滤文件 ├── ranker.py # 关键词排序 ├── prompt_builder.py # 拼接上下文 └── config.py # 配置模型参数核心思路是main.py接收一个问题scanner.py扫描仓库得到候选文件列表ranker.py根据问题筛选出最相关的几个文件prompt_builder.py把文件内容组织成结构化提示最后调用模型拿到回答。每个模块都只干一件事后面想换成向量检索只需要改ranker.py。3.2 核心代码实现与参数选择我直接给出化简可跑的核心代码并解释每一步的作用。首先是扫描器跳过不需要的目录和文件类型# scanner.py import os SKIP_DIRS {.git, node_modules, dist, __pycache__, target, build} SKIP_EXTS {.png, .jpg, .ico, .lock, .woff, .ttf, .pdf} def scan(path: str, max_depth: int 4): results [] for root, dirs, files in os.walk(path): dirs[:] [d for d in dirs if d not in SKIP_DIRS] depth root[len(path):].count(os.sep) if depth max_depth: dirs[:] [] for f in files: ext os.path.splitext(f)[1] if ext in SKIP_EXTS: continue full os.path.join(root, f) results.append(full) return results这里的max_depth参数很关键。大型仓库扫描全部文件会非常慢而且会引入大量不相关内容。我一般控制在3到4层对绝大多数业务项目已经够用。然后是排序器我用了关键词命中次数加上路径权重的方式# ranker.py import re def words(text: str): return set(re.findall(r[a-zA-Z_][a-zA-Z0-9_]{2,}, text.lower())) def rank_files(files, question: str, top_k: int 8): q_words words(question) scored [] for idx, f in enumerate(files): base os.path.basename(f).lower() score 0 for w in q_words: if w in base: score 5 # 文件名命中权重最高 # 在文件路径里匹配 for w in q_words: if w in f.lower(): score 2 # 在文件开头内容里匹配只读前2000字符 try: with open(f, r, errorsignore) as fh: head fh.read(2000).lower() for w in q_words: if w in head: score 1 except Exception: pass scored.append((score, f)) scored.sort(reverseTrue, keylambda x: x[0]) return [f for _, f in scored[:top_k] if _ 0]这个排序器的设计思路是文件名命中比路径命中值钱路径命中比内容命中值钱内容命中当保底。因为文件名是作者对模块职责的最直接概括而且不会因为换行格式影响匹配。top_k设置成8是一个性价比比较高的值文件太少可能漏掉关键信息太多则浪费token。接下来是Prompt拼装# prompt_builder.py def build_prompt(file_paths, question: str): sections [] for i, fp in enumerate(file_paths): with open(fp, r, errorsignore) as f: content f.read() # 超长文件只保留前后各2000字符 if len(content) 4000: content content[:2000] \n... [truncated] ...\n content[-2000:] sections.append(fdocument index\{i}\ path\{fp}\\n{content}\n/document) ctx \n\n.join(sections) return f你有以下仓库文件作为上下文。请根据这些上下文回答问题。 {ctx} 问题{question} 回答这里有个值得多说一句的设计超长文件截断时保留开头和结尾而不是只保留开头。因为代码文件开头通常是import和配置结尾往往是主函数或核心逻辑两者都很有价值。中间部分如果被截断通常损失可控。这个细节是实测后发现的只留开头的话模型经常找不到关键函数。主入口调用API# main.py import scanner, ranker, prompt_builder from openai import OpenAI client OpenAI(base_urlhttps://your-api-endpoint, api_keyyour-key) def main(repo_path: str, question: str): files scanner.scan(repo_path) picked ranker.rank_files(files, question, top_k8) prompt prompt_builder.build_prompt(picked, question) resp client.chat.completions.create( modelyour-model-name, messages[{role: user, content: prompt}], temperature0.2, max_tokens1500 ) print(\n--- 选中的文件 ---) for p in picked: print(p) print(\n--- 回答 ---) print(resp.choices[0].message.content) if __name__ __main__: main(/path/to/repo, 这个项目的用户登录流程是怎样的)temperature设置成0.2是我在代码场景下的偏好。代码生成和代码问题回答都希望输出更确定、更贴近上下文温度太高容易出现“自由发挥”温度太低又可能输出过于呆板的套话。实测0.2是平衡点。3.3 实际运行效果与参数调整假设我现在对一个小型Flask项目提问“用户注册时需要校验哪些字段”脚本会先扫描出所有.py文件然后根据关键词user、register、field、validate计算得分排在前面的通常是app.py、models/user.py、forms/register.py、services/auth.py这类文件。Prompt里带上这些文件内容之后模型的回答不再泛泛而谈而是能准确写出username最小长度、密码必须包含数字和字母等具体规则。运行一次之后我会看两个指标选中的文件是否合理以及回答是否引用了上下文中的具体内容。如果选中的文件明显不对就检查关键词拆词逻辑比如驼峰命名是否被正确切分。如果回答正确但答案太长就把max_tokens调小。这版实现已经足够应对很多内部工具场景了。但如果你要把 context-mode 做得更专业还需要处理更多边缘情况接下来这部分是真正的干货。4. 常见问题与排查技巧实录4.1 检索不到关键文件这是我遇到最多的问题。表现形式是回答质量还不错但明显遗漏了某个关键模块。排查思路分三步走。第一步检查文件名和问题关键词的匹配方式。我早期版本用的是英文空格分词遇到user_profile这种下划线命名就会拆错导致profile匹配不到。后来改成兼容大小写和下划线的分词规则命中率明显提升。第二步检查文件是否被过滤规则排除了。有一次我调试一个前端项目发现package.json和vite.config.js都没进上下文最后发现是我的扫描器把.js文件当时给过滤了。过滤规则越少越好宁可进来再排序不要在扫描阶段就误杀。第三步考虑是不是top_k太小。如果项目本身非常庞大8个文件名额不够用可以动态调整。比如先按得分提取20个文件再统计总token数在预算范围内尽量多带。4.2 上下文窗口溢出的处理窗口溢出的报错信息五花八门但本质都一样塞进去的内容太多。我总结了三个从轻到重的解法。最轻量的是截断长文件像我上面代码里写的那样单文件超过4000字符就截断。适用于仓库里有一两个特别大的文件的情况。注意截断时保留文件头部和尾部这种方案在大多数场景下效果可接受但如果你关心中间的逻辑信息就丢了。中等级别是分层摘要。先递归地把项目按模块划分每个模块生成一段短摘要摘要之间互相引用。这样模型能在有限的token里看到更多模块的全貌。缺点是摘要本身有损细节会丢失。重量级方案是引入向量检索。把所有文件切片后做embedding问题来了只召回最相似的切片不再依赖文件名和关键词。这套方案前期准备成本高但检索精度和上下文利用率都是最好的。4.3 模型回答质量不稳定的调参思路如果你发现同样的问题有时候回答得很精准有时候又乱答先别怀疑模型大概率是上下文拼装的问题。一个关键排查点上下文顺序。我发现在Prompt里相关度最高的文件放最前面能让模型更重视这部分内容。如果你的排序逻辑没有把最相关的文件放前面模型就可能被次相关甚至不相关的内容带偏。这就像面试官上来先问你最擅长的项目你自然发挥稳定。另一个点是Prompt指令的清晰度。如果你只说“请回答以下问题”模型可能不知道要不要引用上下文。改成“请基于以下文档内容回答问题不要臆测上下文之外的信息”答案的稳定性和可追溯性会明显上升。4.4 问题排查速查表现象可能原因解决方式回答与项目无关检索排序失效检查分词规则、提高文件名权重上下文里看不到关键文件扫描过滤规则过严或top_k太小放宽过滤规则动态调整top_k请求报token超限上下文拼装量太大截断长文件控制单文件最大长度回答过于泛泛上下文相关度不够增加检索召回数量或接入向量检索多轮对话后续回答变差历史消息占用窗口清理早期对话只保留最近几轮摘要同一个问题答案不稳定温度过高或上下文顺序不佳降低temperature把最相关文件放前面5. 从“能用”到“好用”的扩展方向5.1 引入向量检索关键词排序的问题在于它对语义理解为零。你说“用户改了密码之后需要重新登录”关键词可能是reset、login但项目里的函数名可能是invalidate_session。这两个词之间没有任何字面重叠关键词排序就找不到了。向量检索可以理解语义相关性把reset password和invalidate_session拉近。实现方法也不复杂把代码文件按函数或类切块每块喂给 embedding 模型得到向量后存入向量数据库。提问时同样把问题向量化做相似度搜索。你可以先用内存版numpy手动算余弦相似度验证效果以后再把数据量大了再换向量库。5.2 与版本控制信息结合我后来给工具加了一个新维度git 信息。它会解析当前分支的最近提交把“最近改动的文件”作为强信号。因为你在开发时遇到的问题往往就出在你刚改过的代码里。把这类文件的优先级抬高命中率会提高很多。还可以用git diff拿到当前未提交的改动内容直接作为上下文的一部分。这在做代码审查和重构时特别有用AI能知道你即将改动什么。5.3 自动化触发与交互设计工具做到后面就不仅是“问一个问题看一个回答”了。可以考虑接入文件系统监听当某个文件被保存时自动更新它的索引或者在编辑器里加一个快捷键选中代码后自动带上相关文件发起AI请求。这部分交互设计决定了工具在真实工作流里能被用多少次。再好的功能如果每次用都要敲一遍完整的命令行用两次就懒得碰了。我自己的实践是把 context-mode 工具接到一个本地HTTP服务上用Flow或者Raycast这类工具配置了快捷键选中代码后直接弹出AI建议窗口。整个交互体验接近 Cursor 那种感觉但完全可控、可定制。几点个人体会折腾 context-mode 这段时间我最大的体会是上下文不是越多越好而是越准越好。AI模型本身的能力差距其实没有想象中那么大真正拉开体验差距的是你投喂给它的上下文质量。一个精心筛选过的5个文件远好过一股脑塞进去的50个文件一个标注清晰、顺序合理、带边界标签的Prompt远好过一堆文件内容堆在一起。如果你现在用的AI编程工具经常给出“看似正确、实则跑不通”的代码不妨先别急着换更强的模型。试试手动把相关文件都加进对话看看回答质量有没有变化。如果有效说明你已经理解了 context-mode 的价值。接下来要做的事情就是把这个手动过程自动化——这篇文章里的代码正好可以作为起点。