xinghuoapi/skills/sync-upstream/SKILL.md

---
name: sync-upstream
description: 从上游 Wei-Shaw/sub2api 拉取最新代码并合并，自动保留所有 StarFireAPI 自定义配置（品牌、链接、docker-compose、更新模块禁用）。
license: MIT
metadata:
  author: huangzhenpc
  version: "1.0"
---

# 同步上游（sync-upstream）

## 触发条件

当以下任一条件满足时激活本技能：

- 用户要求"拉取上游"、"同步上游"、"合并上游"、"sync upstream"。
- 用户使用 `/sync-upstream` 命令。

## 目标

从上游仓库 `https://github.com/Wei-Shaw/sub2api.git` 拉取最新代码，合并到本地 `main` 分支，并确保所有 StarFireAPI 自定义配置不被覆盖。

## 自定义配置清单（必须保留）

以下是本项目相对于上游的所有自定义改动，合并后必须逐项检查并保留：

### 1. 品牌替换：`Sub2API` → `StarFireAPI`

所有面向用户的前端代码中，`Sub2API` 必须替换为 `StarFireAPI`。涉及的文件类型：

- `frontend/index.html` — 页面标题
- `frontend/src/stores/app.ts` — siteName 默认值
- `frontend/src/i18n/locales/en.ts` — 英文翻译中所有 `Sub2API`
- `frontend/src/i18n/locales/zh.ts` — 中文翻译中所有 `Sub2API`
- `frontend/src/views/**/*.vue` — HomeView、RegisterView、EmailVerifyView 等
- `frontend/src/components/layout/AuthLayout.vue` — siteName 默认值
- `frontend/src/router/title.ts` — 页面标题 fallback
- `frontend/src/router/index.ts` — siteName fallback
- `frontend/src/views/admin/SettingsView.vue` — site_name 默认值
- `frontend/src/router/__tests__/title.spec.ts` — 测试期望值

**扫描方法**：合并后执行 `grep -rn "Sub2API" frontend/src/ --include="*.ts" --include="*.vue" --include="*.html"`，对所有影响运行时的结果替换为 `StarFireAPI`（代码注释可保留）。

### 2. 链接替换：GitHub → 官网

| 原始值 | 替换为 |
|--------|--------|
| `https://github.com/Wei-Shaw/sub2api` | `https://anthropic.edu.pl` |
| GitHub 图标 SVG（长 path） | 房子图标 `<path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/>` |
| `viewOnGithub: 'View on GitHub'` | `viewOnGithub: 'Official Site'` |
| `viewOnGithub: '在 GitHub 上查看'` | `viewOnGithub: '访问官网'` |

涉及文件：
- `frontend/src/components/layout/AppHeader.vue`
- `frontend/src/views/HomeView.vue`
- `frontend/src/i18n/locales/en.ts`
- `frontend/src/i18n/locales/zh.ts`

**扫描方法**：合并后执行 `grep -rn "github.com/Wei-Shaw/sub2api" frontend/src/`，检查是否有新的前端 GitHub 链接被引入。

### 3. docker-compose 自定义（`deploy/docker-compose.yml`）

| 配置项 | 上游默认值 | 我们的值 |
|--------|-----------|---------|
| compose project name | 无 | `name: xinghuoapi` |
| 镜像 | `weishaw/sub2api:latest` | `starfireapi:latest` |
| 端口映射 | `8080:8080` | `6580:8080` |
| Redis Host | `redis`（内置容器） | `${REDIS_HOST:-172.18.0.2}`（外部 Redis） |
| Redis Password | `${REDIS_PASSWORD:-}` | `${REDIS_PASSWORD:-redis_JCHeKT}` |
| Redis 容器 | 正常启用 | `profiles: [disabled]`（禁用） |
| sub2api depends_on | postgres + redis | 仅 postgres |

**重要**：合并 docker-compose.yml 时要特别小心，新增的环境变量（如数据库连接池参数、OAuth secrets 等）应该接受，但上述自定义项必须保留。

