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

Схема конфигурации рабочего пространства Aggrega

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

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

Файл конфигурации рабочего пространства, который читает CLI aggrega. Располагается в .aggrega-config.yaml. Блок workspace служит маркером корня: его наличие отмечает корень рабочего пространства, и он содержит только каталоги каталогов. Каждый другой ключ является настройкой и располагается на верхнем уровне в следующих классах: откуда содержимое загружается, как закрепляется и кэшируется (выбор реестра, автономный режим, поведение автоматической загрузки и закрепления, расположение кэшей артефактов и скомпилированных модулей и ограничения их размера), как устанавливается доверие к содержимому (подписывание и поведение проверки подписей), насколько строго оценивается авторинг (настройки lint для каждого правила, строгость в отношении устаревших элементов и подсказка о релизе для авторинга), какие Wasm-плагины подключены ко всему рабочему пространству (привязки governance, linter, importer и привязки отрисовки провайдером для каждой цели) и как работает CLI (параллелизм, обслуживание и ограничения вытеснения кэша разбора демона). Приведённые ниже свойства образуют полный и авторитетный список; это описание называет классы, а не ключи, поэтому добавление ключа не может сделать его неверным. Плоская структура верхнего уровня, без оболочки apiVersion/kind, отличная от содержимого каталога. Порядок развития схемы: добавление нового ключа верхнего уровня является повышением SemVer-MINOR (аддитивным); удаление или перемещение ключа либо ужесточение ограничения является несовместимым изменением SemVer-MAJOR.

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

Свойства

СвойствоТипОбязательноОписание
workspaceobjectнетМаркер корня рабочего пространства. Одно его присутствие отмечает каталог как корень рабочего пространства; он содержит только определяющие корень каталоги каталогов — собственные каталоги рабочего пространства и те, что даны какой-либо сущности Release как её собственные. Каждый параметр, не определяющий корень, находится на верхнем уровне, а не здесь. Напишите workspace: {}, чтобы отметить корень без вендоренных каталогов.
default_registrystringнетРеестр OCI по умолчанию, в который публикуются сущности и из которого разрешаются зависимости, когда сущность не указывает реестр явно: aggrega push публикует туда, а aggrega pull загружает оттуда. По умолчанию hub.aggrega.ai. Укажите name записи из registries, который тогда обозначает host этой записи; сам хост; или хост, за которым следуют / и путь репозитория, например ghcr.io/acme или harbor.example.com/platform. Сначала сопоставляется имя: значение, являющееся name одной записи, означает хост этой записи, даже если оно также записано как хост, поэтому публикация, загрузка, проверка подписи и все параметры доверия для отдельного реестра используют этот один хост; значение, которым названы две записи, отклоняется как неоднозначное, а имя, за которым следует путь, отклоняется, потому что имя обозначает хост записи, а не расположение внутри него. Любое другое значение должно быть хостом, записанным в том написании, под которым хранится его политика доверия: имя хоста в нижнем регистре, содержащее точку (registry.example.com), localhost, одиночное имя с портом (registry:5000), адрес IPv4 или адрес IPv6 в скобках ([::1]), каждое с необязательным :port и без схемы, учётных данных, пробелов и заглавных букв — с необязательным путём репозитория: один или несколько сегментов из строчных букв и цифр, соединённых через /, которые внутри сегмента могут разделяться ., _, __ или дефисами, без тега, дайджеста и завершающего /. Путь определяет, где публикуется и откуда загружается содержимое: каждая сущность, публикуемая через реестр по умолчанию, публикуется под <host>/<path>/, и каждая сущность, разрешаемая через него, загружается оттуда, поэтому опубликованное одним находит другой. Путь никогда не участвует в определении доверия к реестру: запись registries, политика которой применяется, вход в систему, требование подписи и доверенные идентичности определяются только по хосту. Порт 443 на хосте, доступном по HTTPS, является портом этого хоста по умолчанию, и его указание отклоняется с указанием написания без него; localhost и другие loopback-адреса доступны по обычному HTTP, поэтому там 443 — обычный порт и сохраняется. Пустое значение не задаёт реестр по умолчанию. Значение проверяется при загрузке конфигурации, а не этой схемой, поскольку запись, на которую ссылается имя, может быть объявлена в другом файле конфигурации: оно читается после всех файлов конфигурации и переменной окружения AGGREGA_DEFAULT_REGISTRY и отклоняется одинаковыми словами, какой бы из них его ни задал, с указанием этого файла или переменной. Флаг --registry, задающий место назначения публикации для одного вызова, сопоставляется с именами записей так же; любое другое его значение может быть ссылкой, и хост, который называет эта ссылка, подчиняется тем же требованиям к написанию и является местом, куда попадает публикация, без пути репозитория. Хост проверяется только по написанию: разрешается ли имя и отвечает ли там реестр, не проверяется. По умолчанию: "hub.aggrega.ai"
offlineлогическаянетЕсли true, сборка не обращается ни к одному реестру; используются только кэшированные артефакты и вендоренное содержимое каталогов. По умолчанию false. По умолчанию: false
auto_pullлогическаянетЕсли false (по умолчанию), aggrega build работает только на чтение: он никогда не записывает закрепления источников, а отсутствующий или неполный lock-файл для релиза явно останавливает сборку с диагностикой, предлагающей сначала выполнить aggrega pull --release <release>. Если true, aggrega build перед сборкой выполняет шаг загрузки внутри процесса — разрешая зависимости сущности Release в lock-файл и кэш, — поэтому первая сборка для сущности Release не требует явного шага загрузки. Тот же разовый вариант доступен в командной строке как aggrega build --auto-pull; pull остаётся единственным, кто записывает lock-файл. offline: true не отключает шаг загрузки: он выполняется по тому, что уже есть на машине, — кэшу и локальным каталогам — без обращения к реестру, а ссылка, которой нет ни там, ни там, останавливает сборку собственным отказом загрузки с указанием этой ссылки. По умолчанию: false
pin_sources_at_pullлогическаянетЕсли false (по умолчанию), загрузка не записывает закреплений рядом с сущностью: для сущности Recipe или FeatureRecipe в одном из каталогов этого рабочего пространства, которую собирает сущность Release, она останавливается, если entity.lock рядом с сущностью не содержит закрепления для каждого входа, который читает сущность, — удалённого source: с полностью указанными координатами, файла, импортируемого записью artifacts, или каждого файла локального source: рядом с сущностью, — с указанием сущности, каждого входа и его класса, а также aggrega pin как шага, который их записывает. Закрепление — шаг автора сущности, поэтому сущность, которую никто не закрепил, ещё не готова к использованию. Если true, каждая загрузка в этом рабочем пространстве вместо этого выполняет этот шаг для тех же сущностей, записывая те же байты entity.lock, что записывает aggrega pin; так рабочее пространство, использующее сущности, которые кто-то другой не закрепил, однократно записывает их закрепления вместо остановки. Сборка, заполняющая собственный lock-файл, является загрузкой и следует этому параметру. aggrega pull --pin-sources закрепляет для одного вызова, а --pin-sources=false останавливает для одного вызова, независимо от этого параметра. Сущность, разрешённая из кэша, а не из каталога, не имеет места для записи lock-файла и никогда не закрепляется и не задерживается загрузкой. По умолчанию: false
pin_sources_at_pushлогическаянетЕсли true, каждый aggrega push в этом рабочем пространстве выполняет шаг закрепления автора сущности для публикуемой сущности перед её упаковкой, поэтому entity.lock, который этот шаг записывает рядом с сущностью, входит в публикуемое; если false (по умолчанию), push не выполняет шаг закрепления и отклоняет сущность Recipe или FeatureRecipe, чей entity.lock не содержит всех закреплений, которые записал бы этот шаг, с указанием aggrega pin. Шаг записывает рядом с сущностью, поэтому выполняется только там, где у сущности есть доступное для записи место, а у push оно есть всегда: он публикует сущность, названную её документом. aggrega push --pin-sources закрепляет для одного вызова, а --pin-sources=false — нет, независимо от этого параметра. Это тот же шаг, что выполняет aggrega pin, записывающий те же байты. По умолчанию: false
artifact_cache_dirstringнетЛокальный каталог кэша артефактов и содержимого (загрузки из реестров, манифесты OCI, скомпилированные фикстуры). По умолчанию .aggrega/cache. По соглашению следует добавлять в gitignore. Путь интерпретируется относительно корня рабочего пространства, откуда бы ни запускалась команда; абсолютное значение отклоняется при загрузке конфигурации, поскольку каждый, кто читает этот параметр, разрешает его относительно этого корня, и абсолютный путь указывал бы на место, до которого они никогда не доходят. Кэш может находиться внутри каталога каталогов — значение по умолчанию так и делает, поскольку каталог часто является корнем рабочего пространства, — но не должен САМ БЫТЬ им: сканирование каталога пропускает кэш, поэтому значение, указывающее на каталог, исключает из сканирования всё его содержимое. Значение, указывающее на сам корень рабочего пространства (. или любое написание, сводящееся к нему), отклоняется при загрузке конфигурации именно по этой причине. Значение, указывающее на любой другой каталог, не отклоняется: оно загружается без ошибок, а сканирование затем ничего не находит в этом каталоге, поэтому следить за тем, чтобы кэш не находился в каталогах, перечисленных в workspace.catalog_dirs, должны вы. Отличается от parse_cache, который ограничивает кэш разбора демона в памяти, и от compiled_module_cache, который ограничивает общее для машины хранилище скомпилированных модулей. По умолчанию: ".aggrega/cache"
skip_signature_verificationлогическаянетГлобальное явное отключение проверки подписей. Если true, проверка подписей отключается для всех реестров, включая обязательный базовый уровень hub. Предназначено для аварийных сценариев и разработки; отключение никогда не происходит незаметно — везде, где pull проверил бы подпись, он предупреждает, что проверка глобально отключена. По умолчанию false. По умолчанию: false
buildobjectнетНастройки строгости на этапе сборки и подсказки для авторов. authoring_release передаёт LSP подсказку current Release для встроенной диагностики; halt_on_deprecated_severity определяет, как сборка реагирует на использование устаревших сущностей; yaml_indent задаёт ширину отступа для каждого генерируемого YAML-артефакта.
pluginsobjectнетПодключения Wasm-плагинов на уровне рабочего пространства. Каждый сокет (governance, linter, importer) принимает массив ссылок на плагины; сборка вызывает документированную входную функцию каждого плагина в соответствии с контрактом его сокета. Список providers связывает возможности с плагинами рендеринга провайдеров, которые их обслуживают.
lintobjectнетНастройки строгости для отдельных правил.
parse_cacheobjectнетОграничения вытеснения для кэша разбора демона. Оба ограничения действуют одновременно — цикл вытеснения LRU запускается после каждой вставки в кэш и удаляет наименее недавно использованные записи, пока и число записей, и общий объём в байтах не окажутся в пределах ограничений. Ноль в любом из них означает unbounded on that axis, что полезно для сценариев CI, где кэш существует только в течение одного вызова. Не путать с artifact_cache_dir — кэшем содержимого на диске.
compiled_module_cacheobjectнетОграничение размера дискового кэша скомпилированных модулей — хранилища машинного кода, которое компилятор использует повторно, чтобы Wasm-плагин компилировался один раз на машину, а не при каждой сборке. Кэш общий для всех рабочих пространств на машине, поэтому этот ключ следует указывать в глобальном файле конфигурации, если вам нужно одно значение для всей машины. Ограничение применяется один раз за вызов, до загрузки любого плагина: целые записи удаляются, начиная с самых давно скомпилированных, пока остаток не уложится в ограничение, — и никогда во время компиляции в ходе сборки. Удаление записи стоит лишь последующей перекомпиляции, поэтому ограничение можно безопасно уменьшать. aggrega cache status сообщает текущий размер хранилища, а aggrega cache evict --max-size по запросу сокращает его до ограничения, заданного в командной строке. Не путать с artifact_cache_dir (загруженное из реестров содержимое) и с parse_cache (кэш разбора демона в памяти).
concurrencyobjectнетНастройки параллелизма диспетчеризации запросов демона. Демон читает запросы из единого потока stdin и обрабатывает каждый через пул рабочих потоков, разбирающий ограниченную очередь запросов; ответы выдаются в порядке поступления запросов независимо от порядка их завершения.
serveobjectнетНастройки поведения демона (aggrega serve) — компилятора как сервиса, используемого интеграциями с IDE.
mcpobjectнетНастройки сервера Model Context Protocol (aggrega mcp). transport выбирает способ обращения к серверу — через стандартные ввод и вывод процесса или через HTTP — и читается при любом выборе. announce_tools также читается на обоих транспортах, поскольку набор инструментов, предлагаемых клиенту, — свойство сервера, а не способа, которым клиент к нему обратился. Все остальные ключи настраивают слушатель, запускаемый HTTP-транспортом, и не используются, пока сервер работает через стандартные ввод и вывод, — включая listen, который в этом случае читается лишь для того, чтобы сервер мог одной строкой в потоке ошибок сообщить, что адрес не используется. Для каждого ключа ниже указано, к какой группе он относится. Не путать с serve, который настраивает демон-бэкенд для редактора.
registriesRegistryConfig[]нетНастройки для отдельных реестров и политика доверия подписям, с ключом по хосту реестра. Реестр, не указанный здесь, использует значения по умолчанию: имеющаяся подпись проверяется, а отсутствие подписи допускается, за исключением hub.aggrega.ai, встроенный базовый уровень которого требует проверенной подписи даже без явной записи. Явная запись для хоста переопределяет базовый уровень этого хоста. По умолчанию: []
signingSigningConfigнетБлок подписи верхнего уровня, применяемый ко всем реестрам: URL-адреса сервисов бесключевой подписи, необязательный путь к ключу для подписи с ключом и позиция доверия для всех реестров (required и kinds). Блок signing отдельного реестра переопределяет конечные точки по умолчанию для этого хоста и несёт ту же позицию required/kinds, ограниченную этим хостом, — одно имя, одна задача, область действия определяется расположением. Политика required/kinds верхнего уровня монотонно объединяется по каскаду конфигураций. Безопасность: этот блок не содержит секретных данных — токен идентификации OIDC никогда не является полем конфигурации (он передаётся во время выполнения через флаг или окружение OIDC), а key_path — это путь к файлу ключа, а не байты ключа непосредственно.

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

