SSD Nodes Learn Hosting plans →
Panduan Matt ConnorOleh Matt Connor · Dikemas kini 2026-10-24

Graft: Cara Bina Peta Kod untuk Ejen Pengekodan

Gunakan Graft untuk menghurai repositori melalui tree-sitter menjadi peta kod berterusan. Elakkan carian grep berulang dengan menyediakan konteks melalui protokol MCP.

Apakah peta kod untuk ejen pengekodan

Peta kod untuk ejen pengekodan ialah indeks berterusan bagi repositori anda yang digunakan oleh ejen untuk mencari maklumat, berbanding melakukan carian grep dari awal dalam setiap sesi baharu. Graft merupakan salah satu implementasi bagi 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 capaian melalui MCP (model context protocol, iaitu antara muka standard yang digunakan oleh ejen pengekodan untuk memanggil alat luaran).

Graft bukan proksi dan bukan juga gerbang. Tiada apa-apa yang berada di antara ejen anda dan API model. Peta tersebut hanyalah folder pada cakera yang dibaca oleh ejen. Perbezaan ini 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 menghabiskan konteks untuk menemui semula struktur

Perhatikan ejen memulakan kerja pada repositori yang telah dilihatnya sebanyak lima puluh kali. Ia menyenaraikan direktori. Ia melakukan 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. Ia 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, dan anda membayarnya sekali lagi. Prompt caching hanya memberikan diskaun untuk awalan prompt yang sama dalam tempoh lima minit terakhir, atau satu jam terakhir dengan kos tambahan, jadi ia tidak boleh membawa hasil penerokaan semalam ke dalam sesi hari ini. Pada repositori yang besar, fasa orientasi menelan kos lebih tinggi daripada suntingan itu sendiri: sepuluh panggilan alat untuk mencari kod, satu untuk mengubahnya. Orientasi hanyalah separuh daripada bil tersebut dan suntingan adalah separuh lagi, itulah sebabnya kemahiran yang mengekalkan ejen pada perubahan terkecil yang berkesan 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 dilampirkan. Penerokaan 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 ke mana perginya bajet sebenar dalam satu sesi, bagaimana Claude Code membelanjakan tetingkap konteksnya merangkumi perakaunan tersebut.

Apakah 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 merupakan panggilan model yang perlu anda bayar.

Sokongan bahasa dibahagikan kepada peringkat, dan peringkat tersebut memberitahu anda sejauh mana anda boleh mempercayai graf panggilan. TypeScript, JavaScript, Python, Go, Java, Kotlin, PHP, Swift dan R mendapat resolusi rentas fail yang peka skop. Rust, C, C++, C#, Ruby, Scala, Elixir, Solidity, OCaml, Zig, Dart, Clojure, Nix dan Lua mendapat simbol berserta sisi panggilan generik, yang bermaksud sesuatu sisi boleh jadi 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 17 Oktober 2026, keluaran semasa ialah 0.23.0 yang diterbitkan pada 15 Oktober 2026, manakala versi pertama 0.1.0 bertarikh Julai 2026. Anggap ia sebagai perisian yang masih baharu. Keluaran 0.22.0 yang diterbitkan pada 14 Oktober 2026 menamakan semula projek tersebut kepada Trail-code: kod yang sama kini turut diedarkan sebagai @trailhq/trail-code dengan arahan trail, sementara @nanonets/graft mengekalkan arahan graft.

Panduan ini menetapkan versi 0.21.1, iaitu keluaran yang diterbitkan pada 29 September 2026 dan merupakan keluaran terakhir sebelum penamaan semula, kerana versi 0.22 dan 0.23 menukar arahan yang digunakan dalam panduan ini. Bermula versi 0.22, graft check membandingkan diff cawangan anda dengan pembelajaran pasukan repo dan keluar dengan kod 1 jika berlaku konflik, pengesanan drift dipindahkan ke graft build --check, dan alatan MCP dinamakan sebagai trail_* (pelayan masih menjawab kepada nama lama graft_*). Log perubahan 0.23.0 juga menyatakan bahawa dalam repo yang disediakan dengan trail, peta berpindah ke .trail/cache/ dan Claude Code tidak lagi mendapat pelayan MCP, manakala README masih menerangkan graft/ dan .mcp.json. Baca log perubahan dan jalankan --dry-run sebelum anda menukar penetapan versi.

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

