> ## Documentation Index
> Fetch the complete documentation index at: https://huoban.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 愿景与开源策略

> Huoban 的官方项目定位、对象模型、开源策略和早期路线。

# Huoban 愿景与开源策略

> Huoban 是 AI 系统的开放编排协议：**可排版、可润墨、可印刷**。

本文是 Huoban 的第一版官方战略文档。它用于固定项目的方向、边界、对象模型、开源路线和早期采用策略。它不是实现说明，也不是临时讨论记录；后续 README、Spec、Schema、CLI、MCP Server、Adapter 和示例 flow 都应该以本文为方向约束。

Huoban 的目标不是再做一个 agent workflow runner，也不是再做一个 skill 集合。Huoban 要成为 AI 原生编排的对象模型层：用一套开放、可验证、可扩展的标准对象，描述 skill、context、flow、run、checkpoint、artifact、eval、policy、adapter、registry 和 trust。

## 1. 项目定位

Huoban 的定位是：

> A shared object model and open orchestration protocol for AI-native work.

中文可以表述为：

> Huoban 是 AI 原生工作的共享对象模型与开放编排协议。

这个定位有几个明确边界：

* Huoban 首先是标准和对象模型，不是执行器。
* Huoban 描述 agent work，而不是只运行 agent work。
* Huoban 允许不同 runtime、IDE、agent、MCP server 和外部工具链实现它。
* Huoban 不替代 Superpowers、OpenSpec、Claude Code skills、Codex skills、Matt Pocock skills、Cursor Rules、AGENTS.md 或 CLAUDE.md。
* Huoban 要把这些已有资产标准化成可组合、可快照、可校验、可迁移的对象。

一句话：Huoban 的核心不是“更会跑 agent”，而是“更会描述 agent 工作”。

## 2. 首批用户

Huoban 的第一批用户不是普通开发者，也不是大型企业采购者，而是高级 AI 编程用户和 agent power user。

他们通常已经在使用或组合：

* Claude Code
* Codex
* Cursor
* MCP tools
* AGENTS.md / CLAUDE.md / Cursor Rules
* Superpowers / OpenSpec / Matt Pocock skills
* 自己沉淀的 prompts、loops、checklists、review flows

他们的痛点不是“不会用 AI 写代码”，而是：

* 上下文不能稳定复用。
* workflow 只存在于脑子、聊天记录或笔记里。
* skill 分散在多个生态，缺少共同接口。
* 每次都在手工排 prompt。
* 外部工具链通常整包绑定，不方便拆开重排。
* agent 可以循环执行，但缺少清晰的 checkpoint、policy、eval 和 proofing 标准。
* 好的个人方法论无法变成团队可分享、社区可复用的标准对象。

因此，Huoban 的早期采用策略应聚焦这些 power user。普通开发者和企业用户可以是后续扩展对象，但不是冷启动阶段的首要目标。

## 3. 第一个不可替代价值

Huoban 的第一个不可替代价值不是“运行一个 flow”。

它的第一价值是：

> 把用户已经在脑子里、笔记里、AGENTS.md 里、CLAUDE.md 里、SKILL.md 里和聊天习惯里的 AI workflow，变成可命名、可保存、可验证、可复用、可分享的对象。

换句话说，Huoban 早期要解决的是隐性工作流显性化，而不是立刻成为最强执行引擎。

这决定了早期优先级：

1. 对象模型优先。
2. Spec 优先。
3. Schema 优先。
4. Import / Export 优先。
5. Validate / Explain 优先。
6. Dry-run 优先。
7. Full runtime 后置。

## 4. 标准路线

Huoban 的公开定位不应从执行器开始，而应从标准对象开始。

AI 原生编排正在快速分化：不同 agent、IDE、MCP server、skill 生态和外部工具链都会形成自己的执行方式。如果 Huoban 只提供某一种执行器，它很容易被具体平台替代。Huoban 更应该定义这些系统之间可以共享的对象语言。

这条路线意味着 Huoban 要优先完成几件事：

* 定义 AI 编排世界里的资源对象。
* 定义这些对象的版本规则。
* 定义 `spec`、`status`、`conditions` 的状态模型。
* 定义扩展对象和兼容等级。
* 定义信任、权限、副作用和审计边界。
* 允许多个 runtime 实现同一个对象模型。

