SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

Graft:为编程代理构建代码库地图

Graft 使用 tree-sitter 解析代码库,生成按符号关联的 Markdown 地图,并通过 MCP 提供查询,让代理无需每次会话重新搜索目录、定义和调用关系。

编程代理使用的代码库地图是什么

面向编程代理的代码库地图,是代码库的持久化索引。代理可以从中查找信息,而不必在每个新会话中重新使用 grep 从头搜索。Graft 是这种方案的一种实现。它使用 tree-sitter 解析代码,生成一组相互链接的 Markdown 节点和按符号组织的连接图,并通过 MCP(model context protocol,编程代理调用外部工具所使用的标准接口)提供检索工具。

Graft 不是代理,也不是网关。代理与模型 API 之间没有额外的中间层。该地图是磁盘上的一个文件夹,代理会读取其中的内容。这个区别决定了您要解决的问题:自托管令牌网关负责计量和路由您已经发送的请求,而代码库地图会改变您实际需要发送的请求数量。

这项技术早于该工具存在,也会在该工具之后继续使用。请先了解这项技术,再了解具体机制。

编码代理为何会消耗上下文来重新发现代码结构

观察代理在一个已经处理过 50 次的代码库上开始工作。它会列出目录。搜索某个符号。打开 3 个文件来查找哪个文件定义了该函数,然后再打开第 4 个文件来查找谁调用了它。这些都不是任务本身,而是定位过程;每次会话都要为此消耗输入 token。

原因很简单。模型无法在会话之间保留记忆。代理对代码布局的所有了解,都存在于会话结束时被丢弃的上下文窗口中。因此,每次都会从零开始进行相同的发现过程,而您也会再次为此付费。Prompt caching 只会为最近 5 分钟内见过的相同提示前缀提供折扣;如果延长到 1 小时,则需要额外付费。因此,它无法将昨天的探索带入今天的会话。在大型代码库中,定位阶段的成本高于编辑阶段:需要 10 次工具调用来定位代码,只需 1 次调用即可修改代码。定位和编辑是这笔成本的两个部分,因此 限制代理只进行能够奏效的最小改动的技能值得与代码库地图配合使用,而不是在两者之间做选择。

地图将发现过程从模型转移到磁盘,从而打破这一循环。解析器只需遍历代码库一次,记录每个符号的定义位置以及符号之间的调用关系,然后随着代码变化持续更新记录。代理提出一个问题,即可获得附带文件和行号的答案。重复探索变成低成本查询。

您已经在使用一种功能较弱的版本。说明约定的 AGENTS.md可以避免代理每次重新推导您的约定。生成的地图则可以避免代理重新推导代码结构。区别在于由谁编写。指令文件由您手动编写,因此规模较小。地图由解析器生成,因此可以覆盖 10000 个文件。至于会话中的上下文预算实际花在哪里,Claude Code 如何使用其上下文窗口介绍了相关分配。

Graft 实际构建的内容

仓库根目录下的一个 graft/ 文件夹中包含两个产物。

第一个产物是以链接 Markdown 编写的节点图,每个节点对应一个文件。每个节点包含简明的英文摘要、从源代码中提取的重要逻辑行组成的“核心”、带内容哈希的精确源文件、指向其他节点的类型化 wiki 链接(depends_on、part_of、uses、implements),以及一个可在重新生成后保留的备注部分,用于记录解析器无法推断的上下文。

第二个产物是 graft/.graph/wiring.json,即 tree-sitter 提取的按符号划分的结构图,其中包含定义、引用以及符号之间的调用边。

这种拆分很重要,因为只有其中一部分需要模型。graft build 完全由 tree-sitter 处理,从不调用 LLM(大型语言模型),因此结果具有确定性且不产生费用。graft build --deep 会添加书面摘要和按符号划分的核心内容,这些操作会调用模型并产生费用。

