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 仓库的共享契约 documentation-writing-review.md 为主体，解析这套"文档写作与评审路由"机制的定位、适用面、执行步骤与验收标准，并结合仓库内的 WRITING.md、docs/CONTRIBUTING.md 与相关技能文件，说明它如何在 Agent 产出文字、GitHub 评论、测试标题、变更日志、用户文档等所有解释性文本上落地。读完本文，你将掌握 NemoClaw 中"写什么—按什么规范写—如何评审—评审到何种边界才算完成"的完整技术链路，可直接复用于同类开源项目的文档治理设计。

一、契约定位：一套"路由"而非一份"写作规则"

该文档的标题是Documentation Writing and Review Routing，关键词是Routing（路由）。它的职责不是重新定义写作规则，而是回答三个问题：

1. 哪些表面（Surface）必须遵守它：任何编写或评审 Agent 回复、进度更新、工具调用标签与描述、GitHub 文本、评论、测试标题、文档、变更日志条目、公告（Announcements）、维护者指引的技能，都必须使用该契约。
2. 遇到不同类型的文字改动，应加载哪份规范：解释性文字改动跟随写作指南，面向公众的文档改动跟随文档贡献指南。
3. 评审任务应覆盖到什么程度：完成分配的完整评审，而非找到第一个阻塞性问题就停止。

用契约原文的话说："Use this routing contract in any skill that writes or reviews agent responses, progress updates, tool-call labels or descriptions, GitHub text, comments, test titles, documentation, changelog entries, Announcements, or maintainer guidance."（见 .agents/skills/_shared/documentation-writing-review.md）。

这一设计避免了"每份技能各自复制一套写作规范"的维护灾难：仓库根级 AGENTS.md 明确要求"Skills that write or review explanatory text must follow the shared Documentation Writing and Review contract"，同时在 AGENTS.md 中规定直接文档改动必须遵循该契约、经过文档验证与独立评审。规范只维护一份，其余文件通过链接引用，这与契约中"Do not copy either guide's rules into a skill"的要求互为表里。

二、评审前的加载动作：按表面选择规范

契约将评审流程的第一步定义为"为当前表面加载对应指引"（Load the Guidance for the Surface），共三条：

2.1 写作指南的核心约束

WRITING.md 是 NemoClaw 的解释性文本事实来源，其总原则是"写出能让读者正确行动的最短文本"，并借鉴了 ASD-STE100 简明技术英语的平民语言原则（仓库明确声明不主张完全合规，见 WRITING.md）。几个关键技术规则：

• 准确性：命令、默认值与行为必须对照已检入的源码、测试或脚本验证；每个凭据（credential）必须说明其位置、访问、生命周期与移除方式；每个条件式或尽力而为（best-effort）的控制必须说明失败或回退结果。
• 直接性：指明行动者、动作与对象；被动语态仅在行动者未知或无意义时使用；使用must表示要求、may表示许可、can表示能力、should表示建议；指令尽量不超过 20 词，描述尽量不超过 25 词。
• 术语一致：一个概念一个术语，不因行文多样性使用同义词，并通过 controlled-words.md 受控词表统一全仓库术语。例如产品名必须写作NemoClaw（而非 nemoclaw/Nemoclaw）、OpenShell（而非 openshell/Open Shell）、Model Context Protocol (MCP)（首次出现展开全称），技术名词agent定义为"使用模型与工具完成任务的软件"，sandbox与container严格区分（见 .agents/skills/_shared/controlled-words.md）。

2.2 文档贡献指南的流程约束

docs/CONTRIBUTING.md 规定了用户可见改动的完整旅程：先在docs/下找到"拥有该行为"的页面并完整阅读（包括index.yml导航、生成的变体、入链与重定向）；编写时遵循 docs/STYLE.md（页面与过程结构、代码块、产品名）与 docs/AUTOMATION.md（变更日志、启动提示、变体、路由链接、发布）；随后在仓库根目录运行：

npm run docs

该命令会准备生成的文档并校验 Fern 配置、链接与 MDX；生成产物位于docs/_build/，应修复源文件而非直接编辑生成文件。文档专属改动不需要运行npm test或npm run check，除非改动触及生成的运行时行为、测试基础设施或其他仓库级契约。

三、完成分配评审：全量、邻接、按根因分组

契约对评审执行本身提出了严格的方法论约束（对应 .agents/skills/_shared/documentation-writing-review.md）：

1. 评审完整的 diff 与 PR 文本，并完成每一个适用的评审类别；不得在第一个阻塞性发现后停止，必须把全部有证据支持的发现汇总到一份评审结果中。
2. 发现与行为、安全、数据安全、测试或发布歧义相关的问题时，检查相邻路径：把实现同一操作或同类失败模式的未改动兄弟路径也纳入检查范围。
3. 按根因对重复发现分组，并给出代表性位置（representative locations）。
4. 不要在未改动的文本中要求无关清理——评审范围始终以被 PR 改动的文本为界。

