1. 项目概述：context-mode到底在解决什么问题

1.1 核心需求解析：代码上下文碎片化

做开发久了都会遇到一个场景：接手一个老项目，打开一个函数文件，想改一行逻辑，却要先翻遍七八个相关文件才能搞明白这个函数被人怎么调用、依赖了哪些配置、上游数据从哪来。代码本身并不复杂，复杂的是散落在各个文件里的"上下文"。更麻烦的是，现在很多辅助编程的工具、脚本、代码分析器，也面临同样的困境——你把它指向当前文件，它只看得到局部；你把它指向整个仓库，它又会被海量无关代码淹没。

"context-mode"这个概念，说通俗点，就是把"我需要看多少上下文"这件事，从拍脑袋变成一套可配置、可切换、可复用的策略体系。它不是一个单一功能，而是一种处理代码上下文的思路：按任务类型、按代码规模、按分析深度，把上下文拆成若干档位，用工具统一管理。我刚接触这个思路的时候，第一反应是"这不就是给AI工具换个提示词嘛"，但真正跑起来才发现，就算模型能力强，喂进去的上下文如果是脏的、乱的、过时的，输出质量照样崩。上下文不是越多越好，而是越"对"越好。

这个项目适合谁来参考？如果你日常写代码依赖辅助工具、维护中大型仓库、或者在做代码分析类的内部小工具，那 context-mode 的思路对你直接有用。如果你只是写点脚本娱乐，也可以把它的模式设计搬过来用，只是体量不用搞得那么重。

1.2 为什么需要"模式化"而不是"一刀切"

我在刚开始做这个项目时，最大的困惑是：为什么不能让工具自动判断该看多少上下文？后来实际用下来发现，所谓"自动判断"，在两个关键点上永远做不好。

第一是意图判断。同一段代码，你是想补全下一行、修复一个Bug、还是想理解整块业务逻辑，对上下文的需求完全不同。补全可能只需要当前函数的前后二十行；修Bug要看调用约定和数据流；理解业务逻辑要看整个模块的入口、出口和边界。机器很难从一行代码反推出你的意图，所以不如人来指定模式。

第二是成本控制。上下文越大，处理延迟越高，成本也越高，并且无关信息会稀释注意力。实测下来，在保持了约40万行的模拟项目仓库里，我一开始把整个仓库结构都丢给分析工具，结果等它读完目录和关键文件，一次操作要等很久，而且回答里充满了无关文件的干扰信息。反而是按模式切好上下文之后，速度快了，准确率也上来了。

所以 context-mode 的核心价值，就是把"上下文管理的复杂度"提前处理掉，把决策留给用户，把执行自动化。这就像打游戏前先设置好画质档位，而不是每帧都让引擎重新算一次。模式化可能不是最智能的，但它是当前工程实践里最稳、最可控、最好调试的方案。

2. 核心细节解析：context-mode的分类与原理

2.1 三种粒度模式：局部、关联、全景

在实际落地时，我把 context-mode 拆成三个默认档位，名字就叫局部模式、关联模式和全景模式。这三档不是随便拍的，而是对照真实开发中三类最典型的查看代码场景。

局部模式（local）对应的是"我只改手头这个文件"。它采集的范围限于当前文件内的函数定义、类结构、变量声明和导入语句，配合简单的语法范围标记。这个模式适合代码补全、格式化、局部重构。它的优势是极快、极省，几乎不用做什么跨文件分析。

关联模式（related）对应的是"我要改的东西牵扯到别的文件"。在局部模式基础上，它会额外采集当前文件直接依赖的模块：导入的模块、被调用的外部函数、读取的配置文件、以及调用当前文件的地方。这个模式适合功能开发、Bug修复和接口变更。它需要在项目里建立一份依赖索引，采集速度尚可，但准确率高很多。

全景模式（explorer）对应的是"我要搞懂这个项目或者这一大片模块"。它会扫描整个仓库的目录结构、模块入口、测试组织、构建脚本、核心出口，生成一份结构化的项目地图。这个模式适合新人接手项目、架构评审、跨模块迁移。它最慢，但也最能回答"这个项目到底是怎么搭起来"的问题。

