Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Розширюваність

Розширюваність екосистеми та запобіжники компілятора

1. Універсальний інтерфейс WebAssembly (Wasm)

Щоб забезпечити архітектурну симетрію в усій екосистемі, Aggrega використовує стандартизований контракт виконання, який однаково застосовується до кожного Wasm-сокета в конвеєрі компілятора.

YAML-інтерфейс для виклику будь-якого плагіна спирається на два свідомо обрані ключові слова: function і with.

  • function: Aggrega вбудовує середовище виконання Wasm (набір інструментів Extism поверх рушія Wazero) і виконує Wasm безпосередньо в пам’яті, тож жоден процес операційної системи не запускається. function називає експорт, який викликає хост на Go: явно експортовану функцію модуля Wasm.
  • with: власні вхідні дані плагіна, відокремлені від values розробника та від parameters, які виконує Release. Ключове слово дотримується домовленості GitHub Actions (with:); якщо плагін оголошує JSON Schema для своїх вхідних даних, хост перевіряє їх за нею перед виконанням.

Типи Wasm Plugins: Цей універсальний інтерфейс function і with підтримує кожен програмований сокет компілятора:

Тип PluginДе виконуєтьсяПризначенняОчікуваний результат
Provider (provider)Рендеринг (генерація)Перетворює остаточний IR у пам’яті на фізичні файли у вигляді рядків для цільового формату (Helm, Terraform, Compose).Масив файлів у вигляді рядків.
Крок конвеєра FeatureRecipe (pipeline-step)Конвеєр плагінів сутності Recipe або FeatureRecipeПослідовні кроки, що отримують секрети або впроваджують sidecar-контейнери в базові AST.patches за RFC 6902 до набору документів із ключами, а також side_effects (створення нового документа чи файлу), diagnostics і outputs, які може прочитати наступний крок. Вхідні дані кроку містять цей набір документів із ключами та відрендерений вхід with кроку.
Governance (governance)Перед розгортанням анотацій, побудова топології, статичний аналіз або етап рендерингуВиконує ролі керування в конвеєрі збірки. Перед розгортанням анотацій впроваджує анотації в розв’язані компоненти, а під час побудови топології автоматично позначає вузли мітками відповідності чи середовища (оператор явно вмикає кожну з цих ролей). Під час статичного аналізу або на етапі рендерингу діє як гучний запобіжник: перевіряє ребра графа, шляхи й мітки — або відрендерені артефакти — на відповідність межам безпеки. Що саме він може видавати, визначає роль, до якої його приєднано, а не його вид.Перед розгортанням анотацій — впровадження анотацій. Під час побудови топології — масив JSONPatch, спрямованих на metadata.labels. Під час статичного аналізу або на етапі рендерингу — вердикти рівня halt, warn або info (політика Rego збирає їх у deny, warn і audit); halt зупиняє збірку.
Linter (linter)Поза збіркоюНеобов’язкові перевірки FinOps або гігієни (наприклад, оцінка хмарних витрат на основі .infra) і дисципліна під час публікації.Рядки попереджень або фатальні зупинки.
Розширення CLI (cli)Під час виконання (aggrega <command>)Готова до підключення команда верхнього рівня, яку надає підписаний ізольований плагін, без жодного коду Go для окремої команди в хості.Потокові стандартний вивід і потік помилок, а також код виходу гостьового модуля.
Parser (parser)На вимогу, скрізь, де читається сторонній форматПеретворює сторонній вихідний текст (HCL, TOML, YAML, JSON, JSON з коментарями) на канонічне дерево JSON.tree і diagnostics, а також необов’язкові вихідні spans.
Importer (importer)На вимогу, поза будь-якою збіркою (aggrega import, редактор та інструмент import асистента)Перетворює стороннє джерело визначення інфраструктури чи агентів (Langflow, Flowise, n8n, конфігурацію MCP, застосунок Compose, застосунок Dify, оголошених агентів проєкту CrewAI, конфігурацію застосунку LangGraph, конфігурації агентів застосунку Google ADK, декларативного агента Agent Framework) на чернеткові авторські файли Aggrega, оголошуючи формати, які він обробляє, як можливості import:<format>.Чернеткові сутності Aggregate / Component / Release або посилання на сутності Components каталогу, які він повторно використовує, рішення про зіставлення, що стоять за ними, діагностику та файли каркаса для запису.

Середовище виконання хоста: пісочниця, що забороняє можливості. Aggrega вбудовує Wasm-хост як набір інструментів Extism, що працює поверх рушія Wazero; бінарний файл хоста залишається чистим Go без залежності від нативного інструментарію, тож aggrega без проблем крос-компілюється. Кожен сокет працює за брандмауером AOT-чистоти: хост відмовляється надавати плагіну будь-яку можливість доступу під час виконання — ні мережі, ні файлової системи, ні системного годинника, ні середовища, ні стандартного вводу-виводу, — тож виклик, який скористався б такою можливістю, завершується помилкою, а плагін, що імпортує з інтерфейсу хоста, якого хост не надає, відхиляється під час завантаження. Плагін, що не може дістатися мережі чи прочитати годинник, не може порушити гарантію компіляції наперед (ahead-of-time), що однаковий вхід дає однаковий вихід. Середовища виконання мов, яким потрібно кілька нешкідливих імпортів під час запуску, працюють із конфігурацією цих імпортів, що забороняє можливості: хост фіксує видимий системний годинник, надає справжню ентропію, відкидає стандартний ввід-вивід і не надає доступу до файлової системи, аргументів чи середовища — тож плагін не може дістатися жодної можливості хоста, що змінюється між збірками. Ентропію свідомо залишено справжньою, а не зафіксованою: її фіксація стабілізувала б внутрішнє зерно хешування та порядок ітерації словників середовища виконання гостьової мови і так приховала б плагін, чий власний вивід не відтворюваний, замість того щоб дати цьому проявитися як відмінний вивід. Плагін, результат якого залежить від ентропії, — це проблема детермінізму на рівні авторства, і ця конфігурація побудована так, щоб виявити її, а не замаскувати.

