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

Конфигурация

Откуда aggrega считывает свои настройки и в какой файл следует поместить ту или иную настройку.

Простой случай

Два файла, и большинству проектов больше ничего не нужно.

Один файл в вашем проекте с именем .aggrega-config.yaml, расположенный в корне проекта. Он описывает, как собирается этот проект: в каких каталогах лежит вендорированное содержимое каталога, какие плагины отрисовывают какие цели, какие правила линтера ослаблены, где размещается локальный кэш. Он фиксируется в репозитории, поэтому коллега, клонировавший проект, собирает его так же.

Именно его блок workspace: помечает каталог как корень проекта:

# <project>/.aggrega-config.yaml
workspace:
catalog_dirs:
- ./catalog
auto_pull: true

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

Один глобальный файл на вашей машине — ~/.config/aggrega/config.yaml, а в Windows — aggrega\config.yaml внутри каталога, указанного переменной окружения APPDATA. Через него разрешается каждое рабочее пространство на этой машине, и он содержит настройки, относящиеся к машине, а не к какому-либо одному проекту: реестры, из которых вы получаете содержимое, и политику доверия подписям для каждого из них, допустимый размер хранилища скомпилированных модулей и все установленные вами плагины расширения команд. Они одинаковы, где бы вы ни работали, поэтому смысл в том, чтобы объявить их один раз. Файл загружается автоматически, если он есть, и ничего не ломается, если его нет.

~/.config/aggrega/config.yaml
registries:
- host: hub.aggrega.ai
signing:
required: true

aggrega config init создаёт этот глобальный файл за вас, регистрируя реестр вместе с объявляемой им политикой доверия подписям, и сообщает, где находится файл на вашей машине и где хранятся общемашинные кэши. aggrega config show выводит то, что действует прямо сейчас, а aggrega config show --origin сообщает, какой файл — или какая переменная окружения — определил каждую настройку.

Секреты — это не конфигурация. Пароль реестра и токен идентичности для подписи никогда не являются полями ни одного из файлов; они передаются через переменную окружения или флаг в тот момент, когда нужны. См. environment-variables.md.

Откуда читаются локальные сущности

У проекта, хранящего собственное содержимое каталога — сущность Component, Feature, Recipe или один из видов библиотек, — есть два способа указать, где лежит это содержимое, и первый вообще не требует конфигурации.

Каталог catalog в корне проекта читается независимо от того, указан ли он где-либо. Поместите сущность в <project>/catalog/, и её прочитает каждая команда, загружающая каталог, в том числе в проекте с пустым блоком workspace:. Каталог читается рекурсивно, поэтому то, как вы располагаете в нём подкаталоги, решаете вы.

Каталоги, перечисленные в workspace.catalog_dirs, тоже читаются, причём первыми. Список — это упорядоченный стек поиска: первый каталог, объявивший идентичность, владеет ею, а та же идентичность в последующем каталоге затеняется. catalog читается после всего перечисленного — если только перечисленный каталог уже не содержит его, и тогда он читается как часть этого каталога, — поэтому перечисление каталога добавляет к тому, что у вас было, а не заменяет это. Повторяемый --catalog <dir> в командной строке читается раньше обоих, а относительный путь, указанный там, разрешается относительно каталога, из которого вы запустили команду, поскольку его не объявлял ни один файл конфигурации. Каталог, названный более одного раза — в командной строке и в списке или дважды в списке, — читается один раз, в том месте, где он был назван впервые, поэтому ничто в нём не сообщается как затенённое самим собой: затенение — это всегда два разных файла, объявляющих одну идентичность. Два написания одного каталога, путь к нему через ссылку и — в файловой системе без учёта регистра — написание в другом регистре обозначают один и тот же каталог. Каталог внутри другого перечисленного каталога всё равно читается как отдельная запись. Проект, хранящий вариант каталога для каждой сущности Release, может вместо этого дать каждой сущности Release собственный список — см. Собственные каталоги каталога для сущности Release.

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

Перечисленный каталог должен быть каталогом. Перечисленный путь, по которому ничего нет или находится файл либо ссылка, ведущая в никуда, отклоняется до того, как что-либо будет прочитано или записано, каждой командой, читающей каталог сущностей, — pull, сборкой, валидацией, инспекцией, lint, а также теми же операциями, запущенными из редактора через aggrega serve или из ассистента через aggrega mcp, — поэтому сборка никогда не выполняется с меньшим числом каталогов, чем вы перечислили. Отказ называет запись в том виде, в каком она написана, путь, в который она разрешилась, файл конфигурации и строку, в которых она указана, и список, в котором она находится:

<project>/.aggrega-config.yaml:4: the `workspace.catalog_dirs` entry "../shared/aggrega-catalog" names <directory>, which does not exist; create that directory, or remove the entry: workspace configuration is invalid

Создайте каталог или удалите запись: копия проекта, взятая без соседнего checkout, который он перечисляет, удаляет эту запись и разрешает из реестра то, что предоставил бы checkout. То же относится к каталогу, перечисленному в собственной записи сущности Release, к каталогу, добавленному файлом конфигурации, который принадлежит вашему конвейеру, или глобальным файлом, и к каталогу, переданному в переменной AGGREGA_CATALOG_DIRS, которую отказ называет вместо файла. Сама конфигурация по-прежнему загружается, поэтому команда, не читающая каталог сущностей, по-прежнему выполняется. Несуществующий каталог --catalog был введён для одной команды, и aggrega build отклоняет его, называя каталог. Перечисленный каталог, который существует, но не может быть прочитан, отклоняется командами, загружающими весь каталог сущностей, с указанием его имени.

Пустой список означает, что у проекта вообще нет локального каталога, и это единственное написание, которое отключает и чтение catalog:

# <project>/.aggrega-config.yaml
workspace:
catalog_dirs: []

Отсутствие ключа означает другое: опущенный список — обычный случай, и catalog по-прежнему читается.

Сборка, pull, валидация или aggrega inspect, не находящие сущность под использованным вами именем, сообщают, откуда этот проект читает локальные сущности и что изменить, чтобы названная вами сущность была прочитана. Ничего подобного не сообщается, если вы записали пустой список: отказ от чтения локального каталога — это то, что вы там объявили, и предложение изменить это было бы спором с вами. Не сообщается это и тогда, когда документ, объявляющий это имя, был прочитан и отклонён: этот документ уже лежит там, откуда читает каталог, поэтому отчёт вместо этого называет, что именно документ нарушает, — строку и ограничение, — и перемещение ничего бы не исправило. Документ, настолько искажённый, что объявленное в нём имя вообще не удаётся прочитать, невозможно сопоставить с использованным вами именем, поэтому описание всё равно выдаётся, — а если этот документ объявляет apiVersion Aggrega, сборка, pull или валидация сущности Release называет его рядом с описанием, с причиной, которую указал сам парсер, поскольку это может быть тот файл, который нужно открыть. Сбой, при котором сущность найдена, но не может быть принята, — реестр теперь отдаёт другие байты под версией, закреплённой вашим lock-файлом, файл сущности не может быть прочитан, — тоже не является отсутствующей сущностью, и он сообщает только собственное средство исправления.

