nemoclaw-contributor-update-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update Docs from Commits

从提交记录更新文档

Scan recent git history for commits that affect user-facing behavior and draft documentation updates for each.

扫描最近的git历史记录，找出影响用户可见行为的提交，并为每个提交起草文档更新内容。

Prerequisites

前置条件

You must be in the NemoClaw git repository (
```
NemoClaw
```
).
The
```
docs/
```
directory must exist with the current doc set.

你必须处于NemoClaw git仓库（
```
NemoClaw
```
）中。
必须存在包含当前文档集的
```
docs/
```
目录。

When to Use

适用场景

After a batch of features or fixes has landed and docs may be stale.
Before a release, to catch any doc gaps.
During daily release prep, before opening the docs refresh PR.
When a contributor asks "what docs need updating?"

一批功能或修复落地后，文档可能已过时。
发布前，用于排查文档缺口。
日常发布准备期间，在开启文档刷新PR之前。
当贡献者询问“哪些文档需要更新？”时。

Step 0: Load the Skip List

步骤0：加载跳过列表

Before scanning commits, read

docs/.docs-skip

if it exists. This file lists features and commits that are merged but should not be documented yet (experimental, under review, etc.).

bash

cat docs/.docs-skip

Parse these sections from the file:

```
skip-features:
```
— substring patterns matched against commit messages and changed file paths. Any commit whose message or file list contains a listed string is excluded.
```
skip-terms:
```
— terms that must never appear in generated documentation. Check all drafted content against this list before writing. If a drafted sentence contains a skip-term, remove that sentence or the entire section. This is a hard gate — no skip-term may appear in any doc output.

