你有没有过这种经历：上午还埋在一个项目的某个模块里，下午被线上告警拽到另一个项目，处理完再切回来，对着终端愣了几秒——我刚才在看哪个文件？这个分支推到远端没有？环境变量是不是被我改乱了？我太经常碰到这种情况了，后来干脆把“上下文恢复”这件事交给了工具。这个工具我命名为context-mode，核心命令只有一个cm，做的事情也很朴素：把你在哪个目录、什么分支、什么环境、甚至在哪个tmux窗口，打包成一枚快照，想回来的时候一条命令还原现场。这篇文章没有复杂的原理，就是我实际使用这套工作流小半年的配置、经验和踩坑记录，适合跟我一样经常多项目并行的同学参考。

1. 不是又一个目录跳转工具，而是“现场还原机”

1.1 多项目并行时代，“记性不好”不是你的错

我同时维护的项目类型跨度很大，一个Java后端、一个前端管理后台、一个Python数据脚本。以前切换项目靠的是“记得”——切过去之前脑子里默念一句“我在fix/order-timeout分支上，REDIS用的是本地6379的5号库，dev server还没起”，然后切去另一个仓库改bug。这个流程听起来很熟练，但只要中间被一件急事打断，大概率回来会对着终端发呆。

认知科学里有个大致估算：人被打断后，重新进入专注状态平均需要好几分钟，而且重新加载出来的信息经常是残缺的。开发场景更明显——环境变量改到哪一步了、某段代码改了一半、git stash里存了几个临时修改，这些细节靠人脑根本记不住。我一开始还以为是自己记性变差了，后来才意识到这是多任务并行的必然损耗。

这个感觉很像在厨房里同时炖着汤、炒着菜、热着饭——每个锅都有自己的火候和调味进度。突然接个电话回来，你很可能忘了炖汤里到底放没放盐。代码上下文丢失的结果更严重，不仅浪费时间，还可能带着错误记忆去改代码，引入新的bug。

所以我不太认同“靠自律记住上下文”这种说法。人的工作记忆容量就那么大，与其硬扛，不如把“现场状态”交给工具存好。我当时就在想，要是终端能像IDE一样记住你刚才在哪个工程、什么分支、什么环境，切项目会不会就没那么痛了。基于这个想法，我把context-mode这个思路做成了小工具，核心命令就一个cm。

1.2 历史命令不够，要的是“状态快照”

很多人的第一反应是：用shell历史不就行了？往上翻几个命令，看看之前cd到哪个目录、export了什么变量、切了哪个分支，不就知道了吗？我一开始也这么干，但很快就发现了几个硬伤。

历史记录只是“点状信息”。你看到的是一串命令序列，而不是某个时刻的完整工作现场，两者信息量差着量级。比如环境变量里的某个临时值、tmux窗口布局、还有未提交的git改动，这些不会出现在历史里，但恰恰是恢复现场最需要的东西。

历史记录不分上下文。多个项目混着操作，历史是一锅粥，翻半天也不知道哪条export是在哪个项目里执行的。而且历史很容易被命令噪声淹没，你只是跑了一个ls，也可能占掉好几行，找关键信息全靠眼力。

context-mode存的是“状态快照”，不是命令序列。快照包括当前路径、白名单里的环境变量、Git分支和工作区状态、tmux会话信息，外加一句自定义备注。恢复快照的本质，不是把之前敲过的命令重新执行一遍，而是把整套环境变量和位置关系还原到保存的那一刻。

1.3 三条设计原则：轻量、透明、可组合

工具设计我给自己定了三条规矩，后来的所有功能都围绕这三条来。

第一是轻量。不搞常驻守护进程，不用数据库，就是Shell函数加JSON文件。之所以这样，是因为日常shell环境里任何“重量级服务”都可能变成新负担——忘记启动、端口占用、重启后丢状态，反而得不偿失。context-mode不存在“服务没起来”的问题，因为它根本没有服务。