语言支持分为多个级别,级别决定了调用图的可信范围。TypeScript、JavaScript、Python、Go、Java、Kotlin、PHP、Swift 和 R 支持感知作用域的跨文件解析。Rust、C、C++、C#、Ruby、Scala、Elixir、Solidity、OCaml、Zig、Dart、Clojure、Nix 和 Lua 支持符号及通用调用边,这意味着某条边可能只是名称匹配,而不是已解析的引用。使用 --lsp 和 rust-analyzer 或 gopls 等语言服务器可以选择启用编译器级调用边。

安装 Graft 并固定版本

Graft 需要 Node.js 20 或更高版本,采用 MIT 许可证。截至 17 October 2026,当前版本为 0.23.0,于 15 October 2026 发布;首个发布版本 0.1.0 的日期为 July 2026。应将其视为较新的软件。14 October 2026 发布的 0.22.0 将项目重命名为 Trail-code:现在同一份代码也以 @trailhq/trail-code 的形式发布,并提供 trail 命令;@nanonets/graft 仍提供 graft 命令。

本指南固定使用 0.21.1。该版本于 29 September 2026 发布,是重命名前的最后一个版本,因为 0.22 和 0.23 修改了本指南依赖的命令。从 0.22 开始,graft check 会将你的分支差异与代码库的团队经验进行比较,发现冲突时以状态码 1 退出;漂移检测移至 graft build --check,MCP 工具命名为 trail_*(服务器仍响应旧的 graft_* 名称)。0.23.0 的变更日志还说明,在使用 trail 设置的代码库中,地图会移至 .trail/cache/,而 Claude Code 不再获得 MCP 服务器;但 README 仍描述 graft/ 和 .mcp.json。在修改版本固定值之前,请阅读变更日志并运行 --dry-run。

npm install -g @nanonets/graft@0.21.1
npm ls -g @nanonets/graft

npm ls -g 应输出 @nanonets/graft@0.21.1。请有意固定该版本。单独运行 npm install -g @nanonets/graft 时,会在运行命令的时刻解析为 latest 标签;对于每月发布多个次要版本的项目,这会导致你周二使用的工具与同事周一安装的工具不同。固定版本可以让所有人的 CLI 标志和图格式保持一致,并由你决定何时升级。

然后将它接入你拥有的代码库:

cd /path/to/your/repo
graft init --dry-run
graft init

graft init 会询问要接入哪些编码代理,然后构建图。先运行 --dry-run,查看它计划修改的文件列表,因为其中一些文件位于代码库之外。graft init 具有幂等性,不会覆盖现有配置,因此再次运行是安全的。如需撤销,graft uninstall 会删除 Graft 写入的所有文件和配置条目;在传入 -y 之前,它只执行试运行。

同一个提示还包含遥测复选框。从 0.12.0 版本开始,Graft 默认发送匿名使用情况 ping:只发送分桶计数和固定标签,不发送代码、文件路径或代码库名称。事件每天最多发送一次,但安装事件例外:npm 的 postinstall hook 会立即将其交给后台发送器。可以在 graft init 期间取消选中该复选框,运行 graft telemetry disable,或设置 DO_NOT_TRACK=1 将其关闭(在 CI 中也会自动关闭);graft telemetry debug 会输出将要发送的数据批次,但不会实际发送。

在 0.21.1 中,接入支持 Claude Code、Cursor、Codex、GitHub Copilot、Google Gemini、Kiro、Windsurf、Grok (xAI)、AdaL、Hermes Agent 和 Google Antigravity。自 0.13.0 版本起,Hermes Agent 一直是一级 graft init 宿主;在固定版本中,graft init --agents hermes 和 graft init --agents antigravity 可像选择其他宿主一样选择这两个宿主。Grok 在 0.13.0 版本中加入,可通过 graft init --agents grok 选择。Claude Code 获得最深度的集成:MCP 服务器条目、显示图大小和陈旧状态的状态栏、用于重建图的编辑后 hook,以及位于 .claude/ 下的技能文件。其他宿主会获得一个说明文件或规则文件,告知代理这些工具存在(Hermes Agent 和 Antigravity 都会读取 AGENTS.md 部分);Grok 还会在自己的配置中获得一个 MCP 块。因此,“支持”表示 Graft 会写入接入配置;如果代理跳过自身的规则文件,也会跳过该地图。这就是通常所说的 代理忽略你为其编写的指令 的原因,在这里同样适用。

