Cara Bina Peta Pangkalan Kod Untuk Ejen Pengekodan

Apakah peta pangkalan kod untuk ejen pengekodan

Peta pangkalan kod untuk ejen pengekodan ialah indeks kekal bagi repositori anda yang dirujuk oleh ejen untuk mencari maklumat, berbanding melakukan carian grep dari awal dalam setiap sesi baharu. Graft merupakan salah satu pelaksanaan idea tersebut. Ia menghuraikan kod anda menggunakan tree-sitter, menulis folder yang mengandungi nod markdown terpaut serta graf pendawaian bagi setiap simbol, dan menyediakan alat perolehan melalui MCP (model context protocol, iaitu antara muka standard yang digunakan oleh ejen pengekodan untuk memanggil alat luaran).

Graft bukanlah proksi dan ia bukan gerbang. Tiada apa-apa yang berada di antara ejen anda dan API model. Peta tersebut hanyalah folder pada cakera yang dibaca oleh ejen. Perbezaan tersebut menentukan masalah yang anda selesaikan: gerbang token yang dihoskan sendiri mengukur dan menghalakan permintaan yang anda hantar, manakala peta mengubah jumlah permintaan yang perlu anda hantar.

Teknik ini lebih lama daripada alat ini dan akan terus relevan selepas alat ini tidak lagi digunakan. Pelajari tekniknya dahulu, kemudian barulah mekanismenya.

Mengapa ejen pengekodan membazirkan konteks untuk menemui semula struktur

Perhatikan ejen memulakan kerja pada repositori yang telah dilihatnya sebanyak lima puluh kali. Ia menyenaraikan direktori. Ia menjalankan grep untuk mencari simbol. Ia membuka tiga fail untuk mencari fail mana yang mentakrifkan fungsi tersebut, kemudian fail keempat untuk mengetahui siapa yang memanggilnya. Tiada satu pun daripada itu adalah tugasan sebenar. Itu adalah proses orientasi, dan ia dibayar menggunakan token input pada setiap sesi.

Puncanya mudah. Model tidak mempunyai memori antara sesi. Segala yang dipelajari oleh ejen tentang susun atur anda berada dalam tetingkap konteks yang dibuang apabila sesi berakhir. Jadi, penemuan yang sama dijalankan semula dari sifar, pada harga penuh. Pada repositori yang besar, fasa orientasi menelan kos lebih tinggi daripada penyuntingan itu sendiri: sepuluh panggilan alat untuk mencari kod, satu untuk mengubahnya. Orientasi hanyalah separuh daripada bil tersebut dan penyuntingan adalah separuh lagi, itulah sebabnya kemahiran yang mengekalkan ejen pada perubahan terkecil yang berfungsi berbaloi untuk digandingkan dengan peta dan bukannya memilih antara satu sama lain.

Peta memecahkan gelung tersebut dengan memindahkan proses penemuan daripada model ke cakera. Pengurai (parser) menelusuri repositori sekali, merekodkan simbol mana yang ditakrifkan di mana dan simbol mana yang memanggil yang mana, kemudian memastikan rekod tersebut sentiasa terkini apabila kod berubah. Ejen bertanya satu soalan dan mendapat jawapan berserta fail dan baris yang berkaitan. Eksplorasi berulang menjadi carian yang murah.

Anda sudah menggunakan versi yang lebih lemah bagi perkara ini. Fail AGENTS.md yang menyatakan konvensyen anda menghalang ejen daripada menerbitkan semula konvensyen anda setiap kali. Peta yang dijana menghalang ejen daripada menerbitkan semula struktur anda. Perbezaannya ialah siapa yang menulisnya. Anda menulis fail arahan secara manual, jadi ia kekal kecil. Pengurai menjana peta, jadi ia boleh meliputi sepuluh ribu fail. Bagi mengetahui ke mana perginya bajet dalam sesuatu sesi, bagaimana Claude Code membelanjakan tetingkap konteksnya merangkumi perakaunan tersebut.

Apa yang sebenarnya dibina oleh Graft

Dua artifak, kedua-duanya di bawah satu folder graft/ pada akar repositori.

Yang pertama ialah graf nod yang ditulis sebagai markdown terpaut, satu fail bagi setiap nod. Setiap nod mengandungi ringkasan dalam bahasa biasa, "inti" bagi baris logik penting yang diambil daripada sumber, fail sumber tepat dengan hash kandungan, pautan wiki bertaip ke nod lain (depends_on, part_of, uses, implements), dan bahagian nota yang kekal selepas penjanaan semula supaya anda boleh merekodkan konteks yang tidak dapat disimpulkan oleh penghurai (parser).

