NemoClaw 文档重构指南保持已发布路由稳定地重组 docs 导航、所有权与内容【免费下载链接】NemoClawRun agents like Hermes, LangChain Deep Agents, and OpenClaw more securely inside NVIDIA OpenShell with managed inference项目地址: https://gitcode.com/gh_mirrors/ne/NemoClawNemoClaw 使用 SKILL.md 及其三份阶段化参考文档定义了一套“不改产品语义、不丢任何事实、不破坏任何已发布 URL”的文档结构重构方法。本篇将完整拆解该方法的八步流程——从盘点所有权、按用户旅程设计目录到 URL 迁移契约、可读性修正与确定性校验——并结合仓库中的路由检查脚本与 Agent 变体生成脚本说明每一步规则背后的工程实现依据读完即可对任意docs/分区做一次有边界的结构重构。技能定位一个有边界的重构工作流该技能是一个“维护者技能”maintainer skill其对外元数据见 agents/openai.yaml展示名为 “NemoClaw Maintainer Docs Refactor”默认提示语是“把快速增长的 NemoClaw 文档分区重组为结构一致的聚焦页面”。SKILL.md 开篇给出的目标是在一个有边界的文档分区内重构不改变产品含义同时做到三件事——保留每一个有用事实、每个主题只有一个规范所有者canonical owner、保留每一个受支持的已发布路由published route。整个方法按“阶段化加载load the phase that applies”组织请求类型使用的参考文档对应步骤审计 / 结构规划references/structure.mdStep 1 盘点、Step 2 旅程设计、Step 3 规范所有权变更已发布路由或移动内容前references/migration.mdStep 4 URL 迁移契约、Step 5 内容安全实施、Step 6 可读性修正已实现的重构完成后references/validation.mdStep 7 校验、Step 8 独立评审SKILL.md 明确要求规划类请求不要加载执行细节而“执行重构”的请求天然包含实现与验证常规排版选择无需单独审批。前置条件先读全量上下文再动笔SKILL.md 的 Prerequisites 一节列出三条硬性前置在 NemoClaw 仓库根目录下工作在规划或编辑前先遵循共享的文档写作与评审契约。该契约本身又路由到两个权威来源面向任何说明性文本的 WRITING.md负责断言准确性、写作规则、术语路由以及面向公开文档的文档贡献者指南负责文档流程、模式与校验契约强调“不要把两份指南的规则复制进技能里”评审时还要“完成全部适用的评审类别不因第一个阻塞性问题就停止”编辑前读全目标页面、它们在docs/index.yml中的导航条目、fern/docs.yml中的重定向以及所有入站链接inbound links。第三条是整个方法能“无 404 迁移”的根基NemoClaw 的文档站由 Fern 构建页面路由来自docs/index.yml中声明的 slug 层级而不是源文件目录。这一点在仓库中有专门的守卫脚本印证——scripts/check-docs-published-routes.mts 头部注释记录了真实事故背景NemoClaw#5445docs/deployment/install-openclaw-plugins.mdx实际发布在manage-sandboxes分区下路由是/user-guide/openclaw/manage-sandboxes/install-openclaw-plugins一条模仿“源目录”写法的链接如../deployment/install-openclaw-plugins在磁盘上可以解析、fern check也能通过但线上会 404。因此重构前必须同时掌握“源文件位置”与“已发布路由”两套坐标。选择交付物规划、实施与边界控制SKILL.md 的 “Choose the Deliverable” 一节规定了交付物判定规则跨分区所有权、导航层级、已发布 URL 变更属于维护者级决策请求是“规划 / 审计 / 提案结构”时在信息架构、所有权映射与 URL 迁移计划之后就停止请求是“重构”时实施计划、执行校验并报告完成的迁移工作范围锁定在命名的文档分区内相邻技术债单独报告不顺手混入本次重构允许跨分区移动当规范所有权确有需要时但必须在计划与迁移报告中显式标明该移动只有当选择会改变主题所有权、公开 URL、支持的变体或用户工作流时才向请求方提出选项常规细节遵循仓库既有惯例。这一节把“做什么”与“做到什么程度”分开避免规划请求被悄悄升级成实现也避免重构请求被卡在无关的样式决策上。Step 1编辑前先建所有权清单structure.mdStep 1要求通读整个分区而不是抽样最长的页面并执行五步盘点为 OpenClaw、Hermes、Deep Agents 每个导航变体列出所有页面与嵌套分组仓库中实际还有 Pi 变体见后文变体生成机制列出源页面中每个 H2/H3再映射没有自己的标题但承载实质内容的散文块、表格、callout 与按 provider 区分的操作步骤找出入站链接、旧路由与锚点引用、重定向、发布说明链接、README 链接、测试、生成页面映射、以及点名当前文档所有者的源注释与仓库指令记录每个变体渲染哪些页面或内容块识别重复的步骤、故障排查指引、参考事实与相关主题列表。仓库级发现建议用rg技能给出了起步命令rg -n ^(##|###) docs/section rg -n section-slug|page-slug|page-title docs fern README.md test scripts盘点完成后先创建所有权清单表再提出新目录当前页面或分区用户任务变体规范所有者动作既有主题读者想完成什么适用的指南目标页面保留 / 拆分 / 移动 / 合并 / 删除硬性约束每个旧的 H2 和 H3 都必须出现在这张表里。这保证重构是“有台账的搬迁”而不是凭感觉改写。Step 2按用户旅程设计目录structure.mdStep 2给出默认的用户旅程序列——某阶段没有实质读者任务就省略绝不为凑齐序列而造薄页面Choose选择帮读者在 provider、模型、部署方式或方案之间做选择Set Up搭建不同 provider/平台/集成的步骤差异大时各自拥有独立页面Operate操作检查、切换、配置、生命周期与日常管理Validate验证证明配置与运行时行为不混入宽泛的故障排查Troubleshoot and Reference排障与参考可复用的失败处置与查询材料放在规范 Reference 分区。仅在“选择/操作之前读者确需独立心智模型”时才增加About / Understand页不要为了给分区一个可点击的首项而创建总览页。配套导航规则这些规则直接对应docs/index.yml的节点结构分区标题与可折叠 TOC 节点必须是不可点击的分组节点只包含section、slug、contents以及collapsed等展示设置所有读者内容放在子页面默认root section → task group → page三层除非材料证明存在真实的第三层区分否则不加深每页一个主主题或用户任务前置条件与即时成功验证可以留在同页但不同用户目标、不同 provider 流程、可复用概念与可复用参考资料必须拆页页面标题偏好动词开头Choose、Set Up、Configure、View、Switch、Verify、Troubleshoot分组标签用简短名词短语provider/平台特定步骤放独立页面而不是往通用页面追加更多分区各变体尽量复用分组 slug 与顺序省略不支持的页面从不发布空分组。仓库中 docs/index.yml 正是这套规则的落地形态例如 Inference 分区约第 55 行起就是section: Inferenceslug: inference下挂Choose a Provider and Model、Hosted Inference、Local Inference、Custom Endpoints、Manage Inference、Validate Inference等子分组页面 slug 均为choose-…、set-up-…、view-…、switch-…、verify-…这类动词开头命名——SKILL.md 最后特意点名Inference 分区是这套方法的“活例子”其结构把“About Inference Routing理解推理路由对应 docs/inference/how-inference-routing-works.mdx”、选择 provider 与模型、托管/本地/自定义三条搭建路径、管理、验证、以及规范的 Reference 排障分开。技能同时提醒可以复用它的推理与一致性规则但不要照抄推理专属的页面名。Step 3确立规范所有权structure.mdStep 3要求在移动内容之前把每个事实、步骤、故障模式指派给唯一页面搭建步骤留在聚焦的搭建页日常操作留在 manage/operate 页验证行为留在验证页可复用的故障现象、诊断与处置移入规范 Reference 排障区若 docs/reference/troubleshooting.mdx 仍是聚焦的负责人就用它若规范页本身过大则改建成一个不可点击的 Troubleshooting 分组 聚焦子页面而不是继续养大单体页结构化查询材料保留在 Reference对同一内容链接到规范位置而不是在多个页面复述移动排障/参考内容前先在目标位置搜索相同症状、标题、命令与特征短语——已有文档则合并不留较短的重复副本旧页面的每一个独特事实都必须保留两个页面表述不一致时向权威来源核实行为而不是选更新的措辞。Step 4URL 迁移契约migration.mdStep 4要求在删除或重命名文件之前先建路由表旧已发布路由新已发布路由变体是否需要重定向内容所有者旧 URL最终页面 URL适用指南是/否源 MDX 页面若一个旧页面将拆成多个目的地还要建锚点迁移表旧路由与锚点新路由与锚点入站引用动作旧页面片段最终主题片段文档、发布说明、README、测试或源码更新入站链接记录不可避免的锚点损失路由规则逐条对应 fern/docs.yml 的 redirects 配置约定已发布 URL 由docs/index.yml中分区与页面的slug层级派生不来自源文件目录MDX 内使用无扩展名的路由式链接永不链接或重定向到不可点击的分区节点为受支持的旧形态加重定向包括latest与非latest、变体路由、以及存在过的变体化之前的扁平路由每条重定向直接指向最终页面不造重定向链审计通配符优先级确保通配符目标也直接解析到已发布页面当仓库或外部引用证明.html、index.html旧形态曾被发布或引用时必须保留其直接重定向每个重定向目标必须在“其来源所代表的每一个变体”下均已发布被删除的落地页/分区根路由重定向到第一个真正有价值的页面而不是空的替代总览页移动后的排障内容链接指向规范参考页有必要时带具体锚点历史发布说明链接在其原页面被拆分时更新到最相关的规范主题不能靠页面级重定向找回被移动的锚点语义共享源页面可以通过_build/agent-variants/*.generated.mdx路径出现在导航中那些是被忽略的构建产物——永远编辑源页面与导航映射而不是生成文件。“重定向直接指向最终页”“.html形态直接重定向”“通配符优先级”这几条并非空谈仓库里有对应的确定性检查scripts/check-docs-published-routes.mts 中findMissingDirectLegacyManageSandboxRedirects约 L179-L210要求 Manage Sandboxes 的.html/index.html旧形态各自有一条直接重定向避免“先剥掉.html、再靠第二条重定向跳最终页”的链式写法findMissingDirectLegacyReleaseNotesRedirects约 L213-L292则枚举 Release Notes 全部 15 个旧形态含.html、/index.html、.md、.mdxlatest与非latest两套并检查它们必须排在泛化通配符如/nemoclaw/:path*.html之前否则更具体的规则会被通配符抢先。Step 5 与 Step 6内容安全的实施顺序与可读性修正migration.md 规定实施必须按“内容安全”的六步顺序创建目标页面并搬移全部映射内容把重复内容合并进规范所有者为每一个受支持的指南变体更新docs/index.yml更新路由式链接与相关主题列表在fern/docs.yml添加直接重定向只有当旧源页面的独特内容与入站路由都已交代清楚后才删除被取代的源页面。同时遵循面向公开文档的规则与重构专属规则简单 Markdown 列表相邻项之间不留空行含AgentOnly块的共享列表在变体渲染后必须结构完整需要检查生成的变体输出结构性拆分期间保留可运行的命令与行为断言不做顺手的大段改写。随后Step 6在结构重构完成后单独跑一遍可读性修正一个散文块满足任一条件即成为评审候选——4 个及以上句子、约 70 词以上、约 400 字符以上、或承担多个目的跨条件块拼接的长段落即使低于阈值也要评审。修正是同主题想法拆成短段落块内含不同任务/决策/阶段时加描述性 H2/H3不为单薄的段落加标题不为缩短而改写事实保留命令、链接、callout 语义、技术断言、路由所有权与 agent 适用性。机械统计段落大小时排除 frontmatter、代码围栏、表格、标题、JSX 标签与单个列表项。修正后要重新生成 agent 变体并检查生成的 OpenClaw、Hermes、Deep Agents 页面中是否出现源文件没有的稠密块——当移除AgentOnly包裹使变体特定文本与共享文本拼在一起时要在条件块两侧补回源段落边界再重新生成直到源与生成页的段落块都可读为止。变体机制为什么“重新生成”是硬性步骤“重新生成 agent 变体”之所以是流程中的一等步骤是因为 NemoClaw 的文档站为四个 agent 变体openclaw、hermes、deepagents、pi定义于 scripts/sync-agent-variant-docs.mts 第 12 行的agentVariants常量分别渲染导航。该脚本的核心机制直接解释了上文多条规则的必要性AgentOnly variant...指令stripAgentOnlyBlocksForVariant约 L94-L142按活动变体保留或剥除条件块且禁止嵌套渲染后若残留AgentOnly标签、AgentGuideimport 或运行时组件assertStaticallyResolvedVariantPage会直接抛错让npm run docs失败$$nemoclawCLI 哨兵共享源用哨兵$$nemoclaw表示 CLI 名按变体替换为nemoclaw/nemohermes/nemo-deepagentscliForVariant约 L527-L531只在单变体页面使用哨兵会被assertNoUnsharedPlaceholders拒绝会按字面量渲染命令参考页特殊处理reference/commands.mdx的 frontmatter 会被按变体改写标题、描述、description-agent、keywords 与sidebar-titleupdateCommandsFrontmatter约 L349-L408正文中的nemoclaw调用、命令替换与锚点也会被transformNemoclawCliInvocations约 L776-L794改写同时保护nemoclaw onboard --agent hermes等不可别名化的字面量空节检查assertNoEmptyVariantSections约 L252-L309会拒绝“某标题在另一变体的AgentOnly块里而本页渲染为空”的写法——这正是 Step 6 要求“在移除AgentOnly包裹时补回段落边界”的机器执行者生成文件写入docs/_build/agent-variants/相对目录/基名.variant.generated.mdx头部带“由脚本生成、禁止手改”的注释写入前会清理过期生成文件。因此 SKILL.md 与 migration.md 中“编辑源页面与导航映射而不是生成文件”“变体渲染后检查列表结构”等规则本质上是与该脚本的契约对齐。Step 7用确定性检查验证重构validation.mdStep 7给出的标准校验命令与 package.json 中的脚本一一对应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其中docs:sync-agent-variants实际是docs:prepare的别名先生成 starter prompt 再运行变体同步而npm run docs会执行docs:strict即docs:preparedocs:validatestarter prompt 检查、--check模式的变体同步、docs:check-routes最后以fern.config.json锁定的 Fern 版本运行fern check。两个 vitest 用例分别测试 check-docs-published-routes.mts 的路由/重定向逻辑与文档链接检查。若被重构分区不在现有已发布路由检查器的覆盖内要新增或扩展聚焦的路由测试并“测试可观察的已发布路由与重定向而不是源文件相对假设”。check-docs-published-routes.mts 的实现值得细看buildPublishedRouteIndex约 L139-L157解析 docs/index.yml按walkLayout约 L77-L137从每个变体 layout 的 slug 链拼出/user-guide/variant/...路由集合并且对没有显式 slug 的节点直接抛错因为 Fern 会从 title 派生 slug会静默偏移下游全部路由findBrokenPublishedRoutes把页内相对链接按“链接页的已发布路由”而非“源文件目录”解析resolvePublishedRoute约 L348-L364——这正是 SKILL.md 强调“先读导航与重定向再编辑”的机器版本。脚本尾部维护了一份GUARDED_SOURCE_PAGES守卫清单约 L590-L612把历史上反复回归的reference/commands.mdx、整个configure-agents/、inference/、manage-sandboxes/与若干 deployment 页面全部纳入逐页路由校验。构建完成后validation.md 还要求完成一组人工/脚本混合审计搜索每一个被删文件名、旧 slug、旧标题、旧路由搜索每一个被移动锚点并更新语义目的地已改变的引用在源注释、包级AGENTS.md、测试与脚本中搜索点名旧文档所有者的语句确认没有页面链接到可折叠分区根确认所有重定向在适用变体下终止于已发布页面把旧标题清单与新页面对照交代每一个独特主题在规范排障/参考目的地搜索重复标题与重复处置变体块或共享列表变化时检查生成的 OpenClaw/Hermes/Deep Agents 页面确认简单列表相邻项间无空行导航深度、标题或条件内容变化时在 Fern 预览中目检仓库提供npm run docs:live与npm run docs:preview:watch支撑本地预览。最后一条认知校准非常重要把自动链接反馈当作假设。Fern 按已发布 slug 路由解析链接合法链接可能不匹配源文件相对路径编辑前先对照docs/index.yml、fern/docs.yml、生成变体映射与确定性路由检查核实链接告警——即使页面路由存在缺失的锚点仍可能是真实问题。Step 8独立的文档评审validation.mdStep 8要求对完成的“纯文档变更”跑一次独立的文档写作者评审把旧→新所有权映射交给评审者让它检查内容丢失、重复所有权、变体漂移、坏重定向、过大段落块、生成的段落拼接与风格回退——不告诉它预期结论应用有效发现后重跑受影响的检查。这与 documentation-writing-review.md 中“完成整个被指派的评审、一次性报告全部有证据的发现、不因发现阻塞项就提前终止”的要求一致。完成契约与结果报告SKILL.md 用“Completion Contract”把两类请求的完成标准分开。规划类请求的完成意味着所有权映射、拟议结构、路由迁移计划与未决决策已被记录下述实现类检查不适用。已实施的重构则要求全部满足读者可选择的每个可见 TOC 项都是真实主题页每个可折叠分组节点都不可点击、且无页面内容每页只拥有一个主主题或任务每个旧分区都被映射到目的地或被明确说明理由后有意移除排障与参考指引各有一个规范所有者没有受支持变体渲染出指向未发布页面的链接或重定向旧 URL 直接重定向到最终已发布页面共享内容在每个适用 agent 变体下正确渲染源页面与生成变体页面都没有未解决的过大或多用途散文块简单列表保持紧凑文档构建、路由检查、链接检查与 diff 检查全部通过。实施完成后的报告需覆盖最终的旅程式 TOC创建/移动/合并/删除的页面排障与参考的规范所有权决策保留的重定向与旧路由变体间差异对稠密段落块做的可读性编辑校验命令与结果以及有意延后的相邻清理对应前述“报告相邻债而非顺手合并”的边界规则。小结方法要点速查环节核心动作仓库证据前置读目标页、docs/index.yml导航、fern/docs.yml重定向、入站链接docs/index.yml、fern/docs.yml盘点每页 H2/H3 全部入台账rg全仓搜索引用structure.md Step 1设计Choose/Set Up/Operate/Validate/Troubleshoot 旅程分组节点不可点击动词页标题docs/index.yml Inference 分区活例所有权一主题一主页排障入规范 Reference链接不复述docs/reference/troubleshooting.mdx迁移先路由表与锚点表重定向直达最终页不编辑生成文件migration.md Step 4实施六步内容安全顺序列表紧凑保留命令与行为断言同上 Step 5可读性≥4 句/约 70 词/约 400 字符/多用途即评审修后重新生成变体scripts/sync-agent-variant-docs.mts校验npm run docs:sync-agent-variants、npm run docs、两个 vitest 路由/链接测试、git diff --checkvalidation.md、package.json评审独立评审者持所有权映射查丢失/重复/漂移/坏重定向documentation-writing-review.md按这套流程执行重构的结果是目录按读者旅程组织、每个事实有唯一规范所有者、旧 URL 全部直达新页面、四个 agent 变体渲染一致并且每一步都有仓库内可重跑的确定性检查兜底。【免费下载链接】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），仅供参考 NemoClaw 文档重构指南：保持已发布路由稳定地重组 docs 导航、所有权与内容
NemoClaw 文档重构指南保持已发布路由稳定地重组 docs 导航、所有权与内容【免费下载链接】NemoClawRun agents like Hermes, LangChain Deep Agents, and OpenClaw more securely inside NVIDIA OpenShell with managed inference项目地址: https://gitcode.com/gh_mirrors/ne/NemoClawNemoClaw 使用 SKILL.md 及其三份阶段化参考文档定义了一套“不改产品语义、不丢任何事实、不破坏任何已发布 URL”的文档结构重构方法。本篇将完整拆解该方法的八步流程——从盘点所有权、按用户旅程设计目录到 URL 迁移契约、可读性修正与确定性校验——并结合仓库中的路由检查脚本与 Agent 变体生成脚本说明每一步规则背后的工程实现依据读完即可对任意docs/分区做一次有边界的结构重构。技能定位一个有边界的重构工作流该技能是一个“维护者技能”maintainer skill其对外元数据见 agents/openai.yaml展示名为 “NemoClaw Maintainer Docs Refactor”默认提示语是“把快速增长的 NemoClaw 文档分区重组为结构一致的聚焦页面”。SKILL.md 开篇给出的目标是在一个有边界的文档分区内重构不改变产品含义同时做到三件事——保留每一个有用事实、每个主题只有一个规范所有者canonical owner、保留每一个受支持的已发布路由published route。整个方法按“阶段化加载load the phase that applies”组织请求类型使用的参考文档对应步骤审计 / 结构规划references/structure.mdStep 1 盘点、Step 2 旅程设计、Step 3 规范所有权变更已发布路由或移动内容前references/migration.mdStep 4 URL 迁移契约、Step 5 内容安全实施、Step 6 可读性修正已实现的重构完成后references/validation.mdStep 7 校验、Step 8 独立评审SKILL.md 明确要求规划类请求不要加载执行细节而“执行重构”的请求天然包含实现与验证常规排版选择无需单独审批。前置条件先读全量上下文再动笔SKILL.md 的 Prerequisites 一节列出三条硬性前置在 NemoClaw 仓库根目录下工作在规划或编辑前先遵循共享的文档写作与评审契约。该契约本身又路由到两个权威来源面向任何说明性文本的 WRITING.md负责断言准确性、写作规则、术语路由以及面向公开文档的文档贡献者指南负责文档流程、模式与校验契约强调“不要把两份指南的规则复制进技能里”评审时还要“完成全部适用的评审类别不因第一个阻塞性问题就停止”编辑前读全目标页面、它们在docs/index.yml中的导航条目、fern/docs.yml中的重定向以及所有入站链接inbound links。第三条是整个方法能“无 404 迁移”的根基NemoClaw 的文档站由 Fern 构建页面路由来自docs/index.yml中声明的 slug 层级而不是源文件目录。这一点在仓库中有专门的守卫脚本印证——scripts/check-docs-published-routes.mts 头部注释记录了真实事故背景NemoClaw#5445docs/deployment/install-openclaw-plugins.mdx实际发布在manage-sandboxes分区下路由是/user-guide/openclaw/manage-sandboxes/install-openclaw-plugins一条模仿“源目录”写法的链接如../deployment/install-openclaw-plugins在磁盘上可以解析、fern check也能通过但线上会 404。因此重构前必须同时掌握“源文件位置”与“已发布路由”两套坐标。选择交付物规划、实施与边界控制SKILL.md 的 “Choose the Deliverable” 一节规定了交付物判定规则跨分区所有权、导航层级、已发布 URL 变更属于维护者级决策请求是“规划 / 审计 / 提案结构”时在信息架构、所有权映射与 URL 迁移计划之后就停止请求是“重构”时实施计划、执行校验并报告完成的迁移工作范围锁定在命名的文档分区内相邻技术债单独报告不顺手混入本次重构允许跨分区移动当规范所有权确有需要时但必须在计划与迁移报告中显式标明该移动只有当选择会改变主题所有权、公开 URL、支持的变体或用户工作流时才向请求方提出选项常规细节遵循仓库既有惯例。这一节把“做什么”与“做到什么程度”分开避免规划请求被悄悄升级成实现也避免重构请求被卡在无关的样式决策上。Step 1编辑前先建所有权清单structure.mdStep 1要求通读整个分区而不是抽样最长的页面并执行五步盘点为 OpenClaw、Hermes、Deep Agents 每个导航变体列出所有页面与嵌套分组仓库中实际还有 Pi 变体见后文变体生成机制列出源页面中每个 H2/H3再映射没有自己的标题但承载实质内容的散文块、表格、callout 与按 provider 区分的操作步骤找出入站链接、旧路由与锚点引用、重定向、发布说明链接、README 链接、测试、生成页面映射、以及点名当前文档所有者的源注释与仓库指令记录每个变体渲染哪些页面或内容块识别重复的步骤、故障排查指引、参考事实与相关主题列表。仓库级发现建议用rg技能给出了起步命令rg -n ^(##|###) docs/section rg -n section-slug|page-slug|page-title docs fern README.md test scripts盘点完成后先创建所有权清单表再提出新目录当前页面或分区用户任务变体规范所有者动作既有主题读者想完成什么适用的指南目标页面保留 / 拆分 / 移动 / 合并 / 删除硬性约束每个旧的 H2 和 H3 都必须出现在这张表里。这保证重构是“有台账的搬迁”而不是凭感觉改写。Step 2按用户旅程设计目录structure.mdStep 2给出默认的用户旅程序列——某阶段没有实质读者任务就省略绝不为凑齐序列而造薄页面Choose选择帮读者在 provider、模型、部署方式或方案之间做选择Set Up搭建不同 provider/平台/集成的步骤差异大时各自拥有独立页面Operate操作检查、切换、配置、生命周期与日常管理Validate验证证明配置与运行时行为不混入宽泛的故障排查Troubleshoot and Reference排障与参考可复用的失败处置与查询材料放在规范 Reference 分区。仅在“选择/操作之前读者确需独立心智模型”时才增加About / Understand页不要为了给分区一个可点击的首项而创建总览页。配套导航规则这些规则直接对应docs/index.yml的节点结构分区标题与可折叠 TOC 节点必须是不可点击的分组节点只包含section、slug、contents以及collapsed等展示设置所有读者内容放在子页面默认root section → task group → page三层除非材料证明存在真实的第三层区分否则不加深每页一个主主题或用户任务前置条件与即时成功验证可以留在同页但不同用户目标、不同 provider 流程、可复用概念与可复用参考资料必须拆页页面标题偏好动词开头Choose、Set Up、Configure、View、Switch、Verify、Troubleshoot分组标签用简短名词短语provider/平台特定步骤放独立页面而不是往通用页面追加更多分区各变体尽量复用分组 slug 与顺序省略不支持的页面从不发布空分组。仓库中 docs/index.yml 正是这套规则的落地形态例如 Inference 分区约第 55 行起就是section: Inferenceslug: inference下挂Choose a Provider and Model、Hosted Inference、Local Inference、Custom Endpoints、Manage Inference、Validate Inference等子分组页面 slug 均为choose-…、set-up-…、view-…、switch-…、verify-…这类动词开头命名——SKILL.md 最后特意点名Inference 分区是这套方法的“活例子”其结构把“About Inference Routing理解推理路由对应 docs/inference/how-inference-routing-works.mdx”、选择 provider 与模型、托管/本地/自定义三条搭建路径、管理、验证、以及规范的 Reference 排障分开。技能同时提醒可以复用它的推理与一致性规则但不要照抄推理专属的页面名。Step 3确立规范所有权structure.mdStep 3要求在移动内容之前把每个事实、步骤、故障模式指派给唯一页面搭建步骤留在聚焦的搭建页日常操作留在 manage/operate 页验证行为留在验证页可复用的故障现象、诊断与处置移入规范 Reference 排障区若 docs/reference/troubleshooting.mdx 仍是聚焦的负责人就用它若规范页本身过大则改建成一个不可点击的 Troubleshooting 分组 聚焦子页面而不是继续养大单体页结构化查询材料保留在 Reference对同一内容链接到规范位置而不是在多个页面复述移动排障/参考内容前先在目标位置搜索相同症状、标题、命令与特征短语——已有文档则合并不留较短的重复副本旧页面的每一个独特事实都必须保留两个页面表述不一致时向权威来源核实行为而不是选更新的措辞。Step 4URL 迁移契约migration.mdStep 4要求在删除或重命名文件之前先建路由表旧已发布路由新已发布路由变体是否需要重定向内容所有者旧 URL最终页面 URL适用指南是/否源 MDX 页面若一个旧页面将拆成多个目的地还要建锚点迁移表旧路由与锚点新路由与锚点入站引用动作旧页面片段最终主题片段文档、发布说明、README、测试或源码更新入站链接记录不可避免的锚点损失路由规则逐条对应 fern/docs.yml 的 redirects 配置约定已发布 URL 由docs/index.yml中分区与页面的slug层级派生不来自源文件目录MDX 内使用无扩展名的路由式链接永不链接或重定向到不可点击的分区节点为受支持的旧形态加重定向包括latest与非latest、变体路由、以及存在过的变体化之前的扁平路由每条重定向直接指向最终页面不造重定向链审计通配符优先级确保通配符目标也直接解析到已发布页面当仓库或外部引用证明.html、index.html旧形态曾被发布或引用时必须保留其直接重定向每个重定向目标必须在“其来源所代表的每一个变体”下均已发布被删除的落地页/分区根路由重定向到第一个真正有价值的页面而不是空的替代总览页移动后的排障内容链接指向规范参考页有必要时带具体锚点历史发布说明链接在其原页面被拆分时更新到最相关的规范主题不能靠页面级重定向找回被移动的锚点语义共享源页面可以通过_build/agent-variants/*.generated.mdx路径出现在导航中那些是被忽略的构建产物——永远编辑源页面与导航映射而不是生成文件。“重定向直接指向最终页”“.html形态直接重定向”“通配符优先级”这几条并非空谈仓库里有对应的确定性检查scripts/check-docs-published-routes.mts 中findMissingDirectLegacyManageSandboxRedirects约 L179-L210要求 Manage Sandboxes 的.html/index.html旧形态各自有一条直接重定向避免“先剥掉.html、再靠第二条重定向跳最终页”的链式写法findMissingDirectLegacyReleaseNotesRedirects约 L213-L292则枚举 Release Notes 全部 15 个旧形态含.html、/index.html、.md、.mdxlatest与非latest两套并检查它们必须排在泛化通配符如/nemoclaw/:path*.html之前否则更具体的规则会被通配符抢先。Step 5 与 Step 6内容安全的实施顺序与可读性修正migration.md 规定实施必须按“内容安全”的六步顺序创建目标页面并搬移全部映射内容把重复内容合并进规范所有者为每一个受支持的指南变体更新docs/index.yml更新路由式链接与相关主题列表在fern/docs.yml添加直接重定向只有当旧源页面的独特内容与入站路由都已交代清楚后才删除被取代的源页面。同时遵循面向公开文档的规则与重构专属规则简单 Markdown 列表相邻项之间不留空行含AgentOnly块的共享列表在变体渲染后必须结构完整需要检查生成的变体输出结构性拆分期间保留可运行的命令与行为断言不做顺手的大段改写。随后Step 6在结构重构完成后单独跑一遍可读性修正一个散文块满足任一条件即成为评审候选——4 个及以上句子、约 70 词以上、约 400 字符以上、或承担多个目的跨条件块拼接的长段落即使低于阈值也要评审。修正是同主题想法拆成短段落块内含不同任务/决策/阶段时加描述性 H2/H3不为单薄的段落加标题不为缩短而改写事实保留命令、链接、callout 语义、技术断言、路由所有权与 agent 适用性。机械统计段落大小时排除 frontmatter、代码围栏、表格、标题、JSX 标签与单个列表项。修正后要重新生成 agent 变体并检查生成的 OpenClaw、Hermes、Deep Agents 页面中是否出现源文件没有的稠密块——当移除AgentOnly包裹使变体特定文本与共享文本拼在一起时要在条件块两侧补回源段落边界再重新生成直到源与生成页的段落块都可读为止。变体机制为什么“重新生成”是硬性步骤“重新生成 agent 变体”之所以是流程中的一等步骤是因为 NemoClaw 的文档站为四个 agent 变体openclaw、hermes、deepagents、pi定义于 scripts/sync-agent-variant-docs.mts 第 12 行的agentVariants常量分别渲染导航。该脚本的核心机制直接解释了上文多条规则的必要性AgentOnly variant...指令stripAgentOnlyBlocksForVariant约 L94-L142按活动变体保留或剥除条件块且禁止嵌套渲染后若残留AgentOnly标签、AgentGuideimport 或运行时组件assertStaticallyResolvedVariantPage会直接抛错让npm run docs失败$$nemoclawCLI 哨兵共享源用哨兵$$nemoclaw表示 CLI 名按变体替换为nemoclaw/nemohermes/nemo-deepagentscliForVariant约 L527-L531只在单变体页面使用哨兵会被assertNoUnsharedPlaceholders拒绝会按字面量渲染命令参考页特殊处理reference/commands.mdx的 frontmatter 会被按变体改写标题、描述、description-agent、keywords 与sidebar-titleupdateCommandsFrontmatter约 L349-L408正文中的nemoclaw调用、命令替换与锚点也会被transformNemoclawCliInvocations约 L776-L794改写同时保护nemoclaw onboard --agent hermes等不可别名化的字面量空节检查assertNoEmptyVariantSections约 L252-L309会拒绝“某标题在另一变体的AgentOnly块里而本页渲染为空”的写法——这正是 Step 6 要求“在移除AgentOnly包裹时补回段落边界”的机器执行者生成文件写入docs/_build/agent-variants/相对目录/基名.variant.generated.mdx头部带“由脚本生成、禁止手改”的注释写入前会清理过期生成文件。因此 SKILL.md 与 migration.md 中“编辑源页面与导航映射而不是生成文件”“变体渲染后检查列表结构”等规则本质上是与该脚本的契约对齐。Step 7用确定性检查验证重构validation.mdStep 7给出的标准校验命令与 package.json 中的脚本一一对应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其中docs:sync-agent-variants实际是docs:prepare的别名先生成 starter prompt 再运行变体同步而npm run docs会执行docs:strict即docs:preparedocs:validatestarter prompt 检查、--check模式的变体同步、docs:check-routes最后以fern.config.json锁定的 Fern 版本运行fern check。两个 vitest 用例分别测试 check-docs-published-routes.mts 的路由/重定向逻辑与文档链接检查。若被重构分区不在现有已发布路由检查器的覆盖内要新增或扩展聚焦的路由测试并“测试可观察的已发布路由与重定向而不是源文件相对假设”。check-docs-published-routes.mts 的实现值得细看buildPublishedRouteIndex约 L139-L157解析 docs/index.yml按walkLayout约 L77-L137从每个变体 layout 的 slug 链拼出/user-guide/variant/...路由集合并且对没有显式 slug 的节点直接抛错因为 Fern 会从 title 派生 slug会静默偏移下游全部路由findBrokenPublishedRoutes把页内相对链接按“链接页的已发布路由”而非“源文件目录”解析resolvePublishedRoute约 L348-L364——这正是 SKILL.md 强调“先读导航与重定向再编辑”的机器版本。脚本尾部维护了一份GUARDED_SOURCE_PAGES守卫清单约 L590-L612把历史上反复回归的reference/commands.mdx、整个configure-agents/、inference/、manage-sandboxes/与若干 deployment 页面全部纳入逐页路由校验。构建完成后validation.md 还要求完成一组人工/脚本混合审计搜索每一个被删文件名、旧 slug、旧标题、旧路由搜索每一个被移动锚点并更新语义目的地已改变的引用在源注释、包级AGENTS.md、测试与脚本中搜索点名旧文档所有者的语句确认没有页面链接到可折叠分区根确认所有重定向在适用变体下终止于已发布页面把旧标题清单与新页面对照交代每一个独特主题在规范排障/参考目的地搜索重复标题与重复处置变体块或共享列表变化时检查生成的 OpenClaw/Hermes/Deep Agents 页面确认简单列表相邻项间无空行导航深度、标题或条件内容变化时在 Fern 预览中目检仓库提供npm run docs:live与npm run docs:preview:watch支撑本地预览。最后一条认知校准非常重要把自动链接反馈当作假设。Fern 按已发布 slug 路由解析链接合法链接可能不匹配源文件相对路径编辑前先对照docs/index.yml、fern/docs.yml、生成变体映射与确定性路由检查核实链接告警——即使页面路由存在缺失的锚点仍可能是真实问题。Step 8独立的文档评审validation.mdStep 8要求对完成的“纯文档变更”跑一次独立的文档写作者评审把旧→新所有权映射交给评审者让它检查内容丢失、重复所有权、变体漂移、坏重定向、过大段落块、生成的段落拼接与风格回退——不告诉它预期结论应用有效发现后重跑受影响的检查。这与 documentation-writing-review.md 中“完成整个被指派的评审、一次性报告全部有证据的发现、不因发现阻塞项就提前终止”的要求一致。完成契约与结果报告SKILL.md 用“Completion Contract”把两类请求的完成标准分开。规划类请求的完成意味着所有权映射、拟议结构、路由迁移计划与未决决策已被记录下述实现类检查不适用。已实施的重构则要求全部满足读者可选择的每个可见 TOC 项都是真实主题页每个可折叠分组节点都不可点击、且无页面内容每页只拥有一个主主题或任务每个旧分区都被映射到目的地或被明确说明理由后有意移除排障与参考指引各有一个规范所有者没有受支持变体渲染出指向未发布页面的链接或重定向旧 URL 直接重定向到最终已发布页面共享内容在每个适用 agent 变体下正确渲染源页面与生成变体页面都没有未解决的过大或多用途散文块简单列表保持紧凑文档构建、路由检查、链接检查与 diff 检查全部通过。实施完成后的报告需覆盖最终的旅程式 TOC创建/移动/合并/删除的页面排障与参考的规范所有权决策保留的重定向与旧路由变体间差异对稠密段落块做的可读性编辑校验命令与结果以及有意延后的相邻清理对应前述“报告相邻债而非顺手合并”的边界规则。小结方法要点速查环节核心动作仓库证据前置读目标页、docs/index.yml导航、fern/docs.yml重定向、入站链接docs/index.yml、fern/docs.yml盘点每页 H2/H3 全部入台账rg全仓搜索引用structure.md Step 1设计Choose/Set Up/Operate/Validate/Troubleshoot 旅程分组节点不可点击动词页标题docs/index.yml Inference 分区活例所有权一主题一主页排障入规范 Reference链接不复述docs/reference/troubleshooting.mdx迁移先路由表与锚点表重定向直达最终页不编辑生成文件migration.md Step 4实施六步内容安全顺序列表紧凑保留命令与行为断言同上 Step 5可读性≥4 句/约 70 词/约 400 字符/多用途即评审修后重新生成变体scripts/sync-agent-variant-docs.mts校验npm run docs:sync-agent-variants、npm run docs、两个 vitest 路由/链接测试、git diff --checkvalidation.md、package.json评审独立评审者持所有权映射查丢失/重复/漂移/坏重定向documentation-writing-review.md按这套流程执行重构的结果是目录按读者旅程组织、每个事实有唯一规范所有者、旧 URL 全部直达新页面、四个 agent 变体渲染一致并且每一步都有仓库内可重跑的确定性检查兜底。【免费下载链接】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），仅供参考