示例：Preflight 与 Lifecycle

这个 example 展示三个嵌入式执行契约：

Requirement 声明 Skill、Profile 或 Adapter 的目标环境依赖。
Preflight 分别记录 dependency resolution 与 current-environment readiness。
Lifecycle Handler 用有限事件声明观察、上报和清理集成。

它们都不是新的顶层 kind。Huoban 仍然只有 10 个顶层 kind。

dry-run 不是 Preflight，Preflight 不是授权。只有 Run scope 的 PreflightReady=True 能满足 execute Run 的 readiness 前置条件；Policy、Trust、Checkpoint、sandbox 和平台权限仍须独立判断。

文中的 examples/... 是 Huoban source repo 内的路径，不是文档站链接。

public example 中的依赖

owner	Requirement	检查目标
`Profile/huoban-open-source-project`	`contextSource`	`examples/import/AGENTS.md` 可读。
`Adapter/grill-me-skill-md`	`localPath`	`examples/fixtures/grill-me/SKILL.md` 可读。
`Skill/spec-outline-writer`	`executable`	`node` 在 `PATH` 上可执行。
`Adapter/stage-reporting-mcp`	`mcpTool`	MCP endpoint 与 `report_stage` tool 已声明；offline readiness 为 `Unknown`。

这些 Requirement 分别嵌入 Profile、Adapter 和 Skill，而不是放进 Run 顶层。

完整 reporting Adapter

下面逐字取自 examples/adapters/stage-reporting-mcp.yaml：

apiVersion: huoban.dev/v1alpha1
kind: Adapter
metadata:
  name: stage-reporting-mcp
spec:
  source:
    type: mcpTool
    url: http://127.0.0.1:8787/mcp
    tool: report_stage
  capabilities:
    - huoban.dev/stageReporting
  requirements:
    - id: reporting-tool
      type: mcpTool
      origin: declared
      freshness:
        maxAgeSeconds: 60
      target:
        serverUrl: http://127.0.0.1:8787/mcp
        name: report_stage
  mapping:
    inputs:
      event: lifecycle.event
      run: lifecycle.runRef
      stage: lifecycle.stage
      artifacts: lifecycle.artifactRefs
  sideEffects:
    declared:
      - networkAccess
      - sendMessage
  trustRef:
    name: local-stage-reporting

freshness.maxAgeSeconds 只在动态 readiness 得到非-Unknown 结果时产生 validUntil。offline MCP check 不会伪造新鲜度。

完整 reporting Trust

下面逐字取自 examples/trust/local-stage-reporting.yaml：

apiVersion: huoban.dev/v1alpha1
kind: Trust
metadata:
  name: local-stage-reporting
spec:
  subjectRef:
    kind: Adapter
    name: stage-reporting-mcp
  source:
    type: http
    url: http://127.0.0.1:8787/mcp
  level: unknown
  sandbox:
    required: true
    network: restricted
  policyRefs:
    - name: safe-defaults

这个 Trust 明确保留 level: unknown。Preflight 即使发现 endpoint，也不会把它提升为 reviewed 或 trusted。

完整 Flow

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

apiVersion: huoban.dev/v1alpha1
kind: Flow
metadata:
  name: idea-to-spec-review
  generation: 2
spec:
  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: user.prompt
      outputs:
        - name: review-notes
          artifactType: decision-notes
    - id: draft-spec-outline
      requires:
        capability: huoban.dev/specification
        role: spec-writer
      inputs:
        - name: review-notes
          from: stages.sharpen-idea.outputs.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

Handler 需要 stage-reporter role。具体实现必须在 Run binding 中锁定，不能写进 Flow：

bindings:
  stage-reporter:
    adapterRef: stage-reporting-mcp

复现 dry-run 与默认离线 Preflight

最短命令：

npm run print:dry-run
npm run preflight

以下命令把输出写到 tmp/，不会覆盖 committed examples。第二条命令没有传 --offline 或 --live，因此使用默认 offline：

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

node ./bin/huoban.js preflight tmp/idea-to-spec-review-dry-run.yaml \
  --workspace "examples/flows/*.yaml" \
  --workspace "examples/skills/*.yaml" \
  --workspace "examples/adapters/*.yaml" \
  --workspace "examples/profiles/*.yaml" \
  --workspace "examples/policies/*.yaml" \
  --workspace "examples/trust/*.yaml" \
  --out tmp/idea-to-spec-review-preflighted.yaml \
  --report tmp/idea-to-spec-review-preflight-report.yaml \
  --at 2026-07-15T00:00:00.000Z

