Chuyển tới nội dung

Tài liệu tham chiếu API MCP

Khám phá 11 công cụ MCP của Maguyva, các tham số và thời điểm dùng từng công cụ. Kiểm tra phản hồi tools/list của trình khách đã kết nối để biết các đối số khả dụng.

Tổng quan API

#

Các công cụ được chia thành 4 nhóm:

  • Công cụ tìm kiếm cốt lõi - Khả năng tìm kiếm nâng cao trên toàn bộ codebase của bạn
  • Công cụ cấu trúc & đồ thị - Truy vấn AST, tra cứu ký hiệu và phân tích phụ thuộc
  • Công cụ phân tích mã - Phân tích mã chuyên sâu và ánh xạ các mối quan hệ
  • Công cụ hệ thống & tiện ích - Ngữ cảnh kho mã, hướng dẫn công cụ và phản hồi

Với công cụ chấp nhận kho mã, dùng định dạng định danh repository này: "owner/repo:branch". Nhánh mặc định là main nếu không chỉ định.

Bỏ repository khi MCP client của bạn cung cấp mặc định theo từng yêu cầu hoặc khi khóa có thể truy cập đúng một repository; ngược lại, truyền rõ ràng. Dùng repository_context(action="info", repository="owner/repo") để kiểm tra cách một repository được phân giải.

Định dạng tham số Repository

#

Dùng các định dạng sau khi chỉ định kho mã:

  • Có nhánh: "owner/repo:branch" - ví dụ, "owner/repository:develop"
  • Nhánh mặc định: "owner/repo" - dùng nhánh main khi không chỉ định nhánh "owner/repository"
  • Mặc định theo yêu cầu hoặc repository duy nhất: Bỏ repository khi MCP client cung cấp giá trị mặc định cho yêu cầu hoặc khóa chỉ truy cập được đúng một repository; nếu không, hãy truyền rõ ràng.

Ví dụ prompt:

Hỏi về một repo cụ thể:            "Tìm middleware xác thực trong owner/my-repo"
Liệt kê các repo có thể truy cập:  "Khóa Maguyva này có thể truy cập những repo nào?"
Ghi đè cho một truy vấn:           "Tìm các mẫu xác thực trong owner/other-repo:develop"

Lọc theo ngôn ngữ

#

Dùng language_filter trong các chế độ tìm kiếm có hỗ trợ. Với text_pattern_search, chọn search_scope="content"; với get_task_context, dùng scope="semantic" không kèm điểm xuất phát hay ngữ cảnh liên quan.

  • language_filter="python" - Chỉ lọc file Python
  • language_filter="typescript" - Chỉ lọc file TypeScript
  • Phân biệt hoa thường: Dùng tên ngôn ngữ viết thường
  • Mặc định: Chuỗi rỗng (không lọc) - trả về kết quả từ mọi ngôn ngữ
  • Phạm vi hỗ trợ: Bộ lọc ngôn ngữ hoạt động trên toàn bộ 285+ ngôn ngữ và công nghệ dựa trên văn bản được hỗ trợ. Xem tương thích để có danh sách đầy đủ. 
"Chỉ tìm middleware xác thực trong các tệp Python"
"Tìm kiếm kết nối cơ sở dữ liệu trong TypeScript"

Tài liệu tham chiếu API được sinh từ mã nguồn vào 21 tháng 10, 2026.

Công cụ tìm kiếm cốt lõi

#

intelligent_search Ổn định

Bắt đầu tại đây với mọi câu hỏi về mã nguồn. Chế độ mặc định auto/balanced chuyển các truy vấn được nhận diện chắc chắn là hỏi về định nghĩa sang tìm kiếm cấu trúc, truy vấn về tham chiếu hoặc tác động sang đồ thị, và truy vấn cần khớp chính xác sang tìm kiếm văn bản. Các truy vấn khác dùng ngữ nghĩa và văn bản đã lập chỉ mục. Dùng mode=hybrid hoặc auto với quality=thorough để yêu cầu cả bốn phương thức tìm kiếm; chế độ được chỉ định rõ có ưu tiên cao hơn quality. language_filter loại đồ thị khỏi auto/hybrid và từ chối mode=graph được chỉ định rõ. Ưu tiên dùng công cụ này thay cho Grep/Glob khi bạn chưa biết đường dẫn.

Tham số:

query Bắt buộc
Kiểu
str minLength=1
Mô tả
Truy vấn tìm kiếm
repository Tùy chọn
Kiểu
str
Mô tả
Repository theo định dạng owner/repo[:branch]. Tùy chọn — không truyền tham số này để dùng repository mặc định do trình khách cung cấp cho yêu cầu (nếu có), hoặc repository duy nhất mà khóa có thể truy cập. Chỉ truyền tường minh khi muốn nhắm tới một repo đã lập chỉ mục khác. Ưu tiên các nhánh đã lập chỉ mục khớp chính xác; nhánh không khả dụng có thể chuyển về main hoặc nhánh duy nhất có thể truy cập. Metadata của phản hồi cho biết danh tính được yêu cầu và danh tính thực sự được dùng, đồng thời cảnh báo khi xảy ra việc chuyển này.
mode Tùy chọn
Kiểu
Literal[auto, hybrid, semantic, text, structural, ast, graph]
Mặc định
auto
Mô tả
Chế độ tìm kiếm
limit Tùy chọn
Kiểu
int minimum=1, maximum=50
Mặc định
10
Mô tả
Số kết quả tối đa trong cửa sổ top-K được xếp hạng này
language_filter Tùy chọn
Kiểu
str
Mô tả
Bộ lọc ngôn ngữ
path_filter Tùy chọn
Kiểu
str
Mô tả
Lọc các ứng viên truy xuất theo tiền tố đường dẫn file. Các nút lân cận trong đồ thị và ngữ cảnh cộng đồng đính kèm có thể bao gồm các file nằm ngoài tiền tố này.
boost_by_importance Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Tùy chọn bật: xếp hạng lại theo độ trung tâm bằng các chỉ số đồ thị của từng ký hiệu (is_articulation_point, bridge_count, k_core, centrality, v.v.). Mặc định tắt để giữ xếp hạng an toàn cho agent (các nút trung tâm toàn cục có thể lấn át kết quả chứa mã triển khai); bật khi khám phá kiến trúc. Áp dụng cho cả 4 phương thức khi mỗi kết quả có liên kết tới ký hiệu.
branch Tùy chọn
Kiểu
str
Mô tả
Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
quality Tùy chọn
Kiểu
Literal[quick, balanced, thorough]
Mặc định
balanced
Mô tả
Preset chất lượng tìm kiếm
include_content Tùy chọn
Kiểu
bool
Mặc định
true
Mô tả
Bao gồm nội dung trong kết quả
explain_routing Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Bao gồm giải thích quyết định routing
importance_weight Tùy chọn
Kiểu
float minimum=0, maximum=1
Mặc định
0.3
Mô tả
Trọng số cho tăng cường tầm quan trọng (0=không, 1=đầy đủ)
orphans Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Bao gồm các ký hiệu mồ côi (không có tham chiếu trỏ đến)
include_community_context Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Bao gồm các symbol liên quan từ cùng code community để có context rộng hơn
community_depth Tùy chọn
Kiểu
int minimum=1, maximum=3
Mặc định
1
Mô tả
Độ sâu mở rộng context community
graph_view Tùy chọn
Kiểu
Literal[dependency, type, data_flow, control_flow]
Mặc định
dependency
Mô tả
Góc nhìn đồ thị dùng cho các chỉ số
seed_symbol_ids Tùy chọn
Kiểu
list[str] maxItems=20
Mô tả
Các ký hiệu khởi đầu cho tác vụ ở Tier-1: ID của những ký hiệu đóng vai trò trung tâm trong tác vụ hiện tại. Khi được cung cấp, các kết quả đã hợp nhất được xếp hạng lại theo độ gần với mức ảnh hưởng giảm dần theo độ sâu của Approach A (khớp chính xác ký hiệu khởi đầu + số bước qua các cạnh đồ thị). Đây là tín hiệu bổ sung — không truyền tham số này để dùng xếp hạng toàn cục.
seed_file_paths Tùy chọn
Kiểu
list[str] maxItems=10
Mô tả
Các tệp khởi đầu cho tác vụ ở Tier-1: đường dẫn tệp đã lập chỉ mục mà agent đang mở hoặc vừa chỉnh sửa. Khi được cung cấp, các kết quả đã hợp nhất được xếp hạng lại theo độ gần của đường dẫn, với trọng số giảm theo độ sâu bằng 1/(1+d) (cùng tệp → cùng thư mục → các gói lân cận). Đây là tín hiệu bổ sung — không truyền tham số này để dùng xếp hạng toàn cục.

