把同一段需求讲给三个不同的 AI 编程助手听它们通常都能给出像模像样的方案但让同一个助手连着干三周活儿它十有八九会忘掉第二周自己刚定下的接口约束然后在第三周又写出一份风格互相打架的代码。这个现象我观察了很久最后想明白了一件事我们一直在给 AI 换更好的大脑却很少有人认真给它配记忆、地图和账本。所以我做了一套 AI 编程代理工具链拆成 9 个 MIT 协议的仓库把长期记忆、代码结构认知、token 消耗记账三件事分开解决每个仓库可以独立接入也能组合成完整流水线。下面我会把九个仓库的定位逐个拆开讲清楚说明背后的设计取舍最后交代我在真实项目里验证过的接入顺序和踩坑记录。无论你是在折腾自己的 AI 编程工作流还是单纯对给代理做外围基建感兴趣应该都能找到可以直接照抄的部分。1. AI 编程代理真正缺的不是更强的模型1.1 三个几乎每个团队都会撞上的痛点先说失忆。代理的能力虽然在快速变强但它的工作记忆基本上被上下文窗口的大小框死了。窗口再大也装不下几个星期的开发过程更不用说跨项目、跨会话的长期积累。会话一结束代理就回到什么都不知道的状态。上周五刚和它讨论清楚的支付模块统一走内部接口不允许业务层直连第三方 SDK这周一再开新会话它大概率完全不记得。这意味着AI 编程代理的实际产出质量很大程度上取决于人工反复喂背景信息的耐心。第二个痛点是代理对仓库结构脸盲。一个上万文件的中型仓库对代理来说就是个迷宫。它惯常的做法是先 grep 关键词再逐个打开文件读取靠多轮搜索拼凑对系统的理解。这个过程中大量上下文被浪费在探索而不是生成上。更麻烦的是它可能根本找不到那些没有关键词命中的关键文件于是给出一个看似合理、实际一跑就错的方案。第三个痛点是成本黑盒。跑一次跨多个文件的重构动辄消耗大量 token但具体烧在哪一步、摊到哪个项目、哪个会话头上基本是一笔糊涂账。个人开发者还能忍一忍团队一旦多人共用一套代理月底收到一张看不懂的账单就会开始怀疑AI 编程到底是在省钱还是烧钱。1.2 这三个问题为什么要分开治而不是揉成一团我一开始也想做一个单体仓库把所有能力塞进去一股脑提供给使用者。后来放弃了因为不同团队对这三件事的需求节奏完全不一样有人被成本折磨最急的是把账记清楚有人觉得代理老是忘事最需要的是记忆也有人项目规模大到代理已经读不完代码先要一份能持续更新的地图。把三者捆在一起等于强迫所有人一起等最慢的那块功能。所以在设计上我定了一条硬规矩仓库之间不互相依赖具体实现只依赖一套公共的数据结构定义。每个模块可以独立升级、独立使用。整套工具的定位是旁路组件——它不侵入代理的内部逻辑而是通过标准的输入输出接口插到代理工作流的外围。代理还是那个代理只是多了记忆、地图和账本三样东西。1.3 这套东西到底适合谁如果你平时只用一个编码助手做点小修小改偶尔写个脚本那这套工具链大概率是过度设计。但如果你像我一样把编码助手当日常主力每天让它处理跨多文件的重构、调试、写测试、改历史代码并且已经开始为它怎么又忘了或者这个月 token 怎么又超了而头疼那这套工具链就是给你准备的。我后面写的所有参数、配置和踩坑记录都是从这类高强度使用场景里折腾出来的不是纸上谈兵。2. 记忆仓库代理的长期记忆核心是决策记录而不是聊天记录2.1 为什么全量存聊天记录是错的我最早的想法很简单把代理的会话历史全部落库需要的时候原样翻出来再喂回去。做了个 demo 之后立刻发现这条路走不通。全量历史的信息密度太低里面有大量寒暄、试错、无效推测、重复提问把它一股脑塞回上下文等于花大价钱买了一堆噪音还挤占了真正有用的指令空间。真正值得长期保留的是结果性信息目标是什么、最终决定了什么、被明确否定了什么、现在还卡在哪里。这跟写代码注释是同一个道理有价值的注释永远在解释为什么而不是复述做了什么。所以我把记忆最终定义为一条条结构化记录每条记录有类型、作用域、状态和优先级而不是一整坨对话文本。2.2 记忆记录的字段设计与写入时机一条记忆记录的核心形式大概是这样的{ type: decision, project: sim-demo, agent_id: agent-01, session_id: s-1024, ts: 2025-06-12T10:24:00Z, scope: payment, priority: 5, status: active, content: 支付模块统一走 payment-core 接口禁止业务层直接调用第三方 SDK }type 目前支持五种goal目标、decision决定、constraint约束、progress进展、lesson教训。scope 标记作用域比如某个模块、某个目录、某个具体文件priority 是摘要淘汰时用的分数status 允许把过期的决定标记为 superseded避免代理继续执行一条已经被推翻的旧约束。写入时机比字段格式更重要。我总结了三个必须写入的时机代理给出结论性表述的时候用户纠正、驳回、修改代理方案的时候一个子任务完成、代码被正式提交的时候。工具链在每个时机提供钩子代理通过工具调用写入。写多了不怕摘要阶段会压缩写少了才是大问题因为漏掉一条关键约束后面所有决策都可能跑偏。2.3 存储与检索轻量优先不迷信向量数据库存储层我用了一个非常轻的方案SQLite 存结构化记录本地向量索引存语义检索用的嵌入向量。几百条到几千条记忆的量级完全没有必要上外部向量数据库——那只会多一个需要运维的组件检索延迟反而增加。检索分两种。精确检索按项目、作用域、类型过滤适合查一下支付模块还有哪些生效的约束这类明确问题。语义检索按文本相似度召回适合我记得上次讨论过性能优化具体结论是什么来着这种模糊回忆。新会话启动时工具链把当前项目最相关的记忆捞出来生成一份不超过几十行的记忆摘要按优先级排序后注入系统提示词。摘要这块我踩过一个很典型的坑刚开始贪心把 20 条相关记忆全塞进去结果上下文膨胀代理反而变得缩手缩脚连合理的自主判断都不敢做了。后来默认只带 5 到 10 条一条一句只保留有明确行动含义的内容。这条经验后来被我写进了文档第一页也是我最想告诉使用者的一个教训。3. 代码地图让代理用查地图代替翻迷宫3.1 索引器干的事符号表加文件依赖图代码地图仓库解决的就是代理对仓库脸盲的问题。核心组件是一个索引器扫描仓库里的源文件用语法分析引擎提取符号信息函数、类、接口、路由、配置项、公开 API。输出物是两张表符号表和文件依赖图。符号表记录某个符号在哪里定义、签名是什么文件依赖图记录A 文件被谁引用、改了 A 会影响谁。这两张表放在单文件数据库里查询在本地进程内完成不需要单独起服务也不需要网络请求。对一个几万文件规模的仓库做首次全量索引我用普通开发机实测大概需要几分钟之后进入监听模式靠文件系统变更事件做增量更新每秒能消化几个到几十个文件日常开发里基本感觉不到它在后台跑。3.2 容错设计代理会产出坏代码索引器不能跟着崩索引器必须容忍不完美的代码这是从真实工作流里逼出来的要求。AI 编程代理在工作过程中会产出临时文件、半成品、语法还没补全的片段、以及写了一半就中断的测试。如果索引器遇到解析错误就抛异常、中断索引它根本活不过一个正常的开发日。我做了两个关键设计。一是任何文件解析失败都只记录一条警告、跳过该文件绝不中断整体索引二是默认排除生成目录、依赖目录、构建产物目录避免这些噪音文件挤占地图里的有效信息。排除列表做成了全局默认配置用户不需要自己维护当然它也开放修改入口遇到特殊仓库结构时可以按需调整。3.3 查询接口与代理的实际配合方式代理不需要把整张地图背进上下文它只需要一组按需查询的工具。我最终保留了四类最常用的查询查询类型典型问题返回内容符号定位这个函数定义在哪里文件路径与行号调用关系哪些地方在调用这个函数调用方列表引用查询哪些文件 import 了这个模块文件路径列表变更影响这次提交的改动会影响哪些文件受影响文件清单这套查询在改造既有工作流时最有用。实测下来代理从自己 grep 整个仓库切换到按需查地图之后探索阶段的 token 消耗降了一截并且修 bug 时给出的方案不再绕远路。地图的价值曲线很陡峭仓库小的时候你感觉不到它仓库大到人脑记不住结构之后它就是刚需。4. Token 记账从月底看糊涂账到每一笔都有明细4.1 采集端把杂乱的用量事件收敛成标准记录记账仓库的采集端只做一件事把代理运行时产生的各种用量事件统一收敛成标准格式的记录。每条记录至少带这些维度项目、会话、代理模型、动作类别、输入 token、输出 token、时间戳。其中动作类别是记账系统根据调用上下文推断出来的比如一次搜索、一次读文件、一次写文件、一次多轮对话。为什么一定要分动作类别因为只有把 token 花在哪个环节搞清楚才有优化的抓手。我见过最典型的情况某个深夜任务里代理在一个循环中反复读取同一个大文件把预算烧掉一大截。只看总额你只会得出AI 好贵的结论看了动作分布才会发现真正的问题是工具调用策略有 bug需要修的是工作流而不是换模型。4.2 预算策略默认只预警不硬断预算策略引擎支持按项目、按会话、按天或按周设置限额。默认策略是预警但不硬断超过阈值向指定渠道推一条消息附上前五名消耗项。硬性阻断在真实协作里会卡住正常流程还容易误伤正在跑的长任务预警则让每个人都产生预算快爆了的自觉又不至于打断工作。配置大概长这样budgets: weekly: default: 5000000 project-payment: 2000000 alerts: - at: 80% channel: chat message: 本周 token 用量已超 80%前五名消耗项见报表如果团队使用我建议按周设置主限额而不是按天。开发任务的节奏天然不均衡某天集中做重构、某天只是开会讨论按天卡太紧会导致大家为了凑指标反而更浪费。4.3 记账数据攒多了还能反哺工程优化记账数据积累了几个月之后我发现了两个设计之初没预料到的用途。第一个是效率审计把同一个任务的多次迭代放在一起看消耗曲线能直接回答这版改动到底比上一版贵了多少这个数据在讨论技术方案取舍时非常好用。第二个是反哺工具调优。我按动作类别统计 token 占比发现很多任务的消耗大头居然不是生成代码而是反复搜索、阅读、回溯。基于这个发现我调整了代码地图的查询优先级给高频查询结果加了缓存整个工作链的 token 消耗下降了大概两三成。记账模块表面上是财务工具实际受益最大的却是工程效率。5. 九个仓库的分工从单体到积木的拆分过程5.1 仓库清单与定位表九个仓库按职责分成三横一纵三条功能线分别是记忆、地图、账本一条纵向是公共协议负责兜住所有跨模块的数据结构。完整清单和各自的使用场景如下仓库功能线核心职责独立使用场景记忆核心记忆记忆记录的模型定义、读写 API代理跨会话失忆严重记忆存储适配记忆SQLite、本地向量索引等后端实现需要更换记忆存储介质代码索引器地图源码符号提取、增量更新、容错解析仓库大代理探索效率低代码查询服务地图符号定位、依赖查询、变更影响分析需要按需查地图能力代理适配器集成把上述能力转成代理可调用的工具要快速接入现有代理Token 采集器账本用量事件采集与标准化消耗完全不可见预算策略引擎账本限额、告警、配额计算成本开始失控记账看板账本多维报表、日周报推送需要向团队展示数据公共协议底座全链路共享的数据结构定义想自己实现某个模块5.2 拆的过程以及拆分后最麻烦的版本问题九块功能最早都挤在一个仓库里改一行要全量发版使用者想只拿记账也得把整包拉下来。后来我花了几轮重构先抽出公共协议仓库把所有仓库之间要传递的数据结构统一放进去再按依赖方向逐层拆出其他仓库保证依赖只有一个方向没有任何循环引用。拆完最大的代价是版本管理复杂度九个仓库各自发版怎么保证组合起来不出问题。我的应对是给协议仓库定了一条纪律——只做向后兼容的修改非兼容变更必须升大版本号其余仓库各自独立发版不强行要求同版本部署。这样使用者可以按需组合不同仓库的版本不会出现升级 A 就必须连带升级 B的锁死情况。5.3 按需组合别一上来就九仓全上实际使用中我不建议新用户一开始就九个仓库全上。只关心成本的人拉 Token 采集器和记账看板就够了被失忆折磨得最狠的团队先上记忆核心和存储适配项目规模到了一定程度、代理明显读不完代码的团队再加代码地图。组合使用时代理适配器负责把三套能力统一成同一个工具调用协议避免代理那边要记三套不同规则。6. 全 MIT 的取舍为什么选择不设防的开源方式6.1 把被用起来放在被保护前面开源协议的选择上我没有纠结太久直接选了 MIT。这个协议允许任何人任意使用、修改、再分发包括商用不需要经过原作者同意。我知道有人会心疼代码被白嫖但对我来说这套工具链的价值模型不是靠卖授权赚钱而是靠被接入到越来越多的真实项目里滚雪球。被使用的范围越广能收到的反馈、改进和 bug 报告就越多。如果我用限制更严格的协议潜在使用者里的企业团队一旦需要法务审核才能接入很可能就直接跳过这个方案了。这种看一眼协议就放弃的流失是所有严格协议都绕不开的隐性成本。相比之下被用起来带来的长期收益远大于防止别人用带来的心理安全感。6.2 宽松协议形成的反馈循环选 MIT 之后有一个非常实际的好处使用者没有任何法律顾虑可以放心大胆地把代码接进私有项目、商业产品。于是我能收到更真实的场景反馈而不是停留在看起来不错的点赞层面。已经有几位使用者直接把改进提交回上游其中包含几个我完全想不到的 bug 修复和新工具调用这部分外部贡献比我自己埋头写效率高得多。6.3 宽松不等于没底线最后说明一点MIT 宽松但不代表可以抹掉版权声明。基于这套代码做二次分发的时候需要保留原始版权信息。把它塞进商业项目、内部系统、SaaS 服务都不需要联系我但如果你把它重新打包发布基本署名要求还是要守住的。这是我在整个协议选择里唯一想对使用者强调的一条底线。7. 真实接入经验推荐顺序、踩坑记录和后续方向7.1 三轮接入顺序先账本再地图最后记忆我在多个真实项目里跑过这套工具链如果让我重来一遍接入顺序会按成本从低到高来排。第一轮只接记账先把消耗看清楚养成花 token 要有数的习惯。这一步收益最快基本当天就能看到效果也最有动力说服团队继续往下接。第二轮接代码地图。等代理学会查地图而不是瞎翻文件以后再观察 token 消耗有没有下降、生成的方案有没有更贴合仓库现状。这里要留出一周左右的适应期因为代理需要慢慢学会先查再写的工作习惯。第三轮接记忆。记忆是所有功能里收益最慢的一环它的价值依赖持续积累得跑上几周才会明显感到代理好像真的记住了一些东西。但它的长期价值最大尤其适合经常跨代码库、跨项目复用的场景。7.2 三个值得写进文档的坑第一个坑是记忆摘要太贪心。前面提过我把 20 条 active 决策全部塞进摘要的事这里再补一个细节那之后代理开始过度谨慎连无关紧要的小改动都要反复确认因为它觉得每个历史约束都还生效。解决方式很直接摘要只放当前 scope 内最相关的约束和最近的进展历史决策默认折叠需要时再展开查询而且 status 为 superseded 的记录永远不进摘要。第二个坑是索引器误扫生成目录。地图里混入构建产物的符号后查询结果出现大量误导项代理查到过 dist 目录里的同名函数整体判断都乱了。解决方式是在全局配置里强制排除dist、node_modules、build这类目录并且把排除表做成默认值而不是留给用户自己配——等用户踩了坑再配代价已经付过了。第三个坑是记账时区不一致。用量事件如果混用多个时区的时间戳按天汇总的日报就会对不上账月底复盘时数据怎么都对不齐。最终统一在采集端强制转成 UTC 存储展示层再转本地时区数据才彻底对齐。这种问题只有跑真实长周期才会暴露文档里基本不会有人写。7.3 我接下来的计划短期优先做记忆仓库的遗忘策略给记忆按时间、作用域、价值打分低优先级记忆自动进入冷存储检索时排除掉避免噪音稀释真正有用的决策。代码地图这边准备扩展对更多语言的支持重点补动态语言里常见的模式匹配。账本这边计划加一个按提交分账的维度把每次代码提交的 token 成本直接落到评审环节让优化讨论有数据支撑而不是凭感觉。最后说一点个人体会。这套工具链真正改变我的不是让 AI 编程代理变得多么聪明而是让我对AI 在项目里到底干了什么第一次有了量化的认知。记忆让代理学会尊重之前的决定地图让它不再对着仓库瞎猜账本让每一分 token 都有地方可以查。维护九个仓库确实比维护一个单体更费神版本同步、协议稳定、兼容性测试都得自己扛。但每当我看到代理在新会话里还记得前几天的约束看到它重构时主动绕开不该碰的模块看到月报里的 token 消耗逐月下降就会觉得这九份代码没有白写。如果你也想给自己的代理搭这类外围基建我的建议是从记账开始先把现状看清楚再一步步补记忆和地图——别像我一开始那样贪多求全。整套工具链都是 MIT 协议直接拿去用也欢迎来改开源这件事本来就是在互相借鉴里进步的。