Yang kedua ialah graft/.graph/wiring.json, graf struktur per-simbol yang diekstrak oleh tree-sitter: definisi, rujukan, dan sisi panggilan (call edges) di antaranya.

Pembahagian ini penting kerana hanya satu bahagian yang memerlukan model. graft build adalah tree-sitter tulen dan tidak pernah memanggil LLM (model bahasa besar), jadi ia bersifat deterministik dan tidak menelan kos. graft build --deep menambah ringkasan bertulis dan inti per-simbol, dan itu adalah panggilan model yang perlu anda bayar.

Sokongan bahasa adalah berperingkat, dan peringkat tersebut memberitahu anda sejauh mana anda boleh mempercayai graf panggilan. TypeScript, JavaScript, Python, Go dan Java mendapat resolusi rentas fail yang sedar skop (scope-aware). Rust, C, C++, C#, Ruby, PHP, Kotlin, Scala, Swift, Elixir, Solidity, OCaml, Zig dan Dart mendapat simbol berserta sisi panggilan generik, yang bermaksud sesuatu sisi boleh menjadi padanan nama dan bukannya rujukan yang diselesaikan. Sisi gred pengkompil (compiler-grade) adalah pilihan dengan --lsp dan pelayan bahasa seperti rust-analyzer atau gopls.

Memasang Graft dan menetapkan versi

Graft memerlukan Node.js 20 atau lebih baharu dan dilesenkan di bawah MIT. Setakat Ogos 2026, keluaran semasa ialah 0.10.1, dan versi pertama yang diterbitkan, 0.1.0, bertarikh Julai 2026. Anggap ia sebagai perisian yang masih baharu.

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

npm ls -g sepatutnya memaparkan @nanonets/graft@0.10.1. Tetapkan versi tersebut secara sengaja. Arahan npm install -g @nanonets/graft biasa akan menyelesaikan tag latest pada saat anda menjalankannya, dan bagi projek yang mengeluarkan beberapa keluaran minor sebulan, ini akan memberikan anda alat yang berbeza pada hari Selasa berbanding apa yang dipasang oleh rakan sekerja anda pada hari Isnin. Versi yang ditetapkan memastikan flag CLI dan format graf kekal sama untuk semua orang, jadi anda hanya menaik taraf apabila anda membuat keputusan.

Kemudian, sambungkan ia ke dalam repositori milik anda:

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

graft init akan bertanya ejen pengekodan mana yang ingin anda sambungkan, kemudian membina graf tersebut. Jalankan --dry-run terlebih dahulu dan baca senarai fail yang akan disentuh, kerana sesetengah daripadanya berada di luar repositori. graft init adalah idempoten dan tidak akan menulis ganti konfigurasi sedia ada, jadi menjalankannya buat kali kedua adalah selamat.

Setakat Ogos 2026, penyambungan ini meliputi Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf dan AdaL. Claude Code mendapat integrasi paling mendalam: entri pelayan MCP, baris status yang menunjukkan saiz dan status lapuk graf, cangkuk pasca-edit yang membina semula graf, dan fail kemahiran di bawah .claude/. Ejen lain menerima fail arahan atau peraturan yang memberitahu ejen bahawa alat tersebut wujud. Oleh itu, "disokong" bermaksud Graft menulis penyambungan tersebut, jadi ejen yang mengabaikan fail peraturannya sendiri juga akan mengabaikan peta tersebut. Itulah sebab biasa mengapa ejen mengabaikan arahan yang anda tulis untuk mereka, dan ia terpakai di sini sama seperti di tempat lain.

Apa yang masuk ke dalam repositori anda, dan apa yang perlu dikecualikan daripada git

Selepas graft init, jangkakan perkara berikut:

• graft/: graf nod markdown dan graft/.graph/wiring.json. Ditambahkan ke dalam .gitignore untuk anda.
• .mcp.json: mendaftarkan pelayan MCP graft supaya Claude Code memulakannya.
• .claude/settings.json: digabungkan di tempatnya, menambah statusline dan cangkuk (hooks) pasca-suntingan.
• AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/graft.mdc, .kiro/steering/graft.md, .windsurf/rules/graft.md dan .adal/skills/graft/SKILL.md: bahagian yang dipagari penanda (marker-fenced) yang dilampirkan pada mana-mana fail yang sepadan dengan ejen yang anda pilih.
• ~/.codex/config.toml, ~/.codex/hooks.json dan ~/.codex/hooks/graft/graft-hooks.cjs: peringkat mesin, ditulis hanya apabila anda memilih Codex. graft init --no-global melangkau bahagian ini, dan graft init --no-hooks melangkau shim cangkuk secara berasingan.

