貢獻 NemoClaw 文件

本指南說明如何撰寫、編輯和審查 NemoClaw 的文件。如果你更改了會影響使用者行為的程式碼，請在同一個 PR 中更新相關文件。

善用 Agent 技能

如果你使用 AI 程式碼助手（Cursor、Claude Code、Codex 等），儲存庫中包含可自動化文件工作的技能。在從頭撰寫之前先試試它們。

技能功能適用時機
update-docs掃描近期 commit 中影響使用者的變更，草擬文件更新。功能上線後、發版前、或需要找出文件缺漏時。

技能存放在 .agents/skills/，會自動遵循下方的風格指南。使用時，請要求你的助手執行它。例如，請它「把 v0.2.0 之後合併的所有內容同步到文件」。

何時更新文件

當你的變更符合以下情況時，請更新文件：

  • 新增、移除或重新命名了 CLI 指令或旗標。
  • 改變了預設行為或設定。
  • 新增了使用者會互動的功能。
  • 修正了文件中描述不正確的錯誤。
  • 更動了 API、協定或政策結構。

在本機建構文件

建構文件並檢查輸出，確認文件正確無誤。

建構文件的指令：

make docs

在本機提供文件服務並在變更時自動重新建構：

make docs-live

撰寫慣例

格式

  • 文件使用 MyST Markdown，這是一種與 Sphinx 相容的 CommonMark 超集。
  • 每個頁面以 YAML frontmatter 開頭（title、description、topics、tags、content type）。
  • 在 frontmatter 之後加入 SPDX 授權標頭。

Frontmatter 範本

---
title:
  page: "NemoClaw 頁面標題 — 附帶情境的副標題"
  nav: "簡短導覽標題"
description: "頁面的一句話摘要。"
keywords: ["主要關鍵字", "次要關鍵字片語"]
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 建立了一個 gateway」，而不是「一個 gateway 被 CLI 建立了」。
  • 用第二人稱（「你」）稱呼讀者。
  • 使用現在式。「指令回傳錯誤」，而不是「指令將會回傳錯誤」。
  • 陳述事實。不要用「只需」、「輕鬆地」、「當然」等模稜兩可的修飾語。

應避免的模式

以下模式在 LLM 生成的文字中很常見，會削弱技術讀者的信任。審查時請移除它們。

模式問題修正
不必要的粗體在一般指示上寫「這是一個關鍵步驟」。粗體保留給 UI 標籤、參數名稱和真正的警告。
到處都是破折號「gateway——它跑在 Docker 裡——建立沙箱。」用逗號或拆成兩句。破折號偶爾用可以，但不要每段都出現好幾次。
浮誇形容「OpenShell 提供了強大、穩健、無縫的體驗。」說它做了什麼，而不是它有多厲害。
虛詞填充「只需執行指令」或「你可以輕鬆設定……」拿掉那個副詞。「執行指令。」
正文中的 emoji「來開始吧！」文件正文中不放 emoji。
修辭性提問「想保護你的代理嗎？看這裡就對了！」直接陳述目的。

格式規則

  • 每句話以句號結尾。
  • 原始檔中一句話一行（讓 diff 更好讀）。
  • 對 CLI 指令、檔案路徑、旗標、參數名稱和值使用 code 格式。
  • 程式碼區塊用 console 語言標示 CLI 範例。指令前加 $： 
    $ nemoclaw onboard
  • 用表格呈現結構化比較。表格保持簡單（不要嵌套格式）。
  • 用 blockquote 警告語（> **注意：**、> **警告：**）做 callout，不要用粗體。
  • 避免巢狀警告語。
  • 不要為章節標題編號。寫「部署 Gateway」而不是「第 1 節：部署 Gateway」或「步驟 3：驗證。」
  • 標題中不要用冒號。寫「部署與管理 Gateway」而不是「Gateway：部署與管理」。
  • 冒號僅用於引導清單。不要把冒號當作子句之間的通用標點。

用語表

請統一使用以下用語：

使用不要使用
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: 作為 conventional commit 類型開啟 PR。
docs: update quickstart for new onboard wizard

如果文件變更伴隨程式碼變更，請放在同一個 PR 中，並使用程式碼變更的 commit 類型：

feat(cli): add policy-add command

審查文件 PR

審查文件時：

  • 檢查是否遵循上述風格指南。
  • 注意 LLM 生成模式（過多粗體、破折號、填充語）。
  • 驗證程式碼範例是否正確且可執行。
  • 確認交叉引用和連結沒有失效。
  • 在本機建構檢查呈現效果。
arrow_back
上一頁
License