Chuyển tới nội dung

Sổ tay công thức

Công thức nấu ăn thiết thực cho công việc Maguyva MCP hàng ngày. Mỗi công thức đặt tên cho các công cụ và trình tự — không phải là tham chiếu tham số đầy đủ. Để biết thông số dao, hãy sử dụng Tham khảo MCP API. Để thiết lập lần đầu, hãy sử dụng Bắt đầu nhanh.

Chọn đúng công cụ#

Hầu hết các câu hỏi đều bắt đầu bằng một cuộc gọi. Chỉ leo thang khi câu trả lời đầu tiên quá rộng hoặc quá mỏng.

  • intelligent_search - bắt đầu tại đây cho bất kỳ câu hỏi về cơ sở mã ngôn ngữ tự nhiên nào; nó định tuyến trên semantic, symbol, tìm kiếm cấu trúc và dependency.
  • find_symbol - bạn đã biết hàm, lớp hoặc tên biến.
  • dependency_search — bán kính bùng nổ: người gọi, người phụ thuộc hoặc tác động trước (và sau) chỉnh sửa.
  • get_task_context — khu vực xa lạ; một gói tệp được giới hạn, symbol và các phần phụ thuộc cho mô tả nhiệm vụ.
  • repository_context — liệt kê các kho lưu trữ có thể truy cập hoặc kiểm tra cách giải quyết tên kho lưu trữ.
  • ask_maguyva với operation="guidance" — trợ giúp cục bộ về lựa chọn công cụ và cách sử dụng Maguyva (không có đột biến repo).

Cài đặt và xác minh ứng dụng khách#

Đưa Maguyva vào MCP client của bạn và xác nhận kết nối với danh sách kho lưu trữ thực.

  1. Tạo khóa API trong app.maguyva.ai (các khóa bắt đầu bằng mgv_).
  2. Kết nối và lập chỉ mục ít nhất một kho lưu trữ GitHub mà bạn đã hiểu.
  3. Kết nối máy khách của bạn bằng Hướng dẫn cài đặt (plugin Claude Code hoặc cấu hình từ xa gốc cho Cursor, VS Code, Windsurf, Zed và các loại khác).
  4. Hãy hỏi đại lý "Tôi đã kết nối những kho lưu trữ nào?" của bạn — thực hiện xác thực và repository_context từ đầu đến cuối.
  5. Hãy hỏi một câu hỏi thực tế về kho lưu trữ đó mà bạn có thể chấm điểm câu trả lời của họ. Bạn sẽ thấy đường dẫn tệp và số dòng từ cây được lập chỉ mục.

Bị kẹt chìa khóa, cầu nối hoặc kho lưu trữ bị thiếu? Khắc phục sự cố.

Hỏi trước khi chỉnh sửa#

Lập bản đồ symbol và bán kính vụ nổ trước khi thay đổi mã chia sẻ. Các công cụ Maguyva không sửa đổi kho lưu trữ của bạn - chúng thông báo chỉnh sửa mà ứng dụng khách của bạn áp dụng cục bộ.

  1. Nếu bạn biết tên symbol, hãy gọi find_symbol để tìm hiểu định nghĩa và cách sử dụng.
  2. Nếu bạn chỉ có mô tả nhiệm vụ ("thêm SSO", "sửa webhook thanh toán"), hãy bắt đầu với get_task_context hoặc intelligent_search.
  3. Trước khi chỉnh sửa symbol được chia sẻ, hãy gọi dependency_search bằng phân tích tác động/phụ thuộc (hoặc chuyển các đường dẫn đã thay đổi cho tác động kiểu PR-) để bạn thấy bán kính vụ nổ.
  4. Mở các tệp được trích dẫn (đọc cục bộ cho các tệp trên đĩa; get_file cho các đường dẫn từ xa/repo chéo) và xác nhận kế hoạch dựa trên mã thực.
  5. Sau khi chỉnh sửa, hãy kiểm tra lại các symbol tương tự với dependency_search (bao gồm xác minh sau chỉnh sửa khi khách hàng của bạn hỗ trợ cờ xác minh) để người gọi vẫn giải quyết như mong đợi.

