做AI工具的人应该都有过类似的体验：模型回答得“驴唇不对马嘴”，你前一句话它还记得，隔了几轮它就像失忆了一样。尤其是本地跑大模型、写自动化脚本或者做个人知识库助手的时候，这个问题特别明显。我自己维护的一个本地开发辅助工具就卡在这里很久，直到我把“上下文怎么组织”这件事彻底重做了一遍，做成了一个独立的模块，起名就叫context-mode。简单来说，它是这套工具里专门负责“决定该让模型看到什么”的模块，解决的是上下文窗口有限、历史消息膨胀、多文件项目信息零散这三件最让人头疼的事。
这篇文章不打算写成一层层的文档说明，我就按实际做这个模块的过程来聊：为什么要专门做一个“上下文模式”，它的核心设计思路是什么，实现的时候哪些环节最容易翻车，以及怎么配置、怎么调、怎么排查。不管你是想给自己的AI项目补一段上下文管理逻辑，还是单纯好奇这类功能怎么落地，这篇都值得顺着往下看。
1. 为什么要专门做一个“上下文模式”
1.1 上下文不是越多越好，而是“越合适越好”
很多人一开始的想法特别朴素：上下文嘛，把对话历史、文件内容、检索结果全部拼在一起扔给模型，模型总能找到有用的信息。但真跑过一次就知道，这条路根本走不通。大模型的输入窗口虽然越来越大，但token是实打实要成本的，而且上下文一长，模型对关键信息的聚焦能力会明显下降。你塞了一堆代码文件进去，它反而抓不住你真正想问的那一段。
我最初也踩过这个坑，把项目目录下所有源码都读进prompt，结果模型开始一本正经地分析无关的配置文件，真正要改的逻辑反而没注意到。后来我想明白一个道理：context-mode存在的意义不是“无脑多塞上下文”，而是“按需选择上下文”。我们需要给对话、工具或代码补全功能一个明确的能力——在不同场景下，决定哪些上下文值得进入窗口，哪些应该被丢弃或压缩。
1.2 没有Context模式时的典型痛点
如果不用一个专门的模块来管上下文，你会持续遇到几类问题：
第一，会话历史越滚越长，直接打到上下文上限。这个问题在本地部署场景尤其致命，因为硬件算力本来就有限，输入token一多，推理速度肉眼可见地变慢。第二，Ottoman，“旧信息把位置占了，新信息进不来”。第三，多轮对话中间穿插了代码修改、文件切换后，模型完全不知道当前你在做哪个文件。第四，不同任务需要不同粒度的上下文，比如随手问一句“这个函数在哪个文件”，跟“把整个模块重构一遍”，需要的上下文完全不是一回事。
这些问题光靠调prompt是解决不掉的，必须在代码层面建立一个有结构、有策略的上下文管理机制。context-mode的核心就是把“上下文组织策略”抽出来作为一个可配置、可切换的模块，让上层应用在不同场景下自动选择最合适的组合方式。
1.3 它的适用范围和场景
有必要说明一下，context-mode不是一个面向终端用户的可视化功能，它的定位更接近“底层能力模块”。你可以把它挂在AI编程助手上，也可以挂在本地知识库问答系统、命令行工具、自动化脚本里。只要是“把若干来源的信息拼给大模型”的场景，它基本都能派上用场。
我这边实际使用最频繁的场景是本地开发辅助工具里的三个功能：代码问答、文件生成、修改建议。过去三个功能共用一套上下文拼接逻辑，效果很一般。后来给它们各自配置了不同的上下文模式，才明显感觉到回答质量上了一个台阶。这也是为什么我觉得有必要把它单独做成模块而不是混在主业务里，因为它的调整频率和对业务逻辑的独立性，比大多数人想象的高得多。
2. 整体设计与三个核心模式拆解
2.1 设计目标与三层架构
开始写代码之前，我先明确了context-mode模块的几个设计目标：可插拔、可观测、可配置。可插拔意思是上层业务不应该关心上下文怎么拼，只调接口传参数就行；可观测是说每一次组装上下文之后，要能知道用了哪些来源、花了多少token；可配置则是说不同场景可以通过配置切换策略，不用改业务代码。
最终我采用了三层架构：第一层是数据源层，负责采集所有候选上下文片段，包括对话记录、文件内容、检索结果、工具输出等；第二层是决策层，根据当前模式对候选片段做评分、筛选、排序；第三层是组装层，按照token预算把筛选出的片段拼成最终prompt。context-mode从外部看就是一个接口，输入是一堆候选片段加一个模式标识，输出就是拼好的上下文块和对应的token统计。
这个架构的好处是每一层都能单独测试。数据源层可以独立验证每个来源抓取是否完整，决策层可以单独调评分参数，组装层的token截断逻辑可以针对不同模型的计费规则做适配。对后期排查问题来说，这种分层真的是省了大劲。
2.2 核心模式一：auto模式
auto模式是这个模块里我最推荐默认开启的模式，它的核心思路是“所有候选上下文都参与打分，但只有分数够高、相关性够强的片段才进入最终上下文”。这里面的关键就是一个好的评分函数。
我最初用的评分逻辑比较简单：文本重叠度加上关键词命中数。效果只能说勉强能看，最大的问题是遇到同义表述就抓瞎。后来升级成了两步评分：先用轻量级的BM25粗筛，把明显不相关的片段砍掉；再用向量相似度做精排，选出最匹配的若干片段。虽然多了一步向量计算的消耗，但准确率提升非常明显。
auto模式里还有个重要设计叫消息衰减权重。时间越早的对话消息，相关度权重越低，但不是直接删除。这样既兼顾了最近对话的核心信息，又保留了早期可能存在的关键铺垫。你可以在配置里调整衰减系数，默认值是0.9，意思是每往前一轮，权重衰减10%。这个值我觉得对大多数场景是合适的，但如果你的项目特别依赖早期交代的规则，建议把衰减系数调到0.95以上。
2.3 核心模式二：replay模式
有些场景下，光靠“相关性筛选”是不够的。比如你让模型帮忙审查一个前前后后改了三十轮的文件，中间涉及大量历史修改原因，这种时候必须让模型看到完整上下文轨迹，一个片段都不能漏。这就是replay模式存在的意义。
replay模式的策略是“按时间线完整回放指定的上下文来源”，它不做筛选，只做组织和截断。优先保留系统提示词和最先交代的任务目标，然后把对话历史、操作记录按时间顺序完整保留，最后才考虑附带资源文件。
这个模式对token的消耗是最高的，所以我做了一个保护机制：当历史内容超出预算时，不是从头开始截断，而是从最早的记录开始压缩。怎么压缩呢？分两种情况：如果一段历史只有两三轮，直接丢弃太可惜，就把它变成一个简短的摘要；如果摘要本身已经存在，就继续摘要旧的、保留完整的新内容。这样能保证模型看到的永远是“完整脉络+最新细节”，而不是断断续续的碎片。
replay模式特别适合三种场景：代码审查、长文档校对、多步骤任务执行。如果你发现模型经常“忘记”最开始交代的目标，很可能就是因为它一直用的是auto模式的筛选逻辑，而这时就应该切到replay模式。
2.4 核心模式三：global模式
第三种模式叫global模式，它是专门用来处理“长期稳定信息”的。什么是长期稳定信息？比如项目的技术栈、代码风格约定、API使用规范、用户的偏好设置、之前决定过的方案等。这些信息的特点是：非常重要、长期不变、但每一次对话都可能用到。
我在做global模式的时候参考了RAG的思路，但做了很大简化。不搞复杂的向量库，因为它本质上是一个频繁读取的静态配置，我直接维护了一个按优先级排序的全局上下文库，每个条目有固定的优先级和业务标签。比如项目约定的代码风格是优先级最高的标签，用户偏好设置排第二，常见问题排第三。组装上下文时，global模式会先把这些固定片段放进去，再根据剩余预算加入会话历史的检索结果。
这里有个细节挺重要：全局上下文库的内容最好不要直接以原始文本入库，而是应该做成“精简条目”。比如“项目使用Python 3.10”这条，不要存成“我们在项目里使用Python 3.10版本，这是我们之前讨论决定的”，而是直接存成结构化条目：[tech-stack] python=3.10。这样既省token，又方便后续程序化处理。我用下来以后发现，这种方式比存完整文本的效率高一倍不止。
3. 实操过程与核心环节实现
3.1 先做配置结构，把模式的“开关”立起来
context-mode第一步不是写打分逻辑，而是先把配置结构定下来。因为这个模块是给多个业务场景复用的，每个场景的模式可能不一样，如果配置不清晰，后面一定乱。
我用的配置文件是YAML格式，核心结构是一个模式枚举加上每个模式的独立参数：
context_mode: enabled: true default_mode: auto modes: auto: use_bm25: true use_vector: true top_k: 8 decay_factor: 0.9 min_score: 0.35 replay: max_history_turns: 60 summary_before_truncate: true preserve_first_turns: 3 global: priority_tags: ["code_style", "user_pref", "tech_stack"] max_global_entries: 20 retrieve_after_global: true这里每个字段背后都有讲究，我挑几个重点说。min_score是auto模式里最低通过分数，我一开始没设，结果一些相关性不太行但“能沾边”的片段总会被塞进去，回答经常跑偏。设了0.35以后，整体质量稳定了很多。preserve_first_turns是replay模式里一个容易被忽视的字段，作用是不管后面怎么压缩，最开始几轮交代的任务目标必须原样保留，这个值设为3对我来说是个稳妥的平衡点，太少了容易丢失任务起点，太多了又浪费token。
3.2 实现候选上下文采集与评分
数据源层我设计了一个统一的候选片段结构，它长这样：
@dataclass class ContextCandidate: source: str # 来源: "chat", "file", "search", "tool" content: str # 片段内容 timestamp: float # 时间戳 metadata: dict # 额外的元信息，如文件路径、消息角色 score: float = 0.0 # 打分后的分数，默认0不管上层业务传来的是对话消息、文件内容还是搜索结果，一律包装成这个结构，然后塞进决策层去做统一处理。这样上层代码会非常干净，不用知道内部是怎么打分的。
打分过程的顺序也很重要。我是先算基础分数，再乘时间衰减权重，最后结合业务权重调整。基础分数就是前面说的BM25+向量相似度融合，具体的公式是：
基础分 = 0.4 * bm25_score + 0.6 * vector_similarity 最终分 = 基础分 * (decay_factor ** age)这里面有个藏得很深但很关键的点：向量相似度在短文本上的表现很不稳定。一个只有十几个字的短消息和一个几百字的长文档，用向量相似度对比时，短消息经常拿到虚高的分数。我的处理方式是给不同来源加了不同的权重系数：文件内容的向量相似度权重高一点，对话消息的基础上分权重高一点。这两种数据特征不一样，得分逻辑就不该完全一致。
3.3 token预算分配与截断逻辑的实现
上下文拼装的最后一步是预算分配。每个模型有自己上下文上限，通常不能把窗口完全占满，因为还要给模型的输出留空间。我的经验是输入token控制在总窗口的50%到60%之间，剩余留给输出和临时变量。
def assemble_context(candidates, mode, total_budget): if mode == "auto": ranked = sorted(candidates, key=lambda c: c.score, reverse=True) elif mode == "replay": ranked = sorted(candidates, key=lambda c: c.timestamp) elif mode == "global": ranked = sort_by_priority_then_score(candidates) else: raise ValueError(f"unknown mode: {mode}") used = 0 result = [] for cand in ranked: cost = estimate_tokens(cand.content) if used + cost > total_budget: # 预算不足时尝试截断当前片段，而不是直接跳过 trimmed = trim_to_fit(cand.content, total_budget - used) if trimmed: result.append(trimmed) break result.append(cand.content) used += cost return "\n".join(result), used这个实现有意识地解决了两个常见问题。第一个是“预算不足时不要直接跳过当前片段”，因为很多场景下这个片段恰恰是最关键的，截断一部分内容保留关键开头，比彻底丢掉好得多。第二个是“截断必须以语义边界为准”，这里的trim_to_fit会优先在段落边界截断，其次是句子边界，实在不行才在字符级截断。如果直接按固定字符数硬切，很容易把代码块、表格、或者markdown语法切成残缺状态，模型看到以后轻则格式乱掉，重则直接出错。
这里还要提一个我自己踩过的坑：不同tokenizer对中文的计费差异特别大。有些模型把中文一个字算一个token，有些按词切分，同样一段内容在不同模型上的token估算差异可能超过50%。所以estimate_tokens不能用统一规则，我是在配置里给每个模型预设了一个token_ratio参数，相对于英文token数的倍率，中文场景基本在1.5到2.0之间。有一段时间我没注意这个问题，上下文预算总是莫名其妙的爆掉，排查了很久才发现是token估算偏小导致的。
3.4 接入业务层的完整调用流程
模块内部实现得再漂亮，接入方式太复杂也会让业务方不想用。我的做法是把context-mode对外暴露成一个极其简单的调用入口，只有两个参数：请求类型和原始输入。
ctx_response = context_mode.process( scene="code_review", # 业务场景，自动映射到对应模式 user_input="帮我看看auth模块有没有安全问题", candidates=collect_all_candidates(), # 由外部负责采集 ) # 拿到的输出 prompt = ctx_response.prompt stat = ctx_response.token_usage内部会根据scene自动决定走auto、replay还是global，并加载对应的配置参数。业务方完全不需要知道决策逻辑。而采集候选这个动作为什么要放在外部？因为不同业务场景下的数据来源完全不同，代码问答要读项目文件，知识库问答要检索文档，这些逻辑本身就应该留在业务侧。
接入后我加了一个运行时监控池，每完成一次组装，都会把候选片段的来源分布、得分情况、最终保留率记录下来。这样后续调参的时候，不是靠感觉说“这个模式效果不太好”，而是能直接看数据。比如某个场景下发现文件类片段的保留率过低，就可以针对性调整文件来源的权重。这种反馈闭环对持续优化特别重要。
4. 常见问题与排查技巧实录
4.1 模式不生效，切了等于没切
这个是我接到反馈最多的问题：明明在配置里把默认模式改成了replay，但跑起来之后感觉跟之前一模一样。排查下来发现大部分人都犯了一个低级错误——改了配置文件，但没有触发模块的热加载机制。
我的解决方案是两层的。第一层，配置文件有变更时，可以通过监听文件修改事件自动刷新配置，但这需要额外引入watchdog之类的监听库，不是所有环境都方便。第二层，因为没有全局刷新机制，接口每次调用时都会读取配置的mtime做一次快速对比，发现有变化就重新加载配置。但如果不支持热重载，那就需要主动调用一次context_mode.reload()。在排查问题的时候，大概率就是某个场景提前创建了配置对象，后续调用一直沿用旧配置，所以模式切换没生效。
4.2 拼出来的prompt内容破碎或者格式混乱
这个问题在代码场景尤其常见。诊断信息显示模型经常收到没有缩进的Python代码块、被拦腰截断的JSON片段、或者结尾缺少闭合括号的SQL。本质上都是截断逻辑过于粗暴导致的。
规避的核心办法就是前面说的“语义边界截断”。代码场景要识别代码块边界，不能从函数体中间切断；文档场景要找段落和换行；对话消息要按完整问答对截断，不能把回答的中间部分直接暴露给模型。还有一个反直觉的细节：有时候主动舍弃一部分上下文，比“长截断后再拼上”效果更好。我发现与其保留半个残缺代码块，不如干脆把这一轮丢弃，让模型明说“相关信息不足”，然后由上层去触发检索或追问。这在实践中反而能减少幻觉式的错误回答。
另外，如果你的候选片段是markdown格式，拼入prompt之前建议做一次格式规范。不要求完全统一，但至少标题层级要一致，代码块语言标识要正确，列表缩进不能乱。因为大模型本身依赖格式来推断结构，格式乱了，理解也会跟着乱。
4.3 填了token预算上限，模型还是说“信息被截断”
这类问题通常不是因为代码里没做截断，而是因为estimate_tokens估出来的数字和实际模型计费口径对不上。我在之前提过，不同模型中文token差异很大，这里实际出现的情况是：估算函数说用了4000个token，但模型实际消费了6500个token，上下文直接超限。解决方法是给每个部署端配置独立的token预估值，并通过实际调用日志反向校准。校准公式很简单：
实际token = 模型返回的usage字段中的total_tokens 估算偏差率 = (实际token - 估算token) / 估算token把连续多次调用的估算偏差率取平均值，然后在代码里做同步修正。我自己的模块上线初期就发生过一次偏差率高达72%的情况，修正后上下文超额的问题立竿见影地消失了。
4.4 候选片段太多，打分耗时过长
如果项目规模上来了，可能一次问答会采集几十个甚至上百个候选片段，逐一打分的时间会有隐患。实测下来，纯粹的BM25精排和向量相似度计算，在100个片段级别延迟在100毫秒左右，但如果在本地用CPU跑向量模型，延迟会成倍增长。
一种革命性的做法是在数据源层就增加一次轻量预过滤。第一次粗暴过滤掉一半无关内容，再进入精细评分。比如先把全部候选按“是否包含当前用户输入中的关键词”过一遍，命中规则之外的直接降低优先级，这样精细评分阶段需要处理的片段数量大大减少。代价是有极低概率误伤有效内容，但对大部分场景来说，这个风险是可接受的。
4.5 常见问题速查表
| 现象 | 大概率原因 | 处理思路 |
|---|---|---|
| 模式切换没效果 | 配置缓存未刷新 | 检查是否调用reload，确认配置对象mtime |
| prompt中代码不完整 | 字符级硬切 | 改用段落/代码块边界截断 |
| 输入token超限 | 估算口径偏差 | 按模型usage字段反向校准估算系数 |
| 回答频繁跑题 | min_score设置过低 | 提高阈值，检查是否有低分片段混入 |
| 上下文组装耗时高 | 候选未做预过滤 | 增加关键词预过滤层，压缩精细评分数量 |
| 早期对话信息丢失 | 衰减系数过小 | 调高decay_factor或切换到replay模式 |
5. 一点实操心得：什么才是一个好用的上下文模式
如果让我提炼一句做context-mode最重要的经验，我会说：上下文管理的本质是预算管理和信息分层，你不可能把所有信息都塞进去，但你可以让真正重要的信息始终在窗口里。模式的意义就是让这个过程感知到场景差异，自动调整策略。
实际做下来以后有几点心得值得分享。一是别追求“通用最优”，auto模式确实能覆盖大多数情况，但代码审查和长文档处理这类场景必须切replay，基础问答才适合auto。二是上下文模块的日志和监控一定要从第一天就接上，没有监控的话，你怎么调参数都是盲猜。三是宁可少放一个片段，也不要把片段截成半截子丢给模型，这个教训花的代价挺大。
如果你正在做类似的功能，完全可以参考我上面讲的三种模式和那套三层架构，先把候选采集、决策筛选、组装截断这三层逻辑搭出来，再逐步丰富模式细节。配置参数的调整没有标准答案，建议你先在auto模式下用默认参数跑上一段时间，收集一些实际案例，再针对性地做调整。我现在的方案也是这么迭代出来的，每个参数背后都有一次真实问题的支撑。
最后顺手补充一个很多人不太注意的小细节：context-mode在设计时候还留了一个“强制保留区”的概念，可以手动指定某些片段无论如何都必须在prompt里。这个功能在我处理紧急bug排查时特别好用——比如某个崩溃日志已经定位到了，后面无论聊什么，它都会固定出现在上下文里，模型不会突然忘记它。如果你也经常和长会话打交道，建议在你的实现里把这个保留机制加上，它救场的频率比你想象得高。
