Flow 模型

Flow 是 Huoban 的版式：定义一类 AI 工作应该如何被排版。它不执行任务，不保存结果，也不要求绑定某个具体 agent 工具。它描述的是工作结构：调用者要提供哪些输入，需要哪些 capability，分成哪些 stage，输入和输出如何传递，哪里需要 checkpoint，默认使用哪些 Profile 和 Policy，以及哪些有限生命周期事件需要上报或观察。本页属于核心概念，解释 Flow 的设计边界和编排模型；字段级定义、必填项和 schema 约束见 Flow 规范。

版式不是执行

Flow 描述这类 AI 工作如何排版；Run 才记录一次具体执行。

Capability-first

stage 优先声明需要什么能力，而不是先绑定某个具体 skill。

入口先声明

spec.inputs 定义调用契约；具体值只进入一次 Run 的 inputBindings。

Stage 是能力边界

stage 描述 capability、输入、输出和校对边界，不是 shell step。

校对点显式

checkpoints 让高判断力或高风险位置在版式中可见。

生命周期显式

lifecycle 用有限事件声明上报、观察与清理，不把任意 hook 命令塞进版式。

Flow 不是 Run

Flow 和 Run 的边界必须前置理解。

对象	第一性职责	不承担
`Flow`	可复用版式，声明工作结构、默认 `Profile` / `Policy` 和 checkpoint。	不保存执行结果、错误、耗时、实际副作用和产物引用。
`Run`	一次印刷，锁定某个 Flow 的具体执行视图。	不重新定义这类工作的通用结构。
`Checkpoint`	一次执行中发生的校对请求和决策边界。	不替代 Flow 的版式声明。
`Artifact`	一次执行产生的具体产物、内容引用、hash 和 review。	不替代 Flow 的预期输出声明。

一句话：Flow 定义一类 AI 工作的可复用结构；Run 记录一次具体执行。

Flow 的职责

Flow 应回答的问题是结构问题：

这类工作需要哪些 capability？
每次调用必须或可以提供哪些动态输入？
这些 capability 如何分成 stage？
每个 stage 的输入来自哪里？
每个 stage 预期输出什么 artifact 类型？
哪些位置需要 checkpoint？
默认使用哪些 Profile 和 Policy？
哪些有限生命周期事件需要 handler，以及它们是 required 还是 bestEffort？

当前 Flow schema 不定义 retry、rollback、pause、abort 这类控制流语义。实现可以在 status 中报告状态或等待 checkpoint，但重试、回退和中止策略不属于 v1alpha1 Flow 的承诺。

Capability-first

Flow 的主路径是 capability-first。stage 应优先声明“需要什么能力”，而不是“必须调用哪个 skill”。

apiVersion: huoban.dev/v1alpha1
kind: Flow
metadata:
  name: idea-to-spec-review
spec:
  inputs:
    - name: idea
      type: file
      required: true
      description: Markdown source containing the idea to review.
  profileRefs:
    - name: huoban-open-source-project
  policyRefs:
    - name: safe-defaults
  stages:
    - id: sharpen-idea
      requires:
        capability: huoban.dev/designReview
        role: primary-review
      inputs:
        - name: idea
          from:
            flowInput: idea
      outputs:
        - name: review-notes
          artifactType: decision-notes
  checkpoints:
    - after: sharpen-idea
      type: humanApproval
      required: true
      reason: ConfirmDirectionBeforeSpec

这个 Flow 没有说必须使用哪个具体 agent、skill 或 MCP server。它只声明 sharpen-idea 这个 stage 需要 huoban.dev/designReview 能力。一次具体执行中，Run 再把 role 绑定到可用的 Skill 或 Adapter。

# Run spec fragment
flowRef:
  name: idea-to-spec-review
mode: dryRun
bindings:
  primary-review:
    adapterRef: grill-me-skill-md
inputBindings:
  idea:
    type: file
    contentRef:
      type: file
      path: examples/inputs/product-idea.md
    hash: sha256:...
snapshot:
  flowSpecHash: sha256:...
  profileRefHash: sha256:...
  policyRefHash: sha256:...
  bindingHash: sha256:...
  inputBindingHash: sha256:...

这样同一个 Flow 可以在不同工具、团队和执行环境中复用。

Shortcut 语法

v1alpha1 schema 允许 uses 作为兼容 shortcut：

