添加中文文档

docs/zh/BRANCH-FORK-MAINTENANCE.md

@@ -0,0 +1,81 @@
+# 分支与 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`。
+
+## 向前合并流程
+
+```bash
+# 在你的本地 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 时：
+
+1. Fork `nanoclaw` 为 `nanoclaw-{channel}`
+2. 移除仅上游存在的工作流：`bump-version.yml`、`update-tokens.yml`
+3. 添加频道代码、依赖、环境变量
+4. 立即向前合并 main 以建立干净的基准
+
+## 依赖
+
+Forks 和分支在上游基础上添加自己的依赖。当上游添加或移除一个依赖时，在下一次向前合并后验证 forks/分支仍能构建——传递依赖的变更可能破坏下游代码。