分支与 Fork 维护指南

结构

nanocoai/nanoclaw（上游）——核心引擎，包含技能定义（.claude/skills/）。main 分支上没有频道代码。

频道 forks（nanoclaw-whatsapp、nanoclaw-telegram、nanoclaw-slack 等）——每个 fork = 上游 + 一个频道的代码。用户克隆上游，然后将某个 fork 合并到自己的克隆中以添加频道。

上游的 skill/* 和 feat/* 分支——添加与频道无关的功能（例如 skill/compact、skill/apple-container）。用户将这些分支合并到自己的克隆中以添加能力。与 forks 重复的频道特定技能分支（例如 skill/whatsapp、skill/telegram）为历史遗留分支。

用户如何添加能力

用户克隆上游 main
  ├── 合并 nanoclaw-whatsapp fork  → 添加 WhatsApp
  ├── 合并 skill/compact 分支    → 添加 /compact 命令
  └── 合并 skill/apple-container   → 切换到 Apple Container

合并方向

上游 main ──→ 频道 forks     （向前合并以保持 forks 同步）
上游 main ──→ skill 分支     （向前合并以保持分支同步）

Forks 和 skill 分支携带已应用的代码变更。用户将它们合并到自己的克隆/forks 中以添加能力。它们永远不会被合并回上游 main。

向前合并流程

# 在你的本地 nanoclaw 检出中
git checkout main && git pull

# 对于一个 fork：
git fetch nanoclaw-whatsapp
git checkout -B whatsapp-merge nanoclaw-whatsapp/main
git merge main
# 解决冲突（见下文）
# 移除仅上游存在的工作流文件（每次合并都会重新添加，因为 main 上有这些文件）：
git rm .github/workflows/bump-version.yml .github/workflows/update-tokens.yml 2>/dev/null
git push nanoclaw-whatsapp HEAD:main
git checkout main && git branch -D whatsapp-merge

# 对于一个 skill 分支：
git checkout -B skill/compact origin/skill/compact
git merge main
# 解决冲突（见下文）
git push origin skill/compact
git checkout main && git branch -D skill/compact

冲突解决

每次都会冲突的相同文件：

文件	解决方式
`package.json`	取 main 的版本 + 保留 fork/分支特定的依赖
`pnpm-lock.yaml`	`git checkout main -- pnpm-lock.yaml && pnpm install`
`.env.example`	合并：main 的条目 + fork/分支特定的条目
`repo-tokens/badge.svg`	取 main 的版本（自动生成）

源码变更（例如 src/types.ts、src/index.ts）通常能自动干净合并，但如果双方修改了相同行也可能冲突。每次向前合并后一定要构建和测试——即使 git 报告没有冲突，自动合并的代码也可能静默错误（例如引用了一个已重命名的函数或使用了一个已移除的参数）。

何时向前合并

在 main 上任何涉及共享文件的变更之后（package.json、src/index.ts、CLAUDE.md 等）。小而频繁的合并 = 轻松的冲突。大而不频繁的合并 = 痛苦。

Fork 设置

创建新的频道 fork 时：

Fork nanoclaw 为 nanoclaw-{channel}
移除仅上游存在的工作流：bump-version.yml、update-tokens.yml
添加频道代码、依赖、环境变量
立即向前合并 main 以建立干净的基准

依赖

Forks 和分支在上游基础上添加自己的依赖。当上游添加或移除一个依赖时，在下一次向前合并后验证 forks/分支仍能构建——传递依赖的变更可能破坏下游代码。

3.5 KiB Raw Permalink Blame History Unescape Escape