Tìm mã bằng đồ thị mã

Hướng dẫn này chỉ cho bạn cách đưa một kho mã vào đồ thị mã, rồi dùng nó để trả lời câu hỏi mà bạn thực sự có trước một lần tái cấu trúc: cái gì phụ thuộc vào thứ này?

Đồ thị mã là một cơ sở dữ liệu về ký hiệu và cạnh, được dựng bằng cách phân tích cú pháp các bản checkout đã đăng ký của bạn bằng tree-sitter. Các công cụ của nó hướng tới agent — bạn tiếp cận chúng bằng cách hỏi một agent.

Trước khi bắt đầu

Đồ thị lập chỉ mục cho Dart, JavaScript, TypeScript, TSX, PHP, Python, Rust, Zig, C, C++, Go, Java, Ruby, C#, Swift, Kotlin, R, Assembly, MATLAB và Ada. Các tệp thuộc bất kỳ ngôn ngữ nào khác đều không được phân tích cú pháp, nên chúng không xuất hiện trong search_code, code_symbol, code_callers, code_callees hay code_impact.

Hai điều nữa định hình những gì được lập chỉ mục:

Trong một worktree git, bước liệt kê dựa vào git ls-files --cached --others --exclude-standard, nên mọi .gitignore, tệp loại trừ lồng nhau, .git/info/exclude và tệp loại trừ toàn cục đều được tôn trọng. Đó là thứ giữ node_modules và đầu ra bản dựng khỏi đồ thị.
Dart được sinh tự động thì luôn bị loại bỏ, bất kể cấu hình. Các tệp sinh tự động thường được commit, nên chỉ git thì không loại trừ chúng, và chúng bị xáo trộn sau mỗi lần chạy sinh mã.

Đưa một kho mã vào chỉ mục

Việc đăng ký một bản checkout kích hoạt RepoAdded, sự kiện này tự động khởi động quy trình index_code cho nó. Xem Thêm kho mã vào không gian làm việc.

Để lập chỉ mục lại bằng tay:

Mở Cài đặt → Không gian làm việc → Kho lưu trữ.
Nhấn nút Lập chỉ mục mã trên dòng của kho mã đó.
Trong lúc chạy, nút hiển thị số tệp đã xong trên tổng số, kèm một nút hủy. Khi chạy xong, nó lắng lại thành một dấu kiểm kèm số lượng ký hiệu.

Đồ thị được phân vùng theo không gian làm việc, kho mã và bản checkout: bản checkout được liên kết là một phân vùng, còn mỗi worktree của space có phân vùng riêng (khóa theo id kho mã cô lập của nó).

Có hai cơ chế điều tiết đáng để biết, vì chúng giải thích một khoảng chờ trông như bị treo:

Bộ theo dõi tệp chỉ nhận một lượt lập chỉ mục tại một thời điểm trên máy chủ — một bản checkout thứ hai phải chờ. Quy trình index_code cũng bị giới hạn riêng ở một lượt chạy cho mỗi không gian làm việc, nên hai kho mã trong cùng một không gian làm việc phải xếp hàng; những không gian làm việc khác nhau có thể lập chỉ mục song song. Bản thân trình lập chỉ mục tuần tự hóa hai lượt chạy trên cùng một bản checkout, để một lần khởi động quy trình và một lượt quét của bộ theo dõi không thể phân tích cú pháp nó hai lần.
Những worktree thuộc space không hoạt động (không có tin nhắn nào trong tuần trước) thì không được theo dõi lẫn lập chỉ mục. Các bản checkout được liên kết vẫn được theo dõi. Một quyết định bỏ qua sẽ được kiểm tra lại sau năm phút, nên một space hoạt động trở lại sẽ được đưa vào trở lại.

Tìm một ký hiệu

Hãy yêu cầu một agent tìm kiếm. Công cụ là search_code và nó cần cả một không gian làm việc lẫn một kho mã:

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

Id kho mã đến từ list_repos. Tham số tùy chọn mode nhận các giá trị keyword, semantic hoặc hybrid và mặc định là hybrid — BM25 trên tên, chữ ký và chú thích tài liệu, hợp nhất với độ tương đồng vector.

