Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Схема Aggrega Core (Plugin)

Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.

Идентификатор схемы: https://aggrega.ai/schemas/plugin-v1beta1.schema.json

Плагин Wasm: модуль WebAssembly, опубликованный в реестре OCI и идентифицируемый по своему metadata.pluginType — сокету, который он реализует, — и своему голому metadata.name; он объявляет целевую версию ABI, необязательный указатель на подпись и необязательный блок runtime. Сущность и её .wasm публикуются как один манифест OCI с тегом metadata.version: YAML сущности — как config blob манифеста, .wasm — как встроенный слой, подписанный один раз. Идентичность — это координата metadata.pluginType/metadata.name плюс metadata.version сущности; расположение .wasm выводится из этой координаты и настроенного реестра, а разрешённый дайджест содержимого хранится в lock-файле, а не в сущности. Lock-файл фиксирует дайджест, а политика доверия для каждого реестра проверяет подпись артефакта при загрузке (pull). Компилятор не интерпретирует поведение плагина — он маршрутизирует ссылку; байты исполняет среда выполнения WebAssembly.

Руководство по созданию сущностей Plugin см. в справочнике по созданию Plugin; на этой странице описана структурная схема, которую описывает этот справочник.

Тип верхнего уровня: object

Свойства

СвойствоТипОбязательноОписание
apiVersionconst “aggrega.ai/v1beta1”даКонстанта: "aggrega.ai/v1beta1"
kindconst “Plugin”даКонстанта: "Plugin"
metadataobjectда
specobjectдаВерсия ABI, на которую рассчитан плагин, необязательный указатель на подпись и необязательный блок runtime. Расположение .wasm плагина выводится из идентичности плагина — его metadata.pluginType (сокета) и его простого metadata.name — и настроенного реестра; в spec оно не хранится.

Дополнительные свойства не допускаются.

plugin.metadata

СвойствоТипОбязательноОписание
namestringдаНе менее 1 символа.
versionstringдаВерсия сущности Plugin в строгом формате Semantic Versioning (например, 1.0.0). Шаблон: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$.
pluginTypestring (enum)даТип сокета, который реализует этот плагин. Плагин реализует ровно один тип сокета из таксономии типов плагинов, распознаваемой средой выполнения: provider (преобразует узлы IR в нативные артефакты провайдера), linter (проверяет авторское содержимое и выдаёт диагностические сообщения), pipeline-step (шаг в pipeline: сущности FeatureRecipe или Recipe, который применяет патчи к набору отрисованных документов), governance (выполняет роли управления в конвейере сборки — преобразует метки узлов при построении топологии либо выносит вердикт «принять/отклонить» по графу IR на этапе статического анализа или по отрисованным артефактам на этапе отрисовки; что он может выдавать, определяет роль, к которой он подключён, а не его вид), cli (добавляет подкоманду времени выполнения aggrega <cmd>, которую оператор вызывает в командной строке, — сокет времени выполнения, отличный от сокетов отрисовки и конвейера времени компиляции), parser (превращает исходный текст на стороннем языке в каноническое структурированное дерево, чтобы потребитель читал дерево, не имея собственного парсера языка; обрабатываемые форматы объявляются как возможности parse:<format>), importer (превращает сторонний источник с описанием инфраструктуры или агентов в черновые авторские файлы Aggrega; обрабатываемые форматы объявляются как возможности import:<format>). Допустимые значения: "provider", "linter", "pipeline-step", "governance", "cli", "parser", "importer"
descriptionstringнетЧто представляет собой эта сущность и для чего она нужна — для того, кто решает, использовать ли её. Начните с предложения, называющего её, затем добавьте то, что читателю нужно, чтобы выбрать её и правильно использовать: чего она ожидает от сборки, которая её запускает, и что в её поведении может оказаться неожиданным. Обычная длина — короткий абзац.
maintainersobject[]нетСписок сопровождающих, которым принадлежит эта сущность.
licensestringнетИдентификатор SPDX лицензии программного обеспечения, которое описывает эта сущность, например MIT или AGPL-3.0. Он фиксирует условия этого программного обеспечения, а не условия данного файла.
repositorystringнетURL Git-репозитория, в котором находятся исходные файлы.
homestringнетURL домашней страницы, вики или документации этой сущности.
keywordsstring[]нетСписок описательных ключевых слов для удобства поиска в интерфейсе.

Дополнительные свойства не допускаются.

plugin.metadata.maintainers[]
СвойствоТипОбязательноОписание
namestringда
emailstringнет
urlstringнет

Дополнительные свойства не допускаются.

plugin.spec

Версия ABI, на которую рассчитан плагин, необязательный указатель на подпись и необязательный блок runtime. Расположение .wasm плагина выводится из идентичности плагина — его metadata.pluginType (сокета) и его простого metadata.name — и настроенного реестра; в spec оно не хранится.

