Graft 评测：仓库地图能成为团队资产吗？

Graft 解决的是一个真实问题，而它在社交媒体上流传的那个版本，恰恰在工程负责人最关心的地方说错了。问题确实存在：编码智能体在大多数任务开始时都是盲的，它用 grep 在你的仓库里翻找，把昨天已经建立过的认知重新建立一遍，然后让你为这次重新发现付费。Graft 把这份认知写成互链的 Markdown 节点存到磁盘上，让下一个任务一开始就有方向。

信息流里流传的说法是，这份地图随后会通过 Git 传递，整个团队都能继承它。Graft 自己的文档说的正好相反。在 Graft 官方仓库的 README 中写着，这个图是 "a local, regenerable cache (like node_modules), not something you commit"。graft build 会自动把 graft/ 写进你的 .gitignore，团队里每个人都要自己运行 graft build 生成自己的副本。

这不是缺陷，而是正确的默认设置，而且它改变了你实际在推行的东西：你推行的是一个共同约定加一次廉价的重建，而不是一份共享文档。我们在 2026 年 8 月 18 日审阅该项目后的结论是：在一个仓库里把 Graft 接进来并做实测，但要围绕真正属于版本控制的内容来规划团队故事。本页负责"Graft 评测"和"仓库地图与 Git"这类产品相关的搜索意图。我们的Graphify 评测负责可查询代码库知识图谱的选型问题，而图工程指南负责回答图谱在什么情况下才值得投入。

Graft 是什么？

Graft 是一个采用 MIT 许可的 TypeScript 命令行工具，它把仓库转换成一个由互链 Markdown 节点组成的目录，外加一份按符号组织的代码图，并把这些产物接入你已经在用的智能体。安装只有两条命令，npm install -g @nanonets/graft 和 graft init。它分两层构建，而这两层的区别同时决定了你的成本和你的隐私评审。

有两个设计选择值得单独说，因为它们比基准表格更能说明这个工具的价值。第一，没有向量库：项目自己的描述就是"智能体可以读的文件"，没有服务端、没有数据库、没有嵌入。第二，新鲜度是一个循环而不是一个索引：每次查询都会把工作区与上一次构建的指纹做比对，只重建发生变化的部分，过程是结构化的且不消耗 token，因此答案也能描述尚未提交的改动。

第二点才是真正的工程贡献。一份过期的地图比没有地图更糟，因为智能体会信它。这里也要提前人的工作：Aider 早在 2023 年 10 月就发布了用 tree-sitter 生成、按 PageRank 排序的仓库地图。排序过的仓库地图并不新鲜。新鲜的是刷新循环和面向多种智能体的接线。

Graft 会把仓库地图提交进 Git 吗？

不会，而且你也不应该希望它这样做。通过版本控制传递的是接线：graft init 放进 .claude/ 的文件、AGENTS.md 中带标记的 Graft 段落，以及 MCP 配置。graft/ 下生成的图被 gitignore，并在每个克隆里重建。

我们在这个网站自己的仓库里，以更痛的方式得出了同样的结论。我们在并行的 git worktree 里跑编码智能体，那里生成的图谱输出被有意排除在版本控制之外，因为生成的文件名会在并行分支之间冲突，而机器写出来的文件产生的冲突要耗费评审时间，却带不来任何评审价值。一份提交进版本库的地图还会随着所在分支的推进而变旧，而那恰恰是智能体最可能照它行动的时刻。

所以关于团队收益，诚实的说法比流传的说法更窄，也更有用。Graft 并不会把你的智能体建立起来的认知交给你的同事。它交给同事的是一条两秒钟的命令，从同一个事实来源也就是代码，重建出一份等价的地图。这比一份共享文件更可靠，因为它不会漂移。但这也意味着这是一项推广任务，而不是一项文档任务。

那么什么才该放进 Git？

有用的规则很短：把需要人负责的内容提交进去，把解析器可以重新推导的内容交给重建。生成的结构便宜且能自我纠正。意图两样都不是。

