说实话一开始做这个工具的时候我并没有打算把它当个项目来做。当时手头同时维护着三个项目一个是内部管理系统一个是给客户端写的 SDK 示例库还有一个是个人博客的改造。每个项目的目录结构、格式化规范、需要注入给 AI 编程助手的项目说明甚至终端里的提示符风格都不一样。我每天的状态就是切目录 → 改环境变量 → 翻 README 确认约定 → 复制一份项目说明贴给 AI 助手 → 开始干活。切到下一个项目重复一遍。中间只要漏一步轻则 linter 报错刷屏重则把测试环境的配置打到生产目录里。后来我实在受不了了花了两个晚上写了一个叫 context-mode 的小工具。它的核心思路很简单把项目上下文做成可切换、可继承、可自动加载的配置文件进入目录即生效。这篇文章我尽量把设计思路、实现细节、踩过的坑都写清楚希望能给同样被上下文碎片化折磨的人一点参考。1. 先厘清问题我们说的上下文到底指什么动手写代码之前我花了很长一段时间去定义上下文这个词。因为如果连要解决问题的边界都不清楚工具很容易做成一个什么都做、什么都做不好的瑞士军刀。1.1 被分散在五六个地方的隐性信息以我当时的日常开发为例一个项目的上下文其实散落在这些地方终端环境变量NODE_ENV、API_BASE_URL、DATABASE_URL每次换项目都得手动 export更麻烦的是这些变量有时还需要区分开发、测试、预发布环境。项目约定文档README 里写的代码风格、commit 规范、目录职责说明。平时用不上但每次有新人加入或者你休假回来再看自己的代码时这些信息就变得特别重要。给 AI 助手注入的提示词当时我在尝试用 AI 辅助写代码但每次都得把项目的技术栈、目录结构、编码规范贴进对话里。对话一长AI 就忘了前面的约束还得重新贴。编辑器/终端配置比如 Prettier 的 printWidth、eslint 的规则集。虽然项目里通常有配置文件但有些团队规范不属于某个具体工具而是人的约定。运行脚本与启动方式启动开发服务器是npm run dev还是make serve测试命令是什么这些信息通常埋在 package.json 或 Makefile 里但查找成本不低。这些信息并不是不存在而是太分散了。分散带来的问题就是每次切换项目你都要重新人肉加载一遍。而人最擅长的事情就是忘记加载。1.2 为什么简单的 dotenv 方案不够用可能你会说用 direnv 或者 dotenv 不就解决了吗我在初期确实试过这两条路但它们解决的是不同层面的问题。direnv 解决的是环境变量随目录自动加载的问题它能在你cd进目录时自动执行.envrc里的脚本。这很强大但也意味着它把执行任意 shell 代码的权力交给你如果配置不当很容易出现进了目录就莫名其妙多了几十个环境变量的情况排查起来很痛苦。dotenv 解决的是把配置写进.env文件的问题但它本身不会自动化你必须依赖框架的支持或者自己在启动时手动加载。而且.env文件通常承担不了项目约定文档和AI 提示词这种文本型上下文的职责。我需要的是一个更完整的抽象context-mode 应该管理进入一个项目时我需要让哪些东西处于正确状态这一整件事环境变量只是其中一部分。1.3 我对 context-mode 的定义经过两天的折腾和思考我把 context-mode 的定义收敛成一句话一个轻量的、基于目录切换的上下文管理器。它允许你为每个项目或全局环境定义一组上下文配置包括环境变量、项目说明文本、目录别名、启动命令模板然后在进入项目目录时自动加载并生效。这个定义有几个关键点基于目录切换触发不是手动 source也不是启动时读取而是通过监听cd操作触发加载。配置是声明式的用 YAML而不是 Shell 脚本。这样可读性好也能在加载前做校验。不只管环境变量还包括文本型的上下文项目说明、可复用的命令。这给后面接入 AI 助手留了接口。2. 核心设计配置结构、优先级与加载时机定义清楚问题之后设计就变得顺理成章了。但真正实现的时候还是有几个设计决策花了比较多的时间这里逐一说明。2.1 三层的配置结构我把配置分成三层分别存储在不同的位置层级存储位置作用范围典型用途全局层~/.context-mode/global.yaml所有项目通用环境变量如EDITOR、个人偏好用户层~/.context-mode/users/用户名.yaml当前用户的个人项目个人开发机的专属配置不入库项目层项目根/.ctx/config.yaml当前项目项目相关的环境变量、说明、命令模板全局层和用户层的区别在于如果一台开发机只有你在用这两层其实可以合并。但如果存在多用户共用开发机或者你需要把个人配置和机器配置分开管理的场景区分开来会有帮助。我认识的一些团队会把用户层的配置模板放进 dotfiles 仓库管理项目层的配置则要求项目成员统一维护。2.2 配置文件的字段设计每个配置文件的核心结构长这样version: 1 name: my-project env: NODE_ENV: development API_BASE_URL: http://localhost:3000/api LOG_LEVEL: debug texts: ai_context: | 这是一个基于 FastAPI React 的项目。 后端代码在 app/ 目录下前端在 frontend/ 目录下。 提交信息请使用 conventional commits 规范。 不要修改 database/migrations/ 下已有的迁移文件。 commands: dev: npm run dev test: npm run test -- --watch lint: npm run lint:fix aliases: dc: docker-compose shell: prompt_prefix: my-projectenv 字段用于注入环境变量texts 字段用于存储任意文本段落ai_context是我专门给 AI 助手用的commands 字段定义常用的项目命令aliases 定义终端别名shell.prompt_prefix 用来修改终端提示符让你一眼知道自己当前在哪个项目里。2.3 优先级规则小范围覆盖大范围三层配置之间的优先级很明确项目层 用户层 全局层这个规则的含义是项目层的同名环境变量会覆盖用户层和全局层的定义。这么设计的逻辑很简单——离项目越近的配置对项目的了解越准确。全局层定义的API_BASE_URL是通用默认值但项目 A 可能有自己的 API 地址这时候项目层的配置必须获胜。在实际实现中我采用的是逐层合并的策略先读全局层再读用户层最后读项目层同名字段后读的覆盖先读的。YAML 文件之间的嵌套结构比如命令和别名也遵循同样的规则但环境变量层面因为不存在嵌套覆盖逻辑更简单直接。2.4 加载时机shell hook 的设计要让进入目录自动生效落地必须和 shell 集成。在 bash 和 zsh 中都有现成的chpwd钩子机制可以在目录切换后触发自定义函数。但在实现细节上有一个很容易被忽略的问题hook 里不能直接修改当前 shell 的环境变量。如果你在 hook 里面写export FOObar其实是在子 shell 里执行的对当前 shell 完全不生效。所以正确的做法是hook 函数把需要导出的变量作为字符串输出然后通过eval在当前 shell 里执行。我最终的方案是# 在 .bashrc 或 .zshrc 中 _context_mode_hook() { local output output$(context-mode apply --export 2/dev/null) if [ -n $output ]; then eval $output fi } # 定义 PROMPT_COMMAND 或者在 zsh 中用 add-zsh-hook if [ -n $ZSH_VERSION ]; then autoload -Uz add-zsh-hook add-zsh-hook chpwd _context_mode_hook else PROMPT_COMMAND_context_mode_hook; $PROMPT_COMMAND fi # 初始加载 _context_mode_hookcontext-mode apply --export命令会输出类似export NODE_ENVdevelopment; export API_BASE_URL...;的片段然后由 hook 里的eval真正执行。3. 从零实现核心逻辑其实只有两百行整个工具的核心逻辑并不复杂我把代码量控制在一千行以内。这里只讲几个关键的实现点。3.1 目录搜索向上查找 .ctx 目录context-mode 的apply命令第一步是定位当前目录所属的项目根。做法是从当前目录开始逐级向上查找.ctx目录找到的第一个就是项目配置。from pathlib import Path def find_project_root(start: Path) - Path | None: current start.resolve() while True: if (current / .ctx / config.yaml).exists(): return current if current.parent current: return None current current.parent这段代码要注意两个点先resolve()再开始查找避免路径里有..或符号链接导致查找路径和实际路径不一致。边界条件current.parent current说明已经到根目录必须终止循环否则会无限循环。如果找到项目根就加载项目层配置否则只加载全局层和用户层配置。3.2 变量展开支持嵌套引用环境变量之间有时会互相引用。比如你配置一个BASE_URL然后API_URL基于它拼接env: BASE_URL: http://localhost:8080 API_URL: ${BASE_URL}/api这里需要支持${VAR}的占位符展开。实现上我用正则找出所有占位符然后递归查询import re from typing import Dict ENV_RE re.compile(r\$\{([^}])\}) def expand_env_vars(value: str, env: Dict[str, str], stack: set) - str: def replacer(match): key match.group(1) if key in stack: raise ValueError(fcircular reference detected: {key}) if key not in env: return match.group(0) stack.add(key) expanded expand_env_vars(env[key], env, stack) stack.remove(key) return expanded return ENV_RE.sub(replacer, value)注意我用了一个stack集合来检测循环引用。如果两个变量互相引用简单的递归展开会死循环这个检测能在第一时间报错而不是等到栈溢出。3.3 输出的几种模式apply命令根据不同的使用场景输出不同的格式。这是上下文切换工具能不能融入工作流的关键。# apply.py def generate_exports(merged: dict) - str: lines [] for key, value in merged[env].items(): escaped value.replace(, \\) lines.append(fexport {key}{escaped};) return \n.join(lines) def generate_json(merged: dict) - str: import json return json.dumps({ env: merged[env], texts: merged[texts], commands: merged[commands], }, ensure_asciiFalse, indent2)--export给 shell hook 用--json给其他程序比如 TextMate 插件、CI 脚本、AI 辅助工具用。后面我会讲到这个--json输出后来成了接入 AI 助手的关键接口。3.4 解释为什么不用配置文件驱动 hook有人可能会问既然要执行 shell 层面的操作比如设置 aliases为什么不直接在.ctx/config.yaml里允许写 shell 代码然后 source 它我最初确实想过这种方案但很快否定了。原因有三安全性如果项目层的配置可以写任意 shell 代码那么克隆一个恶意仓库进到目录就执行了恶意脚本这是巨大的安全风险。声明式配置没有这个问题最多是设置一些环境变量和别名。可移植性Shell 脚本天然依赖当前 shell 的类型和机器环境声明式配置可以跨 shell、跨平台复用。可校验性YAML 结构可以被解析和检查shell 脚本则很难静态分析。所以 context-mode 的设计原则是状态变更全部通过 export 和 alias 白名单实现不让配置直接接触 shell。4. 实测场景三种用法把上下文真正串起来工具写完之后我在自己的开发环境里用了一周期间不断调整。这里分享三个最典型的实测场景以及效果。4.1 场景一AI 编程助理的上下文注入这个场景应该是最多人需要的。我用 AI 辅助写代码时最大的痛点就是它不记得项目约定。每次开新对话都要重新贴一遍项目说明贴得不够详细时它就会给出不符合项目风格的代码。有了 context-mode 之后我写了一个小脚本ctx-ai#!/usr/bin/env bash # 将项目上下文输出为适合粘贴给 AI 助手的文本 context-mode apply --json | plutil -convert raw -r -o - 2/dev/null || \ context-mode apply --json | python3 -c import json, sys ctx json.load(sys.stdin) for key, text in ctx[texts].items(): print(f {key} ) print(text) print() 然后在 AI 助手的 Custom Instructions 或者每次对话开始时先粘贴ctx-ai的输出。实测体验是AI 对项目结构的理解、代码风格的遵循程度明显提升因为上下文说明里写清楚了前端在什么目录后端 API 使用什么框架不要修改哪个目录下的文件这些关键约束。这个场景的核心价值不在于省了几行字而是让 AI 的回复质量从一开始就基于正确的上下文而不是靠它猜。后来我还做了一步自动化的尝试写了一个代理脚本把ctx-ai的输出自动拼接到发送给 AI API 的请求里。这个已经脱离了 context-mode 本身的功能范围但也验证了--json输出作为接口的包容性。4.2 场景二多项目环境变量自动切换第二个直接受益的场景是多项目并行开发时的环境变量混乱问题。之前的情况是项目 A 需要NODE_ENVstaging项目 B 需要NODE_ENVdevelopment项目 C 需要DATABASE_URL指向本地 Postgres。一旦你忘了切换就可能把 staging 的配置用在 development 的项目里。虽然不至于出大事故但排查起来很费时间。配好 context-mode 后的流程变成了# 项目 A 的 .ctx/config.yaml env: NODE_ENV: staging API_BASE_URL: https://staging.example.com DATABASE_URL: postgres://localhost:5432/project_a_staging # 项目 B 的 .ctx/config.yaml env: NODE_ENV: development API_BASE_URL: http://localhost:3000 DATABASE_URL: postgres://localhost:5432/project_b_dev切换目录的瞬间环境变量就自动变成对应项目的值再也不用手动 export。我还特意在shell.prompt_prefix里配置了项目缩写终端提示符会显示[proj-a] ➜ src/这样的格式低头看一眼就知道自己在哪。这里额外分享一个细节环境变量写进配置文件之后项目之间的隔离性会变强但也要注意同一个变量在不同项目里的值是否有潜在冲突。比如两个项目都定义了PORT如果你在 global 层也定义了PORT8080最后生效的是项目层的值。相反如果某个项目没定义PORTglobal 层的8080就会泄漏进去。所以我的建议是global 层只放真正通用的变量比如EDITOR、LANG不要放可能因项目而异的变量。4.3 场景三新成员上手与团队约定沉淀第三个场景属于长期价值向的。对于团队项目context-mode的项目配置文件可以作为机器可读的 README存在。新成员克隆仓库后只要安装 context-mode 并进到项目目录环境变量、启动命令说明都会自动就位。为了这个场景我后来又给配置文件增加了一个字段docs: overview: | 本项目用于处理用户订单的生命周期管理。 包含订单创建、支付回调、库存扣减、售后流程。 技术栈Spring Boot 3 MySQL 8 Redis。 onboarding: | 1. 本地启动依赖docker-compose up -d mysql redis 2. 复制 application.dev.yaml 并修改数据库密码 3. 访问 http://localhost:8080/actuator/health 确认服务启动新成员可以用context-mode doc onboarding快速看到上手指引也可以直接用context-mode text ai_context输出给 AI 助手。这实际上把项目经验从一个不可查询的 Word 文档变成了结构化的、可以自动加载的资产。5. 踩坑记录这些问题没试过真的想不到我前面说核心逻辑只有两百行但真正把它接入日常开发流程时是花了一半以上的时间在解决各种边缘问题。这些坑不一定都能通过代码逻辑规避但提前知道可以让后来者少走弯路。5.1 shell hook 的环境变量导出时机最典型的坑就是我之前提到的子 shell 问题。第一次把_context_mode_hook的函数写好后我在代码里直接调用os.environ[FOO] bar然后发现当前 shell 一点反应都没有。排查了半天才意识到context-mode是一个独立进程它只能修改自己的进程环境变量不能影响父进程 shell。这个问题的教训是任何外部工具都没法直接改变 shell 的环境只能通过输出文本 父 shell eval的组合拳来实现。我后来在 README 里专门用粗体强调了这一点context-mode 本身不修改环境变量它只输出你需要执行的 export 语句。5.2 eval 的安全与转义问题既然用了eval转义问题就绕不开。如果环境变量的值里带有单引号直接拼进export FOO...就会出错。我在前面代码里用了value.replace(, \\)这个技巧简单解释一下假设值里有单引号Its a test。直接拼export FOOIts a test是错误的因为 shell 会把字符串切成It和s a test。正确的做法是用\来表示一个转义的单引号。替换后的结果是export FOOIt\s a test;。这个写法虽然看起来很丑但确实是 shell 中安全的单引号转义方案。后来我还遇到了值里包含$的坑。比如某个密码是pa$$word如果用双引号包会触发变量展开必须用单引号包。这也是我坚持在generate_exports里用单引号包裹所有值的原因。5.3 符号链接目录的根查找find_project_root里我特意用了resolve()这源于一次实际遇到的问题。我的项目目录是一个符号链接指向挂在别的盘符下的真实目录。第一次实现时我没有 resolve导致符号链接路径下解析出的项目配置路径和实际路径不一致出现了能找到配置文件但加载失败的诡异情况。resolve()会把符号链接解析成真实路径这样目录查找和配置文件读取都在同一套路径体系下进行问题就消失了。副作用是如果同一个真实目录有两个符号链接指向它用不同链接进入时context-mode 感知到的项目根是同一个真实目录这是预期行为因为配置文件本身就在真实目录下。5.4 hook 重入保护还有一个必须处理的细节hook 自身的触发时机。_context_mode_hook被定义在PROMPT_COMMAND里这意味着每次终端显示提示符之前都会调用一次。当context-mode apply --export输出的内容很多时可能会导致终端每次都执行一长串 export体验很差。更严重的问题是潜在的死循环如果在配置的环境变量里包含了一个会触发 hook 的操作不太可能但理论上存在或者 eval 的执行本身又改变了目录就可能触发递归调用。解决方案是加一个简单的重入保护_CONTEXT_MODE_LAST_DIR _context_mode_hook() { local current_dir$PWD if [ $current_dir $_CONTEXT_MODE_LAST_DIR ]; then return 0 fi _CONTEXT_MODE_LAST_DIR$current_dir # ... 实际逻辑 }这个值记录了上次应用的目录只有目录变化时才重新执行 apply。这既避免了重复 export也在很大程度上防止了重入。5.5 变量展开的循环引用检测前面提到过expand_env_vars函数的stack参数这是实际踩坑后才加的。一开始我的实现很简单直接递归展开def expand_env_vars(value, env): return ENV_RE.sub(lambda m: env.get(m.group(1), m.group(0)), value)直到某天我在配置文件里误写了一个自引用env: FOO: ${FOO}-suffix然后apply命令就栈溢出崩溃了。排查过程倒是很直观但加一个循环引用检测也让工具在面对更复杂的错误配置时更加健壮。5.6 YAML 解析中的类型陷阱YAML 解析有个经典坑NODE_ENV: true如果写成NODE_ENV: true解析出来的就是一个布尔值而不是字符串。这会导致环境变量变成export NODE_ENVtrue看起来没区别但某些框架做字符串比较时可能出问题。为了避免这种隐式类型转换我在解析后的校验阶段做了一步强制类型转换所有 env 字段的值都必须解析为字符串如果不是字符串就显式转换成字符串并给出一个警告。虽然这只是一个小小的防御措施但避免了大量由类型歧义导致的诡异 bug。5.7 与 direnv 共存的冲突处理在我用上 context-mode 之前部分项目已经在用 direnv。两者同时存在时优先级可能会打架。我的选择是context-mode 只负责管理环境变量direnv 负责执行复杂的 shell 级操作。规则是如果项目根目录存在.ctx/config.yamlcontext-mode 的配置优先生效direnv的.envrc可以往后放。实现方式是在apply函数里显式检查.envrc的存在并在输出中优先生成 context-mode 的 export。这种做法不一定适合所有人但至少在我的环境里它提供了一个清晰的迁移路径。6. 进阶优化让 context-mode 更贴合日常使用基础功能完成之后我又加了几个提升体验的小功能这里挑两个最有用的展开讲。6.1 动态变量与系统信息有些场景下环境变量的值需要依赖当前系统状态。比如开发时你需要把本机的局域网 IP 注入到环境变量或者根据当前 git 分支动态切换环境。我在配置里支持了${ctx:git_branch}和${ctx:hostname}这类动态变量env: GIT_BRANCH: ${ctx:git_branch} HOST_IP: ${ctx:lan_ip}这些变量在处理时就近展开def resolve_dynamic(key: str) - str: if key ctx:git_branch: import subprocess return subprocess.check_output( [git, rev-parse, --abbrev-ref, HEAD], stderrsubprocess.DEVNULL ).decode().strip() if key ctx:hostname: import socket return socket.gethostname() if key ctx:lan_ip: # 简化实现从 socket 推断 import socket s socket.socket(socket.AF_INET, socket.SOCK_DGRAM) try: s.connect((8.8.8.8, 80)) return s.getsockname()[0] finally: s.close() return f${{{key}}}这里特别注意ctx:git_branch的执行依赖当前目录在 git 仓库内如果不在仓库内会抛异常所以要捕获异常并返回空字符串。这种功能看起来华而不实但在多分支并行开发的工作流里非常实用比如你切到release分支时环境变量能自动变成生产配置。6.2 按场景加载子组还有一个常用场景同一个项目开发环境和测试环境需要不同的环境变量。虽然可以直接在项目层的 env 里写死但更优雅的方式是支持场景子组scenes: dev: env: API_BASE_URL: http://localhost:3000 DEBUG: true test: env: API_BASE_URL: https://test.example.com DEBUG: false active_scene: dev使用context-mode apply --scene test可以临时切换到 test 场景默认使用active_scene里指定的场景。这个设计在测试 API 集成时特别有用避免为了切换场景而反复编辑配置文件。6.3 与编辑器/IDE 的协作我使用 context-mode 的方式不止在终端里还通过输出 JSON 喂给编辑器脚本。举个例子在我的 Neovim 配置里有一个 Lua 脚本会在加载项目文件时读取context-mode apply --json的输出动态设置 pylsp 的路径参数和 flake8 的 max-line-length。这样同一份配置同时服务于终端和编辑器真正做到一处配置、处处生效。类似地VS Code 用户可以在.vscode/settings.json里引用环境变量{ python.analysis.extraPaths: [ ${env:PROJECT_SRC_PATH} ] }前提是 VS Code 的终端里环境变量已经被 context-mode 注入过了。如果是从 GUI 启动的 VS Code那么需要通过 shell 启动 VS Code或者在.vscode/settings.json里改用context-mode apply --json的输出。7. 最后再聊几点维护心得工具用了大概半个月之后我停下来回看整个从零搭建的过程有几个认知层面的收获值得记录。第一工具的价值在于减少切换成本而不是减少配置成本。一开始我花了很大精力去美化配置文件结构、简化 YAML 语法后来发现在实际使用中配置一次的成本并不高真正高的是每次切换项目时重新加载脑内上下文的成本。所以 context-mode 的核心必须放在加载要快、要准、要自动而不是一味追求配置的多功能性。第二声明式配置的边界就是工具的边界。当用户想在配置文件里写 shell 脚本来实现进入目录就做一堆事情时最好停下来想一想这事应该由更通用的工具比如 Makefile、脚本来负责塞进 context-mode 只会增加维护复杂度。我现在的原则是环境变量、文本说明、别名这些状态交给 context-mode操作逻辑、流程控制这些行为交给项目自己的自动化脚本。第三安全边界一定要硬。既然 context-mode 可以注入环境变量那就意味着它有能力影响项目进程的行为。如果项目层配置能被不怀好意的人改动那就可能注入恶意变量。所以我现在只从可信来源克隆仓库同时会在apply之前校验配置文件哈希项目维护者可以把预期哈希写在.ctx/checksum文件中。这个机制虽然增加了一些流程负担但对于团队协作场景我认为是必要的。最后再分享一个小技巧如果你也和我一样经常用 AI 辅助编程建议在texts.ai_context里不仅写项目技术栈还要写清楚这个项目不做什么。比如本项目不做用户注册模块统一走 SSO不要在 service 层直接操作数据库请走 repository 层。这些负面约束往往比正面约束更能提升 AI 输出的准确性。我实测下来加了这些约束之后AI 生成的代码方向明显更符合团队的实际预期。context-mode 这个项目目前还在持续迭代不过它的核心价值已经被验证了当你把所有隐性上下文都显式化、自动化之后无论是在终端命令、IDE 配置还是 AI 协作场景整个开发体验都会顺畅很多。有类似困扰的朋友不妨试试类似的思路不一定要用我这个工具但把项目上下文管理起来这件事绝对值得投入时间。