aggrega-config.workspace

Маркер корня рабочего пространства. Одно его присутствие отмечает каталог как корень рабочего пространства; он содержит только определяющие корень каталоги каталогов — собственные каталоги рабочего пространства и те, что даны какой-либо сущности Release как её собственные. Каждый параметр, не определяющий корень, находится на верхнем уровне, а не здесь. Напишите workspace: {}, чтобы отметить корень без вендоренных каталогов.

СвойствоТипОбязательноОписание
catalog_dirsstring[]нетНеобязательные каталоговые директории, из которых это рабочее пространство читает локальные сущности, прежде чем обратиться к реестру. Каждая запись — путь в файловой системе, разрешаемый относительно файла, в котором она объявлена. Список — упорядоченный стек поиска, где побеждает первое совпадение: идентичностью владеет директория, указанная раньше всех из объявляющих её, а та же идентичность в более поздней директории затеняется. Директория catalog в корне рабочего пространства тоже читается — после всех перечисленных записей и только если она существует, — если только перечисленная запись уже не содержит её, и тогда она читается как часть этой записи; поэтому перечисление директории дополняет то, что рабочее пространство уже читало, а не заменяет его. Отсутствие этого ключа и запись его пустым списком означают разное: без ключа рабочее пространство по-прежнему читает catalog; при записи [] оно не читает никакого локального каталога — так рабочее пространство сообщает, что каталога у него нет. Release, которому в releases заданы собственные каталоговые директории, читает их вместо этого списка. Область действия — корень: локальные каталоговые директории принадлежат этому корню рабочего пространства, поэтому они находятся в маркере корня, а не на верхнем уровне.
catalog_dirs_appendstring[]нетНеобязательное дополнение (только добавление) к итоговому списку catalog_dirs. На каждом уровне приоритета указанные здесь записи присоединяются к разрешённому базовому списку, позволяя конфигурациям рабочего пространства и глобальной конфигурации объединять каталоговые директории, а не затенять их. Взаимодействие на одном уровне: если на одном уровне заданы и catalog_dirs, и catalog_dirs_append, разрешённое значение на этом уровне — базовый список, за которым следует список добавления. Значение по умолчанию: []
releasesmap из ReleaseCatalogConfigнетНеобязательные собственные каталоговые директории для сущности Release — для рабочего пространства, которое хранит несколько вариантов каталога рядом и собирает каждый Release с одним из них. Каждый ключ — файл Release, записанный как путь относительно объявляющего его файла; каждое значение содержит catalog_dirs и catalog_dirs_append с тем же смыслом, что и в этом блоке, но в области действия одного этого Release. Release, указанный здесь, читает свой catalog_dirs вместо списка этого блока, а затем свой catalog_dirs_append; запись без catalog_dirs сохраняет список этого блока и добавляет после него свой catalog_dirs_append. Порядок поиска, директория catalog в корне рабочего пространства и смысл пустого списка — те же, что и для собственного списка этого блока, а Release, не указанный в этой карте, читает список этого блока точно так же, как прежде. Release читает эти директории при любом способе сборки — в терминале, из редактора через aggrega serve или через aggrega mcp, — а директория --catalog по-прежнему просматривается перед ними в рамках одного вызова. Запись, указывающая на несуществующий файл, отклоняется при загрузке конфигурации с указанием записи и файла, поэтому переименование Release не может незаметно изменить каталог, с которым он собирается. Между файлами конфигурации запись каждого Release объединяется так же, как собственные ключи этого блока: catalog_dirs для этого Release из более близкого файла заменяет значение из более дальнего, а catalog_dirs_append для него из каждого файла добавляется в порядке каскада. AGGREGA_CATALOG_DIRS задаёт список этого блока и не затрагивает записи здесь. Операция, не относящаяся к одному Release, — проверка линтером или валидация всего каталога, поиск сущности по имени или перечисление сущностей рабочего пространства редактором, — читает список этого блока, а не эти.

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

aggrega-config.build

Настройки строгости на этапе сборки и подсказки для авторов. authoring_release передаёт LSP подсказку current Release для встроенной диагностики; halt_on_deprecated_severity определяет, как сборка реагирует на использование устаревших сущностей; yaml_indent задаёт ширину отступа для каждого генерируемого YAML-артефакта.

СвойствоТипОбязательноОписание
authoring_releasestringнетПуть к YAML-файлу Release, который LSP рассматривает как контекст current Release для встроенной диагностики. Необязательно.
yaml_indentintegerнетШирина отступа (в пробелах) для каждого отрисованного YAML-артефакта — файлов docker-compose, шаблонов и values чартов Helm и манифестов Kubernetes. По умолчанию 2 — общепринятая ширина для этих форматов. Минимум: 2. Максимум: 9. Значение по умолчанию: 2
halt_on_deprecated_severitystring (enum)нетУровень серьёзности в упорядоченном наборе warning < error < retracted, начиная с которого записанный маркер устаревания останавливает сборку. Он действует в обоих местах, где записывается маркер: в lock-файле — для всего, что сборка воспроизводит байт в байт, и в записи доверия к плагинам рядом с ним — для плагина, подключённого в роли, возвращающей вердикт «принять или отклонить»: подключения plugins.governance на ir-verdict или render-verdict и любого подключения plugins.linter. Один регулятор, одно правило, оба хранилища. По умолчанию не задан, и это означает, что ни один записанный маркер не останавливает сборку: маркер записывается для версии, которую вы уже закрепили, поэтому сборка, однажды завершившаяся успешно, продолжает завершаться успешно. Уведомление и разрешение — две отдельные оси, и ни одна из них не является этим регулятором. Каждая поверхность, читающая любую из записей, сообщает о каждой закреплённой ею устаревшей ссылке и каждом доверенном плагине с маркером — при любом уровне серьёзности, — указывая его, его уровень и сообщение: aggrega build, aggrega validate --release, aggrega lint --release, демон для редакторов и AI-инструменты build, describe и validate. Поэтому повышение этого порога никогда не уменьшает объём сообщаемого вам. Этот регулятор управляет только сборкой: он останавливает aggrega build (и AI-инструмент build, который выполняет ту же операцию), тогда как поверхности отчётности называют маркер и продолжают работу. Только маркер retracted влияет на то, в какую версию разрешается ссылка, и делает это, когда aggrega pull выбирает версию, а не при сборке. Допустимые значения: "warning", "error", "retracted"

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

aggrega-config.plugins