Phù hợp nhất cho:

  • Khám phá toàn bộ index hoặc cold-start khi chưa rõ nên dùng tool nào
  • Xếp hạng hợp nhất đa phương thức trên ngữ nghĩa, văn bản, cấu trúc và đồ thị

Không khuyến nghị cho:

  • Đã biết tên symbol — dùng trực tiếp find_symbol
  • Đã biết path trên đĩa — dùng local Read/Grep trước

semantic_search Ổn định

Tìm mã theo ý nghĩa thay vì văn bản chính xác. Dùng cho truy vấn khái niệm như 'logic thử lại' hoặc 'quy trình làm quen của người dùng' khi chưa biết từ khóa hay tên ký hiệu. Trả về các đoạn liên quan với độ đa dạng tệp được giới hạn; tùy chọn xếp hạng lại theo tầm quan trọng trong đồ thị được bật bằng boost_by_importance. Ưu tiên hơn Grep cho tìm kiếm khái niệm.

Tham số:

query Bắt buộc
Kiểu
str minLength=1
Mô tả
Truy vấn tìm kiếm (theo khái niệm, dựa trên ý nghĩa)
repository Tùy chọn
Kiểu
str
Mô tả
Repository theo định dạng owner/repo[:branch]. Tùy chọn — không truyền tham số này để dùng repository mặc định do trình khách cung cấp cho yêu cầu (nếu có), hoặc repository duy nhất mà khóa có thể truy cập. Chỉ truyền tường minh khi muốn nhắm tới một repo đã lập chỉ mục khác. Ưu tiên các nhánh đã lập chỉ mục khớp chính xác; nhánh không khả dụng có thể chuyển về main hoặc nhánh duy nhất có thể truy cập. Metadata của phản hồi cho biết danh tính được yêu cầu và danh tính thực sự được dùng, đồng thời cảnh báo khi xảy ra việc chuyển này.
limit Tùy chọn
Kiểu
int minimum=1, maximum=50
Mặc định
5
Mô tả
Số kết quả tối đa trong cửa sổ top-K được xếp hạng này
similarity_threshold Tùy chọn
Kiểu
float minimum=0, maximum=1
Mặc định
0.6
Mô tả
Ngưỡng điểm tương đồng tối thiểu
language_filter Tùy chọn
Kiểu
str
Mô tả
Bộ lọc ngôn ngữ (python, typescript, v.v.)
path_filter Tùy chọn
Kiểu
str
Mô tả
Lọc theo tiền tố đường dẫn tệp
boost_by_importance Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Tùy chọn bật: xếp hạng lại theo tầm quan trọng trong đồ thị đã chuẩn hóa cho từng ký hiệu (mặc định tắt; tối đa 1,5 lần độ tương đồng).
branch Tùy chọn
Kiểu
str
Mô tả
Ghi đè nhánh (mặc định: lấy từ tham số repository hoặc main); chỉ áp dụng cho một lần gọi
include_content Tùy chọn
Kiểu
bool
Mặc định
true
Mô tả
Bao gồm nội dung chunk trong kết quả
graph_view Tùy chọn
Kiểu
Literal[dependency, type, data_flow, control_flow]
Mặc định
dependency
Mô tả
Góc nhìn đồ thị dùng cho các chỉ số

Phù hợp nhất cho:

  • Truy vấn khái niệm ("xác thực hoạt động như thế nào?", "chiến lược bộ nhớ đệm")
  • Tìm kiếm tương đồng giữa các gói

Không khuyến nghị cho:

  • Đã biết tên symbol — dùng find_symbol thay thế
  • Chuỗi chính xác hoặc thông báo lỗi — dùng text_pattern_search

text_pattern_search Ổn định

Tìm nội dung đã lập chỉ mục. exact và regex dùng grep trên toàn bộ tập tệp/blob; fuzzy content tìm trong tập đoạn ngữ nghĩa có giới hạn. Phạm vi file và symbol chỉ dùng trigram — mode=exact mặc định được chuyển thành fuzzy. Các tùy chỉnh ngôn ngữ, hoa/thường và ngưỡng riêng yêu cầu phạm vi content. Bộ lọc đường dẫn dùng cửa sổ ứng viên giới hạn và báo khi độ bao phủ chưa đầy đủ. Dùng Grep cục bộ cho thư mục hẹp đã có trên đĩa.

Tham số:

query Bắt buộc
Kiểu
str minLength=1
Mô tả
Pattern văn bản cần tìm
repository Tùy chọn
Kiểu
str
Mô tả
Repository theo định dạng owner/repo[:branch]. Tùy chọn — không truyền tham số này để dùng repository mặc định do trình khách cung cấp cho yêu cầu (nếu có), hoặc repository duy nhất mà khóa có thể truy cập. Chỉ truyền tường minh khi muốn nhắm tới một repo đã lập chỉ mục khác. Ưu tiên các nhánh đã lập chỉ mục khớp chính xác; nhánh không khả dụng có thể chuyển về main hoặc nhánh duy nhất có thể truy cập. Metadata của phản hồi cho biết danh tính được yêu cầu và danh tính thực sự được dùng, đồng thời cảnh báo khi xảy ra việc chuyển này.
mode Tùy chọn
Kiểu
Literal[fuzzy, exact, regex]
Mặc định
exact
Mô tả
Chế độ tìm kiếm. Regex thực thi cú pháp nâng cao/POSIX của PostgreSQL; dùng \y cho ranh giới từ (\b nghĩa là backspace). Các mẫu cũng phải qua trình xác thực an toàn JavaScript, vì vậy các cấu trúc chỉ dành riêng cho PostgreSQL như cờ (?i) nội tuyến sẽ bị từ chối; hãy dùng case_sensitive thay thế.
search_scope Tùy chọn
Kiểu
Literal[content, symbols, files]
Mặc định
content
Mô tả
Phạm vi tìm kiếm
limit Tùy chọn
Kiểu
int minimum=1, maximum=50
Mặc định
5
Mô tả
Số kết quả tối đa mỗi trang khi không dùng cursor. Việc tiếp tục sẽ dùng kích thước trang được lưu trong cursor; bỏ qua cursor để bắt đầu với một limit khác.
offset Tùy chọn
Kiểu
int minimum=0
Mô tả
Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.
cursor Tùy chọn
Kiểu
str
Mô tả
cursor không minh bạch lấy từ pagination.next_cursor. Truyền nguyên trạng và giữ nguyên query cùng các bộ lọc. Vị trí và kích thước trang của nó sẽ ghi đè offset và limit.
language_filter Tùy chọn
Kiểu
str
Mô tả
Bộ lọc ngôn ngữ
path_filter Tùy chọn
Kiểu
str
Mô tả
Lọc theo tiền tố đường dẫn tệp
case_sensitive Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
So khớp phân biệt chữ hoa/thường
branch Tùy chọn
Kiểu
str
Mô tả
Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
fuzzy_algorithm Tùy chọn
Kiểu
Literal[hybrid, trigram, levenshtein]
Mặc định
hybrid
Mô tả
Thuật toán so khớp fuzzy
threshold Tùy chọn
Kiểu
float minimum=0, maximum=1
Mặc định
0.05
Mô tả
Ngưỡng tương đồng tối thiểu cho fuzzy
semantic_fallback Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Thử semantic search sau khi trang lexical đầu tiên trống; metadata.fallback_status phân biệt các trạng thái dự phòng used, empty và unavailable.

Phù hợp nhất cho:

  • Chuỗi chính xác, thông báo lỗi và regex
  • Khớp trigram fuzzy cho văn bản gần đúng

Không khuyến nghị cho:

  • Đã biết path trên đĩa — ưu tiên local Grep
  • Truy vấn khái niệm — dùng semantic_search

Công cụ cấu trúc & đồ thị

#

structural_search Ổn định

Ưu tiên preset=functions|classes|methods|imports|variables (hoặc pattern= tự do). Tìm mã theo cấu trúc AST, không theo văn bản. Bộ lọc mức trung gian: name_pattern, node_type, decorator, parent_child. Bộ lọc đường dẫn/ltree/lời gọi thuộc loại nâng cao; đặt advanced=true khi chủ động dùng chúng. Nếu không đặt, bộ lọc nâng cao vẫn được áp dụng kèm cảnh báo trong siêu dữ liệu. Cung cấp ít nhất một bộ chọn cấu trúc.

Tham số:

repository Tùy chọn
Kiểu
str
Mô tả
Repository theo định dạng owner/repo[:branch]. Tùy chọn — không truyền tham số này để dùng repository mặc định do trình khách cung cấp cho yêu cầu (nếu có), hoặc repository duy nhất mà khóa có thể truy cập. Chỉ truyền tường minh khi muốn nhắm tới một repo đã lập chỉ mục khác. Ưu tiên các nhánh đã lập chỉ mục khớp chính xác; nhánh không khả dụng có thể chuyển về main hoặc nhánh duy nhất có thể truy cập. Metadata của phản hồi cho biết danh tính được yêu cầu và danh tính thực sự được dùng, đồng thời cảnh báo khi xảy ra việc chuyển này.
preset Tùy chọn
Kiểu
Literal[functions, classes, methods, imports, variables]
Mô tả
Bộ chọn cấu trúc được ưu tiên. Mở rộng thành các kiểu nút AST tương ứng giữa các ngôn ngữ — functions (các định nghĩa function/arrow/method trên nhiều ngôn ngữ); classes (các khai báo class/struct/interface, thân kiểu và các phần triển khai); methods (các định nghĩa method, và function_definition ở những ngôn ngữ không có nút method); imports (các câu lệnh import/use/include); variables (các khai báo variable/let/const/static). Ưu tiên dùng thay cho pattern/node_type dạng tự do khi duyệt mã.
pattern Tùy chọn
Kiểu
str
Mô tả
pattern dạng tự do sẽ lấp đầy các selector còn thiếu (tự động phát hiện: 'def foo(' → node_type + name_pattern). Có thể kết hợp với preset; các selector tường minh được ưu tiên hơn. Nên dùng preset= cho các truy vấn duyệt (browse).
name_pattern Tùy chọn
Kiểu
str maxLength=256
Mô tả
Pattern tên symbol (wildcard shell, regex POSIX có giới hạn, hoặc văn bản fuzzy; tối đa 256 ký tự)
node_type Tùy chọn
Kiểu
str
Mô tả
Loại node AST (function_definition, class_definition, v.v.) — ưu tiên preset= cho các hình dạng phổ biến
decorator Tùy chọn
Kiểu
str
Mô tả
Bộ lọc theo tên decorator
base_class Tùy chọn
Kiểu
str
Mô tả
Bộ lọc theo base class
language_filter Tùy chọn
Kiểu
str
Mô tả
Bộ lọc ngôn ngữ (python, typescript, v.v.)
limit Tùy chọn
Kiểu
int minimum=1, maximum=50
Mặc định
20
Mô tả
Số kết quả tối đa mỗi trang khi không dùng cursor. Việc tiếp tục sẽ dùng kích thước trang được lưu trong cursor; bỏ qua cursor để bắt đầu với một limit khác.
offset Tùy chọn
Kiểu
int minimum=0
Mô tả
Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.
cursor Tùy chọn
Kiểu
str
Mô tả
cursor không minh bạch lấy từ pagination.next_cursor. Truyền nguyên trạng và giữ nguyên query cùng các bộ lọc. Vị trí và kích thước trang của nó sẽ ghi đè offset và limit.
path_filter Tùy chọn
Kiểu
str
Mô tả
Lọc theo tiền tố đường dẫn tệp
branch Tùy chọn
Kiểu
str
Mô tả
Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
query_type Tùy chọn
Kiểu
Literal[node_type, name_pattern, parent_child]
Mô tả
Loại truy vấn được chỉ định tường minh
parent_type Tùy chọn
Kiểu
str
Mô tả
Bộ lọc kiểu node cha AST
relationship Tùy chọn
Kiểu
Literal[parent, ancestor]
Mặc định
parent
Mô tả
Với truy vấn parent_child: chỉ nút cha trực tiếp, hoặc bất kỳ nút tổ tiên nào (dùng ancestor cho các phương thức lớp nằm trong phần thân/khối của lớp)
has_modifier Tùy chọn
Kiểu
str
Mô tả
Lọc theo modifier (export, async, static, v.v.)
advanced Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Đặt true khi chủ động dùng bộ lọc đường dẫn/ltree/lời gọi nâng cao (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). Khi là false, các bộ lọc nâng cao được cung cấp vẫn áp dụng kèm cảnh báo trong siêu dữ liệu. Ưu tiên preset= cho truy vấn cấu trúc thông thường.
callee_text Tùy chọn
Kiểu
str
Mô tả
Nâng cao — ưu tiên preset=functions|classes|methods|imports|variables. Bộ lọc văn bản của đối tượng được gọi trong biểu thức gọi. Đặt advanced=true khi chủ động dùng các bộ lọc đường dẫn/ltree/lời gọi.
callee_name Tùy chọn
Kiểu
str
Mô tả
Nâng cao — ưu tiên preset=functions|classes|methods|imports|variables. Bộ lọc tên của đối tượng được gọi trong biểu thức gọi. Đặt advanced=true khi chủ động dùng các bộ lọc đường dẫn/ltree/lời gọi.
field_role Tùy chọn
Kiểu
str
Mô tả
Nâng cao — ưu tiên preset=functions|classes|methods|imports|variables. Bộ lọc vai trò của trường trong AST. Đặt advanced=true khi chủ động dùng các bộ lọc đường dẫn/ltree/lời gọi.
ltree_ancestor Tùy chọn
Kiểu
str
Mô tả
Nâng cao — ưu tiên preset=functions|classes|methods|imports|variables. Bộ lọc đường dẫn ltree của nút tổ tiên trong AST. Đặt advanced=true khi chủ động dùng các bộ lọc đường dẫn/ltree/lời gọi.
ltree_descendant Tùy chọn
Kiểu
str
Mô tả
Nâng cao — ưu tiên preset=functions|classes|methods|imports|variables. Bộ lọc đường dẫn ltree của nút hậu duệ trong AST. Đặt advanced=true khi chủ động dùng các bộ lọc đường dẫn/ltree/lời gọi.
definition_name Tùy chọn
Kiểu
str
Mô tả
Nâng cao — ưu tiên preset=functions|classes|methods|imports|variables. Bộ lọc tên định nghĩa. Đặt advanced=true khi chủ động dùng các bộ lọc đường dẫn/ltree/lời gọi.
min_depth Tùy chọn
Kiểu
int
Mô tả
Nâng cao — ưu tiên preset=functions|classes|methods|imports|variables. Độ sâu AST tối thiểu. Đặt advanced=true khi chủ động dùng các bộ lọc đường dẫn/ltree/lời gọi.
max_depth Tùy chọn
Kiểu
int
Mô tả
Nâng cao — ưu tiên preset=functions|classes|methods|imports|variables. Độ sâu AST tối đa. Đặt advanced=true khi chủ động dùng các bộ lọc đường dẫn/ltree/lời gọi.

Phù hợp nhất cho:

  • Cấu trúc cấp AST: class, decorator, preset function/method
  • Tìm code theo hình dạng, không phải theo văn bản

Không khuyến nghị cho:

  • Truy vấn free-text hoặc khái niệm — dùng semantic_search hoặc intelligent_search

dependency_search Ổn định

Công cụ chính cho phạm vi ảnh hưởng và đồ thị. Trả lời «điều gì gọi thành phần này?» hoặc «thành phần này dùng gì?» qua đồ thị lời gọi/import thực tế. Để xem tác động trước khi sửa: dùng analysis_type="dependents" hoặc analysis_type="impact" (hướng vào, mặc định độ sâu nông cho impact), với include_metrics=false theo mặc định (bật để có độ trung tâm và refactor_risk). dependents/impact mặc định bao gồm production_callers: các vị trí sử dụng duy nhất trong mã sản xuất theo loại (call, instantiate, value_reference cho hàm được truyền như giá trị), cộng với các vị trí IMPORT, loại trừ kiểm thử và có mức tin cậy EXTRACTED/INFERRED — không chỉ là bản liệt kê chỉ số. Tác động PR/diff: truyền changed_paths và/hoặc patch (unified diff); xác định ký hiệu theo đường dẫn và trả về dữ liệu gọn về các thành phần phụ thuộc hướng vào ở độ sâu nông, không cần tên ký hiệu. Sau khi sửa, đặt verify_after_edit=true với targets và/hoặc changed_paths để truy vấn lại gọn từ nhiều gốc đối với các ký hiệu bị ảnh hưởng. Cũng hỗ trợ dependencies, centrality và orphans. analyze_dependencies dùng cùng cách duyệt để phân tích tác động qua nhiều bước.

Tham số:

