FND-002：有意识的文档编写：标准、结构与国际化策略

自 v0.7.0 起 · 类型：文档 · 修订版 7

规范参考 · 经团队批准 · 修订版 7 原始 RFC 讨论：\#5576

在你们阅读此内容之前，给团队的一条提示。

文档不是你在代码完成之后才写的东西。它本身就是一个产品界面,是项目与每一位将来会为其贡献、使用或基于它进行开发的人之间的接口。一个没有文档的代码库,会迫使每一个新人从零开始重新摸索一切。而一个文档糟糕的代码库往往更糟,因为它会给人带来虚假的信心。本 RFC 提议以我们应用于架构的同样的用心来对待文档:先有愿景,再有结构,最后才是内容。

目录

1. 文档理念
2. 诚实评估：我们目前的状况
3. 分类框架：EA 工件在页面上
4. 国际化问题
5. 仓库 / Wiki 分离
6. ADR 标准
7. AGENTS.md 作为 AI 开发层
8. 目标结构
9. 替换文档契约
10. 我们应采用的标准
11. 分阶段路线图

修订历史

Foundation 修订政策

Foundation 修订元数据会保留已纳入批准基线的草案修订，并记录批准后规范性决策的演变。当合并的更改影响架构、必需流程、发布契约、贡献者行为或权威源的所有权时，应推进显示的修订号，并新增一行按时间顺序排列的记录。后续的反转属于单独的修订，因为这两种状态先后都对项目具有约束力。未纳入批准、仅涉及问题的草案不计入。

对于不会改变契约的移动、格式调整、标点修改、标题规范化、链接修复或路径更新，不要提升修订号。当基础文档明确将操作细节委托给另一个受维护的来源时，仅限于这些细节的更改不会导致基础文档修订。

显示的两个修订值以及本地修订历史记录中的最高修订行必须在同一变更中一并更新。通过修订添加的行保留该修订分配的修订日期。稍后回填历史记录时，使用变更进入 master 的日期。

1. 文档哲学

文档问题几乎总是源于在撰写第一句话之前跳过了一个本应提出的问题：这份文档是什么类型，它的目标读者是谁？

如果没有对这一问题的解答，文档就会堆积成一大堆页面，它们都属于同一个模糊类别的不同变体：“关于项目的资料”。设置指南与架构决策并列，面向用户的使用指南与内部编码规范并存。README 的三十种语言翻译与安全策略文档争夺空间。没有人能找到任何东西，所有内容以不同的速度过时，每一个涉及文档的 PR 都变成了一场关于哪些页面需要更新的谈判。

修复方法不是编写更多文档。修复方法是，在编写任何内容之前，先确定你要创建的工件类型。类型决定了格式、受众、位置、生命周期以及谁负责保持其最新状态。一旦确定了类型，其余部分自然会随之而来。

本 RFC 采用 Svyatoslav Kotusev 提出的 EA Artifacts on a Page 框架（https://eaonapage.com）作为所有 ZeroClaw 文档的分类视角。该框架基于实证、刻意保持非规定性，并能直接映射到一个开源基础设施项目实际所需的各类文档。

该团队正在采用的更广泛开发哲学中借用的核心原则：

文档和代码一样，应该沿着“愿景 → 架构 → 设计 → 实现”这条路径向上追溯。如果在动笔之前无法明确文档的类型及其目标读者，说明你尚未准备好开始撰写。

2. 诚实评估：我们目前的状况

2.1 i18n 的影响范围

当前文档中最容易衡量的问题是本地化系统：

i18n 系统会在每篇文档 PR 中产生贡献者税。当前的 docs-contract.md 包含此要求：

如果某项更改涉及文档 IA、运行时契约引用或共享文档中面向用户的措辞，请在同一 PR 中为受支持的本地化语言执行 i18n 跟进。

这意味着，修复安装指南中拼写错误的贡献者必须更新多达六种语言版本的文档，否则该 PR 将无法通过审查。这对贡献者来说是一个显著的障碍，尤其是对于构成该项目贡献者主体的学生和初级工程师而言。

2.2 结构问题

当前的 docs/ 目录结构在同一层级中混合了三种本质上不同的文档类型：

