AI编程代理工程化：记忆、代码地图与Token记账开源工具链实践

先说一下背景。我过去半年一直在折腾 AI 编程代理这件事，说白了就是让大模型不只是聊天，而是能真正钻进代码仓库里，自己定位问题、改代码、跑测试、然后接着修。听起来很美好，实际跑起来会发现三个绕不开的坎儿：一是代理干着干着就“失忆”，上下文窗口一挤，前面分析过的结论全忘了；二是整个代码仓库几百个文件，代理根本不知道该看哪里，只能反复把无关代码拉进上下文；三是 token 烧得飞快，改一个小功能可能比雇人还贵，但又说不清楚钱到底花在哪了。

后来我干脆自己攒了一套工具链，拆成了 9 个仓库，全部 MIT 协议开源，覆盖了记忆、代码地图、token 记账这几个核心场景。这篇文章就把这套工具链的整体设计、每个仓库的定位、以及我在实际使用中踩过的坑完整复盘一遍，给也在折腾 AI 编程代理的同学一个可以直接照搬的思路。

1. 为什么攒出这套工具链

1.1 AI 编程代理的现状与卡点

先说清楚 AI 编程代理是指什么。不是那种 IDE 里的补全插件，而是一个能够自主完成编码任务的程序：你给它一个 issue 描述，它自己读代码、定位相关模块、写补丁、跑测试，然后根据失败结果继续迭代修。听起来很接近“AI 程序员”了，但现阶段跑真实项目的时候，问题非常集中。

第一个问题是上下文失控。以常见的 200k token 上下文窗口为例，中大型项目里核心代码加上依赖关系随便就能吃掉一半，再塞几个测试输出、错误栈，留给推理的空间就很有限了。更要命的是代理在输出长 token 序列的时候，前面的决策理由很容易被挤出去，哪怕截图里刚才已经确定了“问题出在某个模块的缓存逻辑”，过了一会儿它又绕回去翻别的文件。

第二个问题是代码库理解浅。直接把整个仓库丢给模型，模型也能“看懂”一部分，但非常盲目。它不知道这个项目的入口在哪、哪些模块是核心域、哪些是边缘代码，不知道一个函数被哪些上层模块调用，一旦改了影响范围多大。结果就是代理经常在无关文件里浪费大量调用，或者改了一个私有函数，然后整个测试套件崩了。这不是模型能力的问题，而是缺少“导航”信息。

第三个问题是 token 开销不可控。我见过最夸张的一次，代理只是给某个后端服务加一个字段校验，结果烧掉了大几十万 token，大多数都花在重复读取同一个大文件、反复分析同一段报错上。事后一查账单，根本不知道是哪个环节出了问题。没有计量就没有优化，这是我攒工具链的直接导火索。

1.2 工具链的设计原则：记忆、地图、记账三大支柱

既然问题集中在上面三点，我的方案就围绕三个支柱展开。

记忆模块负责跨会话持久化。代理每次运行之前，先把之前沉淀下来的项目事实、用户偏好、历史决策再读进来，而不是每次从零开始摸索。代码地图模块负责给仓库建索引。代理接到任务后，先查地图知道去哪儿读代码，而不是漫无目的地遍历。token 记账模块负责全链路计量。每次调用都记录模型、token 数量、费用、用途，让你清楚看到成本到底消耗在哪个环节。

除了三大支柱，我还做了几个辅助仓库：任务编排、上下文压缩、测试生成、缓存、统一配置。这样整套工具链才能串成一个完整的工作流。当时也犹豫过要不要全都塞进一个大仓库里，最后决定拆成 9 个独立仓库，核心原因有三个：一是每个模块的迭代节奏不一样，比如 token 记账接口经常变，但代码地图的生成策略相对稳定，拆开可以独立发版；二是使用者可以按需取用，不一定全家桶全上；三是权限边界更清晰，比如 map 生成只需要读代码，memory 需要读写存储，拆开之后每个模块的职责一目了然。

许可证最终全选了 MIT，没别的原因，就是希望降低采用门槛。我自己也被各种 LICENSE 卡过，MIT 是收得最少的。代理工具这种面向开发者的项目，信任是最稀缺的资源，License 宽松一点，大家才敢往自己的核心流程里嵌入。

2. 九个仓库是怎么分工的

2.1 仓库全景与定位

先看一张总览表，把这 9 个仓库的定位捋一遍。为了避免歧义，下面用的都是功能描述形式的代称，没有使用特定的产品名。