三个模式之间用命令切换，底层共享同一个索引缓存，所以切换本身开销很小。

2.2 意图驱动的上下文策略：不同任务喂不同的料

模式定粒度的同时，我还引入了一个"意图"维度。光有粒度不行，因为同样是关联模式，修Bug和补新功能要的东西并不完全一样。我在每个模式内部又细分了几个动作类型，下面这张表是实际配置的核心逻辑：

为什么这么设计？以Bug修复为例，如果你只把出错函数丢给分析工具，它看到的只是"这个函数内部"，不知道这个函数被谁以什么参数调用、返回值被如何消费，那就很容易给出一个局部正确但整体破坏的方案。所以Bug修复必须跳到关联模式，把调用链路带上。反过来，代码补全时如果硬塞全景上下文，工具反而会被无关模块干扰，本来应该顺手的补全变得犹豫不决。

这个"模式 + 意图"的二维设计，是 context-mode 里最值得借鉴的一点。它不追求一个万能上下文，而是维护一个上下文策略矩阵，由用户根据自己的目标选定。

2.3 上下文管理的计算逻辑：token预算与相关性排序

处理上下文的另一个核心问题是：给定一个模式，具体要采多少内容？这里我做了一套很朴素但有效的计算逻辑。

先算token预算。我按不同模式给出一档推荐上限：局部模式大概控制在几千token以内，关联模式可以到一两万，全景模式再翻几倍。预算上限的作用不是精确计费，而是倒逼采集器做取舍。宁可少给，也不要给一堆弱相关的素材。

然后算相关性排序。在关联模式里，采集器会从目标文件出发，沿着依赖引用关系往外扩散，每往外跳一层，相关性就降一档。一级依赖的权重最高，二级依赖次之，超过三级基本就不采了。这个"跳层衰减"的思想，本质上和社交网络里的影响力衰减是一样的。你不需要把所有朋友的朋友的朋友都拉进讨论，只需要关心直接相关的人。

最后是去重和合并。同一个模块可能被多个文件导入，我在索引里做了引用计数，引用越多的公共模块优先级越高；而只被当前文件用到一次的私有模块，优先级反而低。一开始我搞反了，以为公共模块要往后排，后来发现公共模块往往承载着数据结构和基础约定，恰恰是最值得先看的。

为了让这套逻辑可复现，我把所有策略收敛到一个配置文件里，后面会专门讲实现。

3. 实操过程与核心环节实现：搭建自己的context-mode系统

3.1 指令集设计与工作流定义

先把实际可落地的部分摆出来。我没有把 context-mode 做成一款多复杂的重型框架，而是设计成一个CLI工具加一个配置文件，配合编辑器里的快捷键使用。下面是我最终定下来的指令集：

• ctx-mode local：切换到局部模式，采集当前文件的核心结构。
• ctx-mode related：切换到关联模式，采集当前文件及一二级依赖。
• ctx-mode explore：切换到全景模式，采集整个仓库的结构化地图。
• ctx-mode status：查看当前模式、命中文件数和最近一次快照生成时间。
• ctx-mode rebuild：重建依赖索引，一般在代码结构大改之后手动触发。
• ctx-mode dump > snapshot.md：把当前模式采集到的上下文快照导出成一个Markdown文件，方便人工审查或作为附件丢给分析工具。

工作流上，我一般是这样用的：写新功能时默认开关联模式，改了3个文件以上没把握就切全景模式看一眼依赖，做简单补全就降到局部模式。切换成本很低，按下快捷键生成新快照，再继续干活。快照生成完我会先扫一眼 size 和命中清单，确认没有采到奇怪的文件再继续操作。

提示：快照一定要支持人工审查。我之前有过一次，关联模式把整个测试目录都卷进来了，快照体积翻了三倍，步骤全部乱了。加了"预览命中清单"这一步之后，这种问题基本不会再出现。

3.2 上下文采集流程的具体实现

核心流程按顺序分为四步：构建索引、计算关联、组装快照、增量更新。我逐个说。

