sub2api/.agents/workflows/sync-upstream.md

description

description
从上游 (origin/main) 同步更新，保留 Antigravity 自定义改动

前置检查

// turbo

1. 查看当前状态和上游差异

cd /Users/win/2025/aitool/MiniGravity/sub2api
git fetch origin
git log --oneline HEAD..origin/main

如果上游没有新 commits，停止（无需同步）。

执行同步

2. 确保工作区干净

git status

如果有未提交的改动，先 git stash。

// turbo 3. 备份当前自定义 patches

mkdir -p /tmp/antigravity-patches
git format-patch origin/main..HEAD -o /tmp/antigravity-patches/
echo "已备份 $(ls /tmp/antigravity-patches/*.patch 2>/dev/null | wc -l) 个 patch 到 /tmp/antigravity-patches/"

4. 执行 rebase（把自定义 commits 移植到最新 upstream 上）

git rebase origin/main

如果有冲突，根据下方"冲突解决指南"处理，然后 git rebase --continue。

// turbo 5. 编译验证

cd /Users/win/2025/aitool/MiniGravity/sub2api/backend && go build ./...

6. 推送

git push origin main --force-with-lease

---

冲突解决指南

高频冲突文件及处理策略

backend/internal/repository/http_upstream.go

我方改动：在 Do() 和 DoWithTLS() 中新增了 Node.js TLS 代理路由逻辑。 策略：保留上游对函数签名/连接池的改动，确保我方在函数开头新增的 isNodeTLSProxyEnabled() 判断块被保留。

# 查看冲突
git diff backend/internal/repository/http_upstream.go
# 关键：确保以下两个块被保留（来自 ours）：
# 1. Do() 中的 Node.js proxy 路由 (~L128-137)
# 2. DoWithTLS() 中的 Node.js proxy 路由 (~L180-187)
# 3. isNodeTLSProxyEnabled() / shouldRouteViaNodeProxy() / doViaNodeTLSProxy() 函数

backend/internal/config/config.go

我方改动：在 GatewayConfig struct 新增了 NodeTLSProxy、InstanceSalt、FingerprintDefaults 三个字段。 策略：上游通常只在 struct 末尾添加新字段，我方也是添加字段，基本不冲突。

# 确保以下字段存在于 GatewayConfig struct 中
grep -n "NodeTLSProxy\|InstanceSalt\|FingerprintDefaults" backend/internal/config/config.go

backend/internal/service/identity_service.go

我方改动：

• 更新了 defaultFingerprint 的版本号
• 新增 ApplyDefaultFingerprintOverrides() 函数
• 新增 NewIdentityServiceWithSalt() 函数
• 在 IdentityService struct 加 instanceSalt 字段 策略：上游通常不改 defaultFingerprint，直接 Accept Ours 这部分。

backend/internal/pkg/claude/constants.go

我方改动：更新 Claude CLI 版本常量（CLI_VERSION / SDK_VERSION）。 策略：直接保留我方版本号（更新的）。

backend/cmd/server/wire_gen.go

我方改动：可能因 Wire 依赖注入改变。 策略：先接受 Theirs，然后重新运行 go generate ./cmd/server/ 重新生成。

---

零冲突文件（永远不会冲突）

以下目录是我方全新添加，upstream 没有，永远不会冲突：

• tools/node-tls-proxy/ — Node.js TLS 代理
• tools/firewall/ — iptables 防火墙规则
• tools/sora-curl-cffi-sidecar/ — Sora curl_cffi sidecar
• deploy/docker-compose.tls-proxy.yml — TLS 代理 compose
• deploy/build-push-tls-proxy.sh — 构建推送脚本