Закрепляет ли pull или push сущность

Сущность Recipe или FeatureRecipe хранит закрепления для читаемых ею входных данных — удалённого source:, записанного полностью, файла, импортируемого записью artifacts, файлов source: рядом с ней — в entity.lock рядом с собой, и их запись — это шаг автора сущности, aggrega pin. По умолчанию ни pull, ни push не выполняют этот шаг: pull останавливается на сущности, которую её lock не закрепляет, а push отказывается её публиковать. Два ключа, по одному на команду, делают выполнение шага поведением этой команды по умолчанию:

# <project>/.aggrega-config.yaml
workspace: {}
pin_sources_at_pull: true
pin_sources_at_push: true

Каждый ключ управляет своей командой и ничем больше, и --pin-sources каждой команды переопределяет её ключ в обоих направлениях: --pin-sources=false отключает шаг на один запуск в проекте, настроенном на закрепление. Сборка, заполняющая собственный lock-файл, является pull и следует pin_sources_at_pull. Эти ключи место в файле проекта, а не в глобальном: записывают ли pull проекта закрепления — это политика данного проекта, и коллега, клонировавший его, должен получить тот же ответ. pin_sources_at_pull также позволяет проекту, использующему чужой незакреплённый каталог, записать эти закрепления один раз, а не останавливаться при каждом pull.

Какой плагин выполняет рендеринг для возможности

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

# <project>/.aggrega-config.yaml
workspace: {}
plugins:
providers:
- capability: helm
uri: provider/helm

Pull разрешает запись и фиксирует выбранный плагин в lock-файле сущности Release, а сборка рендерит через то, что зафиксировано в lock-файле, поэтому изменение здесь вступает в силу при следующем pull.

uri называет плагин по его идентификатору, provider/<name>, и никогда — по месту, где он опубликован. aggrega plugin add provider <query> --capability <capability> создаёт запись именно в такой форме, без версии: запись выбирает, какой плагин обслуживает возможность, версией становится та, которую закрепляет сущность Recipe, а иначе наивысшая доступная, и lock-файл фиксирует ту, которую выбрал pull. Плагин, встроенный в компилятор, обслуживается в собственной версии компилятора, поэтому версия, указанная в записи для такого плагина, разрешается, только если это именно эта версия. Запись, чей uri является расположением в реестре — oci://hub.aggrega.ai/plugin/provider/helm, — не называет идентификатор ни одного плагина и отклоняется при загрузке файла с указанием записи и формы, которую следует написать.

Записи пишутся один раз для всего проекта, а сборка относится к одной сущности Release, поэтому запись для возможности, которую данная сущность Release никогда не запрашивает, допустима — её читает другая сущность Release в проекте — и ни о чём не сообщается. Что каждая сборка и каждый aggrega validate --release всё же проверяют — это каждую запись, независимо от того, запрашивает ли сущность Recipe её возможность, по тому, что запись указывает:

  • Запись, указывающая плагин, который не обслуживает её возможность, останавливает сборку и проваливает валидацию. Pull разрешает каждую запись, указывающую плагин, и отклоняет ту, которую не может разрешить, поэтому после того, как запись прошла через pull, сборка располагает её плагином и знает, что он обслуживает; запись, указывающая плагин, которого у сборки ещё нет, оценивается после того, как pull его загрузит. Сообщение называет запись, плагин, то, что этот плагин действительно обслуживает, и написание на расстоянии одной правки, если оно есть, — так выглядит опечатка вроде hlem вместо helm.
  • Запись, указывающая только возможность, которую не обслуживает ни один плагин, читаемый сборкой, даёт предупреждение, и сборка продолжается. Обслуживающий её плагин может читаться только другой сущностью Release, которую эта сборка не видит, а запись без плагина не выбирает ничего, чего разрешение возможности не выбрало бы и без неё.

Возможность здесь никогда не содержит двоеточия, а возможность с двоеточием отклоняется при загрузке файла. Поле capability: сущности Recipe читается как возможность до последнего двоеточия и закрепление версии после него, поэтому запись с ключом helm:1.0.0 никогда не удалось бы найти. Закрепляйте версию на плагине — uri: provider/helm:1.0.0 — или в сущности Recipe.

Какой импортер превращает источник в черновики

aggrega import передаёт источник импортеру, объявляющему формат источника, — импортеру из вашего каталога или одному из встроенных импортеров компилятора, import:langflow для потока Langflow. Если формат объявляет ровно один импортер, ничего настраивать не нужно. Запись plugins.importer подключает импортер, указывая его в своём uri по идентификатору и версии, и передаёт ему то, что содержит в with:

# <project>/.aggrega-config.yaml
workspace: {}
plugins:
importer:
- uri: importer/agent-flows:1.2.0
with:
settings:
target_namespace: payments

aggrega plugin add importer записывает uri именно в такой форме. Версия бывает точной — :1.2.0 — или диапазоном — :^1.2.0 для наивысшей версии не ниже указанной в пределах той же мажорной версии. Пишите одно или другое: в этом списке uri без двоеточия читается как путь в файловой системе, как описано в разделе Куда указывает относительный путь, и не указывает никакой импортер.

Действие записи зависит от того, объявляет ли указанный в ней импортер формат, запрашиваемый импортом:

  • Объявляет: запускается именно этот импортер, в версии, указанной в uri, сколько бы других импортеров в каталоге ни объявляли этот формат, и ему передаются with.sources и with.settings записи. Запись — это способ, которым рабочее пространство, чей каталог объединяет импортеры двух издателей для одного формата, указывает, какой из них использовать.
  • Не объявляет — указывает импортер другого формата, плагин другого вида или то, чего нет ни в вашем каталоге, ни в компиляторе: запись не участвует в этом импорте. Она ничего не выбирает, и её with не передаётся ни одному импортеру. Настройки записи доходят только до указанного в ней импортера, поэтому рабочее пространство, подключающее по одному импортеру на формат, настраивает каждый так, что настройки одного не попадают к другому.

