xinghuoapi/skills/sync-upstream/SKILL.md

name, description, license, metadata

name	description	license	metadata
sync-upstream	从上游 Wei-Shaw/sub2api 拉取最新代码并合并，自动保留所有 StarFireAPI 自定义配置（品牌、链接、docker-compose、更新模块禁用）。	MIT	author version huangzhenpc 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 方法始终返回无更新：

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 中强制返回无更新：

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 步：准备

# 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 步：分析差异

# 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 步：执行合并

git merge upstream/main --no-edit

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

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

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

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

1. 品牌扫描：

   grep -rn "Sub2API" frontend/src/ --include="*.ts" --include="*.vue" --include="*.html"
   

   将所有影响运行时的 Sub2API 替换为 StarFireAPI（代码注释除外）。

2. 链接扫描：

   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 步：提交

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：

git push origin main

注意事项

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