chore: 添加 sync-upstream skill 自动化上游合并流程
定义拉取上游、合并、重新应用自定义配置（品牌、链接、docker-compose、更新模块禁用）的标准化流程， 使用 /sync-upstream 即可触发。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
206
skills/sync-upstream/SKILL.md
Normal file
206
skills/sync-upstream/SKILL.md
Normal file
@@ -0,0 +1,206 @@
|
||||
---
|
||||
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/` 下影响运行时行为的代码
|
||||
Reference in New Issue
Block a user