ADR 0013: Поверхность команд и discoverability (палитра, минимальный toolbar)¶

Статус: Accepted (направление; состав команд и итерации UI — отдельно)
Дата: 2026-04-02

Связанные ADR¶

ADR	Роль
0012	см. [раздел «Разделение с 0012»](#scope-split-0012
0014	ситуационные чеклисты — отдельный ADR
0010	режимы и видимость
0008	команды и MCP
0002	один слой для человека и агента, если команды общие
0030	Слои идентификаторов команд, хоткеев и UI (без одной таблицы «всё в одном» пока)
0060	аккордный слой FMS-style, S/T, overlay — расширение keyboard-first, не замена палитры
0119	слэш в composer Intercom — третья поверхность discoverability; тот же `command_id`, дополняет палитру и аккорд

Вне ADR¶

Документ	Роль
north-star — keyboard-first	продуктовый принцип: палитра и хоткеи — опорные пути

Разделение с 0012 ¶

0012 — размещение и плавающий хром workspace.
0013 (этот ADR) — поверхность команд: как пользователь вызывает действия и как обеспечивается discoverability без раздувания toolbar.

Контекст¶

Продуктовый ориентир: CascadeIDE запланирована как keyboard-first — основные действия должны быть доступны с клавиатуры и через палитру команд; этот ADR задаёт поверхность (палитра, минимальный toolbar, discoverability), а не «IDE под мышь».

0012 решает пространственную перегрузку: нижняя зона, телеметрия, плавающий хром, при необходимости отдельные окна и расширение MCP для них. Отдельно стоит вопрос сколько командных элементов держать на экране и как пользователь (и агент по именам) находит действие.

Сейчас верхняя toolbar может быть длинной и смешанной по смыслу (см. 0012 — контекст про toolbar). Раздувание полосы кнопок противоречит цели разгрузки: то же «понамешано», что и у фиксированного хрома, только по горизонтали.

При этом только палитра команд без опоры в контексте ухудшает discoverability для тех, кто ещё не знает названий команд — классическая проблема «Command Palette» (как Ctrl+Shift+P в VS Code): мощно для поиска по строке, слабее для «что мне жать в этой ситуации».

В авиации discoverability часто делают чеклистами и якорями в поле зрения (в т.ч. на органах управления): не полный каталог процедур, а ситуация → короткий список. Это аналог ситуационной подсказки, а не замена справочнику команд.

Решение¶

Разделение осей — см. раздел «Разделение с 0012» выше и ADR 0012; полные формулировки для обоих ADR — в той секции.
Опорная точка — палитра команд (аналог Ctrl+Shift+P): одна явная точка входа (кнопка «Command» и/или хоткей), поиск по списку команд с подсказками и привязкой к хоткеям, fuzzy/подстрока, недавние и частые — чтобы не требовать длинной полосы кнопок для всего.
Discoverability не сводить к одной палитре: дополнить ситуационными мини-чеклистами (контекст режима/сценария: отладка, первый запуск, «перед коммитом») — короткие закреплённые шаги в зоне внимания, по аналогии с чеклистами в авиации (не замена полного списка команд). Механика чеклистов — 0014.
Toolbar минимизировать: оставить только якорные действия с высокой частотой (или убрать до одной кнопки открытия палитры — по продуктовой итерации). Остальное — палитра + режимы (0010) + при необходимости чеклисты.
Три опорных входа для человека (один реестр): палитра (поиск и полный каталог), аккорд/Melody (0060), слэш в Intercom (0119 — unified command line в composer). Не смешивать роли: сжатые мнемоники — аккорд/c:, иерархический discoverability в канале — / + autocomplete.
Паритет агента: команды, доступные человеку из палитры и привязанные к тому же слою, что и IdeCommands/MCP, остаются согласованными с автоматизацией (0002, 0008); имена и id не разъезжаются между «кнопка в UI» и «вызов агента».

Связь с 0014 ¶

Ситуационные чеклисты (модель данных, триггеры, каталог сценариев, карточка в UI, mermaid, порядок внедрения после реестра) зафиксированы в 0014. В 0013 остаётся решение уровня поверхности: палитра как опора, toolbar минимальный, discoverability не только поиском по имени; чеклист как механизм discoverability детализируется там. Якорь для прежних ссылок на «видение чеклистов»: 0014 § Видение.

Последствия¶

Потребуется единый реестр команд для палитры: id и исполнение уже в IdeCommands + IdeMcpCommandExecutor; отдельно — метаданные UI (имя, категория, видимость в палитре, правило по режиму) и хоткеи из файлов — чертёж: docs/design/ide-command-registry-v1.md.
Toolbar и палитра — два представления одного слоя, а не дублирование логики в разных местах.
Два слоя файлов хоткеев: (1) шипнутый каталог с exe — Hotkeys/hotkeys.toml под AppContext.BaseDirectory (как UiModes/, Themes/), там лежит полная базовая карта command_id → жест — без длинной таблицы сочетаний в исходниках; (2) пользовательский %LocalAppData%\CascadeIDE\hotkeys.toml — только переопределения поверх базы. Загрузка и сохранение пользовательского слоя — отдельно от CascadeIdeSettings; в коде — парсинг, мердж и привязка к реестру команд; при отсутствии или повреждении шипнутого файла — узкий аварийный fallback (минимум одна команда открытия палитры), не дублирование всей карты в C#.
Каталог чеклистов и третье представление вызовов — см. последствия в 0014.
Документация для пользователя (позже): хоткей палитры по умолчанию; путь к hotkeys.toml; чеклисты — 0014.

Отклонённые альтернативы (как финальное состояние)¶

Только длинный toolbar без палитры и без ситуационных подсказок — отклонено как противоречащее разгрузке хрома (0012).
Только палитра без якорей и контекстных чеклистов — отклонено как недостаточное для discoverability в незнакомых сценариях.
Хранить пользовательские сочетания клавиш только внутри settings.toml (разделом) — отклонено: каталог хоткеев будет расти; нужны обмен файлами и будущие пресеты без смешения с AI/MCP и прочими полями настроек.
Держать все стандартные сочетания как строковые литералы в C# (размазанные по классам) — отклонено: карта жестов должна жить в data-файле рядом с UiModes/ / Themes/, чтобы в коде оставались id команд и логика, а не длинный список клавиш.

Решения по реализации (уточнение после обсуждения)¶

Базовые хоткеи (шип): Hotkeys/hotkeys.toml под AppContext.BaseDirectory — единый источник строк жестов для продуктовых дефолтов; репозиторий содержит тот же файл, что попадает в поставку. Формат — пары command_id → строка жеста; детали — command-palette-ux-concept-v1.md §9.
Пользовательский слой: hotkeys.toml в %LocalAppData%\CascadeIDE\ (рядом с settings.toml) — только переопределения поверх шипнутой карты; отсутствующие ключи не ошибка: берётся значение из шипнутого файла. Несколько пресетов — не часть минимального v1; при появлении — поле вроде hotkeys_preset в settings.toml или соглашение об именах, см. §9 UX-документа.
Будущее (после нескольких пресетов): опциональное inherits в файле пресета хоткеев — как inherits в UiModes/<id>.toml (0010): один родитель (id или имя базового файла), разрешение цепочки, затем мердж пар command_id → жест — явные в дочернем перекрывают родителя; циклы — ошибка загрузки с понятным сообщением (паттерн как в UiModeCatalog).
Хоткей палитры по умолчанию (в шипнутом файле): Ctrl+Q (как Quick Launch в Visual Studio). Переопределение — в пользовательском hotkeys.toml; конфликт с ОС — см. command-palette-ux-concept-v1.md §8.
Фокус: при открытии — поле поиска; при закрытии — восстановление фокуса на элемент до открытия (одно главное окно). Детали UX — в command-palette-ux-concept-v1.md §6; мультиоконность — с 0017.

Обсуждение (открытые вопросы для следующих итераций)¶

Вопросы по чеклистам (состав сценариев, пересечение с 0011, 0012) — в 0014.
Схема inherits для хоткеев (когда появятся несколько пресетов) — уточнять вместе с первой реализацией пресетов; ориентир — 0010 § inherits и код UiModeCatalog.