---
name: merge-upstream
description: 拉取上游仓库更新并合并到本地 fork。当用户说"拉取上游"、"合并上游"、"merge upstream"、"pull upstream"、"上游更新"时触发此技能。这是一个高频操作，任何涉及从 upstream 同步代码的请求都应使用此技能。
---

# 上游合并工作流

本项目是 [Wei-Shaw/sub2api](https://github.com/Wei-Shaw/sub2api) 的 fork，品牌名从 `Sub2API` 改为 `TianShuAPI`。

## 执行步骤

### 1. 获取上游更新

```bash
git fetch upstream
```

### 2. 查看新提交

对比本地 HEAD 和 upstream/main，列出新增提交：

```bash
git log --oneline HEAD..upstream/main
```

如果没有新提交，告知用户已是最新，流程结束。

### 3. 合并

```bash
git merge upstream/main --no-edit
```

### 4. 解决冲突

合并冲突几乎总是因为品牌名差异。核心规则：

- **始终保留 `TianShuAPI`**，不要用 `Sub2API`
- **接受上游所有新功能、新字段、新参数**
- 采用上游的代码结构重构（如函数签名变更、新的 import），只替换品牌名

常见冲突文件及处理方式：

| 文件 | 冲突原因 | 处理 |
|------|---------|------|
| `backend/internal/service/setting_service.go` | SiteName 默认值 | 保留 `"TianShuAPI"`，接受新字段 |
| `frontend/src/i18n/locales/zh.ts` | 中文翻译中的品牌名 | 保留 `TianShuAPI`，接受新翻译 |
| `frontend/src/i18n/locales/en.ts` | 英文翻译中的品牌名 | 保留 `TianShuAPI`，接受新翻译 |
| `frontend/src/views/admin/SettingsView.vue` | 表单默认值 | 保留 `'TianShuAPI'`，接受新字段 |
| `frontend/src/main.ts` | 文档标题 | 保留 `'TianShuAPI'`，采用上游结构 |
| `frontend/src/router/title.ts` | 标题解析默认值 | 保留 `'TianShuAPI'`，接受新参数 |
| `frontend/src/components/layout/AuthLayout.vue` | 认证页面默认名 | 保留 `'TianShuAPI'`，采用上游结构 |
| `deploy/docker-compose.yml` | 1Panel 适配 vs 上游默认 | 保留 1Panel 结构，接受新环境变量 |

### 5. 提交

```bash
git add <冲突文件>
git commit -m "Merge upstream/main: <版本范围> updates

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
```

提交信息中的版本范围从 git tag 获取，如 `v0.1.85-v0.1.87`。

### 6. 推送

```bash
git push origin main
```

## 服务器部署提示

合并完成后提醒用户服务器更新步骤：

```bash
cd /opt/sub2api-dev
git checkout deploy/docker-compose.yml
git pull
sed -i 's|PGDATA=/var/lib/postgresql/data$|PGDATA=/var/lib/postgresql/data/18/docker|' deploy/docker-compose.yml
cd deploy && docker compose up -d --build
```

注意：服务器上必须用 `docker compose`（v2），不要用 `docker-compose`（v1 已不兼容）。