[原创]【技术分享】跨生态桥接：将 Claude Code 无缝接入 Google Antigravity订阅算力的反向代理架构实现-AI 工具与工作流-看雪安全社区

# 【技术分享】跨生态桥接：将 Claude Code 无缝接入 Google Antigravity/Cloud Code 订阅算力的反向代理架构实现

> **论坛建议板块**：『编程技术』 或 『安全工具』  
> **文章标签**：`AI工具`, `反向代理`, `ClaudeCode`, `GoogleCloudCode`, `OAuth2`, `SSE流式`  
> **摘要**：Claude Code 作为 Anthropic 官方推出的强大终端 Agent，其通信深度强绑定官方 Messages API 规范。而 Google One AI Premium 订阅提供了充裕的高性能模型（Claude 4.6 Sonnet / Opus / Gemini 3.8），却只允许自家的 Antigravity 客户端调用其私有 Cloud Code PA 接口。本文详细拆解一款开源本地代理网关的设计与实现，从 OAuth 2.0 PKCE 凭证自动续期、内部托管项目绑定、双向 JSON Schema / SSE 协议状态机转换，到客户端防伪伪装与首包缓冲策略，实现双生态的完全无缝桥接。

---

## 0x01 背景与核心痛点（生态断层）

随着大语言模型生态的分化，开发者的常用工具与订阅算力常常出现错位：
* **下游客户端（Claude Code CLI）**：体验极佳的终端代码 Agent，但只认 Anthropic 官方规范：
 * 请求入口：`6c1K9s2c8@1M7s2y4Q4x3@1q4Q4x3V1k6Q4x3V1k6S2M7r3W2Q4x3X3g2S2L8Y4c8Z5M7X3!0H3K9h3y4Q4x3X3g2U0L8$3#2Q4x3V1k6$3x3g2)9J5c8X3#2W2M7%4y4S2k6$3g2K6i4K6j5H3
 * 报文结构：Anthropic Messages JSON 格式（`content_blocks`, `tool_use`, `thinking`）
 * 流式机制：基于 Anthropic 专属 SSE 事件规范（`message_start`, `content_block_delta`...）
* **上游算力源（Google One AI Premium / Antigravity）**：用户购买了 Google 订阅，包含充足的 Claude 3.5 Sonnet / Opus 额度，但 Google 的门禁极其严格：
 * 通信接口：Google 内部私有 Generative AI PA 协议（`v1internal:streamGenerateContent`）
 * 鉴权机制：Google OAuth 2.0 凭证，绑定到专属托管项目（如 `aicode-consumers`）
 * 客户端审查：严格要求官方 Antigravity IDE 的 Headers 特征（`X-Client-Name: antigravity`），并对竞争对手 Agent 指纹进行拦截。

**核心目标**：实现一个本地高性能协议中继网关（`antigravity-claude-proxy`），在本地监听 `8080` 端口。对下作为标准的 Anthropic API 服务供 Claude Code 无感知调用；对上伪装成 Antigravity 官方客户端向 Google 索取真实算力。

>  **系列与排查篇导读**：  
> 本文是《Claude Code 接入 Google Antigravity 实战》的**【架构与实现篇】**。  
> 如果你在重型上下文（大量 Skills/Tools）使用中遇到了启动即报 `400/429 RESOURCE_EXHAUSTED` 的问题，这是由于 Google 云端 WAF 针对竞品词汇的指纹封杀所致，完整单变量逆向破案过程请参阅：  
>  **[《【逆向排查】深挖云端黑盒：Claude Code 接入 Google Cloud Code 伪装 429 RESOURCE_EXHAUSTED 竞品指纹过滤破案实录》](./kanxue_post_2_heavy_context_429.md)**。

---

## 0x02 全局架构拓扑设计

```text
┌─────────────────────────────────────────────────────────────┐
│                    Claude Code CLI (客户端)                  │
│       发送: Anthropic 标准 Messages API (含 Tools/Skills)     │
│       接收: Anthropic 标准 SSE 流 (message_start, delta...)   │
└──────────────────────────────┬──────────────────────────────┘
                               │ HTTP: http://localhost:8080/v1/messages
                               ▼