Если формат объявляют несколько импортеров и ни один из них не подключён единственным образом — не подключён никакой или записи указывают два из них, — импорт отклоняется с указанием импортеров, между которыми не удалось выбрать. Запись, указывающая импортер, объявляющий формат, в версии, которой не удовлетворяет ни одна его версия в каталоге, — точной версии, которой нет в каталоге, или диапазоне, в который не попадает ни одна из его версий, — тоже отклоняется с указанием версии, а не запускает вместо неё другую версию; значение, вовсе не являющееся версией, например :latest, отклоняется как некорректное. Сущность Plugin одного из базовых импортеров компилятора, рядом с которой в её папке каталога нет модуля, не является кандидатом: в собственной версии компилятора вместо неё запускается базовый импортер, а в любой другой версии сущность остаётся кандидатом, только если запись указывает именно эту версию или ни один импортер с её именем, способный запуститься, не объявляет формат, как описано в разделе Какой из них выполняется рядом с вашими собственными импортёрами.

Каждый импортер подключается одной записью. Две записи, указывающие один импортер — тот же идентификатор, в одной версии или в двух, — отклоняются при загрузке конфигурации, какой бы командой она ни читалась, с указанием обеих записей и файлов, в которых они написаны. Правило охватывает все файлы, вносящие вклад в список: запись в глобальном файле, запись в файле проекта, запись в importer_append и запись в .aggrega-config-append-ci.yaml конвейера учитываются все, поэтому перевод импортера на новую версию означает изменение версии в его единственной записи. aggrega plugin add importer делает именно это, когда список plugins.importer файла, в который он пишет, уже указывает этот импортер: команда переводит эту запись на разрешённую версию, сохраняя место записи и её with, а не добавляет вторую. Других списков она не читает, поэтому импортер, подключённый в importer_append или в .aggrega-config-append-ci.yaml конвейера, команда подключает второй раз, и эта пара отклоняется при загрузке конфигурации; меняйте версию такой записи там, где она написана. Запись, чей uri — путь в файловой системе, не указывает импортер и не сравнивается, а на списки plugins.governance и plugins.linter правило не распространяется: один плагин может быть подключён к ним несколько раз, каждый раз со своим with.

Парсерам, через которые читает импорт, запись не нужна. Импортер читает свой источник — а импорт, не указывающий формат, распознаёт его — через парсер для синтаксиса источника: тот, который ваш каталог предоставляет для этого синтаксиса, а для синтаксиса, для которого ваш каталог парсера не предоставляет, — тот, что встроен в сам компилятор, в том числе JSON. Поэтому рабочее пространство, в каталоге которого нет парсера, импортирует поток Langflow или Flowise без какой-либо настройки. Ни один список не подключает парсер: используется парсер, который ваш каталог предоставляет для синтаксиса, а два парсера с разными именами, обслуживающие один синтаксис, отклоняются, как описано в A parse or import format is advertised by more than one plugin (Формат разбора или импорта объявлен более чем одним плагином).

Начало с нуля

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

Знать это заранее не обязательно. Команда, которая читает конфигурацию и не находит файла нигде, сообщает об этом один раз в стандартный поток ошибок и называет aggrega config init как способ его создать. Это совет, а не сбой: стандартный вывод не затрагивается, от вас ничего не требуется, а код завершения такой, какой команда вернула бы в любом случае. Сообщение выводится, только когда стандартный поток ошибок — терминал, поэтому оно доходит до вас за клавиатурой и никогда не накапливается в журнале конвейера. Как только появляется хотя бы один файл — файл вашего проекта или глобальный, — сообщение перестаёт выводиться.

Чтобы заполнить глобальный файл официальным хабом и политикой доверия, которую объявляет этот хаб:

Terminal window
aggrega config init

Передайте --registry <host>, чтобы указать другой реестр, --workspace, чтобы записать запись в файл этого проекта вместо глобального, и --dry-run, чтобы увидеть содержимое, которое было бы записано, ничего не создавая. Команда полностью описана в aggrega-config.md.

Как записывается хост реестра

Каждый registries[].host называет хост реестра. То же делает default_registry — при необходимости с последующим путём репозитория, — если только он не называет вместо этого одну из этих записей (см. ниже). Хост записывается как сам хост, в том единственном написании, под которым хранится политика доверия реестра:

  • имя хоста в нижнем регистре, содержащее точку, например registry.example.com;
  • localhost или одиночное имя с портом, например registry:5000;
  • адрес IPv4, например 127.0.0.1, или адрес IPv6 в квадратных скобках, например [::1];

каждый с необязательным :port и ничем больше — без схемы, без пути, без учётных данных, без пробелов и без заглавных букв. Одиночное имя без порта не является хостом реестра, потому что такую форму имеет первый сегмент имени сущности каталога — core в core/web-api, — и одно никогда не должно приниматься за другое.

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: registry.example.com
registries:
- host: registry.example.com
signing:
required: true

Написание — часть политики. Запись registries применяется к хосту, который называет её host:, а встроенное требование подписи официального хаба применяется к hub.aggrega.ai, поэтому хост, записанный иначе, достиг бы нужного реестра, но миновал бы написанную для него политику. Вместо этого он отклоняется при загрузке конфигурации, и в отказе указывается написание, которое следует использовать: HUB.AGGREGA.AI и https://registry.example.com отклоняются с указанием hub.aggrega.ai и registry.example.com, и так же отклоняется registry.example.com/charts в качестве registries[].host, который не содержит пути. Порт 443 — порт по умолчанию для хоста, доступного по HTTPS, поэтому hub.aggrega.ai:443 отклоняется так же, с указанием hub.aggrega.ai. localhost и другие loopback-адреса, напротив, доступны по обычному HTTP, где 443 — обычный порт, поэтому localhost:443 принимается в том виде, как записан. Пустой default_registry не называет реестр по умолчанию.

default_registry может содержать путь репозитория. Многие реестры хранят каждый репозиторий под владельцем или проектом — ghcr.io/<owner>, <host>/<project> в Harbor, — и реестр по умолчанию на одном из них записывается как хост, за которым следует этот путь:

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: ghcr.io/acme
registries:
- host: ghcr.io
signing:
required: true

Путь — это место, где публикуется и откуда загружается содержимое. Через этот реестр по умолчанию aggrega push публикует core/api-server версии 1.0.0 по адресу ghcr.io/acme/component/core/api-server:1.0.0, а pull, разрешающий core/api-server, загружает его из того же места, поэтому подпись, приложенная при публикации, тоже находится там. Путь — это путь репозитория в грамматике OCI distribution: один или несколько сегментов из строчных букв и цифр, соединённых /, которые внутри сегмента могут разделяться ., _, __ или дефисами, без тега, дайджеста и завершающего /.

