update-nanoclaw

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

About

关于

Your NanoClaw fork drifts from upstream as you customize it. This skill pulls upstream changes into your install without losing your modifications.

Run

/update-nanoclaw

in Claude Code.

当你自定义NanoClaw后，你的分支会与上游代码逐渐产生差异。本Skill可帮助你将上游变更整合到本地安装中，同时保留你的自定义修改。

在Claude Code中运行

/update-nanoclaw

即可使用。

How it works

工作原理

Preflight: checks for clean working tree (

git status --porcelain

). If

upstream

remote is missing, asks you for the URL (defaults to

https://github.com/qwibitai/nanoclaw.git

) and adds it. Detects the upstream branch name (

main

master

Backup: creates a timestamped backup branch and tag (

backup/pre-update-<hash>-<timestamp>

pre-update-<hash>-<timestamp>

) before touching anything. Safe to run multiple times.

Preview: runs

git log

and

git diff

against the merge base to show upstream changes since your last sync. Groups changed files into categories:

Skills (
```
.claude/skills/
```
): unlikely to conflict unless you edited an upstream skill
Source (
```
src/
```
): may conflict if you modified the same files
Build/config (
```
package.json
```
,
```
tsconfig*.json
```
,
```
container/
```
): review needed

Update paths (you pick one):

```
merge
```
(default):
```
git merge upstream/<branch>
```
. Resolves all conflicts in one pass.
```
cherry-pick
```
:
```
git cherry-pick <hashes>
```
. Pull in only the commits you want.
```
rebase
```
:
```
git rebase upstream/<branch>
```
. Linear history, but conflicts resolve per-commit.
```
abort
```
: just view the changelog, change nothing.

Conflict preview: before merging, runs a dry-run (

git merge --no-commit --no-ff

) to show which files would conflict. You can still abort at this point.

Conflict resolution: opens only conflicted files, resolves the conflict markers, keeps your local customizations intact.

Validation: runs

npm run build

and

npm test

Breaking changes check: after validation, reads CHANGELOG.md for any

[BREAKING]

entries introduced by the update. If found, shows each breaking change and offers to run the recommended skill to migrate.

预检：检查工作树是否干净（执行

git status --porcelain

）。如果缺少

upstream

远程仓库，会询问你仓库URL（默认值为

https://github.com/qwibitai/nanoclaw.git

）并添加它。自动检测上游分支名称（

main

或

master

）。

备份：在进行任何操作前，创建带时间戳的备份分支和标签（格式为

backup/pre-update-<hash>-<timestamp>

和

pre-update-<hash>-<timestamp>

）。可安全多次运行。

预览：基于合并基准执行

git log

和

git diff

，展示自上次同步以来的上游变更。将变更文件分为以下类别：

Skills（
```
.claude/skills/
```
）：除非你编辑过上游Skill，否则不太可能产生冲突
源码（
```
src/
```
）：如果你修改过相同文件，可能会产生冲突
构建/配置（
```
package.json
```
、
```
tsconfig*.json
```
、
```
container/
```
）：需要重点检查

更新路径（你可选择其一）：

```
merge
```
（默认）：执行
```
git merge upstream/<branch>
```
，一次性解决所有冲突。
```
cherry-pick
```
：执行
```
git cherry-pick <hashes>
```
，仅拉取你需要的提交。
```
rebase
```
：执行
```
git rebase upstream/<branch>
```
，生成线性提交历史，但需逐个提交解决冲突。
```
abort
```
：仅查看变更日志，不做任何修改。

冲突预览：合并前执行试运行（

git merge --no-commit --no-ff

），展示可能产生冲突的文件。此时你仍可选择中止操作。

冲突解决：仅打开存在冲突的文件，解决冲突标记，保留本地自定义内容。

验证：执行

npm run build

和

npm test

。

破坏性变更检查：验证通过后，读取CHANGELOG.md查看更新引入的

[BREAKING]

条目。如果存在，会展示每个破坏性变更，并提供推荐的迁移Skill供你运行。

Rollback

回滚

The backup tag is printed at the end of each run:

git reset --hard pre-update-<hash>-<timestamp>

Backup branch

backup/pre-update-<hash>-<timestamp>

also exists.

每次运行结束后会打印备份标签：

git reset --hard pre-update-<hash>-<timestamp>

同时会创建备份分支

backup/pre-update-<hash>-<timestamp>

。

Token usage

Token消耗

Only opens files with actual conflicts. Uses

git log

git diff

, and

git status

for everything else. Does not scan or refactor unrelated code.

仅打开存在实际冲突的文件。其他操作均依赖

git log

、

git diff

和

git status

，不会扫描或重构无关代码，Token消耗较低。

Goal

目标

Help a user with a customized NanoClaw install safely incorporate upstream changes without a fresh reinstall and without blowing tokens.

帮助使用自定义NanoClaw安装的用户安全整合上游变更，无需重新安装，且Token消耗低。

Operating principles

操作原则

Never proceed with a dirty working tree.
Always create a rollback point (backup branch + tag) before touching anything.
Prefer git-native operations (fetch, merge, cherry-pick). Do not manually rewrite files except conflict markers.
Default to MERGE (one-pass conflict resolution). Offer REBASE as an explicit option.
Keep token usage low: rely on
```
git status
```
,
```
git log
```
,
```
git diff
```
, and open only conflicted files.

工作树不干净时绝不继续操作。
在进行任何操作前，始终创建回滚点（备份分支+标签）。
优先使用Git原生操作（fetch、merge、cherry-pick）。除冲突标记外，不手动重写文件。
默认使用MERGE（一次性解决冲突），将REBASE作为高级选项提供。
保持Token消耗低：依赖
```
git status
```
、
```
git log
```
、
```
git diff
```
，仅打开冲突文件。

Step 0: Preflight (stop early if unsafe)

步骤0：预检（不安全则提前终止）

Run:

```
git status --porcelain
```
If output is non-empty:
Tell the user to commit or stash first, then stop.

Confirm remotes:

```
git remote -v
```
If
```
upstream
```
is missing:
Ask the user for the upstream repo URL (default:
```
https://github.com/qwibitai/nanoclaw.git
```
).

Add it:

git remote add upstream <user-provided-url>

Then:
```
git fetch upstream --prune
```

Determine the upstream branch name:

```
git branch -r | grep upstream/
```
If
```
upstream/main
```
exists, use
```
main
```
.
If only
```
upstream/master
```
exists, use
```
master
```
.
Otherwise, ask the user which branch to use.
Store this as UPSTREAM_BRANCH for all subsequent commands. Every command below that references
```
upstream/main
```
should use
```
upstream/$UPSTREAM_BRANCH
```
instead.

Fetch:

```
git fetch upstream --prune
```

执行：

```
git status --porcelain
```
如果输出非空：
告知用户先提交或暂存变更，然后终止操作。

确认远程仓库：

```
git remote -v
```
如果缺少
```
upstream
```
：
询问用户上游仓库URL（默认：
```
https://github.com/qwibitai/nanoclaw.git
```
）。

添加远程仓库：

git remote add upstream <用户提供的URL>

然后执行：
```
git fetch upstream --prune
```

确定上游分支名称：

```
git branch -r | grep upstream/
```
如果
```
upstream/main
```
存在，使用
```
main
```
。
如果仅存在
```
upstream/master
```
，使用
```
master
```
。
否则，询问用户要使用哪个分支。
将其存储为UPSTREAM_BRANCH，供后续所有命令使用。以下所有引用
```
upstream/main
```
的命令均替换为
```
upstream/$UPSTREAM_BRANCH
```
。

拉取上游代码：

```
git fetch upstream --prune
```

Step 1: Create a safety net

步骤1：创建安全保障

Capture current state:

```
HASH=$(git rev-parse --short HEAD)
```
```
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
```

Create backup branch and tag (using timestamp to avoid collisions on retry):

git branch backup/pre-update-$HASH-$TIMESTAMP

```
git tag pre-update-$HASH-$TIMESTAMP
```

Save the tag name for later reference in the summary and rollback instructions.

捕获当前状态：

```
HASH=$(git rev-parse --short HEAD)
```
```
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
```

创建备份分支和标签（使用时间戳避免重试时冲突）：

git branch backup/pre-update-$HASH-$TIMESTAMP

```
git tag pre-update-$HASH-$TIMESTAMP
```

保存标签名称，用于后续总结和回滚说明。

Step 2: Preview what upstream changed (no edits yet)

步骤2：预览上游变更（暂不编辑）

Compute common base:

BASE=$(git merge-base HEAD upstream/$UPSTREAM_BRANCH)

Show upstream commits since BASE:

git log --oneline $BASE..upstream/$UPSTREAM_BRANCH

Show local commits since BASE (custom drift):

```
git log --oneline $BASE..HEAD
```

Show file-level impact from upstream:

git diff --name-only $BASE..upstream/$UPSTREAM_BRANCH

Bucket the upstream changed files:

Skills (
```
.claude/skills/
```
): unlikely to conflict unless the user edited an upstream skill
Source (
```
src/
```
): may conflict if user modified the same files

Build/config (

package.json

package-lock.json

tsconfig*.json

container/

launchd/

): review needed

Other: docs, tests, misc

Present these buckets to the user and ask them to choose one path using AskUserQuestion:

A) Full update: merge all upstream changes
B) Selective update: cherry-pick specific upstream commits
C) Abort: they only wanted the preview
D) Rebase mode: advanced, linear history (warn: resolves conflicts per-commit)

