@jsonstudio/rcc 0.89.1548 → 0.89.1562

package/docs/daemon-admin-ui.html

@@ -885,6 +885,7 @@
                 <label for="oauthAuthAliasInput">alias</label>
                 <input id="oauthAuthAliasInput" type="text" placeholder="default" style="width: 240px;" />
               </div>
+              <div id="oauthAuthIssueHint" class="notice" style="display:none; margin-bottom: 10px; white-space: pre-wrap;"></div>
               <div class="row" style="margin-bottom: 10px;">
                 <label><input id="oauthOpenBrowser" type="checkbox" checked /> open browser</label>
                 <label><input id="oauthForceReauth" type="checkbox" /> force reauthorize</label>
@@ -1957,18 +1958,129 @@
         $("authCookieBox").style.display = mode === "cookie" ? "block" : "none";
       }
 
+      function findAuthIssueForProviderAlias(providerRaw, aliasRaw) {
+        const provider = textOf(providerRaw || "").trim().toLowerCase();
+        const alias = textOf(aliasRaw || "").trim().toLowerCase();
+        if (!provider || !alias) return null;
+        const list = Array.isArray(UI.quotaProviders) ? UI.quotaProviders : [];
+        if (provider !== "antigravity") return null;
+        const prefix = `antigravity.${alias}.`;
+        for (const q of list) {
+          const pk = textOf(q && q.providerKey ? q.providerKey : "").trim().toLowerCase();
+          if (!pk.startsWith(prefix)) continue;
+          const issue = q && q.authIssue && typeof q.authIssue === "object" ? q.authIssue : null;
+          if (issue && issue.kind === "google_account_verification") {
+            return { kind: issue.kind, url: textOf(issue.url || ""), message: textOf(issue.message || "") };
+          }
+        }
+        return null;
+      }
+
+      function updateOauthAuthIssueHint() {
+        const el = $("oauthAuthIssueHint");
+        if (!el) return;
+        const provider = textOf($("oauthProviderSelect").value || "").trim().toLowerCase();
+        const alias = textOf($("oauthAuthAliasInput").value || "default").trim().toLowerCase();
+        const issue = findAuthIssueForProviderAlias(provider, alias);
+        if (!issue) {
+          el.style.display = "none";
+          el.textContent = "";
+          return;
+        }
+        if (issue.kind === "google_account_verification") {
+          const url = issue.url ? `\n\nOpen: ${issue.url}` : "";
+          el.textContent =
+            `⚠ Google requires account verification for alias \"${alias}\".\n` +
+            `Complete the browser verification flow, then click Authorize again.${url}`;
+          el.style.display = "block";
+          return;
+        }
+        el.style.display = "none";
+        el.textContent = "";
+      }
+
+      function listAntigravityProviderKeysByAlias(aliasRaw) {
+        const alias = textOf(aliasRaw || "").trim().toLowerCase();
+        if (!alias) return [];
+        const list = Array.isArray(UI.quotaProviders) ? UI.quotaProviders : [];
+        const prefix = `antigravity.${alias}.`;
+        const out = [];
+        for (const q of list) {
+          const pk = textOf(q && q.providerKey ? q.providerKey : "").trim();
+          if (!pk) continue;
+          if (pk.toLowerCase().startsWith(prefix)) out.push(pk);
+        }
+        out.sort((a, b) => a.localeCompare(b));
+        return out;
+      }
+
+      async function recoverAntigravityAliasIfAuthVerify(aliasRaw) {
+        if (!UI.adminAuth || !UI.adminAuth.authenticated) {
+          return;
+        }
+        const keys = listAntigravityProviderKeysByAlias(aliasRaw);
+        if (!keys.length) return;
+        const toRecover = [];
+        for (const key of keys) {
+          const q = getQuotaStateByProviderKey(key);
+          if (!q) continue;
+          if (textOf(q.reason || "").trim() === "authVerify") {
+            toRecover.push(key);
+          }
+        }
+        if (!toRecover.length) {
+          return;
+        }
+        for (const key of toRecover) {
+          try {
+            await apiFetch(`/quota/providers/${encodeURIComponent(key)}/recover`, { method: "POST" });
+          } catch {
+            // best-effort
+          }
+        }
+      }
+
       async function refreshCredentials() {
         const body = $("credentialsTbody");
         body.replaceChildren();
         try {
           const items = await apiFetch("/daemon/credentials");
+          // Best-effort: load quota provider state so we can surface upstream auth issues (e.g. Google verify required).
+          try {
+            const quota = await apiFetch("/quota/providers");
+            const quotaProviders = quota && Array.isArray(quota.providers) ? quota.providers : [];
+            UI.quotaProviders = quotaProviders;
+            UI.quotaProvidersUpdatedAt = Date.now();
+            UI.quotaProviderMap = new Map(quotaProviders.map((q) => [textOf(q.providerKey), q]));
+          } catch {
+            // ignore
+          }
+
+          updateOauthAuthIssueHint();
           for (const c of items || []) {
             const tr = document.createElement("tr");
             const exp = c.expiresInSec == null ? "—" : `${c.expiresInSec}s`;
             tr.appendChild(createCell("td", c.kind || "", ""));
             tr.appendChild(createCell("td", c.provider || "", "mono"));
             tr.appendChild(createCell("td", c.alias || "", "mono"));
-            tr.appendChild(createCell("td", c.status || "", ""));
+            const statusTd = document.createElement("td");
+            statusTd.appendChild(pill(c.status || "—", (c.status || "") === "valid" ? "ok" : "warn"));
+            const issue = findAuthIssueForProviderAlias(c.provider, c.alias);
+            if (issue) {
+              statusTd.appendChild(document.createTextNode(" "));
+              statusTd.appendChild(pill("verify required", "bad"));
+              if (issue.url) {
+                statusTd.appendChild(document.createTextNode(" "));
+                const a = document.createElement("a");
+                a.href = issue.url;
+                a.target = "_blank";
+                a.rel = "noreferrer";
+                a.textContent = "open";
+                a.className = "mono";
+                statusTd.appendChild(a);
+              }
+            }
+            tr.appendChild(statusTd);
             tr.appendChild(createCell("td", exp, "mono"));
             tr.appendChild(createCell("td", c.secretRef || "—", "mono"));
             body.appendChild(tr);
@@ -2004,6 +2116,7 @@
 	        setLog("credentialOpLog", "");
 	        const provider = $("oauthProviderSelect").value;
 	        const alias = ($("oauthAuthAliasInput").value || "default").trim() || "default";
+	        updateOauthAuthIssueHint();
 	        const openBrowser = $("oauthOpenBrowser").checked;
 	        const forceReauthorize = $("oauthForceReauth").checked;
 	        try {
@@ -2013,6 +2126,17 @@
 	          });
 	          setLog("credentialOpLog", `OK. tokenFile: ${out.tokenFile || "—"}`);
 	          await refreshCredentials();
+	          // If OAuth was blocked by Google account verification and the user just completed it,
+	          // attempt to recover the alias back into the pool.
+	          if (textOf(provider).trim().toLowerCase() === "antigravity") {
+	            try {
+	              await recoverAntigravityAliasIfAuthVerify(alias);
+	            } catch {}
+	            try {
+	              await refreshQuota();
+	              await refreshCredentials();
+	            } catch {}
+	          }
 	        } catch (e) {
 	          setLog("credentialOpLog", `Authorize failed: ${e.message}`);
 	        }
@@ -2700,6 +2824,8 @@
           const out = await apiFetch("/quota/providers");
           UI.quotaProviders = Array.isArray(out.providers) ? out.providers : [];
           UI.quotaProvidersUpdatedAt = Date.now();
+          UI.quotaProviderMap = new Map(UI.quotaProviders.map((q) => [textOf(q.providerKey), q]));
+          updateOauthAuthIssueHint();
           renderQuotaProviders();
         } catch (e) {
           if (e && e.status === 401) notifyUnauthorizedOnce("quota");
@@ -2816,10 +2942,25 @@
               const reason = textOf(q.reason || "");
               const reasonKind =
                 reason === "ok" ? "ok" :
+                reason === "authVerify" ? "bad" :
                 reason === "cooldown" ? "warn" :
                 reason === "blacklist" || reason === "fatal" || reason === "quotaDepleted" ? "bad" : "warn";
               const reasonTd = document.createElement("td");
               reasonTd.appendChild(pill(reason || "—", reasonKind));
+              const issue = q && q.authIssue && typeof q.authIssue === "object" ? q.authIssue : null;
+              if (issue && issue.kind === "google_account_verification") {
+                const url = textOf(issue.url || "");
+                if (url) {
+                  reasonTd.appendChild(document.createTextNode(" "));
+                  const a = document.createElement("a");
+                  a.href = url;
+                  a.target = "_blank";
+                  a.rel = "noreferrer";
+                  a.textContent = "verify";
+                  a.className = "mono";
+                  reasonTd.appendChild(a);
+                }
+              }
               tr.appendChild(reasonTd);
 
               const cooldown = formatEpochWithDelta(q.cooldownUntil);
@@ -3332,6 +3473,8 @@
       $("refreshCredentialsBtn").addEventListener("click", refreshCredentials);
       $("saveOauthBrowserBtn").addEventListener("click", saveSettings);
       $("oauthAuthorizeBtn").addEventListener("click", authorizeOauth);
+      $("oauthProviderSelect").addEventListener("change", updateOauthAuthIssueHint);
+      $("oauthAuthAliasInput").addEventListener("input", updateOauthAuthIssueHint);
 
       $("refreshQuotaBtn").addEventListener("click", refreshQuota);
       $("refreshQuotaSnapshotBtn").addEventListener("click", refreshQuotaSnapshotNow);

package/docs/providers/antigravity-fingerprint-ua-warmup.md

@@ -6,6 +6,26 @@
 
 ---
 
+## 0) 你需要知道的文件/目录/入口
+
+### 关键目录（默认都在 `~/.routecodex/`）
+
+- OAuth token：`auth/antigravity-oauth-*.json`
+- Camoufox profile：`camoufox-profiles/rc-gemini.<alias>/...`
+- Camoufox 指纹 env：`camoufox-fp/rc-gemini.<alias>.json`
+- reauth-required 标记：`state/antigravity-reauth-required.json`
+- UA 版本缓存：`state/antigravity-ua-version.json`
+
+> 为什么 profileId 是 `rc-gemini.<alias>`：`gemini-cli` 与 `antigravity` 共享同一“指纹家族（gemini）”，同 alias 共用同一套 profile/指纹，避免一个账号跑出两套平台指纹。
+
+### 关键日志/接口
+
+- 启动 warmup：`[antigravity:warmup] ...`
+- Quota / pool UI 数据：`GET /quota/providers`（包含 `fpOs/fpArch/fpSuffix/...`）
+- OAuth 本地 portal：OAuth 前会展示 token + 指纹摘要（Camoufox profile + OS/Arch）
+
+---
+
 ## 1) 403：`verify your account`（UA/指纹不匹配导致的重新验证）
 
 ### 现象
@@ -19,12 +39,55 @@
 - Antigravity/Gemini **禁止使用 Linux 指纹**（`linux/*`），发现即要求修复并重新 OAuth。
 - 每个 alias 使用自己对应的 Camoufox profile 指纹（避免“多个账号互相污染”）。
 
+### UA 的原则：版本可更新，OS/arch 不可漂移
+
+`User-Agent` header 形态：
+
+```
+antigravity/<version> <os>/<arch>
+```
+
+- `<os>/<arch>` 来自 alias 的 OAuth 指纹（Camoufox）；**不能随意改**。
+- `<version>` 允许更新（避免 “This version of Antigravity is no longer supported.”）。
+
+RouteCodex 的版本号来源（从高到低）：
+1. `ROUTECODEX_ANTIGRAVITY_USER_AGENT` / `RCC_ANTIGRAVITY_USER_AGENT`（完全覆盖）
+2. `ROUTECODEX_ANTIGRAVITY_UA_VERSION` / `RCC_ANTIGRAVITY_UA_VERSION`
+3. 远程拉取（可通过 `ROUTECODEX_ANTIGRAVITY_UA_DISABLE_REMOTE=1` 禁用）
+4. `~/.routecodex/state/antigravity-ua-version.json`
+5. 兜底版本（仅保证“有值”，不保证不过期）
+
 ### 修复步骤
 1. 修复指纹（把 linux 修回 windows/macos）：
    - `routecodex camoufox-fp repair --provider antigravity --all`
 2. 对被标记需要 reauth 的 alias 重新 OAuth：
    - `routecodex oauth antigravity-auto <token-selector-or-path>`
    - 或批量：`routecodex oauth reauth-required`
+3. 如果 Google 提示需要二次验证（账户风控页），用对应 alias 的 profile 打开浏览器完成验证（“养号/解封”）：
+   - `rcc camoufox ~/.routecodex/auth/antigravity-oauth-<alias>.json --url '<verify_url>'`
+
+> 关键点：必须用 **同一个 alias 的 Camoufox profile** 打开验证页，否则容易造成“验证通过但指纹漂移 → 继续 403”。
+
+---
+
+## 1.1) 多账号并发：为什么会“一个号 403 牵连别的号”
+
+### 现象
+- 多个 Antigravity alias 同时跑（或者同一会话内快速切换 alias）时，某个 alias 触发 `verify your account` 之后，其他 alias 也开始陆续 403。
+
+### 我们确认过的根因（与 Antigravity-Manager 行为对齐）
+- Antigravity/Cloud Code Assist **对同一会话指纹（sessionId）跨账号切换极敏感**：同一个会话如果在短时间内换 OAuth cookie / device profile，极容易触发 Google 风控。
+- Antigravity-Manager 的策略是 **session_id → account 绑定**：同一 session 不随便换账号；账号需要验证就让它失败并提示用户完成验证。
+
+### RouteCodex 的修复策略（现在的默认行为）
+- 当某个 Antigravity alias 命中 **403 verify** 时：
+  - Virtual Router 会将该 alias（同 runtimeKey 下的所有模型 key）立即标记为 `auth_verify` 冷却（默认 24h，可通过 OAuth 重新恢复）。
+  - 同一次请求的重试阶段，会 **避免命中任何 Antigravity alias**，只尝试非 Antigravity 的兜底池（例如 `gemini-cli`）。
+- 当某个 Antigravity alias 命中 **429** 时：
+  - 重试阶段同样 **不在 Antigravity 内换号**，只走非 Antigravity 兜底（避免“429→换号→全家 403”）。
+  - 具体“换号”交给后续请求 + Virtual Router 健康/冷却机制（而不是在单次请求里瞬间轮询所有账号）。
+
+> 经验：这条策略会让“单次请求”的 fallback 更克制，但能显著降低“多账号一起用 → 全部触发二次验证”的概率。
 
 ---
 
@@ -33,6 +96,29 @@
 ### 现象
 - 上游返回 `HTTP 429`，错误体含 `RESOURCE_EXHAUSTED`。
 
+### 关键结论（本次事故的“真因”）
+我们遇到过一种非常典型的形态：
+- **第一次请求 OK**（upstream 在响应里下发了 `thoughtSignature`）
+- **第二次（带工具历史）开始 429**（本地在历史 `functionCall` part 里丢了/没注入 `thoughtSignature`）
+
+而“丢签名”的根因不是 quota，而是 **Antigravity provider 配错了 compat profile**：
+- `chat:gemini` 不会跑 `gemini_cli_request_wrap`（因此不会做历史 `thoughtSignature` 注入）
+- Antigravity 必须用 `chat:gemini-cli`（Cloud Code Assist wrapper 对齐 + signature 注入）
+
+修复点：确保你的用户配置中（`~/.routecodex/config.json`）：
+
+```jsonc
+{
+  "virtualrouter": {
+    "providers": {
+      "antigravity": {
+        "compatibilityProfile": "chat:gemini-cli"
+      }
+    }
+  }
+}
+```
+
 ### 说明
 - 这类 429 可能是“真实配额/容量”或上游策略性拒绝，**不能假设一定是本地形状问题**。
 - 但在 Antigravity/Gemini 路径上，如果请求形状/历史/工具 schema/签名注入不对齐，也会显著放大 429 的出现概率（尤其是长上下文 + 多工具历史）。
@@ -47,7 +133,19 @@
   - tool 声明字段对齐（例如 Gemini 最新规范要求 `parameters`）
   - Antigravity wrapper 语义要求：不把内部调试字段带到上游（版本/buildTime 等只留在本地快照）
 
-> 上述行为有黑盒回归：同一 payload 跑“mock upstream”验证 signature 缓存与注入是否生效。
+### 如何确认签名注入真的生效（不是“占位”）
+
+建议用 codex-samples 快照做证据链（不看日志猜测）：
+
+1. 找到一次成功返回且包含 `thoughtSignature` 的响应快照（`provider-response.json` / SSE 片段中 `candidate.content.parts[].thoughtSignature`）。
+2. 紧接着找下一次“带工具历史”的请求快照，检查 request body 的 `contents[].parts[].functionCall` 是否带同一个 `thoughtSignature`。
+
+> 这个验证不依赖“你是否真的有 quota”；只要 upstream 在某次响应里下发过 signature，后续注入就应当可见。
+
+### 如何确认 compat profile 真的生效
+用 `--snap` 或 dev 默认快照（`~/.routecodex/codex-samples/...`）检查 pipeline stage8：
+- `chat_process.req.stage8.outbound.compat.json` 里必须出现 `chat:gemini-cli`
+- 如果你看到的是 `chat:gemini`，说明 profile 仍然配错（很容易复发“第一次 OK，第二次 429”）
 
 ---
 
@@ -59,6 +157,23 @@
   - UA 的 `<os>/<arch>` 与指纹期望一致
   - 若修过指纹，需要完成 OAuth reauth
 
+### Warmup 实际做了什么
+
+实现位置：
+- 检查逻辑：`src/providers/auth/antigravity-warmup.ts:warmupCheckAntigravityAlias()`
+- 启动触发：`src/server/runtime/http-server/index.ts`（初始化阶段遍历 `antigravity.<alias>.*` providerKey）
+
+行为（高层）：
+1. 读取 alias 的 Camoufox 指纹 → 推断期望 suffix（`windows|macos` + `amd64|aarch64`）。
+2. 解析/生成 `User-Agent`（会强制刷新版本号，避免过旧）。
+3. 校验 `ua_suffix === expected_suffix`。
+4. 若检测到 alias 处于 `reauth_required` 状态，则提示 OAuth，并在满足条件时自动清理“陈旧标记”（通过 token 文件 mtime 判断）。
+5. 如果 warmup 失败且 quota 模块可用，会把该 alias 下的所有 providerKey **blacklist** 一段时间（默认很长，避免运行时误用被 ban）。
+
+可控开关：
+- 禁用 warmup：`ROUTECODEX_ANTIGRAVITY_WARMUP=0` / `RCC_ANTIGRAVITY_WARMUP=0`
+- blacklist 时长：`ROUTECODEX_ANTIGRAVITY_WARMUP_BLACKLIST_MS=<ms>`
+
 ### 日志格式
 - 启动后会看到：
   - `[antigravity:warmup] OK ... fp_os=... fp_arch=... expected=... actual=...`
@@ -72,4 +187,3 @@
 ## 4) 变更范围约束（架构要求）
 - Hub Pipeline 仍是唯一执行路径；Provider 层只做传输（auth/http/retry/compat hook）。
 - Antigravity 的 session/signature 逻辑 **不扩散**：最多位于 compat 与 gemini-cli provider 路径。
-