NemoClaw 文档重构验证指南：发布路由、链接审计与独立评审的确定性检查体系

NemoClaw 文档重构验证指南发布路由、链接审计与独立评审的确定性检查体系【免费下载链接】NemoClawRun agents like Hermes, LangChain Deep Agents, and OpenClaw more securely inside NVIDIA OpenShell with managed inference项目地址: https://gitcode.com/gh_mirrors/ne/NemoClaw本文聚焦 NemoClaw 文档工程中的重构验证环节当文档页面、导航或内容所有权发生结构性调整后如何用确定性检查、发布路由审计与独立评审三道关卡在“保留每条已发布路由、每个主题唯一归属”的前提下验证重构结果。读完本文你将掌握文档重构完成后从命令级验证到逐条审计、再到独立 Reviewer 复核的完整闭环流程并理解 Fern 发布路由与源文件路径之间容易踩坑的差异对应仓库中的 validation.md 与 SKILL.md 工作流。验证阶段总览先跑确定性检查再做独立评审NemoClaw 的文档重构nemoclaw-maintainer-refactor-docs把“验证”划分为两个连续阶段Step 7验证重构本身——运行仓库既有的确定性检查而不是发明一套新的路由模型Step 8运行独立的文档评审——由一名不知道预期结论的独立文档作者对纯文档变更做第二道复核。两个阶段的核心立场是一致的文档重构验证依赖仓库中已固化的检查工具链npm 脚本、vitest 测试、git diff 检查在此基础上补充针对本次改动的定向审计最后用“盲评”式独立评审兜底。第一阶段运行确定性检查命令在仓库根目录依次执行以下命令作为重构后的第一道防线原文档命令原样继承npm run docs:sync-agent-variants npm run docs npx vitest run test/generation/check-docs-published-routes.test.ts test/generation/check-docs-links.test.ts git diff --check四条命令各自承担明确职责与 package.json 中的脚本定义一一对应命令底层脚本/工具验证目标npm run docs:sync-agent-variants即docs:prepare调用 generate-starter-prompt.mts 与 sync-agent-variant-docs.mts重新生成 OpenClaw / Hermes / Deep Agents / Pi 各 agent 变体页面_build/agent-variants/*.generated.mdx并同步 starter promptnpm run docs即docs:strictdocs:preparedocs:validate走完整文档构建链路同步变体、校验 starter prompt、校验变体漂移、校验发布路由、最后用fern-api check做 Fern 站点校验npx vitest run ...check-docs-published-routes.test.ts ...check-docs-links.test.ts两个生成期测试套件前者校验内部链接解析到真实“已发布”的 Fern 路由后者通过check-docs.sh做本地文件链接、站点路由与代码块/注释豁免校验git diff --checkGit 原生检出空白错误行尾空格、冲突标记残留等 diff 级格式问题补充说明docs 脚本的完整链路npm run docs不是简单的一步而是经过docs:strict递归展开的复合命令docs:preparedocs:sync-starter-promptsync-agent-variant-docs.mts生成各变体页面docs:validatedocs:check-starter-prompt校验 starter prompt 未漂移docs:check-agent-variantssync-agent-variant-docs.mts --check确认生成产物与源一致docs:check-routes即tsx scripts/check-docs-published-routes.mts见下文源码分析fern-api checkFern 官方导航/重定向校验。因此执行npm run docs时发布路由检查docs:check-routes已经作为内置环节自动运行第 3 条 vitest 命令则是对同一逻辑在测试夹具层面的补充覆盖。第二阶段前哨为未覆盖的章节补充聚焦路由测试确定性命令只能覆盖仓库已固化的检查面。当被重构的章节不在当前 published-route 检查器的守护范围内时原文档要求新增或扩展聚焦的路由测试且断言的对象必须是“可观察的已发布路由与重定向”而不是“源文件相对路径的假设”。这一点与检查脚本的设计理念完全一致check-docs-published-routes.mts专门维护了一个GUARDED_SOURCE_PAGES列表reference/commands.mdx、reference/network-policies.mdx、configure-agents/、inference/、manage-sandboxes/下全部 MDX 等并对这些页面做了“逐变体渲染后校验链接”的守护。如果你的重构范围落在这张表之外就应当像仓库为 inference 与 manage-sandboxes 提供findBrokenPublishedInferenceRoutes/findBrokenPublishedManageSandboxRoutes这样“聚焦而不扩散”的检查函数一样为重构章节补一个同等粒度的测试。构建后的逐项审计清单原文档要求构建完成后完成以下审计逐条落实下表为原文档清单的完整展开旧名全搜搜索每一个被删除的文件名、旧 slug、旧标题、旧路由确认它们都以重定向或内容迁移的方式被妥善处理锚点迁移搜索每一个被移动的锚点anchor更新所有“语义目的地已改变”的引用归属者改名在源码注释、包级AGENTS.md、测试与脚本中搜索所有点名“前文档负责人”的表述并同步更新折叠根不可链接确认没有任何页面链接到可折叠分组节点foldable section root——折叠节点没有页面内容链接它会直接 404重定向全部终止于已发布页面确认所有重定向的终点对适用的每个 agent 变体而言都是真实发布的页面标题清单对账把旧的标题清单与新的页面逐一比对为每一个唯一主题找到去处不允许“内容凭空消失”故障排查/参考去重在 canonical 的 troubleshooting 与 reference 目的地中搜索重复标题、重复的修复方案确保每个问题只有一个权威答复变体页人工抽查当变体块AgentOnly或共享列表发生变化时人工检查生成的 OpenClaw、Hermes、Deep Agents 页面列表紧凑性确认简单列表中连续条目之间没有空行保持 compact 风格Fern 预览目检当导航深度、标题或条件内容变化时用 Fern 预览肉眼复核站点呈现。其中第 4、5 条有直接的源码级支撑check-docs-published-routes.mts会拒绝把折叠分组节点当作链接目标slug 缺失的 section/page/changelog 直接throw并通过findBrokenPublishedRedirects将:variant占位符逐个展开校验防止“某个变体可用、另一个变体 404”的重定向被漏检。关键原理Fern 链接从“发布 slug 路由”解析而非源文件目录这是整个验证体系中最容易误判、也最值得展开的一点。原文档的告诫是把自动化链接反馈当作假设hypothesis而非结论。因为 Fern 的链接从发布后的 slug 路由解析一个“有效链接”可能并不匹配源文件相对路径。为什么源文件路径会“骗过”检查检查脚本文件头的注释记录了两起真实事故NemoClaw#5445、PR #6290docs/deployment/install-openclaw-plugins.mdx在源目录上位于deployment/但它通过 docs/index.yml 的导航被发布到manage-sandboxes分组下其真实路由是/user-guide/openclaw/manage-sandboxes/install-openclaw-plugins。如果按源目录写../deployment/install-openclaw-plugins这种链接磁盘上文件存在、fern check也通过但线上站点 404。这正是发布路由检查器存在的根本原因。源码级的三段式校验check-docs-published-routes.mts 的核心逻辑可以拆成三步构建发布路由索引buildPublishedRouteIndex解析 docs/index.yml 的navigation.variants按“/user-guide/{variant}/{父级 slug 链}/{页面 slug}”拼接出每个页面的发布路由同时把_build/agent-variants/foo.{variant}.generated.mdx这类生成路径映射回共享源foo.mdx并强制要求每个 page/section/changelog 显式声明 slug缺失即报错防止 Fern 自动派生 slug 导致路由漂移按 Fern 语义解析链接resolvePublishedRoute根绝对路由/user-guide/...直接按站点 base URL 锚定相对链接则基于“链接所在页面的发布路由”向上解析parts.pop()丢掉本页 slug 再处理..而不是基于源文件目录——这正是它能抓住 PR #6290 那类缺陷的关键渲染后校验findBrokenPublishedRoutes对共享源页面先按各变体渲染renderAgentVariantPage再提取 Markdown 链接extractMarkdownLinks会跳过代码块与行内代码同时容忍 CommonMark 的链接 title最后逐一比对解析结果是否命中路由索引。变更日志Release Notes的特殊规则共享的changelog/会以带日期的永久链接发布/user-guide/{variant}/release-notes/2026/7/14形式。findBrokenChangelogRoutes强制要求变更日志中的站内链接必须使用根绝对路由若写../reference/commands这类相对链接会解析到/release-notes/2026/reference/commands这种不存在的位置。对应的测试用例 check-docs-published-routes.test.ts 专门断言了这一行为。重定向的“直接到达”原则findBrokenPublishedRedirects对fern/docs.yml中涉及/inference、/deployment、/manage-sandboxes、/release-notes等分组的重定向做目标校验:variant占位符逐个变体展开而findMissingDirectLegacyManageSandboxRedirects与findMissingDirectLegacyReleaseNotesRedirects则要求旧版.html、/index.html、.md、.mdx形式都有直达最终页面的显式重定向且必须排在/nemoclaw/:path*.html这类通配规则之前否则会形成“先剥后缀、再二次跳转”的间接链。这也对应 migration.md 中的规则“每个重定向直接指向最终页面禁止重定向链”。链接测试的另一半check-docs-links.test.tscheck-docs-links.test.ts 通过 bash 调用check-docs.sh --only-links --local-only覆盖另一类场景本地 Markdown 相对链接断链带行号报告、代码围栏含~~~、长度不匹配围栏、带尾随文本的围栏、行内代码、HTML 注释内的链接豁免以及 Fern 路由风格链接不允许带.md/.mdx后缀deployment/deploy-to-remote-gpu.mdx报错、deployment/deploy-to-remote-gpu通过。它还验证了“Fern 导航解析失败必须大声失败”failed to parse Fern navigation/no Fern routes found避免静默跳过检查。第三阶段运行独立的文档评审确定性检查全部通过后进入 Step 8——独立文档评审评审对象本次纯文档变更输入材料旧→新的内容所有权映射表old-to-new ownership map评审人一名独立的文档作者不知道预期结论避免“确认偏误”检查项内容丢失、所有权重复、变体漂移、错误重定向、超大段落块、生成导致的段落拼接、风格回退处理方式采纳有效发现重新运行受影响的所有检查。这一设计把“机器检查”与“人审”解耦机器保证路由、链接、构建层面的确定性事实人审负责语义完整性——例如某个主题是否在迁移中丢失了独有事实、两个页面是否同时声称对同一主题负责、变体渲染后共享列表是否出现结构性损坏。收尾用完成契约对照验证成果验证完毕后可对照 SKILL.md 的 Completion Contract 做最终收口它本质上是把上文所有检查点汇总为可勾选的验收条件每个可见 TOC 项都是真实主题页每个可折叠分组节点不可点击且无页面内容每个页面只归属一个主主题或任务每个旧章节都有明确去向或注明删除理由troubleshooting 与 reference 指导只有一个 canonical 归属者没有任何受支持的变体渲染出指向未发布页面的链接或重定向旧 URL 直达最终发布页共享内容在每个适用 agent 变体下渲染正确源页面与生成变体页均无未处理的超大/多用途段落块简单列表保持紧凑docs 构建、路由检查、链接检查、diff 检查全部通过。最后按 migration.md 的提醒_build/agent-variants/*.generated.mdx是生成产物不直接编辑——任何变体差异都应改源页面与导航映射docs/index.yml再通过npm run docs:sync-agent-variants重新生成并在报告中记录本次验证用到的命令与结果。小结NemoClaw 的文档重构验证是一套“确定性检查打底、定向审计补漏、独立评审兜底”的三层体系npm run docs链路把发布路由检查内置进日常构建check-docs-published-routes.mts从源码层面杜绝“源路径可用但发布路由 404”的历史缺陷审计清单覆盖旧名、锚点、归属者、重定向与变体渲染的每个细节最后的盲评式独立评审守住语义完整性。这套方法不限于 NemoClaw——任何基于 Fern 多变体发布、且存在“源目录 ≠ 发布路由”映射的文档仓库都可以照此建立自己的验证闭环。【免费下载链接】NemoClawRun agents like Hermes, LangChain Deep Agents, and OpenClaw more securely inside NVIDIA OpenShell with managed inference项目地址: https://gitcode.com/gh_mirrors/ne/NemoClaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考