# Как работает Maguyva

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

Подключите репозиторий GitHub, и Maguyva превратит его в несколько поисковых представлений, которые агент может использовать по запросу. Вместо того чтобы сваливать в контекст целые файлы, модель получает доступ с опорой на данные репозитория к символам, структуре, документации, зависимостям и ранжированным фрагментам кода.

Когда вы подключаете репозиторий, Maguyva запускает облачные конвейеры приёма по коду, документации, манифестам, символам и метаданным зависимостей. Цель — один раз построить долговечную память о коде, вместо того чтобы заставлять каждый запуск агента заново открывать репозиторий с нуля.

Эти конвейеры создают несколько специализированных слоёв данных: точный текстовый поиск, семантический поиск, поиск символов и ссылок, структурные представления и анализ графа зависимостей. Разные вопросы направляются в разные слои.

Maguyva предлагает 5 возможностей поиска: semantic, AST, symbol, dependency, text. В intelligent_search доступны четыре поисковые модальности: семантическая, текстовая, структурная и графовая. По умолчанию auto/balanced направляет вопросы об определениях с уверенно распознанным намерением в структурный поиск, вопросы о ссылках или влиянии — в граф, а запросы на точное совпадение — в текстовый поиск. Для остальных вопросов используются семантический поиск и индексированный текст. Чтобы запросить все четыре поисковые модальности, используйте mode=hybrid или auto с quality=thorough. Явно заданный mode имеет приоритет над quality. language_filter исключает граф из auto/hybrid и отклоняется при явном mode=graph. Результаты нескольких модальностей объединяются и ранжируются по релевантности запросу.

Представления приватного репозитория соседствуют с публичными справочными данными для поддерживаемых languages and text-based technologies. Ваш агент обращается ко всей системе через инструменты MCP — на них можно опираться при планировании и проверке или использовать точечно при редактировании.

### 1. Приём репозитория

- **Анализ структуры кода**: Разбирает файлы на символы, ссылки и архитектурные границы
- **Разрешение зависимостей**: Отображает, как файлы, модули и символы зависят друг от друга
- **Интеграция документации**: Подтягивает документацию репозитория и связанные справочные материалы вместе с кодом

### Маршрутизация и ранжирование

- **Оценка релевантности**: Выбирает поисковые свидетельства согласно режиму поиска и профилю качества, затем ранжирует совпадения по релевантности запросу
- **Снижение шума**: Уменьшает число повторных совпадений и ограничивает фрагменты на файл, чтобы один файл не занял всё окно результатов
- **Приоритизация контекста**: По умолчанию ограничивает объём результатов и сохраняет их релевантность. Усиление по важности включается явно через boost_by_importance=true для обзора архитектуры и не является стандартной политикой ранжирования

### Хранимые представления

- **Семантический поиск**: Находит концептуально похожий код и документацию, даже если точные слова отличаются
- **Символьные и структурные представления**: Поддерживает точный поиск символов, поиск ссылок и запросы по структуре AST
- **Анализ графа зависимостей**: Отслеживает вызывающий код, импорты и радиус влияния по всей кодовой базе

### Функции безопасности

- **Безопасность передачи данных**: Соединения с сервисом используют HTTPS/TLS
- **Управляемое хранилище**: Проиндексированные данные хранятся на управляемой инфраструктуре с шифрованием на уровне хранилища в состоянии покоя
- **Изоляция пространств имён**: Данные репозитория ограничиваются рабочим пространством и пространством имён на всём пути конвейера и запросов к базе данных
- **Контроль доступа**: Доступ к репозиторию ограничен границами организации и пространства имён

### Чего ожидать

- **Более точное планирование**: Агенты могут сверить подход с реальным репозиторием, прежде чем начать писать код
- **Более безопасный рефакторинг**: Проверки радиуса влияния и зависимостей снижают риск поломок, которых можно избежать
- **Меньше потерь токенов**: Возвращаются только релевантные фрагменты вместо целых файлов
- **Более быстрое понимание репозитория**: Модель быстро получает обоснованные ответы вместо того, чтобы заново открывать структуру проекта при каждом запуске

### Автоматические обновления

- **Синхронизация репозитория**: Обновляется через задачи синхронизации с GitHub по мере изменения кода
- **Инкрементальная обработка**: Для эффективности обрабатываются только изменённые файлы
- **Контекст с учётом веток**: Поддерживает отдельные индексы для каждой ветки git, чтобы агенты видели правильный контекст для каждой ветки

Maguyva поставляется как облачный MCP-сервер. Ваш агент вызывает инструменты для того ракурса, который ему нужен, вместо того чтобы полагаться на то, что модель запомнит вашу архитектуру с нуля. Четыре группы выше — это сгруппированные представления конкретных инструментов: Семантический поиск объединяет `semantic_search` и `intelligent_search`; Поиск символов объединяет `find_symbol` и `get_task_context`; Структурный поиск объединяет `structural_search` и `text_pattern_search`; Граф зависимостей объединяет `dependency_search` и `analyze_dependencies` — а также `get_file`, `repository_context` и `ask_maguyva` как вспомогательные утилиты. Полный список всех 11 инструментов см. в разделе «[справочник MCP API](https://maguyva.ai/docs/mcp-api)».

Производительность зависит от размера кодовой базы и сложности запроса. Maguyva фокусируется на выдаче максимально релевантного контекста, а не на сваливании целых файлов. Поддерживаемые языки и клиенты — на странице [совместимости](https://maguyva.ai/docs/compatibility).

Результаты зависят от размера и сложности вашей кодовой базы, а также от типов запросов, которые обрабатывает ваш ИИ-агент.

Подключите репозитории GitHub через портал Maguyva. Задания синхронизации GitHub обновляют индексы при изменении кода. Портал также показывает использование API.