СвойствоТипОбязательноОписание
abiVersionstring (enum)даВерсия ABI взаимодействия хоста и гостя, на которую рассчитан плагин. v1beta1 — единственное допустимое значение; сущность Plugin, объявляющая версию ABI, которую этот компилятор больше не поддерживает, отклоняется с указанием версии, под которую следует пересобрать плагин. Допустимые значения: "v1beta1"
signatureobjectнетНеобязательный описательный указатель на прикреплённую подпись плагина. Этот блок служит только документацией — он сообщает читателям каталога, где находится подпись и как она была создана; сам он не допускает и не блокирует плагин. Применяемая проверка — политика доверия конкретного реестра, выполняемая при загрузке (pull): подпись извлекается как OCI referrer, проверяется по доверенным идентичностям реестра или закреплённому ключу и записывается в lock-файл как проверенный факт. Реестр, требующий подписей, прерывает загрузку, если обязательная подпись отсутствует, не является доверенной или недействительна.
runtimeobjectнетНеобязательные ограничения выполнения, которые хост применяет при загрузке и запуске плагина. Исходящий сетевой доступ не является авторским полем: плагин никогда не обращается к сети во время сборки (граница ahead-of-time), поэтому поля со списком разрешённых хостов здесь нет.
exportsobject[]нетЭкспорты, которые предоставляет этот плагин, каждый со своей объявленной возможностью. Экспорт — это одна именованная точка входа, которую вызывает хост (например, render_node, lint_naming, step); блок возможностей экспорта — авторское утверждение о том, что делает этот экспорт, и хост сверяет его с самоотчётом плагина при публикации и при загрузке. Записи сохраняют авторский порядок. Отсутствие поля означает, что авторская поверхность экспортов не объявлена.
commandsobject[]нетУправляется машиной, не заполняйте вручную: записывается командой aggrega plugin sync (или aggrega plugin gen-catalog) из самоотчёта плагина. Глаголы верхнего уровня aggrega <command>, которые добавляет CLI-плагин, считываются из самоотчёта плагина и записываются здесь в порядке, объявленном в самоотчёте, поэтому набор команд, устанавливаемый CLI-плагином, можно прочитать из сущности, не загружая плагин. Плагин, не являющийся CLI-плагином, не добавляет команд и записывает пустой список. Хост устанавливает ровно этот набор; записанный набор, расходящийся с самоотчётом плагина, вызывает остановку при загрузке, а публикация отклоняет набор, не согласованный с бинарным файлом, и предлагает автору записать его заново.
providerobjectнетБлок сокета провайдера для плагина pluginType: provider: обслуживаемые им возможности, способ трансляции вида aggrega.ai/v1beta1 Workload, считываемые им нативные аннотации платформы и его контракт поведения отрисовки. Присутствует только у плагинов, отрисовывающих для провайдера; отсутствует у всех прочих типов плагинов.
pipelineStepobjectнетБлок шага конвейера для плагина pluginType: pipeline-step: возможности провайдера, с которыми совместим его шаг. Присутствует только у плагинов pipeline-step; отсутствует у всех прочих типов плагинов.
parserobjectнетБлок парсера для плагина pluginType: parser: исходные форматы, которые он превращает в каноническое структурированное дерево. Присутствует только у плагинов-парсеров; отсутствует у всех прочих типов плагинов.
importerobjectнетБлок импортёра для плагина pluginType: importer: сторонние исходные форматы, которые он превращает в черновые авторские файлы Aggrega, и сигнатуры, по которым распознаётся источник этих форматов. Присутствует только у плагинов-импортёров; отсутствует у всех прочих типов плагинов.

Дополнительные свойства не допускаются.

plugin.spec.signature

Необязательный описательный указатель на прикреплённую подпись плагина. Этот блок служит только документацией — он сообщает читателям каталога, где находится подпись и как она была создана; сам он не допускает и не блокирует плагин. Применяемая проверка — политика доверия конкретного реестра, выполняемая при загрузке (pull): подпись извлекается как OCI referrer, проверяется по доверенным идентичностям реестра или закреплённому ключу и записывается в lock-файл как проверенный факт. Реестр, требующий подписей, прерывает загрузку, если обязательная подпись отсутствует, не является доверенной или недействительна.

СвойствоТипОбязательноОписание
typeconst “sigstore-cosign”даСхема подписи. sigstore-cosign — поддерживаемая схема. Константа: "sigstore-cosign"
signatureRefstringнетСсылка OCI referrer на прикреплённый пакет подписи — для документации и обнаружения. Отсутствует, если подпись обнаруживается перечислением referrer при загрузке, а не закреплена здесь.
publicKeyRefstringнетУказатель на открытый ключ, которым создана подпись, — для подписи с ключом. Отсутствие поля означает бесключевую подпись (на основе идентичности OIDC), проверяемую по доверенным идентичностям реестра.

Дополнительные свойства не допускаются.

plugin.spec.runtime

Необязательные ограничения выполнения, которые хост применяет при загрузке и запуске плагина. Исходящий сетевой доступ не является авторским полем: плагин никогда не обращается к сети во время сборки (граница ahead-of-time), поэтому поля со списком разрешённых хостов здесь нет.

