@jsonstudio/rcc 0.89.1348 → 0.89.1488

package/docs/antigravity-gemini-format-cleanup.md

@@ -0,0 +1,143 @@
+---
+title: Antigravity Gemini 格式清理要求
+date: 2026-01-25
+tags:
+  - routecodex
+  - antigravity
+  - gemini
+  - claude
+status: active
+---
+
+# Antigravity Gemini 格式清理要求（gcli2api 对齐）
+
+> [!summary]
+> 本文汇总当前 **antigravity** 走 Gemini 协议时的格式清理要求，覆盖 **Gemini 系列** 与 **Claude 系列** 的关键输出/请求规范、UA/Headers 规范、工具历史一致性要求等。
+> 本次改动已生效：历史 `functionCall` 强制补 `thoughtSignature: "skip_thought_signature_validator"`。
+
+## 1) 适用范围
+- **Gemini 系列**：`gemini-3-pro-low / gemini-3-pro-high` 等 Gemini 协议模型。
+- **Claude 系列**：`claude-*` 走 antigravity/兼容层的 Gemini 路由时的兼容字段统一。
+
+---
+
+## 2) UA 与 Headers（Antigravity Tools 对齐）
+- **Antigravity 分支**：
+  - **JSON wrapper 内保留**：`requestId / requestType / userAgent / project / request`
+  - **不发送 Gemini CLI header triplet**：`x-goog-api-client / client-metadata`（避免与 Antigravity Tools 行为不一致）
+  - **不注入 session_id**（保持协议最小化）
+- **非 Antigravity 分支**（Gemini CLI 常规）：
+  - 仍可维持稳定 header triplet（用于 Gemini CLI 兼容）
+
+> [!note]
+> Antigravity 路径的 User-Agent 由 wrapper 里的 `userAgent: "antigravity"` 控制，Header 仅保留必要的 HTTP 通用头。
+
+---
+
+## 3) 工具与历史一致性（核心要求）
+
+> [!important]
+> **历史中出现的工具调用必须与当前请求 tools 对齐**。历史中不得出现当前 tools 列表中不存在的工具调用。
+
+- **历史工具清理**：
+  - 对 **history 中出现但当前 tools 不存在** 的 `functionCall`/`functionResponse` 做 **移除或降级为纯文本**。
+  - 保持 **tools 列表与历史工具调用**的 **一一对应**。
+- **工具名合法性**：
+  - Gemini 对函数名字符集/形状严格校验；不合法名称需 **清理或过滤**。
+- **工具 schema 对齐**：
+  - 历史 `functionCall.args` 必须与当前工具 schema 对齐。
+  - 对 `args` 做 **结构修正**：Gemini 期望 `functionCall.args` 为对象（Struct），非对象需包 `value`。
+
+---
+
+## 4) Gemini 协议的格式清理要点
+
+### 4.1 functionCall 历史补签名
+- **新增要求（已生效）**：
+  - 历史 `functionCall` **必须包含**：
+    - `thoughtSignature: "skip_thought_signature_validator"`
+  - 这是 gcli2api 的行为：即使没有真实签名，也需要该字段以通过 Cloud Code 严格校验。
+
+### 4.2 工具 schema 输出
+- **始终输出工具 schema**（Gemini 需要工具声明来校验 `functionCall`/`functionResponse`）。
+- `toolConfig.functionCallingConfig`：
+  - `NONE / ANY / ALLOWED` 按 `tool_choice` 映射。
+
+### 4.3 Content 清理
+- 统一 `contents` 结构，确保每条 entry 的 parts 合法。
+- 对无效 part 做降级或过滤，避免 Gemini 侧 malformed。
+
+---
+
+## 5) Claude 系列在 Antigravity 中的兼容统一
+
+- Claude-thinking / 非 thinking 输出在 antigravity 侧 **统一形态**：
+  - 保证与 Gemini/OpenAI 响应结构一致的 **content 形状**。
+- 保持 **history/tool 行为与 Gemini 同步**（同样遵循历史工具一致性要求）。
+
+---
+
+## 6) 当前已生效的关键修复（含 2026-01-26 更新）
+
+- ✅ **历史 functionCall 强制补 `thoughtSignature`**（gcli2api 行为一致）。
+- ✅ **history/tool 对齐清理**：历史工具调用不再允许与当前 tools 不一致。
+- ✅ **args 结构修正**：非对象 args 包装到 `{ value }`。
+- ✅ **UA/Headers 与 Antigravity Tools 对齐**（wrapper 保留 identity，移除 Gemini CLI triplet）。
+- ✅ **兼容层保留 wrapper 字段**：`chat:gemini` 的 `shallow_pick` 允许 `request / requestId / requestType / userAgent / project`。
+- ✅ **上游 request 不含 metadata**：避免 `Unknown name "metadata" at 'request'`。
+- ✅ **baseURL 对齐 prod**：`https://cloudcode-pa.googleapis.com`。
+
+---
+
+## 6.1) Request Wrapper 结构（Antigravity）
+
+```json
+{
+  "model": "gemini-3-pro",
+  "project": "your-project-id",
+  "requestId": "agent-...",
+  "requestType": "agent|web_search|image_gen",
+  "userAgent": "antigravity",
+  "request": {
+    "contents": [...],
+    "systemInstruction": {...},
+    "tools": [...],
+    "generationConfig": {...},
+    "safetySettings": [...]
+  }
+}
+```
+
+> [!important]
+> `request` 内部 **禁止** `metadata` 字段。
+
+---
+
+## 6.2) 多账号 alias 策略（Antigravity）
+
+- **默认策略**：按 **model 维度**挑选“最佳账号”（剩余配额最高）。
+- **不做轮询**：只有当该 alias 的该 model **为空** 才切换。
+- **model 空判定**：
+  - quota `<= 0`
+  - 或 **429 冷却移出账号池 ≥ 30s**
+- **数据来源**：quota 池（antigravity quota snapshot 注入到 `quotaView`）。
+- **模型族分开**：每个 model 单独选择最佳 alias。
+
+> [!note]
+> “最佳账号推荐”来自 quota 池的剩余额度排序，优先消耗高配额账号以提升稳定性与命中率。
+
+---
+
+## 7) 验证方式（建议）
+
+- 对比两条请求（首条无历史、次条带历史）：
+  - `provider-request.json` 中 **`functionCall` 必须带 `thoughtSignature`**。
+  - `tools` 与历史 functionCall **必须一一对齐**。
+  - `args` 必须为对象（Struct）。
+
+---
+
+## 8) 备注
+
+> [!note]
+> 本次修改已验证生效。若后续仍出现 429 或 Cloud Code 严格校验失败，优先检查 **history 中工具清理是否遗漏** 或 **functionCall/Response 的结构化字段是否存在差异**。

