Написание файлов Aggrega
Описание сущностей в Aggrega — это короткий повторяемый цикл. Какую бы сущность вы ни писали — сущность Aggregate разработчика, сущность Component архитектора, сущность Recipe эксплуатации или сущность Release оператора, — одни и те же пять шагов приводят вас от пустого файла к проверенному:
- Выберите сущность, которой владеет ваша роль.
- Изучите её структуру по JSON Schema и справочной странице.
- Начните с заготовки, а не с пустого файла.
- Заполните поля, которыми владеет ваша роль, оставив остальные их владельцам.
- Проверьте, затем скомпилируйте.
На этой странице цикл проходится один раз — как для человека, пишущего вручную, так и для ИИ-ассистента, работающего через сервер Model Context Protocol. Оба пути — это один и тот же цикл над одними и теми же справочными ресурсами. Обоим нужен исполняемый файл aggrega: раздел Установка исполняемого файла устанавливает его одной командой.
1. Выберите сущность, которой владеет ваша роль
Aggrega разделяет описание на четыре взаимодействующие роли — намерение разработчика, каталог платформы, инфраструктурные рецепты и связывание развёртывания. Каждая роль обычно владеет определённым набором видов сущностей. Если вы уже знаете свою роль, переходите к нужной сущности; если нет, прочитайте Персоны о четырёх ролях и Сущности по ролям — полное соответствие видов и ролей.
Это разделение — рекомендация, а не правило, которое обеспечивает компилятор. Автор-одиночка может играть все роли и написать все сущности за один раз; компилятор принимает любой способ описания, проходящий проверку по схеме. Роли существуют, чтобы разграничить ответственность, а не чтобы ограничивать то, что вы можете писать.
2. Изучите её структуру
У каждого вида сущности есть каноническая JSON Schema и справочная страница с описанием каждого поля. Прочитайте обе, прежде чем писать:
- Схема задаёт точную структуру: обязательные поля, допустимые значения и вложенность. В командной строке её выводит
aggrega get-schema <kind>;aggrega get-schema --listперечисляет все виды, которые можно запросить. Ассистент читает те же байты из ресурсаschema://<kind>. См. справку поaggrega get-schema. - Справочная страница объясняет, что означает каждое поле и как поля связаны между собой. Страницы сущностей находятся в
language-reference/entities/— например, component или aggregate. Ассистент читает ту же страницу из ресурсаlangref://entities/<kind>.
Схема говорит, что структурно допустимо; справка — что разумно. Читайте схему, чтобы избежать отклонения при проверке, и справку, чтобы написать то, что делает задуманное.
3. Начните с заготовки
Начинать с заготовки быстрее и надёжнее, чем с пустого файла. Ассистент, подключённый к серверу MCP, вызывает инструмент scaffold с видом и именем и получает минимальную отправную точку со всеми полями, обязательными для этого вида, и заполнителем везде, где значение ещё нужно указать. При ручной работе aggrega scaffold <kind> <name> выводит ту же отправную точку в стандартный вывод, так что перенаправьте её в файл; или скопируйте ближайший рабочий пример и сократите его до нужного.
В любом случае заготовка уже содержит обязательные поля верхнего уровня (apiVersion, kind, metadata.name) в правильной форме, поэтому вы уделяете внимание полям своей роли, а не шаблонному коду.
4. Заполните поля, которыми владеет ваша роль
Заполняйте только те разделы, за которые отвечает ваша роль, и оставляйте остальные их владельцам. Разработчик задаёт намерение приложения и значения; архитектор объявляет контракт — значения, которые может задать разработчик, выходные данные, которые предоставляет компонент, и сокеты, которые он открывает; эксплуатация отображает этот контракт на конкретного провайдера, не меняя интерфейс для разработчика; оператор связывает развёртывание. В разделе Сущности по ролям для каждого вида указано, какие разделы принадлежат какой роли.
Именно то, что каждое значение находится в разделе, которым управляет его владелец, позволяет одному и тому же намерению разработчика нацеливаться на разную инфраструктуру в разных окружениях без изменения файла разработчика. Это и есть причина, по которой поверхность описания вообще разделена.
Ограничьте описание несколькими короткими абзацами. Поле metadata.description сущности — это текст, который читатель видит до того, как выбрать её: он публикуется вместе с сущностью как её описание для поиска, и aggrega search сопоставляет с ним запрос. Пишите его для этого момента короткими абзацами — в свёрнутом блоке description: > пустая строка начинает новый абзац, — объясняя, что представляет собой сущность, как читатель её использует, где она реализуется и чего она не делает. Ограничение, которое читателю нужно знать до выбора сущности, тоже относится сюда, изложенное кратко. Всё остальное — почему значение по умолчанию именно такое, как настройка ведёт себя на одной цели, что значение означает при каждой реализации — помещайте в комментарии YAML рядом с полем или блоком, который они поясняют, где их прочитает человек, работающий с этим полем. Компилятор никак не ограничивает длину описания и не реагирует на его содержание, поэтому краткость нужна ради читателя.
5. Проверьте, затем скомпилируйте
Проверьте файл, прежде чем на него полагаться:
- Ассистент вызывает инструмент
validate, который сразу сообщает об ошибках схемы и ссылок, чтобы ассистент мог исправить черновик, прежде чем вернуть его. - При ручной работе
aggrega validate <file>проверяет один файл Component, Feature, Recipe, FeatureRecipe, Workload или Plugin, аaggrega validate --release <release>проверяет всё, до чего доходит сущность Release, включая её Aggregate и Manifest.aggrega lintприменяет правила дисциплины публикации к сущности каталога, аaggrega inspectразрешает и показывает то, что видит компилятор. Когда вся топология готова,aggrega pull --release <release>разрешает её зависимости и записывает lock-файл, после чегоaggrega build --release <release>компилирует сущность Release в артефакты для каждой границы — неудачная сборка точно указывает, что исправить.
Ранняя проверка обходится дешевле поздней неудачной сборки. Напишите, проверьте, исправьте и только потом компилируйте.
Описание сущностей с ИИ-ассистентом
Команда aggrega mcp запускает сервер Model Context Protocol, который превращает любой клиент с поддержкой MCP в ассистента, знающего Aggrega. После подключения ассистент может:
- Принять роль с помощью встроенных промптов — по одному на персону (разработчик, архитектор, эксплуатация) плюс специализированный шаблон для отдельной сущности. Каждый промпт задаёт роль и направляет ассистента к схеме, справочной странице и этому руководству, чтобы его предложения оставались в пределах разделов, которыми владеет роль.
- Читать справку через ресурсы:
schema://<kind>— JSON Schema вида,langref://<path>— любая справочная страница,authoring://<topic>— это руководство. - Действовать в вашем рабочем пространстве через инструменты:
scaffold— создать корректную заготовку,validate— проверить черновик,describe— изучить сущность каталога,get-schema— получить схему по виду.
Всё, что читает ассистент, предоставляется с вашей машины: схемы встроены в бинарный файл, а страницы руководства и справки берутся из пакета документации, хранящегося в кеше вашей машины, который сервер загружает из реестра, если при запуске не находит там копии. Чтение страницы, создание заготовки и валидация не обращаются к сети; если пакет загрузить не удаётся, схемы по-прежнему предоставляются, а страницы — нет. Чтобы подключить клиент, следуйте разделу Подключение MCP-сервера; остальное, что доступно ассистенту, описано в разделе Что ваш ассистент может делать с Aggrega. О самой команде см. справку по aggrega mcp.
Что дальше
- Персоны — разберитесь в четырёх ролях, прежде чем выбрать сущность.
- Сущности по ролям — полное соответствие видов и ролей.
- Установка — установите бинарный файл; подключить ассистента поможет раздел Подключение MCP-сервера.
- Настройка Aggrega с помощью ИИ-ассистента — один промпт, по которому ваш ассистент сам устанавливает и подключает Aggrega.
- Обзор CLI — все подкоманды
aggrega.