• 与代码相关的文档，必须与代码库同步版本控制（架构决策记录 ADR、API 规范、安全策略、贡献流程）
• 用户可见的操作文档，应与代码发布独立更新（安装指南、故障排除、部署指南等）
• 社区文档：由社区维护，无需正式审核流程（翻译、常见问题解答、社区指南）

这三个文件都位于 docs/ 目录下，它们之间没有结构上的区分。结果是一个扁平的堆，其中包含一个手动维护的 SUMMARY.md，每次发生任何更改时都需要有人去更新它。

2.3 ADR 差距

在撰写这份 RFC 时，项目在旧文档树中已有两份架构决策记录：用于 WASM 插件的 ADR-003，以及用于工具共享状态所有权的 ADR-004。ADR-004 尤其是一个很好的范例：结构清晰、引用了代码、具体明确。但项目至少已经做出了五六项同等甚至更重大的架构决策，却从未被记录下来：

• 选择 Rust 而非 TypeScript
• 基于特性的可扩展性模型
• WASM 插件系统设计
• 后端无关的内存存储契约和 SQLite 默认实现
• 安全模型（配对码、自主级别、沙盒层）

如果没有这些记录，每位新贡献者都必须通过代码考古来重新发现背后的原因。每个读取代码库的 AI 编程助手都只能知道“是什么”，而无法了解“为什么”。这是未记录的技术债务中最昂贵的一种形式。

2.4 已经做得好的部分

docs-contract.md 这个概念，把文档视为受治理的产品表面，是正确的方向。它只是还需要合适的规则。根目录下的 AGENTS.md 非常出色，为 AI 辅助开发树立了恰当的先例。ADR-004 证明了团队能够编写高质量的架构记录。

3. 分类框架：EA 工件在一页上

EA 页面工件框架定义了五类架构工件。ZeroClaw 仓库中的每份文档都应归属于其中一类，而该类别决定了其存放位置、格式以及何时失效。

该表格中明显缺失的内容包括： 用户指南、安装说明、特定频道的操作指南、故障排除、常见问题解答。这些属于操作内容，而非 EA 产物。它们不会随代码一起进行版本控制，应放置在 GitHub Wiki 上。

使用框架

在编写任何文档之前，请先回答以下两个问题：

1. 这是什么制品家族？ 如果你无法回答这个问题，说明你还没有准备好进行编写。
2. 是否需要与代码一起进行版本控制？ 如果是，则将其放入代码仓库中。如果不是，则将其放在 Wiki 上。

一个有用的测试标准是：如果读者对照代码库的不同版本阅读此文档，该文档是否会变得错误或产生误导？ 如果是，则文档应存放在代码仓库中，并与代码一起进行版本管理；如果否，则文档应存放在 Wiki 上。

4. i18n 问题

4.1 移除参数的理由

从仓库中移除所有非英文内容的理由基于以下四个支柱：

1. 受众可以随时获得翻译。 ZeroClaw 的主要用户是运行 AI 助手的人。每一个这样的用户都能即时获得高质量的机器翻译，无论是通过他们运行的代理、通过浏览器，还是通过数十种免费翻译服务中的任意一种。在代码仓库中提供翻译所带来的实际收益微乎其微。

2. 翻译内容几乎肯定已过时。 机器翻译的内容可能只生成过一次，且未与英文源文件保持同步。对于 AI 辅助开发而言，过时的文档比没有文档更糟糕，因为语言模型会基于过时信息自信地得出错误结论。

3. 贡献者税是真实且可衡量的。 docs-contract.md 的对等性要求意味着每个文档 PR 都必须涉及多达六种语言版本。这使得文档贡献变得昂贵，并阻碍了那些保持文档健康的小幅、增量改进（例如修复拼写错误、澄清步骤、更新过时的引用）。

4. 本地化是社区工作，而非核心项目工作。 最有能力维护日语文档的是日语贡献者。将本地化内容放在主仓库中并要求保持同步，会将负担转嫁给核心维护者，而不是受益的社区。GitHub Wiki 正确地反转了这一点：社区成员可以编辑和维护他们语言的页面，而无需提交 PR。