Graf tersebut merupakan cache, seperti node_modules. Jangan lakukan commit pada fail ini. Ia dijana semula daripada kod dalam beberapa saat, ia berubah pada hampir setiap suntingan, dan melakukan commit pada fail ini akan menukarkan pembetulan satu baris kepada diff ratusan fail yang tidak akan dibaca oleh mana-mana penyemak. Lakukan commit pada pendawaian (wiring) sebaliknya, termasuk AGENTS.md dan .mcp.json. Rakan sepasukan akan mengklon repositori, menjalankan graft build, dan mendapatkan graf tempatan mereka sendiri.

Pastikan peraturan ignore telah dimasukkan sebelum commit pertama anda:

grep -n graft .gitignore
git status --short

grep sepatutnya mencetak baris yang mengandungi graft/, dan git status --short sepatutnya tidak menyenaraikan apa-apa di bawah graft/. Fail di bawah graft/ yang muncul dalam output tersebut bermakna entri ignore tiada atau telah ditindih di tempat lain. Betulkannya sebelum anda melakukan commit, kerana git akan terus menjejaki fail sebaik sahaja ia ditambah, dan suntingan .gitignore kemudian tidak akan menghentikan penjejakannya.

Jika anda lebih suka mendaftarkan pelayan MCP secara manual, atau menetapkannya pada versi yang sama dengan yang anda pasang, entrinya adalah kecil:

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

Alat perolehan yang dipanggil oleh ejen anda sebagai ganti grep

Graft mendedahkan enam alat melalui MCP. graft_find_code mengembalikan nod yang disusun mengikut pangkat untuk deskripsi tugasan, berserta fail dan baris. graft_file_api mengembalikan setiap signatur dalam fail tanpa badan fungsi. graft_trace_calls menelusuri pemanggil atau yang dipanggil beberapa tahap ke dalam. graft_find_all mengembalikan hasil regex yang dikumpulkan mengikut simbol. graft_repo_map memberikan pandangan awal terhadap repositori yang tidak dikenali. graft_check_freshness melaporkan sama ada graf masih sepadan dengan kod.

Setiap satu mempunyai pasangan CLI, yang merupakan cara anda menyemak perkara yang sebenarnya diberikan kepada ejen anda:

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 sepatutnya mencetak nod yang disusun mengikut pangkat dengan rujukan file:line dan bukannya kandungan fail. Itulah keseluruhan mekanismenya: ejen menerima penuding dan membuka satu fail, bukannya membaca sepuluh fail untuk mencari fail yang betul. graft viz membuka pemapar interaktif pada localhost jika anda ingin melihat graf itu sendiri. Jika graft ask tidak mengembalikan apa-apa yang berguna untuk soalan yang boleh anda jawab dalam tiga puluh saat, graf tersebut sudah lapuk atau bahasa anda berada dalam tahap umum, dan peta tersebut tidak akan membantu ejen anda juga.

Satu kos yang mudah terlepas pandang. Enam definisi alat disuntik ke dalam prompt sistem bagi setiap permintaan untuk keseluruhan sesi. Anda membayar kos tersebut sama ada ejen menggunakan peta itu atau tidak. Pada repositori yang cukup kecil untuk dimuatkan dalam konteks, caj tetap itu boleh menjadi lebih besar daripada penjimatan masa penerokaan yang diberikannya.

Apa yang berlaku kepada graf apabila kod berubah

Muat semula struktur adalah murah dan automatik. Graft membaca working tree anda dan bukannya git, jadi suntingan yang belum anda commit dan suntingan yang telah anda stage adalah sama-sama kelihatan kepadanya. Pertanyaan (query) hanya menghuraikan semula fail yang stat-nya berubah, yang didokumenkan oleh projek sebagai sekitar 3 ms overhead, dan binaan semula hujung-pusingan (turn-end rebuild) hanya menyentuh fail di mana kod telah dialihkan. Tetapkan GRAFT_NO_REFRESH=1 atau hantar --no-refresh untuk menjawab daripada graf pada cakera tanpa menghuraikan semula. Hantar --no-reuse untuk memaksa penghuraian semula sejuk bagi segala-galanya, iaitu perkara yang anda mahukan selepas menaik taraf Graft itu sendiri.

