Довідник мови
«Що» та «як використовувати» в Aggrega. Синтаксис, виклик CLI, каталог помилок, розібрані приклади.
Для першого ознайомлення читайте розділи нижче по порядку. Довідкові підкаталоги наведено під відповідним розділом — переходьте до них безпосередньо, коли шукаєте конкретну сутність, ключове слово, провайдер, команду CLI або помилку.
Перш ніж читати розділи по порядку, ознайомтеся з Станом мови, щоб дізнатися про поточний стан готовності: які елементи мови доступні вже сьогодні, які приймаються, але компілятор ще не обробляє їх, а які заплановано на майбутні ітерації. Розділ Сумісність визначає, що реліз обіцяє щодо схем, командного рядка, інструментів асистента, кодів помилок і наборів для розробки плагінів.
Модель рівнів сутностей
Види сутностей для авторингу в Aggrega організовано у три рівні, що відображають поступовість впровадження (нижче). Поряд із ними існує сутність Workload, якою володіє платформа: це не окремий вид для авторингу, а форма, якої набуває синтезований вхід сутності Recipe, і вона виражає форму обчислень через словник form: (stateless, stateful, daemon, scheduled, task, reference). Поділ на рівні — це механізм документації та онбордингу, а не обмеження під час виконання: кожен вид сутності є повноправним елементом мови; компілятор обробляє їх однаково; Aggrega з відкритим кодом підтримує всі рівні без ліцензування чи обмеження функцій. Позначки рівнів сигналізують «розширене; пропустіть, якщо не потрібно» для навігації, а не щодо можливостей.
| Рівень | Види сутностей | Коли впроваджувати |
|---|---|---|
| Рівень 1 — мінімально життєздатна поверхня | Aggregate, Component, Recipe, Manifest, Release | День 1 — засновники-одинаки й невеликі команди випускають робоче програмне забезпечення лише з рівнем 1. Ментальна модель: «У мене є застосунок; я хочу його розгорнути; ось як». |
| Рівень 2 — розподіл ролей | Feature, FeatureRecipe, Plugin | День 30 — невеликі команди, у яких ролі розділяються (розробник + Ops + іноді Security). Рівень 2 з’являється через Plugins для рендерингу провайдерів (Ops обирають серед Helm, helm-chart, Compose, Terraform і CloudFormation), Features (Security керує обліковими даними окремо від конфігурації застосунку) та FeatureRecipes (налаштування під час прив’язки для кожного провайдера). |
| Рівень 3 — повторне використання між сутностями Component | SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary | День 365 — зрілі каталоги, де спільні форми повторюються в багатьох сутностях. Поріг неформальний: коли форма (наприклад, PodResources) з’являється у 5+ сутностях Components і узгодження оновлень стає тертям, запис у SchemaLibrary виправдовує себе. |
Кожен крок переходу є добровільним. Засновника-одинака ніколи не змушують дивитися на рівень 3; корпоративний каталог має повний доступ до рівня 3 за потреби. Рівень 1 є повним для сценарію засновника-одинака — розробник може випускати робочі застосунки, використовуючи лише сутності рівня 1. Це сильна властивість дизайну: рівень 1 — не «підмножина, що компілюється»; це «підмножина, що випускає програмне забезпечення».
Поверхня рівня 1 із п’яти сутностей має вхідну ціну — Aggregate + Component + Recipe + Manifest + Release означає більше церемоній, ніж «покладіть YAML-файл і отримайте працюючий сервіс». Ця ціна — плата за розділення авторингу на чотири домени (Developer Intent / Platform Catalog / Platform Ops / Routing), яке відрізняє Aggrega від чистого Helm чи чистого Terraform. Навчальні посібники рівня 1 явно проводять через налаштування п’яти сутностей.
У межах рівня 3 механіку spec.templates / $instantiate: (параметричні помічники в SchemaLibrary) задокументовано як ще розширенішу підфункцію. Більшість тих, хто впроваджує рівень 3, спочатку не звертаються до spec.templates; поріг — «коли у вашій бібліотеці 6+ схем зі спільною параметризованою структурою».
Порядок читання
- Як користуватися цим довідником
- Домовленості щодо іменування
- Огляд довідника сутностей
- Рівень 1: aggregate, component, recipe, manifest, release
- Рівень 2: feature, featurerecipe, plugin
- Рівень 3: schemalibrary, mappinglibrary, workloadlibrary, artifactlibrary
- Наскрізне: workload (вид сутності компілятора, що належить платформі й використовується всередині
workload:сутності Recipe)
- Огляд словника
- Довідник словника: topology-triad (provides, inject, uses), data-pillars (values, infra, parameters, locals), inheritance-and-interface (extends, implements), modifier-system (appliesTo, selectors), compact-form-authoring, cross-document-ref, labels-and-annotations, publishing-surface, social-contracts, validation-surface, output-composition, uri-grammar, version-resolution
- Огляд шаблонів
- Довідник шаблонів: expansion-matrix, template-context-contract, sprig-functions, parameters-context, assertions-block, rendered-resource-names
- Огляд Providers
- Довідник Providers: architecture, well-known-annotations, reference-matrix, helm, helm-chart, compose, terraform, cloudformation
- Огляд CLI
- Довідник CLI: aggrega-build, aggrega-inspect, aggrega-pull, aggrega-lint, aggrega-auth, aggrega-cache, aggrega-config, aggrega-deprecate, aggrega-edit-document, aggrega-explain, aggrega-get-schema, aggrega-import і файл відповідей імпорту, aggrega-login, aggrega-logout, aggrega-mcp, aggrega-pin, aggrega-plugin, aggrega-push, aggrega-push-artifact, aggrega-registry, aggrega-scaffold, aggrega-search, aggrega-serve, aggrega-sign, aggrega-skills, aggrega-validate, aggrega-version, global-flags, configuration, environment-variables, workspace-boundary
- Огляд помилок
- Довідник помилок: fatal-halts, warnings, sentinels, error-translation
- Огляд прикладів
- Довідник прикладів: 01-getting-started, 02-data-model, 03-features-and-policies, 04-secrets, 05-credential-features, 06-composition, 07-input-kinds, 08-advanced-patterns, 09-cross-boundary-routing; робочі простори, які можна запустити: Приклади для запуску
Довідник з розробки Plugin
Поверхня плагінів Wasm розташована поруч із послідовністю розділів, а не всередині неї: автор плагіна читає її незалежно від шляху створення сутностей. Сторінка сутності plugin описує поверхню створення каталогу; сторінки нижче описують сокети, корисні навантаження та робочий процес автора.
- plugin-contract — сокети, до яких підключається плагін, їхнє місце в конвеєрі та форми вхідних і вихідних даних кожного сокета.
- plugin-developer-guide — наскрізний робочий процес автора:
describe(), заявлені можливості, обмеження середовища виконання, життєвий цикл publish/pull/build, підписування, версіювання. - policy-socket — докладно про сокет керування: його чотири ролі, рівні серйозності вердиктів, канал вхідних даних оператора та написання політики для будь-якого з рушіїв, що постачаються в складі компілятора.
- governance-attachment-facts — факти щодо кожного підключення, які політика керування зчитує з графа збирання, зокрема три одиниці позначки чутливості та причини, чому відсутність позначки не є дозволом.
- when-to-use-a-pipeline-step — вибір між кроком конвеєра та шаблонною сутністю FeatureRecipe.
- embedded-plugins — плагіни, що постачаються в складі бінарного файлу компілятора.
- tagging-plugins — два вбудовані плагіни управління, що записують мітки без політики,
governance/label-injectorіgovernance/selector-tagger: їхні налаштування та те, що записує кожен із них. - core-importers — десять імпортерів компілятора, від Langflow, Flowise та n8n до Compose, MCP і фреймворків агентів: що кожен із них читає та що складає як чернетку, їхні налаштування та їх публікація з кожним випуском компілятора.
- authoring-a-provider-walkthrough — покроковий розбір створення гостьового модуля провайдера: від порожнього каталогу до збірки, яка записує файли, відрендерені провайдером.
- writing-a-governance-plugin — написання власного плагіна управління на основі каркаса адаптера з набору для плагінів: одне правило, ручний запуск експорту кожної ролі, сутність
Pluginу каталозі робочого простору та збірка, яку плагін відхиляє. - compatibility — як версіонуються набори для розробки плагінів: що можуть змінити патч-реліз і мінорний реліз набору і що забезпечує, щоб уже зібраний плагін і далі завантажувався.