4.2 保持不变

值得保留的一点是：i18n 方法的结构。使 ZeroClaw 支持多种语言的理念是正确的。但位置和所有权模型是错误的。

4.3 替换策略

1. 从仓库根目录中删除所有 README.*.md 文件，除了 README.md

2. 完全删除 docs/i18n/

3. 从 docs/ 中移除所有非英文的 hub 文件（例如 docs/README.zh-CN.md）

4. 在主要的 README.md 中添加一个 Languages 部分：

   社区维护的翻译可在 GitHub Wiki 中找到。要贡献翻译或改进现有翻译，请直接编辑 Wiki。欢迎所有语言参与。

5. 在 GitHub Wiki 上创建一个 Translations 页面，其中包含可用语言列表、它们的完成度以及负责维护的贡献者

6. 可选： 添加 zeroclaw docs --translate CLI 功能，使用已配置的 LLM 提供方按需翻译任意文档页面，这对于一款核心用途即为 AI 辅助的产品而言是再合适不过的功能

4.4 AGENTS.md 的影响

从 docs-contract.md 中移除 i18n 后续处理要求。替换为：文档 PR 仅以英文进行审查。翻译由社区在 Wiki 上维护，不受 PR 审查约束。

5. 仓库与 Wiki 分离

5.1 决策规则

如果代码更改会导致文档内容过时，则该文档应位于仓库中；否则，应位于 Wiki 上。

这不是一个模糊规则。请逐字应用它。

仓库。 ADR 记录了在特定时间点做出某项具体架构决策的原因。即使代码发生变化，ADR 仍能准确描述当时所做出的决策及其时间。代码可能已偏离该决策，但记录本身依然准确。

这听起来应该放在仓库里，但其实不该。 配置 Telegram 频道的设置指南描述了用户针对当前版本软件所执行的步骤。如果配置格式发生变化，该指南就会过时。设置指南应当按照自己的节奏更新，而不应与代码提交绑定。正确的模式是：API 参考文档（直接映射到配置结构体）放在仓库里，而引导用户使用该 API 的设置指南则放在 Wiki 上，当步骤发生变化时任何人都可以更新。

5.2 实践中的拆分

保留在仓库中（docs/book/src/）：

移至 GitHub Wiki（提议中；尚未执行）：

已删除（i18n 移除）：

5.3 Wiki 结构

Home
│
├── Getting Started
│     ├── Installation
│     ├── Quick Start (TL;DR)
│     ├── Migrating from OpenClaw
│     └── Onboarding Walkthrough
│
├── Configuration
│     ├── Providers
│     ├── Channels
│     ├── Memory
│     ├── Security & Pairing
│     └── Tunnels
│
├── Channels
│     ├── Telegram
│     ├── Discord
│     ├── Slack
│     ├── WhatsApp
│     └── ... (one page per channel)
│
├── Operations
│     ├── Troubleshooting
│     ├── Deployment
│     ├── Network Setup
│     └── Performance Tuning
│
├── Hardware
│     ├── Getting Started with Peripherals
│     ├── ESP32 Setup
│     ├── STM32 Nucleo Setup
│     └── Arduino Setup
│
└── Community
      ├── FAQ
      ├── Translations
      └── How to Contribute

6. ADR 标准

6.1 格式

所有架构决策记录都使用 Nygard 格式，并通过 YAML frontmatter 扩展以便机器可读。ADR-004 是此 RFC 标识的模型。本节对该结构进行形式化说明。

每个 ADR 包含三个部分和五个前置元数据字段：

---
id: ADR-NNN
title: 描述决策的简短祈使句
date: YYYY-MM-DD
status: proposed | accepted | deprecated | superseded-by-ADR-NNN
relates-to:
  - ADR-XXX (可选，相关决策列表)
  - crates/zeroclaw-api (可选，受影响的代码路径)
---

# ADR-NNN: 标题

## 背景

导致需要做出决策的情况、约束或问题是什么？
当时存在哪些影响因素？考虑了哪些选项？

## 决策

做出了什么决定？使用主动语态陈述。
“我们将……”而不是“决定是……”

