context-mode：让shell按目录自动切换环境变量与上下文

这个项目的名字叫 context-mode，核心用途是帮你为每一类工作场景定义一套独立的环境模式，再由 shell 根据你当前所在的目录、仓库、特征文件等信息，自动进入对应的模式。说得直白一点，就是让你的终端“看一眼就知道你在干什么”，然后把 PATH、环境变量、alias、工作目录这些状态自动切到符合当前任务的形态。这个工具最适合那些经常在多个项目、多套技术栈之间横跳的人，比如前端写一半切到后端接口任务、白天写业务代码晚上写开源项目、或者在同一台机器上维护客户 A 和客户 B 两套隔离环境。如果你也受够了手动 export、手动 source、手动切目录这一套重复操作，context-mode 就是来干掉这些脏活的。

1. 为什么需要 context-mode：我每天被环境切换折磨

1.1 你在多个项目间切换时，其实在切换“上下文”

“上下文”这个词听起来抽象，但拆开看就非常具体。我常用的几个终端窗口分别对应不同项目：有的窗口在写 React 组件，node_modules 里的工具链要顺手；有的窗口在跑 Python 数据处理脚本，希望默认的python指向项目虚拟环境；还有的窗口纯粹当服务器在连远程环境。人脑切到不同任务时需要一段时间“把思路加载进来”，shell 环境也一样。如果你把所有项目的 bin 目录都塞进全局 PATH，后果就是命令冲突、版本错乱，甚至不同项目的依赖同名但版本不同，运行起来直接崩溃。这个问题的本质是：环境变量、别名、工作目录这些状态，应当跟着“当前正在做什么任务”走，而不是永远固定一份全局配置。

context-mode 解决的就是这个映射问题。它把“上下文”拆成可识别的信号：当前目录路径、git 远程地址、目录下是否存在.context-mode.yml、打开的是不是某个 tmux 窗口等。只要这些信号命中某条规则，它就认为你进入了某个模式，例如work、personal、docs、data，然后自动加载对应配置。离开这个目录、切换仓库时，又把环境恢复到进入之前的状态。整个过程不需要你手动干预，只在提示符刷新时自动判断。

1.2 现有方案为什么不够顺手

在动手写 context-mode 之前，我当然试过不少现成办法。最原始的是给每个项目写一个load-env.sh，进入目录就 source 一次；换项目时再 source 另一个。这套流程最大的问题是靠记忆驱动，忘了切就是事故现场。而且项目多了以后，脚本碎一地，维护成本直线上升。

后来又试过目录级别的环境加载工具，比如在某些目录放一个.envrc文件，进入目录自动激活脚本。它本身是个不错的思路，但对我来说有几点不顺手：第一，环境配置和目录强绑定，同一个模式要复制到多个目录时只能到处贴文件；第二，“离开目录后恢复原状”这件事做得很粗，或者说我不太愿意把整个环境的恢复逻辑交给一个局部脚本；第三，我想让一组规则决定进入模式，而不是一个目录一个文件硬编码。

所以 context-mode 的设计目标从一开始就很明确：把“上下文识别逻辑”和“环境切换动作”分离开，集中在一个配置文件里维护。规则是声明式的，动作是可组合的，shell 只负责在提示符出现前执行一次判断。这样既避免了目录级配置文件的碎片化，又保留了按目录自动触发的便利性。

2. 架构设计：核心原则是“脚本永远不直接改你的 shell”

2.1 为什么选择“输出 shell 片段 + eval”方案

第一版 context-mode 我天真地想用 Python 直接修改环境变量，马上被现实教育了：子进程无论怎么 os.environ 折腾，都影响不了父进程 shell 的内存。环境变量、alias、函数这些状态，本质上属于当前 shell 进程，外部程序根本没有权限直接动它。要跨进程变更 shell 状态，最经典的做法就是让外部程序“输出一段 shell 代码”，然后由父 shell 执行eval来真正修改自己。

所以 context-mode 的核心接口设计成了一个打印 shell 片段的命令：context-mode switch。它接收当前目录、当前 shell 标识，分析配置后，把需要执行的动作转换成export、unset、alias、unalias这样的 shell 语句，输出到 stdout。shell 侧拿到这段输出后 eval 一下，环境就切换过去了。这个模式被很多成熟工具验证过，实用、可靠，不依赖任何 IPC 或者守护进程，既好调试也好测试。

