Artifact 模型

Artifact 是 Huoban 的印张：把 AI 工作产物从聊天输出、临时文件或工具结果，变成可引用、可校对、可复盘的标准产物。它不是文件系统，也不是日志仓库。Artifact 记录一次 AI 工作产生了什么；在 Run 产物场景中，推荐记录它来自哪个 Run / stage、内容在哪里、摘要是什么、hash 是什么、当前审查状态是什么。本页属于核心概念，解释 Artifact 的设计边界和使用模型；字段级定义、必填项和 schema 约束见 Artifact 规范。

记录实际产物

Artifact 记录实际产生的文档、diff、报告、决策记录、测试结果或导出结果。

连接 Run 与 stage

runRef 和 stage 说明产物来自哪一次执行、哪个阶段。

引用内容位置

contentRef 指向文件、URL、Git blob 或对象内容，不内联大段正文。

进入校对链路

review.status 给出轻量状态；完整判断仍由 Checkpoint 承载。

保存预检证据

huoban.dev/preflight-report 使用 object data 保存 Run scope 的结构化就绪检查。

Artifact 不是普通文件

Artifact 的第一性职责是把结果对象化，而不是存储所有内容。

对象	职责	不承担
`Flow`	声明某个 stage 预期产出哪些 artifact type。	不保存实际产物。
`Run`	记录一次执行实际产生了哪些 Artifact 引用。	不保存产物正文，不替代内容存储。
`Artifact`	保存产物类型、来源、内容引用、hash、摘要和 review 状态。	不执行任务，不决定流程是否继续，不保存完整审查历史。
`Checkpoint`	对一个或多个 Artifact 发起校对请求并记录决策边界。	不保存产物正文。
`Policy`	判断行为是否允许、拒绝或需要审批。	不记录行为产物。

一句话：Flow 是版式，Run 是一次锁版印刷，Artifact 是实际印出来的印张。

什么应该成为 Artifact

只有进入 Huoban 编排链路、需要被引用、审查、复盘或复用的产物，才应该成为 Artifact。

应成为 Artifact	不应默认成为 Artifact
设计评审记录	普通聊天回复
需求草案	临时 scratch 内容
代码 diff	未进入 Flow / Run 的本地文件
测试报告	工具 stdout 的每一行
生成的 Profile	agent 内部推理过程
迁移结果	没有复用、审查或追溯价值的中间文本
安全审查结论	一次性调试噪声
dry-run 输出	未命名、未引用的临时片段

如果所有输出都是 Artifact，Huoban 会退化成日志系统；如果没有 Artifact，Huoban 又无法沉淀可审查产物。

与 Flow outputs 的关系

Flow.spec.stages[].outputs 是预期产物声明，Artifact 是实际产物记录。

# Flow spec fragment
stages:
  - id: sharpen-idea
    outputs:
      - name: review-notes
        artifactType: decision-notes

边界是：

Flow 声明某个 stage 预计产出什么类型的产物。
Run 执行后在 status.artifacts 中索引实际产物。
Artifact 记录该产物的 type、runRef、stage、contentRef、hash 和 review。

不要把 Flow.outputs 写成产物本体，也不要让 Artifact 反过来定义流程预期。

与 Run 的关系

Run.status.artifacts 是一次执行里的产物索引，Artifact 是每个产物自己的标准对象。

# Run status fragment
artifacts:
  - name: review-notes

# Artifact spec fragment
runRef:
  name: idea-to-spec-review-001
stage: sharpen-idea
contentRef:
  type: file
  path: examples/artifacts/idea-review.md
hash: sha256:9ad055106d6f4411941a3bbeb26f8487dc9e68476df9d575fc9535121c775dbe

边界是：

Run 记录这次执行实际发生了什么。
Run.status.artifacts 引用这次执行产生的 Artifact。
Artifact.spec.runRef 可反向指回来源 Run。
Artifact.spec.stage 可说明来自哪个 stage。
Artifact.spec.contentRef 指向实际内容。
Artifact.spec.hash 用于完整性校验和复盘。

不要把完整产物内容塞进 Run.status。Run 是执行视图，不是内容仓库。

与 Checkpoint 的关系

Checkpoint 常见的审查对象是 Artifact，而不是抽象的“这次感觉怎么样”。当前 v1alpha1 中 artifactRefs 是可选字段，因此不是每个 Checkpoint 都必须引用 Artifact；但一旦需要审查具体产物，就应该通过 artifactRefs 建立对象引用。

# Checkpoint spec fragment
artifactRefs:
  - name: review-notes

边界是：

Artifact 保存被审查产物的元数据、引用和摘要。
Checkpoint.spec.artifactRefs 指向待审查产物。
Checkpoint 记录 approve / requestChanges / reject 等决策边界。
一个 Checkpoint 可以审查多个 Artifact。
一个 Artifact 也可能经历多个 Checkpoint。

Artifact.spec.review.status 可以保存产物当前审查状态，但不替代 Checkpoint 的决策记录。

review status

Artifact.spec.review.status 是产物当前审查状态的轻量标记，不是完整审批记录。

status	语义
`pending`	产物待审查。
`approved`	产物已通过某次校对。
`rejected`	产物被拒绝。
`changesRequested`	需要修改后再审。

它不保存审批人、审批理由全文、评论线程、规则命中详情或完整决策历史。需要这些信息时，应通过 Checkpoint、关联评审 Artifact、实现侧记录或未来扩展表达。

contentRef 与 hash

Artifact 是产物索引和元数据对象，不是内容仓库。当前 contentRef.type 支持：

contentRef type	语义
`file`	仓库或工作区中的文件路径。
`url`	外部 URL。
`gitBlob`	Git blob 引用。
`object`	内联结构化对象，内容必须放在 `data`。

