1. 为什么需要 context-mode多项目切换时的“上下文丢失”1.1 三个真实场景不是矫情是真被坑过不知道你有没有这种经历早上还在 A 项目里改接口联调中午运维突然说 B 项目线上有告警你切过去处理了两个小时等回到 A 项目时已经想不起自己刚才改到哪个文件、本地服务起了没、环境变量是什么。这种“我在哪我刚才干到哪了”的迷失感干开发的人几乎每天都经历。我最早开始琢磨 context-mode 这个概念就是因为这个“上下文丢失”问题太频繁了。具体来说有三个场景让我深受其害第一个场景是多项目并行。我在同一个终端里经常同时守着两三个项目的开发环境各有各的虚拟环境、端口环境变量和常用命令。切到另一个项目时光是把source .env、cd到对应目录、重新设置FLASK_ENV或者VITE_BASE_URL这一串动作做一遍就要花掉半分钟。一天切换二十次就是十分钟的纯浪费。第二个场景是中断后恢复。写代码最怕被打断因为重新进入心流需要时间。被打断之后哪怕只是去看一眼线上日志回来后也要花几分钟回忆“我改到哪了”。如果能把当前工作目录、改动中的文件、正在看的报错位置都存成一个“上下文”回来一键加载重新进入状态的时间会大幅缩短。第三个场景是终端窗口过多。习惯用多个终端窗口的人都有这种体验窗口标题写着“前端”但里面其实已经不跑前端了或者开了四五个窗口各有各的用途根本分不清谁是谁。context-mode 如果能给每个工作场景起名字、保存状态、随时列出当前有哪些上下文终端管理会清爽很多。这三个场景合起来催生了我想要的一套东西能在任意时刻给当前工作状态拍一张“快照”在需要的时候再把它恢复出来。这个模式我就叫它 context-mode。1.2 到底什么才算“上下文”拆开看信息单元在计算机体系结构里“上下文”是一个很精确的词。操作系统做进程切换时要保存和恢复的东西叫作上下文包括寄存器值、程序计数器、栈指针、内存映射表等等。它本质上就是一套让“程序继续跑”所必需的现场信息。平时我们工作的上下文丢失和操作系统进程切换其实是同一个模型工作状态被中断后得有一组信息才能把现场恢复回来。那对一个坐在终端前的开发者来说一套完整的工作上下文到底包含什么我列了一下通常包括下面这些信息单元当前工作目录最基础也最核心回答了“我在哪个项目里”。环境变量比如DATABASE_URL、API_BASE_URL、FLASK_ENV、JAVA_HOME这类项目特有的变量。最近动过的文件哪些文件是你正在修改的是回到工作状态最快的线索。当前分支或者正在执行的任务比如 git 分支、某条待验证的命令。临时记录比如一个 TODO、一个还没确定的接口返回格式、一段正在排错的报错信息。这就像一个“书签”只不过它记住的不是网页位置而是你工作现场的全部关键状态。很多人以为记住当前目录就够了其实这只是第一层。真正影响效率的是环境变量和脑子里的思路这两样东西光靠cd是恢复不回来的。我当时设计 context-mode 的第一原则就是轻量且可观测。它不应该是一个重型的、必须开守护进程的工具而应该是我随时想保存就保存、想恢复就恢复的一组命令。它要像一个便利贴而不是一个项目管理软件。2. context-mode 整体设计存储结构、命令设计、选型理由2.1 为什么不用现成的 tmux / 会话管理工具可能有人会问这些东西 tmux 不是都支持吗我确实长期用 tmux它也能保存窗口布局、开多个会话但我还是觉得缺了点东西。tmux 解决的问题是“终端会话的持久化”但它不会专门记录“这个窗口是哪个项目、用哪些环境变量、我正在改哪些文件”。tmux 的会话名只到你给的那个程度它不理解你的项目语义。而且 tmux 的嵌套切换在心理负担上也比较重我在需要快速响应时更多还是用系统自带的终端再开一个新的 Tab而不是先tmux detach再tmux attach。还有一类方向是 direnv 或者 asdf 这种自动加载工具。它们能够在进入目录时自动设置环境变量非常有用但它们解决的是“进入目录后自动配置环境”而不是“切换时主动保存工作现场”。换句话说direnv 是单向的进入就行而 context-mode 我想要的是一种显式的、带名字的、可以随时切换的“状态存储”。这就像收藏夹和浏览器自动填充的区别direnv 是自动填充表单而我想要的收藏夹把整个页面连同滚动位置都存下来。于是我自己设计了一个更切中场景的轻量工具。2.2 存储与命令一个 JSON 文件加四个命令我的设计思路非常朴素用一个 JSON 文件作为唯一存储用四个命令作为全部交互。存储放在用户的本地数据目录里按名字索引。命令设计如下ctx save name把当前工作目录、指定环境变量、最近记录保存为名为name的上下文。ctx load name恢复name对应的上下文包括cd目录、导入环境变量、打印最近文件列表。ctx list列出所有已保存的上下文。ctx delete name删除不再用的上下文。存储路径我放在$HOME/.local/share/ctx-mode/contexts.json。这个位置符合 XDG 规范也方便直接放到网盘或者 dotfiles 仓库里同步。JSON 文件长这样{ project-a: { cwd: /home/user/work/project-a, env: { PROJECT_ROOT: /home/user/work/project-a, API_BASE_URL: http://localhost:8080 }, note: 正在处理登录模块的接口联调, recent_files: [ src/api/auth.ts, src/views/Login.vue ], saved_at: 2025-06-18T10:32:00 } }为什么用 JSON我用过 YAML、TOML、SQLite 对比过最后选择 JSON 的理由很实际第一Python 和 Node 的标准库都直接支持解析和序列化零成本第二格式足够直观手工编辑也不容易错第三它是文本文件可以直接放进 Git 仓库做版本管理。SQLite 看起来更专业但对这种量级的数据是杀鸡用牛刀。每台上网的开发机最多也就几十个上下文JSON 文件的大小通常不到几十 KB读取延迟可以忽略不计。维护成本才是关键。2.3 环境变量白名单决定上下文安全边界环境变量是上下文里最微妙的部分。你不能什么变量都保存原因有两个一是机器上可能有敏感信息比如AWS_SECRET_ACCESS_KEY保存到明文 JSON 里有泄露风险二是环境变量很容易过期比如数据库密码换了你保存的还是旧值。我采用的方案是白名单机制。每个上下文只保存明确指定的白名单变量而不是全部环境变量的快照。我在ctx save命令里加了一个--env参数允许手动指定要保存的变量名比如ctx save project-a --env PROJECT_ROOT --env API_BASE_URL这样有两个好处首先是安全只有你确认过的变量才会进存储其次是透明任何时候打开 JSON 文件都能看到这个上下文依赖了哪些环境变量不会出现“我明明导入了结果没生效”这种玄学问题。在恢复的时候也要注意应该是“只导入白名单里存在的变量”而不是“把这个环境下的全部变量导进来”否则几个项目切换几次之后当前 shell 的环境变量会变成一个谁都说不清楚的混合物后续排查问题会非常痛苦。3. 从零实现一个可用的 context-modePython 版3.1 完整代码ctx 命令行工具我选择用 Python 3 实现因为标准库的json、os、subprocess已经足够不需要装第三方包。考虑到跨平台代码里只用了HOME和pwd这类通用路径在 Linux 和 macOS 上都能跑Windows 的话需要调整一下路径和 cd 处理逻辑这里不展开说。完整代码贴在下面然后我会挑几段重点解读。建议你直接保存成ctx.py放到PATH路径下配合别名使用。#!/usr/bin/env python3 ctx - 极简 context-mode 命令行工具 import argparse import json import os import subprocess import sys from datetime import datetime CTX_HOME os.path.join( os.environ.get(XDG_DATA_HOME, os.path.expanduser(~/.local/share)), ctx-mode, ) STORE_FILE os.path.join(CTX_HOME, contexts.json) ENV_WHITELIST_KEY _env_whitelist RECENT_FILES_KEY _recent_files def ensure_store() - None: os.makedirs(CTX_HOME, exist_okTrue) if not os.path.exists(STORE_FILE): with open(STORE_FILE, w, encodingutf-8) as f: json.dump({}, f, ensure_asciiFalse, indent2) def load_store() - dict: with open(STORE_FILE, r, encodingutf-8) as f: return json.load(f) def save_store(data: dict) - None: with open(STORE_FILE, w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse, indent2) def get_env_values(names: list) - dict: result {} for name in names: value os.environ.get(name) if value is not None: result[name] value return result def get_recent_files(limit: int 5) - list: 尽力从 shell 历史中提取当前目录下最近操作过的文件路径。 home os.path.expanduser(~) cwd os.getcwd() for hist_file in [.bash_history, .zsh_history]: hist_path os.path.join(home, hist_file) if not os.path.exists(hist_path): continue recent [] try: with open(hist_path, r, encodingutf-8, errorsignore) as f: lines f.readlines() except OSError: continue for line in reversed(lines): line line.strip().lstrip(:) tokens line.split() for token in tokens: if token.startswith(cwd): relative os.path.relpath(token, cwd) if not relative.startswith(..): recent.append(relative) break if len(recent) limit: break return recent return [] def cmd_save(args): ensure_store() data load_store() env_values get_env_values(args.env) recent get_recent_files(args.limit) if args.enable_history else [] note args.note if args.note else entry { cwd: os.getcwd(), env: env_values, note: note, recent_files: recent, saved_at: datetime.now().isoformat(timespecseconds), } data[args.name] entry save_store(data) print(f[ctx] 已保存上下文: {args.name} ({entry[cwd]})) def cmd_load(args): data load_store() if args.name not in data: print(f[ctx] 找不到上下文: {args.name}, filesys.stderr) sys.exit(1) entry data[args.name] cwd os.path.expanduser(entry[cwd]) if not os.path.isdir(cwd): print(f[ctx] 警告: 目录不存在 {cwd}, filesys.stderr) attempted_dir input(是否手动指定目录? (直接回车跳过, 或输入新路径): ) if attempted_dir and os.path.isdir(attempted_dir): cwd attempted_dir else: cwd None # 环境变量只导入白名单值, 以及当前上下文里已有的值。 for key, val in entry.get(env, {}).items(): os.environ[key] val # 子shell 里设置变量并进入目录, 最后进入交互 shell。 if cwd: os.chdir(cwd) banner [f- 已加载上下文: {args.name}] banner.append(f 目录: {cwd if cwd else os.getcwd()}) if entry.get(note): banner.append(f 备注: {entry[note]}) if entry.get(recent_files): banner.append( 最近文件:) banner.extend([f - {f} for f in entry[recent_files]]) print(\n.join(banner)) # 如果当前是交互 shell, 可以用 python 替换进程, 让环境变量真正生效 # 这里用 export 方式输出, 由外层函数 eval 捕获, 或者直接让用户使用以下命令 if args.shell: subprocess.run([bash, -i], checkFalse) def cmd_list(_args): data load_store() if not data: print([ctx] 当前没有保存任何上下文) return print(f共 {len(data)} 个上下文:) for name, entry in sorted(data.items()): when entry.get(saved_at, ?)[:16] cwd entry.get(cwd, ?) note entry.get(note, ) print(f {name:20} {when} {cwd} {note}) def cmd_delete(args): data load_store() if args.name in data: del data[args.name] save_store(data) print(f[ctx] 已删除上下文: {args.name}) else: print(f[ctx] 不存在: {args.name}, filesys.stderr) def main(): parser argparse.ArgumentParser(progctx, descriptioncontext-mode 轻量上下文切换工具) subparsers parser.add_subparsers(destcommand, requiredTrue) p_save subparsers.add_parser(save, help保存当前状态为上下文) p_save.add_argument(name, help上下文名称) p_save.add_argument(--env, actionappend, default[], help要保存的环境变量名, 可重复) p_save.add_argument(--note, defaultNone, help备注信息) p_save.add_argument(--limit, typeint, default5, help从历史中提取最近文件数量) p_save.add_argument(--disable-history, destenable_history, actionstore_false, help禁用从 shell 历史提取最近文件) p_save.set_defaults(funccmd_save) p_load subparsers.add_parser(load, help加载一个上下文) p_load.add_argument(name, help上下文名称) p_load.add_argument(--shell, actionstore_true, help恢复后启动 bash 交互会话) p_load.set_defaults(funccmd_load) p_list subparsers.add_parser(list, help列出所有上下文) p_list.set_defaults(funccmd_list) p_del subparsers.add_parser(delete, help删除一个上下文) p_del.add_argument(name, help上下文名称) p_del.set_defaults(funccmd_delete) args parser.parse_args() ensure_store() args.func(args) if __name__ __main__: main()3.2 关键代码细节逐行解读直接抄代码是没用的你得看懂几个关键决策否则改起来就是灾难。先看ENV_WHITELIST_KEY和RECENT_FILES_KEY这两个常量。它们其实是预留的扩展位。当前实现里环境变量白名单是写在每个上下文内部的env字段中如果你以后想做“全局共享白名单”可以用这两个 key 存到根级别。这是个小心思防止以后改结构的时候破坏已有数据。再看get_recent_files这个函数。它的作用是尝试从 shell 历史文件里捞最近操作的文件这个想法听起来简单实现起来坑不少。每个 shell 的 history 格式都不一样bash 是普通命令一行行地存zsh 带时间戳前缀和分号。我这里的解析策略是先把每行去掉左侧多余字符然后假设命令里的路径可能是绝对路径或者以cwd开头的路径用相对路径转换判断是否在当前目录下。这段代码不完美但它足够用它只做“尽力而为”捞不到就对历史文件返回空列表绝不影响保存动作。我自己试用过几个月从 zsh 历史里提取最近编辑的文件准确率大概在七八成因为总有些人习惯用相对路径操作文件有人用编辑器打开文件时写的是相对路径那就不在我这段代码的覆盖范围内了。然后是cmd_load里的环境变量恢复逻辑直接用os.environ[key] val设置。这在 Python 进程本身有效但关键是后续怎么让当前 shell 拿到这个变量。我这边实际采用的方式是配合 shell 函数使用——把ctx load的输出解析成 export 语句再eval执行。这在下文“别名与 Shell 补全”里会说。cmd_load里有个--shell参数它会加载完毕之后自动进入一个bash -i的交互子 shell。这是我在需要“干净隔离环境”时用的有时候不想污染当前窗口就在保存的上下文里换个新 shell 干活退出子 shell 后当前环境原封不动继续做之前的事。这个思路也可以配合 tmux 使用效果是“一个上下文一个窗口”。最后注意save_store里的ensure_asciiFalse我当初漏了这个参数JSON 文件里全是\u转义的中文备注里的中文全变成了乱码排查了半天才发现是这里的问题。写文件时编码统一用utf-8这是处理中文路径和备注的基本要求。3.3 顺手加上的 Shell 别名与补全Python 脚本本身已经能跑但我还要组合一套更好的日常体验。首先是在.bashrc或者.zshrc里加一个 shell 函数让ctx load不只是打印信息而是真正改变当前 shell 的目录和环境变量。直接执行 Python 脚本是做不到这种效果的因为子进程无法改变父进程的环境。我在 shell 配置里这样写ctx() { case $1 in load) local name$2 # 用 Python 输出需要 export 的语句, 然后 eval eval $(ctx.py load $name --export) ;; save|list|delete) ctx.py $ ;; *) ctx.py $ ;; esac }对应的我改了下cmd_load增加一个--export选项。这个模式下不打印普通 banner而是输出一串export VARvalue和cd /path/to/dir的 shell 语句由外层eval执行。这样环境变量才能真正落到当前 shell 上。补全在 zsh 里是重点bash 的complete写起来要单独搞函数zsh 更顺手些。我把补全挂到ctx上让它列出已保存的上下文# ~/.zshrc 里 _ctx_completion() { local -a contexts contexts( $(ctx.py list --plain 2/dev/null | cut -d -f1) ) _describe context contexts } compdef _ctx_completion ctx这里我给cmd_list加了个--plain标志只输出上下文名字一行一个方便脚本消费。这个组合装好之后我每天的使用频率变得非常高ctx save temp-note几乎成了肌肉记忆。4. 进阶让 context-mode 服务 AI 编程工作流4.1 生成“上下文记忆卡”CONTEXT.mdcontext-mode 保存的是机器可读的状态但当我要把工作现场交给 AI 编程助手时AI 需要的是人能读懂的描述。这里我发展出了一个配套习惯在每个上下文里维护一张CONTEXT.md记忆卡用来给 AI 提供背景信息。记忆卡不是让我手写的。我写了一个小脚本在ctx save后自动生成内容包含这些元素当前业务模块一句话说明正在做哪个功能。关键技术约束比如项目用的框架版本、接口规范、代码风格约定。最近改动清单用git diff --stat拉最近改动的文件列表。当前分支和最近提交用git log --oneline -5。遗留问题清单这是我主动补充的比如“登录接口的 token 刷新逻辑有竞态问题还没修”。生成这个文件的逻辑不大可以直接补充到cmd_save里。加上以后我的每个项目里都会多一个上下文名-CONTEXT.md这个文件的好处是第一时间打开哪怕过了三天也能迅速想起自己之前在想什么。给 AI 用的时候我的做法是直接把这几个文件的内容拼进对话。Visual Studio Code 的 Copilot 有项目上下文感知但很多 AI 工具其实不知道你最近改了哪个文件更不知道你脑中的方案。给它一个明确的 CONTEXT.md 会大幅提高它输出代码的相关性。4.2 把上下文交给 AI 读提示词的组织方式这里分享一个我实测非常有效的提示词组织方式。当我在 AI 对话框里粘贴上下文时一行行贴原始文件效果很差AI分不清哪些是重点。我建议按这样的模板再包装一遍背景我正在处理项目 [项目名]当前上下文是 [ctx save 的 name]。 项目技术栈[框架 语言 版本] 当前工作模块[模块名] 已知约束[比如“不能改动核心库代码”“接口遵循 REST 规范”] 最近改动的文件 - [文件1] - [文件2] 遗留问题 1. [问题1] 2. [问题2] 请基于以上信息帮我实现/分析/排查 [具体任务]。这套模板看起来平平无奇但实际用下来我发现 AI 的回答准确率有明显改善。原因很简单之前它需要自己去猜项目结构很容易跑偏现在上下文明确告诉它边界条件它的搜索空间缩小了生成内容就更收敛。在代码生成类任务里好的上下文比好的模型更决定输出质量。顺便说个反面教训有段时间我图省事直接把整个 CONTEXT.md 和十几个文件粘贴进去结果 AI 开始关注无关紧要的文件。后来我把文件列表精简到最多 5 个再加上一句“只参考列出的文件”效果立刻好转。5. 常见问题与排查技巧实录5.1 保存的目录不存在了怎么办开发过程中迁移目录很常见。项目从/home/user/work/project-a挪到/home/user/work/archive/project-a保存的上下文里的cwd就失效了。我的处理是cmd_load里加了一个回退逻辑检测到目录不存在时先打印警告然后交互式询问是否手动输入新路径。这个设计很实用因为绝大多数时候目录只是被移动了不是被删掉了手动输入一次新路径就解决问题。如果你想要更自动的方案可以在输入新路径后顺手用ctx.py save name再保存一次把新路径更新进去。不要试图在 load 时自动扫描全盘去找原始目录那个功能以后可能会加但目前手动确认已经够了。5.2 环境变量没生效或残留我遇到过两个方向的坑。第一个是忘记走 shell 函数。直接执行ctx.py load name只会打印 banner不会修改当前 shell 的环境变量。如果你发现“明明加载了上下文但echo $API_BASE_URL还是空”八成就是绕过了 shell 里的ctx()函数直接跑 Python 脚本了。这个问题我踩过至少三次后来在cmd_load里增加了一个明显的提示文字“请通过 ctx() shell 函数加载以修改当前环境”。第二个是残留问题。当你保存一个上下文时它的白名单环境变量进入os.environ但当你加载另一个上下文时上一个上下文里设置过的变量如果没有在当前白名单里就会一直保留在 shell 环境里。两个项目如果变量名冲突比如都用PORT但值不同切来切去之后就会出现“明明加载了 A 结果还是 B 的端口”。我的对策是在 shell 函数里维护一份“上一次加载的环境变量列表”加载新上下文之前先unset掉这份列表里的变量确保环境干净。代码大致是__ctx_previous_env_vars() ctx() { local cmd$1 if [[ $cmd load ]]; then for v in ${__ctx_previous_env_vars[]}; do unset $v done eval $(ctx.py load $2 --export) __ctx_previous_env_vars( $(ctx.py load $2 --exported-names 2/dev/null) ) fi }这个模式目前跑得很稳。5.3 多终端互踩并发写入与冲突context-mode 用单个 JSON 文件当存储多终端同时执行ctx save时理论上存在“读改写”的竞态条件两个终端同时读到相同的最新数据各自追加不同的上下文后写回后写的一个会覆盖前一个的修改。实际上因为我一天最多保存几十次且都是单人使用这个问题极少遇到。但如果你工作流里有多台终端同时保存可以做两件事防患于未然第一保存前重新load_store()而不是缓存第二在写操作前用fcntl.flock对存储文件加锁。我后来顺手加了个基于flock的简易版本成本约十行代码但彻底消除了这个隐患。5.4 上下文过期了清理与整理用久了上下文会越来越多。有时候你保存了一个上下文两天后打开一看根本不知道这项目是干嘛的。为了避免这种“垃圾场”效应我给自己定了两条规则保存时必须写--note。哪怕一句“登录模块联调”也逼自己在命名和备注上花十秒钟。每个周五会花两分钟跑一次ctx list把不再活跃的上下文删掉。那些“临时切过去看看”的看完就删。我也在想是不是可以给上下文加“最后使用时间”然后自动归档但就目前的使用强度来说人工 Friday 清理已经足够。工具不一定要大而全顺手才是第一位的。在整理这一块我还有一个习惯把一个长周期任务的上下文拆成多个短周期的比如design-review、fix-auth-session、polish-README。每完成一个就删一个看到 list 慢慢变短本身就是一种“今天干了不少事”的正反馈。收尾一点个人体会我在实际使用中发现context-mode 真正带来的价值不是那几十秒的目录切换时间而是它给了大脑一个“恢复位”。每次ctx save的瞬间其实是在强迫我梳理“当前这个时刻到底什么信息值得留下”。这个动作本身就很有价值它会让你从不同的任务中抽离出来先想清楚再做切换而不是看到什么就跳到什么。说回工具本身。我刻意没有引入 npm 包、没有做守护进程、没有搞交互式 TUI多个原因叠加下来这反而是这个方案最稳的地方无论过了多久只要系统里还有 Python 3这些脚本就永远能跑。与其追求某个生态的整合不如找一个几十年后还能打开文件读懂的格式。JSON 文件摆在那谁都能打开看看谁都能手工改一改这才是轻量工具真正耐用的底气。最后分享一个小技巧把ctx list的输出挂到 shell 提示符上比如在.zshrc里定义一个precmd钩子每次命令执行完自动显示当前项目名和上下文名。我当时是这样做的效果非常好因为每次看到提示符都会提醒自己“现在是哪个上下文”相当于是给 context-mode 加了一眼可见的状态提示你值得一试。