文档分层

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

文档的五个核心层次

各层写作准则与内容契约

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

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

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

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

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

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

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

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

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

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

维护者专属辅助层

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

跨层链接规范

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

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

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