Flow 是 Huoban 的版式：它声明 stage 如何排列、每个 stage 需要什么 capability、何处校对，以及哪些 lifecycle 集成跟随有限事件。Flow 是声明，不是 executor。
设计背景见 Flow 模型，Lifecycle fragment 见 Lifecycle Handler。
顶层字段
Stage 字段
stage item 不允许表中之外的字段。schema 的
anyOf 允许同时写 requires 与 uses，但当前 Preflight 会把这种组合记录为 AmbiguousStageBinding 失败。
Checkpoint 声明字段
schema 不要求
after 或 before，也不禁止二者同时出现。当前 Preflight 不解析 checkpoint 位置；不要把解释器显示位置误认为关系验证。
合法示例
examples/flows/idea-to-spec-review.yaml。
当前 CLI 行为
Dry-run print
huoban print --dry-run 读取一个 Flow，拒绝重复 input name，并验证 required/unknown/type-mismatched --input，生成 mode: dryRun 的 Run。它复制 Flow profile/policy refs，加入命令行 refs、implementation bindings 与 input bindings，并生成 flowSpecHash、profileRefHash、policyRefHash、bindingHash、inputBindingHash。
dry-run 只生成计划；它不执行 stage，也不自动运行 Preflight。
Preflight
当前 Preflight 会：- 解析 Flow ref 及请求的 generation。
- 解析 Flow 与 Run 合并后的 Profile/Policy refs。
- 报告重复 stage id 和重复 lifecycle handler id。
- 报告重复 Flow input name、未声明
flowInput、不存在的stageOutput和不是前序 stage 的输出引用。 - 检查 required Run input binding、未知 binding 与 binding type。
- 对
requires按 role 查 Run binding，并检查 Skill/Adapter 是否提供 capability。 - 对
uses要求 workspace 中恰好有一个同名 Skill 或 Adapter；它只支持 dry-run 与诊断，execute mode 会产生LegacyUseNotLocked。 - 检查 Lifecycle Handler 的 stage selector、binding 和依赖。
requires.role 在 schema 中可选，但缺失 role 无法找到锁定 binding，当前 Preflight 会产生 BindingMissing。可执行的 capability-first Flow 应显式写 role。
验证边界
- schema 不要求 stage id 唯一；当前 Preflight 会检查重复。
- schema 封闭
from形状；当前 Preflight 进一步检查flowInput声明和stageOutput的存在性与先后关系。当前协议不做 output artifact type 到下游 stage input type 的推断。 - 当前 Preflight 不解析 checkpoint 的
before/after或 reason。 - Flow 的
status不保存运行进度；实际进度属于 Run。 - 当前仓库没有 Flow executor 或 Lifecycle dispatcher。
相邻概念边界
常见错误
- 在同一 stage 同时写
requires和uses，只因为 schema 可以通过。 - 省略
requires.role却期望 Run 自动按 stage id 绑定。 - 把外部文件或可执行程序写进 stage
requires；这些属于 Skill/Profile/Adapter 的 Requirement。 - 把调用文件写成 Requirement，或使用
user.prompt、stages.a.outputs.b等自由字符串来源。 - 让 stage 引用当前或未来 stage 的输出。
- 把 shell command、模型参数或 runner 配置写入 Flow。
- 声称 checkpoint 引用和 input/output 数据流已被当前 Preflight 验证。
- 认为 dry-run 已经执行 stage 或证明环境就绪。