你可能注意到了，记忆、代码地图、token 记账这三块是重头戏，其他仓库是围绕它们的配套。task-orchestrator 负责把这些能力串起来：代理执行任务时，先向 memory-core 要历史决策，向 code-map-service 要文件定位，再向 token-meter 报告每一步的消耗，整套流程像一个流水线。

2.2 仓库拆分与协作工作流

拆成 9 个仓库有一个附带的好处：每个仓库的复杂度都不高，单独看代码很容易读懂。任何一个新加入的开发者，想给 token-meter 加一个模型计价逻辑，只需要理解代理调用拦截这一个小点，不需要先搞懂记忆存储的向量索引是怎么做的。

协作流程上，我设计的是事件驱动。每个仓库只对外暴露能力接口，内部实现完全隔离。比如 memory-core 只负责存取记忆，不关心是谁在调用、agent 正在执行什么任务。一次典型任务的调用链通常长这样：

1. task-orchestrator 拿到 issue 描述后，先调 memory-core 查询相关历史决策。
2. agent 调 code-map-service 拿到涉及文件的入口、依赖关系。
3. agent 通过 repo-ragger 对某个具体模块进行自然语言问答，定位问题核心。
4. 每次调用 LLM 时，代理拦截层会把 token 用量发给 token-meter。
5. 生成补丁后，test-factory 自动补充测试用例。
6. 最终结果异步回写 memory-core，成为下一次任务的历史上下文。

这套流程跑起来之后，最明显的变化是代理不再“东翻西找”。给它一个任务，它先看地图、再看记忆、然后精准地读目标文件。token 消费从几万降到几千，成功率反而上去了。

3. 核心模块设计与实操要点

3.1 记忆模块：不只是存对话记录

记忆模块很容易被误解成“把聊天记录存下来”，但真正的项目记忆要复杂得多。我设计成三类数据：

项目事实：比如“服务 A 依赖 Redis 存储 session”“某模块的接口参数做了签名校验”“测试环境需要特定的 mock 配置”。这类事实是稳定的，不会频繁变化。

决策记录：比如“之前因为并发问题选择了消息队列方案”“放弃了对某个第三方库的直接依赖”。这类记录最有价值，因为代理经常重复踩坑，历史决策能直接避免重蹈覆辙。

任务历史：每次完成的任务描述、改动的文件列表、验证结果。这类数据帮助代理理解“当前任务和之前的任务有什么关联”。

实操中，我把记忆条目设计成带元数据的结构：来源、时间戳、置信度、状态。来源标明是来自用户反馈、代码分析还是历史任务；置信度用来控制检索排序。比如用户手动确认的信息置信度最高，代码自动推导的次之，推测性结论最低。如果后面发现一条事实和新的代码状态冲突，就把旧条目标记为过期，而不是直接删除——保留历史轨迹也是记忆的一部分。

记忆的检索我用的是混合策略。关键词匹配负责精确命中的场景，比如“查某个配置项在哪个文件里”；向量语义检索则负责模糊查询，比如“之前有没有处理过类似的内存泄漏问题”。全部命中后按置信度和时间衰减排序。这里有一个非常隐蔽的坑：记忆过期。项目代码天天变，一个月前的事实可能早就失效了。所以我在写入记忆时强制要求带业务版本号，检索的时候会把版本号差异作为排序惩罚项，版本差得越多，排名越靠后。

3.2 代码地图模块：让代理知道该看哪里

代码地图的核心思路是：不把整个仓库塞给模型，只给模型一张“导航图”。具体分成三层：

结构层：模块列表、每个模块的职责描述、入口文件、对外暴露的接口。相当于代码库的“目录”。

依赖层：模块之间的依赖关系、调用关系。比如“服务 B 调用了服务 A 的某个接口”“工具模块被 15 个文件引用”。这张依赖图能让代理评估改动的影响范围。

索引层：文件名到语义描述的倒排索引。代理看到一个堆栈信息时，能快速定位到具体文件、具体函数。

生成方式是 AST 静态分析加启发式摘要。代码地图服务遍历仓库，解析每个文件的抽象语法树，提取函数、类、导入关系，然后按模块聚合生成摘要。这里面最耗时的部分是“模块职责描述”：直接让 LLM 读整个模块生成摘要，成本太高；我的做法是先生成每个文件的骨架信息，再让模型读骨架摘要来概括模块含义。骨架摘要很小，几百 token 就能描述一个文件，整个模块也就一两千 token，整体开销可接受。

实操中有一个关键取舍：代码地图必须增量更新，不能每次全量重建。我一开始是每次任务启动时重新生成地图，但仓库大一点就要几分钟，体验很差。后来改成监听文件变动事件，文件保存后只更新受影响模块的地图条目。这里踩过一个坑：文件重命名会导致地图里的调用关系大面积失效，光是文件路径变化还不够，需要检测文件内符号的变更，对引用该符号的地图条目做级联刷新。代码地图生成不是“一锤子买卖”，是需要持续维护的活。