## 后果

该决策会带来哪些结果？
列出正面和负面的后果——每个决策都有权衡。
注明由此产生的任何后续决策或行动。

## 参考

相关代码文件、问题和外部资源的链接。

6.2 ADR 生命周期规则

• ADR 一旦被接受就不可更改。 如果决策发生变化，旧的 ADR 会被标记为 superseded-by-ADR-NNN，并编写一个新的 ADR 来描述新决策以及它为何取代了旧决策。
• ADR 按顺序编号，且永不重新编号。 序列中出现空缺是可以接受的（被拒绝的提议 ADR 可以撤回，从而留下空缺）。
• ADR 存放在 docs/book/src/architecture/decisions/。 它们命名为 ADR-NNN-short-slug.md。
• 重大的架构变更需要一份架构决策记录（ADR）。“重大”意味着：对新手贡献者而言令人意外的决策、对未来选择产生约束的决策，或涉及非直观权衡的决策。

6.3 基础 ADR 集

以下基础性决策和路线图目标都有长期有效的 ADR。ADR-001 至 ADR-005 是对现有架构的追溯性记录。ADR-006 和 ADR-007 描述了 FND-001 中受实现门控的目标，在相应边界完成交付之前应保持为 proposed 状态。

事后 ADR 应添加备注：

这是一份对正式 ADR 流程之前做出的决策的追溯性记录。日期反映的是决策做出的时间，而非本记录撰写的时间。

如果原始决策日期未知，请使用添加 ADR 记录的日期，并在注释中说明。如果追溯性的 ADR 已被后续决策取代，请保留历史 ADR，并单独编写取代它的 ADR。

6.4 为什么这对 AI 辅助开发很重要

当 AI 编程助手读取一个仓库时，它看到的是当前的代码状态。它无法看到被拒绝的选择、权衡过的利弊，或是为何选择某种特定结构而非其他替代方案的原因。如果没有架构决策记录（ADRs），AI 会提出违反其无法获知的架构约束的更改建议。而有了 ADRs，推理过程变得明确且机器可读。通过 frontmatter，ADRs 变得可查询：AI 工具可以找到所有与 zeroclaw-api 相关的 ADRs，并在编辑该 crate 之前将其作为上下文加载。

7. AGENTS.md 作为 AI 开发层

7.1 模式

根 AGENTS.md 是项目为 AI 辅助开发提供的精简、始终加载的约定。它统管项目范围内的安全、隐私、授权、贡献与验证策略。架构与贡献映射将复杂任务路由到相关的来源，而编码代理指南则保存可选的细节，例如示例、当前稳定性分配、技能发现以及受保护的操作文档。这种分层约定在保持具体且有明确主张的同时，无需将每个细节都加载到每个会话中。

随着工作区分解为多个 crate（依据微内核架构 RFC），每个 crate 都应拥有自己的 AGENTS.md。借此机制，架构边界不仅能在编译期通过 crate 依赖关系得以强制实施，更能在 AI 辅助层、即编写任何代码之前的推理层就成为可执行的约束。

7.2 每个 crate 的 AGENTS.md 包含的内容

保持简短。超过 60 行的 AGENTS.md 将不会被阅读。每个文件回答五个问题：

# <crate-name>

## What this crate is
One or two sentences. What problem does this crate solve?

## What this crate is allowed to depend on
List the crates this crate may import. Be explicit.
If a dependency is not listed here, do not add it without an ADR.

## Extension points
Where can new implementations be added? What trait do they implement?
Link to the relevant traits.

## What does NOT belong here
Explicit anti-patterns. What would be a mistake to add to this crate?

## Related ADRs
- ADR-NNN: Short title

7.3 示例

对于 crates/zeroclaw-api（提取后）：

# zeroclaw-api

## What this crate is
Trait definitions and shared data types for the ZeroClaw plugin and kernel
interfaces. This is the contract layer. Everything else depends on it.

## What this crate is allowed to depend on
- serde, serde_json (serialization)
- async-trait (async trait support)
- anyhow (error types)
- tokio (async runtime types, minimal)
Nothing else. No HTTP clients. No database drivers. No external services.