package/docs/antigravity-routing-contract.md

@@ -0,0 +1,31 @@
+# Antigravity 429 + sticky-queue contract (standard behavior)
+
+This document defines the *default* behavior for Antigravity routing under transient 429s. It is a hard requirement
+for the "standard" execution path; any alternative behavior is considered legacy compatibility.
+
+## Contract (3 rules)
+
+1) **Success sticks**  
+   Once an alias is selected for a `(providerId=antigravity, modelId)` group, routing keeps selecting that alias
+   until the alias becomes unavailable (error / cooldown / blacklist).
+
+2) **429 cools down + rotates to tail**  
+   For capacity-style 429s (e.g. upstream "model capacity exhausted"), routing:
+   - immediately applies a short cooldown to the failing `providerKey` (alias-level for Antigravity), and
+   - on retry, rotates the failing alias to the tail of the sticky-queue, so the next attempt prefers a different alias.
+
+3) **Fallback only when exhausted**  
+   Retrying stays within Antigravity for the same model as long as any usable alias remains.
+   Only when all aliases are excluded/cooling/blacklisted does routing fall back to other providers/routes.
+
+## Where this is implemented
+
+- **Retry hint plumbing (excludedProviderKeys)**: `src/server/runtime/http-server/request-executor.ts`
+- **Sticky-queue selection + alias rotation**:
+  - `sharedmodule/llmswitch-core/src/router/virtual-router/engine-selection/alias-selection.ts`
+  - `sharedmodule/llmswitch-core/src/router/virtual-router/engine-selection/tier-selection.ts`
+  - `sharedmodule/llmswitch-core/src/router/virtual-router/engine-selection/tier-selection-select.ts`
+- **Capacity-style 429 cooldown (alias-level for Antigravity)**:
+  - `src/manager/modules/quota/provider-quota-daemon.model-backoff.ts`
+  - `src/manager/modules/quota/provider-quota-daemon.events.ts`
+