这个方案也带来一个安全注意事项：eval 的输入必须被严格看待。context-mode 只认可用户自己配置里的动作，并且我会在生成语句时做一次简单检查，遇到可疑内容就拒绝执行。写配置时的基本底线是：不要把不可信的、动态拼接的内容放进 actions 里。这一点后面会专门说。

2.2 状态机设计与幂等

环境切换最怕的事情之一是重复执行。如果每次提示符刷新都无脑执行export FOO=bar，短期没事，可一旦涉及 PATH 这类增量变量，就会越加越长，甚至出现几十遍重复路径。因此 context-mode 需要明确的状态模型。整条链路就四个状态：未进入任何模式、进入模式 A、从模式 A 切到模式 B、离开模式恢复未定义状态。

状态转移的核心依据是当前上下文指纹。每次 shell 提示符触发 hook 时，context-mode 都会重新计算指纹，再和上一次停留模式对比。如果指纹没变，说明还在同一个上下文，直接输出空内容，不对 shell 做任何操作。如果指纹变了，就生成一份“先回滚旧模式，再进入新模式”的完整指令。这套逻辑保证了幂等性：不管触发多少次，只要上下文没变，最终环境就是同一个状态，不会叠加脏数据。

具体实现时，我用了状态文件记录“当前所在的模式名”以及“进入该模式前的环境快照”。状态文件按 shell 独立 PID 存放，避免多个终端窗口互相干扰。切换的伪代码逻辑非常直白：

1. 计算当前上下文指纹。
2. 读取状态文件，找到当前模式。
3. 如果指纹命中的模式和当前模式相同，输出空。
4. 如果不同，先根据旧模式的动作回滚，再根据新模式的动作执行，更新状态文件。
5. 如果没命中任何模式，回滚旧模式，清除模式名。

2.3 配置格式：为什么选 YAML

在选择配置格式时，我对比过 JSON、YAML、TOML。JSON 写起来不够舒服，注释也麻烦；TOML 虽然直观，但表达嵌套的匹配规则时有点啰嗦；YAML 的缩进结构很适合描述“规则-条件-动作”这种树形内容，而且支持注释，可以在配置里把每个模式为什么存在写得清清楚楚。最终定下 YAML。

配置结构大致是：一个rules列表，每条规则包含name、match、actions三个部分。match声明上下文指纹的匹配条件，actions声明进入模式后要执行的动作。这个结构从一开始就稳定下来，之后加功能只是在match和actions里扩充字段，不需要改整体框架。

3. 核心模块实现与实操要点

3.1 上下文指纹：怎么判断“我在哪”

上下文指纹是整个工具的感知层。我把指纹分成几类信号，按可信度和计算成本排序：

第一类是目录信号。包括当前绝对路径是否等于某个路径、是否在某目录之下、是否匹配某个 glob 模式。这类信号计算成本最低，一条Path.match或者前缀判断就能完成。

第二类是特征文件信号。目录下是否存在特定文件，比如.git、package.json、pyproject.toml、Cargo.toml、.context-mode.yml。这类信号特别适合识别“这是个什么类型的项目”。比如某目录下存在pyproject.toml，就直接判定为 Python 工程，可以自动加虚拟环境 bin 到 PATH。

第三类是 git 仓库信号。检查当前目录是否属于某个 git 仓库，以及远程地址包含什么关键字。这个信号适合区分“这是公司仓库”还是“个人开源仓库”。代价是需要调用git remote get-url，有时候比较慢，所以我会加缓存，同一个仓库地址缓存在内存字典里，短时间内不重复跑。

第四类是环境信号。比如当前 shell 是否是交互式、终端窗口标题是什么、是否在 tmux 会话里。这个信号用来处理窗口层面的差异，比如在 tmux 的某个 pane 里专门做日志查看，就切到只读模式。

指纹代码大致长这样：