Подключения Wasm-плагинов на уровне рабочего пространства. Каждый сокет (governance, linter, importer) принимает массив ссылок на плагины; сборка вызывает документированную входную функцию каждого плагина в соответствии с контрактом его сокета. Список providers связывает возможности с плагинами рендеринга провайдеров, которые их обслуживают.

СвойствоТипОбязательноОписание
governancePluginRef[]нетПлагины сокета governance. Каждая запись называет роль конвейера role, в которой подключён плагин (annotation-transform, label-transform, ir-verdict или render-verdict); роль определяет и то, что плагин может выдавать, и его функцию входа по умолчанию (annotation-transform → transform_annotations; label-transform → mutate; ir-verdict → verdict_ir; render-verdict → verdict_render). По умолчанию: []
governance_appendPluginRef[]нетДополнение к действующему списку governance, допускающее только добавление. Записи отсюда присоединяются к разрешённому базовому списку на каждом уровне приоритета, так что конфигурации рабочего пространства и глобальная конфигурация объединяют подключения governance, а не затеняют их. По умолчанию: []
linterPluginRef[]нетПлагины сокета linter. Функция входа по умолчанию: lint_rules. Экспорты плагина-линтера должны начинаться с lint_, поэтому function: в такой записи называет экспорт с этим префиксом. По умолчанию: []
linter_appendPluginRef[]нетДополнение к действующему списку linter, допускающее только добавление. Та же семантика «объединять, а не затенять», что и у governance_append. По умолчанию: []
importerFixedEntryPluginRef[]нетПлагины сокета importer. Сокет вызывает функцию входа import; подключение её не называет. По умолчанию: []
importer_appendFixedEntryPluginRef[]нетДополнение к действующему списку importer, допускающее только добавление. Та же семантика «объединять, а не затенять», что и у governance_append. По умолчанию: []
providersFixedEntryPluginRef[]нетВыбор провайдера для каждой возможности. Каждая запись связывает одну возможность провайдера (голое имя возможности, которое Recipe связывает через spec.capability, например helm или compose) с голой идентичностью плагина рендеринга провайдера, который её обслуживает (идентичность сущности Plugin — её metadata.pluginType и metadata.name, соединённые косой чертой, например provider/helm), с необязательным завершающим :version в тех же трёх формах, что и закрепление версии (голая, точная :1.0.0 или диапазон совместимости по мажорной версии :^1.0.0). Это поверхность разрешения неоднозначности и переопределения для федеративного каталога, где одну возможность обслуживают несколько плагинов провайдеров: связывание выбирает, плагин какого издателя рендерит эту возможность. Когда возможность обслуживает ровно один плагин провайдера, запись не нужна. Во всём объединённом списке допускается ровно одна запись на возможность; повторяющаяся возможность явно останавливает разрешение. Разрешение происходит при pull: pull записывает разрешённое связывание в lockfile конкретной сущности Release, а сборка читает lockfile — изменение здесь после pull не применяется до следующего pull, поэтому вывод сборки от него не зависит (детерминированный вывод). Каждая сборка и каждая валидация сущности Release также проверяет каждую запись здесь, независимо от того, запрашивает ли её возможность какой-либо Recipe: запись, называющая имеющийся у сборки плагин, который не обслуживает возможность записи, останавливает сборку с указанием того, что этот плагин обслуживает, и написания на расстоянии одной правки, если такое есть; запись, называющая возможность без плагина, когда ни один плагин провайдера, читаемый сборкой, эту возможность не обслуживает, выдаёт предупреждение, а не остановку, поскольку обслуживающий её плагин может читать только другая сущность Release; а запись для возможности, которую обслуживает плагин, но которую эта сущность Release никогда не запрашивает, допустима и ничего не сообщает, так как записи пишутся для всего рабочего пространства, а сборка относится к одной сущности Release. Значение capability, содержащее двоеточие, отклоняется при загрузке конфигурации: spec.capability сущности Recipe читается как возможность до последнего двоеточия и закрепление версии после него, поэтому ни один Recipe не смог бы обратиться к такой записи. Отсутствие записи для однозначно обслуживаемой возможности не является ошибкой; отсутствие записи для неоднозначно обслуживаемой возможности явно останавливает pull с перечислением плагинов-кандидатов. Сосуществование версий сохраняется: связывание выбирает репозиторий плагина для каждой возможности, а собственное закрепление версии в spec.capability каждого Recipe выбирает версию в этом репозитории, поэтому два Recipes, закрепляющие разные версии одного провайдера, по-прежнему сосуществуют. По умолчанию: []
providers_appendFixedEntryPluginRef[]нетДополнение к действующему списку providers, допускающее только добавление. Записи отсюда присоединяются к разрешённому базовому списку на каждом уровне приоритета, так что конфигурации рабочего пространства и глобальная конфигурация объединяют связывания провайдеров, а не затеняют их. Та же семантика «объединять, а не затенять», что и у governance_append. Правило «одна запись на возможность» применяется к объединённому списку, поэтому добавленная запись, называющая возможность, уже связанную на нижнем уровне, явно останавливает разрешение. По умолчанию: []
cliCLIPluginRef[]нетПлагины-расширения CLI, устанавливаемые как команды aggrega верхнего уровня. Каждая запись закрепляет один плагин CLI по его разрешённой ссылке на артефакт с закреплённой версией и по дайджесту содержимого гостевых байтов, в которые эта ссылка разрешилась при установке. В отличие от четырёх сквозных списков сокетов, чей базовый список целиком заменяется по каскаду конфигураций, список CLI объединяется: плагин CLI в глобальной конфигурации регистрирует свои команды в каждом рабочем пространстве, плагин в конфигурации рабочего пространства регистрируется только в этом проекте, и оба регистрируются вместе — поэтому парный _append не нужен. Имена команд и справка, которые вносит каждый плагин, берутся из собственного самоописания плагина, читаемого из дискового кеша describe с ключом digest (при холодном кеше запасным вариантом служит загрузка гостя); список хранит только закрепление. При вызове команды разрешённые байты хешируются заново и сравниваются с digest; несовпадение явно останавливает команду и требует перезакрепления, так что плагин, чьи байты изменились после закрепления, никогда не запускается незамеченным. По умолчанию: []

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

aggrega-config.lint

Настройки строгости для отдельных правил.

СвойствоТипОбязательноОписание
publishing_disciplineobjectнетОбщие для рабочего пространства пороги для набора правил линтера публикации. Флаги allow_* ослабляют отдельные проверки нежелательных практик. Неизменяемость артефактов здесь не настраивается: aggrega push безусловно отказывается перезаписывать опубликованную версию.

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

aggrega-config.lint.publishing_discipline

Общие для рабочего пространства пороги для набора правил линтера публикации. Флаги allow_* ослабляют отдельные проверки нежелательных практик. Неизменяемость артефактов здесь не настраивается: aggrega push безусловно отказывается перезаписывать опубликованную версию.

СвойствоТипОбязательноОписание
allow_dynamic_refsлогическаянетЕсли true, линтер публикации принимает конструкции JSON Schema $dynamicRef / $dynamicAnchor в содержимом каталога. По умолчанию false; эти конструкции не рекомендуются, поскольку делают композицию схем во время компиляции нелокальной. По умолчанию: false
allow_id_overridesлогическаянетЕсли true, линтер публикации принимает переопределения $id во вложенных схемах в содержимом схемы сущности. По умолчанию false; переопределения $id нарушают соглашение «один канонический идентификатор на схему», на которое опираются и резолвер, и валидатор JSON Schema. По умолчанию: false
allow_direct_x_aggrega_extensionsлогическаянетЕсли true, проверка нерекомендуемых конструкций во время сборки принимает ключевые слова x-aggrega-selector и x-aggrega-inject, написанные непосредственно в содержимом схемы. По умолчанию false; рекомендуемый способ — usesSchema (для сокетов зависимостей) или featuresSchema (для привязок учётных данных), которые компилятор составляет в эти ключевые слова. По умолчанию: false
allow_aggrega_ai_prefixлогическаянетЕсли true, линтер публикации принимает ключи аннотаций с зарезервированными пространствами имён aggrega.ai/ и feature.aggrega.ai/ вне их канонических контекстов. Правило зарезервированных префиксов контролирует metadata.annotations сущностей каталога: голый префикс aggrega.ai/ принадлежит платформе (общеизвестные ключи аннотаций освобождены от проверки независимо от этого флага); префикс feature.aggrega.ai/ каноничен только для вида Feature. По умолчанию false. Операторы устанавливают этот флаг, когда корпоративным инструментам обоснованно требуется зарезервированный префикс; флаг ослабляет оба префикса одновременно. По умолчанию: false
allow_nonstandard_namesлогическаянетЕсли true, линтер публикации принимает имена сущностей каталога, не следующие документированным соглашениям об именовании проекта. По умолчанию false; единообразное именование важно для резолвера, выбора по меткам и удобства рецензентов. По умолчанию: false
allow_category_mismatchesлогическаянетЕсли true, линтер публикации отключает правило соответствия категории каталогу. Соглашение стандартного каталога требует, чтобы сущности Components в core// объявляли component.aggrega.ai/category={category}, совпадающее с сегментом каталога, где {category} — одно из значений закрытого набора (например, ai-agent, ai-model, ai-tool, datastore, gateway, compute, …). Рабочие пространства с обоснованными постоянными исключениями отказываются от правила здесь. По умолчанию false. По умолчанию: false
allow_undeclared_recipe_providesлогическаянетЕсли true, линтер публикации отключает правило provides-declared-by-component. Это правило сообщает о каждом ключе, который сущность Recipe публикует в spec.provides, но который сущность Component, названная в её spec.implements, не объявляет в разделе provides своей spec.schema. Это две разные поверхности: то, что публикует Recipe, — значение, которое получает потребитель, а то, что объявляет Component, — выходной контракт, по которому проверяется ссылка inject from:, поэтому ключ, опубликованный без объявления, приводит к остановке на такой ссылке. В остальном Recipe, публикующая больше, чем объявляет её Component, принимается при сборке, поэтому замечание носит рекомендательный характер, а не является отказом в публикации. По умолчанию false. По умолчанию: false
allow_connection_credential_mismatchesлогическаянетЕсли true, линтер публикации отключает правило connection-credential-matches-target-key, которое aggrega lint --release применяет к названной сущности Release: к самой Release, к сущности Aggregate, которую она развёртывает, и к сущностям Components, используемым экземплярами этой Aggregate. Для каждого соединения, цель которого объявляет ключ, требуемый от вызывающих, правило сравнивает, на что ссылаются оба конца: учётные данные, предъявляемые соединением, и ключ, который цель хранит в своём слоте. Оно сообщает, если концы называют разные секреты или ключ объявлен только на одном конце, и никогда не приводит ни одно из значений. Ни один конец не видит вложений другого, поэтому они совпадают только за счёт дисциплины авторов — обычно один параметр питает оба, — а сборка принимает их в любом случае, поэтому замечание носит рекомендательный характер. Рабочее пространство, в котором концы намеренно различаются, отказывается от правила здесь. По умолчанию false. По умолчанию: false

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

