aggrega push-artifact
将独立的数据产物(如文档包)发布到 OCI 注册表
概要
aggrega push-artifact <file> [flags]说明
Publish a standalone data artifact — a documentation bundle or any other non-entity blob — to an OCI registry under the reserved docs/ namespace. Unlike push, which bundles a catalog entity and dispatches on its kind, push-artifact carries opaque bytes: it reads the file, packs it under the given media type (defaulting to the documentation-bundle media type), and tags it at docs/<name>:<tag>. The published artifact is signed separately by reference with aggrega sign. Beside it, push-artifact states when it published, as a small published-at attachment carrying this machine's clock in UTC to the second; the attachment moves no digest and changes no tag.标志
| 标志 | 默认值 | 描述 |
|---|---|---|
--dry-run | false | 计算引用并打印拟定的 |
--media-type | application/vnd.aggrega.docs.v1beta1+tar+gz | OCI 产物媒体类型;默认为文档包媒体类型 |
--name | — | 保留的 docs/ 命名空间内的产物名称(例如 “aggrega-docs” 发布到 docs/aggrega-docs) |
--registry | — | 目标注册表主机(覆盖工作区的 default_registry) |
--tag | — | 发布产物所用的版本标签(必需) |
文档包产物
文档包是一个独立的数据产物(渲染后文档的 gzip 压缩 tar 包),而不是目录实体。它带有媒体类型 application/vnd.aggrega.docs.v1beta1+tar+gz,这是使用者从注册表拉取该包时看到的产物类型。
文档包发布在 docs/ 仓库段下:--name aggrega-docs 将产物放在 docs/aggrega-docs,--tag 选择版本,因此拉取坐标为 <registry>/docs/<name>:<tag>,例如
hub.aggrega.ai/docs/aggrega-docs:1.0.0。由于该包是普通的数据产物而非目录实体,任何兼容 OCI 的客户端都可以使用该引用和媒体类型获取它。发布的文件带有通过 --name 指定的名称,因此按名称写入文件的客户端会以该名称写入:
oras pull hub.aggrega.ai/docs/aggrega-docs:1.0.0 会在当前目录留下 aggrega-docs,与发布时逐字节相同。
当注册表写入失败时
发布分步骤写入注册表:文件、指明该文件的 manifest、标签,然后是其旁边的发布日期。当注册表或网络以后续尝试可能成功的方式使其中某次写入失败时(例如服务器错误、超时或连接重置),该写入会被重试;
aggrega push 列出了这些失败。每次写入最多尝试三次,间隔依次为半秒和一秒,每次尝试都是对相同字节的重新上传,而不是重发失败的请求,因此重试的写入与单次尝试写入的结果相同。
写入在最后一次尝试后仍失败时,命令失败,错误会指明是哪一步。附加日期失败发生在产物已写入之后:产物保持已发布状态,命令以非零状态退出,并说明无法附加其发布日期。再次运行相同的发布即可完成它:产物被报告为已发布,不上传任何内容,并在产物没有日期时附加日期,该日期记录的是那次运行的时钟,即发布完成的时间。已经带有日期的产物不会附加任何内容;无法读取列表时,命令以非零状态退出,且不附加任何内容。
离线
发布产物需要一次网络往返,因此在离线模式下(配置文件中的顶层 offline 键、AGGREGA_OFFLINE 或 --offline),该命令会在读取文件之前拒绝执行,并在拒绝信息中指明是这三者中的哪一个设置了该模式。--dry-run 仍可使用,因为它只计算引用,不发起调用。要在离线工作区中为单次运行执行发布,请传入 --offline=false。
另请参阅
- ./aggrega-sign.md:数据产物在发布之后按引用进行签名; 此命令本身不附加签名。
- ./aggrega-serve.md:守护进程在
aggrega/publishArtifact提供相同的发布功能,因此编辑器无需离开会话即可运行它。 - ./aggrega-mcp.md:相同的功能以
publish-artifact工具的形式提供,助手可以调用它。 在允许之前,请先阅读该页面中关于允许它的说明。