第二是透明。存了什么、恢复什么，必须能直接看到。cm list查看所有快照，cm show查看单个快照的完整内容。这一点非常重要，状态管理工具最怕黑盒，你不知道它悄悄存了什么，出了问题都没法排查。

第三是可组合。不绑定某个终端复用器或IDE。你在tmux里能用、在zsh里能用、在VS Code的集成终端里也能用。它提供的是积木，具体怎么搭由你自己决定。我后来把context-mode接进tmux和zsh，但如果你只用裸终端，它照样跑得起来。

2. 核心概念拆解：快照、栈与模式

2.1 一个上下文快照到底存了什么

先看一份真实的快照文件，存的是我在mall-api项目里排查订单超时问题的现场：

{ "name": "mall-order-timeout", "created_at": "2024-06-15T10:23:11+08:00", "cwd": "/home/user/work/mall-api", "git": { "branch": "fix/order-timeout", "dirty": true, "stash_count": 2 }, "env": { "NODE_ENV": "development", "REDIS_URL": "redis://localhost:6379/5", "LOG_LEVEL": "debug" }, "tmux": { "session": "mall-api", "layout": "d2e3e1", "window_active": 1 }, "note": "订单超时问题排查中，resolver里的超时时间先改成30s验证" }

逐个字段说。

cwd是当前工作目录，恢复时直接cd过去。git字段记录分支名、工作区是否有未提交改动（dirty）、git stash里有几条记录。这几个字段作用很大——恢复现场时你能立刻知道工作区不是干净的，别一上来就以为可以随便切分支。

env是环境变量快照，但它不是全量导出的。全量保存会有大问题：PATH这类变量依赖当前shell环境，直接覆盖会把shell搅乱；PS1里可能带着转义序列；临时变量如SHLVL恢复后根本对不上。所以context-mode用了“白名单+前缀匹配”的策略，只有你关心的、自定义的变量才会被抓进快照。

tmux记录会话名、窗口布局和当前活动窗口。恢复时就靠这些信息重新接入原来的tmux会话。note是一段自定义备注，别小看它，很多时候你保存快照一周后再回来看，文件名已经不能让你想起当时的意图了，备注才是提醒自己的关键。

2.2 为什么用栈而不是目录书签

早先版本里我用过类似“目录书签”的模型：mark一下当前位置，回头直接jump回来。这个模型确实简单，但实际用起来很快暴露问题——它只能表达“我收藏了这个地方”，不能表达“我临时离开，但待会儿必须回来”这种语义。

后来我把切换模型改成了栈，每次切走就push一个上下文，处理完再pop回来。这样和浏览器后退按钮的逻辑一样，保留了一条完整的“回退链”。关键是栈支持多级嵌套：你可以从项目A切到项目B，再从项目B切到项目C，然后在C里pop一次回到B，再pop一次回到A，沿途所有状态都不会丢。

举个实际场景。上午我在mall-api的fix/order-timeout分支上写代码，下午支付网关告警，我cm push pay-gateway-hotfix，切去处理告警。处理完cm pop，整个环境就回到了mall-api的现场。如果支付网关处理过程中又插进来一个任务，那就再push一层，栈会帮你按顺序回退。

为什么不用“离开时记住，回来时恢复”这种单向逻辑？因为真实工作的打断往往是嵌套的，你永远不知道处理告警的过程中还会不会再被别的事情拽走。栈结构天然支持这种任意深度的嵌套，比单一书签要灵活得多。

2.3 模式和上下文是两个东西

刚开始用的时候我也把模式和上下文混在一起，后来踩了好几次坑才把它们彻底分开。

上下文是“此刻的现场”——你在哪个目录、环境变量是什么、git分支在哪、正在做什么。它是动态的，每次保存都不同。模式是“可复用的模板”——针对某类任务预设好环境变量和启动命令，比如开发模式、调试模式、发布模式。它是静态的，定义一次就能反复用。

打个比方，上下文像是你办公桌上摊开的图纸和量具，模式像是工具箱里分好类的螺丝刀套装。你从工具架上取一套“调试螺丝刀”（激活模式），再在桌上摊开某张图纸（恢复上下文），两者互不干扰，又能组合使用。