# Stage fragment
id: review
uses: mattpocock/grill-me

但 uses 不是推荐主路径。没有 Registry、Adapter 或 Skill metadata 时，工具只能保留这个引用或标记为 unresolved，不能保证自动展开成 capability 与 Run binding。当前 Preflight 允许它用于 dry-run 和诊断；execute mode 必须改用 requires.capability 与锁定的 Run binding，否则产生 LegacyUseNotLocked。推荐主路径仍然是：

# Stage fragment
id: review
requires:
  capability: huoban.dev/designReview
  role: primary-review

这里的 requires 是 Flow 的能力需求：它包含 capability 与可选 role，用于选择实现。它不是 Skill、Profile、Adapter 上的 requirements[]；后者描述实现依赖的文件、程序、MCP 能力、凭据或上下文来源。详见 Requirement。

入口契约与内部数据流

Flow.spec.inputs 声明调用入口，不保存某次调用的值：

inputs:
  - name: document
    type: file
    required: true
  - name: instruction
    type: text
    required: false

v1alpha1 支持 file、text、object 和 artifactRef。具体调用值进入 Run.spec.inputBindings。这对结构解决两个不同问题：Flow 回答“这类工作接受什么”，Run 回答“这一次实际给了什么”。 stage 只能使用两种结构化来源：

inputs:
  - name: document
    from:
      flowInput: document
  - name: review-notes
    from:
      stageOutput:
        stage: sharpen-idea
        output: review-notes

flowInput 必须已在 Flow 入口声明；stageOutput 必须来自当前 stage 之前的已声明输出。Preflight 会拒绝未声明入口、不存在的输出和未来 stage 引用。任意字符串表达式不属于 v1alpha1。

动态输入不是 Requirement。输入说明这次处理什么；Requirement 说明目标环境需要具备什么。

Stage 是能力边界

Stage 是 Flow 中最小的能力编排单元。它不是 task step，也不是 shell step。它应该描述一段 AI 工作需要的 capability、输入、输出和校对边界。

# Stage fragment
id: draft-spec-outline
requires:
  capability: huoban.dev/specification
  role: spec-writer
inputs:
  - name: review-notes
    from:
      stageOutput:
        stage: sharpen-idea
        output: review-notes
outputs:
  - name: spec-outline
    artifactType: markdown

不要把 stage 写成：

# Not a Huoban Flow stage
run: npm test
shell: bash
command: claude -p "review this idea"

命令、CLI 参数、模型调用细节和工具私有字段应该进入 Adapter、导入层或实现私有扩展，不应污染 Flow 的核心对象。

Lifecycle Handler

Flow 可以在有限生命周期事件上声明观察性处理器：

lifecycle:
  - id: report-stage-success
    on: stage.succeeded
    delivery: bestEffort
    requires:
      capability: huoban.dev/stageReporting
      role: stage-reporter
    timeoutSeconds: 10
    retry:
      maxAttempts: 3

handler 和 stage 一样只声明 capability 与 role；具体 provider 由 Run.spec.bindings.stage-reporter 锁定。bestEffort 与 required 是对具备 dispatcher 的实现提出的 delivery 语义；当前 reference CLI 只把前者作为 optional、后者作为 required 参与 Preflight，并不实际投递。 Lifecycle Handler 不是任意 hook：

只能使用 v1alpha1 的有限事件枚举。
match 当前只按 stage id 过滤。
同一事件上的多个 handler 不保证顺序。
handler 不修改 stage 图、不作业务判断，也不会因自身 invocation 再产生 lifecycle event。
需要严格先后关系的工作必须建模为 stage。
run.succeeded、run.failed、run.cancelled 只允许 bestEffort；required 收尾使用 run.finalizing。

当前 reference implementation 支持 schema、Preflight、explain、事件信封示例和 invocation 状态形状，尚未提供实际 dispatcher。详见 Lifecycle Handler。

Checkpoint

Flow 可以声明哪里需要校对，但不保存校对结果。

# Flow spec fragment
checkpoints:
  - after: sharpen-idea
    type: humanApproval
    required: true
    reason: ConfirmDirectionBeforeSpec

边界是：

Flow.spec.checkpoints 声明校对点。
Checkpoint 对象承载一次具体校对请求和决策上下文。
Run.status.conditions 记录这次执行是否正在等待 checkpoint。
Artifact 保存供审查的材料、输出正文或决策记录内容；审批状态和继续/停止决策应进入 Checkpoint / Run 状态。