repository Tùy chọn
Kiểu
str
Mô tả
Repository theo định dạng owner/repo[:branch]. Tùy chọn — không truyền tham số này để dùng repository mặc định do trình khách cung cấp cho yêu cầu (nếu có), hoặc repository duy nhất mà khóa có thể truy cập. Chỉ truyền tường minh khi muốn nhắm tới một repo đã lập chỉ mục khác. Ưu tiên các nhánh đã lập chỉ mục khớp chính xác; nhánh không khả dụng có thể chuyển về main hoặc nhánh duy nhất có thể truy cập. Metadata của phản hồi cho biết danh tính được yêu cầu và danh tính thực sự được dùng, đồng thời cảnh báo khi xảy ra việc chuyển này.
query Tùy chọn
Kiểu
str
Mô tả
Tên symbol hoặc từ khóa tìm kiếm
target Tùy chọn
Kiểu
str
Mô tả
Tên symbol (alias cho query)
symbol_id Tùy chọn
Kiểu
UUID
Mô tả
Chọn một lần xuất hiện cụ thể bằng UUID trong các ứng viên khớp với tên được chỉ định ở query/target, sau khi lọc theo không gian tên, đường dẫn và ngôn ngữ. Dùng ID do find_symbol hoặc các kết quả thay thế của đồ thị trả về. Chỉ áp dụng cho phép duyệt có chỉ định tên; ID nằm ngoài phạm vi ứng viên bị giới hạn sẽ gây lỗi.
changed_paths Tùy chọn
Kiểu
list[str] maxItems=50
Mô tả
Các đường dẫn tệp chính xác tính từ thư mục gốc repo dùng để phân tích tác động PR/diff (mặc định), hoặc làm điểm xuất phát để kiểm chứng sau chỉnh sửa khi verify_after_edit=true. Các đường dẫn không phân giải được có thể trả về gợi ý có gắn nhãn; các tệp được gợi ý không bao giờ trở thành điểm gốc phân tích tác động. Với PR/diff: khi không có thông tin dòng, duyệt các định nghĩa cấp cao nhất của từng đường dẫn (ưu tiên định nghĩa được export, theo thứ tự trong tệp) và báo changed_lines_unknown; truyền patch= để lấy các ký hiệu thay đổi theo từng dòng. Khi kiểm chứng: tối đa 5 định nghĩa cấp cao nhất trên mỗi đường dẫn làm điểm xuất phát (giới hạn được hạ thấp hơn trong chế độ kiểm chứng). Phân tích tác động PR/diff không yêu cầu query/target.
patch Tùy chọn
Kiểu
str maxLength=500000
Mô tả
Phân tích tác động PR/diff: văn bản ở định dạng unified diff / git patch. Đường dẫn được lấy từ các dòng tiêu đề diff --git / --- / +++; các dòng trong hunk (phía cũ = commit đã được lập chỉ mục) được ánh xạ tới hàm/phương thức/lớp bao quanh, rồi duyệt từ đó để tìm chính xác các thành phần phụ thuộc, public_api_changed và các hàm gọi mà diff không chạm tới.
head_commit Tùy chọn
Kiểu
str pattern=^[0-9a-fA-F]{7,64}$
Mô tả
SHA commit của đoạn code bạn đang hỏi (git rev-parse HEAD, hoặc base commit của patch). complete:true yêu cầu index ở đúng commit này và được build bởi resolver hiện tại; nếu không, giá trị giữ nguyên complete:false kèm index_stale / index_freshness_unverified / index_built_by_older_resolver, và index_basis.statement cho biết câu trả lời đầy đủ trong phạm vi nào. Dòng 'base-commit:' của một patch (git format-patch --base) cũng cung cấp giá trị này.
analysis_type Tùy chọn
Kiểu
Literal[centrality, dependencies, dependents, impact, orphans]
Mặc định
dependencies
Mô tả
Chế độ phân tích. impact = phạm vi ảnh hưởng (các thành phần phụ thuộc theo cạnh hướng vào; độ sâu shallow khi không truyền depth). dependents cũng dùng để phân tích tác động. Khi có changed_paths hoặc patch, hệ thống luôn chuyển sang phân tích tác động PR/diff. centrality/orphans không yêu cầu đối tượng đích. orphans là các ứng viên mã không dùng đến, không phải bằng chứng rằng có thể xóa an toàn; hãy kiểm chứng các tham chiếu trong mã nguồn.
depth Tùy chọn
Kiểu
Literal[shallow, balanced, deep]
Mô tả
Độ sâu duyệt. Mặc định là balanced; impact và PR/diff impact mặc định dùng shallow. depth được chỉ định tường minh sẽ ghi đè các giá trị mặc định này. Chế độ xác minh luôn dùng shallow.
limit Tùy chọn
Kiểu
int minimum=1, maximum=50
Mặc định
20
Mô tả
Số kết quả tối đa mỗi trang khi không dùng cursor. Việc tiếp tục sẽ dùng kích thước trang được lưu trong cursor; bỏ qua cursor để bắt đầu với một limit khác.
offset Tùy chọn
Kiểu
int minimum=0
Mô tả
Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.
cursor Tùy chọn
Kiểu
str
Mô tả
cursor không minh bạch lấy từ pagination.next_cursor. Truyền nguyên trạng và giữ nguyên query cùng các bộ lọc. Vị trí và kích thước trang của nó sẽ ghi đè offset và limit.
path_filter Tùy chọn
Kiểu
str
Mô tả
Giới hạn việc phân giải ký hiệu đích theo tiền tố đường dẫn tệp; các quan hệ đồ thị trả về vẫn có thể đi ra ngoài đường dẫn đó
language_filter Tùy chọn
Kiểu
str
Mô tả
Lọc việc phân giải target và kết quả duyệt (browse) theo ngôn ngữ
direction Tùy chọn
Kiểu
Literal[outgoing, incoming, both]
Mô tả
Hướng duyệt đồ thị (ghi đè hướng được suy ra từ analysis_type)
relationship_types Tùy chọn
Kiểu
list[str]
Mô tả
Lọc các loại edge (CALL, IMPORT, INHERITS_FROM, v.v.). Một danh sách không rỗng sẽ ghi đè mặc định của graph_view.
exclude_test_paths Tùy chọn
Kiểu
bool
Mặc định
true
Mô tả
Mặc định true: loại trừ các path test, fixture, vendor, và ví dụ khỏi kết quả traversal và centrality. Đặt false để bao gồm chúng. Phân tích orphan chỉ tuân theo thiết lập này ở những nơi backend đã triển khai hỗ trợ; nếu không, nó giữ nguyên các loại trừ noise nghiêm ngặt riêng của mình và báo cáo sự điều chỉnh.
exclude_generated_paths Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Loại trừ các khai báo tự sinh cùng các đường dẫn đầu ra build, báo cáo độ bao phủ kiểm thử, cache, source-map và tạo tác mã đã rút gọn (minified) khỏi kết quả duyệt đồ thị
include_module_symbols Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Mặc định là false: loại bỏ các cạnh có from_name hoặc to_name là ký hiệu __module__ tổng hợp (nhiễu ở cấp mô-đun). Đặt true để đưa các cạnh cấp mô-đun vào kết quả dependents/dependencies.
include_isolated Tùy chọn
Kiểu
bool
Mô tả
Chỉ dành cho orphans. Mặc định false. Đặt true để trả về cả các ký hiệu không có dòng chỉ số đồ thị (hoàn toàn không có cạnh đồ thị nào). Khi exclude_test_paths là true, các ký hiệu stylesheet/markup/dữ liệu (CSS, HTML, ...), khai báo .d.ts và các path test/fixture/vendor/example vẫn bị loại trừ ở nơi backend hỗ trợ, trừ khi language_filter chỉ định ngôn ngữ đó; các thuộc tính object literal của TypeScript vẫn có thể xuất hiện như các hàm cô lập.
exclude_exported Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Chỉ dành cho ký hiệu mồ côi. Mặc định false: các ký hiệu được xuất (API công khai) không được dùng trong kho mã vẫn được trả về với is_exported=true. Đặt true để chỉ lấy các ứng viên nội bộ.
branch Tùy chọn
Kiểu
str
Mô tả
Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
per_hop_limit Tùy chọn
Kiểu
int minimum=1, maximum=300
Mô tả
Số relationship tối đa mỗi hop (1-300)
include_metrics Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Chỉ số đồ thị tùy chọn trên các dòng kết quả (được nén gọn cùng refactor_risk). Metrics cũng được lấy nội bộ khi min_centrality>0 nhưng không được trả về trừ khi giá trị này là true.
metrics_detail Tùy chọn
Kiểu
Literal[summary, full]
Mặc định
summary
Mô tả
Khi include_metrics=true: summary (mặc định) trả về các tín hiệu hỗ trợ quyết định + refactor_risk; full trả về bộ chỉ số đã chọn lọc lớn hơn
include_edge_metadata Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Bao gồm siêu dữ liệu thô của cạnh và các trọng số (dung lượng lớn). Phản hồi phân tích tác động dạng gọn không bật tùy chọn này.
symbol_types Tùy chọn
Kiểu
list[str]
Mô tả
Lọc các symbol được trả về theo loại (function, class, method, v.v.). Không được hỗ trợ trong phân tích orphan; hãy dùng path_filter hoặc language_filter trong trường hợp đó. Danh sách rỗng sẽ không áp dụng bộ lọc theo loại nào.
exact_match Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Yêu cầu khớp chính xác tên symbol (tắt fuzzy matching)
find_similar_patterns Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Tìm các pattern sử dụng tương tự
min_centrality Tùy chọn
Kiểu
float minimum=0
Mặc định
0
Mô tả
Điểm PageRank tối thiểu cho việc duyệt ký hiệu có tên và phân tích tác động PR/diff. Các ngưỡng dương không được hỗ trợ trong chế độ duyệt centrality/orphans. Metrics được lấy nội bộ để lọc; graph_metrics chỉ được trả về khi include_metrics=true. Bị bỏ qua bởi verify_after_edit, vốn dùng các tham số gọn cố định.
graph_view Tùy chọn
Kiểu
Literal[dependency, type, data_flow, control_flow]
Mặc định
dependency
Mô tả
Góc nhìn đồ thị dùng để xác định các quan hệ mặc định khi duyệt, các chỉ số và thứ hạng theo độ trung tâm; phân tích ký hiệu mồ côi được tính trên tất cả các góc nhìn
verify_after_edit Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Truy vấn lại đồ thị impact đã được lập chỉ mục cho các symbol đã chỉnh sửa trong một phản hồi đa gốc gọn nhẹ duy nhất. Cần có targets và/hoặc changed_paths (hoặc target/query). Sử dụng phép duyệt shallow cố định và ngân sách gọn nhẹ; các tùy chọn depth/limit/cursor/metrics không áp dụng. Mặc định trả về incoming dependents; kết quả phản ánh đồ thị đã lập chỉ mục (có thể chậm hơn so với các chỉnh sửa trực tiếp). Khi là true, có ưu tiên cao hơn PR/diff impact đối với cùng changed_paths.
targets Tùy chọn
Kiểu
list[str] maxItems=15
Mô tả
Khi verify_after_edit=true: tên các ký hiệu cần kiểm chứng lại (các hàm gọi/các thành phần phụ thuộc). Được hợp nhất với target/query nếu cả hai cùng được cung cấp.

