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路由。它的职责不是重新定义写作规则而是回答三个问题哪些表面Surface必须遵守它任何编写或评审 Agent 回复、进度更新、工具调用标签与描述、GitHub 文本、评论、测试标题、文档、变更日志条目、公告Announcements、维护者指引的技能都必须使用该契约。遇到不同类型的文字改动应加载哪份规范解释性文字改动跟随写作指南面向公众的文档改动跟随文档贡献指南。评审任务应覆盖到什么程度完成分配的完整评审而非找到第一个阻塞性问题就停止。用契约原文的话说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 guides rules into a skill的要求互为表里。二、评审前的加载动作按表面选择规范契约将评审流程的第一步定义为为当前表面加载对应指引Load the Guidance for the Surface共三条目标表面应加载的规范职责边界任何被改动的解释性文本WRITING.md拥有主张准确性claim accuracy、写作规则、评审范围、术语路由面向公众的文档docs/CONTRIBUTING.md拥有文档流程、模式与验证契约中 Agent-Written Text 定义的每个边界WRITING.md 的对应要求Agent 发送消息、在 GitHub 发布文字、发起带可见标签的工具调用之前必须应用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评审完整的 diff 与 PR 文本并完成每一个适用的评审类别不得在第一个阻塞性发现后停止必须把全部有证据支持的发现汇总到一份评审结果中。发现与行为、安全、数据安全、测试或发布歧义相关的问题时检查相邻路径把实现同一操作或同类失败模式的未改动兄弟路径也纳入检查范围。按根因对重复发现分组并给出代表性位置representative locations。不要在未改动的文本中要求无关清理——评审范围始终以被 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输入信任与命令构造Input trust and command construction输入来自哪里、是否可信、如何进入命令。凭据的位置、访问、生命周期、传输与移除Credential location, access, lifetime, transfer, and removal与 WRITING.md 对凭据命名位置、访问、生命周期与移除的要求一一对应。命令与传输的状态传播Command and transport status propagation状态是否如实回传、失败是否被吞掉。结果分类Result classification区分成功、无法定论的验证inconclusive verification与基础设施故障。动作分类Action classification区分回滚rollback、重试retry与停止stop。资源所有权、清理与缺席确认Resource ownership, cleanup, and absence confirmation。部分外部写入与授权边界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 中提交任何解释性文本或文档改动前可按该契约做如下自检表面识别这段文字属于 Agent 回复、工具标签、测试标题、变更日志、用户文档还是维护者指引是否在契约适用范围内规范加载解释性文本是否遵循 WRITING.md公众文档是否遵循 docs/CONTRIBUTING.md术语是否命中 受控词表事实核对命令、默认值与行为是否对照源码/测试/脚本验证过凭据四要素位置、访问、生命周期、移除是否齐全失败与回退结果是否写明评审完整性是否覆盖全部评审类别、检查了相邻路径、按根因分组并在汇总一份结果后才给出 blocker 与 suggestion验证执行文档改动是否运行npm run docs并修复docs/_build/暴露的问题是否获得独立文档写作评审提交与记录是否使用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考