ADR 0041: Protocol Buffers — рассмотрение для сообщений агента и IDE (точка входа)¶
Статус: Proposed (фиксация направления обсуждения и критериев; не решение о немедленной миграции с JSON)
Дата: 2026-04-13
Связанные ADR¶
| ADR | Роль |
|---|---|
| 0008 | контракты MCP и инфраструктура |
| 0018 | канон IdeCommands, ProtocolDocGen |
| 0038 | фасад агента, инструменты |
| 0001 | JSON как выбранное хранилище для отдельного домена — не смешивать с предметом этого ADR |
Вне ADR¶
| Документ | Роль |
|---|---|
| MCP-PROTOCOL.md | текущий wire-формат команд IDE для агента |
Контекст¶
Долго обсуждалась возможность использовать Protocol Buffers (protobuf) вместо или рядом с JSON для обмена структурированными сообщениями между агентом, IDE и смежными процессами. Решение не было зафиксировано в репозитории; без ADR теряется точка входа для последующих обсуждений и оценки трудозатрат.
Этот ADR задаёт рамку: где protobuf уместен, где JSON остаётся разумным дефолтом, какие границы разделять и какие критерии использовать при принятии решения — без обязательства внедрения в конкретной версии продукта.
Проблема¶
- JSON сегодня доминирует во внешних протоколах (MCP, многие LLM API), удобен для логов, отладки и ручной инспекции, не требует отдельного контура генерации схемы в простых сценариях.
- Protobuf даёт компактное представление, быстрый parse/serialize в типичных реализациях, явную схему с эволюцией через номера полей и codegen в .NET — но добавляет пайплайн (
.proto, сборка, дисциплина версий) и хуже читается человеком без инструментов.
Без зафиксированных границ команда рискует либо отклонить protobuf без формулировки критериев, либо смешать «внутренний бинарный контур» с «внешним JSON» без явной политики.
Решение (принципы)¶
1. Разделение по границам, а не «всё или ничег
- Внешняя / человеко-читаемая граница (спецификации вроде JSON-RPC MCP, публичные API, копипаст в чаты, быстрый grep по логам): JSON остаётся естественным кандидатом, пока спецификация или экосистема не требуют иного.
- Внутренний высокочастотный или объёмный контур (IPC между процессами IDE, потоки событий, персистентные логи больших структур, несколько языков с общим контрактом): protobuf (или иной IDL + бинарный формат) — кандидат на оценку, если измеримая выгода перевешивает стоимость сопровождения.
Переход «везде protobuf вместо JSON» не является целью этого ADR.
2. Критерии, при которых имеет смысл углублять protobuf¶
Имеет смысл выделять время на прототип или RFC, если выполняется не одно из ниже, а устойчивое сочетание по метрикам:
- Объём данных или частота сообщений создаёт заметную нагрузку на CPU/IO по сравнению с остальным пайплайном.
- Нужна строгая совместимость версий схемы при параллельной эволюции клиентов (полевая модель protobuf).
- Планируются несколько реализаций (например IDE + отдельные сервисы) и важен единый контракт без расхождения рукописных DTO.
Если ни один критерий не выполняется, JSON + дисциплина типов (и тесты контракта) могут оставаться достаточными.
3. Гибрид¶
Допустима и часто разумна схема: тот же логический контракт — разные кодеки на разных участках (например JSON на wire MCP и protobuf между внутренними компонентами), при явном mapping и тестах на границе. Это не обязанность дублировать каждое поле вручную навсегда — но точка конверсии должна быть осознанной и задокументированной.
4. Связь с текущим MCP и IdeCommands¶
Пока MCP-PROTOCOL.md и генерация исполнителей описывают JSON-аргументы команд, смена внешнего представления для агента — отдельное решение (спецификация MCP, совместимость с клиентами). Этот ADR не отменяет текущий канон; он задаёт рамку для будущих RFC по внутренним или опциональным контурам.
Не цели¶
- Обязательная миграция всего обмена с агентами на protobuf в ближайшем релизе.
- Отказ от JSON в логах и отладочных дампах без замены инструментами просмотра.
- Привязка к конкретной библиотеке gRPC: protobuf может сочетаться с gRPC, но решение о транспорте — отдельно.
Открытые вопросы¶
- Какие конкретные потоки в Cascade IDE (имена подсистем) первыми кандидаты на замер «JSON vs protobuf» — отдельный чертёж или задача после появления профилирования.
- Нужен ли единый репозиторий
.proto(monorepo + подмодули) или допустимы только внутренние контракты до стабилизации API. - Как документировать границу для контрибьюторов: один абзац в architecture-policy.md vs ссылка только на этот ADR.
Последствия¶
- Появляется стабильная ссылка для обсуждений и приоритизации: «см. 0041».
- Реализация protobuf не следует автоматически из статуса Proposed; требуется отдельное решение с метриками или пилотом.