СвойствоТипОбязательноОписание
maxMemoryPagesintegerнетОграничивает линейную память плагина в страницах Wasm (64 KiB на страницу). Ноль или отсутствие поля применяет ограничение платформы по умолчанию, поэтому загрузка никогда не бывает неограниченной; присоединение, которому нужно больше, повышает это значение. Минимум: 0.
timeoutMsintegerнетОграничивает время выполнения собственного кода плагина за один вызов, в миллисекундах, не считая времени, проведённого внутри вызываемых им функций хоста. В Linux измеряется процессорное время, поэтому время ожидания процессора на загруженной машине не учитывается; в других системах измеряется прошедшее время. Первый вызов только что загруженного плагина учитывает также собственный запуск плагина. Ноль или отсутствие поля применяет ограничение платформы по умолчанию, поэтому вызов никогда не становится неотменяемым; присоединение, которое выполняется дольше, повышает это значение. Минимум: 0.
hostFunctionsstring[]нетУправляется машиной, не заполняйте вручную: функции хоста, которые импортирует плагин, считываются из секции импорта .wasm командой aggrega plugin sync (или aggrega plugin gen-catalog) и записываются здесь в каноническом виде (отсортированными, без дубликатов). Публикация заново выводит их из двоичного файла и отклоняет сущность, запись которой отличается; загрузка из реестра снова выводит и проверяет их. Хост регистрирует ровно этот выведенный набор и проверяет каждую запись по курируемому списку разрешённых.
configKVmap of stringнетСпецифичная для Plugin конфигурация, которую среда выполнения передаёт плагину при запуске, в виде пар «ключ — значение» из строк. Записи сохраняют порядок, заданный автором, поэтому выводимая запись побайтово идентична между запусками. Если поле отсутствует, действует пустая конфигурация среды выполнения по умолчанию.

Дополнительные свойства не допускаются.

plugin.spec.exports[]
СвойствоТипОбязательноОписание
namestringдаИмя экспорта в ABI — имя, по которому хост выполняет диспетчеризацию (например, render_node, lint_naming, step). Длина не менее 1 символа.
operatesstring (enum)нетОперация конвейера, которую выполняет этот экспорт: patch (изменить существующий отрисованный документ) или emit (добавить новый документ). Отсутствие поля не заявляет никакой операции. Допустимые значения: "patch", "emit"
scopestring (enum)нетКорень документов, с которым работает этот экспорт: own (собственные отрисованные документы узла) или host (документы компонента, к которому подключён FeatureRecipe уровня компонента). Отсутствие поля не заявляет никакой области. Допустимые значения: "own", "host"
selectorstringнетПроизвольное понятное человеку описание того, на что действует экспорт (например, workloads carrying a pod template). Документация для читателей каталога; компилятор его не интерпретирует.

Дополнительные свойства не допускаются.

plugin.spec.commands[]
СвойствоТипОбязательноОписание
namestringдаГлагол команды, который регистрирует хост, — токен aggrega <name>, который вызывает оператор, и дискриминатор, передаваемый хостом плагину при вызове, чтобы один плагин, обслуживающий несколько команд, мог выбрать обработку по вызванной команде. Длина не менее 1 символа.
descriptionstringнетОднострочная краткая справка по команде, отображаемая в списке команд и в выводе справки. Только документация; хост на неё не реагирует.
flagsobject[]нетФлаги команды в объявленном порядке. Каждая запись добавляет один флаг, который хост регистрирует для команды, чтобы aggrega help отображал его так же, как флаг встроенной команды. У команды без флагов список пуст. В пределах команды каждое имя флага и каждое сокращение встречается один раз, и ни один флаг не повторяет флаг, который уже есть у каждой команды aggrega, — --help, -h и глобальные флаги; хост проверяет это при добавлении команд плагина, и плагин с ошибочными объявлениями не добавляется, а выводится предупреждение.

Дополнительные свойства не допускаются.

plugin.spec.commands[].flags[]
СвойствоТипОбязательноОписание
namestringдаДлинное имя флага — токен —name, который оператор передаёт в командной строке. Его должен указывать каждый объявленный флаг. Длина не менее 1 символа.
shorthandstringнетНеобязательный короткий псевдоним флага — форма -x, которую оператор может передать вместо длинного имени, — в виде одной буквы или цифры ASCII. Отсутствие поля означает, что у флага нет короткого псевдонима. Шаблон: ^[A-Za-z0-9]$.
descriptionstringнетОднострочная справка по флагу, отображаемая в выводе справки команды. Это необязательная документация; хост её не проверяет и на неё не реагирует.
typestring (enum)нетТип значения флага — string, bool или int — и вид флага, в котором его отображает справка. При отсутствии поля флаг отображается как строковый. Допустимые значения: "string", "bool", "int"
defaultstringнетЗначение флага по умолчанию, если оператор его не передал, записанное в виде строки. Для флага bool или int это значение соответствующего типа. Отсутствие поля означает, что флаг не объявляет значения по умолчанию.

Дополнительные свойства не допускаются.

plugin.spec.provider

Блок сокета провайдера для плагина pluginType: provider: обслуживаемые им возможности, способ трансляции вида aggrega.ai/v1beta1 Workload, считываемые им нативные аннотации платформы и его контракт поведения отрисовки. Присутствует только у плагинов, отрисовывающих для провайдера; отсутствует у всех прочих типов плагинов.