Розроблення для хоста: PDK. Автори плагінів не пишуть вручну ABI пам’яті Wasm. Aggrega постачає Plugin Development Kit трьома мовами — Go, Rust і TypeScript — тонкі обгортки, що надають типізовані вхід і вихід кожного сокета, тож автор пише звичайні функції. Інтерфейс function / with, описаний вище, — це те, чим сутність Aggregate або FeatureRecipe викликає плагін; PDK — це те, на основі чого автор плагіна його створює.

Де працює кожен сокет. Кожен сокет працює через той самий хост: лінтер публікації — в aggrega lint; ролі керування, провайдери рендерингу та кроки конвеєрів Recipe і FeatureRecipe — під час aggrega build; парсери — скрізь, де читається сторонній формат; імпортери — в aggrega import; а плагіни CLI — як команди верхнього рівня. Готовність кожного сокета див. у розділі Стан мови.

Які плагіни закріплено, а які обирає ваше середовище. Aggrega розділяє плагіни за тим, чи змінюють вони результат, який ви постачаєте. Плагіни, що формують результат, — провайдери рендерингу, плагіни керування, приєднані в ролі перетворення (label-transform, annotation-transform), і кроки конвеєрів FeatureRecipe та Recipe — закріплюються в lockfile релізу, коли ви виконуєте aggrega pull, і відтворюються байт-у-байт під час aggrega build і aggrega serve лише з цього lockfile. Два види не закріплюються, бо збірка щоразу читає кожен із них з того самого місця: провайдер рендерингу, що постачається всередині бінарного файлу компілятора, і провайдер або крок конвеєра, чию сутність Plugin створено в одному з ваших власних каталогів. Щоб змінити, який плагін, що формує результат, застосовується, потрібно виконати pull повторно; зміна конфігурації робочого простору після pull не змінює результат збірки до наступного pull. Плагіни-шлюзи — політики та лінтери — оцінюють збірку, не змінюючи її байтів, тому вони кешуються під час pull (щоб збірка могла запускати їх і офлайн; той, що міститься в бінарному файлі компілятора, або створений у вашому власному каталозі, натомість читається звідти), але не закріплюються: який шлюз запускається, обирає ваше середовище під час збірки, тож розподіл «дозвільний для розробки / суворий для CI» — це звичайний вибір конфігурації, а не повторний pull, і перемикання шлюзів ніколи не змінює результат, який видає успішна збірка. Plugins, що діють лише на вхідні дані авторингу, як-от імпортери та розширення CLI, не формують жодного результату збірки, тож не закріплюються й не входять до кешованого набору збірки.

2. Конвеєри Plugin для FeatureRecipe

FeatureRecipes пов’язують абстрактні операційні наміри (наприклад, підключення захисного проксі чи впровадження sidecar) з версіонованими конвеєрами плагінів WebAssembly (Wasm). Ops оголошує, що потрібно сутності Feature для конкретної цільової платформи провайдера; компілятор виконує оголошений конвеєр над плоским графом IR.

Це зв’язування має три наслідки для екосистеми:

  • Незалежна еволюція. Інфраструктурний словник розширюється через зовнішні плагіни Wasm без потреби в основному релізі компілятора Aggrega. Нові провайдери, нові sidecar і нові інтеграції безпеки постачаються як незалежні бінарні файли Wasm, сумісні зі стабільним ABI Wasm.
  • Семантичне версіонування. FeatureRecipes посилаються на плагіни Wasm за версією — точною (:1.0.0) або діапазоном зі знаком вставки (:^1.0.0, найвища сумісна з нею версія). З таким діапазоном Ops фіксує мажорну версію, отримуючи її мінорні та патч-релізи щоразу, коли lockfile повторно розв’язується за допомогою aggrega pull --upgrade.
  • Винесення складності. Генерація специфічних для постачальника CRD або складний рендеринг (специфічні для постачальника об’єкти політик, нативні ресурси маршрутизації провайдера) розміщуються в чистих плагінах Wasm, що працюють із плоским графом IR, а не пронизують оголошення схем чи логіку шаблонів у визначеннях компонентів.

Ланцюжки конвеєра — розділення відповідальності між плагінами. Конвеєр FeatureRecipe може послідовно поєднувати кілька плагінів Wasm, кожен з яких отримує від компілятора той самий контекст вузла IR. Стандартний шаблон розподіляє відповідальність так, щоб один плагін не ніс водночас і семантичного наміру функції, і фізичного механізму перехоплення трафіку конкретного цільового середовища.

Канонічний ланцюжок із двох плагінів виглядає так:

  • Конфігураційний плагін, що видає семантичні правила для функції (правила політик безпеки, шаблони аудиту, пороги обмеження частоти запитів). Він розуміє намір функції; він не розуміє інфраструктуру перехоплення трафіку цільового середовища.
  • Плагін маршрутизації, що видає фізичну конфігурацію mesh, яка переносить ці правила (CRD шлюзів, патчі впровадження sidecar, правила брандмауера). Він розуміє інфраструктуру цільового середовища; він не розуміє семантичного наміру функції.

Обидва плагіни послідовно отримують від компілятора той самий контекст вузла IR, тож вони чисто компонуються без прямого зв’язку між собою. Компілятор оркеструє конвеєр; плагіни несуть знання предметної області.

3. Перехоплення трафіку: ціль HTTPRoute

Модель розширюваності Aggrega орієнтується на стандарт HTTPRoute з Kubernetes Gateway API як на міжпровайдерний артефакт для перехоплення трафіку на рівні mesh. Стандартна бібліотека видає об’єкти HTTPRoute через сутність Feature core/http-route, чия сутність FeatureRecipe для helm рендерить один маршрут на кожен приєднаний компонент; цільові середовища, що споживають Gateway API, транслюють HTTPRoute у свої нативні інфраструктури.