Phù hợp nhất cho:

  • Phân tích phạm vi ảnh hưởng / tác động trước khi chỉnh sửa một ký hiệu dùng chung
  • Phân tích tác động PR/diff qua changed_paths hoặc patch
  • Xác minh sau khi sửa qua verify_after_edit

Không khuyến nghị cho:

  • Tra cứu text hoặc symbol đơn giản — dùng text_pattern_search hoặc find_symbol

Công cụ phân tích mã

#

find_symbol Ổn định

Nhảy tới nơi hàm, lớp hoặc biến được định nghĩa và sử dụng. Dùng khi bạn biết tên (ví dụ "getCurrentUser") — nhanh và chính xác hơn Grep, bao phủ toàn bộ repo đã lập chỉ mục. Tùy chọn trả về references và metrics tầm quan trọng.

Tham số:

symbol_name Tùy chọn
Kiểu
str
Mô tả
Tên symbol để tìm (tùy chọn — bỏ để duyệt theo metrics)
repository Tùy chọn
Kiểu
str
Mô tả
Repository theo định dạng owner/repo[:branch]. Tùy chọn — không truyền tham số này để dùng repository mặc định do trình khách cung cấp cho yêu cầu (nếu có), hoặc repository duy nhất mà khóa có thể truy cập. Chỉ truyền tường minh khi muốn nhắm tới một repo đã lập chỉ mục khác. Ưu tiên các nhánh đã lập chỉ mục khớp chính xác; nhánh không khả dụng có thể chuyển về main hoặc nhánh duy nhất có thể truy cập. Metadata của phản hồi cho biết danh tính được yêu cầu và danh tính thực sự được dùng, đồng thời cảnh báo khi xảy ra việc chuyển này.
scope Tùy chọn
Kiểu
Literal[definitions, references, both]
Mặc định
both
Mô tả
Phạm vi tìm kiếm; references yêu cầu symbol_name không rỗng.
limit Tùy chọn
Kiểu
int minimum=1, maximum=50
Mặc định
15
Mô tả
Số kết quả tối đa mỗi trang khi không dùng cursor. Việc tiếp tục sẽ dùng kích thước trang được lưu trong cursor; bỏ qua cursor để bắt đầu với một limit khác.
offset Tùy chọn
Kiểu
int minimum=0
Mô tả
Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.
cursor Tùy chọn
Kiểu
str
Mô tả
cursor không minh bạch lấy từ pagination.next_cursor. Truyền nguyên trạng và giữ nguyên query cùng các bộ lọc. Vị trí và kích thước trang của nó sẽ ghi đè offset và limit.
find_similar Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Bao gồm tên symbol tương tự
include_metrics Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Bao gồm metrics centrality
metrics_detail Tùy chọn
Kiểu
Literal[summary, full]
Mặc định
summary
Mô tả
Khi include_metrics=true: summary (mặc định) trả về các tín hiệu hỗ trợ quyết định + refactor_risk; full trả về bộ chỉ số đã chọn lọc lớn hơn
path_filter Tùy chọn
Kiểu
str
Mô tả
Lọc theo tiền tố đường dẫn tệp
branch Tùy chọn
Kiểu
str
Mô tả
Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
symbol_type Tùy chọn
Kiểu
str minLength=1
Mô tả
Lọc theo loại ký hiệu đã lập chỉ mục, ví dụ function, class, struct, enum hoặc trait. Sử dụng loại được trả về từ kết quả ký hiệu; loại thay đổi tùy theo ngôn ngữ.
high_impact Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Duyệt các ký hiệu quan trọng về mặt kiến trúc (không truyền symbol_name). Chế độ mặc định là popularity (thập phân vị PageRank cao nhất, loại trừ các nút tiện ích siêu kết nối). Đặt high_impact_mode=risk để tìm các đỉnh khớp đóng vai trò cầu nối.
high_impact_mode Tùy chọn
Kiểu
Literal[popularity, risk]
Mặc định
popularity
Mô tả
Khi high_impact=true: popularity = thập phân vị PageRank cao nhất, loại trừ các nút tiện ích siêu kết nối/mô-đun; risk = các đỉnh khớp được xếp hạng theo bridge_count của SMV rồi đến k_core (rủi ro khi tái cấu trúc do cấu trúc đồ thị, không phải mức độ phổ biến của nút trung tâm)
in_cycle Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Lọc các symbol có ghi nhận thuộc về một chu trình phụ thuộc (dependency cycle).
exclude_test_paths Tùy chọn
Kiểu
bool
Mặc định
true
Mô tả
Khi duyệt theo các chỉ số đồ thị, loại trừ kiểm thử, fixture, mã thư viện bên thứ ba và ví dụ trước khi xếp hạng; thao tác tra cứu ký hiệu theo tên không thay đổi
reference_views Tùy chọn
Kiểu
list[Literal[dependency, type, data_flow, control_flow, all]] minItems=1, maxItems=5
Mô tả
Các chế độ xem đồ thị có cạnh đi vào điền references/reference_count (scope references/both). Mặc định ["dependency", "type"]: lời gọi, nhập, xuất, tham chiếu, khởi tạo đối tượng, kế thừa, ghi đè, bộ trang trí và sử dụng kiểu. Nếu không chọn data_flow, các lần sử dụng data_flow được phân giải chính xác (hàm gọi lại, trình xử lý, khóa sắp xếp) được trả về riêng dưới dạng value_references/value_reference_count, không có kết quả khớp chỉ suy ra từ tên. Thêm data_flow hoặc control_flow, hoặc truyền ["all"] cho mọi loại và cấp cạnh. Cùng nhóm chế độ xem với graph_view của dependency_search.
relationship_types Tùy chọn
Kiểu
list[str]
Mô tả
Các loại cạnh tham chiếu được chỉ định rõ (CALL, IMPORT, READS, v.v.). Danh sách không rỗng ghi đè reference_views.

Phù hợp nhất cho:

  • Ghim definition, reference và chỉ số đồ thị của một symbol đã biết
  • Duyệt theo centrality, high_impact hoặc in_cycle khi bỏ qua symbol_name

Không khuyến nghị cho:

  • Truy vấn khái niệm hoặc khu vực chưa biết — dùng intelligent_search hoặc semantic_search