Mỗi kết quả mang id, tên, tên đầy đủ, loại, đường dẫn tệp, dòng bắt đầu và dòng kết thúc của ký hiệu, cùng chữ ký của nó khi có. id chính là tay nắm mà bạn truyền cho mọi công cụ khác trên trang này.

Khi đã biết chính xác tên, hãy tra thẳng nó thay vì tìm kiếm:

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

Truy vết các lời gọi

Cả hai đều nhận một symbol_id từ kết quả tìm kiếm, cùng một limit tùy chọn (mặc định 50):

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

code_callers trả về những ký hiệu có một cạnh đi vào ký hiệu này; code_callees trả về những ký hiệu mà nó phụ thuộc vào.

Kiểm tra một thay đổi sẽ làm hỏng những gì

Đây là công cụ mà cả trang này tồn tại vì nó:

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

Nó tính bán kính phụ thuộc ngược: mọi thứ phụ thuộc trực tiếp hoặc gián tiếp vào ký hiệu theo các cạnh calls, extends và implements (import, mixin và tham chiếu generic được lưu trong đồ thị nhưng không được duyệt ở đây). depth là số bước nhảy tối đa, trong khoảng từ 1 đến 6, mặc định là 2.

Kết quả gồm ba trường:

root — ký hiệu mà bạn đã hỏi tới
impacted — tập hợp có thể tiếp cận được, bao gồm cả gốc ở độ sâu 0, mỗi phần tử mang depth của nó tính từ gốc
edgeCount — số cạnh mà lượt duyệt đã đi qua, dưới dạng một con số thay vì chính các cạnh đó

Hãy chạy nó trước khi bạn đổi tên hay thay đổi chữ ký, rồi đưa danh sách bị ảnh hưởng cho agent làm phạm vi hoạt động.

Kết quả được đối chiếu với bản làm việc của chính bên gọi

Với bên gọi là agent, id space được tự động chèn vào và kết quả được đối chiếu với bản làm việc của chính space đó. Một ký hiệu có tệp không còn tồn tại trong cây của bên gọi sẽ bị bỏ qua, và phản hồi mang theo một bộ đếm staleOmitted cùng một ghi chú cho biết chỉ mục đã cũ đối với những ký hiệu đó.

Đó là lý do bạn và một agent có thể nhận được những câu trả lời khác nhau cho cùng một truy vấn, và cũng là lý do một agent trong space này có thể nhận câu trả lời khác với một agent trong space khác. Mọi cuộc hội thoại trong một space dùng chung một worktree đó. Việc đối chiếu thất bại theo hướng mở: một câu trả lời cũ vẫn được ưu tiên hơn một câu trả lời rỗng.

Hãy yêu cầu một agent chạy code_impact (hoặc review_studio.blastRadius) khi bạn muốn biết bán kính ảnh hưởng của một thay đổi. Xem Tính toán đánh giá.

Tìm kiếm ngữ nghĩa cần mô hình embedding

Ký hiệu và dữ kiện được nhúng vector ngay tại thời điểm ghi, và chỉ khi mô hình embedding trên thiết bị đã được cài. Trước đó, mode: "semantic" và nửa ngữ nghĩa của chế độ hybrid không có gì để so khớp, và tìm kiếm thực chất chỉ còn theo từ khóa.

Hãy cài mô hình tại Cài đặt → Máy chủ → Chẩn đoán & quyền riêng tư → Tìm kiếm ngữ nghĩa trước khi lập chỉ mục. Ký hiệu nhận một vector khi tệp chứa nó được nạp vào.

Cũng lưu ý rằng mọi lần dựng lại tệp nhị phân của máy chủ đều đưa các dylib ngữ pháp vào lại và thay đổi mtime của chúng, khiến mọi checkpoint của chỉ mục trở nên vô hiệu và buộc một lượt quét lại toàn bộ mỗi bản checkout ở lần chạy kế tiếp. Nó băm lại, nhưng không trích xuất lại những tệp không đổi.

Đồ thị chứa những gì

Các loại ký hiệu: function, method, class, field, enum, constructor, getter, setter, typedef, extension, mixin, variable.

Các loại cạnh: calls, imports, extends, implements, mixes in, references.

Chữ ký chuẩn tắc của những công cụ này nằm trong Công cụ MCP.

Hướng dẫn liên quan

Khái niệm liên quan

Không gian làm việc và cô lập