OpenClaw 文档叠加层（Documentation Overlay）：页面类型分类、信息架构与验证命令实战

OpenClaw 文档叠加层Documentation Overlay页面类型分类、信息架构与验证命令实战【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 仓库在通用技术文档技能之上专门维护了一份名为 OpenClaw Documentation Overlay 的文档工程规则集.agents/skills/technical-documentation/references/openclaw.md它规定了 OpenClaw 文档工作的页面类型、主题页/指南页的标准结构、信息架构导航规则、源码佐证要求、改写保留审查流程以及验证命令清单。读完本文你将掌握在 OpenClaw 这类大型文档库中写之前先选页面类型、写完后按最窄证明跑验证的完整文档工程方法论并能直接使用仓库内对应的脚本与命令自行验证每一条规则。Overlay 的定位叠加而非替代这份参考文件开篇即声明它只用于 OpenClaw 的文档工作Use this reference only for OpenClaw docs work其作用是把 OpenClaw 专属的页面类型、导航、保留preservation与验证规则叠加layer在通用 technical-documentation 技能之上。这一叠加关系在整个技能目录中有明确的组织方式技能入口 .agents/skills/technical-documentation/SKILL.md 的 Workflow 第 6 步写明处理 OpenClaw 文档任务时readreferences/openclaw.mdbefore the build/review playbook即必须先读 overlay 再进入构建/评审流程通用规则集位于 .agents/skills/technical-documentation/references/principles.md其Practical merge policy规定规则冲突时的优先级读者任务成功 结构清晰 长期可维护性 Agent 优化并明确When the target repo or request is OpenClaw-specific, layerreferences/openclaw.mdon top评审手册 .agents/skills/technical-documentation/references/review.md 在 Scope、OpenClaw 专属检查项、结构检查等多个环节都回指 overlay要求confirm the content matches an explicit page type fromreferences/openclaw.md。换言之overlay 不是一个独立体系而是一层仓库作用域的策略约束通用原则管文档怎么写才好overlay 管OpenClaw 文档长什么样、放哪里、怎么证明写对了。读者模型五条写作立场Overlay 的 Reader Model 一节给出五条面向读者的写作立场这是所有页面类型共享的底层约束以读者要完成的任务开头Lead with the task the reader is trying to complete先给一条推荐路径再谈备选方案Give one recommended path before alternatives主文档只聚焦常见路径把高密度的契约细节和罕见的调试细节下沉到链接引用的 reference 或 troubleshooting 页生产风险必须写在读者真正可能犯错的那个位置而不是集中到某处注意事项章节把概念、指南、参考、CLI 页、SDK 文档、测试、排障互相链接让读者无需重读就能继续深入。第 3 条和第 5 条在 OpenClaw 的实际文档中可以直接观察到例如 docs/gateway/index.md 的 frontmatter 中read_when: Running or debugging the gateway process开篇即以Use this page for day-1 startup and day-2 operations of the Gateway service点明任务场景并把深度排障通过 Card 组件链接到专门的 troubleshooting 页——这正是主路径聚焦 细节下沉 横向链接规则在成品文档中的体现。八种页面类型写之前先分类Overlay 要求Choose the page type before writing or reviewing共定义八种页面类型页面类型职责Overview总览把读者路由到正确的产品区域、集成路径或指南Quickstart快速上手用最少且安全的步骤让新用户拿到一个可用的结果Topic page主题页端到端地解释一个重要的 OpenClaw 实体或能力面surfaceGuide指南从前提条件走到生产就绪走通一个完整工作流API/SDK/CLI reference参考定义范围内每一个对象、方法、命令、选项、响应、错误、枚举、默认值和版本规则Testing guide测试指南展示沙箱搭建、fixture、模拟故障以及 live 模式差异Troubleshooting guide排障指南把可观察的症状映射到检查项、原因和修复Governance file治理文件保持 agent/贡献者策略具体、有作用域、并与当前 OpenClaw 仓库行为对齐分类是后续所有规则的锚点结构模板见下两节按页面类型选择导航归属见信息架构一节按页面类型放置验证手段见验证体系一节按触碰的表面选择。Topic Page 的标准结构八步Overlay 为主要实体页规定了固定的章节形状标题直接以实体或能力面命名无标题的开篇段Unheaded opening说清它是什么、它拥有什么owns、以及它不拥有什么Requirements仅当设置确实需要账号、版本、权限、插件、操作系统或凭证时才出现Quickstart推荐路径 最小可靠验证Configuration把与任务强相关的选项内联写出穷举式细节链接到参考文档主要子主题按读者意图reader intent组织禁止用一个泛化的 Subtopics 标题兜底Troubleshooting只写可观察的失败现象和具体检查项Related links指向指南、参考、命令、概念和相邻主题。其中第 2 条说清不拥有什么和第 6 条按意图组织子主题是主题页最容易违背的两条。前者迫使作者在开篇就划定边界避免读者把 A 实体的问题带到 B 实体的页面来找答案后者与 Reader Model 第 3 条呼应——密度高的内容要按意图分流而不是堆在一个通用容器里。Guide 的标准结构九步工作流类页面使用另一套形状标题以结果命名而不是实现细节命名Title naming the outcome, not the implementation detail开篇说明读者能完成什么Before you begin账号、密钥、权限、版本、工具与假设Choose a path仅当读者确实必须做选择时才出现Steps动词开头的标题配命令、预期输出和检查点Test用最小可靠证据证明工作流确实跑通Production readiness安全、重试、限制、可观测性、迁移与清理Troubleshooting紧挨着会导致失败的那个工作流放置而不是游离到文末之外See also链接概念、参考、SDK 文档与相邻指南。与 Topic Page 对比可以提炼出两者的分工主题页回答这个实体是什么、怎么用指南回答如何从 0 走到生产。Overlay 刻意在第 4 步加上only when the reader must decide的限定防止指南页退化成菜单页第 8 步则再次落实风险写在读者会犯错的地方这一读者模型原则。文档信息架构IA与导航规则Overlay 的 Docs IA And Navigation 一节给出五条导航规则每一条都能在仓库里找到对应物改导航之前先读 docs/docs.json。这是 OpenClaw 的 Mintlify 文档站配置theme: mint、$schema: https://mintlify.com/docs.json定义了站点名称、导航、字体、配色与重定向主题页与常见工作流留在主读者路径上穷举契约、生成的参考、仅维护者可见的细节与支持性材料放到Reference或其他作用域清晰的支持页下生成的plugins/reference/*子页与纯重定向页除非明确要求否则不出现在可见导航里。这条规则的现实背景在 docs/docs.json 的redirects数组中可见仓库中存在大量形如/plan/swarms - /en/tools/swarm、/concepts/channel-docking - /en/concepts/session#retired-channel-docking的重定向记录说明页面搬迁、退役retired是常态而纯重定向页不应污染导航树页面搬迁时交接材料中必须包含 keep/drop/move/destination 矩阵保留/丢弃/移动/目标位置与后文保留审查一节呼应为参与文档索引的页面添加 Read when 提示用于 docs-list 路由。第 5 条在仓库中有完整的工具链支撑scripts/docs-list.js 会遍历docs/下的.md/.mdx文件排除archive、research等目录解析 frontmatter 中的summary与read_when字段为文档感知型工具渲染按需的标题元数据。以 docs/index.md 为例summary: OpenClaw is a multi-channel gateway for AI agents that runs on any OS. read_when: - Introducing OpenClaw to newcomersread_when声明的就是什么意图的读者应该被路由到这里它把 Overlay 的按读者意图组织规则从写作约束落成了可被脚本解析的元数据。源码佐证原则Source-Backed ContentOverlay 要求文档内容必须以当前仓库行为为证据共五条CLI 文档必须与当前的 flags、输出、错误、示例一致API/SDK 文档必须包含字段、默认值、枚举取值、约束、可空行为、生命周期状态、错误与恢复指引配置文档必须与导出的类型、schema/help 输出、元数据、基线文件和当前文档对齐依赖支撑的行为dependency-backed behavior必须先从上文档、源码或类型中核实才能写下默认值、时序、错误或 API 行为严格区分四种状态当前行为current、已发布行为shipped、计划行为planned、维护者意图maintainer intent。第 5 条尤其针对文档领先于代码的常见漂移把 roadmap 写成能力、把 PR 讨论写成已发布行为都会让文档从可验证的契约退化为愿望清单。在 OpenClaw 这样的仓库中这一条可以通过docs:check-links、生成脚本如 scripts/generate-base-config-schema.ts 这类 schema 生成入口以及plugins/reference生成物与源页面的比对来落地。示例写作规范ExamplesOverlay 对代码示例与命令示例给出八条硬规范优先给完整的、可直接复制粘贴的命令与片段使用现实的变量名和取值占位符一律用尖括号命名如API_KEY当预期输出有助于验证时展示成功输出每个代码块只承载一个概念单元并使用语言特定的 fence避免隐藏 setup、auth、错误处理或清理的看起来能跑的示例绝不暴露真实密钥、线上配置、电话号码、私密视频或凭证示例必须自包含与 principles.md 中Keep examples self-contained and minimize dependencies的通用约束一致。这八条实质上把示例当作可执行的契约来对待复制即可运行、运行即可验证、验证即闭环。保留审查Preservation Reviews改写与拆分时不丢事实针对改写rewrite或拆分split文档的场景Overlay 定义了五步保留审查流程改写前先识别源单元source units标题、段落、表格、示例、CLI/API 契约、警告、排障事实把每个保留单元映射到目标页面或章节宽泛的 covered 标记不构成稠密材料的证据——当源单元信息密度高时必须使用行级或论断级line- or claim-level的证据对丢弃的内容必须定性是过时obsolete、他处重复duplicated elsewhere、不受支持unsupported还是移到了参考/支持页当使用 docs-audit 产物时验证它是带非空mappings[]的映射审计数据而不仅仅是清单或重新索引的 JSON。这套流程与导航一节第 4 条的 keep/drop/move/destination 矩阵是同一枚硬币的两面矩阵管页面级去向保留审查管内容级去向。它的工程价值在于把我改写了这一页从主观陈述变成可审查的映射表——任何一条警告、一个字段表、一条排障事实都能被问到它现在在哪、为什么。验证体系选择最窄的证明Overlay 最后一节给出了验证命令清单核心原则是Choose the narrowest proof that covers the touched surface选择能覆盖触碰表面的最窄证明验证命令适用表面仓库内实现pnpm docs:list文档清单与 frontmatter 元数据scripts/docs-list.jspnpm docs:check-mdxMDX 语法与结构scripts/check-docs-mdx.mjs对docs目录与根 README 运行pnpm docs:check-links文档内链接有效性scripts/docs-link-audit.mjs另有--anchors变体校验锚点pnpm docs:check-i18n-glossary国际化术语表一致性scripts/check-docs-i18n-glossary.mtspnpm format:docs:check或pnpm lint:docs格式化与 Markdown 风格scripts/format-docs.mts--check模式lint:docs使用 config/markdownlint-cli2.jsoncgit diff --check空白字符/冲突标记等低级问题git 自带生成文档或清单检查生成的参考、插件目录、labeler、文档脚本被修改时对应生成脚本如 scripts/docs-link-audit.mjs 同族的生成/审计入口行为测试或命令探针behavior tests / command probes文档声称了运行时行为时仓库内的测试与命令探测上述脚本名与命令的映射可以在 package.json 的 scripts 段逐一核对docs:list、docs:check-mdx、docs:check-links、docs:check-links:anchors、docs:check-i18n-glossary、format:docs:check、lint:docs等。此外仓库还提供 scripts/docs-map:genpnpm docs:map:gen生成带标题的文档地图作为导航变更前的盘点手段。清单最后还有一条兜底规则如果验证被阻断必须明确说出哪条命令没有跑、以及为什么If proof is blocked, say exactly which command was not run and why。这保证了未验证本身也是一个可审计、可追踪的状态而不是被静默跳过。把 Overlay 放回完整工作流结合技能入口 SKILL.md 的 Workflowoverlay 在整个文档工作流中的位置是任务分类build/review × brownfield/evergreen尽早盘点文档全貌治理文件 产品文档读 principles.md 获取通用规则集若是 OpenClaw 文档工作读本文所述的 overlaybuild 走 build playbookreview 走 review.md 并主动发现问题输出交付物 验证说明 遗留缺口其中 OpenClaw 专属检查项页面类型归属、docs/docs.json导航、生成参考页可见性、保留映射全部来自 overlay。可以推断这种通用原则 仓库 overlay的分层设计是 OpenClaw 文档体系能同时服务人类读者、搜索引擎和 Agent 的关键通用原则保证跨仓库可迁移的写作质量overlay 则把导航归属、保留审查、最窄验证这些只能在具体仓库语境下成立的约束固化成了可执行的检查项。小结Overlay 是一份作用域明确的叠加规则只在 OpenClaw 文档工作中生效先于 build/review playbook 被读取先选页面类型再写内容八种页面类型各自绑定结构模板、导航归属与验证手段导航以 docs/docs.json 为单一事实源生成的参考页与纯重定向页默认不进入可见导航页面搬迁必须附带去向矩阵内容以源码为证CLI flags、API 字段、配置默认值都要能从仓库中的类型、schema、help 输出或测试中复验改写必须可追溯每个源单元都要有保留映射丢弃内容必须定性验证取最窄证明pnpm docs:list/docs:check-mdx/docs:check-links/docs:check-i18n-glossary/format:docs:check/lint:docs按触碰表面选择被阻断时明确声明未跑的命令及原因。遵循这套 overlayOpenClaw 的文档变更就从凭经验的写作变成了带分类、带导航、带保留映射、带最窄验证的工程化流程——这也是大型多通道网关项目能在数百页文档docs/下 20 主题目录规模上保持准确性的方法论基础。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考