analyze_dependencies Ổn định

Phân tích phạm vi ảnh hưởng bằng cùng cách duyệt với dependency_search (dependents/incoming). Ưu tiên dependency_search với analysis_type="dependents" hoặc "impact" cho phân tích tác động. Trả về phản hồi tác động qua nhiều bước với các trường graph, connection_summary và số liệu tùy chọn có refactor_risk. connection_summary đếm các cạnh giới hạn theo nhóm quan hệ cho gốc đã chọn, trước khi lọc theo test/đường dẫn. Các trường cũ incoming_production/outgoing_production chỉ những cạnh không thuộc module, bao gồm cả test; đó không phải số bên gọi trong mã sản xuất. Dùng graph_view để giới hạn nhóm quan hệ: dependency (mặc định), type, data_flow, control_flow.

Tham số:

repository Tùy chọn
Kiểu
str
Mô tả
Repository theo định dạng owner/repo[:branch]. Tùy chọn — không truyền tham số này để dùng repository mặc định do trình khách cung cấp cho yêu cầu (nếu có), hoặc repository duy nhất mà khóa có thể truy cập. Chỉ truyền tường minh khi muốn nhắm tới một repo đã lập chỉ mục khác. Ưu tiên các nhánh đã lập chỉ mục khớp chính xác; nhánh không khả dụng có thể chuyển về main hoặc nhánh duy nhất có thể truy cập. Metadata của phản hồi cho biết danh tính được yêu cầu và danh tính thực sự được dùng, đồng thời cảnh báo khi xảy ra việc chuyển này.
target Bắt buộc
Kiểu
str minLength=1
Mô tả
Tên symbol cần phân tích
symbol_id Tùy chọn
Kiểu
UUID
Mô tả
Chọn một lần xuất hiện cụ thể bằng UUID trong các ứng viên của target, sau khi lọc theo không gian tên, đường dẫn và ngôn ngữ; ID nằm ngoài phạm vi ứng viên bị giới hạn sẽ gây lỗi.
depth Tùy chọn
Kiểu
Literal[shallow, balanced, deep]
Mặc định
balanced
Mô tả
Độ sâu phân tích
limit Tùy chọn
Kiểu
int minimum=1, maximum=50
Mặc định
10
Mô tả
Số kết quả tối đa mỗi trang khi không dùng cursor. Việc tiếp tục sẽ dùng kích thước trang được lưu trong cursor; bỏ qua cursor để bắt đầu với một limit khác.
offset Tùy chọn
Kiểu
int minimum=0
Mô tả
Offset tương thích đã lỗi thời. Ưu tiên dùng cursor từ pagination.next_cursor.
cursor Tùy chọn
Kiểu
str
Mô tả
cursor không minh bạch lấy từ pagination.next_cursor. Truyền nguyên trạng và giữ nguyên query cùng các bộ lọc. Vị trí và kích thước trang của nó sẽ ghi đè offset và limit.
direction Tùy chọn
Kiểu
Literal[incoming, outgoing, both]
Mặc định
incoming
Mô tả
Hướng duyệt đồ thị
relationship_types Tùy chọn
Kiểu
list[str]
Mô tả
Lọc theo loại cạnh (CALL, IMPORT, INHERITS_FROM, v.v.). Danh sách không rỗng sẽ ghi đè các giá trị mặc định của graph_view; danh sách rỗng sẽ dùng các giá trị mặc định đó.
graph_view Tùy chọn
Kiểu
Literal[dependency, type, data_flow, control_flow]
Mặc định
dependency
Mô tả
Chế độ xem đồ thị: xác định cả loại cạnh được duyệt mặc định lẫn số liệu của chế độ xem nào được dùng khi include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (mặc định), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Được áp dụng làm giá trị mặc định của relationship_types khi relationship_types bị bỏ qua hoặc để trống. Khớp với tên tham số graph_view đã có sẵn của dependency_search, để nhất quán giữa các công cụ.
path_filter Tùy chọn
Kiểu
str
Mô tả
Giới hạn việc phân giải ký hiệu đích theo tiền tố đường dẫn tệp; các quan hệ đồ thị trả về vẫn có thể đi ra ngoài đường dẫn đó
language_filter Tùy chọn
Kiểu
str
Mô tả
Bộ lọc ngôn ngữ
branch Tùy chọn
Kiểu
str
Mô tả
Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
per_hop_limit Tùy chọn
Kiểu
int minimum=1, maximum=300
Mô tả
Số relationship tối đa mỗi hop (1-300)
include_metrics Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Bao gồm các chỉ số đồ thị trong kết quả, mỗi mục được bổ sung một khối refactor_risk suy ra từ các chỉ số ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk là "low" khi ký hiệu không phải đỉnh khớp (trong góc nhìn đã chọn), "medium" khi là đỉnh khớp nối ít cạnh, "high" khi nối nhiều cạnh (ngưỡng dựa trên heuristic, chưa được kiểm chứng thực nghiệm). Bỏ phần chỉ số của từng ký hiệu nếu không có bản ghi chỉ số cho ký hiệu/góc nhìn đó.
metrics_detail Tùy chọn
Kiểu
Literal[summary, full]
Mặc định
summary
Mô tả
Khi include_metrics=true: summary (mặc định) trả về các tín hiệu hỗ trợ quyết định + refactor_risk; full trả về bộ chỉ số đã chọn lọc lớn hơn
include_edge_metadata Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Bao gồm siêu dữ liệu thô của cạnh và các trọng số. Mặc định tắt vì siêu dữ liệu từ bộ trích xuất có thể lớn; khi bật, phản hồi cho biết mức độ bao phủ của phần dữ liệu bổ sung.
exclude_test_paths Tùy chọn
Kiểu
bool
Mặc định
true
Mô tả
Mặc định là true: loại trừ các đường dẫn kiểm thử, fixture, mã thư viện bên thứ ba và ví dụ khỏi các cạnh đồ thị trả về. Đặt false để bao gồm chúng.
include_module_symbols Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Mặc định là false: loại bỏ các cạnh có from_name hoặc to_name là ký hiệu __module__ tổng hợp. Đặt true để bao gồm các cạnh cấp mô-đun.
head_commit Tùy chọn
Kiểu
str pattern=^[0-9a-fA-F]{7,64}$
Mô tả
SHA commit của đoạn code bạn đang hỏi (git rev-parse HEAD, hoặc base commit của patch). complete:true yêu cầu index ở đúng commit này và được build bởi resolver hiện tại; nếu không, giá trị giữ nguyên complete:false kèm index_stale / index_freshness_unverified / index_built_by_older_resolver, và index_basis.statement cho biết câu trả lời đầy đủ trong phạm vi nào. Dòng 'base-commit:' của một patch (git format-patch --base) cũng cung cấp giá trị này.

Phù hợp nhất cho:

  • Phân tích tác động qua nhiều bước khi cần các trường phản hồi graph và connection_summary

Không khuyến nghị cho:

  • Phân tích tác động nói chung: ưu tiên dependency_search để duyệt linh hoạt và kiểm tra từ nhiều gốc

get_task_context Ổn định

Bắt đầu làm việc trong một khu vực xa lạ? Mô tả nhiệm vụ (ví dụ: "thêm hỗ trợ SSO", "sửa webhook thanh toán") để nhận được, chỉ trong một lần gọi, một gói giới hạn gồm các file, mã nguồn, symbol và phụ thuộc liên quan. Các file được cung cấp làm seed sẽ đóng góp nội dung được lập chỉ mục trực tiếp ngay cả khi chúng không định nghĩa symbol nào. Các lớp (layer) thất bại sẽ được gắn nhãn; nếu toàn bộ việc truy xuất thất bại thì trả về lỗi công cụ. Để có thêm kết quả, hãy tiếp tục dùng công cụ tìm kiếm chuyên biệt cho lớp đó.

Tham số:

task_description Bắt buộc
Kiểu
str minLength=1
Mô tả
Mô tả tác vụ cần lấy context
repository Tùy chọn
Kiểu
str
Mô tả
Repository theo định dạng owner/repo[:branch]. Tùy chọn — không truyền tham số này để dùng repository mặc định do trình khách cung cấp cho yêu cầu (nếu có), hoặc repository duy nhất mà khóa có thể truy cập. Chỉ truyền tường minh khi muốn nhắm tới một repo đã lập chỉ mục khác. Ưu tiên các nhánh đã lập chỉ mục khớp chính xác; nhánh không khả dụng có thể chuyển về main hoặc nhánh duy nhất có thể truy cập. Metadata của phản hồi cho biết danh tính được yêu cầu và danh tính thực sự được dùng, đồng thời cảnh báo khi xảy ra việc chuyển này.
limit Tùy chọn
Kiểu
int minimum=1, maximum=50
Mặc định
15
Mô tả
Số mục context tối đa mỗi lớp
scope Tùy chọn
Kiểu
Literal[semantic, symbols, dependencies, all]
Mặc định
all
Mô tả
Những lớp ngữ cảnh cần đưa vào
language_filter Tùy chọn
Kiểu
str
Mô tả
Bộ lọc ngôn ngữ: yêu cầu scope=semantic mà không có điểm khởi đầu tường minh hoặc ngữ cảnh liên quan; chỉ mục của các lớp khác không thể áp đặt ngôn ngữ.
path_filter Tùy chọn
Kiểu
str
Mô tả
Tiền tố đường dẫn file cho các điểm gốc truy xuất theo ngữ nghĩa và từ khóa. Các seed tường minh có thể nằm ngoài tiền tố này; ngữ cảnh đồ thị có thể vượt qua ranh giới thư mục.
branch Tùy chọn
Kiểu
str
Mô tả
Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
include_related_context Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Bao gồm context liên quan từ các symbol lân cận
seed_symbol_ids Tùy chọn
Kiểu
list[str] maxItems=20
Mô tả
Các điểm khởi đầu tường minh của tác vụ: xuất hiện đầu tiên trong lớp ký hiệu và được giữ lại trong cửa sổ dependencies/related_context có giới hạn. Các lớp đồ thị xếp hạng điểm khởi đầu tường minh cùng vùng lân cận gần nhất của chúng trước khi quay về dùng từ khóa; mức độ quan trọng chỉ dùng để phân định khi độ liên quan ngang nhau. Việc mở rộng đồ thị yêu cầu scope=all|dependencies (scope=symbols|semantic không bao giờ chạy phép duyệt phụ thuộc). Không truyền tham số này để xếp hạng chỉ theo từ khóa với mức độ quan trọng giảm dần theo độ sâu.
seed_file_paths Tùy chọn
Kiểu
list[str] maxItems=10
Mô tả
Các điểm khởi đầu tường minh: đường dẫn tệp đã lập chỉ mục chính xác mà agent đang mở hoặc vừa chỉnh sửa. Trả về bằng chứng trực tiếp có giới hạn từ các tệp và tối đa 5 điểm khởi đầu đồ thị cho mỗi tệp, ưu tiên các kết quả khớp chính xác với tên tác vụ từ phép tra cứu ký hiệu có giới hạn, trước các định nghĩa và những ký hiệu xuất hiện tình cờ. Tệp không có ký hiệu vẫn cung cấp bằng chứng. Các tệp bị thiếu có thể trả về gợi ý có gắn nhãn nhưng không phải là điểm khởi đầu. Việc mở rộng đồ thị yêu cầu scope=all|dependencies.

Phù hợp nhất cho:

  • Ngữ cảnh theo tác vụ, kết hợp các tệp được chọn làm điểm khởi đầu với các lớp ngữ nghĩa, ký hiệu và phụ thuộc

Không khuyến nghị cho:

  • Tra cứu bằng một công cụ khi đã có công cụ chuyên biệt hơn trả lời được câu hỏi

get_file Ổn định

Đọc một tệp từ kho lưu trữ đã lập chỉ mục theo đường dẫn. Ưu tiên dùng công cụ tệp cục bộ cho các tệp trên đĩa; dùng công cụ này cho ảnh chụp nhanh đã lập chỉ mục từ xa. Tiếp tục các phản hồi có giới hạn bằng metadata.next_line_start và next_character_start. Chỉ xóa ký tự xuống dòng cuối cùng cùng dấu [truncated] khi metadata.truncated=true; nếu không, đó có thể là văn bản nguồn nguyên văn.

Tham số:

file_path Bắt buộc
Kiểu
str
Mô tả
Đường dẫn file so với gốc repository
repository Tùy chọn
Kiểu
str
Mô tả
Repository theo định dạng owner/repo[:branch]. Tùy chọn — không truyền tham số này để dùng repository mặc định do trình khách cung cấp cho yêu cầu (nếu có), hoặc repository duy nhất mà khóa có thể truy cập. Chỉ truyền tường minh khi muốn nhắm tới một repo đã lập chỉ mục khác. Ưu tiên các nhánh đã lập chỉ mục khớp chính xác; nhánh không khả dụng có thể chuyển về main hoặc nhánh duy nhất có thể truy cập. Metadata của phản hồi cho biết danh tính được yêu cầu và danh tính thực sự được dùng, đồng thời cảnh báo khi xảy ra việc chuyển này.
line_start Tùy chọn
Kiểu
int minimum=1
Mô tả
Dòng bắt đầu (đánh số từ 1)
line_end Tùy chọn
Kiểu
int minimum=1
Mô tả
Dòng kết thúc (1-indexed, bao gồm cả dòng đó; phải bằng hoặc sau line_start)
character_start Tùy chọn
Kiểu
int minimum=0
Mặc định
0
Mô tả
Độ lệch theo đơn vị mã UTF-16 chỉ trong dòng bắt đầu (chỉ số từ 0). Dùng metadata.next_character_start để đọc tiếp dòng mới được đọc một phần.
branch Tùy chọn
Kiểu
str
Mô tả
Ghi đè nhánh (chỉ áp dụng cho một lần gọi)
max_tokens Tùy chọn
Kiểu
int minimum=1, maximum=50000
Mặc định
5000
Mô tả
Ngân sách nội dung xấp xỉ (4 đơn vị mã UTF-16 mỗi token; không phải giới hạn chính xác của bộ tách token).
include_metadata Tùy chọn
Kiểu
bool
Mặc định
true
Mô tả
Bao gồm siêu dữ liệu mô tả tệp. Siêu dữ liệu cắt ngắn và tiếp tục luôn được trả về.

Phù hợp nhất cho:

  • Bản chụp tệp từ xa hoặc đã lập chỉ mục (phạm vi dòng, giới hạn token)

Không khuyến nghị cho:

  • Path đã có sẵn trên đĩa cục bộ — dùng Read tool cục bộ

Công cụ hệ thống & tiện ích

#

repository_context Ổn định

Liệt kê các repository bạn có thể tìm kiếm, hoặc lấy thông tin định danh của một repository (namespace/branch, indexed_commit_sha / độ mới của chỉ mục). Dùng action:"list" khi không biết slug của repository; các công cụ tìm kiếm chấp nhận trực tiếp một slug đã biết, hoặc mặc định dùng repository duy nhất của key bạn. list dùng pattern và phân trang; info yêu cầu repository và hỗ trợ branch cùng include_statistics=true tùy chọn.

Tham số:

action Bắt buộc
Kiểu
Literal[list, info]
Mô tả
Thao tác: list các repo có sẵn hoặc lấy info của repo
repository Tùy chọn
Kiểu
str
Mô tả
Chỉ dành cho info: repository theo định dạng owner/repo hoặc owner/repo:branch (bắt buộc đối với info)
branch Tùy chọn
Kiểu
str
Mô tả
Chỉ dành cho info: ghi đè nhánh
pattern Tùy chọn
Kiểu
str
Mô tả
Chỉ dành cho list: chuỗi con tên repository, không phân biệt chữ hoa/thường
include_statistics Tùy chọn
Kiểu
bool
Mặc định
false
Mô tả
Chỉ mang tính thông tin: bao gồm số lượng dữ liệu đã lập chỉ mục có giới hạn. Số lượng file/blob là chính xác; số lượng chỉ mục lớn hơn là ước tính. Xem count_accuracy và estimate_analyzed_at. Mặc định là false.
limit Tùy chọn
Kiểu
int minimum=1, maximum=50
Mặc định
20
Mô tả
Số kết quả tối đa mỗi trang khi không dùng cursor. Việc tiếp tục sẽ dùng kích thước trang được lưu trong cursor; bỏ qua cursor để bắt đầu với một limit khác.
offset Tùy chọn
Kiểu
int minimum=0
Mô tả
Offset tương thích đã lỗi thời. Ưu tiên cursor lấy từ pagination.next_cursor.
cursor Tùy chọn
Kiểu
str
Mô tả
cursor không minh bạch lấy từ pagination.next_cursor. Truyền nguyên trạng và giữ nguyên query cùng các bộ lọc. Vị trí và kích thước trang của nó sẽ ghi đè offset và limit.

Phù hợp nhất cho:

  • Liệt kê các repository có thể truy cập
  • Xác định định danh repository, nhánh và độ cập nhật của chỉ mục so với HEAD

Không khuyến nghị cho:

  • Mặc định thống kê toàn namespace — truyền rõ include_statistics=true, vì có thể chậm hơn resolution