aggrega-config.parse_cache

Ограничения вытеснения для кэша разбора демона. Оба ограничения действуют одновременно — цикл вытеснения LRU запускается после каждой вставки в кэш и удаляет наименее недавно использованные записи, пока и число записей, и общий объём в байтах не окажутся в пределах ограничений. Ноль в любом из них означает unbounded on that axis, что полезно для сценариев CI, где кэш существует только в течение одного вызова. Не путать с artifact_cache_dir — кэшем содержимого на диске.

СвойствоТипОбязательноОписание
max_entriesintegerнетОграничение числа кешированных результатов разбора. По умолчанию 1000. 0 отключает ось числа записей (вытеснение по числу записей не запускается). Минимум: 0. По умолчанию: 1000
max_bytesintegerнетОграничение суммарного размера в байтах документов, хранимых кешем. По умолчанию 100000000 (100 МБ). 0 отключает байтовую ось (вытеснение по объёму в байтах не запускается). Минимум: 0. По умолчанию: 100000000

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

aggrega-config.compiled_module_cache

Ограничение размера дискового кэша скомпилированных модулей — хранилища машинного кода, которое компилятор использует повторно, чтобы Wasm-плагин компилировался один раз на машину, а не при каждой сборке. Кэш общий для всех рабочих пространств на машине, поэтому этот ключ следует указывать в глобальном файле конфигурации, если вам нужно одно значение для всей машины. Ограничение применяется один раз за вызов, до загрузки любого плагина: целые записи удаляются, начиная с самых давно скомпилированных, пока остаток не уложится в ограничение, — и никогда во время компиляции в ходе сборки. Удаление записи стоит лишь последующей перекомпиляции, поэтому ограничение можно безопасно уменьшать. aggrega cache status сообщает текущий размер хранилища, а aggrega cache evict --max-size по запросу сокращает его до ограничения, заданного в командной строке. Не путать с artifact_cache_dir (загруженное из реестров содержимое) и с parse_cache (кэш разбора демона в памяти).

СвойствоТипОбязательноОписание
max_bytesintegerнетОграничение объёма в байтах, который кеш скомпилированных модулей занимает на диске. По умолчанию 53687091200 (50 ГиБ) — потолок, останавливающий неограниченный рост, а не бюджет, который должен ощущаться: один скомпилированный плагин достигает сотен мегабайт, поэтому на машине, собирающей много версий плагинов, накапливаются гигабайты. Задавайте значение больше, чем компилирует одна сборка: ограничение применяется до того, как сборка что-либо компилирует, поэтому ограничение меньше рабочего набора одной сборки заставляет каждую сборку удалять и заново компилировать одни и те же модули, и хранилище перестаёт что-либо экономить. Поскольку ограничение применяется сначала, а затем сборка записывает скомпилированное, между сборками хранилище может превышать ограничение; оно снова урезается в начале следующей сборки. 0 отключает ограничение (хранилище растёт без предела, и ничего не удаляется автоматически). Поскольку хранилище — один каталог, общий для всех рабочих пространств, это ограничение не действует на уровне проекта, даже если его содержит собственный файл проекта: значение разрешается так же, как любой другой ключ, с приоритетом ближайшего файла, но у хранилища всё равно только один размер. Действует ограничение из последней сборки, поэтому два проекта с разными ограничениями применяют их по очереди, и низкое ограничение в одном удаляет машинный код, скомпилированный другим. Задать его один раз в глобальном файле конфигурации — способ получить одно значение для всей машины. aggrega config show --origin называет файл, из которого взято действующее значение каждого параметра. Минимум: 0. По умолчанию: 53687091200

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

aggrega-config.concurrency

Настройки параллелизма диспетчеризации запросов демона. Демон читает запросы из единого потока stdin и обрабатывает каждый через пул рабочих потоков, разбирающий ограниченную очередь запросов; ответы выдаются в порядке поступления запросов независимо от порядка их завершения.

СвойствоТипОбязательноОписание
pool_sizeintegerнетЧисло обработчиков, обслуживающих очередь запросов. По умолчанию 4: до четырёх запросов обрабатываются параллельно; установите 1, чтобы выполнять запросы последовательно в порядке поступления. Значение меньше 1 повышается до 1 при запуске демона. Минимум: 1. По умолчанию: 4

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

aggrega-config.serve

Настройки поведения демона (aggrega serve) — компилятора как сервиса, используемого интеграциями с IDE.

СвойствоТипОбязательноОписание
build_on_inspectлогическаянетВыполняет ли демон этап рендеринга артефактов при инспекции графа IR, чтобы рекомендательные сообщения, которые aggrega build выдаёт при рендеринге, также отображались как проблемы в редакторе. Никаких проверок, на которых сборка останавливается, это не добавляет. В любом случае ничего не записывается на диск — ни отрендеренных артефактов, ни выходного каталога, ни lock-файла, — а этап рендеринга никогда не изменяет граф, поэтому если инспекция возвращает граф, он в обоих случаях один и тот же. По умолчанию false, как у aggrega inspect: команда терминала не доходит до этапа рендеринга при инспекции графа, поэтому тоже не выдаёт таких сообщений, и инспекция в редакторе, которая их не выдаёт, показывает вам то же, что и терминал. Установите true, чтобы запросить у редактора этот дополнительный уровень. По умолчанию: false
lint_on_validateлогическаянетВыполняет ли демон проверку соглашений о публикации при валидации сущности каталога, чтобы замечания, которые aggrega lint сообщает об этой сущности, также отображались как проблемы в редакторе. Замечания носят рекомендательный характер: документ, к которому они относятся, всё равно проходит валидацию, а его Release по-прежнему разрешается и рендерится. Выполняется только проверка, читающая локальное содержимое, — реестр не опрашивается, ничего не загружается и ничего не записывается, — и она применяется к буферу, который держит редактор, а не к файлу на диске, поэтому исправленное вами имя перестаёт отображаться ещё до сохранения. По умолчанию false: сеанс редактора сообщает, корректен ли документ, и ничего не говорит о том, можно ли опубликовать сущность, пока вы не запросите этот второй уровень. Установите true, чтобы запросить его. Независимо от этого ключа редактор всегда может запросить проверку напрямую; так же выполняется и сравнение перед публикацией с ранее опубликованной версией. По умолчанию: false

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

aggrega-config.mcp

Настройки сервера Model Context Protocol (aggrega mcp). transport выбирает способ обращения к серверу — через стандартные ввод и вывод процесса или через HTTP — и читается при любом выборе. announce_tools также читается на обоих транспортах, поскольку набор инструментов, предлагаемых клиенту, — свойство сервера, а не способа, которым клиент к нему обратился. Все остальные ключи настраивают слушатель, запускаемый HTTP-транспортом, и не используются, пока сервер работает через стандартные ввод и вывод, — включая listen, который в этом случае читается лишь для того, чтобы сервер мог одной строкой в потоке ошибок сообщить, что адрес не используется. Для каждого ключа ниже указано, к какой группе он относится. Не путать с serve, который настраивает демон-бэкенд для редактора.

