在 AI 辅助编程干了快两年我最深的体会是模型能力本身早就不是瓶颈“怎么把上下文喂给它”才是。很多人拿着同一个模型有人能稳定产出高质量代码有人每次都要反复纠正、甚至推倒重来——差的那一块往往就是 context-mode上下文模式的设计。说实话早期我也吃过亏一个需求聊到一半把无关的报错日志、旧方案全塞进对话里结果模型开始“犯迷糊”回答越扯越远。后来我把这套东西单独拎出来做成了一个叫 context-mode 的小方案专门管理“当前该让模型看到什么”实测下来项目推进速度快了不少。这篇文章就把我的完整设计、踩过的坑、以及可以直接复用的脚本都摊开讲清楚。先说明一下 context-mode 是干嘛的它不是插件也不是某个大模型的功能而是一套“上下文组织与切换策略”。核心思路是把一次复杂任务拆成不同的上下文模式比如聚焦某个模块、纵览整个项目、回溯上次讨论然后按需切换而不是把所有信息一股脑丢给模型。适合谁看如果你经常用 AI 写代码、做方案评审、梳理历史遗留系统或者你自己在做 Agent 类应用却被“上下文爆炸”折磨那这篇内容应该能帮你少走不少弯路。我会从问题拆解、模式设计、代码实现到具体排查按实操顺序完整走一遍。1. context-mode 到底在解决什么问题1.1 上下文窗口的“虚假充裕”现在的模型动不动就是 128K、200K 上下文窗口听起来很大但真正好用的部分远没那么宽。我自己测过一个长会话跑到几万字之后模型对前面细节的引用准确率明显下降尤其是当你在中段穿插了大量无用信息时它甚至会“记住”错误的东西。这就像一个人听你讲了半小时你说的大部分是废话那他能抓住的关键点自然就少。窗口大不代表信息密度高更不代表注意力能均匀覆盖每个角落。context-mode 的第一个核心目标就是把有限的注意力预算花在最值得看的信息上。它不是去扩大窗口而是主动控制进入窗口的内容。所谓“上下文模式”本质上就是一组可切换的筛选规则决定当前阶段系统自动携带哪些材料、省略哪些材料。1.2 多任务并行时的“上下文污染”做真实项目时一个会话里往往同时夹着需求说明、代码片段、报错信息、修改意见。这些内容混在一起模型很容易串味。最典型的一个现象你上一轮刚讨论完支付模块的退款逻辑下一轮让它看订单列表的接口设计它可能就把退款的异常处理思路带到新接口里来产物结构看着没问题细节全是错的。这就是上下文污染。我当时做 context-mode起因就是这个。同一套代码库里多个任务并行我需要一种办法让每个任务“只看到自己的上下文”彼此不串。后来我把它做成三档可切换的模式——聚焦模式、全局模式、回溯模式——对应不同的工作场景才算是真正治住了这个毛病。1.3 长周期项目的“记忆断层”还有一种情况一个项目做了两三个月中间隔了一两周没动再回去改代码时你跟模型说“继续上次那个方案”模型早就忘了。于是你只能重新翻聊天记录、找当时的结论再手动贴进去。这个过程既痛苦又容易漏细节。context-mode 的第三个目标就是给这种场景一个轻量级的“记忆索引”不是把所有历史都喂给模型而是把关键的决策依据、结论摘要、相关代码路径快速拉回来。2. 三种核心上下文模式的设计思路2.1 Focus Mode聚焦当前模块切断无关信息聚焦模式是日常开发最常用的一档。它的规则很简单当前任务是 A 模块那就只让模型看到 A 模块的代码、A 模块的接口文档、以及和 A 直接相关的最近改动。其他模块的内容哪怕多看一眼都算浪费。这时候省下来的上下文空间可以让模型把注意力集中在细节逻辑上。实际操作中我通常会在切换聚焦模式时顺手生成一份“模块简况”包含模块职责的一句话描述关键文件路径清单当前待解决的问题描述最近一次改动的 diff 摘要这么一来模型拿到的是高度提炼后的“工作卡”而不是自己去翻一堆源码。你会发现它给出的方案明显更稳因为不需要依赖模型自己去猜哪些文件是核心。2.2 Global Mode纵览全局处理跨模块设计当任务涉及多个模块协作——比如新功能要同时改前端、后端接口和数据库表结构——聚焦模式就不够用了。这种时候需要切到全局模式把架构层面的信息带进来。全局模式下我建议携带的内容是另一种口径项目整体架构图或模块依赖说明本次需求涉及的所有模块清单每个模块的对外接口签名数据流向的大致路径注意全局模式不要直接堆所有模块的全部代码那又回到上下文污染的原点。这里有两个原则一是“只带接口不带实现”二是“带结构和依赖关系不带历史包袱”。让模型先理解全貌再基于全貌做设计决策至于具体某个函数怎么写可以回落到聚焦模式去完成。2.3 Recall Mode回溯历史决策避免重复讨论Recall Mode 是我额外加的一档专门处理“之前讨论过的东西”。它的设计初衷很朴素很多时候重提旧事不是要模型重新推理一遍而是只要它“想起来”当时的结论即可。我的做法是维护一份轻量的决策日志格式类似日期、任务编号、当时的问题、最终结论、涉及的代码文件 这些条目平时不喂给模型只有切到回溯模式时才按关键词检索并注入。相当于给模型配了一个“最近记忆”而不是“全部记忆”。这样做的好处是当你隔了三周重新打开一个任务直接把旧结论和当时的关键 diff 丢给它它就能快速接上茬不再需要你从头讲解来龙去脉。3. 实操落地用一个轻量脚本把 context-mode 跑起来3.1 先搭一个最小可用的实现框架有了理论设计下一步就是落地。我先说结论context-mode 不需要做成一个很重的系统一个几百行的 Python 脚本就能把核心逻辑跑通。它的骨架就是三部分——上下文源、过滤规则、输出组装。我建议先用最简单的方式组织文件让每类信息都有自己的“槽位”然后按模式拼接输出。这是我的目录结构非常朴素context-mode/ ├── sources/ │ ├── module_focus/ # 聚焦模式下各模块的简况文件 │ ├── global_arch/ # 全局模式下的架构说明 │ └── decision_log/ # 回溯模式用的决策日志 ├── rules/ │ └── mode_rules.json # 每种模式的过滤与组装规则 └── build_context.py # 核心生成脚本核心思路是每个上下文源文件只维护自己的内容脚本负责按模式挑选和组装。你不需要记住一堆东西只需要在切换模式时重新跑一次脚本当前上下文的“快照”就生成好了。3.2 模式规则如何配置我把模式规则放在一个 JSON 文件里清晰可改。用一段示例来说明{ focus: { include_sources: [module_focus], max_tokens: 3000, description: 仅携带当前模块简况用于精读和改代码 }, global: { include_sources: [module_focus, global_arch], max_tokens: 6000, description: 携带模块简况和架构说明用于跨模块设计 }, recall: { include_sources: [decision_log], max_tokens: 2000, description: 检索历史决策记录用于快速接续旧任务 } }这里有一个容易被忽略的点我给每种模式都设了 max_tokens 上限。如果你的上下文源文件很多但模式预设很小那么这个模式天然就会强制你“写出更精炼的内容”。比起在对话里告诉模型“把回答控制在多少字”在输入端做限制要可靠得多——因为一旦输入的都是一堆冗长内容它很难跳出那个啰嗦的语境。3.3 核心脚本写法与扩展点写给 build_context.py 的一个最小实现示例语言用的是 Pythonimport json from pathlib import Path BASE_DIR Path(__file__).parent SOURCES_DIR BASE_DIR / sources def load_mode_rules(): with open(BASE_DIR / rules / mode_rules.json, r, encodingutf-8) as f: return json.load(f) def gather_source_content(source_name: str, keyword: str ) - str: source_dir SOURCES_DIR / source_name contents [] if source_dir.exists(): for path in sorted(source_dir.glob(*.md)): text path.read_text(encodingutf-8).strip() if keyword and keyword not in text: continue contents.append(f### {path.stem}\n{text}) return \n\n.join(contents) def build_context(mode: str, keyword: str ): rules load_mode_rules() if mode not in rules: raise ValueError(fUnknown mode: {mode}) mode_cfg rules[mode] chunks [f# Mode: {mode}] for source_name in mode_cfg[include_sources]: content gather_source_content(source_name, keyword) if content: chunks.append(content) context \n\n.join(chunks) # 这里只做简单的字符数截断实际使用时可以按 token 数估算 max_chars mode_cfg[max_tokens] * 3 if len(context) max_chars: context context[:max_chars] return context if __name__ __main__: import sys mode sys.argv[1] if len(sys.argv) 1 else focus keyword sys.argv[2] if len(sys.argv) 2 else output build_context(mode, keyword) print(output)使用方式很简单聚焦模式不带关键词直接python build_context.py focus回溯模式带一个主题词比如python build_context.py recall 订单超时它就会把所有决策日志里提到“订单超时”的条目筛选出来。这里我用了字符数当 token 数的近似字符数除以 3 估算中英文混合文本时大致可用。但这只能算个占位方案真正做到按 token 截断建议引入分词器或者直接调用模型服务商提供的计数接口。这一步看起来小实际影响很大——我踩过“以为输入没超限、结果还是被模型截断”的坑后面会细说。3.4 跟现有 AI 工具链怎么接脚本本身只负责产出上下文文本接下来怎么用取决于你习惯的工具。我当时的主流用法是先在命令行把上下文生成到剪贴板再粘贴到对话里。更顺滑一点的做法是放在 IDE 的终端面板里选中文件后直接生成贴完就走。如果你自己在开发 Agent完全可以把 build_context 的输出接入 prompt 前缀按 mode 动态拼接。有一点值得提醒不要把这些源文件一股脑都交给模型去维护。它们更适合人工维护或者由另一个简单的脚本从代码仓库自动提取——比如从 git 提交记录生成最近 diff 摘要。把“生成上下文”和“使用上下文”分成两步能让你更容易排查问题。4. 实操中反复踩到的坑与排查技巧4.1 上下文源文件越写越长触发“隐性超限”第一个坑来得很快。我刚跑通脚本时模块简况文件写着写着就从 200 字膨胀到 2000 字因为总觉得“说不定哪个细节有用”。结果就是脚本截断逻辑一直触发模型拿到的上下文被砍掉尾巴而恰好被砍掉的部分往往是决定性信息。排查方式其实不复杂跑完脚本后先检查输出的开头和结尾确认有没有被截断再检查截断点附近是不是关键信息。我后来给自己定了一条铁律——每个模块简况文件只允许写五块内容模块职责文件路径当前状态最近变更摘要待解决问题超过五块就说明信息太杂应该拆分文件而不是强行续写。这个限制看着死板但能保证每条信息都是浓缩过的颗粒度。4.2 模式间信息冲突模型“两头为难”另一个常见问题是同一个信息在聚焦模式和全局模式里的表述不一致。比如聚焦模式里写“订单模块使用 MySQL 存储”全局模式里写“订单数据经消息队列写到 HBase”。模型一看到两处矛盾它不会主动指出错误而是会选一个它觉得更合理的来“缝合”结果可能是四不像。这类问题最有效的排查手段是定期做“模式产物比对”。我会在每次大版本调整后分别生成 focus 和 global 两套上下文人工扫一眼对同一问题的口径是否一致。说起来是份苦力活但确实帮我抓出过好几次文档更新不及时的问题。如果你的上下文源本身就有自动化提取的部分记得在构建设置里加上来源时间戳至少能快速定位哪份内容过期了。4.3 检索关键词太窄回溯模式“一片空白”回溯模式很容易出现另一个极端关键词太精确了搜不到东西。比如你记得当时讨论过“订单超时自动关闭”但在决策日志里写的是“超时关单”这个关键词差就差一个“自动”结果就没搜到。我后来在决策日志里额外加了一个“别名”字段手动维护两三个同义说法。维护成本低但命中率提升非常明显。如果你不想手动加也可以简单做大小写归一、去掉无意义的“的、了、在”这类噪音词后再匹配。别急着上语义搜索纯关键词在大多数场景下已经够用。4.4 token 估算偏差导致模型输出被截断前面提到的截断问题再说一个细节很多模型 API 对输入输出是分别计数的。context-mode 只管输入侧但如果你一次生成的上下文已经接近模型窗口上限留给输出的空间就非常小。模型可能回复到一半直接断掉你会误以为是代码生成失败其实只是输出侧 token 超了。我习惯在生成上下文时留出 30% 的余量。比如模型的上下文窗口是 32K那 build_context 的 max_tokens 就设成 20K 左右。宁可少带一点背景也要保证它能完整输出。这个比例我自己测试下来比较稳你可以按任务性质微调纯代码生成任务余量可以小一些涉及长篇方案设计就得留足输出空间。4.5 频繁切换模式反而打断心流最后一个是使用习惯层面的坑。context-mode 的设计初衷是帮你管理上下文但如果每写几行就切一次模式反而会打断思路。我的经验是一个任务内尽可能少切换最好“一次聚焦做到有阶段性产出再切全局做整体校验”。具体节奏可以这样安排接到任务时先开一次全局模式理解全貌并定好实现方案动手写代码时切到聚焦模式尽量不吃不喝干完一个完整模块模块收尾后切到回溯模式拉出之前相关的决策记录做对照防止实现偏离既定结论这样切换次数是有限的而且每一次切换都有明确的目的。如果你发现自己在一小时内切了五六次基本可以断定是任务拆解得不够细根源不在模式工具上。5. 从工具到习惯context-mode 的进阶用法5.1 如何让团队也接受这套上下文思维把 context-mode 从一个个人脚本变成团队规范比想象中难。刚开始同事会觉得“多此一举”——以前直接复制文件内容给模型不就行了后来一个项目里连续出现两次上下文污染导致返工大家才开始接受。我的经验是不要强迫所有人都用你的脚本而是先推广“上下文三档思维”也就是让他们意识到“当前这次对话该让模型聚焦、全局还是回溯”。思维先统一形式可以各显神通。工具层可以做得宽松一点比如提供一个只读的 markdown 模板让同事按格式填空维护上下文源文件。大部分人不喜欢写额外文档但如果是“填空”加“选择模式”这种轻操作执行阻力会小很多。等大家体会到好处再慢慢把脚本标准化也来得及。5.2 适合往自动化方向扩展的几个点这套东西稳定运行之后有几个方向值得继续投入。第一是自动提取用 git hooks 在每次提交时自动生成 diff 摘要写到最近变更里省去手动维护。第二是增量索引决策日志积累到一定量级后用简单的向量检索替代关键词匹配回溯模式的召回率会更稳定。第三是跟 Agent 调度器挂钩让 Agent 在内部决策时自己选择该加载哪个模式而不是由人手动切换。我还没有把这三个点全部做完但从实践效果看第二个方向的收益最直接。当决策日志超过一百条关键词检索的漏召回问题会越来越明显。我最近在尝试用轻量级的向量化方案替换关键词过滤模式规则文件不需要大改只换 gather_source_content 底层的匹配逻辑即可。5.3 边界认知context-mode 不是万能药最后想给一句提醒context-mode 解决的是“信息选择与组织”问题它不能解决“模型能力不够”的问题。如果你的模型经常逻辑错乱那大概率不是上下文没喂好而是要换一个更擅长推理的模型或把任务拆得更细。做完上下文管理之后该做的提示词工程、任务拆解、结果审查一样都不能省。我自己有个简单判断标准如果上下文已经很精炼、模式切换也没问题但模型还是频繁出错那就先停下来别再调上下文了去调整任务本身的颗粒度。很多时候是把一个复杂大任务直接压在一次对话里换谁都容易翻车。6. 实测下来的一些个人偏好与参数建议6.1 文件粒度与命名规则关于上下文源文件我强烈建议按“模块”而不是按“文件”来组织。以文件为粒度会导致内容碎片化生成上下文时还得自己拼以模块为粒度一份 markdown 就够描述一个领域。命名上我习惯用模块名-状态.md比如order-pending.md、payment-refund.md。检索的时候用模块名直接定位比拍脑袋起文件名好使一百倍。6.2 三种模式下比较舒服的 token 分配我自己的项目属于中型代码库模块数大概 20 个左右以下是我实测下来比较舒服的参数区间模式携带源建议 max_tokens适用场景focus单模块简况2500 - 3500单文件或单模块精细改动global模块简况 架构说明5500 - 7000跨模块设计、接口方案评审recall决策日志检索结果1000 - 2500接续旧任务、复盘结论这个区间给的是参考不需要严格照抄。项目复杂度越高全局模式的余量就要越大但聚焦模式不应该随项目变大而无限膨胀它是用来“把事做细”的不是用来“把所有事都塞进来”的。6.3 最后一个提升效率的小技巧如果你跟我一样经常在同一个任务里反复切换模式可以考虑给脚本加一个“快照缓存”。按相同模式和相同关键词生成过的上下文如果源文件没有变化就直接复用上次的结果省去重新遍历文件的时间。对于大仓库来说这个优化能明显改善使用体验。实现的话就是在输出目录里按关键词哈希存一个缓存文件每次构建前比一下源文件的修改时间即可。说句实在话context-mode 这套东西本身没有太高深的技术含量它更多是一种使用思路的转变别再跟 AI 玩“信息填鸭”学会给它剪裁出最合适的视野。只要养成了这个习惯你会发现同样一个模型产出的质量能有非常明显的提升。