Huoban 不应该自我定位为 “AI Workflow Runner”。更准确的定位是：

> Huoban defines the object model for AI-native orchestration.

中文：

> Huoban 定义 AI 原生编排的对象模型。

## 5. 早期应避免的方向偏差

Huoban 如果要成为开放标准，就必须从第一版开始避免几类方向偏差。

### 5.1 不要只做 runner

如果 Huoban 只提供 `huoban run`，它会被理解成又一个 workflow runner。runner 很容易被模型厂商、IDE、agent 平台或内部工具替代。

Huoban 应先定义标准对象，再提供 reference runtime。

### 5.2 版本策略必须从第一版开始

Huoban v0.1 应使用明确的 API 版本，例如：

```yaml theme={null}
apiVersion: huoban.dev/v1alpha1
kind: Flow
```

从 `v1alpha1` 开始就应定义：

* alpha / beta / stable 的含义。
* 破坏性变更策略。
* deprecation 策略。
* migration 工具方向。
* schema 版本兼容原则。

### 5.3 扩展点必须早设计

Huoban 不应等生态复杂后才补扩展点。第一版对象模型就应预留：

* Adapter
* Policy
* Eval
* Registry
* Runtime binding
* MCP binding
* Trust metadata
* Capability namespace

### 5.4 spec/status 边界必须严格

用户写 `spec`，runtime 写 `status`。

`spec` 描述期望状态，`status` 描述观察到的实际状态。不要把运行日志、临时结果、执行命令、artifact 内容和用户期望混在同一个字段里。

### 5.5 复杂度要分层暴露

Huoban 可以定义完整对象宇宙，但不能要求早期实现者一次支持全部对象。

因此必须有 conformance levels。

### 5.6 治理不能太晚

早期可以由创始人快速决策，但如果目标是行业标准，就要预留中立治理路线：

* 初期 BDFL 决策，提高速度。
* 形成核心贡献者后建立轻量 steering 机制。
* Spec 变更要有公开讨论和版本记录。
* 长期可考虑中立基金会或开放治理结构。

### 5.7 安全和权限不能后补

AI flow 会读文件、写文件、改 git、调用网络、访问 secret、发布内容、花钱、发送消息。Policy、side effects、trust model 必须从第一版写进标准。

## 6. API 对象模型

Huoban 应采用声明式资源对象模型：

```yaml theme={null}
apiVersion: huoban.dev/v1alpha1
kind: Flow
metadata:
  name: idea-to-spec-review
spec:
  ...
status:
  ...
```

核心约定：

* `apiVersion` 表示对象 API 版本。
* `kind` 表示对象类型。
* `metadata` 表示名称、标签、版本、generation、来源等元信息。
* `spec` 表示期望状态。
* `status` 表示 runtime 观察到的状态。

第一版不应设计成过程式脚本。也就是说，核心 spec 中应避免：

```yaml theme={null}
run: claude -p "..."
shell: ...
command: ...
```

这些实现细节可以出现在 Adapter 或 runtime-specific extension 中，但不应污染核心对象模型。

## 7. 完整对象宇宙与分级兼容

Huoban v0.1 应一次性定义完整对象宇宙，但兼容性分层。

这避免两个问题：

* 对象定义太少，项目显得没有标准野心。
* 第一版要求太多，早期实现者无法进入。

### 7.1 Core API Objects

Core 对象是最小 Huoban runtime 必须理解的对象：

* `Skill`
* `Profile`
* `Flow`
* `Run`
* `Checkpoint`

### 7.2 Standard Extension Objects

扩展对象应在 v0.1 中定义，但 runtime 可以选择性支持：

* `Artifact`
* `Adapter`
* `Policy`
* `Eval`
* `Registry`
* `Context`
* `Permission`
* `Tool`
* `Resource`
* `Prompt`
* `Runtime`
* `Binding`
* `Trust`

### 7.3 Conformance Levels

Huoban 应定义兼容等级：

| Level                       | 含义                                               |
| --------------------------- | ------------------------------------------------ |
| `Huoban Spec Aware`         | 能读取并校验 Huoban YAML / JSON。                       |
| `Huoban Core Compatible`    | 支持 `Skill / Profile / Flow / Run / Checkpoint`。  |
| `Huoban Adapter Compatible` | 支持把外部 skill / 外部能力适配成 Huoban Skill。              |
| `Huoban Policy Compatible`  | 支持权限、副作用、风险等级和审批策略。                              |
| `Huoban MCP Compatible`     | 支持通过 MCP 暴露或调用 Huoban 对象。                        |
| `Huoban Full Runtime`       | 支持完整执行、状态、artifact、registry、eval、policy 和 trust。 |

