Перейти до вмісту
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.

Що далі