第一步构建索引。索引的输入是仓库内的源代码文件，输出是一份映射表，记录每个文件的导入关系、导出的函数与类、宏定义、配置项引用。解析代码我用的是语法树而不是正则，因为正则很容易挂在外来语法上，语法树至少保证结构正确。解析到依赖关系后，建立反向引用：也就是"谁引用了这个文件"，方便从任意文件反查调用方。

第二步计算关联。给定一个目标文件，从它的导入表出发，向外扩散一层拿到一级依赖集合；再对每个一级依赖做同样操作拿到二级依赖集合。每层都带上从目标文件出发的路径，方便快照里呈现"为什么这个文件会被采集进来"。这一步的性能瓶颈在二级依赖集合可能很大，所以我做了一层过滤：只保留确实包含目标符号引用链的二级依赖，排除那种仅仅同名但无关的模块。

第三步组装快照。根据当前模式，从索引里挑选内容，按"目标文件自身信息 → 一级依赖摘要 → 二级依赖引用片段 → 仓库地图"的顺序排列。局部模式只保留第一段；关联模式到第三段；全景模式四段全上。段与段之间有明确的分隔标记，标注来源文件路径和采集时间。这样无论是人读还是工具读，都知道这段信息从哪来、有多新鲜。

第四步增量更新。每次切换模式都全量重建索引是不现实的，尤其仓库大起来以后。我做的是：索引持久化到本地缓存，文件变更时只重新解析变更过的文件，并更新反向引用表。快照则在每次切换模式时打印"命中文件数"和"是否使用缓存"，如果命中率低于预期就提示手动重建。仓库历史记录里的最近改动也会被单独标记出来，因为最近改过的文件往往是当前任务的高价值上下文。

3.3 与现有工具链的集成方式

context-mode 本身不是一个孤立系统，它的价值在于能接进日常开发链路。我做了三类集成，你可以按需参考。

第一类是编辑器快捷键集成。我把模式切换和快照导出绑定到编辑器的快捷键上，比如"局部模式快速导出"和"关联模式导出"，实际使用中比敲命令快很多。编辑器里的选中内容会自动作为目标文件的一个补充片段，拼进快照末尾。

第二类是分析工具前置处理。很多辅助编程工具都支持把文件内容作为输入。我在调用前先跑一次ctx-mode dump，把快照写到临时文件，再让工具读取这个临时文件作为附加上下文。这样工具拿到的信息结构清晰、范围克制，也不会因为对话太长而丢失重点。

第三类是批处理脚本。处理一批文件的场景下，我会写一个循环脚本，逐个文件生成关联快照再做后续分析。注意控制并发数量和输出目录，因为快照文件本身就是文本，量大了一样会占空间。

我实际用下来，这三类集成里反馈最好的是第二类。工具拿到快照后直接说"这个上下文的结构比直接贴代码清楚多了"，说明结构化快照确实比一堆散碎文件更符合工具读取的偏好。

注意：快照文件不要提交进仓库，它体积大、噪声多、时效性强，只应该作为临时产物存在。别问我怎么知道要加这条注意事项。

4. 常见问题与排查技巧实录

4.1 命中率低：采到的内容总是不够

最常见的现象是，切到关联模式，结果快照里只有当前文件本身，依赖文件一个都没带上。我排查时发现，大部分是依赖写法的问题：不是标准导入语句，而是通过路径拼接、动态加载。这在很多老项目里尤其常见。

解决方案是给索引加上"动态引用扫描"。我写了一个轻量的正则兜底层，专门识别require(某个变量)、字符串拼接的导入路径、配置文件里填的模块路径等非标准写法。这一层不追求完美，能抓到七八成就算赢。兜底层的存在还能反向促进代码规范：每次动态引用被识别出来，我都会顺手检查是不是可以改成显式导入。

另外，关联深度到底设多少也要调试。一级依赖很好采，二级依赖容易爆，三级基本是噪音。我建议默认二级，如果发现某个任务确实需要三级，就单独为那个任务加白名单，把特定模块手动拉进上下文，而不是统一把阈值调高。

4.2 上下文过期：快照内容跟实际代码对不上