## 8. 对象命名原则

Huoban 的品牌层和哲学层应坚定使用活字印刷术隐喻。

但 API 层应使用全球开发者熟悉的英文对象名。

正确边界：

* 品牌名：`Huoban`
* 哲学叙事：活字、排版、润墨、校对、印刷、拆版还字
* API 对象：`Skill`、`Profile`、`Flow`、`Run`、`Checkpoint`、`Policy`、`Adapter`
* 文档中解释：`Skill = 活字`，`Profile = 墨方`，`Flow = 版式`，`Run = 印刷`，`Checkpoint = 校对`

不要在 schema 中使用 `PaiBan`、`MoFang`、`YinShua` 这类音译对象名。文化隐喻应降低理解成本，而不是提高采用门槛。

## 9. Flow 与 Capability Binding

Flow 不应直接绑定具体 skill 作为唯一模式。

更标准的设计是：Flow 引用 capability，Run 绑定具体 skill。

例如 Flow 表达：

```yaml theme={null}
stages:
  - id: review
    requires:
      capability: huoban.dev/designReview
      role: primary-review
```

Run 或 runtime binding 再解析为：

```yaml theme={null}
bindings:
  primary-review:
    skillRef: mattpocock/grill-me
```

这样有几个好处：

* Flow 可移植，不被某个具体 skill 锁死。
* Registry 可以按 capability 索引 skill。
* Adapter 可以声明自己满足哪些 capability。
* 不同 runtime 可以选择不同实现。

第一版示例可以允许 shortcut：

```yaml theme={null}
uses: mattpocock/grill-me
```

但标准层应保留 capability-first 的方向。

## 10. Capability Taxonomy

Huoban v0.1 应定义顶层 capability taxonomy，但不要细到具体 skill。

建议第一版标准能力包括：

* `ideation`
* `planning`
* `specification`
* `designReview`
* `implementation`
* `testing`
* `verification`
* `documentation`
* `migration`
* `release`
* `research`
* `debugging`
* `refactoring`
* `codeReview`
* `securityReview`

命名空间规则：

* 标准能力使用 `huoban.dev/*`。
* 第三方能力使用自己的 namespace，例如 `vendor.example/customCapability`。

第一版不要陷入细分类争论。顶层 taxonomy 的目标是形成共同语言，而不是描述世界上所有工作类型。

## 11. Profile：墨方与上下文运行时

Profile 是 Huoban 的核心对象之一。

它不是简单的 prompt 文件，也不是更复杂的 AGENTS.md。Profile 是结构化、分层、可合并、可版本化、可快照、可导入导出的上下文对象。

### 11.1 Profile 与现有规则文件的关系

Huoban 对现有文件的定位：

* `AGENTS.md` 是 profile file。
* `CLAUDE.md` 是 Claude Code 生态里的 profile file。
* Cursor Rules 是 IDE 场景下的 profile file。
* `Huoban Profile` 是 profile object。

一句话：

> AGENTS.md is a profile file. Huoban Profile is a profile object.

Huoban 不应该替代这些文件，而应该支持导入和导出。

### 11.2 Profile 的 data 与 content 双层模型

Profile 不应只存自然语言，也不应只存结构化字段。

推荐模型：

```yaml theme={null}
apiVersion: huoban.dev/v1alpha1
kind: Profile
metadata:
  name: huoban-open-source-project
spec:
  layers:
    - name: architecture
      data:
        architectureStyle: spec-first
        objectModel: declarative-resource
      content: |
        Prefer defining API objects before implementing runtime behavior.
        Avoid turning Huoban into a workflow runner too early.
```

语义：

* `data` 给 runtime、validator、policy、explain、merge 和 conflict detection 使用。
* `content` 给 agent 作为自然语言上下文使用。
* 两者都进入 Run snapshot。
* 如果 `data` 和 `content` 明显冲突，runtime 应生成 condition。

自然语言负责影响判断；结构化字段负责形成标准。

### 11.3 多层 Profile

