大模型上下文窗口管理实战：context-mode 的分级注入与折叠机制

最近在折腾 AI 辅助编程时，我一直在跟一个问题较劲：上下文不够用，或者用不对。去年做了个小模块，代号叫context-mode，专门用来解决大模型在代码场景下上下文窗口越用越碎、越用越乱的问题。它在 IDE 里帮我管理对话上下文和文件上下文，保证该记住的东西不丢，不该塞进来的东西不占地方。这几个月实测下来，它的确让我的 AI 编程效率上了一个台阶，至少不用每聊几句就手动清理对话了。

这篇东西不是某个开源项目的官方文档，只是我把自己从需求分析、方案设计、代码实现到实际踩坑的整个过程整理了一遍，希望对正在做 AI 辅助编程工具、写 LLM Agent，或者单纯被上下文窗口逼疯的读者有些参考价值。

1. 为什么需要 context-mode：AI 编程时上下文到底乱在哪

先说一个很多人可能没意识到的现象。大语言模型的上下文窗口虽然在不断增大，从早期的 4K、8K 到现在的 128K、200K，表面看起来足够塞下一个中型项目的多个文件。但实际用起来完全是另一回事，尤其在辅助编程场景里，上下文窗口的有效容量远低于标称值，因为模型需要对“最新指令”和“关键文件结构”保持高度敏感，一旦上下文里塞满了无关历史对话，模型的注意力就会分散，回答质量和指令遵循度会明显下滑。

1.1 上下文“不够用”其实不是容量问题，而是管理问题

我一开始也以为是容量问题，后来在项目里盯了几周 token 消耗才发现，真正的问题在于浪费。一个常见的场景是这样的：你让 AI 帮你改某个模块，聊着聊着，AI 把相关的三个文件内容都贴进了对话，接着你们又讨论了七八轮修改意见。这时候上下文窗口里可能已经塞了十几个文件的不同版本，其中大部分内容已经过时了。你后来说“把刚才那个函数改成异步”，AI 反而去改了函数的一个旧版本，因为新版函数早已被挤出了窗口，或者被淹没在了历史对话里。

这就是典型的上下文管理缺失。缺的不是容量，而是对上下文的组织、筛选和淘汰机制。

1.2 多任务并行是上下文混乱的重灾区

另一个问题出现在多任务并行时。真实开发中不会有人只聊一个需求。我经常上午让 AI 帮我看某个接口的报错，下午又让它设计另一个模块的表结构，晚上还要它重构一段老代码。这三件事如果都在同一个对话里发生，AI 会说“根据之前的背景”然后开始胡说八道，因为不同任务的上下文彼此污染。上下文窗口里的信息既有当前任务的核心代码，又有上一个任务遗留的中间产物，模型无法可靠地区分哪些与当前任务相关。

这也是我在设计 context-mode 时最优先考虑解决的场景。它本质上是在对话系统中建立一种“任务隔离”的机制，让不同任务的上下文互不干扰，同时让当前任务的核心信息始终处于模型中优先级最高的位置。

1.3 从 IDE 插件到 Agent 框架，所有接入 LLM 的工具都需要上下文管理

一开始我以为这只是 IDE 插件才需要面对的问题，后来发现只要用 LLM 做稍微复杂一点的事情，都需要这个能力。比如写一个自动提交 PR 的 Agent，它需要同时知道当前分支的改动范围、相关文件的历史修改、测试结果、代码风格约束，而这些信息分散在不同工具和流程里，如果一股脑全传给模型，不仅 token 消耗夸张，模型还会被噪声信息带偏。

所以我把 context-mode 做成一个相对独立的上下文管理模块，它不为某个特定的 IDE 或框架服务，而是提供一组通用的接口：注册上下文源、计算优先级、裁剪过期内容、按需注入。这样不管接的是 IDE 插件、终端助手还是 CI 里的自动化脚本，同一套上下文策略都能复用。

2. context-mode 的核心设计思路：分级上下文与动态注入

设计这个模块时，我最开始尝试的是一个很直白的方案：每次请求前，把相关的文件内容、对话历史、指令按固定顺序全都拼起来发给模型。简单粗暴，但很快在真实使用中暴露了问题，最明显的是 token 超限和模型“遗忘”关键指令。

