全局标志
每个 aggrega 子命令都可使用的标志。
--workspace-root <path>
将 <path> 用作工作区根目录,完全跳过发现过程。省略该标志时,aggrega 会从当前目录向上逐级查找来发现根目录;如果这一查找没有找到任何结果,而命令又以绝对路径指定了其 Release 或文档,则改为从该文件所在的文件夹向上查找。关于什么能锚定根目录、按什么顺序锚定,以及哪些命令会指定这样的文件,请参阅配置。
AGGREGA_WORKSPACE_ROOT 是对应的环境变量:未给出 --workspace-root 时,由该变量提供根目录。两者都设置时,以标志为准。
无论根目录通过哪种方式给出,它都是根目录,服务器也不例外:发给 aggrega mcp 的请求如果没有指定自己的工作区,就在该根目录中处理,不会搜索其上层目录。如果根目录不是一个已存在的文件夹(路径不指向任何内容,或指向一个文件),每个读取其工作区的命令都会在执行任何其他操作之前拒绝它;aggrega serve 和 aggrega mcp 监听器会拒绝在这样的根目录上启动,而通过标准输入和输出运行的 aggrega mcp 仍会照常启动,但对每个在该工作区中执行操作的调用都以该拒绝作答。拒绝信息会指明根目录由两者中的哪一个提供,即 --workspace-root 或 AGGREGA_WORKSPACE_ROOT,并原样给出其值。不读取工作区的命令(例如 aggrega version)也不会读取根目录,因此不会因此被拒绝。
如果两者都未给出,且发现过程没有锚定任何目录,则命令运行所在的文件夹即为根目录,读取其工作区的命令会在标准错误输出中用一行说明这一点,并指明该文件夹和此标志;请参阅配置,其中也说明了为什么在这样的文件夹中不会向制品缓存写入任何内容。
全局配置文件
--config <path> 为单次调用显式指定全局配置文件。它优先于 AGGREGA_CONFIG 环境变量,而后者又优先于默认位置——由于两者都是有意指定某个文件,路径不存在时会明确报错,而不是静默回退。与 AGGREGA_* 设置变量不同,两者都不覆盖单个设置,而是选择应用哪个文件。无论最终解析到哪个文件,项目自身的配置文件仍会叠加在它之上。配置介绍了解析顺序以及该文件中应包含的内容。
--config 和 AGGREGA_CONFIG 环境变量既选择读取来源,也选择写入目标:使用 --config <path> 运行的命令从该文件读取配置,并将其更改写入同一文件,因此一条命令写入的内容,正是以相同调用形式运行的下一条命令读回的内容。
修改配置的命令根据设置的性质选择写入哪个文件:机器范围的工具配置(registry)默认写入全局文件,而参与构建的配置(provider 绑定,或 governance/linter/importer 插槽挂载)默认写入已提交的项目文件。传入 --global 或 --workspace 可覆盖默认行为,命令会打印写入的位置。
要在新机器上初始化全局配置——注册一个 registry 及其签名信任策略,使已签名的制品无需手动编辑 YAML 即可拉取并验证——请运行 aggrega config init。要查看当前生效的配置,并通过 --origin 查看每项设置由哪一层决定,请运行 aggrega config show。
--offline
在本次运行中拒绝一切网络访问。
离线是一种工作区状态,而不是某一个命令的模式,可以从三个地方开启:此标志、AGGREGA_OFFLINE,以及配置文件中的顶层 offline 键。三者含义相同,并遵循通常的优先顺序——标志优先于环境变量,环境变量优先于配置文件。
**关闭方向与开启方向同样是该标志的职责。**当已提交的配置文件或已导出的变量开启了离线状态时,--offline=false 可为单个命令允许网络访问。在你无权编辑该文件时这一点尤为重要:如果一个项目的 .aggrega-config.yaml 包含 offline: true,那么所有克隆它的人都会被拒绝发布,而传入 --offline=false 是唯一既不需要提交、也不需要导出变量的办法。
哪些会被拒绝,哪些不会
界限取决于工作本身需要什么,而不是输入了哪个命令。
会被拒绝,因为不访问 registry 就无法成立:
--upgrade,无论出现在何处。它会重新解析每个依赖,并将每个依赖浮动到 registry 当前提供的最高版本,而“最高可用版本”是关于 registry 此刻提供什么内容的断言。如果针对已有缓存运行它,就会锁定恰好被缓存的版本,同时报告已浮动到最新版本,这比直接停止更糟。- 其本身工作就是一次网络往返的命令:
aggrega push、aggrega push-artifact和aggrega registry update。这些命令会在读取你的实体或遍历你的仓库之前就给出提示,且拒绝信息会指明是三个地方中的哪一个设置了离线状态,这样没有输入任何标志的人也知道该去哪里查看。
不会被拒绝,因为本机可能已经能够满足它:
- 普通的
aggrega pull,以及aggrega build --auto-pull。两者都遵循已记录的锁定版本,只解析尚无锁定的内容,因此如果工作区的所有引用都已缓存或存在于catalog_dirs目录中,就能完全不访问网络而完成。如果这样的运行确实需要获取某些内容,它会在那一刻被拒绝,并被告知无法满足的是哪个引用。 - 针对已填充的 lockfile 运行的
aggrega build,它从缓存中读取整个闭包。它唯一的网络访问是一种修复:如果存储中某个已锁定的外部输入的副本丢失,会按 lockfile 已记录的摘要重新获取该输入。在离线状态下,连这一操作也没有可用的传输方式,因此丢失的副本会使构建停止,并指明离线状态。 --dry-run发布。它的全部行为就是报告将要发布的内容而不调用任何东西,因此它是发布的离线安全形式,而不是与离线状态相矛盾。
一台持有其目录和制品本地副本的隔离网络机器,正是这种划分要确保能继续工作的情形:这样的工作区处于离线状态,而它所做的几乎所有事情仍然可以满足。
配置优先级
标志的优先级高于一切:高于环境变量,高于配置文件,也高于内置默认值。配置给出了完整的优先级层次,environment-variables.md 则列出了所有以 AGGREGA_ 为前缀的变量。
aggrega config show --origin 会报告每项设置由上述哪一层决定,你输入的标志会被报告为标志——因此,当某次拒绝指出的层出乎你的意料时,可以用该命令加以确认。
另请参阅
- configuration.md — 某项设置应放在哪个文件中,以及完整的优先级模型。
- environment-variables.md — 完整的
AGGREGA_*变量参考。 - aggrega-serve.md — 守护进程通过同一根目录发现路径解析其工作区。
| 标志 | 默认值 | 描述 |
|---|---|---|
--config | — | 全局配置文件的路径,覆盖 AGGREGA_CONFIG 环境变量和默认位置。工作区树中的配置文件仍会叠加在其上 |
--no-color | false | 在所有输出中禁用 ANSI 颜色。也可通过 NO_COLOR 环境变量启用 |
--offline | false | 在本次运行中拒绝所有网络访问:无需编辑配置即可开启离线模式。若配置文件或 AGGREGA_OFFLINE 已开启离线模式,可传入 —offline=false 在单次运行中将其关闭。被拒绝的是离开 registry 就无法成立的操作:—upgrade(其全部作用就是将每个依赖浮动到 registry 当前提供的最高版本),以及本身工作就是一次网络往返的命令——push、push-artifact 和 registry update。仍可运行的是本机已能满足的一切:基于已填充 lockfile 的构建、针对已缓存或存在于本地目录中的引用的 —auto-pull,以及 dry run(它报告将要发布的内容,不发起任何调用) |
--plain | false | 无障碍模式:禁用颜色,并绘制简单、静态的进度行,不使用旋转动画或光标重绘,即使在终端上也是如此。专为屏幕阅读器设计 |
--workspace-root | — | 用作工作区根目录的绝对路径(跳过发现) |