Separuh yang ditulis model berkelakuan berbeza, dan ia adalah bahagian yang menjadi salah secara senyap. Ringkasan dan crux disimpan dalam cache. Setiap nod merekodkan hash kandungan bagi sumbernya, jadi apabila fail sumber berubah, nod tersebut ditandakan sebagai lapuk (stale) dan bukannya dibentangkan sebagai semasa. Flag itu hanya membantu jika sesuatu bertindak ke atasnya. Muat semula dengan graft build --deep, yang membelanjakan token model sekali lagi.

Jadikan kelapukan kelihatan:

graft check .
echo $?

Status keluar 0 bermakna graf sepadan dengan kod. Status keluar 1 bermakna terdapat hanyutan (drift). Jalankannya daripada pre-push hook, atau pada cawangan dalam CI, supaya peta berusia enam bulan tidak boleh menjawab dengan yakin tentang kod yang telah ditulis semula pada bulan Mac.

Teliti angka penanda aras yang diterbitkan

Dakwaan utama Graft ialah "sehingga 4x lebih murah dan 3x lebih pantas, dengan ketepatan yang lebih baik atau tiada kehilangan ketepatan". Angka tersebut datang daripada penanda aras projek itu sendiri yang diterbitkan dalam README miliknya. Berikut adalah dua ujian yang dilaporkan sepenuhnya.

[
  {
    "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
  }
]

Ujian terkawal tersebut melibatkan 162 larian merentasi dua repositori, salah satunya ialah Graft sendiri, dengan tiga percubaan bagi setiap tugasan. Ia melaporkan 42% token yang lebih sedikit dan 46% panggilan alat yang lebih sedikit. Larian SWE-bench Verified melibatkan 50 contoh dengan model yang sama pada kedua-dua bahagian, dan ia melaporkan penjimatan yang lebih kecil: 23% token dan 25% panggilan alat. Larian ketiga menghasilkan semula lima pull request PocketBase yang telah digabungkan dengan kos 11.02 dolar AS berbanding 13.91 untuk garis dasar.

Anggap kesemuanya sebagai penanda aras vendor. Dua perkara mengehadkan maklumat yang boleh anda peroleh daripadanya. Ujian terkawal merangkumi repositori Graft sendiri, iaitu kod dasar yang digunakan oleh penulisnya untuk melakukan penalaan. SWE-bench Verified ialah set data awam bagi isu daripada projek Python sumber terbuka yang terkenal, dan set data awam adalah perkara yang dioptimumkan oleh alatan, sama ada disengajakan atau tidak. Tiada satu pun daripadanya merupakan kenyataan mengenai monorepo peribadi anda, yang mempunyai tabiat penamaan dan kod mati tersendiri.

Ketepatan memerlukan penelitian lanjut. Pada ujian terkawal, ia tidak berubah: 93% dengan peta berbanding 93% tanpa peta. Lonjakan kepada 66% daripada 54% hanya muncul pada SWE-bench Verified. Alat yang mengurangkan bil token anda dan mengekalkan kualiti pada tahap yang sama masih merupakan pertukaran yang baik. Cuma jangan gabungkan hasil ketepatan SWE-bench dengan hasil token ujian tersebut dan memetik kedua-duanya sebagai satu dakwaan.

Ukur delta token anda sendiri sebelum mempercayainya

Satu-satunya angka yang penting ialah angka daripada repositori anda sendiri. Kaedah ini mengambil masa satu petang.

Pilih tugasan yang boleh anda ulangi dengan tepat. Soalan lebih baik daripada suntingan, kerana suntingan mengubah repositori dan percubaan kedua tidak lagi menjadi eksperimen yang sama. "Modul manakah yang menguatkuasakan had kadar pada laluan log masuk" adalah bentuk soalan yang tepat.

Hidupkan telemetri dan hantarkannya ke terminal anda sendiri:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claude

Pengeksport konsol mencetak rekod metrik semasa ia dikumpulkan. Rekod yang anda perlukan ialah claude_code.token.usage, yang membawa atribut type bagi input, output, cacheRead atau cacheCreation. Orientasi muncul dalam input dan cacheRead, kerana di situlah kandungan fail berakhir. Tambahkan kedua-duanya.

Jalankan tugasan tersebut sebanyak tiga kali, setiap satunya dalam sesi baharu, dengan peta disambungkan. Kemudian, alihkan entri graf daripada .mcp.json dan jalankan tiga kali lagi. Bandingkan median dan bukannya larian tunggal, kerana larian ejen sangat berbeza-beza dan satu larian yang tidak bernasib baik akan memberikan anda maklumat yang salah. Rekodkan juga kiraan panggilan alat: panggilan alat ialah mekanismenya, dan token ialah kesannya, jadi penjimatan token tanpa penurunan dalam panggilan alat bermakna sesuatu yang lain telah berubah.