实际使用中，我会先激活开发模式，再恢复某个项目的上下文。模式负责把NODE_ENV设成development、LOG_LEVEL设成debug、执行一条初始化命令；上下文负责把工作目录切到对应的仓库、把分支切回去、把tmux会话接回来。分工明确，谁都不抢谁的活。

2.4 配置文件的骨架长什么样

配置文件放在~/.config/context-mode/config.json，我常用的配置大概是这样的：

{ "storage": "~/.local/share/context-mode", "env_whitelist": ["NODE_ENV", "DATABASE_URL", "APP_*"], "git_integration": true, "tmux_integration": true, "modes": { "dev": { "description": "日常开发模式", "env": { "NODE_ENV": "development", "LOG_LEVEL": "debug" }, "init_commands": ["npm run dev"] }, "debug": { "description": "调试模式", "env": { "NODE_ENV": "test", "DEBUG": "app:*" }, "init_commands": ["npm run test:watch"] } } }

env_whitelist是关键，支持精确变量名和通配符前缀两种写法，比如APP_*会匹配所有以APP_开头的变量。这里一定要认真规划，宁可少存也不要乱存，存了太多无关变量，恢复时会互相干扰。

init_commands是一个命令数组，激活模式时按顺序执行。设计成数组是因为有些项目启动前确实需要多条准备命令，比如先切换Node版本再启动dev server。注意我故意没在模式里放cwd字段——恢复目录是上下文该管的事情，模式越纯粹越好。

3. 从零配置一套context-mode工作流

3.1 安装与初始化

安装过程不复杂，我习惯把工具放在~/.context-mode目录下面：

git clone https://github.com/yourname/context-mode.git ~/.context-mode cd ~/.context-mode && ./install.sh cm init

cm init会自动检测你当前用的shell，然后在对应的rc文件里追加一行加载配置。建议安装后手动确认一下：

tail -n 5 ~/.zshrc

如果你用zsh，有个细节需要注意：加载行建议加在rc文件末尾，不要加在最前面，避免和oh-my-zsh这类框架的初始化互相覆盖。bash用户的坑少一些，但同样建议确认一下没有和已有alias冲突。

初始化完成之后可以先跑一下cm doctor，它会检查配置格式、存储目录权限和shell hook是否正确加载。这一步能省掉后面很多排查时间。

3.2 保存你的第一个上下文

用一个实际场景来演示。假设我在mall-api项目里排查订单超时问题，当前目录在~/work/mall-api，分支是fix/order-timeout，我需要两个关键环境变量：

cd ~/work/mall-api export REDIS_URL=redis://localhost:6379/5 export ORDER_TIMEOUT_SECONDS=30 git checkout fix/order-timeout cm save mall-order-timeout

保存之后用cm list确认：

$ cm list NAME CREATED BRANCH NOTES mall-order-timeout 2024-06-15 10:23 fix/order-timeout 订单超时问题排查中

保存操作会把当前目录、白名单内环境变量、git分支、tmux状态一并写入快照。这里我建议在保存之前顺手看一眼git status，确认工作区状态，因为快照里会记录dirty标记，如果你之后恢复，一眼就能知道当时有没有未提交的修改。

给快照命名是我比较讲究的事情。一开始我用test1、final这种名字，过几天根本不知道对应什么。现在统一用“项目名-任务名”的格式，比如pay-fix-quota、order-debug-timeout，列表里扫一眼就能定位。配合note字段写清当时做到哪一步，恢复的时候信息量足够完整。

3.3 编写可复用的模式

现在看看模式怎么配。还是以mall-api为例，这个项目平时有两种启动方式，普通开发模式和数据看模式。我在配置文件里写：

{ "modes": { "dev": { "description": "日常开发模式", "env": { "NODE_ENV": "development", "LOG_LEVEL": "debug", "API_BASE": "http://localhost:3000" }, "init_commands": ["nvm use 18", "npm run dev"] }, "debug": { "description": "调试模式", "env": { "NODE_ENV": "test", "DEBUG": "app:*" }, "init_commands": ["nvm use 18", "npm run test:watch"] } } }