Путь никогда не участвует в том, как реестру оказывается доверие. Запись registries, чья политика применяется, учётные данные, которые сохраняет aggrega login, требование подписи и доверенные идентичности находятся только по хосту, поэтому приведённая выше запись для ghcr.io управляет ghcr.io/acme и любым другим путём на этом хосте, и никакое написание пути не может её обойти; сам host: записи не содержит пути. Хост, записанный в другом написании перед путём, отклоняется с указанием места, которое следует записать, — GHCR.io/acme и https://ghcr.io/acme указывают на ghcr.io/acme, — а то, что следует за хостом, если это не путь репозитория, отклоняется с указанием хоста, за которым оно следует.

default_registry может вместо этого называть запись. Записанный как name: записи в registries, он обозначает host: этой записи. Публикация, pull, проверка подписей и все настройки доверия для отдельного реестра затем используют этот хост, и никакое содержимое не загружается с хоста, написанного так же, как имя:

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: local
registries:
- name: local
host: 127.0.0.1:5000

Имя сопоставляется раньше написания хоста, так же как его сопоставляет флаг --registry, поэтому значение, которое является name: записи, обозначает эту запись, даже если оно записано и как хост. Имя, которое носят две записи, отклоняется как неоднозначное с указанием обоих хостов. Запись может находиться в любом из файлов — default_registry проекта может называть запись, объявленную в глобальном файле, — потому что имя читается один раз, по записям, действующим после чтения всех файлов и окружения. Значение, которое не является ни именем записи, ни хостом реестра — отдельно или с последующим путём репозитория, — отклоняется, и в отказе говорится, что исправит любое из двух. Имя с последующим путём, например local/acme, тоже отклоняется: имя обозначает хост своей записи, а не место под ним, поэтому в отказе указываются два написания, которые следует использовать вместо него, — local или хост записи с последующим путём, 127.0.0.1:5000/acme. Удаление записи командой aggrega registry remove оставляет default_registry таким, каким он записан, поэтому значение по умолчанию, называвшее удалённую запись, после этого не называет ничего и отклоняется, пока его не перепишут.

Каждый уровень подчиняется одному и тому же написанию. Значение отклоняется одними и теми же словами, откуда бы оно ни пришло: из файла конфигурации, из AGGREGA_DEFAULT_REGISTRY или из флага --registry, который называет назначение одного aggrega push или aggrega push-artifact. Этот флаг называет хост, и публикация, которую он направляет, попадает на этот хост без пути репозитория: путь относится к default_registry. aggrega registry add и aggrega config init --registry тоже применяют это требование к переданному им хосту; кроме того, они принимают вместо него ссылку и создают запись под хостом, который называет ссылка. Отказ из-за файла указывает файл и ключ; отказ из-за окружения указывает переменную. Схема задаёт форму хоста шаблоном для registries[].host и не задаёт никакой для default_registry, значением которого может быть имя любой записи, — поэтому редактор, читающий только схему, не отмечает опечатку в значении по умолчанию, и отклоняет её загрузка конфигурации.

Хост оценивается только по написанию, и путь тоже. Разрешается ли имя, отвечает ли там реестр, существует ли на нём путь — при загрузке конфигурации не проверяется.

Что что переопределяет

CLI flag > environment variable > configuration file > built-in default

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

Флаг побеждает тем, что был указан, а не значением, которое он несёт, и для логической настройки в этом разница между пригодным верхним уровнем и его отсутствием. --offline включает этот режим на один запуск; --offline=false выключает его на один запуск там, где зафиксированный файл или экспортированная переменная его включили. Уровень, читающий только значение, не мог бы отличить «выключено» от «не упомянуто», поэтому каждая команда выглядела бы так, будто запросила значение флага по умолчанию, и не было бы никакого способа отменить настроенное значение.

Это вся модель для одного проекта на одной машине. Всё, что описано ниже, существует для проектов, которые её перерастают.

За пределами двух файлов

Эти механизмы созданы для более крупных структур — монорепозитория связанных проектов, конвейера, который добавляет собственные настройки, общего каталога, который расширяют несколько проектов. Прибегайте к ним, когда у вас есть проблема, которую они решают.

Несколько файлов конфигурации внутри проекта

Свой вклад вносит каждый .aggrega-config.yaml от корня проекта до каталога, в котором выполняется команда, и более близкий файл переопределяет более далёкий. Поэтому подпроект может иметь собственный файл, который корректирует объявленное в корне, не повторяя его.

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

Передача --workspace-root не только отменяет поиск, но и меняет это: собирается только собственный файл конфигурации указанного корня, поэтому файлы в каталогах ниже него не вносят вклада. Благодаря этому конфигурация закреплённого корня остаётся одинаковой, откуда бы ни запускалась команда.

Каждый собранный таким образом файл читается изнутри проекта. Файл, являющийся символической ссылкой, ведущей за пределы проекта, — или находящийся в каталоге, доступном через такую ссылку, — не читается, и каждая команда, читающая конфигурацию, останавливается на нём, указывая ссылку, а не настраивает проект по оставшимся файлам; то же относится и к файлу конвейера, описанному ниже. Немногие команды, которые её никогда не читают, например aggrega version и aggrega help, выполняются с предупреждением, указывающим ссылку. Языковой сервер редактора и инструменты ассистента читают конфигурацию так же и всё равно запускаются над таким проектом, чтобы его можно было вывести в списке: их списки сущностей Release и других сущностей отвечают, прочитанные без какой-либо конфигурации, и называют файл среди непрочитанных ссылок, а каждый другой запрос, который определяет конфигурация, останавливается на нём, указывая ссылку. Конфигурация, хранящаяся вне проекта, читается, если указать её как глобальный файл, как описано в разделе Явное указание глобального файла. См. Граница рабочего пространства.

Расширение списка вместо его замены

Настройка со значением-списком ведёт себя как любая другая: значение более близкого файла заменяет значение более далёкого. Если вы хотите добавить к объявленному во внешнем файле, а не повторять его, используйте сопутствующую настройку добавления рядом с ней:

настройка-списокеё сопутствующая настройка добавления
workspace.catalog_dirscatalog_dirs_append
plugins.governancegovernance_append
plugins.linterlinter_append
plugins.importerimporter_append
plugins.providersproviders_append

Записи в сопутствующей настройке присоединяются к разрешённому списку на каждом уровне, а не затеняют его, поэтому подпроект добавляет линтер к тому, что уже объявил корень:

# <project>/services/api/.aggrega-config.yaml
plugins:
linter_append:
- uri: ./lint/api-rules.wasm

Если один файл задаёт и базовый список, и его сопутствующую настройку, значение этого файла — базовый список, за которым следуют добавленные записи.

Блок workspace: — исключение в том, где можно записать сопутствующую настройку. Файл, содержащий этот блок, отмечает свой каталог как корень проекта, поэтому файл подпроекта, в котором записано workspace.catalog_dirs_append, начал бы собственный проект, а не дополнил бы объемлющий. Сопутствующая настройка каталогов каталога компонуется между вашим глобальным файлом и корневым файлом проекта.

Список plugins.cli компонуется между файлами сам по себе и не имеет сопутствующей настройки: расширение команд, объявленное в глобальном файле, регистрирует свою команду в каждом проекте, объявленное в проекте — только там, и оба регистрируются вместе. Каждая запись закрепляет один плагин: uri, который она разрешает, и digest байтов, проверенных aggrega plugin add cli, записанный как sha256: с последующими 64 шестнадцатеричными цифрами в нижнем регистре. Дайджест в любом другом написании никогда не мог бы совпасть с хешем разрешённых байтов, поэтому он отклоняется при загрузке файла с указанием файла и записи.

Собственные каталоги каталога для сущности Release

Проект может хранить несколько вариантов каталога рядом — по одному на цель, каждый с Recipes, которые отображают одни и те же Components для другого провайдера, — и собирать каждый Release по одному из них. Назовите каждый Release в workspace.releases и задайте ему собственный catalog_dirs:

# <project>/.aggrega-config.yaml
workspace:
releases:
release-compose.yaml:
catalog_dirs:
- ./catalog-compose
release-helm.yaml:
catalog_dirs:
- ./catalog-helm

Каждый ключ — это файл Release, записанный относительно файла конфигурации, который его называет. Ключ — как build.authoring_release — может называть Release, хранящийся вне проекта, и указание его здесь — способ, которым проект до него добирается: ссылка внутри проекта, ведущая к нему, читается, а не пропускается, как описано в разделе Граница рабочего пространства. Два ключа под ним означают то же, что и в блоке workspace:, но в пределах этого одного Release:

  • catalog_dirs заменяет список рабочего пространства для этого Release. Порядок поиска, каталог catalog, читаемый после него, и смысл пустого списка — те же, что и для собственного списка рабочего пространства.
  • catalog_dirs_append читается после списка Release. Запись, в которой указан только catalog_dirs_append, сохраняет список рабочего пространства и дополняет его.

Release, не названный в карте, читает собственный workspace.catalog_dirs рабочего пространства. Release, названный в карте, читает собственные каталоги, как бы он ни собирался — aggrega build или aggrega pull в терминале, редактором через aggrega serve, ассистентом через aggrega mcp, — поэтому ни одному из них не нужен флаг, чтобы найти свой каталог. --catalog <dir> в командной строке по-прежнему просматривается раньше каталогов Release, для этого одного вызова. А поиск, не нашедший сущности под использованным вами именем, указывает запись этого Release как место, где следует перечислить содержащий её каталог.

Запись, указывающая несуществующий файл, отклоняется при загрузке конфигурации с указанием записи и файла. Поэтому переименование Release останавливает каждую команду, пока запись не переименуют вместе с ним, а не позволяет Release собираться по списку рабочего пространства без какого-либо уведомления об этом. Директория, которую перечисляет запись, должна быть директорией, как и та, что указана в списке рабочего пространства: не являющуюся директорией отклоняет каждая команда, читающая каталог этого Release, с указанием записи и её строки.

То, что не касается какого-либо одного Release, по-прежнему читает список рабочего пространства: линтинг или валидация всего каталога, поиск сущности по имени, Aggregate, проверяемый сам по себе, и список сущностей рабочего пространства в редакторе. AGGREGA_CATALOG_DIRS задаёт список рабочего пространства и не затрагивает ни одну запись здесь, а файл конфигурации, которым владеет ваш конвейер, карту не читает вовсе.

Файл конфигурации, которым владеет ваш конвейер

Файл с именем .aggrega-config-append-ci.yaml может находиться рядом с написанным вручную файлом в любом каталоге, который посещает обход. Это отдельный файл, чтобы автоматизированный конвейер мог владеть им и перезаписывать его целиком, никогда не затрагивая написанное человеком.

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

Куда указывает относительный путь

Относительный путь в файловой системе разрешается относительно каталога файла, в котором он объявлен, — не относительно корня проекта и не относительно каталога, из которого вы запустили команду. Это правило стоит перечитать дважды: путь, который выглядит как путь относительно проекта, разрешается в другое место, а сборка всё равно завершается успешно — с содержимым, которое вы не имели в виду.

Оно применяется к workspace.catalog_dirs, к файлам сущностей Release, указанным ключами в workspace.releases, и к каталогам, которые перечисляет каждая запись, к локальным путям файловой системы в подключении plugins.governance или plugins.linter — uri, указывающему на файл .wasm на диске, и к каждой записи в with.sources этого подключения, — а также к каждой записи в with.sources подключения plugins.importer. Во всех трёх списках uri без двоеточия, не называющий реестр, — как importer/agent-flows, так и ./lint/api-rules.wasm, — является таким путём, тогда как uri, называющий плагин по его идентификатору, содержит версию после двоеточия, importer/agent-flows:1.2.0, и остаётся в точности как написан. uri подключения импортёра называет подключаемый импортёр, как описано в разделе Какой импортёр превращает источник в черновики; импорт не читает модуль по указанному там пути. Правило применяется и к записям в дополняющих ключах, и каждая из них привязывается к собственному объявляющему файлу, а не к файлу, на котором заканчивается слияние. Оно применяется также к mcp.tls.cert_file, mcp.tls.key_file и mcp.authorization.jwks_file, так что файл, лежащий рядом с файлом, который его называет, находится, откуда бы ни был запущен сервер.

Итак, при такой структуре:

myproject/
├── .aggrega-config.yaml
└── services/
├── .aggrega-config.yaml
└── catalog/

и ./catalog, записанном в корневом файле, путь обозначает myproject/catalog. Записанный в services/.aggrega-config.yaml, тот же текст обозначает myproject/services/catalog. Абсолютный путь остаётся в точности как написан, как и ссылка на реестр, например oci://hub.aggrega.ai/plugins/helm:1.0.0.

