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