СвойствоТипОбязательноОписание
transportstring (enum)нетСпособ доступа к серверу: stdio использует протокол через стандартные ввод и вывод процесса — так к нему обращается клиент, запускающий команду как подпроцесс; http обслуживает его по HTTP на адресе, указанном в listen, и по HTTPS, если в tls указаны сертификат и ключ. aggrega mcp --transport stdio|http переопределяет этот ключ для одного вызова. По умолчанию stdio, поэтому рабочее пространство, в котором транспорт не указан, обслуживается через стандартные ввод и вывод, что бы ещё ни содержал этот блок, — слушатель запускается, только если выбран http, здесь или в командной строке. Любое другое значение отклоняется при загрузке конфигурации. Установите http в конфигурации сервера, к которому обращаются по сети, и оставьте ключ незаданным, если клиент сам запускает сервер: при выбранном stdio адрес в listen не используется, и сервер сообщает об этом одной строкой в поток ошибок. Допустимые значения: "stdio", "http" По умолчанию: "stdio"
listenstringнетАдрес, к которому привязывается слушатель, когда выбран транспорт HTTP. Он указывает, где слушать, и ничего не выбирает: транспорт выбирается в transport, а при выбранном stdio этот ключ не используется. Допускаются две формы: host:port для TCP-адреса и unix:, за которым следует путь в файловой системе, для Unix-сокета. aggrega mcp --listen <address> переопределяет этот ключ для одного вызова. По умолчанию пусто, а транспорту HTTP нужен адрес из одного или другого источника: если нет ни того, ни другого, запуск с этим транспортом отклоняется до какой-либо привязки. Адрес без шифрования — без сертификата и ключа в tls — допускается только на loopback (127.0.0.1, ::1 или localhost, разрешающийся в один из них) или на Unix-сокете; такую схему сервер использует, когда TLS завершает стоящий перед ним прокси. Любой другой адрес отклоняется до привязки с указанием mcp.tls.cert_file и mcp.tls.key_file. Те же две формы — единственно допустимые, с сертификатом или без, если задан authorization.trusted_proxy, поскольку заголовку можно доверять как учётным данным, только если установить его не может никто, кроме прокси. По умолчанию: ""
tlsobjectнетСертификат и ключ для завершения TLS внутри обслуживающего процесса. Задайте оба, чтобы обслуживать HTTPS непосредственно со слушателя, указанного в listen. Оставьте оба незаданными, чтобы обслуживать без шифрования; тогда listen ограничен loopback или Unix-сокетом — такую схему следует использовать, когда сертификат держит стоящий перед сервером прокси. Оба ключа — пути к файлам на диске; ни один не содержит ключевой материал непосредственно.
allowed_originsstring[]нетИсточники, допускаемые в заголовке Origin запроса. Запрос, заголовок Origin которого указывает источник, отсутствующий в этом списке, отклоняется с кодом 403; запрос с указанным в списке источником или вовсе без заголовка Origin обслуживается. Запись сравнивается с заголовком точно, поэтому каждая записывается так, как браузер отправляет источник: схема в нижнем регистре, ://, хост в нижнем регистре — имя, адрес IPv4 или адрес IPv6 в квадратных скобках — и : с портом, если он не является портом схемы по умолчанию, и ничего после этого. Например, https://app.example.com или http://localhost:3000. Запись в любом другом виде никогда не совпадёт с тем, что отправляет браузер, поэтому она отклоняется при загрузке файла конфигурации с указанием файла и записи: запись с завершающим / или путём (https://app.example.com/), запись без схемы (app.example.com) и запись, содержащая заглавную букву или пробел. По умолчанию пусто, поэтому ни один источник не допускается и обслуживается только вызывающая сторона, не отправляющая заголовок Origin. Поэтому браузерному клиенту нужно, чтобы его источник был указан здесь; клиент, не являющийся браузером, такого заголовка не отправляет и записи не требует. Каждая запись соответствует шаблону ^[a-z][a-z0-9+.-]*://(?:[a-z0-9._-]+|\[[0-9a-f:.]+\])(?::[0-9]{1,5})?$. По умолчанию: []
limitsobjectнетОграничения, которые слушатель HTTP применяет к принимаемому трафику, чтобы одна вызывающая сторона не могла исчерпать ресурсы обслуживающего процесса. Они ограничивают размер одного запроса, число одновременно выполняемых запросов и скорость, с которой может отправлять запросы одна вызывающая сторона. Ни одно из них нельзя отключить.
authorizationobjectнетЧто этот сервер объявляет о токенах носителя, которые предъявляют его вызывающие стороны: какой сервер авторизации их выдаёт, адрес, который этот сервер публикует для себя как ресурс, для которого они выдаются, при необходимости — файл, из которого читаются ключи проверки этого сервера, и при необходимости — заголовки, которые устанавливает прокси перед сервером, когда токены вместо него проверяет этот прокси. issuer и resource обязательны всякий раз, когда выбран транспорт HTTP, и без них запуск слушателя отклоняется до какой-либо привязки; сервер, работающий через стандартный ввод и вывод, ничего из этого не читает. Оба публикуются в документе метаданных защищённого ресурса OAuth, который отдаёт слушатель; это единственный ответ, который вызывающая сторона по HTTP получает без запроса учётных данных, потому что клиент читает его, чтобы узнать, где получить токен. Этот блок не содержит секретных данных: токен предъявляется вызывающей стороной в выполняемом ею запросе и никогда не является полем конфигурации, а jwks_file указывает открытые ключи проверки, а не что-либо, что подписывает.
deny_reachstring (enum)[]нетВиды охвата, которых этот сервер не допускает, что бы ни говорил токен вызывающей стороны. Каждая операция объявляет, как далеко распространяются её собственные последствия: none — для операции, которая читает или отрисовывает и ничего после себя не оставляет, workspace — для операции, которая пишет внутри рабочего пространства, обслуживаемого этим процессом, registry — для операции, которая публикует, подписывает или отзывает, и machine — для операции, которая изменяет то, что разделяют все рабочие пространства на хосте; указание вида здесь изымает из этого сервера все инструменты этого вида. Изъятый инструмент отсутствует в списке инструментов и в ответе describe-capabilities для любой вызывающей стороны, а его вызов всё равно отклоняется с указанием этой настройки, потому что никакая область действия не может его допустить. По умолчанию пусто, поэтому сервер допускает всё, что допускают области действия его вызывающих сторон. Это ограничение, которое сервер устанавливает сам для себя, поверх ограничения для каждой вызывающей стороны, задаваемого областями действия: сервер, который обслуживает только чтение, указывает здесь три пишущих вида и после этого не может публиковать даже для вызывающей стороны, токен которой содержит все области действия. Указание machine принимается и ничего не меняет: ни один инструмент этого вида вообще не предлагается по HTTP, и это свойство транспорта, а не настройка. Читается при запуске слушателя: значение вне этих четырёх отклоняется при загрузке конфигурации, а для его изменения требуется перезапуск. Вообще не читается, пока сервер работает через стандартный ввод и вывод, где вызывающая сторона — это человек, запустивший процесс. Допустимые значения для каждой записи: "none", "workspace", "registry", "machine". Значение по умолчанию: []
announce_toolsstring[]нетИнструменты, которые объявляет этот сервер, названные в точности так, как их сообщает список инструментов. Если опустить ключ, объявляются все инструменты этого сервера — именно этого ожидает клиент, следующий протоколу: он получает весь список инструментов и сам решает, какую его часть предоставить модели. Если задать список, объявляются ровно эти инструменты: не включённый в него отсутствует в списке инструментов, отсутствует в ответе describe-capabilities и отклоняется при вызове по имени с указанием этой настройки. Если задать пустой список, ничего не объявляется. Задавайте его там, где клиент на другой стороне ограничивает число регистрируемых инструментов (некоторые клиенты применяют это ограничение сразу ко всем серверам, к которым подключены), и указывайте инструменты, нужные этому клиенту. Он лишь сужает объявляемое и ничего более: он не может расширить ни deny_reach, который изымает возможность полностью, ни области действия, содержащиеся в токене вызывающей стороны. Указанный здесь инструмент того вида, который изымает deny_reach, остаётся вне списка инструментов и отклоняется при вызове с указанием той настройки; указанный здесь инструмент, который не допускают области действия вызывающей стороны, всё равно попадает в список, а его вызов отклоняется с указанием области действия, которая бы его допустила. Каждое имя должно принадлежать инструменту, имеющемуся в этом бинарном файле: имя, которому не соответствует ни один инструмент, отклоняется при запуске сервера, потому что иначе тот, кто запросил более узкий набор, получил бы другой, и ничто бы об этом не сообщило. Имя из семейства cli-, которое выполняет команду aggrega в отдельном процессе, принимается на обоих транспортах и ничего не объявляет по HTTP, где ни одной вызывающей стороне такой инструмент не предлагается. Читается на обоих транспортах при запуске сервера, поэтому объявленный набор фиксирован на всё время жизни процесса, а для его изменения требуется перезапуск.
healthobjectнетГде супервизор спрашивает, жив ли этот процесс и готов ли он отвечать на вызов. На обе проверки отвечает отдельный адрес и никогда — адрес, указанный в listen: каждый запрос к конечной точке несёт токен носителя, поэтому проба, на которую отвечали бы там, давала бы любому, кто может достичь конечной точки, неаутентифицированные сведения о процессе вместе со свободным способом заставить его работать. Конечная точка отвечает на /healthz и /readyz тем же 404, что и на любой путь, который она не обслуживает, — одинаково с токеном и без него.

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

aggrega-config.mcp.tls

Сертификат и ключ для завершения TLS внутри обслуживающего процесса. Задайте оба, чтобы обслуживать HTTPS непосредственно со слушателя, указанного в listen. Оставьте оба незаданными, чтобы обслуживать без шифрования; тогда listen ограничен loopback или Unix-сокетом — такую схему следует использовать, когда сертификат держит стоящий перед сервером прокси. Оба ключа — пути к файлам на диске; ни один не содержит ключевой материал непосредственно.

СвойствоТипОбязательноОписание
cert_filestringнетПуть к цепочке сертификатов PEM, которую предъявляет слушатель; читается при запуске процесса. Задаётся вместе с key_file. По умолчанию пусто, поэтому слушатель работает без шифрования, а listen ограничен loopback-адресом или сокетом Unix. Значение по умолчанию: ""
key_filestringнетПуть к закрытому ключу PEM для сертификата из cert_file; читается при запуске процесса. Задаётся вместе с ним. Путь к файлу, а не встроенные данные ключа. По умолчанию пусто, поэтому слушатель работает без шифрования, а listen ограничен loopback-адресом или сокетом Unix. Значение по умолчанию: ""

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

aggrega-config.mcp.limits

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

СвойствоТипОбязательноОписание
max_body_bytesintegerнетНаибольший размер тела запроса, который принимает слушатель, в байтах. Запрос, тело которого его превышает, отклоняется с 413, и тело не читается дальше предела. По умолчанию 4194304 (4 МиБ) — значительно больше вызова инструмента с целым авторским документом и значительно меньше того, что позволило бы одной вызывающей стороне занять существенную долю памяти процесса. Минимум равен 1, поэтому значения, отключающего предел, нет; увеличивайте его там, где вызывающие стороны обоснованно отправляют документы большего размера. Минимум: 1. Значение по умолчанию: 4194304
max_concurrent_requestsintegerнетСколько запросов слушатель выполняет одновременно. Запрос, поступивший, когда столько уже выполняется, отклоняется с 503, а не ставится в очередь, поэтому вызывающей стороне сообщается, что нужно повторить попытку, вместо ожидания за работой, которую она не видит. По умолчанию 16 — этого достаточно для нескольких одновременных вызовов инструментов при сохранении отзывчивости небольшого хоста; на более мощном хосте увеличьте значение. Минимум равен 1, поэтому значения, отключающего предел, нет. Минимум: 1. Значение по умолчанию: 16
requests_per_minuteintegerнетСколько запросов одна вызывающая сторона может отправить за минуту. Подсчёт ведётся для каждой вызывающей стороны, а не для сервера — по субъекту, указанному в токене вызывающей стороны, или по идентификатору, заявленному доверенным прокси, — поэтому одна загруженная вызывающая сторона не может израсходовать лимит другой. Вызывающая сторона может отправить столько запросов разом; затем лимит равномерно восполняется, по одному запросу каждые 60 / requests_per_minute секунд, а запрос, поступивший при исчерпанном лимите, отклоняется с 429. По умолчанию 120, то есть два в секунду устойчиво: намного больше, чем отправляет ассистент, управляющий рабочим пространством, и всё же ограничение для клиента, зациклившегося в работе. Минимум равен 1, поэтому значения, отключающего предел, нет. Минимум: 1. Значение по умолчанию: 120

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

aggrega-config.mcp.authorization

Что этот сервер объявляет о токенах носителя, которые предъявляют его вызывающие стороны: какой сервер авторизации их выдаёт, адрес, который этот сервер публикует для себя как ресурс, для которого они выдаются, при необходимости — файл, из которого читаются ключи проверки этого сервера, и при необходимости — заголовки, которые устанавливает прокси перед сервером, когда токены вместо него проверяет этот прокси. issuer и resource обязательны всякий раз, когда выбран транспорт HTTP, и без них запуск слушателя отклоняется до какой-либо привязки; сервер, работающий через стандартный ввод и вывод, ничего из этого не читает. Оба публикуются в документе метаданных защищённого ресурса OAuth, который отдаёт слушатель; это единственный ответ, который вызывающая сторона по HTTP получает без запроса учётных данных, потому что клиент читает его, чтобы узнать, где получить токен. Этот блок не содержит секретных данных: токен предъявляется вызывающей стороной в выполняемом ею запросе и никогда не является полем конфигурации, а jwks_file указывает открытые ключи проверки, а не что-либо, что подписывает.

