对象模型

Huoban 的对象模型定义 AI 原生工作的最小可描述结构。它不从“如何执行命令”开始，而是从“如何描述 AI 原生工作”开始：能力是什么，上下文是什么，如何编排，在哪些边界停下，允许哪些副作用，产物如何留下，来源是否可信。本页属于核心概念，解释对象模型的设计边界和阅读方式；字段级定义、必填项和 schema 约束见规范参考。 AGENTS.md、CLAUDE.md、Cursor Rules 和 SKILL.md 都是重要入口，但它们通常把上下文、能力、外部依赖、权限、执行意图和审查边界混在自然语言里。Huoban 对象模型把这些内容拆成不同职责：上下文进入 Profile，能力进入 Skill 或 Adapter，权限进入 Policy，编排进入 Flow，一次工作进入 Run，决策边界进入 Checkpoint；外部依赖和执行前证据使用共享执行契约表达。

对象优先

Huoban 先定义 AI 工作的标准对象，而不是先定义某个工具的调用方式。

职责分离

能力、上下文、编排、权限、执行、校对、产物和信任分别由不同对象表达。

声明与观察分离

spec 表达期望结构，status 表达工具或系统观察到的处理状态。

非脚本格式

核心对象描述工作结构，不把 shell 命令、模型参数或工具私有字段作为中心。

最小对象链路

Huoban 的对象不是平铺词表，而是一条 AI 工作链路。v1alpha1 的十个顶层 kind 具有同等协议地位；具体实现可以只消费其中一部分，但不能因此发明协议内不存在的 Core/Extension 等级。

能力：Skill

Skill 声明可复用能力、输入输出、上下文提示和副作用。

上下文：Profile

Profile 把团队规则、项目结构、领域语言和历史决策整理成分层上下文。

编排：Flow

Flow 通过 capability-first stage 描述能力如何排列、产物声明如何传递、哪里需要 checkpoint。

边界：Policy

Policy 声明副作用、权限和审批规则，让自动化边界可审查。

快照：Run

Run 锁定一次工作使用的对象引用、mode、bindings 和当前 schema 支持的 snapshot hash。

预检：Requirement 与 Preflight

对象声明外部依赖；Preflight 在具体 Run 和 workspace 上记录引用、binding 与环境就绪证据。

校对：Checkpoint

Checkpoint 把高判断力或高风险位置变成显式决策边界。

产物：Artifact

Artifact 记录一次 Run 产生的文档、报告、代码、diff 或决策记录。

来源：Registry 与 Trust

Registry 组织对象来源和索引范围，Trust 记录对象来源、审查状态、信任等级和 sandbox 要求。

十个顶层对象

对象	职责	v1alpha1 字段锚点
`Skill`	声明可复用能力。	`capabilities`、`inputs`、`outputs`、`requirements`、`sideEffects`、`checkpoint`、`adapterRef`
`Profile`	声明分层上下文。	`layers`、`merge`、`requirements`、`policyRefs`
`Flow`	声明 capability-first 编排。	`profileRefs`、`policyRefs`、`stages`、`checkpoints`、`lifecycle`
`Run`	锁定一次 AI 工作的执行视图。	`flowRef`、`profileRefs`、`policyRefs`、`mode`、`bindings`、`snapshot`
`Checkpoint`	声明必须显式处理的决策边界。	`runRef`、`stage`、`reason`、`requiredActions`、`artifactRefs`、`expiresAt`
`Policy`	声明权限、副作用、审批和危险动作限制。	`rules`、`defaults.unknownSideEffect`、`effect`、`when.capabilities`、`when.sideEffects`、`when.trustLevels`
`Adapter`	标准化外部 skill、MCP tool、导入格式或外部能力。	`source`、`capabilities`、`requirements`、`mapping`、`sideEffects`、`checkpoint`、`trustRef`
`Artifact`	记录一次工作产生的可审查产物。	`type`、`runRef`、`stage`、`contentRef`、`summary`、`hash`、`review`；object 内容使用 `contentRef.data`
`Registry`	组织对象来源和索引范围。	`sources`、`index.includeKinds`、`trustPolicyRef`
`Trust`	记录对象来源、审查状态、信任等级和 sandbox 要求。	`subjectRef`、`source`、`level`、`review`、`signatures`、`sandbox`、`policyRefs`

Huoban v1alpha1 只有以上十个顶层 kind。执行前就绪与生命周期语义不通过增加大对象解决，而是使用四类共享结构：

共享结构	所在位置	职责
`Requirement`	`Skill`、`Profile`、`Adapter` 的 `spec.requirements[]`	声明文件、程序、MCP、凭据、runner capability 或上下文来源依赖。
`Preflight Report`	`Artifact.spec.contentRef.data`	保存 Run/workspace 上逐项 Resolution 与 Readiness 证据。
`Lifecycle Handler`	`Flow.spec.lifecycle[]`	在有限事件上声明上报、观察或清理能力及 delivery。
`Lifecycle Event Envelope`	handler 的协议输入	携带 event id、type、runRef、stage/checkpoint 和 Artifact 引用等最小上下文。

这些结构没有独立 metadata、spec/status 生命周期，也不进入 Registry.index.includeKinds。它们是共享协议结构，不是“次一级对象”。详见 Requirement、Preflight 和 Lifecycle Handler。

未进入 v1alpha1 的候选方向

