我让 AI 编程智能体为我的代码库构建了一张地图，结果是这样的

每当你让 AI 编程助手修复 bug 或解释某项功能的工作原理时，它通常都会从零开始。它会读取文件、到处 grep，并慢慢重建它昨天就已经对你的项目建立好的理解。今天是 2026 年 9 月 2 日，这个问题正受到越来越多的关注，因为如今 AI 编程智能体所承担的自主多步骤工作远超一年前，这意味着在每次会话中“从零开始”的成本在时间和 Token 账单上都会迅速累积。

这正是名为 Graft 的工具试图解决的问题。我在一个真实项目上试用了它，而不是什么玩具式的 demo，我想带你全面了解它的实际功能、发现了什么，以及它的不足之处。

Graft 究竟是什么

可以把 Graft 想象成你代码的图书管理员。AI 智能体不必在每次需要理解某些内容时漫无目的地穿梭于各个文件夹之间，Graft 只需构建一次索引：一个由相互链接的小型文本文件组成的文件夹，用于描述代码各部分的作用、哪些函数调用了哪些其他函数，以及所有内容是如何关联在一起的。

它通过两个层次来实现这一点：

1. 一个 结构图，基于名为 tree-sitter 的代码解析技术构建。这一层完全不需要任何 AI 模型。它只是像编译器一样读取你的代码，并提取函数名称、类以及它们之间的关联。
2. 一个可选的 概念层，它使用 AI 模型以通俗易懂的语言编写代码各部分用途的摘要。这部分运行需要调用 AI 模型，因而会产生费用，所以是可选择性开启的。

最关键的部分在于：第一层，也就是绘制整个代码库地图的那一层，完全免费且不需要 API 密钥。它完全在本地解析你的文件。

为什么我决定在真实项目上测试它

我在同一个仓库中跨多个真实代码库工作：一个用 Kotlin 编写的 Android 应用、一个采用现代 Web 框架构建的网站、几个小型后端服务，以及一些用于处理琐碎任务的 Python 脚本。其中一个代码库，也就是那个 Android 应用，有一个单文件已经膨胀到了三千多行，因为新功能不断被生搬硬套地塞进去，而不是进行合理的拆分。这在实际软件项目中极为普遍。每个人都打算“以后”再重构，而“以后”却一拖再拖。

在改动这样的文件之前，你肯定想确切搞清楚到底谁依赖谁，以免一个小小的改动悄无声息地破坏掉相隔三个屏幕之外的功能。这正是 Graft 旨在解答的问题，因此这感觉是一次公正、真实的检验。

安装与配置

第 1 步：安装工具

Graft 作为轻量级命令行程序进行安装，类似于在机器上全局安装任何开发者工具：

npm install -g @nanonets/graft

第 2 步：预览将要更改的内容

在将任何内容接入项目之前，你可以让它准确展示会创建或修改哪些文件，此时它不会触碰任何现有内容：

graft init --dry-run

这打印出了一个简短的列表：几个用于 AI 编程助手的配置文件、一个 skill 文件，以及一个存放所生成图谱本身的文件夹。在做出实质性变更前能看到这个列表，说明该工具尊重你的项目，这是一个好迹象。

第 3 步：运行它，范围仅限当前项目

类似的某些工具还想写入全局配置，从而影响你机器上的每一个项目，而不仅仅是你当前正在处理的项目。我并不希望这样，所以我使用了一个参数标志来让所有内容保持在本地：

graft init --no-global -y

它解析了项目中的每个真实源文件（就我而言，涵盖 Kotlin、TypeScript、JavaScript 和 Python 的 77 个文件），并在几秒钟内构建出了一个包含 561 个独立代码片段以及它们之间 1,229 个连接关系的图谱，全程无需任何 AI 模型参与，完全零成本。

投入实际使用

有趣的事情发生了。我让 Graft 生成全仓库的导向地图，它立刻标出了那个庞大的 Android 文件中的一个函数是整个项目中最被依赖的代码片段，有其他十处地方都调用了它。

接着我问了一个更具针对性的问题：如果我修改那个函数，显示出会受到影响的所有内容。Graft 追踪了整条链路：每个页面、每个辅助文件，以及该函数行为会波及到的每一个地方，瞬间完成且完全免费。