## Extension points
All traits in this crate are extension points:
- `Provider` (src/providers/traits.rs) — LLM provider implementations
- `Channel` (src/channels/traits.rs) — messaging platform integrations
- `Tool` (src/tools/traits.rs) — agent tool implementations
- `Memory` (src/memory/traits.rs) — persistence backends
- `Observer` (src/observability/traits.rs) — observability backends
- `RuntimeAdapter` (src/runtime/traits.rs) — execution environments
- `Peripheral` (src/peripherals/traits.rs) — hardware integrations

## What does NOT belong here
- Any concrete implementation of any trait
- Any dependency on a specific messaging platform, LLM provider, or database
- Any network I/O or filesystem access
- Any binary or executable target

## Related ADRs
- ADR-002: Trait-driven extensibility

对于 crates/zeroclaw-kernel（提取后）：

# zeroclaw-kernel

## What this crate is
The orchestration engine. Runs the agent loop, manages the service registry,
exposes the local IPC API. The kernel knows nothing about specific channels,
providers, or tools — only their abstract interfaces.

## What this crate is allowed to depend on
- zeroclaw-api (traits only)
- zeroclaw-tool-call-parser (parsing, no agent state)
- Standard async/runtime crates (tokio, anyhow, tracing)
- Config and storage crates (toml, serde, rusqlite for core memory)
NOT: any specific channel, provider, or tool implementation crate.

## Extension points
- `Registry::register_channel()` — add a channel at startup
- `Registry::register_tool()` — add a tool at startup
- `Registry::set_provider()` — set the active provider at startup
Implementations are registered by the binary crate, not by the kernel.

## What does NOT belong here
- Any import of TelegramChannel, DiscordChannel, or any named channel
- Any import of AnthropicProvider, OpenAIProvider, or any named provider
- Any tool implementation beyond the 10-12 designated core tools
- The gateway HTTP server or any web serving code

## Related ADRs
- ADR-002: Trait-driven extensibility
- ADR-006: Optional channels migrate to runtime plugins
- ADR-007: Gateway extraction into a separate optional binary

7.4 AGENTS.md 层级结构

根目录的 AGENTS.md 设置了简洁的全项目策略。架构与贡献地图将任务路由至已维护的架构、基础、测试、安全和维护者资源。编码智能体指南提供详细的全项目示例和注册表，可按需使用，但不属于始终加载的引导程序。

crate 级别的 AGENTS.md 文件会针对其特定作用域细化该策略。当 AI 工具读取 crates/zeroclaw-api/ 中的文件时，它应读取根契约，按照该任务的架构映射执行，并在存在时读取 crates/zeroclaw-api/AGENTS.md。crate 策略更具体，并在其作用域内优先适用，但它不能削弱项目范围内的安全、隐私或授权要求。

8. 目标结构

在 mdBook 迁移之后，仓库中与代码相邻的文档源布局为：

docs/book/src/
│
├── README.md                    ← mdBook introduction
├── SUMMARY.md                   ← Canonical mdBook TOC
│
├── architecture/
│   ├── overview.md              ← Current system landscape
│   ├── decisions/               ← ADRs (immutable once accepted)
│   │   ├── ADR-001-rust-first.md
│   │   ├── ADR-002-trait-driven-extensibility.md
│   │   ├── ADR-003-wasm-plugin-model.md
│   │   ├── ADR-004-tool-shared-state-ownership.md
│   │   ├── ADR-005-pluggable-memory-backends.md
│   │   ├── ADR-006-runtime-channel-plugins.md
│   │   ├── ADR-007-gateway-extraction.md
│   │   └── ADR-009-wit-wasmtime-plugin-execution.md
│   └── diagrams/
│       ├── component-map.md     ← Mermaid: crate topology
│       └── data-flow.md         ← Mermaid: message lifecycle
│
├── contributing/
│   ├── index.md
│   ├── architecture-map.md
│   ├── rfcs.md
│   ├── testing.md
│   └── pr-review-protocol.md
│
├── reference/
│   ├── index.md
│   ├── cli.md
│   ├── config.md
│   └── providers.md
│
├── security/
│   ├── overview.md
│   ├── model.md
│   ├── sandboxing.md
│   └── tool-receipts.md
│
├── hardware/
│   ├── index.md
│   ├── subsystem.md
│   ├── adding-boards-and-tools.md
│   └── hardware-peripherals-design.md
│
└── foundations/
    ├── fnd-001-intentional-architecture.md
    ├── fnd-002-documentation-standards.md
    ├── fnd-003-governance.md
    ├── fnd-004-engineering-infrastructure.md
    ├── fnd-005-contribution-culture.md
    └── fnd-006-zero-compromise-in-practice.md