def collect_fingerprint(cwd: str, env: dict) -> dict: fp = { "cwd": cwd, "cwd_parts": list(Path(cwd).resolve().parts), "marker_files": [], "git_remote": None, "tmux_pane": env.get("TMUX_PANE", ""), "shell": env.get("SHELL", ""), } for marker in [".git", "package.json", "pyproject.toml", "Cargo.toml", "go.mod", ".context-mode.yml"]: if (Path(cwd) / marker).exists(): fp["marker_files"].append(marker) try: result = subprocess.run( ["git", "remote", "get-url", "origin"], cwd=cwd, capture_output=True, text=True, timeout=1, ) if result.returncode == 0: fp["git_remote"] = result.stdout.strip() except Exception: pass return fp

3.2 匹配规则与优先级

有了指纹，下一步就是把它和规则里的条件做匹配。匹配条件支持几种常见写法：cwd_equals、cwd_ancestor、cwd_glob、marker、git_remote_contains。配置示例：

rules: - name: "company" match: git_remote_contains: "git@github.com:my-company/" actions: env: APP_ENV: production aliases: gs: "git status" dev: "./dev.sh" - name: "personal-go" match: marker: "go.mod" cwd_ancestor: "~/code/playground" actions: env: GOPATH: "~/code/playground/thirdparty" path_prefix: "~/code/playground/bin"

规则匹配顺序很重要。context-mode 按配置文件里出现的先后顺序计算，同时为每一个匹配动作计算一个“具体程度”分值。目录精确等值加 10 分，祖先目录加 5 分，特征文件加 3 分，git remote 加 2 分。最终选择得分最高且所有条件都命中的规则。这样能避免出现“全身都匹配”的粗规则覆盖掉“精准定位”的细规则。

匹配代码的主体是一个循环，遍历规则集合，逐项校验：

def match_rule(rule, fp): match = rule.get("match", {}) if "cwd_equals" in match and fp["cwd"] != expanduser(match["cwd_equals"]): return 0 if "cwd_ancestor" in match: ancestor = Path(expanduser(match["cwd_ancestor"])).resolve() if not Path(fp["cwd"]).resolve().is_relative_to(ancestor): return 0 if "marker" in match and match["marker"] not in fp["marker_files"]: return 0 if "git_remote_contains" in match: if not fp["git_remote"] or match["git_remote_contains"] not in fp["git_remote"]: return 0 return score(match)

3.3 动作执行与回滚机制

这个部分是最容易被低估的。配置里写env: FOO: bar只是第一步，真正难的是怎么从状态 A 干净地回到初始状态。context-mode 用“环境快照”来解决。进入模式之前，把当前环境中所有将要被修改的变量值记录下来，存进状态文件；以后要离开模式时，根据快照决定export成原值还是unset掉。下面这段代码描述了快照和生成 shell 指令的核心流程：

def generate_switch_commands(old_context, new_context): commands = [] # 先回滚旧状态的 env if old_context: for var, old_value in old_context["saved_env"].items(): if old_value is None: commands.append(f"unset {var}") else: commands.append(f"export {var}={shlex.quote(old_value)}") # 再设置新状态的 env for var, value in new_context.get("actions", {}).get("env", {}).items(): commands.append(f"export {var}={shlex.quote(value)}") # PATH 前缀处理 for prefix in new_context.get("actions", {}).get("path_prefix", []): commands.append(f'export PATH="{prefix}:$PATH"') # alias for alias_name, alias_value in new_context.get("actions", {}).get("aliases", {}).items(): commands.append(f"alias {alias_name}={shlex.quote(alias_value)}") return "\n".join(commands)

这里有几个细节值得注意。一是环境变量快照必须在“第一次进入模式时”保存，而不是离开时保存。因为进入后变量已经被改了，离开时想恢复就必须先有一份修改前的副本。二是 PATH 这类增量变量，如果每次进入都做path_prefix，没有幂等处理就会重复。我的做法是把 PATH 前缀也存进快照，离开时去掉这些前缀。三是 alias 的恢复，bash/zsh 都支持unalias，但前提是旧值不是函数；如果旧环境本来就有同名 alias，快照里要保留它，离开时重新 alias 回去。

3.4 shell hook 集成细节

为了让整个工具自动触发，需要给 shell 加 hook。zsh 用precmd_functions，bash 用PROMPT_COMMAND，fish 用fish_prompt。hook 的任务就一件事：执行context-mode switch，捕获输出，eval。同时必须注意不要破坏上一条命令的退出码。以下是 bash 版本：

