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

aggrega config

Инспекция и управление конфигурацией рабочего пространства

Синтаксис

aggrega config

Описание

Inspect and manage the configuration Aggrega reads.
Most projects need two files.
One .aggrega-config.yaml at your project root, carrying a "workspace:" block —
that block is what marks the root — holds how this project builds: its catalog
directories, its provider bindings, which lint rules it relaxes. It is
committed, so a teammate who clones the project builds it the same way.
One global file is shared across every workspace on this machine:
~/.config/aggrega/config.yaml, or on Windows aggrega\config.yaml inside the
directory the APPDATA environment variable names. It holds what belongs to the
machine rather than to any one project: the registries you pull from and the
signature trust policy for each, how large the compiled-module store may grow,
any command extension you have installed. It loads automatically when it is
there, and nothing breaks when it is not.
Your project's file wins over the global one, an environment variable wins
over both, and a flag wins over everything.
Secrets are not configuration. A registry password or a signing identity token
is never a field in either file; it is supplied by environment variable or flag
at the moment it is needed.
Because the effective configuration is assembled rather than written anywhere,
"aggrega config show" is how you see what actually applies, and --origin is how
you find out which layer each setting came from. "aggrega config init" seeds a
working configuration, and "aggrega config capture" freezes the effective
build-critical settings into this workspace so a build does not depend on a
global file that is not committed.
Larger projects have more to work with. None of it is needed to start, and each
piece exists for the shape it solves:
More than one file inside a project. Every .aggrega-config.yaml from the
project root down to the directory you run in contributes, a nearer file
overriding a farther one. Only a file carrying "workspace:" marks the root;
one without it contributes settings without anchoring anything.
Extending a list instead of replacing it. A nearer file's list replaces the
farther one's. The companions catalog_dirs_append, governance_append,
linter_append, importer_append and providers_append concatenate onto the
resolved list at each layer instead of shadowing it.
A file your pipeline owns. .aggrega-config-append-ci.yaml may sit beside the
hand-authored file in any of those directories, so automation can overwrite
it wholesale without touching what a person wrote. It is additive only: it
removes nothing and overrides no scalar, and a scalar key written in it is
ignored and named in a warning. It never marks a root.
A relative path anchors to the file that declared it. A catalog directory, a
local plugin path, or an entry under a plugin's with.sources resolves against
the directory of the config file it was written in — not the project root,
and not the directory you ran the command from. So the same "./catalog" names
a different directory depending on which file carries it. Two settings sit
outside this rule: artifact_cache_dir is interpreted relative to the project
root wherever you run from, and AGGREGA_CATALOG_DIRS has no declaring file at
all, so supply absolute paths in it.
The other root markers. A "workspace:" block wins outright at whatever depth
it sits. Failing one, the nearest .aggrega/ directory or aggregate*.yaml,
release*.yaml or manifest*.yaml file anchors the root, in that order within a
directory; failing everything, your working directory is used.
--workspace-root skips discovery entirely.
Naming the global file. --config <path> wins over the AGGREGA_CONFIG
environment variable, which wins over the default location. Both name a file
deliberately, so a path either gives that does not exist is a loud error
rather than a silent fallback. Whichever file resolves is also the one a
config-writing command writes when it writes globally.

Подкоманды

КомандаОписание
aggrega config captureЗафиксировать действующую конфигурацию, критичную для сборки, в этом рабочем пространстве
aggrega config initСоздать рабочую конфигурацию с реестром и его политикой доверия
aggrega config showПоказать действующую конфигурацию и источник каждого параметра

Описание aggrega config capture

Write the effective build-critical configuration into this project's workspace
config file, so the workspace builds identically without relying on the
machine's global configuration.
The build-critical subset is the configuration a build participates in: a set of
plugin socket attachments and the catalog directories. By default the captured
sockets are only those that determine the
rendered output — the provider bindings and the transform-role governance attachments — since only those must
travel with the project for byte-identical output. Pass --all-plugins to also
freeze the verdict-role governance, linter, and importer sockets, which otherwise stay free to
vary by environment. Each field is written at its effective value — the value
that resolves right now with the global configuration and the workspace tree
merged together — so a binding that today comes only from the global config is
materialized into the workspace and travels with the project.
Machine-wide tooling settings, such as a registry's trust policy, are not
captured: they stay in the global config by their nature. Capture always writes
this project's workspace config file. Running it again on an unchanged
configuration rewrites the same file byte-for-byte. Run in a folder that is not
inside a workspace, with no --workspace-root naming one, it writes nothing and
exits with an error saying so.