激活模式用的是cm mode dev，它会做两件事：把env里的变量设置到当前shell，再按顺序执行init_commands里的命令。

我故意没在模式里写cwd，因为模式不关心你在哪个项目里。同一个dev模式，在mall-api项目里能用，在pay-gateway项目里也能用。模式是通用的，上下文才是具体的，这个边界划清楚了，使用起来非常顺手。

如果你项目里需要“进入某个目录后激活某个模式”这种绑定关系，不建议写死在模式里，而是用alias或zsh函数包一层。比如我常这么干：

alias mall-dev='cd ~/work/mall-api && cm mode dev && cm up mall-order-timeout'

这样一个alias就把目录切换、模式激活、上下文恢复三件事都做完了。

3.4 让tmux一起工作

tmux和context-mode是绝配。我通常为每个项目开一个tmux会话，窗口1跑编辑器，窗口2跑dev server，窗口3做git操作区。保存上下文时，tmux会话名、窗口布局、当前活动窗口都会被记录下来。

恢复上下文时，context-mode会做一次“智能接入”：如果目标tmux会话已经存在，就附加过去，不重复创建；如果不存在，就按照配置创建一个新的会话再附加。这样你恢复现场后，看到的还是之前那套窗口布局，而不是一个光秃秃的shell。

这里有个非常容易踩的坑：tmux会话名不能乱起。我之前给两个项目都起过叫dev的会话，保存上下文时记录的都是dev，恢复的时候tea直接附加到了错误的会话上。排查了十分钟才反应过来是会话名冲突。

我的经验是会话名统一用项目名为基础，比如mall-api、pay-gateway，再加后缀区分用途。mall-api-dev和pay-gateway-dev一眼就能看出来属于哪个项目，又不会重名。

3.5 一次完整的切换动线

用一条完整的时间线把上面的命令串起来，你就能看到这套工作流日常是怎么跑的。

上午10点，我在mall-api的fix/order-timeout分支上排查订单超时，环境变量已经配好，tmux会话里dev server正在跑：

cm save mall-order-timeout

11点20分，线上支付网关告警，超时率飙升。我执行：

cm push pay-gateway-hotfix

cm push做了两件事：先把当前现场保存到临时槽位，再清空环境变量和目录状态，让你可以干净地切换。这就是我前面说的“push前自动快照”，就算忘了手动save，回退链也不会断。

11点21分，我切到pay-gateway仓库，专注处理告警相关的问题。12点10分修复完成，准备回到原来的订单模块：

cm pop

执行完这一条，工作目录回到~/work/mall-api，分支恢复到fix/order-timeout，之前设置的环境变量全部还原，tmux会话也自动附加回来了。整个过程不用我回忆任何细节，脑子里的“上下文加载”成本几乎为零。

这套动线用了一个多月之后，我再也没在终端前发过呆。切项目虽然说是“切”，但实际体验更像“临时走开一下再回来”，状态一直在手边。

3.6 自动保存的取舍

工具本身提供自动保存选项，可以设置间隔时间定期保存当前上下文。我实际用了一段时间之后，把自动保存关掉了。

原因是我发现自动保存会把“脏状态”也存进去。有一次我把PATH临时改坏了，本来想着手动修一下，结果自动保存在这个时间点触发，把错误的PATH存进了快照。之后恢复这个快照时，PATH一直不对，排查了很久才发现是自动保存的锅。

现在我用的策略是“手动save + push前自动快照”。cm push执行时会自动保存一份当前状态到临时槽位，用于栈回退，不覆盖手动的命名快照。这样既保证回退链的完整性，又不会让自动保存把混乱状态写进正式的上下文记录。

真正值得手动save的时机，我总结了三个：写完一个模块准备切换任务时、开始修bug之前、以及一天工作结束时。这三个时间点保存的上下文，基本覆盖了我90%的恢复需求。

4. 踩坑记录与问题排查速查

