最近大半年，我一直在折腾一个叫 context-mode 的小工具。起因很简单：我手上同时维护着一个工具链项目、几个内容脚本和一个半死不活的小网站，每次从一套逻辑切到另一套逻辑，都要重新找对应的提示词、重新核对文件路径、重新回忆当时跟同事约定的输出格式。最崩溃的一次，我在 AI 助手里填了整整一版 A 项目的上下文，结果把 B 项目的问题发进去，它一本正经地用 A 项目的规范和目录结构回答我，整个对话直接报废。就是从那天起，我决定把“当前我在做什么事情、这个任务需要知道哪些背景、输出必须遵守什么规则”做成可以一键切换的模式，也就是 context-mode。
这篇文章会把从设计到落地这段过程完整盘一遍，包括模式怎么定义、切换逻辑怎么写、怎么和编辑器以及 AI 助手打通，还有我踩过的几个坑。如果你也有多任务并行导致上下文错乱的痛感，可以直接照着搭一套，半天就能上手。
1. 为什么需要 context-mode：动手之前先理清痛点
1.1 多任务切换的隐性成本不在“动作”而在“记忆”
很多人觉得多任务切换的麻烦无非是打开几个目录、切几个标签页，最多改一下环境变量。但真正恼人的不是这些动作，而是大脑和工具里残留的“记忆”。比如我写脚本的时候，脑子里装的是代码风格、接口文档、目录约定；转头去改一个小程序页面的时候，这些记忆不会自动清空，反而会干扰判断。工具也一样，进程还在、环境变量还在、AI 对话历史还在，它们都在用上一套认知来处理新任务。
所以 context-mode 想解决的第一件事，不是“怎么切得更快”，而是“切完之后，旧任务留下的语义影响怎么彻底剥离”。这也是它跟普通配置文件、普通脚本的差别：它管的是上下文本身，不只是值。
1.2 上下文不等于环境变量，更不等于一堆文件夹
刚开始我的思路也很朴素，觉得写几个 alias 命令，切目录的时候顺手 export 几个变量就够了。但用了几天就发现不对劲，环境变量只能存键值对，存不了“规则”，也存不了“这段任务需要在 AI 对话里遵循的表达方式”。更麻烦的是，环境变量不区分模式，切来切去很容易串。
后来又试过把不同任务放在不同终端会话里管理，但终端的隔离解决不了内容层面的混乱，我在 A 终端照样可以打开 B 项目的文件，AI 助手也不会因为你换了终端就变聪明。真正靠谱的粒度是把“上下文”抽象成模式：一个模式是一套完整的任务上下文，包含变量、文件集合、规则、提示词模板，甚至默认的输出风格。切换模式就是整包替换，不是改几个参数。
1.3 一个模式要能覆盖“人脑 + 工具 + AI”三类上下文
设计的时候我把上下文拆成了三类。第一类是给人看的，比如当前项目的背景说明、最近进展、关键决策记录；第二类是给工具看的，比如当前应该读取哪些文件、环境变量是哪些、编译参数是什么；第三类是给 AI 助手看的，比如系统提示词、任务目标、输出格式约定、禁止事项。三类上下文用一套模式管理，才能真正做到“切换一个动作，三个层面同步刷新”。
这也是 context-mode 名字里 mode 的意义：它不是某个单一配置，而是一整套运行时状态的可切换集合。
2. 核心设计拆解：模式的组成、加载与隔离机制
2.1 模式定义：用统一结构承载所有上下文信息
我最终设计的模式清单是一个 JSON 文件，结构偏向“语义化 + 可合并”。每个模式包含基础信息、上下文片段、文件索引、环境变量和规则五块，让处理不同内容的场景都能找到对应的位置。
{ "mode": { "id": "toolchain-project", "name": "工具链开发模式", "projectRoot": "./", "scope": "toolchain" }, "context": { "snippets": [ "该项目的构建命令统一使用 build.sh，不要直接调用编译器。", "代码风格遵循仓库根目录的 .coding-style 文件中的约定。" ], "prompt_template": "你现在是一名工具链开发助手。当前工作目录是 {{projectRoot}}。请基于 {{files}} 中的内容回答问题。", "files": [ "src/main.py", "docs/architecture.md", "config/project.yaml" ], "env": { "PROJECT_MODE": "toolchain", "LOG_LEVEL": "debug" }, "rules": { "read_only_files": ["config/production.yaml"], "output_language": "中文", "required_tools": ["make", "cmake"] } } }这里有几个设计细节值得展开。snippets 是给人看的短文本，适合写在终端提示里；files 是任务需要高频访问的文件清单，用来控制 AI 助手的检索范围，避免它什么文件都翻；prompt_template 是给 AI 助手的骨架文本，里面留了插槽，加载的时候会把其他字段填进去；rules 是输出约束，我踩过不少次“AI 答得好好的就是不按规矩输出”的坑，最后靠 rules 字段把硬性约束固定下来。
2.2 模式加载与释放：保证上下文不残留
模式定义好之后，最关键的机制是加载和释放。加载不是单纯的读取，而是一次“上下文包”的重新组装。切换模式时，先清空当前内存中的上下文对象，反注册相关监听器，释放文件句柄，再读入新模式的配置，生成新的上下文包。顺序很重要，必须“先释放后加载”，否则容易出现新任务用到旧模式残留数据的情况。
我在代码里用了一个简单粗暴的思路：每次切换都生成一个全新的 ContextBundle，旧的直接丢弃，不做什么复杂的状态迁移。这个设计后来被证明是对的，省掉了大量“考虑两个模式之间状态如何转换”的复杂度。
2.3 全局模式与任务模式：优先级怎样设计
实际使用中，有些上下文是通用的，比如你总是要求 AI 用中文输出、总是要求工具编译出带调试信息的版本；有些是当前任务专属的。因此 context-mode 支持模式叠加：一个全局模式做底座，一个任务模式叠加在上层。
优先级规则其实很简单：后加载的覆盖先加载的，任务模式里的 snippets 永远排在全局模式前面，env 变量同名时以任务模式为准。合并完了不想再保留全局影响，可以显式执行一次“纯任务模式”切换，把全局上下文完全剥离。这个设计一开始我以为会很复杂，但随着使用发现，绝大多数场景只需要一层全局 + 一层任务，两层的叠加规则足够用了。
3. 从零实现一个可用的 context-mode
3.1 模式清单的存放与组织
我建议把模式清单统一放在项目根目录下的 .context-mode/modes 目录里，每个模式单独一个文件。这样 pic 目录可以整体提交到 Git，别人拉下来项目之后直接切模式就能进入状态。除此之外，我还在 .context-mode/ 下放一个 context.json，用来记录当前激活的模式 ID，方便跨终端同步状态。
.context-mode/ modes/ global.json toolchain-project.json content-script.json website-fix.json context.jsoncontext.json 的内容很简单，本质上就是“当前模式指针”。有了它，你在任意终端敲切换命令，都能立刻知道当前处于哪个模式，也方便在编辑器状态栏里展示当前模式名。
3.2 核心管理器逻辑：加载、合并、输出
我用 Python 实现了这个管理器的核心。之所以选 Python，是因为环境里基本都有，不需要额外装运行时，而且处理 JSON 很方便。核心是一个 ContextManager 类，负责读取模式、合并全局上下文、生成最终上下文包。
import json import os import shutil class ContextManager: def __init__(self, root_dir): self.root_dir = root_dir self.modes_dir = os.path.join(root_dir, ".context-mode", "modes") self.state_file = os.path.join(root_dir, ".context-mode", "context.json") self.current_bundle = None self.load() def load(self): global_cfg = self._read_mode("global.json") current_id = self._read_current_mode_id() task_cfg = self._read_mode(f"{current_id}.json") if current_id else {} merged = self._merge_contexts(global_cfg, task_cfg) self.current_bundle = self._assemble_bundle(merged) return self.current_bundle def switch(self, mode_id): self._write_current_mode_id(mode_id) # 关键：先清空旧模式，再加载新模式 self.current_bundle = None return self.load() def current_mode_name(self): if self.current_bundle: return self.current_bundle["name"] return "none"着重要说一下 _merge_contexts 这段。它不是简单地拼接 JSON，而是对列表做追加、对字典做覆盖、对字符串做模板插值。比如全局的 snippets 是“输出用中文”，任务的 snippets 是“构建用 build.sh”，合并后两个都会保留。而 env 字段如果有同名变量，任务模式的取值会覆盖全局的，这样设计避免了“全局默认值被意外改掉”的问题。
3.3 生成最终上下文包：给人和 AI 都能用的产物
最终上下文包 _assemble_bundle 会生成三个产物：第一个是给人看的终端提示文本，包含当前模式名、重点 snippets、注意的 rules；第二个是给 AI 助手的完整提示词，把 prompt_template 里的插槽全部填成具体内容；第三个是给工具用的环境变量字典，方便在自动化脚本里 export。
def _assemble_bundle(self, merged): prompt = merged["context"]["prompt_template"] files_str = ", ".join(f"`{f}`" for f in merged["context"]["files"]) prompt = prompt.replace("{{projectRoot}}", merged["mode"]["projectRoot"]) prompt = prompt.replace("{{files}}", files_str) env_snapshot = dict(merged["context"]["env"]) env_snapshot["CONTEXT_MODE"] = merged["mode"]["id"] human_lines = [f"[context-mode] 当前模式：{merged['mode']['name']}"] human_lines += [f"- {s}" for s in merged["context"]["snippets"]] if merged["context"]["rules"].get("output_language"): human_lines.append(f"- 输出语言：{merged['context']['rules']['output_language']}") return { "name": merged["mode"]["name"], "human_readable": "\n".join(human_lines), "ai_prompt": prompt, "env": env_snapshot, "raw": merged }这段代码看起来简单，但它解决了实际使用里最能节省时间的点：以前切任务要自己一条条整理提示词，现在生成一份上下文包之后，直接复制给 AI 助手就能开始干活，文件清单和规范都包含在提示词里了。实测下来，我单个模式的提示词生成时间在 5 毫秒以内，完全不影响日常操作流畅度。
3.4 接入日常工作流：编辑器、终端与 AI 助手
模式管理器本身只能算完成了一半，真正让它发挥价值的是接入日常工作流。我在终端里加了两个别名：ctx 用来查看当前模式，ctx-switch 用来切换模式。编辑器状态栏会读取 context.json 显示当前模式名，AI 助手插件会读取当前模式的 ai_prompt，在每次会话开始时自动填充。切模式这个动作被收敛成一条命令，整个过程不到一秒钟。
还有一个小工具：watch 模式。运行ctx watch之后，程序会监听配置文件的变更，一旦你改了模式文件，当前上下文包会在后台自动刷新。这个功能在处理频繁调整规则的项目里特别有用，省去“改完配置再手动重载”的麻烦。
4. 常见问题与排查经验实录
4.1 上下文串场：明明切了模式，旧上下文还在影响 AI 回答
这个问题我遇到太多次了，尤其是早期版本。排查结果显示，问题不在模式管理器，而在于 AI 助手客户端本身。切换模式只是更新了本地的上下文包，但 AI 对话窗口仍然保留着历史对话记录，你发过去的提示词会被旧的对话历史影响。解决方式是在 AI 助手里主动开启“新对话”或“清空上下文”，不要只是替换第一条消息。
后来我在 ctx-switch 命令里默认加了一条提示，切模式之后输出一行“请在新对话中开始，或手动清空当前对话历史”。这个细节显著降低了误用概率。如果你也遇到类似问题，先自查是不是历史会话没有清理，而不是怀疑配置没加载。
4.2 配置覆盖顺序混乱：同名环境变量到底该听谁的
还有一次排查了很久的问题：任务模式下明明配置了LOG_LEVEL=info，跑起来还是 debug。最后找到原因是全局模式带了LOG_LEVEL=debug，而合并逻辑里全局模式排在任务模式后面，任务模式反而被覆盖掉了。这个坑提醒我把覆盖方向写清楚，并加上了日志打印。现在合并完成后，我会把最终的 env 字典打印到终端，能直接看到每个变量的最终取值，再也没出现过同类问题。
4.3 项目迁移后文件路径失效：相对路径还是绝对路径？
模式里写文件清单时，我一开始图省事用了绝对路径，结果整个项目拷到另一台机器上之后，路径全废了。后来改成相对路径，以模式文件所在目录为基准，但配置里又混入了不同深度的相对路径，导致 AI 提示词里出现歧义。最终统一方案是：模式文件里只写相对于项目根目录的路径，项目根目录在 mode 的 projectRoot 字段里声明，装配上下文包时统一拼成 compile-path。这样项目整体迁移时只需要改 projectRoot 一个字段。
4.4 调参经验速查：哪些设置值得优先调整
我把这段过程中比较有共性的经验整理成一个速查表，适合刚开始做类似模式管理的人参考。
| 痛点场景 | 推荐设置 | 备注 |
|---|---|---|
| AI 回答不带项目背景 | prompts 里加入 projectRoot 与完整 file list | file list 控制在 5 个以内，别把所有文件都塞进去 |
| 多终端之间状态不一致 | 每次切换都持久化模式 ID 到 context.json | 编辑器与终端读同一份状态文件 |
| 全局规范被任务配置意外覆盖 | 全局模式的 key 加前缀，如 global.xxx | 避免同名键天然产生覆盖 |
| 临时调整不想改配置文件 | 支持命令行临时注入 snippets 并叠加到当前模式 | 只作用于当前会话 |
| 插件运行久了内存膨胀 | 切换模式时显式释放旧 ContextBundle | 简单粗暴但有效 |
4.5 一个值得试试的扩展方向：按任务自动推荐模式
模式切换本身已经解决了很多问题，但更进一步的做法是“自动识别当前任务并推荐模式”。我在项目根目录做了个简单启发式：检测最近修改的核心文件属于哪个模式的文件清单，就提示你切到对应模式。虽然在多项目混合作业时准确率还有提升空间，但已经能减少一半的手动切换。如果你做完基础版之后有余力，可以往这个方向扩一扩。
最后说一个我个人的小体会。context-mode 最值钱的地方不是代码本身，而是它逼着我把每个任务的隐性约定显式写了出来。过去很多规范只在脑子里或者聊天记录里，做完这个工具之后，所有项目的上下文都以文件形式沉淀下来了，换人接手、隔几个月再回头维护，都能快速回到状态。现在我的习惯是：进任何项目第一件事就是ctx switch <mode>，已经像喝水一样自然。
