最近在整理工作流的时候我把零散在各个终端里的项目状态统一收拢成了一个叫context-mode的小工具。你可能也遇到过这种状态开了三四个终端窗口每个窗口里 cd 到不同目录、导出过不同的环境变量、甚至为了不同项目设置了不同的 shell 提示符一旦切到别的任务再切回来环境已经面目全非得重新 export 一遍。context-mode 要解决的就是把这堆我正在哪、我在跑什么、我需要哪些参数打包成一个可命名的上下文一条命令切走、一条命令切回。这篇文章不是工具文档是我从需求梳理到实现、再到实际使用了几个月的完整过程记录。里面会拆解 context-mode 的核心设计思路、配置文件怎么写、命令怎么用得顺手、以及和 AI 辅助编码工具联动时怎么把上下文喂给模型。如果你也经常在多项目之间来回横跳或者想让每个项目的启动环境更规范一点这篇文章应该能直接帮你落地一套自己的方案。1. 为什么会有这个工具先聊聊上下文切换这件事1.1 我踩过的切换坑三个终端的教训我日常的工作状态是同时维护一个后端服务、一个前端工程偶尔还要处理线上告警和脚本任务。以前的做法很原始开三个终端窗口分别 cd 到不同目录然后每个窗口手动 export 一些变量。看起来没什么问题但真正跑起来的时候痛点非常明显。第一个坑是环境变量靠记忆。比如后端服务依赖DATABASE_URL、REDIS_URL前端工程需要PUBLIC_API_BASE每次新开一个终端都得重新 export 一遍。偶尔漏了一个变量服务起不来排查半天发现只是环境变量没设全。第二个坑是路径来回跳。有时候同一个终端里要在多个项目之间切换cd来cd去加上git branch的状态、当前用的 Python 虚拟环境整个终端状态很难一眼看清。第三个坑更隐蔽——上下文信息没法传递。我想让某个脚本知道当前正在处理项目 A 的发布流程或者想让 AI 辅助工具知道我现在在改数据库迁移文件这些信息散落在各自的命令里没有一个统一的地方可以读取。这三个坑本质上是同一个问题终端缺乏上下文这个抽象层。目录只是一个维度环境变量是另一个维度而当前任务、当前项目的约定参数更是完全没人管的维度。系统的、可复现的上下文管理比单纯的目录切换要复杂得多也重要得多。1.2 context-mode 的核心定位上下文不是环境变量而是一组可组合的状态我一开始的想法很简单写个脚本把每个项目的环境变量存下来切换的时候 source 一下。但用起来之后发现不够。因为上下文里不只有环境变量还有当前目录切到上下文时应该自动 cd 到对应项目的根目录。提示符与别名不同项目希望有不同风格的提示符比如显示当前 context 名和 git 分支。命令别名后端项目里我习惯用dev代表启动开发服务器前端项目里dev可能代表启动 Vite别名必须跟着上下文走。任务备注当前这个 context 正在做什么给未来的自己留一句话备注。对外参数供脚本或者 AI 工具读取的键值对比如TASK_TYPEmigration、PROJECT_NAMEorder-service。所以 context-mode 的定位不是环境变量管理器而是一组可命名、可切换、可持久化的终端状态集合。环境变量只是这个集合里的一部分。这样设计之后切换上下文就变成了一次完整的工作现场恢复而不是零散的 export 和 cd。1.3 这个工具适合谁用如果你符合下面任意一条我觉得 context-mode 的思路值得参考同时维护两个以上项目经常在终端里来回切换目录和变量。团队环境里不同项目有不同的约定变量希望把这些约定固化下来。经常使用 AI 辅助编程工具希望模型能自动拿到当前项目的技术栈、启动命令、关键路径等上下文信息。喜欢把工作流自动化希望所有终端状态都能被记录、被恢复、被分享。我后面的所有设计都围绕这几类人的真实场景展开。2. 整体设计与方案选型2.1 三个核心抽象Context / Profile / Session在设计 context-mode 时我引入了三个抽象分别是 Context、Profile 和 Session。这三个词的边界如果不划清楚后面实现会越写越乱。Context上下文一个完整的工作场景定义。它包含名称、描述、工作目录、环境变量表、别名表、提示符模板、备注等。Context 是静态配置定义这个项目长什么样。Profile档案Context 的实例化结果。同一份 Context 可以有不同的 Profile比如开发环境的 Profile 和联调环境的 Profile。Profile 解决同一项目不同运行参数的问题。Session会话当前终端实际激活的状态。Session 就是我现在正处在哪个 Profile 里、从什么时候开始、有没有临时的本地覆盖。用生活化的类比来说Context 是菜谱Profile 是按菜谱做的不同分量的菜Session 是你餐桌上正在吃的那一盘。实际使用中用户大多数时候只需要操作 Context 和 Session定义好 Context然后use创建 Session。这个三层设计还有一个好处配置可以分层共享。Context 可以提交到仓库里让团队共用Profile 可以放在个人目录里做覆盖Session 状态只属于某个终端实例不会污染别人。2.2 为什么不用 tmux 或者 direnv而要自己写很多人会问已有 direnv、tmux、shell 的 chpwd 钩子为什么还要造轮子我确实都试过说说各自的局限性。direnv擅长处理进入某个目录时自动加载环境变量但它强依赖目录层级切换目录才触发加载。问题是同一个项目可能分散在多个目录或者不同项目共享同一目录direnv 只能靠.envrc文件被动触发没法做到按项目语义切换。tmux擅长保存终端会话可以把窗口、面板、当前目录都保存下来。但 tmux 的会话恢复偏重量级而且不方便在会话之间传递上下文参数想给脚本暴露当前项目信息就更麻烦。shell 的 chpwd 钩子能自定义目录切换逻辑但逻辑散落在.zshrc里难以共享和版本化管理也让新同事很难快速理解项目环境约定。我的方案是一个命令行工具 shell 集成脚本的组合。CLI 负责读写配置、管理上下文、输出切换指令shell 集成负责在子进程里真正执行cd、export、alias等操作。这样既保留了 CLI 的可测试性和表达能力又能和 shell 无缝配合。2.3 技术选型Shell 一个 JSON 文件就够了context-mode 的实现选择了Python 3 JSON 配置文件 zsh/bash 集成脚本。为什么不用 Go 或 Rust因为我并不追求极致的启动速度而且配置解析、格式校验、甚至以后想加 YAML 支持Python 做起来都很快。整个工具的核心逻辑只有几百行保持轻量比性能更重要。JSON 作为存储格式也够用。虽然 YAML 可读性更好但 JSON 不需要额外依赖Python 原生支持而且大多数编辑器对 JSON 的格式化支持都很完善。配置结构稳定之后我反而觉得 JSON 更适合做机器读写——它能明确表达嵌套结构不会像 YAML 那样被缩进问题搞得头大。整体架构分成三层配置层~/.context-mode/config.json存放所有 Context 定义~/.context-mode/state.json存放 Session 状态。命令层cm命令负责所有操作包括cm use、cm list、cm pull、cm push等。集成层shell 函数cm_activate读取 CLI 输出的环境变更清单并实际执行保证环境变更发生在当前 shell 进程中。这个分层很关键也是后面排查很多问题的切入点。3. 核心功能拆解与实操要点3.1 初始化一份 context 配置长什么样初始化很简单执行cm init之后工具会在~/.context-mode/下生成一个默认配置文件。我习惯把配置按项目实体来组织一个具体的例子{ contexts: [ { name: order-svc, description: 订单后端服务, workdir: ~/work/order-service, env: { DATABASE_URL: postgres://localhost:5432/order_dev, REDIS_URL: redis://localhost:6379/0, LOG_LEVEL: debug }, aliases: { dev: npm run dev, migrate: npm run migrate }, prompt: order-svc, note: 正在处理订单超时问题 } ], profiles: { order-svc: { staging: { env: { DATABASE_URL: postgres://staging-host:5432/order_staging } } } } }特别注意aliases里的dev。在 order-svc 这个 context 里dev就是启动后端开发服务器。这样的好处是每个项目都可以有自己的命令简写不用记一堆 npm scripts。配置里的prompt字段会让终端的提示符变为[order-svc] ➜一眼就能看出当前在哪个 context。配置文件的语义我用一个表整理一下字段作用必填说明nameContext 名称是唯一标识切换时用workdir工作目录是激活时自动 cd 到这里env环境变量否激活时全部 exportaliases命令别名否激活时写入当前 shellprompt提示符前缀否激活时改变 PS1note任务备注否给当前任务留个说明3.2 高频操作use、list、push、pull实际使用中90% 的操作集中在四个命令上。cm use name是核心命令。执行后工具会读取对应 Context 的配置返回一串需要在当前 shell 执行的指令由集成函数真正执行。指令包括cd、export、alias、PS1赋值。我故意让 CLI 本身不直接改环境这是为了保持纯度——CLI 只回答应该变更什么shell 集成只负责执行变更。cm list输出所有可用的 context 列表配合--verbose可以查看每个 context 的关键环境变量和当前激活状态。我在实际使用中会把它绑成一个快捷键随时查看自己的现场。cm push和cm pull是我后来加上的功能。push表示把当前 Session 的某个临时变更写回 Profile 配置比如我临时改了LOG_LEVELinfo调试完发现这个值以后也应该用就执行cm push env.LOG_LEVEL写回去。pull则是从配置里重新拉取某个字段覆盖当前 Session 的值。这两个命令解决了临时修改和固化修改之间的矛盾不用再手动编辑 JSON。3.3 环境变量、路径、提示符的联动逻辑context-mode 的激活逻辑是有顺序的不是一股脑全执行。顺序错了会踩大坑。我整理出来的正确顺序是先记录当前 Session 的退出前状态如果有。解析新 Context 的完整配置合并 Profile 的覆盖项。清理旧 Context 产生的影响把旧 context 导出的变量从环境里移除把旧别名 unalias。这里不能通过unset全部清空因为有些变量可能是系统本来就有的所以配置里需要记录当前 Session 导出了哪些变量名。应用新配置先cd到 workdir再逐个export再设置别名和提示符。把新的 Session 信息写入state.json供并行终端和脚本读取。很多早期版本的工具在切换时忘记清理旧状态导致两个 context 之间的变量互相污染。尤其像PATH这种累积型变量切换几次之后会出现一堆重复路径。所以我在设计上明确要求管理好导出变量清单不能只加不减。3.4 与 AI 辅助编码工具的联动把上下文喂给模型这个是 context-mode 意外收获的最大价值。现在很多 AI 辅助编码工具最大的问题不是模型能力而是模型不知道你的项目背景。你问它帮我改一下这个服务的超时逻辑它根本不知道是哪个服务、用的什么框架、代码在哪儿。为了让 AI 吃到上下文我在配置里增加了一个ai_context字段把项目背景信息结构化地放进去{ name: order-svc, ai_context: { tech_stack: Node.js 20 Express PostgreSQL, entry: src/server.js, test_cmd: npm test, conventions: { errors: 统一抛出 AppError错误码见 src/errors.js, db: 迁移文件在 migrations/ 目录用 knex } } }配合一个简单的脚本可以把当前激活 context 的ai_context输出成一段 Markdown 文本然后让我在 AI 工具里粘贴或者在终端里通过管道直接塞给命令行 AI 助手。由于 context 已经激活脚本读取state.json就知道该输出哪份上下文。我还做过一个自动化版本在cm use之后自动把ai_context写入/tmp/current_context.md这样 AI 工具配置成自动读取这个文件就能随时拿到最新上下文。模型回答的质量明显提升了尤其是在涉及数据库迁移和错误处理规范这类项目特有规则时不再需要我在每个 prompt 里重复一遍项目背景。4. 关键实现与执行细节4.1 配置解析与上下文存储格式配置解析的思路是先校验再使用。我会在cm use之前先做一次完整校验避免已经有配置错误的情况下切换造成半激活状态。import json import os import re from pathlib import Path CONFIG_PATH Path(os.environ.get(CONTEXT_MODE_CONFIG, ~/.context-mode/config.json)).expanduser() def load_config(): with open(CONFIG_PATH, r, encodingutf-8) as f: return json.load(f) def validate_context(ctx): required [name, workdir] for key in required: if key not in ctx: raise ValueError(fcontext 缺少字段: {key}) if not re.match(r^[a-zA-Z0-9_-]$, ctx[name]): raise ValueError(fcontext 名称包含非法字符: {ctx[name]}) return True def resolve_workdir(raw_path): 展开 ~ 和相对于配置文件目录的相对路径 path Path(raw_path).expanduser() if not path.is_absolute(): path CONFIG_PATH.parent / path return str(path.resolve())这里面我踩过的一个细节是路径解析。配置写在~/.context-mode/config.json里但工作目录的路径如果直接按字面用~/work/xxx这种写法可能在子进程里展开错误。所以一定得在 Python 侧用expanduser()和resolve()预处理不能把原始字符串丢给 shell。配置存储格式我用了 JSON但每个 Context 内部的 env 字段允许嵌套覆盖。Profile 的覆盖逻辑是递归合并的也就是 Profile 里写了env.DATABASE_URL就只覆盖这一个键其他 env 保持 Context 原样。这个递归合并函数也是所有配置操作的核心def deep_merge(base: dict, override: dict) - dict: result dict(base) for key, value in override.items(): if key in result and isinstance(result[key], dict) and isinstance(value, dict): result[key] deep_merge(result[key], value) else: result[key] value return result4.2 切换逻辑与 shell 集成CLI 这边cm use的核心输出是一份变更清单我把它定义成一种简单的行协议每行一个操作指令。这样 shell 集成脚本可以逐行解析并执行不需要和 CLI 共享内部数据结构。def emit_actions(ctx, profile_nameNone): actions [] actions.append(fcd:{resolve_workdir(ctx[workdir])}) for key, value in ctx.get(env, {}).items(): actions.append(fexport:{key}{value}) for alias, cmd in ctx.get(aliases, {}).items(): actions.append(falias:{alias}{cmd}) if ctx.get(prompt): actions.append(fprompt:{ctx[prompt]}) return actionsshell 集成这边我写了一个 zsh 函数cm_activate。它调用 CLI 拿到 actions逐个执行。关键点是CLI 是在子进程里运行的它的 export 不会影响父 shell所以真正改变环境的动作必须放在这个函数里做。cm_activate() { local profile${1:-} local actions_file actions_file$(mktemp) cm _emit_actions $profile $actions_file local status$? if [[ $status -ne 0 ]]; then cat $actions_file rm -f $actions_file return $status fi while IFS read -r line; do case ${line%%:*} in cd) cd ${line#cd:} ;; export) export ${line#export:} ;; alias) alias ${line#alias:} ;; prompt) cm_set_prompt ${line#prompt:} ;; *) ;; esac done $actions_file rm -f $actions_file cm _save_session $profile }这里有一个很容易被忽略的问题如果cd后面跟着空路径或者带空格路径按:分割会出错。所以我在 CLI 端对路径做了 base64 编码shell 端先解码再执行。这个问题是我在实际使用中遇到路径带空格就失灵之后修复的算是比较典型的真实场景坑。4.3 补全脚本与 Hook 机制context-mode 能让cm use TAB自动补全 context 名称。补全逻辑直接从配置里读 context 名字即可不需要额外维护一个列表_cm_completions() { local -a contexts contexts(${(f)$(cm _context_names)}) _describe context contexts } compdef _cm_completions cm刚开始没做补全的时候每次都要敲完整的 context 名order-svc还好遇到order-svc-staging-2025这种长名字就得反复 TAB 或者复制粘贴。补全之后误输入的情况也少了很多因为 shell 会明确告诉你可选的名字有哪些。Hook 机制是我设计里比较独特的一部分。每个 Context 可以在配置里声明on_enter和on_leave两条命令。on_enter在激活时执行比如自动启动docker compose up -d或者创建一个 tmux 窗口on_leave在离开时执行比如保存当前测试报告或者停止本地守护进程。{ name: order-svc, hooks: { on_enter: docker compose up -d db, on_leave: docker compose stop } }注意这里我用了守护进程而不是守护程序避免拗口。Hook 的设计初衷是让 context 不只是静态状态还能触发一系列行为。但我也给自己立了规矩Hook 里绝对不能放耗时超过几十秒的操作否则切一次 context 要等半天体验反而变差。5. 实际使用中的常见问题与排查实录5.1 子进程环境变量不生效这是所有 shell 相关工具最常见的坑。现象是执行cm use order-svc之后当前终端的环境变量是对的但在这个终端里新开的子进程比如运行 npm script、python 脚本却拿不到应有的变量。排查思路很直接先确认export有没有真正执行到当前 shell。用echo $DATABASE_URL看看当前 shell 有没有值。如果有值而子进程拿不到那通常不是 context-mode 的问题而是子进程的启动方式覆盖了环境变量。比如 npm scripts 里如果有自己的.env文件dotenv 会优先读取项目里的.env覆盖系统的环境变量。如果当前 shell 没有值检查一下cm_activate函数的执行错误。常见原因是 zsh 函数定义时用了错误的语法比如alias语句里有空格没有加引号。我建议在-x模式下手动执行一次cm_activate看哪一行解析出错。5.2 多终端并行切换导致配置覆盖我同时开很多终端每个终端都可能执行cm use。早期版本state.json记录的是最后一次激活的 context 名结果终端 A 切到 order-svc终端 B 也切到 order-svc然后终端 A 执行cm push env.LOG_LEVELB 终端再执行任何跟 state 相关的操作都可能把 A 的变更冲掉。解决方法是让 Session 带一个唯一的 session ID。每个终端在第一次激活时生成一个 UUID 并写入state.json之后所有操作都带上这个 session IDstate 文件变成一张 Session 表而不是单一状态。cm ps命令可以列出所有活跃 SessionSESSION ID CONTEXT STARTED NOTE a1b2c3d4... order-svc 2025-01-12 10:32 调订单超时 f6e5d4c3... web-front 2025-01-12 11:02 迁移按钮组件这样每个终端各管各的现场互不干扰。共享的只有配置而配置被设计成只追加、不覆盖所以并发问题主要集中在状态文件上。引入 session ID 之后基本解决了这个问题。5.3 敏感信息误写入配置仓库Context 配置里经常包含DATABASE_URL这种带用户名密码的连接串。如果把 config.json 提交到 Git 仓库密码就泄露了。我在实际使用中吃过一次亏后来做了三个补救措施配置分离把所有可能含敏感信息的字段挪到~/.context-mode/secrets.json这个文件被.gitignore排除config.json 里只存储变量名引用。值校验cm validate命令会扫描配置里的 env 值如果发现形如postgres://user:password的连接串就发出警告。红acted 输出cm list --verbose输出环境变量时默认对密码部分打码只有--show-secrets才显示明文。我觉得这个问题的本质是配置文件的定位应该是可分享的项目约定不应该成为秘密仓库。如果项目确实需要分发连接信息应该走团队已有的密钥管理系统在on_enter钩子里通过命令从密钥系统拉取而不是直接写死在配置里。5.4 性能与启动开销有几个同事试用后反馈切换有延迟我分析了一下主要开销来自三块CLI 的 Python 启动时间、配置文件解析时间、以及cd之后 shell 自动触发的各种钩子比如 zsh 的 chpwd、自定义的 git status 提示。Python 从启动到执行完解析大概 50 到 80 毫秒这个基本可以接受。真正拖慢的是 shell 的 prompt 渲染。因为我的提示符里加了 git 分支显示每次cd都会触发一次 git 命令。优化思路有三个把prompt的渲染放在后台用异步更新的方式避免每次提示符都阻塞等待 git。在on_enter钩子里加一个预热 git 分支缓存的逻辑让切换后第一次提示符迅速出现。如果完全不在乎 prompt 显示可以只显示 context 名不做 git 集成。实际上context 切换的体感和终端本身的速度关系很大。在 macOS 的默认终端里整体启动延迟比较明显换到更轻量的终端模拟器之后切换体验流畅很多。我一般建议使用者关注切换动作是否超过 200 毫秒超过就排查钩子没超过就无需折腾。最后再分享一个让我觉得这工具真正值回票价的小技巧。我把自己常用的几个上下文做成了像工作台一样的组合早上打开终端先cm use office这个 context 会自动 cd 到工作目录、加载项目变量、启动必要的本地服务然后我把ai_context输出到固定的临时文件供 AI 工具持续读取。下午切换到cm use side-project所有状态又立刻变成另一个完全不同但同样完备的现场。以前要在两个项目间切换需要手动停服务、改环境变量、重新开窗口现在只需要一条命令。根据我个人这几个月使用的体会把上下文做成显式的、可管理的东西省下来的不只是敲命令的几秒钟而是每次切换后的重新定位成本——这种无声的效率提升才是这类小工具真正值得打磨的地方。