СвойствоТипОбязательноОписание
capabilitiesstring[]нетЗаписывается из самоотчёта .wasm плагина командой aggrega plugin gen-catalog, поэтому источник этого списка — сам плагин. Автор может сузить его перед публикацией, удалив запись, которую эта сущность не должна предлагать, но не может добавить ни одной, которой нет в самоотчёте: публикация, а также aggrega validate с .wasm плагина, переданным через --plugin, отклоняют список, называющий возможность, которой нет в самоотчёте. Публикация отправляет сущность в том виде, в каком она написана, никогда не переписывая этот список, и отмечает каждую возможность из самоотчёта, которую список опускает. Возможности, которые обслуживает этот провайдер, — имена возможностей, такие как helm или compose, форму вывода которых он отрисовывает. Провайдер универсален для артефактов с общей формой вывода возможности, но не для всех возможностей, поэтому список — это явное заявление о проверенной совместимости, а не намерение. Записи сохраняют порядок автора. Запрошенная в сущности Recipe цель провайдера разрешается в плагин-провайдер, список которого содержит эту цель; цель, указанная более чем одним плагином-провайдером, останавливает сборку как неоднозначная, если только выбор plugins.providers в конфигурации рабочего пространства не указывает, какой плагин использовать. Пустой или отсутствующий список не заявляет никаких возможностей, поэтому плагин не обслуживает ни одной цели.
workloadSchemastringнетJSON Schema 2020-12, документирующая, как этот провайдер преобразует вид Workload aggrega.ai/v1beta1 в нативные для провайдера манифесты. Если поле задано, провайдер поддерживает Recipes, объявляющие блок workload: (синтезированный режим), — провайдер преобразует Workload в нативные для провайдера манифесты, руководствуясь этой схемой как документацией и контрактом. Поддерживается ли сущность Recipe с workload:, определяется возможностью синтеза у привязанного провайдера, а не наличием этого поля: сущность Recipe в синтезированном режиме, привязанная к провайдеру, который не умеет синтезировать, явно останавливает сборку во время отрисовки. Каталог стандартной библиотеки объявляет workloadSchema у синтезирующих провайдеров как документированный контракт, синхронизированный с этой возможностью. Поле — это документированный контракт: при загрузке тело компилируется в JSON Schema 2020-12 для проверки корректности, и больше его ничто не читает.
wellKnownAnnotationsobject[]нетЗаявление провайдера о поддержке: нативные для платформы общеизвестные ключи аннотаций (пространство имён aggrega.ai/), которые читает этот провайдер, каждый — с областью, в которой он читается, и поведением, применяемым при его отсутствии. Объявляйте ключ, только если провайдер его читает: опубликованная матрица поддержки отрисовывается из этих объявлений, поэтому указанный здесь ключ — это ключ, изменения которого, как может ожидать автор, меняют отрисованный вывод в названной области. Компилятор использует объявление двумя способами: scope, называющий вид входных данных, который не заявлен в собственном contract.inputKinds провайдера, противоречит соседнему заявлению в той же сущности, и сборка останавливается с указанием ключа и противоречия; а сборка выдаёт предупреждение об аннотации aggrega.ai/, доходящей до рендера через этот провайдер, если ни одна запись не охватывает её ни в одном из видов входных данных, которые объявляет этот рендер. Поле не связано с правилом, регулирующим привязку значения под зарезервированным префиксом aggrega.ai/. Отсутствие поля не заявляет поддержки, и для этого провайдера такое предупреждение не выдаётся; провайдер, который не читает ни одного из этих ключей, объявляет readsNoWellKnownAnnotations вместо этого списка. Записи образуют упорядоченный список и сохраняют порядок автора.
readsNoWellKnownAnnotationsконстанта trueнетОбъявляет, что этот провайдер не читает ни одного из нативных для платформы ключей аннотаций в пространстве имён aggrega.ai/, то есть ключей, которые иначе перечислялись бы в wellKnownAnnotations: это заявление о поддержке, не охватывающее ни одного ключа, — явное высказывание там, где отсутствие и этого поля, и wellKnownAnnotations означает молчание. Тогда сборка выдаёт предупреждение о каждой аннотации aggrega.ai/, которая доходит до рендера через этот провайдер, с указанием ключа, провайдера и видов входных данных, которые объявляет этот рендер; значение по-прежнему проходит без изменений, и сборка не останавливается. Записать можно только true, поэтому отсутствие поля остаётся единственным способом ничего не сказать. Его нельзя записать вместе с wellKnownAnnotations: провайдер, который читает часть ключей, вместо этого перечисляет их там. Константа: true
contractobjectнетСамостоятельно объявленный провайдером контракт поведения отрисовки: виды входных данных, которые он отрисовывает, как он собирает повузловой вывод группы диспетчеризации и в каких каталогах этот вывод располагается, пара разделителей шаблонов, применяемая к импортированным файлам артефактов, может ли один загруженный экземпляр обслуживать все переходы, связывает ли он межграничные рёбра, учитывает ли записи omit, принимает ли файлы, которые сущность Recipe добавляет в общий вывод своей границы, и какие файлы его экосистема никогда не поставляет рядом с исходником. Это запись на момент публикации самоотчёта плагина-провайдера, которую хост сверяет с этим самоотчётом при публикации и при загрузке. Отсутствие поля не объявляет контракта поведения отрисовки, и сверка сравнивает только заявления отдельных экспортов.

