ADR 0020: Видимость рассуждения агента и ограничения провайдеров LLM¶

Статус: Proposed
Дата: 2026-04-06

Связанные ADR¶

ADR	Роль
0016	внешний агент, stdio
0008	контракты и инфраструктура
0002	паритет человек/агент по смыслу «что произошло»

Контекст¶

В типичном IDE-агентном UX (в т.ч. у хостов с пошаговым «инференсом») пользователь видит сжатый след: фрагменты рассуждения, вызовы инструментов, итог — но не обязательно полную внутреннюю цепочку рассуждения модели за один проход.
Cascade IDE целится дать агенту и человеку общую опорную поверхность (команды, MCP, состояние). Естественное ожидание — больше прозрачности, чем «чёрный ящик»: что модель сделала, в каком порядке, с какими входами/выходами инструментов.
Ограничение не только UI: у разных провайдеров LLM разные контракты ответа. Часть моделей явно отдаёт отдельные поля (например расширенное рассуждение, structured steps); часть — скрывает сырой chain-of-thought по политике безопасности или продуктовой политике; часть даёт только итоговый текст и метаданные usage. Ожидать «полный внутренний монолог как у человека» независимо от провайдера нельзя.
Путаница «плохой UI» vs «API не отдаёт» вредит доверию: пользователь должен понимать, где мы показываем всё доступное, а где дыра на стороне провайдера.

Решение (направление)¶

Слоистая модель видимости (концептуально; детали реализации — при интеграции конкретного провайдера):
L0 — всегда: финальный ответ ассистента пользователю, факты об ошибках/отмене, полные трассируемые действия (вызовы MCP, git, терминал и т.д. — то, что IDE уже контролирует).
L1 — по умолчанию включено, если API отдаёт: потоковые куски текста рассуждения, отдельные поля thinking / аналоги, явные «шаги» из структурированного ответа.
L2 — опционально / расширенный режим: сырой лог запросов-ответов к API (с редактированием секретов), диагностика токенов, тайминги — для отладки интеграции и доверия «что ушло и что пришло».
Честная разметка: в UI, если провайдер не возвращает скрытое рассуждение, не имитировать его заглушками; показывать явное сообщение уровня «провайдер не отдаёт внутреннюю цепочку» (формулировка — пользовательски, без жаргона, когда не режим отладки).
Адаптер на провайдера: маппинг полей ответа (текст, структура, streaming) в единую внутреннюю модель событий чата; слой видимости подписан на эту модель, а не на сырой JSON каждого вендора в UI.
Паритет смысла с 0002: человек и агент должны иметь доступ к одинаково полным сведениям о действиях в среде (инструменты, команды). К содержимому скрытых весов модели паритет не гарантируется — он ограничен API.

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

Появляется явная зависимость от дорожной карты провайдеров: улучшение «прозрачности мысли» без смены модели/режима может быть невозможно.
Тесты интеграции: сценарии «что показываем при streaming», «что при отсутствии поля X», без хрупкой привязки к тексту юридических дисклеймеров провайдера.
Документация для пользователя Cascade: что именно IDE может обещать по видимости рассуждения, а что — нет.

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

Показывать только итоговый ответ без трасс инструментов — противоречит цели IDE и доверию к агенту.
Генерировать или «достраивать» рассуждение постфактум для красоты — создаёт ложное ощущение полноты и подрывает доверие.
Одинаковые гарантии для всех провайдеров — нереалистично без общего стандарта открытого рассуждения на стороне API.

Открытые вопросы¶

Конкретные контракты выбранных провайдеров (Anthropic, OpenAI, локальные и т.д.) — какие поля реально доступны в production-ключах Cascade IDE.
Нужна ли отдельная политика хранения логов L2 (локально только, TTL, исключение секретов).