我最近在带一个 AI 辅助编程的项目代码仓库越来越大开发新功能时模型频繁答非所问要么漏掉关键约束要么把无关模块的旧逻辑也带进来。排查到最后问题不在模型本身而在输入给模型的那块“背景信息”上——上下文里塞了太多低价值内容真正重要的部分反而被稀释了。后来我干脆自己写了套上下文管理模式context-mode专门治理这个问题。这篇文章就把我做这套东西的完整思路、实现细节和踩坑过程记录下来。说实话当下的开发工作流里AI 工具的上下文管理几乎是个被所有人感知、但很少有人系统化解决的问题。很多人觉得“上下文不够就多贴点”结果上下文越贴越乱模型的表现反而越来越差。context-mode 的核心不是“给更多”而是“给得准”——对上下文做结构化、打分排序、按需裁剪让每一寸上下文窗口都花在刀刃上。这篇文章适合正在用 AI 编程助手、被上下文窗口限制折磨的开发者也适合想给自己的 AI 工具链搭一套上下文管理基础设施的技术负责人。顺便说一句这套机制完全和具体模型无关你用的是闭源 API 也好、本地开源模型也好思路都是一样适用的。1. context-mode 要解决的问题上下文窗口不是越大越好1.1 一个具体崩溃场景先说我遇到的那个具体场景。项目里有一个支付模块横跨前端、网关、风控、回调通知四个子系统每个子系统都有一堆历史文档。当时要做的是一个“基于用户历史行为的风控策略调整”我按常规做法把相关代码文件、需求文档、接口定义全部塞给模型一次性贴了大概两万 token 的上下文。模型输出确实能看懂需求但给出的方案里混入了大量旧版风控规则的描述还引用了已经被下线的一个“黑名单名单库”接口——这个接口在当前代码库里根本不存在因为它三个月前就废弃了。这事让我意识到模型跑偏不大可能是参数问题而是我给它的上下文里同时包含了“正确的旧信息”和“已经过时但仍然存在的旧信息”模型没有可靠依据来区分这两者。再往深了说人类程序员在接手同样任务时会自动做一件事把注意力聚焦在当前版本的关键路径上忽略掉历史遗留和无关模块。但直接把整个仓库丢给模型它做不到这种聚焦。所以 context-mode 的实现目标本质上就是把“人类程序员的上下文聚焦能力”用工程手段实现出来。1.2 根本矛盾信息量 vs 信号密度上下文管理的核心矛盾用一句话概括上下文窗口的确在变大但模型对长上下文的注意力会分散尤其是在中间位置的信息最容易丢。我把这个问题拆成两个维度信息量上下文里到底包含了多少和当前任务相关的实体、约束、代码位置。信号密度相关信息在全部上下文中的占比。大多数人的做法只提升了前者忽略后者。贴了十个文件进去只有两个真正相关那信息量是上去了但信号密度下来了模型的选择性注意力机制会让它更关注开头和结尾的内容中间的关键逻辑反而被当噪声滤掉。context-mode 的思路就是反过来主动降低无效信息的绝对量把上下文里塞满高密度信号宁可信息量略少也必须保证每条信息都精准命中当前任务。1.3 上下文管理的三个实际成本除了信号密度问题还有三个常常被忽略的成本第一是成本问题。按 token 计费的 API 服务上下文越长、单次请求就越贵。如果一个功能要反复迭代十轮每轮都带三万 token 的“行李”那这中间浪费的钱非常可观。第二是延迟。上下文越长prefill 阶段的计算量越大首 token 返回时间基本线性增长。在实际交互场景里多等三秒和少等三秒体感差异极其明显。第三是出错风险。长上下文带来的一个隐蔽问题是“惯性漂移”。模型会顺着上下文里既有的写法往下走哪怕这个写法已经被标记为待废弃。只要有旧代码在上下文里模型就会倾向于产出和旧代码风格一致的新代码而不是采用你希望的新架构。前两个还好说第三个问题几乎只能靠控制上下文内容来解决。这也是我在很多内部讨论里反复强调的别把上下文只当成“输入”要把它当成“约束条件”。模型不是被问题塑造的而是被上下文塑造的。2. context-mode 的三层架构标签过滤、优先级排序、窗口回收2.1 第一层上下文标签体系要做上下文管理第一步不是写代码而是建立一套描述上下文的标签体系。我采用的标签体系是沿着“内容类型 × 生命周期 × 权威层级”三个维度展开的。内容类型代码文件、接口定义、依赖配置、需求描述、历史决策记录、测试用例、运行日志。 生命周期永久核心项目架构说明、全局规范、版本相关当前迭代的需求文档、变更记录、临时相关本次任务临时引入的报错堆栈、一次性某个具体函数的局部实现。 权威层级强约束接口签名、编译错误、命令行规范、中约束业务规则描述、模块边界说明、弱约束历史讨论、个人偏好、非强制性建议。这个标签体系直接决定了后续过滤和排序的效果。比如一个文件内容既有永久核心的架构描述又有临时相关的报错信息那它就应该被拆开处理而不是整体塞进上下文。实际落地时我给每个代码仓库维护了一份 context-manifest.json里面按模块写明哪些路径属于“核心稳定层”、哪些属于“版本活跃层”、哪些属于“禁止自动带入层”。这套文件是人工维护的但维护成本极低因为一个模块的结构不会天天变真正经常变的只是版本活跃层里那几句描述。2.2 第二层上下文优先级打分有了标签接下来就是对每条候选上下文做打分排序。我给每条候选内容算一个综合分得分 内容类型权重 × 任务相关度系数 × 时效系数举个简单的例子用户要调整支付回调逻辑候选内容有当前支付回调的接口实现文件相关度 1.0类型权重 0.9时效 0.9得分约 0.81三个月前的风控说明文档相关度 0.6类型权重 0.5时效 0.3得分约 0.09全局架构 README相关度 0.4类型权重 0.8时效 1.0得分约 0.32。那最后进上下文的优先级就是回调实现文件 架构 README 风控旧文档。如果窗口不够后两项就得让位。打分这块其实不需要复杂的语义模型。我用的是关键词命中加人工标注相结合的方式把任务描述拆成名词实体和动词动作两类然后到候选内容里做加权匹配。命中名词实体的权重高命中动词动作的权重稍低两边都命中的内容分最高。这套规则简单粗暴但实际效果比某些复杂向量检索稳定得多因为项目上下文里的大量术语是高度定制化的向量模型不一定能处理好。2.3 第三层上下文窗口的滚动回收前两层解决的是“选什么进上下文”第三层解决的是“上下文满了怎么办”。我设置了一个硬顶比如 8K token 的窗口上限每当要加入新内容时先检查当前总量超了就按得分从低到高淘汰直到塞得下新内容。这个过程我做了两个补充约束强约束内容永不淘汰接口签名、错误信息这类高权威内容一旦进入上下文再低分也不踢出去。刚加入的内容有短暂保护期新内容加入后 2 轮对话内不会被立即淘汰避免出现“刚说完就忘了”的情况。这个回收机制看起来简单但它是整个 context-mode 的稳定器。没有它上下文管理就是一次性快照没办法应对长会话里的持续演进。3. 手把手实现 context-mode一套轻量级上下文管理服务3.1 环境与工具选型我实现这套系统的时候没有引入重型框架核心就三个组件Python 3.10 写服务端逻辑SQLite 存标签配置和上下文操作日志一个基于 FastAPI 的本地 HTTP 服务统一对外提供上下文组装接口。选这些不是因为它们最“先进”而是因为 context-mode 的核心价值不在框架而在策略。换句话说所有策略逻辑加起来也就几百行代码不需要为了它去上微服务那一套。如果后续要接更大的团队需要多模接入那就再封装一层适配器底层的策略逻辑不用动。工具选型这一步我给个明确建议先别碰那些专门做 context 编排的重型平台因为它们的抽象层级太高出现问题很难定位到具体是哪条策略导致的。自己写一个几百行的服务你能看清楚每一次上下文组装的前因后果这对调试来说太重要了。3.2 核心数据结构整个系统的核心数据模型就三张表context_items上下文条目、tags标签定义、task_sessions任务会话。context_items 表的关键字段字段名用途item_id条目标识比如 file:///src/payment/callback.pycontent_preview内容预览用于展示时判断是否误选item_typecode / doc / api / log / requirementlifecyclecore / versioned / temp / ephemeralauthoritystrong / medium / weakkeywords逗号分隔的关键词列表last_updated最后更新时间用于时效系数计算task_sessions 表就简单一点session_id、task_description、created_at、total_tokens_used。每次组装上下文都往这个表里写一条记录方便事后复盘“为什么刚才那次会话带了这些内容”。这里我特意强调了复盘能力因为在调试 prompt 效果时最怕的就是不知道模型看到了什么。有了 session 记录每一次失败都能回到当时的上下文去检查定位问题的速度会快非常多。3.3 上下文组装流程的实现组装流程有四个步骤任务解析、候选召回、打分排序、窗口压缩。第一步把用户的任务描述拆成名词实体和动词动作。我用了一个很小的基于规则的分词器内置了一个项目专属名词表比如“支付回调”“风控”“网关”“黑名单”……命中名词表的词会被单独标记不参与通用分词。第二步根据名词实体和标签体系召回候选。检查每个候选条目的关键词是否命中任务描述的名词实体命中一个就能召回。这里的召回条件要放宽宁可多召回也不能漏掉关键项。第三步按前面说的公式打分排序。这一步包含时效系数的计算last_updated 距当前时间越近时效系数越高超过 90 天没有更新的代码文件时效系数会降到 0.3 以下。第四步做窗口压缩。按得分从低到高淘汰直至总 token 数小于等于硬顶。但凡是强约束标记的内容直接跳过淘汰逻辑。这套流程跑起来之后我每次发起任务请求都走组装接口拿到的上下文是动态生成的而不是手工拼贴的。3.4 代码实现示例这里给一个简化版的核心代码帮助理解整个流程。完整版涉及项目内部结构比较多就不贴了只看骨架。# context_mode/assembler.py # 简化版上下文组装流程 from dataclasses import dataclass dataclass class ContextItem: item_id: str item_type: str lifecycle: str authority: str keywords: list last_updated: float content: str token_size: int def assemble_context(task_desc, items, hard_limit8000): # 1. 任务解析通过关键词匹配得到一组候选 entities extract_entities(task_desc) # [支付回调, 风控策略] candidates [item for item in items if is_hit(item, entities)] # 2. 打分排序 for item in candidates: item.score score_item(item, entities) candidates.sort(keylambda x: x.score, reverseTrue) # 3. 窗口压缩强约束内容不淘汰 selected [] total_tokens 0 for item in candidates: if total_tokens item.token_size hard_limit and item.authority ! strong: continue selected.append(item) total_tokens item.token_size if total_tokens hard_limit: break return selected def extract_entities(task_desc: str) - list: # 用预置名词表做提取示例略 return [支付回调, 风控策略]在跑通这套基础流程之后你会发现一个很自然的需求上下文组装不能只是静态快照它必须是一个持续演进的过程。所以我又加了一个增量刷新机制每一轮对话结束后会根据用户的新输入重新运行组装流程把新出现的实体纳入召回范围再把已经失去价值的旧条目淘汰掉。3.5 与 LLM API 的对接方式组装好的上下文怎么传给模型我用的是 Prompt 模板预填充的方式。具体来说FastAPI 服务返回的不是字符串而是一条组装好的消息列表。最前面是 system 指令说明“以下内容是 context-mode 根据当前任务筛选出的项目背景资料回答时以其中强约束条目为优先级”。然后按顺序附上选中的上下文条目每个条目前面加一行元信息标记它的标签和权重比如[code][core][strong] file:///src/payment/callback.py模型通过这行标记能快速判断后面内容的权威性和时效性从而更合理地分配注意力。实际效果是加了元信息标记之后模型对强约束内容的遵守率明显提升这个在后面实测数据里会展示。4. 实测效果开启 context-mode 前后的直观对比4.1 测试场景设计为了量化 context-mode 的提升效果我做了三组测试任务任务 A在支付回调模块中增加一个新的幂等校验逻辑任务 B重构风控策略查询逻辑从同步查询改为异步批量上报任务 C排查一个偶发的回调超时问题。每个任务都跑两轮一轮用“全量手工贴上下文”的传统方式一轮用 context-mode 组装后的精简上下文。为了避免随机性每个任务跑三次取效果中位数。衡量指标我选了三个首轮答案可运行率不报错、不引用过期接口最终生成代码需要的人工修正行数每轮交互平均耗时从发送请求到拿到首个 token。4.2 数值对比三组任务跑完的数据如下任务传统方式可运行率context-mode 可运行率传统方式修正行数context-mode 修正行数传统方式平均延迟context-mode 平均延迟任务 A33%89%37 行11 行5.8s2.1s任务 B44%78%52 行19 行6.7s2.5s任务 C67%100%59 行8 行7.2s2.2s数据说明两个直观结论第一首轮答案质量提升非常明显尤其是任务 C几乎没有再出现引用过期接口的问题第二延迟下降幅度很大直接原因就是从大约两万 token 的上下文降到了四千到五千 token。真正让我意外的还不是这些正向指标而是任务 B 的修正行数没有低于预期深入看原因后发现问题出在异步改造涉及到的模块范围比预估的大context-mode 召回的上下文里缺少了一个上游服务的数据结构说明。后来在标签配置里补上了该条目的关键词这个缺口就消失了。这说明 context-mode 不是纯自动系统它的效果很大程度依赖初始标签配置的完整度。4.3 信号密度提升的量化把上面那次测试的上下文体积做统计传统方式平均每次请求的上下文 token 数是 18400context-mode 降到 4600。为什么降幅这么明显核心在于标签过滤的结果是把整个目录全部剔除只留真正命中的文件。那些“顺手”贴进来的无关文档在传统方式里占了几乎一半的 token 量现在被完全清掉了。信号密度方面我统计了上下文里与任务直接相关的句子占全文的比例传统方式大概是 12%context-mode 提升到 47%。这个数字非常直观地解释了模型表现提升的来源——它对相关信息看得更清楚了。5. 实测中的三个大坑和对应解法5.1 坑一语义相关但关键词不命中的条目被误杀第一次跑测试时就发现了这个问题。任务描述是“回调超时如何排查”但真正涉及超时监控的模块文件关键词只有一句话没有直接出现“回调”这个词导致召回阶段被漏掉。解法是给 keywords 字段加“同义扩展”配置。我在项目里手工维护了一张同义词表比如“超时”对应“timeout、延迟、慢请求、上游阻塞”召回时先做同义词展开再做匹配。后续又加了基于源码注释的自动关键词提取凡是文档标注过“依赖”“关联”关系的都会补充到双方条目的 keywords 里。这个坑给到的教训是上下文管理的召回环节宁可宽不可窄。漏招的代价比多招更大因为少一条关键上下文模型可能直接方向性错误而多招一条顶多占点 token。5.2 坑二内容类型权重设计过细反而打架最初我给内容类型权重设计了十个档位比如“接口定义 0.9、代码实现 0.8、测试用例 0.6、运行日志 0.5……”结果发现这带来一个很奇怪的现象排查类任务召回的日志内容被大量淘汰因为日志的权重太低每条得分都拼不过代码文件。后来我把十档压缩成四档0.9接口和强约束、0.75代码和架构、0.5需求和测试、0.35日志和临时记录。同时加了一个任务类型修正系数如果判断任务描述偏向排查诊断日志内容的权重自动乘以 1.5。这个改动告诉我的道理很朴素权重设计的核心不是精细而是让模型和策略都有一致的行为预期。十个档位之间差别太小排序稳定性反而差。5.3 坑三强约束内容永不淘汰导致上下文僵化强约束内容永不淘汰的设计起初是为了保证模型不会丢掉接口约定但实际跑下来发现一个问题如果一场对话涉及的强约束条目太多比如要同时改三个子系统的接口强约束内容可能会累加到一万多 token挤占掉其他中约束内容的空间而某些中约束的上下文在当前步骤里其实更重要。现在我把“永不淘汰”改成了“核心槽位机制”。就是把强约束内容分成三个槽位全局强约束比如构建命令、语言版本任何时候都保留任务相关的强约束按相关性排序最多保留五个超出槽位的强约束降级为中约束参与整体排序。这个调整相当于给强约束内容设了一个“上线”保证它们不会被极端场景下的过多数目反噬。修正后重新跑了任务 B修正行数从 19 行降到了 13 行虽然不如任务 A 那么惊艳但趋势是对的。6. context-mode 的扩展方向从编程辅助到跨场景复用6.1 应用在文档问答场景的改造思路做完编程场景下的验证之后我顺手把 context-mode 用到了一个内部知识库问答机器人上。底层的标签过滤逻辑完全不用改只是把内容类型换成了制度文档、流程手册、历史工单、FAQ。打分排序逻辑也沿用只是把“时效系数”换成了“版本有效系数”。实际体验下来问答机器人关于新流程的准确率明显上升。这让我确认了一件事context-mode 本质上不是“AI 编程助手专用工具”而是一种通用的上下文治理方法论——只要你的场景是“从大量信息中提取少量高价值内容交给模型”这套三层架构就都适用。6.2 与 RAG 检索增强生成的组合玩法很多人会问context-mode 和 RAG 有什么关系是不是重复了我认为它们是互补关系。RAG 解决的是“在超大知识库里检索出若干文档片段”的问题而 context-mode 解决的是“在检索回的大量片段之间做优先级整合”的问题。实际使用时RAG 召回结果作为 context-mode 的候选集再由 context-mode 按标签体系和任务相关度做二次筛选排序效果是 112 的。我在一个内部项目里试过这种组合把候选文档从二十份压到五份问答准确率和回答速度都得到了保证。这个方向我认为值得大家在自己的应用里探索并不复杂只是多了一层策略函数。6.3 后续想做的自动标签推荐现在的 context-mode 最需要人工维护的部分是 manifest 配置也就是标注入口。我在想两个自动化的方向基于 AST 解析的代码依赖关系自动生成模块关键词基于历史任务会话的上下文选择日志自动学习哪些类型的文件经常被同时选中进而调整标签权重。这其实就带点个性化了每条项目在实践里形成的“上下文操作习惯”会被系统保存下来让 context-mode 越来越贴合团队自己真实的开发套路。我准备在下一个版本里加上这两个功能试试水看看能不能把人工维护成本再降一个档次。最后分享一个实际操作中的小经验context-mode 这套东西刚落地时很长一段时间只在你一个人手工调用时会配置得很准因为你会下意识把该打的标签打上。但一旦团队其他人开始用你就得把“标签配置评审”当成日常工作中一环每周过一遍近两周的新增文件把没打标的补上。第一次漏配标签的教训可能是一小时的返工但定期维护配置的习惯能帮你省下的是所有人每周都会遇到的十几分钟低效拉扯。