| 1 | # ADR 0013: Поверхность команд и discoverability (палитра, минимальный toolbar) |
| 2 | |
| 3 | **Статус:** Accepted (направление; состав команд и итерации UI — отдельно) |
| 4 | **Дата:** 2026-04-02 |
| 5 | ## Связанные ADR |
| 6 | |
| 7 | | ADR | Роль | |
| 8 | |-----|------| |
| 9 | | [0012](0012-floating-workspace-chrome.md) | см. [раздел «Разделение с 0012»](#scope-split-0012 | |
| 10 | | [0014](0014-situational-checklists.md) | ситуационные чеклисты — отдельный ADR | |
| 11 | | [0010](0010-ui-modes-toml-configuration.md) | режимы и видимость | |
| 12 | | [0008](0008-mcp-contracts-and-testable-infrastructure.md) | команды и MCP | |
| 13 | | [0002](0002-debug-human-agent-parity.md) | один слой для человека и агента, если команды общие | |
| 14 | | [0030](0030-command-ids-hotkeys-and-ui-registry-layers.md) | Слои идентификаторов команд, хоткеев и UI (без одной таблицы «всё в одном» пока) | |
| 15 | | [0060](0060-keyboard-chord-stack-fms-tactical-strategic.md) | аккордный слой FMS-style, S/T, overlay — **расширение** keyboard-first, не замена палитры | |
| 16 | | [0119](0119-chat-slash-commands-intercom-surface.md) | слэш в composer Intercom — **третья** поверхность discoverability; тот же `command_id`, дополняет палитру и аккорд | |
| 17 | |
| 18 | ### Вне ADR |
| 19 | |
| 20 | | Документ | Роль | |
| 21 | |----------|------| |
| 22 | | [north-star — keyboard-first](../design/north-star-cursor-mcp-cascade-workbench-v1.md) | продуктовый принцип: палитра и хоткеи — опорные пути | |
| 23 | |
| 24 | ## Разделение с [0012](0012-floating-workspace-chrome.md) |
| 25 | |
| 26 | - **[0012](0012-floating-workspace-chrome.md)** — размещение и плавающий хром workspace. |
| 27 | - **0013 (этот ADR)** — поверхность команд: как пользователь вызывает действия и как обеспечивается discoverability без раздувания toolbar. |
| 28 | |
| 29 | --- |
| 30 | ## Контекст |
| 31 | |
| 32 | **Продуктовый ориентир:** CascadeIDE **запланирована как keyboard-first** — основные действия должны быть доступны с клавиатуры и через палитру команд; этот ADR задаёт поверхность (палитра, минимальный toolbar, discoverability), а не «IDE под мышь». |
| 33 | |
| 34 | **0012** решает **пространственную** перегрузку: нижняя зона, телеметрия, плавающий хром, при необходимости отдельные окна и расширение MCP для них. Отдельно стоит вопрос **сколько командных элементов** держать на экране и **как** пользователь (и агент по именам) находит действие. |
| 35 | |
| 36 | Сейчас верхняя **toolbar** может быть длинной и **смешанной по смыслу** (см. [0012](0012-floating-workspace-chrome.md) — контекст про toolbar). Раздувание полосы кнопок противоречит цели разгрузки: то же «понамешано», что и у фиксированного хрома, только по горизонтали. |
| 37 | |
| 38 | При этом **только палитра команд** без опоры в контексте ухудшает **discoverability** для тех, кто ещё не знает названий команд — классическая проблема «Command Palette» (как Ctrl+Shift+P в VS Code): мощно для поиска по строке, слабее для «что мне жать в *этой* ситуации». |
| 39 | |
| 40 | В авиации discoverability часто делают **чеклистами и якорями в поле зрения** (в т.ч. на органах управления): не полный каталог процедур, а **ситуация → короткий список**. Это аналог **ситуационной** подсказки, а не замена справочнику команд. |
| 41 | |
| 42 | ## Решение |
| 43 | |
| 44 | 1. **Разделение осей** — см. [раздел «Разделение с 0012»](#scope-split-0012) выше и [ADR 0012](0012-floating-workspace-chrome.md); полные формулировки для обоих ADR — в той [секции](#scope-split-0012). |
| 45 | |
| 46 | 2. **Опорная точка — палитра команд** (аналог Ctrl+Shift+P): одна явная точка входа (кнопка «Command» и/или хоткей), **поиск по списку команд** с подсказками и привязкой к хоткеям, **fuzzy/подстрока**, **недавние и частые** — чтобы не требовать длинной полосы кнопок для всего. |
| 47 | |
| 48 | 3. **Discoverability не сводить к одной палитре:** дополнить **ситуационными мини-чеклистами** (контекст режима/сценария: отладка, первый запуск, «перед коммитом») — короткие закреплённые шаги в зоне внимания, по аналогии с чеклистами в авиации (не замена полного списка команд). Механика чеклистов — **[0014](0014-situational-checklists.md)**. |
| 49 | |
| 50 | 4. **Toolbar минимизировать:** оставить только **якорные** действия с высокой частотой (или убрать до одной кнопки открытия палитры — по продуктовой итерации). Остальное — палитра + режимы ([0010](0010-ui-modes-toml-configuration.md)) + при необходимости чеклисты. |
| 51 | |
| 52 | 5. **Три опорных входа для человека** (один реестр): **палитра** (поиск и полный каталог), **аккорд/Melody** ([0060](0060-keyboard-chord-stack-fms-tactical-strategic.md)), **слэш в Intercom** ([0119](0119-chat-slash-commands-intercom-surface.md) — unified command line в composer). Не смешивать роли: сжатые мнемоники — аккорд/`c:`, иерархический discoverability в канале — `/` + autocomplete. |
| 53 | |
| 54 | 6. **Паритет агента:** команды, доступные человеку из палитры и привязанные к тому же слою, что и `IdeCommands`/MCP, остаются **согласованными** с автоматизацией ([0002](0002-debug-human-agent-parity.md), [0008](0008-mcp-contracts-and-testable-infrastructure.md)); имена и id не разъезжаются между «кнопка в UI» и «вызов агента». |
| 55 | |
| 56 | ## Связь с [0014](0014-situational-checklists.md) |
| 57 | |
| 58 | **Ситуационные чеклисты** (модель данных, триггеры, каталог сценариев, карточка в UI, mermaid, порядок внедрения после реестра) зафиксированы в **[0014](0014-situational-checklists.md)**. В [0013](0013-command-surface-and-discoverability.md) остаётся решение уровня поверхности: палитра как опора, toolbar минимальный, discoverability не только поиском по имени; чеклист как механизм discoverability детализируется там. Якорь для прежних ссылок на «видение чеклистов»: [0014 § Видение](0014-situational-checklists.md#checklist-vision). |
| 59 | |
| 60 | ## Последствия |
| 61 | |
| 62 | - Потребуется **единый реестр команд** для палитры: **id и исполнение** уже в `IdeCommands` + `IdeMcpCommandExecutor`; отдельно — **метаданные UI** (имя, категория, видимость в палитре, правило по режиму) и хоткеи из файлов — чертёж: [`docs/design/ide-command-registry-v1.md`](../design/ide-command-registry-v1.md). |
| 63 | - Toolbar и палитра — **два представления одного слоя**, а не дублирование логики в разных местах. |
| 64 | - **Два слоя файлов хоткеев:** (1) **шипнутый** каталог с exe — `Hotkeys/hotkeys.toml` под `AppContext.BaseDirectory` (как `UiModes/`, `Themes/`), там лежит **полная базовая карта** `command_id` → жест — **без длинной таблицы сочетаний в исходниках**; (2) **пользовательский** `%LocalAppData%\CascadeIDE\hotkeys.toml` — только переопределения поверх базы. Загрузка и сохранение пользовательского слоя — отдельно от `CascadeIdeSettings`; в коде — парсинг, мердж и привязка к реестру команд; при отсутствии или повреждении шипнутого файла — узкий аварийный fallback (минимум одна команда открытия палитры), не дублирование всей карты в C#. |
| 65 | - Каталог чеклистов и третье представление вызовов — см. последствия в [0014](0014-situational-checklists.md). |
| 66 | - Документация для пользователя (позже): хоткей палитры по умолчанию; путь к `hotkeys.toml`; чеклисты — [0014](0014-situational-checklists.md). |
| 67 | |
| 68 | ## Отклонённые альтернативы (как финальное состояние) |
| 69 | |
| 70 | - **Только длинный toolbar** без палитры и без ситуационных подсказок — отклонено как противоречащее разгрузке хрома ([0012](0012-floating-workspace-chrome.md)). |
| 71 | - **Только палитра** без якорей и контекстных чеклистов — отклонено как недостаточное для discoverability в незнакомых сценариях. |
| 72 | - **Хранить пользовательские сочетания клавиш только внутри `settings.toml` (разделом)** — отклонено: каталог хоткеев будет расти; нужны обмен файлами и будущие пресеты без смешения с AI/MCP и прочими полями настроек. |
| 73 | - **Держать все стандартные сочетания как строковые литералы в C#** (размазанные по классам) — отклонено: карта жестов должна жить в **data-файле** рядом с `UiModes/` / `Themes/`, чтобы в коде оставались id команд и логика, а не длинный список клавиш. |
| 74 | |
| 75 | ## Решения по реализации (уточнение после обсуждения) |
| 76 | |
| 77 | - **Базовые хоткеи (шип):** **`Hotkeys/hotkeys.toml`** под `AppContext.BaseDirectory` — единый источник **строк жестов** для продуктовых дефолтов; репозиторий содержит тот же файл, что попадает в поставку. Формат — пары `command_id` → строка жеста; детали — [`command-palette-ux-concept-v1.md`](../ui-ux/command-palette-ux-concept-v1.md) §9. |
| 78 | - **Пользовательский слой:** **`hotkeys.toml`** в `%LocalAppData%\CascadeIDE\` (рядом с `settings.toml`) — только **переопределения** поверх шипнутой карты; отсутствующие ключи не ошибка: берётся значение из шипнутого файла. Несколько пресетов — **не часть минимального v1**; при появлении — поле вроде `hotkeys_preset` в `settings.toml` или соглашение об именах, см. §9 UX-документа. |
| 79 | - **Будущее (после нескольких пресетов):** опциональное **`inherits`** в файле пресета хоткеев — как **`inherits` в `UiModes/<id>.toml`** ([0010](0010-ui-modes-toml-configuration.md)): один родитель (id или имя базового файла), разрешение цепочки, затем **мердж пар** `command_id` → жест — явные в дочернем перекрывают родителя; циклы — ошибка загрузки с понятным сообщением (паттерн как в `UiModeCatalog`). |
| 80 | - **Хоткей палитры по умолчанию (в шипнутом файле):** **Ctrl+Q** (как Quick Launch в Visual Studio). Переопределение — в пользовательском `hotkeys.toml`; конфликт с ОС — см. [`command-palette-ux-concept-v1.md`](../ui-ux/command-palette-ux-concept-v1.md) §8. |
| 81 | - **Фокус:** при открытии — поле поиска; при закрытии — восстановление фокуса на элемент до открытия (одно главное окно). Детали UX — в [`command-palette-ux-concept-v1.md`](../ui-ux/command-palette-ux-concept-v1.md) §6; мультиоконность — с [0017](0017-multi-window-workspace-and-agent-surfaces.md). |
| 82 | |
| 83 | ## Обсуждение (открытые вопросы для следующих итераций) |
| 84 | |
| 85 | - Вопросы по **чеклистам** (состав сценариев, пересечение с [0011](0011-debug-situational-awareness.md), [0012](0012-floating-workspace-chrome.md)) — в [0014](0014-situational-checklists.md). |
| 86 | - Схема **`inherits`** для хоткеев (когда появятся несколько пресетов) — уточнять вместе с первой реализацией пресетов; ориентир — [0010 § `inherits`](0010-ui-modes-toml-configuration.md) и код **`UiModeCatalog`**. |
| 87 | |