Флаги aggrega config capture

ФлагПо умолчаниюОписание
--all-pluginsfalseЗафиксировать все сокеты плагинов, включая шлюзы governance с ролью verdict, линтеров и импортёров. Без этого флага capture фиксирует только сокеты, определяющие результат рендеринга (привязки провайдеров и подключения governance с ролью transform).

Описание aggrega config init

Seed a working configuration by registering a registry and its signature trust
policy, so a fresh machine can pull and verify signed artifacts without editing
YAML by hand.
By default it registers the official hub (hub.aggrega.ai) with signatures
required and the official trusted identities. The registry's advertised trust
policy is fetched once from its own origin and pinned locally — trust-on-first-
use; when the hub is unreachable, advertises nothing, or the workspace is
offline, its built-in official baseline is written instead, so init still
produces a usable config offline. Pass --registry to seed a different registry
(for an air-gapped or private hub). Such a registry has no built-in baseline,
so seeding it while the workspace is offline is refused: init takes no
identities or key to pin by hand, so register it once while online, or add it
with "aggrega registry add --identity" or "--key".
The entry is written to the global config shared across every workspace by
default; pass --workspace to write it to this project's workspace config
instead. If the target config file already exists, init refuses rather than
overwrite it — pass --force to write anyway (the registry entry is merged into
the existing file, other settings preserved).
Before anything else, init says where things are: the configuration file it
created — or, under --force, the one already there that it wrote into — and
the directory the machine-wide caches are kept in. On Windows that directory is
aggrega\cache inside the directory the LOCALAPPDATA environment variable names;
elsewhere it is a directory named aggrega under the per-user cache directory:
~/.cache/aggrega on Linux unless XDG_CACHE_HOME names another, and
~/Library/Caches/aggrega on macOS.
A seeded configuration is a document you own and go on editing, so --dry-run does
everything init does except write: it hands the content back, creating and
modifying nothing. The answer names the file the content is for — which matters
here, because the target is the global config unless --workspace selects this
project's own. A caller that keeps its own document model puts the content there,
where it is visible before it is saved and can be amended or undone. The registry
is still contacted for its advertised trust policy, because the policy in that
content is the policy a write would have pinned.
Because a dry run does everything else init does, it refuses an existing config
file exactly as a write refuses it, and for the same reason. So its exit code
predicts the write's: if the dry run refuses, init would have refused. Pass
--force alongside it to see the merge an overwriting write would produce.
Under --dry-run standard output carries that content and nothing else, so it stays
parseable. A registry seeded with no trust policy, because it advertises none,
still produces its notice, on standard error: read that stream too, or that
configuration arrives without the advice to pin identities by hand. A pinned
policy, whether advertised or the hub's built-in baseline, is in the content
itself and produces no notice.

Флаги aggrega config init

ФлагПо умолчаниюОписание
--dry-runfalseВыполнить всё, кроме записи: вернуть созданную конфигурацию как содержимое с указанием файла, для которого она предназначена, ничего не создавая и не изменяя. Всё остальное поведение совпадает с поведением записи, поэтому существующий файл конфигурации отклоняется точно так же, как при записи, — передайте вместе с ним —force, чтобы получить слияние, которое произвела бы перезаписывающая запись.
--forcefalseПерезаписать существующий файл конфигурации. Без этого флага init отказывается работать, если целевой файл уже существует.
--globalfalseЗаписать запись в глобальную конфигурацию, общую для всех рабочих пространств. Это поведение по умолчанию.
--registryhub.aggrega.aiХост реестра, добавляемого вместе с его политикой доверия. По умолчанию — официальный хаб.
--workspacefalseЗаписать запись в конфигурацию рабочего пространства этого проекта вместо глобальной конфигурации.

Описание aggrega config show