Kemudian, tolak kos yang tidak ditunjukkan oleh penanda aras. graft build --deep membelanjakan token model pada setiap muat semula penuh. Enam skema alat disertakan dalam setiap permintaan. Jika ejen anda berjalan pada pelayan yang anda sewa, meletakkan had siling pada perbelanjaan ejen mengubah perkara ini daripada kejutan kepada bajet, dan apa yang sebenarnya dilaporkan oleh telemetri ejen pengekodan merangkumi perkara yang keluar daripada mesin sebaik sahaja anda mendayakan pengeksport.

Bilakah pemetaan kod (codebase map) tidak lagi membantu?

• Repositori sudah pun muat dalam konteks. Servis kecil yang tunggal tidak memerlukan peta, dan anda masih perlu membayar untuk enam skema alat bagi setiap permintaan. Jika ejen anda menemui mana-mana fail hari ini dalam satu atau dua panggilan alat, abaikan pemetaan tersebut.
• Bahasa anda berada dalam tier umum. Tepi panggilan (call edges) generik bermakna graft callers boleh terlepas pemanggil, atau menghasilkan pemanggil daripada perlanggaran nama. Sahkan dengan graft grep sebelum anda mempercayai jejari impak (blast radius).
• Graf menjadi lapuk dan tiada siapa yang perasan. graft check keluar dengan kod 1 jika berlaku hanyutan (drift), yang hanya berguna jika ada sesuatu yang menjalankannya. Gunakan hook atau langkah CI, bukan sekadar tabiat.
• Monorepo memerlukan skop. Monorepo git tunggal dipecahkan secara automatik oleh fail ruang kerja, go.mod, pyproject.toml atau Cargo.toml, dan graft ask "..." --in services/billing/ mengecilkan pertanyaan kepada satu sub-projek. Naluri yang sama yang membawa kepada fail AGENTS.md bersarang bagi setiap pakej terpakai pada peta tersebut.
• Ejen mengabaikan pendawaian. Perhatikan panggilan alat dalam sesi sebenar sebelum anda membuat kesimpulan bahawa peta tersebut sedang digunakan. Ejen yang masih menjalankan grep memberitahu anda bahawa ia tidak pernah membaca fail peraturan tersebut.

FAQ

Should I commit the graft/ folder to git?

No. graft build adds graft/ to your .gitignore automatically, because the graph is a regenerable cache like node_modules. It changes on nearly every edit, so committing it buries real diffs under hundreds of generated files. Commit the wiring that tells agents the map exists, AGENTS.md and .mcp.json among them, and let each teammate run graft build locally. Verify with grep -n graft .gitignore and git status --short before your first commit, because git keeps tracking a file once it has been added, and editing .gitignore afterwards does not untrack it.

Does Graft cost money to run?

The structural half does not. graft build, graft ask, graft check and the six MCP retrieval tools are tree-sitter operations that never call a model. graft build --deep is the paid half: it writes the plain-English summaries and per-symbol cruxes through an LLM, configured with GRAFT_PROVIDER, GRAFT_API_KEY and GRAFT_MODEL, plus GRAFT_BASE_URL for any OpenAI-compatible endpoint. You can run Graft with structure only and never spend a token on the graph itself.

How much will a codebase map actually save on my repository?

Nobody can tell you without measuring. The project reports 42% fewer tokens on its own 162-run sweep and 23% on SWE-bench Verified, both against a baseline with no map. Both are vendor benchmarks, one of them run partly on Graft's own repository, and neither describes your private code. Run one repeatable question three times with the map and three times without, with CLAUDE_CODE_ENABLE_TELEMETRY=1 and OTEL_METRICS_EXPORTER=console set, then compare the median of claude_code.token.usage for the input and cacheRead types.

What happens to the graph when I refactor?

Structure re-parses itself. Graft stats the working tree and re-parses only the files that changed, so a rename is picked up on the next query at roughly 3 ms of overhead, and it sees uncommitted work because it reads files rather than git history. The model-written summaries are what goes stale: each node stores a content hash of its sources, and a changed source marks the node stale instead of rewriting it. Run graft check . to see the drift, then graft build --deep to refresh the written half.

Which coding agents can use Graft today?

As of August 2026 graft init wires Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf and AdaL. Claude Code gets the most: an MCP server entry in .mcp.json, a statusline, post-edit hooks and a skill file under .claude/. Codex gets an AGENTS.md section plus machine-wide entries under ~/.codex/, which graft init --no-global skips. The others receive a rules or steering file. Any other MCP client can use the server directly by registering the command npx -y @nanonets/graft@0.10.1 mcp.