If Abort: stop here.

计算共同基准：

BASE=$(git merge-base HEAD upstream/$UPSTREAM_BRANCH)

展示自基准以来的上游提交：

git log --oneline $BASE..upstream/$UPSTREAM_BRANCH

展示自基准以来的本地提交（自定义差异）：

```
git log --oneline $BASE..HEAD
```

展示上游变更的文件级影响：

git diff --name-only $BASE..upstream/$UPSTREAM_BRANCH

将上游变更文件分类：

Skills（
```
.claude/skills/
```
）：除非用户编辑过上游Skill，否则不太可能冲突
源码（
```
src/
```
）：如果用户修改过相同文件，可能冲突

构建/配置（

package.json

、

package-lock.json

、

tsconfig*.json

、

container/

、

launchd/

）：需要检查

其他：文档、测试、杂项

将这些分类展示给用户，使用AskUserQuestion让用户选择更新路径：

A) 完整更新：合并所有上游变更
B) 选择性更新：cherry-pick特定上游提交
C) 中止：仅需要预览
D) Rebase模式：高级选项，生成线性历史（警告：需逐个提交解决冲突）

如果选择中止：在此处停止操作。

Step 3: Conflict preview (before committing anything)

步骤3：冲突预览（提交前）

If Full update or Rebase:

Dry-run merge to preview conflicts. Run these as a single chained command so the abort always executes:

git merge --no-commit --no-ff upstream/$UPSTREAM_BRANCH; git diff --name-only --diff-filter=U; git merge --abort

If conflicts were listed: show them and ask user if they want to proceed.
If no conflicts: tell user it is clean and proceed.

如果选择完整更新或Rebase：

执行试运行合并以预览冲突。将以下命令链式执行，确保中止操作始终生效：

git merge --no-commit --no-ff upstream/$UPSTREAM_BRANCH; git diff --name-only --diff-filter=U; git merge --abort

如果列出了冲突：展示给用户并询问是否继续。
如果无冲突：告知用户可安全继续。

Step 4A: Full update (MERGE, default)

步骤4A：完整更新（MERGE，默认）

Run:

git merge upstream/$UPSTREAM_BRANCH --no-edit

If conflicts occur:

Run
```
git status
```
and identify conflicted files.
For each conflicted file:
- Open the file.
- Resolve only conflict markers.
- Preserve intentional local customizations.
- Incorporate upstream fixes/improvements.
- Do not refactor surrounding code.
- ```
git add <file>
```
When all resolved:
- If merge did not auto-commit:
```
git commit --no-edit
```

执行：

git merge upstream/$UPSTREAM_BRANCH --no-edit

如果产生冲突：