Show the configuration that applies right now.
By default it leads with the cascade of config files and environment overrides
that contributed, lowest precedence first, then prints the effective merged
configuration — the global config, the workspace-tree cascade, and any
environment override combined into what applies right now.
Pass --global or --workspace to print a single layer's own file bytes verbatim,
preserving its comments and formatting; when that layer's file does not exist it
says so rather than failing. The two are mutually exclusive.
Pass --origin to annotate each effective setting with the layer it came from —
a command-line flag, an environment variable, a config file, or the built-in
defaults, highest precedence first. A flag is named as the reader typed it, so
a setting a flag decided reports that flag as its source. A setting is
attributed to the highest-precedence layer that sets it, whatever value that
layer writes: a file restating the default is the file named, not the built-in
defaults. List and map settings are attributed as a whole. The signing
requirement is the one exception: any layer may turn it on and none can turn it
off, so it names the first layer that turns it on.

Флаги aggrega config show

ФлагПо умолчаниюОписание
--globalfalseВывести байты глобального файла конфигурации дословно, сохраняя его комментарии и форматирование.
--originfalseПометить каждый действующий параметр слоем, из которого он получен (флаг командной строки, переменная окружения, файл конфигурации или встроенные значения по умолчанию).
--workspacefalseВывести байты файла конфигурации рабочего пространства этого проекта дословно, сохраняя его комментарии и форматирование.

Что делает команда

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

config init — создание рабочей конфигурации

aggrega config init создаёт конфигурацию на новой машине, регистрируя реестр и его политику доверия к подписям, чтобы подписанные артефакты загружались и проверялись без ручного редактирования YAML. По умолчанию регистрируется официальный хаб (hub.aggrega.ai) с обязательными подписями и его официальными доверенными идентичностями. Объявленная реестром политика доверия однократно загружается с его собственного источника и закрепляется локально (доверие при первом использовании); если хаб недоступен, ничего не объявляет или рабочее пространство находится в автономном режиме, вместо неё записывается встроенная официальная базовая политика, поэтому init создаёт пригодную конфигурацию и без сети.

Прежде всего init сообщает, где что находится. Инициализация новой машины с Linux начинается с:

Created the global configuration file at /home/you/.config/aggrega/config.yaml
Machine-wide caches are kept in /home/you/.cache/aggrega

а новой машины с Windows — с:

Created the global configuration file at C:\Users\you\AppData\Roaming\aggrega\config.yaml
Machine-wide caches are kept in C:\Users\you\AppData\Local\aggrega\cache

Первая строка называет файл конфигурации, который записала команда init: Created, если файла не было, и Using, если он был и --force позволил init записать в него; при --workspace вместо глобального называется файл конфигурации рабочего пространства. Вторая называет каталог, в котором хранятся общие для машины кэши — скомпилированные плагины и их описания; это место, где каждая платформа хранит кэши пользователя; правило для каждой платформы приведено в разделе Какие кэши принадлежат проекту, а какие — машине. Каждая строка заканчивается путём, и после него ничего нет, поэтому путь можно скопировать как есть. Последующие строки относятся к самой регистрации: что обнаружила загрузка политики доверия и в каком файле зарегистрирован реестр. Отклонённая инициализация не выводит ни одной из этих строк, поскольку ничего не создала; не выводит их и --dry-run, стандартный вывод которого содержит только возвращаемое содержимое.

  • --registry <host> инициализирует другой реестр — изолированный или частный хаб — вместо официального. У такого реестра нет встроенной базовой политики, поэтому если он ничего не объявляет, запись создаётся без политики, а в автономном рабочем пространстве его инициализация отклоняется (краткий код E0310): политику невозможно загрузить, а init не принимает --identity или --key, чтобы закрепить её вручную. Инициализируйте его один раз при наличии сети или добавьте с помощью aggrega registry add и предоставленной вами политики.
  • Если целевой файл уже существует, init отказывается его перезаписывать; --force всё же выполняет запись, объединяя запись реестра с существующим файлом и сохраняя остальные настройки.
  • --dry-run делает всё то же, что и init, кроме записи. Он возвращает созданную конфигурацию как содержимое, ничего не создавая и не изменяя, а в ответе указан файл, для которого предназначено содержимое, — это важно, потому что целью является глобальная конфигурация, если только --workspace не выбирает собственную конфигурацию проекта. Вызывающая программа со своей моделью документа, например редактор, помещает содержимое туда, где его видно до сохранения и можно изменить или отменить.
  • Поскольку пробный запуск делает всё остальное, что делает init, его код завершения предсказывает код записи. Он отклоняет существующий файл конфигурации точно так же и по той же причине, что и запись, поэтому с его помощью можно узнать, завершится ли init успешно, прежде чем вносить изменение. Чтобы увидеть документ, который создала бы перезаписывающая запись, передайте вместе с ним --force: --force --dry-run сообщает результат объединения и по-прежнему ничего не записывает.
  • К реестру всё равно выполняется обращение за объявленной политикой доверия, потому что политика в возвращаемом содержимом — это та политика, которую закрепила бы запись. Пробный запуск выполняет к собственному источнику реестра тот же единственный неаутентифицированный запрос, что и запись.
  • При --dry-run стандартный вывод содержит это содержимое и ничего больше, поэтому его можно разбирать программно. Единственное, что содержимое выразить не может, — это отсутствие: если реестр не объявляет политику доверия и инициализируется без неё, уведомление об этом — с предложением закрепить идентичности через --identity или --key — выводится в стандартный поток ошибок. Документ конфигурации без доверенных идентичностей выглядит одинаково, была ли закреплена оказавшаяся пустой политика или никакая политика не объявлялась вовсе, поэтому читайте оба потока; программа, отбрасывающая стандартный поток ошибок, ничего об этом не узнает. Если реестр объявляет политику или вместо неё закрепляется встроенная базовая политика официального хаба, закреплённая политика находится в самом возвращаемом содержимом и отдельное уведомление не выводится.

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