Дополнительные свойства не допускаются.

plugin.spec.provider.wellKnownAnnotations[]
СвойствоТипОбязательноОписание
keystringдаНативный для платформы общеизвестный ключ аннотации, который читает провайдер (например, aggrega.ai/namespace). Располагается в зарезервированном платформой пространстве имён аннотаций aggrega.ai/ — директивы платформы, читаемые провайдером. Шаблон: ^aggrega\.ai/.+.
purposestringдаЧем управляет аннотация — поведение отрисовки, на которое она влияет, если задана.
defaultBehaviorstringнетПоведение, которое провайдер применяет, если эта аннотация отсутствует.
scopestring (enum)[]нетГде этот провайдер читает ключ. Первые три значения — виды входных данных сущности Recipe; они называют путь отрисовки, на котором читается ключ: sourced — вендорный набор файлов, synthesized — Workload, материализуемый провайдером, artifactsStandalone — узел, весь вывод которого состоит из импортированных документов артефактов. Каждое из них должно быть видом входных данных, заявленным в contract.inputKinds этого провайдера; указание незаявленного останавливает сборку. boundary предназначено для ключа, разрешаемого один раз на границу, а не на узел, — имени собранного артефакта или контекста размещения, из которого формируется межграничная ссылка, — где вид входных данных не является значимой осью, поэтому оно не сопоставляется с contract.inputKinds. Ключ, читаемый на нескольких путях, перечисляет их все. Отсутствие поля не делает заявлений по путям: ничего не проверяется, и ключ сообщает лишь, что провайдер где-то его читает. Не менее 1 записи. Ни одна запись не может встречаться дважды. Допустимые значения для каждой записи: "sourced", "synthesized", "artifactsStandalone", "boundary".

Дополнительные свойства не допускаются.

plugin.spec.provider.contract

Самостоятельно объявленный провайдером контракт поведения отрисовки: виды входных данных, которые он отрисовывает, как он собирает повузловой вывод группы диспетчеризации и в каких каталогах этот вывод располагается, пара разделителей шаблонов, применяемая к импортированным файлам артефактов, может ли один загруженный экземпляр обслуживать все переходы, связывает ли он межграничные рёбра, учитывает ли записи omit, принимает ли файлы, которые сущность Recipe добавляет в общий вывод своей границы, и какие файлы его экосистема никогда не поставляет рядом с исходником. Это запись на момент публикации самоотчёта плагина-провайдера, которую хост сверяет с этим самоотчётом при публикации и при загрузке. Отсутствие поля не объявляет контракта поведения отрисовки, и сверка сравнивает только заявления отдельных экспортов.

