1. 这套工具链到底在解决什么问题

先说说我为什么要做这件事。过去一年多，我几乎每天都在跟 AI 编程代理打交道——写代码、改 bug、做代码审查、生成测试用例，能用的场景基本都试了一遍。用得越多，越发现一个尴尬的现实：单个 AI 编程代理的能力已经很强了，但把它们串起来当成一套工程化工具链来用，体验非常割裂。

具体来说，我遇到了几个反复出现的痛点。

第一个痛点是记忆断层。每次开一个新的会话窗口，代理就完全失忆了。上一轮对话里讨论过的架构决策、命名约定、踩过的坑，全部归零。你得重新贴一遍上下文，或者把之前的对话记录手动复制过去。一次两次还能忍，天天这么干就是纯浪费时间。

第二个痛点是代码理解效率低。一个中等规模的项目，几千个文件，代理要理解代码结构，只能靠你手动喂文件路径，或者让它自己去 grep。它不知道哪些文件是核心模块，哪些是自动生成的，哪些是废弃代码。结果就是它经常在无关的文件上浪费大量 token，真正关键的代码反而没读到。

第三个痛点是token 消耗不透明。用 AI 编程代理，token 就是钱。但大多数工具不告诉你每次请求到底花了多少 token，哪些操作最费 token，哪些可以优化。你只能月底看账单的时候心疼一下，然后继续这么用。

这三个痛点，单独看都不算致命，但叠加在一起，就让 AI 编程代理的工程化落地变得非常别扭。你明明知道这东西能大幅提升效率，但实际用起来总感觉差一口气。

所以我决定自己动手，把这套工具链开源出来。一共 9 个仓库，全部 MIT 协议，覆盖了从记忆管理、代码地图构建到 token 记账的完整链路。每个仓库都可以独立使用，也可以组合起来形成一套完整的 AI 编程代理工作流。

这套工具链适合谁？如果你只是偶尔用 AI 写个脚本，可能用不上。但如果你满足以下任意一条，这套东西应该能帮到你：

• 每天高频使用 AI 编程代理，希望减少重复的上下文准备工作
• 在中等规模以上的项目里用 AI 代理，需要它更精准地理解代码结构
• 对 token 消耗敏感，想搞清楚钱到底花在哪了
• 想基于现有工具做二次开发，搭建自己的 AI 编程工作流

下面我会逐个拆解这套工具链的设计思路、核心实现和实操要点。内容会比较长，但都是实打实的经验，不是那种“安装完就完事”的教程。

2. 整体架构与设计思路拆解

2.1 为什么是 9 个仓库而不是 1 个

很多人问我，为什么不做一个大而全的工具，非要拆成 9 个仓库。这个问题我在设计初期也纠结过，最后选择拆分，主要基于三个考虑。

第一是职责单一，方便替换。AI 编程代理这个领域变化太快了，今天用这个模型，明天可能就换了。如果所有功能耦合在一起，换个模型适配层就要动整个项目。拆成独立仓库后，记忆管理、代码地图、token 记账各自独立，你想换掉其中任何一个，不影响其他部分。

第二是降低使用门槛。不是每个人都需要全套工具。有人可能只想要 token 记账，有人只想要代码地图。拆开之后，你可以按需取用，不用为了一个功能引入一堆依赖。

第三是方便社区贡献。单个仓库的代码量控制在合理范围内，新人想贡献代码，不用先花一周时间理解整个项目。每个仓库的 README 和文档也更容易维护。

这 9 个仓库在逻辑上分为三层：

基础层是地基，核心层是主体，应用层是入口。三层之间通过定义良好的接口通信，每一层都可以单独测试和替换。

2.2 记忆管理的设计取舍

记忆管理是这套工具链里我最花心思的部分。核心问题是：AI 编程代理需要记住什么，以及怎么记住。

我试过几种方案。最简单的方案是把所有对话历史都存下来，每次请求全量带上。这个方案的问题是 token 消耗爆炸，而且大部分历史信息对当前任务没用。另一个极端是只保留最近几轮对话，但这样又会丢失重要的长期上下文。

最后我采用的方案是分层记忆 + 按需检索。

分层记忆的意思是，把记忆分成三个层次：

