Схема Aggrega Wasm Describe Socket
Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.
Идентификатор схемы: https://aggrega.ai/schemas/wasm-describe-v1beta1.schema.json
Формат передачи данных, который каждый Wasm-плагин возвращает из своего экспорта describe() (PluginDescriptor). describe() — это самоописание плагина, которое хост считывает один раз при загрузке плагина: версия ABI, с которой связывается гостевой модуль, тип плагина, предлагаемые им экспорты с объявлением возможностей каждого экспорта, самоотчёт о возможностях на уровне плагина, необязательный контракт поведения рендеринга для провайдера, необязательный контракт распознавания для импортёра, необязательные команды CLI, необязательная схема настроек и необязательные метаданные об авторстве. Один формат охватывает все типы плагинов — провайдер, линтер, шаг конвейера feature-recipe, управление (governance), CLI, парсер и импортёр. Хост считывает describe() до вызова любого другого экспорта и отклоняет дескриптор, который не может принять, вместо того чтобы неправильно вызвать плагин при диспетчеризации.
Одна из следующих форм
PluginDescriptor
Определения
PluginDescriptor
Полное самоописание плагина, возвращаемое из describe() и считываемое один раз при загрузке. Оно содержит согласование совместимости ABI, тип плагина, предлагаемые экспорты и необязательные поверхности для каждого типа (контракт поведения рендеринга провайдера, контракт распознавания импортёра, команды CLI-плагина, схему настроек, метаданные об авторстве).
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
abi_version | const “v1beta1” | да | ABI плагина, к которому привязывается гость. Хост принимает ровно эту версию; гость, собранный под любой другой ABI, отклоняется при загрузке, а не вызывается неправильно при диспетчеризации. Константа: "v1beta1" |
plugin_type | string (enum) | да | Вид плагина. Он определяет правило минимального экспорта, которое проверяет хост, и вместе с именем экспорта — шаблон доставки входных данных по умолчанию. Плагин governance выполняет роли преобразования и вердикта в конвейере сборки; то, что он может выдавать, определяет роль, к которой он подключён, а не его вид. Допустимые значения: "provider", "linter", "pipeline-step", "governance", "cli", "parser", "importer" |
capabilities | string[] | нет | Что обслуживает плагин. В передаваемых данных список плоский, а соседнее обязательное поле plugin_type определяет, какой из четырёх смыслов несёт каждая запись: для провайдера — имена возможностей (например, helm или compose), форму вывода которых он отрисовывает; для шага конвейера feature-recipe — возможности провайдеров, с которыми совместим его шаг; для парсера — исходные форматы, которые он превращает в каноническое структурированное дерево, каждый записывается как parse: |
exports | PluginExport[] | да | Экспорты, которые предлагает плагин, в объявленном порядке. Хост проверяет наличие минимального экспорта для данного типа и привязывает поверхность хоста для каждого экспорта перед его вызовом. |
contract | ProviderContract | нет | Самоописание поведения рендеринга провайдера — виды входных данных, которые он рендерит, способ сборки вывода отдельных узлов группы диспетчеризации и применяемая пара разделителей шаблонов артефактов. Оно описывает провайдер в целом, а не какой-либо отдельный экспорт. Отсутствует у плагина, который не объявляет контракт поведения рендеринга. |
importer | ImporterContract | нет | Самоописание импортёра о том, как распознаётся источник в заявленных им форматах, когда импорт не указывает формат. Объявлять его может только плагин, у которого plugin_type равен importer; любой другой плагин, объявивший его, отклоняется при загрузке. Отсутствует у импортёра, который не объявляет способа распознавания своих форматов; тогда к его форматам можно обратиться, только указав их явно. |
description | string | нет | Собственное однострочное человекочитаемое описание того, что делает плагин, отличное от описания отдельного экспорта и от описания в метаданных сущности. Оно носит информационный характер; хост его не проверяет и на него не реагирует. |
commands | PluginCLICommand[] | нет | Глаголы команд aggrega верхнего уровня, добавляемые CLI-плагином, каждый со своей строкой краткой справки. Один CLI-плагин может добавлять несколько команд; хост регистрирует по одной команде на запись и при вызове передаёт гостю разрешённое имя команды. Плагин, не являющийся CLI-плагином, оставляет поле пустым. |
settings_schema | object | нет | Необязательный документ JSON Schema, который плагин объявляет для типизации настроек, задаваемых оператором в его подключении. Если он задан, хост компилирует его при загрузке и при диспетчеризации, перед вызовом плагина, проверяет по нему настройки подключения; несоответствующие настройки останавливают сборку. Если он не задан, плагин не объявляет формы, и настройки передаются без изменений. Схема — собственное произвольное объявление плагина; хост выполняет по ней обычную проверку JSON Schema и не интерпретирует смысл настроек. |
metadata | PluginDescriptorMeta | нет | Необязательные сведения об авторстве и происхождении сборки. Они не несут поведенческого контракта — хост их не проверяет и на них не реагирует. |
Дополнительные свойства не допускаются.
PluginExport
Один экспорт, предлагаемый плагином, в том виде, в каком он объявлен в describe(). Хост направляет вызов экспорту по его имени и привязывает поверхность хоста с минимальными привилегиями, которых требуют объявленные функции хоста этого экспорта.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | Имя экспорта в ABI — например, render_node, assemble_boundary, lint_rules или step. Хост направляет вызов экспорту по этому имени. |
input_pattern | string (enum) | нет | Как хост доставляет входные данные экспорта: b передаёт полную полезную нагрузку непосредственно, чтобы гость рендерил только по ней; a передаёт небольшую полезную нагрузку, которую гость дополняет через функции хоста. Экспорт, не указавший это поле, получает значение по умолчанию для своего типа плагина и имени. Допустимые значения: "a", "b" |
host_functions | string[] | нет | Имена функций хоста, которые импортирует этот экспорт. Каждое имя должно входить в список разрешённых функций хоста. Объявление является определяющим и при загрузке сверяется с функциями, которые гость фактически импортирует из своего модуля, поэтому оно не может разойтись с функциями, которые гость действительно вызывает. |
description | string | нет | Необязательный человекочитаемый текст, описывающий экспорт. Это документация для читателей каталога; хост её не проверяет и на неё не реагирует. |
stability | string (enum) | нет | Уровень стабильности экспорта. Отсутствующее значение не несёт заявления о стабильности. Допустимые значения: "stable", "experimental", "deprecated" |
operates | string (enum) | нет | Операция конвейера, которую выполняет этот экспорт: patch изменяет существующий отрендеренный документ, emit добавляет новый документ. Форма значения проверяется при загрузке; среда выполнения считывает его при диспетчеризации шага. Допустимые значения: "patch", "emit" |
scope | string (enum) | нет | Корень документов, с которым работает этот экспорт: own — собственные отрендеренные документы узла, host — документы компонента, к которому подключён feature recipe уровня компонента. Форма значения проверяется при загрузке; среда выполнения разрешает документы области при диспетчеризации. Допустимые значения: "own", "host" |
selector | string | нет | Произвольное человекочитаемое описание того, на что воздействует экспорт. Это документация для читателей каталога; хост не проверяет её содержимое и не реагирует на него. |
input | object | нет | Необязательный документ JSON Schema, который экспорт шага объявляет для типизации локальных входных данных шага, передаваемых записью конвейера через её блок with. Если он задан, он описывает форму, которой удовлетворяют входные данные with шага; если не задан, экспорт не объявляет контракта входных данных. Схема — собственное произвольное объявление экспорта о поверхности входных данных, на которую ориентируется автор конвейера для этого экспорта. |
output | object | нет | Необязательный документ JSON Schema, который экспорт шага объявляет для типизации выходных данных, возвращаемых им для одного шага, — формы адресуемых выходных данных, которые шаг предоставляет для чтения последующему шагу или шаблону. Если он задан, он описывает форму этих возвращаемых данных; если не задан, экспорт не объявляет контракта выходных данных. Схема — собственное произвольное объявление экспорта о поверхности выходных данных, которую он производит. |
Дополнительные свойства не допускаются.
PluginCLICommand
Один глагол команды aggrega верхнего уровня, добавляемый CLI-плагином, в том виде, в каком он объявлен в describe(). Хост регистрирует по одной команде на запись и при вызове передаёт гостю разрешённое имя команды, поэтому один гость может обслуживать несколько команд и выбирать поведение по имени.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | Глагол команды, который регистрирует хост, — токен aggrega, вызываемый оператором, и дискриминатор, который хост передаёт гостю, чтобы тот мог определить, какая команда вызвана. Его должна указывать каждая объявленная команда. |
description | string | нет | Однострочная краткая справка по команде, отображаемая в списке команд и в выводе справки. Это необязательная документация; хост её не проверяет и на неё не реагирует. |
flags | PluginCommandFlag[] | нет | Флаги команды в объявленном порядке. Каждая запись добавляет один флаг, который хост регистрирует для команды, чтобы aggrega help |
Дополнительные свойства не допускаются.
PluginCommandFlag
Один флаг, который CLI-плагин объявляет для команды, как сообщается в describe(). Хост регистрирует его в команде, чтобы aggrega help
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | Длинное имя флага — токен —name, который оператор передаёт в командной строке. Его должен указывать каждый объявленный флаг. Длина не менее 1 символа. |
shorthand | string | нет | Необязательный односимвольный короткий псевдоним флага — форма -x, которую оператор может передать вместо длинного имени. Отсутствие означает, что у флага нет короткого псевдонима. |
description | string | нет | Однострочная справка по флагу, отображаемая в выводе справки команды. Это необязательная документация; хост её не проверяет и на неё не реагирует. |
type | string | нет | Тип значения флага — например, string, bool или int. Отсутствие не заявляет никакого типа. |
default | string | нет | Значение флага по умолчанию, если оператор его не передаёт, записанное в виде строки. Отсутствие означает, что флаг не объявляет значения по умолчанию. |
Дополнительные свойства не допускаются.
PluginDescriptorMeta
Необязательные метаданные об авторстве и происхождении сборки, которые плагин объявляет в describe(). Они носят информационный характер; хост их не проверяет и на них не реагирует. Поля version и commit — это сведения о происхождении сборки, внедряемые в гостевой модуль во время сборки; сборка без таких сведений их опускает.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
author | string | нет | Автор плагина. |
repository | string | нет | Репозиторий исходного кода плагина. |
license | string | нет | Идентификатор лицензии плагина. |
version | string | нет | Версия происхождения сборки, внедрённая в гостевой модуль во время сборки. Опускается сборкой без таких сведений. |
commit | string | нет | Короткий хеш коммита, из которого собран гостевой модуль. Опускается сборкой без таких сведений. |
Дополнительные свойства не допускаются.
ProviderContract
Самоописание провайдера: поведение рендеринга во время компиляции, которое он выполняет для всех рендерируемых узлов, — принимаемые виды входных данных, собирает ли он и как повузловой вывод группы диспетчеризации в единый артефакт, пара разделителей Go-шаблонов, применяемая к импортированным файлам артефактов, принимает ли он файлы, которые Recipe добавляет в общий вывод своей границы, и файлы, которые его экосистема никогда не поставляет рядом с исходником. Оно описывает провайдер в целом, а не какой-либо отдельный экспорт. Проверка при загрузке сверяет его с заявлением, указанным автором в сущности.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
input_kinds | InputKinds | да | Какие из трёх видов входных данных Recipe рендерит плагин: набор файлов из источника, синтезированную рабочую нагрузку и автономный узел, содержащий только артефакты. |
boundary_assembly | string (enum) | да | Как плагин объединяет повузловой вывод рендеринга группы диспетчеризации: none записывает вывод каждого узла непосредственно по пути диспетчеризации, merge сливает повузловые фрагменты в один документ, а nest помещает вывод каждого узла в его собственную позицию в объемлющей структуре. Пустое значение не заявляет никакого способа сборки. Допустимые значения: "none", "merge", "nest", "" |
artifact_delimiters | ArtifactDelimiters | нет | Пара разделителей Go-шаблонов, которую плагин применяет к импортированным файлам артефактов. Отсутствие означает пару открытия/закрытия по умолчанию; плагин, целевой синтаксис которого конфликтует с этой парой, указывает здесь альтернативную пару. |
assembly_name_annotation | AssemblyNameAnnotation | нет | Аннотация границы, разрешённое значение которой задаёт имя артефакта, собираемого плагином из группы диспетчеризации. Отсутствие означает, что плагин именует сборку только по пути диспетчеризации. |
reusable_instance | логическая | нет | Может ли один загруженный экземпляр плагина обслуживать все переходы рендеринга, сборки и проверки в рамках сборки вместо нового экземпляра на каждый переход. Плагин объявляет true, только если не хранит состояние между переходами. Отсутствие (false) — безопасное значение по умолчанию: хост загружает новый экземпляр на каждый переход. |
cross_boundary_linking | логическая | нет | Связывает ли плагин межграничные рёбра uses — рёбра, потребляющий и потребляемый концы которых собираются в разные группы диспетчеризации, — создавая нативные для провайдера перекрёстные ссылки через свои экспорты link_publish и link_resolve. Плагин объявляет true, только если экспортирует оба. Отсутствие (false) — безопасное значение по умолчанию: плагин не связывает межграничные рёбра. |
omits | логическая | нет | Соблюдает ли плагин записи omit, которые несёт вход render_node: он исключает из всего возвращаемого каждую отрендеренную единицу, которой соответствует запись, и сообщает в поле omitted вывода по одному счётчику на каждую переданную ему запись. Плагин объявляет true, только если делает и то и другое. Отсутствие (false) — безопасное значение по умолчанию: плагин не заявляет, что что-либо исключает. |
boundary_artifacts | логическая | нет | Принимает ли цель плагина файлы, которые Recipe добавляет в общий вывод границы, в которой он рендерит. Хост вычисляет эти файлы и записывает каждый один раз в каталог с собранным выводом группы диспетчеризации, рядом с тем, что записывает сборка плагина; плагину ни один из них не передаётся, и он ни один из них не читает, поэтому заявление означает, что его цель считает файл, размещённый там, частью вывода границы. Отсутствие (false) — безопасное значение по умолчанию: Recipe, объявляющий такие файлы для этого плагина, отклоняется до начала любого рендеринга. |
nest_segment | string | нет | Каталог, в который цель плагина помещает собственный подкаталог каждого участника, — для плагина, вкладывающего повузловой вывод группы диспетчеризации. Хост объединяет этот сегмент, имя участника на уровне описания и собственный путь каждого файла. Читается, только когда boundary_assembly равно nest. При отсутствии хост помещает подкаталог каждого участника непосредственно в позицию диспетчеризации, без объемлющего каталога. Значение задаёт один каталог и никогда не путь: значение, содержащее разделитель пути или обозначающее текущий либо родительский каталог, отклоняется, поскольку хост подставляет в него имя участника, и фрагмент пути поместил бы файлы участника не под позицию диспетчеризации, а в другое место. |
source_ignore | SourceIgnore | нет | Файлы, которые экосистема этого плагина никогда не поставляет рядом с рендерируемым им исходником, объявленные в виде правил игнорирования. Хост читает это объявление, когда автор закрепляет Recipe или FeatureRecipe, возможность которого этот плагин для него обслуживает: он объединяет эти правила с собственным файлом игнорирования автора, записывает объединённые правила в файл блокировки сущности рядом с ней, и с этого момента каждая публикация сущности, каждое сравнение её локального исходника и каждый её рендеринг применяют записанные правила, не обращаясь к плагину повторно. Таким образом, Recipe, опубликованный для возможности, несёт файлы, сохранённые правилами его издателя, и плагин рендерит его, если поддерживает ту же версию ABI, его контракт соответствует заявлению сущности и ему не нужен ни один файл вне этого набора. Плагин, которому нужен файл, исключённый из набора, должен явно завершить сборку с ошибкой и назвать этот файл; со стороны хоста — отказ упаковать или прочитать файл, которого нет в наборе, с указанием его имени. Отсутствие не объявляет правил игнорирования, и тогда рендерируемый плагином исходник сохраняет все файлы, которые сохраняют собственные правила автора. |
Дополнительные свойства не допускаются.
SourceIgnore
Правила игнорирования, которые экосистема плагина применяет к каталогу исходника, в синтаксисе gitignore: шаблон без косой черты или только с завершающей косой чертой соответствует имени на любой глубине, шаблон с любой другой косой чертой читается от корня каталога, к которому он относится, завершающая косая черта соответствует только каталогу, а начальный ! возвращает то, что исключило предыдущее правило. Правила применяются по порядку, и более позднее совпадение отменяет более раннее. В каталог, исключённый правилом, обход не заходит, поэтому ничто внутри него не возвращается, если сначала не возвращён сам каталог.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
patterns | string[] | нет | Собственные шаблоны игнорирования экосистемы, каждый относительно корня обходимого локального каталога исходника, в порядке применения. Отсутствие или пустой список не объявляет ни одного. |
files | string[] | нет | Имена файлов игнорирования, которые экосистема учитывает внутри исходника, — например, .helmignore для чарта. Где бы обход исходника ни нашёл файл с одним из этих имён, его строки читаются как дополнительные шаблоны в том же синтаксисе, каждый относительно каталога, содержащего файл, и применяются после шаблонов выше; пустые строки и строки, начинающиеся с #, пропускаются. Сам файл с таким именем переносится, если его не исключает какое-либо правило. Отсутствие или пустой список не называет ни одного. |
Дополнительные свойства не допускаются.
InputKinds
Какие виды входных данных сущности Recipe отрисовывает плагин. Каждое поле — независимое заявление; плагин может сообщать любую их комбинацию.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
sourced | логическая | да | Отрисовывает ли плагин набор файлов из источника (chart, модуль, compose-файл). |
synthesized | логическая | да | Отрисовывает ли плагин синтезированную рабочую нагрузку. |
artifacts_standalone | логическая | да | Отрисовывает ли плагин автономный узел, состоящий только из артефактов, — узел, который содержит импортированные документы артефактов и не содержит ни источника, ни рабочей нагрузки. |
Дополнительные свойства не допускаются.
ArtifactDelimiters
Пара разделителей Go-шаблонов, которую плагин применяет к импортированным файлам артефактов; сообщается, когда она отличается от пары по умолчанию.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
left | string | да | Открывающий разделитель. |
right | string | да | Закрывающий разделитель. |
Дополнительные свойства не допускаются.
AssemblyNameAnnotation
Аннотация границы, разрешённое значение которой задаёт имя собранного артефакта плагина; сообщается, когда плагин объединяет участвующие границы группы диспетчеризации в одну именованную сборку.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
annotation | string | да | Ключ аннотации границы, из которого плагин считывает имя собранного артефакта. |
require_unique | логическая | нет | Должны ли все границы, участвующие в одной группе диспетчеризации, совпадать в разрешённом значении аннотации. Если true, группа, участвующие границы которой разрешают аннотацию в разные значения, останавливает сборку; если false, плагин принимает первое разрешённое значение. |
Дополнительные свойства не допускаются.
ImporterContract
Что импортёр объявляет о своих форматах помимо их объявления как поддерживаемых: сигнатуры, по которым распознаётся источник этих форматов. Когда импорт не указывает формат, хост считывает сигнатуры, записанные каждым импортёром, из которых выбирает импорт, — импортёрами из каталога рабочего пространства и базовыми импортёрами компилятора, сущности Plugin которых содержит бинарный файл, — сопоставляет каждую с источником, не зная, что представляет собой какой-либо формат, и читает источник в формате того единственного импортёра, сигнатура которого совпала. Источник, с которым не совпала ни одна сигнатура, отклоняется с запросом формата, а источник, с которым совпали сигнатуры более чем одного формата, отклоняется с указанием этих форматов. Сущность Plugin записывает тот же список, и хост отклоняет импортёр, отчёт describe() которого отличается от записи.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
detect | DetectSignature[] | нет | Сигнатуры, распознающие источник форматов этого импортёра, в объявленном порядке; источник распознаётся, когда с ним совпадает любая из них. Источник, распознанный импортёром, распознаётся как каждый формат, который объявляет импортёр, поэтому у импортёра, объявляющего более одного формата, каждое совпадение отклоняется как неоднозначное, и импортёр, источники которого должны распознаваться, объявляет один формат. Отсутствие или пустой список не объявляет ни одной сигнатуры, и к форматам импортёра можно обратиться, только указав их явно. |
Дополнительные свойства не допускаются.
DetectSignature
Один способ распознавания источника: синтаксис, в котором читается источник, имена файлов, к которым применяется сигнатура, и предикаты, которым должно удовлетворять разобранное дерево. Сигнатура совпадает с файлом, имя которого соответствует одному из её шаблонов файлов — или, если она не объявляет ни одного, с источником, представляющим собой один файл, как бы он ни назывался, — байты которого разбираются в её синтаксисе и разобранное дерево которого удовлетворяет каждому из её предикатов. С каталогом она совпадает, если совпадает с одним из файлов каталога, выбранных её шаблонами, поэтому сигнатура без шаблонов не совпадает ни с одним каталогом.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
syntax | string | да | Синтаксический формат, в котором разбирается источник, — например, json или yaml; это формат, который плагин-парсер объявляет как parse: |
files | string[] | нет | Шаблоны имён файлов, к которым применяется сигнатура; они сопоставляются с концом имени источника, разделители в котором читаются как прямые косые черты: шаблон из одного сегмента сопоставляется с собственным именем файла, а шаблон из нескольких сегментов, разделённых косой чертой, — с таким же числом последних сегментов его пути, поэтому .vscode/mcp.json совпадает с файлом mcp.json в каталоге .vscode. Внутри сегмента * соответствует любой последовательности символов, ? — одному символу, а […] — одному символу из класса. Сигнатура применяется, когда совпадает любой шаблон. Некорректный шаблон отклоняется при загрузке. Отсутствие или пустой список применяет сигнатуру к источнику, представляющему собой один файл, как бы он ни назывался, и ни к одному файлу каталога. Шаблоны сигнатур импортёра также определяют, какие файлы каталога передаёт ему импорт. |
match | PathMatch[] | нет | Предикаты, которым должно удовлетворять разобранное дерево, — все без исключения, в объявленном порядке. Отсутствие или пустой список не требует от дерева ничего, кроме успешного разбора в этом синтаксисе. |
Дополнительные свойства не допускаются.
PathMatch
Один предикат над разобранным деревом: значение, на которое указывает путь, вид, которым должно быть это значение, и, необязательно, строка, которой оно должно быть равно или с которой должно начинаться.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
path | string | да | Место в дереве, которое проверяет предикат, записанное как ключи, соединённые точками, от вершины дерева: data.nodes указывает член nodes объекта data верхнего уровня. Сегмент, записанный целым числом, 0 или больше, выбирает эту позицию массива, считая с нуля, поэтому nodes.0.type указывает type первого узла; каждый другой сегмент выбирает член объекта. Ключ, который сам содержит точку, указать нельзя. Длина не менее 1 символа. |
is | string (enum) | да | На что должен указывать путь: present выполняется, когда путь указывает на значение любого вида, включая null; absent выполняется, когда путь ни на что не указывает; object, array, string, number и boolean выполняются, когда путь указывает на значение соответствующего вида. Допустимые значения: "present", "absent", "object", "array", "string", "number", "boolean" |
equals | string | нет | Строка, которой должно точно равняться значение, на которое указывает путь. Значение, не являющееся строкой, никогда ей не равно. В одном предикате объявляется не более одного из equals и prefix, и предикат, объявляющий оба, отклоняется при загрузке. Длина не менее 1 символа. |
prefix | string | нет | Строка, с которой должно начинаться значение, на которое указывает путь. Значение, не являющееся строкой, никогда с неё не начинается. В одном предикате объявляется не более одного из equals и prefix, и предикат, объявляющий оба, отклоняется при загрузке. Длина не менее 1 символа. |
Дополнительные свойства не допускаются.