Расширяемость
Расширяемость экосистемы и ограничители компилятора
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) | До расширения аннотаций, построение топологии, статический анализ или стадия рендеринга | Выполняет роли управления в конвейере сборки. До расширения аннотаций внедряет аннотации в разрешённые компоненты, а при построении топологии автоматически помечает узлы метками соответствия или окружения (оператор явно включает каждую из этих ролей). При статическом анализе или на стадии рендеринга действует как «громкий ограничитель»: проверяет рёбра графа, пути и метки — или отрендеренные артефакты — на соответствие границам безопасности. Что он может выдавать, определяет роль, к которой он подключён, а не его вид. | До расширения аннотаций — внедрения аннотаций. При построении топологии — массив JSONPatch, нацеленных на metadata.labels. При статическом анализе или на стадии рендеринга — вердикты с серьёзностью halt, warn или info (политика Rego собирает их в deny, warn и audit); halt останавливает сборку. |
Линтер (linter) | Вне основного процесса | Необязательные проверки FinOps или гигиены (например, оценка облачных затрат по .infra) и дисциплина при публикации. | Строки предупреждений или фатальные остановки. |
Расширение CLI (cli) | Время выполнения (aggrega <command>) | Подключаемая команда верхнего уровня, предоставляемая подписанным изолированным плагином, без какого-либо кода на Go для отдельной команды в хосте. | Потоковые стандартный вывод и вывод ошибок, а также код завершения гостевого модуля. |
Парсер (parser) | По запросу, везде, где читается чужой формат | Преобразует исходный текст в чужом формате (HCL, TOML, YAML, JSON, JSON с комментариями) в каноническое дерево JSON. | tree и diagnostics, а также необязательные spans исходника. |
Импортёр (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-чистоты: хост отказывается предоставлять плагину любую возможность доступа во время выполнения — ни сети, ни файловой системы, ни системных часов, ни окружения, ни стандартного ввода-вывода, — поэтому вызов, который воспользовался бы такой возможностью, завершается ошибкой, а плагин, импортирующий из интерфейса хоста, которого хост не предоставляет, отклоняется при загрузке. Плагин, который не может обратиться к сети или прочитать часы, не может нарушить гарантию компилятора с предварительной компиляцией, что одинаковый вход даёт одинаковый выход. Среды выполнения языков, которым нужны несколько безобидных импортов при запуске, работают с конфигурацией этих импортов, в которой возможности запрещены: хост фиксирует наблюдаемые системные часы, предоставляет настоящую энтропию, отбрасывает стандартный ввод-вывод и не даёт доступа к файловой системе, аргументам или окружению — поэтому плагин не может достичь ни одной возможности хоста, меняющейся от сборки к сборке. Энтропия намеренно оставлена настоящей, а не зафиксированной: её фиксация стабилизировала бы внутреннее начальное значение хеша и порядок обхода словарей в среде выполнения гостевого языка и тем самым скрыла бы плагин, чей собственный вывод не воспроизводим, вместо того чтобы это проявилось как различающийся вывод. Плагин, результат которого зависит от энтропии, — это проблема детерминизма на уровне авторинга, и эта конфигурация построена так, чтобы выявлять её, а не маскировать.
Разработка для хоста: 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 — закрепляются в lock-файле релиза при выполнении aggrega pull и воспроизводятся побайтово идентично при aggrega build и aggrega serve только по этому lock-файлу. Два вида не закрепляются, потому что сборка каждый раз читает их из одного и того же места: провайдер рендеринга, поставляемый внутри бинарного файла компилятора, и провайдер или шаг конвейера, чья сущность Plugin описана в одном из ваших собственных каталогов. Чтобы изменить применяемый плагин, формирующий результат, нужно выполнить pull повторно; изменение конфигурации рабочего пространства после pull не меняет результат сборки до следующего pull. Плагины-шлюзы — политики и линтеры — оценивают сборку, не изменяя её байтов, поэтому они кешируются при pull (чтобы сборка могла запускать их офлайн; плагин, который несёт бинарный файл компилятора, или плагин, описанный в вашем собственном каталоге, читается оттуда), но не закрепляются: какой шлюз запускается, выбирает ваше окружение во время сборки, так что разделение «мягко для разработки / строго для CI» — обычный выбор конфигурации, а не повторный pull, и смена шлюзов никогда не меняет результат, который выдаёт успешная сборка. Plugins, работающие только с исходными файлами описания, например импортёры и расширения CLI, не формируют результат сборки и не закрепляются и не входят в кешируемый набор сборки.
2. Конвейеры Plugin для FeatureRecipe
FeatureRecipes связывают абстрактные эксплуатационные намерения (например, подключение прокси безопасности или внедрение sidecar-контейнера) с версионированными конвейерами плагинов WebAssembly (Wasm). Команда эксплуатации объявляет, что требуется сущности Feature на конкретной целевой платформе провайдера; компилятор выполняет объявленный конвейер над плоским графом IR.
Эта привязка имеет три следствия для экосистемы:
- Независимое развитие. Инфраструктурный словарь расширяется за счёт внешних плагинов Wasm, не требуя выпуска новой версии ядра компилятора Aggrega. Новые провайдеры, новые sidecar-контейнеры и новые интеграции безопасности поставляются как независимые двоичные файлы Wasm, использующие стабильный Wasm ABI.
- Семантическое версионирование. FeatureRecipes ссылаются на плагины Wasm по версии — точной (
:1.0.0) или по диапазону с кареткой (:^1.0.0, наибольшая совместимая с ней версия). С диапазоном с кареткой команда эксплуатации фиксирует мажорную версию, получая её минорные и патч-выпуски всякий раз, когда lock-файл заново разрешается с помощью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-инженерам нужно проследить путь от работающего пода Kubernetes или облачного ресурса обратно к семантическому намерению разработчика в сущности Aggregate. Модель расширяемости Aggrega полностью передаёт это преобразование под контроль автора плагина Wasm.
Компилятор передаёт полный словарь labels графа IR в песочницу Wasm без интерпретации. Дальше логику сопоставления определяет автор плагина — команда Platform Ops: передать все метки как есть, отфильтровать по определённым доменным префиксам (*.aggrega.ai/*) или напрямую сопоставить метки графа с нативными схемами тегирования провайдера (преобразовав метку IR в tags AWS, annotations Kubernetes или облачно-специфичный механизм метаданных). Компилятор не накладывает никаких ограничений на тегирование генерируемых артефактов.
Такая автономия удерживает предметно-специфичную логику — какие метки важны для наблюдаемости, какие соответствуют нативным соглашениям о тегировании, какие являются внутренними для платформы — внутри слоя плагинов 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 — это компилятор, работающий заранее (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 корпоративного каталога передаются точно так же, как Components стандартной библиотеки. Представление содержит для каждой сущности Component имя, версию и метки, имена ключей, которые объявляют её values и provides, и селекторы её сокетов, но никогда — значение, значение по умолчанию или секрет; для него ничего не загружается, кроме этого снимка, и его порядок фиксирован, так что один каталог даёт одно представление. Импортёр, построенный на пакете импортёров Go PDK, — в том числе собственные импортёры компилятора для Langflow, Flowise, n8n и Compose, — сопоставляет каждый узел источника с этими Components и ни с чем другим, используя детерминированную модель уверенности без ИИ-модели, и записывает решение — рассмотренных кандидатов, присвоенный уровень совпадения и сделанный выбор — в виде проверяемых подсказок, которые автор может прочитать и изменить. Сущность Component, добавленная в каталог, становится кандидатом при следующем импорте без пересборки импортёра. По умолчанию создаются только подсказки: импорт предлагает, автор решает. Совпадение с высокой уверенностью можно записать как ссылку на существующий компонент каталога вместо заново созданного тела, но только если оператор это включит, — всегда как явное, обратимое предложение, которое утверждает автор, и никогда как незаметная перезапись. Поскольку оценка не использует ни ИИ-модели, ни поиска во время выполнения, один и тот же источник, оцениваемый по одному и тому же каталогу, всегда даёт одни и те же подсказки.
Поток оформляется в черновике как платформа, которая его выполняет. Поток Langflow, чат-поток Flowise и рабочий процесс n8n выполняются на платформе, и по умолчанию импорт создаёт черновик этой платформы, а не узлов потока: один экземпляр платформенной сущности Component из стандартной библиотеки — 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 или плагин. Цель — соответствовать хорошо понятному контракту вывода, а не копировать реализацию какого-либо проекта.