尧图网站建设 
1. 为什么 AI 编码代理需要一个独立的上下文管理层1.1 从“对话历史”到“上下文资产”的认知转变大多数开发者第一次接触 AI 编码代理时脑子里装的还是聊天机器人的模型我发一段话它回一段话对话历史就是全部记忆。这个模型在写个函数、改个变量名的时候够用但一旦项目规模上去问题就暴露得非常彻底。我去年接手过一个中型后端项目代码量大概在八万行左右模块之间耦合不算特别严重但业务逻辑盘根错节。当时我尝试用 AI 编码代理来辅助重构结果发现一个很尴尬的现象每次新开一个会话代理都要我重新解释一遍项目结构、技术栈、命名规范、数据库表关系。更离谱的是即便我在同一个会话里连续对话聊到第三四个问题的时候它就开始“忘记”前面说过的约束条件给出的代码风格前后不一致甚至会把已经废弃的接口又拿出来用。这不是模型能力的问题而是上下文管理机制的问题。传统的对话式 AI 把“上下文”等同于“聊天记录”聊天记录一长就截断、就摘要、就丢失细节。但对于编码代理来说上下文不是聊天记录而是项目知识、任务状态、历史决策、代码约束的集合。这些东西需要被结构化地存储、按需检索、精准注入而不是一股脑塞进对话窗口里。Context Mode 这个概念之所以值得单独拿出来讲就是因为它把上下文从“对话的附属品”提升成了“独立管理的资产”。它要解决的核心问题是如何让 AI 编码代理在长周期、多任务、跨会话的场景下依然能拿到准确、完整、不过载的上下文信息。1.2 传统上下文管理的三个致命伤在深入 Context Mode 的具体实现之前先把传统方案的问题说透这样后面讲设计思路的时候你才能理解每个决策背后的动机。第一个问题是上下文窗口的硬限制。不管模型支持多少 token它总是有限的。一个真实项目的代码库、文档、历史提交记录加起来轻松超过百万 token。你不可能把所有东西都塞进去。传统做法是截断或者摘要但截断会丢关键信息摘要会丢细节精度。我见过最粗暴的做法是只保留最近 N 轮对话结果代理把半小时前确认过的架构决策忘得一干二净。第二个问题是上下文的非结构化。聊天记录是线性的、时序的但项目知识是网状的。一个数据库表结构可能同时关联到 ORM 定义、迁移脚本、API 文档、测试用例。你把这些东西按时间顺序堆在对话里代理很难建立起正确的关联。它可能记得你十分钟前说过“用户表叫 users”但忘了二十分钟前说过“所有表名用复数形式”。第三个问题是跨会话的状态丢失。今天上午你花了两小时跟代理讨论清楚了一个模块的重构方案下午重新打开编辑器一切归零。你得重新解释背景重新确认约束重新纠正它犯过的错误。这种重复劳动在长期项目里累积起来消耗的时间非常可观。Context Mode 的设计目标就是针对这三点用外部存储解决窗口限制用结构化索引解决非结构化问题用持久化机制解决跨会话状态丢失。1.3 Context Mode 的核心设计哲学我理解 Context Mode 的核心哲学可以用一句话概括上下文不是用来“装”的而是用来“查”的。传统思路是想办法把更多东西塞进模型的上下文窗口Context Mode 的思路是建立一个外部的上下文存储层模型需要什么就去查什么。这有点像 CPU 的缓存机制寄存器容量最小但最快内存容量大但慢一些硬盘容量最大但最慢。Context Mode 相当于给 AI 编码代理加了一层“上下文缓存”把最常用的信息放在快速访问层把全量信息放在持久化存储层按需调度。这个思路落地需要几个关键组件一个结构化的存储引擎通常用 SQLite 这类嵌入式数据库、一套索引和检索机制、一个与代理运行时对接的协议层MCP 在这里扮演了重要角色、以及一套上下文生命周期的管理策略什么时候写入、什么时候读取、什么时候淘汰。接下来的章节我会逐一拆解这些组件结合我在实际项目中的使用经验把每个环节的实操要点和踩过的坑都讲清楚。2. 核心架构拆解SQLite 与 MCP 如何撑起上下文管理层2.1 为什么是 SQLite 而不是别的存储方案第一次看到 Context Mode 用 SQLite 做上下文存储的时候我其实有点意外。脑子里第一反应是为什么不用向量数据库为什么不用 Redis为什么不用文件系统后来自己动手搭了一套类似的东西之后才明白 SQLite 在这个场景下的优势几乎是压倒性的。零运维成本。向量数据库和 Redis 都需要独立部署、配置、监控。对于一个本地运行的 AI 编码代理来说引入这些外部依赖会让部署复杂度直线上升。SQLite 就是一个文件复制、备份、迁移都是一条命令的事。我在 Rocky Linux 上部署的时候sqlite3直接yum install就完事不需要任何额外配置。结构化查询能力。上下文信息天然适合用关系模型来表达。一个任务有多个步骤一个步骤关联多个文件一个文件有多个版本这些关系用 SQL 的 JOIN 查起来非常自然。向量数据库擅长的是语义相似度检索但编码代理需要的往往是精确查询“把 task_id 为 42 的所有相关文件找出来”这种查询用 SQL 比用向量检索准确得多。事务保证。上下文写入必须是原子的。如果代理在更新任务状态的时候中途崩溃不能出现“任务标记为完成但相关文件没更新”这种不一致状态。SQLite 的 ACID 事务在这个场景下非常关键。单文件便携性。你可以把整个上下文数据库打包带走换一台机器继续用。这对于需要在多台设备之间切换的开发者来说非常实用。当然 SQLite 也有它的局限。并发写入性能在高频场景下会成为瓶颈全文检索能力相比专门的搜索引擎要弱一些。但在 AI 编码代理这个场景下写入频率并不高通常是任务级别的粒度检索也以结构化查询为主SQLite 的短板基本不会暴露。2.2 MCP 协议在上下文管理中的角色定位MCP 最近热度很高但很多人对它的理解还停留在“让 AI 调用外部工具”这个层面。在 Context Mode 的架构里MCP 的作用远不止于此它实际上是代理运行时与上下文存储层之间的标准接口。我画一个简单的类比如果把 Context Mode 比作一个图书馆SQLite 是书架那么 MCP 就是借书证和检索系统。代理不需要知道书具体放在哪个架子上只需要通过 MCP 提供的标准接口说“我要借关于用户认证的所有资料”MCP 层负责把请求翻译成 SQL 查询从 SQLite 里取出数据再以代理能理解的格式返回。这个设计的好处是解耦。上下文存储的具体实现可以换今天用 SQLite明天换成别的嵌入式数据库只要 MCP 接口不变代理端的代码就不用动。反过来代理端的实现也可以换今天用这个编码助手明天换另一个只要它支持 MCP 协议就能接入同一套上下文存储。在实际配置中MCP 服务通常以本地进程的形式运行通过标准输入输出或者本地 socket 与代理通信。我在 Windows 环境下用db browser for sqlite来查看和调试上下文数据库同时 MCP 服务在后台运行两者互不干扰。这种“可视化调试 程序化访问”的组合在排查问题时非常高效。2.3 上下文数据的表结构设计这部分是我踩坑最多的地方也是我觉得最有必要详细展开的。Context Mode 的数据库表结构设计直接决定了检索效率和上下文质量。一个经过实战检验的最小可用表结构大概包含以下几张表表名用途关键字段contexts存储上下文条目id, type, content, created_at, updated_attasks任务状态跟踪id, name, status, parent_id, created_atcontext_task_map上下文与任务的关联context_id, task_id, relevancefiles文件元信息id, path, hash, last_indexedcontext_file_map上下文与文件的关联context_id, file_id, relation_typecontexts表是核心每一条记录代表一个独立的上下文单元。type字段用来区分上下文的种类比如decision架构决策、constraint约束条件、snippet代码片段、reference参考资料。这个分类非常重要因为不同类型的上下文在检索时的优先级和注入策略是不一样的。tasks表用来跟踪任务的层级结构。一个大的重构任务可能拆成多个子任务子任务又可能拆成更细的步骤。用parent_id建立树形结构代理在检索上下文的时候可以沿着任务树向上追溯把父任务的相关上下文也带出来。关联表的设计是精髓。context_task_map里的relevance字段用来标记上下文与任务的相关程度检索的时候可以按相关度排序优先注入最相关的上下文。context_file_map里的relation_type用来区分文件和上下文的关系类型比如defines文件定义了上下文中的某个概念、uses文件使用了上下文中的某个概念、modifies文件修改了上下文中的某个概念。注意表结构一旦确定后期修改字段类型的成本很高。SQLite 修改字段类型需要重建表所以在初期设计时就要想清楚每个字段的类型和约束。我建议所有文本字段统一用 TEXT时间字段统一用 INTEGER 存 Unix 时间戳避免时区和格式问题。2.4 上下文写入与检索的完整流程理解了表结构之后来看一个完整的上下文流转过程。假设代理正在执行一个“重构用户认证模块”的任务。写入阶段代理在分析代码的过程中识别出一个关键决策——“JWT token 的过期时间从 24 小时调整为 2 小时”。这个决策会被封装成一条contexts记录type为decisioncontent里包含决策内容和理由。同时这个决策关联到当前任务context_task_map以及涉及到的文件context_file_map。检索阶段当代理需要修改认证相关的代码时它通过 MCP 发起一个检索请求参数包括当前任务 ID、涉及的文件路径、需要的上下文类型。MCP 层把请求翻译成 SQL从contexts表里查出所有关联的决策、约束和代码片段按相关度排序后返回。注入阶段代理拿到检索结果后根据上下文类型和当前对话窗口的剩余空间决定注入哪些内容。决策和约束类上下文优先级最高代码片段次之参考资料最低。如果窗口空间不够低优先级的上下文会被摘要后再注入。这个流程的关键在于按需检索。代理不是一次性把所有上下文都加载进来而是在需要的时候才去查。这大大降低了上下文窗口的压力也让代理能够处理远超窗口限制的项目规模。我在实际使用中发现检索请求的参数设计非常关键。如果参数太宽泛查出来的上下文太多注入后反而干扰代理的判断如果参数太窄又可能漏掉关键信息。一个实用的技巧是先用文件路径做粗筛再用任务 ID 做精筛最后用上下文类型做优先级排序。这个三层过滤策略在大多数场景下都能取得不错的效果。3. 实操落地从零搭建一套可用的上下文管理系统3.1 环境准备与依赖安装这一节我以 Linux 环境为例把从零搭建的步骤完整走一遍。Windows 和 macOS 的差异我会在关键步骤处标注。首先是 SQLite 的安装。大多数 Linux 发行版已经预装了 SQLite但版本可能比较老。我建议手动安装最新稳定版# Rocky Linux / CentOS / RHEL 系 sudo yum install sqlite sqlite-devel # Ubuntu / Debian 系 sudo apt-get install sqlite3 libsqlite3-dev # 验证安装 sqlite3 --version如果你用的是 Windows直接去 SQLite 官网下载预编译的二进制文件解压后把目录加到 PATH 里就行。macOS 用户可以用 Homebrewbrew install sqlite3。接下来是 MCP 服务端的准备。MCP 本身是一个协议规范具体的服务端实现取决于你用的技术栈。我选择用 Python 来实现因为生态成熟、调试方便# 创建虚拟环境 python3 -m venv context-mode-env source context-mode-env/bin/activate # 安装依赖 pip install mcp sqlite-utilssqlite-utils这个库强烈推荐它提供了一套非常顺手的命令行工具和 Python API用来操作 SQLite 数据库比裸写 SQL 效率高很多。比如创建一个表sqlite-utils create-table context.db contexts \ id integer \ type text \ content text \ created_at integer \ updated_at integer \ --pk id这条命令就完成了建表比手写CREATE TABLE语句省事得多。提示数据库文件建议放在项目根目录下的.context/目录里并加入.gitignore。上下文数据是本地开发环境的一部分不应该提交到代码仓库。3.2 数据库初始化与表结构创建环境准备好之后开始建库建表。我把完整的初始化脚本贴出来你可以直接复制使用import sqlite3 import time def init_db(db_path.context/context.db): conn sqlite3.connect(db_path) cursor conn.cursor() # 上下文主表 cursor.execute( CREATE TABLE IF NOT EXISTS contexts ( id INTEGER PRIMARY KEY AUTOINCREMENT, type TEXT NOT NULL, content TEXT NOT NULL, metadata TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL ) ) # 任务表 cursor.execute( CREATE TABLE IF NOT EXISTS tasks ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, status TEXT DEFAULT pending, parent_id INTEGER, created_at INTEGER NOT NULL, FOREIGN KEY (parent_id) REFERENCES tasks(id) ) ) # 上下文-任务关联表 cursor.execute( CREATE TABLE IF NOT EXISTS context_task_map ( context_id INTEGER NOT NULL, task_id INTEGER NOT NULL, relevance REAL DEFAULT 1.0, PRIMARY KEY (context_id, task_id), FOREIGN KEY (context_id) REFERENCES contexts(id), FOREIGN KEY (task_id) REFERENCES tasks(id) ) ) # 文件表 cursor.execute( CREATE TABLE IF NOT EXISTS files ( id INTEGER PRIMARY KEY AUTOINCREMENT, path TEXT UNIQUE NOT NULL, hash TEXT, last_indexed INTEGER ) ) # 上下文-文件关联表 cursor.execute( CREATE TABLE IF NOT EXISTS context_file_map ( context_id INTEGER NOT NULL, file_id INTEGER NOT NULL, relation_type TEXT DEFAULT related, PRIMARY KEY (context_id, file_id), FOREIGN KEY (context_id) REFERENCES contexts(id), FOREIGN KEY (file_id) REFERENCES files(id) ) ) # 创建索引加速查询 cursor.execute(CREATE INDEX IF NOT EXISTS idx_contexts_type ON contexts(type)) cursor.execute(CREATE INDEX IF NOT EXISTS idx_contexts_created ON contexts(created_at)) cursor.execute(CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status)) conn.commit() conn.close() print(Database initialized successfully.) if __name__ __main__: init_db()这个脚本执行完之后你会得到一个包含五张表和三个索引的数据库文件。索引的创建是有讲究的contexts.type上的索引加速按类型筛选contexts.created_at上的索引加速按时间排序tasks.status上的索引加速查找待处理任务。关于metadata字段我特意留了一个 TEXT 类型的扩展字段用来存 JSON 格式的附加信息。比如一条代码片段类型的上下文可以在metadata里存{language: python, line_start: 42, line_end: 58}。这样既保持了主表的简洁又保留了扩展能力。3.3 MCP 服务端的核心接口实现MCP 服务端需要暴露几个核心接口给代理调用。我用 Python 的mcp库来实现核心接口包括写入上下文、检索上下文、更新任务状态、关联文件。import json import sqlite3 import time from mcp.server import Server, NotificationOptions from mcp.server.models import InitializationOptions import mcp.server.stdio import mcp.types as types app Server(context-mode) DB_PATH .context/context.db def get_db(): conn sqlite3.connect(DB_PATH) conn.row_factory sqlite3.Row return conn app.list_tools() async def list_tools(): return [ types.Tool( namewrite_context, description写入一条新的上下文记录, inputSchema{ type: object, properties: { type: {type: string, description: 上下文类型decision/constraint/snippet/reference}, content: {type: string, description: 上下文内容}, task_id: {type: integer, description: 关联的任务ID}, file_paths: {type: array, items: {type: string}, description: 关联的文件路径列表} }, required: [type, content] } ), types.Tool( namequery_context, description检索上下文记录, inputSchema{ type: object, properties: { task_id: {type: integer}, file_path: {type: string}, context_type: {type: string}, limit: {type: integer, default: 20} } } ), types.Tool( nameupdate_task, description更新任务状态, inputSchema{ type: object, properties: { task_id: {type: integer}, status: {type: string} }, required: [task_id, status] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): conn get_db() cursor conn.cursor() now int(time.time()) if name write_context: cursor.execute( INSERT INTO contexts (type, content, created_at, updated_at) VALUES (?, ?, ?, ?), (arguments[type], arguments[content], now, now) ) context_id cursor.lastrowid if task_id in arguments: cursor.execute( INSERT OR REPLACE INTO context_task_map (context_id, task_id, relevance) VALUES (?, ?, 1.0), (context_id, arguments[task_id]) ) if file_paths in arguments: for path in arguments[file_paths]: cursor.execute( INSERT OR IGNORE INTO files (path, last_indexed) VALUES (?, ?), (path, now) ) cursor.execute(SELECT id FROM files WHERE path ?, (path,)) file_id cursor.fetchone()[0] cursor.execute( INSERT OR REPLACE INTO context_file_map (context_id, file_id, relation_type) VALUES (?, ?, related), (context_id, file_id) ) conn.commit() conn.close() return [types.TextContent(typetext, textjson.dumps({context_id: context_id}))] elif name query_context: query SELECT DISTINCT c.* FROM contexts c params [] conditions [] if task_id in arguments: query JOIN context_task_map ctm ON c.id ctm.context_id conditions.append(ctm.task_id ?) params.append(arguments[task_id]) if file_path in arguments: query JOIN context_file_map cfm ON c.id cfm.context_id query JOIN files f ON cfm.file_id f.id conditions.append(f.path ?) params.append(arguments[file_path]) if context_type in arguments: conditions.append(c.type ?) params.append(arguments[context_type]) if conditions: query WHERE AND .join(conditions) query ORDER BY c.updated_at DESC LIMIT ? params.append(arguments.get(limit, 20)) cursor.execute(query, params) rows [dict(row) for row in cursor.fetchall()] conn.close() return [types.TextContent(typetext, textjson.dumps(rows, ensure_asciiFalse))] elif name update_task: cursor.execute( UPDATE tasks SET status ? WHERE id ?, (arguments[status], arguments[task_id]) ) conn.commit() conn.close() return [types.TextContent(typetext, textjson.dumps({updated: True}))] conn.close() return [types.TextContent(typetext, textjson.dumps({error: unknown tool}))] async def main(): async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): await app.run( read_stream, write_stream, InitializationOptions( server_namecontext-mode, server_version0.1.0 ) ) if __name__ __main__: import asyncio asyncio.run(main())这段代码实现了三个核心工具write_context、query_context、update_task。代理通过 MCP 协议调用这些工具就能完成上下文的读写操作。query_context的实现里有一个细节值得注意我用了DISTINCT来去重。因为一个上下文可能同时关联多个任务和多个文件JOIN 之后会产生重复行。DISTINCT确保每个上下文只返回一次。这个坑我在早期版本里踩过当时没加DISTINCT检索结果里同一条上下文出现了七八次注入后严重浪费了窗口空间。3.4 与编码代理的对接配置MCP 服务端跑起来之后需要在编码代理那边配置连接。不同的代理配置方式不一样但核心都是告诉代理“有一个 MCP 服务在某个地址上你可以调用它的工具”。以常见的配置格式为例通常是在代理的配置文件里加一段{ mcpServers: { context-mode: { command: python, args: [/path/to/context_mode_server.py], env: { DB_PATH: /path/to/project/.context/context.db } } } }配置完成之后重启代理它应该能自动发现context-mode提供的三个工具。你可以在代理的对话里让它“列出当前可用的工具”来验证连接是否成功。如果代理找不到 MCP 服务排查顺序是这样的先确认 Python 路径和脚本路径是否正确再确认依赖是否安装完整最后检查代理的日志输出。我遇到过最常见的问题是 Python 虚拟环境没有激活导致mcp库找不到。解决办法是在配置里用虚拟环境里的 Python 绝对路径而不是系统 Python。注意MCP 服务是以子进程形式运行的代理启动时它会自动拉起。如果代理异常退出MCP 进程可能变成孤儿进程。建议在服务端代码里加一个心跳检测父进程消失后自动退出。4. 上下文生命周期管理与检索策略优化4.1 上下文的写入时机与粒度控制上下文管理最容易犯的错误是“什么都往里写”。我刚开始用的时候恨不得把代理说的每一句话都存进去结果数据库迅速膨胀检索出来的上下文噪音极大代理反而被干扰得更厉害。后来我总结了一个原则只写入那些“下次会话还需要知道”的信息。具体来说以下几类信息值得写入架构决策为什么选 A 不选 B这个决策的约束条件是什么。接口约定模块之间的调用协议、数据格式、错误码定义。命名规范项目特有的命名习惯比如“所有 DTO 以 Request/Response 结尾”。已知问题当前版本存在的 bug、临时绕过方案、待优化项。关键代码片段那些被多个模块引用的核心函数或类。而以下几类信息不建议写入临时的调试输出和日志。已经被推翻的中间方案。代理的寒暄和确认性回复。可以从代码本身直接推断出来的信息。粒度控制也很关键。一条上下文记录应该是一个独立的、自包含的知识单元。比如“用户认证使用 JWT过期时间 2 小时刷新令牌 7 天”就是一条好的上下文。而“今天讨论了认证方案先说了 A 方案后来觉得不行又讨论了 B 方案最后决定用 C 方案”就是一条糟糕的上下文因为它包含了太多过程信息真正有用的结论被淹没了。4.2 检索结果的排序与截断策略检索出来的上下文不能一股脑全注入需要排序和截断。我的策略是三层排序第一层按类型优先级。constraint和decision类型优先级最高因为它们直接影响代码的正确性。snippet次之reference最低。第二层按时间新鲜度。同样类型的上下文越新的越相关。用updated_at倒序排列。第三层按关联强度。通过context_task_map.relevance字段来区分。直接关联当前任务的上下文优先级高于关联父任务的。排序之后是截断。我通常会给上下文注入预留窗口空间的 30% 左右。如果排序后的上下文总长度超过这个预算就从最低优先级的开始截断。截断时不是简单丢弃而是把多条低优先级上下文合并成一条摘要。比如三条关于日志格式的reference类型上下文可以合并成“日志格式相关参考使用 JSON 格式包含 timestamp、level、module、message 四个字段”。这个合并逻辑可以用一个简单的规则引擎来实现也可以让代理自己来做。我倾向于让代理来做因为代理更理解上下文的语义合并出来的摘要质量更高。4.3 上下文过期与清理机制上下文不是越多越好过期的上下文会拖慢检索速度也会增加噪音。我设计了一套简单的过期策略上下文类型默认保留期清理条件decision永久被新决策显式覆盖constraint永久关联任务标记为完成snippet90 天关联文件已删除或大幅修改reference30 天超过保留期且未被检索清理任务可以做成一个定时脚本每天跑一次def cleanup_expired_contexts(db_path, days_threshold90): conn sqlite3.connect(db_path) cursor conn.cursor() cutoff int(time.time()) - days_threshold * 86400 # 清理过期的 reference 类型上下文 cursor.execute( DELETE FROM contexts WHERE type reference AND updated_at ? AND id NOT IN ( SELECT context_id FROM context_task_map JOIN tasks ON context_task_map.task_id tasks.id WHERE tasks.status ! completed ) , (cutoff,)) deleted cursor.rowcount conn.commit() conn.close() return deleted这个清理逻辑的关键是只清理那些没有关联到活跃任务的上下文。如果一个reference上下文还关联着未完成的任务说明它还有用不能删。4.4 多任务场景下的上下文隔离与共享实际项目中开发者往往同时推进多个任务。任务 A 的上下文不应该干扰任务 B 的代理行为但有些全局性的上下文比如项目编码规范又应该被所有任务共享。我的做法是在contexts表里加一个scope字段用来标记上下文的作用域global全局上下文所有任务可见。task任务级上下文只有关联的任务可见。session会话级上下文只在当前会话有效会话结束即失效。检索的时候查询条件里加上scope IN (global, task)并且task_id匹配当前任务。这样既保证了全局规范的一致性又实现了任务之间的隔离。session级别的上下文我通常不写入数据库而是放在内存里会话结束自动丢弃。这类上下文包括临时的调试信息、当前正在编辑的文件内容等。提示如果你的项目有多个开发者共用一套上下文数据库建议再加一个owner字段来区分上下文来源。否则 A 开发者写入的临时决策可能会干扰 B 开发者的代理行为。5. 实战中踩过的坑与排查技巧5.1 数据库锁冲突与并发写入问题SQLite 默认的并发模型是“多读单写”。当代理同时发起多个写入请求时后到的请求会收到database is locked错误。我在早期版本里没处理这个问题导致代理偶尔会丢失上下文写入。解决方案有两个层面。第一层是应用层重试import time import sqlite3 def execute_with_retry(conn, query, params, max_retries5): for attempt in range(max_retries): try: cursor conn.cursor() cursor.execute(query, params) conn.commit() return cursor except sqlite3.OperationalError as e: if database is locked in str(e) and attempt max_retries - 1: time.sleep(0.1 * (attempt 1)) continue raise return None第二层是数据库配置优化conn sqlite3.connect(db_path, timeout10) conn.execute(PRAGMA journal_modeWAL) conn.execute(PRAGMA busy_timeout5000)WAL模式Write-Ahead Logging允许一个写入者和多个读取者同时操作大大降低了锁冲突的概率。busy_timeout设置成 5000 毫秒意味着遇到锁的时候会自动等待 5 秒再报错给重试留出了空间。这两个配置加上之后我在实际使用中再也没有遇到过锁冲突导致的上下文丢失。5.2 检索结果不准确的原因分析检索结果不准确通常表现为两种要么查出来一堆不相关的上下文要么该查出来的没查出来。查出来太多不相关的内容最常见的原因是文件路径匹配太宽泛。比如你用src/作为查询条件那所有在src/下的文件关联的上下文都会被查出来。解决办法是尽量用精确的文件路径或者用文件 ID 而不是路径来关联。另一个原因是上下文类型没有正确设置。如果所有上下文都标成reference那优先级排序就失效了。写入的时候一定要根据内容性质选择正确的类型。该查出来的没查出来通常是关联关系没有建立完整。比如你写入了一条关于数据库表结构的决策但忘记关联到models.py文件。下次代理修改models.py的时候就检索不到这条决策。解决办法是在写入上下文的时候尽量把相关的文件都关联上。宁可多关联几个也不要漏掉。我后来养成了一个习惯每次写入上下文之后立刻用query_context反向查一次确认能查到。这个“写入后验证”的步骤帮我避免了很多关联遗漏的问题。5.3 上下文注入过多导致代理“分心”这是一个很微妙的问题。上下文注入太少代理缺乏信息注入太多代理反而会“分心”在无关的信息上浪费注意力。我遇到过一个典型案例代理在修改一个简单的工具函数时检索出了二十多条相关上下文包括三个月前的架构讨论、两周前的性能优化决策、昨天的代码审查意见。结果代理花了大量篇幅分析这些上下文最后给出的修改方案反而偏离了当前任务的实际需求。解决办法是动态调整检索范围。对于简单的、局部的修改任务只检索直接关联文件的constraint和snippet类型上下文限制在 5 条以内。对于复杂的、跨模块的重构任务才扩大检索范围。我在 MCP 服务端加了一个query_context的mode参数focused精确模式只查直接关联的上下文限制 5 条。normal普通模式查直接关联和一级间接关联限制 15 条。broad宽泛模式查所有关联限制 30 条。代理根据任务复杂度自己选择模式。这个简单的分级策略效果非常明显代理的输出质量有了肉眼可见的提升。5.4 常见问题速查表现象可能原因排查方法解决方案代理找不到 MCP 工具配置路径错误或依赖缺失检查代理日志中的 MCP 连接信息确认 Python 路径和依赖安装写入上下文报错数据库锁冲突查看错误信息是否含 database is locked启用 WAL 模式并加重试逻辑检索结果为空关联关系未建立直接查数据库确认记录存在写入时补全 task_id 和 file_paths检索结果过多查询条件太宽泛检查查询参数中的文件路径使用精确路径或文件 ID代理输出质量下降上下文注入过多统计注入的上下文条数和长度降低检索模式或增加截断阈值数据库文件过大过期上下文未清理查看各类型上下文的记录数运行清理脚本删除过期数据跨会话状态丢失上下文未持久化检查数据库文件是否被正确写入确认写入操作有 commit这张表里的每一行都是我实际遇到过的问题。其中“代理输出质量下降”这一条最隐蔽因为代理不会报错只是给出的结果不如预期。你需要对比注入上下文前后的输出差异才能定位到是上下文过多导致的。6. 从 Context Mode 延伸出的几个实用技巧6.1 用上下文数据库做项目知识沉淀Context Mode 的数据库不仅仅服务于 AI 代理它本身就是一个结构化的项目知识库。我现在的习惯是每次跟代理讨论出一个重要的架构决策就手动写入一条decision类型的上下文。日积月累下来这个数据库就成了项目的“决策日志”。新加入项目的开发者或者你自己几个月后回头看可以通过查询这个数据库快速了解项目的关键设计。这比翻聊天记录或者找文档高效得多因为每条上下文都是结构化的、可检索的。我甚至用db browser for sqlite给数据库做了一个简单的可视化界面按类型和任务分组展示上下文。团队内部共享这个数据库文件大家都能看到最新的决策和约束。6.2 上下文模板化与自动化写入手动写入上下文虽然灵活但效率不高。我后来做了一套模板把常见的上下文类型预定义好格式代理只需要填充关键信息就行。比如架构决策的模板决策[一句话描述] 背景[为什么需要做这个决策] 选项[考虑过哪些方案] 选择[最终选了哪个] 理由[为什么选这个] 影响[对哪些模块有影响]代理在讨论过程中识别到决策点时自动按这个模板生成上下文并写入。这样既保证了上下文的完整性又减少了手动整理的工作量。自动化写入的触发条件可以这样设计当代理的回复中包含“决定”、“选择”、“采用”、“方案”等关键词并且回复长度超过一定阈值时提示代理生成一条decision类型的上下文。这个规则虽然简单但命中率相当高。6.3 上下文质量评估与持续优化上下文管理不是一劳永逸的需要持续评估和优化。我给自己定了一个简单的评估指标代理首次回复的准确率。如果代理在拿到上下文后第一次给出的方案就需要大幅修改说明上下文质量有问题。评估的方法也很直接每周抽几个典型任务对比“有上下文注入”和“无上下文注入”两种情况下代理的表现。如果差异不明显说明上下文没有起到应有的作用需要检查检索策略或上下文内容。我还会定期审查数据库里的上下文把那些表述模糊、信息量低的记录删掉或重写。一条好的上下文应该让读者无论是人还是代理在 10 秒内理解核心信息。如果需要反复读才能明白那就需要重写。这套评估和优化机制运行了几个月之后我的上下文数据库从最初的两百多条精简到了八十多条但代理的表现反而更好了。这印证了一个道理上下文管理的核心不是“多”而是“准”。6.4 与其他工具的联动思路Context Mode 的数据库是一个开放的结构可以和其他开发工具联动。我目前尝试过的几个方向与代码审查工具联动。代码审查中发现的常见问题自动写入constraint类型的上下文。下次代理写代码时就会自动规避这些问题。与任务管理工具联动。任务管理系统里的任务描述和验收标准同步到tasks表。代理可以直接读取任务详情不需要人工转述。与文档系统联动。项目文档的关键段落提取成reference类型的上下文代理在需要时可以检索到相关文档内容。这些联动的核心思路都是一样的把散落在各个工具里的项目知识统一汇聚到上下文数据库里让代理有一个单一的信息来源。这个思路的扩展空间还很大我目前也还在探索中。 AI编码代理上下文管理：SQLite与MCP实战指南
1. 为什么 AI 编码代理需要一个独立的上下文管理层1.1 从“对话历史”到“上下文资产”的认知转变大多数开发者第一次接触 AI 编码代理时脑子里装的还是聊天机器人的模型我发一段话它回一段话对话历史就是全部记忆。这个模型在写个函数、改个变量名的时候够用但一旦项目规模上去问题就暴露得非常彻底。我去年接手过一个中型后端项目代码量大概在八万行左右模块之间耦合不算特别严重但业务逻辑盘根错节。当时我尝试用 AI 编码代理来辅助重构结果发现一个很尴尬的现象每次新开一个会话代理都要我重新解释一遍项目结构、技术栈、命名规范、数据库表关系。更离谱的是即便我在同一个会话里连续对话聊到第三四个问题的时候它就开始“忘记”前面说过的约束条件给出的代码风格前后不一致甚至会把已经废弃的接口又拿出来用。这不是模型能力的问题而是上下文管理机制的问题。传统的对话式 AI 把“上下文”等同于“聊天记录”聊天记录一长就截断、就摘要、就丢失细节。但对于编码代理来说上下文不是聊天记录而是项目知识、任务状态、历史决策、代码约束的集合。这些东西需要被结构化地存储、按需检索、精准注入而不是一股脑塞进对话窗口里。Context Mode 这个概念之所以值得单独拿出来讲就是因为它把上下文从“对话的附属品”提升成了“独立管理的资产”。它要解决的核心问题是如何让 AI 编码代理在长周期、多任务、跨会话的场景下依然能拿到准确、完整、不过载的上下文信息。1.2 传统上下文管理的三个致命伤在深入 Context Mode 的具体实现之前先把传统方案的问题说透这样后面讲设计思路的时候你才能理解每个决策背后的动机。第一个问题是上下文窗口的硬限制。不管模型支持多少 token它总是有限的。一个真实项目的代码库、文档、历史提交记录加起来轻松超过百万 token。你不可能把所有东西都塞进去。传统做法是截断或者摘要但截断会丢关键信息摘要会丢细节精度。我见过最粗暴的做法是只保留最近 N 轮对话结果代理把半小时前确认过的架构决策忘得一干二净。第二个问题是上下文的非结构化。聊天记录是线性的、时序的但项目知识是网状的。一个数据库表结构可能同时关联到 ORM 定义、迁移脚本、API 文档、测试用例。你把这些东西按时间顺序堆在对话里代理很难建立起正确的关联。它可能记得你十分钟前说过“用户表叫 users”但忘了二十分钟前说过“所有表名用复数形式”。第三个问题是跨会话的状态丢失。今天上午你花了两小时跟代理讨论清楚了一个模块的重构方案下午重新打开编辑器一切归零。你得重新解释背景重新确认约束重新纠正它犯过的错误。这种重复劳动在长期项目里累积起来消耗的时间非常可观。Context Mode 的设计目标就是针对这三点用外部存储解决窗口限制用结构化索引解决非结构化问题用持久化机制解决跨会话状态丢失。1.3 Context Mode 的核心设计哲学我理解 Context Mode 的核心哲学可以用一句话概括上下文不是用来“装”的而是用来“查”的。传统思路是想办法把更多东西塞进模型的上下文窗口Context Mode 的思路是建立一个外部的上下文存储层模型需要什么就去查什么。这有点像 CPU 的缓存机制寄存器容量最小但最快内存容量大但慢一些硬盘容量最大但最慢。Context Mode 相当于给 AI 编码代理加了一层“上下文缓存”把最常用的信息放在快速访问层把全量信息放在持久化存储层按需调度。这个思路落地需要几个关键组件一个结构化的存储引擎通常用 SQLite 这类嵌入式数据库、一套索引和检索机制、一个与代理运行时对接的协议层MCP 在这里扮演了重要角色、以及一套上下文生命周期的管理策略什么时候写入、什么时候读取、什么时候淘汰。接下来的章节我会逐一拆解这些组件结合我在实际项目中的使用经验把每个环节的实操要点和踩过的坑都讲清楚。2. 核心架构拆解SQLite 与 MCP 如何撑起上下文管理层2.1 为什么是 SQLite 而不是别的存储方案第一次看到 Context Mode 用 SQLite 做上下文存储的时候我其实有点意外。脑子里第一反应是为什么不用向量数据库为什么不用 Redis为什么不用文件系统后来自己动手搭了一套类似的东西之后才明白 SQLite 在这个场景下的优势几乎是压倒性的。零运维成本。向量数据库和 Redis 都需要独立部署、配置、监控。对于一个本地运行的 AI 编码代理来说引入这些外部依赖会让部署复杂度直线上升。SQLite 就是一个文件复制、备份、迁移都是一条命令的事。我在 Rocky Linux 上部署的时候sqlite3直接yum install就完事不需要任何额外配置。结构化查询能力。上下文信息天然适合用关系模型来表达。一个任务有多个步骤一个步骤关联多个文件一个文件有多个版本这些关系用 SQL 的 JOIN 查起来非常自然。向量数据库擅长的是语义相似度检索但编码代理需要的往往是精确查询“把 task_id 为 42 的所有相关文件找出来”这种查询用 SQL 比用向量检索准确得多。事务保证。上下文写入必须是原子的。如果代理在更新任务状态的时候中途崩溃不能出现“任务标记为完成但相关文件没更新”这种不一致状态。SQLite 的 ACID 事务在这个场景下非常关键。单文件便携性。你可以把整个上下文数据库打包带走换一台机器继续用。这对于需要在多台设备之间切换的开发者来说非常实用。当然 SQLite 也有它的局限。并发写入性能在高频场景下会成为瓶颈全文检索能力相比专门的搜索引擎要弱一些。但在 AI 编码代理这个场景下写入频率并不高通常是任务级别的粒度检索也以结构化查询为主SQLite 的短板基本不会暴露。2.2 MCP 协议在上下文管理中的角色定位MCP 最近热度很高但很多人对它的理解还停留在“让 AI 调用外部工具”这个层面。在 Context Mode 的架构里MCP 的作用远不止于此它实际上是代理运行时与上下文存储层之间的标准接口。我画一个简单的类比如果把 Context Mode 比作一个图书馆SQLite 是书架那么 MCP 就是借书证和检索系统。代理不需要知道书具体放在哪个架子上只需要通过 MCP 提供的标准接口说“我要借关于用户认证的所有资料”MCP 层负责把请求翻译成 SQL 查询从 SQLite 里取出数据再以代理能理解的格式返回。这个设计的好处是解耦。上下文存储的具体实现可以换今天用 SQLite明天换成别的嵌入式数据库只要 MCP 接口不变代理端的代码就不用动。反过来代理端的实现也可以换今天用这个编码助手明天换另一个只要它支持 MCP 协议就能接入同一套上下文存储。在实际配置中MCP 服务通常以本地进程的形式运行通过标准输入输出或者本地 socket 与代理通信。我在 Windows 环境下用db browser for sqlite来查看和调试上下文数据库同时 MCP 服务在后台运行两者互不干扰。这种“可视化调试 程序化访问”的组合在排查问题时非常高效。2.3 上下文数据的表结构设计这部分是我踩坑最多的地方也是我觉得最有必要详细展开的。Context Mode 的数据库表结构设计直接决定了检索效率和上下文质量。一个经过实战检验的最小可用表结构大概包含以下几张表表名用途关键字段contexts存储上下文条目id, type, content, created_at, updated_attasks任务状态跟踪id, name, status, parent_id, created_atcontext_task_map上下文与任务的关联context_id, task_id, relevancefiles文件元信息id, path, hash, last_indexedcontext_file_map上下文与文件的关联context_id, file_id, relation_typecontexts表是核心每一条记录代表一个独立的上下文单元。type字段用来区分上下文的种类比如decision架构决策、constraint约束条件、snippet代码片段、reference参考资料。这个分类非常重要因为不同类型的上下文在检索时的优先级和注入策略是不一样的。tasks表用来跟踪任务的层级结构。一个大的重构任务可能拆成多个子任务子任务又可能拆成更细的步骤。用parent_id建立树形结构代理在检索上下文的时候可以沿着任务树向上追溯把父任务的相关上下文也带出来。关联表的设计是精髓。context_task_map里的relevance字段用来标记上下文与任务的相关程度检索的时候可以按相关度排序优先注入最相关的上下文。context_file_map里的relation_type用来区分文件和上下文的关系类型比如defines文件定义了上下文中的某个概念、uses文件使用了上下文中的某个概念、modifies文件修改了上下文中的某个概念。注意表结构一旦确定后期修改字段类型的成本很高。SQLite 修改字段类型需要重建表所以在初期设计时就要想清楚每个字段的类型和约束。我建议所有文本字段统一用 TEXT时间字段统一用 INTEGER 存 Unix 时间戳避免时区和格式问题。2.4 上下文写入与检索的完整流程理解了表结构之后来看一个完整的上下文流转过程。假设代理正在执行一个“重构用户认证模块”的任务。写入阶段代理在分析代码的过程中识别出一个关键决策——“JWT token 的过期时间从 24 小时调整为 2 小时”。这个决策会被封装成一条contexts记录type为decisioncontent里包含决策内容和理由。同时这个决策关联到当前任务context_task_map以及涉及到的文件context_file_map。检索阶段当代理需要修改认证相关的代码时它通过 MCP 发起一个检索请求参数包括当前任务 ID、涉及的文件路径、需要的上下文类型。MCP 层把请求翻译成 SQL从contexts表里查出所有关联的决策、约束和代码片段按相关度排序后返回。注入阶段代理拿到检索结果后根据上下文类型和当前对话窗口的剩余空间决定注入哪些内容。决策和约束类上下文优先级最高代码片段次之参考资料最低。如果窗口空间不够低优先级的上下文会被摘要后再注入。这个流程的关键在于按需检索。代理不是一次性把所有上下文都加载进来而是在需要的时候才去查。这大大降低了上下文窗口的压力也让代理能够处理远超窗口限制的项目规模。我在实际使用中发现检索请求的参数设计非常关键。如果参数太宽泛查出来的上下文太多注入后反而干扰代理的判断如果参数太窄又可能漏掉关键信息。一个实用的技巧是先用文件路径做粗筛再用任务 ID 做精筛最后用上下文类型做优先级排序。这个三层过滤策略在大多数场景下都能取得不错的效果。3. 实操落地从零搭建一套可用的上下文管理系统3.1 环境准备与依赖安装这一节我以 Linux 环境为例把从零搭建的步骤完整走一遍。Windows 和 macOS 的差异我会在关键步骤处标注。首先是 SQLite 的安装。大多数 Linux 发行版已经预装了 SQLite但版本可能比较老。我建议手动安装最新稳定版# Rocky Linux / CentOS / RHEL 系 sudo yum install sqlite sqlite-devel # Ubuntu / Debian 系 sudo apt-get install sqlite3 libsqlite3-dev # 验证安装 sqlite3 --version如果你用的是 Windows直接去 SQLite 官网下载预编译的二进制文件解压后把目录加到 PATH 里就行。macOS 用户可以用 Homebrewbrew install sqlite3。接下来是 MCP 服务端的准备。MCP 本身是一个协议规范具体的服务端实现取决于你用的技术栈。我选择用 Python 来实现因为生态成熟、调试方便# 创建虚拟环境 python3 -m venv context-mode-env source context-mode-env/bin/activate # 安装依赖 pip install mcp sqlite-utilssqlite-utils这个库强烈推荐它提供了一套非常顺手的命令行工具和 Python API用来操作 SQLite 数据库比裸写 SQL 效率高很多。比如创建一个表sqlite-utils create-table context.db contexts \ id integer \ type text \ content text \ created_at integer \ updated_at integer \ --pk id这条命令就完成了建表比手写CREATE TABLE语句省事得多。提示数据库文件建议放在项目根目录下的.context/目录里并加入.gitignore。上下文数据是本地开发环境的一部分不应该提交到代码仓库。3.2 数据库初始化与表结构创建环境准备好之后开始建库建表。我把完整的初始化脚本贴出来你可以直接复制使用import sqlite3 import time def init_db(db_path.context/context.db): conn sqlite3.connect(db_path) cursor conn.cursor() # 上下文主表 cursor.execute( CREATE TABLE IF NOT EXISTS contexts ( id INTEGER PRIMARY KEY AUTOINCREMENT, type TEXT NOT NULL, content TEXT NOT NULL, metadata TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL ) ) # 任务表 cursor.execute( CREATE TABLE IF NOT EXISTS tasks ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, status TEXT DEFAULT pending, parent_id INTEGER, created_at INTEGER NOT NULL, FOREIGN KEY (parent_id) REFERENCES tasks(id) ) ) # 上下文-任务关联表 cursor.execute( CREATE TABLE IF NOT EXISTS context_task_map ( context_id INTEGER NOT NULL, task_id INTEGER NOT NULL, relevance REAL DEFAULT 1.0, PRIMARY KEY (context_id, task_id), FOREIGN KEY (context_id) REFERENCES contexts(id), FOREIGN KEY (task_id) REFERENCES tasks(id) ) ) # 文件表 cursor.execute( CREATE TABLE IF NOT EXISTS files ( id INTEGER PRIMARY KEY AUTOINCREMENT, path TEXT UNIQUE NOT NULL, hash TEXT, last_indexed INTEGER ) ) # 上下文-文件关联表 cursor.execute( CREATE TABLE IF NOT EXISTS context_file_map ( context_id INTEGER NOT NULL, file_id INTEGER NOT NULL, relation_type TEXT DEFAULT related, PRIMARY KEY (context_id, file_id), FOREIGN KEY (context_id) REFERENCES contexts(id), FOREIGN KEY (file_id) REFERENCES files(id) ) ) # 创建索引加速查询 cursor.execute(CREATE INDEX IF NOT EXISTS idx_contexts_type ON contexts(type)) cursor.execute(CREATE INDEX IF NOT EXISTS idx_contexts_created ON contexts(created_at)) cursor.execute(CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status)) conn.commit() conn.close() print(Database initialized successfully.) if __name__ __main__: init_db()这个脚本执行完之后你会得到一个包含五张表和三个索引的数据库文件。索引的创建是有讲究的contexts.type上的索引加速按类型筛选contexts.created_at上的索引加速按时间排序tasks.status上的索引加速查找待处理任务。关于metadata字段我特意留了一个 TEXT 类型的扩展字段用来存 JSON 格式的附加信息。比如一条代码片段类型的上下文可以在metadata里存{language: python, line_start: 42, line_end: 58}。这样既保持了主表的简洁又保留了扩展能力。3.3 MCP 服务端的核心接口实现MCP 服务端需要暴露几个核心接口给代理调用。我用 Python 的mcp库来实现核心接口包括写入上下文、检索上下文、更新任务状态、关联文件。import json import sqlite3 import time from mcp.server import Server, NotificationOptions from mcp.server.models import InitializationOptions import mcp.server.stdio import mcp.types as types app Server(context-mode) DB_PATH .context/context.db def get_db(): conn sqlite3.connect(DB_PATH) conn.row_factory sqlite3.Row return conn app.list_tools() async def list_tools(): return [ types.Tool( namewrite_context, description写入一条新的上下文记录, inputSchema{ type: object, properties: { type: {type: string, description: 上下文类型decision/constraint/snippet/reference}, content: {type: string, description: 上下文内容}, task_id: {type: integer, description: 关联的任务ID}, file_paths: {type: array, items: {type: string}, description: 关联的文件路径列表} }, required: [type, content] } ), types.Tool( namequery_context, description检索上下文记录, inputSchema{ type: object, properties: { task_id: {type: integer}, file_path: {type: string}, context_type: {type: string}, limit: {type: integer, default: 20} } } ), types.Tool( nameupdate_task, description更新任务状态, inputSchema{ type: object, properties: { task_id: {type: integer}, status: {type: string} }, required: [task_id, status] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): conn get_db() cursor conn.cursor() now int(time.time()) if name write_context: cursor.execute( INSERT INTO contexts (type, content, created_at, updated_at) VALUES (?, ?, ?, ?), (arguments[type], arguments[content], now, now) ) context_id cursor.lastrowid if task_id in arguments: cursor.execute( INSERT OR REPLACE INTO context_task_map (context_id, task_id, relevance) VALUES (?, ?, 1.0), (context_id, arguments[task_id]) ) if file_paths in arguments: for path in arguments[file_paths]: cursor.execute( INSERT OR IGNORE INTO files (path, last_indexed) VALUES (?, ?), (path, now) ) cursor.execute(SELECT id FROM files WHERE path ?, (path,)) file_id cursor.fetchone()[0] cursor.execute( INSERT OR REPLACE INTO context_file_map (context_id, file_id, relation_type) VALUES (?, ?, related), (context_id, file_id) ) conn.commit() conn.close() return [types.TextContent(typetext, textjson.dumps({context_id: context_id}))] elif name query_context: query SELECT DISTINCT c.* FROM contexts c params [] conditions [] if task_id in arguments: query JOIN context_task_map ctm ON c.id ctm.context_id conditions.append(ctm.task_id ?) params.append(arguments[task_id]) if file_path in arguments: query JOIN context_file_map cfm ON c.id cfm.context_id query JOIN files f ON cfm.file_id f.id conditions.append(f.path ?) params.append(arguments[file_path]) if context_type in arguments: conditions.append(c.type ?) params.append(arguments[context_type]) if conditions: query WHERE AND .join(conditions) query ORDER BY c.updated_at DESC LIMIT ? params.append(arguments.get(limit, 20)) cursor.execute(query, params) rows [dict(row) for row in cursor.fetchall()] conn.close() return [types.TextContent(typetext, textjson.dumps(rows, ensure_asciiFalse))] elif name update_task: cursor.execute( UPDATE tasks SET status ? WHERE id ?, (arguments[status], arguments[task_id]) ) conn.commit() conn.close() return [types.TextContent(typetext, textjson.dumps({updated: True}))] conn.close() return [types.TextContent(typetext, textjson.dumps({error: unknown tool}))] async def main(): async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): await app.run( read_stream, write_stream, InitializationOptions( server_namecontext-mode, server_version0.1.0 ) ) if __name__ __main__: import asyncio asyncio.run(main())这段代码实现了三个核心工具write_context、query_context、update_task。代理通过 MCP 协议调用这些工具就能完成上下文的读写操作。query_context的实现里有一个细节值得注意我用了DISTINCT来去重。因为一个上下文可能同时关联多个任务和多个文件JOIN 之后会产生重复行。DISTINCT确保每个上下文只返回一次。这个坑我在早期版本里踩过当时没加DISTINCT检索结果里同一条上下文出现了七八次注入后严重浪费了窗口空间。3.4 与编码代理的对接配置MCP 服务端跑起来之后需要在编码代理那边配置连接。不同的代理配置方式不一样但核心都是告诉代理“有一个 MCP 服务在某个地址上你可以调用它的工具”。以常见的配置格式为例通常是在代理的配置文件里加一段{ mcpServers: { context-mode: { command: python, args: [/path/to/context_mode_server.py], env: { DB_PATH: /path/to/project/.context/context.db } } } }配置完成之后重启代理它应该能自动发现context-mode提供的三个工具。你可以在代理的对话里让它“列出当前可用的工具”来验证连接是否成功。如果代理找不到 MCP 服务排查顺序是这样的先确认 Python 路径和脚本路径是否正确再确认依赖是否安装完整最后检查代理的日志输出。我遇到过最常见的问题是 Python 虚拟环境没有激活导致mcp库找不到。解决办法是在配置里用虚拟环境里的 Python 绝对路径而不是系统 Python。注意MCP 服务是以子进程形式运行的代理启动时它会自动拉起。如果代理异常退出MCP 进程可能变成孤儿进程。建议在服务端代码里加一个心跳检测父进程消失后自动退出。4. 上下文生命周期管理与检索策略优化4.1 上下文的写入时机与粒度控制上下文管理最容易犯的错误是“什么都往里写”。我刚开始用的时候恨不得把代理说的每一句话都存进去结果数据库迅速膨胀检索出来的上下文噪音极大代理反而被干扰得更厉害。后来我总结了一个原则只写入那些“下次会话还需要知道”的信息。具体来说以下几类信息值得写入架构决策为什么选 A 不选 B这个决策的约束条件是什么。接口约定模块之间的调用协议、数据格式、错误码定义。命名规范项目特有的命名习惯比如“所有 DTO 以 Request/Response 结尾”。已知问题当前版本存在的 bug、临时绕过方案、待优化项。关键代码片段那些被多个模块引用的核心函数或类。而以下几类信息不建议写入临时的调试输出和日志。已经被推翻的中间方案。代理的寒暄和确认性回复。可以从代码本身直接推断出来的信息。粒度控制也很关键。一条上下文记录应该是一个独立的、自包含的知识单元。比如“用户认证使用 JWT过期时间 2 小时刷新令牌 7 天”就是一条好的上下文。而“今天讨论了认证方案先说了 A 方案后来觉得不行又讨论了 B 方案最后决定用 C 方案”就是一条糟糕的上下文因为它包含了太多过程信息真正有用的结论被淹没了。4.2 检索结果的排序与截断策略检索出来的上下文不能一股脑全注入需要排序和截断。我的策略是三层排序第一层按类型优先级。constraint和decision类型优先级最高因为它们直接影响代码的正确性。snippet次之reference最低。第二层按时间新鲜度。同样类型的上下文越新的越相关。用updated_at倒序排列。第三层按关联强度。通过context_task_map.relevance字段来区分。直接关联当前任务的上下文优先级高于关联父任务的。排序之后是截断。我通常会给上下文注入预留窗口空间的 30% 左右。如果排序后的上下文总长度超过这个预算就从最低优先级的开始截断。截断时不是简单丢弃而是把多条低优先级上下文合并成一条摘要。比如三条关于日志格式的reference类型上下文可以合并成“日志格式相关参考使用 JSON 格式包含 timestamp、level、module、message 四个字段”。这个合并逻辑可以用一个简单的规则引擎来实现也可以让代理自己来做。我倾向于让代理来做因为代理更理解上下文的语义合并出来的摘要质量更高。4.3 上下文过期与清理机制上下文不是越多越好过期的上下文会拖慢检索速度也会增加噪音。我设计了一套简单的过期策略上下文类型默认保留期清理条件decision永久被新决策显式覆盖constraint永久关联任务标记为完成snippet90 天关联文件已删除或大幅修改reference30 天超过保留期且未被检索清理任务可以做成一个定时脚本每天跑一次def cleanup_expired_contexts(db_path, days_threshold90): conn sqlite3.connect(db_path) cursor conn.cursor() cutoff int(time.time()) - days_threshold * 86400 # 清理过期的 reference 类型上下文 cursor.execute( DELETE FROM contexts WHERE type reference AND updated_at ? AND id NOT IN ( SELECT context_id FROM context_task_map JOIN tasks ON context_task_map.task_id tasks.id WHERE tasks.status ! completed ) , (cutoff,)) deleted cursor.rowcount conn.commit() conn.close() return deleted这个清理逻辑的关键是只清理那些没有关联到活跃任务的上下文。如果一个reference上下文还关联着未完成的任务说明它还有用不能删。4.4 多任务场景下的上下文隔离与共享实际项目中开发者往往同时推进多个任务。任务 A 的上下文不应该干扰任务 B 的代理行为但有些全局性的上下文比如项目编码规范又应该被所有任务共享。我的做法是在contexts表里加一个scope字段用来标记上下文的作用域global全局上下文所有任务可见。task任务级上下文只有关联的任务可见。session会话级上下文只在当前会话有效会话结束即失效。检索的时候查询条件里加上scope IN (global, task)并且task_id匹配当前任务。这样既保证了全局规范的一致性又实现了任务之间的隔离。session级别的上下文我通常不写入数据库而是放在内存里会话结束自动丢弃。这类上下文包括临时的调试信息、当前正在编辑的文件内容等。提示如果你的项目有多个开发者共用一套上下文数据库建议再加一个owner字段来区分上下文来源。否则 A 开发者写入的临时决策可能会干扰 B 开发者的代理行为。5. 实战中踩过的坑与排查技巧5.1 数据库锁冲突与并发写入问题SQLite 默认的并发模型是“多读单写”。当代理同时发起多个写入请求时后到的请求会收到database is locked错误。我在早期版本里没处理这个问题导致代理偶尔会丢失上下文写入。解决方案有两个层面。第一层是应用层重试import time import sqlite3 def execute_with_retry(conn, query, params, max_retries5): for attempt in range(max_retries): try: cursor conn.cursor() cursor.execute(query, params) conn.commit() return cursor except sqlite3.OperationalError as e: if database is locked in str(e) and attempt max_retries - 1: time.sleep(0.1 * (attempt 1)) continue raise return None第二层是数据库配置优化conn sqlite3.connect(db_path, timeout10) conn.execute(PRAGMA journal_modeWAL) conn.execute(PRAGMA busy_timeout5000)WAL模式Write-Ahead Logging允许一个写入者和多个读取者同时操作大大降低了锁冲突的概率。busy_timeout设置成 5000 毫秒意味着遇到锁的时候会自动等待 5 秒再报错给重试留出了空间。这两个配置加上之后我在实际使用中再也没有遇到过锁冲突导致的上下文丢失。5.2 检索结果不准确的原因分析检索结果不准确通常表现为两种要么查出来一堆不相关的上下文要么该查出来的没查出来。查出来太多不相关的内容最常见的原因是文件路径匹配太宽泛。比如你用src/作为查询条件那所有在src/下的文件关联的上下文都会被查出来。解决办法是尽量用精确的文件路径或者用文件 ID 而不是路径来关联。另一个原因是上下文类型没有正确设置。如果所有上下文都标成reference那优先级排序就失效了。写入的时候一定要根据内容性质选择正确的类型。该查出来的没查出来通常是关联关系没有建立完整。比如你写入了一条关于数据库表结构的决策但忘记关联到models.py文件。下次代理修改models.py的时候就检索不到这条决策。解决办法是在写入上下文的时候尽量把相关的文件都关联上。宁可多关联几个也不要漏掉。我后来养成了一个习惯每次写入上下文之后立刻用query_context反向查一次确认能查到。这个“写入后验证”的步骤帮我避免了很多关联遗漏的问题。5.3 上下文注入过多导致代理“分心”这是一个很微妙的问题。上下文注入太少代理缺乏信息注入太多代理反而会“分心”在无关的信息上浪费注意力。我遇到过一个典型案例代理在修改一个简单的工具函数时检索出了二十多条相关上下文包括三个月前的架构讨论、两周前的性能优化决策、昨天的代码审查意见。结果代理花了大量篇幅分析这些上下文最后给出的修改方案反而偏离了当前任务的实际需求。解决办法是动态调整检索范围。对于简单的、局部的修改任务只检索直接关联文件的constraint和snippet类型上下文限制在 5 条以内。对于复杂的、跨模块的重构任务才扩大检索范围。我在 MCP 服务端加了一个query_context的mode参数focused精确模式只查直接关联的上下文限制 5 条。normal普通模式查直接关联和一级间接关联限制 15 条。broad宽泛模式查所有关联限制 30 条。代理根据任务复杂度自己选择模式。这个简单的分级策略效果非常明显代理的输出质量有了肉眼可见的提升。5.4 常见问题速查表现象可能原因排查方法解决方案代理找不到 MCP 工具配置路径错误或依赖缺失检查代理日志中的 MCP 连接信息确认 Python 路径和依赖安装写入上下文报错数据库锁冲突查看错误信息是否含 database is locked启用 WAL 模式并加重试逻辑检索结果为空关联关系未建立直接查数据库确认记录存在写入时补全 task_id 和 file_paths检索结果过多查询条件太宽泛检查查询参数中的文件路径使用精确路径或文件 ID代理输出质量下降上下文注入过多统计注入的上下文条数和长度降低检索模式或增加截断阈值数据库文件过大过期上下文未清理查看各类型上下文的记录数运行清理脚本删除过期数据跨会话状态丢失上下文未持久化检查数据库文件是否被正确写入确认写入操作有 commit这张表里的每一行都是我实际遇到过的问题。其中“代理输出质量下降”这一条最隐蔽因为代理不会报错只是给出的结果不如预期。你需要对比注入上下文前后的输出差异才能定位到是上下文过多导致的。6. 从 Context Mode 延伸出的几个实用技巧6.1 用上下文数据库做项目知识沉淀Context Mode 的数据库不仅仅服务于 AI 代理它本身就是一个结构化的项目知识库。我现在的习惯是每次跟代理讨论出一个重要的架构决策就手动写入一条decision类型的上下文。日积月累下来这个数据库就成了项目的“决策日志”。新加入项目的开发者或者你自己几个月后回头看可以通过查询这个数据库快速了解项目的关键设计。这比翻聊天记录或者找文档高效得多因为每条上下文都是结构化的、可检索的。我甚至用db browser for sqlite给数据库做了一个简单的可视化界面按类型和任务分组展示上下文。团队内部共享这个数据库文件大家都能看到最新的决策和约束。6.2 上下文模板化与自动化写入手动写入上下文虽然灵活但效率不高。我后来做了一套模板把常见的上下文类型预定义好格式代理只需要填充关键信息就行。比如架构决策的模板决策[一句话描述] 背景[为什么需要做这个决策] 选项[考虑过哪些方案] 选择[最终选了哪个] 理由[为什么选这个] 影响[对哪些模块有影响]代理在讨论过程中识别到决策点时自动按这个模板生成上下文并写入。这样既保证了上下文的完整性又减少了手动整理的工作量。自动化写入的触发条件可以这样设计当代理的回复中包含“决定”、“选择”、“采用”、“方案”等关键词并且回复长度超过一定阈值时提示代理生成一条decision类型的上下文。这个规则虽然简单但命中率相当高。6.3 上下文质量评估与持续优化上下文管理不是一劳永逸的需要持续评估和优化。我给自己定了一个简单的评估指标代理首次回复的准确率。如果代理在拿到上下文后第一次给出的方案就需要大幅修改说明上下文质量有问题。评估的方法也很直接每周抽几个典型任务对比“有上下文注入”和“无上下文注入”两种情况下代理的表现。如果差异不明显说明上下文没有起到应有的作用需要检查检索策略或上下文内容。我还会定期审查数据库里的上下文把那些表述模糊、信息量低的记录删掉或重写。一条好的上下文应该让读者无论是人还是代理在 10 秒内理解核心信息。如果需要反复读才能明白那就需要重写。这套评估和优化机制运行了几个月之后我的上下文数据库从最初的两百多条精简到了八十多条但代理的表现反而更好了。这印证了一个道理上下文管理的核心不是“多”而是“准”。6.4 与其他工具的联动思路Context Mode 的数据库是一个开放的结构可以和其他开发工具联动。我目前尝试过的几个方向与代码审查工具联动。代码审查中发现的常见问题自动写入constraint类型的上下文。下次代理写代码时就会自动规避这些问题。与任务管理工具联动。任务管理系统里的任务描述和验收标准同步到tasks表。代理可以直接读取任务详情不需要人工转述。与文档系统联动。项目文档的关键段落提取成reference类型的上下文代理在需要时可以检索到相关文档内容。这些联动的核心思路都是一样的把散落在各个工具里的项目知识统一汇聚到上下文数据库里让代理有一个单一的信息来源。这个思路的扩展空间还很大我目前也还在探索中。