企业官网建设流程全解析

NemoClaw AGENTS.md 深度解析：面向 AI 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

NVIDIA NemoClaw 是一个将 OpenClaw、Hermes 等常驻 AI Agent 安全地运行在 NVIDIA OpenShell 沙箱中的开源参考栈。仓库根目录的 AGENTS.md 是面向编码 Agent 的"操作手册"，它定义了产品范围门禁、Agent 技能体系、开发与测试契约、蓝图镜像 Pin 以及 PR 验收要求。本文以该文档为主体，结合仓库源码与测试，逐节解读这套"机器可读的协作规范"，帮助你理解如何在 NemoClaw 仓库中合规地贡献、测试与发布。

文档定位：AGENTS.md 不是写给人类的说明，而是仓库的"数字宪法"

在 NVIDIA NemoClaw 仓库（根目录 AGENTS.md，同时CLAUDE.md是指向它的符号链接）中，AGENTS.md 承担着为 AI 编码 Agent（如 Claude Code、GitHub Copilot 等）提供"仓库操作上下文"的职责。它与传统的 CONTRIBUTING.md 不同：

• CONTRIBUTING.md面向人类贡献者，说明提交流程与行为准则；
• AGENTS.md面向 Agent 运行时，说明"在动手改代码之前必须先知道什么"——包括哪些变更需要产品决策授权、哪些技能（Skill）负责哪个生命周期阶段、哪些命令用于验证改动、哪些路径属于什么职责边界。

从仓库结构看，这套 Agent 治理体系分布在多个层级：

• 根 AGENTS.md：仓库全局指令（本文主体）；
• 包级AGENTS.md：如 src/lib/messaging/AGENTS.md，承载消息通道架构与迁移指引；
• docs/AGENTS.md：文档 Agent 的工作流与 DORI 路由；
• .agents/skills/：可执行的技能目录，按nemoclaw-contributor-*、nemoclaw-maintainer-*、nemoclaw-user-guide分门别类。

产品范围门禁（Product Scope Gate）：技术正确不等于产品批准

AGENTS.md 首先声明了一个容易被忽视的硬性约束："Technical correctness, passing tests, and green CI do not establish product approval."也就是说，代码能跑、测试全绿、CI 通过，都不构成"这个功能算 NemoClaw 官方支持"的证据。

具体规则可以拆解为：

若产品决策缺失，则不能将贡献作为"规范 NemoClaw 行为"批准或记录；应停下来请求维护者指示，或通过 Community Solutions 走独立方案。

仓库中的managed-inference/、agents/（Hermes、LangChain Deep Agents、OpenClaw 各变体）正是这类"产品面"的典型：例如agents/hermes/manifest.yaml、agents/openclaw/manifest.yaml以及 managed-inference/presets/ 下的 YAML 配方，都属于受该门禁约束的受支持集成，新增此类内容必须先有Accept决策。

Agent 技能体系：按生命周期阶段分工，一个阶段一个 Owner

仓库的 Agent 能力并不写在 AGENTS.md 正文里，而是以技能（Skill）的形式放在.agents/skills/下（.claude/skills是指向.agents/skills的符号链接，两个路径解析到同一内容）。AGENTS.md 给出的路由规则是：

• 面向终端用户的文档路由 →nemoclaw-user-guide；
• 贡献者工作流 →nemoclaw-contributor-*；
• 维护者工作流 →nemoclaw-maintainer-*；
• 选择技能或浏览目录 →nemoclaw-skills-guide；已知技能则直接调用，不预加载整条生命周期栈。

贡献者生命周期采用"一阶段一 Owner"的串行分工：

组件专属指导必须写在组件所属包的AGENTS.md中，而不是塞进技能里。技能编写本身也有契约：描述要短且具体；条件性流程放 references，完成标准放 entrypoint；保留具体的安全、发布与发布约束，避免无消费者的通用清单；涉及解释性文本的技能必须遵守共享的 Documentation Writing and Review 契约；技能工作流要保持 Agent 框架无关（state capabilities、actions、observable results，而不是要求特定的工具名）。