┌─────────────────────────────────────────────────────────────┐
│             antigravity-claude-proxy (核心代理网关)          │
│                                                             │
│  [1. Server 服务入口 (src/server.js)]                       │
│      ├── Express HTTP Server (监听 8080 端口)                │
│      ├── 路由分发 (/v1/messages, /v1/models, /health)       │
│      └── 首包缓冲策略 (First-Chunk Buffering，防下游挂死)    │
│                                                             │
│  [2. 账号与凭据管理层 (src/account-manager/ & src/auth/)]   │
│      ├── OAuth 2.0 自动换 Token (Refresh Token -> Access)   │
│      ├── 项目发现 (loadCodeAssist -> aicode-consumers)      │
│      ├── 多账号调度 (Hybrid / Sticky / Round-Robin 算法)    │
│      └── 本地持久化 (~/.config/antigravity-proxy/accounts.json)
│                                                             │
│  [3. 双向协议格式转换引擎 (src/format/)]                     │
│      ├── Request Converter (Anthropic Schema -> Google)     │
│      ├── Schema Sanitizer (清洗 Google 不支持的 JSON Schema) │
│      ├── Cache Control 清除器 (剥离 Claude 私有缓存标记)     │
│      └── Thinking Utils (思维链签名保护与预算分配)           │
│                                                             │
│  [4. Cloud Code 组包与脱敏层 (src/cloudcode/)]               │
│      ├── Request Builder (封装 Google Cloud Code PA 信封)   │
│      ├── Identity Scrubber (中和 Anthropic 竞品指纹)         │
│      └── Session Manager (会话 ID 派生以保障多轮上下文一致)   │
│                                                             │
│  [5. 流式传输与事件映射层 (src/cloudcode/)]                 │
│      ├── SSE Parser (解析 Google 流式分块)                   │
│      └── SSE Streamer (组装 Anthropic 标准事件推送给下游)    │
└──────────────────────────────┬──────────────────────────────┘
                               │ HTTPS (带 Google OAuth Bearer Token + 官方防伪 Headers)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│      Google Cloud Code PA (daily-cloudcode-pa.googleapis.com)│
│               执行真实的 Claude 3.5 / Gemini 模型推理         │
└─────────────────────────────────────────────────────────────┘
```

---

## 0x03 Google 身份鉴权与凭证生命周期

### 1. OAuth 2.0 授权机制
代理基于标准 Google OAuth 2.0 Authorization Code + PKCE 流程构建：
* **授权 Scope**：`442K9s2c8@1M7s2y4Q4x3@1q4Q4x3V1k6Q4x3V1k6%4N6%4N6Q4x3X3g2Y4L8$3!0Y4L8r3g2S2M7r3W2K6i4K6u0W2j5$3!0E0i4K6u0r3j5i4g2@1K9q4)9J5c8X3y4D9L8%4g2V1i4K6u0V1M7r3I4S2N6r3k6G2M7X3#2Q4y4U0m8Q4c8e0y4Q4z5o6m8Q4z5o6t1`.
* **双 Token 体系**：
 * **Refresh Token**：长效凭证，存储在 `~/.config/antigravity-proxy/accounts.json` 中，除非手动解绑，否则永久有效。
 * **Access Token**：每次向上游请求时携带的短期 Bearer Token（有效期 1 小时）。
* **自动静默续期**：网关在 Access Token 过期前 5 分钟，自动向 `c1aK9s2c8@1M7s2y4Q4x3@1q4Q4x3V1k6Q4x3V1k6G2j5i4g2@1K9o6u0Q4x3X3g2Y4L8$3!0Y4L8r3g2S2M7r3W2K6i4K6u0W2j5$3!0E0i4K6u0r3N6r3!0C8k6h3&6Q4y4U0l9`. 发送请求刷新 Access Token，用户完全无感。

### 2. 内部项目自动挂载（`loadCodeAssist`）
Google One 订阅用户的免费算力并不挂在个人新建的 GCP 项目下，而是挂载在 Google 为开发者托管的专用 Project（通常为 `aicode-consumers` 或 `rising-fact-xxxx`）。
网关启动时自动向内部接口 `v1internal:loadCodeAssist` 报到，探测该 Project ID 及订阅状态（`tier: "pro"`），并在随后的每个请求外层自动封装 `project: "aicode-consumers"`。

