Skip to main content

​
规范参考总览

Huoban 规范参考面向实现者、Adapter 作者、工具作者和标准贡献者。它回答的问题不是“Huoban 为什么存在”，而是“一个 Huoban 对象应该长什么样”。 当前参考版本为 huoban.dev/v1alpha1。

​
资源对象格式

所有 Huoban 对象共享同一外壳： 
apiVersion: huoban.dev/v1alpha1
kind: Flow
metadata:
  name: idea-to-spec-review
spec:
  ...
status:
  ...
字段约定：
字段要求说明
apiVersion必填对象 API 版本。v0.1 使用 huoban.dev/v1alpha1。
kind必填对象类型，例如 Skill、Profile、Flow。
metadata必填名称、标签、generation、来源和所有权。
spec必填作者声明的期望状态。
status可选runtime 观察到的实际状态，只能由 runtime 写入。

​
对象分类

Core API Objects 是最小兼容 runtime 必须理解的对象： Standard Extension Objects 在 v0.1 中定义，但 runtime 可以按兼容等级选择支持： 更多扩展对象，例如 Eval、Context、Tool、Resource、Prompt、Runtime、Binding，会在后续 reference 中继续拆页。

​
spec / status 边界

spec 是用户或上游系统声明的期望状态，status 是 runtime 观察到的事实。 不要把运行日志、临时命令、artifact 内容和用户期望混在 spec 里。状态应该进入 status.phase、status.conditions、status.observedSideEffects 或专门的 Artifact 对象。

​
Conditions

Huoban 使用 conditions 表达细粒度状态。一个 condition 至少应包含： 
type: FlowValidated
status: "True"
reason: SchemaValid
message: "Flow passed schema validation."
lastTransitionTime: "2026-06-23T12:00:00Z"
推荐字段：
字段说明
type条件类型，例如 ProfileResolved、CheckpointRequired。
statusTrue、False 或 Unknown。
reason稳定、机器可读的原因。
message面向人的解释。
lastTransitionTime状态变化时间。

​
generation

对象 spec 发生语义变化时，metadata.generation 应递增。runtime 写入 status.observedGeneration，表示当前状态对应哪一代 spec。 
metadata:
  generation: 3
status:
  observedGeneration: 2
如果二者不一致，说明 status 还没有追上最新 spec。

​
实现建议

v0.1 实现不需要一次支持全部对象。推荐顺序：
  1. 支持读取与校验 apiVersion / kind / metadata / spec。
  2. 支持 Profile import / export。
  3. 支持 Flow explain / dry-run。
  4. 支持 Run snapshot。
  5. 支持 Policy 与 side effects。
  6. 支持 Adapter 与外部生态迁移。
参见 兼容等级。