开发指引与快速参考：从检出到验证的命令矩阵

AGENTS.md 要求：涉及源码、测试、构建工具或 Git hook 的改动，先读 Development Reference——它拥有架构地图、语言约定、测试通道与 hook 行为；涉及消息通道的改动还要读 src/lib/messaging/AGENTS.md。

快速参考表是高频使用的核心命令，结合源码进一步说明：

从 package.json 的 scripts 可以看到更完整的验证矩阵：npm test会先清理并构建 CLI 与插件再跑cli、integration、installer-integration、package-contract、plugin、e2e-support六个 Vitest 项目；npm run test:fast只跑cli、plugin、e2e-support；npm run validate:pr调用scripts/checks/validate-pr.mts，要求干净的已提交树并执行只读格式化检查。

scripts/dev-setup.sh的实现印证了 AGENTS.md 的边界承诺——其 usage 输出明确：setup 永不修改宿主包、全局 Git 配置、GitHub 状态、签名密钥、凭据、许可证或沙箱；CLI 暴露（--expose-cli）与运行时 onboarding（--with-runtime）都是显式 opt-in。

仓库工作规范：范围、E2E、平实语言与直接设计

范围与完成（Scope and completion）

遵循用户请求的结果与既有授权。仓库技能提供任务知识与操作约束，但不得添加未被请求的工作，也不得要求用户重复授权；绑定不可逆操作的特定确认仍然适用。需要暂停时，必须点名文件、引用需求并说明缺失的决策；在该决策挂起期间，继续独立的已授权工作。

实现、检查与适用的验证必须完成：修复由改动引起的失败并重跑受影响的检查，无需每步都询问；被请求时才进入 PR 发布与评审跟进；"首个补丁"或生命周期移交不算完成。本地验证须保持在测试记录的效果范围内；实时 E2E 与外部写入保留各自的授权边界；./scripts/dev-setup.sh --expose-cli仅在明确批准时使用。

E2E 选择与编写

新增或扩展 E2E 测试前必读 E2E authoring reference，它拥有行为选择、覆盖粒度与有界重试要求；执行或证据检查用nemoclaw-maintainer-e2e。从 test/README.md 可知，E2E 测试分e2e/support/（e2e-support项目，确定性测试）与e2e/live/（e2e-live项目，会变更外部真实状态、运行在临时 Brev 云实例上的 opt-in 目标）两层，断言预算由ci/e2e-assertion-budget.json以棘轮（ratchet）方式约束，npm run e2e:assertions:check会拒绝断言数量增长或基线过期。

平实语言与直接设计

所有 Agent 撰写的文本遵循 WRITING.md。这是一份把航空业简化英语标准（ASD-STE100 Issue 9）的原则应用到软件工程写作的指南：句子要短、动作要直接、"must/may/can/should" 语义严格区分、指令控制在 20 词以内、描述控制在 25 词以内、一个概念一个术语、去掉just/simply/obviously/robust等空洞修饰。配套的受控词表在 .agents/skills/_shared/controlled-words.md。

"直接设计"（Direct Design）原则：只为当前的需求与消费者添加机制，验证方式与改动行为匹配；完成最小的请求结果并报告证据。

Git/GitHub 访问失败与 PR 跟进

访问失败与机械式 Git 恢复遵循 .agents/skills/_shared/git-github-hard-stop.md；PR 发布后的跟进遵循 .agents/skills/_shared/pr-follow-up.md。

常见模式（Common Patterns）：新增功能时该往哪里放

AGENTS.md 给出了四类高频扩展的落地路径，与仓库目录一一对应：

新增 CLI 命令

• 入口：bin/nemoclaw.js——它加载dist/中已编译的 CLI（编译产物在dist/lib/，从src/lib/编译而来）；
• 测试放在test/下。

从 bin/nemoclaw.js 的实现看，这个入口还承担了环境适配：被调用为nemo-deepagents时注入NEMOCLAW_AGENT=langchain-deepagents-code；顶层错误会经过redactForLog脱敏后再输出，避免敏感信息泄漏。注意 package.json 同时声明了nemoclaw、nemoclaw-acp、nemoclaw-blueprint-runner、nemohermes、nemo-deepagents五个 bin。