执行
```
git status
```
识别冲突文件。
对每个冲突文件：
- 打开文件。
- 仅解决冲突标记。
- 保留有意的本地自定义内容。
- 整合上游修复/改进。
- 不重构周边代码。
- 执行
```
git add <file>
```
所有冲突解决后：
- 如果合并未自动提交：执行
```
git commit --no-edit
```

Step 4B: Selective update (CHERRY-PICK)

步骤4B：选择性更新（CHERRY-PICK）

If user chose Selective:

Recompute BASE if needed:

BASE=$(git merge-base HEAD upstream/$UPSTREAM_BRANCH)

Show commit list again:

git log --oneline $BASE..upstream/$UPSTREAM_BRANCH

Ask user which commit hashes they want.
Apply:
```
git cherry-pick <hash1> <hash2> ...
```

If conflicts during cherry-pick:

Resolve only conflict markers, then:

```
git add <file>
```
```
git cherry-pick --continue
```
If user wants to stop:
```
git cherry-pick --abort
```

如果用户选择选择性更新：

必要时重新计算基准：

BASE=$(git merge-base HEAD upstream/$UPSTREAM_BRANCH)

再次展示提交列表：

git log --oneline $BASE..upstream/$UPSTREAM_BRANCH

询问用户要选择哪些提交哈希值。
执行：
```
git cherry-pick <hash1> <hash2> ...
```

如果cherry-pick过程中产生冲突：

仅解决冲突标记，然后：
- 执行
```
git add <file>
```
- 执行
```
git cherry-pick --continue
```
  如果用户想停止：
- 执行
```
git cherry-pick --abort
```

Step 4C: Rebase (only if user explicitly chose option D)

步骤4C：Rebase（仅当用户明确选择选项D时）

Run:

```
git rebase upstream/$UPSTREAM_BRANCH
```

If conflicts:

Resolve conflict markers only, then:
- ```
git add <file>
```
- ```
git rebase --continue
```
  If it gets messy (more than 3 rounds of conflicts):
- ```
git rebase --abort
```
- Recommend merge instead.

执行：

```
git rebase upstream/$UPSTREAM_BRANCH
```

如果产生冲突：

仅解决冲突标记，然后：
- 执行
```
git add <file>
```
- 执行
```
git rebase --continue
```
  如果情况复杂（超过3轮冲突）：
- 执行
```
git rebase --abort
```
- 推荐使用merge方式。

Step 5: Validation

步骤5：验证

Run:

```
npm run build
```
```
npm test
```
(do not fail the flow if tests are not configured)

If build fails:

Show the error.
Only fix issues clearly caused by the merge (missing imports, type mismatches from merged code).
Do not refactor unrelated code.
If unclear, ask the user before making changes.

执行：

```
npm run build
```
```
npm test
```
（如果未配置测试，不终止流程）

如果构建失败：

展示错误信息。
仅修复明显由合并导致的问题（缺失的导入、合并代码导致的类型不匹配）。
不重构无关代码。
如果不确定，修改前询问用户。

Step 6: Breaking changes check

步骤6：破坏性变更检查

After validation succeeds, check if the update introduced any breaking changes.

Determine which CHANGELOG entries are new by diffing against the backup tag:

git diff <backup-tag-from-step-1>..HEAD -- CHANGELOG.md

Parse the diff output for lines starting with

+[BREAKING]

. Each such line is one breaking change entry. The format is:

[BREAKING] <description>. Run `/<skill-name>` to <action>.

If no

[BREAKING]

lines are found:

Skip this step silently. Proceed to Step 7 (skill updates check).

If one or more

[BREAKING]

lines are found:

Display a warning header to the user: "This update includes breaking changes that may require action:"
For each breaking change, display the full description.
Collect all skill names referenced in the breaking change entries (the
```
/<skill-name>
```
part).
Use AskUserQuestion to ask the user which migration skills they want to run now. Options:
- One option per referenced skill (e.g., "Run /add-whatsapp to re-add WhatsApp channel")
- "Skip — I'll handle these manually"
Set
```
multiSelect: true
```
so the user can pick multiple skills if there are several breaking changes.
For each skill the user selects, invoke it using the Skill tool.
After all selected skills complete (or if user chose Skip), proceed to Step 7 (skill updates check).