Preflight 输出两个协议对象：

更新后的 Run，包含 conditions 与 status.preflight summary。
Artifact，包含完整、逐项的 Preflight report。

完整 preflighted Run

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

apiVersion: huoban.dev/v1alpha1
kind: Run
metadata:
  name: idea-to-spec-review-dry-run
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
  snapshot:
    flowSpecHash: sha256:b7a80c75e7a8f3f0e043d78623e84a0bd70def9f50134657751bf5e27a5fece2
    profileRefHash: sha256:7559a8d488bbdb57906ee5116931bc487bbae1841ab059037d9723c2d848bf77
    policyRefHash: sha256:745db2bbc095810039b9b13ef544ce49bd28e1f7474757cf256e27906fb65006
    bindingHash: sha256:9d47cbf573e28dad7fd0080bdc96894a27ba85377421e4e34f3455cc58a5f01b
status:
  phase: Planned
  conditions:
    - type: RunPlanned
      status: "True"
      reason: DryRunGenerated
      message: Dry-run plan generated without executing agent work.
    - type: FlowSnapshotCreated
      status: "True"
      reason: FlowSpecHashed
      message: Flow/idea-to-spec-review spec was hashed into the Run snapshot.
    - type: PreflightResolved
      status: "True"
      reason: DependenciesResolved
      message: Static references, generations, capabilities, and bindings were checked.
      lastTransitionTime: 2026-07-15T00:00:00.000Z
    - type: PreflightReady
      status: "True"
      reason: DependenciesReady
      message: Current-environment availability was checked for all required dependencies.
      lastTransitionTime: 2026-07-15T00:00:00.000Z
    - type: OptionalDependencyUnavailable
      status: "True"
      reason: OptionalCheckNotReady
      message: At least one optional dependency, including a best-effort lifecycle handler, is unavailable or unknown.
      lastTransitionTime: 2026-07-15T00:00:00.000Z
  preflight:
    scope:
      type: run
    snapshotHash: sha256:727425f3b2752558c1857b555989abf5b1e56a5c1a34e85cc831313ff0f25669
    checkedAt: 2026-07-15T00:00:00.000Z
    reportRef:
      kind: Artifact
      name: idea-to-spec-review-dry-run-preflight-report

PreflightReady=True 与 OptionalDependencyUnavailable=True 可以同时成立：best-effort handler 的 checks 是 optional，不阻塞 required gate。

resolution 与 readiness

Preflight 对每项 dependency 分开记录两个结果：

结果	问题	示例
`resolution`	引用或 target 是否明确且可解析？	MCP endpoint 与 tool name 已完整声明。
`readiness`	当前环境现在能否使用它？	offline 模式没有 discovery，因此 MCP tool 为 `Unknown`。

下面是 report 中 MCP Requirement 的完整 check，逐字取自 examples/generated/idea-to-spec-review-preflight-report.yaml：

- id: lifecycle.report-stage-success.adapter.stage-reporting-mcp.reporting-tool.0
  ownerRef:
    kind: Adapter
    name: stage-reporting-mcp
  requirementType: mcpTool
  optional: true
  handlerId: report-stage-success
  checkedAt: 2026-07-15T00:00:00.000Z
  resolution:
    status: "True"
    reason: DynamicTargetResolved
    message: The dynamic target is fully declared.
  readiness:
    status: Unknown
    reason: McpProbeSkipped
    message: Offline preflight resolved the MCP target but did not perform live discovery.

Report 的 snapshotHash 哈希 Run.spec。如果 Run.spec 发生变化，采用方必须比较 hash 或重新 Preflight；不要把旧 evidence 当作新 snapshot 的结论。

dryRun 与 execute gate

Run mode	required check gate
`dryRun`	required `False` 会失败；required `Unknown` 可以保留给审查。
`explain`	与 `dryRun` 相同，只允许保留 required `Unknown`，不允许硬 `False`。
`execute`	required resolution 和 readiness 都必须聚合为 `True`。
省略 `mode`	reference CLI 按 `execute` 处理。

即使 execute Preflight gate 通过，仍然没有获得授权。当前 CLI 也没有 execute 命令。

stage scope

传入 --stage 会生成 stage scope evidence 和 StagePreflightResolved / StagePreflightReady conditions：

