刚看到这个标题的时候，我第一反应是：这不就是一个带记忆的配置切换器么？后来越琢磨越觉得不对，比自己想的要复杂得多，也实用得多。
“context-mode”现在是个很火的概念，但它不是那种玄乎的AI术语，而是实打实的工程问题：你在不同的项目、不同的分支、不同的环境之间来回切换时，需要跟着变的不止是环境变量，还有工具链版本、配置文件、命令行参数、依赖源、甚至编辑器状态。把这些东西当成一个整体来管理和切换，就叫上下文模式。
这背后的需求其实一直存在，只是以前大家靠的是各种临时手段硬撑：开多个终端、手动改配置文件、写一堆export命令、复制粘贴环境变量。撑到某一天，你忘了切回来，结果在错误的上下文中跑了一个关键操作，浪费了一下午时间排查。我相信每个开发者在职业生涯里至少踩过一次这种坑。
这篇文章我会从零开始，带你把一个可用的context-mode完整实现出来。它解决的核心问题就是：让“环境上下文”变成可以被显式创建、切换、记录、回溯的一等公民，而不是散落在各个shell脚本里的一堆秘密。
1. 项目拆解：context-mode 到底在解决什么问题
1.1 痛点场景先还原一下
先说说我自己的真实经历。有一段时间我在同时维护三个项目：一个是基于 Node 18 的老管理系统，一个是切到 Python 3.11 + FastAPI 的新服务，还有一个是偶尔碰一下的 Go 微服务。这三个项目对开发环境的要求完全不同，最明显的冲突在：
- Node 版本：A 项目只能用 16，B 项目要 18，还有个 C 项目要 20。
- 私有源：有些项目要从公司内网源拉依赖，有些走公共源。
- 环境变量：数据库连接串、缓存地址、日志级别，每个项目都不一样。
- 命令行别名：比如部署命令，A 项目是 deploy.sh，B 项目是 fab deploy。
- 编辑器状态：最烦的是打开 IDE 后要手动切换工作区配置、格式化规则。
我当时的办法是每个项目开一个专属终端，里面手动执行source scripts/env.sh来加载环境变量。看起来很常规，但问题在于：
第一，这些脚本散落在各个项目仓库里，一旦项目多了，你根本记不住哪个仓库的哪个脚本是干什么的。第二，脚本之间没有隔离机制，从一个项目切到另一个项目时，旧的环境变量并不会自动清理，于是出现PATH里同时存在两个版本的Node、PYTHONPATH指向上一个项目的诡异情况。第三，没有“上下文”这个概念，你只是在执行一段脚本，而不是在“切换状态”，出错了也不知道去哪看。
context-mode要解决的，就是把这个散乱的过程变成一个统一、可感知、可回溯的状态管理模型。
1.2 为什么叫 context-mode，而不叫环境切换工具
这是我自己在梳理需求时反复纠结过的问题。环境变量、配置项、工具链版本，单独拿一个出来，都有现成的工具去管理（direnv、dotenv、nvm、rvm……），但这些工具之间是割裂的。而且它们大多数是“环境”维度的抽象，不是“上下文”维度的抽象。
什么是上下文？上下文是一个工作场景的完整快照。在这个场景里，不仅环境变量要配对，还有：
- 你用的包管理器及其配置文件
- 当前项目的根目录
- 激活时自动启动的服务或守护进程
- 该项目专属的命令别名和函数
- 可能还有依赖的数据库、缓存等外部资源的状态
“环境切换”是一个动作，而“上下文”是整个场景本身。比如你在做需求开发、在修线上Bug、在做性能排查，这三种工作虽然在同一个项目里，但可能对应完全不同的调试工具、日志等级、临时配置。如果只有“环境变量”这一层抽象，你是表达不了这种差异的。
所以我最终把项目的核心理念定为：把进入一种工作状态时需要的所有变化，打包成一个可切换、可嵌套、可序列化的上下文单元。这个理念比“环境管理”更贴近实际开发体验，也更能指导后续的架构设计。
1.3 方案选型：为什么我选了 Python + JSON 而不是 Shell 脚本
明确了要解决的问题之后，就到了选型阶段。坦白讲，第一版我想过直接用纯 Shell 写，因为它不需要任何运行时依赖，一个文件拷到任何 Linux/macOS 机器上就能跑。但很快我就发现了一个致命问题：如果你的 context 里需要保存结构化的数据——比如多组环境变量、多个别名、多个文件路径映射——Shell 只有字符串数组和关联数组可以用。处理嵌套结构、序列化、版本迁移会非常痛苦。
Node.js 也可以，而且处理 JSON 很方便。但对于一个经常要在不同机器上快速拉起来用的工具，Node 的启动速度和依赖安装还是有点重。
最后还是选了 Python 标准库来做。选择它的理由非常具体：
- Python 3.8+ 自带 json、argparse、pathlib，零第三方依赖。
- 数据结构表达能力强，dict 和 list 天然很适合上下文这种嵌套配置。
- 启动速度虽然比不上纯 Shell，但对命令行工具来说，300ms 以内的延迟完全可以接受。
- 后续如果要扩展更复杂的逻辑（比如上下文合并、差异比较、钩子系统），Python 的实现成本明显更轻松。
而且 Python 在几乎所有开发机上都有，不需要额外安装运行时。代价是需要把 Shell 的父子进程关系处理好——因为子进程里改环境变量影响不了父进程。这个问题的解法不是回避它，而是用shell集成的方式绕过去，后面实操部分我会详细讲。
2. 核心设计与实现细节
2.1 定一个小目标：一个可以运行的最小闭环
项目切入的方向建议收敛到最小可用的闭环。不要一开始就想着支持钩子、支持嵌套、支持远程上下文，那些都会让第一版变成永远发不出来的半成品。我在实现时给自己划定的 MVP 边界是：
- 能够创建一个上下文（指定上下文名称和对应的目录）
- 能够列出所有已有上下文，并查看当前激活的是哪一个
- 能够切换上下文，自动加载该上下文里定义的环境变量、别名、工作目录和自定义命令
- 能够退出上下文（取消激活），恢复到系统默认状态
- 能够把当前生效的上下文状态持久化，支持下次进入终端时自动恢复
这个范围，一个下午就能跑通，而且已经覆盖了日常 80% 的需求。后面所有复杂的扩展，都是在这个闭环上慢慢加的。
2.2 配置文件长什么样：JSON 的字段怎么设计
存储层我选的是 JSON 文件，放在用户主目录下的 .context-mode/contexts/ 目录里。每个上下文对应一个独立的 JSON 文件，文件名即上下文名称。这么做的好处是：上下文之间天然隔离，不会因为一个文件损坏影响所有上下文，也方便用 git 对配置历史做版本管理。
我实际使用的配置结构长这样：
{ "name": "service-a", "version": "1", "description": "A 项目日常开发环境", "env": { "NODE_ENV": "development", "API_BASE_URL": "http://localhost:8080", "LOG_LEVEL": "debug" }, "path": { "prepend": ["/opt/node/18/bin", "$PROJECT_ROOT/scripts"], "append": [] }, "aliases": { "dev": "npm run dev -- --port 3000", "deploy": "./scripts/deploy.sh" }, "cwd": "~/work/service-a", "extensions": {} }env 字段就是激活时需要导出的环境变量。这里有个细节：值里允许引用占位符，比如 $PROJECT_ROOT 会在加载时被替换成上下文的 cwd 值。这样你可以在别名和环境变量里复用路径信息，不用写死绝对路径，迁移到另一台机器时不用改配置。
path.prepend 和 path.append 用来控制 PATH 顺序。prepend 里的路径会加到 PATH 最前面，实现“优先使用本项目专属的工具链”的效果。比如同一个系统里装了多个 Node 版本，你用 prepend 指定本项目要用 18，而系统默认是 20，切换进来之后就自动用 18 了。
aliases 字段是重点设计。它不只是简单的 字符串别名 = 命令，而是支持变量展开。在加载时，$PROJECT_ROOT 和 ${VAR} 都会被替换成对应上下文的值。这样你在不同机器上 clone 到不同路径，别名依然能正确工作。
extensions 字段目前保留为扩展点位，我在第一版里没实现具体逻辑，但后面可以塞入 git 分支自动切换、启动/停止子进程等功能，不用改数据结构。
2.3 命令设计：交互方式尽量贴近直觉
CLI 设计上我参考了 git 的子命令风格，一共有六个基础命令：
ctx list # 列出所有上下文，标记当前激活项 ctx use <name> # 切换到指定上下文 ctx exit # 退出当前上下文 ctx create <name> # 交互式创建新上下文 ctx show [name] # 查看上下文详情 ctx rm <name> # 删除一个上下文这里没有加 ctx init，因为 context-mode 的使用逻辑是“围绕项目目录展开”，上下文文件集中在 ~/.context-mode/contexts/ 里，不要求项目根目录有 .context 之类的标记文件。好处是：你可以为一个目录维护多个上下文，而不用把配置污染进代码仓库。
有一个交互细节值得提一下：ctx use 之后，工具应该打印当前加载了哪些环境变量和别名，以及从哪个旧上下文切换过来的。这个反馈很重要，否则程序员很容易忘记自己当前在哪个上下文里，然后又开始犯错。
2.4 状态记录：切换后如何追踪当前上下文
状态文件我放在 ~/.context-mode/state.json，内容只有两行：
{ "current": "service-a", "previous": "service-b", "updated_at": "2025-01-16T14:23:11+08:00" }为什么不用一个纯文本文件？因为我在 2.2 版本里要支持退出时的“返回上一个上下文”，这样做需要同时记录 current 和 previous。等版本号留出来之后，将来做多目录同时激活多个上下文时，这个结构直接可以扩展成 stack。
这个状态文件会被两种情况读取：一种是 ctx 命令本身，另一种是 Shell 集成函数里的 prompt 渲染。后面讲 shell 联动时再说。
3. 实操：从零实现一个可用的 context-mode
3.1 项目目录结构先搭起来
我的项目根目录叫 context-mode，结构比较简单，就三个文件：
context-mode/ __main__.py // 入口 ctx // 可执行脚本（包装 python 命令） lib/ __init__.py core.py // 核心逻辑：加载、展开、切换 storage.py // 上下文读写、状态持久化main.py 如果一个目录要能被 python -m 直接调用，这个文件是必须的。而 ctx 这个脚本是用户主目录下的软链接还是直接复制到 PATH 里，取决于你习惯。我的选择是：把 ctx 脚本复制到 ~/.local/bin/ctx，内容如下：
#!/usr/bin/env bash python3 "$HOME/.context-mode/__main__.py" "$@"这样保证你用到的代码版本是全局统一的一份，升级方便。
3.2 初始化与上下文发现机制的实现
storage.py 里的上下文发现逻辑，我建议用 pathlib 来实现。遍历 ~/.context-mode/contexts/*.json 文件，返回上下文名称列表。注意，在解析每个文件时要做基础合法性校验，不能因为一个 JSON 文件损坏就让整个 list 命令报错。
# lib/storage.py import json import os from pathlib import Path BASE_DIR = Path.home() / ".context-mode" CONTEXTS_DIR = BASE_DIR / "contexts" STATE_FILE = BASE_DIR / "state.json" def ensure_layout() -> None: CONTEXTS_DIR.mkdir(parents=True, exist_ok=True) if not STATE_FILE.exists(): write_state({"current": None, "previous": None}) def list_contexts() -> list[str]: ensure_layout() contexts = [] for p in CONTEXTS_DIR.glob("*.json"): if p.name == "contexts.json": continue try: data = json.loads(p.read_text(encoding="utf-8")) contexts.append(data["name"]) except (json.JSONDecodeError, KeyError): print(f"[warn] skip invalid ctx file: {p.name}") return sorted(contexts) def load_context(name: str) -> dict | None: ctx_file = CONTEXTS_DIR / f"{name}.json" if not ctx_file.exists(): return None return json.loads(ctx_file.read_text(encoding="utf-8")) def read_state() -> dict: ensure_layout() return json.loads(STATE_FILE.read_text(encoding="utf-8")) def write_state(state: dict) -> None: STATE_FILE.write_text( json.dumps(state, indent=2, ensure_ascii=False), encoding="utf-8" )这里的容错逻辑是我踩过坑之后才加的。以前直接用 json.load 一把梭，遇到一个损坏文件，整个命令直接崩掉，排查半天还找不到原因。现在每个文件单独 try/except，读不到的就打印警告跳过，其他正常上下文不受影响。
3.3 核心切换逻辑：变量展开与加载
core.py 里最关键的函数是 activate，它的职责是：拿到一个上下文配置，对其中所有涉及路径和变量的字符串做展开，然后把加载命令输出成一段 shell 脚本，交给父 shell 去 eval。这也是 context-mode 能够影响当前终端的关键——Python 子进程本身改不了父进程的环境变量，唯一靠谱的做法就是让子进程生成脚本，父进程执行。
# lib/core.py import json import os import re from pathlib import Path from . import storage VAR_RE = re.compile(r"\$\{([^}]+)\}|\\$([A-Za-z_][A-Za-z0-9_]*)") def expand_vars(value: str, env: dict) -> str: def replace(m: re.Match) -> str: key = m.group(1) or m.group(2) if key in env: return str(env[key]) return os.environ.get(key, "") return VAR_RE.sub(replace, value) def build_activation_script(ctx: dict) -> str: env = dict(os.environ) env["PROJECT_ROOT"] = ctx.get("cwd", "") lines = [] for key, val in ctx.get("env", {}).items(): expanded = expand_vars(val, env) lines.append(f"export {key}={shlex.quote(expanded)}") for p in ctx.get("path", {}).get("prepend", []): expanded = expand_vars(p, env) lines.append(f"export PATH={shlex.quote(expanded)}:$PATH") for alias, cmd in ctx.get("aliases", {}).items(): expanded = expand_vars(cmd, env) lines.append(f"alias {alias}='{expanded}'") return "\n".join(lines)变量展开这个环节，我吃过亏。一开始用的是纯 replace 字符串替换，忽略了一个重要场景：环境变量的值里还引用了另一个环境变量。比如 API_BASE_URL=http://localhost:8080，然后另一个变量 CALLBACK_URL=$API_BASE_URL/callback。一次性替换就搞不定了。后来我改成循环展开，一直到没有新的变化为止。
另外还有一个小细节：alias 里如果有引号，直接拼进 shell 脚本会爆炸。我最后用的是 shlex.quote 统一处理。虽然生成的脚本可读性差一点，但安全性高很多——你永远不该假设配置文件里的内容是可信的。
3.4 Shell 联动和环境变量的加载方式
这一步是整个架构里最容易翻车的地方。最朴素的方案是用户在切换上下文后手动执行 source 命令，但这样还是容易忘记。我的做法是提供一堆函数式的小片段，写在 ~/.bashrc 或 ~/.zshrc 里：
ctx() { if [[ $1 == "use" ]]; then __ctx_dir="$HOME/.context-mode" output=$(python3 "$__ctx_dir/__main__.py" use "$2") if [[ $? -eq 0 ]]; then eval "$output" fi elif [[ $1 == "exit" ]]; then output=$(python3 "$__ctx_dir/__main__.py" exit) if [[ $? -eq 0 ]]; then eval "$output" fi else python3 "$__ctx_dir/__main__.py" "$@" fi }重点在于：Python 脚本向 stdout 输出的是可以直接 eval 的 Shell 语句，而普通的提示信息全部走 stderr 或者直接丢弃。这样你在 shell 里敲 ctx use service-a 时，前台只看到一行“切换到 service-a”，但实际上环境变量、PATH、别名都已经生效了。
为了避免每次切换后环境变量残留导致下次切换时变量错乱，我还在激活脚本开头加了一段清理逻辑：先取消所有旧上下文里 set 过的变量。实现方法是 Python 在生成脚本前，先读取 state.json 里的 previous 上下文配置，对比出哪些变量是旧上下文新增的，然后输出 unset 语句。
这一步不加上，ctx use 从 A 切到 B 时，A 设置过的 API_BASE_URL 不会自动消失。这是所有 context 切换工具最容易犯的通病。
3.5 自动恢复上次上下文：进入新终端就绪
既然状态文件已经把 current 上下文持久化了，实现自动恢复就很顺理成章。我把下面的代码放进了 .bashrc：
if [[ -f "$HOME/.context-mode/auto_restore.lock" ]]; then ctx use "$(cat "$HOME/.context-mode/auto_restore.lock")" fi这里我加了个锁文件，原因是我并不希望所有终端都自动恢复上下文——有些项目你只是想临时看一眼，不想强制切进去。所以 ctx use 后面带一个 --persist 选项，只有显式启用了这个 flag 的切换才会写入 auto_restore.lock。这样既保留了自动恢复的能力，又不会让你在一个临时目录里突然被拉到别的项目上下文里，非常实用。
3.6 创建上下文：交互式引导减少手写错误
新建上下文的时候如果直接让人手写 JSON，很容易写坏。我加了一个交互式向导，逻辑是：
- 输入上下文名称。
- 输入项目根目录，支持 ~ 和相对路径，自动转换为绝对路径。
- 逐个输入环境变量，key=value 一行一个，空行结束。
- 逐个输入别名，一行一个，冒号分隔 alias:command。
- 确认后写入 JSON 文件。
ctx create service-a这个向导看着简单，但实际处理了几个容易出错的细节：
- key 只能包含字母、数字、下划线，不能以数字开头，否则 shell 里 export 会报错。
- value 如果包含特殊字符（空格、单引号、$），写入 JSON 时会原样保留，加载时才做展开。
- cwd 路径在写入时会做一次 tilde 展开，避免某些场景下 ~ 不生效的问题。
创建完成后立即打印生成后的配置预览，让用户确认。预览用 JSON 格式化输出，高亮当前上下文定义的关键字段，以免后续加载时发现错误还得再找。
4. 常见问题与排查技巧实录
4.1 四个高频问题和对应处理方式
版本切换失效。最典型的场景：用 nvm 切换 Node 版本后，执行 ctx use 却发现node -v还是老版本。原因特别简单——PATH 更新顺序问题。nvm 的 shim 写在 .bashrc 里，在 ctx use 执行之前就已经把它的 PATH 前缀放在前面了。而 context-mode 把 Node 的版本路径 prepend 到最前面时，并没有完全替代掉 nvm 的路径。解决办法是：在切换上下文时把老版本相关路径从 PATH 里先剔除，再 prepend 新的。我在 build_activation_script 里加了一个 escape_paths 参数，专门做这件事。
切换后环境变量残留。上面说过，从 A 切到 B 后 A 的变量还在，是因为没有卸载机制。实现上其实不只是在切出时清理，也可以在激活新上下文时对比旧新差异自动 unset。我推荐后一种，因为你在重启终端或手动 source 时也会触发清理，体验更稳。要注意区分哪些变量是系统本来就有、哪些是旧上下文加的，方法是在状态文件里把 current 的 env_keys 单独存一份。
Zsh 下别名无法展开。在 .zshrc 里如果用了setopt aliases但激活上下文后 alias 命令无效，大概率是因为 zsh 在非交互式模式下默认不展开别名，而 context-mode 生成的是整段 eval 代码，需要保证当前 shell 是交互式。这个没有特别完美的绕过方案，实用做法是提示用户确认当前是交互式终端，或者在激活脚本内强制开启setopt aliases。
配置文件内变量引用顺序导致空值。你在定义 env 时写了DATABASE_URL=$HOST/db，而 HOST 在下一行才定义，那么展开时就会拿到空值。解决方式是引入阶段化的两轮展开：第一轮只展开系统环境变量，第二轮将上下文自己的变量也纳入展开环境。有了两轮，变量定义顺序就不重要了。我的实现里 expand_vars 函数支持传入一个 extra_env，第一次调用时 extra_env 为空字典，第二次调用把它自身当作扩展环境代入。
4.2 调试技巧：配置写好后怎么快速确认没写错
我习惯在写完一个上下文后，用ctx show <name>来验证展开逻辑是否正常。这个子命令不仅打印原始 JSON，还打印激活脚本的预览。注意它只负责渲染，不执行，所以你可以安全地看输出，发现哪个变量变成了空字符串、哪个别名展开错了路径。
调试时最常出现的幻觉是：你看着 JSON 文件里写对了，但激活后 shell 里的值和预期不一致。这时候可以去查 ~/.context-mode/ 下的 debug.log，每执行一次激活操作，就把生成的 Shell 脚本原文写入日志。你直接翻日志看最后 eval 到 shell 里的是什么，基本一眼定位问题。
如果跟 PATH 相关，我还会执行echo $PATH配合which -a node来确认可执行文件解析顺序。因为环境变量问题往往不是单点错误，而是顺序、覆盖、残留三者叠加的结果。
4.3 兼容性和性能考虑
Python 3.8 到 3.12 我都测过，代码里没用到 3.10 之后的语法，老版本跑也没问题。Shell 侧支持 bash 和 zsh，因为生成的脚本只是 export、alias 这类最基础的命令，不依赖某个 shell 独有的特性。
关于性能：我原以为每次激活要启动 Python 解析 JSON，怎么也得 200ms 到 300ms。实测下来，一个包含二十个环境变量、十条 PATH 和十个别名的上下文，完整展开加输出脚本大概 90ms。加上 eval 的时间，用户体感小于 0.2 秒，完全不会觉得卡。如果你处理的上下文规模更夸张，比如上百个变量、几十个 PATH，也基本在 300ms 以内。
唯一的慢点是首次启动时的冷启动延迟，但 Python 解释器启动速度在现代机器上已经可以忽略。如果你频繁在终端里执行 ctx list、ctx show 这种轻量命令，介意这 50ms 的话，可以考虑用一个常驻后台服务做预热，不过我觉得对日常使用来说没必要。
4.4 格式错误防御与数据安全
我在 storage.py 里加了上下文文件格式校验器，不只检查 JSON 能不能解析，还验证必须字段是否存在、类型是否正确。比如 env 必须是一个 dict，path.prepend 必须是一个 list，name 必须和文件名一致。不符合要求的文件直接列入 warning，不参与任何加载逻辑。
数据安全方面，所有上下文配置都在用户自己主目录下，没有提权需求。一个额外的保护是，在 ctx rm 删除上下文前会打印即将删除的目标路径并要求二次确认。删除操作不直接删文件，而是移到 ~/.context-mode/trash/ 目录，保留 7 天后才物理清除。这个设计减少了因为手滑把重要上下文搞没的悲剧。
5. 经验总结与后续扩展
5.1 做完这个项目之后我理解了什么
上下文管理这件事，难点从来不是“怎么设置环境变量”，而是“怎么让你意识到当前处于哪个上下文”。单纯提供 export 和 source 的工具多如牛毛，真正稀缺的是可观察性。所谓可观察性，就是你一看到终端提示符、执行 pwd、甚至瞥一眼编辑器的状态栏，就能立刻知道此刻处于哪个上下文。
context-mode 的提示符扩展就是我做的第一个增补：它把当前上下文名称染成绿色并放在 PS1 的最前面，一旦你没在任何上下文里，就显示默认的灰色。这个改动看似微小，但对实际工作流的改变是巨大的——每次敲命令前你都会下意识扫一眼提示符，这个动作几乎消除了“在错误上下文里胡搞”的可能性。
5.2 下一步可以加的方向
我列了几个我认为最有价值的扩展，按实现成本从低到高排：
- 上下文依赖关系：支持某个上下文在激活前自动激活一个基础上下文（比如 common）。这是第二优先级。
- 动态钩子：激活上下文时自动执行 pre 和 post 脚本，比如拉取最新的 .env 文件、启动本地依赖服务、停止上一个上下文的服务。
- Git 分支联动：在上下文配置里加一个 branch 字段，切换上下文时自动检出对应分支。
- 编辑器和 IDE 联动：通过生成 .vscode/settings.json 或 .editorconfig 的方式，让不同上下文有独立的编辑器状态。
- 远程上下文支持：配置存在远端仓库，切换时从远端拉取或推送。适合多台机器同步开发环境的情况。
这里面我认为最实用的是动态钩子。我遇到的真实场景是：每次切到某个项目的上下文，都要手动启动 MySQL，切走时再手动停掉。如果能做到切换即启停，上下文就真的成为工作流的一部分了。
5.3 最后一个建议
不管你是不是决定自己写一套，我都建议在团队里建立“上下文即代码”的意识。上下文配置应该跟着项目仓库走，或者至少有一个模板文件供新成员快速导入。我踩过的另一个坑是：花了大量时间打磨自己的配置，但同事加入项目的时候还是得一切从头配起。
我在项目仓库里放了一个 contexts.example.json，作为标准化模板。新成员 clone 项目后，一条命令导入模板，再改两三个个人信息相关的字段，就能获得和团队一致的工作环境。这是上下文模式真正体现价值的地方——它不只是一个工具，更是一种团队协作的规矩。
