Graft 程式碼代理程式的 codebase map
Graft 使用 tree-sitter 解析 repository,建立可供 coding agent 透過 MCP 查詢的 codebase map,避免每次 session 重新搜尋相同結構。
程式碼代理程式使用的程式碼庫地圖是什麼
供程式碼代理程式使用的程式碼庫地圖,是儲存庫的持久索引。代理程式會查詢這份索引,而不是在每次新工作階段中從頭開始使用 grep 搜尋。Graft 是這種概念的一種實作。它會使用 tree-sitter 解析程式碼,建立一個包含相互連結 Markdown 節點的資料夾,以及每個符號的連結圖,並透過 MCP(model context protocol,程式碼代理程式呼叫外部工具時使用的標準介面)提供擷取工具。
Graft 不是 proxy,也不是 gateway。代理程式與模型 API 之間不會經過任何中介層。這份地圖是磁碟上的資料夾,代理程式會直接讀取。這項差異決定了你要解決的問題:自架 token gateway 會計量並路由你已經送出的請求;地圖則會改變你總共需要送出的請求數量。
這項技術早於這個工具,也會延續到工具停止使用之後。先學會這項技術,再了解實作細節。
編碼代理程式為何會耗用上下文重新探索結構
觀察代理程式開始處理一個它已經看過 50 次的儲存庫。它會列出目錄、使用 grep 搜尋符號,開啟 3 個檔案以找出函式的定義位置,再開啟第 4 個檔案以確認呼叫端。這些都不是工作本身,而是熟悉環境的過程;每次工作階段都必須為此支付輸入 token。
原因很簡單。模型無法在工作階段之間保留記憶。代理程式對目錄結構的所有了解,都存在工作階段結束時會被捨棄的上下文視窗中。因此,每次都要從零開始重新探索,而你也要再次支付這些成本。Prompt caching 只會為最近 5 分鐘內出現過的相同提示前綴提供折扣;若要延長到 1 小時,還需支付額外費用,因此無法將昨天的探索延續到今天的工作階段。在大型儲存庫中,熟悉環境的成本可能高於實際修改:使用 10 次工具呼叫定位程式碼,只使用 1 次工具呼叫進行修改。熟悉環境只是這筆成本的一半,修改則是另一半;因此,要求代理程式採用能運作的最小變更的 skill 值得搭配結構地圖使用,而不是在兩者之間擇一。
結構地圖會將探索工作從模型移到磁碟上,藉此打破這個循環。解析器只需遍歷儲存庫 1 次,記錄各符號的定義位置,以及各符號之間的呼叫關係,然後隨程式碼變更持續更新這些記錄。代理程式提出 1 個問題,就能取得附有檔案與行號的答案。反覆探索會變成低成本的查詢。
你已經在使用較弱的類似做法。說明團隊慣例的 AGENTS.md 可避免代理程式每次重新推導慣例。自動產生的結構地圖則可避免它重新推導目錄結構。差異在於撰寫者不同。你會手動撰寫指示檔,因此內容可以保持精簡。解析器會產生結構地圖,因此可以涵蓋 10000 個檔案。若要了解工作階段中的預算實際花費在哪裡,請參閱 Claude Code 如何使用上下文視窗,其中涵蓋了相關的用量分析。
Graft 實際建立的內容
在 repository 根目錄的同一個 graft/ 資料夾下,會建立 2 個產物。
第一個產物是以相互連結的 Markdown 撰寫的節點圖,每個節點各自使用 1 個檔案。每個節點包含簡明的英文摘要、從原始碼擷取的重要邏輯行所組成的「核心」、含內容雜湊的確切原始碼檔案、指向其他節點的具型別 wikilink(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/graftnpm ls -g 應輸出 @nanonets/graft@0.21.1。請刻意固定該版本。單獨使用 npm install -g @nanonets/graft 時,會解析你執行命令當下的 latest 標籤;對於每月發布多個次要版本的專案,這會導致你在 Tuesday 使用的工具與同事在 Monday 安裝的工具不同。固定版本可讓所有人的 CLI 旗標與圖形格式保持一致,並由你決定升級時機。
接著,將它整合到你擁有的儲存庫:
cd /path/to/your/repo
graft init --dry-run
graft initgraft init 會詢問要整合哪些程式碼代理,然後建立圖形。請先執行 --dry-run,並閱讀它預計修改的檔案清單,因為其中部分檔案位於儲存庫外。graft init 具備冪等性,不會覆寫現有設定,因此再次執行是安全的。若要復原,graft uninstall 會移除 Graft 寫入的所有檔案與設定項目;在傳入 -y 前,它只會執行試執行。
相同的提示也包含遙測核取方塊。自 0.12.0 版本起,Graft 預設會傳送匿名使用情況回報:只包含分組計數與固定標籤,不包含你的程式碼、檔案路徑或儲存庫名稱。事件每天最多傳送一次,但安裝事件除外;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/ 下的 skill 檔案。其他主機會取得指示檔或規則檔,告知代理可使用這些工具(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:將以 marker 標記的區段附加至與所選 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 --shortgrep 應輸出包含 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 提供 6 個工具。graft_find_code 會根據工作描述傳回排序後的節點,以及檔案和行號。graft_file_api 會傳回檔案中的所有簽章,但不包含函式本體。graft_trace_calls 會逐層追蹤呼叫端或被呼叫端。graft_find_all 會依符號分組傳回正規表示式比對結果。graft_repo_map 會先概覽不熟悉的儲存庫。graft_check_freshness 會報告圖譜是否仍與程式碼一致。
每個工具都有對應的 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" --jsongraft ask 應列出排序後的節點,並附上 file:line 參照,而不是輸出檔案內容。這就是整個機制:代理收到的是指標,只需開啟一個檔案,而不是讀取 10 個檔案來找出正確檔案。若要自行查看圖譜,graft viz 會在 localhost 開啟互動式檢視器。若 graft ask 對一個你能在 30 秒內回答的問題沒有傳回有用結果,不要改寫問題後再次查詢。排序擷取可能找不到結果,而專案自己的 skill 檔案也指出,命中結果不足時應改用 graft grep、graft skeleton 或 graft callers。如果這些工具仍無法提供足夠結果,請檢查圖譜是否已偏離程式碼(針對固定版本 0.21.1 使用 graft check .,從 0.22 起使用 graft build --check),並確認你的語言所屬的層級,因為過時的圖譜或過於寬泛的層級邊,都會以相同方式導致代理失效。
有一項成本很容易忽略。每個工作階段的每次請求,系統提示都會注入 6 個工具定義。不論代理是否使用這張圖譜,你都必須支付這項成本。對於小到足以放入上下文的儲存庫,這項固定成本可能高於它所節省的探索工作。
程式碼變更時,圖譜會發生什麼事
結構更新成本低,而且會自動進行。Graft 讀取的是工作樹,而不是 git,因此尚未提交的編輯與已暫存的編輯,對 Graft 而言同樣可見。每次查詢都會先檢查工作樹的檔案狀態,只重新解析有變更的檔案。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 中執行,避免使用已經過時 6 個月的映射,卻對 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 的自有基準測試。以下是其中完整回報的 2 次測試。
此圖表背後的資料
[
{
"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
}
]受控測試是在 2 個儲存庫上執行 162 次,其中 1 個是 Graft 自身的儲存庫;每項任務執行 3 次。測試回報未快取輸入 token 減少 42%,工具呼叫減少 46%。SWE-bench Verified 測試包含 50 個執行個體,兩組使用相同模型,回報的節省幅度較小:token 減少 23%,工具呼叫減少 25%。另一次測試包含 15 個 PocketBase 任務:10 個開發者問題,以及 5 個重現已合併 pull request 的任務;總成本為 11.02 美元,基準組則為 13.91 美元。
請將上述結果全部視為供應商基準測試。這些結果有 2 個限制。受控測試包含 Graft 自身的儲存庫,而這正是其作者調校工具時使用的程式碼庫。SWE-bench Verified 是由知名開放原始碼 Python 專案問題組成的公開資料集;無論是否出於主觀意圖,工具通常都會針對公開資料集進行最佳化。這 2 項結果都不能代表你的私有 monorepo,因為你的程式庫有自身的命名習慣與未使用程式碼。
正確性需要另外檢視。在受控測試中,正確性沒有變化:使用 map 時為 93%,未使用時為 93%。從 54% 提高至 66% 的結果,只出現在 SWE-bench Verified。若工具能降低 token 成本,同時維持相同品質,仍然是值得的交換。但不要把 SWE-bench 的正確性結果套用到受控測試的 token 結果,再將兩者合併成單一主張。
在相信任何結論前,先測量你自己的 token 差異
唯一重要的數字,是來自你自己 repository 的數字。這個方法只需一個下午。
選擇一項可以完全重複的工作。問題比編輯更適合,因為編輯會變更 repository,第二次執行時就不再是相同的實驗。「哪個模組會對 login route 強制執行速率限制」就是適合的問題形式。
啟用 telemetry,並將資料傳送到自己的終端機:
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claudeconsole exporter 會在收集 metric record 時逐筆輸出。你需要的是 claude_code.token.usage,其中包含 type attribute,值為 input、output、cacheRead 或 cacheCreation。Orientation 會出現在 input 與 cacheRead 中,因為檔案內容會寫入這兩個欄位。將兩者相加。
在 map 已接入的情況下,於每次全新的 session 中執行該工作 3 次。接著從 .mcp.json 移除 graft entry,再執行 3 次。比較中位數,不要比較單次結果,因為 agent 執行結果的差異很大,某次不走運的執行可能會得出與事實相反的結論。同時記錄 tool-call count:tool call 是機制,token 是結果;如果 token 減少但 tool call 沒有下降,表示變動發生在其他地方。
接著扣除 benchmark 未顯示的成本。graft build --deep 每次完整 refresh 都會使用 model token。6 個 tool schema 也會隨每個 request 一起傳送。如果 agent 執行於你租用的 server,為 agent 支出設定硬性上限,就能將這項成本從意外支出轉為預算;而coding agent 的 telemetry 實際回報哪些內容則說明啟用 exporter 後,哪些資料會離開這台機器。
程式碼庫對應圖何時不再有幫助?
- 儲存庫已可完整放入上下文。 單一的小型服務不需要對應圖,而且每次請求仍須支付 6 個工具結構的成本。如果代理程式今天只需呼叫 1 或 2 次工具就能找到任何檔案,請略過對應圖。
- 使用的語言屬於廣泛支援層級。 通用呼叫邊可能使
graft callers遺漏呼叫端,或因名稱衝突而產生錯誤的呼叫端。信任影響範圍前,先使用graft grep確認。 - 圖形已過時,但沒有人注意到。 在 0.21.1 中,
graft check會在偵測到偏差時結束並回傳 1(從 0.22 起,graft build --check也會如此),但前提是確實有程序執行它。應設定 pre-push hook,而不是依賴習慣。 - monorepo 需要設定範圍。 單一 git monorepo 不會自動分割,但
graft build會從pnpm-workspace.yaml、package.jsonworkspace,或每個套件的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。
程式碼庫地圖實際上能為我的 repository 節省多少成本?
除非實際測量,否則無法得知。該專案報告指出,在自身的 162 次執行測試中,未快取的輸入 token 減少了 42%;在 SWE-bench Verified 中,token 減少了 23%,兩者都是與未使用地圖的基準比較。這些都是廠商基準測試,其中一項部分使用 Graft 自身的 repository 執行,兩者都無法代表您的私有程式碼。請設定 CLAUDE_CODE_ENABLE_TELEMETRY=1 和 OTEL_METRICS_EXPORTER=console,使用同一個可重複的問題,分別搭配地圖執行 3 次和不搭配地圖執行 3 次,然後比較 claude_code.token.usage 在 input 和 cacheRead 類型中的中位數。
重構時,圖譜會發生什麼變化?
結構會自行重新解析。Graft 會檢查工作樹,只重新解析變更過的檔案,因此重新命名會在下次查詢時反映出來。若沒有任何變更,在 0.21.1 中,此檢查約需 3 ms;在目前版本中則需數十毫秒。它會讀取檔案,而不是 git 歷史,因此也能讀取尚未提交的變更。會過時的是由模型產生的摘要:每個節點都會儲存其來源的內容雜湊值;來源變更時,系統會將節點標示為過時,而不是改寫節點。請檢查是否有偏移(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 server 項目,另有狀態列、編輯後 hooks,以及位於 .claude/ 下的 skill 檔案。Codex 有 AGENTS.md 區段,並在 ~/.codex/ 下提供全機設定項目;graft init --no-global 不包含這些項目。Grok 具備 skill 檔案,並在 .grok/config.toml 中提供 MCP 區塊。Hermes Agent 和 Antigravity 會讀取 AGENTS.md 區段,其他代理程式則會收到 rules 或 steering 檔案。其他 MCP 用戶端也能直接使用此 server,只要註冊 npx -y @nanonets/graft@0.21.1 mcp 指令即可。