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

aggrega search

搜索已配置注册表的本地索引

概要

aggrega search [query] [flags]

说明

Search the local index of the configured registries for entities matching a
free-text query and optional facet filters.
The index is the offline snapshot written by 'aggrega registry update'; search
reads it and contacts no network. Run 'aggrega registry update' first, and again
whenever you want to pick up newly published entities. A freshness line naming
each searched registry and when its index was last updated is written to standard
error, so standard output carries only the result data.
The optional positional query is a case-insensitive substring matched against
each 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 catalog
category 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 the
results are merged. With --registry (a host or a friendly alias), only that
registry's index is searched.
A search needs at least one configured registry. With none configured there is
nowhere 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 what
lets a caller tell a search that ran and matched nothing from a search that
could not be performed. Run 'aggrega config init' to register a registry with
its signature trust policy, then 'aggrega registry update' to build the index.
The version reported for an entity is the one a resolution would take: a
version a publisher has retracted, where the retraction carries a signature
this workspace's trust policy verifies, is not reported. Such an entity is
still listed, and the versions left out are named in a NOTES column, so an
entity whose every published version is retracted is reported as existing with
no version to take rather than disappearing from the result. Pass
--include-retracted to report the highest published version whatever its
retraction status; the NOTES column names the retracted versions either way.
The same holds for 'aggrega search -o json', where the 'version' field carries
the version a resolution would take and a 'retracted' array names the versions
left out.

标志

标志默认值描述
--capability[]要匹配的 Plugin 能力。可重复指定;声明了其中任意一项的记录会被保留。
--include-retractedfalse报告已发布的最高版本,即使已验证的标记撤回了该版本。默认情况下,报告的版本是解析时会选取的版本。
--kind[]要匹配的实体种类(component|feature|recipe|featurerecipe|workload|plugin)。可重复指定;匹配其中任意一项的记录会被保留。不区分大小写。
--limit0限制结果数量(0 表示不限制)。
--output, -otable输出格式: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。