新增插件功能

• 源码在nemoclaw/src/，测试以*.test.ts与源码同目录共存（co-located）；
• 构建命令cd nemoclaw && npm run build。

nemoclaw/是独立的 npm 工程（有自己独立的package.json与node_modules），注册 OpenClaw 的/nemoclawTUI 斜杠命令（见 nemoclaw/openclaw.plugin.json）。它的子目录分工明确：src/blueprint/（runner、snapshot、SSRF 校验、状态管理）、src/commands/（斜杠命令与迁移状态）、src/onboard/（onboarding 配置）。

新增网络策略预设（network policy preset）

• 在nemoclaw-blueprint/policies/presets/下新增 YAML；
• 遵循现有预设结构（参考github.yaml、brave.yaml）。

仓库现有 24 个预设（brave、brew、claude-code、github、gmail、huggingface、jira、local-inference、local-memory、npm、pypi、tavily、weather等）。以 github.yaml 为例，其注释揭示了设计动机：曾经github.com/api.github.com加 git 二进制被静默包含在基础沙箱策略中，导致每个沙箱都能 clone/push/调 GitHub API；移入预设后恢复最小权限（least-privilege）——只有用户显式选择该预设（nemoclaw onboard时，或事后openshell policy set）沙箱才有 GitHub 访问。预设结构包含preset.name、preset.description、network_policies.<name>.endpoints（host/port/access）与binaries列表。

新增模型专属沙箱兼容（model-specific sandbox compatibility）

• 在nemoclaw-blueprint/model-specific-setup/<agent>/下加声明式清单；
• 一个 manifest 只对应一个agent（openclaw、hermes等），禁止共享的多 Agent manifest；
• OpenClaw 可执行包装器放nemoclaw-blueprint/openclaw-plugins/；
• Hermes 可执行包装器放agents/hermes/；
• 保持agents/hermes/generate-config.ts为薄构建时入口，Hermes 的 env 解析、配置构造、registry 处理与序列化放agents/hermes/config/；
• 不为 OpenClaw 的问题添加 Hermes 行为，除非有 Hermes 专属的复现或验收测试。

仓库 model-specific-setup 下已有hermes/与openclaw/（后者含nemotron-3-super-120b-managed-inference.json、gemini-3-managed-inference.json、kimi-k2.6-managed-inference.json等模型兼容清单），并有 schema.json 约束清单格式。

蓝图镜像 Pin：不可变摘要的双重绑定

这是 AGENTS.md 中最具 NemoClaw 特色的工程约束之一。当受管理沙箱镜像变化时，必须同时更新nemoclaw-blueprint/blueprint.yaml中的两个字段：

1. 顶层digest字段；
2. components.sandbox.image字段。

两者必须使用同一个不可变 SHA-256 摘要，发布工具必须成对更新。test/onboarding/validate-blueprint.test.ts 会拒绝可变标签（mutable tags）与不匹配的摘要。

为什么这么设计？blueprint.yaml 的注释说明了原委（issue #1438）：顶层digest让下游消费者或发布工具无需解析 components 树即可校验蓝图声明的沙箱镜像，同时堵住了"有人升级了 Pin 的镜像却忘记顶层字段"这种可轻易绕过的路径；components.sandbox.image固定到具体摘要（如ghcr.io/nvidia/openshell-community/sandboxes/openclaw@sha256:b3d8…），是为了防止将来 registry 被攻破或有人误 force-push:latest时沙箱镜像被静默替换。这正是供应链安全中"不可变引用"（immutable reference）思想的落地。

从测试侧印证：test/onboarding/onboard-extra-provider-reconciliation.test.ts的 fixture 同时出现ref: "…@sha256:aaaa…"与digest: "sha256:aaaa…"两个字段；test/onboarding/onboard-fresh-create-identity.test.ts校验沙箱以@sha256:摘要引用、并警告"Do not delete the sandbox by mutable sandbox name"。而test/onboarding/blueprint-name-schema.test.ts则从另一个角度守护安全：拒绝命令替换（$(id)）、前导数字、前导横线、空白与控制字符、129 字符等非法蓝图名称——这些正是把 YAML/Shell 注入面挡在沙箱编排入口之外。

