Skip to main content
Run 是 Huoban 的锁版印刷。Flow 描述可复用版式；Run 把一次工作实际采用的 Flow、动态输入、Profile、Policy、mode 与实现 bindings 固定下来，并为 Preflight、stage 状态、生命周期投递和 Artifact 提供统一索引。 Run 不是聊天记录，也不是完整执行日志。它保存足以解释“这一次准备如何工作、使用了什么、当前观察到什么”的声明和状态。 本页解释设计边界；字段级定义见 Run 规范。

锁定一次组合

spec 固定 Flow、调用输入、Profile、Policy、mode、bindings 和当前 snapshot 字段。

执行前有证据

status.preflight 把 Run scope 的就绪结论绑定到同一份 Run.spec。

状态与声明分离

作者写 spec；工具或 runtime 写 status、conditions、Artifact 引用和 lifecycle invocation。

不冻结整个世界

当前 snapshot 只覆盖 schema 明示的内容；它不是所有被引用对象的完整归档包。

​
Run 的职责

Run 必须回答：
  • 采用哪个 Flow generation？
  • 本次使用哪些 Profile 与 Policy 引用？
  • 当前是 explain、dryRun 还是 execute？
  • Flow 的每个入口槽在这次调用中绑定了什么？
  • 每个 stage 和 lifecycle role 绑定到哪个 Skill 或 Adapter？
  • 这些声明对应哪些 snapshot hash？
  • Run scope 的 Preflight 是否仍有效？
  • 当前 stage、条件、副作用、产物与 lifecycle invocation 是什么？
Run 不负责定义可复用流程、权限规则、具体校对请求或产物正文。这些分别属于 Flow、Policy、Checkpoint 和 Artifact。

​
三种 mode

schema 允许省略 mode，但 reference CLI 与 Preflight 按 execute 解释省略值。这样缺失字段不会形成 readiness 门禁旁路；需要解释或演练时必须显式写出 explain 或 dryRun。 dry-run 不等于 Preflight。dry-run 形成“准备执行什么”的 Run；Preflight 记录“当前环境的机械就绪检查结果”；Policy、Trust 与 Checkpoint 再回答“是否允许执行”。

​
Input binding：从入口槽到本次调用

Flow 先声明入口契约：
Run 再锁定这一次的值：
支持的 binding 如下： 协议不规定 .huoban/runs/... 之类的磁盘布局。实现可以把源文件复制到 Run 自己的内容寻址存储，但必须保存稳定内容引用与 hash。不要把 secret 放进 inline text/object；密钥属于 credential Requirement。

​
Implementation binding：从 role 到实现

Flow 只声明 capability 与 role：
Run 把 role 绑定到一个具体实现：
每个 binding 必须在 skillRef 与 adapterRef 中二选一。provider 必须声明 Flow 所需 capability；Preflight 会检查 role、对象引用与 capability 是否匹配。

​
fallback

fallback 属于本次 Run binding，而不属于 Adapter：
fallback 不是运行时任意热切换。它必须显式锁定、提供同一 capability，并以与主 binding 相同的 requiredness 通过同一 Run 的 Preflight。当前 reference implementation 记录和检查 fallback 声明，但不提供自动切换 runtime。

​
Snapshot 的准确边界

snapshot 整体可选；一旦存在，v1alpha1 要求以下五个 hash 全部出现： profileRefHash 与 policyRefHash 不等于被引用对象完整内容的 hash。若实现需要内容级不可变性，应使用 generation、外部内容寻址存储或未来标准字段；不能把引用列表 hash 描述成完整 Profile / Policy 快照。 Preflight Report 的 snapshotHash 又是另一层：它哈希完整 Run.spec，用来防止把旧报告套到已修改的 Run 上。它同样不归档 workspace 中所有对象内容。

​
Preflight gate

Run scope Preflight 的摘要进入 status：
execute 前必须同时满足：
  1. scope 是 run，不是单个 stage。
  2. report 的 snapshotHash 对应当前 Run.spec。
  3. 报告未超过 validUntil（如果存在）。
  4. PreflightReady=True。
这只记录机械就绪观察。Policy、Trust、Checkpoint 与实际执行权限仍需独立处理。详见 Preflight 模型。

​
Lifecycle invocation

Flow 声明 lifecycle handler，Run 用 bindings 锁定 provider；处理过程记录在 status.lifecycleInvocations：
eventId 标识一个逻辑事件，重试应复用它。attempts 与 phase 记录投递观察状态，但当前 schema 和 reference CLI 不提供 dispatcher，也不承诺 exactly once。详见 Lifecycle Handler。

​
Conditions、Checkpoint 与 Artifact

Run.status.conditions 是机器可读摘要，不替代专属对象： 不要把产物正文、审批评论或完整事件 payload 塞进 Run status。

​
结构示例

完整文件位于 source repository 的 examples/runs/idea-to-spec-review-run.yaml；生成路径和 Preflight 报告见 Preflight 与 Lifecycle 示例。

​
常见错误

  • 把 profileRefHash 写成 effective Profile 内容 hash。
  • 同一个 binding 同时写 skillRef 与 adapterRef。
  • 在 Run 启动后静默更换 provider 或 fallback。
  • 给 Run 增加 Flow 未声明的输入，或让 binding 类型与入口类型不一致。
  • 只保存文件 path 而不保存内容 hash，随后仍声称 Run 可重放。
  • 用 stage scope Preflight 结果授权整次 Run。
  • 把 PreflightReady=True 当作 Policy 已通过。
  • 在 dry-run 中伪造已执行的 lifecycle invocation 或 Artifact。
  • 把 Run 当成日志、队列或产物内容仓库。