文档分层

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

五个文档层级

各层写作规范与内容契约

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 (查阅设计理由)

何时更新哪一层