后来我参考了操作系统内存分页的思路，设计了分级上下文机制。这个机制是整个 context-mode 的地基，后面所有的功能都是围绕它生长的。

2.1 三级上下文划分：核心、工作、归档

我把上下文分成三个层级，分别是核心上下文、工作上下文和归档上下文。每个层级的存储位置、更新频率、注入优先级都不同。

核心上下文保存的是长期有效且绝不能丢失的信息，比如项目技术栈、代码风格约定、当前任务的总目标、关键架构约束。这类信息通常体量不大，可能只有几百个 token，但必须保证在每次请求中都出现。工作上下文保存的是当前任务正在操作的代码片段、最近的修改记录、最新的用户指令，这部分信息变化最快，也是最容易把窗口撑爆的地方。归档上下文则是历史对话摘要、已经完成的旧任务记录、暂时不需要但又不能彻底删除的信息，正常情况下不会被注入，只有在需要回顾时才会被临时调取。

这三级的划分让我在控制 token 预算时有明确的抓手。核心上下文是固定开销，工作上下文是弹性开销，归档上下文是可选开销。

2.2 动态注入：不是“全塞进去”，而是“按需放进来”

动态注入的核心逻辑是：在每轮请求前，系统根据当前指令和已知上下文，计算出一个最小必要集合，只把这个集合发给模型。这个计算过程不是简单的长度截断，而是基于相关性打分的筛选。

我实现了一个轻量的相关性评分机制。每一条上下文片段都有一个元信息，包括来源文件、最近访问时间、被任务引用的次数等。当新指令进来时，我会提取指令中的关键词，与各个上下文片段的标签做匹配，同时结合时间衰减因子，把分数算出来。得分高的片段进入工作上下文，得分低的在需要时从归档里拉取而不是直接丢弃。

2.3 为什么不用向量数据库做上下文召回

说到相关性筛选，可能有人第一反应是引入向量检索，给文件内容和对话历史做嵌入，然后靠语义相似度召回上下文。这个方案我也认真考虑过，但最终没有在 context-mode 里做，原因很简单：延迟和成本。每次请求前如果都要做一遍向量检索，多出来的耗时虽然没有到不能容忍的地步，但在 IDE 这种交互场景里，任何超过 200 毫秒的额外等待都会影响体验。

更重要的是，编程场景中的相关性往往不只是语义相关，还有强结构相关性。比如用户修改了文件 A 中的某个函数，这个函数的调用点在文件 B 中，那么文件 B 的相关性不是由语义相似度决定的，而是由符号引用关系决定的。向量检索处理不了这种精确的依赖关系，但一个简单的文件依赖图谱可以。所以我用了一个更朴素的方式：维护一份文件依赖索引，只要当前指令涉及某个符号，就自动把符号的定义处、引用处列为核心候选。效果很直接，几乎没有额外延迟。

2.4 上下文折叠：让不重要的信息“退场”

除了按需注入，context-mode 还有一个关键机制叫上下文折叠。它的作用是把暂时不需要完整呈现的上下文片段，替换成一个更紧凑的摘要。比如某段历史对话本来有 2000 个 token，折叠后就变成了一句“用户已确认数据迁移方案，待实施”，只占 20 个 token。等到后续指令真的涉及迁移细节时，再展开回完整版本。

这个机制借鉴了编辑器的代码折叠思路。代码折叠不删除代码，只是暂时隐藏细节，让视野集中在当前关心的区域。上下文折叠也一样，不丢掉信息，只是让信息以更经济的方式存在。为了实现折叠和展开，我给每条上下文片段都保留了原始文本和摘要文本两种形态，并维护了一份折叠状态表。这套方案在今天的大模型应用场景里尤其重要，因为无论窗口多大，总有比你项目代码量更大的可能性。

3. 具体实现：一个最小可用的 context-mode 完整流程

这一节我会把 context-mode 的核心实现拆开讲。它不是什么高深的东西，但细节确实很多，我会尽量按一个可复现的路径来说明。整体模块由四部分组成：上下文片段管理器、相关性打分器、注入编排器、折叠与恢复器。

3.1 上下文片段的数据结构设计