package/docs/chat-semantic-expansion-plan.md

@@ -2,6 +2,8 @@
 
 > 目标：让 llmswitch-core 中的 Chat Process / Standardized 桥承接四种协议的语义，不再依赖 metadata 透传 “raw payload”，并按顺序分阶段完成。
 
+> 术语约定：本文中的 “chat process” 指代码层面的 `chat_process` 阶段（工具治理/路由/协议重建的必经处理段）。
+
 ### 阶段 0：现状确认
 
 1. **协议扫描**  
@@ -9,7 +11,7 @@
    - `responses-mapper.ts`：resume/include/store 等通过 `metadata.responsesContext/responseFormat` 储存。  
    - `anthropic-mapper.ts`：system blocks、tool alias、内容 shape 等塞进 `metadata.extraFields`。  
    - `gemini-mapper.ts`：systemInstruction、safetySettings、generationConfig、toolConfig 均在 metadata/parameters。
-2. **chat-process / standardized 桥**  
+2. **chat process / standardized 桥**  
    - 只理解 `messages/tools/toolOutputs/parameters`，其余通通进 `metadata.capturedContext`。
 
 ### 阶段 1：扩展 Chat Process + Standardized 桥
@@ -20,13 +22,13 @@
      - **协议专属命名空间**：`semantics.responses` / `semantics.anthropic` / `semantics.gemini`。每个命名空间内定义稳定 contract，禁止随意往里塞 provider extras。  
      - **providerExtras** 仅用于临时透传，默认禁止业务逻辑读取，后续接线完成后应趋近于空。
    - `chatEnvelopeToStandardized` / `standardizedToChatEnvelope` 深拷贝 `semantics`。
-2. **chat-process 适配**  
+2. **chat process 适配**  
    - `runHubChatProcess`、工具治理、路由决策只读 `request.semantics`；除 mapper/bridge 外，任何模块不得写入 `semantics`。  
    - Metadata 退回诊断角色：仅保留 `missingFields/providerMetadata` 等调试字段，`capturedContext` 禁止再夹带业务语义。
 3. **模块测试**  
-   - 新增 spec：构造 `ChatEnvelope` (含 system/responses/anthropic/gemini)，执行标准化→还原→chat-process，断言 `semantics` 原样保留。
+   - 新增 spec：构造 `ChatEnvelope` (含 system/responses/anthropic/gemini)，执行标准化→还原→chat process，断言 `semantics` 原样保留。
 
-> 完成该阶段后，chat-process 成为“语义承接层”，为后续接线提供可靠落点。
+> 完成该阶段后，chat process 成为“语义承接层”，为后续接线提供可靠落点。
 
 ### 阶段 2：协议语义接线（分批）
 
@@ -69,10 +71,10 @@
 ### 注意事项
 
 - **严格顺序**：阶段 1 完成并通过黑盒测试后，才能启动阶段 2 的任何接线工作。  
-- **只读语义**：除 Semantic Mapper / Bridge 外，任何模块不得写 `semantics`； chat-process 之后的所有节点禁止从 metadata/raw 读取业务语义。  
+- **只读语义**：除 Semantic Mapper / Bridge 外，任何模块不得写 `semantics`； chat process 之后的所有节点禁止从 metadata/raw 读取业务语义。  
 - **最小增量**：每个协议接线尽量独立 PR/commit，便于回滚。  
 - **兼容期双写**：阶段 2 中需维护 semantics & metadata 双写（写 semantics → 同步旧字段）；读路径优先 semantics，metadata 仅保底兼容，直到阶段 3 清理完成。  
-- **验证方式**：所有语义字段必须能在 `StandardizedRequest.semantics` 中观测到，且 chat-process/路由/工具治理仅依赖该结构。
+- **验证方式**：所有语义字段必须能在 `StandardizedRequest.semantics` 中观测到，且 chat process/路由/工具治理仅依赖该结构。
 
 ### 审查建议