---

## 0x04 双向协议转换引擎实现细节

### 1. 请求维度映射（Request Mapping）
在 `src/format/request-converter.js` 中完成数据模型重构：

| Anthropic 概念 | Google Cloud Code PA 对应映射 | 处理细节与避坑点 |
| :--- | :--- | :--- |
| `system` (字符串或 TextBlocks) | `request.systemInstruction.parts` | 必须剥离 `cache_control`；必须经过 Identity Scrubbing 中和竞品特征。 |
| `messages[i].role` (`user`/`assistant`) | `contents[i].role` (`user`/`model`) | Anthropic 的 `assistant` 必须重命名为 `model`。 |
| `tools` (Anthropic Tool 规范) | `request.tools[0].functionDeclarations` | 格式重构为 Google Function Calling 规范；剔除 `$schema`、`default` 等非法字段。 |
| `tool_use` (Assistant 发起调用) | `parts: [{ functionCall: { name, args } }]` | 工具名称与参数转为 JSON 对象。 |
| `tool_result` (User 返回执行结果) | `parts: [{ functionResponse: { name, response } }]` | 针对 Claude 系列模型，保留部分原生 Anthropic 标识。 |
| `thinking.budget_tokens` | `generationConfig.thinkingConfig` | 映射为 Google 思考预算限制，防止死循环。 |

### 2. 流式响应状态机转换（SSE Streamer）
在 `src/cloudcode/sse-streamer.js` 中，网关作为下游的 SSE Server，向下游输出标准的 5 阶段状态机：
1. **`message_start`**：下发包含消息 ID、模型名和初始元数据的事件。
2. **`content_block_start`**：标记文本块（`type: "text"`）或深度思考块（`type: "thinking"`）的开始。
3. **`content_block_delta`**：将 Google 的 `candidates[0].content.parts[0].text` 打包为 Anthropic 打字机增量推给终端。
4. **`content_block_stop`**：当前块结束；若模型发起工具调用，在此输出 `type: "tool_use"`。
5. **`message_delta` & `message_stop`**：附带 Token 消耗统计（`usage`），优雅断开连接。

### 3. 首包缓冲策略（First-Chunk Buffering）
流式代理最大的陷阱在于 HTTP 状态码的写入时机：
* **常见错误做法**：网关收到下游请求，立即执行 `res.writeHead(200)` 并开始推流。一旦上游在首个 Chunk 发生 4xx/5xx 错误（如限流或认证失败），此时 HTTP 头已经发出，再也无法向客户端返回合法的 JSON 错误报文，导致下游 CLI 直接崩溃挂死。
* **正确做法**：采用异步生成器（`async function*`）在内存中 pull 出第一个业务 Chunk；**仅当首个 Chunk 成功获取后，才向客户端 flush 200 OK 响应头**；若首个包抛错，则直接返回标准 HTTP 4xx/5xx JSON。

### 4. 官方客户端防伪伪装
在 `src/constants.js` 中伪装了完整的 Antigravity 二进制特征：
```javascript
export const ANTIGRAVITY_HEADERS = {
    'User-Agent': 'Mozilla/5.0 ... Antigravity/1.110.0',
    'Content-Type': 'application/json',
    'X-Client-Name': 'antigravity',
    'X-Client-Version': '1.110.0',
    'x-goog-api-client': 'gl-node/18.18.2 fire/0.8.6 grpc/1.10.x'
};
```

### 5. 竞品特征中和脱敏机制（Identity Scrubbing）
在构建反向代理时，最隐蔽、最致命的一个坑点是**云厂商后端针对竞品 SDK 的指纹审查**。  
Claude Code 在向 API 发送请求时，会在 `system` 字段头部强制注入私有计费头和身份标识：
```text
x-anthropic-billing-header: cc_version=2.1.284.12a; cc_entrypoint=sdk-cli;
You are a Claude agent, built on Anthropic's Claude Agent SDK.
```
Google Cloud Code PA 内部设置了安全过滤规则：**只要检测到关键词 `"Anthropic"`，上游会直接返回一个伪装的 `HTTP 429 RESOURCE_EXHAUSTED`**（故意伪装成配额耗尽以阻断竞争对手）。

