| 1 | # Зачем гибридный индекс и почему он устроен именно так |
| 2 | |
| 3 | Это текст **для человека**, который открывает репозиторий MCP: зачем слой между агентом и кодовой базой и почему выбраны конкретные компромиссы. Формальное архитектурное решение с нумерацией ADR относится к **CascadeIDE** — см. **[ADR 0105](https://github.com/KarataevDmitry/cascade-ide/blob/main/docs/adr/0105-hybrid-codebase-index-for-csharp-web.md)** (*Accepted · Implemented*). Интеграция продукта в IDE — **[ADR 0106](https://github.com/KarataevDmitry/cascade-ide/blob/main/docs/adr/0106-hybrid-codebase-index-cascadeide-integration-and-semantic-map.md)**. |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## Какую проблему решаем |
| 8 | |
| 9 | Агенту и человеку в IDE нужно **быстро сузить** область поиска: куда смотреть, какие файлы открыть, какие символы потом проверять Roslyn’ом. «Перечитать полрепозитория» или десятки вызовов навигации — слишком дорого по шагам и по контексту модели. |
| 10 | |
| 11 | При этом для **C#** у нас уже есть единственный надёжный источник для опасных операций (переименование, usages, семантический impact) — это **Roslyn**. Индекс не должен создавать иллюзию «ещё один компилятор». |
| 12 | |
| 13 | --- |
| 14 | |
| 15 | ## Почему два слоя: Roslyn и «слой B» |
| 16 | |
| 17 | - **Roslyn** даёт истину по символам там, где есть семантическая модель. |
| 18 | - Часть артефактов **Roslyn не индексирует как символы** (или не индексирует вообще): Razor/Blazor разметка, AXAML, markdown, конфиги, пайплайны, CSS/HTML. Там нужен хотя бы **полнотекст и эвристики**, чтобы не грепать всё дерево вслепую. |
| 19 | - **`*.cs` в FTS опционально** и осознанно «как текст»: это помощь для ориентации и поиска по строкам/идентификаторам, **не** замена поиску символов. Иначе агент перепутает «попало в топ» с «семантически это то же». |
| 20 | |
| 21 | Отсюда же требование **явной метки типа попадания** (`hit_kind` и связанные поля в ответах): человек или оркестратор должен понимать, перед ним текстовое совпадение или путь к **следующему** вызову Roslyn. |
| 22 | |
| 23 | --- |
| 24 | |
| 25 | ## Почему SQLite FTS5 (+ опционально вектора в том же мире) |
| 26 | |
| 27 | - Нужен **один локальный артефакт** на workspace/решение без обязательного Docker и без обязательного отдельного сервера в baseline установки. |
| 28 | - **FTS5** — зрелый keyword-слой с предсказуемой стоимостью и маленьким operational footprint для Windows/Linux/macOS. |
| 29 | - **Векторный канал** (semantic) — включение по желанию: отдельные провайдеры эмбеддингов, отдельные настройки; keyword остаётся основой «всегда работает». |
| 30 | |
| 31 | Тяжёлые альтернативы класса «всегда включённый граф + Qdrant + контейнеры» откладываем: они хороши для исследований, но плохо совпадают с целью «поднять и искать локально». |
| 32 | |
| 33 | --- |
| 34 | |
| 35 | ## Почему отдельный процесс MCP, а не только библиотека внутри IDE |
| 36 | |
| 37 | - Те же **tool id и JSON-контракты** можно вызывать из Cursor/другого хоста MCP **без** запуска Avalonia и без общей памяти с IDE. |
| 38 | - Индекс, watcher и SQLite обновления изолированы: сбои и перезапуск не привязаны жёстко к UI-процессу CascadeIDE. |
| 39 | |
| 40 | IDE может позже использовать **то же ядро in-process** или тот же бинарник как дочерний процесс — контракт остаётся общим. |
| 41 | |
| 42 | --- |
| 43 | |
| 44 | ## Почему эвристики Razor / AXAML в виде «заголовков» к чанку (`__hci_*`) |
| 45 | |
| 46 | Полный парсер Razor/XAML давал бы точность ценой сложности и зависимостей. На первом слое нужно **ускорить поиск ключевых слов**: директивы (`@page`, `@inject`, …), обработчики, ресурсы, пары файл–code-behind. Эти строки добавляются в начало текстового содержимого артефакта при индексации так, чтобы **FTS нашёл их по запросу**, не притворяясь синтаксическим деревом. |
| 47 | |
| 48 | Это сознательно **подсказка для ориентации**, а не замена редактору форм или анализатору AXAML/CDS в IDE. |
| 49 | |
| 50 | --- |
| 51 | |
| 52 | ## Что сознательно не делаем в этом MCP |
| 53 | |
| 54 | - Не заменяем Roslyn для рефакторингов по C#. |
| 55 | - Не строим канонический **semantic graph** приложения как у карты намерений в CascadeIDE ([0106](https://github.com/KarataevDmitry/cascade-ide/blob/main/docs/adr/0106-hybrid-codebase-index-cascadeide-integration-and-semantic-map.md)): индекс — вход для orientation, не источник графа управления UI. |
| 56 | - Не тащим в baseline обязательный Docker/облако — только опции. |
| 57 | |
| 58 | --- |
| 59 | |
| 60 | ## Куда смотреть дальше |
| 61 | |
| 62 | | Документ | Содержание | |
| 63 | | --- | --- | |
| 64 | | [ADR 0105 в CascadeIDE](https://github.com/KarataevDmitry/cascade-ide/blob/main/docs/adr/0105-hybrid-codebase-index-for-csharp-web.md) | Решение, слои, глоссарий, план внедрения, эскизы чанкинга и фьюжна | |
| 65 | | [MCP-TOOLS](MCP-TOOLS.md) | Описание инструментов MCP (генерируется из кода) | |
| 66 | | [README](../README.md) | Установка, `settings.toml`, быстрый старт | |
| 67 | |