4. Автономія Plugin: розв’язання міток

Коли плагіни Wasm генерують фізичні ресурси з графа IR, SRE потрібно простежити запущений Pod Kubernetes або хмарний ресурс до семантичного наміру розробника в сутності Aggregate. Модель розширюваності Aggrega повністю віддає цю трансляцію під контроль автора плагіна Wasm.

Компілятор передає повний словник labels графа IR у пісочницю Wasm без інтерпретації. Далі логіку відображення визначає автор плагіна — Platform Ops: передати всі мітки дослівно, відфільтрувати за певними доменними префіксами (*.aggrega.ai/*) або відобразити мітки графа безпосередньо в нативні схеми тегування провайдера (транслюючи мітку IR в AWS tags, Kubernetes annotations або хмарно-специфічний механізм метаданих). Компілятор не накладає жодних обмежень на те, як тегуються згенеровані артефакти.

Така автономія тримає доменно-специфічні знання — які мітки важливі для спостережуваності, які відображаються в нативні домовленості тегування, які є внутрішніми для платформи — у шарі плагінів Wasm, де екосистема розвивається незалежно від циклу релізів компілятора на Go.

5. Розширення CLI: команди часу виконання

Наведені вище сокети працюють всередині збірки — компілятор викликає їх під час розбору, змінення, валідації та рендерингу сутності Aggregate. Сокет розширень CLI відрізняється за своєю природою: він працює в терміналі, поза будь-якою збіркою, коли оператор вводить aggrega <command>. Саме так зростає набір команд aggrega без випуску ядра.

Що таке розширення CLI. Розширення CLI — це підключувана команда aggrega <command>, яку надає підписаний ізольований Wasm-плагін. Воно дотримується того самого підходу підключуваних компонентів, якими володіє гість, що й сокет рендерингу: доменна логіка повністю міститься в гостьовому модулі, а хост на Go не додає жодного коду для окремих команд. Щоб додати нову команду верхнього рівня, потрібні лише три речі — двійковий файл .wasm, одна сутність Plugin, що оголошує pluginType: cli (див. Plugin), і явний виклик aggrega plugin add cli. Хост дізнається про команду з самозвіту встановленого плагіна; жодна команда не вкомпільована у двійковий файл.

Чому сокет часу виконання може те, чого не може сокет збірки. Оскільки сокети часу компіляції працюють під час збірки, вони залишаються без привілеїв і детермінованими: Aggrega — це компілятор AOT (ahead-of-time), і той самий вхід завжди має давати той самий вихід (див. Архітектурні інваріанти). Тому плагін рендерингу чи політик не може звертатися до мережі, читати годинник або виводити дані в термінал — усе, що змінюється між запусками, порушило б цю гарантію. Розширення CLI працює після цієї межі та поза нею, і ним керує людина в командному рядку, а не детермінований конвеєр. Саме тому плагін CLI може потоково виводити стандартний вивід і стандартний потік помилок під час роботи та повертати код завершення процесу: немає артефакту збірки, побайтовій стабільності якого ці ефекти могли б загрожувати.

Встановлення, запуск і пошук. aggrega plugin add cli <query> шукає в налаштованому реєстрі відповідний плагін cli, перевіряє його за політикою довіри реєстру та встановлює як команду верхнього рівня — спершу виводячи оголошені можливості плагіна, щоб оператор підтвердив, що саме дозволено команді, ще до її встановлення. Після встановлення aggrega <command> запускає її, як будь-яку вбудовану команду. Плагін CLI оголошує свої команди та їхні прапорці у самозвіті describe(), і хост показує прапорці кожної команди в aggrega help <command> так само, як для вбудованої команди, тож оператор знаходить --flags встановленої команди тим самим способом. Щоб знайти команди для встановлення та вміст каталогу, aggrega search виконує запит до локального індексу налаштованих реєстрів — --kind plugin --plugin-type cli звужує результати до плагінів CLI, доступних для встановлення, а пошук без фільтра охоплює сутності каталогу; aggrega plugin list показує, що вже встановлено. Прапорці та формати виводу кожної команди описано на цих довідкових сторінках.

Модель можливостей. Розширення CLI починає з фіксованого базового набору, який отримує кожна команда без жодного оголошення та запиту:

Базова можливістьНадається
Вхідні аргументи командного рядкаЗавжди
Потоковий стандартний вивід і стандартний потік помилокЗавжди
Вихідний код завершення процесуЗавжди

Усе, що виходить за межі базового набору, вимкнено за замовчуванням. Плагін, якому потрібно більше, явно оголошує кожну додаткову можливість, і хост надає її лише після того, як покаже її під час встановлення для підтвердження оператором. Клас можливостей, доданий понад базовий набір, — доступ до середовища, файлової системи чи мережі, інтерактивне введення — надається за тим самим бар’єром «оголосити й підтвердити», тож команда ніколи не зможе непомітно отримати доступ, якого оператор не схвалив.

Вбудовані команди завжди мають пріоритет. Встановлений плагін ніколи не може затінити вбудовану команду. Захист зарезервованих імен на основі списку заборон охороняє вбудовані команди та набір імен, зарезервованих для вбудованих команд, а конфлікт відхиляється під час встановлення, а не дозволяє перевизначити базову поведінку. Набір команд, на який покладається оператор, залишається стабільним незалежно від того, що встановлено поверх нього.

6. Parser Plugins: читання сторонніх форматів

Компілятору регулярно доводиться читати текст у форматі, який створив не він, — модуль Terraform у HCL, файл конфігурації в TOML, маніфест у YAML чи JSON. Сокет парсерів надає цю здатність читання, не навчаючи ядро компілятора жодного конкретного формату. Парсер — це плагін без стану, що перетворює сторонній вихідний текст на структуроване дерево JSON: передайте йому байти файлу HCL, і він поверне той самий вміст як об’єкт JSON, який решта конвеєра вже вміє обходити. Будь-яка частина компілятора, якій треба прочитати формат, що він не розбирає нативно, запитує розібране дерево і працює з ним.

Формат — це можливість, а не функція компілятора. Парсер оголошує формати, які він обробляє, як можливості — parse:hcl, parse:toml тощо, — а хост обирає парсер за запитаним форматом, запускає його і повертає дерево. Це та сама модель підключуваних плагінів з оголошеними можливостями, що й у провайдерів рендерингу та плагінів CLI: ядро компілятора не містить вбудованого списку форматів, тож додати формат означає випустити новий плагін-парсер, а не випуск ядра. Парсери для HCL, TOML, YAML, JSON і JSON з коментарями постачаються у двійковому файлі як початковий набір; підприємство, якому потрібен інший формат, випускає плагін-парсер, що його оголошує.

Вибір формату декларативний і ніколи не вгадується. Хост ніколи не аналізує вміст файлу, щоб визначити, що це. Він обирає формат за оголошеними сигналами у фіксованому порядку пріоритету. Провайдер рендерингу може оголосити формат кожного файлу, який він створює, і хост беззастережно віддає перевагу цьому оголошеному виробником формату — провайдер, що записав байти, є авторитетом щодо того, як їх читати. Для файлу, який виробник не позначив, запасним варіантом є фіксована таблиця розширень файлів — .tf обирає HCL, .toml обирає TOML, .yaml обирає YAML, .json обирає JSON. Вибір за оголошеним форматом або фіксованим розширенням зберігає розбір детермінованим і зрозумілим: той самий вхід завжди потрапляє до того самого парсера, і оператор може визначити, який парсер запуститься, не знаючи байтів усередині файлу. Аналіз вмісту зробив би вибір залежним від корисного навантаження, і Aggrega цього не робить.

Парсер суто синтаксичний. Результат — це дерево JSON разом із діагностикою та, за бажанням, вихідними позиціями, з яких походить кожен вузол. Парсер не несе жодного значення Aggrega — він повідомляє, що текст говорить структурно, і нічого про те, що він означає як сутність Component, Recipe чи будь-яка інша. Перетворення розібраного дерева на сутності Aggrega — окреме завдання, яке розташоване деінше; єдине завдання парсера — точний переклад синтаксису в JSON. У тому самому дусі напрям читання односторонній: парсер читає формат у дерево, але не записує формат назад.

Споживач: політика над Terraform HCL. Політика етапу рендерингу, якій потрібно перевірити Terraform, що створює збірка, сама не вивчає HCL. Хост розбирає артефакт HCL через сокет парсерів і передає плагіну політики дерево JSON, яке той уже читає, тож політика міркує над структурованими даними в тій самій формі, яку отримує кожен інший сокет. Нові читачі сторонніх форматів компонуються так само — запитати в хоста дерево, потім працювати з JSON, — тож здатність компілятора розуміти формат зростає завдяки додаванню плагінів-парсерів, а не розростанню ядра.

7. Importer Plugins: створення чернеток авторських файлів зі сторонніх джерел

Команда рідко починає з чистого аркуша. Її агентна архітектура часто вже існує деінде — потік Langflow або Flowise, робочий процес n8n, застосунок Dify, MCP-сервери, з якими налаштовано клієнт, застосунок Compose, агенти, які оголошує конфігурація фреймворку. Сокет імпортера перетворює таке стороннє джерело на готовий старт для авторингу в Aggrega: він читає джерело й створює чернетки сутностей Aggregate і Component, а з конфігурації MCP, застосунку Compose або оголошеної конфігурації фреймворку — чернетку Release, щоб автор переглянув і завершив їх; так команда переносить в Aggrega те, що вже має, замість того щоб писати це заново вручну. Імпортер відображає значення — він читає, чим є вузол джерела, і пропонує сутність Aggrega, що його представляє, або залишає його всередині потоку, який несе чернетка платформи; компілятор непрозоро пропускає згенеровані сутності далі, так само як він залишається агностичним щодо того, що виробляє будь-який плагін.

Формат — це можливість, а не функція компілятора. Імпортер оголошує формати, які він обробляє, як можливості — import:langflow, import:flowise, import:n8n, import:mcp, import:compose, import:dify, import:crewai, import:langgraph, import:google-adk, import:agent-framework тощо, — а хост знаходить імпортер за запитаним форматом, запускає його й отримує назад сутності, чернетки яких він створив. Це та сама модель підключуваних плагінів з оголошеними можливостями, яку сокет парсера використовує з parse:<format>: ядро компілятора не містить вбудованого списку форматів для імпорту, тож підтримка нового формату — це випуск плагіна-імпортера, який його оголошує, а не випуск нової версії ядра.

Імпортер читає через сокет парсера; він не розбирає джерело повторно. Імпортерові потрібна структурована форма його джерела, але він не реалізує заново читання формату, який екосистема вже розбирає. Коли йому потрібне дерево, він просить хост запустити відповідний парсер — той, що каталог робочого простору надає для синтаксису джерела, або, якщо каталог жодного не надає, той, що містить сам компілятор, — через ту саму опосередковану хостом можливість розбору, яку використовує решта конвеєра, і працює з отриманим JSON-деревом. Читання (синтаксис у дерево) залишається завданням парсера; відображення (дерево в сутності Aggrega) — завданням імпортера. Два сокети поєднуються, не дублюючи один одного: імпортер додає логіку відображення для джерела й спирається на наявний парсер для роботи з байтами.

Формат розпізнається за тим, що оголошує його імпортер, і ніколи не вгадується. Імпорт може прямо назвати формат свого джерела. Якщо він цього не робить, формат розпізнається за сигнатурами, які кожен імпортер оголошує у своєму самозвіті і які записує його сутність Plugin: синтаксис, у якому читається джерело, імена файлів, до яких застосовується сигнатура, і шляхи, які розібране дерево повинно або не повинно містити. Хост не знає жодного власного формату. Він розбирає джерело парсером, який каталог робочого простору надає для кожного синтаксису, названого сигнатурою, — або власним парсером компілятора, якщо каталог жодного не надає, — обчислює оголошені предикати над отриманим деревом і читає джерело як формат того єдиного імпортера, чия сигнатура збігається. Оголошені сигнатури займають місце, яке для сокета парсера займає фіксована мапа розширень файлів, бо формати, які читає імпорт, можуть мати спільне розширення — експорт Langflow, експорт Flowise і робочий процес n8n є файлами JSON. Джерело, якому не відповідає жодна сигнатура, відхиляється із запитом формату й переліком форматів, які оголошують імпортери, — або, для теки, із запитом одного з її файлів окремо чи формату, імпортер якого оголошує шаблони файлів, і переліком лише цих форматів; джерело, якому відповідають сигнатури кількох форматів, відхиляється з їх переліком. Розпізнавання не читає нічого, крім джерела, і не звертається до мережі, тож розпізнавання нового формату — це оголошення, яке постачає новий імпортер, а не зміна хоста. Правила написання сигнатури описано в розділі Сокет імпортера.

Каталог читається через файли, які оголошує його імпортер. Джерело — це файл або каталог. Файл передається імпортерові цілком. Каталог читається як набір іменованих джерел — саме ті його файли, які вибирають шаблони файлів у сигнатурах імпортера, кожен названий своїм шляхом усередині каталогу, у відсортованому порядку, — і жоден інший файл каталогу не відкривається; посилання, яке вивело б читання за межі каталогу, відхиляється до того, як щось буде прочитано. Імпортер, що не оголошує шаблонів файлів, читає один файл і відхиляє каталог; каталог, у якому немає жодного файлу, вибраного шаблонами імпортера, також відхиляється. Імпортери компілятора для Langflow, Flowise, n8n, Dify і Agent Framework не оголошують жодних шаблонів, тож кожен читає один експортований файл потоку, робочого процесу чи застосунку або одного декларативного агента; його імпортер MCP оголошує імена файлів конфігурацій MCP-клієнтів, які він читає, тож каталог проєкту читається через конфігурації, що в ньому містяться; його імпортер Compose оголошує імена файлів, які Compose читає за замовчуванням, тож каталог проєкту читається через його файл Compose і файл перевизначень, який Compose накладає поверх нього; його імпортер CrewAI оголошує імена файлів, під якими проєкт CrewAI оголошує своїх агентів і завдання, тож каталог проєкту читається через ці оголошення, а його програма ніколи не читається; його імпортер LangGraph оголошує langgraph.json, тож каталог застосунку читається лише через його конфігурацію, а його код і файли середовища ніколи не читаються: файл середовища, названий конфігурацією, потрапляє до імпортера лише тоді, коли його передає with.sources підключення імпортера, і тоді лише заради імен змінних; а його імпортер Google ADK оголошує root_agent.yaml, тож каталог застосунку читається лише через конфігурацію його кореневого агента, конфігурації, названі його субагентами, потрапляють до імпортера лише тоді, коли їх передає with.sources підключення імпортера, а ні його код, ні його файл середовища ніколи не читаються.

Відображення детерміноване, має оцінку впевненості й зважується відносно вашого власного каталогу. Хост передає імпортерові подання сутностей Components, які містить власний каталог робочого простору, — каталог, з якого вибрано імпортер, — папки каталогу робочого простору або, якщо він не вказує жодної, знімок каталогу, який публікує його реєстр за замовчуванням, — причому сутності Components корпоративного каталогу так само, як і стандартної бібліотеки. Подання містить для кожної сутності Component її ім’я, версію та мітки, імена ключів, які оголошують її values і provides, і селектори її сокетів, але ніколи не значення, значення за замовчуванням чи секрет; для нього нічого не завантажується, окрім цього знімка, а його порядок фіксований, тож один каталог дає одне подання. Імпортер, побудований на пакеті імпортера Go PDK, — зокрема власні імпортери компілятора для Langflow, Flowise, n8n і Compose, — зважує кожен вузол джерела відносно цих Components і нічого іншого, з детермінованою моделлю впевненості без жодної ML-моделі, і записує рішення — кандидатів, яких він зважив, призначений рівень збігу і зроблений вибір — як підказки, які автор може прочитати й переглянути. Сутність Component, що з’являється в каталозі, стає кандидатом під час наступного імпорту без перезбирання будь-якого імпортера. За замовчуванням є лише підказки: імпорт пропонує, а автор вирішує. Збіг з високою впевненістю можна записати як посилання на наявний компонент каталогу замість щойно створеного тіла, але лише коли оператор це ввімкне — завжди як явну, оборотну пропозицію, яку схвалює автор, і ніколи як непомітне переписування. Оскільки оцінювання не використовує ні ML-моделі, ні пошуку під час виконання, те саме джерело, оцінене відносно того самого каталогу, завжди дає ті самі підказки.

Потік чернетково оформлюється як платформа, що його виконує. Потік Langflow, чатпотік Flowise і робочий процес n8n виконуються на платформі, і за замовчуванням імпорт створює чернетку цієї платформи, а не вузлів потоку: один екземпляр платформного компонента стандартної бібліотеки — core/ai-agent/langflow, core/ai-agent/flowise або core/ai-agent/n8n, — що несе потік у тому вигляді, у якому його експортовано, у своєму значенні flow_definition, яке платформа завантажує під час розгортання. Кожна частина потоку, яку приймає сокет платформи, — на платформах стандартної бібліотеки це модель, MCP-сервер або інший інструмент, доступний через HTTP, і векторне сховище, — стає окремою сутністю Component, на яку посилаються або яку створюють чернетково залежно від рішення зіставлення, і підключається до цього сокета в uses платформи. Отже, кожен виклик, який потік робить до моделі, інструмента чи сховища, — це з’єднання, яке оголошує сутність Aggregate: плагін керування, що оцінює граф, бачить його так само, як будь-яке інше ребро, а список дозволеного вихідного трафіку стандартної бібліотеки, який параметр attach_egress_allowlist приєднує до платформи, дозволяє платформі з’єднуватися лише з тим, до чого ведуть її з’єднання, з її власними подами та DNS кластера. Там, де формат це дозволяє, чернетка записує в перенесений потік те, що змушує потік звертатися до кожної частини через її з’єднання. Кожен інший вузол — агент, ланцюжок, тригер — залишається всередині перенесеного потоку й не стає сутністю Component, а його рішення фіксує кандидатів, з якими його порівнювали. Застосунок Dify чернетково оформлюється так само, у формі, якої набуває ціла інсталяція: один запис інсталяції Dify, яку збирає стандартна бібліотека, core/dify, що несе застосунок у своєму параметрі app_definition, причому інсталяція сама підключає свої з’єднання. Параметр layout приєднання імпортера вибирає чернетку: platform (за замовчуванням) або nodes, що створює кожен вузол джерела як окрему сутність Component, кожне ребро потоку — як з’єднання uses, і не переносить потоку. У розділі Платформа, що несе потік описано, які вузли стають частинами і куди кожен підключається.

Фреймворк, орієнтований на код, читається через його оголошену конфігурацію, а не через програму. CrewAI, LangGraph, Google ADK і Agent Framework зберігають поведінку застосунку в його програмі, а агентів, графи та моделі оголошують у конфігурації поруч із нею. Їхні імпортери читають лише ці оголошення — файли агентів і завдань проєкту CrewAI, langgraph.json застосунку LangGraph, конфігурації агентів застосунку Google ADK, декларативного агента Agent Framework — і створюють чернетку агента стандартної бібліотеки для цього фреймворку навколо програми, яку вони ніколи не відкривають, підключену до того, що називають оголошення: моделі, яку запитує агент, там, де сокет model агента її приймає, і сховища даних, у якому контрольна точка LangGraph зберігає стан. До MCP-сервера, який називає агент Agent Framework, звертається постачальник моделі як до розміщеного інструмента, тож чернетка називає його в коментарях і нічого до нього не підключає. Програма виконується в образі, який називає сутність Release. Те, що каже лише програма, — логіка завдання, інструмент, визначений у її коді, агент, якого будує її код, — називається в коментарях і рішеннях чернетки й не стає сутністю Component; перенесення цього у файли автора — робота автора, вручну або за допомогою ШІ-асистента, що працює від імені автора через aggrega mcp, який читає довідник, створює каркаси сутностей і перевіряє їх.

Те, що джерело повідомляє про виконання своїх частин, потрапляє в чернетку Release. Операційні вхідні дані надає сутність Release, тому імпортери MCP, Compose, CrewAI, LangGraph, Google ADK і Agent Framework створюють чернетку Release поруч із сутністю Aggregate, яку називає її spec.aggregate: сутність Release несе те, що повідомляє джерело, — командний рядок або адресу сервера, образ і порт універсального сервера, кінцеву точку моделі, — а в коментарях над кожним записом — те, що джерело повідомляє, але жоден ключ чернеткової сутності Component не приймає, як-от томи сервісу чи середовище конфігурації. Те, чого не повідомляє жодне джерело, — образ, що виконує програму фреймворку, облікові дані, які пред’являє з’єднання, metadata.environment і spec.manifest сутності Release, — називається в коментарі там, де йому місце, щоб його надав оператор, і збирання зупиняється, називаючи те з образу, середовища й маніфесту, що досі не задано. Чернетка платформи не створює сутності Release: коментар над екземпляром платформи називає те, що надає Release, — власні вхідні дані платформи, як-от образ, який вона виконує, або її обліковий запис власника, адресу кожного підключеного MCP-сервера та облікові дані, які пред’являє кожне з’єднання.

Значення облікових даних, яке містить джерело, переноситься як є, якщо не запитано його видалення. Імпортер знаходить у своєму джерелі кожне значення, що може містити облікові дані, кожне одного з класів: те, що формат позначає як облікові дані, член конфігурації MCP-сервера або вхідні дані, які формат позначає як не облікові дані, але які все одно можуть їх містити, як-от заголовки запиту. За замовчуванням жодне не записується порожнім: кожне значення, що щось містить, переноситься як є — у потоці чи застосунку, який несе платформа, або в чернетці Release — і називається в попередженні credential-carried за місцем, де воно розташоване, — його вузлом, сервером, сервісом чи агентом і його полем, — а не за значенням, разом зі значенням параметра, яке записує його порожнім. Параметр empty_credentials вмикає видалення клас за класом: marked записує порожнім те, що формат позначає як облікові дані, і кожен член конфігурації MCP-сервера, а all — також вхідні дані, позначені як не облікові дані; про кожне значення, записане порожнім, повідомляється через credential-emptied. Те, що чернетка записує, щоб потік досягав свого з’єднання, є підключенням і записується незалежно від параметра, а з’єднання в чернетці не несе облікових даних: сутність Release приєднує ті, які пред’являє кожне з’єднання. Файл, на який джерело лише вказує, як-от файл середовища, читається лише заради назв його змінних, якщо взагалі читається, а чернетка, створена вузол за вузлом, не читає жодного значення. Те, що лежить поза місцями, які знаходить імпортер, — код власного компонента, промпт — автор має переглянути перед тим, як ділитися чернеткою, як описано в розділі Значення облікових даних, які містить потік.

Команда, редактор і асистент виконують один і той самий імпорт. aggrega import <file or directory> виконує імпорт із термінала; редактор виконує ту саму операцію через запит aggrega/import своєї сесії, а ШІ-асистент — через інструмент import сервера aggrega mcp. Усі три вибирають імпортер однаково серед імпортерів, які містить каталог робочого простору, і базових імпортерів компілятора: той, який називає приєднання plugins.importer, якщо воно називає імпортер, що оголошує цей формат, а інакше — найвищу версію єдиного імпортера, який його оголошує; імпортери з двома різними назвами для одного формату, жоден з яких не приєднано, зупиняють імпорт із зазначенням обох, як описано в розділі Which importer turns a source into drafts (Який імпортер перетворює джерело на чернетки). Усі три повідомляють про рішення зіставлення поруч із чернетками. Команда виводить у стандартний потік помилок по одному рядку на кожен зіставлений вузол, називаючи вибрану для нього сутність Component або чернетку, чи на неї посилаються, чи її створено чернетково, рівень збігу та, якщо імпортер зважував кандидата, оцінку найкращого кандидата; редактор показує ті самі рядки, а результат сесії редактора й відповідь асистента містять кожне рішення повністю. Отже, автор бачить, де імпорт робив припущення, на будь-якій поверхні, що його виконала, не відкриваючи чернеток. --format явно називає формат джерела — наприклад, langflow, flowise, n8n, mcp, compose, dify, crewai, langgraph, google-adk або agent-framework — замість розпізнавання. Команда розміщує сутності та будь-які файли-заготовки, створені імпортом, під коренем робочого простору або під каталогом, який називає --output-dir; --dry-run робить усе, що робить команда, крім запису, повертаючи чернеткові файли як вміст і називаючи файл, для якого призначено кожен, тож автор може переглянути заготовку, перш ніж фіксувати щось у робочому дереві.

Базові імпортери. Базові імпортери, які постачає компілятор, читають такі формати, по одному імпортеру на кожен:

  • Langflow — потік, експортований із Langflow, створюється як чернетка платформи Langflow зі стандартної бібліотеки, що містить цей потік, а кожну його частину, яку приймає сокет, під’єднано до цього сокета.
  • Flowise — chatflow або agentflow, експортований із Flowise, створюється як чернетка платформи Flowise зі стандартної бібліотеки, що його містить, а кожну його частину, яку приймає сокет, під’єднано до цього сокета.
  • n8n — робочий процес, експортований із n8n, створюється як чернетка платформи n8n зі стандартної бібліотеки, що його містить, а кожну його частину, яку приймає сокет, під’єднано до цього сокета.
  • Dify — застосунок, експортований із Dify, створюється як чернетка інсталяції Dify, яку збирає стандартна бібліотека, що містить цей застосунок, а моделі, інструменти та бази знань, які він називає, повідомляються як налаштовані всередині Dify.
  • MCP — конфігурація MCP-клієнта або опис сервера з реєстру MCP; кожен сервер створюється як чернетка екземпляра інструмента MCP зі стандартної бібліотеки, разом із Release, що містить командний рядок, адресу або образ кожного сервера.
  • Compose — інфраструктурний формат; кожен сервіс застосунку Compose створюється як чернетка сутності Component каталогу, якій відповідає його образ, — через таблицю, яку містить імпортер і яку генерують зі сутностей Recipes і Components стандартного каталогу для Compose під час його збирання, — або як універсальний сервер, що запускає його образ, разом із Release, що містить образ і порт кожного універсального сервера, а в коментарях — порти, томи та середовище, які оголошує кожен сервіс.
  • CrewAI — агенти, яких проєкт CrewAI оголошує у своїх конфігураційних файлах; кожен створюється як чернетка агента CrewAI зі стандартної бібліотеки, що містить його роль, мету та передісторію і під’єднаний до моделі, яку він називає, а завдання та інструменти проєкту повідомляються як належні його програмі, саму програму ніколи не читають, і Release залишає образ, що її запускає, для визначення оператором.
  • LangGraph — графи, які оголошує конфігурація застосунку LangGraph; кожен створюється як чернетка агента LangGraph зі стандартної бібліотеки, що містить шлях імпорту його графа і під’єднаний до сховища даних, у якому його checkpointer зберігає стан, разом із Release, що в коментарі зазначає середовище, оголошене конфігурацією, а код графів ніколи не читають.
  • Google ADK — дерева агентів, які оголошують конфігурації агентів застосунку Google ADK; кожне створюється як чернетка агента ADK зі стандартної бібліотеки, під’єднаного до моделі, яку воно називає, там, де ADK надсилає запити цієї моделі до Gemini API, а модель, до якої звертаються будь-яким іншим способом — скажімо, через рядок моделі LiteLLM, — називається в коментарі, а її під’єднання залишається авторові, разом із Release, що залишає образ, який запускає застосунок, для визначення оператором, а код застосунку ніколи не читають.
  • Agent Framework — декларативний агент Agent Framework, створюється як чернетка агента Agent Framework зі стандартної бібліотеки, під’єднаного до моделі OpenAI, яку він називає, причому кожен MCP-сервер, який він називає, записується в коментарях, оскільки постачальник моделі звертається до нього як до розміщеного інструмента, разом із Release, що містить кінцеву точку моделі та, у коментарі, адресу кожного сервера, а код застосунку ніколи не читають.

Це такі самі плагіни-імпортери, як і будь-які інші, — інтелектуальна логіка зіставлення, специфічна для формату, міститься в них, а не в ядрі, — зібрані з вихідного коду компілятора й опубліковані з кожним випуском компілятора у версії цього випуску. Жоден не вкомпільовано у двійковий файл: двійковий файл містить сутність Plugin кожного з них і дайджест єдиного модуля, який він приймає, тож кожен обслуговує свій формат у кожному робочому просторі без запису в каталозі. Перший імпорт, якому потрібен імпортер, відсутній на машині, завантажує його з реєстру робочого простору за замовчуванням, перевіряє на відповідність цьому дайджесту, верифікує так, як pull верифікує завантажений плагін, — його підпис згідно з політикою довіри цього реєстру та хост-функції, які він використовує, — і зберігає в кеші вмісту робочого простору; кожен наступний імпорт читає його звідти, не звертаючись заради нього до мережі. Імпорт не закріплює жодного імпортера: для нього більше нічого не записується — ні запису в lock-файлі, ні запису про довірені плагіни, — жоден pull не кешує його і жодне збирання його не читає. Модуль, що не проходить верифікацію, відхиляється, і нічого не зберігається. Якщо модуль неможливо завантажити — робочий простір офлайн, його реєстр недоступний або реєстр його не містить, — імпорт зупиняється із зазначенням імпортера, його версії та того, що розміщує його модуль на машині. Вибір лишається за робочим простором: імпортер, який його каталог містить під іншою назвою для одного з цих форматів, запускається там, де його називає прив’язка plugins.importer, а імпортер із тією самою назвою і версією, що й базовий імпортер, запускається замість нього.

Початкове наповнення та розширення каталогу

Каталог не обов’язково будувати з нуля. Більша частина роботи з початкового наповнення Recipes і плагінів для нового середовища — це створення заготовок і повторне використання, а не написання кожного бінарного файлу вручну.

Імпорт стороннього джерела в чернетки авторських файлів. aggrega import <file or directory> читає декларативне джерело визначення агентів — потік Langflow або Flowise, робочий процес n8n або конфігурацію клієнта MCP чи опис сервера з реєстру MCP — застосунок Compose, застосунок Dify, агентів, яких оголошує проєкт CrewAI, графи, які оголошує конфігурація застосунку LangGraph, агентів, яких оголошують конфігурації агентів застосунку Google ADK, або декларативного агента Agent Framework, і створює першу чернетку YAML для Aggregate і Component, а з джерела MCP, Compose, CrewAI, LangGraph, Google ADK або Agent Framework — ще й чернетку Release, яку автор перегляне та завершить, тож команда переносить уже наявне, а не створює його заново вручну. Для кожного вузла потоку та кожного сервісу застосунку Compose він оцінює Components власного каталогу робочого простору — як корпоративного каталогу, так і стандартної бібліотеки — за допомогою детермінованої моделі впевненості без використання мовних моделей і записує рішення — кандидатів, яких він зважив, присвоєний рівень і зроблений вибір — як підказки для перегляду, про які повідомляють і команда, і редактор, і асистент; збіг із високою впевненістю можна записати як посилання на каталог, коли оператор це ввімкне, — завжди як явну оборотну пропозицію, яку схвалює автор, а не як непомітне переписування. Кожна сутність Component, яку отримує каталог, стає кандидатом, якого зважить наступний імпорт. Логіка зіставлення, специфічна для формату, міститься в плагіні-імпортері: власні імпортери компілятора для Langflow, Flowise, n8n, MCP, Compose, Dify, CrewAI, LangGraph, Google ADK і Agent Framework обслуговують ці формати в кожному робочому просторі, завантажуючись і перевіряючись під час першого використання, а каталог додає формат, містячи плагін-імпортер, який його оголошує. Джерело-каталог читається за шаблонами файлів, які оголошує його імпортер; імпортери Langflow, Flowise, n8n, Dify і Agent Framework не оголошують жодного, і кожен читає один експортований файл або декларативного агента, тоді як імпортер MCP читає конфігурації клієнтів, що містяться в каталозі, імпортер Compose — його файли Compose, об’єднані так, як їх об’єднує Compose, імпортер CrewAI — оголошення проєкту, але ніколи не його програму, імпортер LangGraph — конфігурацію застосунку, але ніколи не його код чи файл середовища — назви з якого він читає лише тоді, коли його приєднання передає йому цей файл, — а імпортер Google ADK — кореневу конфігурацію агента застосунку, але ніколи не його код чи файл середовища, а конфігурації його субагентів читає тоді, коли їх передає приєднання, — це конфігурація, яку ADK позначає як експериментальну, агенти якої типово використовують модель Gemini, а до моделей інших постачальників звертаються за назвою через власні класи ADK або через рядок моделі LiteLLM.

Більшість роботи з плагінами — це шаблони, а не скомпільований код. Значна частка функцій лише додає статичний sidecar, змінну середовища чи мітку — звичайний JSONPatch без умовної логіки. Один конфігурований плагін-патчер, написаний один раз так, щоб приймати декларативний шаблон JSONPatch як вхідні дані with, може покрити цей поширений випадок без окремого скомпільованого бінарного файлу для кожної функції: автор пише шаблон, а для багатьох цілей у стилі CRD достатньо самого шаблону valuesMapping (часто з посиланнями на спільні фрагменти в записі MappingLibrary). Спеціально написані плагіни PDK призначені для справді умовної решти.

Орієнтування на усталені інструменти. Пишучи нову логіку плагіна, автори можуть звертатися до публічно задокументованих форм виводу усталених інструментів з відкритим кодом — структури CRD, патчів або шаблонів, які ці інструменти, як відомо, генерують, — як до орієнтира для цільової форми, яку має створити новий плагін, з дотриманням ліцензії кожного проєкту. Вебхуки для впровадження sidecar, бібліотеки конструкцій вищого рівня, генератори CRD для операторів і каталоги трейтів чи композицій — усі публікують структури виводу, що близько відповідають тому, що має генерувати порівнянний FeatureRecipe чи плагін. Мета — відповідати добре зрозумілому контракту виводу, а не копіювати реалізацію будь-якого проєкту.