Aminetwiti/antigravity-patch-proxy
GitHub: Aminetwiti/antigravity-patch-proxy
该项目是一个本地反向代理补丁，旨在让 Google Antigravity IDE 原生接入 Claude、OpenAI、DeepSeek 等 19 种以上第三方或本地大语言模型。
Stars: 5 | Forks: 1
# Google Antigravity 自定义模型代理 — 将 Claude, OpenAI, DeepSeek 和 Ollama 添加到 Antigravity IDE
`)。
3. 自定义模型被动态追加到 `agentModelSorts` 和模型数组中，以便它们在 IDE 选择器中原生渲染，并启用所有功能标志。
### 请求生命周期与数据流
```
sequenceDiagram
autonumber
participant IDE as Antigravity IDE (UI)
participant LS as Language Server (Go Binary)
participant Proxy as Local Proxy (127.0.0.1:50999)
participant Registry as Translator Registry
participant Ext as External Provider API (OpenAI/Claude/Ollama)
IDE->>LS: User sends prompt with custom model selected
LS->>Proxy: POST /v1internal:streamGenerateContent?alt=sse
Proxy->>Proxy: Intercept request & detect model ID (MODEL_PLACEHOLDER_*)
Proxy->>Registry: Lookup provider translator (e.g. anthropic.ts)
Registry->>Proxy: Transformed payload (Anthropic / OpenAI format)
Proxy->>Ext: POST https://api.anthropic.com/v1/messages (SSE)
loop SSE Token Streaming
Ext-->>Proxy: data: {"type": "content_block_delta", ...}
Proxy->>Proxy: mapChunkToGemini() via jsonRepair
Proxy-->>LS: SSE data: {"response": {"candidates": [...]}}
LS-->>IDE: Render text chunk in chat UI
end
```
## 截图与 UI 集成
注入的 UI 与 Antigravity 类似 VS Code 的深色界面无缝融合：
| 自定义模型仪表板 | 添加模型弹窗 |
|---|---|
|  |  |
| 提供商选择 (Claude, OpenAI, DeepSeek, Ollama) | Antigravity 聊天 UI 中的模型选择器 |
|---|---|
|  |  |
| 自动回退与故障转移流通知 |
|---|
|  |
## 核心技术特性
### 自动模型回退与流警告卡片
当主要模型遇到速率限制 (`rate_limit` / 429)、上下文长度限制或提供商超时时，代理会自动启动 **Auto-Fallback**：
- **无缝故障转移**：自动使用次要模型重试提示（例如，从 `MiniMax-M2.7` 回退到 `MiniMax-M3`，或从 `Claude-3.5-Sonnet` 回退到 `GPT-4o`）。
- **原生流警告卡片**：将内联的 Markdown 警告块 (`> ⚠️ Auto-fallback: failed (). Retrying with …`) 直接发送到 IDE 聊天响应流中，而不会中断 agent 的工作流。
- **上下文保留**：在故障转移边界之间保留完整的对话历史和活动的工具定义。
### 格式转换器
代理在 `src/proxy/translators/` 下具有独立的转换器模块：
- **OpenAI 转换器 (`openai.ts`)**：在 Gemini `contents`/`parts` 和 OpenAI `messages` 之间进行完全映射，包括工具调用、系统提示和 `usage` token 指标。
- **Anthropic 转换器 (`anthropic.ts`)**：处理 Claude 的 `system` 参数、`tool_use` 块、SSE `content_block_start`/`delta` 事件以及 thinking 参数提取。
- **Google AI Studio 透传 (`google.ts`)**：通过自动模型路由直接透传到 Google AI Studio 密钥 (`https://generativelanguage.googleapis.com`)。
- **Ollama 转换器 (`ollama.ts`)**：兼容本地 Ollama、LM Studio 和 vLLM 服务器，无需 API 密钥。
### 双向 SSE 流式传输
- **无缓冲超时**：流式请求 (`streamGenerateContent`) 绕过响应缓冲并直接通过管道传输 SSE 块，以防止 Language Server 执行超时。
- **安全的 JSON 修复 (`jsonRepair.ts`)**：使用字符串级状态机 (`repairPartialJson()`) 解析并修复格式错误或截断的 SSE 块。**绝不使用 `eval()` 或 `new Function()`**。
### 工具调用与函数执行
- 将 Gemini 的 `functionDeclarations` 转换为 OpenAI 的 `tools` / Anthropic 的 `tool_use`。
- 使用 `src/proxy/shared.ts` 状态存储，在多轮对话中将执行响应 (`functionResponse`) 匹配回上游的 `tool_call_id` token。
### DeepSeek 与 Claude Thinking 支持
- 在 `modelUtils.ts` 中检测推理参数 (`reasoning_effort`, `thinking`)。
- 根据 IDE 的功能自动去除或显示推理块 (`... `)。
### 单模型断路器与弹性 (`circuitBreaker.ts`)
- **短路故障**：当上游提供商遇到持续错误或超时时自动跳闸。防止代理挂起并保持 IDE 模型选择下拉菜单的响应性。
- **自适应重试预算 (`retryBudget.ts`)**：根据观察到的历史可靠性动态调整每个提供商的重试次数。不稳定的模型会获得较少的重试次数以防止请求风暴，而稳定的模型则被授予重试次数。
### 自动流转回退路由
- **无缝提供商重定向**：如果主要的自定义模型返回 `429 Rate Limit` 或 `5xx Server Error`，代理会自动将提示重新路由到配置好的备用回退模型。
- **流内透明度**：在聊天流的顶部直接发送轻量级的 Markdown 通知块（例如 `> ⚠️ Auto-fallback: Claude 3.5 Sonnet failed (rate_limit). Retrying with DeepSeek R1...`）。
### 遥测、指标与配置交换
- **实时延迟指标 (`metrics.ts`)**：通过 `/metrics` 暴露延迟分布 (`proxy_upstream_ms`) 和错误计数器 (`proxy_errors_total`)。
- **配置导入/导出 (`configExchange.ts`)**：提供结构化的 JSON 导出和批量导入，方便在开发团队之间共享模型预设。
- **原生系统托盘集成 (`tray.ts`, `menu.ts`)**：嵌入式托盘菜单，提供快速的服务器状态、日志快捷方式和切换控制。
## 安全架构
### AES-256-GCM 加密 (`safeStorage`)
所有自定义模型配置都存储在 `%APPDATA%/antigravity/custom_models.json`（或操作系统的等效位置）中。
- **静态加密**：通过 Electron `safeStorage`（由 Windows DPAPI、macOS Keychain 或 Linux Secret Service 支持）使用 **AES-256-GCM** 对 API 密钥进行加密。
- **自动迁移**：首次运行时，将旧的明文密钥无缝升级为加密的 payload (`enc:gcm:...`) (`src/proxy/modelLoader.ts`)。
### 请求强化与 DoS 防护
- **请求体大小限制**：严格的 10 MB payload 限制，以防止缓冲区耗尽的 DoS 攻击 (`HTTP 413 Payload Too Large`)。
- **超时**：所有出站请求都有 30 秒到 120 秒的可配置超时，以防止连接挂起。
- **标头脱敏**：诊断日志输出中会清除 CSRF token 和 authorization 标头。
## 快速开始与安装
### Windows 设置
#### 一键脚本
双击或在终端中运行：
```
repatch.bat
```
#### npm 手动构建
```
npm run build
npm run repatch
```
### macOS 与 Linux 设置
```
# macOS (解压 /Applications/Antigravity.app、打补丁、重新打包 app.asar)
npm run repack:mac
# Linux (自动检测安装目录)
npm run repack:linux
```
### 企业级 MITM HTTPS 模式
如果您的网络需要使用自定义 SSL 证书拦截端口 443：
```
"Start Antigravity MITM.bat"
```
*(需要管理员权限)*
## `ag-doctor` 诊断 CLI
`ag-doctor` 是本仓库提供的内置诊断和维护工具。
### 命令参考
```
# 运行完整诊断套件 (Binary patch 状态、proxy 端口、config 完整性)
npm run doctor
# 快速健康检查
npm run doctor:check
# 自动修复 (应用 binary patch、修复损坏的 config、重置端口)
npm run doctor:repair
# 列出当前活动的自定义模型并测试 API 端点
npm run doctor:models
# 流式传输实时诊断日志
npm run doctor:logs
```
### CLI 架构与 Worker 模式
`ag-doctor` 运行在两种执行模式下 (`ag-doctor/bin/ag-doctor.js`)：
1. **CLI 模式**：用于终端环境检查、模型列出和自动修复的一次性执行。
2. **Worker 模式 (`--worker`)**：通过 `stdin`/`stdout` 生成进程内的 JSON-RPC 守护进程，消除了 IDE UI 查询时的进程生成开销。
### 可视化诊断仪表板 (`ag-doctor-ui`)
除了终端 CLI 外，本仓库还包含 **`ag-doctor-ui`**，这是一个专用的 Electron UI 渲染应用程序：
- **可视化健康监视器**：端口 `50999` 绑定、Language Server 二进制补丁和 SSL 证书有效性的实时状态指示器。
- **一键自动修复**：单按钮修复流程，用于解除端口卡死、恢复损坏的 `app.asar` 备份以及重新应用版本补丁。
- **实时日志检查器**：集成的日志追踪窗口，具有实时的严重性过滤器 (`INFO`, `WARN`, `ERROR`) 和自动的 API 密钥脱敏。
#### 流量检查器视图 (`traffic-inspector.ts`)
- **实时网络日志记录**：拦截并显示活动的 Cloud API 请求、HTTP 状态码、目标模型、翻译后的提供商以及端到端的延迟基准。
- **Payload 差异与重放**：为请求/响应 payload 生成可视化的差异视图 (`generateDiffView`)，并支持单击重放请求 (`replayEntry`)。
- **多字段过滤**：通过 URL 路径、模型名称、提供商或 HTTP 状态码即时过滤条目。
#### 故障场景展示 (`custom-error-scenarios.ts`, `failure-scenario-showcase.ts`)
- **可视化错误模拟**：交互式展示，预览所有提供商的错误场景（速率限制 429、计费/配额超限、身份验证错误 401/403、网络超时、SSL 绕过失败）。
- **原生 Antigravity 横幅渲染**：渲染完全复刻的原生 Antigravity 错误卡片，包含类别徽章、状态标签、解码后的故障排除提示以及主要/次要操作按钮 (`ag-btn-primary`, `ag-btn-dismiss`)。
- **交互式 QA 过滤标签**：通过场景类别 (`Rate Limit`, `Authentication`, `Network`, `Quota`) 过滤错误卡片，用于视觉调试和 QA 验证。
### 版本感知补丁引擎
- **多版本二进制补丁**：`ag-doctor` 会自动检测已安装的 Antigravity 版本（v2.0.x 到 v2.3.x），并执行二进制字符串替换，而不会破坏 Go 可执行文件的对齐方式。
- **备份与回滚安全**：在修改二进制 payload 之前，会创建带时间戳的 `app.asar` `.bak` 副本，允许通过 1 条命令即时回滚 (`npm run doctor:repair`)。
## 提供商配置矩阵
| 提供商 | 预设 Slug | 目标 Base URL | 需要 Key | 流式传输 | 工具调用 |
|---|---|---|---|---|---|
| **OpenAI** | `openai` | `https://api.openai.com/v1` | 是 | 是 | 是 |
| **Anthropic** | `anthropic` | `https://api.anthropic.com/v1` | 是 | 是 | 是 |
| **OpenRouter** | `openrouter` | `https://openrouter.ai/api/v1` | 是 | 是 | 是 |
| **Google AI Studio** | `google` | `https://generativelanguage.googleapis.com` | 是 | 是 | 是 |
| **Ollama** | `ollama` | `http://localhost:11434` | 否 | 是 | 是 |
| **DeepSeek** | `openai` | `https://api.deepseek.com/v1` | 是 | 是 | 是 |
| **Groq** | `openai` | `https://api.groq.com/openai/v1` | 是 | 是 | 是 |
| **Mistral AI** | `openai` | `https://api.mistral.ai/v1` | 是 | 是 | 是 |
| **Together API** | `openai` | `https://api.together.xyz/v1` | 是 | 是 | 是 |
| **LM Studio** | `openai` | `http://localhost:1234/v1` | 否 | 是 | 是 |
| **vLLM / LocalAI** | `openai` | 自定义 Endpoint | 可选 | 是 | 是 |
## `custom_models.json` Schema 参考
配置保存在 `%APPDATA%/antigravity/custom_models.json` 下：
```
[
{
"id": "custom-claude-3-5-sonnet",
"name": "Claude 3.5 Sonnet",
"provider": "anthropic",
"model": "claude-3-5-sonnet-20241022",
"apiKey": "enc:gcm:...",
"baseUrl": "https://api.anthropic.com/v1",
"parameters": {
"temperature": 0.7,
"topP": 0.9,
"maxTokens": 4096,
"customSystemPrompt": "Focus on high-performance clean code."
},
"retry": {
"maxRetries": 3,
"timeoutMs": 60000
}
}
]
```
## 开发者指南
### 代码库结构
```
├── ag-doctor/ # Diagnostic CLI suite & worker daemon
├── scripts/ # Repack, deploy, and MITM launcher scripts
├── src/
│ ├── constants.ts # Central source of truth (Providers, default ports, timeouts)
│ ├── cryptoStore.ts # AES-256-GCM encryption wrapper
│ ├── main.ts # Electron main process interceptors
│ ├── preload.ts # Injected Custom Models Settings UI
│ ├── ipcHandlers.ts # IPC storage & connection test handlers
│ ├── proxy/
│ │ ├── proxy.ts # Core HTTP proxy server orchestration
│ │ ├── registry.ts # Translator auto-discovery registry
│ │ ├── protoInjector.ts # Protobuf payload injection
│ │ ├── jsonRepair.ts # Safe non-eval SSE JSON repair
│ │ ├── retryStrategy.ts # Exponential backoff retry logic
│ │ └── translators/ # OpenAI, Anthropic, Google, Ollama translators
│ └── __tests__/ # 1455 unit tests (Vitest)
```
### 构建与监听模式
```
# 编译 TypeScript 文件 (src/ -> dist/)
npm run build
# 用于迭代代码更改的 Watch mode
npm run watch
```
### 运行测试
测试套件通过 **Vitest** 运行：
```
# 运行全部 1455 个单元测试
npm test
# 在 Watch mode 下运行测试
npm run test:watch
```
### 添加新的转换器模块
要添加对新的 LLM 提供商格式的支持：
1. 创建 `src/proxy/translators/.ts`。
2. 实现并导出：
export function mapGeminiTo(body: any, modelName: string): any;
export function mapToGemini(res: any, modelName: string): any;
export function mapChunkToGemini(chunk: any, modelName: string): any;
3. 将提供商定义添加到 [src/constants.ts](src/constants.ts) 中的 `PROVIDERS`。
## 故障排除与诊断
| 症状 | 原因 | 解决方案 |
|---|---|---|
| 聊天下拉菜单中缺少模型 | IDE 更新覆盖了 `app.asar` | 运行 `npm run doctor:repair` 或 `repatch.bat` |
| 连接测试失败 (401/403) | API Key 无效或过期 | 在设置中检查密钥或运行 `npm run doctor:models` |
| 端口 50999 被占用 | 另一个代理实例处于活动状态 | `ag-doctor` 自动选择回退端口 |
| 日志中出现 `ERR_HTTP_HEADERS_SENT` | 上游响应竞态条件 | 由 `safeWriteHead` 助手自动处理 |
| SSL / 证书错误 | 公司代理 SSL 拦截 | 通过 `"Start Antigravity MITM.bat"` 启用 MITM 模式 |
完整的故障排除指南详见 [TROUBLESHOOTING.md](TROUBLESHOOTING.md)。
## 常见问题解答 (FAQ)
### 如何将 Anthropic Claude 3.5 Sonnet 或 DeepSeek R1 添加到 Google Antigravity IDE？
您可以通过在 Google Antigravity IDE 中打开自定义模型设置弹窗，输入您的 API 密钥和提供商 Base URL，并运行自动补丁程序（Windows 上的 `repatch.bat` 或 macOS 上的 `npm run repack:mac`），来添加 Claude 3.5 Sonnet、DeepSeek R1、OpenAI GPT-4o 或任何自定义的 LLM 模型。
### 我的提供商 API 密钥安全吗？
是的。所有自定义模型配置和 API 密钥都存储在本地，并通过 Electron `safeStorage`（由 Windows DPAPI、macOS Keychain 或 Linux Secret Service 支持）使用 **AES-256-GCM** 进行静态加密。密钥永远不会发送到第三方跟踪服务器。
### 我可以在 Google Antigravity 中运行带有 Ollama 或 LM Studio 的本地 LLM 吗？
是的。将提供商设置为 `ollama` 或 `openai`，并将端点设置为 `http://localhost:11434` (Ollama) 或 `http://localhost:1234/v1` (LM Studio)。离线本地推理无需 API 密钥。
### 自动回退和故障转移如何工作？
如果主要的自定义模型返回 `429 Rate Limit`、配额超限或超时，代理会自动使用您配置的次要回退模型重试提示，并在聊天流中呈现原生的警告横幅，而不会破坏对话历史。
## GitHub 搜索与主题元数据
为了在 GitHub 搜索和 Google SERP 上获得最大的仓库可见性，请确保在 **GitHub Repository Settings > About** 下分配了以下仓库主题：
`google-antigravity` • `antigravity-ide` • `custom-models` • `claude-3-5-sonnet` • `deepseek-r1` • `openai-gpt4o` • `ollama` • `openrouter` • `llm-proxy` • `cloudcode-patch`
## 许可证与致谢
- **许可证**：在 **Apache-2.0 License** 下分发。详情请参阅 [LICENSE](LICENSE)。
- **原始仓库与致谢**：特别感谢 **Abdulvahap OGUT** 提供的原始项目仓库：[vahapogut/antigravity-add-model](https://github.com/vahapogut/antigravity-add-model)。
标签：AI编程助手, API网关, Homebrew安装, MITM代理, SOC Prime, SSE流式传输, StruQ, TypeScript, 云资产清单, 大语言模型代理, 安全插件, 开发工具, 自动化攻击, 逆向工程