__context_mode_hook() { local last_exit=$? local new new="$(command context-mode switch --cwd "$PWD" --shell-id "$$" 2>/dev/null)" if [[ -n "$new" ]]; then eval "$new" fi return $last_exit } PROMPT_COMMAND="__context_mode_hook"

zsh 版本稍微有点不同，因为 zsh 的precmd_functions是以函数数组的方式存在的，还要注意local last_exit=$?的顺序，必须在任何可能改变退出码的命令之前读取。

autoload -Uz add-zsh-hook _context_mode_hook() { local last_exit=$? local new new="$(command context-mode switch --cwd "$PWD" --shell-id "$$" 2>/dev/null)" if [[ -n "$new" ]]; then eval "$new" fi return $last_exit } add-zsh-hook precmd _context_mode_hook

这里我踩过一个坑：bash 的PROMPT_COMMAND如果设成字符串，里面用到了局部变量就会在子 shell 里丢掉；设成函数名最稳妥。另外command context-mode能避免因为 alias 叫了context-mode导致的递归问题，这个小细节能省不少事。

shell hook 的性能也很关键。如果每次提示符都跑一次完整匹配，整个工具会拖慢终端响应。我的优化策略是给 shell 加一层缓存：状态文件里记录上次指纹的哈希，如果当前目录和 shell 标识没变，就不重新匹配，直接输出空。只有目录变化、进到新的 shell、或者状态文件缺失时才做完整计算。实测下来，正常提示符刷新只增加几毫秒开销，几乎无感。

4. 从零跑通：配置一个真实场景并跑通

4.1 最小配置示例

为了讲清楚怎么用，我搭一个实际的场景。假设你本机上有两块工作区：一块是公司项目目录~/code/work，所有仓库的 git 远程都指向公司域名；另一块是个人开源项目目录~/code/oss，里面的一些仓库使用 Go 模块。你希望进入公司目录时默认设置APP_ENV=production，提供一个deploy的快捷命令；进入个人项目时把GOPATH指向本地的模块缓存，并把本地 bin 加进 PATH。

配置可以写成这样：

# ~/.config/context-mode/config.yaml rules: - name: "company" match: cwd_ancestor: "~/code/work" actions: env: APP_ENV: production aliases: deploy: "./deploy.sh" - name: "oss-go" match: cwd_ancestor: "~/code/oss" marker: "go.mod" actions: env: GOPATH: "~/code/oss/.modules" path_prefix: - "~/code/oss/bin"

这里cwd_ancestor表示只要当前目录在~/code/work下，就算命中公司模式。marker表示只有存在go.mod才把GOPATH指过去，避免个人目录下的非 Go 目录也被误伤。

4.2 跑通功能

配置文件放好后，在 shell 里执行一次context-mode switch --cwd "$PWD" --shell-id "$$"，可以看到它输出一段 shell 指令。再配合前面挂上的 hook，实际体验就很完整了。进入~/code/work/api时，它会自动执行：

export APP_ENV=production alias deploy='./deploy.sh'

进入~/code/oss/tool时，自动执行：

export GOPATH=~/code/oss/.modules export PATH=~/code/oss/bin:$PATH

离开这些目录、回到~时，它会恢复APP_ENV、GOPATH和 PATH 的原状。整个过程全程不需要手动输入任何命令，只在提示符出现前静默完成。

4.3 调试技巧

调试这种“自动触发”的工具，最容易头疼的是看不到到底发生了什么。我加了两个实用的调试方法。第一个是--dry-run模式，只打印将要执行的 shell 指令但不真正 eval；第二个是--verbose模式，把指纹、命中的规则、得分都打印出来。遇到“为什么没生效”的问题，我一般是先跑到目标目录下执行：

context-mode switch --cwd "$PWD" --shell-id "$$" --verbose

看输出里指纹收集到了哪些 marker、git remote 是什么、规则匹配到哪个模式、得分多少。问题往往就出现在这一步。如果指纹没问题但环境没切，再检查是不是 eval 那段被什么吞掉了，比如PROMPT_COMMAND里忘了eval。这套“先看指纹、再看匹配、最后看执行”的排查路径，基本覆盖了绝大多数问题。

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

5.1 常见问题速查

