示例：idea-to-spec-review

idea-to-spec-review 把“先审查想法，再起草规格大纲”拆成可验证对象：

sharpen-idea 需要 huoban.dev/designReview。
每次调用把一个 Markdown 文件绑定到 Flow 的 idea 入口。
人类在方向 Checkpoint 做出 approve、requestChanges 或 reject 决策。
draft-spec-outline 需要 huoban.dev/specification，并读取前一 stage 的结构化输出。
stage.succeeded 可以声明一个 best-effort 上报 handler。

当前仓库验证、解释、打印和预检这些对象，但不执行 stage、解决 Checkpoint 或派发 lifecycle event。文中的 examples/... 是 Huoban source repo 内的路径，不是文档站链接。

对象关系

Flow/idea-to-spec-review@2
  input idea:file -> Run input binding -> examples/inputs/product-idea.md + hash
  profileRefs -> Profile/huoban-open-source-project
  policyRefs  -> Policy/safe-defaults
  stage role primary-review -> Run binding -> Adapter/grill-me-skill-md
  stage role spec-writer    -> Run binding -> Skill/spec-outline-writer
  handler role stage-reporter -> Run binding -> Adapter/stage-reporting-mcp

Run/idea-to-spec-review-001
  artifacts -> Artifact/review-notes
  lifecycleInvocations -> report-stage-success: Pending

Checkpoint/idea-to-spec-review-001-direction
  runRef -> Run/idea-to-spec-review-001
  artifactRefs -> Artifact/review-notes

Flow 声明 capability 与 role；具体 Skill、Adapter 和 fallback 只能锁定在 Run.spec.bindings。

完整 Flow

下面逐字取自 examples/flows/idea-to-spec-review.yaml：

apiVersion: huoban.dev/v1alpha1
kind: Flow
metadata:
  name: idea-to-spec-review
  generation: 2
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
    - 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
  checkpoints:
    - after: sharpen-idea
      type: humanApproval
      required: true
      reason: ConfirmDirectionBeforeSpec
  lifecycle:
    - id: report-stage-success
      on: stage.succeeded
      delivery: bestEffort
      requires:
        capability: huoban.dev/stageReporting
        role: stage-reporter
      timeoutSeconds: 10
      retry:
        maxAttempts: 3

这里的 lifecycle block 是声明，不是任意 hook。on 必须来自 v1alpha1 有限事件枚举；handler 通过 role 在 Run 中绑定实现。

打印并预检 dry-run Run

在 source repo 根目录运行：

npm run validate
npm run explain
npm run print:dry-run
npm run preflight

print:dry-run 的当前 binding 参数是：

node ./bin/huoban.js print --dry-run examples/flows/idea-to-spec-review.yaml \
  --out examples/generated/idea-to-spec-review-dry-run.yaml \
  --input idea=file:examples/inputs/product-idea.md \
  --bind primary-review=adapter:grill-me-skill-md \
  --bind spec-writer=skill:spec-outline-writer \
  --bind stage-reporter=adapter:stage-reporting-mcp

生成 Run 的 spec 逐字取自 examples/generated/idea-to-spec-review-dry-run.yaml：

spec:
  flowRef:
    name: idea-to-spec-review
    generation: 2
  profileRefs:
    - name: huoban-open-source-project
  policyRefs:
    - name: safe-defaults
  mode: dryRun
  bindings:
    primary-review:
      adapterRef: grill-me-skill-md
    spec-writer:
      skillRef: spec-outline-writer
    stage-reporter:
      adapterRef: stage-reporting-mcp
  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:7559a8d488bbdb57906ee5116931bc487bbae1841ab059037d9723c2d848bf77
    policyRefHash: sha256:745db2bbc095810039b9b13ef544ce49bd28e1f7474757cf256e27906fb65006
    bindingHash: sha256:9d47cbf573e28dad7fd0080bdc96894a27ba85377421e4e34f3455cc58a5f01b
    inputBindingHash: sha256:fe4ec97370aa81ce5d1808282aef9e48f40928897c1e2feac954cacb6ef30e28

这些值锁定 Flow spec、Profile refs、Policy refs、implementation bindings 和 input bindings。文件 binding 自身的 hash 针对原始 bytes；Preflight report 的 snapshotHash 另行哈希整个 Run.spec。

完整 authored Run

examples/runs/idea-to-spec-review-run.yaml 是手写的协议状态示例，不是当前 CLI runtime 的执行输出。它使用与当前对象组合一致的五个 hash，展示 Checkpoint 等待和 lifecycle invocation 记录：

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
    stage-reporter:
      adapterRef: stage-reporting-mcp
  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