1. 决策与约束。构建与测试命令、智能体不得越过的边界、那个丑陋模块为什么要保持丑陋、哪个接口是契约。AGENTS.md 就是为此存在的，这个格式已被超过 60,000 个开源项目使用，目前由 Linux 基金会下的 Agentic AI Foundation 托管。它由人手写、在 pull request 里评审，值得投入维护。
2. 派生的结构。调用图、符号地图、按重要性排序的文件列表。这些都能重建，所以把它们放进 gitignore，并让重建又快又自动。
3. 不属于代码的组织知识。运行手册、领域规则、带负责人和复核日期的决策。这些属于一个有治理的知识库，那是另一项工程，规则也不同。我们的面向 AI 的公司 Wiki 架构覆盖了这部分。

在这件事上翻车的团队通常朝两个方向之一走。一种是把生成产物提交进去，于是同时继承了合并噪音和自信满满的过期答案。另一种是什么都不写下来，却指望工具推断出从未被记录过的意图。仓库地图无法告诉智能体某张表正在迁移、不能再加列。只有人能。同样的纪律也体现在我们的软件交接清单里，它针对的是同一个问题的人类版本：在知道这件事的人离开之前，哪些内容必须写下来。

Graft 的数据有多可靠？

机制是可信的，而每一个公开数字都来自厂商自己。这样的组合值得一次试点，而不是一次采购决定。Graft 公布了三组独立的测量，它们的强度并不相同。

SWE-bench 那一组最强，因为评分是确定性的。它同时也是最需要仔细读的一组。完整的 SWE-bench Verified 包含 500 个经人工验证的实例，50 个只是其中的十分之一，而报告没有说明是哪十分之一。文中点名讨论的两个实例属于 Django，而一个被广泛使用的 50 实例子集 SWE-bench-verified-mini 只取自 Django 和 Sphinx。这两点都无法说明 Graft 实际抽取了哪些实例，而这个空缺才是值得指出的局限：没有实例清单，这个数字背后的项目和语言覆盖范围就是未知的。在一个未披露构成的 50 实例样本上单轮多解决六个，是一个方向性信号。它不是排行榜位次，也不能证明你的 Kotlin 服务会怎样。

最有操作价值的发现并不在营销的最前面。这组测量还跑了第三种配置：pull，也就是把 Graft 的工具交给智能体，但不预先注入任何内容，只有在需要时才为上下文付费。pull 让出了大部分速度收益，却把正确率提到 98%，而冷启动智能体是 93%。如果做对比做快更重要，那就应该先测这个配置，而它正好与产生头条延迟数字的"预先注入"默认做法相反。

Graft 的真实成本是多少？

没有许可费。免费的部分到此为止，真实预算有四项。

• 结构构建确实免费。tree-sitter 解析、刷新循环和结构类查询从不调用模型。在一个大型仓库里，大部分价值就在这里，而边际成本为零。
• 概念层是一项 token 支出。graft build --deep 用你的密钥为文件和符号生成摘要，并按内容哈希缓存，因此成本取决于代码变动量。要按每位活跃开发者、每个克隆来预算，而不是按每个仓库一次。
• 成熟度也是成本。该项目创建于 2026 年 7 月 3 日，最新标签为 v0.9.0，撰写本文时约有 3,500 个 star 和数十个未关闭的 issue。一个处于智能体上下文路径上的 pre-1.0 依赖，理应像任何构建工具一样锁定版本并验证升级路径。
• 评审时间是最容易被忽略的一项。机器写出的摘要是关于你架构的未评审文字。当智能体照着一个错误摘要行动时，代价由资深工程师在评审里承担。我们的按动作计算成本的框架给出了正确的分母：每个被接受的变更的成本，包含评审分钟数和返工，而不是每次查询省下的 token。

token 是最容易测量、也最不值得优化的东西。这个论点的系统版本在我们的token 预算手册里，它按照保护质量的顺序讲缓存、路由和压缩。

