1. 先弄清 context-mode 到底指什么1.1 它不是推给模型的上下文窗口技巧最近在技术社区的搜索热词里看到 context-mode 这个词时我的第一反应是某个开源项目又换名字了。顺着讨论串翻了一圈才发现大家聊的并不是某个具体工具而是一类正在被反复实践的设计思路你在做 AI 助手、写 Prompt、搭自动化脚本或者调编辑器插件时把上下文单独抽象出来并显式地切换到某一种工作模式。大多数开发者对 context上下文的第一印象来自模型文档里的上下文窗口。窗口越长模型能读的资料越多回答越有依据这没错。但 context-mode 和上下文窗口是两码事。上下文窗口相当于一间办公室的面积面积大说明能摆更多桌椅而 context-mode 是这间办公室当前处于什么状态是当作会议室、开放工位还是档案室。同样大小的空间不同状态下哪些东西应该出现、哪些东西应该收起来规则完全不同。如果只用窗口思维做应用很容易把做法变成把所有能拿到的资料全部塞进 Prompt。我早期就吃过这个亏把业务文档、聊天记录、代码仓库一整段读进来全堆在一条消息里发给模型结果模型在处理一份合同时居然顺着无关的日志内容去补全法律条款输出的东西看着头头是道实际完全跑偏。问题不在于窗口不够大而在于没有告诉模型当前该用哪一部分上下文、以什么身份处理哪一类问题。context-mode 正是在这个背景下被频繁讨论的。它不负责扩充容量而是负责给上下文做状态管理每次任务开始前先声明当前处于哪种模式然后只加载该模式需要的上下文忽略其他一切。简单说它把原来看不见摸不着的模型当前在思考什么背景变成可配置、可切换、可观测的工程部件。1.2 三种最常见的落地形态不同团队聊 context-mode 时落地的形态完全不同。根据我在几个项目里的观察最常见的是下面三种。第一种是配置态。这种方式最朴素通过环境变量或配置文件来切换系统行为。比如你写一个处理文档的脚本设置CONTEXT_MODEdev时加载项目规则和本地代码片段设置CONTEXT_MODEreview时则加载变更列表和缺陷记录。配置态的特点是简单直接逻辑上等于if mode xxx但因为把模式和上下文绑定在一起比散落各处的判断语句清晰得多。第二种是会话态。现在很多对话产品里能看到代码模式写作模式翻译模式本质上就是一种用户可见的 context-mode。切换模式后系统会替换掉一部分前置指令把不同的知识库或工具权限挂到会话上。这个形态和用户最贴近但在工程上反而容易被忽略很多团队只是改了温度参数或换了个系统提示词并没有真正切换上下文来源所以用户经常感觉切了模式也没什么差别。第三种是提示态。这类实现不依赖任何框架纯粹在 Prompt 结构上做文章。把一条消息拆成几个明确区域系统指令区、知识参考区、任务描述区再通过标记符表明当前生效的是哪一组区域。例如在消息前加mode: 代码评审然后只把评审规则和差异内容放进去。提示态最灵活适合那些不想引入额外依赖的轻量场景。三种形态可以单独用也能组合。配置态管后台状态会话态管用户交互提示态管模型输入同一套产品里三层同时存在也很常见。关键不是选哪一种而是先想清楚上下文从哪来、到哪去、由谁触发切换。2. context-mode 的三个核心动作2.1 定义模式边界把上下文域显式化想要在系统里实现 context-mode第一件事不是写代码而是把每个模式的边界画清楚。打个比方公司里的会议室和仓库如果都堆着同样的文件员工就永远不知道该去哪找东西模式边界就是给上下文文件贴上的放到哪个房间的标签。实际操作中我一般先列一个清单一个任务通常涉及几类上下文比如用户诉求、业务规则、历史记录、外部数据、代码内容、工具返回结果。然后按照这些上下文会一起出现且互不干扰的标准把它们分组成不同模式。每个模式需要设置四件事模式名称、允许进入的上下文来源、明确禁止进入的上下文来源、运行时的行为参数比如温度、最大 token 数。举个具体例子一个客服助手可能有处理退款和投诉升级两个模式。退款模式加载的是订单规则、退款流程、商品信息库投诉升级模式加载的是客服话术模板、情绪安抚策略、升级审批流程。订单数据和话术模板可能都存在数据库里但两个模式各自声明了自己的来源就不会出现模型在退款流程里念起了安抚话术这种串场。这里有个容易犯的错误把模式边界等同于功能模块。功能模块只说明系统能做什么模式边界则说明系统在什么背景下做什么。同一个功能模块可以被多个模式复用但每个模式必须能回答此刻我为什么有权使用这个模块。如果你的模式定义里没有设计排除项那它大概率只是功能开关不是真正的 context-mode。2.2 上下文采集与优先级排序边界画完之后第二步是处理哪些上下文先进入、哪些后进入的问题。上下文不是随便拼在一起塞进消息就完了先后顺序直接影响模型对信息的权重判断。我常用的是一条四段式管线采集、筛选、排序、渲染。采集阶段先把所有候选源拉回来包括本地文件、数据库记录、接口返回、用户输入。这个阶段不做过滤只保证该找的都找了。筛选阶段按当前模式的 include 和 exclude 配置把无关内容丢掉把重复内容去重。排序阶段决定上下文在最终消息里的位置我的经验是遵循一个优先级系统指令最高任务描述其次参考知识再次历史过程记录最后。为什么顺序这么重要因为模型对 Prompt 前部的敏感度通常高于后部尤其是系统指令区的内容会持续影响后续所有输出。如果你把某个历史对话放在消息末尾模型很可能忽略它如果把系统指令放在中段指令的作用也会被削弱。我见过一个团队之前把用户权限规则放在一大段产品说明后面模型每次都会优先按照产品说明里的通用建议回答权限限制反而形同虚设。上下文还存在时间维度。同样是用户之前说过的话昨天说的和十秒前说的权重就不一样。这里可以引入简单的滑动窗口只保留最近 N 条消息作为历史或者给更晚的上下文更高的排序位置。如果你在做需要长会话支撑的产品别把所有历史一股脑全加进去滑动窗口比无限累积更稳定也更省钱。2.3 切换、退出与状态复位最后一个核心动作是模式切换时机的管理。很多系统做了 context-mode但只做了进入没做退出和复位。切换模式不是换一件衣服继续干而是把上一个工作台整个清理干净再把新工作台的物品摆好。退出时至少要清理三类状态内存中缓存的上下文列表、临时拼接的 Prompt 片段、可能残留的文件句柄。我见过一个比较典型的故障一个自动化脚本从编辑模式切到发布模式后发布内容里一直带着编辑模式留下的备注标记查了很久才发现是消息模板里的上下文变量没有重置旧的备注文本被拼到了新消息后面。为了做到干净切换我建议给每个上下文实例加一个版本号或时间戳。切模式时不是想当然地清空就好而是检查当前上下文的版本号与目标模式是否匹配不匹配就触发重新加载。这一点在多人共用或并发请求时会特别重要后面排查部分还会详细讲。另一个技巧是给切换过程留过渡区。如果目标模式依赖上游任务的输出不要在一进入新模式时就立刻去读上游数据而是先加载模式配置明确依赖项再触发一次拉取。很多上下文污染问题都是因为切换和加载被当成同一件事实际上它们应该分两步走先切状态再按需加载。3. 用 Python 实现一个最小可用的 context-mode 管理器3.1 先设计配置再写代码不少人在实现 context-mode 时习惯直接上框架比如引入 LangChain 的 Chain 或 Agent 机制但我觉得对于中小型项目自定义一个最小实现往往更可控。用配置驱动的好处是模式怎么定义、哪些上下文进入、参数怎么调全部集中在 YAML 里不用改代码而且团队协作时更容易 review。下面是一份我非常常用的配置文件模板。注意它把模式名、说明、包含清单、排除清单、运行时参数都放在同一个结构里这样的设计让模式在代码里只对应一个对象而不是散落在各种条件分支中。# config.yaml modes: dev: description: 开发任务模式代码编写、缺陷修复 include: - repo/project_rules.md - repo/todo.md - repo/src/ exclude: - repo/docs/changelog.md - repo/test/fixtures/ max_tokens: 4000 temperature: 0.1 system_prompt: | 你是开发助手。优先关注代码实现、接口设计、单元测试。 不要讨论与代码无关的运营或市场话题。 review: description: 评审任务模式代码走查、风险识别 include: - repo/diff/ - repo/.review_rules exclude: - repo/src/generated/ max_tokens: 6000 temperature: 0.3 system_prompt: | 你是代码评审助手。重点是发现潜在缺陷、边界条件和性能问题。 给出结论时先引用对应代码行再解释理由。为什么要用 include 和 exclude 两套配置include 决定主动进场的上下文exclude 决定即使被扫到也要拦在外面。后者非常实用因为在实际采集时你经常会从目录下扫出一堆文件其中总有一些和当前任务无关但容易误导模型的资料exclude 就是防误伤的安全网。3.2 核心代码实现管理的核心类不需要太复杂关键是让配置、加载、组装三个动作各司其职。下面这段代码我保留了一个最小可运行的骨架你可以直接复制改造。import yaml from dataclasses import dataclass, field from pathlib import Path from typing import List, Optional dataclass class ModeConfig: name: str description: str include: List[str] field(default_factorylist) exclude: List[str] field(default_factorylist) max_tokens: int 4000 temperature: float 0.2 system_prompt: str class ContextModeManager: def __init__(self, config_path: str): with open(config_path, r, encodingutf-8) as f: raw yaml.safe_load(f) self.modes: dict[str, ModeConfig] {} for name, cfg in raw.get(modes, {}).items(): self.modes[name] ModeConfig( namename, descriptioncfg.get(description, ), includecfg.get(include, []), excludecfg.get(exclude, []), max_tokenscfg.get(max_tokens, 4000), temperaturecfg.get(temperature, 0.2), system_promptcfg.get(system_prompt, ), ) self.active_mode: Optional[ModeConfig] None self._context_cache: list[str] [] def activate(self, mode_name: str) - ModeConfig: if mode_name not in self.modes: raise ValueError(f未知模式: {mode_name}) # 先复位旧上下文再装载新模式 self._context_cache.clear() self.active_mode self.modes[mode_name] return self.active_mode def _is_excluded(self, file_path: str) - bool: for pattern in self.active_mode.exclude: if file_path.startswith(pattern) or pattern in file_path: return True return False def _collect_file(self, path: str) - Optional[str]: p Path(path) if not p.exists(): return None if p.is_file(): content p.read_text(encodingutf-8) return f### file: {path}\n{content} # 目录则递归收集 parts [] for sub in p.rglob(*): if sub.is_file() and not self._is_excluded(str(sub)): parts.append(f### file: {sub}\n{sub.read_text(encodingutf-8)}) return \n.join(parts) def assemble_context(self) - str: if not self.active_mode: raise RuntimeError(请先 activate 一个模式) chunks [] for item in self.active_mode.include: if self._is_excluded(item): continue content self._collect_file(item) if content: chunks.append(content) return \n\n.join(chunks) def estimate_tokens(self, text: str) - int: # 极简估算中文按每字约 0.6 token英文按空格分词 # 实际上线建议使用 tiktoken 或对应模型的分词器 chinese_chars sum(1 for c in text if \u4e00 c \u9fff) other_chars len(text) - chinese_chars return int(chinese_chars * 0.6 other_chars * 0.3)这里有几个容易出问题的细节。activate方法里先clear缓存再赋值新模式这一行的顺序非常关键如果在切换模式前不清理旧缓存后面组装上下文时可能把上一个模式的内容一并带进来。_collect_file在收集目录时逐个判断 exclude防止把生成目录或无关文档收进来。estimate_tokens使用的是一个极其粗略的估算方式并不是精确计算。上线到正式环境时务必要替换成官方分词器的准确计算否则很容易出现估算没超限实际请求却被截断的尴尬情况。3.3 把它接到 LLM 调用链路里有了配置和管理器接下来要解决的问题是怎么把上下文组装结果送进模型的 API 请求。我建议把上下文和用户问题分成独立的消息片段而不是全部堆在 user 一条消息里。结构化消息更有利于模型理解哪些内容是背景资料哪些内容是待办任务。下面这段代码展示了接入时的标准姿势。from openai import OpenAI client OpenAI() def build_messages(mode_name: str, question: str, config_path: str config.yaml): mgr ContextModeManager(config_path) cfg mgr.activate(mode_name) context_chunk mgr.assemble_context() # 控制上下文长度超出部分做策略性丢弃 context_tokens mgr.estimate_tokens(context_chunk) max_ctx cfg.max_tokens if context_tokens max_ctx: # 实际工程中这里会做“摘要压缩”或“关键段落抽取” # 最简单的方式是截断到安全阈值 ratio max_ctx / context_tokens cut_index int(len(context_chunk) * ratio) context_chunk context_chunk[:cut_index] messages [ {role: system, content: cfg.system_prompt}, {role: user, content: f相关上下文\n{context_chunk}\n\n我的问题{question}} ] return messages, cfg # 使用示例 messages, cfg build_messages(dev, 帮我检查这段代码是否有越界风险) response client.chat.completions.create( modelgpt-4o, messagesmessages, temperaturecfg.temperature, ) print(response.choices[0].message.content)把系统指令单独放一条 system 消息把上下文和问题放在 user 消息里对大多数模型接口都是通用的。截断策略这里只做了最原始的按比例截断防御性可以但效果一般。真正上线时更合理的做法是优先保留上下文中最靠近任务描述的部分或者用模型对超长上下文生成摘要这两种方案都比纯按比例截断更不容易丢关键信息。有一点容易被新手忽略如果用户问题本身就包含上下文比如用户贴了一段代码问哪里有问题要避免把用户贴的代码和系统采集的参考文件拼在一个大字符串里后截断。截断前先区分用户刚给的输入和系统检索的背景资料用户输入区要优先保留完整宁可删背景资料也不要截断用户的直接问题。4. 真实使用中踩过的 7 个坑4.1 上下文串扰A 模式的上下文溜进了 B 模式这个坑排在第一位因为它最具隐蔽性。我曾经维护过一个工具支持产品分析和技术实现两个模式结果模型经常在技术实现模式下回复产品定位建议。查了很多天发现问题出在一个被共用的事件总线上产品分析模式往总线写入了一堆市场调研数据技术实现模式在读取上下文时没有校验来源把总线里所有历史数据全当成了有效背景。解决串扰的思路很直接每个模式必须拥有独立的上下文隔离区或者至少在读取时显式声明来源。总线方案不是不能用但要给每一个上下文条目打上模式标签读取时按当前模式过滤。我后来在组装上下文前增加了一个断言当前模式名必须包含在上下文条目的标签列表中不在列表里的直接丢弃串扰问题才彻底消失。4.2 模式切换后旧状态粘住切换模式后系统还残留着上一个模式的状态是 context-mode 实现中最常见的故障。症状是模式明明切过去了但模型回答的风格、使用的术语、关注的重心还是上一个模式的。我踩过最丢脸的一次是写自动化脚本做日报生成。本来应该切到简短摘要模式结果因为一个全局列表变量没有清空模型继续读到了上一条日报的详细数据生成的日报里全是前一天的内容直接发给了老板。排查到最后问题就出在操作顺序上先加载了新模式配置但旧上下文的列表是在另一个步骤里赋值的而这个步骤在切换完成后一直没被触发。所以要养成切换即复位的习惯。activate方法里第一件事必须清理全部临时状态包括列表、缓存、文件句柄、计数变量。如果某些数据需要跨模式保留要显式把它放到持久化层而不是默认留在内存里。这里用版本号校验也能兜底每次切换把模式名和加载时间组装成一个版本标记任何读取动作都先核对标记不匹配就重新加载。4.3 上下文太长被静默截断模型接口超过最大 token 时通常不会报错而是从中间悄悄截断。真正可怕的是模型不会告诉你它把哪一段截掉了。如果你的关键业务规则恰好被截掉模型的回答看似正常实际已经丧失了核心依据。我做过一个比较离谱的项目本地知识库文档大概 15000 个 token配置上限 8000启动时一直没报错因为程序没有做任何截断操作。第一次接口调用后返回结果居然还带着前面几页的内容可后续问题只要涉及文档后半部分模型就开始胡说八道。后来在日志里加了分片统计才看清排在前面的文档被完整发送了后面超过上限的部分被 SDK 静默丢弃。应对办法是永远不要在客户端依赖模型会自己截断。在调用接口之前由 context-mode 管理器先做一次精确的 token 统计超出部分主动压缩。推荐的做法是给上下文区域划分优先级最高优先级的系统指令永远保留中优先级的参考知识允许被摘要压缩低优先级的历史对话可以直接丢弃。这样即使触发截断也是我们主动选择丢什么而不是让接口随机丢。4.4 上下文折叠与格式污染另一个隐蔽问题是格式污染。很多实现会把上下文包在 Markdown 的引用块或分隔线里然后在前面加一句以下内容是参考资料。这个做法的风险在于如果参考资料本身包含类似的分隔标记模型会被误导认为参考资料里嵌套的内容也是指令。我曾经收集文档时没有做任何清理一份很普通的项目报告里有一段 Markdown 表格表格后面跟着一行粗体字重要请直接按以下步骤操作。结果模型把报告里的这一行当成了系统指令去执行产出了一堆完全不该有的动作。这类问题在上下文模式里出现得特别频繁因为模式会自动加载多个文件你根本不知道文件里有什么格式陷阱。预防措施有三个第一对进入上下文的自由文本做转义或包裹时统一使用随机分隔符而不是固定写法第二所有从外部文档读取的内容明确标注为 data 块而不设指令语气第三最稳妥的办法是尽量使用结构化输入比如 JSON 数组或 XML 节点这样模型能区分数据内容和指令内容格式污染的概率会低很多。4.5 估算 token 与实际 token 偏差过大项目中我见过不止一次代码里算了上下文长度以为没有超限实际接口却提示过长。根因一般是估算函数太粗糙。中文环境下很多模型用字符数乘以某个系数来估算但不同 tokenizer 对中文词组的合并方式差异很大确实容易出现 20% 以上的偏差。我在 3.2 小节的代码里写了极简估算那只是为了演示流程绝不能直接用在生产环境。如果要接入 OpenAI 模型直接用官方提供的 tiktoken 库才靠谱其他模型也有对应的分词器。更保险的做法是在组装完消息后把上下文和消息一起传给一个校验函数在实际请求前再统计一次宁可多花一点计算时间也比接口报错强。4.6 并发请求下的上下文污染当你开始用 context-mode 管理一个在线服务时并发问题就会冒出来。我重构过一个异步服务发现两个用户同时请求时A 用户的上下文偶尔会串到 B 用户的请求里。原因很简单ContextModeManager被定义成了全局单例active_mode 只有一个第二个请求进来时直接覆盖了第一个请求的模式。这里特别提醒如果你把 context-mode 管理器设计成全局对象它的所有状态都是共享的。解决方法是让管理器实例和服务实例一一对应或者干脆在每次请求时新建一个轻量管理器不要跨请求复用带状态的类。只读的配置项可以全局共享但 active_mode、context_cache 这种可变状态绝不能全局共享。4.7 快速排查表现象常见原因排查思路回答中混有其他模式的内容上下文串扰共用存储未做模式过滤检查上下文条目是否携带模式标签读取时是否按模式过滤切换模式后行为没变化状态未复位缓存未清空查看 activate 方法是否先清理旧缓存再加载新配置长上下文中关键信息缺失上下文超出上限被接口静默截断在发送前做精确 token 统计和主动截断策略文档内容被当作指令执行格式污染Markdown 标记冲突使用随机分隔符、结构化数据包裹外部内容并发请求数据串了全局 manager 状态共享将带状态的管理器改为请求独立实例上下文状态总是旧的版本号或时间戳未校验给上下文实例添加版本标记不匹配时重新加载5. context-mode 选型边界什么情况一定别用5.1 值得上 context-mode 的信号判断一个项目是否需要引入 context-mode可以从三个信号入手。第一你的系统本身就在服务多类任务而且这些任务需要的背景知识差异巨大。比如同一个知识库平台既要做内容摘要又要做问答检索两者加载的参考文档和指令规则完全不同这种情况下模式化就很有价值。第二上下文成本已经高到不能无脑堆叠。如果你发现每次请求都在传输几十万字符的资料账单越来越高、响应越来越慢说明你需要对上下文做减负而不是继续扩窗口。context-mode 通过精确过滤和优先级排序能实打实地把成本打下来。第三团队协作要求系统行为可预测。当多个开发者共用一个 Agent 或一套自动化流程时如果每个人都靠临时改 Prompt 来改变行为迟早会失控。把行为定义收敛到模式配置里谁改了什么一目了然排查问题也方便。这个好处在代码评审和自动发布场景里体会最明显。场景判断标志建议方案多任务共用一套系统同一套逻辑要输出多种类型的结果配置驱动 context-mode不同任务不同上下文域上下文体积大且成本高每次请求传输海量参考资料引入 include/exclude 和优先级截断多开发协作临时改 Prompt 导致行为不可控把行为定义收敛到模式配置版本管理一次性简单问答任务单一、上下文很小不要加模式直接构造消息即可尚未理清上下文来源连自己的数据源都没列清楚先做上下文清单再谈模式设计5.2 不建议用的情况context-mode 不是什么银弹有些场景硬套反而会增加复杂度。如果你做的是单一任务的工具例如一个只用来翻译文本的脚本上下文来源本来就固定根本没有切换的必要。这时候加模式配置纯属画蛇添足多了一层 YAML 解析多了一堆异常分支运行效率还降低了。还有一种情况是上下文还没理清楚就急着上模式。我见过一个团队把几十个上下文来源塞进四个模式里但每个模式里到底有哪些文件、哪些数据源连他们自己都说不清。这种状态下模式设计出来就是灾难还不如直接用最笨的全量拼接至少在调试时问题更直观一点。给一个我个人常用的判断标尺如果给系统加 context-mode 之后你需要花超过半天时间来解释配置文件里的某个 include 或 exclude 是干嘛用的那目前就不适合上。模式设计的本质是简化决策如果它反而让团队成员更困惑说明边界划错了先回去整理上下文清单。最后聊一点个人体验。我真正被 context-mode 说服不是因为它把回答准确率提升了多少而是因为它让调试变得可解释了。以前模型跑偏时我只能靠猜是哪段资料在干扰现在只要打印当前模式的配置和组装出来的上下文快照一眼就能看出问题出在排除规则、截断策略还是状态复位。如果你也想做类似的东西我的建议是别急着追求复杂的上下文路由和分层策略先把你手头所有的输入源列出来找出哪些总是同时出现、哪些彼此干扰凭这个直觉去设计模式边界再写代码实现。大多数场景一套 YAML 配上几百行 Python 就完全够用了。