上个月我把一套东西整理好放了出来AI 编程代理工具链一共9 个仓库全部 MIT 协议。这套东西解决的是我在实际用 AI 代理写代码、改项目时反复撞到的那三堵墙——没有记忆、看不懂代码库、token 烧了没账本。如果你也在折腾 Agent 编程、Long Context 管理的那些破事这篇整理应该能让你少走不少弯路。它不是那种宏大叙事的AI 原生开发平台就是掏出来的 9 个库每个单独拎出来都能用合在一起又能串成一条链代理的记忆怎么管、代码地图怎么生成、每次会话到底花了多少 token 怎么记账。这篇我把为什么拆 9 个、每个是干嘛的、实际串起来是什么姿势统统说清楚。1. 为什么还需要自己造一套轮子1.1 三个痛点把我逼到了仓库面前先说记忆。我用 AI 代理干活最气人的一件事上午刚定好的代码风格下午开个新会话它全忘了。不是模型不行是代理本身的上下文根本活不到第二个 session。模型每次是无状态的Agent 框架要么把所有东西塞进 context要么就真什么都不记得。项目一复杂这种失忆就是致命伤。然后是代码地图。你给代理丢一个 10 万行的仓库它 200K 的 context 装不下整个项目。那怎么办它只能从入口文件开始顺藤摸瓜摸到哪算哪。运气好它能摸到核心逻辑运气不好它在配置文件里绕了半小时没出来。没有结构化的项目索引代理解读大型代码库的效率全凭运气。最后是 token。这个感受最直接——我一个月跑下来token 消耗量完全是个黑盒。哪一个任务烧了多少哪个环节最费量根本没人给你记账。等到账单出来才傻眼但为时已晚。1.2 市面上工具的边界在哪我也不是没找过现成的轮子。记忆类的工具有代码索引类的有token 统计的也有。但问题出在两个地方。第一是不够透明。很多工具做成一个黑盒服务数据放在别人的服务器上底层逻辑你根本摸不着。对于我这种喜欢掌控感的人用着实在不踏实。第二是和代理框架的契合度不够。很多记忆方案只适配某一款代理框架换一个就全废。而我的场景是今天用这个代理、明天用那个有时候还会自己写调度逻辑我需要的是低耦合、协议化的东西。所以最后决定自己动手。而且既然是自用为主代码量不需要特别大维护成本完全在我的掌控范围内拆成 9 个仓库管理也很轻量。这个经历让我越来越认同一个观点在 AI 编程工具这个阶段真正的壁垒不是模型而是工程化配套。2. 9 个仓库的拆分逻辑2.1 按单一职责切分我见过很多人做工具链喜欢搞一个大 monorepo全家桶塞进去看着整齐实际用起来全是依赖地狱。我这次特意反着来——9 个仓库每个只解决一个具体问题互相之间依赖非常克制。记忆是记忆、索引是索引、账号是账号。这样的好处是如果你只需要 token 记账你 clone 那一个仓库就行完全不用管其他 8 个。每个库的依赖方也尽量收紧少拖泥带水。下面是完整的清单仓库名核心职责关键依赖去向mem-core会话记忆持久化、提取与分层存储无底层依赖mem-api记忆的 HTTP 查询与管理接口依赖 mem-corecode-map-core静态分析生成项目结构索引无底层依赖code-map-server索引服务、增量更新、查询 API依赖 code-map-coretoken-tracker-coretoken 计数、按会话/操作聚合统计无底层依赖token-tracker-server记账服务与账单查询接口依赖 token-tracker-coreagent-sdk代理侧客户端 SDK记忆/地图/记账的统一入口依赖上述全部核心agent-runtime-example演示代理运行时串联整条链路依赖 agent-sdktoolchain-notes设计文档、部署参考、模式与踩坑记录文档无代码依赖2.2 分组看记忆、地图、记账从功能上这 9 个库其实是三块加一个串联层。记忆组mem-core、mem-api。mem-core 干的是脏活累活从对话流中抽取出关键信息然后按项目、按会话维度落库存起来。mem-api 把它包一层对外接口方便你从代理环境或者其他工具里调用。这一组的核心思考是记忆必须分层全局的项目偏好、本次任务的临时上下文、单条决策的理由三者存的地方和生命周期完全不一样。代码地图组code-map-core、code-map-server。这一组负责把项目代码结构变成可查询的索引。core 做静态解析server 负责跑持续更新的后台服务。因为项目是在不断变化的文件增删改都需要增量反映到索引里。这里最难的是怎么处理增量更新——全量重扫大仓库是很贵的。记账组token-tracker-core、token-tracker-server。core 定义数据模型原始 token、上下文缓存 token、输出 token、按请求还是按会话聚合。server 把它变成可积累的计量服务包括按天的消耗曲线、按任务的成本估算。串联层agent-sdk、agent-runtime-example。agent-sdk 是对上层暴露的统一封装代理只需要跟它交互就行。而 toolchain-notes 更像一个活文档仓库我在里面记录了怎么部署、怎么对接、哪些方案试过不好使。这一层如果没了前面三层就是孤岛对于使用者来说确实是四块硬骨头。2.3 为什么坚决不做单体经常有人问我9 个仓库管理起来不累吗反过来想如果做成一个 monorepo会出现什么改记忆的存储逻辑触发 token 记账模块的 CI 测试改个代码地图的配置被别的模块的 lint 规则波及。独居久了的人都懂哪怕是合租也要水管各走一根这个道理搁工程上一样成立。仓库之间的边界本质上就是人与人、模块与模块之间的沟通成本边界。而且 MIT 协议意味着别人拿过去可以随便改如果做成单体别人想复用其中一个功能就得全盘接受我的设计。拆开之后哪怕有人只用 mem-core 那一个包也很舒服。3. 把三个痛点串成一条链3.1 一次完整任务里它是怎么跑的光拆开测试没意思真正的价值在于合起来用。我在开源仓库里带了一个演示运行时完整复现了代理接任务 → 查记忆 → 看地图 → 干活 → 记账的闭环。下面用一个具体例子走一遍。假设你的仓库里有个 bug 报告登录接口在特定情况下偶发超时。代理接到这个任务时先调mem-api查询这个项目的历史记录发现上周有人提过类似的超时问题当时的结论是某个超时配置参数和数据库连接池配置的组合有问题。这个信息让代理不是从零开始找而是直接带着先验知识去查代码。接着调code-map-server查登录接口所在模块的依赖关系——它不需要看全仓库只需要拿到入口文件、核心调用链、涉及的外层依赖这一层树状结构就足够定位了。干完活之后token-tracker-core里多了几条记录这次会话主模型消费了多少、上下文缓存命中了多少、工具调用消耗了多少。到月底你能精确看到这类 bug 修复的平均成本。3.2 先查记忆还是先查地图的顺序问题你会发现执行顺序不是随机的。先查记忆是因为记忆的查询成本最低而且能用很少的 token 给代理一个要点摘要。先把这个问题有没有人研究过、结论是什么搞清楚避免重复定位。再查地图是因为第二步目的性更强——你要修的具体文件到底在哪依赖链是什么样的。这一步的查询虽然在抽象层级上比全文给代理更有价值但也不宜太早把它和记忆混在一起做。我把这个顺序固化到了演示运行时里。记忆是先验地图是导航记账是复盘。这个思路在你调整提示词框架时非常值得直接搬去用。3.3 agent-sdk 是怎么降低对接成本的从代理侧视角看它不想关心三套 API。所以 agent-sdk 做了几件事统一认证三个服务共用一个 API Key 体系不用各配各的。封装查询语义代理只需要说给我当前任务的记忆摘要、给我文件 X 的依赖图SDK 内部去拼装 HTTP 请求。异步记账上报代理在一个环节结束后直接调track(tool_call, latency_ms)SDK 建议异步落库不让记账影响主流程延迟。上下文截断保护当记忆摘要返回过大时SDK 内置一个按最高预算截断的逻辑不至于把模型的上下文撑爆。这一层做得好不好直接决定了串起来的时候顺不顺畅。如果每次集成都要写一堆胶水代码这个工具链就没有生命力。4. 三个核心模块的设计与选型4.1 记忆分层设计值得认真参考记忆的设计全程围绕一个问题什么信息值得跨会话存在我的答案是结论和偏好优先过程其次原始日志基本不留。mem-core 里定义了四个层级。项目偏好层全局存比如本项目禁止使用 XXX 依赖、文件命名遵循 snake_case任何会话进来都不用重新问。决策记录层按主题存比如某次重构为什么选择 A 方案而不是 B 方案下次会话再遇到同样问题时可以直接引用。任务工作区按会话存本次任务的临时上下文跑完就清理防止累积污染。原始对话流仅在调试模式下短期保留正常模式下不落地。这个分层的核心是避免把所有信息一锅端。记忆最大的风险不是不记得而是记太多了全是噪音。任何模型面对一堆无差别信息时都会选择困难反而干扰了正常决策。4.2 代码地图的增量更新难关code-map-server 启动时会做一次全量扫描建立符号索引和文件依赖关系。但如果你每次 git pull 之后都全量重扫仓库大一点就非常痛苦所以我做了三层增量文件级通过 mtime 判断哪些文件变了只重新分析这些文件。模块级如果文件变化影响了模块导出才向上更新依赖它的模块。全局级只有涉及项目配置、入口文件这类全局节点时才触发整体重扫。实测下来日常迭代中大概 80% 的变更都只落在文件级这个设计让索引服务基本不需要人工介入。这里有个经验可以分享增量更新的难点不是知道哪些变了而是变了之后要连锁更新哪些下游节点。我在 code-map-core 里专门设计了一个 影响面传播 队列避免漏更新这算是这个模块里最值得抄的细节。4.3 token 记账的精度和粒度记账组的核心不只是算总数而是怎么拆成本。token-tracker-core 把一次请求拆成三个维度输入 token含命中上下文缓存的部分以及完全重新处理的部分输出 token工具调用 overhead比如你给代理塞了多长的系统提示词系统提示词这块常常被忽略。很多代理框架会把一个很长的 system prompt 反复塞进每次请求这个开销积少成多非常可观。token-tracker 把这些部分都显式拆出来就是为了让你看清楚钱到底烧在真的在思考上还是烧在每次都重复念说明书上。这个发现直接改变了我写代理提示词的习惯——系统提示词里面不常用的长规则全挪到记忆摘要里按需调取而不是常驻 context。5. 串起来以后的实测效果整套东西我在一个内部模拟项目上跑了几周规模大概是 5 万行代码、二十多个核心模块。对比数据挺有意思。指标没有工具链使用工具链后新任务平均定位时间需要代理从入口扫描耗时约 5-8 分钟带记忆摘要地图导航降到约 1 分钟跨会话重复提问次数频繁几乎每次重新梳理下降约一半以上完成一次修复的 token 消耗波动大经常超预算稳定可控约降低两到三成月度 token 账目黑盒可按任务、按模块、按会话拆分明细记忆对重复性问题的提升最明显。凡是涉及这个项目之前怎么定的这类问题代理基本不用再瞎猜直接调记忆就行。代码地图对陌生模块改造的提升最大代理不用整个项目翻来翻去盯着一张依赖图就能精准下手。token 记账带来的改变更偏长期我盯着账单才意识到某些工具调用环节为了追求完美会把整个模块的内容塞给模型这时 token 烧得很没道理。记账让每个环节的成本都变得可见就会倒逼代理的调用策略变得更经济。成本控制的第一步永远不是限制而是看见。6. 选 MIT 的考量与后续规划6.1 为什么是 MIT 而不是其他协议关于协议我基本没犹豫就直接定了 MIT。理由其实很朴素这 9 个库本来就是我自用工具的副产品而不是一个商业化项目。既然不打算靠它赚钱那就做到最大程度的开放。MIT 比 Apache 要少一堆条款对使用方来说最省心比 GPL 更要宽松很多不论是人拿了去改还是把他闭源内置到商业产品里都没有任何义务要反哺回我。说实话我对使用的场景没有执念我更希望看到它出现在各种不同的项目里哪怕是闭源的。另外选 MIT 还有一个实际的考量代码里如果只保留了著作权声明那么任何人在二次分发时都不需要去研究复杂的许可证兼容性问题。这一点对开源生态的友好程度是最高的。6.2 这几周我的一些体会9 个仓库的整理虽然辛苦但整个过程让我对 AI 编程代理的工程化有了更清楚的认知。模型负责聪明工具链负责可靠。没有记忆再聪明的模型也是金鱼没有地图再大的 context 也装不下一个中型项目没有记账你就永远不知道聪明用在了什么地方。如果你也想搭自己的一套我给三个建议记忆模块先做分层别一上来什么都存先想清楚哪些值得留。代码地图的增量更新一定要从第一天就设计不然项目变大以后你会后悔。token 记账的维度宁可拆细一点先多记账再考虑如何省钱。这三个模块单独拿出任何一个都不算特别难实现。难的是把它们以合适的接口拼在一起并且保证替换其中一个模块时不会影响其他部分。这套工具链的真实价值其实就在这里。