aggrega pull
aggrega pull 解析一个 Release 的全部依赖,并写入一个锁文件,将每个依赖固定到确切的版本和内容摘要。随后的 aggrega build 使用锁文件所固定的内容并对其进行校验;若所需的任何内容未在其中固定,则停止并指出该内容——因此构建可复现,并且能够离线进行。
构建所使用的一切都在这一时刻固定。 目录实体、Recipe 让 provider 指向的源制品,以及 provider 在渲染过程中请求的远程文档,都由同一条命令解析,并记录在同一次锁文件写入中。aggrega pull 是访问网络的步骤;构建则不访问网络。这就是全部规则,本页其余内容都由此推导而来。
功能说明
aggrega pull 在一次处理中解析三类依赖:
- 目录实体——Release 所引用的 Components、Features、Recipes、FeatureRecipes、schema 库和 mapping 库,以及 Wasm 插件,以传递方式解析(通过
extends:、implements:、aggregate:、Feature 附加,以及库的$import:/$ref:位置),在本地不存在时从注册表获取。 - 源制品——单个 Recipe 或 FeatureRecipe 让 provider 指向的远程
source::一个 Helm chart(OCI 或经典 HTTPS),或一个通过 HTTPS 获取的 Compose 片段。每一项都会被获取、缓存并固定。 - 外部输入——provider 在渲染过程中向宿主请求的远程文档,例如 chart 的
values.schema.json中指向某个 URL 的$ref。每一项都会被获取、按其内容摘要存储并固定。
三类中有两类是从你编写的文档中读取的。第三类则不是:外部输入是通过渲染 Release 找到的,这正是本命令会渲染一个 Release 的原因。运行本命令并不需要了解这些——解析如何找到外部输入完整说明了这一点,以及渲染的开销、渲染无法完成时会发生什么,以及自行填充锁文件的构建与之有何关系。
未指定注册表的目录实体通过工作区的 default_registry 获取,默认值所带的仓库路径就是获取位置。 设置 default_registry: ghcr.io/acme 时,core/api-server 从 ghcr.io/acme/component/core/api-server 获取——aggrega push 也通过同一默认值将其发布到这里——其签名也在该处查找。路径仅表示位置:拉取所要求的签名、所信任的密钥和身份,以及所出示的凭据,都是为该主机保存的那些,因此 ghcr.io 的 registries 条目管辖该主机上的所有路径。锁文件按实体的身份、版本和摘要记录此类实体,与记录仅从主机获取的实体相同。路径的写法见注册表主机的写法。
结果写入 Release 旁边的 <release-stem>.lock。若工作区附加了返回接受或拒绝裁决的插件,该目录中还会生成第二个文件——插件信任记录。
被要求固定的拉取还会写入另一类文件。 在你的目录中,每个导入制品文件、指向你完整写出的远程 source:、或读取其旁边 source: 的 Recipe 和 FeatureRecipe 旁边,都有一个 entity.lock,记录该内容的摘要。记录它是实体作者的步骤,即 aggrega pin,默认情况下拉取不会执行此步骤:它要求每个此类实体的锁与该步骤将记录的内容一致,并在缺少固定时停止。aggrega pull --pin-sources,或设置了 pin_sources_at_pull: true 的工作区,会改为执行该步骤——此时拉取的影响范围会超出 Release 所在的目录,但你编写的实体文件永远不会被写入。实体锁描述了该文件,预览拉取将写入的内容会在任何改动发生之前列出你的工作区的全部文件。
因引用解析为空而被拒绝的拉取,无论在何处运行,都会说明本地实体从何处读取。 拒绝信息附带工作区自身对其读取本地实体的目录的说明,以及需要更改什么才能读取到该实体——如说明本地实体从何处读取所示——无论来自本命令、先解析依赖的构建、aggrega mcp 的拉取工具,还是编辑器的依赖解析,都会附带这一说明,因为它们运行的解析过程都会生成它。拉取工具的拒绝信息还会给出该情况的短代码和描述性代码,正如终端在拒绝信息开头打印短代码一样。这些目录中声明了 Aggrega apiVersion 的文件——即其中有一行不缩进、以 apiVersion: 开头且值以 aggrega.ai/ 开头——如果无法加载,例如无法解析为 YAML,就会在同一拒绝信息中被指明,列于加载时跳过的目录文件之中,并附带解析器自身给出的原因:这样的文件可能正是声明该引用所指实体的文件,而从中无法读出任何内容来说明它声明的是哪个实体。声明其他 apiVersion 或未声明任何 apiVersion 的 YAML 文件不是 Aggrega 文档,绝不会在那里被指明。
锁文件
锁文件将每个依赖固定到其 URI、解析后的版本和内容摘要。它包含以下几个部分:目录实体、schema 库和映射库(每个库都带有指回使用它的 Components 和 Features 的反向指针)、Wasm 插件、源制品、外部输入(每项以 URL 为键,并带有请求它的插件),以及 Release 文件本身。该文件以规范、确定性的形式写入。
实体按其发布所携带的内容记录。 实体所在行中的摘要覆盖其文档以及它在旁边指名的每个文件——Recipe 或 FeatureRecipe 的本地 source:、$import: 指名的每个文件、其旁边的 entity.lock、Component 或 Feature 导入的每个 schema 文件——即 aggrega push 所发布的同一组文件。每个文件贡献其路径和字节,其他一概不计:不计归档的压缩方式,不计时间戳,不计权限位,包括执行位。不指名任何文件的实体按其单个文档记录。因此,同一实体无论是从你的目录读取还是从注册表获取,记录的摘要都相同;从一个检出提交的锁文件,在同一提交的另一个检出上也能通过验证,无论其 umask 如何,也无论该检出的系统是否记录哪些文件可执行。在 Recipe 下编辑的 chart、向其声明的源中添加的文件以及更改过的 entity.lock 都会改变摘要;执行位翻转的脚本,以及实体旁边未被任何内容指名的说明文件,则不会。Release 指名的 Aggregate 和 Manifest 以相同方式记录,各自作为其单个文档。库按其字节的摘要记录,无论从何处读取,其字节即其文档。
Manifest 绑定的每个 Recipe 和 FeatureRecipe 都是一行,无论由哪一层绑定。 Manifest 的 name 层为某个实例或某个挂载选择的实现,其获取和记录方式与 type 层为某类型所有实例选择的实现完全相同,其所在行的 referenced_from 指名绑定它的条目——manifest.spec.mappings.components.name.<instance> 或 manifest.spec.mappings.features.name.<attachment>。构建会以该行约束它,因此未记录它的锁文件会使构建中止,并指名该实现和该条目。关于这两层,参见 扁平 URI 映射。
连接的挂载与组件自身的挂载一样都是依赖。 连接上的挂载所指名的 Feature——写在 Aggregate 中组件的 uses: 条目上,或写在 Release 中的连接条目上——其获取和记录方式与写在组件自身上的挂载的 Feature 相同,其所在行的 referenced_from 指名作者编写的连接条目,以 .uses.<socket>.<alias>.features.<slot>.type 结尾。Manifest 绑定到它的实现也是一行,无论是由 features.type 绑定,还是由以挂载名称 <alias>.<slot> 为键的 features.name 绑定。构建会以各自的行约束两者:缺少其中一行的锁文件会使构建中止,并指名该引用及请求它的条目;自拉取以来内容已更改的 Feature 会使构建中止,并指名两个摘要。关于挂载本身,参见 Aggregate 的连接条目。
Component 或 Feature 所扩展的基础实体都有自己的一行,无论是否有其他内容指明它。 拉取会沿每个 extends: 一直追溯到链的末端,并将每个基础实体记录在其自身的种类之下,该行的 referenced_from 指明扩展它的实体的 spec.extends——component(<name>:<version>).spec.extends。构建从该行读取基础实体,因此 Manifest 映射包装实体自身的类型,无需为其基础实体写一行。没有任何目录文件夹、缓存或注册表持有的基础实体,会在合并该链之处报告——参见 An extends: chain cannot be assembled(无法组装一条链)。
Release 按其内容记录,而不仅仅按其名称记录。 Release 请求的一切——某个源解析为哪个 chart 版本、哪些组件落入哪个边界——都依据该文件所含内容解析,因此 release_documents 记录该 Release 及其扩展的每个 Release 的摘要,与指名它的 release 并列。拉取后编辑 Release,下一次构建会在任何渲染之前中止,指名你编辑的文件并提示你重新拉取;普通的 aggrega pull --release <release> 会记录该编辑,同时遵循其他所有固定。摘要覆盖文件的原始字节,因此注释或空白的更改也算在内,与 Aggregate 和 Manifest 完全一样。Release 通过 parameters 导入的文件不以这种方式记录。
**拉取会在其检查签名的每个制品上查找弃用标记,并说明找到了什么。**如果标记自身的签名能通过拉取所认可的签名者验证——即该制品自身的签名者,或注册表 trusted_deprecation_identities 中的某个身份——该标记就会被记录,并连同其严重级别和标记的签名者一起公布。拉取找到但无法认可的标记——无法读取、未签名、由策略不信任的人签名,或带有无法检查的签名——会被报告为 marker present but not honored 并附上原因,且不会被记录。无法完成的查找——拉取无法打开该制品的注册表,或其附加内容的列表没有应答——会被报告为 marker lookup did not complete 并附上原因,且不记录任何内容,因为拉取对是否存在标记一无所知。如果注册表自身的信任策略要求该制品的种类必须签名,且该策略不是 advisory,则上述两种情况中的任何一种都会使拉取停止,而不是仅被报告。不带标记的制品不会产生任何输出行;如果签名验证被关闭(无论是针对工作区还是针对该制品的注册表),则不会查找任何标记。
将 <release-stem>.lock 与 Release 一起提交,就像提交任何固定依赖的清单一样。锁文件的 diff 可让评审者准确看到哪些依赖版本和摘要发生了变化;库摘要的变化会指名它所影响的使用方。
某次拉取做了什么——每个实体是从注册表新获取的(fetched-fresh)、复用了缓存槽(cache-reuse)、在本地目录中找到的(local)、由编译器二进制内的副本提供的(in-binary),还是外部的(external:Release 自身的 Aggregate 或 Manifest,从 Release 指名的文件或条目读取,而不是作为其依赖之一解析;拉取从注册表获取的 Aggregate 则为 fetched-fresh)——是由 --detail 打印到 stdout 的临时拉取事件诊断,从不写入锁文件。由哪个来源提供实体取决于执行拉取的机器的本地状态,因此持久化它会破坏锁文件在不同机器间的字节一致性。它报告的是本次拉取做了什么,事后无法恢复(新拉取的实体会在下一次运行时被缓存);要查看 Release 依赖在拉取后的解析状态,请使用 aggrega inspect。
实体锁
Recipe 或 FeatureRecipe 可能依赖其自身文档之外的字节:从远程 source: 获取的 chart 或片段,artifacts 条目(或 Recipe 的 boundary.artifacts 条目)通过 $import 引入的文件,或者指向目录或其旁边文件的 source: 中的文件。这些内容各自的摘要记录在名为 entity.lock 的文件中,该文件与实体文件位于同一目录。你编写的实体文件永远不会被写入;派生出的内容存放在它旁边。实体锁 schema 逐字段描述了该文件。
由谁写入。 只有一个步骤会写入它:aggrega pin,由实体的作者运行,不需要 Release,并记录锁所包含的每一类固定项。aggrega pull --pin-sources 和 aggrega push --pin-sources 代表作者运行同一步骤,写入相同的字节。未被要求固定的 pull 根本不会写入锁:对于 Release 从你的目录目录构建的每个 Recipe 和 FeatureRecipe,它会将该步骤将要记录的内容与锁中已有的内容进行比较,并在固定项缺失或不再与其输入匹配时停止,指出实体、每个输入及其类别,以及 aggrega pin。本地 source 的文件作为一个整体受其固定项约束:锁中未记录其中任何文件会使 pull 停止,自固定以来新增、修改或删除文件同样如此。工作区键 pin_sources_at_pull 使固定成为每次 pull 的默认行为,而 --pin-sources=false 会在单次运行中恢复停止行为。固定是作者的职责,因此使用者首次 pull 时发生停止,说明实体的发布者从未固定它;使用者的补救办法是使用该键,而不是手动编辑他人的目录。aggrega pin 对此有完整说明。
它包含什么。 三个列表,每行指明一个输入:
sourceDigests:每个完整写出坐标、且其kind、url、chart、module_subdir、version或ref中没有模板的远程source:各占一行。该行包含 source 的kind和url,其chart或module_subdir(如有),它解析到的版本(对于 git source,是其ref指向的提交),以及所获取归档的内容摘要;对于通过 OCI 获取的 chart,还包含 manifest 摘要。artifactDigests:每个由通过$import导入的文件提供的artifacts或boundary.artifacts条目各占一行,指明该条目及文件字节的摘要。artifacts条目以其键命名,boundary.artifacts条目以boundary/<key>命名,因此两个块中写在同一键下的条目会被分别固定。localSourceDigests:对于指向实体旁边目录或文件的source:,其向实体发布内容所贡献的每个文件各占一行,指明该文件在实体旁边的路径及其字节的摘要。此类 source 不会获取任何内容;其文件按现状计算摘要。以模板形式编写的 source 会贡献实体目录中的所有文件,因此每个文件都有一行。
它不包含什么:
- 坐标由模板填充的远程 source,例如从
.infra读取的version。它指向哪个制品由使用该实体的每个 Release 决定,因此它解析到的每个版本都固定在相应 Release 的 lockfile 中,实体旁边不会写入任何与之相关的内容。 - 内联的
artifacts或boundary.artifacts条目(它是实体文件的一部分),以及取自 ArtifactLibrary 的条目(其内容由 lockfile 记录的库版本固定)。
没有需要固定内容的实体不会生成 entity.lock;对不再需要锁的实体运行该步骤时,会删除它。
将它与实体一起提交。 每个 Recipe 和 FeatureRecipe 使用相同的文件名,所在目录表明它属于哪个实体,因此锁随该目录一起移动。它不含时间戳,行按固定顺序排列,因此对未改变的输入运行该步骤会使其字节完全相同,而对它的 diff 会指出变动的 source、导入文件或本地 source 的文件。一个目录只包含一个锁,因此该步骤会拒绝旁边还有其他实体的 Recipe 或 FeatureRecipe(除 Aggregate、Release 和 Manifest 外,每种类型都有自己的目录),被要求固定的 pull 也会在解析任何内容之前拒绝此类实体;每个目录一个实体阐述了这一规则。不进行固定的 pull 不会在实体旁写入任何内容,也不会评判其目录。
aggrega build 让你的文件受其约束。 构建会读取锁并进行三项比较:
- 每个导入文件都会重新计算摘要并与其行比较,
boundary.artifacts文件与artifacts文件完全一样。固定后被编辑的文件会以[CATALOG_ERROR E0026]停止构建,并按其行中的名称指出该制品、导入文件及两个摘要。 - 本地 source 的文件会重新计算摘要,并作为一个整体与其行比较,这发生在 provider 读取该 source 之前。自固定以来被编辑、新增或删除的文件会以
E0305停止构建,归在该 source 所属的组件实例下,并指出每个此类文件及两个摘要;实体旁边不由该 source 贡献的文件不参与比较。没有为本地 source 记录任何行的锁没有可比较的内容,如 A local source no longer matches the pins recorded beside its Recipe(本地 source 不再与其 Recipe 旁记录的固定项匹配)所述。 - 每个 source 行都会与 Release 的 lockfile 为同一 source 记录的摘要进行比较。 不一致会以
[FETCH_ERROR E0135]停止构建,并指出该锁及两个摘要。这两个文件由对同一 source 的两次解析写入(固定步骤的解析和 pull 的解析),因此当这两次解析得到不同字节,或其中一个文件被编辑时,它们会不一致。同一版本下出现不同字节,正是上游重新发布某个版本时的表现。
在变更之前写入的 lockfile 会先停止,而 pull 会指出文件。 lockfile 按实体携带的内容记录实体,锁以及这些比较读取的每个文件都属于其中,因此当构建(或 aggrega pull --verify)所持有的 lockfile 写于导入文件、本地 source 的文件或锁本身变动之前时,会在三项比较中的任何一项运行之前停止:The lockfile no longer matches what the release resolves to(lockfile 不再与 release 解析的结果匹配),并指出实体及两个摘要。随后,普通的 aggrega pull 会指出该文件,因为它让锁受固定步骤将要记录的内容约束,并拒绝固定项不再匹配的输入:An entity reads an input the lock beside it records no pin for(实体读取了其旁边的锁未记录固定项的输入)。
当 lockfile 中没有实体自身内容的记录时,构建遇到的就是这三项比较。 如果 Manifest 通过一个引用命名某个 Recipe 或 FeatureRecipe,而该引用同时也是 Release 所触及的某个 Component 或 Feature 的名称,则该 Recipe 或 FeatureRecipe 没有自己的条目:lockfile 中该引用的条目记录的是该 Component 或 Feature,因此 Recipe 的文件变动时 lockfile 中没有任何内容变化,构建和验证性 pull 会以上述代码报告变动的文件。当 lockfile 的 source_artifacts 条目是发生变化的记录、而实体旁的锁没有变化时,构建遇到的也是 source 行比较。
**应对停止。**如果你是有意修改了导入的文件,请对该实体运行 aggrega pin:该步骤会记录文件的新摘要,下一次构建即会接受它。如果不是有意的,请恢复该文件。发生变动的本地源也有同样两种应对方式:重新固定该实体,或恢复停止信息中列出的文件。对于与 lockfile 不一致的源行,请从版本控制中恢复 entity.lock,或对该实体运行 aggrega pin 以重写它。
**aggrega pull --verify 也会检查它。**校验式 pull 会对 Release 在你的目录(catalog)中所触及的 Recipes 和 FeatureRecipes 旁的锁文件进行同样的三项比较,以相同的代码和相同的措辞报告构建会拒绝的每一个固定项,若存在则以非零状态退出,且不写入任何锁文件。
**不比较锁文件的情形。**从注册表而非你的某个目录(catalog)中解析得到的 Recipe 或 FeatureRecipe 没有供构建读取的锁文件;其源仅受 Release 的 lockfile 约束。此外,在 git ref: 处编写的源,在锁文件中按该 ref 解析到的提交记录,而构建按实体指定的版本查找该源的固定项,因此这一行永远不会被比较——无论是构建还是校验式 pull。lockfile 仍会固定该提交,且每次构建都会据此校验缓存的归档。
插件信任记录
工作区挂载的某些插件从不影响渲染输出。处于 ir-verdict 或 render-verdict 角色的 plugins.governance 挂载,以及所有 plugins.linter 挂载,只返回接受或拒绝的裁决,别无其他——它们的任何字节都不会进入产物。因此它们不属于构建逐字节复现的内容,而恰好固定这些内容的锁文件也就不是记录它们的地方。
它们的身份改为记录在第二个提交的文件中:位于锁文件旁边的 plugins-trust.yaml。该文件为每个此类插件保存一个条目,记录插件的身份坐标、为其选定的版本以及解析所得产物的内容摘要——此外,若 pull 为该产物验证了签名,还记录该签名;若发布者在发布该产物后已将其弃用,还记录 pull 找到并验证的弃用标记。插件信任记录 schema 逐字段描述了该文件。
将 plugins-trust.yaml 与锁文件一起提交,理由与提交锁文件相同:保存在版本控制之外的记录,无人能审查,也无从比对。提交后,它就是一份共享的声明,说明每个此类挂载解析到了哪个插件,而对它的 diff 会指出发生变化的身份。
只有在有内容需要记录时,该文件才会出现。 未挂载任何返回裁决的插件的工作区不会解析此类身份,因此 pull 不写入该文件,也不提及它——这是一种缺省,而非文件丢失。当 pull 确实创建该文件时,会指出所创建的文件并提示你提交它。之后的 pull 会添加记录中尚未包含的身份,并原样保留所有已记录的身份。
对该文件的每次更改都会被通告,此外不通告其他内容。 改动记录的 pull 会为每个变动的条目输出一行,指出插件及变更类型:首次记录的身份、取代原有身份而采用的身份(两者都会列出,以便你看出替换了什么)、针对条目已指向的产物记录的弃用、从条目中清除的弃用、针对条目记录或从中清除的签名,或被删除的条目。上面提到的创建提示是单独的一行,针对的是文件而非条目,因此首次解析时两者都会输出:该文件是新文件且必须提交,以及它现在包含的这些身份。
未改动记录的 pull 对其只字不提。 因此,一旦出现关于该文件的输出行,就意味着已提交的文件发生了变化,值得查看它的 diff——这一点在这里比在锁文件中更重要。锁文件固定的所有内容也都属于构建逐字节复现的内容,因此那里的变化还有第二个地方会显现;而裁决插件的身份没有。该文件是唯一记录关卡被替换的地方。
aggrega pull --dry-run 不会通告上述任何内容,因为它不做任何更改。它会将该记录列入它将要写入的文件之中,如预览 pull 将写入的内容所述。
弃用是添加到记录中已有的条目上,这与重写条目不同。 如果发布者弃用了你已信任的插件,下一次 aggrega pull 会在该插件现有条目上记录该标记——坐标、版本和摘要保持不变,因为产物没有变化,也没有采用任何新内容。因此,普通的 pull 可以添加 deprecation 块,而只有显式升级才会改变身份。标记只针对条目已指向的产物记录,且任何 pull 都不会追踪已停止发布的产物:已记录的标记只会随承载它的条目一同移除,即该条目被删除时,或显式升级重新解析该插件、并发现条目已记录的字节上没有标记时。
已验证的签名以同样方式记录在条目上,且每次 pull 都会重新给出答案。 pull 每次运行时都会依据注册表的信任策略验证每个此类插件的签名——注册表提供的插件每次都按版本获取,因为没有任何东西固定它——并将所验证的内容记录在插件条目上,同样不触及身份:模式、匹配的签名者,以及所缓存签名包的摘要,即锁文件条目所携带的同一个 signature。与标记不同,这个答案会替换条目原有的内容;若 pull 未验证任何签名——插件不携带签名且不要求签名,或由 skip_signature_verification 或 advisory 注册表放行——条目就不记录签名。所验证的签名包也会重新缓存,与其摘要不再匹配的缓存副本会被重写。因此,丢失签名的条目、携带从其他插件复制而来签名的条目、缓存签名包被删除或篡改的条目,或者被删除或在记录签名之前写入的记录,都会由下一次普通的 aggrega pull 修复。构建会让每个此类插件遵守这一事实:参见构建页面上的插件信任记录。
解析所得身份与记录不一致时,pull 会停止。 记录的条目同时指明版本和摘要,因此任一项变化都是同一事件:将要运行的插件不是记录审查时所针对的插件。诊断信息会同时在两个维度上指出该插件、记录所含内容以及本次解析报告的内容——且 pull 停止时不触及记录,因此经过审查的身份仍可用于比对。仅版本变化(字节未变的重新发布)与仅摘要变化(同一版本的重新推送)同样会导致停止。
aggrega pull --verify 进行同样的比对。它不写入 pull 所提交的任何文件,因此不采用任何内容;它报告这些文件是否仍描述 pull 今天将会解析的内容,而该记录就是其中之一。它还会让每个条目的签名与 pull 自身对该插件验证所得的签名保持一致,并报告 pull 将会记录、替换或清除签名的条目——以及记录中没有条目、而构建会因其未记录签名而拒绝的插件——如它比较两个文件中记录的签名所述。
要采用新身份,请按名称指定: aggrega pull --upgrade --release <release> <plugin>,按 .aggrega-config.yaml 挂载中的名称指定插件,不带任何版本后缀。这会重新解析该插件并重写其条目,其他所有已固定的依赖和已记录的身份均保持不变——即使该插件没有锁文件固定也能生效,因为指定的目标也可以是此类挂载之一。不带参数的 aggrega pull --upgrade 会重新解析所有依赖,也会重新解析并重写所有已记录的身份。aggrega build --upgrade 同样如此,它运行一次不带参数的全量刷新 pull,无法指定单个目标。
要移除身份,同样请按名称指定。 从 .aggrega-config.yaml 中解除插件挂载并不会清除其条目,这是有意为之:普通的 aggrega pull 从不移除条目。运行 aggrega pull --upgrade --release <release> <plugin>,按记录中的名称指定插件——即其身份坐标,也就是下文停止信息所输出的字符串——该条目即被删除,其他所有已固定的依赖和已记录的身份均保持不变。不带参数的 aggrega pull --upgrade 会在重新解析其他所有内容的同一轮中,删除所有不再被任何裁决挂载引用的条目。
删除最后一个条目后,文件仍会保留,只是变为空文件,而不会被删除。空记录不包含任何内容,因此不固定任何东西,也不会导致任何中止——与完全没有记录相同——而保留该文件意味着这次删除会在其 diff 中以删除的形式显示出来。
不符合其 schema 的记录会使读取它的每个命令中止——构建、限定于 release 的 lint,以及 pull,包括本身没有任何内容需要记录的 pull。清空的记录与损坏的记录被有意区别对待:清空是删除最后一个条目的方式,清空的记录保持静默;而内容已无法解析的文件属于故障,而非空记录——若将其视为空记录,截断该文件就成了关闭比较的一种方式。从版本控制中恢复该文件,即可找回经过审查的身份。
从编译器二进制文件内置副本提供的插件不会被记录。 pull 记录的是它获取的内容——从 registry 拉取,或从缓存读取——而从二进制文件中不获取任何内容:这些字节由携带它们的编译器版本标识,因此没有属于它们自己的解析结果可记录。所以,附加一个二进制文件已携带的插件不会为其生成条目。这是记录只针对获取的制品,而不是解析失败。
构建、限定于 release 的 lint 以及限定于 release 的验证,会将工作区配置与记录进行核对。 在任何这类附加插件运行之前,aggrega build、aggrega lint --release 和 aggrega validate --release——以及通过 aggrega serve 和 aggrega mcp 执行的相同操作——会将配置中指定的裁决附加项与记录中的条目进行比较。已解析制品摘要与记录不一致的插件会被拒绝,而不会运行。若某个记录条目没有任何已配置的裁决附加项与之对应,运行将中止:一个经过审查而现在缺失的关卡,其产生的输出与该关卡批准过的输出无法区分,而这恰恰是阅读输出的人看不到的。中止信息会指出该插件,并根据你的本意给出两种补救方法——如果删除是失误,就重新附加该插件;如果是有意为之,就运行上文所述的显式升级——并打印出可直接运行的升级命令。反方向的情况——记录中尚未包含的附加项——就是上文所述的首次出现,两种比较都不会因此中止;签名要求是没有条目的附加项无法逃脱的唯一约束。这三个入口在加载从缓存读取的每个插件时,还会将其与条目记录的签名进行核对,构建页面针对构建描述了这一点。整个目录范围和单个实体范围的 lint 不查阅任何记录。
验证之所以要与记录核对,是因为它运行的检查与构建相同。 aggrega validate --release 会执行 aggrega build 执行的所有检查(包括关卡插件),只是不写出制品——正因如此,“这能通过验证”才与“这能构建”含义相同——因此它所运行插件的身份会像构建时一样与记录进行比较。aggrega validate 的其他范围不与记录核对:验证整个目录、单个实体或插件二进制文件时,根本不会读取工作区的插件附加项,因此其中不会运行任何裁决插件,也没有需要记录约束的内容。
将配置与记录核对,确立的是存在性和身份,仅此而已。 它确立记录中指定的每个关卡仍然处于附加状态,并且每个关卡都从为其记录的制品运行。它并不确立运行过的关卡确实返回了裁决,其中有一种情况在任何地方都不会被发现:某个附加项的 function 指定了插件确实声明的导出,但该导出不是其插槽读取的裁决导出,并且其输出中不包含该插槽预期结构之外的顶层字段——空对象就是最简单的例子——这样的附加项会运行,不返回任何可据以拒绝的内容,并放行构建。它的输出与批准的关卡的输出无法区分,任何与记录的比较都无法察觉,因为记录本身没有任何问题:运行的插件正是所记录的那个,只是它什么都没执行。两种相邻的情况确实会中止,因此这一边界并不比字面意思更宽:function 指定了插件未声明的导出时,会在加载插件时被拒绝;输出包含插槽结构未声明的顶层字段时,会被拒绝,而不会被当作恰好为空的裁决列表读取。因此,仅凭已记录的身份,并不足以说明某个关卡做出了任何判断。
记录的摘要约束的是工作区从 aggrega pull 填充的缓存中解析出的插件,而不约束通过其他方式解析的任何插件。 这是裁决附加项通常采用的解析方式——lockfile 中没有固定它,因此其字节来自缓存,而正是在这次读取中,已解析的摘要会与记录的摘要进行比较。工作区通过其他方式解析的裁决插件永远不会经过这次读取,它受其实际解析方式的约束,而不受记录约束:从编译器二进制文件内置副本提供的字节由携带它们的编译器版本标识;位于其目录实体旁边的 .wasm 是你自己目录中的文件;显式的文件系统路径就是你指定的路径;带有 lockfile 固定的插件受该固定约束。将配置与记录核对的另一半则不受此限制:无论插件如何解析,记录中的每个条目都必须仍有某个已配置的附加项与之对应。因此,无论由什么提供,记录都能确立其指定的关卡仍处于附加状态,并确立从缓存提供的那些关卡的制品身份。
遵循与更新
默认情况下,aggrega pull 遵循已有的 lockfile:已固定的依赖解析为其确切的固定版本(并按其固定的摘要校验),只有尚未固定的引用才会被解析并添加,而 Release 不再引用的固定项会被清除。因此,对未改动的 Release 重新拉取不做任何事——它会逐字节地重现同一个 lockfile(包括 generated_at)。添加新依赖,或在手动编辑删除某个固定项后拉取,只会解析这一缺口,其他固定项保持不变。
**重新拉取从缓存读取的依赖,会按获取它的那次拉取所记录的方式原样记录。**其行保留版本、内容 digest 和 manifest_digest(后者取自缓存中与内容并存的 manifest),以及那次拉取在注册表处验证的 signature 和 deprecation。只要构建会接受该行,这些信息都不会再次查询,--detail 将此类依赖报告为 cache-reuse。因此,如果所有依赖都已缓存,且 lockfile 记录了信任配置要求的每个签名、并且只记录构建接受的签名,那么无论能否访问注册表,重新拉取都会写出相同的 lockfile。
重新拉取恰好在构建会拒绝该行的地方再次查询签名,这样的行有两种。
- **lockfile 未记录的必需签名。**当信任配置要求缓存所提供的某个依赖有签名,而 lockfile 行未记录任何签名时——该行被编辑过、lockfile 在先前拉取填充的缓存之上重新写出,或该要求是在写出该行的拉取之后添加的——重新拉取会按缓存中与该依赖并存的 manifest 的摘要,向该依赖的注册表请求其签名,与对所获取依赖的做法完全相同,并将验证后的签名记录到该行。构建拒绝的正是这一行(No verified signature is recorded for an artifact that requires one(未为需要签名的制品记录已验证的签名)),因此再次拉取即可消除该拒绝。注册表未附加签名,或签名不被信任配置接受时,重新拉取会像获取该依赖的拉取一样中止。允许拉取接纳无签名依赖的设置会保持此类行不变,也不会对其做任何查询:顶层的
skip_signature_verification、注册表自身条目上的同一开关(工作区范围签名策略所要求的类型除外),以及标记为advisory的注册表。 - **构建不接受的已记录签名。**当该行记录的签名所对应的缓存签名包在缓存它的拉取之后被删除或修改——或者是从另一行复制而来的
signature,其签名包完好但是为另一个制品生成的——无论签名要求如何,构建都会拒绝该行(A cached signature bundle does not match the digest recorded for it(缓存的签名包与为其记录的摘要不匹配)、A recorded signature was made for a different artifact(记录的签名是为另一个制品生成的))。因此,无论要求如何,重新拉取都会再次向该依赖的注册表查询其签名,经过与所获取依赖相同的验证:验证结果替换该行的签名,其指向的签名包重新缓存,不再与其摘要匹配的缓存副本被改写——这样该行和缓存保存的就是获取该依赖的拉取所留下的内容。信任配置不接受的签名会使重新拉取像获取该依赖的拉取一样中止,在需要签名时注册表未附加签名也是如此。当验证未记录任何签名时——适用情况下的skip_signature_verification(它不做任何查询)、在不需要签名时未附加签名的注册表,或没有任何可验证内容的advisory注册表——该行的签名会被清除,构建在相同设置下会接纳这一结果。
构建接受其已记录签名的行不会再次查询,未记录签名且无任何要求需要签名的行也不会。
**未指定注册表命名、且所在工作区现已不再指定 default_registry 的依赖,无法查询。**其行由记录其签名的拉取绑定到某个注册表,而没有默认值时就没有可查询的注册表。当此类行记录的签名不被构建接受时,重新拉取会以构建自身的拒绝中止,说明没有配置可用于再次查询该行的注册表,并保持 lockfile 不变。将该依赖来源的注册表配置为 default_registry 后再次拉取即可修复。
**这种遵循所管辖的是注册表或缓存提供的内容。**由本地目录目录提供的实体从该目录解析,采用其文件声明的版本,期间不会参考 lockfile 为其记录的条目。lockfile 仍会记录此类实体,所以你会在其中看到它——但手动编辑该条目不会将实体固定在你写的版本,下一次协调会改写该条目以与文件一致。要更改 Release 解析的本地提供实体的版本,请编辑目录文件而非 lockfile。
**固定项指向的是字节而非位置,因此不再保存其固定内容的缓存条目会被跳过而不是被信任。**原地编辑的实体——在同一 version 下有了新内容——会使内容缓存在该名称和版本下仍保存先前的内容。目录目录会被优先读取,因此仍由目录提供的实体会根据其文件固定,过期条目永远不会被读取。拉取为发现 Release 的外部输入而运行的渲染,会像构建一样从保存固定字节的目录目录读取每个固定项,并以 aggrega build 打印的通知报告被跳过的条目。当没有目录目录提供该实体且可访问注册表时,拉取会重新获取固定版本,改写该条目,并在标准错误中说明,列出条目名称和两个摘要:
reuse: cache entry for <name>:<version> held <digest the entry held>, not the pinned <pinned digest>; refreshed from the registry (pin unchanged)获取的字节与任何固定项下的获取一样按固定项校验,因此在该版本下提供其他字节的注册表会使拉取中止,如下文所述。当没有任何来源保存固定字节时——没有目录目录提供该实体、缓存条目保存的是其他字节,且没有注册表提供固定版本或运行无法访问任何注册表——拉取和 aggrega pull --verify 会以 E0135 中止(若缓存条目的 manifest 不是 lockfile 固定的那个,则为 E0133),并列出读取的每个来源及其保存的内容;若运行未访问到任何注册表,中止信息还会指出重新获取固定版本的步骤。
要更新固定版本,请运行 aggrega pull --upgrade --release <release>——它会丢弃现有固定项,并将所有依赖重新解析为满足条件的最新版本。更新是显式操作;默认行为从不让已固定的依赖浮动。这与 npm ci / cargo / go build 的约定一致(默认实现锁定;更新需主动选择),也正是这一点使 aggrega build 的自动拉取安全——构建严格解析 lockfile 固定的内容,从不悄然变更版本。
这种不带参数的形式会丢弃所有已记录的固定项,因此执行前会请求确认。非交互使用时可用 --yes 预先应答;当标准输入不是终端且未提供 --yes 时,它会拒绝执行,而不是等待无人能给出的应答。指定目标(aggrega pull --upgrade --release <release> <uri>)会保留所有未指定的固定项,因此该形式不会询问。aggrega build --upgrade 运行不带参数的形式,并受相同条件约束。
如果某个已固定版本在注册表中的字节不再与 lockfile 记录的摘要相符(上游违反了不可变性),pull 会以完整性错误停止,而不会悄悄采用变化后的字节——运行 --upgrade 可以有意地重新固定。
检查锁文件而不写入
aggrega pull --verify --release <release> 回答一个问题:现在运行 aggrega pull 是否会改变锁文件,或其旁边的插件信任记录?它执行一次 pull 会执行的解析,将锁文件和该记录与解析结果比较,并在 pull 提交的任何内容被写入之前停止——锁文件、插件信任记录和每个 entity.lock 都保持原样。锁文件缺失或存在任何差异时,它以非零状态退出,并逐一指出每处差异。弃用标记不参与比较,如下文所述。它不能与 --upgrade、--dry-run 同时使用,也不能与 --pin-sources 同时使用,无论该标志取何值:verify 既不记录 entity.lock 缺少的固定版本,也不因缺少固定版本而中止,因此该标志不会改变任何东西。
它与 pull 完全一样遵循已记录的固定版本。 锁文件固定的依赖会解析为其固定版本,并按其固定摘要进行校验;由本地目录(catalog)提供的实体从该目录解析,如遵循与更新所述。因此:
- 自上次 pull 以来其注册表发布了更新版本的引用,不算漂移。pull 会保持其固定版本,因此锁文件仍是 pull 会写出的那个;采用更新版本的方式是
aggrega pull --upgrade。 - 如果注册表现在在某个固定版本下提供了不同的字节,verify 会以使 pull 中止的同一完整性错误中止,而不是将该变化报告为漂移。
- 手动编辑的锁文件条目、编辑过的 Release,以及在本地目录中编辑过的实体都会被报告,因为每一项都是锁文件与 pull 现在解析结果之间的差异。
它与 pull 一样读取并填充缓存。 缓存中按其固定版本保存的条目——目录实体或插件的 .wasm——直接从缓存读取,无需询问注册表,这使得 verify 能在离线模式下,对一个已由联网 pull 填充过的工作区运行。缓存中没有的条目会像 pull 那样被获取,不再与其固定版本匹配的条目也会被完全按 pull 的方式处理。因此 verify 可能向缓存添加内容,但它从不移动固定版本。
它比较两个文件中已记录的签名
pull 为某个制品验证过的签名是其写入内容的一部分:锁文件条目上的 signature,以及 plugins-trust.yaml 中挂载在裁决角色上的插件条目上的签名。固定版本一致后,verify 会将每个已记录的签名与 pull 现在会记录的签名进行对照,并在 pull 会在未记录处记录、替换或清除签名时报告该条目,报告为A recorded signature is not the one a pull would record(已记录的签名不是 pull 会记录的签名)。两个文件中所有此类条目都会在同一次运行中列出。
它查询哪些锁文件条目,由 pull 自身决定。 重新 pull 时,会恰好在遵循与更新所述之处向注册表询问条目的签名,verify 沿用同一选择:
- 有两类条目无需询问注册表即可报告, 因为无论注册表如何回答,pull 都会重写它们:一是由缓存提供、在信任配置要求签名处未记录签名的条目——pull 会记录该制品的签名,或在无法确立签名时停止;二是已记录签名是为另一个制品生成的条目,pull 会将其替换为该制品自己的签名。
- pull 会再次查询的其他所有条目都会被询问, 因为只有注册表的回答才能说明 pull 是否会改变它:包括本次 verify 获取了其字节的条目,以及其缓存签名包已被删除、无法读取或被篡改的条目。verify 像 pull 那样询问注册表,并在回答会记录、替换或清除其签名时报告该条目。它验证过的签名包会像 pull 那样被缓存,因此缓存签名包已被删除、而注册表仍提供已记录签名的条目会通过检查,并使缓存得到修复。
已记录签名被构建接受的条目,以及未记录签名且无任何要求签名的条目,pull 和 verify 都不会询问。
插件信任记录同样以 pull 为准。 每次 pull 都会在注册表处验证挂载在裁决角色上的每个插件的签名,verify 也是如此,并报告该验证会记录、替换或清除其签名的条目。记录中没有条目的插件,若构建因其未记录签名而拒绝它,则会被报告,因为 pull 会写入带有其签名的条目,而在此之前构建会拒绝该插件。其他情况属于首次出现,verify 不报告,正如它不报告记录中尚未保存的任何身份。在离线模式下,verify 不就这些插件询问任何注册表,离线描述了它在此情况下改为报告的内容。
弃用标记不参与比较。 pull 之后附加到制品上的标记属于注册表的状态,它会在工作区没有任何变化的情况下变动;若 verify 因此失败,就会让对你未改动文件的检查失败。出于同样的原因,已记录的标记只向构建提出建议,而不会使其停止。因此,pull 可能会在 verify 已通过的条目上记录标记。
预览拉取将写入的内容
aggrega pull --dry-run --release <release> 与普通拉取完全相同地解析依赖,然后不执行写入,而是打印它本应写入的内容:每个文件先有一个标出其路径的标题,后接该文件将包含的内容。
aggrega pull --dry-run --release release.yaml**它列出每个文件,而不仅是 lockfile。**lockfile、在 --pin-sources 下记录的固定版本将变动的每个 Recipe 和 FeatureRecipe 旁边的 entity.lock,以及插件信任记录,都出现在同一份报告中,因为只显示 lockfile 的预览会让你误以为只有 lockfile 会变动。出于同样的原因,遇到未固定实体会中止的拉取,在 --dry-run 下同样会中止:预览显示的就是拉取将要做的事。拉取会逐字节保持原样的文件根本不会出现——报告中出现某个文件名,就意味着该文件即将改变。最后一行统计这些文件的数量,拉取不会改变的工作区报告的数量为零。
**磁盘上的任何内容都不会变动。**不会写入或创建 lockfile,不会写入或删除实体锁,也不会创建或修改信任记录。当某项能力由多个 provider 插件提供而尚未在它们之间做出选择时,运行会中止并指明需要提供什么,而不是主动提出把该选择写入你的配置——预览不会顺带编辑配置文件。
**解析本身仍会运行,因此缓存仍会被填充。**一个 Release 消费哪些外部输入,是渲染它的产物,而拒绝解析的运行将无从报告,因此 --dry-run 与拉取完全相同地获取并存储内容。.aggrega/cache 下的内容只通过 lockfile 记录的固定版本读取,因此填充它不会改变构建所解析的任何内容;dry run 显示的就是拉取将写入的内容。
**在此标志下,单独的 --upgrade 不会发出询问。**确认之所以存在,是因为完全刷新会丢弃每个已记录的固定版本,而预览不丢弃任何固定版本——因此,当你想知道一次刷新会让你付出什么代价时,应使用 aggrega pull --dry-run --upgrade --release <release>,它无需回答即可运行。
**它不能与 --verify 一起使用,**后者本来就不写入任何这些文件。两者同时使用会让该标志看似起了作用而实际什么也没做,因此会被拒绝而不是被忽略。
**有一件事,固定版本的预览并不总能完整显示,发生时它会明确说明。**被要求固定版本的拉取会重写每个 Recipe 和 FeatureRecipe 旁边的 entity.lock,然后渲染该 Release 以发现其外部输入;预览不会改动这些锁,因此当其中记录的某个固定版本已过时——例如你在固定之后编辑了某个导入的文件——该渲染会被约束到未写入的锁仍记录着的过时摘要,并因此停止。报告中的其他内容都与拉取将写入的完全一致;只有所报告 lockfile 的外部输入固定版本不完整。运行会在其输出和诊断信息中都说明这一点,而不是交给你一个看似完整的 lockfile。工作区的首次解析不受影响,因为此时还没有任何已记录的摘要可能过时。
这些固定版本所描述的组合
lockfile 固定的是该 Release 的一次构建将消费的内容,因此解析过程绘制的组合与该构建绘制的组合相同:它解析文档,应用工作区的附加项所声明的变换,并让结果通过构建对完成的图所做的检查。由此产生两个结果,二者都出现在写入 lockfile 的那一遍,而不是出现在第一次读取它的构建中。
**被这些检查拒绝的组合会使拉取中止。**目标不满足其插槽 selector: 的 uses: 边、附加到其 appliesTo: 不允许的 component 上的 Feature,以及这些检查报告的其他所有违规,都会使该命令停止,并给出与构建相同文档时打印的相同诊断——而且中止时会在一次运行中列出所有发现,而不只是第一个,因此一遍就能给你完整的待修正清单。这发生在写入之前,因此 <release-stem>.lock 和 plugins-trust.yaml 保持原样,一个无法构建的 Release 永远不会被记录为已顺利解析。这一点不涵盖返回裁决的附加项:这里不会运行任何 ir-verdict 或 render-verdict 附加项,因此拒绝性裁决会停止分派它的构建、Release 范围的 lint 或 Release 范围的验证,而不是停止本命令。
塑造图的角色中的附加项会在那一遍中运行,因此无法解析的插件会使拉取中止。 label-transform 附加项在任何内容与节点标签匹配之前决定这些标签,annotation-transform 附加项注入会展开为 Feature 附加项的注解——二者都会改变图中的内容,因此绘制图意味着分派它们,而分派它们意味着持有每个插件自身的字节。这一遍无法获取其字节的插件会使运行中止,并指出该插件以及为它找不到的内容——这与构建同一工作区在无法获取它们时给出的拒绝相同。它分派的是这一遍刚刚解析出的附加项列表,其中携带 lockfile 为后续构建重建而记录的设置和定义文件,因此两遍会针对相同的输入运行相同的附加项。
流水线步骤所指定、但没有任何来源持有的 Plugin 同样会使拉取中止。 Recipe 或 FeatureRecipe 的 pipeline 所指定的每个 Plugin 都与该 Release 的其他依赖一起解析——来自目录(catalog)目录、编译器二进制文件中的副本、内容缓存或注册表——而所有这些都不持有的 Plugin,构建同样无法加载。因此拉取会在写入任何内容之前停止,指出该 Plugin 以及其流水线指定了它的 Recipe 或 FeatureRecipe,并给出构建到达该步骤时引发的条件(A plugin reference is not a Plugin entity(插件引用不是 Plugin 实体))。这适用于 Manifest 绑定的每个 Recipe 和 FeatureRecipe,包括该 Release 中没有任何内容附加的那些,因为无论是否渲染,每一个都会被解析并固定版本。发布该 Plugin,或将它与构建好的 .wasm 一起放入 catalog 目录,然后再次拉取。
**这种中止与降级运行是有意区分的两种结果。**无法完成的渲染——即 How the resolution finds external inputs 和 Offline 都描述的那种——会使每个依赖的固定版本保持正确,因此会写入这些固定版本并报告不足之处。被检查拒绝的组合并不是已解析内容的不足:它是一个无法构建的 Release,因此不会为它固定任何内容,运行也会停止。
缓存
拉取的内容存储在 .aggrega/cache 下,分为三个子树:存放目录实体的 entities/、存放源制品的 source-artifacts/,以及存放渲染所用外部输入的 inputs/。目录实体的槽位按其种类、坐标和版本命名(因此坐标和版本相同的一个 Component 与一个 Recipe 仍保留两个槽位),源制品的槽位按其获取来源、版本和内容摘要的前缀命名,外部输入的槽位按其内容摘要命名;构建从其中任何一处读取的内容都会与锁文件记录的内容进行核对。因此,相同的版本固定在多个 Releases 之间共享同一个槽位。每个源制品槽位包含权威归档、重新生成的解压内容和一个小型元数据文件;解压内容在每次读取时都会重新生成,因此构建输出取决于归档和锁文件,而不取决于已解压文件的状态。
缓存从值派生的每个名称都能被 Windows、Linux 和 macOS 同时接受。 坐标、版本、注册表主机或摘要中含有文件名不能包含的字符:坐标各部分之间的 /,以及版本之前、sha256: 内部和注册表端口之前的 :。因此每个值(种类、坐标、版本、注册表主机或摘要)在成为目录名或文件名之前都会先经过拼写转换:小写字母、数字、.、_ 和 - 按原样写出,其他所有字符都写成以 + 开头的转义序列。版本为 1.0.0 的 Component core/devtool/adminer:1.0.0 对应槽位 entities/+zx000043omponent/core+zsdevtool+zsadminer+zx00003a1.0.0/1.0.0/,按内容摘要命名的槽位则是 sha256+zx00003a<hex>。大写字母同样会被转义,因此在不区分大小写的文件系统上,仅大小写不同的两个坐标仍保持两个槽位;Windows 为设备保留的名称(如 con)首字母会被转义;且任何名称都不以句点结尾。两个不同的值绝不会共享同一名称,而同一个值在每台机器上名称都相同。aggrega cache status 按名称拼写所依据的值列出每个条目(目录实体按其坐标、版本和种类列出),而不是按拼写后的名称。
归档中的条目保留其发布者所起的名称,因此在 Windows 上,Windows 无法容纳的条目会被拒绝。 源制品或目录实体的归档所含的文件按归档给出的名称展开,不经缓存拼写转换。当解压在 Windows 上运行时,如果某个条目包含 Windows 无法按原样容纳的部分——即为设备保留的名称(如 NUL 或 aux,不论大小写、带不带扩展名),或以句点或空格结尾的部分——该条目会以 E0340 被拒绝并给出条目名称,且该归档的任何内容都不会被展开。在 Linux 和 macOS 上,这样的条目按其名称展开。跳出解压目录的条目在任何机器上都会被拒绝。
目录实体的槽位只有带上其清单才算一个条目。 槽位保存注册表提供的内容,并在其旁边保存描述该内容的清单。只有内容的槽位——例如在两次写入之间中断的获取,或手动放入的文件——不算条目:拉取和校验式拉取会在能连接时重新向该实体的注册表请求;而构建从不获取,会将该实体视为缺失,正如拉取在无法连接任何注册表时的处理方式。
进入缓存的内容需满足两点:符合实体自身 schema 描述的结构,以及位于缓存为其指定的位置。 从注册表获取的主体在缓存之前会经过其种类的 schema 检查(与读回时的检查相同),因此注册表提供的、被其自身 schema 拒绝的已发布实体或库会使拉取中止并指明所获取的内容,而不是先被缓存、之后才作为故障暴露。此外,如果用于构建缓存位置的某个值会把缓存文件放到该值所指位置之外的地方——例如版本是路径而非版本,或源的 url 路径或 module_subdir 越出了其所在位置——该值会在构建位置时被拒绝,并指明有问题的值。你编写的 Recipe 或 FeatureRecipe 中写入的值,也会在据其构建缓存位置时受到同样的约束;而 git 源的 module_subdir 则更早,在获取仓库之前就会检查,详见下文。
git 仓库从其自身的检出进行归档。 对于 git-repository 源,拉取会在其固定的提交处检出仓库,并归档 module_subdir 指定的目录或整个仓库。按字面越出仓库的 module_subdir(../shared 或 ..\shared)会在获取仓库之前以 E0307 被拒绝并引用该值,因此不会读取检出之外的任何内容。仓库中提交的符号链接,若其指向位于仓库内部,则按其指向的文件或目录归档——module_subdir 本身也可以是这样的链接。指向仓库外部的链接会以 E0321 中止拉取,并指明该链接及其指向,且不缓存任何内容,因此你所拉取的仓库无法让拉取把你机器上的文件复制进制品。检出会在拉取结束后被删除,因此消息按链接在仓库中的位置以及源所指定的仓库和修订来指明链接,而不是给出一个已不存在的目录。该链接应由仓库负责修改。工作区边界说明了此处所应用的规则。
缓存锚定在工作区,而不是你运行命令时所在的目录,因此一个工作区只有一个缓存,从子目录运行的拉取所填充的存储,正是从根目录运行的构建所读取的存储。
未找到工作区且未指定工作区时,拉取会在获取任何内容之前被拒绝。 当没有任何设置指定根目录、发现机制也未锚定任何位置时(无论从你运行命令的文件夹开始,还是对于以绝对路径指定的 Release,从该 Release 所在的文件夹开始),该文件夹就会成为根目录,而在其下写入缓存会使它变成一个工作区。因此拉取会停止,不写入锁文件和缓存,并指明该文件夹及两种解决办法:使用 --workspace-root 或 AGGREGA_WORKSPACE_ROOT 指定工作区,或者为该文件夹提供一个包含 workspace: 块的 .aggrega-config.yaml。aggrega mcp 的拉取工具在未设置根目录启动的服务器上不带 workspace_root 调用时,也会以同样方式被拒绝;配置列出了适用此规则的其他命令。
在无法访问网络的环境中构建
由于此命令是唯一对外访问的步骤,只需一次联网运行,之后的每次构建都可以在本地完成。该次运行会写入 lockfile,并用这些固定版本所指向的字节填充工作区缓存,此后构建不再需要它们之外的任何内容。
需要将三样东西带到断网的机器上:
- Release 及其 lockfile。 将
<release-stem>.lock提交在 Release 旁边;构建正是通过它得知每个依赖解析到的版本和摘要。 plugins-trust.yaml,当工作区挂载了返回裁决的插件时。 构建会在任何裁决挂载运行之前,将其配置中指定的裁决挂载与该记录进行比对,因此携带该记录,才能让断网构建受限于经过审查的身份以及 pull 为它们验证过的签名。按照插件信任记录中的说明,将其提交在 lockfile 旁边。- 缓存目录。 实体、源制品和固定的输入都存放在该目录下,本地
catalog_dirs目录未提供的任何内容都从这里读取。
在断网的机器上照常构建。即使基于完整 lockfile 的构建会从缓存读取其闭包,在那里设置离线模式仍然值得:它会把一次潜在的网络访问变成立即拒绝并指明该模式,而不是一次必须先等待超时的连接尝试。缓存中没有的任何内容,以及 lockfile 未固定的任何外部输入,都会使构建中止,并指明缺少的内容以及能够固定它的解析——不会为了填补空缺而悄悄获取任何内容。
物理隔离的机器和离线工作区是两种不同的声明,这一区别值得保留。 物理隔离的机器可能持有注册表的本地副本,或一个包含所需全部内容的 catalog_dirs 目录,此时在该机器上执行普通的 pull 完全无需对外访问即可满足。离线模式描述的是命令可以访问什么,而不是机器持有什么;离线说明了它拒绝什么、不影响什么。
离线
在离线模式下——即配置文件中的顶层 offline 键、环境中的 AGGREGA_OFFLINE,或命令行上的 --offline——aggrega pull 会拒绝网络访问。拒绝发生在尝试任何连接之前,而不是在获取过程中途超时,因此离线 pull 不会访问任何注册表或远程来源。如果离线模式由已提交的文件或导出的变量设置,而你想让某一条命令绕过它,--offline=false 仅在该次运行中允许网络访问。
在离线模式下,--upgrade 会被直接拒绝,这也是此处唯一会被拒绝的选项。 完整刷新会把每个依赖浮动到注册表当前提供的最高版本,因此需要询问注册表当前提供什么。普通 pull 则不需要:它遵循已记录的固定版本,只解析尚未固定的内容,因此仅凭机器已有的内容即可满足。拒绝信息会说明是三个位置中的哪一个设置了离线模式,以及如何在单次运行中允许网络访问。
此时解析只使用机器上已有的内容:catalog_dirs 搜索栈和 .aggrega/cache 下的缓存。如果目录和缓存能满足每个引用,离线 pull 会正常完成并写入普通的 lockfile。lockfile 记录每个依赖的 URI、解析后的版本和摘要,但从不记录字节由哪个位置提供——因此解析出相同版本的离线 pull 与在线 pull 会写出相同的 lockfile。
离线 pull 无法在本地满足的依赖会使其中止。 该条目绝不会被跳过:
- 在任何位置都无法解析的目录实体会使 pull 中止,并指出该引用及其被引用的位置,从而同时指明缺失的依赖和请求它的对象。
- 远程
source:会使 pull 中止,指出该来源,并提示你允许网络访问,或从联网环境填充缓存。 - 如果缓存中持有的依赖所需的签名未被 lockfile 记录,或其已记录的签名不被构建接受,pull 会以离线拒绝中止并指出该依赖:记录签名意味着要询问其注册表,如 遵循与更新 所述。为该次运行允许网络访问即可记录它。构建接受的已记录签名不会再次查询,因此不会阻止离线 pull。
外部输入是唯一不会导致中止的情况,它会改为如实报告。 发现外部输入的渲染无法获取尚未存储的内容,因此对含有未固定外部输入的 Release 执行离线 pull 时,pull 会完成,写入它解析出的每个依赖固定项,并报告三件事:渲染未完成、它固定了哪些内容,以及对该 Release 的构建将会中止并指出该 URL。它写入的依赖固定项是正确的——它们与渲染无关——因此会被保留,而不是丢弃后让读者重新生成。
这是有意为之,而非缺陷,也没有开关可以改变它。丢弃正确结果的 pull 会让你失去已成功的部分;保持沉默的 pull 会交给你一个看似完整实则不完整的 lockfile。如实报告是唯一能让你采取行动的结果:从联网环境,或从缓存中已持有该内容的环境再次运行 pull,同一条命令就会将其固定。
因此,离线 pull 是拒绝接触网络,而不是对文档所提及的一切给出缩减的结果;对于外部输入,它是一次已完成的解析,并告诉你它无法访问哪些内容。存在的 lockfile 意味着其依赖解析已完成;其外部输入是否完整,由 pull 自身的输出告诉你,构建随后也会据此检查。
在离线模式下,--verify 覆盖的范围更小,并会报告这一点。 查询已记录的来源 ref 当前指向何处需要访问其远程,而离线模式会拒绝这样做。因此离线的 --verify 会检查已固定的依赖并跳过这一项,同时打印一行说明,而不是报告它从未确认过的匹配。只有其注册表才能确认的已记录签名——位于缓存签名包已被删除或修改的 lockfile 条目上——也会以同样方式跳过,并逐行指出每个此类条目:
verify: offline, so the signature the lockfile records for "<reference>" was not checked at its registry, which alone can say whether a pull would record it again; this verify does not cover it无论注册表如何回答,pull 都会重写的已记录签名在离线时仍会被报告,因为无需任何回答即可得知这一点,如 它会比较两个文件中已记录的签名 所述。
挂接在由注册表提供的裁决角色上的插件,是离线校验与离线拉取分道扬镳之处。 这类插件从不在锁文件中固定,因此每次拉取都会从其注册表解析它的 .wasm;对挂接了此类插件的工作区执行离线拉取会在此停止,并将该插件指明为无法解析其 .wasm 的插件——即使内容缓存中存有它,也无论该注册表是否标记为 advisory 或跳过签名验证。离线校验则不就该插件向注册表询问任何内容:它像构建那样从内容缓存中读取插件,并在缓存中没有其 .wasm、或所存文件已不再匹配其已发布清单所指明的摘要时停止。它仍会依据插件信任记录核对插件的身份,并针对该 .wasm 重新检查其宿主函数,任一不一致时即中止,与联网校验完全相同。对于无论注册表如何应答,拉取都会重写其条目的插件,它会予以报告,这也正是构建因其条目而拒绝该插件的情形:因未记录签名——其条目未记录签名,或记录中没有它的条目——或因其条目记录的签名是为另一个制品生成的,拉取会将其替换为该插件自身的签名。其他所有条目——构建接受其签名的条目,以及缓存的签名包已被删除或篡改的条目——它会在一行中指明其签名未经检查,且不报告该签名的任何情况:
verify: offline, so the signature of "<plugin>" was not checked at its registry, which alone can say whether a pull would record the same signature on its entry in the plugin trust record; this verify does not cover it因此,对于联网 pull 会替换或清除其签名的条目——例如签名者被手动编辑过的条目,或其注册表已不再附加签名的条目——离线 verify 会直接放过,只有那一行会说明这一点。气隙环境中的 verify 仍然可用;它不会告诉你的是某个 ref 此后是否已移动,或被跳过的签名是否会被再次记录。仅读取退出码的检查只有在 verify 联网运行时才能覆盖这些情况。
与 aggrega build 的集成
- 校验。
aggrega build会对照 lockfile 校验每个已解析的依赖,并在出现漂移时停止:内容不再与其固定版本匹配的实体、库或插件;Release 现在引用到但 lockfile 未固定的引用,或 lockfile 固定但 Release 已不再引用的引用;以及在 pull 之后被编辑过的 Release 文件。运行停止时打印的命令aggrega pull --release <release>即可清除漂移:pull 按 Release 的当前状态解析它,重写发生变化的固定版本,并保留其他所有固定版本,因此你未改动的内容都不会浮动。如果发生变化的是某个 Recipe 本地源下的文件,pull 会先针对该实体提示aggrega pin,如 实体锁 所述。此命令刚写入的 lockfile 能通过该检查,因为命令在写入前会运行同样的检查;如果 pull 之后紧接着的 build 因漂移而停止,说明 build 收到的输入与 pull 不同——例如只向其中一个传入了--catalog目录,或在两者之间编辑了工作区配置——因此请让两者在相同的输入上运行。aggrega validate --release以及每个会解析 Release 的aggrega inspect选项都会对 lockfile 执行相同的检查,并以相同的停止信息拒绝,因此二者都不会放过构建所拒绝的 lockfile。 - **自动 pull。**如果 lockfile 缺失且
auto_pull为 true,aggrega build会先自动运行 pull。如果auto_pull为 false(其默认值),build 会停止并要求你执行 pull。build 运行的 pull 遵循pin_sources_at_pull,因此遇到未固定的实体时,它会与 pull 一样停止。build 运行的 pull 步骤就是本页描述的那一步,因此填充已有 lockfile 的 build 在遇到已移动的源 ref 时,会与aggrega pull完全一样地停止——参见 确定性与完整性。 - **离线。**在离线模式下,
aggrega build只使用机器上已有的内容,并在尝试任何连接之前拒绝网络访问。缓存中没有其内容的引用会使 build 停止,而不是在获取过程中途失败;没有 lockfile 且未被要求填充它的 build 会停止并指出能填充它的 pull,与在线时完全一样。--auto-pull不会被拒绝:它要求的填充就是本页描述的 pull,因此对于已缓存或存在于本地目录中的目录实体,它无需访问注册表即可写入 lockfile——chart 从远程源获取的 Recipe 会被重新解析,因此离线时即使缓存中有该 chart 也会停止——而两者都没有的引用(或已缓存但 lockfile 未记录其所需签名、或其记录的签名不被 build 接受的引用)会使它以 pull 自身的拒绝信息停止,并指出该引用。--upgrade会被拒绝,原因见 离线。 - **目录搜索。**即使未提供
--catalog,pull 也会遵循.aggrega-config.yaml中的catalog_dirs——以及配置在workspace.releases下为某个 Release 指定的目录——并解析与aggrega build相同的先命中优先搜索栈,因此它固定的依赖与 build 搜索到的内容一致。列出的某个目录若不是目录——例如该处什么都不存在——两个命令都会在解析或写入任何内容之前拒绝它,并指明该条目以及列出它的配置文件和行,如 本地实体从何处读取 所示。
解析如何找到外部输入
本节内容不改变上述规则——固定任何内容的时刻仍然只有一个,就是此命令。本节描述的是此命令如何获取三类输入中的第三类;当你把解析接入流水线、阅读一次降级运行的结果,或思考此命令为何要进行渲染时,这一点很重要。
目录实体和源制品各自在文档中被命名;外部输入则不是。 解析前两者只需读取你编写的内容。外部输入由 provider 在渲染过程中命名,而它命名哪些 URL 取决于正在渲染的值——缺失的某个 values 条目会使 chart 模式的整棵子树不被编译,该子树中的每个远程引用也都不会被请求。读取 Release 无法枚举出这个集合。
因此,此命令在一次运行中做两件事:先解析并固定文档所命名的闭包,再渲染该闭包,以查看 provider 请求了哪些远程文档。渲染出的制品被丢弃,固定项被保留。两者都在这一个命令内部完成,都不是可能固定内容的第二个时刻——lockfile 只写入一次,且包含所有固定项。
在把解析作为一个低成本步骤接入自动化流水线之前,有两个后果值得了解。 它的开销比只读取文档的解析更大,因为它要渲染。它还可能因只读文档的解析不会遇到的原因而失败:某个 provider 无法渲染此 Release。发生这种情况时,依赖固定项仍会被写入,因为它们与渲染无关;诊断信息会指出停止的阶段、已固定的内容,以及构建将会停止并指出未固定的 URL。这次运行并未白费,Offline 展示了以另一种方式得到的相同结果。
渲染还会在写入任何内容之前,让 lockfile 接受构建所执行的比较。 它运行构建自身的流程,因此会把此命令即将写入的 lockfile 与同一 Release 的构建所解析出的结果进行比较,正如构建比较它在磁盘上找到的 lockfile 一样。被该比较拒绝的 lockfile 不会被写入——此命令本应在其后写入的其他任何内容也不会——命令会停止,说明解析与构建对该 Release 的依赖存在分歧,并列出比较所指出的每个条目。你的文件中没有任何内容会导致这种情况,再次解析也会得到同样的分歧,因此请连同该 Release 一起报告,而不要重试。这是唯一会阻止写入的渲染失败,也正因如此,在相同输入上对同一 Release 进行的构建不会对此命令写入的 lockfile 报告漂移。
没有跳过渲染的开关。 这样的开关会以选项的形式保留单一时刻所消除的那种意外:一个 Release 解析顺利,而其渲染所需的某个输入却未被固定,直到构建时才被发现。
--auto-pull 把同样的解析并入构建,且构建只渲染一次。 填充过程中的渲染负责找到并固定外部输入,构建直接呈现该次渲染,而不再执行第二次,因此一条命令完成的构建与在已填充 lockfile 上的普通构建开销相同的渲染。aggrega build 说明了构建的哪些渲染标志会作用于它。
该集合取决于 Release 的参数,这与组件固定项的现有行为一致。 在解析与构建之间编辑 Release 的参数就是对该 Release 的编辑,因此构建会在漂移比较时停止并指出该文件,早于任何渲染请求未固定的 URL;解决办法就是此命令。从单独文件导入的参数不按内容记录,因此改为编辑该文件会进入渲染阶段,渲染会停止并指出未固定的 URL——给出的解决办法同样是此命令。
确定性与完整性
Recipe 的 source: 可以基于 Release 解析后的 values 和 infra(以及在其上定义的 locals)对其版本进行模板化;这些在 pull 时解析,结果会被固定。pull 只求值 source: 字段读取的 locals: 条目,以及这些条目又读取的条目,并且只使用 Aggrega 自身的模板辅助函数:源读取的条目如果调用了 Sprig 函数,pull 会中止,并指出该条目、字段和函数;而没有任何 source: 字段读取的条目则留给 build,build 会在 Recipe 渲染时对其求值和检查——参见 Resolving a source: coordinate registers a narrower function set(解析源坐标时注册的函数集更窄)。可变的 Git 标签或分支会被固定到它所指向的具体提交,你编写的 ref 会记录在其旁边。在 build 时,缓存归档的摘要会根据 lockfile 重新校验,因此被篡改的缓存会被发现。
已记录的 ref 会被约束在它所固定的提交上。 记录 ref 是因为后续运行会再次查询它,而不是为了可读性——构建查询它指向哪个制品,拉取查询它是否仍指向原处。非升级的 pull 会重新查询每个已记录 ref 的指向,若某个 ref 在其远程已移动,运行会停止——指出该制品、ref、lockfile 固定的提交以及它现在解析到的提交——而不会采纳这一移动。运行 aggrega pull --upgrade --release <release> 来采纳它。指定实体 URI 的定向升级则不会采纳:源引用不是你可以指定的实体,因此定向运行会像普通拉取一样保持它不变。
这项检查是构建时摘要重新校验无法替你完成的唯一一件事。采纳了已移动 ref 的拉取会在同一操作中重写获取的字节和记录的摘要,于是构建所比较的两个值会一起改变并保持一致——你构建的源内容将不同于审查 lockfile 时所针对的内容,而且不会有任何报告。
只有 lockfile 记录的 ref 才会这样被约束,而只要你编写了 ref,它就会被记录。仅通过 version: 指定源的 Recipe 没有 ref,因此后续运行没有可重新查询的内容——这是正确的结果,因为你自己写下的版本不会在你不知情时改变。lockfile 参考说明了记录的内容。
写 ref,而不是提交。 build 通过你编写的 ref 查找来自 git 的制品,并与 lockfile 记录的 ref 进行匹配,因此 ref: v1.2.3 会基于该标签被固定时的提交进行构建,提交无需出现在你的 Recipe 中。改为在 version: 中指定可变标签是行不通的,也并非设计用途:version: 按原样匹配,而对于 git 源,lockfile 固定的是提交。
lockfile 固定从注册表和远程源获取的内容,并记录它从你的目录(catalog)中解析的每个实体的摘要——涵盖实体文件及其旁边引用的每个文件,如 The lockfile 所述——以及解析过程读取的每个 Release 文件的摘要。以 ./ 或 ../ 开头的源的文件,以及实体导入的制品文件,也会在该实体旁的锁中逐一固定,如 The entity lock 所述,正是这一点指出了发生变化的文件;两次构建之间工作区其余部分的完整性由源代码控制系统负责。确定性保证的范围参见字节完全一致的输出。
身份验证
镜像仓库凭据仅从 Docker 凭据配置中读取:DOCKER_CONFIG 所指目录中的 config.json,该变量未设置时则为 ~/.docker/config.json,以及该文件通过 credsStore 或 credHelpers 委托的任何凭据助手或操作系统钥匙串。aggrega login <registry> 会将凭据写入该处,docker login <registry> 也会;对于私有 OCI 目录或 chart 镜像仓库,请在 aggrega pull 之前运行其中之一。podman login 和 helm registry login 写入的文件不会被读取。
无法读取的凭据配置在报告时不会透露其内容。 如果 config.json 不是有效的 JSON、某个条目的 auth 值不是以冒号连接的 base64 编码用户名和密码,或者文件指定的凭据助手无法应答,则连接注册表会失败,消息会指明注册表和凭据文件,但绝不会给出文件或条目的内容。aggrega login 和 aggrega logout 以同样方式报告不是有效 JSON 的 config.json,且不会更改其中任何内容。请更正该文件;无法读取的条目也可以用 aggrega login <registry> 替换。
经典 Helm chart 仓库或 chart 归档(helm-https-chart)、compose 片段(compose-https-fragment)以及通过 HTTP 或 HTTPS 访问的 Git 仓库(git-repository)使用 netrc 文件进行身份验证,curl 和 Git 也读取这个按用户的凭据文件。这是这三种类型读取的唯一凭据存储:~/.config/helm/repositories.yaml 和 Git 凭据助手不会被读取。通过 SSH 访问的 Git 仓库通过 SSH agent 进行身份验证,不读取任何 netrc 文件。
machine charts.example.com login deploy-bot password <token>读取哪个文件。 如果设置了 NETRC 环境变量,则读取它指定的文件。否则读取主目录中的 .netrc;在 Windows 上,如果 %USERPROFILE% 中存在 _netrc 则读取它,不存在时读取该处的 .netrc。缺失的文件不包含任何凭据,不算错误。存在但无法读取或不符合 netrc 格式的文件会以 E0360 停止命令,指出该文件——对于格式错误还会指出所在行——但绝不显示文件内容:The netrc file cannot be read(无法读取 netrc 文件)。在 Linux 和 macOS 上,机器上其他用户可读的 netrc 文件会触发一条指出该文件的警告;请将其设为仅你可读(chmod 600)。
哪个条目响应请求。 每个请求按其主机查找——不含端口的主机名,不区分大小写——由第一个指定该主机的 machine 条目响应,若没有则由 default 条目响应。条目的 login 和 password 作为 HTTP 基本凭据发送,http 和 https 均如此;缺少其中任何一个的条目不发送任何内容。索引将 chart 放在另一主机上的仓库按请求分别响应:索引请求使用仓库主机的条目,chart 请求使用 chart 主机的条目。不带凭据的请求必须可匿名读取,以 401 或 403 应答的服务器会将 pull 作为未授权的获取而停止,其修复建议会指出要添加的条目以及查找该条目的文件。
凭据不会写入任何地方。 它在获取运行时被读取并随请求发送:lockfile、Recipe 旁的 entity.lock、源缓存以及每条消息都按你编写的原样携带源的 URL。
源 URL 不携带凭据。 如果 Recipe 或 FeatureRecipe 的源 url 在主机前写了用户——https://user:token@charts.example.com/…,或单独写的令牌,如 https://token@charts.example.com/…——则会在读取文档时、获取任何内容之前以 E0361 被拒绝:验证该 Recipe 会拒绝它,到达它的每次 pull、pin 和构建也会拒绝它。消息会指出主机,但绝不显示凭据:A source URL carries a credential(源 URL 携带凭据)。请改为将凭据放入 netrc 文件的 machine 条目中。对于 SSH,单独写的用户——ssh://git@github.com/…——指的是账户而非秘密,因此被接受,而在该处写入的密码同样会被拒绝。
该检查只读取 URL 中主机之前的部分。 放在查询字符串或路径中的令牌——…/index.yaml?access_token=…——不会被检测到,因此不要将令牌写在那里:URL 会按原样记录在 lockfile、entity.lock 和源缓存中,包括缓存目录的名称。
环境变量
pull 读取的工作区设置可以通过环境变量覆盖,其优先级高于已提交的配置、低于任何标志:AGGREGA_OFFLINE(参见 离线,以及优先级更高的标志 --offline)、AGGREGA_CATALOG_DIRS(以操作系统路径列表分隔符分隔;请提供绝对路径)、AGGREGA_ARTIFACT_CACHE_DIR、AGGREGA_DEFAULT_REGISTRY,以及 AGGREGA_SKIP_SIGNATURE_VERIFICATION(会显式提示——凡是 pull 本应检查签名之处,都会记录一条警告,说明验证已被全局禁用)。完整列表和优先级模型请参见 environment-variables.md。
另请参阅
- ./aggrega-build.md — 校验 lockfile,并在已配置时自动拉取。
- ./aggrega-serve.md — 守护进程在
aggrega/resolveDependencies中提供同样的解析,并在autoPull字段要求时于aggrega/build内执行, 因此编辑器无需离开会话即可运行它;无论哪种方式,它都只在请求指明时运行, 并写入与本命令相同的 lockfile。 - ./aggrega-push.md — 将目录实体发布到注册表。
- ./aggrega-lint.md — 在
aggrega push之前执行的发布关卡。 - ../../architecture/13-catalog-and-registry.md — 目录、lockfile 和缓存模型的完整说明。
概要
aggrega pull [<uri>...] [flags]说明
Resolve the Release's catalog and source dependencies into the cache and write the per-Release lockfile.
By default, pull reconciles the lockfile against the current dependency resolution while honoringthe pins it already records. That pin discipline governs what a registry or the content cacheserves: such an entity is fetched at its pinned version and verified against its pinned digest,and if the registry no longer serves the pinned bytes, pull halts rather than silently re-pinning.An entity a local catalog directory supplies is resolved from that directory instead, at theversion its file declares, and its recorded pin is not consulted — so editing a pin by hand doesnot hold a locally-supplied entity at that version, and the reconcile rewrites the entry to matchthe file. A reference with no pin — newly added, or removed from the lockfile by hand — isresolved fresh and added. Entities no longer among the resolved dependencies are pruned.Re-running pull on an unchanged dependency set is a no-op.
Use --upgrade with no positional arguments to discard the existing lockfile and re-resolveevery entity from current registry state, floating each dependency to the highest availableversion. That form drops every recorded pin, so it asks for confirmation first; --yes answers inadvance, and on a non-interactive stdin it refuses rather than waiting for an answer nobody cangive. Pass one or more entity URIs after --upgrade to upgrade only those: each named pinis dropped and re-resolved fresh while every other pin — and the recorded external inputs —is held unchanged. A named target may also be a plugin that returns an accept-or-reject verdict;such a plugin carries no lockfile pin, and its identity is recorded beside the lockfile instead.Naming one the workspace still attaches adopts the identity it resolves to. Naming one theworkspace no longer attaches drops its recorded identity — the one way to clear an entry thatoutlived the attachment it was recorded for. A bare --upgrade does both for every plugin at once.A URI given without --upgrade is a usage error.
Each Recipe and FeatureRecipe this Release builds from one of your catalog directories carriesthe pins for its own inputs in the entity.lock beside it: a remote source: written out in full,a file an artifacts entry imports, and each file of a local source:. Recording them is theentity author's step, aggrega pin.By default pull records none of them, and halts on an entity whose lock is missing any, namingthe entity, each input and its class, and the command that records them. A local source's filesare held to their pins as one set: a file added, changed or removed since the pin halts the pullthe same way.Pass --pin-sources, or set pin_sources_at_pull in the workspace configuration, to have pull runthat same step instead; --pin-sources=false restores the halt for one run.
Which files of a local source directory belong to its entity was decided when the entity waspinned, by the ignore rules of the plugin that served its capability for the author, and itsentity.lock records that decision. Where the plugin this workspace binds for that capabilitydeclares different rules, pull prints a warning naming both plugins and the difference, andcarries on: the entity's files are the ones its recorded rules kept.标志
| 标志 | 默认值 | 描述 |
|---|---|---|
--catalog | [] | 目录路径;可重复指定。每个 —catalog <dir> 都会被添加到目录搜索栈的最前面(首个匹配者胜出):该栈为工作区的 catalog_dirs,或者,对于工作区配置在 workspace.releases 下为其单独指定目录的 Release,则为该 Release 的目录;如果工作区根目录下存在名为 catalog 的目录,该栈以它结尾。写为空列表的 catalog_dirs 完全不读取任何本地目录。 |
--detail | false | 针对每个已解析的实体,打印本次拉取对它做了什么——从注册表新获取、复用缓存槽、在本地目录中找到、由编译器二进制内部提供,或为外部实体(该 Release 自身的 Aggregate 或 Manifest,从该 Release 指定的文件或条目读取)。仅输出到 stdout;不写入 lockfile |
--dry-run | false | 解析依赖,并打印本次拉取将写入的内容而不实际写入:每个文件的路径及其将包含的内容输出到 stdout,而 lockfile、在 —pin-sources 下记录的固定版本会变动的每个 Recipe 和 FeatureRecipe 旁的 entity.lock,以及插件信任记录都保持不变。只列出实际会改变的文件。解析本身与平时完全相同地运行,因此内容缓存仍会被填充,在未固定的实体上会中止的拉取在此也会中止,而单独的 —upgrade 不会询问,因为它不丢弃任何固定版本——试运行显示的就是拉取将写入的内容。不能与 —verify 一起使用,后者本就不写入这些文件 |
--include-prerelease | false | 尚未实现:接受但忽略,因此传入它的脚本在其开始生效后仍能正常工作 |
--pin-sources | false | 对此 Release 构建的 Recipes 和 FeatureRecipes 运行实体作者的固定步骤,在每个实体旁的 entity.lock 中记录其读取的每个输入的固定版本——完整写出的 remote source:、artifacts 条目导入的文件,以及本地源的每个文件——而不是在锁未记录它们的实体上中止。与 aggrega pin 是同一步骤,写入相同的字节。它写在实体旁边,因此只在实体有可写位置时运行:即你的某个目录中的文档。从缓存解析的实体没有可写位置,永远不会被固定。在两个方向上覆盖工作区的 pin_sources_at_pull:无论该设置如何,—pin-sources 在本次运行中固定,—pin-sources=false 在本次运行中中止 |
--progress | false | 即使 stderr 不是终端,也强制开启拉取进度显示,每个步骤完成时打印一行纯文本及其耗时。默认值为 auto:仅当 stderr 是能解释转义序列的终端时才显示交互式阶段清单,不能解释的终端会得到同样的纯文本行,而重定向或管道输出则不显示任何内容 |
--quiet | false | 关闭 stderr 上的拉取进度显示。不影响 stdout。优先于 —progress |
--release | — | Release YAML 文件的路径(必填)。相对路径相对于你运行命令所在的目录解析,而不是相对于工作区根目录。当该目录不属于任何工作区且未指定根目录时,绝对路径会从该 Release 自身所在的文件夹查找工作区 |
--upgrade | false | 根据注册表的当前状态重新解析依赖,将每个依赖浮动到可用的最高版本。单独使用(无位置参数 URI)时丢弃 lockfile 并重新解析每个实体,并且由于会丢弃所有已记录的固定版本,会先请求确认;指定一个或多个实体 URI 时,仅重新解析这些实体,其他所有固定版本和已记录的外部输入保持不变,且不询问(与 —verify 互斥) |
--verify | false | 将现有 lockfile 与拉取此刻将执行的依赖解析进行校验,不写入 lockfile、插件信任记录或任何 entity.lock;出现偏移或缺少 lockfile 时以非零状态退出。解析与拉取完全相同地遵循 lockfile 记录的固定版本:自拉取以来其注册表已发布更新版本的引用不算偏移,因为拉取会保持其固定版本;而注册表在某个固定版本下提供不同字节时,校验会像拉取一样中止。内容缓存的读取和填充方式与拉取相同:缓存在其固定版本下持有的条目直接从缓存读取而不询问注册表,未持有的条目会被获取,不再与其固定版本匹配的条目的处理方式与拉取完全相同。还会将该 Release 涉及的、你的目录中每个 Recipe 和 FeatureRecipe 旁的 entity.lock 与构建所比对的内容进行核对,并在构建会拒绝的固定版本上以非零状态退出:不再与其记录摘要匹配的导入文件、文件不再与其记录摘要匹配的本地源,或与 lockfile 不一致的源固定版本。还会将 lockfile 为每个制品记录的签名、以及每个插件的插件信任记录,与拉取此刻将记录的内容进行比较,并在拉取会记录、替换或清除某项时以非零状态退出:要求所需但未记录的签名,以及为其他制品生成的签名,会在不询问注册表的情况下报告,因为无论注册表如何应答,拉取都会重写它们;拉取会重新查找并可能原样记录的签名——制品被获取过,或其缓存的签名包被删除或修改——会在其注册表处查询,或在离线状态下不予检查并输出一行说明;插件信任记录涵盖的每个插件都会在其注册表处校验,与每次拉取一样,但离线状态下除外,此时它像构建那样从内容缓存读取,其身份和宿主函数仍会检查,签名则不予检查并输出一行说明,除非构建因其未记录签名或签名为其他制品生成而拒绝它,此时会报告。不比较弃用标记。还会报告 lockfile 记录的编译器和核心插件版本——仅用于审计,从不与当前二进制比较,因此工具链差异永远不算偏移。无论赋予何值,均不能与 —pin-sources 一起使用:校验既不会记录 entity.lock 缺失的固定版本,也不会因此中止,因此该标志不会改变任何东西(与 —upgrade 互斥) |
--yes | false | 预先回答单独 —upgrade 的确认提示,用于非交互式场景。它只作用于这一个提示:其他所有形式的拉取都不会询问,因此在那些场景下传入它不会改变任何行为 |