下列概念目前不是 v1alpha1 schema 对象。它们可以作为未来候选对象、实现扩展或已存在对象的内部语义出现，但不属于当前公共对象模型。

候选概念	v1alpha1 当前表达	可能提升为对象的条件
`Eval`	可先作为 `Artifact.review`、`Checkpoint` reason 或实现侧检查存在。	出现稳定、可复用的校样 schema 和 examples。
`Context`	结构化上下文进入 `Profile.layers`，外部内容引用可进入 `Artifact.contentRef`。	需要跨 Profile、Artifact、Adapter 的独立上下文生命周期。
`Permission`	权限和审批边界进入 `Policy.rules`。	需要比 Policy 更细的授权对象，并有重复 workflow 证据。
`Tool`	外部工具能力通过 `Adapter.source` 和 `Adapter.capabilities` 表达。	工具描述需要脱离 Adapter 独立复用。
`Resource`	可读取资源可通过 `Profile.layers`、`Artifact.contentRef` 或 Adapter 实现语义表达。	资源需要独立权限、信任和生命周期管理。
`Prompt`	可复用提示可作为 `Skill` 的实现材料或 Adapter 来源。	prompt 本身需要成为可验证、可版本化、可组合对象。
`Runtime`	执行环境属于实现侧或兼容等级说明。	执行环境声明需要进入跨实现互操作协议。
独立 `Binding`	当前由 `Run.spec.bindings` 表达 capability 到 `Skill` 或 `Adapter` 的绑定结果。	binding 需要跨 Run 复用、审查或签名。

这条边界很重要：没有 schema 和 examples 支撑的概念，不应该被写成已经稳定的公共标准对象。

资源对象格式

Huoban 对象采用声明式资源对象格式：

apiVersion: huoban.dev/v1alpha1
kind: Flow
metadata:
  name: idea-to-spec-review
spec:
  ...
status:
  ...

字段语义：

字段	作用
`apiVersion`	对象 API 版本，例如 `huoban.dev/v1alpha1`。
`kind`	对象类型，例如 `Skill`、`Profile`、`Flow`、`Run`。
`metadata`	名称、标签、annotations 和 generation 等元信息。
`spec`	作者声明的期望对象结构。
`status`	工具或系统观察到的处理状态。

status 是可选字段。schema 校验字段形状，generation 递增和 observedGeneration 更新由工具或实现约定维护。

spec 与 status

Huoban 必须保持 spec 与 status 的边界。spec 说明“想要什么”，status 说明“已经观察到什么”。作者或上游系统写 spec：

spec:
  profileRefs:
    - name: project-profile
  stages:
    - id: review
      requires:
        capability: huoban.dev/designReview

工具或系统写 status：

status:
  phase: WaitingForCheckpoint
  observedGeneration: 2
  conditions:
    - type: CheckpointRequired
      status: "True"
      reason: HumanReviewRequired

不要把运行日志、临时结果、执行命令、artifact 内容和用户期望混进同一个字段。

generation 与 observedGeneration

Huoban 对象支持：

metadata:
  generation: 3
status:
  observedGeneration: 2

语义：

metadata.generation 在 spec 发生语义变化时递增。
status.observedGeneration 表示当前 status 对应哪个 generation。
如果二者不一致，说明观察状态还没有追上当前 spec。

这能避免用户修改 Flow 或 Profile 后误读旧状态。

Conditions

conditions 是机器可读的状态摘要。它不替代日志、产物正文或审查结论。示例 condition type 包括但不限于：

SkillResolved
ProfileResolved
FlowValidated
PolicyChecked
AdapterBound
RegistryLoaded
TrustResolved
PreflightResolved
PreflightReady
OptionalDependencyUnavailable
RunPlanned
StageStarted
StageCompleted
ArtifactProduced
CheckpointRequired
CheckpointApproved
RunCompleted
RunFailed
ProfileConflictDetected
UndeclaredSideEffectObserved

实现可以定义额外 condition type，但必须保持 type、status、reason 的机器可读结构。

非目标：不做过程式脚本

Huoban 的核心对象不描述“执行哪条命令”，而描述“这项 AI 工作需要什么能力、使用什么上下文、遵守什么边界、在哪里校对、留下什么产物”。核心对象模型不应以这些字段为中心：

run: claude -p "..."
shell: ...
command: ...
model: ...
toolArgs: ...

命令、执行器参数、模型调用细节和工具私有字段不得进入核心对象字段。如需保留，只能放在 schema 已允许的 Adapter 子结构或实现私有扩展中。 Huoban 要描述期望的 AI 工作结构，而不是把自己变成 CI 脚本格式。

开始使用

核心概念

规范参考

迁移指南

示例

标准与治理

开源项目

对象优先

职责分离

声明与观察分离

非脚本格式

最小对象链路

十个顶层对象

未进入 v1alpha1 的候选方向

资源对象格式

spec 与 status

generation 与 observedGeneration

Conditions

非目标：不做过程式脚本

对象优先

职责分离

声明与观察分离

非脚本格式

​最小对象链路

​十个顶层对象

​未进入 v1alpha1 的候选方向

​资源对象格式

​spec 与 status

​generation 与 observedGeneration

​Conditions

​非目标：不做过程式脚本

最小对象链路

十个顶层对象

未进入 v1alpha1 的候选方向

资源对象格式

spec 与 status

generation 与 observedGeneration

Conditions

非目标：不做过程式脚本