aggrega search
搜索已配置注册表的本地索引
概要
aggrega search [query] [flags]说明
Search the local index of the configured registries for entities matching afree-text query and optional facet filters.
The index is the offline snapshot written by 'aggrega registry update'; searchreads it and contacts no network. Run 'aggrega registry update' first, and againwhenever you want to pick up newly published entities. A freshness line namingeach searched registry and when its index was last updated is written to standarderror, so standard output carries only the result data.
The optional positional query is a case-insensitive substring matched againsteach entity's name and description. The facet filters narrow the result further,combining as AND across facets and OR within a repeatable facet:
--kind entity kind (component, feature, recipe, featurerecipe, workload, plugin); repeatable, case-insensitive --capability a plugin capability; repeatable --plugin-type a plugin socket type (for example provider, governance) -l, --selector a label selector over the entity's catalog labels
Category is matched through the label selector, not a dedicated flag: a catalogcategory is the label component.aggrega.ai/category, so'-l component.aggrega.ai/category=compute' scopes the result to that category.
With no --registry, every configured registry's index is searched and theresults are merged. With --registry (a host or a friendly alias), only thatregistry's index is searched.
A search needs at least one configured registry. With none configured there isnowhere to look, so the command refuses: the reason goes to standard error,standard output carries nothing, and the exit status is non-zero. That is whatlets a caller tell a search that ran and matched nothing from a search thatcould not be performed. Run 'aggrega config init' to register a registry withits signature trust policy, then 'aggrega registry update' to build the index.
The version reported for an entity is the one a resolution would take: aversion a publisher has retracted, where the retraction carries a signaturethis workspace's trust policy verifies, is not reported. Such an entity isstill listed, and the versions left out are named in a NOTES column, so anentity whose every published version is retracted is reported as existing withno version to take rather than disappearing from the result. Pass--include-retracted to report the highest published version whatever itsretraction status; the NOTES column names the retracted versions either way.The same holds for 'aggrega search -o json', where the 'version' field carriesthe version a resolution would take and a 'retracted' array names the versionsleft out.标志
| 标志 | 默认值 | 描述 |
|---|---|---|
--capability | [] | 要匹配的 Plugin 能力。可重复指定;声明了其中任意一项的记录会被保留。 |
--include-retracted | false | 报告已发布的最高版本,即使已验证的标记撤回了该版本。默认情况下,报告的版本是解析时会选取的版本。 |
--kind | [] | 要匹配的实体种类(component|feature|recipe|featurerecipe|workload|plugin)。可重复指定;匹配其中任意一项的记录会被保留。不区分大小写。 |
--limit | 0 | 限制结果数量(0 表示不限制)。 |
--output, -o | table | 输出格式:table|json|names。 |
--plugin-type | — | 要匹配的 Plugin 插槽类型(例如 provider、governance、linter)。 |
--registry | — | 仅搜索此注册表,按主机名或友好别名指定。默认搜索所有已配置的注册表。 |
--selector, -l | — | 针对实体目录标签的标签选择器,这些标签包括其类别(-l component.aggrega.ai/category=compute)。 |
未配置注册表时
搜索读取的是本机已配置可访问的注册表的本地索引,因此至少需要一个注册表。如果一个都没有配置,就无处可查,aggrega search
会拒绝执行而不是给出回答:它将原因写入标准错误,以非零状态退出,并
保持标准输出为空——在所有输出格式下都是如此,包括 --output json。
正是这种拒绝把两种不同的回答区分开来。已运行但没有匹配项的搜索
以零状态退出,并在标准输出上报告 (no matches);根本无法运行的搜索
以非零状态退出,并且不在标准输出上报告任何内容。因此,根据退出状态分支的脚本可以
区分“该实体未发布”和“本机没有可查询的注册表”,而标准输出上的提示
加上零状态无法表达这种区别。
运行 aggrega config init 注册一个注册表及其签名信任策略,然后运行
aggrega registry update 构建搜索所读取的本地索引。
aggrega registry list 和 aggrega registry update 对同一情况的回应不同,
这是有意为之。在没有注册表时列出注册表,是对空集的完整列举;
没有可遍历内容的索引构建也就没有剩余工作:两者都是已完成的操作,因此
都在标准输出上报告并以零状态退出。只有搜索是在报告它无法完成
所要求的操作。
搜索报告的版本
VERSION 列给出解析时会选取的版本。已被发布者
撤回的版本不会被报告,前提是该撤回带有本工作区信任
策略可验证的签名——这与决定撤回是否影响拉取的两个条件相同,因此
搜索和拉取对哪个版本才是答案的判断一致。
不满足其中任一条件的撤回不会改变报告的内容。严重级别为 建议性的标记会使其版本仍可被选取,而签名无法验证的标记 不是本工作区会采信的声明。在这两种情况下,报告的已发布最高版本 与完全没有标记时完全相同。
有版本被撤回的实体仍会被列出。NOTES 列指明被排除的
版本,并且只在有内容可报告的结果中出现。所有已发布
版本均被撤回的实体,会以 (none) 作为其版本并附带说明已无
剩余版本的注释进行报告,而不是从结果中删除——被省略的实体
将无法与不存在的实体区分开来。
传入 --include-retracted 可报告已发布的最高版本,无论其撤回
状态如何,这回答的是“发布了什么?”而不是“我应该用什么?”。它
只改变报告的版本;无论哪种情况,NOTES 列都会指明被撤回的
版本。
搜索读取的是 aggrega registry update 写入的本地索引,因此它报告的
是上次构建该索引时各注册表所声明的内容。此后被撤回的版本
尚未记录,而写入标准错误的新鲜度行会指明每个
索引的构建时间。
机器可读的结果
--output json 通过两个字段承载同样的约定:
version是解析时会选取的版本。当所有 已发布版本均被撤回时,它为空字符串,并配有列出全部这些版本的retracted列表。retracted按版本升序列出在该选择中被排除的版本。 没有排除任何版本时,该字段不存在。
想知道自己会得到哪个版本的使用方应读取 version。改为从
deprecations 数组推导,意味着要重新实现严重级别和签名条件,而
这些条件的第二种实现完全可能与编译器所应用的实现
不一致;retracted 报告的是这些条件已经得出的结果。
每条记录还带有 published:索引记录的每个版本,按版本升序
排列,每个版本都带有构建索引时其标签解析到的 manifestDigest,并且在
本工作区信任策略验证了该版本自身签名的情况下,带有其 signer——若有多个
可验证的签名,则取透明日志最早记录的那个。没有 signer 的版本
不带有该策略验证过的签名,对此不作进一步说明。
读取某个版本内容的使用方通过该摘要寻址——例如
aggrega inspect oci://<host>/<repository>@<digest>——因此它读取的是索引
所记录的字节,无论该标签之后发生什么变化。
凡是有记录表明版本何时发布的,其条目还带有 publishedAt,即一个
精确到秒的 UTC RFC 3339 时间戳,以及说明其来源的 publishedAtSource。
transparency-log 是透明日志记录该版本无密钥签名的时间,
本工作区信任策略已将该签名连同日志对该时间的签名承诺一并
验证——即 signer 的签名,也就是可验证签名中最早的那个,因此再次签名某个版本
不会改变这两者。publisher 是发布内容旁所声明的时间,来自
发布机器自身的时钟,没有任何证明。两者分开保存,使按日期
排序的使用方仍能区分经证明的时间和声明的时间。两者都没有的
版本不带日期,对此不作进一步说明;关于各自何时记录,请参阅
aggrega registry update。