• 会话记忆：当前会话窗口内的对话历史，保留最近 N 轮，N 可配置
• 项目记忆：与当前项目相关的长期信息，比如架构决策、命名约定、已知问题
• 全局记忆：跨项目的通用偏好，比如代码风格、常用库、个人习惯

按需检索的意思是，不是所有记忆都塞进每次请求。而是根据当前任务，从项目记忆和全局记忆里检索最相关的片段，动态组装到上下文里。

这里的关键是检索策略。我试过基于关键词的检索，效果一般，因为代码相关的查询往往语义复杂。后来换成了基于嵌入向量的语义检索，效果好很多。具体做法是：把项目记忆和全局记忆里的每条记录都生成嵌入向量，存到本地向量库里。每次请求时，把当前任务描述也生成向量，做相似度检索，取 top-K 条最相关的记忆。

注意：嵌入向量的生成需要调用模型接口，这本身也会消耗 token。我的做法是只在记忆写入时生成一次向量，检索时复用，避免重复计算。

这个方案实测下来，在保持上下文质量的同时，能把每次请求的 token 消耗降低 40% 到 60%。具体降多少，取决于项目记忆的规模和检索的 top-K 设置。

2.3 代码地图的核心原理

代码地图要解决的问题是：让 AI 代理快速理解一个陌生项目的结构。

传统做法是让代理自己去读文件、grep 关键词。这个方式的问题是效率低，而且代理容易迷路。一个几千文件的项目，代理可能读了二十个文件还没找到核心逻辑。

我的做法是预构建代码地图。具体来说，分三步：

第一步是静态分析。用语法解析器把项目里所有代码文件解析成抽象语法树，提取出类、函数、变量、导入关系等结构信息。这一步不执行代码，纯静态分析，速度快。

第二步是依赖图构建。基于静态分析的结果，构建文件之间、模块之间的依赖关系图。谁引用了谁，谁被谁依赖，一目了然。

第三步是重要性排序。根据依赖图的入度和出度，以及代码的复杂度指标，给每个文件、每个函数打一个重要性分数。核心模块分数高，边缘工具分数低。

有了代码地图之后，AI 代理要理解项目时，不需要自己摸索。它可以直接查询代码地图，问“这个项目的入口在哪”“哪个模块被引用最多”“这个函数的调用链是什么”。代码地图会返回结构化的答案，代理基于这些答案再去读具体代码，效率高很多。

实测数据：在一个约 3000 个文件的项目里，没有代码地图时，代理平均需要读取 18 个文件才能定位到核心逻辑；有了代码地图之后，平均只需要读取 4 个文件。token 消耗的差距可想而知。

2.4 token 记账为什么重要

token 记账这件事，很多人觉得不重要，用就完了，算那么细干嘛。但我的经验是，不记账就不知道钱花在哪，不知道钱花在哪就没法优化。

我做的 token 记账工具，核心功能有三个：

• 实时计量：每次请求和响应，都记录输入 token 数、输出 token 数、总 token 数
• 分类统计：按操作类型（读代码、写代码、代码审查、生成测试等）分类统计 token 消耗
• 趋势分析：按天、按周、按月看 token 消耗趋势，找出异常峰值

有了这些数据之后，优化方向就很清晰了。比如我发现代码审查操作的 token 消耗特别高，一查发现是因为每次审查都把整个文件内容塞进去了。后来改成只传变更部分加上下文，token 消耗直接降了 70%。

实操心得：token 记账工具一定要支持按操作类型分类。只看总量没用，必须知道哪类操作最费 token，才能有针对性地优化。

3. 核心模块的实操要点

3.1 记忆模块的配置与使用

记忆模块的安装很简单，但配置有几个关键参数需要根据你的使用习惯调整。

首先是会话记忆的保留轮数。这个参数控制当前会话窗口内保留多少轮对话历史。设太小，代理会忘记刚才讨论的内容；设太大，token 消耗高。我的建议是默认设 10 轮，如果发现代理经常忘记上下文，再往上调。

其次是项目记忆的检索 top-K。这个参数控制每次请求从项目记忆里检索多少条相关记录。设太小，可能漏掉关键信息；设太大，会引入无关信息干扰代理判断。我的经验值是 5 到 8 条，具体取决于项目记忆的规模和质量。

第三是记忆写入的触发条件。不是所有对话都值得写入项目记忆。我的做法是设置几个触发条件：当对话里出现明确的架构决策、命名约定、已知问题标记时，自动写入项目记忆。其他普通对话只保留在会话记忆里。

