你有没有过这种经历：开了一大堆终端窗口，每个窗口里环境还不一样，明明写着同一个项目名，但这个窗口里 Node 是 18，那个窗口里跑的是 Python 的虚拟环境，还有一个窗口的环境变量指向的是线上配置。我曾经就是这种状态下的重度受害者。每天在几个项目间来回切，靠的是“我记得这个终端别乱关”的肌肉记忆，直到有一天我在错误的项目目录里执行了一条本应属于另一个服务的迁移脚本，虽然没造成实际损失，但那次之后我就下定决心：把“当前处于什么上下文”这件事系统化管理。这就是 context-mode 这个小工具从零到可用的完整来龙去脉。
如果你和我一样，经常在多个项目、多套工具链、多份环境配置之间切换，切换成本已经从“敲几条命令”变成了“记住一堆状态”，那这篇文章应该对你有用。它会讲清楚我为什么写这个工具、核心设计怎么来的、实现里最关键的 eval 注入机制是什么，以及在几个版本迭代中我踩过的真实翻车现场。内容偏实操，涉及 shell 脚本、YAML 配置、环境变量管理，但我会尽量把每一步的逻辑讲透，不以“照着抄”为目标，而是让你看完自己也写得出来。
1. 为什么我要写 context-mode：终端里的“上下文漂移”问题
1.1 上下文漂移是怎么发生的
先描述一个非常典型的场景。某天上午，我在给一个后端服务写接口联调，终端里早已 source 了当前项目的虚拟环境，PYTHONPATH 指向的是本地代码目录，API_BASE这个环境变量也被我手动改成指向本地 mock 服务。下午切到另一个前端项目时，我自然地在同一个终端里开始敲命令，结果发现npm用的 registry 还是之前为了调试后端时改过的内网地址，装个依赖磨蹭了半天也没装上。
这种问题不是你敲错命令，而是你正在思考的事情和终端里实际保存的状态已经不是一回事了。我把这个偏差叫作“上下文漂移”。它有三个典型来源：
- 环境变量残留：手动 export 过的东西不会因为你换了目录就自动消失。
- 路径和工具链不一致：不同项目要用的 Node 版本、包管理器、构建工具、Python 解释器各不相同。
- 别名和辅助脚本失效：你在 A 项目里定义了一堆便捷别名，到 B 项目里它们可能指向错误的东西。
最难受的是，这些状态不会主动提醒你。终端只会在你真正犯错的时候，用一条莫名其妙的报错告诉你“你现在的环境不对”。而那个时候，你往往已经花了不少时间。
1.2 现成方案的问题出在哪
在动手写 context-mode 之前，我把当时能想到的现成方案都试了一圈，它们各自都有明显短板：
- .env 文件：很棒，但它只能被程序读取，管不到交互式 shell 里的别名、PATH、PS1 这些“人的环境”。
- direnv：按目录自动加载确实解决了一部分痛点，但它偏重“进入目录就生效”，缺少“我主动定义一个上下文并随时切换”的思维。而且退出目录后，它只撤销自己加载过的变量，你手动设过的变量它一概不管，恢复得并不干净。
- 手动 source 脚本：本质靠自觉，脚本之间没有依赖关系，没有命名空间，source 多了连自己都记不清当前生效的是哪一组。
这些方案有一个共同的底层问题：它们都把“上下文”当作“环境变量的副作用”，而不是一个可以命名的、可切换的、有生命周期的一等概念。我想要的是像cd一样自然的操作——进入一个上下文，环境、路径、别名、钩子全部就位；离开它，一切恢复原状。
1.3 明确需求清单
既然要自己写，我先把需求列成一个清晰的清单，后来的所有实现都围绕这张表展开：
| 需求项 | 具体要求 |
|---|---|
| 命名与描述 | 每个上下文有唯一名字，方便记忆和 tab 补全 |
| 环境变量组 | 进入时批量设置，退出时可靠恢复 |
| 路径管理 | 支持向 PATH 中追加/移除目录 |
| 别名与函数 | 进入后定义项目专属别名，退出时清理 |
| 进入/退出钩子 | 支持执行外部命令，比如切换 Node 版本 |
| 嵌套能力 | 允许从 A 上下文再进入 B 上下文，退出时回到 A |
| 恢复可靠 | 基于快照恢复，不依赖“反向操作”枚举变量 |
| 可扩展性 | 配置用文本文件，新增一个上下文只需新增一个文件 |
这张清单后来几乎原封不动地成了 context-mode 的 v0.1 设计方案。现在回头想，最值得庆幸的是我一开始就把“可靠恢复”提上了需求表，而不是等踩了坑才补，否则后面几次翻车会严重得多。
2. context-mode 的配置设计：一份 profile 搞定环境、路径和钩子
2.1 profile 文件长什么样
我把每一个上下文定义为一个 YAML 文件，放在~/.context-mode/profiles/目录下，新增上下文就是新增一个文件。下面是一个我实际在用的前端项目 profile，结构非常直白：
name: frontend description: 前端项目标准环境 base: common env: NODE_VERSION: "18" PKG_MANAGER: pnpm API_PROXY: "http://localhost:8899" TS_NODE_TRANSPILE_ONLY: "true" path: - ./node_modules/.bin - ./scripts aliases: dev: pnpm dev build: pnpm build lint: pnpm lint hooks: on_enter: - command -v fnm >/dev/null 2>&1 && fnm use 18 on_exit: - command -v fnm >/dev/null 2>&1 && fnm use default一些字段在设计时特意做了取舍，我一个个解释：
base: common表示可以继承另一个 profile。common 里放所有项目都要用的通用环境项，比如EDITOR、LANG、一些通用路径。path中的相对路径是相对于 profile 文件所在目录解析的，比如./node_modules/.bin指的是 profile 文件放在哪个项目目录下，就指向哪个项目的 bin 目录。aliases在进入时定义，退出时自动删掉，避免一个项目的简写命令跑到另一个项目里。hooks是最灵活的部分。node 版本切换这种操作本质是修改当前 shell 状态，不太好直接放进 env 里表达，所以我把执行权限交出去，让用户自己写命令。
2.2 变量展开、优先级和继承机制
配置里最容易被忽视的是“变量展开顺序”。我举一个具体例子，某个 profile 的 env 里写了PATH_PREFIX: $HOME/.local/bin，如果展开太早，后面 shell 执行export PATH_PREFIX=$HOME/.local/bin时，$HOME会正常展开，这没问题。但如果值里包含的是另一个 env 项，比如LOG_DIR: $PROJECT_ROOT/logs，那展开顺序就必须严格按配置的先后顺序来，先展开PROJECT_ROOT，再到LOG_DIR。
我的实现做法是：把同一个 profile 的 env 定义按顺序放入一个临时 shell 片段里，由eval统一执行。这样 shell 天然帮你处理了变量嵌套展开，不需要我在 Python 侧再写一套展开逻辑。需要处理的只有两个边界：
- 如果变量名本身就包含特殊字符，只有通过
printf %q转义才能安全。 - 如果引用的变量在外部 shell 里不存在，展开结果是空字符串，这种通常要靠 hooks 里的检查命令兜底，配置写死值的场景很少遇到。
关于优先级，我采用了一个和常见环境变量相似但略有不同的规则：profile 内部定义的 env 覆盖 base 继承来的同名变量，进入前 shell 已有的同名变量会被快照保存并在退出时恢复。也就是说，context-mode 切换时并不“清空所有旧变量”，只管理 profile 里显式声明的那几个名字。这样做的好处是不会把你手动调试用的变量误删，坏处是如果你希望某个变量“离开后必须消失”，你得在 profile 的清理块里显式声明。准确性的优先级高于便利性。
2.3 为什么恢复基于快照而不是反向操作
这是整个工具设计中最关键的一个决定。一开始我天真地想过，退出一个上下文时，只要把进入时设置过的变量 unset 掉就行，进入时在 PATH 里加了目录，退出时把那个目录删掉就行。这个思路听着合理，实际用却是灾难。
原因很简单：你在一个上下文里不会只做“进入”这一件事。你可能会手动再 export 一个调试变量，可能会改某个已有变量的值，可能会往 PATH 里加新的目录。退出时如果只撤销“进入时的那一步操作”，你手动做的改动就永远残留下来了。而如果退出时盲目把所有相关变量重置，又会把你手动调好的配置一并冲掉。
所以我最后选了“快照”方案：每次进入新上下文之前，把当前 shell 环境中所有将被这个 profile 影响的变量名和值记录到一个临时文件里；退出时，直接从快照文件读取并恢复。等于在任何时间点，context-mode 都有一份“我进来之前长什么样”的备份。这个模型的代价是快照文件会占用一点磁盘，换来的是极高的恢复确定性，我觉得非常值得。
3. eval 注入模型：让子进程和当前 shell 对话的正确姿势
3.1 为什么普通程序改不了你的 shell 环境
如果直接把 context-mode 写成 Python 脚本，运行context-mode enter frontend，你会立刻撞上一堵墙：脚本是在一个子进程里跑的，它内部做一万次os.environ['NODE_VERSION'] = '18'，当前的 bash 也感觉不到分毫。这是 Unix 进程模型的基本限制——子进程不能修改父进程的内存，尤其是环境变量这种父进程自己持有的状态。
说得形象一点：你的 shell 是一个成年人，context-mode 这个命令是它的孩子。孩子长大出门转了一圈，回家想改变父母的记忆，但两个人各自有各自的大脑。技术上唯一的通道是“孩子大声把建议喊出来，父母决定听不听”。
这个通道就是标准输出。context-mode 的模式很明确：工具本身不执行任何状态修改，它只负责在 stdout 上打印一段合法的 shell 代码；调用方用eval把这段代码读回来执行。这就是 eval 注入模型。
3.2 eval 注入的核心调用方式
实际使用中，你会在.bashrc或.zshrc里写一个同名 shell 函数，把整个交互过程包装起来：
# ~/.bashrc 里的封装函数 context-mode() { local subcmd="$1" local name="$2" case "$subcmd" in enter) local script script=$(command context-mode "$subcmd" "$name") || return 1 eval "$script" ;; exit) local script script=$(command context-mode "$subcmd") || return 1 eval "$script" ;; list) command context-mode "$subcmd" ;; *) command context-mode "$@" ;; esac }而 Python 侧的enter子命令，本质上只做了一件事：读配置文件、解析、拼 shell 脚本、打印。以export为例，它不是print(f"export {k}={v}")这种毫无防备的写法，而是每一步都经过shlex.quote：
import os, sys, yaml, shlex, tempfile def render_env(data): lines = [] for key, value in data.get("env", {}).items(): lines.append(f"export {key}={shlex.quote(str(value))}") return "\n".join(lines)“计算”和“执行”两层分开之后，整个工具的安全边界清晰了很多。复杂逻辑集中在 Python 侧，可以做配置解析、路径查找、快照管理；shell 侧永远只负责两件事：接收上下文导出到当前环境、记住上一份快照。
3.3 除了 export 还要管什么
export 只是状态的一部分。要让一个上下文真正“生效”，eval 生成的脚本里还得包含：
export PATH=...PATH 的注入顺序要保证项目本地.bin在前面。alias定义，退出时用unalias清理。unset语句，退出时恢复快照里不存在的变量。cd，如果 profile 声明了workdir字段，我允许它切目录。- hooks 里的命令序列，通常用
;串联。
一个典型的 enter 脚本长这样（简化版）：
# 这条脚本由 context-mode 在 stdout 输出 export NODE_VERSION=18 export PKG_MANAGER=pnpm export PATH='/home/me/frontend/node_modules/.bin:/home/me/frontend/scripts:'"$PATH" alias dev='pnpm dev' cd /home/me/frontend command -v fnm >/dev/null 2>&1 && fnm use 18退出脚本的核心就一行：eval "$(cat /tmp/context-mode-snapshot-frontend.sh)"，这个快照文件就是上一节说的设计。
3.4 引号地狱：拿到手就要正视的问题
eval 注入最阴险的坑永远是引号和特殊字符。我第一次写出 v0.1 的render_env时图省事，直接用了f"export {k}={v}"，很快就在一个含空格的 Windows 风格路径上炸了：
# 错误示例，如果 value 是 "C:\Program Files\Node" export NODE_HOME=C:\Program Files\Nodeshell 会把这一行拆成两个 token，然后报command not found: Files\Node。更闹心的是，如果值里有$、反引号、双引号，shell 会再次展开，等于是给用户植入了一次任意代码执行。教训就一条：任何需要交给 eval 的文本，一律用shlex.quote或者printf %q转义，永远不要自己拼字符串。这个原则写作完成后立刻变成了代码里的铁律，后续再没出过同类问题。
4. 让切换真正无感：目录联动、编辑器同步和多终端一致性
4.1 按目录自动加载：把 context-mode 变成 direnv 的增强版
手动执行context-mode enter已经比过去好用了，但很快我就觉得还是不够“无感”。我进入一个目录的那个瞬间，往往正是我思维切换的开始，如果再让我回忆“这个项目该用哪个 profile”，那又回到了靠自觉的老路。
所以我加了目录自动匹配。规则很简单：进入一个目录时，向上逐层找配置文件。如果项目根目录有.context.toml，里面写了一行profile = "frontend"，当前 shell 就自动执行切换。zsh 里用chpwd钩子，bash 里用PROMPT_COMMAND，原理是一样的：
# zsh autoload -U add-zsh-hook add-zsh-hook chpwd _context_auto_enter # bash 在 PROMPT_COMMAND 里追加： _context_auto_enter这个设计和 direnv 很像，但有两点不同：一是我保留了手动 enter 的能力，自动判断只在存在.context.toml时生效；二是自动进入时不会破坏手动退出行为，你手动执行过context-mode exit之后，我就在这个目录下记一个标记，短期内不会再自动进入，避免用户在“不想被自动切”的场景下被反复打扰。
4.2 与编辑器、IDE 同步：让工具链也感知上下文
终端环境对了，编辑器环境还是拧着的。最烦的场景是：终端里我切到了后端 profile，PATH 指向的是 Python 虚拟环境里的解释器，但 VSCode 里还开着一个旧的 Python 解释器，代码提示和运行结果完全对不上。
办法是让 context-mode 在切换时写一个“当前上下文标记文件”，路径定在~/.context-mode/active，内容就是当前 profile 的名字和它对应的项目目录：
frontend /home/me/workspace/frontend编辑器插件监听这个文件的变动，就能自动加载对应的工作区配置。我没有先写插件，而是先从通用层下手：让这个标记文件决定.vimrc里的exrc路径、决定 IDE 的终端配置，后续无论用什么编辑器都只需要对接这个文件即可。标记文件也成了多终端同步的基础。
4.3 多终端同步：同一个仓库开三个窗口也不乱套
实际工作里从不会只开一个终端。一个仓库里同时开着三个窗口是常态，一个跑构建、一个看日志、一个临时敲命令。如果其中一个窗口手动切了 profile，其他窗口是不知情的，这就又造成了新的“上下文分裂”。
我没上后台守护进程这种重量级方案。原因很简单：context-mode 的定位是轻量 shell 工具，为同步引入一个常驻 daemon 会让用户始终提防“它到底在不在跑”。我采用了一个基于标记文件 mtime 的轮询方案：每个交互式 shell 在显示提示符之前，去比对~/.context-mode/active的 mtime 和本窗口上次执行切换时的 mtime。如果发现文件变了，同步执行一次快照切换逻辑，同时在新的一行打印一行提示，让你知道是哪个窗口切走了。
这个方案不是零延迟的，2 秒内能检测到，对我来说已经足够。它最大的好处是零常驻进程、不需要锁、断电重启也不会有残留状态。如果你的团队协作时每个人开很多终端，这个小同步机制带来的“大局观”非常值。
5. 迭代中的翻车现场：从 v0.1 到 v0.3 的真实踩坑记录
5.1 坑一：只用 3 行拼字符串的逻辑，在第一个真实 profile 上就崩了
v0.1 的 eval 生成器，我前面已经坦白过，最初是没有shlex.quote的。第一个真实世界的 profile 里，某个环境变量值是http://localhost:8899/api/v1?token=a&b=2，我当时甚至没意识到这里还有一个&。当这段代码被 eval 执行时，&前面的部分被 shell 扔到后台执行，后面的部分被当成另一个命令。结果那个下午我看到的现象是：环境变量没设上，反而多了一个莫名其妙的 background job。修复过程没有悬念，就是全面换printf %q。从那以后我把“代码生成代码”这件事当作编写编译器来对待，凡是往 stdout 输出的 shell 片段，全部经过可逆转义。
5.2 坑二：on_exit 钩子里调用 context-mode 导致递归死循环
v0.2 我给 hooks 加了on_exit支持。某个 profile 的 on_exit 里写了一条“退出时恢复 fnm 默认 node 版本”的命令，我满心欢喜地测试，然后眼见着终端进入了死循环：context-mode exit触发 on_exit，on_exit 里的某个脚本因为环境变化又触发了自动进入逻辑，然后再次触发退出……整条eval链像两台对着吼的电话机，直到我把终端关掉才消停。
根因是 hooks 缺少重入保护。修复方式是在 Python 侧加一个文件锁，进入和退出时先尝试获取~/.context-mode/.lock，拿不到锁就跳过 hooks 里的自动切换类命令。这比单纯加环境变量标记更稳，因为锁在跨进程层面有效，不会因为某个子 shell 重启就丢失。
5.3 坑三：每次 cd 都全盘扫描配置目录，把提示符拖成 200ms 龟速
自动目录匹配的 v0.2.1 上线后，我的终端开始明显变卡。每敲一次命令，PROMPT_COMMAND都会触发一次“从当前目录向上找.context.toml”的逻辑，而我的配置目录里已经有十几份 profile，每份还要做 YAML 解析。测下来单次开销到了 150~200ms，交互体验完全是灾难。
优化分成三层：第一层，用 stat 对比当前目录和上次匹配目录是否变化，没变化就直接返回；第二层，缓存从.context.toml解析出来的 profile name，直至文件 mtime 变化；第三层，所有解析只做一次，profile 内容在进入时生成一段 shell 脚本同样缓存一份，后续直接 eval 缓存文件。这三层做完，单次检测开销降到了 5ms 以下，基本感知不到。
5.4 坑四：退出上下文后，临时文件和历史 PID 经常残留
最后一个值得一提的坑是“清理不彻底”。v0.2 的快照文件写到哪里、何时删，一开始我完全没规划，都是靠系统临时目录自动清理。直到某天我发现/tmp/context-mode-*堆了上百个文件，每个都是几百字节，占空间不大但非常碍眼，而且一旦某个快照文件残留，下一次同名 profile 进入时会读到上一轮的过期快照，恢复出一个完全错误的环境。
最终方案是把快照和缓存都统一挪到~/.cache/context-mode/下，每次进入前先清理同 profile 的旧文件，退出后立刻删除本次快照。并且我会在 exit 脚本末尾加一行rm -f，确保即使用户从未再次进入也不会留下过期文件。
5.5 踩坑记录汇总
这一路踩过的坑我整理成一张表，方便以后排查类似问题：
| 阶段 | 现象 | 根因 | 修复方案 |
|---|---|---|---|
| v0.1 | 变量值含&导致后台执行 | 未经转义的 shell 代码拼接 | 全部使用shlex.quote/printf %q |
| v0.2 | 终端出现死循环 | hooks 触发重入 | 文件锁 + 重入检测 |
| v0.2.1 | cd 卡顿 200ms | 每次 prompt 全量扫描配置 | 目录 mtime 判断 + 解析缓存 |
| v0.2 | 残留快照恢复错环境 | 临时文件缺少清理策略 | 统一缓存目录 + 进入前清理 + 退出后删除 |
6. 什么场景不适合用 context-mode，以及我还在改什么
6.1 边界：有些东西不该放进 profile
把项目里所有环境变量一股脑塞进 profile 是很有诱惑力的，但我在实际使用中划了两条红线。第一条：涉及生产凭据的内容不要放进 profile 文件。context-mode 的定位是开发辅助工具，YAML 文件会进 git、会被同步工具带着跑，把数据库密码、API key 放进去相当于把钥匙挂在门口。这些信息应该由密钥管理服务在运行时注入，context-mode 不碰。第二条：需要强审计的多人共用机器上慎用。快照机制会让多人切换时互相覆盖当前上下文，如果环境不一致会导致排查问题的人互相甩锅。
另外，嵌套 context 超过三层之后，人的心智负担会明显上升。你很难立刻说清楚“当前生效的 PATH 到底来自哪个 profile”，排查起来只能一层层 exit。所以我在文档开头写明了建议：一个终端窗口里同时最多嵌套两层，更多的话应该依赖目录自动匹配而不是手动嵌套。
6.2 后续方向：模板函数、路径逼近和 AI 辅助配置
运行了半年之后，我对 context-mode 已经开始放心了，接下来的改进重点不在稳定性，而在配置编写体验上。第一个方向是模板函数，比如允许在 profile 里写{{project_root}}，由工具根据 profile 所在位置自动展开，省去每个新项目都复制一份绝对路径的重复劳动。第二个方向是路径逼近，如果你没写.context.toml但当前目录结构里出现了明显的package.json或pyproject.toml，我可以给出“疑似 profile”的提示，而不是默默什么都不做。第三个方向是 AI 辅助生成：把 profile 的 schema 和一段项目描述喂给大模型，让它生成一份初始配置文件，我再人工确认，可以显著减少冷启动成本。
最后分享一个实际使用中让我长期受益的小技巧：给常用的 profile 做短名字切换。比如frontend我通常直接叫fe，backend叫be。配合 shell 的 tab 补全，整个操作从“敲context-mode enter frontend”缩短到了“敲cm en fe”三个词。这套工具用习惯之后，最大的收益根本不是每层切换省下的几秒钟，而是你永远知道“当前终端处于什么立场”，那种确定性带来的安心感，是任何“多记住几个状态”的策略都给不了的。
