Cari kode dengan graf kode

Panduan ini menunjukkan cara memasukkan repo ke dalam graf kode, lalu memakainya untuk menjawab pertanyaan yang sebenarnya Anda hadapi sebelum refaktor: apa yang bergantung pada ini?

Graf kode adalah basis data simbol dan tepi yang dibangun dengan menguraikan checkout terdaftar Anda memakai tree-sitter. Alat-alatnya berorientasi agen — Anda mengaksesnya dengan meminta agen.

Sebelum memulai

Graf mengindeks Dart, JavaScript, TypeScript, TSX, PHP, Python, Rust, Zig, C, C++, Go, Java, Ruby, C#, Swift, Kotlin, R, Assembly, MATLAB, dan Ada. File dalam bahasa lain tidak diuraikan, sehingga tidak muncul di search_code, code_symbol, code_callers, code_callees, atau code_impact.

Ada dua hal lain yang menentukan apa yang diindeks:

Di dalam work tree git, enumerasi diserahkan kepada git ls-files --cached --others --exclude-standard, sehingga setiap .gitignore, file pengabaian bertingkat, .git/info/exclude, dan file pengecualian global dipatuhi. Itulah yang menjaga node_modules dan hasil build tetap di luar graf.
Dart hasil generasi tetap dibuang. File hasil generasi biasanya di-commit, sehingga git saja tidak akan mengecualikannya dan file-file itu terus berubah pada setiap kali pembuatan kode berjalan.

Indekskan repo

Mendaftarkan checkout memicu RepoAdded, yang secara otomatis menjalankan pipeline index_code untuknya. Lihat Tambahkan repo ke ruang kerja.

Untuk mengindeks ulang secara manual:

Buka Pengaturan → Ruang kerja → Repositori.
Klik tombol Indekskan kode pada baris repo tersebut.
Selama proses berjalan, tombol itu menampilkan jumlah file yang selesai dari totalnya, beserta kontrol pembatalan. Setelah selesai, tombol itu berubah menjadi tanda centang dengan jumlah simbol.

Graf dipartisi berdasarkan ruang kerja, repo, dan checkout: checkout yang ditautkan menjadi satu partisi, dan setiap worktree space memiliki partisinya sendiri (dikunci berdasarkan id repo terisolasi miliknya).

Ada dua pembatas yang perlu Anda ketahui, karena keduanya menjelaskan penantian yang tampak seperti hang:

Pemantau file hanya mengizinkan satu proses indeks pada satu waktu di host — checkout kedua harus menunggu. Pipeline index_code juga dibatasi secara terpisah pada satu eksekusi per ruang kerja, sehingga dua repo di ruang kerja yang sama akan mengantre; ruang kerja yang berbeda dapat mengindeks secara paralel. Pengindeks itu sendiri menyerialkan dua eksekusi pada checkout yang sama, agar permulaan pipeline dan sapuan pemantau tidak dapat menguraikannya dua kali.
Worktree milik space dorman (tidak ada pesan selama sepekan terakhir) tidak dipantau maupun diindeks. Checkout yang ditautkan tetap dipantau. Keputusan untuk melewatinya diperiksa ulang setelah lima menit, sehingga space yang kembali aktif akan ditangani lagi.

Temukan simbol

Minta agen untuk mencari. Alatnya adalah search_code dan alat itu memerlukan ruang kerja sekaligus repo:

search_code(workspace_id: "...", repo_id: "...", query: "authentication middleware")

Id repo berasal dari list_repos. Argumen opsional mode bernilai keyword, semantic, atau hybrid dan bawaannya adalah hybrid — BM25 atas nama, signature, dan komentar dokumentasi, yang digabungkan dengan kemiripan vektor.

Setiap hasil membawa id simbol, nama, nama kualifikasi, jenis, path file, baris awal dan akhir, serta signature-nya bila ada. id itulah pegangan yang Anda berikan ke setiap alat lain di halaman ini.