config show — просмотр того, что действует сейчас

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

Два специализированных представления сужают вывод:

  • --global или --workspace выводит байты файла одного слоя дословно, с сохранением комментариев и форматирования; если файла этого слоя нет, команда сообщает об этом, а не завершается ошибкой. Эти два флага взаимоисключающие.
  • --origin помечает каждую действующую настройку слоем, из которого она получена, — флаг командной строки, переменная окружения, файл конфигурации или встроенные значения по умолчанию, начиная с наивысшего приоритета. Флаг называется так, как вы его ввели, поэтому для настройки, определённой при этом запуске флагом --offline, источником указывается --offline; переменная окружения называется с префиксом env:, а файл конфигурации — по абсолютному пути.

При --origin настройка приписывается слою с наивысшим приоритетом, который её задаёт, каким бы ни было записанное этим слоем значение. Поэтому файл проекта, в котором записано default_registry: hub.aggrega.ai, указывается для этой настройки, даже если встроенное значение по умолчанию — тот же реестр, а файл проекта, повторяющий значение, уже заданное глобальным файлом, указывается вместо глобального файла: в обоих случаях именно этот файл удерживает значение, и именно его удаление изменит ответ в тот день, когда изменится значение по умолчанию или нижележащий файл. Для настройки, которую не задаёт ни один слой, указываются встроенные значения по умолчанию.

  • Что считается заданием настройки. Файл конфигурации задаёт настройку, если содержит её ключ, а настройку-список — также если содержит сопутствующий ключ _append этого списка. Переменная окружения задаёт свою настройку, если экспортирована с непустым значением, а флаг — когда вы его вводите: --offline=false задаёт режим так же определённо, как и --offline.
  • Файл конфигурации, которым владеет ваш конвейер, указывается только для ключей, ради которых он читается, — его дополнений списков и политики подписи. Ключ, который он игнорирует и о котором выводит предупреждение, никогда не указывается как источник значения.
  • Настройки-списки и настройки-словари приписываются целиком слою с наивысшим приоритетом, который их задаёт; какой слой внёс какой элемент списка, не сообщается.
  • Единственное исключение — требование подписи. Любой слой может его включить, и ни один не может выключить, поэтому указывается первый слой, который его включает. Слой, в котором записано required: false, ничего не включает, поэтому если ни один слой его не включает, для настройки указываются встроенные значения по умолчанию.

config capture — фиксация критичных для сборки настроек

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

Фиксируемое подмножество — это набор подключений плагинов к сокетам и каталоги каталогов сущностей:

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

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

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

См. также

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