如果你正在给 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-metertoken 记账token 计量、按模型口径换算、请求明细记录repo-token-budgettoken 记账任务预算管理、预警阈值、熔断控制repo-agent-toolkit集成层CLI 工具、配置加载、把前面八个仓串成一套链路的胶水记忆三个仓、代码地图三个仓、token 记账两个仓再加上一个集成层正好九个。你可能会问为什么不在一个大仓里一个包解决我在最开始写的时候的确是一个巨大的仓库后来发现每次改记忆逻辑都要把代码地图的依赖也重新 buildCI 跑一轮十分钟同事想单独引 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约 90k15否新增分页接口约 350k约 120k18是重构配置读取模块约 600k约 200k22否我当然不会告诉你装了工具链就能保证一次通过那是瞎话但有一点很明确工具链把上下文中真正有价值的信息筛选了出来代理的大部分 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 这两个仓。前者能立刻帮你止血看清钱花在哪后者能显著提升代理的准确率。记忆模块反而是越往后越能体会到价值它属于锦上添花但代码地图和记账属于雪中送炭。这套工具链我一个人维护完全开源全部 MITgithub 上直接就能跑。后续有什么新坑我再补成新的仓库。