建议：

小摘要放在 summary。
大内容放文件、URL、Git blob 或外部对象存储；object/data 只用于适合内联验证的结构化数据。
contentRef 指向内容位置。
hash 用于校验内容完整性。
不要把大段 Markdown、diff、日志或二进制内容内联进 Artifact。

type 命名

Artifact.spec.type 当前是开放字符串，不是 enum。文档只能给推荐命名约定，不能写成协议强制枚举。推荐类型包括：

type	适用产物
`markdown`	普通 Markdown 文档。
`diff`	代码或文档变更 diff。
`decision-notes`	决策记录、评审意见、方向判断。
`test-report`	测试、验证或质量报告。
`profile`	导出的 Profile 或上下文资产。
`policy-report`	Policy 审查结果。
`migration-result`	迁移结果。
`dry-run-plan`	dry-run 产生的执行计划或预演结果。
`huoban.dev/preflight-report`	Preflight 的标准结构化证据；该 type 具有额外 schema 约束。

命名原则：

描述产物形态或用途，不描述工具名。
使用 kebab-case。
不把临时文件名当 type。
同类产物尽量复用同一个 type，方便 Registry 和 Checkpoint 处理。

Preflight Report Artifact

Preflight Report 没有独立 kind。它是一个受约束的 Artifact：

apiVersion: huoban.dev/v1alpha1
kind: Artifact
metadata:
  name: idea-to-spec-review-dry-run-preflight-report
spec:
  type: huoban.dev/preflight-report
  runRef:
    name: idea-to-spec-review-dry-run
  contentRef:
    type: object
    data:
      scope:
        type: run
      snapshotHash: sha256:dc036d6f...
      checkedAt: 2026-07-15T00:00:00.000Z
      checks: []

这个 type 强制要求 runRef、contentRef.type: object 和符合 Preflight Report fragment 的 data。报告保存逐项 Resolution/Readiness 证据；Run.status.preflight.reportRef 指向它。报告不是授权凭证，也不应包含 secret、带凭据 URL、完整 prompt 或 MCP 响应。详见 Preflight 与 Preflight 规范。

与 Policy 的关系

Policy 管“能不能做”，Artifact 记录“做出了什么或准备做什么”。

场景	Policy	Artifact
写文件	判断是否允许写入。	记录 diff、patch 或变更报告。
发 PR	判断是否需要审批。	记录 PR 摘要、diff 或 release notes。
发布远端变更	判断是否禁止、允许或 requireApproval。	记录 dry-run plan、部署摘要或发布记录。
安全审查	判断风险边界。	记录审查材料或结论。

对高风险行为，推荐先生成 dry-run-plan、diff 或 policy-report Artifact，再进入 Checkpoint。

与 Registry 的关系

Registry 可以索引可复用对象，包括 Artifact，但 Artifact 不是包管理对象。边界是：

Registry 保存可发现性。
Artifact 保存产物元数据和内容引用。
普通一次性临时产物不需要注册。
跨项目复用的产物应有稳定 type、contentRef、hash 和 review 状态。

只有有复用、审查或归档价值的产物，才值得进入 Registry。

AI-native 结果层

AI-native 文档不只是让 AI 能读文档，而是让 AI 工作的输入、过程、结果和审查点都能被对象化。Artifact 承担结果对象化。

读者	看到什么
人类读者	产物摘要、review 状态和内容引用。
AI agent	`type`、`runRef`、`stage`、`contentRef`、`hash`、`review.status`。
机器验证	schema、hash 和对象引用链。
公司实践反馈	哪些产物类型稳定，哪些产物需要新 type 或新 review 规则。

Artifact 让 AI 工作的结果可以被描述、引用、校对、复用和迁移，而不是散落在聊天记录、临时文件和工具输出里。

结构示例

apiVersion: huoban.dev/v1alpha1
kind: Artifact
metadata:
  name: review-notes
spec:
  type: decision-notes
  runRef:
    name: idea-to-spec-review-001
  stage: sharpen-idea
  contentRef:
    type: file
    path: examples/artifacts/idea-review.md
  hash: sha256:9ad055106d6f4411941a3bbeb26f8487dc9e68476df9d575fc9535121c775dbe
  review:
    status: pending

这个示例来自 examples/artifacts/review-notes.yaml。它展示的是一次 Run 在 sharpen-idea stage 产生的决策记录产物：正文放在文件里，Artifact 保存类型、来源、内容引用、hash 和审查状态。

开始使用

核心概念

规范参考

迁移指南

示例

标准与治理

开源项目

Artifact 模型

记录实际产物

连接 Run 与 stage

引用内容位置

进入校对链路

保存预检证据

Artifact 不是普通文件

什么应该成为 Artifact

与 Flow outputs 的关系

与 Run 的关系

与 Checkpoint 的关系

review status

contentRef 与 hash

type 命名

Preflight Report Artifact

与 Policy 的关系

与 Registry 的关系

AI-native 结果层

结构示例

记录实际产物

连接 Run 与 stage

引用内容位置

进入校对链路

保存预检证据

​Artifact 不是普通文件

​什么应该成为 Artifact

​与 Flow outputs 的关系

​与 Run 的关系

​与 Checkpoint 的关系

​review status

​contentRef 与 hash

​type 命名

​Preflight Report Artifact

​与 Policy 的关系

​与 Registry 的关系

​AI-native 结果层

​结构示例

Artifact 不是普通文件

什么应该成为 Artifact

与 Flow outputs 的关系

与 Run 的关系

与 Checkpoint 的关系

review status

contentRef 与 hash

type 命名

Preflight Report Artifact

与 Policy 的关系

与 Registry 的关系

AI-native 结果层

结构示例