1. 核心定位与设计思路
1.1 为什么需要 context-mode
我最早接触“context-mode”这个说法，是在做命令行工具和自动化脚本的时候。那时候碰到的痛点很直接：同一个脚本，在不同场景下要加载不同的配置，比如开发环境、测试环境、生产环境，参数不一样，连日志级别和输出格式都不一样。如果每次都在命令行里手动拼接参数，既容易出错，又浪费时间。如果你也写过那种“只要多加一个参数就多一层复杂度”的工具，应该能理解这种别扭感。
后来我发现，与其不断增加参数分支，不如把“场景差异”抽象成一个独立的概念——这就是 context-mode 的由来。简单来说，它把“当前脚本运行时的上下文信息”显式地暴露成一种可切换的模式，模式决定了工具的行为边界。你不需要告诉程序每一个细节，只需要告诉它“现在用哪种模式”，剩下的细节全部由模式定义文件来承载。
这个思路在软件开发里其实由来已久，比如很多框架都有“环境配置”的概念，但在通用工具链和个人自动化脚本里，很少有人把它系统化地实现。context-mode 的特别之处在于，它让“上下文”成了一个可命名、可切换、可复用的一等公民，而不是散落在一堆 if-else 里的隐式状态。
1.2 这个模式能解决什么问题
说个我自己的例子。我维护一个本地博客发布脚本，正常情况下它会扫描drafts/目录，把符合条件的 Markdown 文件渲染成 HTML 并部署到服务器。但有些时候，我只想快速预览某篇文章的效果，并不想真的发布。最初的做法是加一个--preview参数，后来又想加--archive、--clean，参数越堆越多，脚本逻辑也越来越绕。
用 context-mode 之后，我改成让脚本从ctx/目录读取模式定义。每个模式就是一个独立的配置文件，里面的内容告诉脚本“这个模式下该做什么、不该做什么、输出到哪里”。比如preview模式只渲染到本地临时目录，publish模式才会执行部署。切换模式只需要一个参数，比如blog.py --context preview，语义一目了然，也不需要在代码里维护一堆状态分支。
从这个角度看，context-mode 很适合用在几类场景里：
- 自动化脚本需要处理多种运行场景，且场景之间的差异不是一两个参数能解决的。
- 你在开发 CLI 工具，希望用户通过简单的“模式选择”而不是复杂的参数组合来使用它。
- 你在做基于大语言模型的工作流，需要在“通用对话”“代码审查”“文案润色”等不同角色设定之间快速切换。
对于最后一种场景，context-mode 的价值尤其明显。模型的行为高度依赖系统提示词（system prompt）和上下文窗口里塞进去的内容，而“模式”本质上就是把一类上下文预先准备好，一键加载。可以理解成给模型准备了多套“工作台”，每套工作台上面摆好了对应的工具和资料。
2. 核心细节解析与实现要点
2.1 模式定义与状态载体
要落地 context-mode，第一步是定义“模式”的载体。最常见的做法是使用目录加配置文件的方式，业界也有很多现成的工具采用类似的思路，比如direnv用目录级别的.envrc来切换环境变量。我的建议是，先按下面的结构组织：
ctx/ default/ config.json prompt.md preview/ config.json prompt.md publish/ config.json prompt.md每个子目录就是一个独立的 context-mode，里面可以放任意需要的文件。config.json负责声明模式的基本信息，比如模式名、描述、需要加载的模板文件路径；prompt.md存放模型工作流里的系统提示词；如果有其他资源文件，比如示例数据、参考文档、输出模板，也放在对应模式目录下。
config.json 的典型结构长这样：
{ "name": "publish", "description": "正式发布模式，执行完整构建与部署", "load_files": ["prompt.md", "templates/article.html"], "output_dir": "./dist", "settings": { "log_level": "INFO", "dry_run": false } }这个文件的核心作用不是把参数铺开写，而是把“这个模式需要加载什么、输出到哪里、行为上有什么开关”浓缩成一份声明。代码读到这份声明之后，按图索骥即可。
为什么用配置文件而不是直接写在代码里？因为配置文件可以脱离代码被修改，让不熟悉代码的人也能调整运行行为。你可能会觉得“多了一层配置文件反而麻烦”，但当模式数量超过三个、每个模式又涉及到不同模板和输出路径的时候，配置化的收益是肉眼可见的。模式之间的差异被集中管理，而不是散步在代码的不同分支里。
2.2 上下文信息的动态注入
光有静态配置文件还不够，context-mode 的精髓在于“上下文是动态的”。你要能把运行时的信息，比如当前时间、用户输入、上一步的输出结果，注入到这个模式里。这样模式才不是一个死板模板，而是能感知当前环境的“活上下文”。
实现这个效果，我通常在配置里定义一组插槽（slot），比如用${date}、${input}这样的占位符，然后在加载模式时替换成实际值。举个例子，prompt.md里有这样一段：
今天是 ${date}，请基于以下材料写一篇技术博客，风格要求：${tone}。 材料内容： ${content}代码读取这个模板后，用实际值做替换：
import datetime def render_template(template_path, context): with open(template_path, 'r', encoding='utf-8') as f: content = f.read() for key, value in context.items(): content = content.replace('${' + key + '}', str(value)) return content这个实现逻辑非常直白，你不需要引入任何模板引擎也能做到。如果模板的内容比较复杂，建议用Jinja2这类成熟模板库来处理，但原理是一样的：模式负责提供骨架，运行时负责填入血肉。
动态注入最需要注意的一点是“占位符的命名要规范”。我见过不少人前期随意命名，比如某个配置文件里用${t},另一个地方用${time}，结果写替换逻辑的时候非常痛苦，天天出奇怪的 bug。统一命名规则，例如时间一律用${date}，输入文本一律用${input}，输出路径一律用${output}，时间久了之后整个工具链会变得非常好维护。
2.3 显示当前模式，避免“迷航”
context-mode 还有一个容易被忽略但特别重要的细节：用户必须随时知道当前处于哪个模式。这个听起来好像很简单，但实际使用中，一旦模式切换发生在一个自动化流程的深处，你很容易忘记自己现在这一步到底身处哪个模式，尤其当多个模式共享同一个输出目录或者同一个临时目录的时候。
解决这个问题有两个层面的做法。第一个层面是在 CLI 交互界面显示模式，最简单的是在命令行的提示符（prompt）里加上当前模式名，比如写一个 shell 函数：
function get_ctx_mode() { if [ -f ".ctx_mode" ]; then cat ".ctx_mode" else echo "default" fi } export PS1='[\u@\h \W $(get_ctx_mode)]\$ '这里我把当前模式名写在一个.ctx_mode文件里，每次进入 shell 时读取它并显示在提示符上。这种做法就像给工作台挂了一个名牌，时刻提醒自己现在是在哪条线上干活。第二个层面是在自动化流水线里，把当前模式作为元信息写入日志文件的开头，保证事后回溯时能快速定位到运行环境。
2.4 模式切换的原子性
模式切换有时候不是瞬间完成的，它要加载配置、读取文件、还可能更新一些缓存。如果切换过程中程序被中断，就可能出现“配置加载了一半”的脏状态。这就涉及模式切换的原子性问题。
我的经验是：先把目标模式的所有数据加载到内存并做校验，校验通过之后再一次性把状态切换到新的模式。具体来说，建议按这个顺序操作：
- 读取目标模式的
config.json并解析。 - 按照
load_files加载所有模板和资源文件。 - 渲染所有动态插槽。
- 全部成功后再覆盖当前内存中的模式状态。
- 如果任何一步失败，保持原模式不变并报错。
这个流程可以确保切换操作要么完全成功，要么什么都不会改变。实际代码里其实就是简单地分阶段执行，不要边加载边替换。你在一些设计良好的配置管理工具里也能看到同样的原则，关键就是把它落到你自己的脚本里。
3. 实操过程：手把手实现一个可用的 context-mode
3.1 场景定义
为了让这一节更有参考价值，我设计一个非常具体的场景：写一个支持多模式的内容发布工具。这个工具接收用户提供的一段文本，根据当前模式对文本做不同处理。
draft模式：只保存草稿，什么都不要动。polish模式：调用大语言模型润色文案，并输出润色后的结果。publish模式：在润色基础上，生成 HTML 文件并写入到指定发布目录。
这三种模式差异明显，也能覆盖最简单的“上下文切换”使用场景。我建议你不用照抄这个工具的完整代码，而是理解每一段实现背后的思路，然后移植到你自己的项目里。
3.2 创建项目结构与模式配置
首先建立项目结构：
content-tool/ ctx/ draft/ config.json polish/ config.json prompt.md publish/ config.json prompt.md templates/ article.html main.py .ctx_mode先看draft的配置文件：
{ "name": "draft", "description": "保存草稿，不执行任何额外处理", "output_dir": "./drafts", "settings": { "log_level": "DEBUG", "processing": false } }然后是polish的配置：
{ "name": "polish", "description": "调用模型润色文案", "prompt_template": "prompt.md", "output_dir": "./polished", "settings": { "log_level": "INFO", "processing": true, "model": "gpt-4o-mini" } }publish的配置：
{ "name": "publish", "description": "润色并发布为 HTML", "prompt_template": "prompt.md", "template_file": "templates/article.html", "output_dir": "./dist", "settings": { "log_level": "INFO", "processing": true, "model": "gpt-4o-mini" } }三个模式共享同一个prompt.md也不是不行，但既然是不同模式，建议为它们准备不同的提示词。polish模式下的prompt.md大概是这样的：
你是一名资深内容编辑。请对用户提供的文本进行润色，要求： - 保持原意不变，不新增事实。 - 修改语句，使其更通顺、精炼。 - 保留专业术语，不随意替换。 - 输出只包含润色后的文本，不做解释。publish模式下的prompt.md可以加上格式转换指令：
你是一名资深内容编辑。请对用户提供的文本进行润色，并转换成适合发布到个人博客的文章格式。 要求： - 润色后文本需结构清晰，段落分明。 - 如需小标题，用 Markdown 的二级标题。 - 不要生成摘要和总结。看到区别了吗？模式变化的核心，本质上就是这套“加载了哪组指令，带着哪组上下文”的变化。工具代码不需要关心这组指令具体做到了什么，只管加载和替换。
3.3 模式管理器实现
接下来是主程序的核心部分——模式管理器。它的职责是：读配置、加载模板、渲染插槽、切换状态。
我用 Python 来实现，完整代码如下：
import json import os import subprocess import sys from pathlib import Path CTX_ROOT = Path("ctx") class ContextMode: def __init__(self, mode_dir: Path): self.mode_dir = mode_dir self.config = self._load_config() self.name = self.config["name"] self.description = self.config.get("description", "") self.settings = self.config.get("settings", {}) self.prompt = self._load_prompt() self.template = self._load_template() def _load_config(self): config_path = self.mode_dir / "config.json" if not config_path.exists(): raise FileNotFoundError(f"Missing config: {config_path}") with open(config_path, 'r', encoding='utf-8') as f: return json.load(f) def _load_prompt(self): prompt_path = self.mode_dir / "prompt.md" if prompt_path.exists(): return prompt_path.read_text(encoding='utf-8') return None def _load_template(self): template_path = self.mode_dir / self.config.get("template_file", "") if template_path.exists(): return template_path.read_text(encoding='utf-8') return None def render(self, context: dict): rendered_prompt = self.prompt or "" if rendered_prompt: for key, value in context.items(): rendered_prompt = rendered_prompt.replace("${" + key + "}", str(value)) self.rendered_prompt = rendered_prompt这里我把每个ContextMode对象视为一个不可变更的模板，真正注入动态数据时，复制一份并渲染，因为流程中同一个模式可能被用多次，每次的输入都不同，不能污染原有模板。
管理器代码如下：
class ContextManager: def __init__(self, root: Path = CTX_ROOT): self.root = root self.modes = {} self.current_name = "draft" self._scan_modes() def _scan_modes(self): for mode_dir in self.root.iterdir(): if mode_dir.is_dir(): config_path = mode_dir / "config.json" if config_path.exists(): mode = ContextMode(mode_dir) self.modes[mode.name] = mode def switch(self, mode_name: str): if mode_name not in self.modes: raise ValueError(f"Unknown mode: {mode_name}") self.current_name = mode_name def get_current(self): return self.modes[self.current_name] def load_context_file(self, path: Path): if not path.exists(): raise FileNotFoundError(f"Context file not found: {path}") return path.read_text(encoding='utf-8')这段代码有一个细节值得注意：_scan_modes()会在启动时自动扫描ctx目录下所有子目录，你不需要在代码里手动注册模式。以后想新增一个模式，只需要在ctx目录下新建一个文件夹放好配置即可。这种“约定优于配置”的思路能显著降低扩展成本，不用改代码就能加模式。
3.4 主流程串联
主流程做了以下几件事：读入说明是哪个模式的命令行参数，加载模式，把输入内容和其他上下文拼起来，然后把任务交给对应的处理器。
def handle_draft(mode: ContextMode, content: str, context: dict): output_dir = Path(mode.settings.get("output_dir", "./drafts")) output_dir.mkdir(exist_ok=True, parents=True) output_path = output_dir / context["filename"] output_path.write_text(content, encoding='utf-8') print(f"[draft] Saved to {output_path}") def handle_polish(mode: ContextMode, content: str, context: dict): if not mode.prompt: print("[polish] No prompt found, plain copy.") output = content else: output = call_llm(mode.prompt + "\n\n" + content) print("[polish] Output from model received.") output_dir = Path(mode.settings.get("output_dir", "./polished")) output_dir.mkdir(exist_ok=True, parents=True) output_path = output_dir / context["filename"] output_path.write_text(output, encoding='utf-8') print(f"[polish] Saved to {output_path}") def handle_publish(mode: ContextMode, content: str, context: dict): if mode.prompt: content = call_llm(mode.prompt + "\n\n" + content) if mode.template: rendered_html = mode.template.replace("{{title}}", context["title"]) rendered_html = rendered_html.replace("{{content}}", content) output_dir = Path(mode.settings.get("output_dir", "./dist")) output_dir.mkdir(exist_ok=True, parents=True) output_path = output_dir / context["filename_html"] output_path.write_text(rendered_html, encoding='utf-8') print(f"[publish] HTML saved to {output_path}") else: print("[publish] No template found, output plain text.") output_path = Path(mode.settings.get("output_dir", "./dist")) / context["filename"] output_path.write_text(content, encoding='utf-8')call_llm是示意性的函数，实际使用的时候你可以填入任何模型 API 或本地模型调用。关键体会是：同一个工具，随着模式变化，它的“智能程度”和输出形式都会改变，而代码复杂度却没有明显上升。
入口函数：
def main(): if len(sys.argv) < 2: print("Usage: python main.py --context <mode> --file <input.txt> [--title <title>]") sys.exit(1) args = sys.argv[1:] if "--context" in args: idx = args.index("--context") mode_name = args[idx + 1] else: mode_name = "draft" if "--file" in args: idx = args.index("--file") input_path = Path(args[idx + 1]) content = input_path.read_text(encoding='utf-8') else: print("Please provide --file argument.") sys.exit(1) title = "Untitled" if "--title" in args: idx = args.index("--title") title = args[idx + 1] manager = ContextManager() manager.switch(mode_name) mode = manager.get_current() context = { "date": datetime.datetime.now().strftime("%Y-%m-%d"), "title": title, "filename": input_path.stem + ".md", "filename_html": input_path.stem + ".html", } context["content"] = content if mode.name == "draft": handle_draft(mode, content, context) elif mode.name == "polish": handle_polish(mode, content, context) elif mode.name == "publish": handle_publish(mode, content, context) else: print(f"Unhandled mode: {mode.name}") if __name__ == "__main__": main()这段代码足够短，但承载了完整的模式切换逻辑。实际跑一次效果如下：
python main.py --context draft --file notes.md python main.py --context polish --file notes.md python main.py --context publish --file notes.md --title "context-mode实践"第一个命令只是把文件归档到drafts/；第二个命令会把文章润色后存到polished/；第三个命令会走完整流程，最终在dist/生成 HTML。同一个输入文件，三种不同命运，完全由“模式”这一层抽离出来。
3.5 进一步封装成 CLI 工具
脚本写到一定规模后，建议封装成更清晰的 CLI。你可以基于argparse把参数定义集中起来，这样命令行的帮助信息会更友好，别人也能更容易上手。这里一个小技巧：不要把“模式名”散落在各个子命令里，而是把模式名提升为一级参数，让用户第一眼就知道要选模式。
import argparse def build_parser(): parser = argparse.ArgumentParser(description="context-mode content tool") parser.add_argument("--context", choices=["draft", "polish", "publish"], default="draft", help="Context mode to use") parser.add_argument("--file", required=True, help="Input markdown file path") parser.add_argument("--title", default="Untitled", help="Article title for HTML rendering") return parser如果你的模式数量会动态增长，那choices列表也要动态生成，从ContextManager扫描到的模式名里取。这样新增模式后，命令行帮助也会自动同步，不用手改。这是我在实际项目里最常用到的增强。
4. 常见问题与排查技巧实录
4.1 模式生效了但输出没变
这个现象很迷惑人。你兴冲冲地切到publish模式运行，结果输出内容和draft模式一模一样，好像模式切换完全没起作用。排查方向有两个：
第一，确认你当前进程里的ContextManager是不是重新初始化的。如果程序是长驻进程，可能在第一次加载之后，模式列表已经缓存了旧配置，你需要热重载能力。早期的脚本如果只扫一次目录，后面新增的模式就不会被识别出来，这也是为什么我在管理器里保留了重新扫描的接口。
第二，查看处理器分支。如果你在main函数里用硬编码方式分发模式，比如if mode.name == "draft"，那么新模式如果不在分支列表里，就会掉进else，或者被直接忽略。建议处理器映射用字典来维护：
handlers = { "draft": handle_draft, "polish": handle_polish, "publish": handle_publish, } handler = handlers.get(mode.name)这种写法更利于扩展，也不会因为分支条件写错导致走了错误的处理逻辑。
4.2 模板变量替换失败
模板里写了${date}，运行之后输出里还是原样保留${date}。这种问题一般是替换逻辑没有覆盖到完整内容。Python 的str.replace是精确匹配，如果你在模板里写了$date或者{{date}}，那就匹配不上。解决方式是最好在加载模板时就做一次校验：扫描模板里的插槽变量，和实际传入的上下文字典对比，给出明确的缺失报告。
import re def validate_slots(template, context): placeholders = re.findall(r'\$\{(\w+)\}', template) missing = [p for p in placeholders if p not in context] if missing: raise ValueError(f"Missing context slots: {missing}")这一步能在开发早期就把问题暴露出来，保证不会带着残缺的模板去调模型。
4.3 模式切换后的“脏”状态
切换模式时，如果上一次模式留下了一些缓存变量，比如某次输出的内容、临时目录的路径，下一次模式运行时会意外读到这些残留，导致行为异常。我用过的最笨也最有效的方法是：把模式相关的状态集中到一个对象里，切换模式时直接换一个新的模式对象，旧对象的引用全部丢给垃圾回收。这从源头上避免了状态串扰。
有小伙伴问为什么不用全局变量来跟踪当前模式，我之前也贪图省事干过，后来发现全局变量的隐患是“隐式依赖”，一个地方改了全局状态，另一个地方莫名其妙就跟着变。模式切换这种事，显式传递比隐式共享要可靠得多。尤其是在多线程场景下，全局模式状态很容易造成几个线程互相踩踏，切换来切换去，行为完全不可控。
4.4 模式数量一多，配置维护变成灾难
用目录结构组织模式，一开始很清爽，但模式多了之后，每个config.json里可能都有大量重复字段，比如log_level、model这些。这时候我建议引入一个“继承”机制：让每个模式的配置里增加一个extends字段，指向基础模式，之后把自己要覆盖的字段写出来就行。这有点象 CSS 的类继承逻辑，虽然会增加一层解析复杂度，但确实能显著降低维护成本。
{ "extends": "base", "name": "publish", "output_dir": "./dist", "settings": { "processing": true } }解析的时候先递归加载父配置，再用子配置覆盖。这个扩展我建议在模式超过五个之后再考虑，一开始不要过度设计。
4.5 与外部工具链的衔接问题
context-mode 的好处是它并不只限定在某个语言或框架里。在 Shell 层面，你可以通过环境变量来传递当前模式；在 CI 流水线里，你可以用变量把模式名传给构建脚本；在 AI 工作流里，模式名可以决定加载哪套提示词和参考文档。一个典型的做法是让模式名成为环境变量CTX_MODE，所有子进程都可以读取：
export CTX_MODE=publish python main.py --file notes.md程序里读取：
import os mode_name = os.environ.get("CTX_MODE", "default")这个做法让 context-mode 变成了“进程级上下文”，而不是某一次函数调用里的参数，适合在需要多个工具配合的场景里使用。比如你可以在.bashrc里写一个快速切换函数，经常在不同项目间切换时非常方便。
5. 扩展思考：从工具到方法论
5.1 context-mode 作为人机协作的接口
如果把 context-mode 从代码层面拔高一层来看，它其实是在“人与工具之间”建立了一套更稳定的协作协议。你不需要每一次都重新描述需求，只需要说“按这个模式来”，工具就自动进入对应的行为规则和知识背景。这和很多效率工具的设计哲学是一致的：把重复性的决策变成默认值，把注意力留给真正需要判断的地方。
拿我之前提到的 AI 工作流举例。如果你经常写提示词，应该会意识到：提示词的最大问题是“每次都要重新写”。有了 context-mode 之后，模式本身就是提示词的集合，每次要做的只是把当前任务放进去。长期积累下来，你会慢慢沉淀出很多高质量的模式，它们就是你工作效率的真正资产。这比手动复制粘贴提示词要系统得多。
5.2 设计模式的时候要想清楚边界
设计 context-mode 容易陷入两个极端。一是模式粒度太粗，一个模式承担了太多不同的职责，切换模式和不切换没什么区别；二是模式粒度太细，每换一种小操作就新建一个模式，最后模式数量失控，你又要花时间维护模式之间的关系。
我的建议是：一个模式应该对应一个“稳定的任务场景”，场景之间应当有明显区别，比如“调试预览”和“正式发布”就是两个边界清晰的场景。凡是你自己在实际使用中反复手动调整参数的地方，都可以考虑抽成一个新模式；而只是偶尔微调的情境，没有必要为它专门建一个模式。模式越多，你的选择成本就越高，性价比反而下降。
5.3 从 context-mode 延伸出去
这套思路还可以延伸到别处，比如项目管理中的“情境切换”。资深工程师都知道，在不同项目、不同代码库之间切换的时候，头脑里的上下文切换成本非常高。你会突然忘记这个项目的命名风格、构建命令和常见坑点，而 context-mode 就相当于把这些“项目记忆”固化成可调用的模式，不只是给程序用，也可以给人自己留一份速查手册。
我认识的一位同行会为每一个客户项目维护一个.ctx目录，里面放着客户的技术栈说明、代码风格指南、常用的远程服务器列表。进入那个项目目录时，他让 shell 自动激活对应的环境变量和工作目录。这套做法本质上就是 context-mode 思想在个人工作流上的应用。你不需要写繁琐的代码，一套目录加配置就完成了大部分价值。
就我个人的实际体会来说，context-mode 真正好用之处在于它逼迫你思考“我的任务到底可以分为哪些稳定的场景”。这个思考过程本身，比写代码还要有价值。当你把日常操作中的模糊判断逐渐沉淀成一个个清晰的模式，工具的使用体验会发生质的变化。最后分享一个小技巧：每次遇到“我好像有点混乱”的时刻，不用急着加参数或改代码，先暂停下来，把当前的场景描述成一段模式配置，往往思路马上就能理顺。