СвойствоТипОбязательноОписание
inputKindsobjectнетКакие из трёх видов входных данных Recipe отрисовывает этот плагин: набор файлов из источника, синтезированную рабочую нагрузку и автономный узел, состоящий только из артефактов. Каждое поле — независимое заявление.
boundaryAssemblystring (enum)нетКак плагин объединяет повузловой результат отрисовки группы диспетчеризации: none записывает результат каждого узла непосредственно по пути диспетчеризации; merge сводит повузловые фрагменты в один документ; nest помещает результат каждого узла в его собственную позицию внутри объемлющей структуры. Отсутствие поля не заявляет никакого способа сборки. Допустимые значения: "none", "merge", "nest"
artifactDelimitersobjectнетПара разделителей шаблонов Go, которую плагин применяет к импортированным файлам артефактов. Отсутствие поля означает пару по умолчанию {{/}}; плагин, целевой синтаксис которого конфликтует с этой парой, объявляет здесь альтернативную пару.
assemblyNameAnnotationobjectнетАннотация границы, разрешённое значение которой задаёт имя артефакта, собираемого плагином из группы диспетчеризации. Плагин, который сводит участвующие границы группы в одну именованную сборку, объявляет ключ аннотации, который он читает, и то, должны ли все участвующие границы совпадать в разрешённом значении этой аннотации. Отсутствие поля означает, что плагин называет свою сборку только по пути диспетчеризации.
reusableInstanceлогическаянетМожет ли один загруженный экземпляр плагина обслуживать все переходы отрисовки, сборки и проверки в рамках сборки вместо нового экземпляра на каждый переход. Объявляется как true, только когда плагин не хранит состояния между переходами — то есть является чистой функцией от входных данных каждого перехода, — так что один экземпляр выдаёт побайтно идентичный результат независимо от того, используется ли он повторно или загружен заново. Отсутствие поля (false) загружает новый экземпляр на каждый переход, изолируя плагин, который по своему устройству хранит состояние.
crossBoundaryLinkingлогическаянетСвязывает ли плагин межграничное ребро uses — ребро uses, потребляющий и потребляемый концы которого собираются в разные группы диспетчеризации, — выдавая нативные для провайдера перекрёстные ссылки через парный контракт экспорта link_publish/link_resolve. Объявляется как true, только когда плагин экспортирует оба; заявление, не соответствующее паре экспортов, останавливает загрузку. Отсутствие поля (false) не объявляет межграничного связывания, поэтому хост не направляет плагину ни одного перехода связывания.
omitsлогическаянетПоддерживает ли провайдер записи omit — записи, называющие отрисованные единицы, которые нужно исключить из результата узла: он исключает из отрисовываемого каждую единицу, которой соответствует запись, и сообщает, скольким единицам соответствовала каждая запись. Это запись времени публикации для заявления omits, которое делает самоотчёт провайдера, и значение, отличающееся от этого отчёта, останавливает загрузку. Отсутствие поля (false) не объявляет такой поддержки.
boundaryArtifactsлогическаянетПринимает ли провайдер файлы, которые Recipe вносит в общий результат границы, в которой он отрисовывает, в spec.boundary.artifacts этого Recipe: компилятор записывает каждый такой файл один раз в каталог с собранным результатом границы, и цель провайдера считает его частью этого результата. Это запись времени публикации для заявления boundary_artifacts, которое делает самоотчёт провайдера, и значение, отличающееся от этого отчёта, останавливает загрузку. Отсутствие поля (false) не объявляет такой поддержки, и Recipe, объявляющий этот блок для данного провайдера, отклоняется до начала отрисовки.
nestSegmentstringнетКаталог, в который цель этого провайдера помещает собственный подкаталог каждого участника, для провайдера, у которого boundaryAssembly равен nest, — charts для объемлющего чарта, modules для корневого модуля. Компилятор соединяет этот каталог, имя участника и собственный путь каждого файла. Читается только для вкладывающего провайдера. При отсутствии поля подкаталог каждого участника помещается непосредственно в собственный каталог границы. Значение задаёт один каталог и никогда не путь.
sourceIgnoreobjectнетФайлы, которые экосистема этого провайдера никогда не поставляет рядом с отрисовываемым им источником, в виде правил игнорирования в синтаксисе gitignore — запись времени публикации для правил source_ignore, которые объявляет его самоотчёт. Когда автор закрепляет Recipe или FeatureRecipe, возможность которого этот провайдер для него обслуживает, эти правила объединяются с собственным .aggregaignore автора и записываются в entity.lock рядом с сущностью вместе с именем этого плагина, и каждая последующая публикация, сравнение и отрисовка локального источника сущности применяет записанные правила. Если поле присутствует, оно должно совпадать с тем, что объявляет самоотчёт, и загрузка отклоняет плагин, отчёт которого отличается; отсутствие поля ничего не заявляет и не сравнивается.

Дополнительные свойства не допускаются.

plugin.spec.provider.contract.inputKinds

Какие из трёх видов входных данных Recipe отрисовывает этот плагин: набор файлов из источника, синтезированную рабочую нагрузку и автономный узел, состоящий только из артефактов. Каждое поле — независимое заявление.

СвойствоТипОбязательноОписание
sourcedлогическаянетОтрисовывает подключённый набор файлов (чарт, модуль, compose-файл).
synthesizedлогическаянетОтрисовывает синтезированную рабочую нагрузку в нативные артефакты провайдера.
artifactsStandaloneлогическаянетОтрисовывает автономный узел только с артефактами — содержащий импортированные документы артефактов и не имеющий ни источника, ни рабочей нагрузки.

Дополнительные свойства не допускаются.

plugin.spec.provider.contract.artifactDelimiters

Пара разделителей шаблонов Go, которую плагин применяет к импортированным файлам артефактов. Отсутствие поля означает пару по умолчанию {{/}}; плагин, целевой синтаксис которого конфликтует с этой парой, объявляет здесь альтернативную пару.

СвойствоТипОбязательноОписание
leftstringдаОткрывающий разделитель.
rightstringдаЗакрывающий разделитель.

Дополнительные свойства не допускаются.

plugin.spec.provider.contract.assemblyNameAnnotation

Аннотация границы, разрешённое значение которой задаёт имя артефакта, собираемого плагином из группы диспетчеризации. Плагин, который сводит участвующие границы группы в одну именованную сборку, объявляет ключ аннотации, который он читает, и то, должны ли все участвующие границы совпадать в разрешённом значении этой аннотации. Отсутствие поля означает, что плагин называет свою сборку только по пути диспетчеризации.

СвойствоТипОбязательноОписание
annotationstringдаКлюч аннотации границы, из которого плагин считывает имя собранного артефакта.
requireUniqueлогическаянетДолжны ли все границы, участвующие в одной группе диспетчеризации, совпадать в разрешённом значении аннотации. Если true, группа, участвующие границы которой разрешают аннотацию в разные значения, останавливает сборку; если false, плагин принимает первое разрешённое значение.

Дополнительные свойства не допускаются.

plugin.spec.provider.contract.sourceIgnore

