---
title: 文档分层
summary: Holon 如何区分快速开始、概念模型、操作指南、功能参考与维护者运行时规格。
order: 20
---

# 文档分层

Holon 的文档划分为五个独立层级，具备明确的受众定义、问题导向与内容契约。
这样可以彻底避免用户心智模型、权威参考契约与内部运行时规格之间的漂移与混淆。

## 五个文档层级

| 层级 | 读者 | 核心回答的问题 | 适合放什么 | 绝不应该放什么 |
|---|---|---|---|---|
| **快速开始** (`/zh-CN/getting-started/`) | 新用户与评估者 | *“我如何用最短路径在 Holon 跑出第一个成功结果？”* | 最短路径安装、交互式引导、第一个 Agent 运行、结果验证、下一步分流 | 完整 CLI 命令树、全量配置键表、API 所有 endpoint、内部状态契约 |
| **概念** (`/zh-CN/concepts/`) | 用户与集成者 | *“Holon 的心智模型是什么？为什么这样设计？”* | 稳定对象模型（Agent、WorkItem、Task、Workspace）、信任边界、记忆系统、上下文连续性等稳定语义 | 逐步操作教程、具体 flag/endpoint 详表、内部模块/结构体名、易变的引擎实现细节 |
| **指南 (How-to)** (`/zh-CN/guides/`) | 实操用户与运维者 | *“我想达成具体任务 X，应该怎么做？”* | 任务导向工作流：目标场景、前置条件、逐步步骤、验证方法、常见排错、相关参考链接 | 完整参数字典、内部调度算法、设计争议与演进历史 |
| **参考** (`/zh-CN/reference/`) | 用户、集成者与运维者 | *“这个命令、配置项、endpoint 或工具参数的精确定义是什么？”* | CLI 命令树、配置项 schema、HTTP 控制面端点、模型编目、内置工具 schema、退出码字典 | 教程叙事、引导路径、架构选型理由、内部状态机实现 |
| **规格** (`/zh-CN/spec/`) | 维护者与贡献者 | *“运行时当前的内部契约是什么？代码变更必须保持哪些不变量？”* | 调度器状态机、执行根（execution root）不变量、任务生命周期契约、内部安全隔离 | 面向初学者的引导、产品营销叙述、入门教程 |

## 各层写作规范与内容契约

### 1. 快速开始 — 首次成功

- **目的：** 引导新用户在 15 分钟内从零安装并验证第一个运行中的 Agent。
- **要求：** 最简命令、前置条件清晰、给出明确预期输出，并提供下一步分支指引。
- **铁律：** 严禁在此处堆叠全量参数说明或内部仓库结构，保持主路径无干扰。

### 2. 概念 — 用户心智模型

- **目的：** 解释 Holon 的核心对象和用户可观察的语义，使用户能准确预期运行时行为。
- **读者：** 普通用户与外部集成者，**绝非** Holon 引擎的内核开发者。
- **核心治理原则：**
  - **以用户为中心：** 从使用和操作 Holon 的人出发，而非从代码模块出发。
  - **只讲稳定语义：** 聚焦稳定概念（例如 Agent 为什么持久、WorkItem 如何承载目标、信任边界如何防注入）。
  - **严禁把内部实现伪装成概念：** 绝不因为源码里有一个 Rust 模块、结构体、数据库表或私有队列，就强行让用户学习它。
  - **稳定性检验：** 即使底层队列或存储引擎重写，概念页面的说明也必须依然成立。
  - **链接而非复制：** 精确参数外链到 Reference，维护者契约外链到 Spec 或 RFC。

### 3. 指南 — 任务导向 How-to

- **目的：** 解决具体的任务目标（“如何通过 HTTP 集成？”、“如何接入 Prometheus 监控？”）。
- **统一页面结构：**
  1. **目标与场景：** 要完成什么、何时适用。
  2. **前置条件：** 所需环境、凭证或权限。
  3. **步骤说明：** 最小可复现的命令与简明解释。
  4. **验证方式：** 如何确认任务成功。
  5. **常见排错：** 常见失败原因与排查修复。
  6. **相关参考与概念：** 指向权威参考页和背景概念页的链接。
- **铁律：** 指南只包含完成任务所需的最小示例，全量端点或配置查阅统统链接到 Reference。

### 4. 参考 — 权威功能契约

- **目的：** 语法、参数、端点和 Schema 定义的唯一权威事实来源。
- **结构：** 统一的结构化呈现：作用域、语法/Endpoint、参数/载荷、返回值、限制约束、稳定性级别。
- **铁律：** 参考页必须基于编译出的二进制真实行为（`holon --help`、`holon config schema`、路由清单）核对与更新。

### 5. 规格 — 维护者运行时契约

- **目的：** 记录内部调度、执行根不变量、状态机流转等面向维护者和内核贡献者的规范契约。
- **读者：** 仓库贡献者与核心维护者。
- **铁律：** 规格页面是规范性技术契约，不面向普通用户。站点导航中弱化规格入口，避免干扰日常使用。

## 维护者设计支持层

- **`docs/rfcs/` (设计 RFC):** 记录重大特性的设计推演、架构动机与设计边界。
- **`docs/implementation-decisions/` (ADR):** 当存在多个可选方案时，记录为何做出特定选择的设计决策。
- **`docs/archive/`:** 历史归档资料，不再代表当前活跃规范。
- **`docs/website/maintainers/`（维护者流程）：** 面向修改 Holon 本身的人，包含构建、测试和文档维护流程。

## 跨层链接

优良的文档应当跨层相互链接，而不是重复拷贝细节：

```
快速开始 ──────> 指南 (处理具体任务)
   │                │
   ▼                ▼
 概念 ──────────> 参考 (查阅精确参数/接口)
   │
   ▼ (仅维护者)
 规格 ──────────> RFC / ADR (查阅设计理由)
```

## 何时更新哪一层

| 变更类型 | 首要更新目标 | 协同更新目标 |
|---|---|---|
| 新增 CLI 命令或选项 | `reference/cli.md` | 若属于核心操作流，同步相关 `guides/` 或 `getting-started/` |
| 新增 HTTP 控制面接口 | `reference/http-control-plane.md` | 同步对应场景的 `guides/` |
| 新增用户任务场景 | `guides/<task>.md` | 补充到 `reference/` 与 `concepts/` 的链接 |
| 核心对象模型或语义变化 | `concepts/<model>.md` | 涉及内部契约同步更新 `spec/`，接口同步 `reference/` |
| 内部调度算法或状态机调整 | `spec/<contract>.md` | 代码测试用例与维护者记录 |
| 架构选型与设计权衡 | `docs/rfcs/` 或 `docs/implementation-decisions/` | 从 `spec/` 引用 |