Skip to main content
Lifecycle Handler 由 Flow.spec.lifecycle[] 声明，用有限事件枚举连接观察、上报和清理能力。它不是顶层 kind，当前仓库也不提供 lifecycle event dispatcher。 Handler 通过 requires.capability 描述能力，通过 requires.role 在 Run.spec.bindings 中选择 Skill 或 Adapter。外部文件、MCP、凭证等环境依赖仍由被绑定对象的 requirements[] 声明。

​
Handler 字段

当 match 存在时，on 只能是 stage.started、stage.succeeded 或 stage.failed。当 on 是 run.succeeded、run.failed 或 run.cancelled 时，delivery 必须为 bestEffort；required 收尾使用 run.finalizing。 事件枚举固定为：
不得增加任意 hook 字符串。状态改变属于 stage，决策属于 Checkpoint，权限属于 Policy，外部能力属于 Adapter。

​
合法示例

对应 Run 必须把 stage-reporter 绑定到提供 huoban.dev/stageReporting 的 Skill 或 Adapter，例如：

​
当前 Preflight 行为

  • 检查 Flow 内重复 handler id。
  • 检查 match.stages[] 是否引用 Flow 中存在的 stage。
  • 按 requires.role 查找锁定的 Run binding，并检查目标是否提供 requires.capability。
  • 继续检查被绑定 Skill/Adapter 的 Requirement 和当前已实现的关联引用。
  • delivery: bestEffort 会把 binding 及其依赖标记为 optional；required 会参与 required gate。
  • run scope 检查所有 handler；stage scope 只选择 stage.* 事件且 selector 包含该 stage 的 handler。
timeoutSeconds 和 retry.maxAttempts 目前只被 schema 和 explain 读取。没有 dispatcher 执行 timeout、retry 或 handler 调用。

​
Lifecycle Event Envelope

Lifecycle Event Envelope 是独立 fragment，不是 Huoban 对象。 当前 CLI 不生成、投递或消费 Event Envelope；validate 可以直接校验 JSON/YAML envelope fragment。该 schema 只定义互操作形状。

​
Run invocation 状态

Run.status.lifecycleInvocations[] 记录 handler 调用状态： Pending 必须使用 attempts: 0 且不能有 lastAttemptTime；Running、Succeeded、Failed 必须至少有一次 attempt 并记录 lastAttemptTime。 这是状态 schema，不代表当前仓库已经执行 invocation。

​
验证边界

  • huoban validate 会通过 Flow/Run schema 检查嵌入的 Handler 与 invocation，但不解析 binding；也可以校验没有 apiVersion/kind 的 Event Envelope fragment。
  • stage event 必须带 stage 且不能带 checkpointRef；checkpoint event 必须带 checkpointRef；run event 不能带二者。
  • Preflight 检查 handler binding、capability、selector 和依赖，不触发事件。
  • schema 限制 match 只能搭配三类 stage 事件，并限制三类 terminal Run event 只能使用 bestEffort。
  • handler 适用于观察、上报和清理，不应承载状态变更、决策、授权或外部能力定义。

​
相邻概念边界

​
常见错误

  • 写成顶层 kind: LifecycleHandler。
  • 使用 afterStage、onSuccess 等任意 hook 名称代替有限事件。
  • 把 Handler 的 requires 写成 Requirement target。
  • 忘记在 Run 中绑定 handler role。
  • 认为 bestEffort 会让 schema 错误通过；它只影响当前 Preflight 的 optional gate。
  • 在 run.succeeded、run.failed 或 run.cancelled 上声明 required delivery；必须完成的收尾应使用 run.finalizing。
  • 声称当前 CLI 会分发事件、执行 retry 或调用 MCP reporting tool。