每天要同时维护好几摊活的时候，终端里的状态就是一团乱麻：这边目录切到了src/api，那边环境变量指向一套测试配置，再往上还有两个后台任务挂着上一轮的参数。我最初做context-mode这个项目，就是想让"一套工作现场"变成可以随手保存、随时恢复的东西。或者换一种更直白的说法——给终端加上一个"工作现场快照"机制，每种任务或者每个项目对应一个 context，按一个名字切过去，目录、环境变量、备注信息全部到位，不用每次手动折腾。
这篇内容会围绕这个项目完整展开：为什么要做它、核心概念怎么拆、关键代码怎么落、实际跑起来有哪些坑。适合正在给自己的工具链做"多环境切换"的开发者，也适合刚接触环境管理、想理解"上下文"到底是个什么概念的同学。我会尽量把每一步的取舍都讲清楚，而不是只丢结论。
1. 为什么需要上下文模式：从一个切岔了的现场说起
1.1 多任务并行下的真实痛点
我经历过一个很典型的下午。手上有两个项目同时在推进，A 项目在后端接口开发，B 项目在做一个独立的小工具。两个项目用的 Python 环境不同、需要加载的配置来源不同、连终端当前目录都不一样。刚开始我还记得清楚，上午十点切到 B 项目改了个配置，下午两点又切回 A 项目继续写接口。
结果有一次，我在 A 项目的目录里执行了一个 B 项目才用的初始化命令，环境变量立刻乱了，程序启动报错，我还以为是代码改了问题，排查了快一个小时才发现是环境串了。
这种问题不是靠"记性好"能解决的，人在高强度切换时就是会出这种低级失误。后来我在 IDE 里找到了"workspace"的概念——把打开的文件、窗口布局、运行配置一起记住。我在终端里也需要这么一个东西，但 IDE 的 workspace 只管编辑器内部，管不到环境变量、当前目录和命令行工具的真实状态。context-mode想补的就是这个空档：把环境相关的状态做一个可命名的快照。
1.2 上下文模式的本质：给工作现场拍快照
先说清楚我这里定义的"上下文模式"。一个 context 至少包含三部分：当前工作目录、一组关键环境变量、一段可选的说明备注。保存这个 context 的过程就是给当前现场拍快照，恢复 context 的过程就是把快照重新铺回去。
很多人会问：这不就是写几个脚本的事情吗？比如手动写export XX=xxx && cd /path。确实，单次切换可以这么干，但 context-mode 的核心差异在于：
- 它是有名字的状态集合，不是一次性脚本。
- 它可以随时列出所有快照，查看当时在做什么、用了什么配置。
- 它支持"保存时抓取当前真实状态"，而不是在脚本里硬编码变量值。
- 它把恢复逻辑收敛成一条命令，切换成本极低，低到你愿意频繁切换而不是硬扛。
本质上，context-mode 是"环境状态的版本管理"，它和 git 管代码、docker 管依赖一样，是在降低切换和恢复时的认知负担。
1.3 谁适合用、用在什么场景
我把适用对象分成三类。
第一类是后端和运维方向的开发者，经常要在多个项目的目录、环境变量、配置文件之间切换。第二类是写数据处理脚本的人，不同数据处理任务要加载不同的数据源配置、模型路径、日志级别。第三类是喜欢在命令行里做笔记、做实验记录的人，把一组终端状态和一段说明挂在一起，回头再看时能快速知道这个 context 是干什么的。
不太适合的场景也有，比如一个纯静态前端项目，环境变量极少、目录切换没啥成本，那用 alias 就够了，没必要引入 context-mode。这类工具的定位是"切换成本高且状态容易出错"的场景，而不是把所有命令都包一层。
2. 整体设计方案与核心概念
2.1 上下文的结构：状态由什么组成
动手之前最重要的是把"上下文"这个抽象词落到具体字段上。我第一版定义的 Context 结构很简单：
@dataclass class Context: name: str # 模式名，比如 project-a-dev cwd: str # 切换后要进入的目录 env: dict # 关键环境变量集合 notes: str # 备注，这个模式是干嘛的 created_at: str # 创建/更新时间第一眼看上去够用了对吧？实际跑了两周我才发现，env这个字段特别容易踩坑。如果保存时直接把整个os.environ全量快照，那么恢复的时候就会面临一个很尴尬的问题：这台机器上后来新设置的公共变量，会不会被旧快照里的残留值污染？
所以结构本身没问题，问题出在env的采集粒度上。第二版我加了一个关键约束：只保存指定前缀的变量集合。比如MYAPP_*、DB_*，或者明确点名要保存的变量名。这样做的好处是快照体积小、恢复时只动该动的变量，不会把整个环境搞乱。
2.2 模式与上下文的映射关系
另外一个概念是"模式（mode）"和"上下文（context）"之间的关系。一开始我以为一个模式对应唯一一个上下文，后来发现自己经常需要在同一个项目里切换不同环境，比如"本地开发模式"和"联调模式"。
所以最终的设计是：一个模式名对应一个上下文快照，但模式名不能重复；不同模式之间可以共享一些目录或者变量，但快照本身是独立保存的。也就是说，"模式"就是上下文的唯一标识，不存在一对多的关系，否则切换时就不知道该恢复哪一个了。
这个设计决策挺重要。如果允许一个模式挂多个上下文，恢复逻辑就要加一层选择器，命令复杂度会明显上升。而实际使用中，我从没遇到"一个模式下需要多套环境"的强需求——真有这种需求，直接拆成两个模式更清晰。
2.3 切换机制：保存、加载、恢复三步走
整个切换机制我拆成了三个操作：
- 保存（save）：读取当前工作目录、采集指定前缀的环境变量、配上备注，写入存储。
- 加载（load）：按模式名读出快照，不立即改变当前状态，只是返回数据。
- 恢复（restore）：基于快照内容，把目录切过去、把环境变量写进当前进程，如果需要还可以执行一条附加命令。
为什么要把"加载"和"恢复"分开？因为有些使用场景只是"看看这个模式当时用的什么配置"，并不想真的切过去。比如你在排查问题，只需要查看某个模式下的环境变量长什么样，这时候恢复动作反而是副作用。这个拆分让工具更贴近实际使用习惯。
保存时我还做了个约束：环境变量不能全量保存。上文提到只采集前缀，还要在保存前把值里的敏感信息做一个简单过滤。虽然这是个本地工具，但如果有密码类的环境变量混在快照里，快照文件一旦被同步到别的地方就是隐患。
3. 核心实现：数据结构、存储与切换器
3.1 数据结构定义：最简但要够用
我把上面的设计落成了 Python 代码。这里用 dataclass 是因为它自带序列化基础，方便转成 JSON。定义如下：
from dataclasses import asdict, dataclass, field from datetime import datetime from pathlib import Path from typing import Dict, Optional @dataclass class Context: name: str cwd: str env: Dict[str, str] notes: str = "" created_at: str = field( default_factory=lambda: datetime.now().isoformat(timespec="seconds") ) def to_dict(self) -> dict: return asdict(self) @classmethod def from_dict(cls, data: dict) -> "Context": return cls(**data)我在字段顺序上做了点讲究：name和cwd在前，因为它们是快照里最常用的检索字段；env放中间；notes和created_at带默认值靠后。这样在手工编辑 JSON 文件时，就算少写一两个字段也能正常解析。
created_at用 ISO 格式字符串，而不是时间戳数字。原因很实际：直接看文件就能读出来是什么时候保存的，不需要再转换。虽然字符串比数字占几个字节，但对一个本地快照文件来说完全无所谓。
3.2 存储层选型：JSON 文件为什么够用
存储层可选方案很多：SQLite、YAML 文件、JSON 文件、甚至 pickle。我最后选了 JSON 文件，路径放在~/.ctx/contexts.json。
理由有几点。
第一，数据量极小。一个 context 通常就几百字节，一百个 mode 也才几十 KB，数据库对这种量级没有任何优势。第二，JSON 可读可改。就算不用这个工具的命令行，直接打开文件也能看到内容，甚至可以手工调整某个模式的目录路径。第三，它是纯文本，方便放进版本控制或者备份。第四，Python 标准库直接支持，不需要引入额外依赖。
对比一下我为什么不用 YAML：YAML 虽然可读性也强，但解析时要装依赖，而且缩进稍微不注意就会报错，对一个本地工具来说容错性不够好。SQLite 更适合多用户并发读写的场景，这里完全没这个需求。
存储实现我写了下面这段，核心是"读一次、改一次、写一次"：
import json import re from pathlib import Path from typing import Dict, List class ContextStore: def __init__(self, data_file: Path): self.data_file = data_file self.contexts: Dict[str, Context] = {} self._load() def _load(self) -> None: if not self.data_file.exists(): return raw = json.loads(self.data_file.read_text(encoding="utf-8")) for name, item in raw.items(): self.contexts[name] = Context.from_dict(item) def _flush(self) -> None: self.data_file.parent.mkdir(parents=True, exist_ok=True) temp_file = self.data_file.with_suffix(".tmp") payload = {name: ctx.to_dict() for name, ctx in self.contexts.items()} temp_file.write_text( json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8", ) temp_file.replace(self.data_file) def save(self, context: Context) -> None: name = context.name if re.match(r"^[a-zA-Z0-9_-]+$", name) is None: raise ValueError(f"非法模式名: {name}") self.contexts[name] = context self._flush() def get(self, name: str) -> Optional[Context]: return self.contexts.get(name) def list_all(self) -> List[Context]: return sorted( self.contexts.values(), key=lambda c: c.created_at, reverse=True, ) def remove(self, name: str) -> None: self.contexts.pop(name, None) self._flush()这里我特意用了一个临时文件再replace的写法，而不是直接写原文件。原因很简单：如果写入过程中突然断电或者进程被杀，原文件不会变成半个 JSON，下次启动还能正常读取。这个小细节在平时没感觉，真遇到目录里残留.tmp文件时会庆幸自己当时这么做了。
3.3 切换器实现：保存与恢复的逻辑
接下来是核心的切换器。它要做的事情是：抓取当前环境状态、构造 Context 对象、保存；以及读取 Context、修改当前进程环境、切换目录。
import os import subprocess from pathlib import Path from typing import Dict, List class ContextSwitcher: def __init__(self, store: ContextStore): self.store = store def capture_env(self, prefixes: List[str], exact_names: List[str]) -> Dict[str, str]: captured = {} for key, value in os.environ.items(): if any(key.startswith(prefix) for prefix in prefixes): captured[key] = value for name in exact_names: if name in os.environ: captured[name] = os.environ[name] return captured def save_current( self, name: str, cwd: str, prefixes: List[str], exact_names: List[str], notes: str = "", ) -> Context: env = self.capture_env(prefixes, exact_names) context = Context(name=name, cwd=str(cwd), env=env, notes=notes) self.store.save(context) return context def restore(self, name: str, dry_run: bool = False) -> Context: context = self.store.get(name) if context is None: raise KeyError(f"模式 {name} 不存在") if dry_run: return context # 恢复目录 target_dir = Path(context.cwd).expanduser() if not target_dir.exists(): raise FileNotFoundError(f"模式 {name} 的目录不存在: {target_dir}") os.chdir(target_dir) # 恢复环境变量：先清理旧的前缀变量，再写入新值 self._reset_prefix_env(context.env) os.environ.update(context.env) return context def _reset_prefix_env(self, target_env: Dict[str, str]) -> None: # 找出当前环境里以 target_env 的 key 开头或者同名的变量，先删掉 target_keys = set(target_env.keys()) keys_to_remove = [] for key in os.environ: if key in target_keys: keys_to_remove.append(key) else: for tkey in target_keys: if key.startswith(tkey.split("_", 1)[0] + "_"): keys_to_remove.append(key) break for key in set(keys_to_remove): os.environ.pop(key, None)_reset_prefix_env的逻辑是一个重点，也是我踩过坑之后补上的。如果只往环境变量里塞新的值，而不清理旧值，会出现一种很隐蔽的问题：上一次模式里有MYAPP_ENV=prod，当前模式里只设置了MYAPP_DEBUG=1，没有设置MYAPP_ENV，那切换后MYAPP_ENV还会残留为prod。程序行为就会很诡异。所以恢复之前，要把和目标变量同前缀的所有变量都清掉，再做增量更新。
3.4 命令行接口：让模式可被直接调用
代码逻辑写完之后，命令行接口是让它真正好用的关键。我用argparse写了基础命令集：save、load、list、rm。每个命令的交互方式都尽量简短。
import argparse def build_parser(): parser = argparse.ArgumentParser( prog="ctx", description="context-mode: 终端的上下文模式切换工具", ) sub = parser.add_subparsers(dest="command", required=True) save_parser = sub.add_parser("save", help="保存当前状态为新模式") save_parser.add_argument("name", help="模式名，如 project-a-dev") save_parser.add_argument("--prefix", action="append", default=[], help="要抓取的环境变量前缀，可多次传入") save_parser.add_argument("--var", action="append", default=[], help="要抓取的具体环境变量名") save_parser.add_argument("--notes", default="", help="备注说明") save_parser.add_argument("--cwd", default=None, help="保存时使用的目录，默认是当前目录") load_parser = sub.add_parser("load", help="恢复某个模式") load_parser.add_argument("name", help="模式名") load_parser.add_argument("--dry-run", action="store_true", help="只打印信息，不真正切换") sub.add_parser("list", help="列出全部模式") sub.add_parser("rm", help="删除指定模式").add_argument("name") return parser命令行接口要短，这是我一直坚持的原则。ctx save project-a --prefix MYAPP_和ctx load project-a两条命令已经能覆盖八成使用场景。参数多了之后，命令本身又变成了一种记忆负担，这和工具要解决的方向是相反的。
4. 实操演练：从零搭建一个可用的 context-mode
4.1 初始化项目结构与依赖
整个项目我按两个文件组织，不搞复杂工程结构：
ctx/ ctx.py # 命令行入口 context_core.py # 数据结构、存储、切换器依赖只有 Python 3.8+ 标准库，不用pip install任何东西。这样在别的机器上直接拷贝过去就能用，也方便后续做 shell 函数包装。
初始化动作就一个：确认~/.ctx/目录不存在时创建它。这个目录里我会再放一个README.md，用来记录每个模式对应的业务含义。之所以不把说明塞进代码，是因为这类工具的文档就应该放在用户目录下，随工具一起走。
4.2 完整代码与关键说明
把上面的类组合起来，加上主函数：
import sys from pathlib import Path def main(argv: list[str]) -> int: parser = build_parser() args = parser.parse_args(argv) store = ContextStore(Path.home() / ".ctx" / "contexts.json") switcher = ContextSwitcher(store) if args.command == "save": cwd = args.cwd or str(Path.cwd()) switcher.save_current( name=args.name, cwd=cwd, prefixes=args.prefix, exact_names=args.var, notes=args.notes, ) print(f"已保存模式: {args.name}") return 0 if args.command == "load": try: context = switcher.restore(args.name, dry_run=args.dry_run) except (KeyError, FileNotFoundError) as exc: print(f"加载失败: {exc}", file=sys.stderr) return 1 if args.dry_run: print(f"模式 {context.name}: cwd={context.cwd}") for k, v in context.env.items(): print(f" {k}={v}") else: print(f"已切换到模式: {context.name} (cwd={context.cwd})") return 0 if args.command == "list": for context in store.list_all(): marker = " " print(f"{marker} {context.name:<24} {context.cwd}") if context.notes: print(f" notes: {context.notes}") return 0 if args.command == "rm": store.remove(args.name) print(f"已删除模式: {args.name}") return 0 return 0 if __name__ == "__main__": raise SystemExit(main(sys.argv[1:]))这段代码我实际跑起来很稳，但有一个使用前提：切换目录这个动作只在当前进程内有效。你在终端里执行python ctx.py load project-a，这个 Python 进程会切换自己的目录，但退出后终端还是在原来的目录。所以实际使用时，需要用一个 shell 函数来包装，让cd生效在外层终端进程里。
4.3 shell 包装：让切换真正生效
这是 context-mode 能真正落地到日常终端使用的一个关键细节。我在.bashrc里加了下面这段：
ctx() { if [[ "$1" == "load" ]]; then python3 "$HOME/ctx/ctx.py" load "$2" eval "$(python3 "$HOME/ctx/ctx.py" load "$2" --emit-shell)" else python3 "$HOME/ctx/ctx.py" "$@" fi }原理是：先从存储里读出目标 context 的目录和环境变量，然后用 shell 的cd和export在当前 shell 里执行。因为 shell 函数运行在当前进程里，所以cd和export都能保留下来。--emit-shell是我额外加的一个输出分支，打印出可直接被eval的 shell 语句：
if args.command == "load" and args.emit_shell: print(f"cd {context.cwd}") for k, v in context.env.items(): print(f"export {k}={shell_quote(v)}") return 0这里要注意shell_quote，环境变量值里如果有空格或者特殊字符，不加引号直接 export 会裂开。我用shlex.quote来处理。
这个设计我当时犹豫过，因为让工具直接输出 shell 语法看起来不够"优雅"。但实际用下来发现，这是最直接、最不容易出问题的方式。子进程改变不了父进程的环境是操作系统层面的限制，与其绕弯子，不如让 shell 来做它最擅长的事。
4.4 真实演练：三个模式来回切换
假设我现在有 A、B 两个项目，再加上一个"日常杂事"模式。
# 项目 A，保存当前目录，抓取 MYAPP_A 开头的变量 cd ~/work/project-a export MYAPP_A_ENV=dev ctx save project-a --prefix MYAPP_A_ --notes "A 项目，联调环境" # 项目 B cd ~/work/project-b export MYAPP_B_ENV=staging ctx save project-b --prefix MYAPP_B_ --notes "B 项目，staging 联调" # 从 A 切到 B ctx load project-b pwd # 立刻变成 ~/work/project-b echo $MYAPP_B_ENV # staging echo $MYAPP_A_ENV # 应该是空的，因为恢复时清掉了上面最后一行就是_reset_prefix_env在工作。第一次跑的时候我没有这个清理逻辑，结果切到 B 之后MYAPP_A_ENV还挂在环境里，导致某一个构建脚本误判了当前环境。后来我把它补上，才真正做到"干净切换"。
5. 常见问题与排查技巧实录
5.1 上下文被意外覆盖：先检查同名模式再保存
我在使用中踩过最疼的一个坑：手一快，ctx save project-a把原来的project-a现场覆盖了。当时那个旧现场里有我对另一个问题做的临时环境变量调整，一覆盖全没了。
后面我给 save 命令加了个行为：如果模式已存在，默认询问确认，或者强制覆盖时加--force。这个改动虽小，但救回来至少两次重要现场。
if args.command == "save": existing = store.get(args.name) if existing is not None and not args.force: print(f"警告: 模式 {args.name} 已存在，使用 --force 覆盖", file=sys.stderr) return 1排查建议：如果遇到"我的上下文怎么变了"的问题，先看~/.ctx/contexts.json的修改时间，再对照created_at字段。因为 save 会更新created_at，只要不是刚才保存过，就说明有别的操作动过它。
5.2 切换后环境变量残留：恢复前必须做清理
这个我在前面提过，但值得单独列出来。现象是：从模式 A 切到模式 B 之后，程序能读到模式 A 的某个变量。排查方法也很简单：
env | grep MYAPP如果发现问题，就用我代码里的_reset_prefix_env逻辑做清理。但这里有个更精细的点：同前缀变量清理不能太激进。比如你同时保留MYAPP_URL和MYCOMMON_DEBUG，如果只用前缀MYAPP_保存，清理时不能把MYCOMMON_DEBUG也删了。所以要判断"哪个前缀属于当前模式"，我用的策略是取第一个下划线之前的部分作为命名空间，只清理同命名空间的变量。这个策略在变量命名规范统一时很有效，但如果有人用完全不同的前缀命名，需要单独做映射。
5.3 存储文件越来越脏：写入前的字段清理
用了一两个月之后，contexts.json里出现了一些"脏数据"：有的模式名包含空格（手滑输入的），有的cwd指向已经删掉的目录，还有的 env 里保存了完整路径导致快照文件很大。
我做了三件事来解决：
- 模式名写入前统一做正则校验，只允许字母、数字、下划线、中划线。空格或者斜杠直接拒绝。
load时如果目标目录不存在，给出明确报错而不是静默切换。- 保存 env 之前，过滤掉所有值为空字符串的变量，以及以
_开头的内部变量。
此外我还加了一个ctx prune命令，扫描所有模式的cwd，如果目录不存在就标记出来，可一键删除。这个命令虽然不是核心功能，但大大减少了长期使用后的"垃圾积累"，让文件保持干净。
5.4 几个我在这个项目里沉淀下来的设计原则
第一，上下文里保存的状态越少越好。很多人一旦开始做这类工具，恨不得把系统信息、进程列表、历史命令全部存进去。但真正恢复的时候，一条条执行反而很容易出错。我最后的共识只保留"目录 + 环境变量 + 备注"，这是恢复可靠性最高的组合。
第二，工具要提供"只读查看"能力。--dry-run加上之后，我非常频繁地用它来确认模式里到底存了什么，而不是直接 load。这样做的好处是不会打乱当前现场，对敏感场景尤其重要。
第三，给每个模式写一句 notes。哪怕只有一个词，比如"联调""压测""周末实验"，事后翻列表时能快速定位。我见过不少开发者，代码写得很细，但备注完全空白，一个星期后自己都忘了这个模式是干嘛的。
6. 这个工具后续还能往哪里延伸
做到上面这一步，context-mode 已经是一个完整的可用工具了。但我实际使用中一直有几个持续迭代的方向，写出来给大家参考。
一个是给 env 恢复增加"差异预览"。在 load 之前，先对比目标快照和当前环境，把将要变化的变量列出来，像 git diff 那样展示。这个功能对排查特别有用，尤其是在现场环境比较复杂的时候。
另一个是支持"模式继承"。比如project-a和project-a-staging共享大部分配置，只有一两个变量不同。目前的实现是完整复制一份，但后续可以引入 base 模式，让子模式只记录差异。这样能减少重复维护成本。
最后一个是 hooks 机制。有些模式恢复之后需要顺带执行一条命令，比如启动一个本地服务、清理某个临时目录。如果能在 context 里增加on_load字段，恢复时自动执行，这工具就从一个"状态快照工具"变成了一个"环境编排工具"。
我个人实际体会是：context-mode 这类工具的价值不在于技术复杂度，而在于把"状态混乱"这个隐性成本显性化了。我之前每天光是确认自己当前在哪个环境、哪个目录，就要花掉不少注意力，装了这东西之后再也没为这种破事发过愁。如果你们也在被多项目环境切换折磨，可以照着上面的思路搭一个最小版本，先跑一周看看感受。代码量不大，核心逻辑也就一两百行，但带来的清爽感挺明显的。