### 4. 更新模块禁用

#### 后端 `backend/internal/handler/admin/system_handler.go`

`CheckUpdates` 方法始终返回无更新：

```go
func (h *SystemHandler) CheckUpdates(c *gin.Context) {
    info, _ := h.updateSvc.CheckUpdate(c.Request.Context(), false)
    response.Success(c, gin.H{
        "current_version": info.CurrentVersion,
        "latest_version":  info.CurrentVersion,
        "has_update":      false,
        "build_type":      "source",
    })
}
```

#### 前端 `frontend/src/stores/app.ts`

`checkUpdates` action 中强制返回无更新：

```typescript
latestVersion.value = data.current_version  // 不用 data.latest_version
hasUpdate.value = false
buildType.value = 'source'
releaseInfo.value = null
```

#### 前端 `frontend/src/components/common/VersionBadge.vue`

- `isReleaseBuild` 始终为 `false`
- 移除 `buildType` 和 `releaseInfo` computed 变量（避免 TS 未使用变量报错）
- 移除所有 GitHub release 链接、changelog 跳转链接
- 移除 `viewRelease` / `viewChangelog` 相关的 `<a>` 标签

## 工作流程

### 第 1 步：准备

```bash
# 1. 确保工作区干净
git status

# 2. 添加上游 remote（如果不存在）
git remote get-url upstream 2>/dev/null || git remote add upstream https://github.com/Wei-Shaw/sub2api.git

# 3. 拉取上游最新代码
git fetch upstream
```

### 第 2 步：分析差异

```bash
# 1. 查看上游领先的提交数
git log --oneline HEAD..upstream/main | wc -l

# 2. 查看变更统计
git diff --stat HEAD...upstream/main | tail -5

# 3. 查看我们领先上游的自定义提交
git log --oneline --no-merges upstream/main..HEAD
```

向用户报告差异概况，确认后继续。

### 第 3 步：执行合并

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

### 第 4 步：处理冲突（如有）

- 如果有冲突文件，逐一解决
- 优先采用上游的架构/代码重构，但保留自定义配置清单中的值
- 解决后 `git add` 冲突文件

### 第 5 步：重新应用自定义配置

合并完成后（无论是否有冲突），必须全面扫描并修复：

1. **品牌扫描**：
   ```bash
   grep -rn "Sub2API" frontend/src/ --include="*.ts" --include="*.vue" --include="*.html"
   ```
   将所有影响运行时的 `Sub2API` 替换为 `StarFireAPI`（代码注释除外）。

2. **链接扫描**：
   ```bash
   grep -rn "github.com/Wei-Shaw/sub2api" frontend/src/
   ```
   将前端代码中的 GitHub 链接替换为 `anthropic.edu.pl`。

3. **docker-compose 检查**：
   确认 `deploy/docker-compose.yml` 中的自定义项未被覆盖。

4. **更新模块检查**：
   确认 `system_handler.go`、`app.ts`、`VersionBadge.vue` 中的更新禁用逻辑仍然生效。

### 第 6 步：提交

```bash
git add -A
git commit -m "同步上游至最新版本并重新应用自定义配置

上游新增功能：
- [列出主要新功能]

自定义配置保留：
- 品牌化：Sub2API → StarFireAPI
- 链接：GitHub → anthropic.edu.pl 官网
- docker-compose：starfireapi镜像、端口6580、外部Redis、项目名xinghuoapi
- 更新模块禁用

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

### 第 7 步：确认推送

询问用户是否推送到 origin：

```bash
git push origin main
```

## 注意事项

- 合并前必须确保工作区干净（无未提交的改动）
- 如果上游有大量重构导致自定义文件结构变化，需要根据新结构重新应用自定义
- `deploy/` 和 `backend/` 目录下的文档/配置模板中的 GitHub 链接和 Sub2API 字样可以保留（不影响运行时）
- 只替换 `frontend/src/` 下影响运行时行为的代码