| 1 | # ADR 0041: Protocol Buffers — рассмотрение для сообщений агента и IDE (точка входа) |
| 2 | |
| 3 | **Статус:** Proposed (фиксация направления обсуждения и критериев; **не** решение о немедленной миграции с JSON) |
| 4 | **Дата:** 2026-04-13 |
| 5 | ## Связанные ADR |
| 6 | |
| 7 | | ADR | Роль | |
| 8 | |-----|------| |
| 9 | | [0008](0008-mcp-contracts-and-testable-infrastructure.md) | контракты MCP и инфраструктура | |
| 10 | | [0018](0018-ide-commands-canonical-xml-documentation.md) | канон `IdeCommands`, ProtocolDocGen | |
| 11 | | [0038](0038-agent-facade-ai-provider-and-tool-orchestration.md) | фасад агента, инструменты | |
| 12 | | [0001](0001-debug-hypotheses-json-storage.md) | JSON как выбранное хранилище для отдельного домена — не смешивать с предметом этого ADR | |
| 13 | |
| 14 | ### Вне ADR |
| 15 | |
| 16 | | Документ | Роль | |
| 17 | |----------|------| |
| 18 | | [MCP-PROTOCOL.md](../MCP-PROTOCOL.md) | текущий wire-формат команд IDE для агента | |
| 19 | |
| 20 | --- |
| 21 | ## Контекст |
| 22 | |
| 23 | Долго обсуждалась возможность использовать **Protocol Buffers (protobuf)** вместо или рядом с **JSON** для обмена структурированными сообщениями между **агентом**, **IDE** и смежными процессами. Решение не было зафиксировано в репозитории; без ADR теряется **точка входа** для последующих обсуждений и оценки трудозатрат. |
| 24 | |
| 25 | Этот ADR задаёт **рамку**: где protobuf уместен, где JSON остаётся разумным дефолтом, какие **границы** разделять и какие **критерии** использовать при принятии решения — без обязательства внедрения в конкретной версии продукта. |
| 26 | |
| 27 | --- |
| 28 | |
| 29 | ## Проблема |
| 30 | |
| 31 | - **JSON** сегодня доминирует во внешних протоколах (MCP, многие LLM API), удобен для **логов, отладки и ручной инспекции**, не требует отдельного контура генерации схемы в простых сценариях. |
| 32 | - **Protobuf** даёт **компактное представление**, **быстрый** parse/serialize в типичных реализациях, **явную схему** с эволюцией через номера полей и codegen в **.NET** — но добавляет **пайплайн** (`.proto`, сборка, дисциплина версий) и **хуже читается** человеком без инструментов. |
| 33 | |
| 34 | Без зафиксированных **границ** команда рискует либо отклонить protobuf без формулировки критериев, либо смешать «внутренний бинарный контур» с «внешним JSON» без явной политики. |
| 35 | |
| 36 | --- |
| 37 | |
| 38 | <a id="adr0041-p1"></a> |
| 39 | |
| 40 | ## Решение (принципы) |
| 41 | |
| 42 | ### 1. Разделение по границам, а не «всё или ничего» |
| 43 | |
| 44 | - **Внешняя / человеко-читаемая граница** (спецификации вроде JSON-RPC MCP, публичные API, копипаст в чаты, быстрый grep по логам): **JSON** остаётся **естественным кандидатом**, пока спецификация или экосистема не требуют иного. |
| 45 | - **Внутренний высокочастотный или объёмный контур** (IPC между процессами IDE, потоки событий, персистентные логи больших структур, несколько языков с общим контрактом): **protobuf** (или иной **IDL + бинарный** формат) — **кандидат на оценку**, если измеримая выгода перевешивает стоимость сопровождения. |
| 46 | |
| 47 | Переход «везде protobuf вместо JSON» **не** является целью этого ADR. |
| 48 | |
| 49 | <a id="adr0041-p2"></a> |
| 50 | |
| 51 | ### 2. Критерии, при которых имеет смысл углублять protobuf |
| 52 | |
| 53 | Имеет смысл выделять время на прототип или RFC, если выполняется **не одно** из ниже, а устойчивое сочетание по метрикам: |
| 54 | |
| 55 | - **Объём данных** или **частота сообщений** создаёт заметную нагрузку на CPU/IO по сравнению с остальным пайплайном. |
| 56 | - Нужна **строгая совместимость версий** схемы при параллельной эволюции клиентов (полевая модель protobuf). |
| 57 | - Планируются **несколько реализаций** (например IDE + отдельные сервисы) и важен **единый контракт** без расхождения рукописных DTO. |
| 58 | |
| 59 | Если ни один критерий не выполняется, **JSON + дисциплина типов** (и тесты контракта) могут оставаться достаточными. |
| 60 | |
| 61 | <a id="adr0041-p3"></a> |
| 62 | |
| 63 | ### 3. Гибрид |
| 64 | |
| 65 | Допустима и часто разумна схема: **тот же логический контракт** — разные кодеки на разных участках (например JSON на wire MCP и protobuf между внутренними компонентами), при явном **mapping** и тестах на границе. Это **не** обязанность дублировать каждое поле вручную навсегда — но **точка конверсии** должна быть осознанной и задокументированной. |
| 66 | |
| 67 | <a id="adr0041-p4"></a> |
| 68 | |
| 69 | ### 4. Связь с текущим MCP и `IdeCommands` |
| 70 | |
| 71 | Пока [MCP-PROTOCOL.md](../MCP-PROTOCOL.md) и генерация исполнителей описывают **JSON-аргументы** команд, смена **внешнего** представления для агента — **отдельное** решение (спецификация MCP, совместимость с клиентами). Этот ADR **не** отменяет текущий канон; он задаёт рамку для **будущих** RFC по внутренним или опциональным контурам. |
| 72 | |
| 73 | --- |
| 74 | |
| 75 | <a id="adr0041-non-goals"></a> |
| 76 | |
| 77 | ## Не цели |
| 78 | |
| 79 | - Обязательная миграция всего обмена с агентами на protobuf в ближайшем релизе. |
| 80 | - Отказ от JSON в логах и отладочных дампах без замены инструментами просмотра. |
| 81 | - Привязка к конкретной библиотеке gRPC: protobuf **может** сочетаться с gRPC, но решение о транспорте — отдельно. |
| 82 | |
| 83 | --- |
| 84 | |
| 85 | <a id="adr0041-open-questions"></a> |
| 86 | |
| 87 | ## Открытые вопросы |
| 88 | |
| 89 | 1. Какие **конкретные потоки** в Cascade IDE (имена подсистем) первыми кандидаты на замер «JSON vs protobuf» — отдельный чертёж или задача после появления профилирования. |
| 90 | 2. Нужен ли **единый репозиторий `.proto`** (monorepo + подмодули) или допустимы только **внутренние** контракты до стабилизации API. |
| 91 | 3. Как **документировать** границу для контрибьюторов: один абзац в [architecture-policy.md](../architecture-policy.md) vs ссылка только на этот ADR. |
| 92 | |
| 93 | --- |
| 94 | |
| 95 | ## Последствия |
| 96 | |
| 97 | - Появляется **стабильная ссылка** для обсуждений и приоритизации: «см. [0041](0041-protobuf-for-agent-and-ide-messages.md)». |
| 98 | - Реализация protobuf **не** следует автоматически из статуса Proposed; требуется отдельное решение с метриками или пилотом. |
| 99 | |