Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Написание файлов Aggrega

Описание сущностей в Aggrega — это короткий повторяемый цикл. Какую бы сущность вы ни писали — сущность Aggregate разработчика, сущность Component архитектора, сущность Recipe эксплуатации или сущность Release оператора, — одни и те же пять шагов приводят вас от пустого файла к проверенному:

  1. Выберите сущность, которой владеет ваша роль.
  2. Изучите её структуру по JSON Schema и справочной странице.
  3. Начните с заготовки, а не с пустого файла.
  4. Заполните поля, которыми владеет ваша роль, оставив остальные их владельцам.
  5. Проверьте, затем скомпилируйте.

На этой странице цикл проходится один раз — как для человека, пишущего вручную, так и для ИИ-ассистента, работающего через сервер 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.

Что дальше