从当前结构中删除：

docs/i18n/                       ← 169 files, 2.2 MB — removed entirely
docs/maintainers/                ← project snapshots and i18n coverage maps
                                   moved to Wiki (operational, not code-adjacent)
docs/setup-guides/               ← moved to Wiki
docs/ops/                        ← moved to Wiki
README.ar.md (and 30 others)     ← removed from repo root
docs/README.ar.md (and 30 others)← removed

仓库根目录变为干净状态：

README.md
AGENTS.md
CHANGELOG.md
CLAUDE.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
SECURITY.md
LICENSE-APACHE
LICENSE-MIT
NOTICE
Cargo.toml
Cargo.lock
... (build and config files)

不包含语言变体，不重复 README 文件。一个权威的英文 README 链接到用户指南的 Wiki 和技术参考的 docs/ 目录。

9. 替换文档合同

旧的 docs/contributing/docs-contract.md 编码了 i18n 对等性要求和目录结构，本 RFC 已取代这些内容。该文件已被移除；本节是其替代内容。

该替换方案管理三件事：制品分类、repo/wiki 拆分，以及 ADR 治理。它对 i18n 不作任何规定：语言区域的对等性现由 Maintainers → Docs & Translations 页面负责。

替换文档契约：

# Documentation Contract

## Document Classification

Every document in `docs/` belongs to one artifact family:

- **Considerations** — principles and standards that guide decisions
- **Landscapes** — descriptions of the current system state
- **Outlines** — proposals and roadmaps for future work
- **Designs** — ADRs, API specs, and detailed technical decisions
- **Standards** — specific rules for how we build and operate

If you cannot name the family before writing, do not write yet.

## The Repo / Wiki Rule

A document lives in the repository if it would become wrong when the
code changes. It lives on the Wiki if it would not.

Reference documentation (config reference, CLI reference) lives in the
repository because it maps directly to code structures.

User guides, setup instructions, and operational how-tos live on the Wiki
because they update on their own timeline.

## ADR Governance

See `docs/book/src/architecture/decisions/` for the ADR format and lifecycle rules.

Major architectural changes require an ADR before implementation begins,
not after.

## Language

All documents in this repository are written in English.
Community-maintained translations live on the GitHub Wiki.
Documentation PRs are reviewed in English only.

## Freshness

Documents should be updated in the same PR as the code change that makes
them stale. A PR that changes a configuration format must update the
config reference. A PR that adds a new command must update the CLI reference.

RFC issues and roadmap trackers are exempt - they describe intent and
may precede implementation by multiple releases.

10. 我们应该采用的标准

这些文档特定的标准补充了架构 RFC 中提出的更广泛的标准。

Diátaxis 框架（文档结构）

它是什么： Diátaxis（https://diataxis.fr）是一套系统化的技术文档框架，将内容分为四种类型：教程、操作指南、参考和说明。它是 Python 文档、Django 文档以及许多其他文档背后所采用的文档框架。它与 EA Artifacts 方法高度兼容：二者回答的是不同的问题（Diátaxis：如何组织文档的内容；EA Artifacts：这是什么类型的文档以及它应放在何处）。

如何应用： 面向用户维基上的文档应遵循 Diátaxis 结构。代码相关的仓库文档遵循 EA Artifacts。这两个框架在不同的层面上运作，并不冲突。

用于机器可读性的 Markdown Frontmatter

docs/ 目录中的所有文档都应包含 YAML frontmatter。这使得它们可以被 AI 工具、CI 检查以及未来的工具查询：

