| 1 | # ADR 0020: Видимость рассуждения агента и ограничения провайдеров LLM |
| 2 | |
| 3 | **Статус:** Proposed |
| 4 | **Дата:** 2026-04-06 |
| 5 | |
| 6 | ## Связанные ADR |
| 7 | |
| 8 | | ADR | Роль | |
| 9 | |-----|------| |
| 10 | | [0016](0016-agent-client-protocol-external-agent.md) | внешний агент, stdio | |
| 11 | | [0008](0008-mcp-contracts-and-testable-infrastructure.md) | контракты и инфраструктура | |
| 12 | | [0002](0002-debug-human-agent-parity.md) | паритет человек/агент по смыслу «что произошло» | |
| 13 | | [naming-layers-v1.md](../design/naming-layers-v1.md) | `trace.*` semantic ids (§4) | |
| 14 | |
| 15 | --- |
| 16 | ## Контекст |
| 17 | |
| 18 | 1. В типичном IDE-агентном UX (в т.ч. у хостов с пошаговым «инференсом») пользователь видит **сжатый след**: фрагменты рассуждения, вызовы инструментов, итог — но не обязательно **полную** внутреннюю цепочку рассуждения модели за один проход. |
| 19 | |
| 20 | 2. **Cascade IDE** целится дать агенту и человеку **общую опорную поверхность** (команды, MCP, состояние). Естественное ожидание — **больше прозрачности**, чем «чёрный ящик»: что модель сделала, **в каком порядке**, с какими входами/выходами инструментов. |
| 21 | |
| 22 | 3. **Ограничение не только UI:** у разных **провайдеров LLM** разные контракты ответа. Часть моделей явно отдаёт отдельные поля (например расширенное рассуждение, structured steps); часть — **скрывает** сырой chain-of-thought по политике безопасности или продуктовой политике; часть даёт только итоговый текст и метаданные usage. Ожидать «полный внутренний монолог как у человека» **независимо от провайдера** нельзя. |
| 23 | |
| 24 | 4. Путаница **«плохой UI»** vs **«API не отдаёт»** вредит доверию: пользователь должен понимать, где **мы показываем всё доступное**, а где **дыра на стороне провайдера**. |
| 25 | |
| 26 | ## Решение (направление) |
| 27 | |
| 28 | 1. **Слоистая модель видимости** (концептуально; детали реализации — при интеграции конкретного провайдера). Канон **`trace_layer`** — [naming-layers-v1.md](../design/naming-layers-v1.md) §4; legacy L0–L2 — deprecated в UI: |
| 29 | - **`trace.answer`** (legacy L0) — всегда: финальный ответ ассистента пользователю, факты об ошибках/отмене, **полные трассируемые действия** (вызовы MCP, git, терминал и т.д. — то, что IDE уже контролирует). |
| 30 | - **`trace.reasoning`** (legacy L1) — по умолчанию включено, **если API отдаёт:** потоковые куски текста рассуждения, отдельные поля `thinking` / аналоги, явные «шаги» из структурированного ответа. |
| 31 | - **`trace.provider_raw`** (legacy L2) — опционально / расширенный режим: сырой лог запросов-ответов к API (с редактированием секретов), диагностика токенов, тайминги — для отладки интеграции и доверия «что ушло и что пришло». |
| 32 | |
| 33 | 2. **Честная разметка:** в UI, если провайдер **не возвращает** скрытое рассуждение, не имитировать его заглушками; показывать **явное сообщение** уровня «провайдер не отдаёт внутреннюю цепочку» (формулировка — пользовательски, без жаргона, когда не режим отладки). |
| 34 | |
| 35 | 3. **Адаптер на провайдера:** маппинг полей ответа (текст, структура, streaming) в **единую внутреннюю модель** событий чата; слой видимости подписан на эту модель, а не на сырой JSON каждого вендора в UI. |
| 36 | |
| 37 | 4. **Паритет смысла с [0002](0002-debug-human-agent-parity.md):** человек и агент должны иметь доступ к **одинаково полным** сведениям о **действиях в среде** (инструменты, команды). К **содержимому скрытых весов модели** паритет **не гарантируется** — он ограничен API. |
| 38 | |
| 39 | ## Последствия |
| 40 | |
| 41 | - Появляется явная **зависимость от дорожной карты провайдеров**: улучшение «прозрачности мысли» без смены модели/режима может быть **невозможно**. |
| 42 | - Тесты интеграции: сценарии «что показываем при streaming», «что при отсутствии поля X», без хрупкой привязки к тексту юридических дисклеймеров провайдера. |
| 43 | - Документация для пользователя Cascade: **что именно** IDE может обещать по видимости рассуждения, а что — нет. |
| 44 | |
| 45 | ## Отклонённые альтернативы |
| 46 | |
| 47 | - **Показывать только итоговый ответ** без трасс инструментов — противоречит цели IDE и доверию к агенту. |
| 48 | - **Генерировать или «достраивать» рассуждение постфактум** для красоты — создаёт ложное ощущение полноты и подрывает доверие. |
| 49 | - **Одинаковые гарантии для всех провайдеров** — нереалистично без общего стандарта открытого рассуждения на стороне API. |
| 50 | |
| 51 | ## Открытые вопросы |
| 52 | |
| 53 | - Конкретные контракты выбранных провайдеров (Anthropic, OpenAI, локальные и т.д.) — **какие поля** реально доступны в production-ключах Cascade IDE. |
| 54 | - Нужна ли отдельная **политика хранения** логов `trace.provider_raw` (локально только, TTL, исключение секретов). |
| 55 | |