# Jak działa Maguyva

Canonical source: https://maguyva.ai/pl/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).

Podłącz repozytorium GitHub, a Maguyva zamieni je w kilka przeszukiwalnych widoków, z których Twój agent może korzystać na żądanie. Zamiast wrzucać całe pliki do kontekstu, model uzyskuje dostęp oparty na danych repozytorium do symboli, struktury, dokumentacji, zależności i uszeregowanych fragmentów kodu.

Gdy podłączasz repozytorium, Maguyva uruchamia w chmurze pipeline'y wczytywania danych obejmujące kod, dokumentację, manifesty, symbole i metadane zależności. Celem jest jednorazowe zbudowanie trwałej pamięci kodu, zamiast kazać każdemu uruchomieniu agenta odkrywać repo od nowa.

Te pipeline'y tworzą kilka wyspecjalizowanych warstw danych: dokładne wyszukiwanie tekstowe, wyszukiwanie semantyczne, wyszukiwanie symboli i referencji, widoki strukturalne oraz analizę grafu zależności. Różne pytania trafiają do różnych warstw.

Maguyva oferuje 5 funkcji wyszukiwania: semantic, AST, symbol, dependency, text. W intelligent_search dostępne są cztery modalności wyszukiwania: semantyczna, tekstowa, strukturalna i grafowa. Domyślnie auto/balanced kieruje zapytania z wysoką pewnością rozpoznane jako pytania o definicje do wyszukiwania strukturalnego, pytania o odwołania lub wpływ do grafu, a pytania o dokładne dopasowanie do wyszukiwania tekstowego. Pozostałe pytania korzystają ze znaczenia semantycznego i zindeksowanego tekstu. Użyj mode=hybrid albo auto z quality=thorough, aby zażądać wszystkich czterech modalności wyszukiwania; jawnie wybrany tryb ma pierwszeństwo przed quality. language_filter wyklucza graf z auto/hybrid i jest odrzucany przy jawnym trybie grafowym. Wyniki z wielu modalności są łączone i porządkowane według trafności względem zapytania.

Prywatne widoki repozytorium współistnieją z publicznymi danymi referencyjnymi dla obsługiwanych languages and text-based technologies. Twój agent dociera do całego systemu przez narzędzia MCP, na których możesz mocno polegać podczas planowania i walidacji albo używać ich jako wyrywkowych kontroli podczas edycji.

### 1. Wczytywanie repozytorium

- **Analiza struktury kodu**: Parsuje pliki na symbole, referencje i granice architektoniczne
- **Rozwiązywanie zależności**: Mapuje wzajemne zależności między plikami, modułami i symbolami
- **Integracja dokumentacji**: Pobiera dokumentację repozytorium i powiązane materiały referencyjne razem z kodem

### Routing i ranking

- **Ocena trafności**: Wybiera dowody wyszukiwania zgodnie z trybem i profilem jakości, a następnie porządkuje dopasowania według trafności względem zapytania
- **Redukcja szumu**: Ogranicza powtórzone dopasowania i liczbę fragmentów na plik, aby jeden plik nie zapełnił całego okna wyników
- **Priorytetyzacja kontekstu**: Domyślnie ogranicza liczbę wyników i dba o ich trafność. Wzmocnienie według ważności włącza się jawnie przez boost_by_importance=true podczas przeglądu architektury; nie jest to domyślna polityka rankingu

### Przechowywane reprezentacje

- **Wyszukiwanie semantyczne**: Znajduje koncepcyjnie podobny kod i dokumentację, nawet gdy dokładne słowa się różnią
- **Widoki symboli i struktury**: Obsługuje dokładne wyszukiwanie symboli, referencje i pytania oparte na kształcie AST
- **Analiza grafu zależności**: Śledzi wywołujących, importy i zasięg wpływu w całej bazie kodu

### Funkcje bezpieczeństwa

- **Bezpieczeństwo transportu**: Połączenia z usługą korzystają z HTTPS/TLS
- **Zarządzane przechowywanie danych**: Zaindeksowane dane są przechowywane na zarządzanej infrastrukturze z szyfrowaniem na poziomie magazynu w spoczynku
- **Izolacja przestrzeni nazw**: Dane repozytorium są ograniczone przez workspace i przestrzeń nazw na ścieżkach zapytań pipeline'u i bazy danych
- **Kontrola dostępu**: Dostęp do repozytorium jest ograniczony granicami organizacji i przestrzeni nazw

### Czego się spodziewać

- **Lepsza dokładność planowania**: Agenty mogą zweryfikować podejście względem rzeczywistego repozytorium, zanim zaczną kodować
- **Bezpieczniejsze refaktoryzacje**: Kontrole zasięgu wpływu i zależności zmniejszają liczbę awarii, których można uniknąć
- **Mniej zmarnowanych tokenów**: Zwracane są tylko istotne fragmenty zamiast całych plików
- **Szybsze zrozumienie repo**: Model szybko otrzymuje ugruntowane odpowiedzi, zamiast za każdym razem odkrywać strukturę projektu od nowa

### Automatyczne aktualizacje

- **Synchronizacja repozytorium**: Odświeża dane na podstawie zadań synchronizacji z GitHub w miarę zmian w kodzie
- **Przetwarzanie przyrostowe**: Dla wydajności przetwarza tylko zmienione pliki
- **Kontekst uwzględniający gałąź**: Utrzymuje osobne indeksy dla każdej gałęzi git, dzięki czemu agenci widzą właściwy kontekst dla każdej z nich

Maguyva jest dostarczana jako serwer MCP hostowany w chmurze. Twój agent wywołuje narzędzia dla potrzebnej mu perspektywy, zamiast polegać na tym, że model zapamięta Twoją architekturę od zera. Cztery przedstawione powyżej grupy obejmują konkretne narzędzia: Wyszukiwanie semantyczne obejmuje `semantic_search` i `intelligent_search`; Wyszukiwanie symboli obejmuje `find_symbol` i `get_task_context`; Wyszukiwanie strukturalne obejmuje `structural_search` i `text_pattern_search`; Graf zależności obejmuje `dependency_search` i `analyze_dependencies` — a także `get_file`, `repository_context` i `ask_maguyva` jako narzędzia pomocnicze. Pełną listę wszystkich 11 narzędzi znajdziesz tutaj: [Dokumentacja API MCP](https://maguyva.ai/docs/mcp-api).

Wydajność zależy od wielkości bazy kodu i złożoności zapytania. Maguyva skupia się na dostarczaniu najbardziej trafnego kontekstu, zamiast wrzucać całe pliki. Obsługiwane języki i klientów znajdziesz na stronie „[zgodność](https://maguyva.ai/docs/compatibility)”.

Wyniki różnią się w zależności od wielkości i złożoności bazy kodu oraz rodzaju zapytań obsługiwanych przez Twojego agenta AI.

Połącz repozytoria GitHub przez portal Maguyva. Zadania synchronizacji GitHub odświeżają indeksy wraz ze zmianami kodu. Portal pokazuje też wykorzystanie API.