Run 必须支持多个 Profile layer。

现实里的上下文天然分层：

* 个人偏好
* 团队约定
* 项目架构
* 领域知识
* 风险模式
* 临时 checkpoint feedback

示例：

```yaml theme={null}
profileRefs:
  - name: global-style
  - name: project-context
  - name: strict-policy-mode
  - name: run-overrides
```

合并规则应在 v0.1 写清楚：

* 按数组顺序应用。
* 后者覆盖前者的同名 scalar 字段。
* list 字段默认 append，除非声明 replace。
* layer 按 `name` 合并。
* 冲突写入 `status.conditions`。
* 最终 effective profile 必须可解释、可 hash、可快照。

### 11.4 Flow 与 Run 中的 Profile 引用

Profile 可以被 Flow 引用，也可以被 Run 引用。

语义：

* `Flow.spec.profileRefs` 表示默认墨方。
* `Run.spec.profileRefs` 表示本次运行覆盖或追加的墨方。
* `Run.spec.snapshot.profileSpecHash` 表示最终锁定的 effective profile。

最终以 Run snapshot 为准。

## 12. Policy：印坊规矩

Policy 必须与 Profile 分离。

* `Profile` 是墨方，影响 agent 的判断语境。
* `Policy` 是印坊规矩，决定什么能做、什么要审批、什么禁止。

如果混在一起，会导致安全规则和上下文偏好边界不清。

Policy 应以 capability 和 side effect 为中心，而不是以具体命令为中心。

不要这样设计：

```yaml theme={null}
deny:
  - command: git push
  - command: rm -rf
```

应这样设计：

```yaml theme={null}
rules:
  - effect: requireApproval
    when:
      sideEffects:
        - publishRemote
        - spendMoney
  - effect: deny
    when:
      sideEffects:
        - modifyGitHistory
```

标准 side effects 可以包括：

* `readFile`
* `writeFile`
* `deleteFile`
* `executeCommand`
* `modifyGitIndex`
* `modifyGitHistory`
* `networkAccess`
* `sendMessage`
* `publishRemote`
* `spendMoney`
* `accessSecret`
* `installDependency`
* `changePermission`

## 13. Side Effects：声明与观测

Huoban 应区分两类副作用：

* `declaredSideEffects`：Skill / Adapter 声明自己可能产生的副作用。
* `observedSideEffects`：Run 实际观测到的副作用。

示例：

```yaml theme={null}
kind: Skill
spec:
  sideEffects:
    declared:
      - readFile
      - writeFile
      - executeCommand
```

```yaml theme={null}
kind: Run
status:
  observedSideEffects:
    - type: writeFile
      target: spec/v1alpha1/flow.md
      stage: draft-flow
      time: "2026-06-23T12:00:00Z"
```

前者用于计划和审批，后者用于审计和复盘。

如果 observed side effects 超出 declared side effects，runtime 应生成 `UndeclaredSideEffectObserved` condition，并根据 Policy 决定是否中止 Run。

## 14. Adapter：异形活字标准化边界

Adapter 不是简单调用桥。

Adapter 的定位是：

> Convert external capabilities into Huoban-compatible movable type.

外部 skill / 外部能力可能没有 schema、capability、side effect、checkpoint 和 policy 语义。Adapter 的职责是把这些补齐。

Adapter 至少应声明：

* 外部来源，例如 Claude skill、Codex skill、MCP tool、Superpowers、OpenSpec。
* 调用方式。
* 输入输出映射。
* 支持的 capabilities。
* declared side effects。
* checkpoint behavior。
* policy hints。
* version compatibility。
* fallback behavior。

导入 `SKILL.md` 时，默认应生成 Adapter，而不是直接假设原 skill 是原生 Huoban Skill。

## 15. Registry：字架

Registry 是 Huoban 对象模型中的一等对象，但第一阶段不要做 hosted registry 或 marketplace。

v0.1 可以定义：

```yaml theme={null}
kind: Registry
spec:
  sources:
    - type: local
      path: ./skills
    - type: git
      url: https://github.com/example/huoban-skills
```

第一阶段只做：

* 本地 registry 示例。
* static index file。
* schema validation。
* explain 输出。

暂不做：

* hosted registry
* marketplace
* ranking
* package signing
* trust graph
* publish workflow

这些可以进入 roadmap。