常见陷阱（Gotchas）：Agent 最容易踩的四个坑

AGENTS.md 特意为 Agent 列出了四类高频问题：

1. 根目录npm install会触发prek install安装 git hooks：如果 hooks 安装失败，检查core.hooksPath是否被设置，执行git config --unset core.hooksPath。从 package.json 的prepare脚本可以确认：npm install的 prepare 阶段会运行bash scripts/npm-link-or-shim.sh，并在存在prek时执行prek install。
2. nemoclaw/子目录是独立 npm 工程：有自己的package.json和node_modules，但共享根目录的 Oxlint 与 Oxfmt 配置（oxlint.config.ts、oxfmt.config.ts）。
3. 覆盖率阈值带棘轮：ci/coverage-threshold-cli.json与ci/coverage-threshold-plugin.json保存基线，新代码不应降低 CLI 或插件的覆盖率；npm run test:coverage:cli、npm run test:coverage:plugin会用scripts/check-coverage-ratchet.mts校验。
4. .claude/skills是指向.agents/skills的符号链接：两个路径内容相同（已由ls -la .claude确认）。

文档治理与 PR 要求

文档（Documentation）

• docs/是面向公众文档的事实来源（source of truth）；文档 Agent 工作流（含 DORI 路由）遵循 docs/AGENTS.md。
• 普通代码 PR 可把docs/**、fern/docs.yml、fern/assets/**的变更延迟到 "Docs / Author Post-Merge Catch-Up"；但其余所属仓库指引必须留在同一 PR 中，包括存活的AGENTS.md文件、.agents/skills/**与test/e2e/**/README.md。
• 纯文档改动遵循 docs/AGENTS.md、共享的 Documentation Writing and Review 契约、已记录的验证流程与独立评审。

PR 要求（PR Requirements）

• 发布走nemoclaw-contributor-create-pr技能；
• 改动scripts/prepare-dgx-station-host.sh的 PR 必须附带可评审的 DGX Station 测试证据：注明被测试的提交、Station profile 或场景、结果与支撑链接；任何维护者可评审该证据；无合格证据则不得批准或合入；该证据视为人工评审而非经认证的硬件来源；例外情况走既有仓库治理并在 PR 上说明理由；
• 禁止提交 secrets、API keys 或凭据；
• 检查.github/pr-limits.json中贡献者的开放 PR 数量上限。

仓库还从两个维度加强"凭据零提交"：src/lib/security/redact（bin/nemoclaw.js 的顶层错误脱敏即依赖它）与scripts/checks/direct-credential-env.mts（直连凭据环境变量检查）。覆盖率棘轮、断言预算、npm run validate:pr等机制共同构成多层防线。

结语：把"协作规范"变成可验证的工程约束

NemoClaw 的 AGENTS.md 提供了一种值得借鉴的仓库治理范式：它没有停留在"请遵守规范"的口号层面，而是把规范落到可执行的技能目录（.agents/skills/）、可验证的测试（test/onboarding/validate-blueprint.test.ts拒绝可变镜像标签、blueprint-name-schema.test.ts拒绝注入型名称）、可量化的棘轮（覆盖率、E2E 断言预算）与明确的命令契约（dev:setup/dev:doctor/test:changed/validate:pr）上。对任何希望在 AI 辅助开发时代维护大型开源仓库的团队来说，这套"数字宪法 + 可执行技能 + 机器可验证约束"的三层结构，都是一个可直接复用的参考模板。

如需进一步深入，推荐按此顺序阅读：根 AGENTS.md → Development Reference → test/README.md → blueprint.yaml → WRITING.md，再从.agents/skills/中按生命周期阶段选择对应技能实践一遍贡献流程。

【免费下载链接】NemoClawRun agents like Hermes, LangChain Deep Agents, and OpenClaw more securely inside NVIDIA OpenShell with managed inference项目地址: https://gitcode.com/gh_mirrors/ne/NemoClaw