Skip to main content
Artifact 是 Huoban 的印张：它记录产物或协议证据的类型、来源、内容位置、hash 和审查状态。Artifact 不执行审批，也不保存 Run 的 binding 快照。 设计背景见 Artifact 模型，Preflight 特殊类型见 Preflight。

​
字段

​
Content reference

contentRef 必须有 type，且只允许 type、path、url、data 四个字段。 基础 schema 允许某个 type 同时携带其他已声明字段。例如 gitBlob 可以有 path，但当前 v1alpha1 没有 revision 字段或 git blob 解析规则。

​
合法示例

对应 source example：examples/artifacts/review-notes.yaml。

​
Preflight Report 特殊类型

当 spec.type 等于 huoban.dev/preflight-report 时：
  • spec.runRef 必填。
  • spec.contentRef 必填。
  • contentRef.type 固定为 object。
  • contentRef.data 必须符合 Preflight Report fragment。
  • spec.hash 必填，并等于 canonical object data hash。
当前 Preflight CLI 生成该 Artifact，summary 是 required/optional check 数量，hash 是完整 report data 的稳定 SHA-256。字段与合法示例见 Preflight。

​
当前 CLI 行为

  • spec.hash 使用 sha256:<64 位小写十六进制>。file-backed Artifact 与 Preflight Report 必填；前者哈希原始文件 bytes，后者哈希 Huoban canonical JSON v1 的 object data。
  • validate 检查 contentRef 条件和 review enum；特殊 type 触发报告 schema；file-backed Artifact 同时校验本地文件存在和 bytes hash，Preflight Report 同时校验 canonical object data hash。
  • explain 输出 type、Run、stage、contentRef 与 review；对 Preflight Report 额外汇总 scope、checks、hash 与时间。
  • preflight 创建报告 Artifact，并在 Run status 中写入 reportRef。
  • 除 file-backed Artifact 外，当前 CLI 不读取 URL、gitBlob 或普通 object 内容，也不验证这些内容的 hash；它同样不解析 Artifact 与 Run/stage 的关系。

​
验证边界

  • spec.type 没有通用枚举。
  • contentRef.url 只检查字符串；不做网络请求。
  • gitBlob 没有条件必填字段，当前 CLI 也没有 git object resolver。
  • runRef 与 stage 对普通 Artifact 都是可选，且当前 Preflight 不做归属校验。
  • review.status 是产物审查状态，不等于 Checkpoint 决策或 Policy 授权。

​
相邻概念边界

​
常见错误

  • 给 file 漏写 path，给 url 漏写 url，或给 object 漏写 data。
  • 声称 gitBlob 已有 schema 强制的 revision/path 格式。
  • 把大段产物正文写入 Run status，而不是 Artifact 或外部 contentRef。
  • 把普通 Artifact 当作 Preflight Report，却没有使用精确 type huoban.dev/preflight-report。
  • 把 review.status: approved 当成 Checkpoint 已解决。
  • 认为当前 CLI 会验证 URL、gitBlob 或任意 object Artifact hash；当前只验证 file-backed Artifact 和 Preflight Report data hash。