这个问题集中在长时间开发时。改了一个文件，但快照没刷新，导致分析工具还在用旧信息。我做了一个"变更指纹"机制：每个文件解析完都会算一个哈希值，任何一次变更都会让哈希变化。快照生成时对比所有命中文件的哈希，如果发现不一致，就会在快照顶部打印一条"N个文件已过期"的警告。

这个警告不是摆设，我实际使用时发现过期内容害人不浅。有一次改接口名之后忘了刷新快照，工具直接基于旧接口名给了一段新调用方代码，跑起来全是编译错误。从那以后，我把"检查过期"强制做进了快照生成流程，宁愿多花一点点时间，也不要让工具吃脏数据。

4.3 大仓库性能差：切换模式要等好几秒

中大型仓库里，关联模式生成快照慢是必然的，不可能做到零延迟。但我把"算"和"取"拆开了：建立索引是后台任务，切换模式时只查索引、不重扫文件。第一次重建索引确实要等，但之后每次切换都只花零点几秒。

如果切换时依然慢，大概率是索引没有真正持久化，或者缓存被频繁清空。我用了一个双缓存策略：内存缓存给高频切换用，磁盘缓存给进程重启后恢复用。磁盘缓存带版本号，仓库结构变化、工具升级都会触发缓存失效。

实测来说，保持约40万行规模的模拟仓库，局部模式快照生成在几十毫秒级别，关联模式在半秒左右，全景模式首次需要几秒，但后续都是秒回。对日常开发完全够用。

4.4 过度放大的上下文：比没有上下文更糟

这个问题最隐蔽，也最值得单独说。有时候我为了让工具"了解更多"，把模式切到最高档，结果回答质量反而下降。后来想明白了：上下文扩大的同时，信噪比也在下降。工具需要从一堆无关信息里自己捞重点，捞到就还好，捞不到就答非所问。

我在全景模式的配置里加了一个"重点文件集"字段。这个集合可以由人工指定，也可以通过统计最近改动频率自动生成。全景地图正常扫描，但重点文件集的内容会放在快照最前面，并且附上高优先级标记。这样即使全景模式信息量大，工具也会优先处理真正重要的那部分。

给其他遇到同样问题的朋友一个建议：如果你发现工具在"上下文放大"之后反而更蠢，不要急着加更多内容，先看看前部的重点是不是被淹没了。少而精永远好过多而杂。

5. 实操心得与后续扩展建议

5.1 我在实际使用中的三点体会

第一，上下文管理的收益往往不是马上被感知的。你感觉不到"没有噪声"的快乐，只会在噪声多到干扰结果时痛一次。所以不要在出了问题之后才想起开模式，不妨一开始就养成习惯：新建任务第一步，先切对应模式。

第二，配置文件一定要保持极简。我见过一些人把上下文策略写得比业务代码还复杂，最后没人维护、没人敢动。更好的做法是默认模式覆盖大多数场景，特殊场景通过快捷键和临时白名单去解决，而不是把所有情况都塞进配置里。

第三，模式切换要形成肌肉记忆。我花了大概一周时间才适应"干活前先切模式"这个动作，但适应之后效率提升非常明显，尤其是我连续维护多个项目的时候，每个项目各自的上下文地图互不干扰，省掉了大量重新理解代码的时间。

5.2 后续可以这样扩展

context-mode 这套思路再往下走，有几个值得做的方向。一是结合仓库历史数据做智能推荐，比如某次改动涉及的文件集合，自动聚成"这次任务大概需要这个范围的上下文"。二是做多项目统一配置，把个人偏好的上下文策略沉淀成共享配置，新环境直接拉取。三是在上下文快照里加入语义摘要，压缩大文件时保留关键信息，减少token消耗。

我目前已经做了"历史改动聚类"的一部分，效果不错，但还谈不上完善。至少证明了一点：上下文管理不该是每次手动拼拼凑凑的体力活，它可以被工程化、被配置化、被模式化。这大概就是 context-mode 这个项目名最想传达的东西——把上下文当作一等公民，而不是某个工具的附属品。

如果你在这个基础上做出了更智能的版本，欢迎在实践中不断打磨这套思路。上下文这件事，永远值得认真对待。