Файлы, которые экосистема этого провайдера никогда не поставляет рядом с отрисовываемым им источником, в виде правил игнорирования в синтаксисе gitignore — запись времени публикации для правил source_ignore, которые объявляет его самоотчёт. Когда автор закрепляет Recipe или FeatureRecipe, возможность которого этот провайдер для него обслуживает, эти правила объединяются с собственным .aggregaignore автора и записываются в entity.lock рядом с сущностью вместе с именем этого плагина, и каждая последующая публикация, сравнение и отрисовка локального источника сущности применяет записанные правила. Если поле присутствует, оно должно совпадать с тем, что объявляет самоотчёт, и загрузка отклоняет плагин, отчёт которого отличается; отсутствие поля ничего не заявляет и не сравнивается.

СвойствоТипОбязательноОписание
patternsstring[]нетСобственные шаблоны игнорирования экосистемы, каждый из которых отсчитывается от корня локального каталога источника, в порядке их применения.
filesstring[]нетИмена файлов игнорирования, которые экосистема учитывает внутри источника, — .helmignore для chart. Строки каждого такого файла — дополнительные шаблоны, отсчитываемые от каталога, в котором он находится.

Дополнительные свойства не допускаются.

plugin.spec.pipelineStep

Блок шага конвейера для плагина pluginType: pipeline-step: возможности провайдера, с которыми совместим его шаг. Присутствует только у плагинов pipeline-step; отсутствует у всех прочих типов плагинов.

СвойствоТипОбязательноОписание
capabilitiesstring[]нетЗаписывается из самоотчёта .wasm плагина командой aggrega plugin gen-catalog, поэтому источником этого списка является плагин. Автор может сузить его перед публикацией, удалив запись, которую эта сущность не должна предлагать, но не может добавить ни одной, которой нет в самоотчёте: публикация, а также aggrega validate с .wasm плагина, переданным через --plugin, отклоняют список, называющий возможность, которой нет в самоотчёте. Публикация отправляет сущность в том виде, в каком она написана, никогда не переписывая этот список, и отмечает каждую возможность из самоотчёта, которую список опускает. Возможности провайдеров, с которыми совместим шаг конвейера этого плагина, — имена возможностей провайдеров, например helm или compose, отрисованный результат которых шаг умеет преобразовывать. Шаг пишется в расчёте на форму результата одного провайдера за раз, поэтому список — это явное заявление о проверенной совместимости, а не пожелание. Записи сохраняют авторский порядок. Это доступная каталогу запись данного заявления; сборка читает то же заявление из плагина, когда шаг затрагивает область, и останавливается, если провайдер, отрисовывающий документы этой области, в него не входит. Пустой или отсутствующий список не объявляет совместимости, поэтому ни одна область не допускает этот шаг.

Дополнительные свойства не допускаются.

plugin.spec.parser

Блок парсера для плагина pluginType: parser: исходные форматы, которые он превращает в каноническое структурированное дерево. Присутствует только у плагинов-парсеров; отсутствует у всех прочих типов плагинов.

СвойствоТипОбязательноОписание
capabilitiesstring[]нетЗаписывается из самоотчёта .wasm плагина командой aggrega plugin gen-catalog, поэтому источником этого списка является плагин. Автор может сузить его перед публикацией, удалив запись, которую эта сущность не должна предлагать, но не может добавить ни одной, которой нет в самоотчёте: публикация, а также aggrega validate с .wasm плагина, переданным через --plugin, отклоняют список, называющий возможность, которой нет в самоотчёте. Публикация отправляет сущность в том виде, в каком она написана, никогда не переписывая этот список, и отмечает каждую возможность из самоотчёта, которую список опускает. Исходные форматы, которые этот парсер превращает в каноническое структурированное дерево, каждый записывается как parse:<format> — например, parse:yaml. Префикс является частью записи, поэтому плагин, объявляющий несколько форматов, указывает по одной записи на формат. Записи сохраняют авторский порядок. Запрошенный формат разрешается в парсер, список которого содержит соответствующую запись; формат, который не объявляет ни один парсер, останавливает сборку, а формат, объявленный несколькими плагинами-парсерами, останавливает её как неоднозначный. Пустой или отсутствующий список не объявляет форматов, поэтому плагин ничего не разбирает.

Дополнительные свойства не допускаются.

plugin.spec.importer

Блок импортёра для плагина pluginType: importer: сторонние исходные форматы, которые он превращает в черновые авторские файлы Aggrega, и сигнатуры, по которым распознаётся источник этих форматов. Присутствует только у плагинов-импортёров; отсутствует у всех прочих типов плагинов.