СвойствоТипОбязательноОписание
issuerstringнетАдрес сервера авторизации, который выдаёт токены, принимаемые этим слушателем, записанный так, как этот сервер указывает собственный идентификатор издателя, — например, https://login.example.com. Он публикуется в списке authorization_servers документа метаданных защищённого ресурса; именно так клиент узнаёт, где получить токен для этого слушателя. По умолчанию пусто, и это значение непригодно: запуск слушателя отклоняется до какой-либо привязки, если здесь не указан полный адрес, включая схему и хост. Это адрес https, если только сервер авторизации не работает на этой же машине: простой http принимается только для loopback-хоста, такого как localhost, 127.0.0.1 или ::1, а издатель с простым http на любом другом хосте отклоняется до какой-либо привязки с указанием этого ключа и требованием адреса https. Это действует независимо от того, читаются ли ключи у издателя, из jwks_file или токены проверяет стоящий перед сервером trusted_proxy, потому что каждый клиент направляется к издателю за своим токеном. Значение по умолчанию: ""
resourcestringнетАдрес, который этот сервер публикует для себя, — такой, по которому к нему обращается вызывающая сторона, например https://mcp.example.com/mcp. Указывайте адрес, который вызывающие стороны используют на самом деле, включая хост, предъявляемый стоящим перед сервером прокси, потому что это идентификатор, который клиент передаёт серверу авторизации, запрашивая токен для этого сервера, и он публикуется без изменений как поле resource документа метаданных защищённого ресурса. Место, где отдаётся этот документ, выводится из него вставкой /.well-known/oauth-protected-resource между хостом и путём: сервер, опубликованный как https://mcp.example.com/mcp, отдаёт его по адресу https://mcp.example.com/.well-known/oauth-protected-resource/mcp, а также по этому well-known пути без продолжения — там клиент ищет во вторую очередь. Токен принимается, только если этот адрес входит в число указанных в нём аудиторий. По умолчанию пусто, и это значение непригодно: запуск слушателя отклоняется до какой-либо привязки, если здесь не указан полный адрес, включая схему и хост. Значение по умолчанию: ""
jwks_filestringнетПуть к файлу с набором JSON Web Key Set, по которому проверяются токены, принимаемые этим сервером; читается при запуске процесса. По умолчанию пусто, и это обычный случай: ключи читаются у самого сервера авторизации — у issuer запрашивается, где он их публикует, и они загружаются с указанного им адреса, а когда приходит токен, подписанный ключом с идентификатором, которого нет в имеющемся наборе, они перечитываются один раз. Задавайте это там, где рабочее пространство работает офлайн; в этом случае без него запуск слушателя отклоняется до какой-либо привязки, потому что офлайн-рабочее пространство не выполняет сетевых запросов и другого способа получить ключи нет; тогда файл содержит единственные принимаемые ключи, а к серверу авторизации обращений не происходит. Файл содержит открытые ключи проверки и никогда не содержит ничего, что подписывает. Относительный путь разрешается относительно каталога файла конфигурации, в котором он объявлен. Значение по умолчанию: ""
trusted_proxyobjectнетОпределять, кто такая вызывающая сторона, по заголовкам, которые устанавливает стоящий перед сервером прокси, вместо проверки токена носителя здесь. Задавайте это, только если выполняются оба условия: стоящий перед сервером прокси сам проверяет токены, и никто, кроме этого прокси, не может достичь слушателя: когда это задано, listen должен быть loopback-адресом или сокетом Unix, а любой другой адрес отклоняется до какой-либо привязки с указанием обеих настроек. Заголовку можно доверять ровно настолько, насколько можно доверять множеству вызывающих сторон, способных его установить, а на адресе, доступном из сети, любая вызывающая сторона может установить любой заголовок, поэтому слушатель в этом режиме на таком адресе позволил бы любой вызывающей стороне выдать себя за кого угодно. Когда это задано, токен вообще не читается — ни из заголовка Authorization, ни откуда-либо ещё, и набор ключей не загружается; идентификатор вызывающей стороны — это значение principal_header, на запрос без этого заголовка отвечается 401, и читаются только два указанных здесь заголовка. Если опустить его (это значение по умолчанию), этот сервер сам проверяет токены носителя.

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

aggrega-config.mcp.authorization.trusted_proxy

Определять, кто такая вызывающая сторона, по заголовкам, которые устанавливает стоящий перед сервером прокси, вместо проверки токена носителя здесь. Задавайте это, только если выполняются оба условия: стоящий перед сервером прокси сам проверяет токены, и никто, кроме этого прокси, не может достичь слушателя: когда это задано, listen должен быть loopback-адресом или сокетом Unix, а любой другой адрес отклоняется до какой-либо привязки с указанием обеих настроек. Заголовку можно доверять ровно настолько, насколько можно доверять множеству вызывающих сторон, способных его установить, а на адресе, доступном из сети, любая вызывающая сторона может установить любой заголовок, поэтому слушатель в этом режиме на таком адресе позволил бы любой вызывающей стороне выдать себя за кого угодно. Когда это задано, токен вообще не читается — ни из заголовка Authorization, ни откуда-либо ещё, и набор ключей не загружается; идентификатор вызывающей стороны — это значение principal_header, на запрос без этого заголовка отвечается 401, и читаются только два указанных здесь заголовка. Если опустить его (это значение по умолчанию), этот сервер сам проверяет токены носителя.

