Run 对象

Run 是 Huoban 的一次锁版印刷：它锁定某次计划使用的 Flow、动态输入、Profile、Policy 和实现 binding，并承载工具观察到的状态。Run 可以表示 explain、dryRun 或 execute 计划；当前仓库不提供 execute runtime。设计背景见 Run 模型，Preflight 状态见 Preflight。

Spec 字段

字段	要求	Schema 语义
`spec.flowRef`	必填	local object reference。
`spec.profileRefs`	可选	local object reference 数组。
`spec.policyRefs`	可选	local object reference 数组。
`spec.mode`	可选	`explain`、`dryRun` 或 `execute`；schema 不声明默认值，reference CLI 与 Preflight 将省略值按 `execute` 处理。
`spec.bindings`	可选	role 到 implementation binding 的映射。
`spec.inputBindings`	可选	Flow input name 到具体调用 binding 的映射。
`spec.snapshot`	可选	锁定信息对象；一旦存在，五个 hash 字段全部必填。
`spec.snapshot.flowSpecHash`	snapshot 存在时必填	Flow `spec` 的 hash 字符串。
`spec.snapshot.profileRefHash`	snapshot 存在时必填	有效 Profile 引用列表的 hash 字符串。
`spec.snapshot.policyRefHash`	snapshot 存在时必填	有效 Policy 引用列表的 hash 字符串。
`spec.snapshot.bindingHash`	snapshot 存在时必填	bindings 的 hash 字符串。
`spec.snapshot.inputBindingHash`	snapshot 存在时必填	inputBindings 的 hash 字符串。

这五个名称是当前 schema 的完整 snapshot 字段集，并统一使用 sha256:<64 位小写十六进制>。 Huoban canonical JSON v1 的算法固定为：递归按 UTF-16 code unit 升序排列对象 key，保持数组顺序，使用 ECMAScript JSON.stringify 语义序列化，再对 UTF-8 bytes 做 SHA-256。不同实现必须使用相同算法；不能直接哈希 YAML、未排序 JSON 或平台相关文本。

Input binding

每个 spec.inputBindings.<name> 必须匹配 Flow 的同名入口与类型：

type	必填字段	说明
`file`	`contentRef.type: file`、`contentRef.path`、`hash`	`sourcePath` 可选；hash 针对原始文件 bytes。
`text`	`value` string	inline 值进入 `inputBindingHash`。
`object`	`value` object	不接受数组或标量。
`artifactRef`	`artifactRef`、`hash`	ref 可带 generation；hash 锁定 Artifact 内容身份。

Run schema 只验证 binding 形状。print 负责验证 Flow 契约并物化绑定；Preflight 负责验证 required、未知、类型、内容引用与 hash。

Implementation binding

每个 spec.bindings.<role> 的主目标必须且只能选择一种：

reviewer:
  skillRef: design-review

或：

reviewer:
  adapterRef: grill-me-skill-md
  fallback:
    skillRef: design-review

字段	要求	说明
`skillRef`	与 `adapterRef` 二选一	Skill 名称字符串。
`adapterRef`	与 `skillRef` 二选一	Adapter 名称字符串。
`fallback`	可选	implementation target。
`fallback.skillRef`	与 fallback 的 `adapterRef` 二选一	fallback Skill 名称。
`fallback.adapterRef`	与 fallback 的 `skillRef` 二选一	fallback Adapter 名称。

主目标或 fallback 同时写两类 ref 会因 oneOf 失败。fallback 只存在于 Run binding；Adapter schema 没有 spec.fallback。

Status 字段

Run 在通用 status 之外增加：

字段	要求	说明
`status.currentStage`	可选	stage id 字符串。
`status.observedSideEffects`	可选	实际观察到的副作用对象数组；每项必须有枚举内的 `type`，可有其他字段。
`status.artifacts`	可选	Artifact 引用数组。
`status.preflight`	可选	Preflight 摘要；存在时 `scope`、`snapshotHash`、`checkedAt`、`reportRef` 必填。
`status.lifecycleInvocations`	可选	Handler 调用状态数组，见 Lifecycle Handler。

status.phase、status.observedGeneration 和 status.conditions 来自通用状态。除 lifecycle invocation 的 phase 外，schema 不为 Run phase 定义枚举。

合法示例

apiVersion: huoban.dev/v1alpha1
kind: Run
metadata:
  name: idea-to-spec-review-001
spec:
  flowRef:
    name: idea-to-spec-review
    generation: 2
  profileRefs:
    - name: huoban-open-source-project
      generation: 1
  policyRefs:
    - name: safe-defaults
  mode: dryRun
  bindings:
    primary-review:
      adapterRef: grill-me-skill-md
    spec-writer:
      skillRef: spec-outline-writer
  inputBindings:
    idea:
      type: file
      sourcePath: examples/inputs/product-idea.md
      contentRef:
        type: file
        path: examples/inputs/product-idea.md
      hash: sha256:2fa7baf3030dddd710b3818c589ff8378d0d0b7f44af28e60ab1e254d159ac60
  snapshot:
    flowSpecHash: sha256:54d40ab4b480360e5c80a1e00713cb30d6daaeeac37b8edd79874ff40178d2ff
    profileRefHash: sha256:d9ec168320ac8ea60d3aa5f049ce8a58bc0c625f1937d560c7e4b0d801f3d5d9
    policyRefHash: sha256:745db2bbc095810039b9b13ef544ce49bd28e1f7474757cf256e27906fb65006
    bindingHash: sha256:9d47cbf573e28dad7fd0080bdc96894a27ba85377421e4e34f3455cc58a5f01b
    inputBindingHash: sha256:fe4ec97370aa81ce5d1808282aef9e48f40928897c1e2feac954cacb6ef30e28