如果通过手动阅读代码，或者让 AI 助手到处 grep 检索所有内容来获取相同的答案，意味着需要读取大约 200,000 个 Token 的文件内容。Graft 自带的统计工具显示，通过复用图谱，它节省了如此之多的消耗。按照目前中端 Claude 模型的定价，单次交互就能节省大约 40 美分。这听起来可能不多，但每当有人（无论是人类还是 AI）对该代码库提出类似问题时，这种节省都会重复出现，而这正是真正积累价值的地方。

我不太满意的地方

它的体验并非毫无阻碍。一旦接入，Graft 会安装一个在每次向 AI 编程助手发送消息时都会运行的 hook，检查图谱是否能提供相关信息。在两次不同的情况下，当我提出与代码毫无关系的普通闲聊问题时，它依然插话建议去查看图谱。尝试去提供帮助并没有错，但在那些对话轮次中确实造成了不必要的干扰。

同时需要清醒认识到的是，这是一款非常新的工具。在撰写本文前仅仅几个月它才首次发布，而在这么短的时间内它就已经经历了数十次小版本迭代。这种演进速度令人兴奋，但也意味着它并未像那些成熟的开发者工具那样经历过数年真实生产环境的严苛检验。

总结

Graft 解决了与 AI 编程助手协作时一个真实且常见的痛点：在不同会话之间不断重新发现那些从未改变过的代码。在一个真正杂乱、涉及多种语言的项目上，它仅仅依靠本地解析，就在数秒内免费给出了准确且有价值的答案。它并非魔法，也确实给你的工作流程带来了一些多余的插话，但作为在修改代码前帮助 AI 助手理解代码库的基础工具，它确实证明了自己的价值。

优点

• 数秒内构建多语言代码库的完整地图，核心功能无需任何 AI 模型
• 结构图谱完全离线运行，零使用成本
• 能够追踪变更的完整“爆炸半径”，即依赖于你即将编辑的代码的所有内容
• 可将范围限制在单个项目内，不会触碰其他项目的设置
• 自动将生成的数据排除在版本控制之外，避免搞乱共享代码仓库
• 在同一个项目中同时支持多种编程语言

缺点

• 安装的 hook 会在每条消息发送时运行，在与代码无关的对话中可能会让人感觉受到干扰
• 属于非常新的软件，至今实际应用记录较短
• 更深层次的 AI 摘要层仍需你自己提供 AI 模型访问权限，且开启后会产生费用
• 安装配置会涉及项目中的多个配置文件，因此在确认接受之前值得仔细检查写入的内容

注意事项

本文旨在提供参考借鉴，仅反映个人在特定时间点对特定工具的实际使用体验。此处提及的任何命令、数据或版本细节都可能随着工具的演进而发生变化，因此在自行安装前请务必查阅该工具的官方文档。如果你在共享项目上试用，请先检查它提议创建或修改的每个文件，切勿仅仅因为他人使用体验良好就认为新的开发者工具毫无风险。

常见问题解答

• 什么是 Graft？ — 这是一款能够在本地构建代码库关联地图的工具，让 AI 编程助手（以及开发者）可以快速理解代码库，而无需每次都从零开始重新探索。
• 它需要 AI 模型才能工作吗？ — 不需要。它的核心功能（即代码的结构图谱）利用代码解析技术完全离线运行。可选的更深层次确实会使用 AI 模型，但那部分并不是必需的。
• 在现有项目上安装安全吗？ — 在同意任何操作之前，你可以准确预览它会创建或更改的内容，这是在采用任何新开发者工具前非常合理的安全检查手段。
• 它在同一个项目中能支持多种编程语言吗？ — 可以，在我的测试中，它在同一次运行中同时解析了多种语言，包括一种编译型移动应用语言和几种 Web 脚本语言。
• 它会影响同一台电脑上的其他项目吗？ — 只有在你允许的情况下才会。它提供了一个设置项，可以将所有内容限定在单个项目文件夹内。
• 在小型、简单的项目上值得使用吗？ — 可能没那么必要。它的收益随着代码库的规模和复杂混乱程度而增加，尤其是那些积累了大量历史改动的庞大文件。
• 生成的地图需要提交到版本控制中吗？ — 不需要，它被设计为在本地重新生成，通常会自动从版本控制中排除。
• 它最大的缺点是什么？ — 在每条消息上都会进行检查的 hook，这在与代码无关的对话中可能会让人觉得是多余的干扰。

标签

#ai #developertools #codingagents #productivity #softwareengineering #devtools #automation #codereview #techtools #programming