ask_maguyva Ổn định

Nhận hướng dẫn về các công cụ Maguyva hoặc gửi báo cáo lỗi/yêu cầu tính năng được lưu cho đội bảo trì Maguyva. Không bao giờ đưa thông tin bí mật hoặc dữ liệu cá nhân nhạy cảm vào phản hồi. Thao tác evaluate hỗ trợ các biểu thức cho kết quả tất định; ưu tiên tính toán cục bộ hoặc công cụ của môi trường chủ khi xử lý toán học, hàm băm và chuỗi.

Tham số:

operation Bắt buộc
Kiểu
Literal[guidance, report_bug, request_feature, evaluate]
Mô tả
Dùng guidance để được trợ giúp về công cụ, report_bug cho lỗi hoặc request_feature cho đề xuất. evaluate thực thi các biểu thức cho kết quả tất định; ưu tiên tính toán cục bộ cho các phép tính.
query Tùy chọn
Kiểu
str maxLength=500
Mô tả
Chủ đề hướng dẫn (ví dụ tool_selection, semantic_search), hoặc chuỗi biểu thức cho evaluate.
description Tùy chọn
Kiểu
str minLength=1, maxLength=4000
Mô tả
Bắt buộc cho report_bug và request_feature. Phản hồi dạng tự do cho đội bảo trì Maguyva. Không bao giờ đưa thông tin bí mật hoặc dữ liệu cá nhân nhạy cảm vào phản hồi.
related_tool Tùy chọn
Kiểu
Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]
Mô tả
Công cụ Maguyva tùy chọn liên quan chặt chẽ nhất đến phản hồi

Phù hợp nhất cho:

  • Hướng dẫn sử dụng công cụ (operation="guidance")
  • Báo cáo lỗi và yêu cầu tính năng được lưu bền vững cho đội bảo trì Maguyva

Không khuyến nghị cho:

  • Tính toán toán học, hàm băm và chuỗi: ưu tiên tính toán cục bộ hoặc công cụ của môi trường chủ

Thực hành tốt nhất

#
  1. Sử dụng ghi đè tường minh có chủ đích: Bỏ tham số repository khi MCP client của bạn cung cấp mặc định theo từng yêu cầu hoặc khi khóa có thể truy cập đúng một repository; nếu không, hãy truyền rõ ràng.
  2. Chọn đúng chế độ tìm kiếm: Dùng intelligent_search với mode="auto" cho hầu hết trường hợp. Chỉ định chế độ khi bạn biết chính xác mình cần gì.
  3. Tận dụng bộ lọc ngôn ngữ: Dùng language_filter để thu hẹp kết quả và cải thiện hiệu năng.
  4. Tăng cường GraphRAG: Tính năng tăng trọng số theo mức độ quan trọng của GraphRAG bị tắt theo mặc định cho tìm kiếm ngữ nghĩa (boost_by_importance=false) để giữ việc xếp hạng an toàn cho agent. Truyền boost_by_importance=true để bật xếp hạng lại theo độ trung tâm khi khám phá kiến trúc.
  5. Khớp Repository Không Phân Biệt Hoa Thường, Không Phải Khớp Mờ: repository_context khớp tên repository không phân biệt chữ hoa chữ thường — nhưng không sửa lỗi gõ. Khi danh tính được phục vụ khác với danh tính được yêu cầu, metadata.resolution_reason báo "defaulted" (không yêu cầu nhánh nào) hoặc "fallback" (nhánh hoặc repository được yêu cầu không khả dụng). Trường này bị bỏ qua khi yêu cầu khớp chính xác.
  6. Kết hợp công cụ: Dùng nhiều phương thức API cùng nhau để có phân tích toàn diện.
  7. Xử lý tập kết quả lớn: Dùng limit và cơ chế phân trang riêng của từng công cụ (ví dụ line_start/line_end trong get_file).
  8. Dùng ask_maguyva để được hướng dẫn về công cụ: Gọi ask_maguyva với operation="guidance" và query="tool_selection" để nhận lời khuyên chọn công cụ và ví dụ. Dùng công cụ cục bộ để tính toán và biến đổi chuỗi.
  9. Xác minh tác động trước và sau khi chỉnh sửa: Trước khi chỉnh sửa một ký hiệu dùng chung, gọi dependency_search với analysis_type="impact" (hoặc truyền changed_paths để phân tích tác động của PR/diff) nhằm xem phạm vi ảnh hưởng. Sau khi chỉnh sửa, đặt verify_after_edit=true với targets và/hoặc changed_paths để kiểm tra lại đồ thị đã lập chỉ mục ở dạng gọn. Công cụ không đọc thay đổi cục bộ chưa được commit và không thay thế kiểm thử cục bộ. Kiểm tra indexed_commit_sha và độ cập nhật của chỉ mục trước khi coi kết quả là bằng chứng cho phiên bản mới.

Đặc tính hiệu năng

#
Thao tác Ghi chú hiệu năng
Tìm kiếm ngữ nghĩa Bao gồm tạo biểu diễn véc-tơ của truy vấn và truy xuất véc-tơ. Độ trễ phụ thuộc vào cả hai thao tác.
Tìm kiếm văn bản Với tìm kiếm gần đúng trong nội dung, các trang sâu hơn lấy nhiều ứng viên hơn. Thu hẹp truy vấn bằng path_filter và language_filter.
Tìm kiếm cấu trúc Truy vấn các nút AST đã lập chỉ mục. Dùng thiết lập sẵn hoặc mẫu cụ thể và giới hạn số kết quả.
Tìm kiếm phụ thuộc Chi phí tỷ lệ theo depth — ưu tiên depth="shallow" trừ khi bạn cần ngữ cảnh nhiều bước (multi-hop); per_hop_limit giới hạn độ lan tỏa
Truy xuất file Đọc phạm vi cần thiết bằng line_start/line_end hoặc max_tokens, rồi dùng siêu dữ liệu tiếp tục được trả về cho nội dung bị cắt ngắn.
Ngữ cảnh repository Kho mã được xác định trong mỗi lần gọi công cụ. Truyền repository một cách tường minh khi cần một kho mã cụ thể.
ask_maguyva (guidance / evaluate) Chạy trong máy chủ MCP mà không truy vấn chỉ mục kho mã.

Xử lý lỗi

#

Phản hồi công cụ chứa các trường trạng thái chung và trường dữ liệu riêng của công cụ ở cấp cao nhất. Tìm kiếm trả về results; get_file trả về content. Các trường chung gồm:

  • status: Chuỗi — "success" hoặc "error". Tín hiệu khớp suy giảm và độ mới của chỉ mục nằm ở các trường riêng: metadata.resolution_reason bên dưới metadata, và index_freshness.status ở cấp cao nhất của action info thuộc repository_context.
  • timing_ms: Thời gian thực thi công cụ đã trôi qua, tính bằng mili giây
  • applied_filters: Các tham số yêu cầu thực tế được ghi nhận cho thao tác
  • error: Chuỗi thông báo lỗi khi status là "error"; có thể kèm hướng dẫn khôi phục.
  • metadata: Thông tin bổ sung về thao tác (định tuyến, cache, điều chỉnh tham số)
  • pagination: Có trong phản hồi tập hợp được phân trang bằng con trỏ — gồm has_more và next_cursor. Cửa sổ tìm kiếm đã xếp hạng là kết quả top-K có giới hạn, không phải tập hợp phân trang đầy đủ.

Hãy kiểm tra trường status trước khi xử lý payload của công cụ — giá trị của nó là "success" hoặc "error". Cũng cần xử lý lỗi truyền tải MCP/JSON-RPC và lỗi kiểm tra request, vốn có thể xảy ra trước khi payload được tạo ra. Với tín hiệu khớp suy giảm hoặc độ mới, hãy đọc trường dành riêng: metadata.resolution_reason bên dưới metadata, hoặc index_freshness.status ở cấp cao nhất của action info thuộc repository_context (known/partial/unknown/unavailable).

Bắt đầu

#
  1. Cấu hình trình khách MCP: Cấu hình trình khách MCP để kết nối đến điểm cuối máy chủ Maguyva
  2. Xác nhận quyền truy cập repository: Dùng repository_context với list hoặc info để kiểm tra các repository mà khóa API có thể truy cập
  3. Bắt đầu tìm kiếm: Bắt đầu với intelligent_search và chuyển sang các công cụ chuyên biệt khi cần
  4. Kết hợp công cụ: Dùng nhiều công cụ cùng nhau để phân tích mã toàn diện

Để có hướng dẫn tích hợp chi tiết, xem hướng dẫn cài đặt.

Liên quan

Đọc tiếp