配置文件的格式是 YAML，大概长这样：

memory: session: max_turns: 10 project: retrieval_top_k: 6 embedding_model: "local" storage_path: "./.ai-memory/project" global: storage_path: "~/.ai-memory/global" write_triggers: - "architecture_decision" - "naming_convention" - "known_issue"

这里有个细节：嵌入模型我默认用的是本地模型，不是调用远程接口。原因是记忆写入和检索的频率很高，如果每次都调远程接口，token 消耗和延迟都受不了。本地模型虽然效果稍差，但胜在免费且快。如果你对检索质量要求特别高，可以换成远程接口，但要做好 token 预算。

3.2 代码地图的构建流程

代码地图的构建分两步：初始化构建和增量更新。

初始化构建是在项目第一次接入时执行，会扫描整个项目，生成完整的代码地图。这个过程的时间取决于项目规模。一个 3000 文件的项目，大概需要 2 到 3 分钟。构建完成后，代码地图会存到本地文件里，后续查询直接读本地文件，速度很快。

增量更新是在代码变更时执行。我做了文件监听，当检测到代码文件变更时，只重新分析变更的文件和受影响的依赖关系，不重新扫描整个项目。这样增量更新的时间通常在秒级。

构建命令大概是这样：

# 初始化构建 ai-codemap init --project-root ./my-project --output ./.ai-codemap # 增量更新 ai-codemap update --project-root ./my-project --output ./.ai-codemap

构建过程中有几个参数值得注意：

• --ignore-patterns：指定忽略的文件模式，比如node_modules、dist、*.min.js等。这个一定要配，不然自动生成的代码和第三方库会污染代码地图。
• --importance-threshold：重要性分数的阈值，低于这个分数的文件不会出现在代码地图的推荐列表里。默认是 0.3，如果项目里工具类文件特别多，可以调到 0.5。
• --max-depth：依赖图的最大深度。默认是 5 层，超过 5 层的依赖关系不展开。这是为了防止依赖图过大导致查询变慢。

注意：代码地图的构建依赖语法解析器，目前支持主流编程语言，但一些小众语言可能支持不完善。如果你的项目用了小众语言，建议先测试一下解析效果。

3.3 token 记账的接入方式

token 记账模块的接入方式取决于你用的 AI 编程代理工具。我提供了几种常见的接入方式。

如果你的代理工具支持自定义 HTTP 拦截器，那最简单，直接在拦截器里调用记账模块的 API，记录每次请求和响应的 token 数。

如果代理工具不支持拦截器，可以用代理模式。启动一个本地代理服务，所有请求先经过这个代理，代理转发请求的同时记录 token 数。这种方式对代理工具透明，不需要改代理工具的代码。

还有一种方式是手动埋点。在代码里显式调用记账 API，记录关键操作的 token 消耗。这种方式最灵活，但需要改代码。

记账数据的存储我用的是 SQLite，轻量且查询方便。数据表结构大概是：

查询统计的命令：

# 查看今日 token 消耗 ai-token stats --period today # 按操作类型查看 ai-token stats --period week --group-by operation # 导出明细 ai-token export --start 2024-01-01 --end 2024-01-31 --format csv

3.4 上下文组装的策略

上下文组装是连接记忆模块和代码地图的桥梁。它的任务是把记忆检索结果、代码地图查询结果、当前任务描述，组装成最终发给 AI 代理的上下文。

组装策略有几个关键决策点。

第一是优先级排序。不是所有信息都同等重要。我的做法是给每类信息打优先级分数：当前任务描述优先级最高，其次是代码地图返回的核心代码片段，然后是项目记忆里的相关记录，最后是会话记忆。组装时按优先级从高到低填充，直到达到 token 预算上限。

第二是 token 预算分配。每次请求都有一个 token 预算，比如 8000 token。这个预算要在各类信息之间分配。我的默认分配是：任务描述 10%，代码片段 50%，项目记忆 25%，会话记忆 15%。这个比例可以根据任务类型调整。比如代码审查任务，代码片段的占比可以调高到 70%。

第三是去重和压缩。记忆检索和代码地图查询可能返回重复信息。组装时需要去重。另外，有些信息可以压缩，比如把长代码片段压缩成函数签名加注释，把长对话历史压缩成摘要。