Jika Anda sudah tahu nama persisnya, cari langsung dengan cara ini:

code_symbol(workspace_id: "...", repo_id: "...", name: "MyClass")

Lacak pemanggilan

Keduanya menerima symbol_id dari hasil pencarian, ditambah limit opsional (bawaan 50):

code_callers(workspace_id: "...", symbol_id: "...")
code_callees(workspace_id: "...", symbol_id: "...")

code_callers mengembalikan simbol yang memiliki tepi masuk ke simbol ini; code_callees mengembalikan simbol yang menjadi dependensinya.

Periksa apa yang akan rusak akibat perubahan

Inilah alat yang menjadi alasan seluruh halaman ini ada:

code_impact(workspace_id: "...", symbol_id: "...", depth: 3)

Alat ini menghitung radius dependensi terbalik: semua hal yang secara langsung maupun transitif bergantung pada simbol itu melalui tepi calls, extends, dan implements (impor, mix-in, dan referensi generik disimpan di graf tetapi tidak ditelusuri di sini). depth adalah jumlah lompatan maksimum, antara 1 dan 6, dengan bawaan 2.

Hasilnya terdiri atas tiga field:

root — simbol yang Anda tanyakan
impacted — himpunan yang dapat dijangkau, termasuk root pada kedalaman 0, masing-masing membawa depth-nya dari root
edgeCount — berapa banyak tepi yang dilintasi penelusuran, sebagai hitungan dan bukan tepinya sendiri

Jalankan alat ini sebelum Anda mengganti nama atau mengubah signature, dan berikan daftar impacted kepada agen sebagai cakupan kerjanya.

Hasil diperiksa terhadap salinan kerja milik pemanggil

Untuk pemanggil berupa agen, id space disuntikkan secara otomatis dan hasilnya diverifikasi terhadap salinan kerja milik space tersebut. Simbol yang filenya sudah tidak ada lagi di pohon pemanggil akan dihilangkan, dan responsnya membawa hitungan staleOmitted beserta catatan bahwa indeks sudah usang untuk simbol-simbol itu.

Inilah sebabnya Anda dan agen bisa mendapat jawaban berbeda untuk kueri yang sama, dan sebabnya agen di satu space bisa mendapat jawaban berbeda dari agen di space lain. Setiap percakapan dalam satu space berbagi worktree yang sama itu. Verifikasi bersifat fail-open: jawaban yang usang lebih dipilih daripada jawaban kosong.

Minta agen menjalankan code_impact (atau review_studio.blastRadius) saat Anda ingin mengetahui radius dampak suatu perubahan. Lihat Komputasi tinjauan.

Pencarian semantik memerlukan model embedding

Simbol dan fakta di-embed pada saat penulisan, dan hanya jika model embedding di perangkat sudah terpasang. Sebelum itu, mode: "semantic" dan bagian semantik dari hybrid tidak punya apa pun untuk dicocokkan, sehingga pencarian praktis hanya berbasis kata kunci.

Pasang modelnya di Pengaturan → Server → Diagnostik & privasi → Pencarian semantik sebelum Anda mengindeks. Simbol memperoleh vektor saat filenya dicerna.

Perhatikan juga bahwa pembangunan ulang biner server akan menyiapkan ulang dylib grammar dan mengubah mtime-nya, yang membatalkan setiap checkpoint indeks dan memaksa satu penelusuran ulang penuh atas setiap checkout pada eksekusi berikutnya. File akan di-hash ulang, tetapi file yang tidak berubah tidak diekstrak ulang.

Apa yang ada di graf

Jenis simbol: function, method, class, field, enum, constructor, getter, setter, typedef, extension, mixin, variable.

Jenis tepi: calls, imports, extends, implements, mixes in, references.

Signature kanonis untuk alat-alat ini ada di Alat MCP.

Panduan terkait

Konsep terkait

Ruang kerja dan isolasi