Caută cod cu graful de cod

Acest ghid îți arată cum să aduci un repo în graful de cod și apoi cum să îl folosești ca să răspundă întrebării pe care o ai de fapt înainte de o refactorizare: de ce depinde asta?

Graful de cod este o bază de date de simboluri și muchii, construită prin analizarea sintactică a checkout-urilor tale înregistrate cu tree-sitter. Instrumentele sale sunt destinate agenților — le folosești cerându-i unui agent.

Înainte de a începe

Graful indexează Dart, JavaScript, TypeScript, TSX, PHP, Python, Rust, Zig, C, C++, Go, Java, Ruby, C#, Swift, Kotlin, R, Assembly, MATLAB și Ada. Fișierele din orice alt limbaj nu sunt analizate sintactic, deci nu apar în search_code, code_symbol, code_callers, code_callees sau code_impact.

Încă două lucruri influențează ce se indexează:

Într-un arbore de lucru git, enumerarea se bazează pe git ls-files --cached --others --exclude-standard, așa că fiecare .gitignore, fișier de ignorare imbricat, .git/info/exclude și fișierul global de excluderi sunt respectate. Acesta este mecanismul care ține node_modules și rezultatele de build în afara grafului.
Codul Dart generat este eliminat indiferent de situație. Fișierele generate sunt de obicei incluse în commit, așa că git singur nu le-ar exclude, iar ele se schimbă la fiecare rulare de generare de cod.

Indexează un repo

Înregistrarea unui checkout declanșează RepoAdded, care pornește automat pipeline-ul index_code pentru el. Vezi Adaugă repo-uri într-un spațiu de lucru.

Pentru a reindexa manual:

Deschide Setări → Spațiu de lucru → Depozite.
Apasă butonul Indexează codul din rândul repo-ului.
Cât timp rulează, butonul afișează fișierele finalizate din total, împreună cu un control de anulare. Când se termină, se stabilizează într-o bifă cu numărul de simboluri.

Graful este partiționat pe spațiu de lucru, repo și checkout: checkout-ul legat este o partiție, iar fiecare worktree de spațiu primește propria partiție (identificată prin id-ul ei de repo izolat).

Merită să cunoști două limitări, pentru că ele explică o așteptare care pare o blocare:

Monitorul de fișiere admite o singură rulare de indexare simultan pe gazdă — un al doilea checkout așteaptă. Pipeline-ul index_code este limitat separat la o rulare pe spațiu de lucru, așa că două repo-uri din același spațiu de lucru stau la coadă; spații de lucru diferite pot indexa în paralel. Indexatorul însuși serializează două rulări ale aceluiași checkout, astfel încât pornirea unui pipeline și o trecere a monitorului să nu îl poată analiza de două ori.
Worktree-urile care aparțin spațiilor inactive (niciun mesaj în ultima săptămână) nu sunt nici monitorizate, nici indexate. Checkout-urile legate rămân monitorizate. O decizie de omitere este reverificată după cinci minute, așa că un spațiu care redevine activ este preluat.

Găsește un simbol

Cere-i unui agent să caute. Instrumentul este search_code și are nevoie atât de un spațiu de lucru, cât și de un repo:

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

Id-urile de repo vin de la list_repos. Argumentul opțional mode este keyword, semantic sau hybrid și are valoarea implicită hybrid — BM25 peste nume, semnături și comentarii de documentație, combinat cu similaritatea vectorială.

Fiecare rezultat conține id-ul simbolului, numele, numele calificat, tipul, calea fișierului, linia de început și de sfârșit și semnătura lui, atunci când are una. id-ul este identificatorul pe care îl transmiți oricărui alt instrument de pe această pagină.

Când știi numele exact, caută-l direct în schimb:

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

Urmărește apelurile

Ambele primesc un symbol_id dintr-un rezultat de căutare, plus un limit opțional (implicit 50):

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

code_callers returnează simbolurile cu o muchie de intrare către acesta; code_callees le returnează pe cele de care depinde.

Verifică ce ar strica o modificare

Acesta este instrumentul pentru care există toată pagina:

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

Calculează raza dependențelor inverse: tot ce depinde direct sau tranzitiv de simbol pe muchiile calls, extends și implements (importurile, mixin-urile și referințele generice sunt stocate în graf, dar nu sunt parcurse aici). depth este numărul maxim de salturi, între 1 și 6, cu valoarea implicită 2.

Rezultatul are trei câmpuri:

root — simbolul despre care ai întrebat
impacted — mulțimea accesibilă, inclusiv rădăcina la adâncimea 0, fiecare purtându-și depth față de rădăcină
edgeCount — câte muchii a traversat parcurgerea, ca număr, nu muchiile în sine

Rulează-l înainte de a redenumi sau de a schimba o semnătură și dă-i agentului lista celor impactate drept sfera lui de lucru.

Rezultatele sunt verificate față de copia de lucru proprie a apelantului

Pentru un apelant de tip agent, id-ul spațiului este injectat automat, iar rezultatele sunt verificate față de copia de lucru a acelui spațiu. Un simbol al cărui fișier nu mai există în arborele apelantului este omis, iar răspunsul conține un număr staleOmitted și o notă care spune că indexul este învechit pentru acele simboluri.

De aceea tu și un agent puteți primi răspunsuri diferite la aceeași interogare și de aceea un agent dintr-un spațiu poate primi un răspuns diferit de al unui agent din alt spațiu. Fiecare conversație dintr-un spațiu partajează acel unic worktree. Verificarea e permisivă la eșec: un răspuns învechit este preferat unuia gol.

Cere-i unui agent să ruleze code_impact (sau review_studio.blastRadius) când vrei raza de impact a unei modificări. Vezi Calculul revizuirii.

Căutarea semantică are nevoie de modelul de embedding

Simbolurile și faptele sunt încorporate vectorial în momentul scrierii și numai când modelul de embedding de pe dispozitiv este instalat. Până atunci, mode: "semantic" și jumătatea semantică a modului hybrid nu au cu ce să se potrivească, iar căutarea este practic doar pe cuvinte-cheie.

Instalează modelul la Setări → Server → Diagnosticări și confidențialitate → Căutare semantică înainte de a indexa. Simbolurile primesc un vector în momentul în care fișierul lor este ingerat.

Reține și că orice recompilare a binarului serverului repregătește dylib-urile gramaticilor și le schimbă mtime-urile, ceea ce invalidează fiecare checkpoint de index și forțează o nouă parcurgere completă a fiecărui checkout la următoarea rulare. Recalculează hash-urile, dar nu reextrage fișierele nemodificate.

Ce se află în graf

Tipuri de simboluri: funcție, metodă, clasă, câmp, enum, constructor, getter, setter, typedef, extensie, mixin, variabilă.

Tipuri de muchii: apeluri, importuri, extindere, implementare, mixin-uri, referințe.

Semnăturile canonice pentru aceste instrumente se află în Instrumente MCP.

Ghiduri conexe

Concepte conexe

Spații de lucru și izolare