组装模块的配置：

context: token_budget: 8000 allocation: task_description: 0.1 code_snippets: 0.5 project_memory: 0.25 session_memory: 0.15 compression: enabled: true code_snippet_max_lines: 50 session_summary_threshold: 5

实操心得：token 预算不要设得太满。我一般会留 10% 的余量，防止组装过程中出现意外导致超限。另外，压缩功能虽然能省 token，但会损失信息。如果发现代理经常因为信息不足而给出错误答案，先把压缩关掉试试。

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

4.1 记忆检索不准确怎么办

这是被问得最多的问题。记忆检索不准确，通常有三个原因。

原因一：嵌入模型效果差。如果你用的是本地小模型，检索效果可能确实一般。解决办法是换更大的本地模型，或者换成远程接口。但换远程接口会增加 token 消耗，需要权衡。

原因二：记忆记录质量低。如果写入项目记忆的记录本身就很模糊，比如“改了一下配置”，那检索再准也没用。解决办法是优化记忆写入的触发条件和内容格式。我要求每条项目记忆必须包含：什么决策、为什么这么决策、影响范围是什么。格式化的记忆记录检索效果更好。

原因三：top-K 设置不合理。top-K 太小会漏掉相关记忆，太大会引入无关记忆。解决办法是先用默认值 6，然后根据实际效果调整。如果发现代理经常缺少关键上下文，调大到 8 或 10；如果发现代理被无关信息干扰，调小到 4 或 5。

排查步骤：

1. 先看检索返回的记忆列表，人工判断是否相关
2. 如果不相关，检查嵌入模型和记忆记录质量
3. 如果相关但代理没用上，检查上下文组装逻辑
4. 如果代理用了但效果不好，检查记忆记录的表述是否清晰

4.2 代码地图构建失败或结果异常

代码地图构建失败，常见原因和解决办法：

我踩过的一个坑是：项目里用了某种代码生成工具，生成的文件没有扩展名，导致语法解析器识别不了，构建时报了一堆错。解决办法是在 ignore-patterns 里把这些生成文件排除掉。

另一个坑是：monorepo 项目里多个子项目共用依赖，依赖图构建时出现了循环依赖，导致构建卡死。解决办法是设置 max-depth，限制依赖图的深度，避免无限展开。

4.3 token 消耗异常排查

token 消耗突然飙升，通常有以下几个原因：

原因一：上下文组装失控。检查每次请求的实际 token 数，看是否接近或超过预算。如果超了，检查组装逻辑是否有 bug，比如去重没生效、压缩没启用。

原因二：记忆检索返回过多。检查 top-K 设置，以及记忆库的规模。如果记忆库太大，检索时可能返回大量低相关度的记录。

原因三：代码地图查询返回过多。检查代码地图查询的返回条数限制。默认是返回 top-10 相关文件，如果项目特别大，可能需要调小。

原因四：代理工具本身的问题。有些代理工具会在后台自动发送额外请求，比如自动补全、自动格式化等。这些请求也会消耗 token，但容易被忽略。检查代理工具的配置，关掉不必要的自动功能。

排查工具：

# 查看最近 100 次请求的 token 消耗 ai-token recent --limit 100 # 找出 token 消耗最高的 10 次请求 ai-token top --limit 10 --order-by total_tokens # 对比不同操作类型的平均 token 消耗 ai-token compare --group-by operation --metric avg_total_tokens

4.4 多工具组合使用的兼容性问题

这套工具链的 9 个仓库虽然设计上可以独立使用，但组合使用时可能会遇到兼容性问题。常见的有：

版本不匹配。不同仓库的版本更新节奏不一样，可能出现 A 仓库依赖 B 仓库的旧版本，但 B 仓库已经升级了接口。解决办法是使用统一的版本管理，或者锁定各仓库的版本号。

配置冲突。多个仓库可能读取同一个配置文件，但配置项名称冲突。解决办法是每个仓库使用独立的配置命名空间，比如memory.xxx、codemap.xxx、token.xxx。

数据格式不一致。比如记忆模块输出的数据格式和上下文组装模块期望的格式不一致。解决办法是定义统一的数据交换格式，各模块之间通过标准格式通信。

实操心得：组合使用时，建议先用最小配置跑通全流程，再逐步增加功能。不要一上来就全功能开启，出了问题很难定位是哪个模块的锅。

