Створення файлів 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.