ADR 0029: Конфигурация — TOML-first (канон на диске); целостный UI настроек — deferred; точечный UI — фасад канона, не вторая правда¶

Статус: Accepted · Implemented (TOML-first на диске; целостный UI настроек — deferred; точечный UI — фасад)
Дата: 2026-04-08
Обновлено: 2026-04-08 — целостный центр deferred; подраздел «Зачем точечный UI»; перспектива динамического UI от модели; точечный UI = вес кода. Подробности — § История.

Связанные ADR¶

ADR	Роль
0028	путь и формат `settings.toml`
0010	режимы и merge `workspace.toml`
0015	TOML во встроенном редакторе; внешний редактор с богатым тулингом — осознанный вариант
0013	палитра, хоткеи отдельным файлом
0027	ось B: отдельное приложение настроек и тяжёлый онбординг — в отложенном бэклоге до триггеров
0026	часть ключей в merged `workspace.toml` — канон для команды в репо

Резюме¶

TOML-first конфигурация; целостный UI настроек — deferred.
Точечный UI — фасад над тем же файлом, не второй источник истины.

Контекст¶

В продукте одновременно верны три факта:

Файлы — принятый канон хранения: пользовательский settings.toml, бандл/репо для режимов и хрома (0010, 0028).
UI уже меняет часть предпочтений (видимость панелей, режим UI, провайдеры, LSP и т.д.) через модель и сохранение на диск.
В обсуждении периодически всплывает полюс «только TOML» vs «полноценные экраны настроек» — без отдельного ADR легко смешать ожидания: что «настоящая» правда, обязан ли существовать UI для каждого ключа, допустимо ли жить одним файлом.

Нужно зафиксировать одну модель приоритета: диск и формат файлов задают канон; любой UI, который касается настроек, не создаёт вторую правду — но объём экранного UI (одна кнопка vs целый «центр настроек») — отдельное продуктовое решение, согласованное с 0027.

Решение¶

1. Канон — текстовые конфиги на диске (TOML там, где уже принято)¶

Пользовательские предпочтения — settings.toml и связанные файлы в %LocalAppData%\CascadeIDE\ (0028).
Раскладка/метрики/пресеты режимов — UiModes/ и merge с .cascade/workspace.toml (0010).
Секреты — в отдельном файле ai-keys.toml, не в settings.toml (0028).

Расширение набора ключей по смыслу — сначала модель + файл + сериализация, затем (по необходимости и по оси B) элементы UI.

2. Целостный UI настроек — deferred (0027)¶

Под целостным имеется в виду: единая страница/центр «все настройки», отдельное приложение настроек, крупные мастера — то, что в 0027 явно отнесено к отложенному бэклогу до триггеров (внешний контрибьютор, RC, явная боль и т.д.).

Это не запрет на точечные переключатели в основном окне, которые уже есть или появятся по мере фич.
Это не запрет документации «правь settings.toml» как основного пути для части аудитории.

Итого: не планируем сейчас вкладываться в полноэкранный discoverability-слой настроек как в отдельный продукт; планируем жить на TOML + доке + примерах (0027), пока очередь не скажет иначе.

3. Точечный UI — если есть, то фасад канона (не параллельная база)¶

Когда элемент управления в приложении меняет предпочтение, сохраняемое в settings.toml (или другом каноничном файле):

он работает с той же моделью (CascadeIdeSettings и др.), что и сериализация;
сохранение — через SettingsService.Save (и аналоги), без «теневого» реестра только в памяти как источника правды;
нет политики «настройки живут только в UI и иногда экспортируются» — см. отклонённые альтернативы.

Термин «фасад» в этом ADR = архитектурное правило для уже существующего или точечно добавляемого UI: он отражает файл, а не заменяет его скрытой копией. Это не обещание свернуть весь конфиг в богатый UI в ближайшем релизе (см. §2).

Зачем точечный UI, если всё можно править в TOML?¶

Канон по-прежнему файл; точечный UI не добавляет вторую правду и не обязателен для каждого пользователя.