## 16. Run：锁版印刷与快照

Run 表示一次具体执行。它应该像“锁版印刷”：一旦开始，就必须冻结当时依赖。

Flow、Profile、Skill 都可能变化，但 Run 必须可审计、可复盘、可解释。

因此 Run 必须锁定快照。

示例：

```yaml theme={null}
kind: Run
spec:
  flowRef:
    name: idea-to-spec-review
    generation: 4
  profileRefs:
    - name: huoban-open-source-project
      generation: 2
  snapshot:
    flowSpecHash: sha256:...
    profileSpecHash: sha256:...
    skillBindingHash: sha256:...
```

语义：

* `Flow` 是可变版式草案。
* `Profile` 是可变墨方。
* `Skill` 可能更新。
* `Run` 是一次锁定的印刷实例。
* `Run.status` 只能描述这个锁定快照的状态。

如果 Flow 执行到一半，用户修改了 Flow，正在执行的 Run 不应悄悄切换到新版本。

## 17. Status、Conditions 与 Generation

Huoban 应把 Conditions 作为一等状态表达。

粗糙的 `status: running` 不足以描述 AI flow。Huoban 需要知道：

* 哪个 stage 正在运行。
* 哪个 checkpoint 等待人工输入。
* 哪个 artifact 已生成。
* 哪个 policy 阻止了执行。
* 哪个 eval 失败。
* runtime 观察到的是哪一代 spec。

推荐状态结构：

```yaml theme={null}
status:
  observedGeneration: 3
  phase: WaitingForCheckpoint
  conditions:
    - type: ProfileResolved
      status: "True"
      reason: ProfileLoaded
      message: "Profile huoban-open-source-project loaded."
      lastTransitionTime: "2026-06-23T12:00:00Z"
    - type: CheckpointRequired
      status: "True"
      reason: HumanReviewRequired
      message: "The design review stage requires approval."
```

初始 condition types 可以包括：

* `SkillResolved`
* `ProfileResolved`
* `FlowValidated`
* `PolicyChecked`
* `AdapterBound`
* `RunPlanned`
* `StageStarted`
* `StageCompleted`
* `ArtifactProduced`
* `EvalPassed`
* `EvalFailed`
* `CheckpointRequired`
* `CheckpointApproved`
* `RunCompleted`
* `RunFailed`
* `ProfileConflictDetected`
* `UndeclaredSideEffectObserved`

Huoban 还应从 v0.1 引入：

```yaml theme={null}
metadata:
  generation: 3
status:
  observedGeneration: 2
```

语义：

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

## 18. Reconciliation Loop

Huoban 概念上应设计 controller / reconciliation loop，但 v0.1 实现上不要强制。

正确边界：

* Spec 中定义 desired state。
* Status 中记录 observed state。
* Conditions 中表达阶段和校对结果。
* 文档中解释 Huoban runtime 可以采用 reconciliation model。
* Reference runtime 早期只做 validate / explain / dry-run。
* 不强制实现 watch、daemon 或 long-running controller。

未来可以有：

* `huoban-controller`
* `huoban-runtime`
* `huoban-operator`

但 Phase 0 / Phase 1 不做。

## 19. Trust Model

Huoban 必须从第一版文档中写入信任模型，即使机制后续实现。

AI skill / adapter / flow 是高风险供应链。一个恶意 Adapter 可能让 agent 读 secret、改文件、发请求、推代码或花钱。

v0.1 应至少定义：

* 所有外部 Skill / Adapter 默认不可信。
* Trust 是 source、version、signature、policy、sandbox、review 的组合。
* `declaredSideEffects` 是声明，不等于验证。
* `observedSideEffects` 用于审计。
* `Policy` 决定 allow / deny / requireApproval。
* `Checkpoint` 是人工信任边界。
* 未来支持 signatures、provenance、SBOM-like metadata、registry trust levels。

第一版不必实现完整签名、trust graph 或 hosted verification，但标准必须提前声明方向。

## 20. Import / Export 是早期增长入口

Huoban 的第一个 killer use case 应该是 Profile import，而不是 Flow execution。

原因：大量 AI coding power user 已经拥有：

* `AGENTS.md`
* `CLAUDE.md`
* Cursor Rules
* 项目 prompt 文档
* 团队 coding rules

这些都是未标准化的墨。

Huoban 应提供迁移入口：

