| 1 | # HCI в CascadeIDE: операционные заметки для агента и разработчика |
| 2 | |
| 3 | **Связь:** [ADR 0106](adr/0106-hybrid-codebase-index-cascadeide-integration-and-semantic-map.md), [ADR 0105](adr/0105-hybrid-codebase-index-for-csharp-web.md). |
| 4 | |
| 5 | ## Где задаётся конфигурация |
| 6 | |
| 7 | - **Диск:** пользовательский `settings.toml` (см. `SettingsService.GetSettingsPath()`), секция **`[hybrid_index]`**. Образец полей — `docs/samples/settings.toml`. |
| 8 | - **UI:** окно «Настройки» главного окна CascadeIDE — блок **Hybrid Codebase Index (HCI)**; те же значения пишутся в модель и при изменении переезжают в in-proc оркестратор без перезапуска IDE. |
| 9 | |
| 10 | ## Смысл ключей (кратко) |
| 11 | |
| 12 | | TOML / модель | Назначение | |
| 13 | |---------------|------------| |
| 14 | | `enabled` | Мастер-переключатель: если выкл — фонового watcher нет; кнопка «Reindex now» на MFD всё равно выполняет один полный in-proc прогон HCI и публикацию статуса (независимо от включён ли watch по файлам). | |
| 15 | | `index_dir` | Относительный каталог под **корнем workspace** для SQLite и артефактов; должен совпадать с тем, что ожидает внешний MCP `hybrid-codebase-index` при совместном использовании. | |
| 16 | | `debounce_ms` | Задержка после событий `FileSystemWatcher` перед очередным reindex (ограничение 0…60000 в UI). | |
| 17 | | `watch_files` | Поднять watcher; выкл — только статус/hand poke. | |
| 18 | | `auto_reindex_on_solution_open` | При смене/открытии решения выполнить `Poke`, чтобы подтянуть свежесть без ожидания событий ФС. | |
| 19 | | `scope_mode` | `workspace` или `workspace+solution`: один ключ базы на workspace vs отдельные под-папки на решение под `index_dir`. | |
| 20 | | `pause_when_mcp_stdio_host` | При режиме чата **`mcp_only`** не держать фонового watcher (снижение конкуренции с stdio MCP). | |
| 21 | |
| 22 | ## Как проверять состояние |
| 23 | |
| 24 | - **В IDE:** вторичный контур MFD → страница INDEX/HCI (`show_hybrid_index_page`), лампа OK/Caution, счётчик документов, `FRESHNS`, пути scope/БД в подсказках. |
| 25 | - **Снаружи:** MCP `hybrid-codebase-index` к тому же workspace и тем же параметрам области — тот же смысл `databasePath`. |
| 26 | |
| 27 | ## Те же операции через IDE MCP (паритет с внешним HCI MCP) |
| 28 | |
| 29 | Из чата/host с подключённым CascadeIDE MCP агент вызывает **те же идентификаторы**, что у тулов `hybrid-codebase-index`: через `ide_execute_command` или прокси-тулы `ide_codebase_index_*`: |
| 30 | |
| 31 | - `codebase_index_status` — JSON статуса; |
| 32 | - `codebase_index_search` — гибридный поиск (аргументы как у внешнего MCP); |
| 33 | - `codebase_index_explain` — explain по `hit_id`; |
| 34 | - `codebase_index_reindex` — инкремент по умолчанию, `full_rebuild: true` — полная перестройка; после успешного прогона публикуется `HybridIndexStateChanged` для MFD. |
| 35 | |
| 36 | **JSON против события шины.** `codebase_index_status`/`SerializeStatus(IndexStatus)` — полный MCP-ответ (настройки, reindex-state и др. в DTO); в IDE DataBus идёт **свёрнутое** событие `HybridIndexStateChanged` из CCU (`HybridIndexStateChangedUnit`). Для автоматизации нужен MCP — см. кодовые summary на методе и юните; паритет по смыслу путей/БД, не побайтовое совпадение JSON ↔ payload шины. |
| 37 | |
| 38 | Если не переданы `workspace_path` / `solution_path`, область берётся из текущего открытого решения с тем же `ResolveHybridIndexScope`, что оркестратор HCI (`scope_mode` в настройках). |
| 39 | |
| 40 | ## Анти-паттерны |
| 41 | |
| 42 | - Удалять папку `publish` MCP или junction на неё без остановки процесса, который держит `exe`/`dll`. |
| 43 | - Абсолютный `index_dir` в UI/TOML: нормализация принудительно возвращает относительный путь или дефолт `.hybrid-codebase-index`. |
| 44 | |
| 45 | ## Проекция снимка на MFD (развитие и сопровождение) |
| 46 | |
| 47 | 1. **Шина → поле снимка.** Ядро отдаёт `IndexStatus`; **CCU** `Cockpit/ComputingUnits/HybridIndex/HybridIndexStateChangedUnit` сворачивает его в `HybridIndexStateChanged` перед `IDataBus.Publish` (единая точка для watcher/reindex/MCP и задел под Semantic Map). В VM событие приходит через подписку; в UI-поток присваивается `HybridIndexLast` (генерируемое `[ObservableProperty]` + `[NotifyPropertyChangedFor(...)]`). |
| 48 | 2. **Без нового события с шины.** Свежесть и подписи вида «прошло N минут от `IndexedAtIso`» завязаны на UTC: при открытии вкладки INDEX, смене scope/каталога индекса в настройках и после `ApplyHybridCodebaseIndexOrchestrationForCurrentSolution` вызывается `RaiseHybridIndexPresentationProperties()`, который обходит **тот же список имён**, что и атрибут у поля снимка (массив `HybridIndexDependentPresentationNames` рядом с полем — расширять в двух местах сразу). |
| 49 | |
| 50 | Аналогичный приём пачечного обновления без «источника-снимка» для оверлея Cascade Chord: `CascadeChordOverlayPresentationNames` + `NotifyCascadeChordOverlayProperties()` в `MainWindowViewModel.CascadeChord.cs`. |
| 51 | |
| 52 | ## Кодовые якоря |
| 53 | |
| 54 | - Оркестратор: `Features/HybridIndex/Application/HybridIndexOrchestrator.cs` |
| 55 | - Связка с настройками и решением: `MainWindowViewModel.cs` (`ApplyHybridCodebaseIndexOrchestrationForCurrentSolution`), `MainWindowViewModel.SettingsReactive.cs`, `MainWindowViewModel.HybridIndexSettings.cs` |
| 56 | - Проекция UI MFD: `MainWindowViewModel.HybridIndex.cs`, `Views/HybridIndexMfdPageView.axaml` |
| 57 | |