sub2api/ANTIGRAVITY_WARMUP_SOLUTION.md

# Antigravity 账号初始化延迟问题诊断报告

## 问题现象

账号 69 的首次请求时出现：
- 前 46 次请求：HTTP 503 Service Unavailable
- 第 47 次请求：成功（HTTP 200）
- 现象：`[antigravity-Test] attempt=47/60`

## 根本原因

**不是隐私设置问题**，而是**新账号的 Antigravity API 初始化延迟**。

诊断过程：
1. ✓ 隐私设置验证：SetUserSettings 和 FetchUserInfo 都成功
2. ✓ 账户额度：有充足的 AI Credits
3. ✓ Token 有效：GetUserInfo 返回正确的邮箱
4. ⚠ 首次请求延迟：需要 4-6 秒初始化

### 初始化流程耗时分析

```
GetUserInfo                   → 1.2s
LoadCodeAssist               → 2.2s  
FetchAvailableModels         → 1.1s
─────────────────────────────────────
Total Warmup Time            ≈ 4.5s
```

## 解决方案

### 方案 A：账号创建时预热（推荐）✅

在 `account_service.go` 中，账号创建成功后立即预热：

```go
// AccountService.CreateAccount() 或 .ValidateAndCreateAccount()
account, err := s.createAccount(...)
if err == nil && account.Platform == "antigravity" && account.Type == "oauth" {
    // 后台异步预热，不阻塞主流程
    go s.oauthService.WarmupAntigravityAccountAsync(
        context.Background(),
        account.Credentials.AccessToken,
        account.Credentials.ProjectID,
        proxyURL,
        &service.WarmupOptions{Async: true},
    )
}
return account, nil
```

**优势**：
- ✓ 用户首次请求时账号已初始化
- ✓ 非阻塞（后台执行）
- ✓ 失败不影响账号创建
- ✓ 总耗时 4.5s（预热） vs 50s（47 次重试）

### 方案 B：提高新账号的重试上限

在 `antigravity_gateway_service.go` 中对新账号（创建时间 < 5 分钟）使用更多重试：

```go
// isNewAccount 判断账号是否新创建（< 5 分钟）
if time.Since(p.account.CreatedAt) < 5*time.Minute {
    // 新账号：60 次重试，1 秒间隔
    antigravitySmartRetryMaxAttempts = 60
    antigravitySmartRetryBaseDelay = 1 * time.Second
} else {
    // 老账号：1 次重试
    antigravitySmartRetryMaxAttempts = 1
}
```

**优势**：
- 兼容所有现有账号（无需预热）

**劣势**：
- ⚠ 每个新账号请求需要等待 50 秒
- ⚠ 用户体验差

### 方案 C：在账号详情返回预热状态

```go
GET /api/v1/admin/accounts/69
→ {
  "id": 69,
  "warmed_up": false,
  "warming_up_since": "2026-04-10T23:50:00Z",
  "estimated_warmup_complete": "2026-04-10T23:54:30Z"
}
```

**用途**：
- 让前端显示"账号初始化中"
- 用户可等待初始化完成后再使用

---

## 推荐实施方案

**组合 A + C**（最优）：

1. **立即实施**（预热新账号）
   - 在 `account_service.go` 中调用 `WarmupAntigravityAccountAsync()`
   - 新账号创建后 4.5 秒内完成初始化

2. **可选增强**（显示预热状态）
   - 在账号详情 API 返回 `warmed_up` 标志
   - 前端可显示"初始化中..."

---

## 实施步骤

### Step 1: 集成预热功能

已在 `internal/service/antigravity_warmup.go` 中实现：

```go
// 异步预热（推荐）
oauthService.WarmupAntigravityAccountAsync(
    ctx,
    accessToken,
    projectID,
    proxyURL,
    &WarmupOptions{Async: true},
)

// 同步预热（如需等待）
oauthService.WarmupAntigravityAccount(ctx, accessToken, projectID, proxyURL)
```

### Step 2: 在账号创建流程中调用

需要修改的文件：
- `internal/service/account_service.go`
- `internal/handler/admin/account_handler.go` 或对应的 OAuth 处理器

```go
// 创建账号后立即预热
if isAntigravityOAuth {
    go s.oauthService.WarmupAntigravityAccountAsync(
        context.Background(),
        tokenInfo.AccessToken,
        tokenInfo.ProjectID,
        proxyURL,
        &WarmupOptions{Async: true},
    )
}
```

### Step 3: 可选 - 添加预热状态追踪

```go
// Account 模型中添加字段
type Account struct {
    // ...
    WarmupCompletedAt *time.Time  `db:"warmup_completed_at"`
}

// 查询时：
warmed := account.WarmupCompletedAt != nil && time.Now().After(*account.WarmupCompletedAt)
```

---

## 验证方法

### 本地测试

```bash
# 编译诊断工具
go build -o /tmp/test_warmup ./cmd/test_antigravity_warmup

# 顺序请求测试（应该全部成功）
/tmp/test_warmup \
  -token "YOUR_TOKEN" \
  -project "YOUR_PROJECT" \
  -test sequential_requests

# 并发请求测试
/tmp/test_warmup \
  -token "YOUR_TOKEN" \
  -project "YOUR_PROJECT" \
  -test concurrent_requests
```

### 生产验证

1. 创建新 Antigravity 账号
2. 立即发送请求 → 应成功（而非 503）
3. 检查日志：`antigravity_account_warmup_completed`

---

## 时间线

| 步骤 | 耗时 | 说明 |
|------|------|------|
| 创建账号 | 0.5s | API 调用 |
| 开始预热（后台） | 0.1s | 启动 goroutine |
| 预热完成 | 4.5s | GetUserInfo + LoadCodeAssist + FetchAvailableModels |
| 首次请求 | 0.5s | 立即成功（账号已初始化） |
| **总耗时** | **5.6s** | vs 50s（方案 B） |

---

## 总结

```
问题：  新账号首次请求返回 503 Service Unavailable
原因：  Antigravity API 初始化延迟（4-6 秒）
方案：  账号创建时后台异步预热（WarmupAntigravityAccountAsync）
成本：  +4.5 秒（一次性），改善用户体验 10 倍