СвойствоТипОбязательноОписание
capabilitiesstring[]нетЗаписывается из самоотчёта .wasm плагина командой aggrega plugin gen-catalog, поэтому источником этого списка является плагин. Автор может сузить его перед публикацией, удалив запись, которую эта сущность не должна предлагать, но не может добавить ни одной, которой нет в самоотчёте: публикация, а также aggrega validate с .wasm плагина, переданным через --plugin, отклоняют список, называющий возможность, которой нет в самоотчёте. Публикация отправляет сущность в том виде, в каком она написана, никогда не переписывая этот список, и отмечает каждую возможность из самоотчёта, которую список опускает. Внешние исходные форматы, которые этот импортёр превращает в черновые авторские файлы Aggrega, каждый записывается как import:<format> — например, import:terraform. Префикс является частью записи, поэтому плагин, объявляющий несколько форматов, перечисляет по одной записи на формат. Записи сохраняют авторский порядок. Запрошенный формат импорта разрешается в импортёр, список которого содержит соответствующую запись; формат, который не объявляет ни один импортёр, останавливает импорт, а формат, объявленный более чем одним плагином-импортёром, останавливает его как неоднозначный, если только запись plugins.importer в конфигурации рабочего пространства не подключает один из них — тогда запускается он. Пустой или отсутствующий список не заявляет форматов, поэтому плагин ничего не импортирует.
detectobject[]нетУправляется машиной, не заполняйте вручную: выводится из самоотчёта .wasm плагина при генерации сущности из него и записывается сюда в порядке, объявленном самоотчётом. Сигнатуры, по которым распознаётся источник в форматах этого импортёра, когда импорт не указывает формат. aggrega import читает сигнатуры всех импортёров, содержащихся в каталоге рабочего пространства, включая все версии, а также встроенных импортёров компилятора, сопоставляет их с источником, не зная, что представляет собой какой-либо формат, и читает источник в формате того единственного импортёра, чья сигнатура совпала; источник, которому не соответствует ни одна сигнатура, отклоняется с запросом формата, а источник, которому соответствуют сигнатуры более чем одного формата, отклоняется с их перечислением. Импортёр, распознающий источник, распознаёт его как каждый объявленный им формат, поэтому у импортёра, объявляющего более одного формата, каждое совпадение отклоняется как неоднозначное. Если список присутствует, он должен совпадать с тем, что объявляет самоотчёт плагина, запись за записью и в том же порядке, а загрузка и публикация отклоняют плагин, отчёт которого отличается, указывая это поле. Отсутствие не заявляет ничего и не сравнивается, и тогда к форматам импортёра можно обратиться только явно указав их.

Дополнительные свойства не допускаются.

plugin.spec.importer.detect[]
СвойствоТипОбязательноОписание
syntaxstringдаСинтаксический формат, в котором разбирается источник, — например, json или yaml, — то есть формат, который плагин-парсер объявляет как parse:<syntax>. Источник разбирается парсером, который каталог рабочего пространства предоставляет для этого синтаксиса, а для синтаксиса, для которого каталог парсера не предоставляет, — встроенным парсером компилятора, не более одного раза независимо от того, сколько сигнатур указывают этот синтаксис; источник, который в нём не разбирается, не соответствует ни одной сигнатуре, указывающей этот синтаксис. Синтаксис, для которого парсер не предоставляет ни тот, ни другой, останавливает распознавание с указанием отсутствующего парсера. Длина не менее 1 символа.
filesstring[]нетШаблоны имён файлов, к которым применяется сигнатура; они сопоставляются с концом имени источника, разделители в котором читаются как прямые косые черты: шаблон из одного сегмента — с собственным именем файла, а шаблон из нескольких сегментов, разделённых косой чертой, — с таким же числом последних сегментов его пути, так что .vscode/mcp.json соответствует файлу с именем mcp.json в каталоге с именем .vscode. Внутри сегмента * соответствует любой последовательности символов, ? — одному символу, а [...] — одному символу из класса. Сигнатура применяется, если совпадает любой шаблон. Отсутствие или пустой список применяет её к источнику, представляющему собой один файл, как бы он ни назывался, и ни к одному файлу каталога. Шаблоны сигнатур импортёра также определяют, какие файлы каталога aggrega import передаёт ему.
matchobject[]нетПредикаты, которым должно удовлетворять разобранное дерево, — все без исключения, в объявленном порядке. Отсутствие или пустой список не требует от дерева ничего, кроме успешного разбора в этом синтаксисе.

Дополнительные свойства не допускаются.

plugin.spec.importer.detect[].match[]
СвойствоТипОбязательноОписание
pathstringдаМесто в дереве, куда смотрит предикат, записанное как ключи, соединённые точками от вершины дерева: data.nodes обозначает член nodes объекта data верхнего уровня. Сегмент, записанный как целое число 0 или больше, выбирает эту позицию массива при счёте от нуля, поэтому nodes.0.type обозначает type первого узла; каждый другой сегмент выбирает член объекта. Длина не менее 1 символа.
isstring (enum)даЧего должен достичь путь: present выполняется, когда путь достигает значения любого вида, включая null; absent выполняется, когда путь ничего не достигает; object, array, string, number и boolean выполняются, когда путь достигает значения соответствующего вида. Допустимые значения: "present", "absent", "object", "array", "string", "number", "boolean"
equalsstringнетСтрока, которой должно в точности равняться значение, достигаемое путём; значение, не являющееся строкой, никогда ей не равно. В одном предикате объявляется не более одного из equals и prefix. Длина не менее 1 символа.
prefixstringнетСтрока, с которой должно начинаться значение, достигаемое путём; значение, не являющееся строкой, никогда с неё не начинается. В одном предикате объявляется не более одного из equals и prefix. Длина не менее 1 символа.

Дополнительные свойства не допускаются.