Ignore comment lines (starting with

) and inline comments (everything after

Keep the loaded skip list in memory for use throughout the skill execution and the whole documentation process.

在扫描提交之前，如果存在

docs/.docs-skip

文件，请读取该文件。此文件列出了已合并但暂不文档化的功能和提交（如实验性功能、审核中的内容等）。

bash

cat docs/.docs-skip

解析文件中的以下部分：

```
skip-features:
```
—— 与提交消息和变更文件路径匹配的子字符串模式。任何提交消息或文件列表中包含所列字符串的提交都将被排除。
```
skip-terms:
```
—— 绝对不能出现在生成文档中的术语。在写入之前，检查所有起草内容是否包含此类术语。如果起草的句子包含跳过术语，请删除该句子或整个章节。这是硬性要求——任何跳过术语都不得出现在文档输出中。

忽略注释行（以

开头）和行内注释（

之后的所有内容）。

将加载的跳过列表保存在内存中，以便在技能执行和整个文档处理过程中使用。

Step 1: Identify Relevant Commits

步骤1：识别相关提交

Determine the commit range. The user may provide one explicitly (e.g., "since v0.1.0" or "last 30 commits"). If not, default to commits since the head of the main branch.

bash

undefined

确定提交范围。用户可能会明确提供一个范围（例如“自v0.1.0以来”或“最近30次提交”）。如果没有提供，默认使用主分支头部以来的提交。

bash

undefined

Commits since a tag

某个标签之后的提交

git log v0.1.0..HEAD --oneline --no-merges

Or last 50 commits

或最近50次提交

git log -50 --oneline --no-merges


Filter to commits that are likely to affect docs. Apply every rule below before proceeding. A commit excluded by any rule must not produce doc changes.

1. **Commit type**: `feat`, `fix`, `refactor`, `perf` commits often change behavior. `docs` commits are already doc changes. `chore`, `ci`, `test` commits rarely need doc updates.
2. **Files changed**: Changes to `nemoclaw/src/`, `nemoclaw-blueprint/`, `bin/`, `scripts/`, or policy-related code are high-signal.
3. **Ignore**: Changes limited to `test/`, `.github/`, or internal-only modules.
4. **Skip list**: Exclude any commit whose short hash appears in `skip-commits`, or whose commit message or changed file paths contain a `skip-features` substring. Report skipped commits in the final summary under a "Skipped (docs-skip)" heading.
5. **Agent support matrix**: Do not document agent support (e.g., Claude Code, OpenHands, Goose) unless the agent is listed in the tested agent support matrix in the quickstart or platform docs. Commits that add or modify agent integration code should only produce doc updates for agents already in the matrix. Report excluded agents under "Skipped (not in agent matrix)" in the summary.

```bash

git log -50 --oneline --no-merges


筛选出可能影响文档的提交。在继续之前应用以下所有规则。被任何规则排除的提交不得产生文档变更。

1. **提交类型**：`feat`、`fix`、`refactor`、`perf`提交通常会改变行为。`docs`提交本身就是文档变更。`chore`、`ci`、`test`提交几乎不需要更新文档。
2. **变更文件**：对`nemoclaw/src/`、`nemoclaw-blueprint/`、`bin/`、`scripts/`或策略相关代码的变更属于高信号变更。
3. **忽略**：仅涉及`test/`、`.github/`或内部模块的变更。
4. **跳过列表**：排除短哈希出现在`skip-commits`中的提交，或提交消息、变更文件路径包含`skip-features`子字符串的提交。在最终摘要的“已跳过（docs-skip）”标题下报告被跳过的提交。
5. **Agent支持矩阵**：除非Agent在快速入门或平台文档的已测试Agent支持矩阵中列出，否则不要记录Agent支持（如Claude Code、OpenHands、Goose）。添加或修改Agent集成代码的提交仅应为矩阵中已有的Agent生成文档更新。在摘要的“已跳过（不在Agent矩阵中）”下报告被排除的Agent。

```bash

Show files changed per commit to assess impact

显示每次提交变更的文件以评估影响

git log v0.1.0..HEAD --oneline --no-merges --name-only

undefined

git log v0.1.0..HEAD --oneline --no-merges --name-only

undefined

Step 2: Map Commits to Doc Pages

步骤2：将提交映射到文档页面

For each relevant commit, determine which doc page(s) it affects. Use this mapping as a starting point:

Code area	Likely doc page(s)
`nemoclaw/src/commands/` (launch, connect, status, logs)	`docs/reference/commands.mdx`
`nemoclaw/src/commands/` (new command)	May need a new page or entry in `docs/reference/commands.mdx`
`nemoclaw/src/blueprint/`	`docs/reference/architecture.mdx`
`nemoclaw/src/cli.ts` or `nemoclaw/src/index.ts`	`docs/reference/commands.mdx` , `docs/get-started/quickstart.mdx`
`nemoclaw-blueprint/orchestrator/`	`docs/reference/architecture.mdx`
`nemoclaw-blueprint/policies/`	`docs/reference/network-policies.mdx`
`nemoclaw-blueprint/blueprint.yaml`	`docs/reference/architecture.mdx` , `docs/inference/inference-options.mdx`
`scripts/` (setup, start)	`docs/get-started/quickstart.mdx`
`Dockerfile`	`docs/reference/architecture.mdx`
Inference-related changes	`docs/inference/inference-options.mdx`

If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page.

对于每个相关提交，确定它影响哪些文档页面。使用以下映射作为起点：

代码区域	可能对应的文档页面
`nemoclaw/src/commands/` （launch、connect、status、logs）	`docs/reference/commands.mdx`
`nemoclaw/src/commands/` （新命令）	可能需要新页面或在 `docs/reference/commands.mdx` 中添加条目
`nemoclaw/src/blueprint/`	`docs/reference/architecture.mdx`
`nemoclaw/src/cli.ts` 或 `nemoclaw/src/index.ts`	`docs/reference/commands.mdx` 、 `docs/get-started/quickstart.mdx`
`nemoclaw-blueprint/orchestrator/`	`docs/reference/architecture.mdx`
`nemoclaw-blueprint/policies/`	`docs/reference/network-policies.mdx`
`nemoclaw-blueprint/blueprint.yaml`	`docs/reference/architecture.mdx` 、 `docs/inference/inference-options.mdx`
`scripts/` （setup、start）	`docs/get-started/quickstart.mdx`
`Dockerfile`	`docs/reference/architecture.mdx`
推理相关变更	`docs/inference/inference-options.mdx`

如果提交未映射到任何现有页面但引入了用户可见的概念，标记为需要新页面。

Step 3: Read the Commit Details

步骤3：读取提交详情

For each commit that needs a doc update, read the full diff to understand the change:

bash

git show <commit-hash> --stat
git show <commit-hash>

Extract:

What changed (new flag, renamed command, changed default, new feature).
Why it changed (from the commit message body, linked issue, or PR description).
Any breaking changes or migration steps.

对于每个需要更新文档的提交，读取完整的差异内容以理解变更：

bash

git show <commit-hash> --stat
git show <commit-hash>

提取：

变更内容（新标志、重命名命令、变更默认值、新功能）。
变更原因（来自提交消息正文、关联问题或PR描述）。
任何破坏性变更或迁移步骤。

Step 4: Read the Current Doc Page

步骤4：读取当前文档页面

Before editing, read the full target doc page to understand its current content and structure.

Identify where the new content should go. Follow the page's existing structure.

编辑之前，读取完整的目标文档页面以理解其当前内容和结构。

确定新内容应放置的位置。遵循页面的现有结构。

Step 5: Draft the Update

步骤5：起草更新内容

Before writing, verify that the commit was not excluded in Step 1. Do not draft content for commits matched by the skip list or for agent integrations not in the tested agent support matrix. After drafting, scan the content for any

skip-terms

from

docs/.docs-skip

. Remove any sentence or section that contains a skip-term. If in doubt, skip the commit and report it.

Write the doc update following these conventions:

Active voice, present tense, second person.
No unnecessary bold. Reserve bold for UI labels and parameter names.
No em dashes unless used sparingly. Prefer commas or separate sentences.
Start sections with an introductory sentence that orients the reader.
No superlatives. Say what the feature does, not how great it is.
Code examples use
console
language with
```
$
```
prompt prefix.
Include the SPDX header if creating a new page.
Match existing frontmatter format if creating a new page.
Always write NVIDIA in all caps. Wrong: Nvidia, nvidia.
Always capitalize NemoClaw correctly. Wrong: nemoclaw (in prose), Nemoclaw.
Always capitalize OpenShell correctly. Wrong: openshell (in prose), Openshell, openShell.
Do not number section titles. Wrong: "Section 1: Configure Inference" or "Step 3: Verify." Use plain descriptive titles.
No colons in titles. Wrong: "Inference: Cloud and Local." Write "Cloud and Local Inference" instead.
Use colons only to introduce a list. Do not use colons as general-purpose punctuation between clauses.

When updating an existing page:

Add content in the logical place within the existing structure.
Do not reorganize sections unless the change requires it.
Update any cross-references or "Next Steps" links if relevant.

When creating a new page:

Follow the frontmatter template from existing pages in
```
docs/
```
.
Add the page to the appropriate navigation entry in
```
docs/index.yml
```
.

撰写之前，验证提交未在步骤1中被排除。不要为匹配跳过列表的提交或不在已测试Agent支持矩阵中的Agent集成提交起草内容。起草完成后，扫描内容以查找

docs/.docs-skip

中的任何

skip-terms

。删除包含跳过术语的任何句子或章节。如有疑问，跳过该提交并进行报告。

遵循以下规范撰写文档更新：

主动语态、现在时态、第二人称。
避免不必要的粗体。仅为UI标签和参数名称保留粗体。
避免使用破折号，除非少量使用。优先使用逗号或拆分句子。
章节以介绍性句子开头，引导读者理解。
避免使用最高级。说明功能的作用，而非其优越性。
代码示例使用
console
语言，前缀为
```
$
```
提示符。
如果创建新页面，包含SPDX头部。
如果创建新页面，匹配现有前置格式。
NVIDIA始终全部大写。错误写法：Nvidia、nvidia。
NemoClaw始终正确大写。错误写法：nemoclaw（散文中）、Nemoclaw。
OpenShell始终正确大写。错误写法：openshell（散文中）、Openshell、openShell。
章节标题不要编号。错误写法：“Section 1: Configure Inference”或“Step 3: Verify”。使用简洁的描述性标题。
标题中不要使用冒号。错误写法：“Inference: Cloud and Local”。应写为“Cloud and Local Inference”。
仅在引入列表时使用冒号。不要将冒号用作从句之间的通用标点符号。

更新现有页面时：

在现有结构的逻辑位置添加内容。
除非变更需要，否则不要重新组织章节。
如果相关，更新任何交叉引用或“下一步”链接。

创建新页面时：

遵循
```
docs/
```
中现有页面的前置模板。
在
```
docs/index.yml
```
的相应导航条目中添加该页面。

Step 6: Present the Results

步骤6：呈现结果

After drafting all updates, present a summary to the user:

markdown

undefined

起草所有更新后，向用户呈现摘要：

markdown

undefined

Doc Updates from Commits

来自提交记录的文档更新

Updated pages

已更新页面

```
docs/reference/commands.mdx
```
: Added
```
eject
```
command documentation (from commit abc1234).
```
docs/reference/network-policies.mdx
```
: Updated policy schema for new egress rule (from commit def5678).

```
docs/reference/commands.mdx
```
: 添加
```
eject
```
命令文档（来自提交abc1234）。
```
docs/reference/network-policies.mdx
```
: 更新新出站规则的策略 schema（来自提交def5678）。

New pages needed

需要创建的新页面

None (or list any new pages created).

无（或列出已创建的任何新页面）。

Skipped (docs-skip)

已跳过（docs-skip）

```
feat(sandbox): add experimental-flag
```
(abc1234) — matched skip-features: "experimental-flag".

```
feat(sandbox): add experimental-flag
```
(abc1234) —— 匹配skip-features: "experimental-flag"。

Commits with no doc impact

无文档影响的提交

```
chore(deps): bump typescript
```
(abc1234) — internal dependency, no user-facing change.
```
test: add launch command test
```
(def5678) — test-only change.

undefined

```
chore(deps): bump typescript
```
(abc1234) —— 内部依赖，无用户可见变更。
```
test: add launch command test
```
(def5678) —— 仅测试变更。

undefined

Step 7: Apply Release Prep Updates

步骤7：应用发布准备更新

Skip this step when the user only asked for ordinary doc catch-up and no release prep is involved.

If the user invoked this skill for release prep, finish the release-specific doc work before verification:

Make any requested doc version bumps in
```
versions1.json
```
and
```
project.json
```
in the
```
docs/
```
directory.
Determine the release label from the release version. Release labels use
```
vX.Y.Z
```
format. For example, if
```
docs/project.json
```
has
```
"version": "0.0.37"
```
, the release label is
```
v0.0.37
```
. Use the version requested by the user if one was provided; otherwise use the version in
```
docs/project.json
```
after the bump.

Refresh the NemoClaw user skills:

bash

python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx

当用户仅要求普通文档追赶且不涉及发布准备时，跳过此步骤。

如果用户为发布准备调用此技能，请在验证前完成发布特定的文档工作：

在
```
docs/
```
目录的
```
versions1.json
```
和
```
project.json
```
中进行任何要求的文档版本升级。
从发布版本确定发布标签。发布标签使用
```
vX.Y.Z
```
格式。例如，如果
```
docs/project.json
```
中有
```
"version": "0.0.37"
```
，则发布标签为
```
v0.0.37
```
。如果用户提供了版本，则使用该版本；否则使用版本升级后
```
docs/project.json
```
中的版本。

刷新NemoClaw用户技能：

bash

python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx

Step 9: Build and Verify

步骤9：构建与验证

After making changes, build the docs locally:

bash

make docs

Check for:

Build warnings or errors.
Broken cross-references.
Correct rendering of new content.
Generated skill changes that do not correspond to source doc changes.

完成变更后，在本地构建文档：

bash

make docs

检查：

构建警告或错误。
无效的交叉引用。
新内容的正确渲染。
生成的技能变更与源文档变更不匹配的情况。

Step 10: Open the Docs PR

步骤10：开启文档PR

Commit changes and open a pull request with a concise summary of the doc updates and a source summary that links each identified merged PR to its matching doc page. Include the PR number, affected doc page, links, and description of the doc change in this shape:

markdown

- #<doc-impacting-PR-number> -> `docs/path.mdx`: Description of the doc change reflecting the source code changes in the PR.

Apply the

documentation

label and the corresponding release label so reviewers can identify doc-only changes for the target release. When creating the PR with

gh pr create

, pass both labels, for example

--label documentation --label v0.0.37

. If the release label does not exist, report that instead of substituting another label.

提交变更并开启拉取请求，简要总结文档更新内容，并提供源摘要，将每个已识别的合并PR链接到其匹配的文档页面。包含PR编号、受影响的文档页面、链接以及文档变更的描述，格式如下：

markdown

- #<影响文档的PR编号> -> `docs/path.mdx`: 反映PR中源代码变更的文档变更描述。

添加

documentation

标签和相应的发布标签，以便评审人员识别目标版本的纯文档变更。使用

gh pr create

创建PR时，传递两个标签，例如

--label documentation --label v0.0.37

。如果发布标签不存在，请报告该情况，不要替换为其他标签。

Tips

提示

When in doubt about whether a commit needs a doc update, check if the commit message references a CLI flag, config option, or user-visible behavior.
Group related commits that touch the same doc page into a single update rather than making multiple small edits.
If a commit is a breaking change, add a note at the top of the relevant section using a
```
:::{warning}
```
admonition.
PRs that are purely internal refactors with no behavior change do not need doc updates, even if they touch high-signal directories.
To suppress documentation for a merged feature that is not ready for public docs, add it to
```
docs/.docs-skip
```
. Remove the entry once the feature is ready to document.

如果不确定提交是否需要更新文档，请检查提交消息是否引用了CLI标志、配置选项或用户可见行为。
将涉及同一文档页面的相关提交分组为一次更新，而不是进行多次小编辑。
如果提交是破坏性变更，请使用
```
:::{warning}
```
警告框在相关章节顶部添加说明。
纯内部重构且无行为变更的PR不需要更新文档，即使它们涉及高信号目录。
要禁止为尚未准备好公开文档的已合并功能生成文档，请将其添加到
```
docs/.docs-skip
```
。功能准备好文档化后再移除该条目。

Summary of Steps

步骤总结

User says: "Catch up the docs for everything merged since v0.1.0."

Run

git log v0.1.0..HEAD --oneline --no-merges --name-only

Filter to
```
feat
```
,
```
fix
```
,
```
refactor
```
,
```
perf
```
commits touching user-facing code.
Map each to a doc page.
Read the commit diffs and current doc pages.
Draft doc updates reflecting the source code changes in the commits following the style guide.
Release prep only: Apply release-prep version bumps if the user requested release prep.

Release prep only: Run

python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx

Present the summary.
Build with
```
make docs
```
to verify.
Release prep only: Commit changes and open a pull request with the
```
documentation
```
label and the corresponding
```
vX.Y.Z
```
release label. Include a concise summary of the doc updates and a source summary that links each identified merged PR to its matching doc page. Include the PR number, affected doc page, links, and description of the doc change in this shape:

markdown

- #<doc-impacting-PR-number> -> `docs/path.mdx`: Description of the doc change reflecting the source code changes in the PR.

If the release label does not exist, report that the PR was created without the release label or that PR creation failed because the label was missing.

用户说：“追赶自v0.1.0以来所有合并内容的文档。”

运行

git log v0.1.0..HEAD --oneline --no-merges --name-only

。

筛选出涉及用户可见代码的
```
feat
```
、
```
fix
```
、
```
refactor
```
、
```
perf
```
提交。
将每个提交映射到文档页面。
读取提交差异和当前文档页面。
遵循风格指南，起草反映提交中源代码变更的文档更新内容。
仅发布准备： 如果用户要求发布准备，应用发布准备版本升级。

仅发布准备： 运行

python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx

。

呈现摘要。
使用
```
make docs
```
构建以验证。
仅发布准备： 提交变更并开启拉取请求，添加
```
documentation
```
标签和相应的
```
vX.Y.Z
```
发布标签。简要总结文档更新内容，并提供源摘要，将每个已识别的合并PR链接到其匹配的文档页面。包含PR编号、受影响的文档页面、链接以及文档变更的描述，格式如下：

markdown

- #<影响文档的PR编号> -> `docs/path.mdx`: 反映PR中源代码变更的文档变更描述。

如果发布标签不存在，请报告PR已创建但未添加发布标签，或因标签缺失导致PR创建失败。