1. 先搞清楚 context-mode 到底解决什么问题
老实说，我第一次在工具链里看到context-mode这个参数时，第一反应是"又一个装腔作势的配置项"。但真把它用起来之后，我反而觉得这个名字起得相当准——它不是在堆功能，而是在管一件事：你的开发环境、AI 助手、脚本工具，到底应该基于哪一段上下文来做判断。
你可以想象这样一个日常场景：电脑上同时开着公司项目、个人开源项目、还有临时写的小脚本，三个终端窗口里各跑着不同任务的日志，Cursor 里还挂着两个代码库的索引。这时候你问 AI"帮我改一下那个登录超时逻辑"，它大概率会给你翻错仓库，或者把 A 项目里改过的变量名塞进 B 项目里。这真不怪模型笨，问题出在上下文——你给了它一个"混合模式"的输入，它只能给你一个"混合模式"的答案。
context-mode要解决的就是这个混乱。它把工具的运行方式从"一次配置，到处生效"改成"一个上下文，一套行为"：你切到前端项目，它就带着前端项目的目录结构、依赖清单、最近变更记录去思考；你切到数据分析脚本，它就自动切换成"只看这几个文件、只关心这类报错"的模式。说得直白点，它就像给每个任务建了一个独立的隔间，而不是让所有任务在同一个大通铺里互相串味。
这个内容适合谁？如果你是重度 AI 辅助编程的开发者、经常在多个仓库之间横跳的全栈工程师、或者正在做内部工具/CLI 的团队，那这篇文章能帮你省下大量"答非所问"和"改错文件"的时间。就算你只是偶尔用脚本处理文件，理解 context-mode 的思路也能让你少写很多if else来判断"当前到底在哪干活"。
2. 上下文模式的核心设计：三种模式怎么选
既然叫 context-mode，那最核心的问题自然是：上下文到底有哪些模式可选、它们之间的边界在哪。别小看这一步，我见过太多人一上来就堆代码，结果把上下文管理做成了永久内存，什么东西都往里塞，最后工具反而因为"太懂你"而频繁误判。
2.1 strict 模式：只看眼前这一亩三分地
第一种模式是 strict，也就是严格局部模式。工具只读取当前目录、当前打开的文件、或者当前命令里明确指定的输入，绝不主动去翻仓库历史、去读无关配置文件。
它的优点非常直接：上下文小、响应快、不容易跑偏。比如你在调一个fetchData函数，strict 模式下 AI 就只看这个文件和它的直接依赖，不会突然拿三个月前的一次重构来"提醒"你。缺点是显而易见的——当问题跨文件、跨模块时，strict 模式会显得目光短浅，给不出整体方案。
我用一个生活化的类比：strict 模式就像你在厨房里炒菜，只看面前这口锅和手边的调料。锅里的情况你一清二楚，但如果要问你"冰箱里还剩什么菜"，你就答不上来了。
2.2 repo 模式：带上整个仓库的地图和索引
第二种模式是 repo，也叫仓库级上下文模式。它会读取当前仓库的目录结构、关键索引文件、最近的 git 变更、甚至项目里的 README 和架构文档，然后把压缩后的"仓库地图"作为上下文输入。
这个模式的典型场景是跨文件重构：比如你要把某条请求链路从 REST 改成 RPC，strict 模式根本无能为力，repo 模式却能先看清相关模块在哪里、依赖关系长什么样，再给出一个贯通前后的方案。代价也很实在：token 消耗大、响应变慢、偶尔会被无关文件干扰判断。所以 repo 模式更适合作一次性的"大手术"，而不是每敲一行代码都开启。
2.3 auto 模式：让工具自己决定看多少
第三种是 auto，也就是自动混合模式。它介于 strict 和 repo 之间，工具会根据当前问题自动判断需要多大的上下文范围：简单问题只取相关文件，复杂问题自动扩展到仓库索引。
auto 模式听着最完美，但它其实是最难做好的。因为它背后需要一层"意图识别"逻辑，判断用户问到的是局部问题还是全局问题，这个逻辑写得不仔细，就会变成"时灵时不灵"。我在实践里的做法是：把 auto 当作默认入口，但在命令里显式提供--strict和--repo覆盖开关。这样既能享受自动模式的便利，又在关键场景保留手动控制权。
| 模式 | 上下文范围 | 响应速度 | 误判风险 | 适用场景 |
|---|---|---|---|---|
| strict | 当前文件/标准输入 | 最快 | 低 | 小函数调试、单文件修改 |
| repo | 仓库索引+git+文档 | 较慢 | 中 | 跨文件重构、技术方案设计 |
| auto | 由工具自动判断 | 中等 | 需调优 | 日常高频开发 |
3. 实操：从零搭一个 context-mode 脚本
下面这部分我直接摊牌：与其找一个现成的重型框架，我建议你先手写一个几十行的 context-mode 脚本，把原理跑通，再决定要不要上更复杂的方案。我自己维护的这个工具叫ctx，核心逻辑就三个文件，放在~/.ctx/下，全项目加起来不到 300 行。
3.1 需求拆解：context-mode 最少要干四件事
在写代码之前，先想清楚工具必须具备哪些能力：
- 保存上下文：把当前的工作状态（目录、分支、环境变量等）保存成一个"会话"。
- 切换上下文：根据会话名加载对应状态，改变终端行为，并让其他工具能感知。
- 列出/删除上下文：方便管理多个会话，避免越攒越多。
- 导出上下文：把当前上下文的内容整理成文件或文本，方便喂给 AI 助手。
我不建议一上来就做云同步、团队共享、界面 GUI，这些都不是 context-mode 的必需品。先解决单机、单人、终端场景的需求，工具才会真的被用起来。
3.2 数据模型与存储设计
context 本质上是"名称到状态快照"的映射。我用一个 JSON 文件来做存储，路径是~/.ctx/contexts.json。每个上下文记录包含这些字段：
{ "name": "blog-project", "cwd": "/home/dev/workspace/blog", "branch": "feature/context-mode", "env": { "NODE_ENV": "development", "APP_PROFILE": "local" }, "ai_prompt": "你现在是我的博客项目助手，回答问题时优先参考 docs 目录下的设计方案。", "updated_at": "2025-01-18T10:24:00+08:00" }这里关键的不是字段多少，而是你要明确：哪些状态需要"记忆"，哪些状态需要"忽略"。比如cwd和branch每次切换时必须恢复；env里只挑会影响运行行为的变量；ai_prompt是用来描述当前任务的说明文字，这玩意儿在 AI 时代比环境变量还有用。
存储格式选 JSON 是因为调试方便、任何语言都能解析。如果你担心并发写入问题，可以给文件加个简单的锁，或者直接在命令执行时用flock包一层，实测下来足够稳。
3.3 核心命令的实现思路
有了数据模型，命令实现就是体力活。我贴一下关键代码片段，你可以直接照着改造。
切换上下文（ctx use）：
function ctx_use() { local name="$1" local store="$HOME/.ctx/contexts.json" if [ ! -f "$store" ]; then echo "context store not found, run: ctx save <name> first" return 1 fi local cwd cwd=$(python3 -c " import json,sys data=json.load(open('$HOME/.ctx/contexts.json')) ctx=data.get('$name') if not ctx: sys.exit(1) print(ctx['cwd']) " 2>/dev/null) if [ -z "$cwd" ]; then echo "context [$name] not found" return 1 fi cd "$cwd" || return 1 export CTX_MODE="$name" # 读取该上下文对应的环境变量 eval "$(python3 -c " import json data=json.load(open('$HOME/.ctx/contexts.json')) ctx=data['$name'] for k,v in ctx.get('env', {}).items(): print(f'export {k}={json.dumps(v)}') ")" # 把 AI prompt 写入临时文件，后续脚本可以读取 python3 -c " import json data=json.load(open('$HOME/.ctx/contexts.json')) ctx=data['$name'] print(ctx.get('ai_prompt', '')) " > "$HOME/.ctx/current_prompt.txt" echo "switched to context [$name]" }保存上下文（ctx save）：
function ctx_save() { local name="$1" local store="$HOME/.ctx/contexts.json" local tmp="$HOME/.ctx/contexts.tmp.json" mkdir -p "$HOME/.ctx" python3 - "$name" <<'PY' import json, os, sys name = sys.argv[1] store = os.path.expanduser("~/.ctx/contexts.json") try: with open(store) as f: data = json.load(f) except FileNotFoundError: data = {} data[name] = { "name": name, "cwd": os.getcwd(), "branch": os.popen("git rev-parse --abbrev-ref HEAD 2>/dev/null").read().strip() or "not-git", "env": {k: os.environ[k] for k in ["NODE_ENV", "APP_PROFILE"] if k in os.environ}, "updated_at": __import__("datetime").datetime.now().isoformat() } with open(os.path.expanduser("~/.ctx/contexts.tmp.json"), "w") as f: json.dump(data, f, indent=2, ensure_ascii=False) os.replace(os.path.expanduser("~/.ctx/contexts.tmp.json"), store) print(f"context [{name}] saved") PY }这段代码里有一个很容易踩的坑：写入 JSON 时不要直接覆盖原文件。如果脚本中途报错，你的 contexts.json 就直接崩了。我改成先写临时文件再用os.replace原子替换，这个习惯建议保持，反正只多两行。
3.4 把这些命令挂到 shell 生命周期里
命令写出来之后，还得让它们"自动发生"。我觉得 context-mode 最大的价值不在于手动切来切去，而在于你一进入某个目录，它就是那个上下文。
方法很简单：在.bashrc或.zshrc里注册一个PROMPT_COMMAND钩子，每次终端执行命令前检查当前目录是否关联了已保存的 context。如果关联了，就自动加载；没关联，就保持默认状态。
update_current_ctx() { local store="$HOME/.ctx/contexts.json" local map_file="$HOME/.ctx/dir_ctx_map.json" [ -f "$map_file" ] || return 0 local ctx_name ctx_name=$(python3 -c " import json, os map_data=json.load(open('$HOME/.ctx/dir_ctx_map.json')) cwd=os.getcwd() # 使用最长前缀匹配 best = None for prefix, name in map_data.items(): if cwd.startswith(prefix): if best is None or len(prefix) > len(best[0]): best = (prefix, name) if best: print(best[1]) " 2>/dev/null) if [ -n "$ctx_name" ] && [ "$ctx_name" != "$__CTX_CURRENT" ]; then ctx_use "$ctx_name" __CTX_CURRENT="$ctx_name" fi } PROMPT_COMMAND="update_current_ctx; $PROMPT_COMMAND"这段逻辑容易忽略的是"防抖"：如果你每次回车都去执行完整的ctx_use，终端会明显卡顿。所以我用一个__CTX_CURRENT变量记住当前已经加载的上下文，只有切换目标发生变化时才真正执行加载。
4. 把 context-mode 注入 AI 编程工作流
如果说前面这些命令还只是"自嗨型效率工具"，那真正让 context-mode 发挥十倍价值的，是把它和 AI 编程助手联动起来。这个年头谁还没用过 AI 写代码，但绝大多数人用不好 AI 的根本原因，就是不会喂上下文。
4.1 手动粘贴已经是过去式
我见过很多同事的常规操作：把一堆文件内容复制粘贴给对话窗口，然后开始提问。这种操作有两个致命问题——第一，复制的内容往往超出模型窗口上限，聊到一半就开始丢上下文；第二，你复制的未必是模型真正需要的信息，它需要的关键线索可能恰恰没被复制过去。
context-mode 的正确姿势是：先通过 ctx 工具把当前上下文整理成一个结构化文件，再把文件内容或者路径交给 AI。我一般在 prompt 里直接写：
请先阅读 __CTX__/context.md，然后回答我的问题： 本地环境是 development 模式，当前分支是 feature/context-mode， 项目结构见 context.md 中的目录树部分。我的问题是：为什么/api/login 接口在本地返回 502？这样模型拿到的不再是一堆散装代码，而是一份"当前项目在什么状态、我看哪些文件、我要解决什么问题"的说明书。实测下来，回答的有效率至少提高一倍。
4.2 自动生成 context.md
那 context.md 怎么来？当然不能手写，我在 ctx 工具里加了一个 export 子命令，把当前 context 自动整理成 markdown 文件：
ctx export --output "$HOME/.ctx/current_ctx.md"生成的 context.md 长这样：
# Context: blog-project - 工作目录: /home/dev/workspace/blog - 当前分支: feature/context-mode - 应用环境: development ## 目录结构（最近两层） ... ## 当前 git 变更文件 ... ## 关键配置项 ...这里的实现逻辑也不复杂：目录结构用find配合-maxdepth控制层数；git 变更用git status --short；配置项则从项目的.env或配置文件里挑选非敏感字段。生成之后，AI 既能直接读全文，也能只读其中的"目录结构"小节，按需取用。
4.3 用 .ctxignore 控制上下文边界
管理上下文最让人头痛的问题不是"太少"，而是"太多"。仓库里node_modules、vendor、.git这些目录动辄几十万文件，一旦被当作文本读进去，不仅没帮助，还让模型抓不住重点。
解决办法是学习gitignore的思路，搞一个.ctxignore文件：
node_modules/ vendor/ dist/ build/ *.lock .git/在 export 目录结构时，脚本逐行读取.ctxignore，用最简单的前缀匹配把不需要的目录过滤掉。这个技巧看着不起眼，但它直接决定你的 context.md 是"项目地图"还是"垃圾堆"。我见过不少 AI 工具越用越笨，就是因为没有做上下文消解，每回都把不相关的大文件一股脑塞进去。
4.4 token 预算与注入顺序
即便有了 context.md，也还是要注意 token 预算。大模型的注意力不是平均分配的，排在前面和排在后面的内容更容易被记住，中间部分容易被忽略。
所以我在注入顺序上的建议是：
- 最前面放"任务描述"和"当前上下文一句话总结"；
- 中间放目录结构和变更文件清单；
- 最后放最核心的源码片段或报错日志。
这样模型一进来就知道自己在哪个项目、要干嘛，核心材料又是最近读到的，不容易被无关内容带跑。如果你用的是支持长上下文的模型，可以把完整 context.md 放前面，再把具体问题放最后，让它在首尾夹击之下抓住重点。
5. 常见问题与排查技巧实录
工具写完之后，真正让你头疼的往往不是功能缺失，而是一些不起眼但反复出现的毛病。我把自己用 context-mode 半年多以来踩过的坑整理成一张速查表，希望对你有实际帮助。
| 症状 | 可能原因 | 排查思路与解法 |
|---|---|---|
| 切换上下文后环境变量没变 | env字段没有匹配到变量名，或者 shell 缓冲区未刷新 | 先跑 `env |
| AI 回答的内容明显来自另一个项目 | 上下文文件没有清空，模型吃到了上一个 context 的残留 | ctx use时必须先重写current_ctx.md，不能只在原文件后追加；用ctx clear清空再切换 |
| 目录结构导出巨大、超出模型上限 | 没配置.ctxignore或者find深度太深 | 检查.ctxignore是否生效；导出时用-maxdepth 3限制，只保留有代表性的层级 |
ctx save时不定期出现 JSON 损坏 | 多终端并发写入同一个 contexts.json | 改用原子替换（先写 tmp 再os.replace）；脚本入口加flock锁 |
| 切换后 git 分支与目录不匹配 | 手动在别处git checkout过分支，context 快照过期 | ctx save时单独记录分支名；ctx use时提示分支不一致，但不强行切分支，避免丢改动 |
| 上下文文件里出现了密码等敏感信息 | export 时把.env全量写进去 | 在ctx export里使用白名单过滤：只导出键名，不导出值；或者对值做脱敏 |
这里我想特别展开第一个坑。我在初期测试时，明明ctx save存了ENABLE_X=true，切换后echo $ENABLE_X就是打不出来。排查了半天，发现问题出在 shell 函数里用eval导出变量时，值里的特殊字符被二次解析了。后来我统一改用export KEY=$(python3 输出的值)这种方式，并且所有值都用 JSON 序列化，问题才彻底解决。
5.1 串台问题的深层解法
除了上面表格里的快速处理，"串台"（上下文污染）其实值得多讲两句。根本原因在于：AI 是有状态记忆的，但你的项目状态是变化的。
举一个真实教训：一次我在 A 项目里问 AI"这个接口的鉴权方式是什么"，它回答的头头是道。过了两周，我在 B 项目里又问了同样一句话，它居然把 A 项目的鉴权方案原封不动搬了过来——因为它上下文窗口里还留着 A 项目的资料。当时我意识到，单纯"切换上下文"还不够，必须在切换动作里主动销毁旧上下文。
所以在ctx use命令里，我增加了"清理步骤"：
# 切换前清空所有 ctx 相关临时文件 rm -f "$HOME/.ctx/current_prompt.txt" rm -f "$HOME/.ctx/current_ctx.md" __CTX_CURRENT=""这行代码看起来简单，但它彻底堵住了串台漏洞。每次切换都是一次"失忆"，让 AI 只基于当前上下文的文件做判断。如果你用的是 Cursor 或 Cline 这类工具，原理也一样——通过环境变量或配置文件切换工作区，并确保会话上下文不会跨项目复用。
5.2 性能问题的取舍
有朋友问过我：每次进入目录都跑一遍ctx_use，会不会很慢？实测下来，加载 JSON、解析目录、生成 context.md，整套流程大约 200 到 400 毫秒，基本无感。但如果你的仓库非常大，find都扫不完，那确实会对终端造成卡顿。
我的处理策略是：上下文导出是异步的。终端切换 context 时只做最关键的cd和export环境变量，context.md 的生成放到后台子进程跑，生成完成后才写入目标路径。如果 AI 工具在 context.md 还没生成好时就发来请求，会让模型多等一会——但相比每次命令都阻塞，这种等待完全值得。
提示：当上下文导出包含大量文件时，可以先按文件类型过滤，只保留
.py/.ts/.go/.md/.json等文本文件，二进制文件一律跳过。这比限制目录深度更有效，因为很多大小问题是单个大文件造成的。
6. 一点收尾的经验之谈
写到这里，我并不打算做那种"今天我学会了 xxx"的总结。我更想分享的是在反复迭代 context-mode 的过程中，我自己感受最深的三条经验。
第一条：上下文管理的本质是"限制"，不是"收集"。我见过非常多的人恨不得把所有信息都喂给 AI，生怕它不知道。但实际效果恰恰相反，有效的上下文一定是有边界的。你给它一棵树的全部树叶，它反而看不清树冠的形状。
第二条：工具必须藏在工作流里，而不是放在桌面上。context-mode 如果只是又一个需要手动打开的面板，它一定会被遗忘。只有当它挂进 shell 钩子、每次cd自动切换、每次 AI 回答前自动带上项目上下文，它才真正活起来。不要嫌自动化的代码难写，这部分的投入回报率是最高的。
第三条：小步快跑比一步到位更靠谱。你完全可以先只实现ctx save和ctx use两个命令，用一周时间感受切换带来的变化，再逐步添加 env 管理、AI 注入、自动导出。我一开始也想着做一个能云端同步、支持多人协作的完整平台，幸亏没做——现在用的这套本地脚本，简洁稳定，还没那么多需要维护的依赖。
最后再送一个小技巧：在ctx use切换完后，把当前的上下文名打印在终端提示符里，就像(blog-project) ~/workspace/blog $这样。这比任何文档都直观，你永远知道自己现在处于哪个上下文里，也不会再出现"我在哪、我要改哪个文件"的恍惚感。