对应 source example：examples/runs/idea-to-spec-review-run.yaml。

当前 CLI 行为

生成 dry-run

npm exec -- huoban print --dry-run examples/flows/idea-to-spec-review.yaml \
  --out runs/plan.yaml \
  --input idea=file:examples/inputs/product-idea.md \
  --bind primary-review=adapter:grill-me-skill-md \
  --fallback primary-review=skill:design-review

--input 可重复，格式为 name=file:path|text:value|object:json|artifactRef:name[@generation]#sha256:digest。当前 parser 还支持可重复的 --profile <name> 与 --policy <name>。--fallback 只有在同一 role 已有 --bind 时才合法。生成器将 Flow spec、Profile refs、Policy refs、implementation bindings 和 input bindings 分别锁定到五个 snapshot 字段。文件 binding 自身使用 raw-byte SHA-256。输出 phase 为 Planned，conditions 包含 RunPlanned=True 和 FlowSnapshotCreated=True。此命令只生成计划。

Preflight

Preflight 会解析 flowRef 及 generation，将 Flow 默认 Profile/Policy refs 与 Run refs 按名称合并，并检查 role binding、capability、fallback 和可达依赖。fallback 是锁入 Run 的执行候选：它与主 binding 使用相同 requiredness，必须能力匹配并通过同一次 Preflight；reference CLI 不提供自动切换 runtime。 Preflight 的 snapshotHash 与五个 spec.snapshot.* 字段不同：它直接哈希完整 Run.spec。详见 Preflight。 mode: execute 只有在 Run scope 的 required resolution/readiness 都为 True 时才通过当前 Preflight gate，并产生 PreflightReady=True。stage scope 的 StagePreflightReady=True 不能授权整次 Run。

验证边界

validate 检查 binding 的严格二选一，但不解析目标对象或 capability。
Preflight 解析当前实现收集的 refs 与 bindings，但不执行 Flow、Policy 或 Checkpoint。
Run-scope 与 stage-scope Preflight 都会按当前解析结果重算并比对五个 spec.snapshot.* 字段；缺失或不匹配会产生 required False。
Preflight 检查 input binding 的声明、必填性、类型和本地可取得内容；URL 等不可取得 Artifact 内容保持 Unknown。
报告的 snapshotHash 另行哈希完整 Run.spec，用于把证据绑定到本次 Run 声明。
Profile/Policy refs 在当前 Preflight 中按名称覆盖 Flow 默认引用；这不是通用 Profile merge DSL。
status.artifacts 只检查引用形状；当前 Preflight 不验证它们与 stage 的归属关系。
PreflightReady=True 不是 Policy 或 Trust 授权。

相邻概念边界

容易混淆	精确边界
Run / Flow	Flow 是可复用版式；Run 锁定一次具体计划。
binding / Requirement	binding 选择 Skill/Adapter；Requirement 检查该实现的环境依赖。
input binding / Requirement	input binding 锁定本次调用数据；Requirement 声明目标环境依赖。
snapshot / Preflight report	snapshot 锁定计划输入；report 记录某环境、某时刻的检查证据。
Run artifact refs / Artifact	Run 只引用；Artifact 保存类型、内容引用和证据。
Run condition / Checkpoint	condition 记录状态；Checkpoint 是具体决策对象。

常见错误

使用不存在的 profileSpecHash、skillBindingHash 或其他 snapshot 字段，或漏掉 inputBindingHash。
在同一 binding 同时写 skillRef 与 adapterRef。
把 fallback 写进 Adapter，而不是 Run binding。
写入 Flow 未声明的 input binding，或只记录文件 path 而不记录 hash。
认为 dry-run 已经执行 stage 或做过 Preflight。
用 stage scope 结果满足 execute 的 Run scope 门槛。
把 status.artifacts 当作产物正文容器。

开始使用

核心概念

规范参考

迁移指南

示例

标准与治理

开源项目

Spec 字段

Input binding

Implementation binding

Status 字段

合法示例

当前 CLI 行为

生成 dry-run

Preflight

验证边界

相邻概念边界

常见错误

​Spec 字段

​Input binding

​Implementation binding

​Status 字段

​合法示例

​当前 CLI 行为

​生成 dry-run

​Preflight

​验证边界

​相邻概念边界

​常见错误

Spec 字段

Input binding

Implementation binding

Status 字段

合法示例

当前 CLI 行为

生成 dry-run

Preflight

验证边界

相邻概念边界

常见错误