1. 一次上下文切换把我逼疯之后我写了 context-mode如果你也是那种在多项目之间来回横跳的开发者大概率能理解我这句话context-mode 不是用来记住上一条 cd 命令的它要解决的是“一键把整个工作现场恢复回来”这件事。我最早被逼到想写这个工具是在同时维护一个后端服务、一个前端后台、一个内部工具链的时候。早上还在 A 项目的 feature 分支上调接口下午切到 B 项目查线上问题结果 Bash 里环境变量还是 A 项目那套PATH 里挂着 A 项目的 node_modules/.bin工作目录在 B 项目git 分支却是 A 项目的分支。最惨的一次是我在 B 项目的目录下跑了个依赖 A 项目环境变量的脚本因为编译缓存目录指错了地方直接把 A 项目生成的临时文件删了。这些事单看都很小但组合在一起每天要花大量精力去确认“我现在到底在哪个项目里”“这个环境变量从哪来的”“为什么这命令跑出来的结果不对”。所以我做了一个叫 context-mode 的小工具命令行别名是ctm。它的核心模型很简单把当前的工作环境拍成一张“现场快照”起个名字存起来下次想回到这个现场一条命令恢复目录、环境变量、git 分支。这篇文章不是工具发布会而是把我设计这个工具时踩过的坑、做过的选型、以及最后沉淀下来的一些使用心得写出来。适合那些经常在多个仓库、多个分支、多套环境变量之间切换的终端用户如果你正在写类似的东西哪怕只是写了几个 shell 函数里面很多细节应该也对你有用。1.1 触发这个工具的真实场景我举一个具体的例子。我在本地同时跑着blog-api用 Node.js环境变量有DB_HOST、DB_PORT、JWT_SECRETadmin-web用 Vite环境变量有VITE_API_BASE、VITE_DEV_PROXYinternal-tools用 Python环境变量有PYTHONPATH、TOOL_ENV这三个项目我不需要同时打开但经常要在一天内来回切换。每次切换的成本包括cd 到新目录、手动 export 几个环境变量、git checkout 对应分支。如果有一次忘了 export后面所有命令都可能跑在错误配置下。context-mode 做的事情就是把这几个动作打包成一个有名字的“上下文”比如ctm save blog、ctm load blog。说白了这不只是节省键盘敲击而是消灭一类“环境状态不确定”带来的 bug。1.2 我给它设定的边界工具功能不能无限膨胀。我最开始想过保存 shell 历史、保存 tmux 窗口布局、保存后台运行的服务进程后来全部砍掉了。原因很简单保存的东西越多恢复时出错的概率越大而且很多东西根本没法跨会话恢复比如进程 PID 在终端关闭后就没意义了。context-mode 最终只聚焦三件事当前目录、当前环境变量的一个白名单子集、当前 git 分支。这三件事足够覆盖我 90% 的切换需求而且每一条都可以用纯文本可靠地表达。2. context-mode 的领域建模工作现场到底要保存什么为什么不能全存一个“上下文”在 context-mode 里的定义不是抽象的它就是一个可以被序列化到文本文件的现场记录。我把它建模成下面几个字段这里先给个全貌表后面再逐个展开。字段保存内容恢复方式主要风险work_dir当前工作目录的物理路径cd路径含空格或特殊字符env_vars白名单环境变量export变量值里有换行或引号git_branch当前分支名git checkout工作区有未提交改动saved_at快照时间不恢复只展示无context_source上下文归属的项目标记不恢复只展示无这个表里真正需要动脑的是 env_vars 的“白名单”设计。2.1 只保存白名单环境变量而不是整个 env很多人做类似工具的时候第一反应是env snapshot恢复时直接 source 回去。这个方案听起来省事实际上一肚子坑。env输出里包含大量会话相关的变量PWD、OLDPWD、SHLVL、_、TERM、SSH_AUTH_SOCK。这些东西要么恢复时没有意义要么会让你当前 shell 状态乱掉。我采用的方案是白名单加前缀匹配。在配置文件$CTX_HOME/config.sh里可以声明# 精确变量名 CTX_MODE_EXACT_VARS(DB_HOST DB_PORT JWT_SECRET VITE_API_BASE PYTHONPATH TOOL_ENV) # 前缀匹配比如 PACKAGE_MYPROJ_ 开头的都要 CTX_MODE_PREFIXES(MYPROJ_ PACKAGE_)保存的时候只从当前环境里挑出这些变量写入快照。这样既不会把敏感但临时的变量到处乱带也不会因为漏掉某个前缀变量导致恢复环境不完整。2.2 目录保存用物理路径还是逻辑路径这个细节很容易被忽略但踩过一次就忘不了。如果你所在目录是一个符号链接比如/home/me/link-project实际指向/data/projects/project-a用$PWD保存下来的是链接路径恢复时cd进去虽然能工作但如果你同时还依赖pwd_physical来判断项目根目录两个工具看到的结果可能不一致。我在实现里保存的是pwd -P的结果也就是物理路径。原因是大多数构建工具、git 和测试框架最终都会解析到物理路径按物理路径恢复行为最稳定。2.3 不该进入上下文的东西说几个我明确排除的进程 PID服务进程可能已经挂了恢复它没有任何意义。临时 Token比如某个云平台 CL 生成的短期凭证恢复旧 token 可能导致权限失效混淆。Shell 历史历史文件本来就全局共享强行按上下文分段反而影响日常搜索。终端标题太琐碎而且不是所有终端都支持。保存现场不等于保存所有状态。一个好的上下文快照应该只保存那些“能解释当前环境如何运行”的配置而不是“当前环境里恰好有哪些值”。这两个概念区分开以后整个工具的设计就清晰多了。3. 关键技术选型为什么 load 要采用 eval 而不是子进程结构context-mode 实现上最大的一个分岔路口是如何让“恢复命令”真正改变当前 shell 的状态。这看起来是个很基础的问题但实际做的时候很容易被不熟 shell 机制的人写成没法用的版本。3.1 子进程无法改变父 shell 环境如果我把ctm写成一个普通的 Python 脚本那么在 shell 里执行ctm load blog脚本运行在一个子进程里。子进程里os.chdir()和os.environ的修改都只影响子进程自己进程一退出父 shell 什么变化都没有。学过操作系统的读者肯定理解这点子进程不能修改父进程的地址空间。但写工具的时候人容易犯迷糊因为你会看到 Python 脚本里明明执行了cd和export感觉应该生效结果回到 shell 一看什么也没变。3.2 用 shell 函数包一层核心干活用外部脚本我最终用的模式是“shell 函数 外部脚本生成代码 eval 执行”。外部脚本负责读快照、解析变量、生成一段合法的 shell 代码然后由当前 shell 的函数把它 eval 掉。这样环境修改发生在当前 shell 进程内外部脚本只负责算和生成。一个简化的函数骨架长这样CTX_HOME${CTX_HOME:-$HOME/.config/context-mode} ctm() { local cmd$1 shift case $cmd in save) python3 $CTX_HOME/lib/ctx_impl.py save --name $1 ;; load) local generated generated$(python3 $CTX_HOME/lib/ctx_impl.py load --name $1) if [ -n $generated ]; then eval $generated fi ;; list) python3 $CTX_HOME/lib/ctx_impl.py list ;; *) echo usage: ctm [save|load|list|rm] 2 return 1 ;; esac }eval是这里的关键枢纽也是很多人担心的安全点。为了避免 eval 任意内容我只能让 eval 的对象是完全由 context-mode 自己生成的、并且经过严格转义的行绝不能让用户直接在快照文件里写 shell 命令块。快照文件虽然是文本格式但每一行都必须被解析成结构化字段再重新生成恢复脚本。换句话说快照文件不是 shell 脚本它是数据文件。3.3 这个模式和 direnv 是同一招使用direnv的读者可能会发现这个模式其实很眼熟。direnv 也不是直接改环境变量它是在 shell 提示符钩子里执行eval $(direnv export zsh 2/dev/null)。它的 export 子命令会输出一段 shell 代码然后再让当前 shell eval。明白这层机制以后很多“为什么我写不了类似工具”的疑问就消失了。你要做的不只是把状态写进文件而是设计一种安全的“shell 代码生成协议”。3.4 存储格式用结构化文本而不是 JSON 还是干脆用 shell我早期试过用 JSON 存快照后来放弃了。JSON 的好处是结构清晰坏处是当快照文件需要人工检查或修改时体验很差。比如临时想给某个上下文补一个环境变量用 JSON 得注意双层引号转义很容易手滑。最终方案是类.env的KEYVALUE格式加少量元信息行。它长这样# context-name: blog # saved-at: 2025-01-12T21:40:3308:00 cd /data/projects/blog-api export DB_HOST127.0.0.1 export DB_PORT5432 export JWT_SECRETlocal-development-only git checkout feature/rich-text外部脚本读取时逐行解析遇到export KEYvalue就做KEYvalue的解包而不是直接当代码执行。这样既方便人读也方便机器安全处理。4. 核心实现拆解ctm save / load / list / rm 到底做了什么现在把实现细节摊开。我尽量把关键逻辑写成可参考的代码片段你可以直接拿去改造成自己的版本。4.1 快照文件怎么组织所有上下文存放在$CTX_HOME/contexts/目录下一个上下文一个文件文件名就是上下文名。比如$HOME/.config/context-mode/contexts/blog.ctx $HOME/.config/context-mode/contexts/admin.ctx目录结构简单list 命令只要遍历目录取文件名即可rm 命令就是删除对应文件备份也只需要复制整个目录。这种朴素组织方式的好处是没有数据库也没有复杂的索引坏处是如果上下文多了目录下文件会变多但对我这种场景完全够用。4.2 save 命令给当前环境拍一张结构化照片save 的逻辑分三步解析白名单从当前环境中抽取变量。获取当前目录和当前 git 分支。按固定格式写入文件。抽取环境变量这步最需要小心。在 Python 里不能直接拿os.environ的原始值拼进文件必须做转义。因为环境变量值里可能包含换行、单引号、双引号、$符号。我统一用shlex.quote来生成export KEYvalue这一行的 value 部分。一个类似这样的核心片段import os import shlex import subprocess from pathlib import Path CTX_HOME Path(os.environ.get(CTX_HOME, ~/.config/context-mode)).expanduser() CONTEXTS_DIR CTX_HOME / contexts def load_config(): # 读取白名单简单起见直接从这里解析 exact_vars [DB_HOST, DB_PORT, VITE_API_BASE] prefixes [MYPROJ_] return exact_vars, prefixes def save_context(name): exact_vars, prefixes load_config() lines [] lines.append(f# context-name: {name}) lines.append(f# saved-at: {datetime.now().isoformat()}) lines.append(fcd {shlex.quote(os.getcwd())}) for key, value in os.environ.items(): if key in exact_vars or any(key.startswith(p) for p in prefixes): lines.append(fexport {key}{shlex.quote(value)}) branch subprocess.run( [git, branch, --show-current], capture_outputTrue, textTrue ).stdout.strip() if branch: lines.append(fgit checkout {shlex.quote(branch)}) ctx_file CONTEXTS_DIR / f{name}.ctx ctx_file.write_text(\n.join(lines) \n, encodingutf-8)这里我特意保存了cd和git checkout这样的行但在 load 的时候它们会被当成指令执行而不是像export一样先解析再重新生成。原因在于cd和git checkout这两个命令本身就是 shell 上下文的一部分直接执行它们反而安全因为它们对参数的敏感度远低于环境变量值的任意转义。4.3 load 命令恢复顺序比你想的重要load 最重要的不是“能不能执行”而是执行顺序。我的恢复顺序是先cd到目标目录。再设置环境变量。最后切 git 分支。这个顺序的考虑是git 命令需要在目标目录下执行才有效环境变量在 cd 之后设置是为了避免某些目录切换钩子比如 chpwd、direnv在你设置变量之前就把目录相关逻辑跑完。如果你先切分支再设置环境变量碰上有 git hooks 的项目hook 里可能用到当前环境变量结果就会不一致。load 的生成逻辑只要把解析后的行重新输出成代码再交给 shell eval 即可。下面是一个简化版ctm() { case $1 in load) local name$2 local ctx_file$CTX_HOME/contexts/$name.ctx if [ ! -f $ctx_file ]; then echo context $name not found 2 return 1 fi local generated generated$(python3 $CTX_HOME/lib/ctx_impl.py load --name $name) eval $generated export CTX_MODE_CURRENT$name ;; esac }加export CTX_MODE_CURRENT$name是我后来觉得很值的一个小动作。它让当前上下文的名称变成一个环境变量提示符里可以显示脚本里也可以判断。4.4 list / rm / rename 的细节list 只需要扫描目录按文件名排序输出同时把每个文件里的# context-name和# saved-at读出来展示。ctm() { case $1 in list) for f in $CTX_HOME/contexts/*.ctx; do [ -e $f ] || continue basename $f .ctx done ;; rm) rm -f $CTX_HOME/contexts/$2.ctx ;; esac }rm 的时候我会额外检查CTX_MODE_CURRENT是不是等于要删的名字如果是提示一下“你正在删除当前上下文”避免删完不知道自己现在处于什么状态。5. 实际使用中踩过的坑以及对应的解法工具写出来不难难的是用着用着发现各种边界情况。我把踩过的几个坑都列出来每一个都付出了不少调试时间。5.1 环境变量泄漏上下文之间互相污染这个坑是最深的。场景是这样的我先加载了上下文 AA 设置了DATABASE_URLpostgres://localhost/a。然后我手动干了一些活没有切上下文直接执行ctm save b把当前状态保存成了上下文 B。结果 B 里也带上了DATABASE_URLpostgres://localhost/a。之后有一天我加载 B发现数据库指向了 A当场崩溃。根因在于“当前环境变量不一定是当前上下文自己设置的可能是上一个上下文带过来的”。解决办法是给快照保存逻辑加一层“原产地追踪”。在加载上下文时context-mode 会记录这份快照里实际导出了哪些变量名把这些名字写进一个运行时文件$CTX_HOME/.runtime/$name.env.list。保存新上下文时如果某个变量不是当前上下文导出的它就不应该被自动收录。也就是说save 命令默认只保存“当前上下文激活后产生的变量”加上你白名单里明确点名的变量。这个逻辑用文字描述很容易但实现时需要一个全局变量记录“当前活跃的导出变量集合”。我在 shell 函数里用一个$CTX_MODE_EXPORTED数组保存load 时动态组装。5.2 路径含特殊字符的转义问题这个坑比较基础但很实用。项目路径如果含空格比如/data/My Projects/blog-api直接用cd /data/My Projects/blog-api就会断成两截。一开始我偷懒在生成恢复脚本时用双引号包路径cd /data/My Projects/blog-api。这能覆盖空格但路径里要是还有$、反引号、双引号还是会出问题。后来统一改用shlex.quote()把所有 shell 特殊字符都处理干净这个问题才算彻底解决。不要觉得这是小事路径里带$的目录在真实项目里并不罕见尤其是某些公司内部的构建产物目录喜欢用带特殊字符的命名。5.3 git 分支切换时遇到工作区脏数据恢复分支不能无脑git checkout。如果你当前在 context A 对应的目录下工作区里还有两个没提交的文件改动然后执行ctm load blog切到 blog 上下文对应的分支git checkout会直接失败导致上下文恢复到一半。我采用的策略是默认情况下如果目标分支切换会失败load 命令整体返回错误并明确告诉你“工作区不干净建议先 commit 或者 stash”。提供一个ctm load --force blog参数force 模式下先git stash再切分支。我不做自动丢改动的事情这应该是一条底线。5.4 PATH 被无限拼接有些项目会在 activate 脚本里写export PATH/project/bin:$PATH。如果我在保存上下文时直接把$PATH拍进去下一次加载时又在前面拼一段积累几次以后 PATH 会膨胀到几千个字符而且含有大量无效目录。我的解法是保存 PATH 时直接保存完整的 PATH 字符串不做前缀拼接恢复时先清空再赋值。同时在配置里把PATH列为特殊变量context-mode 恢复 PATH 时额外检查重复项确保同一个路径不会出现两遍。这个逻辑放在 load 生成器里属于外部脚本的职责。6. 让 context-mode 和现有生态协作direnv、git worktree、tmux接入了自己的工具之后总要考虑和现有工具共存的问题。context-mode 不是孤立运行的它要在开发者原本的 toolchain 里活下去。6.1 和 direnv 的分工谁负责环境变量direnv的机制是在你进入某个目录时根据.envrc自动加载环境变量。context-mode 和它有一部分功能重叠如果都做环境变量管理会打架。我的经验是如果一个项目有.envrc那环境变量交给 direnvcontext-mode 只负责目录和 git 分支。因为ctm load执行cd进入项目目录后direnv 的 hook 会自动触发如果我在 eval 脚本里先 export 了一套变量紧接着 direnv 又 export 一套后者会覆盖前者导致 context-mode 保存的环境变量形同虚设。实现上我在 load 生成的脚本末尾加了一行判断if [ -f .envrc ] command -v direnv /dev/null 21; then : else # 只有没有 .envrc 时才手动恢复 env_vars fi这个设计算不上完美但在真实场景里足够用有 direnv 的项目按 direnv 的规矩来没有 direnv 的项目context-mode 补齐手动恢复。6.2 用 git worktree 让同一个仓库同时存在多个上下文如果你经常要在同一个仓库的不同分支上并行干活git worktree 是个好东西。它允许你把同一个仓库的不同分支 checkout 到不同目录。context-mode 和 worktree 配合起来很舒服每个 worktree 目录建一个独立上下文里面保存不同的分支名和环境变量。比如ctm save blog-feature # 对应 worktree-a ctm save blog-hotfix # 对应 worktree-b ctm load blog-feature # 进去写 feature ctm load blog-hotfix # 切到 hotfix 现场这比在一个 worktree 里反复 checkout 分支安全得多因为不同上下文的 node_modules 和构建缓存都物理隔离。6.3 tmux让上下文切换同时带动窗口布局tmux 本身是会话管理工具context-mode 不抢它的活。但我会在 tmux 里配合一个技巧每个 tmux 窗口绑定到一个上下文。实际上更常用的做法是给每个 tmux 窗口的 pane 分别设置不同的初始目录然后在 pane 底部用$CTX_MODE_CURRENT显示当前上下文。在.tmux.conf里针对窗口标题也可以做成动态的set -g window-status-current-format #I #W (#{pane_current_path}) 这样即使在多个 tmux 窗口之间跳也能一眼看出当前是不是想到了那个上下文。这只是协作层面上的一个例子不一定所有人都需要。6.4 提示符集成把上下文名称显示在 PS1 里我最后加的一个小功能是在 prompt 中显示当前上下文。因为上下文很多光靠记忆很难判断当前激活的是哪一个。在 zsh 的PROMPT里加一段if [ -n $CTX_MODE_CURRENT ]; then PROMPT[ctx:${CTX_MODE_CURRENT}] $PROMPT fi在 bash 里对应的是PS1。这个改动成本极低收益却很大。每次看到[ctx:blog]就知道现在环境是博客项目的不需要再纠结。7. 最后再分享两个我用到顺手的小细节第一个是快捷键。我把ctm load绑定到了CtrlR的功能里通过 zsh 的历史搜索过滤出ctm load开头的命令再执行。这样切换上下文不需要敲完整的名字搜索一下回车就行。第二个是自动保存。我在 zsh 的precmd钩子里加了一个可选项如果当前上下文已经被激活并且检测到目录或 git 分支变了可以选择提示“上下文已漂移是否保存新的位置”。这个功能不用做成强制的只要提示就够了。因为我经常在一个上下文上手动 cd 到子目录如果自动覆盖快照反而会把原始入口弄丢。工具本身不复杂真正有价值的是把“工作现场”这件事想清楚什么该存、什么不该存、怎么安全恢复、怎么和现有工具相处。写到今天context-mode 已经成了我终端里最常用的几个命令之一。如果你也在多项目切换上吃过亏不妨按上面这个思路做一个自己的精简版希望这些踩坑记录能帮你少走几段弯路。