1. 为什么我要把 AI 编程代理拆成九个独立仓库
先说结论：把一套 AI 编程代理工具链拆成九个仓库、全部走 MIT 协议开源，不是洁癖，是被逼出来的。我最初也是一个大仓库打天下，所有能力塞在一个agent-core里，结果三个月后自己都改不动了——记忆模块和代码索引耦合在一起，改一个检索策略要重新跑一遍全量索引；token 记账逻辑散落在七八个文件里，想加一个"按会话维度统计"的需求，得翻半天代码。真正让我下决心拆分的，是一次线上排查：某个会话的上下文突然爆炸，我花了两个小时才定位到是记忆压缩模块和代码地图模块在互相喂数据，形成了隐性的循环膨胀。
拆成九个仓库之后，每个仓库只解决一个明确的问题，接口用最薄的协议层粘合。这样做的好处很直接：任何一个模块都可以被单独替换、单独测试、单独复用。你只想用我的 token 记账，完全可以只拉那一个仓库，不需要把整套代理框架都搬进来。这也是我坚持全 MIT 的原因——工具链这种东西，越少限制越容易被真正用起来，我不想让任何人在"能不能商用"这种问题上浪费时间。
这九个仓库大致可以归成四类能力：记忆层（短期会话记忆、长期知识沉淀、记忆压缩与召回）、代码理解层（代码地图、符号索引、依赖关系图）、执行与调度层（代理主循环、工具调用编排）、可观测层（token 记账、调用链路追踪）。下面我会按这个脉络，把每一块的设计动机、踩过的坑、以及你可以直接抄的配置都讲清楚。适合谁看？如果你正在自己搭 AI 编程助手，或者已经在用现成的代理但总觉得"上下文管理很玄学""token 花得不明不白"，那这篇基本就是给你写的。
2. 记忆层：短期会话记忆和长期知识沉淀为什么要分开
2.1 短期记忆的核心矛盾是"窗口有限但对话无限"
短期会话记忆要解决的问题很具体：一次编程会话可能持续几十轮，每轮都带代码片段、报错信息、工具返回结果，很快就把上下文窗口撑满。我见过太多实现是把历史消息简单截断——保留最近 N 条，前面的直接丢。这种做法在简单问答里凑合能用，但在编程场景里会出大问题：用户在第 3 轮说过"这个项目用的是 pnpm 不是 npm"，到第 20 轮代理又给你生成npm install，因为它早把这句话截掉了。
我的做法是把短期记忆做成一个带权重的滑动窗口 + 关键事实抽取的双层结构。滑动窗口负责保留最近若干轮的原始对话，保证连贯性；关键事实抽取则把对话里出现的"约束条件"（包管理器、代码风格、目录约定、禁用 API 等）单独拎出来，存成一个结构化的约束列表，这个列表不随窗口滑动而丢失。具体实现上，我用一个轻量的规则匹配加一次小模型调用，把每轮对话里可能的约束抽出来，去重后合并进约束列表。
这里有个参数值得说：窗口保留轮数我默认设成 12 轮，但这个值不是拍脑袋来的。实测下来，编程会话里超过 12 轮之前提到的具体代码细节，用户自己往往也记不清了，真正需要跨轮保留的是"约束"而不是"原文"。所以窗口可以短，约束列表必须长。这个取舍直接决定了 token 消耗——如果无脑保留 30 轮原文，token 成本大概会翻 2.5 倍，而体验提升几乎为零。
2.2 长期记忆不是向量库一塞就完事
长期知识沉淀这块，我踩的最大坑就是"以为向量检索能解决一切"。最开始我把所有历史会话、代码片段、文档全部 embedding 进一个向量库，检索时按相似度 top-k 召回。结果发现两个问题：第一，召回的片段经常是"语义相似但实际无关"，比如你问数据库连接池配置，它给你召回一段讲线程池的代码，因为词面上太像了；第二，纯向量检索没有时间维度和项目维度的过滤，跨项目的记忆会互相污染。
后来我改成混合检索：向量相似度只作为其中一路信号，另外两路是关键词精确匹配和结构化元数据过滤（项目 ID、文件路径、时间范围）。三路结果做加权融合，权重可以按场景调。对于"这个函数在哪定义"这类问题，关键词和路径过滤的权重调高；对于"之前讨论过的架构思路"这类模糊问题，向量权重调高。这个融合逻辑我单独抽成了一个仓库，因为它跟具体的存储后端无关，你换任何向量库都能复用。
还有一个经验：长期记忆一定要有写入节制。不是每轮对话都值得写进长期库，否则库会迅速膨胀、检索质量下降。我的策略是只写入三类内容：用户显式确认的决策、被验证有效的代码模式、以及明确的纠错记录。写入前做一次去重和摘要压缩，把一段对话压成一条 100 字以内的记忆条目。这样长期库的增长是可控的，检索信噪比也高得多。
2.3 记忆压缩：什么时候压、压到什么程度
记忆压缩是记忆层里最容易被低估的一环。上下文快满的时候，你需要把旧内容压缩掉，但压缩得太狠会丢信息，压得太松又没省下 token。我的做法是分级压缩：第一级只做去冗余，把重复的代码块、重复的报错信息合并；第二级做摘要，把一段多轮对话压成要点列表；第三级才做丢弃，只保留约束和结论。
触发时机上，我不等到窗口真的满了才压，而是在用到 70% 容量时就开始第一级压缩，85% 时做第二级。这样留出缓冲，避免在关键推理中途被迫压缩导致上下文断裂。压缩本身也要花 token（要调用模型做摘要），所以我会算一笔账：如果压缩消耗的 token 比省下来的还多，那就不压，直接走丢弃策略。这个判断逻辑我写成了一个简单的成本函数，阈值可以根据你用的模型单价调整。
提示：记忆压缩的摘要模型不一定要用主模型，用一个小而快的模型做摘要，成本能降一个数量级，质量损失在编程场景里几乎感知不到。
3. 代码地图：让代理真正"看懂"项目结构而不是瞎猜
3.1 代码地图要解决的是"代理不知道文件在哪"
没有代码地图的代理，本质上是在盲人摸象。你问它"这个项目的路由是怎么注册的"，它只能靠猜，或者让你把相关文件一个个贴给它。代码地图要做的，就是提前把项目的结构信息索引好，让代理能像人一样"先看目录再定位文件"。
我做的代码地图包含三层信息：文件树与模块划分、符号索引（函数、类、变量的定义位置）、依赖关系图（谁 import 了谁）。这三层不是一次性全量构建的，而是分层按需构建。文件树很轻，启动时扫一遍就行；符号索引稍重，用语法解析器（tree-sitter 这类）跑一遍，只提取定义不提取实现；依赖关系图最重，但可以增量更新，只在你改动文件时重算受影响的部分。
这里的关键设计是增量索引。全量索引一个中型项目可能要几十秒，每次对话都跑一遍完全不现实。我的做法是记录每个文件的哈希，启动时对比哈希，只重新索引变化的文件，并且只更新依赖图里受影响的节点。实测下来，日常开发中增量索引基本在 1 秒以内完成，用户完全无感。
3.2 符号索引为什么比全文检索更靠谱
很多人第一反应是"我直接用 grep 或者全文检索不就行了"。全文检索的问题是噪音太大：你搜一个常见的函数名，可能命中几百处，其中大部分是调用而不是定义。代理需要的是"这个符号在哪定义、被谁引用"，这是结构化的信息，全文检索给不了。
符号索引的价值在于它能回答结构化问题：给定一个符号名，返回它的定义位置、类型、以及所有引用点。有了这个，代理在需要修改某个函数时，能先找到所有调用点，评估影响范围，再动手改。这个能力在重构场景里尤其重要——我实测过一个场景，让代理把一个工具函数的参数从位置参数改成对象参数，有符号索引的情况下它能一次性找出全部 14 个调用点并全部改对，没有索引的情况下它只改了 3 个就以为完事了。
构建符号索引时有个坑：不同语言的语法差异很大，用一套正则硬套会漏掉很多边界情况。我的建议是每种语言用对应的解析器，哪怕多引入几个依赖也值得。对于解析失败的文件（比如语法有问题的），降级到基于缩进和关键词的粗略提取，至少保证不阻塞整体索引。
3.3 依赖关系图怎么用才不鸡肋
依赖关系图如果只是画出来好看，那就是鸡肋。它真正的用处是影响面分析和上下文裁剪。影响面分析前面提过了，改一个模块前先看谁依赖它。上下文裁剪则是：当代理需要理解某个文件时，不是把这个文件孤立地塞进去，而是把它直接依赖的几个文件的关键部分也带上，这样代理能理解这个文件在整个项目里的位置。
但依赖图不能无限展开，否则一个核心工具文件可能牵连出半个项目。我的策略是只展开一层直接依赖，且只带被依赖方的接口部分（函数签名、导出声明），不带实现。这样既给了上下文，又不会让 token 爆炸。实测这个策略在"理解某个模块职责"这类任务上，比只给单个文件的效果好很多，token 增量却只有 30% 左右。
依赖图的另一个用途是检测循环依赖。编程代理在生成代码时，很容易不小心引入循环依赖，因为它只看局部。有了依赖图，代理在新增 import 前可以先查一下会不会形成环，从源头避免这类问题。这个检查我做成了一道轻量的前置校验，成本几乎为零，但省下的调试时间很可观。
4. 代理主循环与工具编排：九个仓库怎么粘在一起
4.1 主循环的设计哲学是"薄"
代理主循环这个仓库，我刻意做得非常薄。它的职责只有三件事：接收用户输入、决定下一步调用哪个工具、把工具结果拼回上下文。所有"聪明"的逻辑——记忆怎么召回、代码怎么索引、token 怎么算——全部下沉到各自的仓库里，主循环只通过统一接口调用它们。
为什么坚持做薄？因为主循环是最难测试、最容易出 bug 的部分。它一旦变厚，任何一个小改动都可能引发连锁反应。做薄之后，主循环的逻辑可以在一屏内看完，测试用例也好写。我给自己定的规矩是：主循环里不允许出现任何超过 20 行的函数，超了就说明这段逻辑该下沉了。
主循环和工具之间的协议我用的是最简单的 JSON schema 描述，每个工具声明自己的入参、出参和副作用。这样新增一个工具不需要改主循环，只要注册进去就行。这个设计让工具链的扩展成本极低——我后来加 token 记账、加调用追踪，都是新增工具或中间件，主循环一行没动。
4.2 工具编排里最容易翻车的是"工具结果太长"
工具调用编排有个隐蔽的坑：工具返回的结果可能非常长，比如读一个大文件、跑一次全量测试。如果直接把原始结果塞回上下文，一次调用就能把窗口撑爆。我的处理是工具结果分级截断 + 摘要：短结果原样返回；中等结果截断并附上"已截断，完整内容在 X"；长结果只返回摘要和关键片段，完整内容存到临时存储，代理需要时再按需读取。
这个策略的关键是"按需读取"要真的可用。我实现了一个read_more工具，代理看到截断提示后可以主动请求读取某一段。实测下来，代理在大多数情况下不需要读全文，摘要就够了；真正需要细节时它也知道去哪读。这比无脑塞全文省了大概 60% 的 token。
另一个坑是工具调用的并发与顺序。有些工具可以并发（比如同时读多个独立文件），有些必须串行（比如先写文件再跑测试）。我在工具声明里加了一个depends_on字段，编排器根据依赖关系自动决定并发还是串行。这个设计让代理在需要同时查多个文件时能快不少，实测并发读文件比串行快 3 到 4 倍。
4.3 九个仓库之间的接口契约怎么定
拆成九个仓库最大的挑战是接口契约。我的原则是接口只传数据，不传行为。也就是说，仓库之间通过纯数据结构通信，不互相传递函数或回调。这样做的好处是每个仓库都能独立测试，mock 起来非常简单。
具体来说，记忆层对外暴露的是"给定查询返回记忆条目列表"，代码地图暴露的是"给定符号返回定义和引用"，token 记账暴露的是"记录一次调用并返回累计用量"。这些接口都是纯函数式的，输入输出明确。主循环负责把这些数据组装成模型能理解的上下文。
版本管理上，我给每个仓库独立打 tag，但维护一个"兼容矩阵"文档，说明哪些版本组合是验证过的。这样用户想混搭不同版本时，至少知道哪些组合靠谱。这个矩阵我建议你也维护一份，多仓库项目最怕的就是版本地狱。
5. Token 记账：把"花得不明不白"变成一笔清账
5.1 为什么 token 记账必须独立成一个仓库
token 记账看起来是个小功能，但它牵扯的面很广：每次模型调用要记、每次工具调用如果内部也调模型也要记、记忆压缩要记、代码索引如果用模型也要记。如果把这些记账逻辑散落在各处，最后你根本对不上账。我把它独立出来，所有需要记账的地方都调同一个接口，保证口径一致。
记账的维度我设计了这几个：按会话（这次对话总共花了多少）、按阶段（记忆召回花了多少、代码索引花了多少、主推理花了多少）、按模型（不同模型单价不同，要分开算）、按工具（哪个工具最费 token）。有了这些维度，你才能回答"我的 token 到底花哪了"这个问题。
实测下来，最常见的浪费是记忆召回和代码索引。很多实现每次对话都重新召回、重新索引，其实大部分内容没变。我加了缓存和增量之后，这两块的 token 消耗降了大概 70%。如果你发现自己的代理 token 消耗异常高，先查这两块。
5.2 记账数据的采集点怎么埋才不漏
采集点埋得不对，账就是错的。我的经验是在模型调用的最底层埋点，而不是在每个业务逻辑里埋。也就是说，所有模型调用都走同一个封装函数，记账逻辑只在这一个函数里。这样无论上层怎么调，都不会漏记。
但这里有个细节：流式调用怎么记？流式返回的 token 数是逐步产生的，你得等流结束才能拿到准确数字。我的做法是流式过程中先记一个估算值，流结束后用准确值覆盖。估算值用字符数除以一个经验系数，误差在 10% 以内，足够做实时监控；准确值用于最终对账。
还有一个容易漏的点是失败调用。模型调用失败时，如果已经产生了部分 token（比如流到一半断了），这部分也是要计费的。我在异常处理里也加了记账，确保失败调用不被漏掉。这个细节很多人忽略，但对账时差的就是这些零头。
5.3 用记账数据反推优化方向
记账不只是为了看账单，更是为了优化。我给自己定了一个规矩：每周看一次记账报表，找出 token 消耗 top 3 的环节，然后问"这个环节能不能省"。
举几个真实的优化例子。有一次发现记忆召回的 token 占比高达 40%，查下来是召回条数设太多（默认 20 条），实际有用的往往就前 5 条。把默认值降到 8 条，召回 token 直接砍半，体验没变化。还有一次发现代码索引在每次对话启动时都全量跑，改成增量后这块从 15% 降到 3%。这些优化如果没有记账数据，根本无从下手。
注意：记账本身也有成本，别记太细。我一开始连每次工具调用的参数都记，结果记账数据比对话数据还大。后来只记关键维度，够用就行。
6. 全 MIT 开源背后的取舍与踩过的坑
6.1 为什么是 MIT 而不是更严格的协议
选 MIT 的理由很实际：工具链这种东西，用户最怕的就是"用了之后发现商用要授权"。MIT 几乎不设限，谁都能拿去用、改、卖，唯一的要求是保留版权声明。对我来说，这套工具链的价值在于被用起来、被改进，而不是靠授权赚钱。协议越宽松，愿意贡献的人越多，生态才转得起来。
当然 MIT 也有代价：别人可以拿去闭源改一改就当成自己的产品卖，你没有任何追索权。我接受这个代价，因为我相信工具链的竞争力在于持续迭代，而不是一锤子买卖。如果你做的是有明确商业壁垒的东西，那另说；但基础设施类的工具，宽松协议利大于弊。
6.2 拆仓库带来的真实麻烦
拆仓库不是没有代价的。最直接的麻烦是依赖管理变复杂。九个仓库之间有依赖关系，用户想全量安装时，得确保版本兼容。我的解法是提供一个"全家桶"元仓库，里面只放依赖声明，用户装这一个就把九个都装上了，版本兼容性由我保证。
第二个麻烦是文档分散。每个仓库有自己的 README，但用户需要的是"怎么把它们串起来用"。我在主仓库里维护了一份集成指南，讲清楚每个模块的职责和它们之间的数据流。这份指南比单个仓库的文档更重要，因为大多数人是从"我想搭一个完整代理"这个角度进来的。
第三个麻烦是issue 分散。用户不知道问题该提到哪个仓库。我的做法是在主仓库放一个"问题分诊"说明，列出常见问题对应的仓库。虽然不能完全避免提错地方，但至少降低了概率。
6.3 给想自己搭工具链的人几条实在建议
如果你也想搭一套类似的工具链，我的建议是先跑通最小闭环，再拆模块。不要一上来就设计九个仓库，那样你会花大量时间在接口设计上，而不是在解决实际问题上。先写一个能用的单文件代理，跑通"输入-推理-工具调用-输出"这个循环，然后再看哪块最痛，把最痛的那块先拆出去。
第二，接口设计要留冗余。我早期的一些接口设计得太"精确"，后来想加个字段就得改所有调用方。后来学乖了，接口里都留一个metadata字段，放一些非核心的扩展信息，加东西不用改签名。
第三，测试要跟着模块走。每个仓库有自己的测试，但模块间的集成测试同样重要。我吃过亏：单个模块测试全绿，集成起来就是跑不通，因为接口理解有偏差。后来我加了一层集成测试，专门测模块间的数据流，这类问题就少多了。
最后说个心态上的事：开源工具链是个长期活，别指望一发布就有人用。我前两个月基本没人 star，第三个月开始有人提 issue，第五个月才有人提 PR。真正让项目活起来的是那些愿意提 issue 和 PR 的人，所以对早期用户的问题一定要认真回，哪怕问题很基础。这套工具链能走到今天，靠的不是我一个人的代码，而是那些愿意试、愿意反馈的人。