4.1 环境变量没有恢复

这是我遇到最多的一个问题。保存快照时明明export了变量，恢复之后变量却是空的。

分三种情况排查。第一，白名单没配好。检查config.json里的env_whitelist，如果你存的变量名不在白名单里，context-mode根本不会采集它，更谈不上恢复。第二，变量是只读的。某些shell变量如BASHOPTS、UID不允许用export覆盖，恢复时会被静默忽略。第三，恢复顺序出了问题。如果你在~/.zshrc里自己又export了同名变量，而且执行顺序晚于context-mode的恢复逻辑，它就会被覆盖成别的值。

排查命令很简单：

cm show mall-order-timeout | grep -A 20 '"env"' echo $REDIS_URL

先看快照里到底存了没有，再对比当前shell里的实际值，基本能定位是哪一类问题。如果是只读变量，那只能在白名单里删掉它，别想着强行覆盖。

4.2 Git分支恢复错乱

恢复上下文时我期望它自动切回保存时的分支，但有时候这个动作会失败，而且失败的方式很迷惑——目录切回去了，分支却没切过去。

原因通常是保存上下文那一刻的工作区状态不干净。git checkout在遇到未提交的改动或冲突时会拒绝执行，如果你的dirty标记为true，context-mode默认不敢自动checkout，因为可能把你没提交的修改给整没了。

我的建议是：不要把自动checkout当成默认行为。context-mode现在只做“目录恢复”和“环境恢复”，git分支你手动切一下并不麻烦，反而更安全。cm show里能看到当时的branch名，照着切就是了。如果确实需要自动切，那就保证保存上下文时工作区是干净的，否则恢复时遇到冲突会很难处理。

4.3 tmux会话名冲突

前面说过，两个项目用了同样的tmux会话名，恢复时会附加到错误的会话上。这个问题比想象中隐蔽，因为你是在恢复之后才发现“不对啊，这个窗口布局不是我要的”。

解决思路有两条：一是命名规范，会话名用项目名做前缀，从根源上避免冲突；二是恢复前先检查目标会话是否存在，如果存在且来自不同的工作目录，就列出所有可选项让你确认，而不是闷头附加。

我也踩过另一个tmux相关的坑：保存上下文时tmux会话已经不存在了（比如之前手动关掉了），快照里记录的session名就成了死引用。恢复时context-mode会试图创建一个同名会话，但因为窗口布局信息是旧的，创建出来的布局可能对不上。现在我对这种情况的容忍度变高了，毕竟tmux会话恢复本来就是尽力而为的事情，窗口布局乱了就手动调一调。

4.4 排查工具与扩展思路

context-mode自带几个排查命令，出问题先跑一遍再逐层看：

cm doctor cm debug cm log

cm doctor检查配置文件格式、存储目录权限和shell hook是否加载。cm debug输出当前shell的完整状态，包括context-mode加载标记。cm log查看最近的保存、恢复、push、pop操作记录。这三条命令基本覆盖了90%的排查场景。

用熟练之后还可以做一些扩展。我在自己环境里做了三件事：一是接fzf做模糊搜索，cm up之后用快捷键搜索快照名；二是在git pre-commit hook里顺手保存一次上下文，这样重要工作节点不会再忘记存档；三是把当前快照名写入tmux的status-left，终端上直接能看到自己在哪个上下文里。

我给团队也推广过这套思路，只不过用的是共享配置文件，团队里每个成员都能选择把哪些上下文模板同步到本地。协作场景下，新人接手项目时直接恢复老手留下的上下文，能省下非常多环境配置的时间。

最后说点实际体会。工具虽然不复杂，但用好的关键在于养成“保存现场”的习惯。我见过不少人装了工具之后仍然不用，就是因为没有建立“重要节点主动保存”的意识。从今天开始，每次结束一个阶段性的工作，顺手cm save一下，坚持一周，你会明显感觉到切换项目的心理负担小了很多。上下文恢复这种事，工具永远是辅助，真正受益的是你不再需要靠脑子硬扛那几分钟。