```bash theme={null}
huoban import AGENTS.md --as Profile --out profiles/project.yaml
huoban explain profiles/project.yaml
huoban validate profiles/project.yaml
huoban export profiles/project.yaml --to AGENTS.md
```

导入规则：

* 原始文本进入 `content`。
* 能识别的内容进入 `data`。
* 自动推断 layer，例如 `style`、`architecture`、`commands`、`testing`、`constraints`。
* 不确定内容保留在 `content`。
* 生成 `ImportUncertain` 或 `ImportNeedsReview` condition。
* 不自动丢弃原始文本。

反向导出也必须支持：

```bash theme={null}
huoban export profile.yaml --to AGENTS.md
huoban export profile.yaml --to CLAUDE.md
huoban export profile.yaml --to cursor-rules
```

这样可以降低采用风险，避免用户担心 lock-in。

## 21. SKILL.md 导入

Huoban 也应支持把现有 `SKILL.md` 导入成 Adapter / Skill 对象。

```bash theme={null}
huoban import path/to/SKILL.md --as Adapter
```

导入后：

* `description` 来自 frontmatter 或正文摘要。
* `content` 保留原始 SKILL.md。
* `capabilities` 可由规则或 AI 推断，但标记 review required。
* `sideEffects` 如果不能确定，标记 unknown。
* 默认生成 Adapter，而不是直接标记为 trusted Skill。
* 用户 review 后才能提升 trust level。

这会把现有 skill 生态变成 Huoban 的活字来源。

## 22. 第一条 Demo Flow

Huoban 的第一条 demo 不应该是复杂代码实现 flow。

更好的第一 demo 是：

```text theme={null}
idea-to-spec-review
```

它展示：

* `Skill`: `grill-me`
* `Profile`: `huoban-open-source-project`
* `Flow`: 从 idea 到 spec review
* `Run`: 一次具体执行
* `Checkpoint`: 等待用户确认方向
* `Artifact`: spec review / decision notes

这个 demo 的价值不是证明 Huoban 能跑任意 agent workflow，而是证明：

> 一个已有 skill 或外部能力可以被 Huoban 化，带着 profile 组成 flow，在 checkpoint 停住，并产出可检查 artifact。

这也形成强叙事：Huoban can print itself.

## 23. CLI 优先级

Huoban 的第一个 CLI 命令不应该是 `run`。

它应该是：

```bash theme={null}
huoban validate
```

原因：

* `run` 会让用户以为 Huoban 是 runner。
* `validate` 会让用户理解 Huoban 是 spec 和对象模型。

第一批 CLI 命令建议：

```bash theme={null}
huoban validate
huoban explain
huoban print --dry-run
huoban import
huoban export
```

暂时不要优先做：

```bash theme={null}
huoban run
huoban agent
huoban mcp serve
```

`print --dry-run` 可以预览一次“印刷”会怎么发生，但不真正执行复杂 agent workflow。

## 24. Schema 技术选择

Huoban v0.1 应采用 JSON Schema。

原因：

* 它是开放标准，不绑定 TypeScript、Go、HTTP 或某个 runtime。
* 它适合 YAML / JSON 工具链。
* 它容易被 GitHub、IDE、validator 和文档站消费。
* 它比 Zod 更中立，比 Protobuf 更轻，比 OpenAPI 更贴合对象模型，比 CUE 更低门槛。

建议结构：

```text theme={null}
schemas/v1alpha1/skill.schema.json
schemas/v1alpha1/profile.schema.json
schemas/v1alpha1/flow.schema.json
schemas/v1alpha1/run.schema.json
schemas/v1alpha1/checkpoint.schema.json
schemas/v1alpha1/artifact.schema.json
schemas/v1alpha1/adapter.schema.json
schemas/v1alpha1/policy.schema.json
schemas/v1alpha1/eval.schema.json
schemas/v1alpha1/registry.schema.json
```

## 25. README 策略

README 第一屏应先讲开发者问题，再展开文化叙事。

推荐顺序：

1. 一句话定位。
2. 开发者痛点。
3. 核心对象。
4. 活字印刷术隐喻。
5. Profile import 示例。
6. 最小 flow 示例。
7. Conformance levels。

第一屏示例：

