Szukaj kodu w grafie kodu

Ten poradnik pokazuje, jak wprowadzić repozytorium do grafu kodu, a następnie użyć go, aby odpowiedzieć na pytanie, które naprawdę masz przed refaktoryzacją: co od tego zależy?

Graf kodu to baza symboli i krawędzi budowana przez parsowanie zarejestrowanych kopii roboczych za pomocą tree-sittera. Jego narzędzia są skierowane do agentów — sięgasz po nie, prosząc agenta.

Zanim zaczniesz

Graf indeksuje Dart, JavaScript, TypeScript, TSX, PHP, Python, Rust, Zig, C, C++, Go, Java, Ruby, C#, Swift, Kotlin, R, Assembly, MATLAB i Ada. Pliki w jakimkolwiek innym języku nie są parsowane, więc nie pojawiają się w search_code, code_symbol, code_callers, code_callees ani code_impact.

To, co trafia do indeksu, kształtują jeszcze dwie rzeczy:

W drzewie roboczym gita wyliczanie opiera się na git ls-files --cached --others --exclude-standard, więc każdy plik .gitignore, zagnieżdżony plik ignorujący, .git/info/exclude oraz globalny plik wykluczeń jest respektowany. To właśnie trzyma node_modules i wyniki kompilacji poza grafem.
Wygenerowany kod Dart jest odrzucany niezależnie od tego. Wygenerowane pliki są zwykle zatwierdzane w repozytorium, więc sam git by ich nie wykluczył, a przy każdym uruchomieniu generatora kodu powodują szum zmian.

Zindeksuj repozytorium

Zarejestrowanie kopii roboczej wyzwala RepoAdded, co automatycznie uruchamia dla niej potok index_code. Zobacz Dodaj repozytoria do obszaru roboczego.

Aby zindeksować ponownie ręcznie:

Otwórz Ustawienia → Obszar roboczy → Repozytoria.
Kliknij przycisk Indeksuj kod w wierszu repozytorium.
Podczas działania przycisk pokazuje liczbę przetworzonych plików względem wszystkich, wraz ze sterowaniem anulowaniem. Po zakończeniu zmienia się w znacznik potwierdzenia z liczbą symboli.

Graf jest dzielony na partycje według obszaru roboczego, repozytorium i kopii roboczej: powiązana kopia robocza to jedna partycja, a każdy worktree przestrzeni ma własną (kluczowaną po identyfikatorze izolowanego repozytorium).

Warto znać dwa ograniczenia przepustowości, bo wyjaśniają oczekiwanie, które wygląda jak zawieszenie:

Obserwator plików dopuszcza na hoście tylko jedno uruchomienie indeksowania naraz — druga kopia robocza czeka. Potok index_code ma osobny limit jednego uruchomienia na obszar roboczy, więc dwa repozytoria w tym samym obszarze roboczym trafiają do kolejki; różne obszary robocze mogą indeksować równolegle. Sam indekser szereguje dwa uruchomienia tej samej kopii roboczej, więc uruchomienie potoku i przebieg obserwatora nie mogą jej sparsować podwójnie.
Worktree należące do uśpionych przestrzeni (brak wiadomości od tygodnia) nie są ani obserwowane, ani indeksowane. Powiązane kopie robocze pozostają obserwowane. Decyzja o pominięciu jest sprawdzana ponownie po pięciu minutach, więc przestrzeń, która znów stanie się aktywna, zostanie uwzględniona.

Znajdź symbol

Poproś agenta o wyszukanie. Narzędzie nazywa się search_code i wymaga zarówno obszaru roboczego, jak i repozytorium:

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

Identyfikatory repozytoriów pochodzą z list_repos. Opcjonalny argument mode przyjmuje wartości keyword, semantic lub hybrid i domyślnie jest to hybrid — BM25 po nazwach, sygnaturach i komentarzach dokumentacyjnych, łączone z podobieństwem wektorowym.