验证通过后，检查更新是否引入了破坏性变更。

通过对比备份标签和当前HEAD，确定CHANGELOG中的新增条目：

git diff <步骤1中的备份标签>..HEAD -- CHANGELOG.md

解析diff输出中以

+[BREAKING]

开头的行，每行对应一个破坏性变更条目。格式如下：

[BREAKING] <描述>。运行`/<skill-name>`以<执行操作>。

如果未找到

[BREAKING]

行：

静默跳过此步骤，进入步骤7（Skill更新检查）。

如果找到一个或多个

[BREAKING]

行：

向用户展示警告标题："本次更新包含可能需要操作的破坏性变更："
展示每个破坏性变更的完整描述。
收集破坏性变更条目中引用的所有Skill名称（即
```
/<skill-name>
```
部分）。
使用AskUserQuestion询问用户现在要运行哪些迁移Skill。选项：
- 每个引用的Skill对应一个选项（例如："运行 /add-whatsapp 重新添加WhatsApp渠道"）
- "跳过 — 我将手动处理"
设置
```
multiSelect: true
```
，以便用户在存在多个破坏性变更时可选择多个Skill。
对用户选择的每个Skill，使用Skill工具调用它。
所有选中的Skill执行完成后（或用户选择跳过），进入步骤7（Skill更新检查）。

Step 7: Check for skill updates

步骤7：检查Skill更新

After the summary, check if skills are distributed as branches in this repo:

```
git branch -r --list 'upstream/skill/*'
```

If any

upstream/skill/*

branches exist:

Use AskUserQuestion to ask: "Upstream has skill branches. Would you like to check for skill updates?"
- Option 1: "Yes, check for updates" (description: "Runs /update-skills to check for and apply skill branch updates")
- Option 2: "No, skip" (description: "You can run /update-skills later any time")
If user selects yes, invoke
```
/update-skills
```
using the Skill tool.
After the skill completes (or if user selected no), proceed to Step 8.

总结完成后，检查本仓库是否以分支形式分发Skill：

```
git branch -r --list 'upstream/skill/*'
```

如果存在

upstream/skill/*

分支：

使用AskUserQuestion询问："上游存在Skill分支。是否要检查Skill更新？"
- 选项1："是，检查更新"（描述："运行 /update-skills 检查并应用Skill分支更新"）
- 选项2："否，跳过"（描述："你可稍后随时运行 /update-skills"）
如果用户选择是，使用Skill工具调用
```
/update-skills
```
。
Skill执行完成后（或用户选择跳过），进入步骤8。

Step 8: Summary + rollback instructions

步骤8：总结 + 回滚说明

Show:

Backup tag: the tag name created in Step 1
New HEAD:
```
git rev-parse --short HEAD
```

Upstream HEAD:

git rev-parse --short upstream/$UPSTREAM_BRANCH

Conflicts resolved (list files, if any)
Breaking changes applied (list skills run, if any)

Remaining local diff vs upstream:

git diff --name-only upstream/$UPSTREAM_BRANCH..HEAD

Tell the user:

To rollback:

git reset --hard <backup-tag-from-step-1>

Backup branch also exists:
```
backup/pre-update-<HASH>-<TIMESTAMP>
```

Restart the service to apply changes:

If using launchd:

launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist && launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist

If running manually: restart
```
npm run dev
```

展示：

备份标签：步骤1中创建的标签名称
当前HEAD：
```
git rev-parse --short HEAD
```

上游HEAD：

git rev-parse --short upstream/$UPSTREAM_BRANCH

已解决的冲突（如有，列出文件）
已应用的破坏性变更（如有，列出运行的Skill）

与上游的剩余本地差异：

git diff --name-only upstream/$UPSTREAM_BRANCH..HEAD

告知用户：

回滚命令：

git reset --hard <步骤1中的备份标签>

同时存在备份分支：
```
backup/pre-update-<HASH>-<TIMESTAMP>
```

重启服务以应用变更：

如果使用launchd：执行

launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist && launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist

如果手动运行：重启
```
npm run dev
```