СвойствоТипОбязательноОписание
principal_headerstringдаЗаголовок, в который стоящий перед сервером прокси помещает идентификатор вызывающей стороны, — например, X-Forwarded-User. Записывается как имя заголовка HTTP: буквы, цифры и дефисы, а также другие символы, допустимые в имени заголовка (!#$%&'*+.^_|~ и обратный апостроф), без пробелов, двоеточий и других разделителей. Имя любой другой формы отклоняется при загрузке файла конфигурации с указанием файла и ключа, потому что ни один запрос не может нести такой заголовок. Пустое имя тоже отклоняется: при нём этот сервер продолжал бы сам проверять токены, тогда как блок говорит, что это делает стоящий перед ним прокси. Чтобы не включать этот режим, опустите trusted_proxy. Значение заголовка берётся в точности как записано и ни с чем не сравнивается — так же, как субъект токена, проверяемого самим сервером, записывается и ни с чем не сравнивается. В этом режиме это всё удостоверение, поэтому оно обязательно всякий раз, когда задан trusted_proxy, а на запрос без него отвечается 401. Шаблон: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+$.
scopes_headerstringнетЗаголовок, в который стоящий перед сервером прокси помещает предоставленные вызывающей стороне области действия, разделённые пробелами, — например, X-Forwarded-Scopes. Записывается как имя заголовка HTTP той же формы, что и principal_header, или остаётся пустым. Имя любой другой формы отклоняется при загрузке файла конфигурации с указанием файла и ключа, потому что ни один запрос не может нести такой заголовок и ни одной вызывающей стороне никогда не была бы предоставлена область действия. По умолчанию пусто, что не заявляет никаких областей действия ни для одной вызывающей стороны. Как бы он ни назывался, никакие заголовки, кроме этого и principal_header, не читаются. Шаблон: ^[!#$%&'*+.^_`|~0-9A-Za-z-]*$. Значение по умолчанию: ""

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

aggrega-config.mcp.health

Где супервизор спрашивает, жив ли этот процесс и готов ли он отвечать на вызов. На обе проверки отвечает отдельный адрес и никогда — адрес, указанный в listen: каждый запрос к конечной точке несёт токен носителя, поэтому проба, на которую отвечали бы там, давала бы любому, кто может достичь конечной точки, неаутентифицированные сведения о процессе вместе со свободным способом заставить его работать. Конечная точка отвечает на /healthz и /readyz тем же 404, что и на любой путь, который она не обслуживает, — одинаково с токеном и без него.

СвойствоТипОбязательноОписание
listenstringнетАдрес, на котором отвечают проверки живости и готовности, в тех же двух формах, что принимает listen: host:port или unix:, за которым следует путь в файловой системе. По умолчанию пусто, поэтому второй слушатель не запускается и ни на одну проверку нигде не отвечают. Если адрес задан, на GET /healthz отвечают 200 с момента запуска процесса, а на GET /readyz отвечают 503, пока рабочее пространство не разрешено и конечная точка не привязана, и 200 с этого момента — именно это различие нужно супервизору, поскольку запущенный процесс ещё не является процессом, способным отвечать на вызов. Каждый ответ — это код состояния с пустым телом, токен не запрашивается и никакие заголовки не читаются; любой другой путь на этом адресе даёт 404, а любой другой метод для этих двух путей — 405. В отличие от listen, этот адрес не ограничен loopback или сокетом Unix, и ни один адрес для него не отклоняется: укажите в нём один из них, для чего он и предназначен, и учтите, что всё, что может достичь выбранного вами адреса, может прочитать эти два ответа. По умолчанию: ""

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

Определения

ReleaseCatalogConfig

Собственные каталоги одной сущности Release: те же два ключа, что и в блоке workspace, с областью действия, ограниченной этой сущностью Release.

СвойствоТипОбязательноОписание
catalog_dirsstring[]нетКаталоги, из которых эта сущность Release читает локальные сущности вместо catalog_dirs рабочего пространства; каждый разрешается относительно файла, в котором он объявлен. Это тот же упорядоченный стек поиска по принципу «первый найденный побеждает», что и список рабочего пространства, причём каталог catalog в корне рабочего пространства читается после него, если этот каталог существует и ни одна из перечисленных записей его ещё не содержит. Если ключ опущен, Release сохраняет список рабочего пространства; если он записан как [], локальный каталог не читается вовсе.
catalog_dirs_appendstring[]нетКаталоги, добавляемые после списка этой сущности Release — её собственного catalog_dirs, если запись его задаёт, иначе списка рабочего пространства; каждый разрешается относительно файла, в котором он объявлен. Default: []

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

RegistryConfig

Настройки и политика доверия к подписям, относящиеся к одному хосту реестра OCI.

СвойствоТипОбязательноОписание
hoststringдаХост реестра, к которому применяются эти настройки (например, hub.aggrega.ai). Он сопоставляется с хостом реестра цели push/pull, поэтому записывается в том написании, в котором выполняется это сопоставление: имя хоста в нижнем регистре, содержащее точку, localhost, одиночное имя с портом (registry:5000), адрес IPv4 или адрес IPv6 в квадратных скобках — каждый с необязательным :port, без схемы, пути, учётных данных, пробелов и заглавных букв. Порт 443 на хосте, доступном по HTTPS, является портом этого хоста по умолчанию, и его указание отклоняется при загрузке конфигурации с указанием хоста, который следует записать без него, поскольку запись в таком написании никогда не была бы найдена; localhost и другие loopback-адреса доступны по обычному HTTP, поэтому 443 там — обычный порт и сохраняется. aggrega registry add и aggrega config init --registry создают запись под ключом хоста, указанного в их аргументе, и отклоняют хост, записанный иначе. Хост оценивается только по написанию: разрешается ли имя и отвечает ли там реестр, не проверяется. Шаблон: ^(?:(?:(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?|localhost|(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])(?:\.(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])){3}|\[(?:(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,7}:|(?:[0-9a-f]{1,4}:){1,6}:[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,5}(?::[0-9a-f]{1,4}){1,2}|(?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,3}|(?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,4}|(?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,5}|[0-9a-f]{1,4}:(?::[0-9a-f]{1,4}){1,6}|:(?:(?::[0-9a-f]{1,4}){1,7}|:))\])(?::(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?|[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?:(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))$.
namestringнетНеобязательный удобный псевдоним для этого реестра. Идентичностью служит хост; name — удобный селектор, который разрешается в хост этой записи везде, где указывается реестр (например, --registry или default_registry). Псевдоним должен быть уникальным среди всех записей.
trusted_identitiesTrustedIdentity[]нетНабор (по ИЛИ) бесключевых идентичностей подписи, принимаемых для артефактов, загружаемых из этого реестра. Подпись проходит проверку, если её сертификат соответствует любой одной записи. Используется путём бесключевой проверки. Default: []
trusted_deprecation_identitiesTrustedIdentity[]нетНабор (по ИЛИ) бесключевых идентичностей, которым дополнительно разрешено подписывать ретроактивную отметку об устаревании для артефакта, загруженного из этого реестра. Отметка об устаревании принимается, если её подпись соответствует подписанту исходного артефакта ИЛИ любой записи здесь — так владелец реестра или команда безопасности может отозвать артефакт, до которого исходный издатель больше не может дотянуться, не получая доверия на подпись самих артефактов. Используется только путём обнаружения устаревания; никогда не расширяет набор доверия для подписей артефактов. Default: []
public_keystringнетЗакреплённый открытый ключ, совместимый с cosign, для реестра в режиме с ключом, записанный прямо в значении как блок PEM: текст от строки -----BEGIN PUBLIC KEY----- (или -----BEGIN RSA PUBLIC KEY-----) до соответствующей ей строки -----END, в том виде, в каком его копирует из файла ключа aggrega registry add --key. Если задан, подписи из этого реестра проверяются офлайн по этому ключу, а не по бесключевым идентичностям. Значение без строки -----BEGIN … PUBLIC KEY----- отклоняется при загрузке файла конфигурации с указанием файла и записи; то же происходит с закрытым ключом, вставленным сюда по ошибке. Строка может находиться в любом месте значения, поскольку ключ читается из блока PEM, содержащегося в значении, а любой текст перед этим блоком игнорируется. Здесь проверяется только эта строка: содержит ли блок декодируемый ключ, выясняется, когда подпись из этого реестра проверяется по нему. Значение объявлено конфиденциальным (x-aggrega-sensitive), поэтому отклонённое значение — прежде всего закрытый ключ, выбранный по ошибке, — никогда не цитируется: в сообщении об отклонении указываются файл, запись и ограничение, которому значение не удовлетворило, — шаблон выше или строковый тип, — а на месте значения показывается <redacted>. Открытый ключ, который загружается, читается и показывается в том виде, в каком записан. Шаблон: -----BEGIN [A-Z ]*PUBLIC KEY-----.
trusted_rootstringнетНеобязательный путь к закреплённому пакету корня доверия Sigstore для бесключевой проверки в изолированной среде. Если задан, бесключевой якорь доверия загружается из этого файла без обращения к сети; если пуст, общедоступный корень доверия загружается и кэшируется.
advisoryлогическаянетЕсли true, ошибка проверки подписи для этого реестра понижается до предупреждения вместо остановки загрузки. Проверка по-прежнему выполняется, и об ошибке сообщается; загрузка продолжается. По умолчанию false. Default: false
skip_signature_verificationлогическаянетАварийный отказ от проверки подписей для отдельного хоста — тот же переключатель skip_signature_verification, что и глобальный, но благодаря размещению ограниченный этим хостом. Он не отменяет политику верхнего уровня signing.required: подпись, требуемая организацией, на этом хосте проверяется независимо от этого переключателя; отключить это может только глобальный переключатель. Его установка вместе с signing.required уровня реестра на том же хосте допустима и сочетает обязательную подпись при push с пропуском проверки при pull: на стороне проверки побеждает пропуск, поскольку требование на уровне хоста (в отличие от требования верхнего уровня) не защищено от пропуска на уровне хоста. По умолчанию false. Default: false
signingSigningConfigнетБлок подписи этого реестра: URL бесключевых сервисов, необязательный путь к ключу для подписи с ключом и позиция доверия для хоста. Поля конечных точек переопределяют глобальный блок signing для push на этот хост; флаг CLI переопределяет оба. required и kinds определяются размещением — в записи реестра они ограничивают единую позицию доверия этим хостом (публикация неподписанного артефакта из области действия отклоняется, как и использование неподписанного), это та же концепция, что и блок signing верхнего уровня для всех реестров.

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

SigningConfig

Блок подписи: URL-адреса сервисов бесключевой подписи, необязательный указатель на файл ключа для подписи с ключом и позиция доверия (required и kinds). Размещённый на верхнем уровне, он применяется ко всем реестрам; размещённый в записи registries[], он применяется к этому хосту — каждое поле определяет свою область действия по размещению. required — единая позиция доверия, охватывающая оба направления (неподписанная отправка в пределах области отклоняется, и неподписанное получение в пределах области отклоняется). Безопасность: блок не содержит секретных данных — токен идентичности OIDC никогда не является полем конфигурации (он кратковременный и передаётся во время выполнения), а key_path — это путь к файлу ключа, а не встроенные байты ключа. Это отражает асимметрию стороны проверки: там допускается встроенный public_key, но сторона подписи содержит только путь к ключу. Сервер aggrega mcp, доступный по HTTP, не обращается к key_path ни при одном размещении, поэтому подпись с ключом через такой слушатель недоступна: вызов, на который он отвечает, подписывается только токеном идентичности, который несёт этот вызов.

СвойствоТипОбязательноОписание
fulcio_urlstringнетURL удостоверяющего центра Fulcio для бесключевой подписи. Если не задан, используется общедоступный экземпляр Fulcio. Записывается как абсолютный URL https: https://, хост и, при необходимости, порт и путь, без пробельных символов — например, https://fulcio.sigstore.dev. Значение любой другой формы, например без схемы (fulcio.example.com) или начинающееся с http://, отклоняется при загрузке файла конфигурации с указанием файла и ключа. Файл проверяется до того, как поверх него применяется что-либо ещё, поэтому та же конечная точка, переданная через AGGREGA_SIGNING_FULCIO_URL, флагом --fulcio-url или в запросе на публикацию из редактора или ассистента, этой форме не обязана соответствовать. Шаблон: ^https://[^\s/?#]+(?:[/?#]\S*)?$.
rekor_urlstringнетURL журнала прозрачности Rekor для бесключевой подписи. Если не задан, используется общедоступный экземпляр Rekor. Записывается как абсолютный URL https: https://, хост и, при необходимости, порт и путь, без пробельных символов — например, https://rekor.sigstore.dev. Значение любой другой формы, например без схемы (rekor.example.com) или начинающееся с http://, отклоняется при загрузке файла конфигурации с указанием файла и ключа. Файл проверяется до того, как поверх него применяется что-либо ещё, поэтому та же конечная точка, переданная через AGGREGA_SIGNING_REKOR_URL, флагом --rekor-url или в запросе на публикацию из редактора или ассистента, этой форме не обязана соответствовать. Шаблон: ^https://[^\s/?#]+(?:[/?#]\S*)?$.
timestamp_urlstringнетURL службы меток времени RFC3161 для бесключевой подписи. Значения по умолчанию нет: если не задан, служба меток времени не используется, а доверенное время бесключевой подписи берётся из её записи в журнале прозрачности. Записывается как абсолютный URL https: https://, хост и, при необходимости, порт и путь, без пробельных символов — например, https://tsa.example.com/api/v1/timestamp. Значение любой другой формы, например без схемы (tsa.example.com) или начинающееся с http://, отклоняется при загрузке файла конфигурации с указанием файла и ключа. Файл проверяется до того, как поверх него применяется что-либо ещё, поэтому та же конечная точка, переданная через AGGREGA_SIGNING_TIMESTAMP_URL, флагом --timestamp-url или в запросе на публикацию из редактора или ассистента, этой форме не обязана соответствовать. Шаблон: ^https://[^\s/?#]+(?:[/?#]\S*)?$.
key_pathstringнетПуть к хранимому PEM-файлу закрытого ключа ECDSA P-256 для автономной подписи с ключом. Путь к файлу, а не встроенные данные ключа. Если не задан, используется бесключевой путь. Сервер aggrega mcp, доступный по HTTP, никогда не обращается к этому ключу, где бы он ни был задан — в блоке signing верхнего уровня, в блоке записи реестра или через AGGREGA_SIGNING_KEY_PATH: вызов, на который отвечает такой слушатель, подписывается только токеном идентичности, который несёт сам вызов, либо отклоняется. Сервер, доступный через стандартный ввод и вывод, подписывает им так же, как терминал.
requiredлогическаянетЕдиная позиция доверия для области действия этого блока: при значении true публикация вида артефакта в пределах области требует подписи (неподписанная отправка в пределах области отклоняется), и его потребление требует подписи (неподписанное получение в пределах области отклоняется). Область определяется размещением — в блоке signing верхнего уровня она охватывает все реестры; в блоке signing записи registries[] — этот один хост. Одно имя, одна задача, обе области. Политика верхнего уровня складывается монотонно по каскаду конфигурации — любой слой, установивший true, делает её фактически true, и никакой слой с более низким приоритетом не может снова её отключить, — поэтому её нельзя убрать обычным редактированием конфигурации. По умолчанию false. Значение по умолчанию: false
kindsstring[]нетОграничивает required определёнными видами артефактов. Пустой список или единственная запись all означает все подписываемые виды; иначе позиция применяется ровно к перечисленным видам, сопоставляемым со значением kind: сущности (например, Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate, Plugin). В блоке signing верхнего уровня складывается как объединение по каскаду — слой может расширить область, но никогда не сузить её. Область определяется размещением, так же как у required. Значение по умолчанию: []

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

TrustedIdentity

Одна допустимая идентичность бесключевой подписи: субъект сертификата (идентичность OIDC) в паре с издателем OIDC, который её удостоверил.

СвойствоТипОбязательноОписание
identitystringнетТочное альтернативное имя субъекта сертификата — идентичность OIDC, привязанная к кратковременному сертификату подписи (например, адрес электронной почты сопровождающего или URI рабочего процесса CI).
identity_regexpstringнетРегулярное выражение, сопоставляемое с субъектом сертификата и используемое вместо точного identity (например, чтобы принимать любой рабочий процесс в организации).
issuerstringдаURL издателя OIDC, выпустившего токен идентичности (например, https://accounts.google.com или https://token.actions.githubusercontent.com).

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

PluginRef

Ссылка на плагин Wasm, подключаемый к сокету, функцию входа которого может назвать подключение, — списки governance и linter. Сокеты с фиксированной точкой входа вместо этого используют FixedEntryPluginRef, который содержит те же поля, но без function. uri и capability вместе выбирают плагин: только uri — прямое подключение (плагин с этим идентификатором подключается как есть — путь сквозных сокетов, поскольку их плагины не объявляют обслуживаемых возможностей); только capability — разрешается плагин, обслуживающий эту возможность (голое имя возможности, которое Recipe привязывает через spec.capability, например helm); оба вместе устраняют неоднозначность — capability называет, что разрешать, а uri выбирает, плагин какого издателя её обслуживает, по голому идентификатору этого плагина, в федеративном каталоге, где возможность обслуживают несколько плагинов. function переопределяет функцию входа сокета по умолчанию; если поле опущено, применяется задокументированное значение сокета по умолчанию — в записи governance оно следует из role. role называет роль подключения governance и читается только в записи governance. with содержит необязательные входные данные времени подключения, которые читает плагин.

СвойствоТипОбязательноОписание
uristringнетИдентификатор плагина: голый идентификатор сущности Plugin — путь <pluginType>/<name>, например governance/redact или provider/helm, — локальный путь в файловой системе или псевдоним реестра. Необязательно: запись может вместо этого выбрать плагин по capability. Необязательный завершающий суффикс :version закрепляет версию в тех же трёх формах, что и любое закрепление версии (без версии, точная :1.0.0 или диапазон, совместимый по мажорной версии, :^1.0.0).
rolestring (enum)нетРоль в конвейере, к которой привязано подключение governance; читается только в записи governance: annotation-transform внедряет аннотации в разрешённые компоненты перед раскрытием аннотаций, так что привязанные внедрения становятся подключениями Feature; label-transform автоматически помечает метки узлов графа топологии при построении топологии; ir-verdict выносит вердикт «принять/отклонить» по графу IR на этапе статического анализа; render-verdict выносит вердикт по отрендеренным артефактам на этапе рендеринга. Именно роль, а не объявленный вид плагина, определяет, что плагин может выдавать: вывод роли вердикта может читаться только как вердикт и никогда не применяется как изменение; вывод роли преобразования ограничен хостом своим аспектом (аннотациями или метками). Роль также выбирает функцию входа по умолчанию (annotation-transform → transform_annotations; label-transform → mutate; ir-verdict → verdict_ir; render-verdict → verdict_render). Допустимые значения: "annotation-transform", "label-transform", "ir-verdict", "render-verdict"
capabilitystringнетВозможность провайдера, для которой эта запись выбирает плагин, — голое имя возможности, которое Recipe привязывает через spec.capability (например, helm, compose). Необязательно: запись может вместо этого подключить плагин напрямую по uri. Привязки провайдеров используют это поле, чтобы выбрать, плагин какого издателя обслуживает возможность в федеративном каталоге; сквозные сокеты оставляют его пустым и подключают по uri.
functionstringнетНеобязательное переопределение функции входа сокета по умолчанию. Если поле опущено, применяется задокументированное значение сокета по умолчанию (governance annotation-transform → transform_annotations, governance label-transform → mutate, governance ir-verdict → verdict_ir, governance render-verdict → verdict_render, linter → lint_rules). Переопределение может назвать любой экспорт, объявленный плагином, и названный экспорт должен возвращать вывод той формы, которую читает сокет: сборка останавливается, если вывод содержит поле верхнего уровня, не объявленное формой, с указанием вызванного экспорта и неожиданного поля. Проверка учитывает, какие имена полей верхнего уровня присутствуют, а не какие отсутствуют или что вложено в них, поэтому она не является полной валидацией вывода.
withPluginRefWithнетНеобязательные входные данные времени подключения, которые читает плагин. Оба члена необязательны и не зависят от сокета, поэтому эту поверхность может повторно использовать любой сокет.

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

FixedEntryPluginRef

Ссылка на плагин Wasm, подключаемый к сокету, точка входа которого фиксирована, а не называется подключением, — список importer и привязки providers. Содержит те же поля, что и PluginRef, но без function: сокет импортёра вызывает единственную функцию входа, названную в контракте его сокета, а провайдер управляет фиксированным набором экспортов, привязанных к фазам, а не одной выбираемой точкой входа, поэтому ни в одном из списков нет точки входа, которую могло бы назвать function, и этот ключ там не принимается. uri и capability вместе выбирают плагин: только uri — прямое подключение (плагин с этим идентификатором подключается как есть — путь сокета импортёра, поскольку его плагины не объявляют обслуживаемых возможностей); только capability — разрешается плагин, обслуживающий эту возможность (голое имя возможности, которое Recipe привязывает через spec.capability, например helm); оба вместе устраняют неоднозначность — capability называет, что разрешать, а uri выбирает, плагин какого издателя её обслуживает, по голому идентификатору этого плагина, в федеративном каталоге, где возможность обслуживают несколько плагинов. role здесь принимается, но не читается ни в одном из списков, которые обслуживает эта форма: названная им роль подключения governance читается в записи governance, использующей PluginRef, поэтому роль, заданная в одной из этих записей, ни на что не влияет. with содержит необязательные входные данные времени подключения, которые читает плагин; привязка провайдера берёт конфигурацию рендеринга из Recipe, поэтому with: в ней отклоняется при загрузке.

СвойствоТипОбязательноОписание
uristringнетИдентификатор плагина: голый идентификатор сущности Plugin — путь <pluginType>/<name>, например governance/redact или provider/helm, — локальный путь в файловой системе или псевдоним реестра. Необязательно: запись может вместо этого выбрать плагин по capability. Необязательный завершающий суффикс :version закрепляет версию в тех же трёх формах, что и любое закрепление версии (без версии, точная :1.0.0 или диапазон, совместимый по мажорной версии, :^1.0.0).
rolestring (enum)нетРоль подключения governance. Ни один из списков, использующих эту форму, её не читает — роль читается в записи governance, а такие записи используют PluginRef, — поэтому заданная здесь роль принимается и ни на что не влияет. Допустимые значения — четыре роли governance; значение каждой описано в PluginRef. Допустимые значения: "annotation-transform", "label-transform", "ir-verdict", "render-verdict"
capabilitystringнетВозможность провайдера, для которой эта запись выбирает плагин, — голое имя возможности, которое Recipe привязывает через spec.capability (например, helm, compose). Необязательно: запись может вместо этого подключить плагин напрямую по uri. Привязки провайдеров используют это поле, чтобы выбрать, плагин какого издателя обслуживает возможность в федеративном каталоге; сквозные сокеты оставляют его пустым и подключают по uri.
withPluginRefWithнетНеобязательные входные данные времени подключения, которые читает плагин. Оба члена необязательны и не зависят от сокета, поэтому эту поверхность может повторно использовать любой сокет.

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

CLIPluginRef

Закреплённый плагин-расширение CLI, установленный как команда верхнего уровня aggrega: разрешённая ссылка на артефакт с закреплённой версией, которую команда разрешает и запускает, и дайджест содержимого байтов гостевого модуля, в которые эта ссылка разрешилась при установке. Вместе они точно закрепляют, какие байты выполняет команда; дайджест также служит ключом кэша describe, который предоставляет имена и справку команды без загрузки гостевого модуля.

СвойствоТипОбязательноОписание
uristringдаРазрешённая ссылка на артефакт с закреплённой версией, которую команда разрешает и запускает, например oci://hub.aggrega.ai/plugin/cli/<name>:1.2.0; закрепляется при установке.
digeststringдаДайджест содержимого гостевых байтов .wasm, в которые ссылка разрешилась при установке, записанный как sha256:, за которым следуют 64 шестнадцатеричные цифры в нижнем регистре хеша SHA-256 этих байтов, — в том написании, которое записывает aggrega plugin add cli и в котором сравниваются разрешённые байты. Дайджест в любом другом написании — шестнадцатеричный без префикса sha256:, с заглавными буквами или другой длины — никогда не может с ним совпасть, поэтому он отклоняется при загрузке файла конфигурации с указанием файла и записи. Он закрепляет точные байты, которые запускает команда, — более позднее разрешение, байты которого дают другой хеш, останавливает команду, — и является ключом кэша describe, который формирует справку команды без загрузки гостевого модуля. Шаблон: ^sha256:[0-9a-f]{64}$.

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

PluginRefWith

Необязательные входные данные времени подключения, которые читает плагин. Оба члена необязательны, а поверхность универсальна, поэтому её может повторно использовать любой сокет.

СвойствоТипОбязательноОписание
sourcesstring[]нетПути к файлам определений, которые хост читает во время компиляции и передаёт плагину. Каждая запись — путь в файловой системе, разрешаемый относительно каталога объявляющего файла конфигурации.
settingsobjectнетОбъект настроек произвольной формы, передаваемый плагину без изменений. Хост не интерпретирует его структуру; плагин сам определяет ключи, которые читает.

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