Każdy wynik zawiera identyfikator symbolu, nazwę, nazwę kwalifikowaną, rodzaj, ścieżkę pliku, wiersz początkowy i końcowy oraz jego sygnaturę, jeśli ją ma. id to uchwyt, który przekazujesz do każdego innego narzędzia na tej stronie.

Gdy znasz dokładną nazwę, wyszukaj ją bezpośrednio:

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

Prześledź wywołania

Oba przyjmują symbol_id z wyniku wyszukiwania oraz opcjonalny limit (domyślnie 50):

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

code_callers zwraca symbole z krawędzią wchodzącą do tego symbolu; code_callees zwraca te, od których on zależy.

Sprawdź, co zepsuje zmiana

To narzędzie, dla którego istnieje cała ta strona:

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

Oblicza ono promień zależności odwrotnych: wszystko, co bezpośrednio lub przechodnio zależy od symbolu wzdłuż krawędzi calls, extends i implements (importy, domiksowania i odwołania generyczne są przechowywane w grafie, ale nie są tu przechodzone). depth to maksymalna liczba skoków, od 1 do 6, domyślnie 2.

Wynik to trzy pola:

root — symbol, o który pytasz
impacted — zbiór osiągalny, wraz z korzeniem na głębokości 0, gdzie każdy element niesie swoją depth od korzenia
edgeCount — ile krawędzi przekroczyło przejście, jako liczba, a nie same krawędzie

Uruchom je, zanim zmienisz nazwę lub sygnaturę, i podaj agentowi listę elementów objętych wpływem jako jego zakres.

Wyniki są weryfikowane względem kopii roboczej wywołującego

W przypadku wywołującego-agenta identyfikator przestrzeni jest wstrzykiwany automatycznie, a wyniki są weryfikowane względem kopii roboczej tej przestrzeni. Symbol, którego plik nie istnieje już w drzewie wywołującego, jest pomijany, a odpowiedź zawiera licznik staleOmitted oraz uwagę, że indeks jest nieaktualny dla tych symboli.

Dlatego ty i agent możecie otrzymać różne odpowiedzi na to samo zapytanie i dlatego agent w jednej przestrzeni może otrzymać inną odpowiedź niż agent w innej. Każda rozmowa w przestrzeni dzieli ten jeden worktree. Weryfikacja zawodzi w bezpieczną stronę: nieaktualna odpowiedź jest lepsza od pustej.

Poproś agenta o uruchomienie code_impact (albo review_studio.blastRadius), gdy chcesz poznać promień wpływu zmiany. Zobacz Obliczenia recenzji.

Wyszukiwanie semantyczne wymaga modelu osadzeń

Symbole i fakty są osadzane w momencie zapisu i tylko wtedy, gdy zainstalowany jest model osadzeń na urządzeniu. Do tego czasu mode: "semantic" i semantyczna połowa trybu hybrid nie mają do czego dopasowywać i wyszukiwanie działa praktycznie tylko po słowach kluczowych.

Zainstaluj model w Ustawienia → Serwer → Diagnostyka i prywatność → Wyszukiwanie semantyczne przed indeksowaniem. Symbole otrzymują wektor, gdy ich plik zostanie wczytany.

Pamiętaj też, że każda przebudowa pliku binarnego serwera ponownie przygotowuje biblioteki dylib gramatyk i zmienia ich znaczniki czasu modyfikacji, co unieważnia każdy punkt kontrolny indeksu i wymusza jedno pełne ponowne przejście po każdej kopii roboczej przy następnym uruchomieniu. Skróty są liczone ponownie, ale niezmienione pliki nie są ponownie ekstrahowane.

Co znajduje się w grafie

Rodzaje symboli: function, method, class, field, enum, constructor, getter, setter, typedef, extension, mixin, variable.

Rodzaje krawędzi: calls, imports, extends, implements, mixes in, references.

Kanoniczne sygnatury tych narzędzi znajdują się w Narzędzia MCP.

Powiązane poradniki

Powiązane koncepcje

Obszary robocze i izolacja