欧盟团队在推广前需要检查什么？

分层的划分刚好与合规问题对应得很整齐。

普通的 graft build 是本地且确定性的，项目声明不发送遥测数据，唯一的网络调用是你自己配置的模型请求。对受监管的工作来说这是一个很强的位置：你获得方向感、符号地图和调用图，而代码没有离开机器。

graft build --deep 是另一个决定。它会把文件和符号内容发送到你指向的供应商，这使该供应商成为你源代码的处理者。请在第一次深度构建之前就把数据处理协议、区域、保留期限和训练用途条款谈定，而不是等到有人已经在支付服务上跑过一遍之后。我们的欧盟数据驻留指南覆盖供应商这一侧，提示前的脱敏覆盖那些测试夹具和日志里带个人数据的仓库。

还有一项控制值得尽早设定：生成的图是对你系统如何拼装起来的一份紧凑且可读的描述。请把它当作源代码对待。它不应该出现在支持包、公开的 CI 产物或工单里的截图中。

Graft、仓库地图还是知识图谱：你要解决哪个问题？

大多数考虑这类工具的团队面对的是五个不同问题之一，而其中只有两个是仓库地图能解决的。

如果你还在判断这些投入是否划算，那就往上一层看。我们关于上下文才是真正瓶颈的分析解释了这个品类为什么存在，而上下文压缩实测报告展示了在我们自己的交付工作而不是厂商表格里，被测量出来的节省是什么样的。

一个能给出结论的两周 Graft 试点

1. 挑一个真让人头疼的仓库。大、多语言、文档差、正在被频繁改动。一个干净的 40 文件服务看不出差别。
2. 在安装任何东西之前先冻结任务集。十个真实的定位与理解类问题，加上五个你已经合并过的变更，回退到它们的基线提交。
3. 跑三组，而不是两组。冷启动、push（预先注入）和 pull（按需提供工具）。厂商自己的数据表明它们在正确性上表现不同。
4. 用测试而不是文件重合度来评判变更。改到正确的文件是很弱的代理指标。你的测试套件才是你本来就信任的评判者。
5. 统计每个被接受的变更的成本。token、墙钟时间、重试和评审分钟数，除以通过评审的变更数。
6. 攻击新鲜度。在工作区脏的状态下、rebase 中途、一次大规模重命名之后，以及在删掉了某个子系统的分支上发起查询。一份自信地说谎的地图是这个品类的主要风险。
7. 有意识地决定深度构建的供应商。把它接到你现有的已批准模型通道上，或者在试点期间关掉概念层，只测量免费的结构层。
8. 检查最终进了 Git 的东西。评审接线的 diff，确认 graft/ 被忽略，并确认没有生成产物混进提交。
9. 锁定版本。然后在试点期间有意升级一次，看看升级的代价是多少。
10. 提前设定放大标准。只有在已验证的正确性或每个被接受变更的成本改善足以支付重建、评审和一个 pre-1.0 依赖时才采用。

两周就够，因为只要有人负责，测量是机械性的。Wavect 的AI 赋能服务会在你的仓库里跑完这套对比，并把测量装置一起交付，让结果不随顾问离开而消失。Twinsoft AI 案例展示了我们在生产工作中如何处理可追溯的 AI 输出与评审者控制。如果你在实施和一份战略文档之间权衡，先比较AI 赋能与通用 AI 咨询，然后告诉我们哪个仓库最让你头疼。

本次研究的边界

状态核查日期为 2026 年 8 月 18 日，依据是 Graft 的公开仓库与项目站点。这是一份独立的架构与采购评测，不是赞助内容，不是安全审计，也不是我们自己对该工具做的受控基准测试。本文引用的每一个性能数字都由厂商公布并由厂商的测量装置评估，其中 SWE-bench 那一组使用了官方评分器。该项目仍处于 pre-1.0 阶段且迭代很快，所以在把它标准化之前请锁定版本并重读当前文档。