npm ls -g sepatutnya mencetak @nanonets/graft@0.21.1. Tetapkan versi tersebut secara sengaja. Arahan npm install -g @nanonets/graft biasa akan menyelesaikan tag latest pada saat anda menjalankannya, dan pada projek yang mengeluarkan beberapa keluaran minor sebulan, ini menyebabkan anda mendapat alatan 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 boleh menaik taraf apabila anda bersedia.

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 yang mana untuk disambungkan, 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. Untuk membatalkan, graft uninstall akan membuang setiap fail dan entri konfigurasi yang ditulis oleh Graft, dan ia merupakan dry run sehingga anda memasukkan -y.

Prompt yang sama mengandungi kotak semak telemetri. Sejak keluaran 0.12.0, Graft menghantar ping penggunaan tanpa nama secara lalai: kiraan berkumpulan dan label tetap, bukan kod, laluan fail atau nama repositori anda. Acara dihantar paling kerap sekali sehari, dengan satu pengecualian: acara pemasangan, yang diserahkan oleh cangkuk postinstall npm kepada penghantar latar belakang dengan serta-merta. Nyahtanda kotak tersebut semasa graft init, jalankan graft telemetry disable, atau tetapkan DO_NOT_TRACK=1 untuk mematikannya (ia juga akan mematikan diri sendiri dalam CI), dan graft telemetry debug akan mencetak kelompok yang sepatutnya dihantar tanpa menghantarnya.

Dalam versi 0.21.1, sambungan meliputi Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent dan Google Antigravity. Hermes Agent telah menjadi hos graft init kelas pertama sejak keluaran 0.13.0, dan pada versi yang ditetapkan, graft init --agents hermes dan graft init --agents antigravity memilih kedua-duanya seperti hos lain. Grok menyertai dalam keluaran 0.13.0 dan dipilih dengan graft init --agents grok. Claude Code mendapat integrasi paling mendalam: entri pelayan MCP, bar status yang menunjukkan saiz dan status lapuk graf, cangkuk pasca-edit yang membina semula graf, dan fail kemahiran di bawah .claude/. Yang lain mendapat fail arahan atau peraturan yang memberitahu ejen bahawa alatan tersebut wujud (Hermes Agent dan Antigravity kedua-duanya membaca bahagian AGENTS.md), dan Grok juga mendapat blok MCP dalam konfigurasinya sendiri. Oleh itu, "Disokong" bermaksud Graft menulis sambungan tersebut, jadi ejen yang melangkau fail peraturannya sendiri akan melangkau peta tersebut juga. Itulah sebab biasa 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 (hook) pasca-suntingan.
  • 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 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.
  • .grok/config.toml: blok [mcp_servers.graft] pada peringkat repositori, ditulis hanya apabila anda memilih Grok.
  • ~/.codex/config.toml, ~/.codex/hooks.json dan ~/.codex/hooks/graft/graft-hooks.cjs: peringkat mesin, ditulis hanya apabila anda memilih Codex dan ~/.codex/ sudah wujud. 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 tersebut. Ia dijana semula daripada kod dalam beberapa saat, ia berubah pada hampir setiap suntingan, dan melakukan commit padanya akan menukar pembaikan satu baris menjadi diff beratus-ratus fail yang tidak akan dibaca oleh mana-mana penyemak. Lakukan commit pada pendawaian (wiring) sebaliknya, termasuk AGENTS.md dan .mcp.json. Rakan sepasukan yang melakukan clone pada repositori, menjalankan graft build, dan mendapatkan graf tempatan mereka sendiri.

