做开发的这些年我最高频的痛点不是某个框架用不熟而是每天要在一堆项目之间来回横跳切目录、改环境变量、唤起不同的本地服务、再给AI助手贴不同的背景说明。尤其是在同时推进两三个项目的时候光是把当前该用哪套配置这件事理清楚就能耗掉不少心力。后来我把这套东西收敛成了一个自研的小工具名字就叫context-mode。它本质上是一个上下文管理模式把每个项目需要的目录、环境变量、命令别名、AI提示词片段打包成一个独立模式通过一条命令完成切换和注入。这篇文章把它的设计思路、实现细节和踩过的坑完整拆一遍给同样被多上下文切换折磨的开发者一个可直接抄作业的参考。1. 为什么需要上下文模式这个抽象先明确一下我要解决的问题长什么样。假设你手头有三个项目一个 Python 写的 AI 服务一个 Node.js 写的前端后台还有一个数据分析脚本库。它们的环境完全隔离启动方式各不一样连对话的 AI 助手需要知道的背景知识也完全不同。1.1 传统切换方案的四种别扭大多数人会怎么处理这种多项目并行我总结下来无非四种路数。第一种是纯靠肌肉记忆。cd 进目录手动 export 环境变量记住每个项目独有的启动命令。这种方案最灵活但对脑子的负担极大中断一次回来就要回想半天。第二种是把所有东西塞进 shell 配置文件。在.zshrc里堆一堆 alias比如alias run-aicd ~/workspace/ai-service export PYTHONPATHsrc uvicorn ...。短期内很爽但配置一旦超过 20 条就变成垃圾场而且 shell 启动速度肉眼可见地变慢换一台机器还要重新收拾。第三种是借助 direnv 这类目录级环境管理工具。这个方案比前两种好很多目录一跳就自动加载环境变量。但它有个天然盲区它只管环境变量管不了AI 助手需要的上下文也管不了同一目录在不同任务下需要不同配置的情况。比如你在同一个仓库里既做日常开发又要做代码评审两件事该给 AI 的背景说明显然不一样direnv 就无能为力了。第四种是压根不切换所有项目全部平铺着同时跑。这在小项目上没问题但项目一多端口冲突、依赖版本冲突、构建缓存互相污染迟早会炸。1.2 context-mode 的核心抽象模式即状态集合我在设计 context-mode 时把上下文定义成一组状态的集合工作目录、环境变量、命令别名、AI 提示词、以及切换时应该执行的钩子命令。这五个东西打包成一份模式模式之间可以随时切换并且支持记录历史方便回退。之所以叫模式而不是环境或者工程是因为它比环境更贴近实际使用场景。同一份代码仓库完全可以派生出多个模式比如ai-dev和ai-review它们共享同一个目录但 AI 提示词和部分环境参数不同。把模式看作一个逻辑工作区物理目录只是模式里的一个属性这样抽象层级就对了。实际使用时的对比也很直观能力项手动切换direnvcontext-mode目录切换手动 cd自动自动环境变量加载手动 export自动自动命令别名/快捷启动需自建 alias不支持内置AI 提示词切换手动复制粘贴不支持自动注入切换历史与回退无无支持同目录多状态勉强可行不支持原生支持所以 context-mode 本质上不是替代 direnv而是把环境加载这件事上升到了工作状态管理的层级顺手把 AI 协作这个新变量也纳入了管理范围。2. 模式文件与切换机制核心实现思路context-mode 的实现其实不复杂核心就两个部分模式文件怎么定义切换时怎么让配置真正生效。2.1 模式文件的格式设计我选用了 YAML 作为模式文件格式存放于~/.context-mode/modes/目录下每个模式一个文件。选 YAML 而不是 JSON纯粹是因为它支持注释而且写多行文本比如 AI 提示词时不需要一堆转义符。一个典型模式长这样name: ai-service description: AI 服务项目日常开发模式 workdir: ~/workspace/ai-service env: PYTHONPATH: src API_TIMEOUT: 30 LOG_LEVEL: debug aliases: run: uvicorn app.main:app --reload --port 8000 test: pytest -x -q lint: ruff check src tests prompt: | 你正在协助开发一个 FastAPI PyTorch 实现的 AI 服务项目。 项目结构src/ 下是业务代码tests/ 下是测试。 回答问题时请参考以下约定 1. 所有新接口必须返回统一格式的 JSON 响应。 2. 模型相关代码放在 src/models/ 中使用 torch.nn.Module 定义。 3. 修改依赖需要同步更新 pyproject.toml。 hooks: on_enter: | echo 进入 ai-service 上下文模式 if [ -f .venv/bin/activate ]; then source .venv/bin/activate fi on_exit: | echo 退出 ai-service 上下文模式字段拆解一下workdir切换后cd的目标目录。注意这里支持~展开在代码里要显式处理后面踩坑部分会细说。env以字典形式定义的环境变量切换时合并进当前环境。aliases这个模式下可用的快捷命令。它们不是全局 alias只在当前模式激活期间临时生效。prompt供 AI 助手使用的背景描述这是 context-mode 比较有特色的部分。它解决的是每次打开 AI 对话窗口都要重新粘贴一遍项目背景的问题。hooks.on_enter/hooks.on_exit进入和退出模式时执行的 shell 命令常见用途是激活虚拟环境、启动/停止依赖服务。2.2 切换命令的原理为什么必须用 evalcontext-mode 的命令设计很简单主命令就五个cm list # 列出所有模式 cm use mode # 切换模式 cm create mode # 新建模式 cm edit mode # 编辑模式 cm status # 查看当前模式与环境状态但这里有一个硬性的技术约束一个子进程也就是cm命令本身是无法修改父进程当前 shell的环境变量的。你在终端里运行任何命令它都在独立进程中执行cd、export这些操作对当前终端没有任何影响。所以切换机制必须绕过这个限制。我的方案是让cm use打印一段 shell 脚本再由用户在 shell 里eval它。为了让这个过程不那么蠢我在.zshrc里定义了一个函数包裹它cm() { if [[ $1 use -n $2 ]]; then eval $(command cm use $2) elif [[ $1 back ]]; then eval $(command cm back) else command cm $ fi }对应的cm use ai-service这个子进程实际输出的是一段可执行的 shell 代码# 由 cm 生成的切换脚本 export __CM_PREV_DIR$(pwd) cd ~/workspace/ai-service export PYTHONPATHsrc export API_TIMEOUT30 export LOG_LEVELdebug alias runuvicorn app.main:app --reload --port 8000 alias testpytest -x -q alias lintruff check src tests # on_enter 钩子 echo 进入 ai-service 上下文模式 if [ -f .venv/bin/activate ]; then source .venv/bin/activate fi export __CM_CURRENTai-service这才是 context-mode 能真正切换环境的根本原因。所有工具只要能生成这类 shell 片段就能实现同样的效果Python、Go 还是 Rust 实现本体都不重要关键是这个 eval 机制。2.3 模式激活状态与退出清理有进入就得有退出。退出模式时最大的难题是你 export 过的变量、定义过的 alias怎么干净地撤销shell 没有原生的批量撤销环境变量能力。我的处理办法是context-mode 在进入模式时会把当前环境的快照写到~/.context-mode/session.sh退出模式时先执行on_exit钩子然后从快照恢复关键变量并unalias掉模式定义的别名。伪代码cm_back() { if [ -f ~/.context-mode/session.sh ]; then # 恢复旧工作目录和旧环境变量 source ~/.context-mode/session.sh unalias run 2/dev/null unalias test 2/dev/null unalias lint 2/dev/null echo 已退出 $(cat ~/.context-mode/current_mode) fi }快照文件里记录的是进入模式前的PWD以及模式可能覆盖的那些环境变量名恢复时重新 export 回去。这套方案不是万能的它没法精确还原一个变量之前未定义的状态只能把你已知会被覆盖的变量还原到旧值。但实际工作中足够用没有人会在模式切换里嵌套太多层。3. AI 提示词注入context-mode 最具价值的部分最初设计 context-mode 时我并没有把 AI 提示词算进去后来在真实使用中发现这个字段反而是用户反馈最多、最让人真香的功能。3.1 问题根源AI 对话的冷启动成本太高大型语言模型本身没有记忆每次新开对话都必须把项目背景、代码结构、约定规范重新告诉它一遍。如果你同时在维护三五个项目每天可能要复制粘贴五六次背景说明。更麻烦的是背景描述这种文本通常还会随项目演进不断修改散落在各个聊天记录里的旧版本很容易混淆。context-mode 的做法很简单直接把项目背景写进模式的prompt字段需要时一键拷出或自动注入到 AI 工具里。3.2 注入方式文件生成管线我在 context-mode 里加了一个派生命令cm context它把当前模式的prompt字段、当前目录下的项目文件清单、最近 Git 提交记录合并成一个结构化上下文文件.context.md。命令逻辑是cm context .context.md生成的.context.md长这样# 项目上下文ai-service ## 模式说明 当前处于 ai-service 开发模式以下是 AI 助手需要知道的背景信息。 ## 角色与目标 你正在协助开发一个 FastAPI PyTorch 实现的 AI 服务项目。 项目结构src/ 下是业务代码tests/ 下是测试。 回答问题时请参考以下约定 1. 所有新接口必须返回统一格式的 JSON 响应。 2. 模型相关代码放在 src/models/ 中使用 torch.nn.Module 定义。 3. 修改依赖需要同步更新 pyproject.toml。 ## 当前项目文件清单 - src/app/main.py - src/app/routers/inference.py - src/models/encoder.py - src/models/decoder.py - tests/test_inference.py - pyproject.toml ## 最近 Git 提交 - 2025-01-18 fix: 修复推理接口在空输入时的崩溃问题 - 2025-01-17 feat: 新增 batch 推理支持配合主流的 AI 编程工具有两种使用姿势一是直接把.context.md的内容粘贴进对话窗口二是如果你的工具支持通过外部命令获取上下文比如某些支持/context命令的客户端可以配置它读取这个文件。我自己最常用的是写一个简单的 shell 函数一键把.context.md送到剪贴板再到 AI 对话里CmdV整个过程两秒完成。copy-context() { cm context | pbcopy echo 上下文已复制到剪贴板 }3.3 动态内容让上下文不过期静态提示词有一个明显问题项目文件清单和 Git 提交记录会变。如果.context.md只能手动重新生成它很快就会过时。我的解决思路是所有动态内容文件清单、Git 记录都在cm context执行时现场生成而不是存进模式文件。模式文件里只保留真正稳定的那部分也就是项目背景、规范和约定。这样子做的好处是静态的部分一次维护动态的部分永远新鲜。当然代价是每次生成上下文文件需要执行git log和find好在这些操作耗时都在几十毫秒级别完全可以接受。这里还有个值得分享的经验给 AI 的上下文不能一味求多。早期我试图把整个项目的 README、设计文档、甚至所有模块的 docstring 都塞进去结果上下文一长模型反而更容易抓不住重点响应质量明显下降。后来我把 prompt 字段的内容控制在 200 到 400 字只保留角色定位 项目结构 必须遵守的约定这三件事效果反而稳定很多。给 AI 的项目背景是给思路不是给材料。4. 状态持久化与自动恢复让切换变成无感操作模式切换本身解决了主动切换的问题但还有一个更大的痛点每次打开一个新终端都回到默认环境需要手动重新进入模式。这很烦尤其是在你明明就在项目目录里的时候。4.1 基于历史频率的目录匹配我给 context-mode 加了一个状态持久层所有切换记录以 JSON 格式写进~/.context-mode/state.json{ current: ai-service, history: [ {mode: ai-service, workdir: ~/workspace/ai-service, timestamp: 1737072000}, {mode: data-analysis, workdir: ~/workspace/data-analysis, timestamp: 1737065000}, {mode: ai-service, workdir: ~/workspace/ai-service, timestamp: 1737040000} ] }新终端启动时shell 初始化脚本会读取$PWD匹配历史记录里最近一次使用该目录时对应的模式然后自动执行切换。匹配逻辑很简单优先精确匹配目录如果当前目录是某模式工作目录的子路径也视为命中。比如你在~/workspace/ai-service/src/models下打开终端历史记录里ai-service模式的工作目录是~/workspace/ai-service就能自动匹配上。4.2 自动恢复的实现细节在.zshrc里自动恢复的代码如下if [[ -n $ZSH_VERSION ]]; then __cm_auto_restore() { local mode mode$(command cm suggest $(pwd)) if [[ -n $mode $mode ! $__CM_SESSION_MODE ]]; then eval $(command cm use $mode --quiet) fi } precmd_functions(__cm_auto_restore) fi这里用了 zsh 的precmd_functions钩子每次终端显示新的提示符之前都会触发一次目录检测。注意我加了一个__CM_SESSION_MODE变量用于标记当前 session 已经处于哪个模式防止频繁重复切换。实际效果是不管在哪个窗口只要cd进项目目录回车之后环境已经切好了哪怕这是一个全新打开的终端。这个体验做到位之后context-mode 才真正从手动工具进化成无感基础设施。4.3 状态机的边界问题自动恢复机制看起来顺滑但有两个边界情况必须处理。第一同一目录多种模式。如果ai-service目录下既有ai-dev模式又有ai-review模式自动匹配只会按照历史记录选择最近一次用过的那个。如果用户想临时用另一个模式手动cm use ai-review就行不会被自动恢复打断。但要注意cm use之后__CM_SESSION_MODE会更新所以后续的新终端会自动使用新的模式。这是合理且自然的。第二模式间嵌套切换。比如在ai-service模式下你临时想去frontend模式看个样式问题办完事再切回来。context-mode 的cm back命令支持回退到上一个模式内部其实就是读取 state.json 的 history 数组倒数第二条记录。这个小功能实际使用的频率出乎意料地高。5. 踩坑实录模式切换里的三个深坑再顺滑的工具都是踩坑踩出来的。context-mode 在开发和使用过程中有几个问题花了我不少时间记录一下给后来者省点弯路。5.1 路径展开~ 和 $VAR 的隐式陷阱第一个坑在 YAML 的workdir字段上。用户写~/workspace/ai-service是人之常情但如果代码里直接拿这个字符串去cdshell 会报错因为~只有在 shell 解析时才会被展开子进程内部不会自动处理。解决办法是路径一律在 Python 端显式展开。我用的是os.path.expanduser而且是在生成切换脚本之前就完成展开输出进 eval 脚本的路径已经是绝对路径import os def expand_path(path: str) - str: return os.path.expanduser(os.path.expandvars(path))expandvars也不能省因为有些用户会在 workdir 里写$WORKSPACE/ai-service这种形式。如果只展开~不展开$VAR这段脚本同样会失败。5.2 eval 二次解析钩子里的特殊字符第二个坑比第一个隐蔽得多。cm use生成的是 shell 脚本然后用户用eval执行这意味着脚本里的内容会被 shell 完整地再解析一遍。于是钩子命令里的$、反引号、双引号都可能被二次求值产生意想不到的后果。举个例子一个用户写on_enter钩子想打印当前项目路径hooks: on_enter: | echo 项目路径是 $(pwd)这段文本如果原样输出到 eval 脚本里$(pwd)会在生成脚本的时候先被求值一次。如果 context-mode 内部是在子进程里用echo之类的方式生成脚本那实际输出的可能是项目路径是 /home/user而不是保留变量表达式。解决思路分两层。第一层context-mode 生成的脚本里所有钩子内容都应该用 heredoc 的方式传递避免在生成阶段被二次展开。第二层在文档层面明确告诉用户钩子内部的$如果需要 shell 延迟求值请使用\$转义。我在实测中更推荐第二种方式因为它在用户可控范围内出问题也好排查。5.3 环境变量残留模式切换最隐蔽的污染源第三个坑是环境变量残留。假设你用了很久的ai-service模式它设置了API_TIMEOUT30。后来你切到># 切换时先清理旧模式变量 __cm_cleanup_env() { if [ -f ~/.context-mode/current_env.list ]; then while IFS read -r var; do unset $var 2/dev/null || true done ~/.context-mode/current_env.list fi }这三类问题本质上是同一个根源子进程、eval、shell 状态这三个环节各自有隐含行为叠加起来就会产生诡异 bug。做这类工具最好在文档里就把切换脚本是被 eval 执行的这一点不断强调。6. 多机同步与团队协作把模式放进版本控制context-mode 除了自己用还可以作为一个团队的协作规范。毕竟配置结构清晰纯文本格式天然适合版本管理。6.1 模式文件的仓库化所有模式文件都在~/.context-mode/modes/下它们是独立的 YAML 文件不依赖任何二进制状态。这意味着可以直接把这个目录纳入 dotfiles 仓库管理cd ~/dotfiles ln -s ~/.context-mode/modes context-modes git add context-modes git commit -m chore: 更新上下文模式配置团队协作时一个典型的做法是每个项目根目录下放一个.context-mode.yaml描述该项目最常用的上下文模式。context-mode 支持从当前目录发现模式文件cm use --local会优先读取项目内的.context-mode.yaml而不是全局~/.context-mode/modes/下的文件。这样做有几个明显好处新同事 clone 仓库后运行一次cm use --local就能获得和团队一致的开发环境与 AI 提示词。模式文件和代码一起演进Review 的时候可以清楚地看到环境配置的变更。项目自包含不依赖个人的全局配置。6.2 敏感信息处理环境变量只存引用模式文件可能包含 API Key、数据库地址等敏感配置。如果直接写进 YAML再推送到 Git 仓库这基本等于裸奔。我坚决不建议在模式文件里存储真实密钥正确做法是只存放环境变量引用env: OPENAI_API_KEY: ${OPENAI_API_KEY} DATABASE_URL: ${DATABASE_URL}context-mode 在生成切换脚本时会执行expandvars从当前 shell 环境里读取真实值。也就是说密钥放在你自己的 shell profile 或者系统钥匙串里模式文件只是传递了一个名字。这样即使模式文件被公开也不会泄露任何秘密。6.3 团队内模式命名的约定多人协作时模式文件会被共享命名规范就变得很重要了。我在自己的团队里定下几条约定模式名前缀与项目目录保持一致使用短横线命名比如ai-service-dev。description字段必须填写禁止留空因为cm list的展示会依赖它。如果模式的prompt字段包含团队特有的编码规范必须在描述里标注团队规范方便新人识别。不在模式文件里书写只对个人生效的配置比如个人专属的编辑器路径、本地端口偏好。这些不是技术强制但能显著减少这个模式是谁的、能不能用这类沟通成本。7. 一周实测数据与当前局限最后展示一组我自己连续使用一周后的数据以及目前工具的明显边界。7.1 真实使用中的切换效率对比我挑了一个典型工作日做了对比统计手动方案和 context-mode 方案各记录了 12 次项目切换的耗时操作手动切换context-mode 切换定位并进入目标目录8-15 秒0自动恢复加载环境变量和虚拟环境5-10 秒1 秒内回忆/输入启动命令5 秒左右1 秒内alias 直接敲准备 AI 项目背景30-60 秒2 秒一键复制单次切换总耗时约 1 分钟约 3 秒一天 12 次切换理论上节省了约 11 分钟。看起来不多但省下来的不是连续时间而是每次切换时我要做什么来着的思考中断。这种注意力损耗比时间数字更值得优化也是我坚持把它做成工具的原因。7.2 已知局限与不适合的场景context-mode 不是一个万能开关有几个场景它明显不擅长。第一Windows 原生环境支持薄弱。eval 机制在 PowerShell 里不存在需要换一套命令规则。目前我的实现只在 macOS/Linux 的 bash/zsh 上验证过Windows 用户建议配合 WSL 使用。第二对 GUI 应用的环境变量注入无效。如果你需要的是给 IDE 或者 Docker Desktop 配置上下文context-mode 帮不上忙因为它只能影响 shell 环境。好在大多数现代 IDE 支持从 shell 启动这算一个轻量绕行方案。第三模式数量过多之后cm list本身会变成一个需要筛选的菜单。我目前维护了 15 个左右模式还能接受如果你维护 50 个以上建议按项目目录分组或者引入标签筛选。这也是下一步想做的优化。第四自动恢复匹配是基于历史频率而不是基于语义。如果你在同一个目录下经常随机切换不同模式自动恢复的成功率会下降。目前合理的使用节奏是一个物理目录对应一到两个常用模式超出这个范围建议手动切换。7.3 后续扩展思路context-mode 的实现足够薄扩展方向其实很多。我准备的计划包括增加模式依赖关系让一个模式可以继承另一个模式的基础配置增加与各类 AI 编程助手的本地插件对接把.context.md的生成从手动命令变成自动监听把状态存储从本地 JSON 换成 SQLite为后续的统计分析和模式推荐打基础。根据我个人的使用经验最值得先做的其实是模式模板功能。把最常见的后端开发、前端开发、数据分析这三类场景做成内置模板新用户只需要改改目录名和项目描述就能用而不是从零手写 YAML。上手门槛低了之后context-mode 才能真正成为日常工具链的默认选项。