为 NemoClaw 文档做贡献

本指南介绍如何撰写、编辑和审阅 NemoClaw 文档。如果你的代码更改影响了面向用户的行为，请在同一个 PR 中更新相关文档。

使用 Agent 技能

如果你使用 AI 编码代理（Cursor、Claude Code、Codex 等），仓库中包含可自动化文档工作的技能。在从头编写之前，请先尝试使用它们。

技能功能说明使用场景
update-docs扫描近期提交中面向用户的更改，并起草文档更新。功能合并后、发布前，或查找文档缺口时使用。

这些技能位于 .agents/skills/ 中，会自动遵循以下风格指南。要使用某个技能，让你的代理运行它即可。例如，你可以要求它”追赶自 v0.2.0 以来合并的所有内容的文档”。

何时更新文档

当你的更改涉及以下情况时，请更新文档：

  • 添加、移除或重命名 CLI 命令或标志。
  • 更改默认行为或配置。
  • 添加用户会交互的新功能。
  • 修复了文档中描述不正确的 bug。
  • 更改了 API、协议或策略 schema。

本地构建文档

通过构建文档并检查输出来验证文档是否正确。

要构建文档，请运行：

make docs

要在本地提供文档服务并在更改时自动重新构建，请运行：

make docs-live

写作规范

格式

  • 文档使用 MyST Markdown，这是 CommonMark 的 Sphinx 兼容超集。
  • 每个页面以 YAML frontmatter 开头（title、description、topics、tags、content type）。
  • 在 frontmatter 之后包含 SPDX 许可证头。

Frontmatter 模板

---
title:
  page: "NemoClaw Page Title — Subtitle with Context"
  nav: "Short Nav Title"
description: "One-sentence summary of the page."
keywords: ["primary keyword", "secondary keyword phrase"]
topics: ["generative_ai", "ai_agents"]
tags: ["openclaw", "openshell", "relevant", "tags"]
content:
  type: concept | how_to | get_started | tutorial | reference
  difficulty: technical_beginner | technical_intermediate | technical_advanced
  audience: ["developer", "engineer"]
status: published
---

页面结构

  1. H1 标题与 title.page 值匹配。
  2. 一到两句话的引言，说明页面内容。
  3. 按任务或概念组织的章节，使用 H2 和 H3。每个章节以引导读者的介绍性句子开头。
  4. 页面底部的”后续步骤”章节，链接到相关页面。

风格指南

像向同事解释事情一样写作。直接、具体、简洁。

语气和语调

  • 使用主动语态。“CLI 创建了一个网关”而不是”网关由 CLI 创建”。
  • 使用第二人称（“你”）称呼读者。
  • 使用现在时态。“该命令返回一个错误”而不是”该命令将返回一个错误”。
  • 陈述事实。不要使用”只需”、“简单地”、“轻松地”或”当然”等模糊词语。

需要避免的模式

以下模式在 LLM 生成的文本中很常见，会降低技术读者的信任度。审阅时请移除它们。

模式问题修正方式
不必要的加粗在常规指示中出现”这是一个关键步骤”。将加粗保留给 UI 标签、参数名称和真正的警告。
过多的破折号”网关——它运行在 Docker 中——创建沙箱。“使用逗号或拆分为两个句子。偶尔使用破折号没问题，但不应在一个段落中多次出现。
最高级”OpenShell 提供了强大、稳健、无缝的体验。“说明它做什么，而不是它有多好。
模糊词语”只需运行该命令”或”你可以轻松配置……”去掉副词。“运行该命令。“
正文中的表情符号”让我们开始吧！“文档正文中不使用表情符号。
反问句”想保护你的代理？看这里就对了！“直接陈述目的。

格式规则

  • 每个句子以句号结尾。
  • 源文件中每行一个句子（使 diff 更易读）。
  • 对 CLI 命令、文件路径、标志、参数名称和值使用 code 格式。
  • 对 CLI 示例使用 console 语言的代码块。命令前缀使用 $： 
    $ nemoclaw onboard
  • 对结构化比较使用表格。保持表格简单（不嵌套格式）。
  • 对提示使用引用块告示（> **注意：**、> **警告：**），而不是粗体文本。
  • 避免嵌套告示。
  • 不要给章节标题编号。写”部署网关”而不是”第 1 节：部署网关”或”步骤 3：验证”。
  • 不要在标题中使用冒号。写”部署和管理网关”而不是”网关：部署和管理”。
  • 冒号仅用于引出列表。不要将冒号用作子句之间的通用标点。

词汇表

请统一使用以下写法：

使用不要使用
gatewayGateway（除非在句首）
sandboxSandbox（除非在句首）
CLIcli, Cli
API keyapi key, API Key
NVIDIANvidia, nvidia
NemoClawnemoclaw（在正文中）, Nemoclaw
OpenClawopenclaw（在正文中）, Openclaw
OpenShellOpen Shell, openShell, Openshell, openshell
mTLSMTLS, mtls
YAMLyaml, Yaml

提交文档更改

  1. 按照项目规范创建分支。
  2. 进行更改。
  3. 使用 make docs 在本地构建并验证输出。
  4. 使用 docs: 作为常规提交类型打开 PR。
docs: update quickstart for new onboard wizard

如果你的文档更改伴随代码更改，请将两者包含在同一个 PR 中，并使用代码更改的提交类型：

feat(cli): add policy-add command

审阅文档 PR

审阅文档时：

  • 检查是否遵循了上述风格指南规则。
  • 注意 LLM 生成的模式（过多加粗、破折号、填充词）。
  • 验证代码示例是否准确且可运行。
  • 确认交叉引用和链接没有损坏。
  • 在本地构建以检查渲染效果。
arrow_back
上一页
License