Skip to main content
Huoban 是 alpha 协议项目。贡献应先改进标准对象、schema、public examples、evidence 和 explain，再扩展 runtime surface。

​
开发环境

使用 Node.js 20 或更高版本：
npm test 会运行 unit tests，重新生成 deterministic Profile、Policy、AGENTS.md、dry-run Run 与 Preflight report，验证 YAML，解释 workspace，并检查 generated-file drift。

​
适合贡献的内容

  • 提高清晰度且不扩大语义的 schema 修正。
  • 有真实输入、schema-valid object 和验证命令的 example。
  • 更准确的 huoban explain 输出。
  • 保持只读、有界的 Preflight checks 或 evidence。
  • 有 fixture 和 review boundary 的迁移支持。
  • 澄清 Profile、Policy、Adapter、Flow、Run、Checkpoint、Requirement、Preflight 与 Lifecycle 的边界。
早期避免：
  • 完整 agent runtime。
  • hosted registry 或 marketplace。
  • 没有安全模型的 external execution。
  • 公司特定规则进入公共 schema。
  • 只有 prose、没有 example/test 的公共标准声明。

​
顶层 kind 边界

当前 10 个顶层 kind 是：
以下是 embedded fragments，不是 kind：
不要为已有职责发明新 kind。新 kind 必须证明与 10 个现有 kind 有不可合并的清晰边界。

​
修改 schema 或 object semantics

  1. 更新 schemas/v1alpha1/ 中的 schema。
  2. 更新至少一个 examples/ object。
  3. 如果影响 deterministic output，更新 generated dry-run 或 Preflight evidence。
  4. 更新对应文档。
  5. 如果改变 Preflight 或 Lifecycle 行为，增加 behavioral test。
  6. 运行 npm test。
每个 changed line 都应能追溯到该语义变更。

​
修改 Requirement 或 Preflight

必须保持：
  • Requirement 只嵌入 Skill、Profile 或 Adapter。
  • inferred Requirement 需要 reviewStatus。
  • 不虚构 review 后的自动状态迁移。
  • resolution 与 readiness 分开。
  • Preflight report snapshotHash 哈希 Run.spec。
  • 默认 offline。
  • --live 只读、有界，不调用 MCP tool。
  • stage scope 不能授权整个 Run。
  • Run scope PreflightReady=True 也不替代 Policy、Trust、Checkpoint 或平台授权。

​
修改 Lifecycle

必须保持：
  • event 来自有限枚举。
  • handler 用 Run binding role 解析实现。
  • delivery、timeout 与 retry 显式且 bounded。
  • 观察、上报与清理可以使用 handler。
  • 状态改变属于 stage。
  • 决策属于 Checkpoint。
  • 权限属于 Policy。
  • 外部能力属于 Adapter。
  • 在 dispatcher/runtime 未实现前，不把 authored status 描述成执行结果。

​
验证矩阵

修改 schema、example 或 CLI 后运行：
修改 Profile、Policy 或 Adapter 迁移行为后运行：
最终运行：

​
Capability 命名

标准 capability 使用 huoban.dev/*：
第三方 capability 使用自己的 DNS-style namespace。新增标准 capability 时必须提供：
  • 与现有 capability 的边界。
  • 至少一个 Skill 或 Adapter example。
  • 至少一个 Flow role usage。
  • 重复真实 workflow 证据。

​
标准提升条件

进入公共标准的模式应同时满足：
  • 在重复真实 workflow 中出现。
  • 不绑定单一公司、仓库、agent 或 runner。
  • 可以被 schema 验证。
  • 有 public example。
  • 可以被 CLI 解释。
  • 提升互操作性。
在此之前，保留在私有 Profile、Policy、Adapter、Flow 和 Run 中。

​
治理原则

  • 核心对象保持小而明确。
  • breaking change 进入 changelog 与 migration notes。
  • generated Markdown 必须 review，不能直接成为可信协议对象。
  • public standard 以 schema、example、test 和 explain evidence 为准。
  • 更正式的治理机制应由稳定外部贡献需求触发，而不是提前设计。