| 1 | # ADR 0051: Intent-based attention routing (TOML) |
| 2 | |
| 3 | **Статус:** Accepted · Implemented |
| 4 | **Дата:** 2026-04-16 |
| 5 | |
| 6 | ## Связанные ADR |
| 7 | |
| 8 | | ADR | Роль | |
| 9 | |-----|------| |
| 10 | | [0021](0021-pfd-mfd-cockpit-attention-model.md) | модель зон внимания и их канонические id | |
| 11 | | [0017](0017-multi-window-workspace-and-agent-surfaces.md) | топология `presentation` | |
| 12 | | [0050](0050-declarative-instrument-zone-placement-toml.md) | декларативный placement `instrument_id` по `surface_id+slot_id` | |
| 13 | |
| 14 | ## Резюме |
| 15 | |
| 16 | - **Intent-based attention routing** в TOML — маршрутизация внимания по намерению. |
| 17 | - Связь с capabilities и зонами [0021](0021-pfd-mfd-cockpit-attention-model.md). |
| 18 | |
| 19 | |
| 20 | ### Снимок реализации |
| 21 | |
| 22 | | Элемент | Значение | |
| 23 | |---------|----------| |
| 24 | | — | секция `[attention_routing]` в bundle `UiModes/workspace.toml` и оверлее `.cascade/workspace.toml`; intent-id — `AttentionRoutingIntentIds` | |
| 25 | |
| 26 | --- |
| 27 | ## Контекст |
| 28 | |
| 29 | В `UiModes/workspace.toml` и `.cascade/workspace.toml` сегодня существует карта размещения UI-панелей по зонам внимания: секция `[attention_zone_panels]` задаёт `panel_id -> attention_zone`. |
| 30 | |
| 31 | Проблема DX: |
| 32 | |
| 33 | - Пользователь должен знать **внутренние идентификаторы** (какие ключи допустимы). |
| 34 | - Названия в стиле `attention_zones` / `attention_zone_panels` легко спутать с другой осью конфигурации: **размещением “какого инструмента кабины”** в слотах (см. ADR [0050](0050-declarative-instrument-zone-placement-toml.md)). |
| 35 | |
| 36 | Нужно чётко развести два независимых слоя: |
| 37 | |
| 38 | 1. **Attention routing**: *куда на сцене направить UI-намерение* (пример: чат — в `mfd`, редактор — в `forward`). |
| 39 | Это про **поток внимания и географию** (`pfd/mfd/forward/hud/eicas`), но **не** про “какой инструмент в слоте”. |
| 40 | 2. **Instrument placement**: *какой `instrument_id` смонтирован в `surface_id+slot_id`* (ADR 0050). |
| 41 | Это про **контент слотов кабины**, но **не** про маршрутизацию панелей/интентов. |
| 42 | |
| 43 | --- |
| 44 | |
| 45 | ## Решение |
| 46 | |
| 47 | Принять intent-based конфигурацию routing’а внимания и **явно назвать** секцию так, чтобы она не пересекалась с instrument placement. |
| 48 | |
| 49 | ### 1) Новая секция |
| 50 | |
| 51 | Заменить `[attention_zone_panels]` на: |
| 52 | |
| 53 | - **`[attention_routing]`** |
| 54 | |
| 55 | Причины: |
| 56 | |
| 57 | - слово *routing* прямо указывает на “маршрутизацию/куда направлять”, а не на “что находится в слоте”; |
| 58 | - не пересекается по смыслу с `[instrument_routing]` (ADR 0050). |
| 59 | |
| 60 | ### 2) Ключи: “интенты”, а не внутренние panel id |
| 61 | |
| 62 | Ключи — человеко-читаемые intent id (v1 совпадают 1:1 с текущими панелями, но трактуются как intent): |
| 63 | |
| 64 | - `solution_explorer` |
| 65 | - `chat` |
| 66 | - `git` |
| 67 | - `terminal` |
| 68 | - `editor` |
| 69 | |
| 70 | Значения — канонические id зон из ADR 0021: |
| 71 | |
| 72 | - `forward`, `pfd`, `mfd`, `hud`, `eicas` |
| 73 | |
| 74 | Пример: |
| 75 | |
| 76 | ```toml |
| 77 | [attention_routing] |
| 78 | solution_explorer = "pfd" |
| 79 | chat = "mfd" |
| 80 | git = "mfd" |
| 81 | terminal = "mfd" |
| 82 | editor = "forward" |
| 83 | ``` |
| 84 | |
| 85 | ### 3) Связь с реализацией |
| 86 | |
| 87 | Внутри рантайма routing остаётся реализован через карту `panel_id -> AttentionZone`, но TOML задаёт **intent**: |
| 88 | |
| 89 | - intent id нормализуется и транслируется в соответствующий `panel_id` (внутренний ключ). |
| 90 | - Если intent неизвестен — выдаётся явная диагностика (лог/статус). |
| 91 | |
| 92 | ### 4) Слои merge (bundle/repo) |
| 93 | |
| 94 | Как и для текущего `workspace.toml`: |
| 95 | |
| 96 | - bundle: `UiModes/workspace.toml` |
| 97 | - repo overlay: `.cascade/workspace.toml` |
| 98 | |
| 99 | Правило приоритета: repo поверх bundle для совпадающих ключей. |
| 100 | |
| 101 | --- |
| 102 | |
| 103 | ## Последствия |
| 104 | |
| 105 | - Конфиг становится понятнее: пользователь видит **интенты**, а не “магические id”. |
| 106 | - Терминология не конфликтует с ADR 0050 (instrument placement). |
| 107 | - Кодовая модель допускает дальнейшую эволюцию: появление новых интентов без раскрытия внутренних panel id. |
| 108 | - `editor_hud` фиксирован как инвариант слоя HUD внутри `forward` и не является настраиваемым intent в TOML. |
| 109 | |
| 110 | --- |
| 111 | |
| 112 | ## Миграция |
| 113 | |
| 114 | Решение “replace”: |
| 115 | |
| 116 | - `[attention_zone_panels]` считается устаревшим и удаляется после внедрения `[attention_routing]`. |
| 117 | - Переходный период может поддерживать оба, но в v1 реализации предпочтительно не держать два параллельных источника истины. |
| 118 | |
| 119 | --- |
| 120 | |
| 121 | ## Открытые вопросы |
| 122 | |
| 123 | - Отдельная пользовательская секция routing в `%LocalAppData%\\CascadeIDE\\settings.toml`: нужна ли в v1, или достаточно bundle+repo. |
| 124 | |