★ FEATURED ARTICLE 你有没有过这种体验打开一个三天没碰的项目光标停在编辑器里脑子里只剩一个疑问——“我当时到底在改哪个文件”或者你把一段代码丢给 AI 辅助工具希望它给点针对性建议结果它输出的全是教科书级别的通用回答完全没接住你项目里的真实约束。问题多半不在代码本身而在“上下文”缺失。AI 助手也好你自己也好都缺一份结构化的项目上下文。我做了个叫context-mode的命令行小工具就是专门解决这个问题的它能把项目当前的结构、关键配置、最近改动、遗留 TODO 全部打包成一份可复用的上下文快照。这篇文章会完整拆开它的设计思路、实现原理、实际使用流程和踩过的坑适合正在用 AI 辅助写代码、或者经常在多个任务之间来回切换的开发者参考。1. 我为什么写了 context-mode三个让我崩溃的瞬间1.1 AI 助手“失忆”的根源是上下文缺失先说最直接的一个触发点。我在几个月前接手一个内部数据同步模块代码量不大但牵涉到三四个服务之间的消息队列约定。每次我问 AI 助手某个函数的调用关系它都答得头头是道但稍微深入一点就开始露馅它以为我在用某套通用框架的默认行为实际上项目里有一层自定义封装它建议我改某个配置项结果那个配置项在这个项目里根本没有被读取。我一开始以为是模型能力不够后来发现根本不是。问题在于我给它的信息太少了。我只丢了一段函数代码却没有告诉它“这个函数被哪些模块调用、消息格式在哪里定义、项目用的什么日志规范”。一个只看到孤立代码片段的 AI和你只拿到一页纸就要给整个项目做诊断本质上没区别。我需要的是把项目的“整体状态”压缩成一段稳定、准确、可复用的上下文描述每次都能直接喂给 AI。这就是 context-mode 最早的动机。1.2 切换任务之后找不回思路第二个崩溃瞬间更日常。当时我同时跟进了两个特性开发一个还在写核心逻辑另一个已经开始调测试。两个项目目录结构完全不一样技术栈也不同。每次从 A 项目切到 B 项目我至少要花十分钟重新回忆我改了哪几个文件、哪个分支、上次跑测试跑到哪一步、有没有留下没写完的代码。打开编辑器看到一堆未提交的改动不敢随便清理因为已经忘了改动之间的因果关系。我也试过自己维护笔记但笔记这东西有个致命弱点它只记录了我“当时觉得重要”的东西等我三天后再看常常想不起来当时为什么觉得这个东西重要。工具自动生成的项目状态快照就不会有这种问题——它是照相机不是印象派画作项目里实际有什么它就记录什么。1.3 团队协作时每次都要口头交代背景第三个场景是帮同事排查问题。有一次同事跑出一个诡异报错让我帮忙看。我先得问他“你用的哪个分支、最近改了哪些文件、这个报错是哪个环境出来的”。一来一回十分钟最后发现他自己也说不清楚因为改动分散在好几个提交里。那个时候我就想如果项目本身能自描述不需要我或者同事用脑子去回忆所有参与协作的人直接读同一份上下文快照效率能高多少。你可能注意到了上面三个场景都有一个共同点需要“项目上下文”的不只是 AI还有人自己。context-mode 做的东西本质上是一份“项目记忆快照”它的价值不局限于喂给 AI也不局限于我自己任何需要快速理解项目现状的人都用得上。2. context-mode 到底收集什么上下文快照的构成2.1 目录结构快照先给出项目骨架context-mode 输出的第一项是项目目录结构树。但这个结构树不是简单地把所有文件列出来而是做过减法的。默认情况下它会自动过滤掉.git、node_modules、build、dist、coverage、__pycache__这类不是源码的目录。否则一个稍微大点的前端项目光node_modules就能列出几万条记录整份快照立刻失去意义。输出形式大概是这样my-project/ ├── README.md ├── package.json ├── tsconfig.json ├── src/ │ ├── main.ts │ ├── modules/ │ │ ├── auth/ │ │ │ ├── auth.controller.ts │ │ │ └── auth.service.ts │ └── shared/ │ ├── /utils.ts │ └── constants.ts ├── scripts/ │ └── migrate.ts └── tests/ ├── auth.test.ts └── utils.test.ts这棵树的用途是让阅读者无论是人还是 AI在几十毫秒内建立起对项目的空间认知。没有这棵树你丢给 AI 一百个文件名它根本不知道谁在哪个目录下有了这棵树它至少能判断“controller 和 service 分开放说明项目用了分层模式”。2.2 关键配置文件的智能识别与抽取目录结构只是骨架真正让 AI 能给出有效建议的是项目里的关键配置文件。context-mode 会按优先级识别那些“描述项目规则”的文件并把内容截取出来放到快照开头附近。我列一下最常见的几类文件类别典型文件名为什么需要依赖元数据package.json / pyproject.toml / go.mod让 AI 知道项目用哪些依赖、脚本命令、包管理器编译/运行配置tsconfig.json / vite.config.ts / Dockerfile让 AI 知道构建方式、目标运行环境代码规范.eslintrc / .prettierrc / rustfmt.toml让 AI 生成的代码风格贴合项目项目说明README.md前 100 行项目总目标、启动方式、约定俗成的规矩环境配置模板.env.example / config/避免把真实密钥放进快照只保留字段结构配置文件的截取深度是可调的。默认情况下每个文件只取前 60 行防止出现那种几千行的大配置把所有 token 都吃掉的情况。你可以在配置里单独指定某个文件“全文读取”也可以指定某个文件“完全跳过”。2.3 git 状态与最近改动知道现在进行到哪一步目录树和配置文件回答的是“项目长什么样”git 状态回答的是“项目正处在什么状态”。context-mode 会读取当前分支名称、未提交的改动文件列表、最近 5 条提交信息以及每个改动文件的大致改动行数。这部分的设计初衷来自我自己经常遇到的情况我改了三个文件但只记得改了第一个另外两个是顺手改的。快照里明确写出branch: feature/order-export uncommitted changes: - src/order/export.ts (86 / -12) - src/order/export.test.ts (43 / -0) - src/shared/utils.ts (6 / -6) recent commits: - 5a3f2c1: adjust export header format - 8d9e0a2: add retry logic to batch job这里有个很容易被忽略的细节快照里放“改动行数”而不是“整个 diff”。因为 diff 体积太大了而且大部分时候 AI 只需要知道“你动了哪个文件的哪个区域”具体的差异内容它可以通过后续追问获取。把 diff 全部塞进快照等于把所有信息一次性倒给 AI反而稀释了重点。2.4 可配置的采集规则不搞一刀切不同项目的个性差异非常大所以 context-mode 的全部采集行为都可以通过配置文件覆盖。配置项大概分四层忽略规则、包含规则、深度限制、自定模板。忽略规则默认读取.gitignore这样项目里已经被忽略的文件不会混进快照同时你可以在配置里追加额外的 ignore 模式。包含规则是反过来的比如你有一个docs/architecture.md虽然整体不在源码扫描范围内但你想每次快照都带上那就在配置里显式包含它。深度限制控制目录树往下展开几层避免一个嵌套很深的项目直接让快照失控。自定模板则是完全放开手脚的部分后面第 6 节我会专门讲。3. 实现原理一个轻量上下文收集器是怎么工作的3.1 扫描与过滤安全地遍历目录context-mode 的实现并不复杂核心就是一个目录遍历器加一套过滤规则。我用脚本语言写了主逻辑不依赖任何第三方库这样部署成本几乎为零——任何一个有脚本运行环境的机器都能直接跑。遍历目录这件事听起来简单但有几个坑必须处理。第一个是符号链接循环有些项目会在公共目录下放一个指向项目根目录的软链如果扫描器不做规范化处理它就会顺着软链反复进入同一个目录轻则快照里出现重复内容重则直接栈溢出。我的处理方式是记录每个目录的绝对路径遇到软链时先确认它指向的绝对路径是否已经在访问集合里如果在就直接跳过。第二个是隐藏文件策略。默认情况下所有以.开头的隐藏文件和目录都会被扫描但只有和项目配置相关的才进入内容抽取环节。因为有些隐藏目录比如缓存目录体积很大却没有信息量全量读取会让快照变得又臭又长。3.2 文件分级哪些内容值得读哪些要跳过不是所有文件都值得被读进快照。context-mode 内部把文件分成四个等级等级描述默认策略核心配置文件、项目说明、接口定义全文或截取前 N 行普通源码文件、测试文件只记录文件名和扩展名不读内容参考文档、历史记录、图表资源只出现在目录树中忽略二进制、缓存、密钥、依赖目录完全不出现在快照里这套分级是我迭代了很多次之后确定的。最初我以为源码文件应该读取一部分内容比如每个文件的前 20 行结果生成出来的快照超级长而且 AI 根本用不上那种碎片化代码。反倒是“只列文件名不读内容”的策略更有效因为 AI 看到src/auth/auth.controller.ts这个名字就已经可以推断出这个模块的职责了。等它需要具体函数实现时再让它去读那个文件就行。二进制文件统一跳过避免出现乱码污染上下文。判断方式也很朴素读取文件的前 8000 字节如果发现\0字符比例超过 1%就认为是二进制文件。这个规则在绝大多数场景下都够用唯一的误判是某些压缩过的文本文件但它们的正常文本形态本身也不适合直接喂给 AI所以跳过成本很低。3.3 生成模板与 Token 控制所有采集到的信息最终要拼装成一份文本。context-mode 没有用复杂的序列化格式而是直接用带缩进的纯文本因为最终用户可能是人也可能是 AI 助手纯文本是兼容性最好的载体。你完全可以直接打开快照文件人工阅读不会有任何障碍。Token 控制是这里最关键的工程决策。我设定了一个总预算默认大概是 6000 到 8000 个 token差不多等于一篇 8000 字左右的英文技术文档。生成快照时按“目录树 → 配置文件 → git 状态 → 自定义笔记”的顺序分配预算。前面部分用掉的预算越多留给后面自定义笔记的空间就越小但配置文件的核心优先级永远高于自定义笔记。这个顺序不是随便定的。我测试过几种排列发现把目录树放最前面能让 AI 最快建立空间结构感配置文件随后用于理解项目规则git 状态第三用于理解当前进度最后放自定义笔记和 TODO。这个顺序下AI 的回答质量最稳定。3.4 增量缓存如何避免重复扫描如果每次运行 context-mode 都全量扫描一遍项目在大型代码库上可能要花几秒甚至十几秒。为了照顾使用体验我加了一层轻量缓存机制基于 git 的 HEAD 提交哈希和未提交改动列表做了一个缓存指纹。只要当前分支的 HEAD 没变未提交文件列表没变目录树和文件分级结果就可以直接复用。真正需要重新生成的只有 git 状态那些标题信息。这样在连续生成快照时速度几乎可以做到毫秒级体验和直接打开一个文件差不多。但这个缓存也踩过坑有时候你改了文件但 git 状态没变化比如改了.gitignore里已忽略的文件缓存就会复用导致快照内容不准。所以后来我加了一个--force参数和一个基于目录树哈希的兜底校验缓存指纹会额外包含项目根目录下文件数量与总大小。文件数量或总大小发生变化时自动全量重扫。4. 从初始化到输出完整操作流程4.1 初始化配置一次设置长期复用第一次在项目里使用 context-mode你只需要运行一个初始化命令context-mode init它会在项目根目录生成一个context-mode.config.yaml文件内容类似下面这样project_name: scan_depth: 4 max_context_lines: 60 max_token_budget: 7000 include_files: - docs/architecture.md - scripts/deploy.md exclude_dirs: - vendor - .cache custom_sections: - section_name: 核心业务规则 source: docs/business-rules.md max_lines: 40初始化之后你至少要做两件事第一给project_name填一个语义化的名字快照里第一行就是你填的这个名字第二根据项目实际情况调整exclude_dirs把那些你自己知道很重但不需要扫描的目录加进去。我不建议第一次直接全默认运行。花两分钟把配置改好后面每次生成的质量都会高很多。配置文件的注释我写得比较全没有配套文档也能看懂。4.2 生成一次性上下文日常使用中你只需要运行context-mode generate输出默认打印到终端但更推荐的做法是重定向到文件里context-mode generate -o context.snapshot.md生成之后你可以直接打开这个文件里面的结构大概长这样# context snapshot: order-service generated at 2025-05-18 10:22:14 branch master | 3 uncommitted changes ## directory structure order-service/ ├── README.md ├── package.json ├── src/... ├── tests/... └── ... ## key configs: package.json ... ## git state ... ## custom notes ...这里的文件格式是纯 Markdown但没有任何花哨的排版所有信息都是层级化文字。把这份快照复制进 AI 助手的对话框或者保存到会话开头它就像给 AI 做了一次“赛前热身”。4.3 把快照接入 AI 会话和断点续作我自己最常用的操作是分两步先把快照内容粘给 AI然后只问一个具体问题。比如我上午改了导出模块下午接着干我会打开保存的快照发给 AI然后说“请根据这份项目上下文告诉我 export.ts 里改动逻辑还可能影响哪些文件。”这里有个关键经验快照不是一次性消耗品。同一天内只要项目状态没有大变化一份快照可以在多个 AI 会话里反复使用。第二天再开工时重新生成一份新的就行。为了让这个过程更顺手我还给 context-mode 加了一个小功能每次生成快照时会自动在结尾附上一条提示如果你在把这个快照给 AI 使用建议附上以下提问 “请基于上面的项目上下文回答我的问题。 我接下来要关注的是______”省掉了每次打前缀的麻烦。你可能会觉得这不过是小事但高频使用时会明显感觉到顺手。5. 三个实际落地场景复盘5.1 场景 A用 AI 辅助排查线上环境报错有一次线上环境连续出现偶发超时我除了日志里的一段堆栈手头什么线索都没有。以前我会自己翻半天代码试图理清调用链再做一堆猜测。这次我先运行context-mode generate把快照和堆栈一起丢给 AI 助手。快照里包含了一个我之前写在配置里的自定义笔记记录着“本服务内部调用外部接口统一走requestWithRetry超时时间为 3 秒”。AI 结合堆栈后立刻指出报错位置虽然看起来在数据库查询但实际上很可能是requestWithRetry的补偿逻辑覆盖了外层设置的超时参数导致整体等待时间被拉长。我顺着这个方向去查果然在某个分支判断里发现超时上下文被错误重置。这个案例里真正起作用的不是 AI 有多聪明而是 context-mode 让 AI 看到了那条“关键业务规则”。没有快照的话我可不会每次都记得把这条规则主动告诉它。5.2 场景 B同时推进两个特性分支时不掉线上个月我同时在做结算单导出和登录页改版两个需求分属不同目录。坦白讲我的短期记忆完全应付不过来。后来我养成了一个习惯每次准备切换任务前先在各自分支上生成一份快照并保存为worklog-xxx.snapshot.md。切换回来时我不需要马上打开编辑器而是先打开快照文件花两分钟读一下目录树和未提交改动。这个过程就像一个极速版“工作记忆加载器”。有两次我甚至发现自己有一两个文件改了一半却完全没有印象正是靠快照里列出的未提交文件清单才想起来。这种“自己帮自己回忆”的感觉很奇特但效果非常扎实。5.3 场景 C团队交接时少说十句废话有一回我要把模块转给一位新同事维护按惯例要找个时段给他讲解架构、约定、现状。我先把 context-mode 生成的快照发过去让他提前看。等他再来找我的时候问题直接从“这个模块是干嘛的”变成了“快照里我看你们对订单号做了归一化处理这是为了兼容老数据吗”。这种变化很有价值交代背景信息的成本被削掉了很大一块人力和精力能放到真正需要交流和判断的事情上。快照不能替代详细设计文档但它能承担“项目现状”这个层面的信息传递而“项目现状”往往是最容易过时、最难口头讲清楚的部分。6. 踩坑记录与调优经验6.1 最大的坑上下文太长导致 AI 忽略关键信息我最早那个版本为了怕遗漏把所有源码文件都截取前 20 行塞进快照。结果生成出来的文件接近 4000 行光读起来都累AI 的注意力也被均匀地稀释了。真正重要的配置规则埋在几百个文件标题里它根本顾不过来。后来我做了两个调整一是源码文件默认不再进入内容抽取只保留目录树二是所有进入内容抽取环节的文件都必须在配置里显式声明要么是常见的配置文件要么是include_files里列出的文件。这样强制自己每次生成快照前都过一遍“什么值得读”。如果你发现 AI 的回答开始对项目背景“睁眼瞎”先别急着怪模型去看看是不是快照太长了。压缩到 400 行以内的快照往往比 4000 行的完整导出效果更好。6.2 排除规则误伤源码的教训有一版配置文件里我想把build目录排除掉顺手写成了exclude_dirs: [build]的语法。但我忽略了项目里还有一个src/build-utils目录它也被误伤了。快照里少了这个模块AI 在分析依赖关系时给出了一个明显不完整的建议我一度以为是代码有 bug。排查到最后发现就是子串匹配的问题。后来我把排除规则默认改成“必须匹配完整路径段”也就是只有目录名为build或者路径完整分割后某一段等于build时才排除。像build-utils这种就不会被误伤。如果你在配置里发现了奇怪的现象第一反应应该是去检查过滤规则而不是怀疑代码逻辑。6.3 二进制与编码问题的兜底策略还有一个比较隐蔽的问题有些文件扩展名看起来是源码实际内容是加密后的密文直接读取会把一堆乱码带进快照。这种情况用我前面提到的 8000 字节探测法能拦住大部分但拦不住全部。比如某些国际化资源文件是 UTF-16 编码正常读取会得到一堆\x00字节。我后来加了一条兜底规则读取文本内容后如果发现非 ASCII 字符占比超过 30%就认为它不适合进入快照只保留文件名。这个阈值听起来粗糙但在实际使用中几乎没有误伤过正常源码。6.4 自定义模板的正确姿势自定义模板是 context-mode 使用率最高的进阶功能。你可以不满足于默认的四个区块而是完全按自己的维度组织快照。比如我给自己做了一套“基于接口边界”的模板区块说明对外暴露接口从路由、消息消费者、定时任务里提取入口信息内部依赖关系用 import 规则推导模块间引用未完成改动从 git 状态和 TODO 注释里汇总风险点自查列出我手动标记过需要复核的位置这套模板的核心思路是把“项目现状”翻译成“决策所需信息”。同样一份项目如果你关注的是数据结构设计那就把重点放在实体定义文件上如果你关注的是部署那就把重点放在容器配置和 CI 脚本上。模板不是越详细越好而是要贴合你当前的工作目标。7. 一些后续规划和个人使用习惯context-mode 目前对我自己来说已经进入了稳定使用阶段但我还惦记着几个改进方向。一个是把“跨会话记忆”做得更细比如多次生成快照之后工具能自动对比出“这段时间项目发生了哪些变化”直接输出一个变化摘要。另一个是降低快照到 AI 会话的搬运成本比如在某些编辑器场景下一键把快照内容插入到当前对话窗口里。最后分享一个自己的使用习惯每天收工之前跑一次context-mode generate把快照存到项目根目录下的.ctx-history里。第二天早上开工先看昨天的快照再跑一份新快照对比差异五分钟之内就能接上前一天的状态。这个习惯帮我省掉了很多“重新摸索上下文”的时间也让我对项目的整体状态一直保持着清晰的认知。如果你经常在工作中感到“记不起来”不妨也给你的项目做一个这样的记忆快照。
阅读完成 · 觉得有帮助？
