CLI 概述
aggrega CLI 是编译器的入口。与 Aggrega 的每一种交互——将 Aggregate 编译为可部署的制品、检查目录或 IR、解析并锁定依赖、发布目录实体、用 validate 检查正确性、用 lint 检查发布约定,以及为 IDE 提供服务——都通过 aggrega 的某个子命令完成。本组章节介绍每个子命令的标志、输入和输出。
aggrega validate 和 aggrega lint 是互补的检查器,二者对应相同的三种范围——整个目录、一个 Release 的依赖闭包,或单个实体。aggrega validate 检查正确性(schema、支柱、引用解析、extends、provider 的输入种类能力,以及——对于渲染实体——隔离渲染);aggrega lint 检查发布约定(命名、类别目录对齐、注解前缀以及版本升级幅度)。二者都不输出制品;用 validate 回答“这是否正确?”,用 lint 回答“这是否遵循目录的发布规范?”。
aggrega build 遵循单一入口原则(Single Entry Point Principle):Release 是唯一的编译输入。aggrega build --release release.yaml 读取 Release 的 aggregate: 和 manifest: 指针来定位拓扑的其余部分,并在 dist/ 下按边界生成输出:命名边界渲染到其声明的 directory: 下,若未声明则渲染到 dist/boundaries/<boundary-name>/ 下;声明顶层 components: 而非命名边界的 Release 则直接平铺渲染到 dist/ 下。拓扑中的每个 component 都必须属于这些边界之一,不被任何边界包含的 component 会使构建停止:component 进入某个边界有两种方式,一是以子 Aggregates 展平后所带的 id 列在该边界的 components: 下,二是位于该边界通过 aggregates: 引入的某个子 Aggregate 之中。两种方式都不满足的 component 会渲染到 Release 声明的所有边界之外,其输出位置、同步波次、注解和每个 component 的 infra: 都无从获取,因此构建会停止并指出该 component,而不是输出未应用 Release 边界配置的制品。同样的关系也会从 Release 一侧检查:边界条目若指向拓扑中不存在的 component,则不配置任何内容,因此同样会停止,诊断信息会报告该条目所指的 id。aggrega pull 同样以 Release 作为输入;aggrega inspect 接受任何实体——目录名称、实体文件、注册表引用或 Release;aggrega push 接受一个目录实体;aggrega validate 和 aggrega lint 接受一个目录实体、一个 Release(通过 --release)或整个目录;aggrega serve 以长期运行的进程方式运行。全局标志页面记录了适用于各子命令的标志。
一个版本可以对命令、标志和助手工具做出哪些更改——以及补丁版本绝不会更改什么——见兼容性中的说明。
各命令参考
aggrega build— 主要的编译命令。读取 Release 指针,解析其引用的 Aggregate 和 Manifest,并按边界输出编译产物。aggrega inspect— 任意实体的可读视图:按名称指定的目录实体、按路径指定的实体文件、直接从注册表读取的已发布实体,或完全解析的 Release;对于 Release,--ir-graph会将其 IR 图以 JSON 写出,--closure会报告其依赖闭包。aggrega pull— 解析 Release 的依赖,写入锁定每个依赖的按 Release 划分的锁文件;缓存目录实体和源产物。aggrega push— 将目录实体发布到 OCI 注册表,可选择在推送时对其签名。aggrega sign— 对一个或多个已发布的产物签名,并将每个签名作为 OCI referrer 附加。aggrega auth token— 以交互方式获取 OIDC 身份令牌并打印到 stdout,以便一批无密钥签名只需一次认证。aggrega registry— 管理工作区已知的注册表及其签名信任策略:添加、列出和删除条目,并通过registry update构建已发布目录元数据的本地可搜索索引。aggrega search— 在已配置注册表的本地索引中搜索已发布的目录实体和可安装的 CLI 插件,按自由文本查询和可选的分面过滤器匹配。aggrega validate— 在整个目录、Release 的依赖闭包(--release)或单个实体范围内检查正确性(schema、支柱、引用解析、extends、输入种类能力、隔离渲染)。aggrega lint— 在整个目录、Release 的依赖闭包(--release)或单个实体范围内检查发布约定;--pre-publish增加感知注册表的版本升级关卡。aggrega serve— 长期运行的编译器即服务守护进程(基于 stdin/stdout 的 JSON-RPC),用于 IDE 集成。aggrega version— 打印 CLI 版本;-o json输出机器可读的对象。aggrega get-schema— 打印实体或契约种类的规范 JSON Schema;--list列出所有种类。这是编写文件时应遵循的权威结构。aggrega scaffold— 打印某实体种类的起始文档,由该种类的 schema 派生:包含必填字段,固定字段已填好,凡需取值处均为占位符。起草时不写入文件;请将输出重定向到你需要的位置。使用--example时,它改为将文档中的某个可运行示例写入新目录,--example --list会列出这些示例。aggrega mcp— 通过标准输入输出或 HTTP 运行 Model Context Protocol 服务器,使支持 MCP 的客户端成为了解 Aggrega 的编写助手。参见编写 Aggrega 文件。aggrega skills— 将教会 AI 助手安装和使用 Aggrega 的技能安装到该助手的技能文件夹中,可针对单个项目,或使用--global针对你的所有项目。aggrega cache— 检查和维护磁盘缓存:列出其中的内容、回收没有任何锁文件引用的制品缓存条目、将已编译模块缓存修剪到大小上限,或清空所有缓存。aggrega config— 检查和管理 Aggrega 读取的配置:显示生效的设置以及每项设置由哪一层决定、生成一份可用的配置,并将构建关键设置固化到工作区中。aggrega deprecate— 为已发布的制品附加经签名的弃用标记。aggrega edit-document— 对文档应用一次有界的结构化编辑,保留其未触及的每个字节。aggrega explain— 解释某个代码所指的中止条件。aggrega import— 将外部源描述转换为 Aggrega 编写文件草稿。aggrega login— 向 OCI 注册表进行身份验证,并存储push、pull和lint --pre-publish所出示的凭据。aggrega logout— 删除已存储的注册表凭据。aggrega pin— 在实体旁边的entity.lock中记录该实体外部输入的内容固定值。aggrega plugin— 列出 CLI 能解析的 Wasm 插件,添加或删除工作区绑定,并在发布 guest 之前对其进行检查。aggrega push-artifact— 将独立的数据制品(例如文档包)发布到 OCI 注册表的docs/命名空间下。- 配置 — 某项设置应放在哪个文件中,以及各层如何组合。从这里开始:它先介绍大多数项目需要的两个文件,再介绍较大项目才会用到的机制。
- 全局标志 — 各子命令共享的标志(工作区根目录、全局配置文件、彩色输出与纯文本无障碍输出,以及离线模式)。离线也可以通过配置设置和环境变量启用 — 参见配置、配置 schema 和环境变量。
- 工作区边界 — 工作区内包含什么,指向工作区外的符号链接对各类路径有何影响,有意指向外部的路径,以及路径被拒绝时该怎么做。
| 命令 | 描述 |
|---|---|
aggrega auth | 管理签名身份 |
aggrega build | 将 Aggregate 和 Release 编译为 provider 原生产物,输出到工作区根目录下的 dist/ |
aggrega cache | 检查和维护磁盘缓存 |
aggrega config | 检查和管理工作区配置 |
aggrega deprecate | 为已发布的产物附加已签名的弃用标记 |
aggrega edit-document | 对文档应用一次有界的结构化编辑,保留其未触及的每个字节 |
aggrega explain | 解释某代码所指的中止条件 |
aggrega get-schema | 打印实体或契约种类的 JSON Schema |
aggrega import | 将外部源描述转换为 Aggrega 编写文件草稿 |
aggrega inspect | 按名称检查目录实体、按路径检查实体文件,或按注册表引用检查已发布实体 |
aggrega lint | 在整个目录、某个 Release 或单个实体范围内检查目录发布约定 |
aggrega login | 向 OCI 注册表认证并存储凭据 |
aggrega logout | 删除已存储的注册表凭据 |
aggrega mcp | 通过标准输入输出或 HTTP 运行 Model Context Protocol 服务器,用于 AI 助手集成 |
aggrega pin | 在实体旁的 entity.lock 中记录该实体外部输入的内容锁定 |
aggrega plugin | 检查 CLI 可解析的 Wasm 插件 |
aggrega pull | 将目录和源依赖解析到缓存中,并写入按 Release 划分的锁文件 |
aggrega push | 打包目录实体并发布到 OCI 注册表 |
aggrega push-artifact | 将独立的数据产物(如文档包)发布到 OCI 注册表 |
aggrega registry | 管理注册表及其签名信任策略 |
aggrega scaffold | 为某实体种类起草起始文档,或将可运行示例写入新目录 |
aggrega search | 搜索已配置注册表的本地索引 |
aggrega serve | 作为长期运行的编译器即服务,在 stdin/stdout 上通过 JSON-RPC 2.0 运行 |
aggrega sign | 对一个或多个已发布的产物签名并附加其签名 |
aggrega skills | 将 Aggrega 技能安装到 AI 助手中 |
aggrega validate | 在整个目录、某个 Release 或单个实体范围内检查正确性 |
aggrega version | 打印 aggrega CLI 版本 |
位置参数与退出状态
每个命令都会拒绝它用不到的位置参数,并通过非零退出状态报告这一拒绝,而不会像调用有效那样正常完成。该规则也适用于仅用于对子命令进行分组的命令:在这类命令中,拼错的子命令名会作为无法识别的位置参数传入,此时会打印该命令的帮助信息,且退出状态为非零,因此脚本中的拼写错误会明确失败,而不会被当作一次成功的运行。以无法识别的命令调用 aggrega 时行为相同,并且在存在足够接近的命令时,还会给出最接近的匹配命令。
无法识别的命令还会说明如何查找同名的 CLI 插件。 答案来自默认注册表的本地索引,该索引由 aggrega registry update 构建、由 aggrega search 读取,因此会立即返回,且无论联网还是离线,拼错的词都不会被发送到任何注册表。如果索引中有同名的 CLI 插件,消息会给出安装它的 aggrega plugin add cli <name> 命令。如果索引中没有,消息会给出查找该插件的搜索命令 aggrega search <name> --kind plugin --plugin-type cli。如果尚未构建任何索引,消息会给出 aggrega plugin add cli <name>,该命令会按这个名称在注册表中查找插件,若没有已发布的同名插件则拒绝执行。无论是哪个命令,都会在需要时为 shell 给名称加上引号。
在位置参数有意义的情况下,每个命令自己的参考页面会说明它接受哪些参数。已安装的 CLI 插件是有意设置的例外:它的命令自行处理参数解析,因此整个参数向量会被转发给该插件,由插件作为其自身参数的唯一解析者——而该调用返回的就是插件自身的退出状态。
进度,以及命令等待注册表的时长
正在等待的命令会说明它在等待什么。 只要命令在等待注册表、下载或首次编译插件,它就会在标准错误上显示该步骤,就像 aggrega build 和 aggrega pull 显示它们的步骤一样:在终端上,显示一行,给出步骤名称、一个旋转指示器以及到目前为止所用的时间,步骤完成后打勾,步骤失败则不打勾;在无法原地重绘的终端上,或在使用 --plain 时,每个步骤结束时输出一行,并附上其用时。如果标准错误不是终端,则不显示任何内容;无论哪种情况,命令在标准输出上打印的内容都不会改变。只有在命令确实在等待某个步骤时才会显示该步骤,因此由缓存提供的运行完全不显示任何内容,而编译插件只有在耗时足够长、属于真正的编译而非缓存命中时才会显示。
除每个已安装 CLI 插件的命令外,以这种方式显示步骤的命令有:
aggrega config init, aggrega deprecate, aggrega explain, aggrega import, aggrega inspect, aggrega lint, aggrega plugin add, aggrega plugin gen-catalog, aggrega plugin run-local, aggrega plugin sync, aggrega push, aggrega push-artifact, aggrega registry add, aggrega scaffold, aggrega sign, aggrega validate
任何请求都不会无休止地等待服务器。 请求完整发送后,最多等待 30 秒让服务器开始回答;对于已经开始到达的回答,最多等待 30 秒接收其下一部分。让请求等待更久的服务器会以 E0376 被拒绝,并指明该服务器和等待时间。受限制的只有等待:持续推进的下载或上传需要多长时间就用多长时间。Recipe 的 source: 通过 HTTPS 获取的 Helm chart 只受两种等待中的第一种限制,其超时以网络库自己的措辞报告,而不是以 E0376 报告。命令在超时时本就会重试的请求 — 例如 aggrega registry update 期间的读取、发布期间的写入 — 会在报告拒绝之前重试。
遍历注册表的完整仓库列表会在五分钟内结束。 有些注册表在回答列表请求之前,会先收集其持有的所有仓库,因此列表每一页的等待时长是遍历可能持续的时长,而不是 30 秒;五分钟后仍未结束的列表会被停止,并以 E0377 被拒绝。aggrega plugin add 只有在没有插件恰好使用所给名称时,才会遍历列表,以查找名称中包含该名称的插件,因此准确指定插件名称时绝不会等待遍历。
对于要求放慢速度的注册表,命令会一直等待,直到它不间断地要求了五分钟为止。命令会按照此类注册表要求的时间等待,同时减少向其并发发送的请求数,并将等待与其他进度一起显示;如果注册表在五分钟内只回答“放慢速度”,则以 E0378 拒绝。要求放慢速度的注册表说明了具体方式。
这三个限制是固定的;没有任何设置可以更改它们。
你输入的路径与工作区边界
你在命令行上输入的路径(--release、--catalog、--output-dir、要校验、lint、固定或发布的文件、--workspace-root)会按其指向使用,无论位于工作区内还是工作区外,也无论途经任何链接。而命令随后自行读取和写入的内容,无论由谁运行,都被限制在工作区之内:它不会通过指向工作区外的链接读取工作区的配置文件、catalog 文档、Release 旁的文档或 Release 的锁文件,不会跟随 Release 或 Manifest 写出工作区的路径,也不会通过此类链接写入其输出、锁文件或缓存。你指定的位于工作区外的目录,其下的内容同样受此限制;你指定的位于工作区外的 Release 只能访问其自身目录中的文件。aggrega edit-document 是唯一一个连你输入的路径也受限制的命令:它只编辑工作区所包含的文档。工作区边界说明了该规则、有意指向工作区外的路径,以及每种拒绝情况的解决办法。
搜索目录索引
aggrega search [query] 在工作区已知的各个注册表中查找已发布的实体。可选的 [query] 是一个不区分大小写的子串,与每个实体的名称和描述进行匹配。分面过滤器用于缩小结果集:
--kind将结果限制为一种或多种实体类型(component、feature、recipe、featurerecipe、workload、plugin);它可以重复使用且不区分大小写,多个类型之间按 OR 组合。-l/--selector按实体的目录标签进行过滤。类别是一个标签,而不是专门的标志:-l component.aggrega.ai/category=datastore。--capability和--plugin-type按声明的能力或插槽类型过滤插件;--capability可以重复使用,并按 OR 组合。--registry按主机或友好别名将搜索范围限定为单个注册表;默认情况下会搜索所有已配置的注册表。--limit限制结果的数量上限。-o/--output选择输出格式:table(默认,便于人工阅读)、json(机器可读的数组)或names(纯标识符,每行一个)。
搜索始终读取本地索引——即由 aggrega registry update 构建和刷新的离线快照。它不访问网络,也不会按需获取任何内容。索引不存在时,命令会失败,并提示你先运行 aggrega registry update。每次运行都会向标准错误输出打印每个注册表的“最后更新”时效信息行,从而使标准输出上的 json 和 names 输出保持干净,便于编写脚本。
Shell 补全
aggrega completion <shell> 将适用于 bash、zsh、fish 或 powershell 的补全脚本输出到 stdout。该脚本在你运行命令时根据 CLI 当前的命令树生成,因此始终反映生成它的二进制文件的命令和标志——随着 CLI 的扩展,无需重新生成任何静态文件。
若要在当前会话中试用补全而无需安装任何内容,可直接 source 该脚本:
source <(aggrega completion bash)若要永久安装补全,请将脚本写入你的 shell 启动时读取的位置。
bash
Bash 补全依赖 bash-completion 软件包;如果尚未安装,请通过操作系统的包管理器安装。
# Linuxaggrega completion bash > /etc/bash_completion.d/aggrega
# macOS (Homebrew)aggrega completion bash > $(brew --prefix)/etc/bash_completion.d/aggregazsh
如果你的 shell 尚未启用补全,请先启用一次:
echo "autoload -U compinit; compinit" >> ~/.zshrc然后将补全脚本写入 fpath 中的某个目录:
# Linuxaggrega completion zsh > "${fpath[1]}/_aggrega"
# macOS (Homebrew)aggrega completion zsh > $(brew --prefix)/share/zsh/site-functions/_aggregafish
aggrega completion fish > ~/.config/fish/completions/aggrega.fishpowershell
将生成的脚本追加到你的 PowerShell 配置文件中,使其在每个会话中加载:
aggrega completion powershell >> $PROFILE启动一个新的 shell,使安装的补全生效。