文档生成流水线
ZeroClaw 文档将手写的 Markdown 与从 Rust 类型、命令定义、注册表、WIT 契约、工作流文件和 UI 元数据实体化而来的引用和代码片段相结合。生成的文件不是第二个可信来源:请修复其所属的源文件或生成器，然后重新构建文档。
当某项变更涉及 schema、CLI 标志、功能清单或硬件清单、插件契约、默认键位映射、主题注册表、mdBook 指令、生成的参考文档、文档门禁或部署工作流时，请使用此页面。对于配置值，请另行阅读 Config 生命周期。对于翻译输出，请继续参阅 本地化目录生命周期。
源到输出映射
| Surface | 规范源 | 物化器 | 输出 | 仓库状态 | 消费者 |
|---|---|---|---|---|---|
| 配置参考 | zeroclaw_config::schema::Config 加上 Configurable 派生 | cargo mdbook refs 或 cargo mdbook build，通过 markdown-schema | docs/book/src/reference/config.md | 已忽略的派生文件 | 配置参考章节和基于架构的指令 |
| CLI 参考 | src/main.rs 中的 Clap 命令树 | cargo mdbook refs 或 cargo mdbook build，通过 markdown-help | docs/book/src/reference/cli.md | 已忽略的派生文件 | CLI 参考章节 |
| 安装路径 | xtask/src/generate/spec.rs 中的类型化路由契约，以及安装程序渲染器中生成的行为主体 | cargo generate installers，通过 xtask/src/generate/docs.rs 和 xtask/src/generate/install_sh.rs | docs/book/src/_snippets/install.md、README 和平台指南中的 Unix 命令块、install.sh 中生成的路由和 picker-helper 区域，以及 docs/book/src/setup/windows.md 中的 Windows 预构建块 | 已跟踪的生成表面 | README 中链接的首次设置、可执行 Unix 路由、Quickstart 和平台设置页面 |
| SOP 语法参考 | parse_steps 语法目录位于 crates/zeroclaw-runtime/src/sop/mod.rs 和 ConditionOp::catalog() 中 | cargo generate sop-syntax，通过 xtask/src/generate/sop_syntax.rs | 已在 docs/book/src/sop/syntax.md 中标记解析器行为和条件运算符区域 | 已跟踪的生成区域 | SOP 编写参考 |
| Rust API 参考 | 跨工作区 crate 的公共 Rust 项 | cargo doc 在 cargo mdbook refs 或 cargo mdbook build 中 | target/doc/，复制到 docs/book/book/api/ | 已忽略的构建输出 | 已发布的 API 参考文档 |
| 功能矩阵 | 通道清单、模型提供商槽位、默认工具以及 docs/book/feature-matrix-parity.toml | xtask/src/cmd/mdbook/feature_matrix.rs 在本地化构建期间 | docs/book/src/_snippets/feature-matrix-*.md | 已忽略的派生代码片段 | 通过 {{#include}} 实现功能对比页面 |
| 硬件表格 | install.sh 中的硬件板卡注册表和工具目录、生成器中的传输描述、发布工作流目标以及低内存阈值 | xtask/src/cmd/mdbook/hardware.rs（在本地化构建期间） | docs/book/src/_snippets/hardware-*.md | 已忽略的派生代码片段 | 硬件和发布目标指南 |
| 插件契约值 | WIT 契约、插件指南和 src/plugin_registry.rs 限制 | 本地化构建期间的 xtask/src/cmd/mdbook/plugins.rs | docs/book/src/_snippets/plugin-*.md | 已忽略的派生代码片段 | 插件编写指南 |
| zerocode 键表 | apps/zerocode/src/keymap/actions.rs 中的默认按键映射 | xtask/src/cmd/mdbook/keymap.rs 在本地化构建期间 | docs/book/src/_snippets/zerocode-*-keys.md | 已忽略的派生代码片段 | zerocode 键绑定页面 |
| 对等组块 | docs/book/peer-groups.toml | xtask/src/cmd/mdbook/peer_groups.rs mdBook 预处理器 | 扩展章节内容 | 仅在构建时 | 使用 peer-group 指令的 Channel 和 peer-group 页面 |
| 主题 CSS 和名称 | web/src/contexts/themes.json | 在语言区域构建期间的 xtask/src/cmd/mdbook/themes.rs | 已忽略的 CSS/名称片段，以及已跟踪的 docs/book/theme/index.hbs 中的生成标记区域 | 混合：派生文件被忽略；标记之外的模板内容保持为已编写状态 | mdBook 主题选择器和 zerocode 主题参考 |
| 区域切换器 | locales.toml 和已跟踪的 docs/book/theme/lang-switcher.js.tpl | inject_lang_switcher_locales 在语言区域构建期间 | docs/book/theme/lang-switcher.js | 已忽略的派生文件 | 已发布的语言选择器 |
| 撰写的章节 | docs/book/src/**/*.md 和跟踪的代码片段 | mdBook 预处理器和渲染器 | docs/book/book/ 下的本地化/版本 HTML | 已跟踪的源文件，已忽略的输出 | 已发布的文档站点 |
| 仪表板 API 类型 | zeroclaw_gateway::openapi::build_spec() 和网关运行时类型 | cargo web gen-api | target/openapi.json、web/src/lib/api-generated.ts、web/src/lib/api-descriptions.ts 和 web/src/lib/api-enums.ts | 已忽略派生文件 | TypeScript 仪表板构建 |
此矩阵描述的是当前的高价值面，而非构建过程中生成的每个辅助文件。可复用的规则在于所有权：一个生成的值应当拥有一个规范输入和一条确定性的物化路径。
mdBook 组装顺序
cargo mdbook 是 .cargo/config.toml 中定义的 xtask 命令接口。其主要命令会组合构建流水线，而不是直接调用普通的 mdbook build。
cargo mdbook refs 从实时代码生成 CLI 和配置的 Markdown，构建工作区 rustdoc，并将 API 输出复制到文档构建树中。cargo mdbook build 执行完整的发布流程：
- 根据当前命令树和配置模式生成
reference/cli.md和reference/config.md。 - 构建工作区 rustdoc。
- 实体化主题、键映射、硬件、功能矩阵和插件代码片段。
- 针对
locales.toml中的每个语言环境运行一次 mdBook，并使用docs/book/book.toml配置的预处理器。 - 检查已渲染主语言环境中的链接。
- 将版本目录、语言区域重定向、rustdoc 树和共享主题资源汇集到
docs/book/book/下。
对等组预处理器在 mdBook 处理每个章节时展开其指令。其他标准 mdBook 预处理器负责处理链接、Mermaid 块和 gettext 本地化。因此，生成的引用需要在章节预处理之前存在，而指令展开和翻译则在区域设置构建期间进行。
文档部署工作流会初始化翻译子模块、安装所需的 mdBook 工具、运行 cargo mdbook build，并将组装好的版本合并到 gh-pages 分支。它在部署期间不会调用翻译提供程序或修复目录。
已跟踪输出和仅构建输出
已跟踪的文件是可供审阅的输入或模板：撰写的 Markdown、locales.toml、docs/book/peer-groups.toml、功能矩阵一致性元数据、主题模板、Rust/WIT 源码以及工作流定义。docs/book/po 路径是指向独立翻译目录仓库的已跟踪 gitlink；其内容和发布标签有各自的生命周期。
被忽略的文件是可重复生成的产物：CLI 和配置引用、大多数生成的代码片段、rustdoc、渲染后的 HTML、语言环境切换器 JavaScript、生成的主题 CSS，以及 dashboard TypeScript API 客户端。文档构建后，它们可能存在于工作树中，但不应包含在提交中。受版本控制的安装相关内容是明确的例外：docs/book/src/_snippets/install.md、README 和平台指南中生成的 Unix 命令块、install.sh 中生成的路由和 picker-helper 区域，以及 docs/book/src/setup/windows.md 中的 Windows 预构建块。
docs/book/theme/index.hbs 是一个值得注意的混合情况。它是一个受版本控制的模板，但主题生成器只会根据 themes.json 重写其中标记的主题列表区域。如果标准生成命令更改了该区域，请检查规范注册表或生成器是否发生了变化；不要将生成的列表视为独立编写的内容。
漂移与验证门禁
不同的检查涵盖不同的失败类别：
| 检查 | 它证明了什么 | 它不能证明的内容 |
|---|---|---|
| 文档质量门禁 | 更改后的 Markdown 符合正文破折号规范，并通过了 markdownlint 检查 | 已忽略的引用或代码片段已从当前代码重新生成 |
| 已添加链接门控 | 比较差异中新增的本地 Markdown 链接可解析 | 现有链接、diff 外生成的链接或渲染后的导航均可正常工作 |
cargo mdbook check | PO 目录解析并通过生成响应、受保护字面量和本地路径审计 | CLI/配置引用和被忽略的代码片段与当前 Rust 源代码相匹配 |
cargo mdbook refs | CLI/配置参考 Markdown 和 rustdoc 可从当前代码生成 | 每个语言区域和主题都会组合成一个完整站点 |
cargo mdbook build | 完整参考资料、代码片段、语言区域构建、渲染后的链接以及站点组装均已完成 | 被忽略的输出会由常规 PR CI 提交或比较 |
| 翻译固定工作流 | docs/book/po gitlink 已初始化并满足 catalog-repository 锁定约定 | 目录覆盖已完成或翻译质量可接受 |
| 文档部署 | 选定的 ref 构建成功，并可合并到版本化的 gh-pages 布局中 | 一个常规的源代码 PR 在审查前重新生成了所有被忽略的输出 |
必需的 PR CI 会运行文档质量检查和新增链接门禁，但不会针对每次文档变更都运行完整的 mdBook 构建。评审者应要求能够覆盖所变更生成器或渲染边界的最精简额外证据，而不应想当然地认为通过的正文检查能够证明生成的输出是最新的。
修正规则
- 修复类型化 schema、派生或 schema-to-Markdown 生成器中的配置引用错误。
- 修复 Clap 命令定义或 Markdown 帮助生成器中的 CLI 引用错误。
- 修复类型化路由契约或其渲染器中的稳定安装行为，然后运行
cargo generate installers；不要手动编辑已跟踪的安装代码片段。 - 修复运行时解析器目录中的 SOP 语法行为或运算符描述，然后运行
cargo generate sop-syntax；不要手动编辑语法参考中的标记列表。 - 修复源支持代码片段错误，需要在其所属的注册表、元数据文件、契约或代码片段生成器中进行。
- 修复
themes.json中的主题列表偏差或标记区域生成器，而不是手动编辑已生成的按钮。 - 应在目录生命周期中修复翻译内容或回退行为，而不是在渲染后的本地化 HTML 中修复。
- 切勿仅仅为了让本地构建看起来是最新的，就提交
docs/book/book/、rustdoc 输出或其他被忽略的生成产物。 - 当生成器行为本身发生变化时，请同时审查源代码变更和一份具有代表性的重新生成的输出，然后运行使用该输出的检查。
源指针
- mdBook 命令组合：
xtask/src/cmd/mdbook/ - CLI 和配置参考：
xtask/src/cmd/mdbook/refs.rs - 本地化构建和站点组装：
xtask/src/cmd/mdbook/build.rs - mdBook 预处理器配置：
docs/book/book.toml - 区域设置注册表：
locales.toml - 文档质量与链接检查门控：
scripts/ci/docs_quality_gate.sh、scripts/ci/docs_links_gate.sh - 翻译固定版本验证：
.github/workflows/validate-translations-pin.yml - 文档部署：
.github/workflows/docs-deploy.yml - 仪表板 OpenAPI 生成：构建 Web 仪表板
- 本地构建命令：在本地构建文档