Skip to main content
Preflight 是 execute 之前的机械就绪门。它回答：本次 Run 引用的对象能否解析、Flow 入口和 Run input binding 是否一致、动态内容是否仍匹配锁定 hash、每个 stage 与 lifecycle handler 是否已有实现 binding、实现声明的 Requirement 在当前 workspace 和环境中是否可用。 Preflight 不是顶层 kind。检查结果写入 Run.status.conditions、Run.status.preflight，详细证据保存为 type: huoban.dev/preflight-report 的 Artifact。

先解析，再检查

Resolution 记录目标声明和引用解析结果；Readiness 记录当前环境检查结果。

证据绑定 Run

报告记录 Run scope、Run.spec 的 snapshot hash、检查时间和逐项结果。

默认离线

默认只做本地、只读检查；--live 才允许对远程 context source 发起只读 HEAD，并对 MCP server 做有限发现请求。

不等于授权

PreflightReady=True 只记录机械就绪观察，不表示 Policy、Trust 或 Checkpoint 已放行。

​
完整执行前链路

1

Validate

校验对象字段形状。Schema 不能证明 workspace 中的引用或外部服务真实存在。
2

Explain 与 dry-run

解释对象关系，把调用值绑定到 Flow 入口，并生成计划态 Run。允许动态依赖仍为 Unknown。
3

Preflight

对锁定的 Run 解析 refs、bindings、Requirement 和 required lifecycle handler，生成结构化证据。
4

Policy、Trust 与 Checkpoint

在机械就绪之后处理副作用、来源信任和显式决策边界。
5

Execute

只有 Run scope 的 PreflightReady=True 且其他治理门已满足，执行器才可以启动。
dryRun 不等于 Preflight，Preflight 也不等于授权。三者回答不同问题：计划是什么、环境是否就绪、行为是否允许。

​
Run scope 与 stage scope

Run scope 检查完整 Run；stage scope 只用于定位某个阶段的阻塞原因。
stage scope 成功不能授权整次 Run。当前 CLI 可以为局部成功返回退出码 0，但会明确提示该结果不构成 Run gate；execute gate 必须读取同一 Run.spec 对应的 Run scope 证据。

​
Resolution 与 Readiness

每个 check 分成两个正交状态： 二者都使用 True、False、Unknown：
  • False：检查得到明确的不满足结果。
  • Unknown：当前检查模式无法得出权威结论。例如 offline 模式不会联网发现 MCP tool。
  • True：检查在当前范围与时刻观察到满足。
必需依赖出现 False 时，聚合 condition 为 False；出现 Unknown 且没有 False 时，聚合 condition 保持 Unknown。二者都会阻断 execute gate。可选依赖仍记录证据，但不单独阻断。

​
Offline 与 live

默认 offline 是安全边界，不只是性能选项。 live Preflight 不执行 tools/call。远程 context source 只允许 HEAD。MCP 请求每次最多等待 5 秒、列表发现最多读取 20 页、单次响应体上限为 1 MiB。报告会去除 URL user info、query、fragment、常见 credential 形式和远端 MCP error text。网络可达也不代表来源可信或行为已获授权。

​
Freshness 与失效

动态事实会变化。Requirement 的 freshness.maxAgeSeconds 用来计算报告的 validUntil。执行器不得复用已过期报告，也不得把不同 Run.spec 的报告套用到当前 Run。 snapshotHash 哈希的是当前 Run.spec，用于关联报告与 Run 声明。权威 Preflight 还会逐项重算 flowSpecHash、profileRefHash、policyRefHash、bindingHash 和 inputBindingHash。这些 hash 不归档被绑定 Skill 或 Adapter 的完整内容，报告本身也未签名；执行实现仍需使用可信时钟、比较 hash 并拒绝过期或被修改的证据。

​
动态输入检查

Preflight 对调用输入分三层检查：
  1. 契约：required 输入已绑定；没有未知 binding；binding 类型与 Flow 声明一致。
  2. 来源：stage 的 flowInput 已声明；stageOutput 存在且来自更早 stage。
  3. 内容：文件按 raw bytes 复核 hash；Artifact ref 按 name/generation/hash 解析，并在 object/file 内容可取得时复核实际内容。
URL 或当前实现无法取回的 Artifact 内容不会因引用存在而变成 ready。其 resolution 可以是 True，readiness 必须保持 Unknown，因此不能通过 execute gate。

​
证据落点

Preflight 的最小证据链包括：
  1. Run.status.conditions 中的 Resolved 与 PreflightReady 摘要。
  2. Run.status.preflight 中的 scope、snapshotHash、checkedAt、可选 validUntil 与 reportRef。
  3. Preflight Report Artifact 中的逐项 checks。
详细字段见 Preflight 规范。

​
失败语义

执行前缺失依赖或动态输入不完整属于 Blocked，不是 stage 业务失败。此时 stage 尚未开始，不能伪造 stage.failed，也不能创建 Checkpoint 让人“批准忽略”必需输入或依赖。 fallback 只有在 Run 中显式锁定、能力匹配且同样通过 Preflight 时才可用。临时热切换实现会使现有报告与 Run snapshot 失真。

​
当前实现边界

reference CLI 已实现 schema、入口契约、结构化数据流、input/implementation binding、内容 hash、Requirement、offline/live MCP discovery、报告 Artifact 和 execute gate 判断。它没有实现输入存储布局、依赖安装、Policy evaluator、Trust evaluator、Checkpoint 工作流或完整执行 runtime。 继续阅读：Preflight 规范、Run 模型、安全边界、示例：Preflight 与 Lifecycle。