huoban.dev/v1alpha1 已由 JSON Schema、examples 和 CLI 实现的协议表面。字段形状以 schemas/v1alpha1/*.schema.json 为准；CLI 行为以 bin/huoban.js 和 lib/preflight.js 为准。
当前 v1alpha1 仍是同版本内直接修订的草案，尚无需要兼容的既有用户。不要据此声称旧 reader 能前向兼容后续修订。
资源外壳
10 个顶层 kind 都使用同一外壳：
每个 condition 必须包含
type、status 和 reason。status 只能是 "True"、"False" 或 Unknown；message 与 lastTransitionTime 是可选字符串，schema 不校验时间格式。
引用形状
引用结构只描述形状。普通
validate 不解析目标；当前 Preflight 只解析其实现明确收集到的引用。
Digest 形状
所有协议 digest 使用sha256:<64 位小写十六进制>。对象 digest 使用 Huoban canonical JSON v1：对象 key 按 UTF-16 code unit 升序递归排列、数组顺序保持、按 ECMAScript JSON.stringify 语义序列化为 UTF-8，再计算 SHA-256。file input 与 file-backed Artifact 直接哈希原始文件 bytes。
10 个顶层 kind
共享执行契约
以下结构嵌入顶层对象或 Artifact 内容，但不是顶层 kind：
把这些结构写成
kind: Requirement、kind: PreflightReport 或 kind: LifecycleHandler 会失败，因为 CLI 找不到对应的顶层 schema。
当前验证边界
完整命令和可验证范围见 兼容与验证。
合法示例
上面的最小Skill 是完整、合法的顶层对象。即使没有副作用，也必须保留必填的 sideEffects.declared: []。
仓库中的组合示例以 examples/**/*.yaml 为准。运行：
相邻概念边界
常见错误
- 发明 schema 中不存在的字段，或把开放状态字段误写进
spec。 - 把 Requirement、Preflight Report 或 Lifecycle Handler 增加为第 11 个 kind。
- 认为引用形状合法就代表引用目标存在。
- 使用自由字符串
user.prompt或stages.a.outputs.b代替结构化flowInput/stageOutput，或只在 Run 塞入未声明输入。 - 把 stage scope 的
StagePreflightReady=True当成整次 Run 的执行门槛。 - 把
PreflightReady=True当成 Policy allow 或 Trust trusted。 - 声称当前仓库有 Flow executor、Lifecycle dispatcher 或 Policy enforcement runtime。