node ./bin/huoban.js preflight tmp/idea-to-spec-review-dry-run.yaml \
  --workspace "examples/**/*.yaml" \
  --out tmp/sharpen-idea-preflighted.yaml \
  --report tmp/sharpen-idea-preflight-report.yaml \
  --stage sharpen-idea

stage scope 只回答该 stage 的检查问题。局部满足 mode 规则时 CLI 可以返回退出码 0，但会明确提示它不构成 Run gate；失败时仍先写出 Run 与 report，再返回非零。它不能替代 Run scope PreflightReady=True，也不能授权整个 Run。

`--live` 的边界

只有明确需要动态 discovery 时才添加：

node ./bin/huoban.js preflight tmp/idea-to-spec-review-dry-run.yaml \
  --workspace "examples/**/*.yaml" \
  --out tmp/idea-to-spec-review-live-preflighted.yaml \
  --report tmp/idea-to-spec-review-live-preflight-report.yaml \
  --live

--live 会访问对象声明的 URL：

remote context 使用只读 HEAD。
MCP 使用 initialize、notifications/initialized 和有界的 tools/list / resources/list。
每次 MCP 响应体上限为 1 MiB；最多遍历 20 页。
不调用 MCP tool。
报告去除 URL user info、query、fragment、常见 credential 形式和远端 MCP error text。
discovery 成功不改变 Trust，也不批准 side effects。

inferred Requirement

当 Requirement 使用 origin: inferred 时，schema 要求 reviewStatus。如果是 needsReview，Preflight 会返回：

resolution: Unknown (RequirementNeedsReview)
readiness: Unknown (RequirementNeedsReview)

当前 CLI 没有 review 命令。不要虚构从 needsReview 到 accepted 的自动状态迁移；review 与记录方式由采用方明确实现。

Lifecycle 有限事件

v1alpha1 只允许：

run.ready
run.started
stage.started
stage.succeeded
stage.failed
checkpoint.requested
checkpoint.resolved
run.finalizing
run.succeeded
run.failed
run.cancelled

不要添加任意 hook 字符串。状态改变属于 Stage，决策属于 Checkpoint，权限属于 Policy，外部能力属于 Adapter；Lifecycle Handler 只用于观察、上报和清理。当前实现只有：

schema 声明；
Run role binding；
Preflight binding / Requirement checks；
explain 输出；
Run.status.lifecycleInvocations 状态形状。

当前没有 lifecycle dispatcher 或执行 runtime。authored Run 中的 Pending invocation 不会自动迁移。因此，delivery 在当前仓库只影响 Preflight requiredness：bestEffort 作为 optional evidence，required 参与 required gate。具备 dispatcher 的采用方才负责兑现投递、timeout 与 retry 语义。终态 run.succeeded、run.failed、run.cancelled 只允许 bestEffort；required 收尾使用 run.finalizing。

Lifecycle Event Envelope

事件信封是共享 fragment，不是顶层 Kind。下面逐字取自 examples/fragments/checkpoint-requested.lifecycle-event.json：

{
  "id": "idea-to-spec-review-001-direction-requested",
  "type": "checkpoint.requested",
  "occurredAt": "2026-07-15T00:00:00.000Z",
  "runRef": {
    "name": "idea-to-spec-review-001"
  },
  "stage": "sharpen-idea",
  "checkpointRef": {
    "name": "idea-to-spec-review-001-direction"
  },
  "artifactRefs": [
    {
      "kind": "Artifact",
      "name": "review-notes"
    }
  ],
  "conditionTypes": [
    "CheckpointRequired"
  ]
}

重试同一逻辑事件时必须复用 id。信封不携带 prompt、Profile 正文、secret 或完整输入输出；handler 通过受控引用读取所需 Artifact。

​public example 中的依赖

​完整 reporting Adapter

​完整 reporting Trust

​完整 Flow

​复现 dry-run 与默认离线 Preflight

​完整 preflighted Run

​resolution 与 readiness

​dryRun 与 execute gate

​stage scope

​--live 的边界

​inferred Requirement

​Lifecycle 有限事件

​Lifecycle Event Envelope

​相关页面

public example 中的依赖

完整 reporting Adapter

完整 reporting Trust

完整 Flow

复现 dry-run 与默认离线 Preflight

完整 preflighted Run

resolution 与 readiness

dryRun 与 execute gate

stage scope

`--live` 的边界

inferred Requirement

Lifecycle 有限事件

Lifecycle Event Envelope

相关页面