--- title: "Graft 评测 2026：智能体仓库地图与 Git" canonical: https://wavect.io/zh/blog/graft-review-agent-repo-map/ language: zh description: "面向技术负责人的 Graft 评测：为什么仓库地图被 gitignore、基准测试到底证明了什么、深度构建的真实成本，以及两周试点计划。" image: "https://wavect.io/img/blog/headers/header_graft-review-agent-repo-map.png" --- [**返回**](/zh/blog/overview/) [![Kevin Riedl](/img/team/kevin.webp)](/zh/team/kevin-riedl/) [Kevin Riedl](/zh/team/kevin-riedl/) https://linkedin.com/in/wsdt 11 分钟 阅读 · 2026年8月18日 最近审核 2026年8月18日 [**下一篇**](/zh/blog/graphify-review-codebase-knowledge-graph/) # Graft 评测：仓库地图能成为团队资产吗？ 要点速览 Graft 是一个采用 MIT 许可的 npm 命令行工具，它把仓库写成互链的 Markdown 节点以及按符号组织的代码图， 让编码智能体在任务开始时就已经有方向，而不必从零开始逐个搜索文件。对团队来说，有两点是决定性的。第一，这份地图并不通过 Git 共享：graft build 会自动把 graft/ 写进.gitignore，每位同事都在本地重建自己的副本，因此热帖中关于地图会随仓库一起 传递的说法并不成立。真正提交进版本库的只有.claude/ 里的接线文件、AGENTS.md 中带标记的段落以及 MCP 配置。这个默认设置 是对的，因为生成文件会在并行分支之间冲突，而一份被提交的地图在分支变动的那一刻就开始说谎。第二，所有公开的性能数字都来自 厂商自己：在两个仓库上跑的 162 次对比，其中一个仓库就是 Graft 本身，正确性由 LLM 评审打分；另有 50 个 SWE-bench Verified 实例，解决数为 33 对 27，只跑了一轮且没有报告方差。机制可信，但不足以作为采购依据。结构层是确定性的 tree-sitter，不需要密钥也不联网；而 graft build --deep 会把文件和符号内容发送到你配置的模型供应商，这正是欧盟团队必须 审查的部分。把需要人负责的内容提交进 Git，把解析器可以重新推导的内容交给重建，并用每个被接受的变更的成本而不是省下的 token 来评估两周试点。事实核查日期：2026 年 8 月 18 日。 **Graft 解决的是一个真实问题，而它在社交媒体上流传的那个版本，恰恰在工程负责人最关心的地方说错了。**问题确实存在：编码智能体在大多数任务开始时都是盲的，它用 grep 在你的仓库里翻找，把昨天已经建立过的认知重新建立一遍，然后让你为这次重新发现付费。Graft 把这份认知写成互链的 Markdown 节点存到磁盘上，让下一个任务一开始就有方向。 信息流里流传的说法是，这份地图随后会通过 Git 传递，整个团队都能继承它。Graft 自己的文档说的正好相反。在 [Graft 官方仓库](https://github.com/NanoNets/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 评测](/zh/blog/graphify-review-codebase-knowledge-graph/) 负责可查询代码库知识图谱的选型问题，而 [图工程指南](/zh/blog/graph-engineering-ai-agents/) 负责回答图谱在什么情况下才值得投入。 ## Graft 是什么？ **Graft 是一个采用 MIT 许可的 TypeScript 命令行工具，它把仓库转换成一个由互链 Markdown 节点组成的目录，外加一份按符号组织的代码图，并把这些产物接入你已经在用的智能体。**安装只有两条命令，`npm install -g @nanonets/graft` 和 `graft init`。它分两层构建，而这两层的区别同时决定了你的成本和你的隐私评审。 | 层级 | 产出什么 | 模型与密钥 | | --- | --- | --- | | 结构层 | 按符号的接线图、按文件的说明卡、覆盖 21 种语言的调用与引用边 | 确定性的 tree-sitter。不用模型，不用密钥，不联网 | | 概念层（`graft build --deep`） | 自然语言的文件摘要、综合出的概念节点、每个符号的摘要与关键片段 | 你的供应商、你的密钥、你的模型。按内容哈希缓存 | | 查询接口 | `ask`、`grep`、`callers`、`skeleton`、`map`、`check`，以及六个 MCP 工具 | 结构类查询无需模型也无需密钥 | | 智能体接线 | Claude Code 的技能文件、`AGENTS.md` 中带标记的段落，以及 Cursor、Copilot、Gemini、Kiro、Windsurf 的规则文件 | 由 `graft init` 写入，采用合并而非覆盖 | 有两个设计选择值得单独说，因为它们比基准表格更能说明这个工具的价值。第一，没有向量库： [项目自己的描述](https://graft.nanonets.ai/) 就是"智能体可以读的文件"，没有服务端、没有数据库、没有嵌入。第二，新鲜度是一个循环而不是一个索引：每次查询都会把工作区与上一次构建的指纹做比对，只重建发生变化的部分，过程是结构化的且不消耗 token，因此答案也能描述尚未提交的改动。 第二点才是真正的工程贡献。一份过期的地图比没有地图更糟，因为智能体会信它。这里也要提前人的工作： [Aider 早在 2023 年 10 月就发布了用 tree-sitter 生成、按 PageRank 排序的仓库地图](https://aider.chat/2023/10/22/repomap.html) 。排序过的仓库地图并不新鲜。新鲜的是刷新循环和面向多种智能体的接线。 ## Graft 会把仓库地图提交进 Git 吗？ **不会，而且你也不应该希望它这样做。**通过版本控制传递的是接线：`graft init` 放进 `.claude/` 的文件、`AGENTS.md` 中带标记的 Graft 段落，以及 MCP 配置。`graft/` 下生成的图被 gitignore，并在每个克隆里重建。 | 产物 | 是否随 Git 传递 | 由谁重建 | 处理错了会怎样 | | --- | --- | --- | --- | | 智能体接线与技能文件 | 是，提交并评审 | 人，在 pull request 里 | 一半团队按另一套智能体约定工作 | | `AGENTS.md` 里手写的约定 | 是，提交并评审 | 人，有意识地写 | 每个提示词都要重述构建与测试规则 | | `graft/` 下的结构图 | 否，默认被 gitignore | 每个克隆，几秒钟，免费 | 生成文件产生合并冲突，地图在某个分支上开始说谎 | | `--deep` 生成的概念摘要 | 否，同一份缓存 | 持有供应商密钥的人 | 关于你系统的未评审文字，没人负责 | | 单次会话的临时上下文 | 否 | 没人，会被丢弃 | 把会话记录当成文档 | 我们在这个网站自己的仓库里，以更痛的方式得出了同样的结论。我们在并行的 git worktree 里跑编码智能体，那里生成的图谱输出被有意排除在版本控制之外，因为生成的文件名会在并行分支之间冲突，而机器写出来的文件产生的冲突要耗费评审时间，却带不来任何评审价值。一份提交进版本库的地图还会随着所在分支的推进而变旧，而那恰恰是智能体最可能照它行动的时刻。 所以关于团队收益，诚实的说法比流传的说法更窄，也更有用。Graft 并不会把你的智能体建立起来的认知交给你的同事。它交给同事的是一条两秒钟的命令，从同一个事实来源也就是代码，重建出一份等价的地图。这比一份共享文件更可靠，因为它不会漂移。但这也意味着这是一项推广任务，而不是一项文档任务。 ## 那么什么才该放进 Git？ 有用的规则很短：**把需要人负责的内容提交进去，把解析器可以重新推导的内容交给重建。**生成的结构便宜且能自我纠正。意图两样都不是。 1. **决策与约束。** 构建与测试命令、智能体不得越过的边界、那个丑陋模块为什么要保持丑陋、哪个接口是契约。 [AGENTS.md](https://agents.md/) 就是为此存在的，这个格式已被超过 60,000 个开源项目使用，目前由 Linux 基金会下的 Agentic AI Foundation 托管。它由人手写、在 pull request 里评审，值得投入维护。 2. **派生的结构。** 调用图、符号地图、按重要性排序的文件列表。这些都能重建，所以把它们放进 gitignore，并让重建又快又自动。 3. **不属于代码的组织知识。** 运行手册、领域规则、带负责人和复核日期的决策。这些属于一个有治理的知识库，那是另一项工程，规则也不同。我们的 [面向 AI 的公司 Wiki 架构](/zh/blog/ai-ready-company-wiki/) 覆盖了这部分。 在这件事上翻车的团队通常朝两个方向之一走。一种是把生成产物提交进去，于是同时继承了合并噪音和自信满满的过期答案。另一种是什么都不写下来，却指望工具推断出从未被记录过的意图。仓库地图无法告诉智能体某张表正在迁移、不能再加列。只有人能。同样的纪律也体现在我们的 [软件交接清单](/zh/software-development-guide/software-handover-checklist/) 里，它针对的是同一个问题的人类版本：在知道这件事的人离开之前，哪些内容必须写下来。 ## Graft 的数据有多可靠？ **机制是可信的，而每一个公开数字都来自厂商自己。**这样的组合值得一次试点，而不是一次采购决定。Graft 公布了三组独立的测量，它们的强度并不相同。 | 测量 | 报告结果 | 它能支持什么 | 它到哪里为止 | | --- | --- | --- | --- | | 162 次受控运行，Claude Sonnet 5，两个仓库，每个任务三轮 | token 从 8,070 降到 4,650，工具调用从 4.2 降到 2.3，延迟从 39.8 秒降到 15.8 秒，成本从 0.0429 降到 0.0292，两组正确率同为 93% | 效率机制：有方向的智能体搜索得更少 | 任务是问答而不是改代码；两个仓库中的一个就是 Graft 本身；正确性由带关键词门槛的 Opus 4.8 评审给出 | | SWE-bench Verified，50 个实例，官方 `swebench` 4.1.0 评分器 | 解决 33/50 对 27/50，同时少用 23% 的 token 和 32% 的墙钟时间 | 真实的正确性，由维护者自己的测试而非模型来评判 | 只用了 500 个已验证实例中的 50 个，差距为六个实例，单轮运行，未报告方差 | | PocketBase，15 个任务，Claude Opus，无界面运行，同一提交的两个克隆 | 成本从 13.91 美元降到 11.02 美元，墙钟从 2,044 秒降到 1,762 秒，5 个已合并 PR 全部复现 | 在厂商无法控制的真实第三方代码库上的表现 | PR 的评分标准是是否改动了与维护者相同的文件，这与通过他们的测试并不等价 | SWE-bench 那一组最强，因为评分是确定性的。它同时也是最需要仔细读的一组。完整的 [SWE-bench Verified](https://www.swebench.com/verified.html) 包含 500 个经人工验证的实例，50 个只是其中的十分之一，而报告没有说明是哪十分之一。文中点名讨论的两个实例属于 Django，而一个被广泛使用的 50 实例子集 [SWE-bench-verified-mini](https://huggingface.co/datasets/MariusHobbhahn/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 依赖，理应像任何构建工具一样锁定版本并验证升级路径。 - **评审时间是最容易被忽略的一项。** 机器写出的摘要是关于你架构的未评审文字。当智能体照着一个错误摘要行动时，代价由资深工程师在评审里承担。我们的 [按动作计算成本的框架](/zh/blog/ai-agent-cost-per-action-2026/) 给出了正确的分母：每个被接受的变更的成本，包含评审分钟数和返工，而不是每次查询省下的 token。 token 是最容易测量、也最不值得优化的东西。这个论点的系统版本在我们的 [token 预算手册](/zh/blog/smarter-token-usage-with-your-ai-coding-agent/) 里，它按照保护质量的顺序讲缓存、路由和压缩。 ## 欧盟团队在推广前需要检查什么？ 分层的划分刚好与合规问题对应得很整齐。 普通的 `graft build` 是本地且确定性的，项目声明不发送遥测数据，唯一的网络调用是你自己配置的模型请求。对受监管的工作来说这是一个很强的位置：你获得方向感、符号地图和调用图，而代码没有离开机器。 `graft build --deep` 是另一个决定。它会把文件和符号内容发送到你指向的供应商，这使该供应商成为你源代码的处理者。请在第一次深度构建之前就把数据处理协议、区域、保留期限和训练用途条款谈定，而不是等到有人已经在支付服务上跑过一遍之后。我们的 [欧盟数据驻留指南](/zh/blog/eu-data-residency-ai-apps-2026/) 覆盖供应商这一侧， [提示前的脱敏](/zh/blog/pii-redaction-before-llm-prompts/) 覆盖那些测试夹具和日志里带个人数据的仓库。 还有一项控制值得尽早设定：生成的图是对你系统如何拼装起来的一份紧凑且可读的描述。请把它当作源代码对待。它不应该出现在支持包、公开的 CI 产物或工单里的截图中。 ## Graft、仓库地图还是知识图谱：你要解决哪个问题？ 大多数考虑这类工具的团队面对的是五个不同问题之一，而其中只有两个是仓库地图能解决的。 | 你真正的问题 | 从哪里开始 | 为什么 | | --- | --- | --- | | 智能体在每个任务里重复探索同一个仓库 | 像 Graft 这样的仓库地图 | 方向感被预先算好并按结构刷新，搜索不再是主要成本 | | 你需要跨代码、schema、基础设施和文档的带类型可查询关系 | [代码库知识图谱评测](/zh/blog/graphify-review-codebase-knowledge-graph/) | 跨混合来源的多跳问题是图谱型负载，不是文件地图 | | 问题是 token 账单，而不是检索 | [工具输出压缩](/zh/blog/codag-cost-control/) | 过大的工具输出和重试循环往往在上下文设计之前就已主导支出 | | 缺的是代码库之外的公司知识 | [面向 AI 的公司 Wiki](/zh/blog/ai-ready-company-wiki/) | 权限、来源与复核循环才是难点，任何代码解析器都提供不了 | | 智能体不遵守你的约定 | [智能体技能与指令](/zh/blog/ai-writing-agent-skills/) | 意图必须由人来写；没有任何地图能推断出从未被记录的规则 | 如果你还在判断这些投入是否划算，那就往上一层看。我们关于 [上下文才是真正瓶颈](/zh/blog/ai-coding-agents-context-not-intelligence/) 的分析解释了这个品类为什么存在，而 [上下文压缩实测报告](/zh/blog/lean-ctx-agency-experience/) 展示了在我们自己的交付工作而不是厂商表格里，被测量出来的节省是什么样的。 ## 一个能给出结论的两周 Graft 试点 1. **挑一个真让人头疼的仓库。** 大、多语言、文档差、正在被频繁改动。一个干净的 40 文件服务看不出差别。 2. **在安装任何东西之前先冻结任务集。** 十个真实的定位与理解类问题，加上五个你已经合并过的变更，回退到它们的基线提交。 3. **跑三组，而不是两组。** 冷启动、push（预先注入）和 pull（按需提供工具）。厂商自己的数据表明它们在正确性上表现不同。 4. **用测试而不是文件重合度来评判变更。** 改到正确的文件是很弱的代理指标。你的测试套件才是你本来就信任的评判者。 5. **统计每个被接受的变更的成本。** token、墙钟时间、重试和评审分钟数，除以通过评审的变更数。 6. **攻击新鲜度。** 在工作区脏的状态下、rebase 中途、一次大规模重命名之后，以及在删掉了某个子系统的分支上发起查询。一份自信地说谎的地图是这个品类的主要风险。 7. **有意识地决定深度构建的供应商。** 把它接到你现有的已批准模型通道上，或者在试点期间关掉概念层，只测量免费的结构层。 8. **检查最终进了 Git 的东西。** 评审接线的 diff，确认 `graft/` 被忽略，并确认没有生成产物混进提交。 9. **锁定版本。** 然后在试点期间有意升级一次，看看升级的代价是多少。 10. **提前设定放大标准。** 只有在已验证的正确性或每个被接受变更的成本改善足以支付重建、评审和一个 pre-1.0 依赖时才采用。 两周就够，因为只要有人负责，测量是机械性的。Wavect 的 [AI 赋能服务](/zh/services/ai-enablement/) 会在你的仓库里跑完这套对比，并把测量装置一起交付，让结果不随顾问离开而消失。 [Twinsoft AI 案例](/zh/case-studies/twinsoft-ai/) 展示了我们在生产工作中如何处理可追溯的 AI 输出与评审者控制。如果你在实施和一份战略文档之间权衡，先比较 [AI 赋能与通用 AI 咨询](/zh/compare/ai-enablement-vs-generic-ai-consultancy/) ，然后 [告诉我们哪个仓库最让你头疼](/zh/contact/) 。 ## 常见问题 ### Graft 会把仓库地图提交进 Git 吗？ 不会。README 写明这个图是像 node_modules 那样的本地可重建缓存，不是需要提交的东西，而且 graft build 会自动把 graft/ 加入.gitignore。被提交的是 graft init 写进.claude/ 的接线文件、AGENTS.md 中带标记的段落以及 MCP 配置。团队里每个人都用 graft build 生成自己的图。 ### Graft 免费吗？ 软件采用 MIT 许可，因此没有许可费。结构构建、刷新循环和结构类查询从不调用模型，每次运行都不产生费用。可选的概念层 graft build --deep 会用你自己的供应商密钥消耗 token。 ### Graft 需要 API 密钥吗？ 结构图不需要。graft build、graft check、graft ask、graft grep、graft callers、graft skeleton 和 graft map 都是确定性的 tree-sitter 操作，不需要密钥也不需要网络。只有写出自然语言摘要和概念节点的 graft build --deep 才需要供应商密钥。 ### Graft 使用嵌入或向量数据库吗？ 不使用。项目明确把自己描述为智能体可以读的文件，没有服务端、没有数据库、没有嵌入。检索依靠对 Markdown 节点和按符号代码图的排序与链接跳转，而不是相似度搜索。 ### 除了 Claude Code，Graft 也能用于其他智能体吗？ 可以。graft init 会检测并接入 Claude Code、Cursor、GitHub Copilot、通过 AGENTS.md 接入的 Codex、Gemini、Kiro、Windsurf 等，同时还提供一个带六个工具的 MCP 服务器。Claude Code 通过 hooks、状态栏和自动同步获得最深的集成。 ### Graft 在 SWE-bench Verified 上的 66% 能和排行榜数字相比吗？ 把它当作方向性的自测对比。它只覆盖 500 个已验证实例中的 50 个，报告没有说明是哪 50 个，因此这个数字背后的项目和语言覆盖范围是未知的，差距是单轮运行中的六个实例且未报告方差。评分本身是可信的，因为它使用官方 swebench 评分器而不是模型评审。 ### 应该一个人用 Graft 还是整个团队用？ 要么整个团队接入，要么就不要用。因为图是在每个克隆里重建的，单个人私下使用既产生不了共享收益，也产生不了可比数据。把接线提交进版本库，就深度层是否允许达成一致，并在团队范围内衡量每个被接受变更的成本。 ## 本次研究的边界 *状态核查日期为 2026 年 8 月 18 日，依据是 Graft 的公开仓库与项目站点。这是一份独立的架构与采购评测，不是赞助内容，不是安全审计，也不是我们自己对该工具做的受控基准测试。本文引用的每一个性能数字都由厂商公布并由厂商的测量装置评估，其中 SWE-bench 那一组使用了官方评分器。该项目仍处于 pre-1.0 阶段且迭代很快，所以在把它标准化之前请锁定版本并重读当前文档。* ## 最终思考 Graft 是对一个被错误表述的问题给出的好答案。编码智能体确实在每个任务之后就丢掉了昂贵获得的理解，而用一个廉价的结构化刷新循环把这份理解写到磁盘上，是一个稳妥的解法。公开的数字方向是对的，而其中最有分量的那组，即在官方 SWE-bench 评分器下跑出来的结果，仍然只是 50 个实例的单轮评分。 团队故事才是流行版本说法崩塌的地方。这份地图是可重建的缓存，不是共享产物，而这恰恰是正确的设计。你的团队通过 Git 继承到的是接线，加上你的工程师有多少纪律把意图写了下来。因为重建循环而采用这个工具，把责任留在被评审的文件里，并用每个被接受变更的成本而不是省下的 token 来评价整件事。 ## 你可能也喜欢.. [**Graphify 评测：代码库知识图谱值得吗？** 仓库地图之外的可查询图谱路线，有它自己的基准边界和落地成本。](/zh/blog/graphify-review-codebase-knowledge-graph/) [**瓶颈从来不是智能** 为什么上下文而不是模型能力才是智能体工具竞相解决的约束。](/zh/blog/ai-coding-agents-context-not-intelligence/) 智能体工程 ## 继续浏览此集群 编程智能体、MCP、上下文系统、评估与可靠自动化控制。 [从核心文章开始**AI 智能体的图工程：知识图谱什么时候值得做？**](/zh/blog/graph-engineering-ai-agents/) - [智能体可读的网站：llms.txt、Markdown 镜像，以及会坏在哪里](/zh/blog/agent-readable-website-llms-txt-markdown-mirrors/) - [本地化 URL 会搞坏 hreflang：只保留一个英文 slug](/zh/blog/english-slugs-vs-localized-urls-hreflang/) - [AI 智能体能用你的产品，还是只能读到它？](/zh/blog/can-an-ai-agent-use-your-product/) - [通过工具输出压缩降低编码代理成本](/zh/blog/codag-cost-control/) - [用 AI 编码智能体更聪明地管理 Token](/zh/blog/smarter-token-usage-with-your-ai-coding-agent/) 只收重要内容 ## 关注与你相关的内容 每当我们发布新文章，你会收到一封简短邮件。你可以关注整个博客，也可以只选感兴趣的主题。 [**返回**](/zh/blog/overview/) [![Kevin Riedl](/img/team/kevin.webp)](/zh/team/kevin-riedl/) [Kevin Riedl](/zh/team/kevin-riedl/) https://linkedin.com/in/wsdt 11 分钟 阅读 · 2026年8月18日 最近审核 2026年8月18日 [**下一篇**](/zh/blog/graphify-review-codebase-knowledge-graph/) 邮件订阅新文章 × × 通过邮件获取新文章 我们发布时给你一封简短邮件。免费，不做跟踪。 ## Structured Data ```json { "@context": "https://schema.org", "@graph": [ { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ], "employee": [ { "@id": "https://wavect.io/team/kevin-riedl/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Kevin Riedl", "url": "https://wavect.io/team/kevin-riedl/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } }, { "@id": "https://wavect.io/team/christof-jori/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Christof Jori", "url": "https://wavect.io/team/christof-jori/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } } ], "founder": [ { "@id": "https://wavect.io/team/kevin-riedl/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Kevin Riedl", "url": "https://wavect.io/team/kevin-riedl/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } }, { "@id": "https://wavect.io/team/christof-jori/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Christof Jori", "url": "https://wavect.io/team/christof-jori/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } } ], "legalRepresentative": [ { "@id": "https://wavect.io/team/kevin-riedl/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Kevin Riedl", "url": "https://wavect.io/team/kevin-riedl/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } }, { "@id": "https://wavect.io/team/christof-jori/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Christof Jori", "url": "https://wavect.io/team/christof-jori/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } } ], "name": "Wavect GmbH", "subjectOf": { "@id": "https://wavect.io/verified-claims.json#dataset", "@type": "Dataset", "creator": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] }, "description": "A machine-readable registry of quantitative and qualitative claims published by Wavect, with review dates, localized page appearances and public third-party citations where available.", "inLanguage": "en", "isAccessibleForFree": true, "license": "https://creativecommons.org/licenses/by/4.0/", "name": "Wavect verified publication claims", "url": "https://wavect.io/verified-claims.json" }, "url": "https://wavect.io/" }, { "@id": "https://wavect.io/team/kevin-riedl/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Kevin Riedl", "sameAs": [ "https://www.wikidata.org/wiki/Q139796365", "https://www.linkedin.com/in/wsdt", "https://github.com/wsdt" ], "url": "https://wavect.io/team/kevin-riedl/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } }, { "@id": "https://wavect.io/team/christof-jori/#person", "@type": "Person", "jobTitle": "Managing Director", "name": "Christof Jori", "sameAs": [ "https://www.wikidata.org/wiki/Q139796367", "https://www.linkedin.com/in/jocr77/", "https://github.com/jo-chris" ], "url": "https://wavect.io/team/christof-jori/", "worksFor": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] } }, { "@id": "https://wavect.io/#website", "@type": "WebSite", "inLanguage": [ "en", "de", "es", "zh" ], "name": "Wavect", "potentialAction": { "@type": "SearchAction", "query-input": "required name=search_term_string", "target": { "@type": "EntryPoint", "urlTemplate": "https://wavect.io/search/?q={search_term_string}" } }, "publisher": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] }, "url": "https://wavect.io/" }, { "@id": "https://wavect.io/zh/blog/graft-review-agent-repo-map/#webpage", "@type": "WebPage", "dateModified": "2026-08-18", "inLanguage": "zh", "isPartOf": { "@id": "https://wavect.io/#website", "@type": "WebSite" }, "lastReviewed": "2026-08-18", "url": "https://wavect.io/zh/blog/graft-review-agent-repo-map/" } ] } ``` ```json { "@context": "https://schema.org", "@type": "BlogPosting", "abstract": "Graft 是一个采用 MIT 许可的 npm 命令行工具，它把仓库写成互链的 Markdown 节点以及按符号组织的代码图， 让编码智能体在任务开始时就已经有方向，而不必从零开始逐个搜索文件。对团队来说，有两点是决定性的。第一，这份地图并不通过 Git 共享：graft build 会自动把 graft/ 写进 .gitignore，每位同事都在本地重建自己的副本，因此热帖中关于地图会随仓库一起 传递的说法并不成立。真正提交进版本库的只有 .claude/ 里的接线文件、AGENTS.md 中带标记的段落以及 MCP 配置。这个默认设置 是对的，因为生成文件会在并行分支之间冲突，而一份被提交的地图在分支变动的那一刻就开始说谎。第二，所有公开的性能数字都来自 厂商自己：在两个仓库上跑的 162 次对比，其中一个仓库就是 Graft 本身，正确性由 LLM 评审打分；另有 50 个 SWE-bench Verified 实例，解决数为 33 对 27，只跑了一轮且没有报告方差。机制可信，但不足以作为采购依据。结构层是确定性的 tree-sitter，不需要密钥也不联网；而 graft build --deep 会把文件和符号内容发送到你配置的模型供应商，这正是欧盟团队必须 审查的部分。把需要人负责的内容提交进 Git，把解析器可以重新推导的内容交给重建，并用每个被接受的变更的成本而不是省下的 token 来评估两周试点。事实核查日期：2026 年 8 月 18 日。", "articleBody": " 博客概览/AI 与智能体/智能体工程 Graft 评测：仓库地图能成为团队资产吗？ 要点速览 Graft 是一个采用 MIT 许可的 npm 命令行工具，它把仓库写成互链的 Markdown 节点以及按符号组织的代码图， 让编码智能体在任务开始时就已经有方向，而不必从零开始逐个搜索文件。对团队来说，有两点是决定性的。第一，这份地图并不通过 Git 共享：graft build 会自动把 graft/ 写进 .gitignore，每位同事都在本地重建自己的副本，因此热帖中关于地图会随仓库一起 传递的说法并不成立。真正提交进版本库的只有 .claude/ 里的接线文件、AGENTS.md 中带标记的段落以及 MCP 配置。这个默认设置 是对的，因为生成文件会在并行分支之间冲突，而一份被提交的地图在分支变动的那一刻就开始说谎。第二，所有公开的性能数字都来自 厂商自己：在两个仓库上跑的 162 次对比，其中一个仓库就是 Graft 本身，正确性由 LLM 评审打分；另有 50 个 SWE-bench Verified 实例，解决数为 33 对 27，只跑了一轮且没有报告方差。机制可信，但不足以作为采购依据。结构层是确定性的 tree-sitter，不需要密钥也不联网；而 graft build --deep 会把文件和符号内容发送到你配置的模型供应商，这正是欧盟团队必须 审查的部分。把需要人负责的内容提交进 Git，把解析器可以重新推导的内容交给重建，并用每个被接受的变更的成本而不是省下的 token 来评估两周试点。事实核查日期：2026 年 8 月 18 日。 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。它分两层构建，而这两层的区别同时决定了你的成本和你的隐私评审。 层级产出什么模型与密钥 结构层按符号的接线图、按文件的说明卡、覆盖 21 种语言的调用与引用边确定性的 tree-sitter。不用模型，不用密钥，不联网 概念层（graft build --deep）自然语言的文件摘要、综合出的概念节点、每个符号的摘要与关键片段你的供应商、你的密钥、你的模型。按内容哈希缓存 查询接口ask、grep、callers、skeleton、map、check，以及六个 MCP 工具结构类查询无需模型也无需密钥 智能体接线Claude Code 的技能文件、AGENTS.md 中带标记的段落，以及 Cursor、Copilot、Gemini、Kiro、Windsurf 的规则文件由 graft init 写入，采用合并而非覆盖 有两个设计选择值得单独说，因为它们比基准表格更能说明这个工具的价值。第一，没有向量库：项目自己的描述就是\"智能体可以读的文件\"，没有服务端、没有数据库、没有嵌入。第二，新鲜度是一个循环而不是一个索引：每次查询都会把工作区与上一次构建的指纹做比对，只重建发生变化的部分，过程是结构化的且不消耗 token，因此答案也能描述尚未提交的改动。 第二点才是真正的工程贡献。一份过期的地图比没有地图更糟，因为智能体会信它。这里也要提前人的工作：Aider 早在 2023 年 10 月就发布了用 tree-sitter 生成、按 PageRank 排序的仓库地图。排序过的仓库地图并不新鲜。新鲜的是刷新循环和面向多种智能体的接线。 Graft 会把仓库地图提交进 Git 吗？ 不会，而且你也不应该希望它这样做。通过版本控制传递的是接线：graft init 放进 .claude/ 的文件、AGENTS.md 中带标记的 Graft 段落，以及 MCP 配置。graft/ 下生成的图被 gitignore，并在每个克隆里重建。 产物是否随 Git 传递由谁重建处理错了会怎样 智能体接线与技能文件是，提交并评审人，在 pull request 里一半团队按另一套智能体约定工作 AGENTS.md 里手写的约定是，提交并评审人，有意识地写每个提示词都要重述构建与测试规则 graft/ 下的结构图否，默认被 gitignore每个克隆，几秒钟，免费生成文件产生合并冲突，地图在某个分支上开始说谎 --deep 生成的概念摘要否，同一份缓存持有供应商密钥的人关于你系统的未评审文字，没人负责 单次会话的临时上下文否没人，会被丢弃把会话记录当成文档 我们在这个网站自己的仓库里，以更痛的方式得出了同样的结论。我们在并行的 git worktree 里跑编码智能体，那里生成的图谱输出被有意排除在版本控制之外，因为生成的文件名会在并行分支之间冲突，而机器写出来的文件产生的冲突要耗费评审时间，却带不来任何评审价值。一份提交进版本库的地图还会随着所在分支的推进而变旧，而那恰恰是智能体最可能照它行动的时刻。 所以关于团队收益，诚实的说法比流传的说法更窄，也更有用。Graft 并不会把你的智能体建立起来的认知交给你的同事。它交给同事的是一条两秒钟的命令，从同一个事实来源也就是代码，重建出一份等价的地图。这比一份共享文件更可靠，因为它不会漂移。但这也意味着这是一项推广任务，而不是一项文档任务。 那么什么才该放进 Git？ 有用的规则很短：把需要人负责的内容提交进去，把解析器可以重新推导的内容交给重建。生成的结构便宜且能自我纠正。意图两样都不是。 决策与约束。构建与测试命令、智能体不得越过的边界、那个丑陋模块为什么要保持丑陋、哪个接口是契约。AGENTS.md 就是为此存在的，这个格式已被超过 60,000 个开源项目使用，目前由 Linux 基金会下的 Agentic AI Foundation 托管。它由人手写、在 pull request 里评审，值得投入维护。 派生的结构。调用图、符号地图、按重要性排序的文件列表。这些都能重建，所以把它们放进 gitignore，并让重建又快又自动。 不属于代码的组织知识。运行手册、领域规则、带负责人和复核日期的决策。这些属于一个有治理的知识库，那是另一项工程，规则也不同。我们的面向 AI 的公司 Wiki 架构覆盖了这部分。 在这件事上翻车的团队通常朝两个方向之一走。一种是把生成产物提交进去，于是同时继承了合并噪音和自信满满的过期答案。另一种是什么都不写下来，却指望工具推断出从未被记录过的意图。仓库地图无法告诉智能体某张表正在迁移、不能再加列。只有人能。同样的纪律也体现在我们的软件交接清单里，它针对的是同一个问题的人类版本：在知道这件事的人离开之前，哪些内容必须写下来。 查看相关服务： AI 咨询 看看生产环境中的应用: Twinsoft AI 先做决定: 如何为 MVP 选择技术栈 Graft 的数据有多可靠？ 机制是可信的，而每一个公开数字都来自厂商自己。这样的组合值得一次试点，而不是一次采购决定。Graft 公布了三组独立的测量，它们的强度并不相同。 测量报告结果它能支持什么它到哪里为止 162 次受控运行，Claude Sonnet 5，两个仓库，每个任务三轮token 从 8,070 降到 4,650，工具调用从 4.2 降到 2.3，延迟从 39.8 秒降到 15.8 秒，成本从 0.0429 降到 0.0292，两组正确率同为 93%效率机制：有方向的智能体搜索得更少任务是问答而不是改代码；两个仓库中的一个就是 Graft 本身；正确性由带关键词门槛的 Opus 4.8 评审给出 SWE-bench Verified，50 个实例，官方 swebench 4.1.0 评分器解决 33/50 对 27/50，同时少用 23% 的 token 和 32% 的墙钟时间真实的正确性，由维护者自己的测试而非模型来评判只用了 500 个已验证实例中的 50 个，差距为六个实例，单轮运行，未报告方差 PocketBase，15 个任务，Claude Opus，无界面运行，同一提交的两个克隆成本从 13.91 美元降到 11.02 美元，墙钟从 2,044 秒降到 1,762 秒，5 个已合并 PR 全部复现在厂商无法控制的真实第三方代码库上的表现PR 的评分标准是是否改动了与维护者相同的文件，这与通过他们的测试并不等价 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 依赖，理应像任何构建工具一样锁定版本并验证升级路径。", "articleSection": "Engineering", "author": { "@id": "https://wavect.io/team/kevin-riedl/#person", "@type": "Person", "name": "Kevin Riedl", "sameAs": [ "https://www.wikidata.org/wiki/Q139796365", "https://www.linkedin.com/in/wsdt", "https://github.com/wsdt" ], "url": "https://wavect.io/team/kevin-riedl/" }, "citation": [ { "@type": "WebPage", "name": "Graft 官方仓库", "url": "https://github.com/NanoNets/Graft" }, { "@type": "WebPage", "name": "项目自己的描述", "url": "https://graft.nanonets.ai/" }, { "@type": "WebPage", "name": "Aider 早在 2023 年 10 月就发布了用 tree-sitter 生成、按 PageRank 排序的仓库地图", "url": "https://aider.chat/2023/10/22/repomap.html" }, { "@type": "WebPage", "name": "AGENTS.md", "url": "https://agents.md/" }, { "@type": "WebPage", "name": "SWE-bench Verified", "url": "https://www.swebench.com/verified.html" }, { "@type": "WebPage", "name": "SWE-bench-verified-mini", "url": "https://huggingface.co/datasets/MariusHobbhahn/swe-bench-verified-mini" } ], "dateModified": "2026-08-18", "datePublished": "2026-08-18", "description": "Graft 是一个采用 MIT 许可的 npm 命令行工具，它把仓库写成互链的 Markdown 节点以及按符号组织的代码图， 让编码智能体在任务开始时就已经有方向，而不必从零开始逐个搜索文件。对团队来说，有两点是决定性的。第一，这份地图并不通过 Git 共享：graft build 会自动把 graft/ 写进 .gitignore，每位同事都在本地重建自己的副本，因此热帖中关于地图会随仓库一起 传递的说法并不成立。真正提交进版本库的只有 .claude/ 里的接线文件、AGENTS.md 中带标记的段落以及 MCP 配置。这个默认设置 是对的，因为生成文件会在并行分支之间冲突，而一份被提交的地图在分支变动的那一刻就开始说谎。第二，所有公开的性能数字都来自 厂商自己：在两个仓库上跑的 162 次对比，其中一个仓库就是 Graft 本身，正确性由 LLM 评审打分；另有 50 个 SWE-bench Verified 实例，解决数为 33 对 27，只跑了一轮且没有报告方差。机制可信，但不足以作为采购依据。结构层是确定性的 tree-sitter，不需要密钥也不联网；而 graft build --deep 会把文件和符号内容发送到你配置的模型供应商，这正是欧盟团队必须 审查的部分。把需要人负责的内容提交进 Git，把解析器可以重新推导的内容交给重建，并用每个被接受的变更的成本而不是省下的 token 来评估两周试点。事实核查日期：2026 年 8 月 18 日。", "headline": "Graft 评测 2026：智能体仓库地图该进 Git 吗？", "image": "https://wavect.io/img/blog/headers/header_graft-review-agent-repo-map.svg", "inLanguage": "zh", "keywords": "Graft, 智能体仓库地图", "mainEntityOfPage": { "@id": "https://wavect.io/zh/blog/graft-review-agent-repo-map/", "@type": "WebPage" }, "publisher": { "@id": "https://wavect.io/#organization", "@type": [ "Organization", "ProfessionalService", "LocalBusiness" ] }, "url": "https://wavect.io/zh/blog/graft-review-agent-repo-map/", "wordCount": 599 } ``` ```json { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "item": "https://wavect.io/zh/", "name": "首页", "position": 1 }, { "@type": "ListItem", "item": "https://wavect.io/zh/blog/overview/", "name": "博客概览", "position": 2 }, { "@type": "ListItem", "item": "https://wavect.io/zh/blog/topics/ai-agents/", "name": "AI 与智能体", "position": 3 }, { "@type": "ListItem", "item": "https://wavect.io/zh/blog/clusters/agent-engineering/", "name": "智能体工程", "position": 4 }, { "@type": "ListItem", "item": "https://wavect.io/zh/blog/graft-review-agent-repo-map/", "name": "Graft 评测 2026：智能体仓库地图与 Git | ", "position": 5 } ] } ``` ```json { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "acceptedAnswer": { "@type": "Answer", "text": "不会。README 写明这个图是像 node_modules 那样的本地可重建缓存，不是需要提交的东西，而且 graft build 会自动把 graft/ 加入 .gitignore。被提交的是 graft init 写进 .claude/ 的接线文件、AGENTS.md 中带标记的段落以及 MCP 配置。团队里每个人都用 graft build 生成自己的图。" }, "name": "Graft 会把仓库地图提交进 Git 吗？" }, { "@type": "Question", "acceptedAnswer": { "@type": "Answer", "text": "软件采用 MIT 许可，因此没有许可费。结构构建、刷新循环和结构类查询从不调用模型，每次运行都不产生费用。可选的概念层 graft build --deep 会用你自己的供应商密钥消耗 token。" }, "name": "Graft 免费吗？" }, { "@type": "Question", "acceptedAnswer": { "@type": "Answer", "text": "结构图不需要。graft build、graft check、graft ask、graft grep、graft callers、graft skeleton 和 graft map 都是确定性的 tree-sitter 操作，不需要密钥也不需要网络。只有写出自然语言摘要和概念节点的 graft build --deep 才需要供应商密钥。" }, "name": "Graft 需要 API 密钥吗？" }, { "@type": "Question", "acceptedAnswer": { "@type": "Answer", "text": "不使用。项目明确把自己描述为智能体可以读的文件，没有服务端、没有数据库、没有嵌入。检索依靠对 Markdown 节点和按符号代码图的排序与链接跳转，而不是相似度搜索。" }, "name": "Graft 使用嵌入或向量数据库吗？" }, { "@type": "Question", "acceptedAnswer": { "@type": "Answer", "text": "可以。graft init 会检测并接入 Claude Code、Cursor、GitHub Copilot、通过 AGENTS.md 接入的 Codex、Gemini、Kiro、Windsurf 等，同时还提供一个带六个工具的 MCP 服务器。Claude Code 通过 hooks、状态栏和自动同步获得最深的集成。" }, "name": "除了 Claude Code，Graft 也能用于其他智能体吗？" }, { "@type": "Question", "acceptedAnswer": { "@type": "Answer", "text": "把它当作方向性的自测对比。它只覆盖 500 个已验证实例中的 50 个，报告没有说明是哪 50 个，因此这个数字背后的项目和语言覆盖范围是未知的，差距是单轮运行中的六个实例且未报告方差。评分本身是可信的，因为它使用官方 swebench 评分器而不是模型评审。" }, "name": "Graft 在 SWE-bench Verified 上的 66% 能和排行榜数字相比吗？" }, { "@type": "Question", "acceptedAnswer": { "@type": "Answer", "text": "要么整个团队接入，要么就不要用。因为图是在每个克隆里重建的，单个人私下使用既产生不了共享收益，也产生不了可比数据。把接线提交进版本库，就深度层是否允许达成一致，并在团队范围内衡量每个被接受变更的成本。" }, "name": "应该一个人用 Graft 还是整个团队用？" } ] } ```