哪些内容会进入仓库,哪些内容不会进入 git

运行 graft init 后,预计会出现以下内容:

  • graft/:markdown 节点图和 graft/.graph/wiring.json。系统会自动将其添加到 .gitignore。
  • .mcp.json:注册 graft MCP server,以便 Claude Code 启动它。
  • .claude/settings.json:就地合并,添加 statusline 和 post-edit hooks。
  • AGENTS.md、GEMINI.md、.github/copilot-instructions.md、.cursor/rules/graft.mdc、.kiro/steering/graft.md、.windsurf/rules/graft.md、.grok/skills/graft/SKILL.md 和 .adal/skills/graft/SKILL.md:追加到与所选 agents 匹配的文件中,各部分由标记分隔。
  • .grok/config.toml:仓库级 [mcp_servers.graft] 块,仅在选择 Grok 时写入。
  • ~/.codex/config.toml、~/.codex/hooks.json 和 ~/.codex/hooks/graft/graft-hooks.cjs:系统范围的内容,仅在选择 Codex 且 ~/.codex/ 已存在时写入。graft init --no-global 会跳过这些内容,graft init --no-hooks 会单独跳过 hook shim。

该图是缓存,类似于 node_modules。不要提交它。它可以在几秒内根据代码重新生成,几乎每次编辑都会发生变化。提交它会将一行修复变成包含数百个文件的差异,审阅者不会查看这种差异。应提交配置连接部分,包括 AGENTS.md 和 .mcp.json。团队成员克隆仓库后,运行 graft build,即可生成自己的本地图。

首次提交前,检查忽略规则是否已生效:

grep -n graft .gitignore
git status --short

grep 应输出包含 graft/ 的行,git status --short 在 graft/ 下不应列出任何内容。如果输出中出现 graft/ 下的文件,说明忽略条目缺失,或已在其他位置被覆盖。请在提交前修复,因为文件一旦被添加,git 就会继续跟踪它;之后编辑 .gitignore 不会取消跟踪。

如果您希望手动注册 MCP server,或将其固定为已安装的相同版本,配置项很简短:

{
  "mcpServers": {
    "graft": {
      "command": "npx",
      "args": ["-y", "@nanonets/graft@0.21.1", "mcp"]
    }
  }
}

代理调用的检索工具,而不是 grep

Graft 通过 MCP 暴露六个工具。graft_find_code 根据任务描述返回按排名排列的节点,并包含文件和行号。graft_file_api 返回文件中的所有签名,但不包含函数体。graft_trace_calls 递归遍历多个层级的调用方或被调用方。graft_find_all 返回按符号分组的正则表达式匹配结果。graft_repo_map 用于初步了解不熟悉的代码库。graft_check_freshness 报告图是否仍与代码一致。

每个工具都有对应的 CLI 命令。通过 CLI 可以检查代理实际收到的内容:

graft map .
graft ask "where do we validate the refresh token"
graft skeleton src/auth/session.ts
graft callers validateRefreshToken
graft callers validateRefreshToken --direction out
graft grep "refresh_token" --json

