“context-mode”这个名字乍看像某个编辑器插件其实是我给自己日常 AI 辅助开发工作流写的一组小脚本。最早只是因为受够了在几个项目之间切换时AI 助手总是把上一个项目的约定和依赖信息带到下一个项目里导致代码建议经常“串味”。后来我干脆做了一个统一的上下文切换机制把每个项目的背景、技术栈、常见命令、编码规范都拆成独立的上下文档案需要时一键加载。用了一段时间之后效果比想象中好很多所以这篇博客就把这套 context-mode 的完整思路、实现代码和踩过的坑都整理出来给同样被上下文混乱困扰的朋友一个参考。这套东西适合谁如果你经常用 AI 编程助手写代码同时手上又有多个项目在维护或者你需要在不同的技术栈之间来回切换那么 context-mode 的工作方式就能帮你把每次对话的“记忆背景”梳理干净。它不依赖某个特定的 AI 工具本质上是一种管理思维加少量脚本完全可以照着自己的习惯改造。1. context-mode 的由来与设计思路1.1 痛点上下文碎片化我最初的状态是打开终端跑一个 AI 编程助手把项目里的几个关键文件路径贴给它然后开始提问。这个做法在单一项目里还算能用但一旦涉及多个项目问题就来了。比如我上午在搞一个 Go 后端服务下午切到 Vue 前端项目AI 助手如果还带着上午的上下文就会用 Go 的习惯去写 TypeScript甚至会把前端项目里根本不存在的依赖告诉你去安装。更麻烦的是有些项目的背景信息非常长比如内部组件的命名规范、数据库表结构、第三方接口的鉴权方式。每次新开会话都要重新粘贴这些内容粘贴完往往已经占用了大量上下文窗口真正用来分析代码的空间就变小了。我曾经仔细观察过几次一个带完整背景描述的会话到后期经常出现“记不清你刚才说的文件内容”的情况就是因为上下文被背景资料塞满了。context-mode 的出发点很直白把“项目背景”和“实时代码”分成两个维度管理。项目背景是相对静态的一个项目在几个月内基本不会变所以应该单独存成文件需要时自动加载实时代码是动态的应该由用户按需提供而不是让 AI 自己去翻整个仓库。这样一来每次对话都有一个清晰的“上下文层”既保留了项目记忆又不会把上下文窗口浪费在重复的背景描述上。1.2 设计目标在设计 context-mode 时我给自己定了几个硬指标切换成本要低一条命令完成上下文切换不需要打开文件去改内容。上下文档案要做成纯文本方便直接用 git 管理也能用任意编辑器查看。对 AI 助手要透明切换之后AI 助手能感知到当前处于哪个上下文而不是靠我口头告诉它。不能入侵项目本身所有上下文档案都存在项目目录之外不往仓库里塞多余文件。这几个指标很关键。切换成本低人才会愿意持续用纯文本意味着可追溯、可 diff对 AI 透明意味着 AI 的回答会自动贴合当前项目不入侵项目则避免了对团队协作造成额外负担。现在市面上的很多 AI 编程工具都推出了项目级记忆功能但大部分都绑定在特定编辑器或特定平台里。我想要的是一套通用的、可以在终端里自由组合的方案context-mode 就是为了满足这种自由度而生。2. 核心功能拆解与实现2.1 上下文档案context file上下文档案是整个机制的心脏。它本质上是一个 Markdown 文件里面记录了这个项目所有值得“记住”的信息。我没有发明任何新的格式就是用最自然的方式写AI 能直接读懂。一个典型的 context file 长这样# 项目用户中心服务 ## 技术栈 - Vite Vue 3 TypeScript - 后端接口为 REST前缀 /api/v1 - 组件库使用 Element Plus ## 项目结构 - src/api - 接口请求封装 - src/views/user - 用户相关页面 - src/components/common - 通用组件 ## 编码约定 - 所有用户列表接口返回格式为 { list, total } - 请求封装统一用 request 函数不要直接使用 axios - 路由命名使用小驼峰页面组件使用大驼峰 ## 当前任务背景 - 正在迁移旧的用户名登录逻辑到手机号登录 - 后端接口联调已完成前端需要补充错误码处理写出这样的档案之后切换到该项目的 context 时脚本会把这份内容注入到 AI 助手的系统提示词或者首条消息里。AI 会根据这些描述调整它的回答风格、命名约定和技术选型整体上就像换了一个熟悉这个项目的“专家”。有人会问上下文档案应该写多详细我的经验是只写长时间内不会变的事实不要写短期任务描述。技术栈、项目结构、接口规范这些能保持几个月而“正在修 bug”“准备上线”这类信息属于短时状态不适合放在档案里否则每次任务变化都要改档案反而增加了维护成本。如果真的需要短期记忆可以在切换时通过命令行参数临时追加。2.2 快速切换命令context-mode 的核心命令是cm我给它起了一个简短的别名用法大概是cm . # 切换到当前目录对应的上下文 cm 项目名 # 切换到指定项目 cm --list # 列出所有已保存的上下文 cm --edit 项目名 # 编辑指定项目的上下文档案切换动作做了什么事情呢简单来说它做了两步第一步读取当前终端所处的目录反向匹配出项目名第二步把对应的上下文档案内容写入一个临时的“活动上下文”文件里。这个活动上下文文件就是给 AI 助手用的入口。这么做的好处是项目上下文变得像“环境变量”一样透明。无论你在哪个目录下打开终端只要执行一次cm .当前会话就绑定了正确的项目记忆。配合 shell 的自动切换钩子甚至可以做到进入一个目录就自动切换上下文彻底不需要手动敲命令。这里有一个设计细节值得说明我故意没有把所有历史上下文全部塞给 AI而是只保留“活动上下文”一份。某个项目一个月没碰它的档案还是原来的内容但你切过去时它会成为当前唯一的上下文。这样做的好处是AI 不会被多个项目的混杂记忆干扰每次对话都只面对一个项目的背景上下文窗口也能省出更多空间给具体代码。2.3 自动注入机制有了档案和切换命令还差最后一步怎么把这些内容真正送到 AI 手里。自动注入的机制不难但位置选错了效果会差很多。对于支持自定义系统提示词的 AI 编程助手我会把活动上下文文件的内容追加到系统提示词的末尾。系统提示词是每轮对话都会保留的高优先级信息放在这里最合适AI 在回答任何问题时都会先看到这些背景。对于不支持系统提示词的助手也可以把上下文内容放在首条消息里效果接近但可能会和后续的追问产生一定干扰。我还做了一个更轻量的做法在 shell 里定义一个预置变量记录当前上下文文件路径。当需要手动贴给 AI 时只需要执行cat $CM_CONTEXT_FILE然后把输出贴入对话。这样做虽然不够自动但胜在兼容一切工具用过的都知道很多时候“能方便地复制”比“自动但偶尔出错”更重要。后来我把两种方式都保留了默认走自动注入遇到没法自动注入的工具时就走手动粘贴自由度很高。3. 实操Linux/macOS 下的完整实现3.1 目录结构与初始化我选择了完全基于 shell 脚本的实现没有引入 Python 或 Node 依赖这样在任何 Linux/macOS 终端都能直接跑。整个 context-mode 的目录结构大概是这样~/.context-mode/ ├── contexts/ # 存放所有项目的上下文档案 │ ├── user-center.md │ ├── blog-frontend.md │ └── admin-system.md ├── active_context.md # 当前活动上下文软链接指向实际档案 └── cm.sh # 主脚本简单解释一下contexts目录是用来存储所有项目档案的地方active_context.md则是一个软链接永远指向当前激活的那个档案。这样设计的话AI 助手只需要固定读取active_context.md不管用户切换了哪个项目它读到的都是最新内容不用修改 AI 工具端的配置。初始化也很简单在~/.bashrc或~/.zshrc里加几行export CM_HOME$HOME/.context-mode export CM_CONTEXT_FILE$CM_HOME/active_context.md alias cm$HOME/.context-mode/cm.sh然后执行source ~/.bashrc。第一次用的时候先创建目录结构再新建一个项目档案即可。3.2 核心脚本代码下面是我实际在用的cm.sh做了简化去掉了一些花哨的交互保留最核心的功能。#!/usr/bin/env bash # context-mode - switch project context for AI assistants CM_HOME${CM_HOME:-$HOME/.context-mode} CONTEXTS_DIR$CM_HOME/contexts ACTIVE_LINK$CM_HOME/active_context.md # 确保目录存在 mkdir -p $CONTEXTS_DIR # 从路径中提取项目名最后一级目录名 project_name() { basename $(cd $1 pwd) } # 列出所有上下文 list_contexts() { echo Available contexts: for file in $CONTEXTS_DIR/*.md; do name$(basename $file .md) if [ $(readlink $ACTIVE_LINK) $file ]; then echo * $name (active) else echo - $name fi done } # 切换到指定项目 switch_context() { local target$1 local ctx_file$CONTEXTS_DIR/$target.md if [ ! -f $ctx_file ]; then echo Context $target not found. echo Create it with: cm --edit $target return 1 fi ln -sf $ctx_file $ACTIVE_LINK echo Switched context to $target. echo Active context: $ctx_file } # 编辑或新建上下文档案 edit_context() { local target$1 local ctx_file$CONTEXTS_DIR/$target.md if [ ! -f $ctx_file ]; then echo # $target $ctx_file echo Context $target created. fi ${EDITOR:-vim} $ctx_file ln -sf $ctx_file $ACTIVE_LINK } case $1 in --list) list_contexts ;; --edit) edit_context $2 ;; ) switch_context $(project_name $PWD) ;; *) switch_context $1 ;; esac这个脚本的核心逻辑就两条ln -sf更新软链接cat $CM_CONTEXT_FILE读取活动档案。其他都只是辅助。你可能会说这也太简单了对这就是我刻意想要的。越简单的机制越不容易出错也越好维护。我来解释一下几个关键选择用软链接而不是复制文件是为了让$CM_CONTEXT_FILE始终保持对当前档案的引用。如果复制就需要在每次切换时同步两份文件多了一步就多了一个出错机会。项目名直接取当前目录的 basename所以一个项目最好都放在同一个目录下。如果你希望一个项目支持多个不同的上下文比如“开发模式”和“代码审查模式”可以允许.md前再加后缀但基础版本够用了。使用${EDITOR:-vim}这样如果你平时用 VS Code可以设EDITORcode --wait编辑档案时就会打开 VS Code保存完才返回终端。3.3 与 AI 编程助手的集成脚本本身只是把上下文档案切来切去真正发挥威力的是把它接到 AI 助手的读取链路上。如果你用的是一个支持自定义系统提示词的 AI 助手可以在它的设置里加一条请先阅读我的项目上下文路径为 ~/.context-mode/active_context.md 根据上下文内容了解项目背景然后回答我的问题。这样每次打开会话AI 会自动读取当前档案。如果你用的编程助手不支持从文件读取那也简单我一般会在会话开头手动执行cm .然后说“我的项目上下文如下”再把cat $CM_CONTEXT_FILE的输出贴进去下面开始提问。虽然多了一步粘贴但效果和自动注入是等价的。另外一个我常用的玩法是结合 shell 钩子实现目录自动切换。在zsh里可以加一个chpwd钩子chpwd() { if [ $PWD ! $HOME ]; then $HOME/.context-mode/cm.sh . /dev/null 21 fi }这样我只要cd进入项目目录上下文档案就会自动切到对应项目根本不用主动执行命令。有一段时间我甚至忘了它的存在只感觉到 AI 助手在哪个项目里都很“懂我”这就是好的工具该有的体验。4. 使用中的常见问题与避坑4.1 上下文过期与更新用了几个星期之后我发现最大的问题其实是自己偷懒不更新上下文档案。比如项目已经换了新的接口前缀但档案里还写着旧地址AI 就会一本正经地把错误信息告诉你。这不怪 AI责任在我。所以我现在养成了一个习惯每当项目发生结构性变化比如新增了目录、改变了请求封装方式、引入了新的依赖就会顺手跑一下cm --edit 项目名把对应内容改掉。频率大概一两周一次不会占用太多时间但可以确保档案始终站在“当前版本”上。如果你觉得纯手动更新太容易忘可以在档案的头部加一个last_updated字段然后用 cron 定期提醒自己检查。不过说实话对于个人项目保持轻量手动维护就够了没必要做过度设计。4.2 多项目交叉还有一种情况是两个项目本身就有依赖关系比如一个前端项目连着两个后端项目。这时候如果只用一个上下文档案AI 往往会搞混“当前在改哪个服务”。我的建议是档案只描述当前仓库本身不要试图把所有关联项目都写进一个档案里。需要联调时把另一个项目的接口文档或者关键的代码摘出来在提问时临时补充这样比全部塞进档案要可靠得多。还有一个多项目交叉的坑就是同名目录。如果你的两个项目都叫web它们就没办法用 basename 来区分了。我后来给 context-mode 加了一个环境变量覆盖机制在项目目录下不放配置文件但允许你在 shell 里手动指定export CM_PROJECT_NAMEuser-center-web cm这个小改动解决了 90% 的同名目录冲突。剩下 10% 的情况比如两个项目同名且你会频繁切换那就建议给其中一个改目录名长痛不如短痛。4.3 隐私与安全上下文档案里可能会写一些不便于公开的信息比如内部服务的地址、数据库表名、API 密钥提示等。如果你用 git 管理~/.context-mode一定要记得这个目录里存的可能就是敏感信息。我的做法是把contexts目录加入.gitignore只把脚本本身提交到仓库。如果确实需要多人共享上下文档案可以考虑单独建一个私有仓库并且不要在档案里写明文密码只写“从环境变量读取”之类的说明。另外当你把一个公开的上下文档案发给别人的时候要留意里面有没有包含你得当前路径、用户名等环境信息。context-mode 本身不抓取环境变量但你在写档案时可能会无意识地把个人路径写进去。这个靠自觉养成检查习惯就好。5. 从 context-mode 到团队协作的扩展思路context-mode 现在只是个人工具但它的基本思想完全可以扩展到团队协作。我们曾经在团队内部讨论过这个方案发现只要统一约定上下文档案的格式就能让不同成员对同一个项目的 AI 助手保持一致的“背景理解”。做法并不复杂在项目仓库里建一个.context/目录放一份经过脱敏的project.md内容就是公共的项目背景。团队成员各自本地维护自己的~/.context-mode/contexts把仓库里的project.md复制过来或者索性在切换脚本里加一条“优先读取项目内 .context/project.md不存在再读本地档案”的逻辑。这样的好处是新成员加入时只需要导入仓库里的背景档案AI 助手就能立刻按照团队规范来辅助编码而不需要每个新人都通过口口相传去了解项目结构。当然项目内档案需要更谨慎地控制信息粒度和代码强相关的结构描述可以写但涉及安全的内容就不要放了。如果你想走得更远还可以把 context-mode 的上下文档案与代码搜索工具结合。比如在切换上下文时同时用ctags或者rg生成一份当前项目关键符号清单追加到档案末尾。不过我实测下来这个功能对小型项目没什么必要对大型项目倒是有些帮助。关键符号清单可以让 AI 在回答问题时快速定位到具体模块减少它“瞎猜文件名”的次数。最后的最后我个人的体会是context-mode 这类工具的价值不在于脚本本身写得多优雅而在于它逼着你去认真思考“AI 要了解哪些关于我这个项目的事实”才能给出好答案。哪怕你不写一行脚本只是养成了把项目背景存成纯文本、每次切换时主动修改的习惯AI 辅助开发的质量也会肉眼可见地提升。先把上下文档案维护好再谈用什么工具去注入这才是这个标题背后真正的核心。