3.3 token 记账模块：把成本可视化

token 记账这个仓库看起来不起眼，但我觉得它是整套工具链里让 AI 编程代理走向工程化的关键。没有计量就没有优化。

设计上我做成一个代理拦截层。所有进出 LLM 的请求都经过它，记录请求模型、输入 token 数、输出 token 数、响应耗时、任务 ID、项目 ID。每次调用完成后，异步写入本地存储或数据库，不阻塞主流程。

成本计算这块需要按模型的官方计费规则来算。每家厂商的计价单位不同，有的按 1K tokens，有的按 1M tokens，输入和输出价格也不一样。我在 config-center 里维护一张模型单价表，格式大致是这样：

然后一次调用的成本就是：输入 token 数 × 输入单价 + 输出 token 数 × 输出单价，再把结果除以 1M 换算成实际金额。比如一次请求消耗了 50K 输入 tokens 和 2K 输出 tokens，用模型 A 计算就是：(50000 × 3.50 + 2000 × 15.00) / 1000000 = 0.205 元。单次看数字不大，但一个完整任务有成百上千次调用，累加起来就很可观了。

token-meter 还带一个预算熔断功能。可以给每个任务设定 token 上限，一旦累计消耗超过阈值，orchstrator 就会暂停任务，先回报给用户确认。这个功能极其有用，能避免代理在错误方向上死循环烧钱。我见过代理反复读同一个文件、反复试同一个错误方案，如果没有熔断，一次跑十几万 token 完全不奇怪。

3.4 辅助模块：编排、压缩、缓存、测试

task-orchestrator 做的事情很简单：把一个大任务拆成可验证的小步骤。比如“给某模块加日志”可以拆成“定位日志配置→找到注入点→生成补丁→跑测试→检查输出”。每个步骤有明确的输入输出和验证条件，代理执行完一步再进入下一步。这种编排方式比直接丢一个大任务给模型稳定得多，特别是复杂任务。

context-compressor 负责在代理运行过程中压缩历史对话和代码片段。它不是简单粗暴地截断，而是按重要性分层：核心决策保留全文，中间推理过程压缩成一两句摘要，代码片段只保留修改过的部分。这个模块上线后，长任务的 token 消耗下降了大约三成，同时任务的完成率反而有所提升。

cache-layer 做请求级缓存。比如代理反复查询“某个配置项的默认值”，第一次查完后缓存，第二次直接命中，不用再走一次 LLM 调用。我实现了语义去重，两段意思相同但表述不同的查询也能命中同一条缓存。这个模块带来的节省最直观，我测过一些重复性任务，token 消耗能降一半。

test-factory 不必多说，就是在代理生成补丁之后，自动分析改动涉及的分支路径，补几个针对性测试用例。它的意义在于，没有测试的情况下，代理改完代码无法判断好坏，只能靠运气。补了测试之后，代理本身就能拿到反馈信号，进行下一轮修复。

4. 实操过程：搭一套最小可用链路

4.1 从零开始的五个步骤

搭这套工具链其实不需要从源代码开始编译，我打包成了可执行文件和镜像，按下面的步骤初始化就行：

第一步，初始化 config-center。本质上是一个配置文件目录，合并默认配置和本地覆盖。核心是设置各项密钥、模型列表、以及模型单价表。环境变量负责放入敏感信息，配置文件只放非敏感配置。

第二步，启动 memory-core 存储端。先建索引目录，然后写入种子记忆。种子记忆不一定要很多，把项目的基本架构、核心目录职责、以及已知的坑先写进去。你会看到后续代理的表现明显比“空机”状态好。

第三步，生成代码地图。在项目根目录执行 code-map-service 的扫描命令，生成初始的仓库摘要。对中大型项目，建议先指定模块范围，不要一上来全量扫描。扫描完成后检查一下模块摘要质量，如果某个关键模块的描述太模糊，需要手工修正一下地图条目，地图质量直接影响代理的定位精度。

第四步，接入 token-meter。在代理的请求入口处挂上拦截中间件，配置好模型单价表，然后把任务 ID 传给记账接口。这一步只需要很少的代码改动，就能获得全链路的成本视图。核心理念是先有数据，再谈优化。

第五步，编写一个最小工作流。让 task-orchestrator 按“读记忆→查地图→执行小步骤→验证→写回记忆”的节奏运行。你可以从一个简单 issue 开始，比如“给某个函数加上输入参数校验”，跑通后再逐渐增加复杂度。