graft ask 应返回带有 file:line 引用的排名节点,而不是文件内容。这就是整个机制:代理收到一个指针后只打开一个文件,而不是读取十个文件来找到正确的文件。graft viz 会在 localhost 上打开交互式查看器,供您自行查看代码图。如果 graft ask 对一个您能在三十秒内回答的问题没有返回有用结果,不要改写问题后再次提问。排名检索可能漏掉结果,项目自己的 skill 文件说明,命中结果较弱时应切换到 graft grep、graft skeleton 或 graft callers。如果这些工具同样没有找到足够结果,请检查图是否发生漂移(固定使用 0.21.1 时运行 graft check .,从 0.22 起运行 graft build --check),并确认您的语言属于哪个层级,因为过时的图或宽泛层级的边同样会导致代理失败。

还有一项容易忽略的成本。整个会话期间,每个请求的 system prompt 都会注入六个工具定义。无论代理是否使用代码图,您都要承担这项成本。对于小到可以放入上下文的代码库,这笔固定开销可能高于它节省的探索成本。

代码发生变化时,图会怎样

结构刷新成本低,而且会自动执行。Graft 读取的是工作树,而不是 git,因此未提交的编辑和已暂存的编辑对它来说同样可见。每次查询都会先检查工作树的文件状态,只重新解析发生变化的文件。0.21.1 文档称,在没有文件变化时,这项检查耗时约 3 ms;当前 README 称耗时为几十毫秒,在项目自己的代码库中约为 50 ms。回合结束时的重建只处理代码发生变化的文件。设置 GRAFT_NO_REFRESH=1,或传入 --no-refresh,即可直接使用磁盘上的图,而不重新解析。传入 --no-reuse 会强制对所有内容执行冷解析;升级 Graft 本身后应使用此选项。

由模型生成的部分行为不同,也是最容易无声出错的部分。摘要和要点会被缓存。每个节点都会记录其源文件的内容哈希,因此源文件发生变化时,该节点会被标记为过期,而不会继续显示为最新状态。这个标记只有在有操作处理它时才有用。使用 graft build --deep 刷新,这会再次消耗模型 token。

让过期状态可见:

graft check .
echo $?

在固定使用 0.21.1 时,退出状态 0 表示图与代码一致,退出状态 1 表示存在偏移。从 0.22 开始,graft check 在与团队学习结果冲突时退出状态为 1;检查偏移则使用 graft build --check,因此更新固定版本时也要修改命令。将其放入 pre-push hook 中运行,避免六个月前生成的图对 3 月重写过的代码给出看似确定的回答。0.21.1 README 将 graft check 描述为本地新鲜度信号,当前 README 则列出 build --check 供 CI 使用。无论采用哪种方式,graft/ 都会被 git 忽略,因此全新的 CI checkout 不会包含图,除非任务先构建一个图。

仔细阅读已发布的基准测试数据

0.21.1 版本的 README 开头写着“成本最高降低 4 倍、速度最高提升 3 倍,同时正确性更好或没有损失”。当前 README 删除了这句话,改用更小的数字开篇:“在同一代理处理相同任务的 162 次运行中:成本降低 32%,未缓存输入 token 减少 42%,耗时减少 60%,正确答案占比不变。”这些数据来自项目自行执行的基准测试,并发布在其 README 中。以下是该项目完整报告的两组运行结果。

图表Graft's own published benchmark results, versus a no-map baseline, as of October 2026
此图表背后的数据
[
  {
    "label": "Controlled sweep",
    "run_count": 162,
    "token_saving_pct": 42,
    "tool_call_saving_pct": 46,
    "correctness_pct": 93,
    "baseline_correctness_pct": 93
  },
  {
    "label": "SWE-bench Verified",
    "run_count": 50,
    "token_saving_pct": 23,
    "tool_call_saving_pct": 25,
    "correctness_pct": 66,
    "baseline_correctness_pct": 54
  }
]

