说实话我受够了在终端里开着十几个窗口每个窗口跑着不同的任务结果一忙起来就分不清哪个窗口干到哪一步。我最近基于context-mode这个思路做了一套终端上下文管理工具核心目标就一个让每个终端会话都能记住“我刚才在干什么、干到哪了、接下来要做什么”切换任务的时候不再靠脑子硬记也不用东翻西翻历史记录。这篇文章就把这套工具的完整设计和实操过程拆开讲清楚适合那些每天泡在终端里、同时维护多个项目、经常被上下文切换搞到头大的开发者参考。项目本身不复杂底层就是一组 shell 脚本加一个轻量的状态存储层但它解决的问题特别实在。我在实际用下来之后觉得它最值钱的地方不是“自动保存状态”这个功能而是它逼着你给每个工作片段打好标签、写下备注让一段段碎片化的终端操作变成一个一个能被回溯、被检索、被恢复的工作单元。下面从需求拆解讲起一路到实现细节和踩坑记录。1. 为什么需要 context-mode终端上下文割裂的真实痛点1.1 多个终端窗口之间的“失忆”困境先描述一个非常典型的场景你上午在 A 窗口改后端接口下午在 B 窗口调前端页面晚上又回到 A 窗口继续改接口。等你回到 A 窗口时眼前只有一个空荡荡的命令行提示符你完全想不起来自己刚才改到第几个文件、数据库迁移有没有跑完、那个接口的 mock 数据放在哪。你只能靠history一条条翻靠pwd和git status猜靠脑袋里残存的记忆拼凑。更糟的是多项目并行的时候。你可能有三个仓库同时处于开发状态每个仓库里有各自的 feature 分支、各自的临时环境变量、各自的构建命令。终端本身是不会替你记住这些的它只负责执行命令你的 shell 配置文件也只会给你一个统一的环境。结果就是每次切换任务你都要重新设置环境变量、重新进入目录、重新找分支、重新回忆上次的测试命令。这些重复劳动本质上是上下文信息的丢失。1.2 context-mode 的产品定位不做重型工具只做上下文快照一开始我考虑过用 tmux 的resurrect和continuum插件它们确实能保存 tmux 会话、窗口布局甚至 pane 里的进程状态重量级场景下很强大。但对于大多数日常工作来说它有点“杀鸡用牛刀”需要装一堆插件、配置各种绑定而且在团队共用开发机或者 SSH 远程场景里tmux 的会话恢复经常因为 PATH、环境变量不一致而翻车。所以我决定自己做一个轻量的 context-mode定位极其克制它不保存进程不接管终端复用只保存上下文元数据。具体来说每次你主动或自动地离开一个工作单元时它会把以下这些信息写成一个上下文快照当前工作目录Git 分支、当前状态clean 还是 dirty有哪些未提交文件自定义的上下文标签和备注比如“修复订单超时问题”最近执行的 N 条关键命令当时的临时环境变量比如编译选项、调试开关这个上下文对应的时间戳和累计使用时长这样设计的核心逻辑是终端会话的“状态”并不等于“进程状态”真正有长期价值的是你把精力投在哪个目录、哪个分支、哪个问题上。只要这些东西被准确记录你随时可以从一个干净的 shell 里一键回到那个“状态”。2. 整体设计与方案选型只做“状态存储 切换协议”2.1 为什么不直接用 tmux session 做绑定其实有个很自然的思路直接用 tmux 的 session name 来标识不同项目每个 session 里保留独立的 shell 环境。这也是很多人惯用的做法。但实际体验下来有几个毛病tmux 会话一多ls出来的名字毫无语义全是0、1、2或者随机字符串你根本看不出哪个对应哪个项目。团队共用服务器时别人也会创建 tmux session你的prefix d一按再回来看可能 session 已经被 attach 到别人那边去了。tmux 保存的是“同一个 shell 进程里的运行现场”而大多数时候我们需要的不是现场而是“重新搭一个现场所需的全部信息”。所以我的方案是用 context-mode 作为独立于 tmux、screen 之外的元数据层。你用什么终端复用工具都可以甚至裸终端都行。context-mode 只负责记录和恢复“语义上下文”不负责维持进程存活。2.2 状态存储不用数据库用 JSON 目录索引选型时候反复纠结过一个问题上下文快照存哪儿、怎么存。第一版我用了 SQLite觉得结构化查询方便后来发现完全没必要。几个核心原因上下文快照的访问模式非常简单按名字精确查、按 tag 模糊搜、按时间排序。这些操作用文件名加目录结构就能完成不需要 SQL。SQLite 文件一旦损坏或者版本升级导致表结构变化排查成本很高。反观 JSON 文件随便打开一个编辑器就能看出了问题能直接手动修复。我希望这工具能“透明得像文件一样”用户可以自己用ls、grep、tar去操作历史快照数据库做不到这种透明性。最终存储结构是这样的~/.config/context-mode/ ├── index.json # 全局索引项目名 - 快照 id 列表 ├── tags.json # 标签倒排索引tag - 快照 id 列表 ├── snapshots/ │ ├── 20250127_143200_order_fix.json │ ├── 20250127_203000_ui_icon_align.json │ └── 20250128_093000_db_migration.json └── current # 当前活动上下文指针index.json里保存的是目录与快照的映射关系而快照文件名自带时间戳和短横线拼接的slug一眼就能看出这是什么时候、关于什么的快照。current文件更简单里面就是一个快照 id记录当前 shell 正挂在哪个上下文下。2.3 核心命令协议save / switch / ls / tag / drop接口设计上我参考了 git 的直觉模型但刻意去掉了所有“暂存区”“工作区”之类的概念只保留五个高频操作ctm save [name] # 保存当前上下文name 可省略省略时自动从目录名和时间生成 ctm switch id|name # 切换到某个已保存的上下文恢复目录/分支/环境变量 ctm ls [--tag xxx] # 列出所有上下文快照支持按标签过滤 ctm tag id tag # 给快照打标签或者追加备注 ctm drop id # 删除某个快照为什么把操作压缩到这么少因为上下文管理的核心负担不在于“功能丰富”而在于“什么时候保存、什么时候唤起”。这两个动作如果做起来费劲这工具很快就会被弃用。我宁愿把保存设计得无脑到手指肌肉记忆也不愿意做一个功能很多但每次使用都要想半天的东西。3. 核心实现与关键参数拆解3.1 快照生成逻辑采集哪些字段为什么是这个顺序快照采集顺序对正确性影响很大。我最初的版本顺序是先跑git status再读环境变量最后写 JSON。后来发现一个隐蔽的问题每条命令都可能改变环境变量而上一条命令写入的“当前分支”可能已经和下一条命令的记录不一致了。所以我定了一个固定采集协议每个字段都有明确时序1. 记录时间戳date %s 2. 记录 $PWD必须在任何 cd 之前 3. 记录 git 分支和状态git rev-parse --abbrev-ref HEAD / git status --porcelain 4. 记录关键环境变量从 CTM_PROFILE_ 白名单前缀里挑选 5. 记录最近命令历史fc -ln -20只记录最近 20 条非重复命令 6. 读取用户备注文件如果有 CONTEXT.md则自动读取前 200 字 7. 写入临时文件校验 JSON 合法性再原子 rename第 6 步是我后来加的一个亮点。很多项目根目录下本来就有一份CONTEXT.md或者README.md里面写了一些项目的说明。context-mode 会在保存快照时自动读取这个文件的前几行作为快照的“语义摘要”。这样即使你当时没来得及手写备注快照本身也会包含一份可读的上下文说明。至于fc -ln -20这个参数是我试错试出来的。最早我直接用history但 zsh 的history默认包含整个会话的累积记录过滤噪音的成本太高。后来换成 bash 的fc -ln它只输出命令而不带行号再结合tail -20就能拿到最近 20 条干净命令。这 20 条命令就会被写进快照的recent_cmds数组作为“下一步可能还要用的命令”的线索。最终生成的 JSON 长这样{ id: 20250127_143200_order_fix, slug: order_fix, project: /home/me/work/orderservice, created_at: 1737930720, last_used_at: 1737930720, git: { branch: feature/timeout-retry, status: [ M src/service/order.go, ?? scripts/bench.sh ] }, env: { CTM_BUILD_DEBUG: 1, CTM_CPU_PROFILE: true }, recent_cmds: [ go test ./internal/order/..., curl localhost:8080/api/v1/orders/123 ], note: 订单超时重试逻辑调了一上午主链路已通还差 mq 消费者的幂等处理 }3.2 switch 切换机制从“恢复环境”到“恢复心理模型”ctm switch是整个工具里最需要小心实现的命令。它不只是帮你cd到目录、切分支那么简单它的核心目标是让切换后的 shell 用户立刻知道“我在哪、我在干嘛、我刚干到哪了”。具体实现分四步第一步读取快照 JSON校验字段完整性 第二步cd 到 project 目录 第三步根据 git.branch 切换分支如果目标分支存在的话 第四步export 所有 CTM_ 前缀的环境变量 第五步打印一张“上下文恢复卡”这里最关键的参数是第五步的上下文恢复卡。它是一段格式固定的文字输出到终端后能快速把人的记忆拉回现场━━━ context-mode restored ━━━ 项目: ~/work/orderservice 分支: feature/timeout-retry 上次工作: 订单超时重试逻辑调了一上午主链路已通... 最近记录: go test ./internal/order/... curl localhost:8080/api/v1/orders/123 ━━━━━━━━━━━━━━━━━━━━━━━━━━━这一张卡片解决了上下文切换最大的痛点你人到了这个目录但你的脑子还停留在上个任务的思维模式里。纯粹靠cd和git checkout是没法把脑子拉回来的但看到“最近记录 备注”之后等于从上一段工作里抽了一张记忆卡片贴在你眼前。3.3 自动清理与上下文合并策略防止快照库变成垃圾场保存快照的门槛太低就意味着一定会产生大量无价值的快照。我的清理策略很简单但一直有效每个项目目录下最多保留 10 个快照超出后自动丢弃最旧的LRU 规则。快照如果创建时间超过 14 天且从未被switch过自动标记为可归档ctm ls默认不显示。手动清理用ctm drop批量清理用ctm drop --older-than 30d。这个策略还有一个补充机制如果用户在同一项目目录、同一 git 分支下连续保存了多个快照而且最近命令相似度超过 70%context-mode 会把这几份快照自动合并成一条备注内容用换行符拼接。这样既保留了历史脉络又不至于让快照列表膨胀到不可用。我做这些清理逻辑的原因很朴素任何工具如果用了几个月之后变得臃肿用户就会失去信任。上下文管理工具尤其如此因为它的核心价值恰恰是“快速找到对的那一段”一个堆满垃圾的列表比没有还可怕。4. 实操过程从零搭建一个可用的 context-mode4.1 安装与初始化把脚本放进 shell 的钩子里context-mode 的核心是一个 package 为纯脚本的项目不依赖 Python、Node 之类的运行时只要求 bash 4.0 或 zsh。我的安装方式非常朴素直接 clone 下来然后把bin/加到 PATH再把一段初始化脚本注入到 shell 的 rc 文件里。# 项目根目录下执行 git clone repo-url ~/.context-mode echo \n# enable context-mode hook\nexport PATH\$HOME/.context-mode/bin:\$PATH\neval \\$(ctm init --shellzsh)\ ~/.zshrc source ~/.zshrcctm init会往 shell 里注入两个 hookchpwd每次目录切换时自动触发一次“轻量级快照采集”只记录PWD和git branch不记录完整状态。这是为了全局索引里始终有最新的目录轨迹。zle-line-initzsh 下每次命令行回车时把当前时间戳记录到一个临时 buffer 里用来计算“在这个上下文里待了多长时间”。安装完之后你可以先手动跑一次ctm save frontend_fix -n 修复按钮居中问题如果命令执行后没有报错再执行ctm ls看是否出现一条记录。第一次显示记录后整个链路就通了。4.2 常用命令实战一次典型的上下文切换流程我用一个真实的工作流来演示假设你上午在api-server仓库修接口超时下午被叫去改web-console的前端样式晚上又要回到接口修复。上午的会话# 进入 api-server 项目 cd ~/work/api-server git checkout feature/timeout-retry # 改了一堆代码之后准备切换任务 ctm save order_timeout -n 超时重试还差 mq 幂等 # 接着 cd 到 web-console开始处理前端 cd ~/work/web-console ctm save button_align -n 订单页按钮错位需要统一间距晚上的会话重新打开终端ctm ls # 输出列表里能看到 order_timeout 和 button_align 两条 ctm switch order_timeout # 会输出上文提到的那张“上下文恢复卡”s witch之后你已经回到~/work/api-servergit 分支切换回feature/timeout-retryCTM_前缀的环境变量也恢复了。此时你再按一下↑就能看到最近命令go test ./internal/order/...一切从大脑之外又回到了指尖之下。4.3 与常用工具的结合技巧tmux、fzf、编辑器context-mode 和 fzf 的组合是我最推荐的一对组合。直接在 shell 配置里加一段alias ctm-findctm ls | fzf --preload cat ~/.config/context-mode/snapshots/{1}.json这样你可以在所有快照里模糊搜索按回车后用 awk 取出快照 id 再传给ctm switch。当快照数量超过 50 条时这个模糊查找的必要性会非常明显。和 tmux 的结合也很有价值在 tmux 的resize-pane场景里每打开一个窗口就自动把当前窗口的标题改成本次会话的slug。我的做法是在 tmux 的配置文件里加一行 hookbind-key -n F8 run-shell tmux rename-window $(ctm-current-slug)这样窗口标题栏里显示的是order_timeout或者button_align而不是默认的zsh。你一眼扫过去就能知道哪个窗口在干什么。编辑器的集成相对简单我平时用 vim所以在.vimrc里加了一个命令切换项目时自动调用ctm switch再重新打开文件列表省掉了跨项目反复cd的麻烦。5. 常见问题与排错实录5.1 并发写入导致快照互相覆盖这是我在最初版本里遇到的最严重问题。终端里同时开着多个标签页每个标签页都在保存快照两个进程同时写同一个目录的 JSON 文件就会出现内容互相覆盖或者写坏的情况。排查过程很有代表性表现是某些快照文件 JSON 解析失败但手工验证命令又查不出问题。后来发现是因为快照写入没有加锁两个 shell 同时ctm save时后写的覆盖了先写的。解决方案是用mkdir做原子锁lockdir~/.config/context-mode/.lock while ! mkdir $lockdir 2/dev/null; do sleep 0.05 done trap rm -rf $lockdir EXIT # 执行快照写入...这个方案比flock更简单且不依赖特定平台。实测下来并发 10 个 shell 同时保存都没再出现覆盖问题。5.2 切换后环境变量丢失与 PATH 错乱ctm switch恢复环境变量时有一个很容易踩的坑直接 source 快照里的环境变量会导致当前 shell 的 PATH 被附加了多次而且某些变量在 sh 和 zsh 下的语法不兼容。我后来改成只恢复CTM_前缀的变量避免污染正常的系统变量同时恢复顺序改为先导出变量再执行cd最后再跑git checkout。因为git checkout会改变当前目录下的文件状态如果在这之前就切了目录某些路径引用会失效。还有一个细节如果你在快照里记录了CTM_BUILD_DEBUG1下次 switch 时它会自动带上但如果你这次切换后主动 export 了别的值应该再保存一个新快照否则下次又会被恢复成旧值。这个特性需要我手写一个优先级的判断显式导出 快照记录 系统默认。5.3 快照越来越多性能下降怎么办当快照总数超过几百条后ctm ls的响应时间会从毫秒级变成秒级原因是它每次都扫描全部 JSON 文件。优化思路有两个加一层文件名索引和加一个--limit参数。文件名索引很简单就是把index.json改成按日期分目录存储snapshots/ ├── 2025/01/20250127_143200_order_fix.json ├── 2025/01/20250127_203000_ui_icon_align.json └── 2025/02/20250201_093000_db_migration.json这样ctm ls只需要读取最近一个月的文件之前的直接跳过。实际测下来即使积累到 1000 条响应时间也能保持在 200ms 以内。如果连这个都不满足那就执行一次ctm drop --older-than 30d把真正的垃圾清空。写在最后的一点体会用这个工具半年最大的感受不是“节省了多少时间”而是“切换任务时的心理负担明显变轻了”。以前我从一个项目切到另一个项目总要先花五分钟回忆一下上次干到哪再花五分钟找回之前的命令和环境。现在ctm switch一敲那些信息直接从终端里冒出来人的思维惯性被打断的瞬间反而能更从容地接上新任务。最后再分享一个小技巧是我无意间发现的保存快照之后再写两句备注。一开始我嫌麻烦很少写备注结果快照列表里全是类似order_fix、button_align这种只有自己能猜的短标签。后来强迫自己每次保存时补上一句自然语言备注比如“超时重试还差 mq 幂等”三个月后回看这些备注它们已经变成了一份真实的项目日志。很多当初以为会记住的细节其实一个周末就忘干净了反而是这些随手写的备注成了最有价值的历史资产。如果你也要做类似的项目建议从第一天就把“备注”当成一等公民而不是可选功能。