---
类型: adr | 提案 | 参考 | 贡献 | 安全 | 硬件
状态: 草稿 | 提议 | 已接受 | 已弃用 | 已取代
上次审查: YYYY-MM-DD
relates-to:
  - ADR-NNN
  - crates/zeroclaw-api
---

CI 检查应验证 docs/ 中的所有文档都具有有效的 frontmatter。这可以防止在未先声明文档类型和状态的情况下编写文档，从而在工具层面强制执行分类规范。

CommonMark + GitHub 风格 Markdown

所有文档均使用 CommonMark（标准化的 Markdown 规范）以及 GitHub Flavored Markdown 扩展（包括表格、任务列表、围栏代码块和 Mermaid 图表）。不使用任何自定义扩展、MDX 或 ReStructuredText。对于架构图，推荐使用 Mermaid 图表而非图像文件，因为它们能够与代码一起进行版本控制。

用于 Prose Linting 的 Vale

它是什么： Vale（https://vale.sh）是一款散文检查工具：它使用可配置的规则来检查写作风格、一致性和可读性。它可以强制执行诸如此类的规则：始终使用 “you” 而非 “the user”、在祈使语句部分避免使用被动语态、使用一致的术语（“plugin” 而非 “extension” 或 “module”）。

为什么重要： 当前文档在语气、术语和风格上不一致。有些页面使用“插件”，有些使用“模块”，还有些使用“扩展”。Vale 使这些规则自动化，并在 CI 阶段强制执行，就像 Clippy 强制执行代码质量一样。

11. 分阶段路线图

文档迁移遵循与架构迁移相同的绞杀榕模式：增量式、始终处于可用状态，避免一次性重写。

阶段 1 · v0.7.0：“清理根目录”

交付物：

• 从仓库根目录移除所有 README.*.md 文件（仅保留 README.md）
• 完全移除 docs/i18n/
• 从 docs/ 中移除所有非英文的 hub 文件
• 在 README.md 中添加 Languages 部分，并附上 Wiki 链接
• 创建 GitHub Wiki，包含结构骨架（主页 + 顶级页面、内容占位符）
• 从 docs-contract.md 中移除 i18n 对等性要求
• 为所有现有的 docs/ 文件添加 YAML 前置元数据
• 创建 docs/book/src/architecture/decisions/，添加 ADR-001 和 ADR-002，恢复 ADR-003 和 ADR-004，并将 ADR-009 作为 ADR-003 的后续替代 WIT/wasmtime 记录添加

成功指标：

• 仓库根目录仅包含一个 README 文件
• docs/i18n/ 目录不存在
• 所有 docs/ 文件均包含有效的 YAML frontmatter（由 CI 强制执行）
• GitHub Wiki 已上线，并从 README 中公开链接

阶段 2 · v0.7.0–v0.8.0：“补写缺失的 ADR”

交付物：

• 将 ADR-005 编写为当前内存存储契约的追溯记录
• 为受实现门控的 FND-001 目标编写拟议的 ADR-006 和 ADR-007 记录
• 添加 Vale 配置（.vale.ini + 样式规则）和 CI 检查
• 用第 9 节中指定的版本完整替换 docs-contract.md
• 将 docs/setup-guides/ 的内容迁移到 GitHub Wiki
• 将 docs/ops/ 的内容迁移到 GitHub Wiki
• 更新 SUMMARY.md 以反映新的结构（仅仓库内容）
• 为 crates/zeroclaw-api 编写根级 AGENTS.md（为后续提取做准备）

成功指标：

• ADR-001 至 ADR-007 均已存在，并分别处于适当的已接受、已提议或已取代状态
• ADR-009 记录了取代 ADR-003 的 WIT/wasmtime 决策
• Vale CI 检查在所有文档中均通过
• Wiki 包含所有迁移部分的完整内容
• docs/ 中无死链

阶段 3 · v0.8.0–v0.9.0：“AI 层”

交付物：