Трение: частые действия (видимость панелей, режим UI и т.п.) дешевле кликом в кокпите, чем каждый раз открывать каталог %LocalAppData%\CascadeIDE\, искать ключ в snake_case, сохранять файл, при необходимости перезапускать сессию.
Редкий разовый заход — нормальный паттерн: например один раз включить внешнего агента (ACP), указать путь к cursor-agent — удобно из UI или тем же ключом в settings.toml по доке; оба входа ведут в один канон (0016).
Паттерн «в настройки в UI почти не лезу, всё держу в TOML» — допустим и ожидаем для части аудитории; паттерн «зашла в UI только на одну опцию» — тоже не противоречит TOML-first: это альтернативный вход, а не отмена файла.

4. Режим TOML-only — полноправный¶

Правка settings.toml (и прочих каноничных файлов) вручную, во встроенном редакторе или внешнем (0015), — нормальный рабочий процесс, в том числе для агента и для «диффов в Git» при переносе машин.
Отсутствие целостного UI настроек (§2) не считается пробелом само по себе. Отсутствие UI для отдельных ключей — тоже ок; чекбокс на каждое поле модели не обязателен (0027).

5. Когда имеет смысл добавлять/расширять точечный UI поверх TOML¶

Высокая частота переключений, безопасность (маскирование секретов), валидация на лету — естественные кандидаты на точечный контрол (по-прежнему по правилам §3).
Сложные структуры (списки MCP-серверов JSON и т.п.) — допустимы как UI, если снимают ошибки ручного редактирования; сериализованный результат по-прежнему лежит в каноничном поле файла.
Целостный «центр настроек» — только после триггеров 0027 или явной боли, не как дефолтная очередь.

6. Ограничение по сессии (честность реализации)¶

Загрузка SettingsService.Load() в типичном сценарии выполняется при старте приложения; прямое изменение settings.toml на диске во время работы сессии может потребовать перезапуска, чтобы все подсистемы подхватили значения (если для конкретного ключа не сделана отдельная перезагрузка). Это не аргумент против TOML-first; это повод при необходимости добавить явное «перечитать настройки» или watcher — отдельной задачей, не смешивая с вопросом канона.

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

Новые настройки: проектировать ключ в модели и файле; целостный UI — не обязателен и по умолчанию не в очереди; точечный UI — по необходимости.
Документация для пользователей и агентов: «как поменять X» может начинаться с пути к файлу и ключа; экранные формы — опциональное удобство и альтернативный вход, не предпосылка (см. §3, подраздел «Зачем точечный UI»).
0027: отложенное приложение/центр настроек согласуется с этим ADR: канон на диске уже есть, богатый UI — позже по триггерам.
Точечный UI увеличивает объём кода (привязки, VM, тесты) — добавлять осознанно; альтернатива раздуванию ручных форм при появлении целостного центра — см. раздел «Перспектива» ниже.

Перспектива (не обязательство реализации)¶

Когда целостный центр настроек перестанет быть deferred по 0027, разумно рассмотреть не набор ручных экранов, а динамическую форму, построенную из той же модели, что и сериализация в settings.toml (например рефлексия/генератор по CascadeIdeSettings + слой метаданных).

Плюс: новое поле в модели и в TOML — при наличии метаданных появляется в UI без N новых ручных биндингов; канон один.

Не сводится к «только CLR-тип»: нужны подписи, порядок, группы, скрытие полей, локализация; секреты остаются вне этой формы (0028); JSON-блобы и нестандартные поля — отдельные шаблоны или многострочный редактор.

Это не решение «делаем сейчас» и не отменяет §2 (целостный слой по-прежнему не в дефолтной очереди); фиксируется как направление на будущее, если триггер вытащит центр настроек из бэклога.

Отклонённые альтернативы¶

Только UI, TOML как скрытый экспорт — отклонено: ломает прозрачность, диффы, работу агента и сценарий «починил в блокноте».
Два источника правды (часть в реестре Windows, часть в TOML) без явного канона — отклонено: дублирование и рассинхрон.
Обязательный UI для каждого поля CascadeIdeSettings — отклонено: избыточно для текущей оси B (0027); TOML-only остаётся допустимым навсегда для продвинутого пути.

История изменений¶

Дата	Изменение
2026-04-08	целостный центр deferred; подраздел «Зачем точечный UI»; перспектива динамического UI от модели; точечный UI = вес кода.