1. 从一次账单焦虑说起：为什么要自己造一个本地优先的编码 Agent
事情的起因很朴素。我日常写代码有相当一部分时间花在重复性的重构、补测试、查文档、写样板代码上，用云端编码 Agent 确实爽，但月底一看账单，心里咯噔一下。尤其是当你想让它长时间跑一个任务、反复读大文件、来回迭代的时候，token 消耗是肉眼可见地往上窜。于是我开始琢磨一件事：能不能把"编码 Agent"这件事拆开，把最贵的部分——也就是模型调用——换成可控的本地或低成本引擎，同时保留 Agent 最核心的能力：读写文件、执行命令、维护上下文、记住历史。
这就是标题里说的"本地优先的多引擎平替"。关键词有三个：本地优先、多引擎、Agent。本地优先的意思是，默认情况下所有数据、会话、文件索引都落在你自己的机器上，用一个轻量数据库（我用的是 SQLite）来存，不依赖任何云端账号；多引擎的意思是，底层模型可以换，今天用这个，明天用那个，接口层做统一抽象；Agent 的意思是，它不只是个聊天框，而是能真正动手改你项目文件的执行体。
这篇文章适合谁看？三类人。第一类是被云端编码工具账单劝退、想自己掌控成本的开发者；第二类是正在学 Agent 开发、想找一个完整可跑通的实战项目练手的同学；第三类是对 SQLite 这种嵌入式数据库感兴趣、想看看它在真实 Agent 场景里怎么用的人。我会把架构设计、引擎抽象、SQLite 表结构、上下文管理、踩过的坑全部摊开讲，代码和配置尽量给到能直接抄的程度。
先说结论：这套东西我陆陆续续打磨了大概三周，现在日常替代了我八成以上的云端编码调用。它不是要完全取代谁，而是在"高频、低价值、可本地化"的任务上，把成本压到几乎为零。下面从架构开始拆。
2. 整体架构：把 Agent 拆成四层，每层都能单独替换
2.1 为什么是四层而不是一个大脚本
很多人写 Agent 的第一反应是写一个大 Python 脚本，把模型调用、文件读写、命令执行全塞在一起。我一开始也这么干，结果就是：想换个模型要改十几处，想加个记忆功能发现状态全散在全局变量里，想调试某一步根本插不进日志。所以第二版我强制自己做了分层，一共四层，从上到下是：
- 交互层（CLI / TUI）：负责接收你的指令、展示 Agent 的思考和执行过程。我用的是命令行交互，简单直接。
- 编排层（Orchestrator）：Agent 的大脑，负责决定"下一步做什么"——是读文件、写文件、执行命令，还是直接回答。这一层是引擎无关的。
- 引擎层（Engine Adapter）：把不同模型提供方的接口统一成同一个
chat()和stream()方法。换引擎只改这一层。 - 持久层（SQLite）：存会话、消息、文件快照、工具调用记录、向量索引。全部落在本地一个
.db文件里。
这样分层最大的好处是：编排逻辑和模型解耦。我可以在同一个会话里，前半段用便宜的小模型做文件检索，后半段用强模型做复杂推理，编排层完全不用感知。
2.2 数据流是怎么走的
一次典型的请求，数据流是这样的：你在 CLI 输入"帮我把 utils 目录下所有函数补上类型注解"，交互层把这句话交给编排层；编排层先从 SQLite 里捞出当前会话的历史消息和项目文件索引，拼成一个上下文；然后调用引擎层的chat()，把上下文和可用工具列表一起发过去；模型返回一个"我要调用 read_file 工具读 utils/a.py"的结构化指令；编排层解析后真正去读文件，把结果再喂回模型；循环直到模型说"我改完了"，编排层把改动写回文件，并把整个过程记进 SQLite。
这里有个关键设计：工具调用是编排层执行的，不是模型执行的。模型只负责"说"要调什么工具、传什么参数，真正动手的是本地代码。这一点非常重要，因为它意味着模型永远碰不到你的文件系统，安全性完全由你掌控。这也是本地优先的核心价值之一。
2.3 本地优先到底优先在哪
"本地优先"不是一句口号，它体现在几个具体决策上。第一，会话数据默认只存本地，SQLite 文件就在项目根目录的.agent/下，你随时可以用 DB Browser for SQLite 打开看里面存了什么，透明。第二，文件索引本地构建，我用简单的关键词倒排加文件哈希，不依赖任何云端 embedding 服务，虽然检索精度不如向量库，但对代码这种结构化文本够用了。第三，引擎可离线，如果你本地跑了开源模型，整个 Agent 可以完全断网运行。
提示：本地优先不等于拒绝云端。我的实际配置是"默认本地小模型 + 复杂任务手动切云端强模型"，把选择权留给自己，而不是被工具绑定。
3. 多引擎抽象：一套接口适配所有模型提供方
3.1 引擎接口应该长什么样
多引擎的关键是抽象出一个足够小、又足够通用的接口。我踩过的坑是：一开始接口设计得太"聪明"，加了各种analyze_image、generate_code之类的方法，结果每接一个新引擎都要实现一堆用不上的方法。后来砍到只剩两个核心方法：
class BaseEngine: def chat(self, messages: list[dict], tools: list[dict] | None = None) -> dict: """同步调用，返回 {content, tool_calls, usage}""" raise NotImplementedError def stream(self, messages: list[dict], tools: list[dict] | None = None): """流式调用，逐块 yield 文本增量""" raise NotImplementedErrormessages用统一的 OpenAI 风格格式（role + content），tools用 JSON Schema 描述。所有引擎适配器负责把这两个参数翻译成自己提供方的格式，再把返回结果翻译回统一结构。这样编排层永远只认这一套。
3.2 适配不同引擎时最容易踩的坑
第一个坑是工具调用的格式差异。有的提供方把工具调用放在message.tool_calls里，有的放在content的特定块里，还有的用 XML 标签包裹。我的做法是在适配器里做归一化，统一转成[{id, name, arguments}]的结构，编排层只处理这一种。
第二个坑是流式响应里工具调用的拼接。流式返回时，工具调用的参数是一块一块吐出来的，你得自己拼。我见过不少人在这里翻车，拼出来的 JSON 缺个括号，解析直接报错。稳妥做法是：流式阶段只累积字符串，等流结束后再统一json.loads，并且加一层容错，解析失败就重试一次。
第三个坑是上下文长度限制不一致。不同引擎能吃的 token 数差很多，编排层不能假设"上下文永远塞得下"。我的方案是在持久层记录每条消息的估算 token 数，拼上下文时从最新往回加，超预算就丢弃最老的消息，同时保留一条"摘要消息"作为长期记忆。
| 引擎类型 | 工具调用支持 | 流式支持 | 典型适用场景 |
|---|---|---|---|
| 本地小模型 | 部分支持，需提示词引导 | 支持 | 文件检索、简单改写、格式转换 |
| 云端强模型 | 原生支持 | 支持 | 复杂重构、跨文件推理、架构设计 |
| 兼容接口服务 | 视实现而定 | 支持 | 作为统一入口，灵活切换后端 |
3.3 引擎切换的运行时策略
我给自己定了个简单的路由规则，写在配置里：任务预估 token 小于 2000 且不涉及跨文件修改，走本地小模型；涉及三个以上文件或需要理解项目结构，走强模型；用户显式指定--engine xxx时无条件服从。这个规则不复杂，但省了我大量手动切换的精力。
实现上，编排层持有一个EngineRouter，根据任务特征返回对应的引擎实例。引擎实例是懒加载的，第一次用到才初始化，避免启动时把所有引擎都连一遍。这里有个小技巧：给每个引擎加一个健康检查缓存，如果某个引擎连续失败三次，短时间内直接跳过它，避免每次都卡在超时上。
4. SQLite 持久层：Agent 的记忆到底该怎么存
4.1 为什么选 SQLite 而不是文件或向量库
先说为什么不用纯 JSON 文件。会话一多，读写整个文件的开销就上来了，而且并发写容易损坏。为什么不用专业向量库？对个人项目来说太重，部署和维护成本高，而且代码检索用关键词倒排其实效果不差。SQLite 的好处是：零部署、单文件、支持事务、支持全文检索（FTS5），完美契合本地优先的定位。
我用 DB Browser for SQLite 直接打开过自己的库，表结构一目了然，调试的时候特别方便。这一点是很多"黑盒"方案给不了的。
4.2 核心表结构设计
我的库里有五张核心表，设计时反复调整过几轮：
-- 会话表 CREATE TABLE sessions ( id TEXT PRIMARY KEY, title TEXT, created_at INTEGER, updated_at INTEGER, engine TEXT, metadata TEXT ); -- 消息表 CREATE TABLE messages ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, role TEXT, content TEXT, tool_calls TEXT, token_estimate INTEGER, created_at INTEGER, FOREIGN KEY (session_id) REFERENCES sessions(id) ); -- 文件快照表 CREATE TABLE file_snapshots ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, path TEXT, content_hash TEXT, content TEXT, created_at INTEGER ); -- 工具调用记录 CREATE TABLE tool_calls ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, message_id INTEGER, tool_name TEXT, arguments TEXT, result TEXT, status TEXT, duration_ms INTEGER, created_at INTEGER ); -- 全文检索索引 CREATE VIRTUAL TABLE file_fts USING fts5( path, content, tokenize='unicode61' );几个设计要点值得说。消息表存 token_estimate，是为了拼上下文时能快速算预算，不用每次重新估算。文件快照表存 content_hash，是为了判断文件是否被外部修改过——如果 Agent 上次读的文件现在哈希变了，说明你手动改过，得重新读。工具调用单独建表，是为了事后分析：哪些工具调用最频繁、哪些经常失败、平均耗时多少，这些数据对优化 Agent 行为非常有用。
4.3 用 FTS5 做代码检索的实操细节
SQLite 的 FTS5 全文检索是这套方案里我最满意的部分。建好虚拟表后，插入文件内容，然后用MATCH查询：
SELECT path, snippet(file_fts, 1, '[', ']', '...', 20) FROM file_fts WHERE file_fts MATCH 'type annotation OR type hint' ORDER BY rank LIMIT 10;snippet函数能直接返回带高亮标记的片段，喂给模型特别合适。但有几个坑要注意：第一，代码里的特殊符号会干扰分词，比如->、::，默认分词器处理不好，我加了预处理，把常见符号替换成空格再入库。第二，FTS5 的查询语法和普通 SQL 不同，OR、AND、NEAR有特定含义，用户输入的关键词要先转义。第三，索引要增量更新，不能每次全量重建，我用文件哈希对比，只更新变化的文件。
注意：FTS5 默认可能没编译进你的 SQLite。用
sqlite3 :memory: "CREATE VIRTUAL TABLE t USING fts5(x)"测一下，报错就说明得换一个带 FTS5 的构建版本。
4.4 会话恢复与上下文重建
Agent 最实用的能力之一是"接着上次聊"。我的实现是：启动时列出最近会话，选中后从 messages 表按时间顺序捞出消息，重新拼成上下文。但这里有个细节——工具调用的结果要不要全部重放？我的经验是不要。工具调用结果往往很长（比如读了一个大文件），全部重放会瞬间撑爆上下文。我的做法是只保留工具调用的"摘要"，比如"读取了 utils/a.py，共 120 行"，具体内容需要时再重新读。
这个策略让会话恢复的上下文占用降低了大概七成，而且不影响模型理解当前进度。踩过的坑是：早期我图省事全量重放，结果恢复一个长会话直接超出上下文限制，模型开始胡言乱语。
5. 编排层：Agent 的决策循环与工具设计
5.1 决策循环的骨架
编排层的核心是一个循环，伪代码大概是这样：
def run_agent(user_input, session): messages = build_context(session, user_input) for step in range(MAX_STEPS): response = engine.chat(messages, tools=TOOL_SCHEMAS) messages.append(response.as_message()) if not response.tool_calls: return response.content for call in response.tool_calls: result = execute_tool(call) messages.append(tool_result_message(call.id, result)) persist_tool_call(session, call, result) return "达到最大步数限制，任务可能未完成"看起来简单，但魔鬼在细节里。MAX_STEPS设多少？我一开始设 10，发现复杂任务不够；设 50，又容易陷入死循环。最后设成 25，并且加了一个"重复检测"：如果连续三次工具调用完全一样，直接中断并提示模型换个思路。
5.2 工具集应该包含哪些能力
工具不在多，在于覆盖核心场景。我最终保留了六个工具：
read_file(path, start, end)：读文件，支持行范围，避免一次读太大。write_file(path, content)：写文件，写之前自动备份到快照表。list_dir(path)：列目录，帮助模型了解项目结构。search_code(query)：走 FTS5 检索，返回相关片段。run_command(cmd)：执行命令，有白名单限制。ask_user(question)：需要澄清时主动问你。
run_command是最危险的工具，我做了三层防护：命令白名单（只允许测试、格式化、构建类命令）、超时限制（默认 30 秒）、输出截断（超过 5000 字符只保留头尾）。这些防护不是不信任模型，而是防止它在理解偏差时造成不可逆的破坏。
5.3 提示词里必须写清楚的几件事
编排层的系统提示词我改了十几版，最后稳定下来的版本强调了几点：第一，明确告诉模型它有哪些工具、每个工具的边界，尤其是read_file要说明"大文件请用行范围分段读"。第二，要求模型在修改文件前先读，避免它凭想象改代码。第三，要求它一次只做一件事，不要在一个回复里既读文件又写文件又跑命令，这样出错了不好定位。
实测下来，把"一次只做一件事"写进提示词后，任务成功率明显提升。因为模型每步的输出变短了，出错概率降低，而且中间结果能被持久层记录下来，方便回溯。
5.4 错误处理：Agent 卡住了怎么办
Agent 最常见的失败模式有三种：工具调用参数错误、陷入循环、上下文超限。我的处理策略各不相同。参数错误时，把错误信息作为工具结果喂回去，让模型自己修正，通常一两次就能改对。陷入循环时，靠前面说的重复检测中断。上下文超限时，触发摘要压缩——把最老的一批消息交给引擎生成一段摘要，替换掉原文。
这里有个经验：摘要压缩要保留工具调用的"意图"而不是"结果"。比如"读取了配置文件以确认端口号"比"读取了 config.yaml，内容是 xxx"更有长期价值，因为前者保留了推理链条，后者只是数据。
6. 实测数据与踩坑复盘
6.1 成本对比：本地优先到底省了多少
我拿自己一个月的实际使用做了粗略统计。改造前，纯云端编码 Agent 的月消耗大概在一个让我肉疼的数字；改造后，同样的任务量，云端调用量下降了约 75%，因为大量简单任务被路由到了本地小模型。剩下的 25% 是真正需要强模型的复杂任务，这部分我没省，也不该省。
需要说明的是，本地小模型不是免费的——它消耗你的电和算力，还有时间成本。我的实测是：本地小模型处理一个简单改写任务平均 8 秒，云端强模型 3 秒。所以路由策略里我加了一条：如果任务对延迟敏感（比如你在交互式地改代码），优先走云端。省钱和体验之间要平衡，不能一刀切。
6.2 那些让我熬夜的坑
第一个大坑是文件编码。我有个项目里有 GBK 编码的老文件，Agent 读进来直接乱码，写回去把文件搞坏了。后来我在读写层强制做编码探测，用chardet之类的库先判断，再决定用什么编码打开。这个坑教训很深：永远不要假设文件是 UTF-8。
第二个坑是符号链接和循环目录。list_dir递归时遇到符号链接指回上级目录，直接无限递归。修复方案是记录已访问的 inode，遇到重复就跳过。
第三个坑是SQLite 并发写。我一度想同时跑两个 Agent 会话，结果两个进程同时写库，报database is locked。SQLite 默认的锁粒度比较粗，解决方案是开启 WAL 模式（PRAGMA journal_mode=WAL），并给写操作加超时重试。开启 WAL 后，读写可以并发，体验好很多。
第四个坑是工具调用结果的截断。早期我不截断，模型读了个几千行的文件，结果上下文直接爆掉。后来统一在工具层做截断，并且告诉模型"结果已截断，如需更多请指定行范围"。
6.3 性能优化：让 Agent 跑得更快
几个实测有效的优化。第一，文件索引预热：启动时后台线程扫描项目，构建 FTS 索引，这样第一次检索不用等。第二，引擎连接复用：HTTP 客户端用连接池，别每次调用都新建。第三，工具结果缓存：同一个文件在同一个会话里读两次，第二次直接返回缓存，除非文件哈希变了。第四，流式输出：让用户能实时看到模型在"想"什么，体感快很多，虽然总耗时没变。
| 优化项 | 优化前 | 优化后 | 说明 |
|---|---|---|---|
| 首次检索延迟 | 约 3 秒 | 约 0.2 秒 | 索引预热 |
| 重复读文件 | 每次真实读盘 | 命中缓存 | 哈希校验 |
| 并发会话 | 报锁错误 | 正常 | WAL 模式 |
| 长会话恢复 | 上下文超限 | 正常 | 摘要压缩 |
7. 如果你想自己动手：从零搭起来的最小路径
7.1 环境准备与依赖选择
技术栈我选的是 Python，理由是生态成熟、上手快。核心依赖就几个：一个 HTTP 客户端（httpx）、SQLite（标准库自带）、一个 CLI 框架（typer或click）、一个终端渲染库（rich）。不需要任何重型框架，整个项目核心代码不到两千行。
数据库文件放在项目根的.agent/sessions.db，记得加进.gitignore。如果你用 VS Code，可以装个 SQLite 查看插件，或者直接用 DB Browser for SQLite 打开，调试时非常直观。
7.2 分阶段实现建议
别想着一次写完。我的建议是分四步走。第一步，先实现最简单的"读文件 + 调模型 + 打印结果"，跑通引擎适配。第二步，加 SQLite 持久化，把消息存下来，实现会话恢复。第三步，加工具调用循环，先只做read_file和write_file。第四步，再加检索、命令执行、路由策略这些进阶功能。
每一步都要能独立跑通、独立验证。我见过太多人一上来就搭大框架，结果卡在某一步调不通，整个项目就烂尾了。
7.3 几个能直接抄的配置片段
WAL 模式和性能相关的 PRAGMA，建议在连接初始化时就设好：
conn = sqlite3.connect(db_path, timeout=10) conn.execute("PRAGMA journal_mode=WAL") conn.execute("PRAGMA synchronous=NORMAL") conn.execute("PRAGMA cache_size=-64000") conn.execute("PRAGMA foreign_keys=ON")cache_size设成负值表示用 KB 为单位，这里给了 64MB 缓存，对个人项目足够。synchronous=NORMAL在 WAL 模式下是安全性和性能的平衡点，比默认的 FULL 快不少。
工具调用的 JSON Schema 也给你一个模板：
{ "name": "read_file", "description": "读取文件内容，大文件请用 start/end 指定行范围", "parameters": { "type": "object", "properties": { "path": {"type": "string", "description": "相对于项目根目录的路径"}, "start": {"type": "integer", "description": "起始行，从 1 开始"}, "end": {"type": "integer", "description": "结束行，含"} }, "required": ["path"] } }描述写得越清楚，模型用错工具的概率越低。这是我在反复调试中体会最深的一点：提示词工程的一半功夫在工具描述上。
8. 这套方案适合谁，以及我后续想加的东西
坦白讲，这套东西不是给所有人准备的。如果你只是偶尔用一下编码助手，云端方案的开箱即用体验更好，没必要折腾。但如果你符合下面几种情况，自己造一个会很值：调用频率高、对成本敏感、在意数据隐私、或者单纯想搞懂 Agent 到底是怎么运转的。
我后续想加的东西有几个。一是更细粒度的权限控制，比如某些目录只读、某些命令需要二次确认。二是多会话并行，现在虽然能开多个进程，但共享索引的同步还不够优雅。三是更好的本地检索，想试试把 FTS5 和轻量向量检索结合，关键词召回加语义重排，精度应该能再上一个台阶。
最后分享一个我踩坑踩出来的小技巧：给 Agent 的每次文件修改都留快照，并且提供一条"回滚到上一步"的命令。模型再聪明也会犯错，有个后悔药，用起来心里踏实得多。这个功能我加了之后，敢让 Agent 动的文件范围明显扩大了，因为它出错了我能一键还原。做本地优先的工具，掌控感才是最大的价值。