常见 checkpoint 触发原因包括高风险副作用、方向尚未确认、Profile 冲突、外部 Adapter 未被信任，或某个 stage 的输出需要人工判断。

Artifact

Flow 可以声明预期输出，不直接承载产物内容。

# Stage fragment
outputs:
  - name: review-notes
    artifactType: decision-notes
  - name: spec-outline
    artifactType: markdown

边界是：

位置	表达内容
`Flow.spec.stages[].outputs`	这个 stage 预期输出什么产物槽位和 artifact 类型。
`Run.status.artifacts`	这次执行实际产生了哪些 artifact 引用。
`Artifact`	产物类型、`contentRef`、`hash`、`review`、`runRef` 和 `stage`。

Flow 声明 stage 预期输出；Artifact 记录一次执行实际产生的产物引用和审查状态。

Profile 与 Policy

Flow 可以声明默认 Profile 和 Policy。

# Flow spec fragment
profileRefs:
  - name: huoban-open-source-project
policyRefs:
  - name: safe-defaults

这些是 Flow 的默认引用，不是一次执行的最终事实。Run 声明本次执行使用的 profileRefs / policyRefs。v1alpha1 snapshot 记录 flowSpecHash、profileRefHash、policyRefHash、bindingHash 和 inputBindingHash；ref hash 只覆盖引用列表，不等于被引用对象完整内容的快照。这对应活字印刷术里的关系：同一版式可以换墨，也可以按不同印坊规矩印刷。

Context engineering 与 loop engineering

用当前行业语言描述，Huoban 处理的是 context engineering、skill reuse 和 agent loop standardization 的交叉问题。但 Huoban 不把这些概念堆进一个大对象里：

行业概念	Huoban 对象拆分
context engineering	`Profile` 负责上下文结构化、分层和合并；执行快照由 `Run` 记录。
agent loop structure	`Flow` 描述多阶段 AI 工作结构：capability、stage、输入输出和 checkpoint。
loop observation	`Lifecycle Handler` 在有限事件上声明上报与观察，invocation 进入 Run status。
execution trace	`Run` 记录一次执行实际使用的 flow、profile、policy、binding、mode、snapshot 与状态索引。
judgment boundary	`Checkpoint` 让 agent loop 在高判断力或高风险位置停下来。
stage output	`Artifact` 留下 stage 输出、审查材料、hash 和复盘依据。

当前 v1alpha1 的 Flow schema 没有定义完整 loop DSL。Flow 是描述 agent loop 结构的基础对象，不是任意循环控制语言；Lifecycle Handler 也不是隐藏的控制流通道。

参考 Flow

idea-to-spec-review 是 Huoban 的首个参考 Flow。它验证的不是“Huoban 能跑任意工作流”，而是一个更基础的标准化路径：静态 Flow 可以声明动态文件入口，现有 AI 能力可以被标准化成 Skill / Adapter，带着 Profile 排成 Flow，通过 Checkpoint 暴露判断边界，并在 Run / Artifact 中留下可审查记录。从示例：idea-to-spec-review 开始阅读完整对象链路。

开始使用

核心概念

规范参考

迁移指南

示例

标准与治理

开源项目

版式不是执行

Capability-first

入口先声明

Stage 是能力边界

校对点显式

生命周期显式

Flow 不是 Run

Flow 的职责

Capability-first

Shortcut 语法

入口契约与内部数据流

Stage 是能力边界

Lifecycle Handler

Checkpoint

Artifact

Profile 与 Policy

Context engineering 与 loop engineering

参考 Flow

版式不是执行

Capability-first

入口先声明

Stage 是能力边界

校对点显式

生命周期显式

​Flow 不是 Run

​Flow 的职责

​Capability-first

​Shortcut 语法

​入口契约与内部数据流

​Stage 是能力边界

​Lifecycle Handler

​Checkpoint

​Artifact

​Profile 与 Policy

​Context engineering 与 loop engineering

​参考 Flow

Flow 不是 Run

Flow 的职责

Capability-first

Shortcut 语法

入口契约与内部数据流

Stage 是能力边界

Lifecycle Handler

Checkpoint

Artifact

Profile 与 Policy

Context engineering 与 loop engineering

参考 Flow