我首先定义了一个统一的数据结构，叫 ContextFragment。它是所有上下文信息的基本单位。字段包括 fragment_id、fragment_type、source、level、content、summary、metadata、last_access_time。fragment_type 分为 user_instruction、file_snippet、conversation_turn、tool_result、summary_fragment。level 就是前面说的核心、工作、归档三级。

class ContextFragment: def __init__(self, fragment_id, fragment_type, source, level, content, summary=""): self.fragment_id = fragment_id self.fragment_type = fragment_type self.source = source self.level = level self.content = content self.summary = summary self.last_access_time = time.time() self.access_count = 0 self.tags = set()

这里每个片段都保留了 summary 字段，这是实现折叠功能的基础。summary 的生成策略是：当片段进入归档层级时，如果它还没有 summary，就用模型生成一次摘要并缓存。由于只有降级时才会触发摘要，实际调用模型的频次很低，不会造成明显的 token 成本。

3.2 相关性评分与候选集生成

相关性评分器是 context-mode 里逻辑最集中的部分。我给它设计了一个简单的打分公式，分数由三部分构成：关键词匹配得分、符号引用得分和时间衰减因子。

关键词匹配得分相对直观，把用户当前指令分词后，与片段的 tags 和 content 做朴素匹配，命中越多得分越高。符号引用得分是编程场景特有的，如果片段涉及的代码符号在当前指令中被提到，直接加一个较大的固定分值。时间衰减因子用指数衰减实现，片段最近一次访问距今越久，分数折损越大。

def score_fragment(fragment, instruction_tokens, symbol_hits): base_score = 0.0 matched = 0 for token in instruction_tokens: if token in fragment.tags: matched += 1 base_score += matched * 2.0 base_score += symbol_hits * 10.0 time_decay = math.exp(-(time.time() - fragment.last_access_time) / 3600) return base_score * time_decay

打分完成后，按分数从高到低排序，依次把片段放入注入候选集，直到 token 预算几乎用完。token 预算的计算方式是：从模型上下文窗口总长度里，先扣除核心上下文的固定占用，再扣除系统提示词的占用，剩下的是工作上下文的可分配空间。

3.3 注入编排器：如何决定最终发给模型的完整提示词

注入编排器的主要工作是把候选集中的片段按一定顺序组装成最终的完整上下文。顺序看起来是个细节，实际影响很大。模型对上下文开头的关注度通常高于中间，对结尾的关注度也较高，这是普遍经验。所以编排器会把核心上下文放在最前面，紧接着是当前用户指令，然后是与指令直接相关的工作上下文片段，最后是一段自动生成的“当前任务状态摘要”作为收尾。归档片段默认不参与注入，除非某条归档片段的分值异常高，说明用户明确在追问历史信息。

另外，我还做了一件很关键的事：在注入内容之前，先注入一段自动生成的“上下文说明”，告诉模型哪些片段是当前有效的、哪些是从归档里临时调取的、哪些是折叠摘要。这听起来有点像给模型写小纸条，但实测下来能明显减少模型把旧版本代码当现版本来修改的错误。因为模型看到“这段代码来自历史版本，仅供了解思路”的标注后，引用时会更谨慎。

3.4 折叠与恢复的具体策略

折叠机制的触发条件有两种。第一种是容量触发，当候选集的总 token 数超过预算时，从低分片段开始折叠，替换成 summary。第二种是时间触发，当某条工作上下文片段超过 30 分钟未被访问时，自动降级为归档并折叠。恢复操作发生在相关性打分器发现某条折叠片段与当前指令高度相关时。恢复不是简单地把 summary 换回 content，而是把 content、summary 同时注入，并标注“此片段刚刚从摘要状态展开”，让模型知道这是最新完整版本。

这里有一个值得注意的细节：折叠摘要的摘要对象不是笼统的“这段对话讲了什么”，而是“在这个项目的当前状态下，这段信息意味着什么”。比如对于一段讨论某个接口签名变更的对话，折叠摘要应该写成“接口 get_user_info 已将返回字段从 user_name 改为 display_name，所有调用方需同步调整”，而不是“用户和助手讨论了重命名问题”。前者是项目状态下可执行的信息，后者只是对话话题的记录。为了让摘要更可用，我在生成摘要时的提示词里特意强调了这一点。