Следующие настройки намеренно не следуют этому правилу, потому что у них нет объявляющего файла, к которому можно привязаться, или потому что все, кто их читает, разрешают их в другом месте:

  • artifact_cache_dir интерпретируется относительно корня проекта, откуда бы ни запускалась команда, так что кэш — это один каталог, а не по одному на каждое место запуска. Абсолютное значение отклоняется при загрузке конфигурации.
  • AGGREGA_CATALOG_DIRS берётся из окружения и вообще не имеет объявляющего файла, поэтому указывайте в ней абсолютные пути.
  • mcp.listen берётся в точности как написан, включая путь файловой системы в форме unix:<path>. Тот же адрес может прийти и из aggrega mcp --listen, у которого нет объявляющего файла, поэтому привязка только варианта из конфигурации заставила бы одну строку обозначать два разных места в зависимости от источника. Указывайте для сокета абсолютный путь.

Одна настройка с общим хранилищем

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

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

Поэтому указывайте её в глобальном файле, если хотите один ответ для всего, что вы собираете, и держите её выше того, что компилирует одна сборка. aggrega cache status сообщает, что сейчас содержит хранилище, а aggrega config show --origin показывает, из какого файла на самом деле взят действующий лимит.

Настройки сервера, к которому обращаются другие

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

# <project>/.aggrega-config.yaml
mcp:
transport: http
listen: 127.0.0.1:7777
authorization:
issuer: https://login.example.com
resource: https://mcp.example.com/mcp
allowed_origins:
- https://studio.example.com
limits:
max_concurrent_requests: 32
deny_reach:
- registry
announce_tools:
- list-entities
- get-schema
- validate
- build
health:
listen: 127.0.0.1:7778

Транспорт выбирает mcp.transport. http запускает слушатель; stdio, вариант по умолчанию, работает через стандартный ввод и вывод, чего и ожидает клиент-подпроцесс. Любое другое значение отклоняется при загрузке этого файла. aggrega mcp --transport <stdio|http> делает то же для одного запуска и имеет приоритет над ключом, как любой флаг имеет приоритет над любым файлом.

mcp.listen указывает, где привязывается слушатель, и ничего не выбирает. Задайте адрес host:port или сокет unix:<path>; aggrega mcp --listen <address> имеет приоритет над ним для одного запуска. Если выбран http и адрес не задан ни там, ни там, запуск отклоняется до какой-либо привязки. Если выбран stdio, явно указанный --listen отклоняется, а адрес, заданный только этим ключом, не используется — сервер сообщает об этом одной строкой в потоке ошибок, называя этот файл и mcp.transport: http. Поэтому сервер, к которому обращаются другие, задаёт оба ключа, как выше, а клиент, запущенный из каталога, который покрывает этот файл, по-прежнему обращается к серверу через собственные потоки. Путь unix: берётся как написан, без привязки — см. Куда указывает относительный путь.

mcp.tls.cert_file и mcp.tls.key_file включают TLS в самом процессе. Задайте оба, и слушатель сам обслуживает HTTPS. Не задавайте ни одного, и он обслуживает открытый текст, что допускается только на loopback или на Unix-сокете — вариант для случая, когда прокси перед процессом держит сертификат и перенаправляет запросы процессу. Слушатель с открытым текстом на любом другом адресе отклоняется до какой-либо привязки с указанием этих двух ключей, как и задание одного из них без другого. Оба являются путями файловой системы и следуют правилу выше: относительный путь разрешается относительно каталога объявившего его файла, поэтому сертификат, закоммиченный рядом с этим файлом, находится, откуда бы ни был запущен сервер. Указывайте их абсолютными, если сертификат управляется вне проекта.

mcp.authorization.issuer и mcp.authorization.resource указывают, кто выдаёт токены, которые предъявляют вызывающие, и как называется этот сервер как ресурс, для которого они выдаются. Оба обязательны всякий раз, когда выбран транспорт http, и без них слушатель отклоняется до какой-либо привязки, потому что на каждый запрос к конечной точке отвечают вызовом bearer-токена, а вызов, который никуда не указывает, клиент не может обработать. Записывайте полные адреса, включая схему и хост: издателя — в точности так, как этот сервер авторизации сам указывает свой идентификатор, а ресурс — как адрес, по которому вызывающие действительно обращаются: хост, который предъявляет прокси перед сервером, если он есть, а не адрес, к которому привязывается этот процесс. Оба публикуются без запроса учётных данных в документе метаданных защищённого ресурса OAuth, который обслуживает слушатель; именно там клиент ищет, где получить токен. Ни один из них не содержит ничего секретного: токен приходит в запросе, который его предъявляет, и никогда не записывается в файл конфигурации. Издатель — это адрес https, если только сервер авторизации не работает на этой машине (localhost, 127.0.0.1 или ::1), и слушатель, указывающий простого издателя http на любом другом хосте, отклоняется до какой-либо привязки, каким бы способом он ни читал свои ключи и своих вызывающих: каждый клиент направляется к издателю за токеном, поэтому по простому http его код авторизации и токен передавались бы по сети без защиты, а если оттуда же читаются ключи, любой, кто находится на этом пути, мог бы их подменить.

mcp.authorization.jwks_file указывает файл с ключами, по которым проверяются токены, вместо того чтобы читать их с сервера авторизации. Если его опустить, сервер читает метаданные этого сервера по их стандартному адресу и следует опубликованному там jwks_uri; так поступает рабочее пространство с доступом к сети. К этому адресу ключей применяется то же правило, что и к издателю, как и к любому адресу, на который перенаправляется любое из этих чтений: к адресу с простым http на другом хосте запрос не выполняется никогда, а на токен, которому нужны эти ключи, отвечают 503, пока сервер авторизации не опубликует свои метаданные и ключи по https. Если его задать, к серверу авторизации никогда не обращаются — это нужно рабочему пространству, объявляющему offline: true, и такое рабочее пространство отклоняется до привязки слушателя, если этот ключ не указывает файл. Это путь, и он следует правилу выше: относительный путь разрешается относительно каталога файла, в котором он объявлен, поэтому набор ключей, закоммиченный рядом с этим файлом, находится, откуда бы ни запускался сервер. Файл содержит открытые ключи проверки, которые и публикует сервер авторизации, — ничего, что подписывает, и ничего секретного.

mcp.allowed_origins учитывается, только когда запрос содержит заголовок Origin, что на практике означает, что его отправил браузер. Перечислите там обслуживаемые источники; запрос, указывающий источник, которого нет в списке, отклоняется, а запрос без такого заголовка обслуживается в любом случае. Клиент, не являющийся браузером, такого заголовка не отправляет, и запись для него не нужна. Запись сравнивается с заголовком точно, поэтому пишите её так, как её отправляет браузер: схема в нижнем регистре, ://, хост в нижнем регистре и : с портом, только если порт не является портом схемы по умолчанию, — https://studio.example.com или http://localhost:3000 для страницы, обслуживаемой на вашей собственной машине, — без пути и без завершающего /. Запись любого другого вида никогда не могла бы совпасть и отклоняется при загрузке этого файла с указанием записи.