Pastikan peraturan pengabaian (ignore rule) telah dimasukkan sebelum commit pertama anda:

grep -n graft .gitignore
git status --short

grep sepatutnya mencetak baris yang mengandungi graft/, dan git status --short tidak sepatutnya menyenaraikan apa-apa di bawah graft/. Fail di bawah graft/ yang muncul dalam output tersebut bermakna entri pengabaian tiada atau ditindih di tempat lain. Betulkannya sebelum anda melakukan commit, kerana git 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.21.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 (callers) atau yang dipanggil (callees) beberapa tahap ke dalam. graft_find_all mengembalikan padanan 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 penunjuk dan membuka satu fail, bukannya membaca sepuluh fail untuk mencari 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, jangan olah semula dan tanya lagi. Perolehan mengikut pangkat boleh terlepas, dan fail kemahiran projek itu sendiri menyatakan bahawa padanan yang lemah bermakna beralih kepada graft grep, graft skeleton atau graft callers. Jika alat tersebut juga tidak mencukupi, semak sama ada berlaku drift (graft check . pada versi 0.21.1 yang disemat, graft build --check daripada 0.22 dan seterusnya) dan sahkan tahap (tier) bahasa anda, kerana graf yang lapuk atau edge tahap luas akan menyebabkan ejen anda gagal dengan cara yang sama.

Satu kos yang mudah terlepas pandang. Enam definisi alat disuntik ke dalam system prompt 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 tersebut boleh menjadi lebih besar daripada penjimatan masa penerokaan yang diberikan.

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. Setiap pertanyaan akan terlebih dahulu melakukan stat pada working tree dan hanya menghuraikan semula fail yang berubah. Dokumentasi 0.21.1 meletakkan pemeriksaan itu pada kira-kira 3 ms apabila tiada apa-apa yang berubah; README semasa menyatakan beberapa puluh milisaat, kira-kira 50 ms pada repositori projek itu sendiri. Pembinaan semula pada akhir giliran 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, yang merupakan tindakan yang anda perlukan selepas menaik taraf Graft itu sendiri.

Bahagian yang ditulis oleh model berkelakuan secara 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 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 $?

Pada versi 0.21.1 yang dipinkan, status keluar 0 bermakna graf sepadan dengan kod dan status keluar 1 bermakna terdapat hanyutan (drift). Bermula dari 0.22 dan seterusnya, graft check keluar dengan 1 jika terdapat konflik dengan pembelajaran pasukan, dan pintu hanyutan adalah graft build --check, jadi tukar arahan apabila anda mengalihkan pin. Jalankannya daripada pre-push hook, supaya peta berusia enam bulan tidak boleh menjawab dengan yakin tentang kod yang telah ditulis semula pada bulan Mac. README 0.21.1 menerangkan graft check sebagai isyarat kesegaran tempatan, dan README semasa menyenaraikan build --check untuk CI. Walau apa pun, graft/ diabaikan oleh git, jadi checkout CI yang baharu bermula tanpa graf melainkan tugasan tersebut membina satu.

Teliti nombor penanda aras yang diterbitkan dengan cermat

README versi 0.21.1 bermula dengan kenyataan "sehingga 4x lebih murah dan 3x lebih pantas, dengan ketepatan yang lebih baik atau tiada kehilangan ketepatan". README semasa telah menggugurkan baris tersebut dan bermula dengan angka yang lebih kecil: "Merentasi 162 larian ejen yang sama pada tugasan yang sama: 32% kos lebih rendah, 42% kurang token input tanpa cache, 60% kurang masa, dan perkadaran jawapan betul yang sama." Angka-angka ini datang daripada penanda aras projek itu sendiri, yang diterbitkan dalam README-nya. Berikut adalah dua larian yang dilaporkan sepenuhnya.

