跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

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 该脚本:

Terminal window
source <(aggrega completion bash)

若要永久安装补全,请将脚本写入你的 shell 启动时读取的位置。

bash

Bash 补全依赖 bash-completion 软件包;如果尚未安装,请通过操作系统的包管理器安装。

Terminal window
# Linux
aggrega completion bash > /etc/bash_completion.d/aggrega
# macOS (Homebrew)
aggrega completion bash > $(brew --prefix)/etc/bash_completion.d/aggrega

zsh

如果你的 shell 尚未启用补全,请先启用一次:

Terminal window
echo "autoload -U compinit; compinit" >> ~/.zshrc

然后将补全脚本写入 fpath 中的某个目录:

Terminal window
# Linux
aggrega completion zsh > "${fpath[1]}/_aggrega"
# macOS (Homebrew)
aggrega completion zsh > $(brew --prefix)/share/zsh/site-functions/_aggrega

fish

Terminal window
aggrega completion fish > ~/.config/fish/completions/aggrega.fish

powershell

将生成的脚本追加到你的 PowerShell 配置文件中,使其在每个会话中加载:

Terminal window
aggrega completion powershell >> $PROFILE

启动一个新的 shell,使安装的补全生效。