4. 工具选型与参数选择：这些数字是怎么定下来的

从零开始实现 context-mode 时，最折磨人的不是功能逻辑，而是那一堆参数。上下文窗口分配比例、时间衰减系数、触发降级的访问间隔、相关性分数的阈值，这些数字直接决定了整个模块的使用体验。我最初都是凭感觉填的，后来踩了不少坑才找到一个相对合理的组合。

4.1 上下文窗口的预算分配

对于默认使用 128K 窗口的模型，我的分配方案是这样的：系统提示词预留 2000 token，核心上下文预留 4000 token，工作上下文最多 8000 token，归档唤醒区预留 2000 token，响应输出预留 8000 token，剩下的空间全部作为缓冲，尽量不动用。为什么给工作上下文只留 8000 token？因为我统计了自己平时在 IDE 里的真实交互，单个任务如果连续修改超过 8000 token 的代码内容，通常意味着这个任务应该拆分子任务，否则对话本身已经太长，模型的指令遵循质量会明显下降。

这个比例不是通用的。如果用的是 32K 窗口的模型，工作上下文就得压缩到 3000 token 左右；如果项目本身特别大，核心上下文可以提到 6000 以上。关键是预留出一块永远不碰的缓冲空间。我之前犯过的错就是死顶窗口边缘，结果模型偶尔要生成长答案时被截断，最后输出不完整。

4.2 时间衰减系数与访问权重的调参过程

时间衰减系数是我调整次数最多的参数。一开始设的是 half-life 为 30 分钟，意思是 30 分钟没访问的片段，相关分就少一半。结果发现日常开发里这个值太敏感，我上午打开一个文件看了一眼，下午真正要改它的时候，它的片段已经被严重降权，关联信息找不到了。后来我把 half-life 调到了 6 小时，效果明显变好。但对同一场景里的短任务，6 小时又显得迟钝，用户刚刚聊完另一个话题再切回来，旧任务的片段仍占着高权重，污染新任务。

最终的解决方案不是改一个固定值，而是把 half-life 参数与任务状态绑定。当 context-mode 检测到用户切换了任务意图，立即给所有旧任务相关片段施加一个额外的时间惩罚，相当于强制快进老化过程。判断任务意图切换的方式很粗但很有效：如果连续两条用户指令中，关键词重叠度极低，且中间间隔超过 5 分钟，就认为发生了任务切换。这个规则在绝大多数场景下都能正确识别。

4.3 为什么选择 JSON 作为上下文片段存储的载体

很多同类工具会直接用 SQLite 或者向量库做持久化，context-mode 最终选了 JSON 文件。原因有两个。第一，上下文片段的使用模式是读多写少，而且每次启动时要把所有片段加载到内存做索引，JSON 的层级结构天然适合表达片段之间的父子关系。第二，调试太方便了，我可以随时把整个上下文快照导出来，逐行检查模型到底看到了什么，Sqlite 虽然查询能力强，但平时用不到，反而多了个依赖。

{ "fragments": [ { "fragment_id": "c001", "type": "file_snippet", "source": "src/services/order.py", "level": "working", "content": "def create_order(user_id, items): ...", "summary": "订单创建入口，校验库存后写入订单表", "last_access_time": 1728000000, "tags": ["order", "create_order", "inventory"] } ], "token_budget": 32768, "model": "deepseek-chat" }

JSON 文件也不是没有缺点，量大了之后每次全量读写会有性能压力。但 context-mode 的设计目标本来就是单机单项目，一个项目撑死几千个片段，JSON 完全扛得住。真要做成服务端多租户架构，那时再换存储引擎也不迟。

5. 实操中的踩坑记录与排查指南

写 context-mode 的过程里，有一个阶段让我印象特别深：功能都已经实现了，但怎么调都不对劲。模型看起来是有上下文了，不过在关键时候总犯低级错误，比如拿旧代码当新代码，或者无视用户的明确指令。那段时间我一度怀疑是提示词写得不好，后来一点点排查才发现，真正的问题全都出在上下文管理的细节上。

5.1 折叠摘要把关键约束给折叠掉了