status:
  phase: WaitingForCheckpoint
  currentStage: sharpen-idea
  conditions:
    - type: RunPlanned
      status: "True"
      reason: DryRunGenerated
    - type: CheckpointRequired
      status: "True"
      reason: ConfirmDirectionBeforeSpec
  lifecycleInvocations:
    - handlerId: report-stage-success
      eventId: idea-to-spec-review-001-sharpen-idea-succeeded
      eventType: stage.succeeded
      stage: sharpen-idea
      phase: Pending
      attempts: 0
  artifacts:
    - name: review-notes

phase: Pending 只展示 invocation status 的协议形状。当前仓库没有 dispatcher 去把它自动变成 Running、Succeeded 或 Failed。

完整 Checkpoint

下面逐字取自 examples/checkpoints/idea-to-spec-review-direction.yaml：

apiVersion: huoban.dev/v1alpha1
kind: Checkpoint
metadata:
  name: idea-to-spec-review-001-direction
spec:
  runRef:
    name: idea-to-spec-review-001
  stage: sharpen-idea
  reason: ConfirmDirectionBeforeSpec
  requiredActions:
    - approve
    - requestChanges
    - reject
  artifactRefs:
    - name: review-notes
status:
  phase: Pending
  conditions:
    - type: CheckpointRequired
      status: "True"
      reason: HumanDesignDecisionRequired

Checkpoint 是决策边界，不属于 Preflight。当前 CLI 也不会在 approve 后自动更新 Run；执行实现必须明确记录自己的状态迁移。

完整 Artifact

下面逐字取自 examples/artifacts/review-notes.yaml：

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

Flow output 是预期产物声明；Artifact 是某次 Run 留下的内容引用、hash 和 review 状态。

explain 结果

npm run explain 中对应部分是：

- compose Flow/idea-to-spec-review
  ink with Profile/huoban-open-source-project
  apply Policy/safe-defaults
  set stage sharpen-idea: huoban.dev/designReview
  set stage draft-spec-outline: huoban.dev/specification
  proof after sharpen-idea: ConfirmDirectionBeforeSpec

对象映射如下：

过程	对象	当前 CLI 是否执行
排列 capability stages	`Flow`	只验证和解释。
声明并锁定调用稿件	`Flow.spec.inputs` + `Run.spec.inputBindings`	`print --dry-run` 会验证并生成；Preflight 会复核。
注入上下文	`Profile`	只记录引用和 Requirement；不构造 runtime prompt。
锁定实现	`Run.spec.bindings`	`print --dry-run` 会生成。
检查依赖	Preflight evidence	CLI 会生成 Run status 与 Artifact。
判断副作用	`Policy`、`Trust`	CLI 不授权或强制执行。
停下决策	`Checkpoint`	schema 可表达；当前无处理 runtime。
运行 stage/handler	runtime	当前仓库未实现。

修改规则

目标	应修改的位置
改工作步骤	`Flow.spec.stages`。
改入口契约	`Flow.spec.inputs`；不要直接给 Run 添加任意字段。
为本次调用换稿件	重新生成 `Run.spec.inputBindings` 与 snapshot，不要热改旧 Run。
更换实现	`Run.spec.bindings`。
添加 fallback	对应 Run binding 的 `fallback`，不是 Flow。
添加上下文依赖	`Profile.spec.requirements`。
添加执行环境依赖	`Skill`、`Profile` 或 `Adapter` 的 `requirements`。
添加审批边界	`Policy` 和 `Checkpoint`。
添加观察、上报或清理	`Flow.spec.lifecycle` 的有限事件 handler。
改变业务状态或权限	stage、Checkpoint 或 Policy；不要藏进 lifecycle handler。

开始使用

核心概念

规范参考

迁移指南

示例

标准与治理

开源项目

示例：idea-to-spec-review

对象关系

完整 Flow

打印并预检 dry-run Run

完整 authored Run

完整 Checkpoint

完整 Artifact

explain 结果

修改规则

相关页面

​对象关系

​完整 Flow

​打印并预检 dry-run Run

​完整 authored Run

​完整 Checkpoint

​完整 Artifact

​explain 结果

​修改规则

​相关页面

对象关系

完整 Flow

打印并预检 dry-run Run

完整 authored Run

完整 Checkpoint

完整 Artifact

explain 结果

修改规则

相关页面