受控测试在两个代码库上运行了 162 次,其中一个是 Graft 自身的代码库;每个任务执行 3 次。测试报告称,未缓存输入 token 减少 42%,工具调用减少 46%。SWE-bench Verified 测试包含 50 个实例,两种方案使用相同模型;该测试报告的节省幅度更小:token 减少 23%,工具调用减少 25%。第三组测试包含 15 个 PocketBase 任务,其中 10 个是开发者问题,另外 5 个是复现的已合并 pull request;总成本为 11.02 美元,而基线为 13.91 美元。

请将这些数据全部视为供应商基准测试。两个因素限制了这些数据的参考价值。受控测试包含 Graft 自身的代码库,而该代码库正是其作者进行优化时使用的代码库。SWE-bench Verified 是一个公开数据集,收录了知名开源 Python 项目中的问题;无论是否有意,工具通常都会针对公开数据集进行优化。两者都不能代表您的私有单体代码库,因为后者有自己的命名习惯,也有自己的死代码。

正确性需要单独审视。在受控测试中,正确性没有变化:使用代码地图时为 93%,不使用代码地图时为 93%。从 54% 提升到 66% 的结果只出现在 SWE-bench Verified 中。如果某个工具能降低 token 成本,同时保持质量不变,这仍然是一笔划算的交易。但不要把 SWE-bench 的正确性结果套用到受控测试的 token 结果上,再将两者作为同一项结论引用。

在相信任何结论前,先测量您自己的 token 差值

唯一有意义的数字来自您的代码仓库。此方法需要一个下午。

选择一个可以完全重复的任务。问题比编辑更合适,因为编辑会修改代码仓库,第二次运行时实验条件就不再相同。“登录路由上由哪个模块实施速率限制”就是合适的问题形式。

启用遥测,并将其发送到您自己的终端:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claude

控制台导出器会在指标记录采集时打印这些记录。您需要关注的是 claude_code.token.usage,它包含一个 type 属性,值为 input、output、cacheRead 或 cacheCreation。定向信息会出现在 input 和 cacheRead 中,因为文件内容会写入这两个字段。将这两个值相加。

在启用映射的情况下,分别在全新会话中运行任务 3 次。然后从 .mcp.json 中移除 graft 条目,再运行 3 次。比较中位数,不要比较单次运行结果,因为 agent 运行的波动很大,某次异常运行可能会得出相反结论。同时记录工具调用次数:工具调用是机制,token 是结果。因此,如果 token 减少但工具调用次数没有下降,说明变化发生在其他地方。

然后扣除基准测试未显示的成本。graft build --deep 每次完整刷新都会消耗模型 token。每个请求都会携带 6 个工具 schema。如果您的 agent 运行在租用的服务器上,为 agent 支出设置硬上限 可以将意外支出转变为预算;启用导出器后,编码 agent 的遥测实际报告哪些内容 会说明哪些数据会离开机器。

代码库地图何时不再有帮助?

  • 代码库已经可以放入上下文。 单个小型服务不需要地图,而且每次请求仍需支付 6 个工具 schema 的开销。如果代理现在通过 1 或 2 次工具调用就能找到任意文件,请跳过它。
  • 你的语言属于广泛支持的层级。 通用调用边可能导致 graft callers 漏掉调用方,也可能因名称冲突生成错误的调用方。在信任影响范围前,使用 graft grep 进行确认。
  • 图已过时,但没有人注意到。 在 0.21.1 中,graft check 检测到漂移时退出码为 1(从 0.22 开始,graft build --check 会这样做),但前提是确实有程序运行它。应使用 pre-push hook,而不是依赖人工习惯。
  • 单体代码库需要限定范围。 单个 Git 单体代码库不会自动拆分,但 graft build 会从 pnpm-workspace.yaml、package.json workspaces 或每个包中的 go.mod、pyproject.toml 或 Cargo.toml 检测子项目,并将其用作排序范围;graft ask "..." --in services/billing/ 可将查询限定到一个子项目。同样的思路也适用于该地图:为每个包放置嵌套的 AGENTS.md 文件。
  • 代理忽略了这些连接关系。 在真实会话中查看工具调用,再判断地图是否被使用。代理如果仍在运行 grep,就说明它从未读取规则文件。

