---
title: 文档分层
summary: 明确文档修改的归属层次，将面向用户的解释与内部运行时规格严格区分开。
order: 30
aliases:
  - /zh-CN/concepts/documentation-layers
  - /zh-CN/concepts/documentation-layers.md
---

<a id="documentation-layers"></a>

# 文档分层

在修改文档时，依照这套分层标准来确定改动应落入哪个位置。用户说明、任务操作指引、精确接口契约与内部实现规格面向不同的读者。关于编辑与本地构建步骤，请参阅[文档工作流](documentation-workflow.md)。

<a id="the-five-documentation-layers"></a>

## 文档的五个核心层次

| 层次 | 目标读者 | 回答的核心问题 | 属于本层的内容 | 不属于本层的内容 |
|---|---|---|---|---|
| **入门指南** (`/getting-started/`) | 新用户与技术评估者 | *“我如何用 Holon 跑通第一个有效结果？”* | 最短路径安装、新手引导、首次 Agent 交互、快速结果核验、进阶路径引导 | 完整的 CLI 命令树、全部配置项编目、全量 API 端点、内部状态模型 |
| **概念** (`/concepts/`) | 终端用户与集成开发者 | *“Holon 的心智模型是什么？为何这样设计？”* | 稳定对象（Agent、WorkItem、Task、Workspace）、信任边界、记忆机制、上下文连续性、可观察的不变量 | 分步实操指令、精确参数/端点清单、内部模块/结构体细节、容易变动的调度机理 |
| **操作指南 (How-to)** (`/guides/`) | 实际操作人员与运维者 | *“我该如何完成某项具体任务？”* | 以任务为导向的工作流：目标、前置条件、分步可复现命令、结果验证、故障排查、相关链接 | 全量参数参考大表、内部调度器算法、架构方案论证 |
| **参考** (`/reference/`) | 用户、集成开发者与运维者 | *“这个参数、端点或配置项的权威定义究竟是什么？”* | CLI 命令树、配置 Schema、HTTP 控制平面端点、模型编目、工具 Schema、状态枚举 | 叙事性教程、入门路径、架构设计背景、内部底层状态机 |
| **规格 (Spec)** (`/spec/`) | 维护者与内核贡献者 | *“后续改动必须严格遵守的内部运行时契约是什么？”* | 调度器状态机、执行根不变量、任务生命周期契约、内部安全隔离边界 | 新手引导、宣传与通俗叙事、快速上手步骤 |

<a id="layer-guidelines-content-contracts"></a>

## 各层写作准则与内容契约

<a id="1-getting-started-first-success"></a>

### 1. 入门指南 —— 首次交付

- **目的：** 带领新用户从环境安装顺利走到获得经核实的 Agent 交付结果。
- **格式：** 最精简的命令、明确的前置条件、具体的预期输出展示，以及清晰的下一步指引。
- **准则：** 绝不要把大段的参数列表或内部目录结构堆砌在入门页面中。保持流程连贯顺畅。

<a id="2-concepts-user-facing-mental-models"></a>

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

- **目的：** 解释 Holon 的核心基石与可观察语义，使用户能够准确推断运行时的行为。
- **读者定位：** 普通用户与上层集成开发者，**而非**运行时内核开发者。
- **写作原则：**
  - **以读者为中心：** 为操作或基于 Holon 进行开发的人撰写。
  - **仅关注稳定语义：** 聚焦持久概念（例如 Agent 为什么跨轮次持久存在、工作项如何跟踪目标、信任边界隔离了什么）。
  - **不要把实现细节包装成概念：** 绝不要因为代码中存在某个 Rust 模块、结构体、数据库表或私有队列机制，就将其强加给普通用户。
  - **行为持久性检验：** 即使底层的队列实现或数据库存储被重写，概念页面的描述依然应当保持准确。
  - **引用而非重复：** 精确参数请链接至参考，维护者契约请链接至规格或 RFC。

<a id="3-guides-task-oriented-how-to"></a>

### 3. 操作指南 —— 任务导向实操

- **目的：** 解决具体的实际操作问题（例如“如何通过 HTTP 调用自动化？”、“如何配置 Prometheus 监控？”）。
- **标准结构：**
  1. **目标与背景：** 将要达成什么，以及何时选用该方案。
  2. **前置条件：** 开始前所需的依赖工具、密钥凭据或系统权限。
  3. **分步操作步骤：** 带有必要解释的最少且可复现的命令。
  4. **验证方式：** 如何确认任务已经成功完成。
  5. **故障排查：** 常见失败现象与对应的直接补救措施。
  6. **相关参考与概念：** 指向权威参考页面与背景概念的直接链接。
- **准则：** 指南页面仅提供精简的内联示例。完整的端点表格或全部配置 Schema 应当归属于参考。

<a id="4-reference-current-authoritative-contract"></a>

### 4. 参考 —— 当前权威契约

- **目的：** 语法、参数、端点与 Schema 定义的单一事实来源。
- **结构：** 标准化的表格与章节：作用域、语法/端点、参数/载荷、返回值、约束限制与稳定性说明。
- **准则：** 参考页面是基于已编译二进制产物核对的权威快照（`holon --help`、`holon config schema`、路由清单）。一旦参数或端点变更，优先更新参考。

<a id="5-spec-maintainer-runtime-contracts"></a>

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

- **目的：** 记录内核贡献者在修改代码时必须严格遵守的内部契约、生命周期状态迁移与系统不变量。
- **读者定位：** 开发和维护 Holon 代码库的贡献者。
- **准则：** 规格页面属于规范性技术契约，非面向终端用户的说明文档。面向普通用户的导航体系弱化展示规格页面，避免底层机制干扰新手。

<a id="supporting-maintainer-layers"></a>

## 维护者专属辅助层

- **`docs/rfcs/` (设计 RFC)：** 重大功能背后的权威设计原理、架构权衡与技术讨论。
- **`docs/implementation-decisions/` (架构决策记录 ADR)：** 在存在多个可行方案时，解释为何选择特定技术方案的轻量级决策记录。
- **`docs/archive/`：** 保留的历史文档，不再作为当前生效的技术规格。
- **`docs/website/maintainers/` (维护者工作流)：** 专门为修改 Holon 自身的人员提供的构建、测试与文档编写流程。

<a id="cross-layer-links"></a>

## 跨层链接规范

结构良好的文档应当通过跨层链接组织知识，而非跨层复制粘贴：

```
入门指南 ──> 操作指南（针对具体任务）
   │              │
   ▼              ▼
 概念 ─────────> 参考（获取精确参数与端点定义）
   │
   ▼（仅限维护者）
 规格 ─────────> RFCs / ADRs（查阅设计原由）
```

<a id="when-to-update-which-layer"></a>

## 变更类型与文档目标对应表

| 变更类型 | 优先更新的目标文档 | 需同步更新的交叉引用 |
|---|---|---|
| 新增 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/` 增加指向链接 |