1. 为什么上下文管理成了 AI 编码代理的生死线过去一年我一直在折腾各种 AI 编码代理从最早的补全插件到后来的自主 Agent踩过的坑能写一本书。但真正让我意识到问题严重性的是去年接手一个中型项目重构的时候——代码库大概有 12 万行涉及 8 个微服务模块。我兴冲冲地把整个仓库丢给一个当时口碑不错的编码代理结果它给出的修改建议里有一半引用了根本不存在的函数名还有几个文件路径完全是幻觉产物。问题出在哪不是模型不够聪明而是上下文管理彻底崩了。你可以把 AI 编码代理想象成一个刚入职的实习生能力很强但记性有限。如果你一次性把公司所有文档、所有代码、所有会议记录全塞给他他反而什么都记不住还会把不同项目的信息混在一起。Context Mode 要解决的就是这个核心矛盾如何在有限的上下文窗口里让代理始终拿到当前任务最需要的那部分信息。这个标题里的重构上下文管理范式说的不是小修小补而是从底层重新思考代理应该记住什么、忘记什么、什么时候去查、查完怎么用。结合热词里频繁出现的 MCP、SQLite 这些关键词我基本可以判断这套方案的核心思路是用结构化的外部存储替代无脑的上下文堆砌让代理像人类工程师一样需要什么就去查什么而不是把所有东西都背在脑子里。这篇文章我会从设计思路、核心机制、实操落地、问题排查四个维度把这套范式拆开讲透。适合正在自建编码代理的开发者、被上下文窗口折磨过的技术负责人以及想理解 MCP 生态到底怎么落地的人。读完你应该能自己搭一套可用的上下文管理系统而不是停留在概念层面。2. 上下文管理的核心矛盾与设计取舍2.1 传统方案的三个致命伤在讲 Context Mode 之前得先说清楚老办法为什么不行。我总结下来传统上下文管理有三个绕不过去的坑。第一个坑是全量注入。很多代理的做法简单粗暴把相关文件全部读进来拼成一个巨大的 prompt。代码库小的时候没问题一旦超过几万行token 消耗直接爆炸。我实测过一个 5 万行的 Python 项目全量注入单次请求就要 18 万 token成本高不说模型对中间部分的注意力还会明显衰减——这就是所谓的lost in the middle现象开头和结尾记得清楚中间的内容基本被忽略。第二个坑是检索粒度太粗。有些方案用向量检索把代码切成块存进向量库需要时按相似度召回。听起来很美但代码不是自然语言一个函数的语义往往依赖它所在的类、导入的模块、调用的其他函数。你按 512 token 切块召回来的片段经常缺胳膊少腿代理拿到半截代码根本没法用。第三个坑是状态丢失。代理执行多步任务时前面步骤的结论、中间产生的临时变量、已经排除的错误方向这些信息如果没有持久化下一步就得重新推导。我见过最离谱的情况是代理在同一个任务里反复读同一个文件七八次每次都从头解析效率低得令人发指。2.2 Context Mode 的核心思路把记忆外包出去Context Mode 的破局点很清晰不要试图让模型记住一切而是给它一套高效的外部记忆系统。这个思路借鉴了人类工程师的工作方式。你写代码的时候不会把整个项目背在脑子里而是靠 IDE 的跳转、grep 搜索、文档查阅来按需获取信息。Context Mode 就是把这种按需获取机制工程化用 MCP 作为代理和外部工具之间的标准接口用 SQLite 作为轻量级的结构化存储。为什么选 SQLite 而不是别的我分析下来有几个现实考量。第一它是单文件数据库零配置代理启动时不需要额外起服务这对本地开发场景太友好了。第二SQL 查询能力足够强代理可以用自然语言转成 SQL 来精确检索代码符号、调用关系、修改历史。第三它足够轻十万条记录的查询在毫秒级完成完全不会成为性能瓶颈。热词里有人问sqlite 查询十万条数据需要多久我可以负责任地说建好索引的情况下单表十万行的条件查询通常在 5 到 20 毫秒之间比网络请求快几个数量级。MCP 在这里扮演的角色是协议层。它定义了代理怎么调用外部工具、怎么传递参数、怎么接收结果。有了 MCP上下文管理系统就不用为每个代理框架单独适配任何支持 MCP 的客户端都能接进来。这也是为什么热词里 MCP 相关的内容这么多——它正在成为 AI 工具集成的事实标准。2.3 方案选型的关键权衡设计这套系统时有几个权衡点必须想清楚我把自己当时的决策过程分享一下。存储选型上SQLite vs 向量库。我最终选了 SQLite 为主、向量检索为辅的混合方案。纯向量库的问题前面说了粒度难控纯 SQLite 又缺乏语义模糊匹配能力。实际做法是代码符号、文件结构、调用关系这些结构化信息进 SQLite用精确查询注释、文档、自然语言描述这些进向量库用相似度召回。两者通过文件路径和符号 ID 关联。更新策略上全量重建 vs 增量更新。全量重建简单可靠但大项目一次要几分钟。增量更新快但容易因为文件监听遗漏导致索引和实际代码不一致。我的选择是首次全量建索引之后用文件系统监听做增量同时每天定时做一次全量校验。这个组合在实测中把索引不一致的概率压到了很低。上下文组装上固定预算 vs 动态预算。固定预算就是每次给代理塞固定大小的上下文简单但浪费。动态预算根据任务复杂度调整复杂任务多给简单任务少给。我倾向动态方案具体做法是先用一个轻量模型判断任务类型再决定召回多少内容。3. 核心机制拆解MCP 与 SQLite 如何协同3.1 MCP 工具层的设计要点MCP 本质上是一套让 AI 代理调用外部能力的标准协议。在 Context Mode 里我把它设计成几个核心工具每个工具职责单一参数明确。第一个工具是search_symbol输入符号名或模糊描述返回匹配的函数、类、变量的定义位置和签名。这个工具背后是一条 SQL 查询走的是符号表的索引。为什么要单独做这个工具而不是让代理直接写 SQL因为代理写 SQL 容易出错而且不同数据库方言不一样封装成工具后代理只需要传自然语言参数稳定性和可移植性都更好。第二个工具是get_context输入文件路径和行号范围返回该区域的代码以及相关的导入、调用者、被调用者信息。这个工具解决的就是前面说的检索粒度问题——不是简单返回一段代码而是把这段代码的依赖关系一起带出来。第三个工具是record_finding让代理把当前步骤的结论写回数据库。比如代理发现函数 A 在模块 B 中被调用了 3 次这条信息就存下来后续步骤可以直接查不用重新分析。第四个工具是query_history查询某个文件或符号的修改历史。这个在排查回归问题时特别有用代理可以知道这段代码上周被改过从而优先怀疑最近的改动。提示工具设计的第一原则是代理不需要知道底层实现。如果代理需要理解 SQL 表结构才能用你的工具那这个工具就是失败的。3.2 SQLite 表结构设计表结构直接决定了查询效率和信息完整性。我踩过几次坑之后最终定下来的核心表有这么几张。symbols表存所有代码符号字段包括 id、name、kind函数/类/变量、file_path、start_line、end_line、signature、parent_id。parent_id 用来表达嵌套关系比如类里面的方法。这张表在 name 和 file_path 上建索引模糊查询走 name 的前缀索引。relations表存符号之间的关系字段有 from_id、to_id、relation_typecalls/imports/inherits。这张表是调用关系分析的核心代理问谁调用了这个函数时一条 SQL 就能答出来。files表存文件元信息包括路径、语言、最后修改时间、内容哈希。内容哈希用来判断文件是否变化避免重复解析。findings表存代理的中间结论字段有 task_id、content、created_at、confidence。这个表让代理的推理过程可追溯也方便多轮任务之间共享状态。embeddings表存向量字段有 symbol_id、vector、model_name。向量用 BLOB 存储查询时先按 symbol_id 关联回 symbols 表拿到元信息。建索引的时候有个细节要注意relations表的 from_id 和 to_id 都要单独建索引因为查询方向可能是双向的。我一开始只建了 from_id 的索引结果反向查询慢得离谱加上 to_id 索引后性能提升了十几倍。3.3 上下文组装算法有了存储和工具接下来最关键的是怎么把召回的信息组装成给模型的上下文。这一步做不好前面所有工作都白费。我的组装算法分四步。第一步是任务解析用一个轻量模型把用户请求拆成目标符号和操作类型。比如给 UserService 的 login 方法加个日志会解析出目标符号是UserService.login操作类型是修改。第二步是种子召回根据目标符号从 symbols 表拿到定义从 relations 表拿到直接调用者和被调用者从 files 表拿到所在文件。这一步拿到的是核心上下文。第三步是扩展召回根据核心上下文里的符号再往外扩一层。比如 login 方法调用了validatePassword那就把validatePassword的定义也拉进来。扩展层数可以配置一般两层足够再多就会引入噪音。第四步是预算裁剪把所有召回内容按重要性排序从高到低填充到 token 预算里。重要性排序的规则是目标符号 直接调用关系 同文件符号 扩展关系。超出预算的部分直接丢弃并在上下文里注明还有 N 个相关符号未展示。这个算法实测下来在 5 万行项目上单次任务的上下文大小能控制在 8000 token 以内比全量注入省了 95% 以上而代理的准确率反而更高因为它拿到的都是真正相关的信息。4. 从零搭建完整实操流程4.1 环境准备与依赖安装先把基础环境搭起来。我用的技术栈是 Python 3.11 SQLite 3.40 一个 MCP 服务框架。SQLite 在 Linux 下的安装很简单Ubuntu 系直接sudo apt install sqlite3 libsqlite3-devCentOS 系用sudo yum install sqlite sqlite-devel。装完用sqlite3 --version确认版本建议 3.35 以上因为要用到一些新的 JSON 函数。Python 侧需要装几个库mcp用于实现 MCP 服务tree-sitter用于代码解析sqlite-utils简化数据库操作watchdog做文件监听。用 pip 一把装完pip install mcp tree-sitter tree-sitter-languages sqlite-utils watchdogtree-sitter 是这套方案的关键依赖它能把代码解析成语法树我们才能准确提取符号和关系。它支持的语言很多Python、JavaScript、Go、Rust 都有现成的语法定义。如果你的项目语言比较小众可能需要自己写语法定义这个成本要提前评估。数据库文件我建议放在项目根目录的.context/下命名为index.db。这个目录加到.gitignore里避免索引文件被提交。初始化的时候用 sqlite-utils 建表import sqlite_utils db sqlite_utils.Database(.context/index.db) db[symbols].create({ id: int, name: str, kind: str, file_path: str, start_line: int, end_line: int, signature: str, parent_id: int }, pkid) db[symbols].create_index([name]) db[symbols].create_index([file_path])其他表类似建法注意索引一定要在建表后立刻加上等数据灌进去再加索引会慢很多。4.2 代码解析与索引构建索引构建是整个系统里最耗时的环节也是最容易出问题的环节。我的做法是分两阶段先扫描文件系统收集文件列表再逐个解析。文件扫描阶段要注意排除目录。node_modules、.git、venv、__pycache__这些必须跳过否则索引会爆炸。我用一个白名单加黑名单的组合白名单是.py、.js、.ts、.go、.rs这些源码后缀黑名单是上面那些目录名。解析阶段用 tree-sitter 遍历语法树遇到函数定义、类定义、变量声明就提取出来存进 symbols 表。提取的时候要记录 start_line 和 end_line这个后面做上下文召回时要用。关系提取稍微复杂一点需要在语法树里找调用表达式、导入语句、继承声明然后解析出符号名再通过符号表反查 ID。这里有个坑要提醒跨文件的关系解析需要两遍扫描。第一遍只建符号表第二遍才解析关系因为解析关系时需要查其他文件的符号 ID如果符号表还没建完就查不到。我第一版没注意这个导致跨文件调用关系全丢了排查了半天才发现是顺序问题。索引构建的代码大概长这样from tree_sitter import Language, Parser import tree_sitter_languages parser Parser() parser.set_language(tree_sitter_languages.get_language(python)) def index_file(path): with open(path, rb) as f: tree parser.parse(f.read()) # 遍历 tree.root_node提取符号和关系 # 具体遍历逻辑根据语言语法调整 ...十万行代码的项目全量索引大概需要 30 到 60 秒取决于机器性能。这个时间可以接受因为只在首次构建和每日校验时执行。4.3 MCP 服务实现与接入MCP 服务的实现要遵循协议规范核心是定义工具列表和处理函数。我用官方 Python SDK 来写结构很清晰from mcp.server import Server from mcp.types import Tool, TextContent app Server(context-mode) app.list_tools() async def list_tools(): return [ Tool(namesearch_symbol, description按名称搜索代码符号, inputSchema{type: object, properties: {query: {type: string}}, required: [query]}), Tool(nameget_context, description获取指定位置的上下文, inputSchema{type: object, properties: {file_path: {type: string}, line: {type: integer}}, required: [file_path, line]}), # 其他工具... ] app.call_tool() async def call_tool(name, arguments): if name search_symbol: results search_symbols(arguments[query]) return [TextContent(typetext, textformat_results(results))] # 其他工具分发...接入客户端的时候不同工具配置方式不一样。以常见的桌面客户端为例需要在配置文件里加上 MCP 服务器地址和启动命令。配置项一般包括 command、args、env 三部分。command 是启动命令args 是参数env 是环境变量。我建议把数据库路径通过 env 传进去这样不同项目可以用不同的索引文件。注意MCP 服务启动后要确认客户端能正确握手。如果工具列表拉不出来先检查服务是否正常监听再看协议版本是否匹配。我遇到过客户端和服务端协议版本差一个小版本导致握手失败的情况升级到同版本就好了。4.4 增量更新与一致性保障索引建好之后代码还在不断变化必须有一套增量更新机制。我用 watchdog 监听文件变化文件保存后触发重新解析更新对应的符号和关系记录。增量更新的难点在于删除和重命名的处理。文件删了对应的符号和关系要清理符号改名了引用它的地方要更新。我的做法是文件变化时先按 file_path 删掉该文件的所有符号和关系再重新解析插入。这样虽然有点暴力但保证了正确性而且单文件重解析很快几百毫秒的事。一致性校验我放在每天凌晨跑一次全量重新解析和数据库里的记录对比发现不一致就修正。这个校验能兜住文件监听遗漏的情况比如某些编辑器保存时触发的文件系统事件不规范。5. 常见问题与排查技巧实录5.1 索引相关的高频问题问题一索引构建卡住不动。最常见的原因是遇到了超大文件或者解析器死循环。我遇到过一次某个自动生成的代码文件有 8 万行tree-sitter 解析时内存直接爆了。解决办法是设置文件大小上限超过 1MB 的文件跳过解析只记录文件元信息。另外解析要加超时单个文件超过 10 秒就放弃。问题二符号查不到。先确认文件是否在索引范围内检查白名单后缀和黑名单目录。如果文件在范围内还查不到可能是解析器不支持该语言的某些语法特性。我遇到过 Python 的 match 语句早期版本 tree-sitter 不支持升级语法定义后解决。问题三关系错乱。同名符号在不同文件里很常见如果关系解析时只按名字匹配就会张冠李戴。解决办法是关系解析要带上作用域信息优先匹配同文件同作用域的符号跨文件匹配时用导入路径限定。5.2 上下文召回的质量问题召回质量差通常表现为代理拿到一堆无关代码或者关键代码没拿到。前者是扩展层数太多后者是种子召回不准。扩展层数我建议从 1 层开始调观察代理的表现不够再加。种子召回不准往往是任务解析出了问题比如用户说改一下登录逻辑解析器不知道登录逻辑对应哪个符号。这种情况可以在任务解析后加一步确认让代理先列出候选符号再让用户或上层逻辑选择。还有一个隐蔽的问题是上下文顺序。模型对上下文开头和结尾的内容注意力更强所以重要的内容要放在开头或结尾次要的放中间。我的做法是把目标符号放最前面直接依赖放最后面扩展内容放中间。5.3 性能与资源问题十万条记录的数据库查询慢通常是索引没建好。用EXPLAIN QUERY PLAN看执行计划如果出现SCAN TABLE就是全表扫描需要加索引。我整理了一个常见查询和对应索引的对照表查询场景涉及表需要的索引按名称搜符号symbolsname查文件内符号symbolsfile_path查调用者relationsto_id查被调用者relationsfrom_id查任务结论findingstask_id内存占用方面主要消耗在解析阶段。如果项目特别大可以分批解析每批处理完释放解析器。数据库本身很省内存SQLite 默认的缓存配置对十万级数据完全够用。5.4 与代理框架的集成问题不同代理框架对 MCP 的支持程度不一样。有的框架工具调用很顺畅有的框架在工具返回大段文本时会截断。遇到截断问题可以在工具层做分页返回时带上has_more标记让代理决定是否继续拉取。还有一个常见问题是工具调用频率过高。代理可能反复调用同一个工具查同样的信息。解决办法是在工具层加缓存相同参数的调用在短时间内直接返回缓存结果。缓存有效期设短一点比如 30 秒避免拿到过期数据。6. 我在实际项目中的几点体会这套 Context Mode 我在三个项目里落地过最大的一个代码库接近 20 万行。跑下来最深的体会是上下文管理的收益不是线性的而是有阈值的。代码库小于 1 万行的时候全量注入和 Context Mode 的差距不明显甚至全量注入因为实现简单反而更省事。但一旦超过 3 万行Context Mode 的优势就指数级放大代理的准确率和响应速度都会有质的提升。另一个体会是索引质量决定一切。我见过太多人把精力花在上下文组装算法上却忽略了索引本身的准确性。索引里符号位置错了、关系漏了后面算法再精妙也是空中楼阁。所以我的建议是索引构建和校验的代码要写得比组装算法更仔细测试覆盖要更全。最后分享一个实用技巧给代理的上下文里加一条元信息告诉它当前上下文的来源和覆盖范围。比如以下内容来自 UserService.py 第 45-120 行包含 login 方法及其直接依赖。这条元信息能显著减少代理的幻觉因为它知道自己看到的是什么、没看到的是什么。这个技巧成本极低但效果立竿见影我在所有项目里都加上了。