FAQ

是否应将 graft/ 文件夹提交到 git?

不应提交。graft build 会自动将 graft/ 添加到 .gitignore,因为该图与 node_modules 一样,属于可重新生成的缓存。它几乎会在每次编辑后发生变化,因此提交它会让数百个生成文件淹没真正的差异。应提交用于告知代理存在该地图的配置,其中包括 AGENTS.md 和 .mcp.json,然后让每位协作者在本地运行 graft build。首次提交前,使用 grep -n graft .gitignore 和 git status --short 进行验证,因为文件一旦被添加,git 就会继续跟踪它;之后再编辑 .gitignore 并不会停止跟踪。

运行 Graft 需要付费吗?

结构分析部分不需要。graft build、graft ask、graft check 和 6 个 MCP 检索工具都是 tree-sitter 操作,从不调用模型。graft build --deep 是付费部分:它通过 LLM 生成通俗英文摘要和每个符号的关键要点,并使用 GRAFT_PROVIDER、GRAFT_API_KEY 和 GRAFT_MODEL 配置;对于任何兼容 OpenAI 的端点,还需使用 GRAFT_BASE_URL。你可以只运行 Graft 的结构分析,不为图本身消耗任何 token。

代码库地图实际能为我的代码库节省多少成本?

不进行测量,没人能告诉你。该项目报告称,在其自身 162 次运行的测试中,未缓存输入 token 比无地图基线少 42%;在 SWE-bench Verified 中,token 少 23%,同样以无地图基线为对照。这两项都是供应商基准测试,其中一项测试部分使用了 Graft 自身的代码库,而且两项都不能说明你的私有代码库情况。使用已设置的 CLAUDE_CODE_ENABLE_TELEMETRY=1 和 OTEL_METRICS_EXPORTER=console,对同一个可重复的问题分别在启用和未启用地图的情况下各运行 3 次,然后比较 claude_code.token.usage 中 input 类型和 cacheRead 类型的中位数。

重构后图会发生什么变化?

结构会自行重新解析。Graft 会检查工作树,只重新解析发生变化的文件,因此重命名会在下一次查询时被识别。没有文件移动时,这项检查在 0.21.1 中大约耗时 3 ms,在当前版本中耗时几十 ms;由于它读取文件而不是 git 历史,因此也能看到未提交的修改。过时的是模型生成的摘要:每个节点都会保存其源文件的内容哈希;源文件发生变化后,节点会被标记为过时,而不是立即重写。使用 graft check . 检查漂移(0.21.1 中使用 graft check .,从 0.22 起使用 graft build --check),然后运行 graft build --deep 刷新生成内容。

目前哪些编码代理可以使用 Graft?

在固定使用的 0.21.1 版本中,graft init 会为 Claude Code、Cursor、Codex、GitHub Copilot、Google Gemini、Kiro、Windsurf、Grok (xAI)、AdaL、Hermes Agent 和 Google Antigravity 配置集成,共 11 个宿主。自 0.13.0 起,变更日志一直将 Hermes Agent 列为一级宿主;在固定版本中,hermes 和 antigravity 是普通的 --agents ID。Claude Code 获得的集成最多:.mcp.json 中的 MCP 服务器条目、状态栏、编辑后钩子,以及 .claude/ 下的技能文件。Codex 获得一个 AGENTS.md 部分,以及 ~/.codex/ 下的机器级条目;graft init --no-global 不处理这些条目。Grok 获得技能文件和 .grok/config.toml 中的 MCP 配置块。Hermes Agent 和 Antigravity 会读取 AGENTS.md 部分,其他代理则会收到规则文件或引导文件。其他任何 MCP 客户端都可以直接注册 npx -y @nanonets/graft@0.21.1 mcp 命令来使用该服务器。

这篇文章对您有帮助吗?