| 1 | # ADR 0031: Чат агента — пакеты уточнений, ответы сложнее «да/нет», треды (направление) |
| 2 | |
| 3 | **Статус:** Proposed (черновик направления до переработки UI чата; детали протокола и экранов — по итерациям) |
| 4 | **Дата:** 2026-04-12 |
| 5 | **Обновлено:** 2026-04-19 — chat surface на pipeline snapshot (`ChatSurfaceCompositor`). Подробности — [§ История](#adr0031-history). |
| 6 | **Обновлено (ранее):** 2026-04-12 — «тема → подтемы», **обзор размаха на одном экране** vs глубокий скролл; смесь подзадач в одной сессии (ADR + ответвления) как норма. |
| 7 | |
| 8 | ## Связанные ADR |
| 9 | |
| 10 | | ADR | Роль | |
| 11 | |-----|------| |
| 12 | | [0016](0016-agent-client-protocol-external-agent.md) | ACP / внешний агент | |
| 13 | | [0017](0017-multi-window-workspace-and-agent-surfaces.md) | зона MFD, `MfdShellView`, второе окно | |
| 14 | | [0021](0021-pfd-mfd-cockpit-attention-model.md) | модель внимания; чат во вторичном контуре | |
| 15 | | [0020](0020-agent-reasoning-visibility-and-provider-limits.md) | слои ответа и трасс | |
| 16 | | [0008](0008-mcp-contracts-and-testable-infrastructure.md) | контракты и паритет при расширении | |
| 17 | | [0044](0044-avalonia-host-skia-agent-chat-surface.md) | разделение Avalonia / слой отрисовки чата; Skia как гипотеза | |
| 18 | | [0072](0072-chat-topic-cards-intent-melody-keyboard-contract.md) | UX-модель topic cards / drill-in/back и intent-навигация по темам | |
| 19 | |
| 20 | --- |
| 21 | ## Контекст |
| 22 | |
| 23 | В истории чата с агентом **естественно**, что за один «ход» пользователя или агента оказывается **несколько вопросов или подпунктов** — это не аномалия, а нормальная плотность диалога. |
| 24 | |
| 25 | Внешние продукты (в т.ч. режимы вроде **Plan** у Cursor) иногда показывают **список уточняющих вопросов** перед построением плана, но ответ часто сводят к **одной короткой строке** или набору жёстких **да/нет**. На практике ответ может быть: |
| 26 | |
| 27 | - **сложнее бинарного** (оговорки, варианты, ссылка на файл, приоритет); |
| 28 | - **связан с другими пунктами** списка (ответ на один меняет смысл следующего). |
| 29 | |
| 30 | Линейная лента сообщений **плохо совпадает** с объектом рассуждения «**пакет вопросов → структурированные ответы**». Текущий UI чата в Cascade (`SecondaryShellPage.Chat`, зона MFD) предстоит **переработать**; этот ADR задаёт **направление**, а не финальный макет. |
| 31 | |
| 32 | **Наблюдение (внешний опыт, напр. Cursor):** чтобы вспомнить, **что уже решили по уточнениям**, часто приходится **сильно отматывать** ленту назад — структура диалога в голове есть, в UI она **растворена в хронологии**. |
| 33 | |
| 34 | **Реальные сессии** распадаются на **тему и подтемы**: правка одного ADR, **по ходу** — ответвление на стороннюю идею и **новый ADR**, возврат к исходной линии. Это **нормальная** «пьеса», а не сбой процесса. Продуктовая гипотеза: у чата может быть роль **показать весь этот размах на одном экране** (обзор, карта, оглавление активных веток — точная форма не зафиксирована), при этом **общий контекст** для агента и человека остаётся **единым** (как сейчас по смыслу: одна сессия, одна передача контекста в модель — детали реализации не смешиваем с «две правды»). |
| 35 | |
| 36 | ## Проблема |
| 37 | |
| 38 | 1. **Один инпут на весь пакет** уточнений не масштабируется на небинарные и многострочные ответы. |
| 39 | 2. **Путаница ролей:** пакетные уточнения к плану/задаче — не то же самое, что разовое **подтверждение** опасного действия (см. PFD и `request_confirmation` в [0017](0017-multi-window-workspace-and-agent-surfaces.md)); смешивать в одном контроле нельзя. |
| 40 | 3. Без **явной структуры** на стороне клиента сложно воспроизводимо тестировать и давать паритет агенту/человеку ([0008](0008-mcp-contracts-and-testable-infrastructure.md)). |
| 41 | 4. **Потеря ориентации при длинной ленте:** без **снимка активной темы / пакета уточнений** пользователь вынужден к **глубокому скроллу**, чтобы восстановить состояние «что мы уже ответили». |
| 42 | |
| 43 | ## Решение (принципы) |
| 44 | |
| 45 | 1. **Пакет уточнений (clarification batch)** — осмысленная единица UI и, при согласовании с транспортом, протокола: набор пунктов с **стабильными идентификаторами** внутри пакета, чтобы ответы передавались как **структура** (`id → текст или выбранное значение`), а не как свободный парсинг одной строки. |
| 46 | |
| 47 | 2. **Представление в UI (целевое):** |
| 48 | - **карточки или блоки по одному пункту** с полем ответа **многострочным** там, где нужно; |
| 49 | - опционально **тип ответа** (краткий текст / выбор из вариантов / да–нет) на пункт; |
| 50 | - опционально **одно общее поле** в дополнение к пунктам («как я хочу в сумме»), если сценарий это оправдывает. |
| 51 | |
| 52 | 3. **Треды / темы** — отдельная ось: это не reply-thread ради reply-thread, а карта устойчивых линий работы. `ThreadNode` представляет тему / ответвление / отдельное исследование; обычные шаги внутри линии — `MessageNode`. Для **одного** пакета вопросов чаще достаточно остаться внутри текущей ветки; `ClarificationBatch` не создаёт новую ветку автоматически. |
| 53 | |
| 54 | 4. **Транспорт (ACP и др.):** расширение контракта сообщений/инструментов под структурированные пакеты — **в scope** вместе с поставкой UI, по аналогии с правилами [0008](0008-mcp-contracts-and-testable-infrastructure.md). Каноническая правда должна жить в structured event flow (`ClarificationBatchOpened`, `ClarificationAnswerSubmitted`) и MCP entrypoints, а не только в одной схлопнутой строке. |
| 55 | |
| 56 | 5. **Связь с зонами:** основной чат остаётся во **вторичном контуре / MFD** ([0021](0021-pfd-mfd-cockpit-attention-model.md)); вынесение на второй монитор — [0017](0017-multi-window-workspace-and-agent-surfaces.md). Критичные подтверждения, требующие внимания PFD, — по политике [0017 п. 6](0017-multi-window-workspace-and-agent-surfaces.md#adr0017-p6), не через замаскированный «чат-да/нет». |
| 57 | |
| 58 | 6. **Обзор размаха (направление, не макет):** рядом с хронологической лентой или вместо «только ленты» — представление **темы → подтем / открытых вопросов / принятых решений**, умещающее **ширину** сессии **в поле зрения**, чтобы не отматывать десятки экранов ради восстановления контекста по уточнениям. Смешение в одной сессии **нескольких линий работ** (например правка ADR и по ходу — отдельный ADR по ответвлению) отражается как **ветвления**, а не как потерянный шум. **Единый контекст** для модели и для пользователя сохраняется: обзор — **проекция** той же истории, а не второй несогласованный канал (детали — при проектировании хранилища диалога). |
| 59 | |
| 60 | ## Отклонённые альтернативы (как достаточное целевое состояние) |
| 61 | |
| 62 | - **Только одна строка ответа** на весь список уточнений — отклонено как систематически слабое для небинарных ответов и связанных вопросов. |
| 63 | - **Один тред без структуры**, полагаясь на парсинг естественного языка для извлечения ответов по пунктам — отклонено как основной путь для пакетных уточнений к плану (может остаться запасным для совместимости). |
| 64 | |
| 65 | ## Открытые вопросы |
| 66 | |
| 67 | - Минимальный **v1**: только визуальное улучшение (N полей вручную в UI) vs **сразу** договорённость с форматом сообщений агента. |
| 68 | - Нужны ли **черновики** ответов (сохранение незавершённого пакета при переключении вкладки/окна). |
| 69 | - Границы **тредов**: когда заводить субтред по пункту плана vs оставить в основной ленте. |
| 70 | - **Обзор размаха:** отдельная панель (оглавление, граф, «карта») vs встроенные **якоря** в ленте; как не дублировать источник правды с транскриптом для модели. |
| 71 | - Как **автоматически** предлагать «ветку» при ответвлении (новый ADR по ходу), не ломая восприятие одной темы. |
| 72 | |
| 73 | ## Последствия |
| 74 | |
| 75 | - Переработка **Chat**-поверхности и слоя состояния диалога в VM вокруг канонического snapshot, а не прямой Avalonia-ленты. |
| 76 | - Тесты UI и сценарии агента с **структурированным** телом пакета уточнений. |
| 77 | - Документация для пользователя: как отвечать на пакет вопросов, как это отличается от обычного сообщения и от подтверждений безопасности. |
| 78 | |
| 79 | ## Статус после принятия |
| 80 | |
| 81 | После согласования: статус **Accepted**, при необходимости ссылка из [concept-to-implementation-map-v1.md](../ui-ux/concept-to-implementation-map-v1.md) и обновление навигатора в [architecture-policy.md](../architecture-policy.md). |
| 82 | |
| 83 | --- |
| 84 | |
| 85 | ## История изменений |
| 86 | |
| 87 | <a id="adr0031-history"></a> |
| 88 | |
| 89 | | Дата | Изменение | |
| 90 | |------|-----------| |
| 91 | | 2026-04-13 | v0 доменной модели пакетов уточнений и валидации в коде: `Models/AgentChat/` (`ClarificationBatch`, `ClarificationItem`, `ClarificationResponse`, `ClarificationBatchValidation`); UI чата пока не подключён. | |
| 92 | | 2026-04-19 | chat surface переведён на pipeline snapshot (`ChatSurfaceCompositor`: `Intent -> Declutter -> Layout -> Render`), Skia закреплён как единый продуктовый path; `ClarificationBatch` / `ClarificationResponse` подключены к реальному chat flow и MCP-командам `open_chat_clarification_batch` / `submit_chat_clarification_response`. | |
| 93 | |