因此，代理在 `src/cloudcode/request-builder.js` 中必须实施自动化中和脱敏过滤：
```javascript
const DEFAULT_IDENTITY_SCRUB = [
    ['Nous Research', 'the assistant team'],
    ['Hermes Agent', 'the assistant'],
    ['Hermes', 'the assistant'],
    ['Anthropic', 'AssistantCorp'],
    ['anthropic', 'assistantcorp'],
    ['ANTHROPIC', 'ASSISTANTCORP']
];

function scrubClientIdentity(text) {
    if (typeof text !== 'string') return text;
    let out = text;
    for (const [term, replacement] of IDENTITY_SCRUB_RULES) {
        out = out.split(term).join(replacement);
    }
    out = out.replace(/Anthropic/gi, 'AssistantCorp');
    return out;
}
```

>  **关于该问题的深度逆向与排查推演**：  
> 当初在排查这个 Bug 时，曾一度以为是 37,000+ tokens 的上下文过大导致“爆额度”。我们通过单变量二分探针实验，逐层剥离 Tools、Messages、System，最终锁定是单个词汇 `"Anthropic"` 触发了 Google 云端黑名单，并修复了本地代理误判 429 导致锁定 30 分钟的死锁 Bug。  
> 完整排查全过程详见排查专文： **[《【逆向排查】深挖云端黑盒：Claude Code 接入 Google Cloud Code 伪装 429 RESOURCE_EXHAUSTED 竞品指纹过滤破案实录》](./kanxue_post_2_heavy_context_429.md)**。

---

## 0x05 快速部署与运维实操

### 1. 全局安装
```powershell
npm install -g antigravity-claude-proxy
```
安装完成后系统获得 `acc` 全局命令。

### 2. 启动与管理命令
```powershell
# 前台调试启动（可查看彩色请求日志与模型分发流）
acc start --log

# 后台静默常驻启动
acc start

# 查看服务运行状态、已绑定账号列表与健康度
acc status

# 停止服务
acc stop
```

### 3. 国内网络代理配置
由于 Google 上游端点在境外，启动前必须设置代理：
```powershell
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
acc start --log
```

### 4. Web 控制台与配额查询
启动后在浏览器打开：
* **Web 控制台**：`http://localhost:8080/`（一键点击 Add Account 即可自动调起 Google OAuth 授权绑定）
* **实时配额接口**：`http://localhost:8080/account-limits?includeHistory=true`（查看各模型真实剩余比例）

---

## 0x06 在 Claude Code / CC Switch 中的使用

在 CC Switch（或终端环境变量）中配置以下内容即可无缝使用：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:8080",
    "ANTHROPIC_AUTH_TOKEN": "test",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6-thinking",
    "ANTHROPIC_DEFAULT_OPUS_MODEL_NAME": "claude-opus-4-6-thinking",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gemini-3.8-flash-medium",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME": "gemini-3.8-flash-medium",
    "CLAUDE_CODE_SUBAGENT_MODEL": "gemini-3.8-flash-high"
  }
}
```

* **主模型（Sonnet）**：`claude-sonnet-4-6` —— 对应 Google 满血 Sonnet 4.6，响应在 3 秒左右。
* **思考模型（Opus）**：`claude-opus-4-6-thinking` —— 耗时 10~15 秒，提供超深度逻辑思维链。
* **子 Agent（Haiku）**：`gemini-3.8-flash-medium` —— 速度极快，适合轻量级任务。

---

## 0x07 延伸阅读与系列导航

*  **本系列故障排查专文**：  
  [《【逆向排查】深挖云端黑盒：Claude Code 接入 Google Cloud Code 伪装 429 RESOURCE_EXHAUSTED 竞品指纹过滤破案实录》](./kanxue_post_2_heavy_context_429.md)  
  *深入记录了面对首句报错 429 时，如何通过单变量脱机探针排除容量假设、如何抓包比对发现 Google 云端黑名单过滤，以及如何解开网关本地 30 分钟自锁死锁的技术复盘与 5 条长效经验法则。*

冰与火的战歌：Windows内核攻防实战高级班！从零到实战，融合AI与Windows内核攻防全技术栈，打造具备自动化能力的内核开发高手。