我把实际使用中遇到的典型问题整理成了一张速查表，遇到同类的可以直接照着处理。

5.2 我在真实使用中踩过的三个坑

第一个坑是 PATH 重复。刚开始实现时，我在actions里写了path_prefix，但离开模式时只恢复了普通环境变量，没有管 PATH，导致切几次以后 PATH 里挂了一串相同的目录。后来我把 PATH 也当作一个特殊变量纳入快照，进入前记录完整 PATH，离开时用更精确的方式把对应前缀摘掉。不要只依赖export PATH=...，更要管好“离开时怎么还原”。

第二个坑是 git remote 查询的超时。如果你在大型 monorepo 里，每次 prompt 都执行git remote get-url origin，不仅要等 git 读配置，还可能因为网络挂载仓库卡住。我的解决方法是给这条查询加 1 秒超时，并且把结果缓存到状态文件里，目录不变就不重复跑。另一方面，如果匹配规则只用了git_remote_contains，可以先用cwd_ancestor缩小范围，减少对 git 的依赖。

第三个坑是 bash 和 zsh 对函数作用域处理不一样。我在 bash 里写测试没问题，切到 zsh 后就发现 hook 内部定义了一个局部变量PATH，结果把整个全局 PATH 覆盖了，后面所有命令都找不到。排查了半天才想起来 zsh 的typeset和 bash 的local在全局/局部变量上的行为差异。从那以后，hook 函数里用到的变量一律用不同的名字前缀，比如_CM_OLD_EXIT，避免常见名字冲突。

5.3 环境变量恢复的顺序问题

环境恢复的顺序也有讲究。假设你从公司模式切到个人模式，公司模式设置了APP_ENV=production，个人模式没有设置APP_ENV。正常逻辑应该是切到个人模式时UNSET APP_ENV。但如果你在个人模式的动作里没有显式处理旧变量，单靠“回滚旧模式”这一步就能做到。先把旧变量恢复成原始值，再设置新模式的值，这个顺序不能反过来。反过来会出现：新模式没有定义旧变量，旧模式先执行设置，然后新模式没有覆盖，最后残留旧状态。我的生成器始终遵循“先回滚、再进入”的顺序，把状态转换变成一条线性流水线。

5.4 多终端并存时的状态隔离

很多人开着多个终端窗口，同一个目录里同时做不同任务。假设你在终端 A 进入了~/code/work，环境切到公司模式；终端 B 还在~/，没有命中任何模式。如果状态文件只有一个公共文件，终端 A 的切换就会污染终端 B，导致终端 B 莫名其妙也有公司模式的 env。这个问题的解法就是每个 shell 独立状态。把状态文件按shell-id拆开，每个终端走各自的状态机，互相不干扰。这也是为什么 hook 需要把$$传给命令：$$在每个交互 shell 里是稳定的，两个终端不可能相同。

6. 最后想分享的几个设计取舍

写到这，我在键盘上敲下最后一个模块的时候，其实心里一直在想一件事：工具类项目最容易失控的地方，就是功能越加越多。context-mode 也有过这个阶段，我曾经想加“按窗口显示模式切换主题”“自动切换 tmux 布局”“动态执行任意命令”等一堆功能，最后砍掉了大半。我现在的原则是，匹配识别层和环境切换层保持正交，识别层可以加入更多指纹信号，切换层只需要做 export、unset、alias、PATH 调整这四件事。凡是需要“跑一段任意脚本”的场景，我建议在 actions 里用alias或显式 shell 命令去承接，而不是让 context-mode 成为通用执行器。

在实操中我觉得最值的决策，是引入了--dry-run和--verbose这两个调试入口。它们让我在排查问题时不必一遍遍猜，直接把内部状态摊开看。每次改完配置文件，我都会先跑到对应目录下看一眼输出，确认无误再放心交给自动 hook。这个习惯让我少掉了大量“以为配置生效了，其实根本没有”的时间。

如果你也想做类似的事，不妨从最小的规则开始：先只管理一个环境变量，跑通整个链路，再加上 PATH 和 alias。等这套流程用顺手了，再慢慢把复杂场景加进去。工具的价值不在于代码量多少，而在于它是否真的能让你少做重复的事。context-mode 现在对我就是这样。