如果你正在给 AI 编程代理打地基，而不是天天调 prompt，你应该能秒懂我说的痛点：上下文一长，代理就开始选择性失忆，代码库稍微大一点它就像第一次进迷宫，月底一看 token 账单，消耗比云服务器还吓人。这套问题的本质是，光靠模型本身的能力不够，必须在外面补一层工程化设施。我最近把攒了大半年的方案整理成一组开源 AI 编程代理工具链，拆成 9 个仓库，全部 MIT 协议，核心就三块：记忆、代码地图、token 记账。
写这套工具链的初衷很简单，我自己在真实项目里被坑了太多次。一开始我也以为只要给代理塞一个足够大的 system prompt 就行，后来发现那是自欺欺人。模型上下文窗口再大，也有装不下的那一天；代码库的结构信息塞进去，既费 token 又不一定被正确理解。与其靠模型硬扛，不如把记忆、导航、计费这些脏活累活都做成独立的基础设施。这篇文章把我拆仓库的思路、每个核心模块的实现细节、跑真实任务时的数据流，以及我踩过的坑都整理出来，适合正在做 AI 编程代理、Agent 平台，或者单纯被 token 费用折磨的开发者参考。
1. 拆链思路：为什么 AI 编程代理需要三块独立基础设施
1.1 记忆：代理的“工作笔记本”不能只靠聊天记录
先聊记忆。很多人以为给 Agent 加记忆就是把历史对话拼起来塞进上下文，我一开始也这么干，结果发现两个致命问题：第一，对话记录越长，代理越容易抓不住重点，明明前面刚说过不允许用某个接口，后面它就忘了；第二，每次请求都重新传输全部历史，token 消耗呈线性上涨，任务跑到一半预算就没了。
后来我把记忆拆成一个独立基础设施，核心思路是分层：短期记忆保留最近几轮原始消息，用于保持对话连贯性；长期记忆把历史压缩成结构化摘要，提取任务目标、已做决定、已验证的事实、待办事项。代理每次启动任务时，不需要读全部历史，只需要加载与当前任务相关的记忆条目。这样既不丢关键信息，又能控制上下文体积。
这个记忆模块不只是一个 JSON 文件，而是一个有写入、读取、检索、合并能力的服务。写入发生在每轮交互之后，后台异步压缩；读取发生在代理开始新任务之前，按关联度拉取。我实际跑下来，同样的任务，加了记忆模块之后代理的重复操作次数明显下降，token 总消耗反而少了。
1.2 代码地图：让模型先看导航图，再进代码库
第二个痛点是代码库理解。大模型在大型代码库面前非常“脸盲”，你给它一个 20 万行的仓库，让它找到某个函数在哪个文件被调用，它往往靠猜。更尴尬的是，你把这些文件内容全部塞进上下文，能塞，但钱也烧完了，而且模型对文件之间的引用关系感知依然很弱。
所以代码地图的思路是：提前离线分析代码库，生成一个紧凑的索引，包含文件结构、符号定义、调用关系、依赖方向、变更历史。代理在动手之前，先通过代码地图服务查询与任务相关的子图，只把这一小块内容放进上下文。比如任务是“修一个登录超时的 bug”，就只加载登录模块附近的符号表和相关函数调用链，而不是整个仓库。
这相当于给代理配了一张厂房导航图。没有导航图它也能干活，但每走一步都要问一次路，还很爱撞墙。有了代码地图，至少它不会再把工具函数和业务函数搞混。后面第 3 节我会具体讲代码地图的数据格式和增量更新方案，那部分是我踩坑最多的。
1.3 token 记账：把大模型消耗当成云账单来管理
最后是 token 记账。这一块最容易被忽视，但往往是项目上线后第一个让人头疼的问题。代理不是只调一次模型，它会在一个任务里反复调用几十次甚至上百次，每一次调用你都要知道花了多少 token、是谁花的、花在哪个任务上。没有记账，你连优化都不知道从哪里优化。
我的 token 记账模块做了三件事：精确计量每个请求的输入输出 token，按任务维度聚合消耗，设置预算阈值触发预警或熔断。你可以把它理解成手机的流量监控，只不过监控的是模型消耗。实测下来，很多看似正常的任务重跑一遍，token 消耗能差 3 倍，问题就藏在某一步反复循环调用里。如果不记账，这种问题会一直背着。
这三个模块单独拎出来都不复杂，但组合在一起，就是 AI 编程代理能稳定落地的基础设施。下面我讲讲 9 个仓库具体怎么切分。
2. 九仓设计与协作边界：MIT 组合拳怎么打
2.1 九个工作仓各自负责什么
先说命名，我在仓库里用的是工作名，大家接手后完全可以按自己的规范重命名。九仓的职责切分遵循一个原则：每个仓库能独立换掉实现，而不影响其他仓。
我列了一张表，基本覆盖了 9 个仓库的划分：
| 仓库工作名 | 模块归属 | 主要职责 |
|---|---|---|
| repo-memory-core | 记忆 | 记忆模型定义、分层压缩逻辑、检索接口 |
| repo-memory-store | 记忆 | 记忆持久化实现，支持文件系统和 SQLite 后端 |
| repo-memory-service | 记忆 | 把记忆能力封装成 HTTP 服务，供代理远程调用 |
| repo-codemap-parser | 代码地图 | 对各语言源码做 AST 解析，提取符号与引用 |
| repo-codemap-index | 代码地图 | 构建符号表、函数调用图、文件依赖图 |
| repo-codemap-service | 代码地图 | 提供代码地图查询 API，输出任务相关子图 |
| repo-token-meter | token 记账 | token 计量、按模型口径换算、请求明细记录 |
| repo-token-budget | token 记账 | 任务预算管理、预警阈值、熔断控制 |
| repo-agent-toolkit | 集成层 | CLI 工具、配置加载、把前面八个仓串成一套链路的胶水 |
记忆三个仓、代码地图三个仓、token 记账两个仓，再加上一个集成层，正好九个。你可能会问，为什么不在一个大仓里一个包解决？我在最开始写的时候的确是一个巨大的仓库，后来发现每次改记忆逻辑都要把代码地图的依赖也重新 build，CI 跑一轮十分钟，同事想单独引 token-meter 还得连带下载一整套无关代码。拆开之后，每个仓库独立测试、独立发包，按需引用，体验完全不一样。
2.2 仓库间的数据协议与版本约定
仓库拆开了，通信协议必须统一，否则联调就是灾难。我规定所有仓库之间的交换格式一律是 JSON，不管是记忆条目、代码地图子图还是 token 账单明细，都用同一个带版本号的 schema。JSON 的缺点是性能一般、类型不严，但对于工具链这种低频高价值的调用场景完全够用，而且调试极其方便，出问题 curl 一下就能看到全貌。
版本约束用的是常规的语义化版本规则。比如 repo-codemap-service 依赖 repo-codemap-index 的导出格式，那么它们之间的 schema 版本必须保持兼容升级，破坏性改动一律通过新主版本表达。集成层 repo-agent-toolkit 在启动时会检查所有依赖仓库的版本，不一致会直接报警而不是静默降级。这些约定看起来繁琐，但多仓库项目翻车大多栽在“某个仓偷偷改了协议，另一个仓不知情”这种问题上。
2.3 为什么坚持全 MIT：少一点法律层面的劝退
协议选了 MIT，没有犹豫过。我见过一些很好的开源项目因为用了强 copyleft 协议，导致公司法务直接一票否决，明明工具很好用，却进不了生产环境。MIT 协议给使用方最低的决策成本：你可以直接引用，可以修改，甚至可以闭源二次开发，只要保留版权声明。
对我自己来说，MIT 也符合这套工具链的定位：基础设施类代码，越多人无痛接入越好。如果有人基于它做了商业产品，我也不觉得亏，反而希望它能成为一块公共地基。第 4 节我会讲这套工具链怎么落地，但现在如果你想先跑起来，建议先看集成层的 CLI，它的配置范本基本涵盖了三类模块的接入方式。
3. 核心实现细节：记忆、代码地图与 token 记账的关键设计
3.1 记忆模块：分层压缩与检索
记忆模块的实现，核心是回答三个问题：什么时候压缩、压缩成什么样、怎么检索。
我在 repo-memory-core 里定义了一个记忆对象模型，分三层。原始消息层保存最近五轮以内的完整对话，这是短期记忆，保证上下文连贯；摘要层保存每条重要事件的压缩描述，比如“用户要求所有外呼接口必须加超时熔断”；结构化记忆层保存实体关系，比如“服务 X 依赖数据库 Y”“任务 Z 已完成”。压缩时机不是定时，而是触发式：当原始消息条数超过 20 条，或者单轮累计 token 超过预设阈值，就触发一次摘要合并。跑批处理时，摘要质量和原文成正比，所以不能压缩太频繁，我压成每 30 分钟最多合并一次。
检索我用的是两个通道的混合：关键词过滤加简单相关度排序。没有上外部向量库，因为记忆条目大多是短文本，用倒排索引足够快。代理发起任务时，集成层会拉取当前任务相关的实体和最近的摘要，拼进系统提示里。这一步有个细节：只拉与任务标签匹配的记忆，不要贪多。我刚开始试过把所有摘要都带上，结果代理被历史信息干扰，反而搞不清当前目标。
3.2 代码地图模块：AST、符号表与增量更新
代码地图的难点不是 AST 解析本身，而是解析完之后的数据怎么组织，以及怎么保持更新。repo-codemap-parser 负责把源码解析成符号表，支持主流的几种常见语言。解析结果会落到 repo-codemap-index，生成文件依赖图和函数调用图。每一层都加了版本号，避免代理拿到过期地图。
我用一个简化格式描述符号：文件路径、符号名、类型（函数/类/变量）、入参简述、被哪些文件引用、调用了哪些符号。对这些信息做子图抽取时，不是简单把整个文件塞给代理，而是以任务涉及的核心符号为起点，沿调用链往外扩两层，再附上文件头部注释。实测下来，这个“两层调用链”的规模对大多数模型来说是刚好能理解的大小，且 token 消耗可控。
增量更新是踩坑重灾区。一开始我设计成全量定时重建，结果一个中型仓库解析要跑好几分钟，任务早做完了地图还没更新。后来改成监听 Git 提交，每次提交只重算变更文件及其直接依赖文件，其他沿用缓存。这个逻辑写起来不算复杂，但收益巨大，地图更新从分钟级降到秒级。在 repo-codemap-service 里我还加了一个 staleness 字段，表明地图最后重建时间，代理请求子图时如果发现地图过期超过一定时限，可以选择拒绝使用并触发重建。
3.3 token 记账模块：精确计量、预算控制与账单存储
token 记账看起来是最简单的模块，但恰恰是最容易出错的地方。首要是计量口径。不同模型可能有不同的 token 计算方法，不能用一个通用字符数估算。repo-token-meter 的做法是内置一个 tokenizer 适配层，按模型类型选择对应的编码方式，并在配置里写明输入和输出的计费倍率。请求进来之后，先按模型实例化 tokenizer，算出 prompt token 和 completion token，再把明细写入账单存储。
预算控制部分在 repo-token-budget。每个任务可以设置一个预算上限，例如 100k token。在任务执行过程中，每次调用模型之前，记账模块会检查当前任务累计消耗加上预估本次消耗是否超过阈值，超过就返回一个预算熔断信号，代理可以选择暂停、缩小任务范围或者申请加预算。我实际使用中还会设置软预警值，比如 80% 预算时在日志里打点，这个预警在任务收尾阶段特别有用，能避免最后一步生成报告时把预算烧穿。
账单存储我用的是 SQLite，按天分表，保留 90 天。每条记录包含时间戳、任务 ID、调用方、模型、输入 token、输出 token、费用估算。这个明细不仅是记账用的，更是优化 prompt 的依据。你只要查一下哪一步调用产生了超长输出，就能精准定位到代码里的问题。
4. 实操记录：用这套工具链跑通一个真实的修 bug 任务
4.1 初始化与最小配置
纸上谈兵没有意思，我拿一个模拟项目 X 实际跑了一遍。这个项目是一个大概 3 万行的后端服务，技术栈就是常见的 Web 框架加关系数据库。第一步是初始化集成层，在项目根目录建一个配置文件，指定代码地图仓库地址、记忆服务地址、预算默认值。
配置示例大致长这样：
{ "task": "fix-login-timeout", "memory": { "service_url": "http://localhost:7801" }, "codemap": { "service_url": "http://localhost:7802", "max_depth": 2 }, "token": { "meter_url": "http://localhost:7803", "task_budget": 120000, "warn_at": 0.8 } }由于九个仓库都是独立的，我可以用一套统一的安装脚本把它们分别启动。启动之后，repo-codemap-service 会在后台对模拟项目 X 做一次全量索引，等它输出地图已就绪的信号，就可以开始跑任务了。
4.2 执行任务时的数据流
模拟任务是这样：代理需要修复登录超时 bug。没有工具链时，代理会用自己的通用知识猜原因，定位到几十个相关文件，反复读取，token 消耗爆表。接入工具链后，数据流变成了三条线并行。
第一条线是记忆线：代理向记忆服务查询“登录”“超时”“最近改动”相关条目，拿到几个关键实体关系。第二条线是代码地图线：代理把“登录”“session”“timeout”作为起点符号，向代码地图服务请求调用链子图。返回结果大概是登录接口文件、超时配置项、session 管理类以及它们之间的引用关系，总共 30 多个符号，压缩成 JSON 后只有几千 token。第三条线是预算线：代理每一次请求模型前，token-meter 先记录并检查预算。
实际跑完后，我对比了无工具链和有工具链的表现。无工具链时代理花了 15 轮调用，试错次数多，总消耗接近 40 万 token；有工具链时代理在第 6 轮就给出一个可用补丁，总消耗不到 10 万 token。成功率也直观改善，因为代码地图里已经标明了哪些文件是有效的修改点，代理不太会在无关代码里乱翻。
4.3 成本与效率对照
我整理了一张模拟测试数据表，数据来自我自己的环境，不同任务可能波动很大，但总体趋势是一致的：
| 任务 | 无工具链 token 消耗 | 有工具链 token 消耗 | 任务完成轮数 | 是否一次通过 |
|---|---|---|---|---|
| 修复登录超时 | 约 400k | 约 90k | 15 | 否 |
| 新增分页接口 | 约 350k | 约 120k | 18 | 是 |
| 重构配置读取模块 | 约 600k | 约 200k | 22 | 否 |
我当然不会告诉你装了工具链就能保证一次通过，那是瞎话，但有一点很明确：工具链把上下文中真正有价值的信息筛选了出来，代理的大部分 token 都花在推理而不是搜资料上。这就是我认为这套链路的真正价值。
5. 常见问题与避坑指南
5.1 记忆压缩过度，代理反而“失忆”
我第一次调记忆压缩时把阈值设得很低，希望节省 token，结果代理经常忘记用户明确提出的格式要求，因为那些要求被压缩得太抽象了。后来我发现，压缩摘要不能只保留“结果”，至少要保留一小段原文示例。比如用户要求“错误提示必须返回 JSON 格式，不要纯文本”，压缩后不能只写“用户要求 JSON”，要附上一两句示例文本。这条经验救了我很多次。
注意：记忆压缩触发条件要保守一点，宁可多存几轮原始消息，也不要过早把所有内容揉成摘要。摘要的丢失是不可逆的。
5.2 代码地图不更新，索引比没有更危险
代码地图最大的坑是“过期地图”。如果代理拿着旧地图去改新代码，轻则找不到符号，重则把已经删掉的模块当依赖引进来，产出的代码直接编译不过。我后来强制要求地图服务每次返回子图时带一个时间戳，代理在启动任务前会对比仓库最新提交时间，超过一小时就拒绝使用地图并发起重建。这个机制能保证你不在烂地基上盖房。
另外，增量更新虽然快，但跨分支场景还是要小心。举个例子，一个分支删除了某个文件，另一个分支还在用，简单的事件监听可能会漏掉这种交叉影响。我的方案是每天凌晨做一次全量重建作为兜底，增量更新保证实时性，全量重建保证一致性。
5.3 token 记账越算越不准？注意模型口径差异
token 记账的精度问题，我踩过一个大坑。早期我用字符数估算，结果和账单差了 20% 以上。后来换成了按模型适配的 tokenizer，和官方计费口径一致了，误差降到很低。但即便如此，同一个请求在不同时间点可能因为系统 prompt 变化导致 token 数波动，所以记账模块不能只记一次最终数，而要在每轮请求时都记录。
如果你在记账里发现某次任务消耗异常高，先判断是不是模型上下文缓存失效。比如代理反复读同一个大文件，如果没有缓存，每次都按全量文件计算 prompt，消耗自然爆炸。代码地图的“子图只拉相关部分”策略其实就是变相在做上下文降本，这也是我强烈建议先接 token-meter 和 codemap-service 两个仓的原因。
5.4 九仓联调的版本漂移问题
多仓库的另一个痛点是版本漂移。我遇到过 repo-memory-core 升级了记忆条目格式，但 repo-memory-service 还在用旧格式，结果代理读出来的记忆字段全部为空。这个问题靠人盯不现实，必须在集成层里加一个版本一致性检查：启动时读取每个仓库导出的 schema 版本，对比集成层 lock 文件里记录的版本清单，不一致立刻终止并提示。
从此之后，每次升级某个仓库，我会同时跑一遍集成层的端到端测试，确保九个仓库之间的契约没有断裂。虽然这样稍微增加了发布成本，但省去了很多联调排错的深夜时间。
6. 后续扩展方向
工具链目前只覆盖我项目里的核心需求，但结构上预留了扩展空间。记忆方面，下一步可以接更强的语义检索，让代理能够跨任务复用经验；代码地图方面，准备增加更多语言支持，并和一些主流的代码托管平台做对接；token 记账方面，打算把多模型、多提供方的换算规则做成可插拔配置，让团队可以统一看到混合模型成本。
如果你只是想先从这套工具链里捞一点好处，我个人建议先接 repo-token-meter 和 repo-codemap-service 这两个仓。前者能立刻帮你止血，看清钱花在哪；后者能显著提升代理的准确率。记忆模块反而是越往后越能体会到价值，它属于锦上添花，但代码地图和记账属于雪中送炭。这套工具链我一个人维护，完全开源，全部 MIT，github 上直接就能跑。后续有什么新坑，我再补成新的仓库。