• 为工作区中的每个新 crate 编写 AGENTS.md 文件（按照架构 RFC 的各个阶段逐步分解）。
• Write docs/book/src/architecture/diagrams/component-map.md（Mermaid，反映目标 crate 拓扑）
• 编写 docs/book/src/architecture/diagrams/data-flow.md（Mermaid，消息生命周期）
• 在 docs/book/src/developing/plugin-sdk.md 中编写插件 SDK 文档
• 在 wit/ 目录下的文件旁编写 WIT 接口文档（由 WIT 自动生成并辅以手动编写的说明）
• 随着内核 IPC API 的稳定，更新 OpenAPI 规范文档

成功指标：

• 工作区中的每个 crate 都包含一个 AGENTS.md
• 架构图使用 Mermaid 格式（docs/ 目录中不包含二进制图像文件）
• 插件 SDK 文档对于外部贡献者编写一个可用的工具插件来说已经足够。

阶段 4 · v1.0.0：“稳定平台”

交付物：

• 一旦相应代码发布，将 ADR-006 和 ADR-007 标记为 accepted
• 在 v1 版本中对内核 IPC API 文档进行版本控制，并提供稳定性保证
• 编写 Plugin Registry 治理文档（谁控制注册表、如何审查插件、如何撤销已被攻破的插件）
• 将插件 SDK 发布为独立文档站点（源自 docs/book/src/developing/plugin-sdk.md）
• 设立 Wiki 翻译协调员角色（由社区成员担任，负责维护翻译页面并协调志愿者翻译人员）

成功指标：

• 所有基础 ADR 均已接受
• 插件 SDK 已完成，并从 README 中外部链接。
• Wiki 拥有至少两种语言的活跃社区维护翻译
• 文档 CI（frontmatter 检查 + Vale）在每个 PR 上都会通过

附录 A：术语表

ADR（架构决策记录）：对重大架构决策的不可变记录，包括促成该决策的背景、所做的决定以及由此带来的影响。ADR 一经接受便不再更改；被取代的决策会以新的 ADR 形式记录下来。

Diátaxis：一种用于组织技术文档结构的系统化框架，它将内容划分为教程（学习导向）、操作指南（目标导向）、参考（信息导向）和解释（理解导向）。参见 https://diataxis.fr。

EA Artifacts on a Page：由 Svyatoslav Kotusev 开发的企业架构文档分类框架。将工件分为五大类：Considerations、Landscapes、Outlines、Designs 和 Standards。参见 https://eaonapage.com。

Frontmatter：位于 Markdown 文件顶部的 YAML 元数据，以 --- 分隔。使文档可被工具、CI 检查和 AI 助手读取和查询。

Nygard 格式：由 Michael Nygard 引入的 ADR 格式：包含三个部分（Context、Decision、Consequences），在不增加冗余形式的情况下记录核心推理过程。

绞杀者无花果模式（Strangler Fig Pattern）：一种迁移策略，围绕旧结构逐步构建新结构，逐块替换而非一次性全部替换。整个迁移过程中系统始终保持可用。

Vale：一款用于技术文档的文本检查工具。它在 CI 阶段强制执行样式、一致性和可读性规则，就像 Clippy 强制执行 Rust 代码质量一样。参见 https://vale.sh。

附录 B：延伸阅读

• Diátaxis 文档框架：按类型组织技术文档的权威参考。
• EA Artifacts on a Page (v2.2)：第 3 节中使用的分类框架。
• 《Docs for Developers》：Jared Bhatti 等著：一本实用的技术文档指南，由维护过大型文档系统的工程师们撰写。
• Vale 文档：第 10 节中提出的文章检查工具的安装指南和配置参考。
• Michael Nygard 关于 ADR 的文章：介绍第 6 节所用 ADR 格式的原始文章。
• GitHub Wikis 文档：用于设置和管理第 5 节中提议的 GitHub Wiki 的参考资料。

本提案基于对 ZeroClaw 文档系统在 v0.6.8 版本的直接分析。所引用的指标（169 个 i18n 文件、2.2 MB、31 种语言版本的 README）均基于直接测量。建议内容反映了开源基础设施项目技术文档中的成熟实践，并针对 ZeroClaw 的具体约束和目标进行了适配。

欢迎提供反馈、更正和替代方案。优秀的文档是社区共同努力的成果，而最好的结构是团队能够实际维护的那一种。