# 分支与 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/分支仍能构建——传递依赖的变更可能破坏下游代码。