mcp.limits ограничивает то, что может запросить один вызывающий: какого размера может быть тело одного запроса, сколько запросов выполняется одновременно и сколько запросов один вызывающий может отправить за минуту. Все три ограничения действуют всегда; ни у одного нет значения, которое его снимает. Третье, requests_per_minute, считается для каждого вызывающего отдельно, поэтому интенсивные запросы одного вызывающего ничего не стоят другому.

mcp.authorization.trusted_proxy получает вызывающего от прокси перед сервером вместо проверки токена здесь. Задайте в principal_header заголовок, которым этот прокси сообщает, кто вызывающий, и при необходимости в scopes_header — заголовок с областями доступа этого вызывающего. Оба являются именами HTTP-заголовков, например X-Forwarded-User: буквы, цифры, дефисы и немногие другие символы, допустимые в имени заголовка, без пробелов и двоеточий; имя любого другого вида отклоняется при загрузке этого файла с указанием ключа, потому что ни один запрос не мог бы его содержать. В этом режиме токен не читается вовсе, а запрос без заголовка субъекта отклоняется. Поскольку тогда заголовок является единственным удостоверением, ему можно доверять только там, где больше никто не может его задать: процесс отклоняется до привязки, если mcp.listen не является loopback-адресом или Unix-сокетом. Если опустить блок, этот сервер сам проверяет токены, что является поведением по умолчанию; блок с пустым principal_header отклоняется, а не читается как это значение по умолчанию.

mcp.deny_reach отзывает у этого развёртывания определённый вид досягаемости. Каждая операция, которую выполняет сервер, объявляет, как далеко распространяются её последствия: none — для операции, которая читает или рендерит и ничего после себя не оставляет, workspace — для операции, которая пишет внутри рабочего пространства, обслуживаемого этим процессом, registry — для операции, которая публикует, подписывает или отзывает, и machine — для операции, которая изменяет то, что общее для всех рабочих пространств на хосте. Указание вида здесь отзывает каждый инструмент, который его достигает: инструмент отсутствует в списке инструментов любого вызывающего, что бы ни содержал токен этого вызывающего, а вызов его отклоняется с указанием этого параметра. Тем самым это ограничение развёртывания, а не вызывающего, и никакое удостоверение его не снимает: сервер, предназначенный только для чтения, перечисляет здесь три пишущих вида и после этого не может публиковать даже для вызывающего, чей токен содержит все области доступа. Если его опустить, что является поведением по умолчанию, это развёртывание допускает всё, что допускают области доступа его вызывающих. Значение, не входящее в эти четыре, отклоняется при загрузке этого файла, а не пропускается. Ничто вида machine не предлагается по HTTP, что бы здесь ни было указано, поэтому его указание принимается и ничего не меняет; в aggrega-mcp.md описаны виды и области доступа, которые их допускают.

mcp.announce_tools сужает то, что объявляет сервер, и это ограничение отличается от ключа выше. Перечислите инструменты, которые объявляет этот сервер, в написании, в котором их сообщает список инструментов, и объявляются именно они: пропущенный отсутствует в списке инструментов любого вызывающего и отклоняется, если его всё же вызывают по имени, с указанием этого параметра. Если опустить ключ (по умолчанию), объявляется каждый инструмент сервера; если записать пустой список, не объявляется ни один, поэтому эти два написания — разные утверждения, и никакое значение по умолчанию за вас не подставляется. От deny_reach его отличает то, что каждый из них отнимает. deny_reach отнимает возможность: операции отозванного вида здесь вообще не предоставляются, и никакое удостоверение не возвращает ни одну из них. announce_tools отнимает только объявление — пропущенные им инструменты остаются возможностями сервера, — и он отвечает на нужды клиента, который ограничивает число регистрируемых инструментов, иногда сразу по всем серверам, к которым подключён. Если заданы оба, побеждает отзыв, поэтому инструмент отозванного вида остаётся отсутствующим, как бы его ни называл этот ключ. Имя, которому не соответствует ни один инструмент, останавливает сервер до того, как он начнёт что-либо обслуживать, с перечислением имеющихся инструментов, а не оставляет вас с поверхностью уже запрошенной. В отличие от других ключей здесь, которые настраивают слушатель, запускаемый транспортом http, он читается при любом транспорте сервера, потому что клиент, ради которого существует сужение, обычно и запустил процесс через его собственные стандартные ввод и вывод; остальное описано в aggrega-mcp.md.

mcp.health.listen выносит проверки живости и готовности на отдельный адрес. Укажите адрес в любой из двух форм mcp.listen, и второй слушатель будет отвечать там на GET /healthz — 200 с момента запуска процесса — и на GET /readyz — 503, пока рабочее пространство не разрешено и конечная точка не привязана, и 200 после этого; именно это позволяет балансировщику придерживать трафик, пока процесс не сможет действительно ответить на вызов. Если ключ опущен, ни одна из проверок нигде не отвечает. На адресе, который называет mcp.listen, они не отвечают никогда: там они получают 404, как любой путь, который он не обслуживает, ведь проба на нём была бы неаутентифицированным чтением слушателя, который отклоняет всё остальное. В отличие от mcp.listen, этот адрес не ограничен, и ни один адрес для него не отклоняется — направьте его на loopback или Unix-сокет, до которого дотягивается супервизор рядом с этим процессом, и учтите, что всё, что может достичь выбранного вами адреса, может прочитать эти два ответа.

schema/other/aggrega-config.md описывает каждый из этих ключей вместе с его значением по умолчанию, если оно есть.

Другие способы распознать корень проекта

