# Maguyva hoạt động như thế nào

Canonical source: https://maguyva.ai/vi/docs/how-it-works

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Kết nối một repository GitHub và Maguyva sẽ biến nó thành nhiều khung nhìn có thể tìm kiếm mà agent của bạn có thể dùng theo nhu cầu. Thay vì đổ toàn bộ tệp vào ngữ cảnh, mô hình được truy cập có căn cứ vào ký hiệu, cấu trúc, tài liệu, phụ thuộc, và các đoạn mã đã được xếp hạng.

Khi bạn kết nối một repository, Maguyva chạy các pipeline nạp dữ liệu trên đám mây để xử lý mã, tài liệu, manifest, ký hiệu và metadata về phụ thuộc. Mục tiêu là xây dựng bộ nhớ mã bền vững một lần, thay vì để agent phải khám phá lại repo từ đầu trong mỗi lượt chạy.

Các pipeline đó tạo ra nhiều lớp dữ liệu chuyên biệt: tìm kiếm văn bản chính xác, truy xuất theo ngữ nghĩa, tra cứu ký hiệu và tham chiếu, khung nhìn cấu trúc, và phân tích đồ thị phụ thuộc. Các câu hỏi khác nhau được định tuyến đến các lớp khác nhau.

Maguyva cung cấp 5 khả năng truy xuất: semantic, AST, symbol, dependency, text. Trong intelligent_search có bốn phương thức tìm kiếm: ngữ nghĩa, văn bản, cấu trúc và đồ thị. 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à bị từ chối khi dùng với chế độ đồ thị được chỉ định rõ. Kết quả từ nhiều phương thức được kết hợp và xếp hạng theo mức độ liên quan đến truy vấn.

Các khung nhìn repository riêng tư được cung cấp cùng với dữ liệu tham chiếu công khai cho languages and text-based technologies được hỗ trợ. Agent của bạn truy cập toàn bộ hệ thống qua các công cụ MCP; bạn có thể dùng chúng thường xuyên khi lập kế hoạch và kiểm chứng, hoặc chỉ để kiểm tra nhanh trong lúc chỉnh sửa.

### 1. Nạp dữ liệu repository

- **Phân tích cấu trúc mã**: Phân tích tệp thành ký hiệu, tham chiếu, và ranh giới kiến trúc
- **Phân giải phụ thuộc**: Ánh xạ cách các tệp, module, và ký hiệu phụ thuộc lẫn nhau
- **Tích hợp tài liệu**: Thu thập tài liệu repository và tài liệu tham khảo liên quan cùng với mã

### Định tuyến và xếp hạng

- **Chấm điểm mức độ liên quan**: Chọn bằng chứng truy xuất theo chế độ tìm kiếm và thiết lập chất lượng, rồi xếp hạng các kết quả khớp theo mức độ liên quan đến truy vấn
- **Giảm nhiễu**: Giảm kết quả khớp trùng lặp và giới hạn số đoạn trên mỗi tệp để một tệp không chiếm toàn bộ cửa sổ kết quả
- **Ưu tiên ngữ cảnh**: Mặc định giữ kết quả trong giới hạn và có liên quan. Việc tăng trọng số theo tầm quan trọng phải được bật bằng boost_by_importance=true khi khám phá kiến trúc; đây không phải chính sách xếp hạng mặc định

### Các biểu diễn được lưu trữ

- **Truy xuất theo ngữ nghĩa**: Tìm mã và tài liệu tương đồng về ý nghĩa ngay cả khi từ ngữ chính xác khác nhau
- **Khung nhìn ký hiệu và cấu trúc**: Hỗ trợ tra cứu ký hiệu chính xác, tham chiếu, và các câu hỏi theo hình dạng AST
- **Phân tích đồ thị phụ thuộc**: Theo dõi hàm gọi, import, và phạm vi ảnh hưởng trên toàn codebase

### Tính năng bảo mật

- **Bảo mật truyền tải**: Kết nối đến dịch vụ sử dụng HTTPS/TLS
- **Lưu trữ được quản lý**: Dữ liệu đã lập chỉ mục được lưu trên hạ tầng được quản lý với mã hóa ở cấp lưu trữ khi ở trạng thái nghỉ
- **Cách ly namespace**: Dữ liệu repository được giới hạn phạm vi theo workspace và namespace xuyên suốt pipeline và đường truy vấn cơ sở dữ liệu
- **Kiểm soát truy cập**: Quyền truy cập repository bị giới hạn bởi ranh giới tổ chức và namespace

### Những gì bạn có thể mong đợi

- **Độ chính xác lập kế hoạch tốt hơn**: Agent có thể xác thực cách tiếp cận với repository thực tế trước khi bắt đầu viết mã
- **Tái cấu trúc an toàn hơn**: Kiểm tra phạm vi ảnh hưởng và phụ thuộc giúp giảm những hỏng hóc có thể tránh được
- **Giảm lãng phí token**: Chỉ trả về các đoạn mã liên quan thay vì toàn bộ tệp
- **Hiểu repo nhanh hơn**: Mô hình nhận được câu trả lời có căn cứ một cách nhanh chóng thay vì phải khám phá lại cấu trúc dự án mỗi lần chạy

### Cập nhật tự động

- **Đồng bộ repository**: Làm mới từ các tác vụ đồng bộ GitHub khi mã thay đổi
- **Xử lý gia tăng**: Chỉ xử lý các tệp đã thay đổi để tăng hiệu quả
- **Ngữ cảnh nhận biết nhánh**: Duy trì chỉ mục riêng cho mỗi nhánh git để agent thấy đúng ngữ cảnh cho từng nhánh

Maguyva được cung cấp dưới dạng máy chủ MCP lưu trữ trên đám mây. Agent của bạn gọi các công cụ cho góc nhìn nó cần thay vì dựa vào mô hình phải ghi nhớ kiến trúc của bạn từ đầu. Bốn bề mặt ở trên là các góc nhìn được nhóm lại trên các công cụ cụ thể: Tìm kiếm ngữ nghĩa bao gồm `semantic_search` và `intelligent_search`; Tra cứu ký hiệu bao gồm `find_symbol` và `get_task_context`; Tìm kiếm cấu trúc bao gồm `structural_search` và `text_pattern_search`; Đồ thị phụ thuộc bao gồm `dependency_search` và `analyze_dependencies` — bên cạnh `get_file`, `repository_context`, và `ask_maguyva` như các tiện ích hỗ trợ. Xem đầy đủ [Tài liệu tham khảo MCP API](https://maguyva.ai/docs/mcp-api) cho toàn bộ 11 công cụ.

Hiệu năng thay đổi tùy theo kích thước codebase và độ phức tạp của truy vấn. Maguyva tập trung vào việc cung cấp ngữ cảnh liên quan nhất thay vì đổ toàn bộ tệp. Xem [khả năng tương thích](https://maguyva.ai/docs/compatibility) để biết các ngôn ngữ và client được hỗ trợ.

Kết quả thay đổi tùy theo kích thước, độ phức tạp của codebase, và loại truy vấn mà agent AI của bạn xử lý.

Kết nối các kho mã GitHub qua cổng Maguyva. Chỉ mục được cập nhật bằng các tác vụ đồng bộ GitHub khi mã thay đổi. Cổng cũng cho phép xem mức sử dụng API.