```md theme={null}
# Huoban

An open orchestration protocol for AI systems:
可排版、可润墨、可印刷。

AI skills are scattered. Context is repeated.
Loops are hard to control. Workflows are hard to share.

Huoban turns them into reusable orchestration objects.
```

文化叙事很重要，但不要让它成为陌生开发者理解项目的第一道门槛。

## 26. 文档优先级

早期文档应优先迁移指南，再补完整规范。

首批文档建议：

1. `README.md`
2. `docs/import-agents-md.md`
3. `docs/import-claude-md.md`
4. `docs/import-cursor-rules.md`
5. `docs/import-skill-md.md`
6. `docs/profile-model.md`
7. `docs/flow-model.md`
8. `docs/object-model.md`
9. `docs/conformance.md`
10. `docs/trust-model.md`

原因：规范文档解释 Huoban 是什么，迁移指南回答用户现在能做什么。

## 27. 仓库策略

Huoban 应使用 mono repo，但 Phase 0 只填文档、spec、schema 和 examples。

建议结构：

```text theme={null}
README.md
HUOBAN_DESIGN_PHILOSOPHY.md
docs/
spec/
schemas/
examples/
```

预留但不急着实现：

```text theme={null}
cli/
mcp/
adapters/
runtime/
registry/
```

这传达的信息是：

> Huoban is a standard first, runtime later.

不要单独创建 `huoban-spec` 仓库。项目应从第一天就叫 `huoban`，只是阶段上先做标准。

## 28. 开源项目形态

Huoban 早期应外在像开发者工具，内核像标准组织。

也就是：

* README 要像工具项目：清楚、直接、有例子。
* Spec 要像标准项目：对象模型、schema、兼容等级。
* CLI 要像参考实现：validate、explain、import、export、dry-run。
* MCP 要像生态入口：让不同 agent 能接入。
* Adapter 要像增长飞轮：把已有生态吸进 Huoban。

一句话：

> 用工具吸引人，用标准留下人。

## 29. 成功指标

Huoban 早期不应把 GitHub stars、npm downloads、Discord 人数当作核心指标。

更好的 north-star metric 是：

> Number of external Huoban objects authored by non-core contributors.

也就是外部用户开始写：

* `Flow` examples
* `Profile` examples
* `Skill` specs
* `Adapter` specs
* 第三方 validator
* 第三方 runtime 实验
* capability taxonomy 讨论
* object boundary 讨论

这说明 Huoban 正在变成语言，而不只是工具。

## 30. 当前阶段结论

当前阶段不要急着写 Phase 0 实现。

正确顺序是：

1. 固化官方愿景与策略文档。
2. 固化设计哲学文档。
3. 梳理对象模型文档。
4. 梳理 Profile import / export 文档。
5. 梳理 Trust Model 和 Conformance 文档。
6. 再创建 Phase 0 仓库骨架。
7. 最后开始 schema 和 CLI reference implementation。

Huoban 的第一步不是写更多代码，而是建立一套足够清晰、足够专业、足够可传播的标准语言。

## 31. 总结

Huoban 的战略方向可以压缩为几句话：

* Huoban 是 AI 原生编排的对象模型层。
* Huoban 的护城河是对象模型和描述语言，不是 runtime。
* Huoban 第一批用户是 AI coding power user。
* Huoban 第一个 killer use case 是 Profile import，而不是 Flow execution。
* Huoban 应采用声明式资源对象模型、JSON Schema、spec/status/conditions、generation/observedGeneration 和 Run snapshot。
* Huoban 应一次性定义完整对象宇宙，但通过 conformance levels 降低采用门槛。
* Huoban 应把现有 AGENTS.md、CLAUDE.md、Cursor Rules 和 SKILL.md 视为可迁移资产，而不是竞争对象。
* Huoban 应优先适配现有生态，而不是重造所有 skill。
* Huoban 应从第一版写入 trust、policy、side effects 和 checkpoint。
* Huoban 的文化隐喻不是装饰，而是项目结构的一部分。

最终定位：

> Huoban 是 AI 系统的开放编排协议：**可排版、可润墨、可印刷**。它把 skill 变成活字，把 context 变成墨方，把 flow 变成版式，把 run 变成锁版印刷，把 checkpoint 变成校对，把 policy 变成印坊规矩，把 adapter 变成异形活字的标准化边界，把 registry 变成字架，把 loop 变成有校样标准的试印循环。