5. 工具选型与二次开发建议

5.1 哪些场景适合用这套工具链

这套工具链不是万能的，它有明确的适用场景。

适合的场景：

• 中等规模以上的项目，文件数超过 500 个
• 高频使用 AI 编程代理，每天请求次数超过 50 次
• 对 token 消耗敏感，需要精细化管理和优化
• 有二次开发需求，想基于现有工具搭建自己的工作流

不太适合的场景：

• 小型脚本项目，文件数少于 100 个
• 偶尔使用 AI 编程代理，每天请求次数少于 10 次
• 对 token 消耗不敏感，或者用的是包月不限量的服务
• 完全不想折腾配置，只想开箱即用

如果你属于后者，这套工具链可能会让你觉得“太重了”。但如果你属于前者，它带来的效率提升和成本节约会非常明显。

5.2 二次开发的扩展点

这套工具链设计时就考虑了二次开发的需求，预留了几个扩展点。

扩展点一：自定义记忆存储后端。默认用的是本地文件加 SQLite，如果你想把记忆存到远程数据库或者云存储，可以实现自定义的存储适配器。

扩展点二：自定义代码地图解析器。默认支持主流编程语言，如果你需要支持小众语言，可以实现自定义的语法解析器插件。

扩展点三：自定义 token 计量规则。不同模型的 token 计算方式可能不同，如果你用的模型不在默认支持列表里，可以实现自定义的计量规则。

扩展点四：自定义上下文组装策略。默认的组装策略是通用的，如果你有特定场景的需求，可以实现自定义的组装策略。

扩展点的接口定义在每个仓库的interfaces目录下，文档在docs/extension.md里。二次开发时，建议先读接口定义，再读默认实现，最后写自己的实现。

5.3 性能优化的几个方向

如果你觉得这套工具链跑得不够快，可以从以下几个方向优化。

方向一：缓存。记忆检索和代码地图查询的结果都可以缓存。相同的查询条件，直接返回缓存结果，不用重新计算。我默认开启了 LRU 缓存，缓存大小可配置。

方向二：并行化。记忆检索和代码地图查询是独立的，可以并行执行。我用的是异步 IO，两个查询同时发起，等两个都返回后再组装上下文。这样能把查询时间缩短一半左右。

方向三：增量更新。代码地图的增量更新比全量构建快很多。确保文件监听进程一直在运行，这样代码变更时能及时更新代码地图，查询时不用等。

方向四：本地模型。嵌入向量的生成如果调远程接口，延迟会很高。换成本地模型后，生成速度能提升一个数量级。代价是检索质量可能稍差，需要权衡。

优化前后的对比数据（基于一个 3000 文件的项目）：

这些数据是实测值，具体数字会因项目规模和硬件配置不同而有差异。但优化方向是通用的。

5.4 安全与隐私方面的考虑

最后说一下安全和隐私。这套工具链处理的是你的代码和对话记录，这些都是敏感信息。我的设计原则是默认本地存储，默认不联网。

记忆数据存在本地文件里，代码地图存在本地文件里，token 记账数据存在本地 SQLite 里。除了调用 AI 模型接口本身，工具链不会主动发送任何数据到外部。

如果你用的是远程嵌入模型接口，那记忆检索时会发送记忆内容到远程。这一点需要注意。如果对隐私要求特别高，建议用本地嵌入模型。

另外，token 记账数据里可能包含请求的元信息，比如操作类型、模型名称等。这些信息本身不敏感，但如果你的操作类型命名包含了项目信息，可能会泄露。建议操作类型用通用命名，不要包含具体项目名。

注意：如果你在团队里共享这套工具链的配置和数据，一定要检查记忆数据和代码地图里是否包含敏感信息。我一般建议每个人的记忆数据和代码地图独立存储，不要共享。

这套工具链我陆陆续续写了大半年，踩了不少坑，也积累了一些经验。9 个仓库全部 MIT 协议，你可以自由使用、修改、分发。如果遇到问题，欢迎提 issue，我会尽量回复。如果觉得有用，给个 star 就是最好的支持。

后续我还会继续迭代，重点方向是提升记忆检索的准确性和代码地图的解析覆盖率。如果你有好的想法或者发现了 bug，欢迎一起讨论。