这一条与 WRITING.md 的评审纪律完全对齐："Review only text changed by the PR unless the task requests an audit of existing text. Do not report unrelated writing problems in the current review."换言之，写作评审是"贴着 diff 走"的，只有任务明确要求审计既有文本时才扩大范围。

四、敏感运维流程的七类边界检查

契约专门为"敏感运维过程"（sensitive operational procedure）列出七类必须逐一审查的边界（见 .agents/skills/_shared/documentation-writing-review.md）：

1. 输入信任与命令构造（Input trust and command construction）：输入来自哪里、是否可信、如何进入命令。
2. 凭据的位置、访问、生命周期、传输与移除（Credential location, access, lifetime, transfer, and removal）：与 WRITING.md 对凭据"命名位置、访问、生命周期与移除"的要求一一对应。
3. 命令与传输的状态传播（Command and transport status propagation）：状态是否如实回传、失败是否被吞掉。
4. 结果分类（Result classification）：区分成功、无法定论的验证（inconclusive verification）与基础设施故障。
5. 动作分类（Action classification）：区分回滚（rollback）、重试（retry）与停止（stop）。
6. 资源所有权、清理与缺席确认（Resource ownership, cleanup, and absence confirmation）。
7. 部分外部写入与授权边界（Partial external writes and authorization boundaries）。

这套边界不是评审清单的堆砌，而是把"文档描述的运维流程是否可安全执行"拆解为可验证的维度。结合受控词表可以看得更清楚：rollback定义为"在不完整或不安全变更后返回已验证的较早状态"，retry定义为"同一操作未完成时再次尝试"，restore定义为"将快照应用到目标沙箱"——文档必须在这些词之间精确区分，否则评审者无从判断流程语义（见 .agents/skills/_shared/controlled-words.md）。

五、在仓库工作流中的落地方式

该契约并非孤立的评审说明，而是被多个技能与文档显式引用的共享契约：

• nemoclaw-contributor-update-docs/SKILL.md 在"加载当前权威"步骤中明确要求读取该共享契约，并规定不把写作规则、页面归属、路由约定、Agent 变体、变更日志格式或验证命令复制进技能本身——统一从当前文档指引、源码树、package 脚本与工作流中派生。
• 根级 AGENTS.md 与 AGENTS.md 将该契约设为所有会编写或评审解释性文本的技能与直接文档改动的强制前置。
• docs/CONTRIBUTING.md 要求文档专属交接前，必须由独立的"文档写作评审"（documentation writer review）对精确提交进行评审，评审必须覆盖：任务完整性与事实准确性；命令、选项、默认值与预期结果；变体、路由、导航与重定向覆盖；重复或错位的所有权；安全、凭据与生命周期主张；以及对WRITING.md与STYLE.md的合规性。每个有效发现都必须被解决或说明为何不适用，随后重跑受影响的验证。

六、评审结果的输出纪律

契约收尾处重申了一个常被忽视的纪律："Return blockers and suggestions only after completing the full assigned review. A blocker does not end the review pass."（阻塞性发现不终止评审轮次，见 .agents/skills/_shared/documentation-writing-review.md）。这意味着评审者必须先走完全部类别、邻接路径与敏感边界检查，再一次性汇总 blocker 与 suggestion。

配合 WRITING.md 的发现报告规则，写作发现的输出格式为：

• 指出被违反的具体规则；
• 在请求范围内引用代表性行；
• 给出保留技术含义的更短重写建议；
• 对同根因同改写的多个位置进行分组；
• 除非措辞会改变行为、安全、数据安全、测试含义或发布含义，否则写作发现一律视为建议（suggestion）；若为阻塞性发现，必须点名该影响。

七、快速自检清单

在 NemoClaw 中提交任何解释性文本或文档改动前，可按该契约做如下自检：

1. 表面识别：这段文字属于 Agent 回复、工具标签、测试标题、变更日志、用户文档还是维护者指引？是否在契约适用范围内？
2. 规范加载：解释性文本是否遵循 WRITING.md？公众文档是否遵循 docs/CONTRIBUTING.md？术语是否命中 受控词表？
3. 事实核对：命令、默认值与行为是否对照源码/测试/脚本验证过？凭据四要素（位置、访问、生命周期、移除）是否齐全？失败与回退结果是否写明？
4. 评审完整性：是否覆盖全部评审类别、检查了相邻路径、按根因分组，并在汇总一份结果后才给出 blocker 与 suggestion？
5. 验证执行：文档改动是否运行npm run docs并修复docs/_build/暴露的问题？是否获得独立文档写作评审？
6. 提交与记录：是否使用docs:作为 Conventional Commit 类型，并记录读者结果、改动页面与契约、验证结果、独立评审结果以及受影响的变体/路由/导航/重定向？

这套"单一契约 + 权威规范 + 全量评审 + 独立复核"的路由机制，使得 NemoClaw 在大量 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