跳转到内容
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捕获所有插件插槽,包括裁决角色的治理、linter 和导入器关卡。不使用此标志时,capture 只冻结决定渲染输出的插槽(provider 绑定和转换角色的治理挂载)。

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要连同其信任策略一起写入的注册表主机。默认为官方 hub。
--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 通过注册一个 registry 及其签名信任策略,在新机器上初始化配置,使已签名的制品无需手动编辑 YAML 即可拉取并验证。默认情况下,它注册官方 hub(hub.aggrega.ai),要求签名,并使用其官方受信任身份。registry 公布的信任策略会从其自身源获取一次并固定在本地(首次使用时信任);当 hub 无法访问、未公布任何内容或工作区处于离线状态时,会改为写入其内置的官方基线,因此 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,文件已存在且 --force 允许 init 写入时为 Using;在 --workspace 下,它指出的是工作区配置文件而非全局配置文件。第二行指出存放机器级缓存(已编译的插件及其描述)的目录,即各平台存放用户缓存的位置;哪些缓存属于此项目,哪些属于机器给出了各平台的规则。每行以其路径结尾,后面没有其他内容,因此可以直接复制该路径。随后的各行属于注册本身:信任策略获取的结果,以及 registry 注册到了哪个文件。被拒绝的初始化不会打印这两行,因为它没有创建任何内容;--dry-run 也不会打印,其标准输出只包含它返回的内容。

  • --registry <host> 初始化另一个 registry(隔离网络或私有 hub),而不是官方 registry。此类 registry 没有内置基线,因此在它未公布任何内容时,条目写入时不带策略,并且在离线工作区中初始化它会被拒绝(短代码 E0310):策略无法获取,而 init 不接受 --identity 或 --key 来手动固定策略。请在联网时初始化一次,或使用 aggrega registry add 并提供你自己的策略来添加它。
  • 如果目标文件已存在,init 会拒绝而不是覆盖它;--force 则仍然写入,将 registry 条目合并到现有文件中并保留其他设置。
  • --dry-run 执行 init 所做的一切,只是不写入。它将初始化的配置作为内容返回,不创建也不修改任何东西,并且返回结果会指出该内容对应的文件——这一点在这里很重要,因为除非 --workspace 选择了此项目自己的配置,否则目标是全局配置。维护自己文档模型的调用方(例如编辑器)会将内容放入其中,在保存前可见,并可修改或撤销。
  • 由于 dry run 执行 init 的其他所有操作,其退出码可预示写入的结果。它拒绝现有配置文件的方式与写入完全相同,原因也相同,因此你可以在确定更改之前用它来询问 init 是否会成功。要查看覆盖写入会生成的文档,请同时传入 --force:--force --dry-run 会报告合并结果,但仍不写入任何内容。
  • 仍会联系 registry 获取其公布的信任策略,因为所报告内容中的策略就是写入时会固定的策略。dry run 向该 registry 自身源发出的单个未经身份验证的请求与写入时相同。
  • 在 --dry-run 下,标准输出只包含该内容,因此保持可解析。内容唯一无法表达的是“缺失”:当 registry 未公布信任策略且初始化时不带策略时,说明这一情况并提示你使用 --identity 或 --key 固定身份的通知会输出到标准错误。无论是固定的策略恰好为空,还是根本没有公布策略,不含受信任身份的配置文档看起来都一样,因此请读取两个流;丢弃标准错误的程序对此一无所知。当 registry 确实公布了策略,或改为固定官方 hub 的内置基线时,固定的策略就在所报告的内容中,不会产生单独的通知。

初始化的配置是你拥有并持续编辑的文档,因此可以将其返回而不是写入。下文所述的冻结有效配置则生成配置解析结果的记录——这是编译器关于自身保存的状态,而不是任何人编写的内容——因此它总是写入,且不提供 --dry-run。

config show — 查看当前生效的配置

aggrega config show 报告当前生效的配置。在默认视图中,它首先列出起作用的配置文件和环境覆盖的级联(优先级最低的在前),然后打印合并后的有效配置——即全局配置、工作区树级联以及所有环境覆盖层组合成的单一结果。通过这一已加载文件的级联,你可以确认哪些文件和环境覆盖决定了当前配置。

两个聚焦视图可缩小输出范围:

  • --global 或 --workspace 原样打印单个层自身的文件字节,保留注释和格式;当该层的文件不存在时,它会说明这一点而不是失败。两者互斥。
  • --origin 为每项有效设置标注其来源层——命令行标志、环境变量、配置文件或内置默认值,优先级最高的在前。标志按你输入的形式命名,因此本次运行中由 --offline 决定的设置会报告 --offline 作为其来源;环境变量以 env: 前缀命名,配置文件则以其绝对路径命名。

在 --origin 下,设置归属于设置它的优先级最高的层,无论该层写入什么值。因此,写入 default_registry: hub.aggrega.ai 的项目文件会被列为该设置的来源,即使内置默认值是同一个 registry;重复全局文件已设置值的项目文件也会被列出,而不是全局文件:在这两种情况下,它都是实际持有该值的文件,并且一旦默认值或其下层文件发生变化,删除它就会改变结果。没有任何层设置的设置会报告内置默认值。

  • 什么算作设置。 配置文件包含某项设置的键时即设置了该设置;对于列表设置,包含该列表的 _append 配套键时也算。环境变量以非空值导出时即设置了其设置,标志则在你输入时即设置——--offline=false 与 --offline 一样确定地设置了该状态。
  • 由你的流水线拥有的配置文件只会因读取它的那些键而被列出,即其列表追加项和签名策略。它忽略并发出警告的键永远不会被报告为值的来源。
  • 列表和映射设置作为整体归属于设置它们的优先级最高的层;不报告列表中的哪个条目由哪个层贡献。
  • 签名要求是唯一的例外。 任何层都可以开启它,但没有层能关闭它,因此它列出第一个开启它的层。写入 required: false 的层不会开启任何东西,因此当没有层开启它时,该设置报告内置默认值。

config capture — 冻结对构建至关重要的设置

aggrega config capture 将当前生效的、对构建至关重要的配置写入本项目的工作区配置文件,使工作区无需依赖本机的全局配置即可得到完全相同的构建结果。机器范围的工具设置(例如注册表的信任策略)不会被捕获;这类设置本质上属于全局配置,会保留在其中。在配置未变的情况下再次运行,会逐字节相同地重写同一个文件。

捕获的子集是一组插件插槽挂载以及目录(catalog)路径:

  • 默认情况下,capture 只冻结决定渲染输出的插槽——provider 绑定以及 transform 角色的治理挂载——因为只有这些必须随项目一起迁移,才能得到逐字节相同的构建结果。目录(catalog)路径始终会被捕获。
  • --all-plugins 将捕获的插槽范围扩大,同时包括 verdict 角色的治理插槽、linter 插槽和 importer 插槽。不使用该标志时,这三类插槽可以随环境而变化。

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 所指定的目录中实际存放的内容,以及为什么存放在其中但未被任何锁文件固定的实体不会被构建找到。