示例总览

Huoban 的 public examples 是可由 schema 和 CLI 验证的协议对象，不是 runtime 演示。当前 workspace 有 18 个对象、10 个顶层 kind。Requirement、Preflight evidence 和 Lifecycle Handler 嵌入现有对象，不增加 kind。

AGENTS.md Profile

运行当前 import、derive 和 export CLI，审查规则推断。

idea-to-spec-review

用 Flow、Run、Checkpoint 和 Artifact 组成可验证工作流。

SKILL.md Adapter

用 Adapter、Requirement、Trust 和 Policy 描述外部能力。

Preflight 与 Lifecycle

区分 resolution、readiness、授权和 handler runtime。

四条示例路径

路径	入口	可复现结果
Profile 迁移	`examples/import/AGENTS.md`	生成 Profile、派生待审查 Policy、导出 AGENTS.md。
capability-first 编排	`examples/flows/idea-to-spec-review.yaml`	验证入口文件，解释 Flow，并打印锁定 refs、bindings 与调用输入的 dry-run Run。
外部能力适配	`examples/fixtures/grill-me/SKILL.md`	验证手写 Adapter、localPath Requirement 和 Trust 记录。
执行前检查	`examples/generated/idea-to-spec-review-dry-run.yaml`	写入 Preflight conditions，并生成 Preflight Report Artifact。

这些 examples/... 值是 Huoban source repo 内的路径，不是文档站 URL。本章在各示例页内嵌关键完整对象，避免把 source checkout 当成阅读前提。

对象清单

kind	public example
`Skill`	`examples/skills/design-review.yaml`、`examples/skills/spec-outline-writer.yaml`
`Profile`	`examples/profiles/huoban-open-source-project.yaml`、`examples/profiles/project-profile.yaml`、`examples/generated/agents-profile.yaml`
`Flow`	`examples/flows/idea-to-spec-review.yaml`
`Run`	`examples/runs/idea-to-spec-review-run.yaml`、`examples/generated/idea-to-spec-review-dry-run.yaml`
`Checkpoint`	`examples/checkpoints/idea-to-spec-review-direction.yaml`
`Policy`	`examples/policies/safe-defaults.yaml`、`examples/derived/agents-risk-policy.yaml`
`Adapter`	`examples/adapters/grill-me-skill-md.yaml`、`examples/adapters/stage-reporting-mcp.yaml`
`Artifact`	`examples/artifacts/review-notes.yaml`、`examples/generated/idea-to-spec-review-preflight-report.yaml`
`Registry`	`examples/registry/local-registry.yaml`
`Trust`	`examples/trust/local-reviewed-grill-me.yaml`、`examples/trust/local-stage-reporting.yaml`

一个完整安全对象

下面逐字取自 examples/policies/safe-defaults.yaml：

apiVersion: huoban.dev/v1alpha1
kind: Policy
metadata:
  name: safe-defaults
spec:
  defaults:
    unknownSideEffect: requireApproval
  rules:
    - effect: requireApproval
      when:
        sideEffects:
          - publishRemote
          - spendMoney
          - accessSecret
    - effect: deny
      when:
        sideEffects:
          - modifyGitHistory

这个对象说明副作用规则，但不会自行执行审批或授予权限。

嵌入式执行契约

构件	所在位置	作用
Flow entry input	`Flow.spec.inputs[]`	声明调用者必须提供的动态稿件类型与名称。
Run input binding	`Run.spec.inputBindings`	保存这次调用的内容引用与锁定 hash。
`Requirement`	`Skill.spec.requirements`、`Profile.spec.requirements`、`Adapter.spec.requirements`	声明目标环境依赖及其来源。
Lifecycle Handler	`Flow.spec.lifecycle[]`	用有限事件、delivery、role、timeout 和 retry 声明观察、上报或清理集成。
Preflight summary	`Run.status.preflight` 与 conditions	记录 scope、`Run.spec` snapshot hash、检查时间和 report 引用。
Preflight Report	`Artifact` 的 `huoban.dev/preflight-report` 内容	分别记录每项 resolution 与 readiness evidence。
Lifecycle Event Envelope	`examples/fragments/stage-succeeded.lifecycle-event.json`、`examples/fragments/checkpoint-requested.lifecycle-event.json`	给 handler 提供有限、最小、可审计的事件输入。
Lifecycle invocation	`Run.status.lifecycleInvocations[]`	记录 handler invocation 状态；当前 example 是声明状态，不是 dispatcher 产物。

复现顺序

在 source repo 根目录运行：

npm install
npm run validate
npm run explain
npm run print:dry-run
npm run preflight

Profile 迁移单独运行：

npm run import:profile
npm run derive:policy
npm run export:agents

完整 deterministic 检查：

npm test

预期 workspace 摘要

Huoban Workspace
  objects: 18
  kinds: Adapter=2, Artifact=2, Checkpoint=1, Flow=1, Policy=2, Profile=3, Registry=1, Run=2, Skill=2, Trust=2
  print process:

npm run explain 还会显示：

Flow generation 2 的两个 capability-first stages。
report-stage-success Lifecycle Handler。
dry-run Run 的三个 role bindings。
Run scope Preflight report 的逐项 snapshot、入口输入、引用、binding 与 Requirement evidence。
两个 Adapter 各自引用的 Trust 对象。

不要从示例推断的行为

看到的对象状态	不能据此声称
`mode: dryRun`	已完成 Preflight。
`PreflightReady=True`	已通过 Policy、Trust、Checkpoint 或平台授权。
`StagePreflightReady=True`	整个 Run 已获准执行。
`lifecycleInvocations[].phase: Pending`	当前仓库存在 Lifecycle dispatcher。
`ImportNeedsReview=True`	已有自动接受或状态迁移流程。

从 AGENTS.md Profile 开始，或直接进入 Preflight 与 Lifecycle。

开始使用

核心概念

规范参考

迁移指南

示例

标准与治理

开源项目

AGENTS.md Profile

idea-to-spec-review

SKILL.md Adapter

Preflight 与 Lifecycle

四条示例路径

对象清单

一个完整安全对象

嵌入式执行契约

复现顺序

预期 workspace 摘要

不要从示例推断的行为

AGENTS.md Profile

idea-to-spec-review

SKILL.md Adapter

Preflight 与 Lifecycle

​四条示例路径

​对象清单

​一个完整安全对象

​嵌入式执行契约

​复现顺序

​预期 workspace 摘要

​不要从示例推断的行为

四条示例路径

对象清单

一个完整安全对象

嵌入式执行契约

复现顺序

预期 workspace 摘要

不要从示例推断的行为