--workspace-root <path> или его аналог AGGREGA_WORKSPACE_ROOT прямо называет корень и пропускает обнаружение. Названная папка должна существовать: путь, который ничего не называет или называет файл, отклоняется до того, как команда сделает что-либо ещё, и в отказе указывается, какой из двух способов задал значение, и оно приводится так, как было задано. В противном случае обнаружение идёт вверх от рабочего каталога, и виды якорей ранжируются друг относительно друга, а не по близости:

  • Файл .aggrega-config.yaml с блоком workspace: побеждает безоговорочно, на какой бы глубине он ни находился. Обход продолжает подниматься в поисках такого файла, даже миновав маркер описанного ниже вида, поэтому явно отмеченный корень выше всегда побеждает случайный маркер под ним.
  • Если такого нет, корень закрепляет ближайший из этих маркеров, а внутри одного каталога они ранжируются в таком порядке: каталог .aggrega/, затем aggregate*.yaml, затем release*.yaml, затем manifest*.yaml.
  • Если ничего не найдено, используется рабочий каталог — команды выполняются, а не отказываются запускаться. Команда, результат которой зависит от рабочего пространства, — та, что читает или записывает документы рабочего пространства, читает или заполняет его кэш артефактов либо обслуживает его, — один раз выводит предупреждение в стандартный поток ошибок: warning: <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace. Команда, результат которой не зависит от того, какая папка является корнем, ничего не сообщает, даже если читает конфигурацию: среди них aggrega version, aggrega config show, aggrega plugin list, aggrega registry list, aggrega explain и aggrega login. aggrega config capture, задача которой — записать собственный файл конфигурации рабочего пространства, в такой папке ничего не записывает и завершается с ошибкой, сообщающей об этом.

В такой папке ничего не записывается в кэш артефактов. Каталог .aggrega/ сам является одним из описанных выше маркеров, поэтому кэш, записанный там, сделал бы папку рабочим пространством лишь потому, что в ней однажды что-то было загружено. Команда, работа которой заполняет кэш, — aggrega pull, сборка, которая сначала разрешает свои зависимости, aggrega registry update, добавление плагина-расширения команд из реестра, — отклоняется до того, как что-либо загрузит, с указанием папки и двух выходов: назвать рабочее пространство с помощью --workspace-root или AGGREGA_WORKSPACE_ROOT либо добавить в папку .aggrega-config.yaml с блоком workspace:. aggrega pin, а также aggrega push для сущности Recipe или FeatureRecipe, которая привязана к закреплениям, записанным в entity.lock рядом с ней, заполняют кэш только удалёнными источниками, которые сущность выписывает полностью и которые загружаются при её закреплении или сверке её закрепления: они отклоняются тем же образом там, где загрузили бы такой источник, до его загрузки. Сущность без такого источника — вовсе без источника, с локальным источником или с источником, координаты которого заполняет каждая сущность Release, — закрепляется или публикуется там так же, как в любом другом месте. Сборка там не отклоняется, но внешний вход, который закрепляет её lock-файл и которого больше нет в кэше, повторно не загружается для восстановления: вместо этого входа рендеру сообщается та же фраза, так же как ему сообщается фраза автономного режима, и он о ней сообщает. Место, куда artifact_cache_dir помещает кэш, здесь ничего не меняет, потому что каталог присоединяется к тому корню, который был найден. Команды, которые только читают, по-прежнему отвечают.

У этого последнего запасного варианта есть одно исключение. Когда корень ничем не назван и рабочий каталог ничего не закрепляет, команда, касающаяся одной сущности Release или одного документа сущности и называющая этот файл абсолютным путём, снова обнаруживает корень, поднимаясь вверх от папки, где лежит файл, и использует то, что найдёт: рабочее пространство, к которому принадлежит файл, или, если не найдено ничего, эту папку. Файл — это тот, который называет --release в aggrega build и aggrega pull; сущность Release, переданная aggrega validate, aggrega lint и aggrega inspect, или же переданный им файл; и документ, переданный aggrega pin, aggrega push и aggrega edit-document. Поэтому сущность Release проекта, собранная извне проекта, читает собственную конфигурацию проекта, как и при запуске команды внутри него, а предупреждения о конфигурации, которые выводит команда, относятся к этому рабочему пространству. Если собственная папка файла тоже ничего не закрепляет, именно её называет уведомление команды и именно в ней не записывается кэш. Относительный путь читается относительно каталога, в котором вы запускаете команду, и ничего не меняет, а названный корень или рабочий каталог, который сам находится внутри рабочего пространства, используется как есть. Сервер ассистента применяет то же правило к вызову, который называет свою сущность Release или документ абсолютным путём.

Отметка корня блоком workspace: — явный и предпочтительный выбор; маркеры-файлы и маркеры-каталоги позволяют всё же собрать проект, который его не объявил.

Явное указание глобального файла

Глобальный слой разрешается в таком порядке:

  1. --config <path> — форма для отдельного вызова.
  2. Переменная окружения AGGREGA_CONFIG.
  3. Расположение по умолчанию: в Windows — aggrega\config.yaml внутри каталога, который называет переменная окружения APPDATA, а в остальных системах — aggrega/config.yaml внутри каталога, который называет XDG_CONFIG_HOME, с запасным вариантом ~/.config/aggrega/config.yaml.

Первые два способа называют явный файл, поэтому несуществующий путь — это громкая ошибка, а не тихий откат: вы запросили конкретный файл. Команда, читающая свою конфигурацию, останавливается с одной фразой, которая заканчивается путём, чтобы его можно было скопировать. aggrega config init — исключение, потому что создание этого файла и есть её назначение: она создаёт названный файл и сообщает об этом. Расположение по умолчанию загружается, когда файл там есть, и молча пропускается, когда его нет. Какой бы файл ни был найден, файлы вашего проекта по-прежнему накладываются поверх него.

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

Этот выбор также определяет, куда записывает команда, изменяющая конфигурацию. Команда, запущенная с --config <path>, читает конфигурацию из этого файла и применяет изменение к тому же файлу, поэтому то, что записывает одна команда, читает следующая.

В какой из двух файлов команда записывает по умолчанию, зависит от характера настройки: общемашинные инструменты, например реестр, попадают в глобальный файл, а настройки, участвующие в сборке, например привязка провайдера или подключение сокета, — в зафиксированный файл проекта, чтобы они перемещались вместе с проектом. Чтобы переопределить это, передайте --global или --workspace, и команда выведет файл, в который записала.

См. также

  • aggrega-config.md — команды aggrega config, которые создают начальную конфигурацию, просматривают и фиксируют её.
  • environment-variables.md — все переменные с префиксом AGGREGA_ и то, где передаются секреты.
  • global-flags.md — --config, --workspace-root и другие флаги, которые принимает каждая подкоманда.
  • schema/other/aggrega-config.md — каждый ключ конфигурации, его тип и значение по умолчанию.
  • aggrega-cache.md — что на самом деле хранится в artifact_cache_dir.
  • workspace-boundary.md — какие пути остаются внутри рабочего пространства и как каталоги и файлы, которые называет эта конфигурация, выходят за его пределы.
  • aggrega-mcp.md — сервер, который настраивает блок mcp.