最近不少人在聊 context-mode 这个词——我一开始以为是某个编辑器的新功能后来才发现大家其实是在讨论同一种诉求怎么在项目越来越大、文件越来越多的时候让当前工作上下文一直保持在手边。我自己试了两周发现这个词背后确实有一套可以落地的做法。这篇文章就把我实际实现的一个 VS Code 扩展从头到尾拆开讲包括核心机制、关键代码、踩过的坑以及怎么把它和 AI 编程工具接在一起用。1. 大项目里代码迷路的真正原因context-mode 要解决的痛点1.1 从一次改需求说起先讲一个真实场景。我手上有个中等规模的前端项目大概三十多个源码文件模块之间互相引用得厉害。某天产品提了个需求在订单列表页加一个批量导出按钮导出前要校验当前用户有没有对应权限导出接口要用项目里已有的downloadByApi工具函数错误处理走统一的showError弹窗。听起来不复杂。但当我准备让 AI 辅助编程工具来帮忙改的时候问题来了如果不给它任何上下文它写出来的代码永远是通用版——会自己定义一个downloadByExcel函数、自己封装一个message.error、甚至凭空捏造一个导出接口。可项目里明明已经有这些基础设施了。于是我像很多人一样开始手动往对话里贴文件权限模块、请求封装、订单接口定义、页面组件…… 贴了六七个文件进去对话瞬间变得很长。AI 开始频繁忘记最早提到的权限函数给出的方案前后不一致最后我不得不频繁提醒之前说过了不要重复提出。这就是典型的上下文断裂。不是 AI 变笨了是它拿到的上下文质量太差、维护成本太高。context-mode 这个思路本质上就是要把跟当前任务有关的文件、符号、依赖关系自动整理成一个可复用的上下文包而不是靠人肉复制粘贴。1.2 什么是上下文一个生活化类比把上下文这个概念说透一点。想象你刚入职一家公司同事把你拉到一边跟你交代工作我们这个模块是三年前的老代码支付回调用PayNotifyHandler处理表结构在orders表里别直接改payment_status字段要走OrderStatusService.Change方法。这段话就是上下文。它包含三样东西相关文件PayNotifyHandler、关键函数OrderStatusService.Change、约束条件不要直接改字段。人脑在工作时会自然维护这样一份当前任务须知。但代码量一上来、人一被打断这份须知就会丢失。AI 也一样它的上下文窗口是有限的而且不会主动去翻你的项目。context-mode 的价值就是把这份当前任务须知从人脑转移到工具里让它自动记录、自动更新、随时可以导出。1.3 为什么不能全指望 AI 自己探索项目有人可能会说AI 工具不是有读取文件的能力吗让它自己去看项目不就行了理论上可以但实操中会碰到几个现实问题。第一是成本。AI 每次自己搜文件、读文件都要消耗大量 token而且它不会智能地只读关键文件常常把无关配置、测试代码一并吞进去。第二是噪声。代码库里充斥着旧代码、废弃接口、只是引用但和当前任务无关的工具函数这些东西越多AI 越容易抓不住重点。第三是窗口限制。LLM 的上下文窗口是有限的你不可能把一个完整仓库塞进去必须有取舍。退一步说就算你不是为了用 AI单纯自己排查 bug在三十个文件之间跳来跳去也容易晕。刚才还在看A组件如何调用B服务切到B服务查了某个函数实现回来又要回忆A到底在哪一行调用。这种迷路消耗的专注力其实比想象中严重。所以我把 context-mode 定位成在开发者或 AI与代码之间加一层自动维护的记忆缓存。它不负责写代码只负责回答一个关键问题——我现在应该看哪些文件、这些文件里的关键符号是什么。2. context-mode 的核心机制活跃追踪、符号指纹与摘要裁剪确定了要解决的问题接下来就是设计。我花了一个周末把原型跑通整体机制分成四块活跃文件追踪、符号指纹提取、摘要裁剪、快照管理。2.1 活跃文件追踪事件源与评分模型第一件事是搞清楚用户当前在关注哪些文件。VS Code 扩展可以很方便地监听文本编辑器事件最自然的信号有三个文件被打开onDidOpenTextDocument说明用户开始关注这个文件加一次较高的分。文件内容被编辑onDidChangeTextDocument说明用户正在这个文件上做事权重最高。文件被关闭onDidCloseTextDocument保留分数但不删记录因为用户很可能一会儿又要打开。光记录事件还不够还要算分数。我用的是一套很简单的加权模型当前得分 基础分 事件加权分 排序列 当前得分 * 时间衰减系数时间衰减系数采用指数衰减比如超过 10 分钟没有活动分数每小时衰减 15%。这样既能保证最近用过的文件排前面又不会让一个昨天打开过但今天没碰的文件一直占着靠前位置。我最初只用了简单的 LRU最近最少使用算法实测发现不够用用户可能只是快速浏览某个文件后跳走了但它依然在队列里排很前面反过来某个文件在五分钟内被频繁切换但因为每次停留时间短LRU 反而把它挤出窗口。加入评分和衰减之后效果明显好很多。2.2 符号指纹通过 LSP 让工具看懂文件有了文件列表还不够上下文里不应该放整个文件内容而应该放这个文件里有哪些关键函数、类、接口。这一步我直接借用了 Language Server Protocol 的能力在 VS Code 里通过内置命令就能拿到结构化的文档符号const symbols await vscode.commands.executeCommandvscode.DocumentSymbol[]( vscode.executeDocumentSymbolProvider, document.uri );DocumentSymbol返回的是一棵树每个节点包含name符号名、kind枚举类型例如类、方法、函数、变量、detail通常是函数签名、range在文件中的行号范围。有了这些信息我就能生成一份符号指纹比如src/services/order.ts ├─ class OrderService │ ├─ createOrder(params: CreateOrderDto): PromiseOrder │ │ lines 23-45 │ ├─ updateOrderStatus(id, status) │ │ lines 67-89 └─ function downloadByApi(url, params) lines 112-130这份指纹比整份文件小得多但信息密度足够高。无论是人看还是 AI 看都能快速知道这个文件里有什么、大概在哪个位置。2.3 摘要裁剪控制 token 预算拿到符号之后还要控制总量。上下文的黄金法则是不是越多越好而是刚好解决当前任务最好。我设了三个可配置的预算参数最多跟踪多少个文件、每个文件最多提取多少个符号、整个上下文包最多多少 token。裁剪策略是先把符号按kind分级类的优先级高于普通函数导出函数高于内部变量然后从高级别开始填充预算。如果一个文件本身分数很高用户正在频繁编辑可以给它多一点预算低活跃度的文件最多保留一个文件名加一句注释。这个设计来源于我的一次失败尝试最初我把所有符号都塞进上下文结果一个中等文件就能贡献上百个符号AI 收到之后反而分不清主次给的建议开始平均用力。裁剪之后上下文变得尖了一眼能看出主链路在哪。2.4 快照机制把当下凝固成可复用资产最后一环是快照。活跃追踪是动态的但很多时候我需要把某个时刻的上下文固定下来比如准备让 AI 改代码、准备写 code review 评论、准备在群里跟同事同步背景。快照的格式我设计成一个 JSON 对象既方便程序读取也方便直接贴给 AI{ version: 1, createdAt: 2025-01-04T14:30:00Z, taskHint: 订单列表页增加批量导出按钮复用项目内的权限校验和下载工具函数, files: [ { path: src/features/order/OrderList.tsx, score: 940, symbols: [ { name: OrderList, kind: React.Component, lines: 15-210 }, { name: handleExport, kind: Method, detail: handleExport(selectedIds: string[]), lines: 120-145 } ] }, { path: src/utils/auth.ts, score: 610, symbols: [ { name: checkPermission, kind: Function, detail: checkPermission(code: string): boolean, lines: 8-36 } ] } ] }这个 JSON 有几个好处机器可读、体积可控、包含行号让 AI 或同事能快速定位。我把它绑定成一个命令ContextMode: Copy Snapshot to Clipboard一键复制然后黏贴到任何对话里都行。3. 落地实操我写的 context-mode 扩展长什么样3.1 选型为什么是 VS Code TypeScript实现平台我选的是 VS Code原因很简单我日常主力编辑器就是它而且它的扩展 API 对文档事件、LSP 交互、工作区存储都有很完整的内置支持不需要额外起服务。语言用 TypeScript类型提示对vscode这个命名空间的 API 写起来很舒服。如果你的主力编辑器是 Neovim完全可以照着同样的思路用 Lua 实现如果更偏好 JetBrains 系IntelliJ 的 PSI 树也能拿到类似的结构化符号。核心思路是通用的平台只是载体。3.2 最小骨架与命令注册一个 VS Code 扩展的入口是package.json里的contributes和主模块的activate方法。我注册了三个命令contextMode.showPanel展示当前上下文面板contextMode.snapshot生成快照并复制到剪贴板contextMode.clear清空当前上下文记录package.json里相关配置如下{ contributes: { commands: [ { command: contextMode.showPanel, title: Context Mode: Show Context Panel }, { command: contextMode.snapshot, title: Context Mode: Copy Snapshot to Clipboard }, { command: contextMode.clear, title: Context Mode: Clear Tracking } ], configuration: { title: context-mode, properties: { contextMode.maxFiles: { type: number, default: 8 }, contextMode.maxSymbolsPerFile: { type: number, default: 20 }, contextMode.ignoredExtensions: { type: array, items: { type: string }, default: [.json, .md, .svg, .min.js, .map] } } } }, activationEvents: [ onCommand:contextMode.showPanel, onCommand:contextMode.snapshot, onStartupFinished ] }注意onStartupFinished这个激活事件我希望扩展在启动时就自动开始追踪但又不阻塞 VS Code 的启动过程用这个事件最合适。如果只写onCommand那么用户不执行命令之前追踪逻辑根本不会跑面板里永远是空的。3.3 核心模块ContextTracker整个扩展的核心是一个ContextTracker类负责监听事件和维护评分列表。我把核心逻辑简化成下面这段代码import * as vscode from vscode; interface FileRecord { uri: string; score: number; lastActive: number; symbolCache: vscode.DocumentSymbol[] | null; } export class ContextTracker { private files: FileRecord[] []; private readonly decayMs 10 * 60 * 1000; constructor(private maxFiles: number) { // 监听打开、编辑、关闭三类事件 vscode.workspace.onDidOpenTextDocument((doc) this.handleOpen(doc)); vscode.workspace.onDidChangeTextDocument((e) this.handleEdit(e)); vscode.window.onDidChangeActiveTextEditor((editor) { if (editor) this.bump(editor.document.uri.toString(), 10); }); } private handleOpen(doc: vscode.TextDocument) { if (doc.uri.scheme ! file) return; if (this.isIgnored(doc.uri)) return; this.bump(doc.uri.toString(), 50); } private handleEdit(e: vscode.TextDocumentChangeEvent) { const uri e.document.uri.toString(); this.bump(uri, 20 e.contentChanges.length * 5); // 编辑说明内容可能变化让缓存失效 const record this.files.find(f f.uri uri); if (record) record.symbolCache null; } private bump(uri: string, weight: number) { const now Date.now(); let record this.files.find(f f.uri uri); if (!record) { record { uri, score: 0, lastActive: now, symbolCache: null }; this.files.push(record); } record.score Math.min(record.score weight, 1000); record.lastActive now; this.prune(); } private prune() { const now Date.now(); // 时间衰减超过10分钟没活动每小时衰减15% const ranked this.files .map(f { const idleHours (now - f.lastActive) / 3600000; const decay Math.pow(0.85, Math.max(0, idleHours - (this.decayMs / 3600000))); return { record: f, effective: f.score * decay }; }) .sort((a, b) b.effective - a.effective); this.files ranked.slice(0, this.maxFiles).map(x x.record); } private isIgnored(uri: vscode.Uri): boolean { const config vscode.workspace.getConfiguration(contextMode); const ignored: string[] config.get(ignoredExtensions, []); return ignored.some(ext uri.fsPath.endsWith(ext)); } getTopFiles(): FileRecord[] { return this.files; } }几个设计点我解释一下。第一score上限设置为 1000避免某个文件因为连续编辑而分数无限膨胀压得其他文件永远没有出头机会。第二编辑事件里按contentChanges.length加权一次改动只动一个字符和一次改动五个区域后者明显更值得提高分数。第三prune时刻控制列表长度避免内存里堆积一堆不再关注的旧文件。3.4 符号提取与面板输出符号提取不能同步做因为 LSP 需要时间去分析。我用防抖加懒加载的机制只在某个文件首次进入窗口、或者被编辑导致缓存失效时才触发符号提取提取完成后放进symbolCache下次直接读缓存。export async function fetchSymbols(doc: vscode.TextDocument): Promisevscode.DocumentSymbol[] { try { const results await vscode.commands.executeCommandvscode.DocumentSymbol[]( vscode.executeDocumentSymbolProvider, doc.uri ); return results ?? []; } catch (e) { return []; } }面板部分我用的是 VS Code 的原生TreeView把文件按分数降序排成一棵树子节点就是符号。这样用户在编辑器里工作时侧边栏就能实时看到我当前的工作上下文长什么样。3.5 配置项与建议值扩展我留了三个核心配置实测下来这几个默认值比较均衡配置项默认值说明与建议contextMode.maxFiles8超过这个数量上下文会变得嘈杂8 比较适合中小项目contextMode.maxSymbolsPerFile20单个文件提取上限防止大文件独占预算contextMode.ignoredExtensions.json .md .svg .min.js .map这些文件很少承载逻辑上下文忽略掉能省很多 tokencontextMode.maxSnapshotTokens8000生成快照时的 token 上限AI 对话一般够用观点配置项别开太多够用就好。这个工具要解决的本来就是维护上下文太麻烦的问题如果配置反而变得复杂就本末倒置了。4. 试用两周后踩过的坑以及针对性的修复4.1 坑一配置文件和测试用例污染上下文原型的第一个版本有个明显问题我打开一个package.json、一个.env.example再打开几个测试文件它们全部进了上下文。结果生成的快照里一半内容是 JSON 配置名和测试用例的describe/it字符串真正重要的业务逻辑反而被挤到后面。排查下来发现两个原因一是文件类型过滤太宽松只排除了node_modules和二进制文件二是测试文件.test.ts、.spec.ts没有被单独处理。修复方式很直接把常见配置声明和测试文件类型加入忽略列表同时增加一个文件大小阈值——超过 300KB 的文件直接跳过。这个阈值在绝大多数场景下不会误伤业务代码因为正常源码文件很少超过这个大小。另一个细节package-lock.json这类文件往往几百 KB而且打开一次就会触发一次编辑事件因为安装依赖时内容会变如果混进上下文token 预算瞬间爆炸。加入忽略列表后这个问题彻底消失。4.2 坑二LSP 符号请求太频繁CPU 飙升在低配笔记本上跑测试时我注意到扩展有一个严重的性能问题只要切换文件就立刻发一次executeDocumentSymbolProvider请求。连续快速切换文件时LSP 服务器忙不过来CPU 占用一度跑到 50% 以上。根本原因是缺少防抖。LSP 的符号分析不是瞬时的频繁请求会阻塞语言服务端让补全、跳转这些基础功能都变卡。修复方案是两层第一层切换文件后延迟 300ms 再请求期间如果用户又切走了就作废这次请求第二层只对已经进入ContextTracker的文件发起符号请求那些只是短暂扫一眼的临时文件不会触发分析。实测下来 CPU 占用降到了 5% 以下。4.3 坑三重启 VS Code 后上下文清零每天早上一打开编辑器上下文面板是空的感觉就像失忆了一样。虽然逻辑上没问题——毕竟用户还没开始活动——但实际体验不好。解决方式是把上下文持久化到workspaceStorage。VS Code 为每个工作区提供一个独立的存储目录适合放这种本地状态数据。每次打分和裁剪之后我会把文件列表和得分写进存储下次启动时先读存储恢复再继续监听事件。这里有一个容易踩的细节持久化的记录可能包含已经删除的文件路径。恢复之后要做一次有效性校验——检查文件是否仍然存在于磁盘上不存在的直接丢弃避免上下文里出现幽灵文件。4.4 效果对比给 AI 发送裸任务与带快照的差异为了确认这个工具真的有价值我做了两次对比测试同样是给订单列表页加导出按钮这个需求。裸任务模式直接输入帮我给订单列表页增加批量导出功能。AI 给出的代码用了自己拼的请求地址、自己封装的下载函数、自己写的错误弹窗。代码能跑但和项目现有架构完全脱钩审核时会被打回。带快照模式先执行ContextMode: Copy Snapshot to Clipboard把上面那串 JSON 黏贴在对话框里再输入需求。AI 直接引用了OrderService.createOrder、checkPermission、downloadByApi给出的代码几乎不需要改就能提交。这个对比让我确信在 AI 辅助编程的场景下上下文的质量直接决定输出的质量。而 context-mode 就是那个让上下文质量稳定在线的工具。5. 进阶玩法把 context-mode 变成团队协作工具5.1 自动生成 code review 的上下文包一个人用 context-mode 解决的是个人效率问题但它完全可以放大到团队场景。最常见的一个玩法是配合 Git 使用。在提 MR 之前先拉出本次变更的所有文件用 context-mode 为每个变更文件生成符号摘要拼成一个变更上下文包。然后把它贴在 MR 描述里或者直接喂给 code review 的 AI 工具让审查者不用来回翻代码就清楚这次改动了哪些关键函数。这个玩法的野路子在于不需要为每个 MR 手动写背景说明符号指纹本身就是最好的背景说明。而且它是机器生成的不会因为写 MR 的人偷懒而缺失。5.2 对接 AI CLI 或 API格式约定如果你用的是命令行 AI 工具或者直接调 APIcontext-mode 的快照可以直接作为系统提示的一部分。我总结了一个实用的拼接模板以下是当前代码库的上下文快照包含活跃文件和关键符号 {snapshot_json} 请基于以上上下文完成下面的任务 {user_task}快照放在前面当参考信息任务放在最后这样模型在生成代码时会更倾向于引用快照里的符号而不是自己创造新的函数名。5.3 自定义语言提取器绕过 LSP 盲区executeDocumentSymbolProvider依赖语言服务但有些场景拿不到符号比如自定义 DSL、模板字符串里的内嵌语言、或者还没装对应扩展的新语言。我在扩展里预留了一个接口允许用户提供一个节流脚本或者正则提取器手动从文本里抓取function、class、def等模式。实测下来至少能在 SQL 文件和部分配置文件里恢复基本的上下文能力。当然这是兜底方案能用 LSP 还是优先用 LSP它的层级信息远比正则丰富而且跨语言稳定。5.4 边界说明context-mode 不适合什么场景最后聊一下边界。这个工具目前比较适合业务项目、中小型代码库、以及在单个仓库内的工作场景。真正的大规模 monorepo 或者需要跨多个仓库协作的任务当前的评分模型还不够聪明——它有可能会把好几个仓库的文件混进同一个上下文造成主题漂移。另外如果你的项目中有大量商业秘密模块要注意快照里包含符号名和行号粘贴到外部 AI 服务之前先确认安全边界该做数据脱敏就做数据脱敏。就我个人而言用了 context-mode 两周之后最大的体会是它没有改变我写代码的方式但改变了我进入状态的速度。以前每次打断后重新接上思路要花几分钟去翻文件、回忆逻辑现在只需要看一眼侧边栏的上下文面板就能迅速知道自己刚才在看什么。最后再分享一个小技巧把ContextMode: Copy Snapshot to Clipboard绑定到CtrlAltC真的用起来之后你会发现自己复制粘贴的文件数量明显变少了。