CartaGraft's own published benchmark results, versus a no-map baseline, as of October 2026
Data di sebalik carta ini
[
  {
    "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
  }
]

Larian terkawal (controlled sweep) melibatkan 162 larian ke atas dua repositori, salah satunya adalah Graft sendiri, dengan tiga percubaan bagi setiap tugasan. Ia melaporkan 42% kurang token input tanpa cache dan 46% kurang panggilan alat (tool calls). Larian SWE-bench Verified melibatkan 50 contoh dengan model yang sama pada kedua-dua kumpulan, dan ia melaporkan penjimatan yang lebih kecil: 23% token dan 25% panggilan alat. Larian ketiga bagi 15 tugasan PocketBase, sepuluh soalan pembangun ditambah lima pull request yang digabungkan dan dihasilkan semula, menelan kos sebanyak 11.02 dolar AS secara keseluruhan berbanding 13.91 untuk garis dasar (baseline).

Anggap kesemuanya sebagai penanda aras vendor. Dua perkara mengehadkan maklumat yang boleh anda peroleh daripadanya. Larian terkawal merangkumi repositori Graft sendiri, iaitu kod sumber yang digunakan oleh pengarangnya 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 daripada ini merupakan kenyataan mengenai monorepo peribadi anda, yang mempunyai tabiat penamaan dan kod mati (dead code) tersendiri.

Ketepatan wajar dibaca sekali lagi. Pada larian 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 daripada larian terkawal dan memetik kedua-duanya sebagai satu tuntutan.

Ukur delta token anda sendiri sebelum mempercayainya

Satu-satunya nombor yang penting ialah nombor 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 mendarat. Tambahkan kedua-duanya.

Jalankan tugasan tersebut sebanyak tiga kali, setiap satunya dalam sesi baharu, dengan peta disambungkan. Kemudian, alih keluar 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 mekanisme, dan token ialah kesan, 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 satu 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 pemetaan, dan anda tetap membayar kos untuk enam skema alat bagi setiap permintaan. Jika ejen anda boleh 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 radius letupan (blast radius).
  • Graf menjadi lapuk dan tiada siapa yang perasan. Pada 0.21.1 graft check akan keluar dengan kod 1 jika berlaku hanyutan (drift) (dari 0.22 dan seterusnya, graft build --check akan melakukannya), yang hanya berguna jika ada sesuatu yang menjalankannya. Gunakan pre-push hook, bukan sekadar tabiat.
  • Monorepo memerlukan skop. Monorepo git tunggal tidak dipecahkan, tetapi graft build mengesan sub-projek daripada pnpm-workspace.yaml, ruang kerja package.json atau go.mod, pyproject.toml atau Cargo.toml bagi setiap pakej dan menggunakannya sebagai skop kedudukan, 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 juga terpakai pada pemetaan.
  • Ejen mengabaikan pendawaian. Perhatikan panggilan alat dalam sesi sebenar sebelum anda membuat kesimpulan bahawa pemetaan sedang digunakan. Ejen yang masih menjalankan grep memberitahu anda bahawa ia tidak pernah membaca fail peraturan tersebut.

FAQ

Patutkah saya melakukan commit pada folder graft/ ke dalam git?

Tidak. graft build menambah graft/ ke dalam .gitignore anda secara automatik, kerana graf tersebut merupakan cache yang boleh dijana semula seperti node_modules. Ia berubah pada hampir setiap suntingan, jadi melakukan commit padanya akan menenggelamkan diff sebenar di bawah ratusan fail yang dijana. Lakukan commit pada pendawaian (wiring) yang memberitahu ejen bahawa peta tersebut wujud, termasuk AGENTS.md dan .mcp.json, dan biarkan setiap rakan sepasukan menjalankan graft build secara setempat. Sahkan dengan grep -n graft .gitignore dan git status --short sebelum commit pertama anda, kerana git akan terus menjejaki fail sebaik sahaja ia ditambah, dan menyunting .gitignore selepas itu tidak akan menghentikan penjejakannya.