第一次严重翻车就出在摘要上。我有一个片段是用户明确要求的“不要修改任何测试文件”，因为 summary 生成时我用的提示词太强调“总结代码变更”，导致摘要把这条约束给丢了。后续对话中这个片段被折叠，模型就真的去动了测试文件。修复方式是在生成摘要时增加一个保底逻辑：如果原内容里包含明显的否定性约束词或者命令式指令，摘要里必须原样保留这些句子，不能改写。看起来是个很傻的修复，但确实有效，我后来把这条规则扩展成了三类必须原文保留的内容：安全约束、明确否决指令、关键命名规则。

5.2 符号相似导致相关性误判

相关性打分器还有一个坑，就是符号名的误匹配。比如用户当前在改 login 函数，打分器把和 login 相关的所有片段都招了回来，其中包括一个根本没关系的数据库表 login_log 的建表语句。这会导致上下文中出现大量噪声。后来我给符号匹配加了个约束：不仅是名称匹配，还要考虑调用链深度。如果当前指令提到了 login，那么 login 函数本身的定义和调用方优先召回，而 login_log 如果与 login 没有直接函数调用关系，只是名字相近，评分就大幅降低。这个调整让召回准确率提升了不少。

5.3 归档恢复时的版本冲突

还有一个很隐蔽的问题，发生在归档片段被恢复时。假设某段代码最早在工作上下文里，后来被折叠进了归档，而这段时间用户已经改了代码，最新版本的片段应该覆盖旧版本。但恢复机制只负责把折叠片段展开，没有校验展开后是否与当前文件内容一致。结果模型同时收到了旧版本代码和新版本代码，产生了严重的版本幻觉。解决方式是恢复前强制从文件重新读取最新内容，比对后再展开，不一致的话直接丢弃归档版本，以文件当前内容为准。

5.4 常见问题速查表

下面这个表是我在实际使用中总结的典型问题、表现和排查方向。

5.5 调试时最常用的一招：导出完整快照

context-mode 里我留了一个隐藏功能，就是把每一轮请求前计算好的注入结果导出为一个 JSON 文件，包含最终拼好发给模型的完整内容、每段来源、每条片段的分数和 token 数。每当模型行为异常，我就拿这个快照去逐行看，问题立刻现原形。这个习惯帮我在开发阶段省下了大量时间，也推荐给所有做类似工具的人。快照文件看起来笨重，却是你唯一能真实看到模型视角的窗口。没有任何日志和分析比“亲眼看到发给模型的内容”更直接。

6. 这个模块还能往哪些方向扩展

context-mode 目前在我的工作流里已经稳定跑了一段时间，但我清楚它离“完善”还很远。以现在的实现为基础，有若干方向是我明确觉得值得继续投入的。

首先是场景感知和自我调整。现在的任务切换检测还很粗糙，靠的是关键词重叠度和时间间隔，真正理想的方式是接入更丰富的开发行为信号，比如光标停留位置、最近打开的文件序列、git 分支切换记录等。这些信号能大幅提高上下文相关性判断的准确性。其次是多会话协同，多个 IDE 窗口同时操作同一个项目时，如何在会话之间共享上下文缓存，是一个很有挑战性的问题，成本主要在一致性和并发控制上。

另外，context-mode 的架构完全适用于构建更复杂的 Agent 工作流。当一个 Agent 在执行多步骤任务时，每一步都需要不同的上下文视角，而手动设计这些视角容易遗漏。如果把 context-mode 的分级机制扩展成“上下文策略模板”，针对测试生成、代码评审、Bug 定位等不同场景预设不同的上下文组织规则，Agent 的稳定性会有明显提升。

我在实际使用中最深的体会是：模型的上下文能力决定了它的上限，而管理上下文的能力决定了你能不能触达这个上限。窗口再大，如果管理机制跟不上，实际可用容量可能只有标称值的一半。context-mode 最终做的，就是把那些容易在忙碌开发中被省略的“整理上下文的动作”自动化，让模型每一次都能站在最佳视角上看你的代码。以后再有人问我要不要用 AI 编程助手，我的回答永远是：工具本身不是关键，关键是你能不能知道它每时每刻在“看”什么。看清楚这一点，你手里的模型就会从聪明变成一个真正好用的队友。