Thông số đầy đủ: Tham khảo MCP API.

Tìm kiếm rồi thay đổi#

Vòng lặp tác nhân mặc định: khám phá → ghim symbol → chỉnh sửa bằng chứng.

  1. Bắt đầu với intelligent_search và một truy vấn bằng ngôn ngữ đơn giản ("thời gian hết hạn phiên hoạt động như thế nào", "logic thử lại ở đâu").
  2. Thu hẹp bằng bộ lọc ngôn ngữ hoặc đường dẫn khi cửa sổ đầu tiên bị nhiễu.
  3. Quảng bá những bản hit đầy hứa hẹn lên find_symbol hoặc dependency_search thay vì đặt lại câu hỏi mơ hồ tương tự.
  4. Chỉ sử dụng get_file khi bạn cần một đường dẫn được lập chỉ mục cụ thể không có trên đĩa.
  5. Chỉnh sửa trong các công cụ khách hàng thông thường của bạn. Maguyva dùng để khám phá và xác minh — không phải để ghi.

Tại sao vòng lặp này hoạt động: Nó hoạt động như thế nào.

Kết quả trống hoặc mỏng#

Khi các công cụ không trả về điều gì hữu ích, hãy sửa độ phân giải và lập chỉ mục trước khi viết lại truy vấn mãi mãi.

  1. Xác nhận kho lưu trữ đã được kết nối và lập chỉ mục xong trong app.maguyva.ai.
  2. Kiểm tra chuỗi kho lưu trữ: "owner/repo" sử dụng nhánh mặc định; "owner/repo:branch" ghim một nhánh. Việc so khớp không phân biệt chữ hoa chữ thường, không mờ — lỗi chính tả không tự động sửa.
  3. Gọi repository_context bằng action="info" và kiểm tra siêu dữ liệu độ phân giải (ví dụ metadata.resolution_reason).
  4. Chỉ bỏ qua repository khi MCP client của bạn cung cấp mặc định yêu cầu hoặc khóa có thể truy cập chính xác một kho lưu trữ; nếu không hãy vượt qua nó một cách rõ ràng.
  5. Thử lại bằng một truy vấn cụ thể hơn, tên symbol đã biết qua find_symbol hoặc bộ lọc ngôn ngữ/đường dẫn. Nếu kết nối bị hỏng, hãy sử dụng Khắc phục sự cố.

Lỗi thiết lập: Khắc phục sự cố.

Làm việc trên nhiều kho lưu trữ#

Nhắm mục tiêu kho lưu trữ được lập chỉ mục phù hợp khi một khóa có thể nhìn thấy nhiều kho lưu trữ.

  1. Gọi repository_context bằng action="list" một lần để tìm hiểu các loại sên chính xác mà chìa khóa của bạn có thể tìm kiếm.
  2. Truyền repository một cách rõ ràng trên các công cụ tìm kiếm và symbol khi bạn cần một kho lưu trữ không mặc định (ví dụ: "owner/other-repo" hoặc "owner/other-repo:develop").
  3. Giữ một câu hỏi = một kho lưu trữ trừ khi bạn cố tình so sánh giữa các kho lưu trữ trong các lệnh gọi riêng biệt.
  4. Sử dụng get_file khi tệp nằm trong kho lưu trữ được lập chỉ mục không phải là cây làm việc hiện tại của bạn.
  5. Hãy nhớ: các công cụ không bao giờ ghi lại vào GitHub — multi-repo context chỉ dành cho việc đọc và lập kế hoạch.

Chi tiết định dạng kho lưu trữ: Tham khảo MCP API.

Bạn mới sử dụng Maguyva? Đi bộ Bắt đầu nhanh trước, sau đó quay lại đây để đi vòng trong ngày thứ hai.

Các bước tiếp theo#