Adakah Graft memerlukan bayaran untuk dijalankan?

Bahagian struktur tidak memerlukan bayaran. graft build, graft ask, graft check dan enam alat perolehan MCP adalah operasi tree-sitter yang tidak pernah memanggil model. graft build --deep ialah bahagian berbayar: ia menulis ringkasan dalam bahasa Inggeris biasa dan cruxes bagi setiap simbol melalui LLM, yang dikonfigurasikan dengan GRAFT_PROVIDER, GRAFT_API_KEY dan GRAFT_MODEL, serta GRAFT_BASE_URL untuk mana-mana endpoint yang serasi dengan OpenAI. Anda boleh menjalankan Graft dengan struktur sahaja dan tidak perlu membelanjakan token untuk graf itu sendiri.

Berapa banyak penjimatan yang akan diberikan oleh peta kod (codebase map) pada repositori saya?

Tiada sesiapa boleh memberitahu anda tanpa melakukan pengukuran. Projek ini melaporkan 42% kurang token input tanpa cache pada 162 larian ujiannya sendiri dan 23% kurang token pada SWE-bench Verified, kedua-duanya berbanding dengan garis dasar tanpa peta. Kedua-duanya adalah penanda aras vendor, salah satunya dijalankan sebahagiannya pada repositori Graft sendiri, dan tiada satu pun yang menggambarkan kod peribadi anda. Jalankan satu soalan yang boleh diulang sebanyak tiga kali dengan peta dan tiga kali tanpa peta, dengan CLAUDE_CODE_ENABLE_TELEMETRY=1 dan OTEL_METRICS_EXPORTER=console ditetapkan, kemudian bandingkan median bagi claude_code.token.usage untuk jenis input dan cacheRead.

Apakah yang berlaku kepada graf apabila saya melakukan refactor?

Struktur akan melakukan penghuraian semula (re-parse) dengan sendirinya. Graft menyemak working tree dan hanya menghuraikan semula fail yang berubah, jadi penamaan semula akan dikesan pada pertanyaan seterusnya. Apabila tiada apa-apa yang berubah, semakan itu memakan masa kira-kira 3 ms dalam 0.21.1 dan beberapa puluh milisaat dalam keluaran semasa, dan ia dapat melihat kerja yang belum di-commit kerana ia membaca fail dan bukannya sejarah git. Ringkasan yang ditulis oleh model adalah bahagian yang menjadi lapuk: setiap nod menyimpan hash kandungan bagi sumbernya, dan sumber yang berubah akan menandakan nod tersebut sebagai lapuk dan bukannya menulis semula nod itu. Semak untuk drift (graft check . pada 0.21.1, graft build --check mulai 0.22), kemudian jalankan graft build --deep untuk menyegarkan bahagian yang ditulis.

Ejen pengekodan manakah yang boleh menggunakan Graft hari ini?

Pada versi 0.21.1 yang dipinkan, graft init menghubungkan Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent dan Google Antigravity, kesemuanya sebelas hos. Changelog telah menyenaraikan Hermes Agent sebagai hos kelas pertama sejak 0.13.0, dan hermes serta antigravity adalah id --agents biasa pada keluaran yang dipinkan. Claude Code mendapat paling banyak: entri pelayan MCP dalam .mcp.json, statusline, post-edit hooks dan fail kemahiran di bawah .claude/. Codex mendapat bahagian AGENTS.md serta entri seluruh mesin di bawah ~/.codex/, yang dilangkau oleh graft init --no-global. Grok mendapat fail kemahiran serta blok MCP dalam .grok/config.toml. Hermes Agent dan Antigravity membaca bahagian AGENTS.md, dan yang lain menerima fail peraturan atau stereng. Mana-mana klien MCP lain boleh menggunakan pelayan tersebut secara terus dengan mendaftarkan arahan npx -y @nanonets/graft@0.21.1 mcp.

Adakah artikel ini berguna?