4.2 一个完整任务的运行实录

我拿一个模拟项目来演示：一个内部工具服务，最近总有用户反馈某个接口返回了空数据，但日志里没有报错。

代理接到这个 issue 后，先调 memory-core 查询历史记录。检索结果发现三个月前有一段“该接口的查询条件在特定边界下会拼接出非法 SQL”的决策记录，当时修复过一次。代理接着调 code-map-service 拿到该接口涉及的模块依赖关系：Controller 层调用 Service 层，Service 层依赖一个查询构建器。再到 repo-ragger 里问“这个查询构建器的边界条件怎么处理的”，得到了一段代码定位。

到这里，代理其实只花了几千 token，没有像以前那样整个仓库翻。它直接读到核心代码，发现非法 SQL 是因为某两个日期参数都为空时生成了错误的条件子句。修复补丁生成后，test-factory 自动补了一个“两个日期都不传”的测试用例，跑了通过。最后任务结果和决策过程都写回 memory-core，下次遇到类似问题，代理可以直接查到这个修复方案。

整个流程里，token-meter 记录下来的总消耗，比之前盲目方式少了接近一半，而且全程可追溯。这就是工具链串联起来的效果。

5. 常见问题与排查技巧实录

5.1 问题速查表

我把实际运行中遇到频率最高的几个问题整理成一个速查表，方便你按图索骥。

5.2 几个需要特别注意的坑

记忆别过度信任。记忆模块启动初期，自动从代码里推导出来的事实错误率不低，需要人工审核或者通过多轮使用验证。我在 memory-core 里加了用户反馈按钮，命中后允许一键“纠正”，之后同类查询会优先采用修正后的版本。这个机制跑了一段时间，记忆的准确率明显上来了。

代码地图别一次全量生成。仓库超过一定规模后，全量扫描的耗时会指数级增加。我现在的策略是只对高频修改路径建深度的地图，边缘模块维持浅层摘要，需要时再扩展。地图是“用进废退”的，哪个模块频繁被修改，就给它建立更细粒度的索引。

token 记账要异步但不丢数据。一开始我用同步写库，结果代理调用一密集，整个流程就被 IO 拖慢了。后来改成异步队列，但又遇到了进程退出时最后一小批数据没刷到磁盘的问题。最终方案是本地先写 WAL（预写日志），再异步批量刷库，保证不丢。这个事看起来不大，但如果你真的想分析长期成本趋势，数据完整性就是命根子。

别让代理自己改工具链配置。这是我踩过最深的一个坑。代理在执行编码任务时，假如代码里刚好涉及 config-center 的配置文件，它可能会顺手“优化”配置，导致整个工具链的行为变化。建议在 config-center 里加一个保护模式，代理只能读不能写，所有修改走人工 review。

6. 使用心得与后续扩展方向

整套工具链跑了大半年，我最深的感受是：AI 编程代理要真正工程化，缺的不是更聪明的模型，而是配套的基础设施。记忆、代码地图、token 记账这三块，相当于给代理配了笔记本、地图和账本。模型本身还是那个模型，但使用效率天差地别。

单独拆成 9 个仓库，也让我体会到小仓库的好处。每个仓库都可以独立测试、独立发布，改动一个模块不会影响其它模块。对我个人来说，维护一个上千行的大仓库和维护十个几百行的小仓库，后者轻松得多，也更容易吸引协作者。MIT 协议带来的正反馈也超出预期，有几个使用者提了不错的 PR，尤其是 cache-layer 的去重优化和 memory-core 的过期判定策略，比我原来的实现明显更好。

后续的扩展方向我列了几个，供你参考。一是支持多模态记忆，把图表、流程图、界面截图也纳入记忆体系，这对前端项目的帮助很大。二是团队共享记忆，把当前“单机版”的记忆存储改造为服务端版本，支持多人协作时共享项目知识。三是成本优化策略自动推荐，基于 token-meter 积累的数据，自动提出“这个环节换更小的模型更划算”之类的建议。四是代码地图的时间维度，记录模块结构的历史演变，让代理能回答“这个模块的架构是哪个版本改成现在这样的”这类问题。

最后再分享一个个人体会。让代理在引入新工具链时，别追求一步到位。先只接上 token-meter，把成本看清；再加代码地图，把定位效率提上去；最后才是记忆模块。每一步都能独立看到效果，出了问题也容易回退。这套渐进式落地的方式，降低了风险，也让整个工具链的收益路径清晰可量化——有时候不加量的优化比推倒重来有用得多。