Antigravity-Manager Documentation

Technical Documentation: lbjlaq/Antigravity-Manager

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Antigravity Tools 🚀

Professional Account Management & Protocol Proxy System for AI Services (v4.9.8)

Antigravity Tools is an all-in-one desktop application designed for developers and AI enthusiasts. It perfectly combines multi-account management, protocol conversion, and smart request scheduling to provide you with a stable, high-speed, and low-cost Local AI Relay Station.

By leveraging this app, you can transform common Web Sessions (Google/Anthropic) into standardized API interfaces, completely eliminating the protocol gap between different providers.

💖 Sponsors Copy Chapter

☕ Support Copy Section

If you find this project helpful, feel free to buy me a coffee!

🚀 Recommended Projects Copy Chapter

If you like this project, you might also be interested in:

• Antigravity-Tools-LS: A Language Server Protocol (LSP) designed for AI protocols, providing you with smarter code completion, diagnostics, and protocol debugging experiences.

🌟 Detailed Feature Matrix Copy Chapter

1. 🎛️ Smart Account Dashboard Copy Section

• Global Real-time Monitoring: Instant insight into the health of all accounts, including average remaining quotas for Gemini Pro, Gemini Flash, Claude, and Gemini Image generation.
• Smart Recommendation: The system uses a real-time algorithm to filter and recommend the "Best Account" based on quota redundancy, supporting one-click switching.
• Active Account Snapshot: Visually displays the specific quota percentage and the last synchronization time of the currently active account.

2. 🔐 Powerful Account Management Copy Section

• OAuth 2.0 Authorization (Auto/Manual): Pre-generates a copyable authorization URL so you can finish auth in any browser; after the callback, the app auto-completes and saves the account (use “I already authorized, continue” if needed).
• Multi-dimensional Import: Supports single token entry, JSON batch import, and automatic hot migration from V1 legacy databases.
• Gateway-level Views: Supports switching between "List" and "Grid" views. Provides 403 Forbidden detection, automatically marking and skipping accounts with permission anomalies.

3. 🔌 Protocol Conversion & Relay (API Proxy) Copy Section

• Multi-Protocol Adaptation (Multi-Sink):
  • OpenAI Format: Provides /v1/chat/completions endpoint, compatible with 99% of existing AI apps.
  • Anthropic Format: Provides native /v1/messages interface, supporting all features of Claude Code CLI (e.g., chain-of-thought, system prompts).
  • Gemini Format: Supports direct calls from official Google AI SDKs.
• Smart Self-healing: When a request encounters 429 (Too Many Requests) or 401 (Expired), the backend triggers millisecond-level automatic retry and silent rotation, ensuring business continuity.

4. 🔀 Model Router Center Copy Section

• Series-based Mapping: Classify complex original model IDs into "Series Groups" (e.g., routing all GPT-4 requests uniformly to gemini-3-pro-high).
• Expert Redirection: Supports custom regex-level model mapping for precise control over every request's landing model.
• Tiered Routing [New]: Automatically prioritizes models based on account tiers (Ultra/Pro/Free) and reset frequencies to ensure stability for high-volume users.
• Silent Background Downgrading [New]: Intelligently identifies background tasks (e.g., Claude CLI title generation) and reroutes them to Flash models to preserve premium quota.

5. 🎨 Multimodal & Imagen 3 Support Copy Section

• Advanced Image Control: Supports precise control over image generation tasks via OpenAI size (e.g., 1024x1024, 16:9) parameters or model name suffixes.
• Enhanced Payload Support: The backend supports payloads up to 100MB (configurable), more than enough for 4K HD image recognition and processing.

📸 GUI Overview Copy Chapter

💡 Usage Examples Copy Section

🏗️ Architecture Copy Chapter

graph TD
    Client([External Apps: Claude Code/NextChat]) -->|OpenAI/Anthropic| Gateway[Antigravity Axum Server]
    Gateway --> Middleware[Middleware: Auth/Rate Limit/Logs]
    Middleware --> Router[Model Router: ID Mapping]
    Router --> Dispatcher[Dispatcher: Rotation/Weights]
    Dispatcher --> Mapper[Request Mapper]
    Mapper --> Upstream[Upstream: Google/Anthropic API]
    Upstream --> ResponseMapper[Response Mapper]
    ResponseMapper --> Client

📥 Installation Copy Chapter

Option A: Terminal Installation (Recommended) Copy Section

Cross-Platform One-Line Install Scripts

Automatically detects your OS, architecture, and package manager — one command to download and install.

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/lbjlaq/Antigravity-Manager/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/lbjlaq/Antigravity-Manager/main/install.ps1 | iex

Supported formats: Linux (.deb / .rpm / .AppImage) | macOS (.dmg) | Windows (NSIS .exe)

Advanced usage: Install a specific version curl -fsSL https://raw.githubusercontent.com/lbjlaq/Antigravity-Manager/main/install.sh | bash -s -- --version 4.6.8, dry-run mode curl -fsSL https://raw.githubusercontent.com/lbjlaq/Antigravity-Manager/main/install.sh | bash -s -- --dry-run

macOS - Homebrew

If you have Homebrew installed, you can also install via:

# 1. Tap the repository
brew tap lbjlaq/antigravity-manager https://github.com/lbjlaq/Antigravity-Manager

# 2. Install the app
brew install --cask antigravity-tools

Arch Linux

You can choose to install via the one-click script or Homebrew:

Option 1: One-click script (Recommended)

curl -sSL https://raw.githubusercontent.com/lbjlaq/Antigravity-Manager/main/deploy/arch/install.sh | bash

Option 2: via Homebrew (If you have Linuxbrew installed)

brew tap lbjlaq/antigravity-manager https://github.com/lbjlaq/Antigravity-Manager
brew install --cask antigravity-tools

Other Linux Distributions

The AppImage will be automatically symlinked to your binary path with executable permissions.

Option B: Manual Download Copy Section

Download from GitHub Releases:

• macOS: .dmg (Universal, Apple Silicon & Intel)
• Windows: .msi or portable .zip
• Linux: .deb or AppImage

Option C: Docker Deployment (Recommended for NAS/Servers) Copy Section

If you prefer running in a containerized environment, we provide a native Docker image. This image supports the v4.0.3 Native Headless architecture, automatically hosts frontend static resources, and allows for direct browser-based management.

Option 1: Direct Run (Recommended)

• API_KEY: Required. Used for AI request authentication.
• WEB_PASSWORD: Optional. Used for Web UI login. Defaults to API_KEY if NOT set.

docker run -d --name antigravity-manager \
  -p 8045:8045 \
  -e API_KEY=sk-your-api-key \
  -e WEB_PASSWORD=your-login-password \
  -e ABV_MAX_BODY_SIZE=104857600 \
  -v ~/.antigravity_tools:/root/.antigravity_tools \
  lbjlaq/antigravity-manager:latest

# Forgot keys? Run `docker logs antigravity-manager` or `grep -E '"api_key"|"admin_password"' ~/.antigravity_tools/gui_config.json`

[!TIP]
🧪 Pulling Beta / Preview Images:
To test the latest Beta pre-release features, specify the corresponding Beta version tag (pre-releases are published independently and will never overwrite the latest stable tag):

bash Copy

# Pull a specific Beta pre-release version (check Docker Hub for all tags)
docker pull lbjlaq/antigravity-manager:v4.8.2-beta.0

# Run Beta container
docker run -d --name antigravity-manager-beta \
  -p 8045:8045 \
  -e API_KEY=sk-your-api-key \
  -e WEB_PASSWORD=your-login-password \
  -e ABV_MAX_BODY_SIZE=104857600 \
  -v ~/.antigravity_tools:/root/.antigravity_tools \
  lbjlaq/antigravity-manager:v4.8.2-beta.0

View all published Beta tags on Docker Hub Tags. If you wish to run the unreleased bleeding-edge beta branch directly, build locally: docker build -t lbjlaq/antigravity-manager:beta -f docker/Dockerfile ..

🔐 Authentication Scenarios

• Scenario A: Only API_KEY is set
  • Web Login: Use API_KEY to access the dashboard.
  • API Calls: Use API_KEY for AI request authentication.
• Scenario B: Both API_KEY and WEB_PASSWORD are set (Recommended)
  • Web Login: Must use WEB_PASSWORD. Using API Key will be rejected (more secure).
  • API Calls: Continue to use API_KEY. This allows you to share the API Key with team members while keeping the password for administrative access only.

🆙 Upgrade Guide for Older Versions

If you are upgrading from v4.0.1 or earlier, your installation won't have a WEB_PASSWORD set by default. You can add one using any of these methods:

1. Web UI (Recommended): Log in using your existing API_KEY, go to the API Proxy Settings page, find the Web UI Management Password section below the API Key, set your new password, and save.
2. Environment Variable (Docker): Stop the old container and start the new one with the added parameter -e WEB_PASSWORD=your_new_password. Note: Environment variables have the highest priority and will override any changes in the UI.
3. Config File (Persistent): Directly edit ~/.antigravity_tools/gui_config.json and add/modify "admin_password": "your_new_password" inside the proxy object.
   • Note: WEB_PASSWORD is the environment variable name, while admin_password is the JSON key in the config file.

[!TIP]
Priority Logic:

• Environment Variable (WEB_PASSWORD) has the highest priority. If set, the application will always use it and ignore values in the configuration file.
• Configuration File (gui_config.json) is used for persistent storage. When you change the password via Web UI and save, it is written here.
• Fallback: If neither is set, it falls back to API_KEY; if even API_KEY is missing, a random one is generated.

Option 2: Use Docker Compose

1. Enter the docker directory and start the service:

cd docker
docker compose up -d

Log rotation: Compose limits JSON logs to 100m per file and keeps 3 files by default to prevent unbounded growth.
Access URL: http://localhost:8045 (Admin Console) | http://localhost:8045/v1 (API Base)
System Requirements:

• RAM: 1GB recommended (minimum 256MB).
• Persistence: Mount /root/.antigravity_tools to persist your data.
• Architecture: Supports x86_64 and ARM64.
  See: Docker Deployment Guide (docker)

🛠️ Troubleshooting - Click to expand

macOS says "App is damaged"?

Due to macOS security gatekeeper, non-App Store apps might show this. You can fix it with:

1. Terminal Command (Recommended):
   bash Copy

   sudo xattr -rd com.apple.quarantine "/Applications/Antigravity Tools.app"

2. Homebrew Installation Advantage:
   When installing via Homebrew (brew install --cask antigravity-tools), quarantine attributes are automatically cleared upon installation for an out-of-the-box experience.

Linux window is black or empty?

On niri, Hyprland, Sway, and similar compositors, older builds forced GDK_BACKEND=x11 whenever DISPLAY was set, and WebKit then drew a black window. Update to a build that includes this fix, or launch once with:

env WEBKIT_DISABLE_DMABUF_RENDERER=1 ANTIGRAVITY_FORCE_WAYLAND=1 antigravity-tools

• ANTIGRAVITY_FORCE_WAYLAND=1: keep native Wayland (do not force X11)
• ANTIGRAVITY_FORCE_X11=1: force X11 if you still need it
• WEBKIT_DISABLE_DMABUF_RENDERER=1: disable the WebKit DMA-BUF renderer

🔌 Quick Integration Examples Copy Chapter

🔐 OAuth Authorization Flow (Add Account) Copy Section

1. Go to Accounts → Add Account → OAuth.
2. The dialog pre-generates an authorization URL before you click any button. Click the URL to copy it to the system clipboard, then open it in the browser you prefer and complete authorization.
3. After consent, the browser opens a local callback page and shows “✅ Authorized successfully!”.
4. The app automatically continues the flow and saves the account; if it doesn’t, click “I already authorized, continue” to finish manually.

Note: the auth URL contains a one-time local callback port. Always use the latest URL shown in the dialog. If the app isn’t running or the dialog is closed during auth, the browser may show localhost refused connection.

How to use with JeikCode? (Recommended) Copy Section

JeikCode is a modern terminal AI Coding Agent crafted by the core maintainer of this project, featuring native deep integration with Antigravity-Manager, delivering 95%+ KV-Cache hit rate and seamless reasoning level control.

1. One-Click Sync via GUI (Recommended):
   • Launch Antigravity-Manager and ensure the API Proxy service is running.
   • Switch to the >_ Agent Tools One-Click Configuration tab.
   • Locate the JeikCode card, choose your desired default model (e.g. gemini-3.8-flash-high), and click 🔄 Sync Now.
   • Simply run jeikcode in your terminal for the TUI, and type /webui to instantly launch the modern WebUI in your browser for a richer visual coding experience out of the box!
2. Temporary Environment Variables:

export ANTHROPIC_BASE_URL="http://127.0.0.1:8045"
export ANTHROPIC_API_KEY="sk-antigravity"
jeikcode --model claude-sonnet-4-6

For complete manual configuration and tuning, see the JeikCode Integration Guide.

How to use with Claude Code CLI? Copy Section

Recommended Client Versions:

• Stable Production Recommendation: Claude Code v2.1.28x (more permissive stream termination verification, highest resilience under network jitter);
• Latest Versions Support: Claude Code v2.1.293 ~ v2.1.295 (requires deploying the gateway version with stream hang prevention and keepalive optimizations, see Diagnosis Guide).

Install recommended stable version: npm install @anthropic-ai/[email protected]

1. Start Antigravity service in the "API Proxy" tab.
2. In your terminal:

export ANTHROPIC_API_KEY="sk-antigravity"
export ANTHROPIC_BASE_URL="http://127.0.0.1:8045"
claude

How to use with OpenCode? Copy Section

1. Go to API Proxy → External Providers → click the OpenCode Sync card.
2. Click Sync to generate ~/.config/opencode/opencode.json:
   • Creates a dedicated provider antigravity-manager (does not overwrite google/anthropic providers)
   • Optional: Check Sync accounts to export antigravity-accounts.json (plugin-compatible v3 format) for the OpenCode plugin
3. Click Clear Config to remove Manager configuration and clean up legacy entries; click Restore to revert from backup.
4. On Windows, the path is C:\Users\\.config\opencode\ (same ~/.config/opencode rule).

Quick verification commands:

# Test antigravity-manager provider (supports --variant)
opencode run "test" --model antigravity-manager/claude-sonnet-4-5-thinking --variant high

# If opencode-antigravity-auth is installed, verify google provider still works independently
opencode run "test" --model google/antigravity-claude-sonnet-4-5-thinking --variant max

How to use in Python? Copy Section

import openai

client = openai.OpenAI(
    api_key="sk-antigravity",
    base_url="http://127.0.0.1:8045/v1"
)

response = client.chat.completions.create(
    model="gemini-3-flash",
    messages=[{"role": "user", "content": "Hello, please introduce yourself"}]
)
print(response.choices[0].message.content)

How to use with Kilo Code? Copy Section

1. Protocol Selection: We recommend using the Gemini protocol.
2. Base URL: Set it to http://127.0.0.1:8045.
3. Note:
   • OpenAI Protocol Limitation: When using OpenAI mode, Kilo Code's request path will append /v1/chat/completions/responses, a non-standard path that will return 404 from Antigravity. Make sure to enter the Base URL and select Gemini mode.
   • Model Mapping: Model names in Kilo Code may differ from Antigravity's defaults. If you encounter connection issues, set up custom mappings on the "Model Mapping" page and check the log files for debugging.

How to use Image Generation (Imagen 3)? Copy Section

Method 1: OpenAI Images API (Recommended)

import openai

client = openai.OpenAI(
    api_key="sk-antigravity",
    base_url="http://127.0.0.1:8045/v1"
)

# Generate image
response = client.images.generate(
    model="gemini-3-pro-image",
    prompt="A futuristic cyberpunk city with neon lights",
    size="1920x1080",      # Supports any WIDTHxHEIGHT format, auto-calculates aspect ratio
    quality="hd",          # "standard" | "hd" | "medium"
    n=1,
    response_format="b64_json"
)

# Save image
import base64
image_data = base64.b64decode(response.data[0].b64_json)
with open("output.png", "wb") as f:
    f.write(image_data)

Supported parameters：

• size: Any WIDTHxHEIGHT format (e.g. 1280x720, 1024x1024, 1920x1080), auto-calculates and maps to standard aspect ratios (21:9, 16:9, 9:16, 4:3, 3:4, 1:1)
• quality:
  • "hd" → 4K resolution (high quality)
  • "medium" → 2K resolution (medium quality)
  • "standard" → Default resolution (standard quality)
• n: Number of images to generate (1-10)
• response_format: "b64_json" or "url" (Data URI)

🎨 Expand to view more image generation methods & parameter mapping rules (Chat API / Model Suffix / Cherry Studio)

Method 2: Chat API + Parameters (✨ New)

All protocols (OpenAI, Claude) Chat APIs now support direct size and quality parameters:

# OpenAI Chat API
response = client.chat.completions.create(
    model="gemini-3-pro-image",
    size="1920x1080",      # ✅ Supports any WIDTHxHEIGHT format
    quality="hd",          # ✅ "standard" | "hd" | "medium"
    messages=[{"role": "user", "content": "A futuristic city"}]
)

# Claude Messages API
curl -X POST http://127.0.0.1:8045/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-antigravity" \
  -d '{
    "model": "gemini-3-pro-image",
    "size": "1280x720",
    "quality": "hd",
    "messages": [{"role": "user", "content": "A cute cat"}]
  }'

Parameter priority: imageSize parameter > quality parameter > model suffix

✨ New imageSize parameter support:

In addition to the quality parameter, you can now also use Gemini's native imageSize parameter:

# Using imageSize parameter (highest priority)
response = client.chat.completions.create(
    model="gemini-3-pro-image",
    size="16:9",           # Aspect ratio
    imageSize="4K",        # ✨ Direct resolution: "1K" | "2K" | "4K"
    messages=[{"role": "user", "content": "A futuristic city"}]
)

# Claude Messages API also supports imageSize
curl -X POST http://127.0.0.1:8045/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-antigravity" \
  -d '{
    "model": "gemini-3-pro-image",
    "size": "1280x720",
    "imageSize": "4K",
    "messages": [{"role": "user", "content": "A cute cat"}]
  }'

Parameter descriptions:

• imageSize: Direct resolution specification ("1K" / "2K" / "4K")
• quality: Infers resolution from quality level ("standard" → 1K, "medium" → 2K, "hd" → 4K)
• Priority: If both imageSize and quality are specified, the system prioritizes imageSize

Method 3: Chat API + Model Suffix

response = client.chat.completions.create(
    model="gemini-3-pro-image-16-9-4k",  # Format: gemini-3-pro-image-[ratio]-[quality]
    messages=[{"role": "user", "content": "A futuristic city"}]
)

Model suffix explanation：

• Aspect ratio: -16-9, -9-16, -4-3, -3-4, -21-9, -1-1
• Quality: -4k (4K), -2k (2K), no suffix (standard)
• Example: gemini-3-pro-image-16-9-4k → 16:9 ratio + 4K resolution

Method 4: Cherry Studio & Other Client Settings

In clients that support OpenAI protocol (e.g., Cherry Studio), you can configure image generation parameters via the Model Settings page:

1. Enter Model Settings: Select the gemini-3-pro-image model
2. Configure Parameters:
   • Size: Enter any WIDTHxHEIGHT format (e.g. 1920x1080, 1024x1024)
   • Quality: Choose standard / hd / medium
   • Number: Set the number of images (1-10)
3. Send Request: Simply type your image description in the chat dialog

Parameter mapping rules:

• size: "1920x1080" → Auto-calculated as 16:9 aspect ratio
• quality: "hd" → Mapped to 4K resolution
• quality: "medium" → Mapped to 2K resolution

📝 Changelog Copy Chapter

Latest version v4.9.8 (2026-10-17): Automatic seamless hot-switch for Antigravity Classic upon quota depletion or threshold breach with streamlined dual-pool cards (Ref #3509); native evolution supporting Antigravity CLI (agy) with automatic shell wrapper injection, thinking effort disassembly, and independent 3-client active account detection with contextual badges (Ref #3686, Ref #3630); comprehensive 403 error body capture and action URL extraction (captcha verification/appeal) with closed-loop self-healing recovery (Ref #3630, Ref #3684); Claude Code 2.1.301 protocol alignment with anti-WAF identity sanitization, full-link request-id injection, and Claude 5 model family integration (PR #3689, Ref #3684, Ref #3686); active reference tracking in JSON Schema recursive flattening to eliminate exponential replication and Linux VPS OOM (SIGKILL 137) crashes, array schema normalization with terminal ARRAY items guards to prevent Gemini 400 errors, adaptive first-chunk Peek timeout extension to 60s/90s/120s for reasoning models, zero-downtime atomic pool reload eliminating 503 errors, and anti-regression rate limit protection (PR #3694, Fixes #3690, Ref #3682, Ref #3693); complete removal of 100% 429-yielding Prod endpoints, relaxed streaming first-chunk watchdog to 120s baseline, multi-turn role preservation for Responses array inputs, and elimination of 0ms optimistic reset storms (PR #3691, PR #3672, PR #3687, PR #3685, Fixes #3506, Ref #3525); traffic monitor inspector overhaul with Postman-style single-tab view, structured vs raw code views, key-value headers tables with Bearer masking, standard dual-link HAR 1.2 export, and 12-language localization coverage (thanks to @cubelikeplayDaniel, @EricZhou05, @blackdm666, @jeikl).

👉 View Full Changelog → CHANGELOG_EN.md

👥 Contributors - Click to expand

Special thanks to all developers who have contributed to this project.

🤝 Special Thanks - Click to expand

This project has referenced or learned from the ideas or code of the following excellent open-source projects during its development (in no particular order):

• learn-claude-code

• Practical-Guide-to-Context-Engineering

• CLIProxyAPI

• OmniRoute

• antigravity-claude-proxy

• aistudio-gemini-proxy

• gcli2api

• agent-vibes

• License: CC BY-NC-SA 4.0. Strictly for non-commercial use.

• Security: All account data is encrypted and stored locally in a SQLite database. Data never leaves your device unless sync is enabled.

Overview (`docker/README.md`) Copy Section

🐋 Antigravity Manager 原生 Docker 部署手冊

本目錄包含 Antigravity Manager 的原生 Headless Docker 部署方案。該方案支持完整的 Web 管理界面、API 反代以及數據持久化，無需複雜的 VNC 或桌面環境。

🆕 本版本部署方案（本地前端構建復用） Copy Chapter

適用於「前端近期不改、後端經常調整」的場景。思路是先在本地生成 dist/，Docker 只編譯後端並直接拷貝 dist/，大幅縮短構建時間並降低前端構建風險。

步驟

1. 本地生成前端靜態資源：

npm ci --legacy-peer-deps
npm run build

2. 使用本方案構建與啟動（後端-only + 復用 dist/）：

docker compose -f docker/docker-compose.yml -f docker/docker-compose.localdist.yml build
docker compose -f docker/docker-compose.yml -f docker/docker-compose.localdist.yml up -d

或合併為單條命令：

docker compose -f docker/docker-compose.yml -f docker/docker-compose.localdist.yml up -d --build

啟動後動態查看日誌：

docker compose -f docker/docker-compose.yml -f docker/docker-compose.localdist.yml logs -f --tail=200

更新方式

• 後端有改動：重跑上面的 build + up -d
• 前端有改動：先在本地重新 npm run build，再重跑 build + up -d

Git 部署提醒

• 若服務器不在本地構建前端，請確保 dist/ 已提交到倉庫（本版本已從 .gitignore 移除）。

🚀 快速開始 Copy Chapter

1. 直接拉取鏡像 (推薦) Copy Section

您可以直接從 Docker Hub 拉取已構建好的鏡像並啟动，無需獲取源碼：

[!IMPORTANT]
安全警告：從 v4.0.3 開始，Docker 版支持 管理密碼與 API Key 分離：

• API Key：通過 -e API_KEY=xxx 設置，用於所有 AI 協議的 API 調用鑒權。
• Web 管理密碼：通過 -e WEB_PASSWORD=xxx 設置，僅用於 Web UI 登錄。
• 默認行為：若未設置 WEB_PASSWORD，系統會自動回退使用 API_KEY 作為登錄密碼。若兩者皆未設置，則生成隨機 Key。
• 查看方式：執行 docker logs antigravity-manager 尋找 Current API Key 或 Web UI Password，或執行 grep -E '"api_key"|"admin_password"' ~/.antigravity_tools/gui_config.json 查看。

# 啟動容器 (請替换 your-secret-key 為強密鑰)
docker run -d \
  --name antigravity-manager \
  -p 8045:8045 \
  -e API_KEY=your-api-key \
  -e WEB_PASSWORD=your-login-password \
  -e ABV_MAX_BODY_SIZE=104857600 \
  -v ~/.antigravity_tools:/root/.antigravity_tools \
  lbjlaq/antigravity-manager:latest

[!TIP]
🧪 體驗 Beta / 預覽版鏡像：
若需使用最新的 Beta 預發布特性，請拉取對應的 Beta 版本 Tag（預發布版本獨立構建發布，不會覆蓋 latest 穩定版標籤）：

bash Copy

# 拉取指定 Beta 預發布版本
docker pull lbjlaq/antigravity-manager:v4.8.2-beta.0

# 運行 Beta 容器
docker run -d --name antigravity-manager-beta \
  -p 8045:8045 \
  -e API_KEY=your-api-key \
  -e WEB_PASSWORD=your-login-password \
  -e ABV_MAX_BODY_SIZE=104857600 \
  -v ~/.antigravity_tools:/root/.antigravity_tools \
  lbjlaq/antigravity-manager:v4.8.2-beta.0

完整版本標籤請查看 Docker Hub Tags。若需直接運行未發版 Tag 的當前最新 beta 分支源碼，可在本地構建：docker build -t lbjlaq/antigravity-manager:beta -f docker/Dockerfile .。

🔐 鑒權邏輯 (Security Scenarios)

• 場景 A：僅設置了 API_KEY
  • Web 登錄：使用 API_KEY 即可進入後台。
  • API 調用：使用 API_KEY 進行 AI 請求鑒權。
• 場景 B：同時設置了 API_KEY 和 WEB_PASSWORD (推薦)
  • Web 登錄：必須使用 WEB_PASSWORD。此時輸入 API Key 將被拒絕，確保管理權限與調用權限隔離。
  • API 調用：繼續使用 API_KEY。您可以放心地將 API Key 分發給團隊成員，而保留密碼僅供管理員使用。

🆙 舊版本升級指引

如果您是從舊版本升級，默認沒有設置 WEB_PASSWORD。您可以通過以下方式添加：

1. Web UI (推薦)：使用原有的 API_KEY 登錄，在 API 反代 設置頁面中設置新的管理密碼。
2. 環境變量：停止舊容器，啟動新容器時增加 -e WEB_PASSWORD=您的新密碼。

[!TIP]
優先級邏輯 (Priority):

• 環境變量 (ABV_WEB_PASSWORD / WEB_PASSWORD) 具有最高優先級。如果設置了環境變量，程序將始終使用它，忽略配置文件中的值。
• 配置文件 (gui_config.json) 用於持久化存儲。當您通過 Web UI 修改密碼並保存時，新密碼會寫入此文件（JSON 字段名為 admin_password）。
• 回退機制: 如果上述兩者皆未設置，則回退使用 API_KEY；若連 API_KEY 也未設置，則隨機生成。

2. 使用 Docker Compose Copy Section

在 docker 目錄下執行：

docker compose up -d

3. 手動構建鏡像 (開發者 / 二改版) Copy Section

如果您需要修改代碼或自定義構建，請在項目根目錄下執行：

Windows PowerShell（推薦）

# 一鍵構建二改版鏡像（標籤 antigravity-manager:local + 版本-fix）
.\docker\build.ps1

# 国内網絡加速
.\docker\build.ps1 -UseMirror

# 構建並推送到你自己的倉庫
.\docker\build.ps1 -UseMirror -Push -Registry "yourname/antigravity-manager"

手動 docker build

# 默認構建最新標籤
docker build -t antigravity-manager:local -f docker/Dockerfile .

# 二改版 Compose 啟動（Windows 可用端口映射，不用 host 網絡）
docker compose -f docker/docker-compose.yml -f docker/docker-compose.fork.yml up -d --build

💡 構建參數

本鏡像支持自動鏡像源切換，以提升国内構建速度：

• USE_MIRROR:
  • auto (默認): 自動檢測網絡環境，若無法訪問 Google 則切換至国内镜像（阿里云/NPM Mirror）。
  • true: 強制使用国内镜像源。
  • false: 強制使用官方默認源。

示例：

# 強制使用国内镜像加速構建
docker build --build-arg USE_MIRROR=true -t antigravity-manager:latest -f docker/Dockerfile .

⚙️ 環境變量配置 Copy Chapter

📂 數據持久化 Copy Chapter

請務必將宿主機目錄掛載至容器內的 /root/.antigravity_tools，否則賬號和配置在容器重啟後會丟失。

🌐 訪問位址 Copy Chapter

• 管理界面: http://localhost:8045
• API Base: http://localhost:8045/v1

📦 Docker Hub 分發 (推薦) Copy Chapter

若要推送至你的倉庫：

# 打上版本標籤並推送
docker tag antigravity-manager:latest lbjlaq/antigravity-manager:latest
docker tag antigravity-manager:latest lbjlaq/antigravity-manager:4.3.0
docker push lbjlaq/antigravity-manager:latest
docker push lbjlaq/antigravity-manager:4.3.0

Overview (`docs/README.md`) Copy Section

Documentation index

This folder contains developer-focused documentation (architecture, implementation details, and validation steps).

Proxy Copy Chapter

• docs/proxy/auth.md — proxy authorization modes, expected client behavior, and implementation pointers.
• docs/proxy/accounts.md — account lifecycle in the proxy pool (including auto-disable on invalid_grant) and UI behavior.

z.ai (GLM) integration Copy Chapter

• docs/zai/implementation.md — end-to-end “what’s implemented” and how to validate it.
• docs/zai/mcp.md — MCP endpoints exposed by the proxy (Search / Reader / Vision) and upstream behavior.
• docs/zai/provider.md — Anthropic-compatible passthrough provider details and dispatch modes.
• docs/zai/vision-mcp.md — built-in Vision MCP server protocol and tool implementations.
• docs/zai/notes.md — research notes, constraints, and future follow-ups (budget/usage, additional endpoints).

Agent Integrations Copy Chapter

• docs/jeikcode_integration.md — JeikCode integration guide, one-click synchronization, configuration options, and KV-cache optimization.

API REFERENCE (`docs/API_REFERENCE.md`) Copy Section

API Reference (v4.3.0)

本文档详细介绍了 Antigravity Tools 暴露的 HTTP API 接口。

注意: 在 v4.0.1 版本中，所有的服务（包括 AI 反代和系统管理）均已整合至统一端口 8045。原有的 19527 端口已废弃。

1. 概览 (Overview) Copy Chapter

Antigravity Gateway 是一个双重角色的服务器：

1. AI Proxy Interface: 兼容 OpenAI/Anthropic/Google 官方 SDK 的标准接口。
2. Management Admin API: 用于管理账号、配置系统、监控流量的 RESTful 接口。

鉴权体系 (Authentication) Copy Section

提示: 默认情况下，Admin Token 与 API Key 是同一个值（即您在 .env 或 Docker 环境变量中设置的 API_KEY）。

2. 管理接口 (Management API) Copy Chapter

Base URL: http://<host>:8045/api

2.1 账号管理 (Account Management) Copy Section

2.2 系统配置 (System Config) Copy Section

2.3 监控与统计 (Monitoring & Stats) Copy Section

流量日志

• GET /logs: 获取日志列表 (支持 limit, offset, filter, errorsOnly 参数)
• GET /logs/count: 获取日志总数
• GET /logs/:id: 获取日志详情
• POST /logs/clear: 清空日志

Token 统计 (v4.0.1 New)

• GET /stats/token/summary: 获取 Token 消耗摘要 (今日/本周/总量)
• GET /stats/token/hourly: 获取按小时统计数据
• GET /stats/token/daily: 获取按日统计数据
• GET /stats/token/by-account: 按账号统计消耗占比
• GET /stats/token/by-model: 按模型统计消耗占比
• POST /stats/token/clear: 重置统计数据

2.4 高级功能 (Advanced) Copy Section

• POST /proxy/cli/sync: 执行 CLI (Claude/Codex) 配置文件同步
• POST /accounts/import/db: 从 v1 旧数据库导入账号
• POST /accounts/oauth/start: 发起 OAuth 授权流程 (Headless)
• POST /proxy/cloudflared/start: 启动 Cloudflare Tunnel

3. AI 协议接口 (AI Protocol Interface) Copy Chapter

Base URL: http://<host>:8045

本服务完全兼容主流 AI 厂商的官方协议规范。您可以直接将本服务的地址填入到支持 OpenAI / Claude 的客户端中。

OpenAI Compatible Copy Section

• 对话生成 (Chat Completions)

  • POST /v1/chat/completions
  • 支持模型: 任何映射后的模型 ID (如 gpt-4o, gemini-1.5-pro)
  • 兼容性: 完全兼容 OpenAI 官方 Response 格式 (包括流式 SSE)。

• 图片生成 (Image Generation)

  • POST /v1/images/generations
  • 支持模型: gemini-3-pro-image (自动映射到 Imagen 3)
  • 参数扩展: 支持 size: "1920x1080", quality: "hd" 等高级参数。

Anthropic Compatible Copy Section

• Claude Messages
  • POST /v1/messages
  • 用途: 支持 Claude CLI (claude), Cursor, Cherry Studio 等客户端。
  • 特性: 完整支持 Tool Use (工具调用) 和 Thinking (思维链) 模式。

Gemini Native Copy Section

• Google AI Studio
  • GET/POST /v1beta/models/*
  • 用途: 供使用 Google 官方 SDK (Python/Node.js) 的应用调用。

CLAUDE CODE 10 VERSIONS DIFF (`docs/CLAUDE_CODE_10_VERSIONS_DIFF.md`) Copy Section

跨 10 个版本 (v2.1.284 ~ v2.1.295) Claude Code 流控制与状态机演进全景对比报告

研究对象：Anthropic 官方发布的 10 个 Darwin ARM64 原生发行版本：
v2.1.284、v2.1.285、v2.1.286、v2.1.288、v2.1.289、v2.1.291、v2.1.292、v2.1.293、v2.1.294、v2.1.295
逆向技术：Mach-O Mach 头部解构、Bun standalone __BUN.__bun 压缩脚本解包、AST 语义比对与状态机拓扑分析

一、版本演进总览与里程碑划分 Copy Chapter

从 v2.1.284 到 v2.1.295，Claude Code 的流控制体系经历了一场由“松散容错”转向“极度严苛的有限状态机校验”的重大演进。

[v2.1.284 ~ v2.1.286] 宽松网络容错期
  └── 允许未完全闭合的流截断，基础网络重试，无复杂思考块拦截
          │
          ▼
[v2.1.288 ~ v2.1.289] 空闲超时看门狗期
  └── 引入 outlastedNonStreamingTimeout，新增 timedOut 错误枚举，流超时硬性判定
          │
          ▼
[v2.1.291 ~ v2.1.293] 状态机契约收紧与中毒爆发期 (当前排查重点)
  └── 引入严苛的三元组契约 (qu !== null && zb && El === null)
  └── 引入 resumedFromIncompleteThinking 脏状态标记
  └── 引入 CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS 与 qz 拦截位，引爆 27 分钟死锁
          │
          ▼
[v2.1.294 ~ v2.1.295] 契约固化与内容审查期
  └── 状态机完全冻结，新增 cli_output_filter 遥测与更严格的 SSE 帧序校验

二、逐版本核心状态机代码与函数 Diff 深度比对 Copy Chapter

1. v2.1.284 ~ v2.1.286：宽松容错基线 Copy Section

• Qnn 核心实现：
  javascript Copy

  function Qnn(e) {
    let n = e.anyBlockFinished ? (e.anyOutputShown ? "output" : "thinkingOnly") : (e.anyOutputShown ? "partialOutput" : (e.anyEvent ? "started" : "nothing")),
        r = ufr(e);
    if (e.complete) {
      if (r === "connectionLost" || r === "truncated" || r === "stalled" || (r === "overloaded" || r === "serverError") && n === "output")
        return;
    }
    return { kind: "streamFailed", cause: r, progress: n, ... };
  }

• 核心特征：
  • ufr 仅包含基础的 connectionLost、truncated、stalled、overloaded、serverError 映射；
  • 缺乏对系统睡眠挂起（suspended）与空闲超时的区分；
  • 对思考块未闭合中断没有特殊的脏标记写入机制，会话容错度极高。

2. v2.1.288 ~ v2.1.289：超时看门狗与 `timedOut` 枚举引入 Copy Section

• Diff 变动点：
  1. 在 Qnn 守卫中引入 timedOut：
     javascript Copy

     - (r === "overloaded" || r === "serverError") && n === "output"
     + (r === "overloaded" || r === "serverError" || r === "timedOut") && n === "output"

  2. 在 ufr 中将 timeout_error 与非流式超时区分：
     javascript Copy

     if (e.isServerError) {
       return e.error instanceof xt && e.error.type === "timeout_error" ? "timedOut" : "serverError";
     }

  3. 引入客户端活跃计时器：outlastedNonStreamingTimeout = monotonicNow() - Cy >= uon()。
• 影响分析：
  网关一旦发生超过客户端 uon() 的长静默（如模型复杂推理未推流），客户端开始单方面定性为 timedOut，不再简单归类为网络断连。

3. v2.1.291 ~ v2.1.293：严苛三元组契约、会话中毒与 27 分钟死锁的引爆点 Copy Section

• Diff 变动点 1：引入严格的三元组不变式：
  javascript Copy

  + complete: qu !== null && zb && El === null

  • El 首次作为打开块的悬挂索引深度绑定在流完成判断中。
  • 如果网关在流结束时遗留了任何未发送 content_block_stop 的块（如 Thinking 块或 Text 块），El 保持为非空，导致 complete 判定永远为 false！
• Diff 变动点 2：引入会话永久中毒脏标记 resumedFromIncompleteThinking：
  javascript Copy

  + if ($e && E.type === "assistant" && !E.isApiErrorMessage && !hr([E])) {
  +   E.resumedFromIncompleteThinking = !0;
  + }

  • 当流在中途中断且仅有思考块时，该轮助手消息被打上 resumedFromIncompleteThinking: true 并持久化落盘；
  • 下一轮提问时，残缺思考块因缺失 Google Gemini Thought Signature 导致上游持续报 400，造成会话永久瘫痪。
• Diff 变动点 3：引入过载基础延迟与 qz 拦截位：
  javascript Copy

  + qz = Ru?.progress === "thinkingOnly" && Ru.cause === "overloaded" && !Ru.stopReasonReceived;
  + if (Ru === void 0 || Ru.progress === "output" || Ru.progress === "thinkingOnly" && !qz) { ... }

  • 新增环境变量与参数 CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS；
  • 若在思考阶段断流且被误判为 overloaded，qz 直接阻断正常 keepPartial 退出，直接坠入 10 次指数退避阶梯，累计卡死长达 27~29 分钟！
• Diff 变动点 4：引入 suspended 挂起态与 outputFiltered：
  • 增强对操作系统休眠的识别与内容过滤拦截。

4. v2.1.294 ~ v2.1.295：状态机固化与遥测审查强化 Copy Section

• Diff 变动点：
  • 状态机完全继承 2.1.293 的三元组契约与 keepPartial 分支逻辑，未做回退；
  • 新增敏感内容审查遥测指标：cli_output_filter_retry_outcome 与 tengu_output_filtered；
  • 强化了对 SSE 异常帧序的捕获：在 message_stop 后若收到任何数据，TJ("closed") 的抛出点更加前置。

三、跨版本 10 大关键判定指标演进对照矩阵 Copy Chapter

四、历史调试反思与 PR #3634 的数学必然性 Copy Chapter

在早期的排查调试中，由于未能洞察 v2.1.291 ~ v2.1.293 发生的核心状态机突变：

1. 回退 9 月方案时的失误：
   曾误认为“应该把底层的网络连接重置和超时透传给客户端，由客户端自身处理重试”。然而在 2.1.293 的严格规则下，裸透传网络异常或合成 overloaded_error 直接命中了 PU(e) 与 qz 拦截位，反而亲手引爆了 27 分钟死锁；
2. 残缺思考块的副作用：
   断流时未能闭合思考块并注入正文，使得消息长度停留在 content.length === 1，精准激活了 bp(e) 触发链，导致大量旧会话被打上脏标记永久中毒。

PR #3634 的数学收敛必然性：
PR #3634 实现的四大防御支柱：

1. 强制闭合未完成块（满足 El === null）；
2. 纯思考断流自动注入正文文本块（使助手消息 content.length >= 2，破除 bp 判定，杜绝会话中毒；同时升级进度为 "output"）；
3. 下发 message_delta(stop_reason: "end_turn") 与 message_stop（满足 qu !== null && zb === true）；
4. 移除 overloaded_error 并前置 message_stop_sent 静默防火墙（彻底绕过 PU(e) 与 TJ("closed")）。

上述实现在数学逻辑与状态机转移图上，100% 完整覆盖并契合了从 v2.1.284 至 v2.1.295 的全部演进规则，是真正意义上的根因级、未来导向型稳态解决方案。

CLAUDE CODE STREAM DIAGNOSIS (`docs/CLAUDE_CODE_STREAM_DIAGNOSIS.md`) Copy Section

Claude Code 与 Antigravity 网关长流断裂、重试风暴与会话中毒深度排查诊断全书

文档版本：v2.0 (全量反编译深度演化版)
逆向目标：Claude Code 官方发行版 v2.1.284 ~ v2.1.295（重点解构本地运行环境 v2.1.293 原生 Darwin ARM64 Bun 内嵌运行时）
对齐分支：beta (PR #3634)
关联 Issue：Issue #3633, Issue #3635

目录 Copy Chapter

1. 错误症状全景总结 (Symptoms Catalog)
2. 客户端架构逆向解构：14 核心机制证据链
   • 2.1 过载判定 PU(e) 源码与 30 分钟惩罚性冷冻
   • 2.2 指数抖动退避计算引擎 vC / LF 与 27 分钟死锁数学公式
   • 2.3 核心终结三元组契约 qu !== null && zb && El === null
   • 2.4 流失败原因分类器 ufr(e) 11 类分类体系
   • 2.5 progress 5 级状态梯度与 Qnn 核心短路豁免模型
   • 2.6 决策引擎 lfr(...) 全分支状态迁移矩阵与 qz 拦截陷阱
   • 2.7 会话历史中毒机制 resumedFromIncompleteThinking 触发条件与阻断数学证明
   • 2.8 会话转录本 (Transcript) 存储架构真相：纯 JSONL + .meta.json (无 SQLite)
   • 2.9 澄清真相：官方不存在 /undo 斜杠命令与 /compact 5 级数据清洗自愈管道
   • 2.10 message_stop 后的静默防火墙契约与 TJ("closed") 格式异常
   • 2.11 传输层 SSE event: error 即刻抛错与协议中断机制
   • 2.12 HTTP 429 限流与 Bur = 60000 (60s) 硬截断崩溃陷阱
   • 2.13 非流式降级分支 (retryWithoutStreaming) 与 jAt(e) 强契约校验
   • 2.14 SSE 保活心跳帧定界规范与双换行 \n\n 约束
3. Antigravity 网关交互准则与绝对红线
4. 版本选型建议与用户自愈指引
5. 9 月历史回退的反思与现代融合架构

一、错误症状全景总结 (Symptoms Catalog) Copy Chapter

在长耗时大算力生成任务（典型如高细节坐标 SVG、深度系统架构推理、批量代码重构）中，中间网络或 Google GFE 往往在 100~116 秒发生 TCP 静默或断连。在未适配最新 Claude Code 状态机时，客户端会呈现以下 4 大恶性症状：

二、客户端架构逆向解构：14 核心机制证据链 Copy Chapter

2.1 过载判定 `PU(e)` 源码与 30 分钟惩罚性冷冻 Copy Section

基于对 Claude Code v2.1.293 内置运行时核心偏移地址 186169512 的反编译：

// 核心过载判定函数: PU(e)
function PU(e) {
  if (!(e instanceof xt)) return !1;
  return e.status === 529 || (e.message?.includes('"type":"overloaded_error"') ?? !1);
}

• 判定要素：
  1. e 必须为 Anthropic SDK 核心 APIError 实例（xt）；
  2. 满足 e.status === 529 或 错误消息字符串包含字面量 "type":"overloaded_error"。
• 级联反应与 30 分钟冷冻期：
  javascript Copy

  let qo = sfr(Jt), uo = qo !== null && qo < LKe; // LKe = 20000ms (20s)
  if (!uo) {
    let ko = Math.max(qo ?? ofr, rfr); // ofr = 1800000 (30分钟!), rfr = 600000 (10分钟!)
    let ir = PU(Jt) ? "overloaded" : "rate_limit";
    ops(Date.now() + ko, ir); // 写入本地冷却期熔断时间戳
    if (jo()) h.fastMode = !1; // 强制关闭 Fast Mode
    continue;
  }

  结论：只要错误载荷中包含 "type":"overloaded_error"，若未携带小于 20 秒的 retry-after，客户端直接进入长达 30 分钟 (1,800,000ms) 的惩罚性冷却状态。

2.2 指数抖动退避计算引擎 `vC` / `LF` 与 27 分钟死锁数学公式 Copy Section

客户端在 chunk-k2e8p61g.js 中实现了精确的指数比例抖动算法：

// 退避核心算法引擎
function vC({attempt: t, baseMs: r, capMs: e = 1/0, factor: o = 2, jitter: n = {kind: "none"}, random: m = Math.random}) {
  let i = Math.min(e, r * o**(t - 1));
  switch (n.kind) {
    case "none": return i;
    case "proportional": return i + m() * n.ratio * i; // 正向 0 ~ +25% 比例抖动
    case "symmetric": return Math.max(0, i + i * n.ratio * (2 * m() - 1));
    case "full": {
      let a = Math.min(n.floorMs, i);
      return a + m() * (i - a);
    }
  }
}

// API 重试封装函数
function LF(e, r, a = 32000, s = Math.random, n = me) { // me = 500ms
  let o = Math.round(vC({attempt: e, baseMs: n, capMs: a, jitter: {kind: "proportional", ratio: 0.25}, random: s}));
  if (r) {
    let i = parseInt(r, 10);
    if (!isNaN(i)) return Math.max(i * 1000, o);
  }
  return o;
}

• 数学公式：
  $$\text{Delay}{\text{base}} = \min(32000, 500 \times 2^{\text{attempt}-1})$$
  $$\text{Delay}{\text{actual}} = \text{Delay}_{\text{base}} \times (1 + 0.25 \times \text{random}())$$
• 重试上限计算 (eVe)：
  javascript Copy

  var yur = 10;    // 默认交互模式上限: 10 次
  var IKe = 15;    // CLAUDE_CODE_MAX_RETRIES 硬截断限制: 15 次
  var _ur = 300;   // Watchdog 模式上限: 300 次

  默认情况下，客户端执行 10 次 重试。在命中 ofr 冷冻窗口叠加指数退避后，10 次重试累计等待时长精准落在 27 ~ 29 分钟，形成终端无法退出的假死风暴。

2.3 核心终结三元组契约 `qu !== null && zb && El === null` Copy Section

在流事件循环生成器 Bfr 与仲裁器 Qnn 中，流的完备性取决于严格的三元组逻辑：

$$\text{complete: } qu \neq \text{null} \land zb \land El === \text{null}$$

1. qu (Stop Reason)：
   • 必须为有效字符串（"end_turn"、"tool_use"、"max_tokens"、"stop_sequence"）；
   • 必须通过 message_delta 的 delta.stop_reason 下发。
2. zb (Terminal Marker)：
   • 布尔标志位。初始为 false；在收到合法携带 stop_reason 的 message_delta 时置为 true；
   • 若随后出现乱序未闭合块事件，会被强制重置为 false。
3. El (Open Block Pointer)：
   • 处于打开状态的内容块索引指针；
   • 收到 content_block_start 时赋值为当前块索引 El = index；
   • 仅在收到 content_block_stop 时重置为 null。
   • 致命断言：若流结束（EOF）时 El !== null，客户端直接执行：
     javascript Copy

     if (uf && El !== null) {
       throw t(`Stream ended cleanly inside open block ${El} (stop_reason=${qu}) — treating as a dropped connection`), new cwr;
     }

     抛出 StreamTruncatedError 并判定为异常截断！

2.4 流失败原因分类器 `ufr(e)` 11 类分类体系 Copy Section

当流中断或报错时，函数 ufr(e) 按确定性优先级将原因解析为以下 11 种枚举值：

2.5 `progress` 5 级状态梯度与 `Qnn` 核心短路豁免模型 Copy Section

客户端定义了 5 级输出进度：

let n = e.anyBlockFinished 
  ? (e.anyOutputShown ? "output" : "thinkingOnly") 
  : (e.anyOutputShown ? "partialOutput" : (e.anyEvent ? "started" : "nothing"));

• "output"：至少 1 个块已关闭且展示了正文/工具调用（最安全状态）；
• "thinkingOnly"：已有块关闭，但全部为思考块，正文未吐出（极度危险状态）；
• "partialOutput"：正文正在吐字，但首个块尚未收到 content_block_stop 闭合；
• "started"：收到过首包（如 message_start 或打开的思考块），但无块关闭且无正文；
• "nothing"：尚未收到任何 SSE 数据帧。

`Qnn` 核心短路豁免守卫：

if (e.complete) {
  if (r === "connectionLost" || r === "suspended" || r === "truncated" || r === "stalled" || 
     ((r === "overloaded" || r === "serverError" || r === "timedOut") && n === "output")) {
    return; // 关键：返回 undefined！
  }
}

数学豁免事实：只要 complete === true 且 progress === "output"，无论遭遇网络断开、超时还是 529，Qnn 均直接返回 undefined！外层 Mp 被赋予 "keepPartial"，彻底绕过 onStreamFailed，绝不触发任何重试！

2.6 决策引擎 `lfr(...)` 全分支状态迁移矩阵与 `qz` 拦截陷阱 Copy Section

若未满足豁免条件，错误进入 lfr 决策矩阵：

`qz` 拦截标志位的致命陷阱：

let qz = Ru?.progress === "thinkingOnly" && Ru.cause === "overloaded" && !Ru.stopReasonReceived;
if (Ru === void 0 || Ru.progress === "output" || Ru.progress === "thinkingOnly" && !qz) {
  // 正常 keepPartial 优雅退出逻辑
}

若断流发生在 thinkingOnly 阶段且错误归因于 overloaded，qz 为 true，将强行阻止客户端进入正常收尾分支，迫使其无条件坠入 27 分钟死循环。

2.7 会话历史中毒机制 `resumedFromIncompleteThinking` 触发条件与阻断数学证明 Copy Section

通过对函数 bp(e, o) 与 Q4o(...) 的反编译分析：

function bp(e, o) {
  let n = e.filter((s) => !s.isApiErrorMessage && !l0e(s)),
      r = n.length === 1 ? n[0] : void 0;
  if (r === void 0 || r.message.content.length !== 1) return !1;
  let u = r.message.content[0];
  return u !== void 0
      && Fme(u) // u.type === "thinking" || u.type === "redacted_thinking"
      && VEn(u) // 必须有合法签名
      && r.message.stop_reason === "max_tokens"
      && Q4o(o, r.message.resumable, UP(r.message.usage));
}

• 中毒触发链条：
  1. 思考断流发生后，若客户端仅记录到残缺思考块（content.length === 1 且无正文）；
  2. 进程退出或下一轮输入刷盘时，Assistant 消息被标记：
     if ($e && E.type === "assistant" && !E.isApiErrorMessage) E.resumedFromIncompleteThinking = !0;
  3. 下一轮提问时，客户端将该残缺思考块回传给上游。因为 Google Gemini 原生不具备 Anthropic 的私有加密思考块连续签名（Thought Signature），上游校验失败直接返回 HTTP 400 Bad Request。
• 网关阻断数学证明：
  网关在思考断流时执行策略——“显式闭合思考块，注入合成正文块，下发 end_turn”。
  此时助手消息的内容变为 [Thinking, Text]，content.length = 2。
  由于 r.message.content.length !== 1，bp(...) 在首个条件分支恒返回 false，从而在数学层面彻底粉碎了 resumedFromIncompleteThinking 的产生前置条件！

2.8 会话转录本 (Transcript) 存储架构真相：纯 JSONL + .meta.json (无 SQLite) Copy Section

经过对 Bun 运行时模块与存储引擎的反编译排查，澄清先前流传的技术误解：

• 无本地 SQLite 参与：Claude Code 业务层转录本完全未采用 SQLite；
• 真实文件体系：
  • 会话数据：~/.claude/projects//<sessionId>.jsonl
  • 会话元数据：~/.claude/projects//<sessionId>.meta.json
  • 子智能体：~/.claude/projects//<sessionId>/subagents/agent-<agentId>.jsonl
• 流式拦截器 n6t：
  javascript Copy

  function n6t(e, n, r) {
    if (!r) return e.length;
    for (let s = n; s < e.length; s++) {
      let g = e[s];
      if (g.type === "assistant" && g.message.stop_reason === null) return s;
    }
    return e.length;
  }

  在流进行期间，stop_reason === null 的未完结助手消息被 n6t 严格拦截、禁止落盘。但一旦遭遇异常掐线且进程退出，强制刷盘会使残缺消息落盘写入 .jsonl，导致持久化污染。

2.9 澄清真相：官方不存在 `/undo` 斜杠命令与 `/compact` 5 级数据清洗自愈管道 Copy Section

反编译全量命令注册表（type: "local" 与 type: "local-jsx"）确认：

• Claude Code 官方命令集中不存在 /undo 斜杠命令。用户此前理解的 undo 实际是快捷键 ctrl+_（输入框单行撤销）或历史栈内存回退；
• 真正的会话级清洗管道为 /compact。客户端在执行 /compact 时按序调用 5 级自愈管道：
  1. Jjr：消除思考块间的空白文本块并补占位符；
  2. oPn / nPn：过滤未闭合且无签名的孤立残缺思考块（抛出 tengu_filtered_orphaned_thinking_message）；
  3. ZAn：剥除末尾残留的孤立思考块，补入 [No message content]，杜绝 Anthropic 400 校验违规；
  4. tPn：消除空白 Assistant 消息并执行 _I 缝合相邻 User 角色；
  5. Zjr：对空 Assistant 消息补入合法文本兜底。
• 自愈指引：对于历史损坏的会话，用户执行 /compact 或 /clear 即可激活上述清洗管道完成无损自愈。

2.10 `message_stop` 后的静默防火墙契约与 `TJ("closed")` 格式异常 Copy Section

在事件消费循环 xet 中：

case "content_block_delta": {
  let Ba = Jg[us.index];
  if (!Ba || Ol.has(Ba)) {
    throw i("tengu_streaming_error", {
      error_type: Ba ? "content_block_closed_delta" : "content_block_not_found_delta"
    }), new TJ(Ba ? "closed" : "unstarted");
  }
}

• 关键机制：收到 content_block_stop 后，块被存入已关闭集合 Ol。如果在 message_stop 发送之后网关继续推流（如延迟的 SSE 数据、迟到的心跳或尾部元数据），将命中 Ol.has(Ba)，抛出 StreamMalformedEventError("closed")（TJ("closed")）。
• 灾难后果：malformed 不受 complete 守卫豁免！客户端会直接将整轮会话定性为畸形，在控制台弹出黄色警告并可能触发非流式重试。
• 网关防线：下发 message_stop 后必须立即使连接到达 HTTP EOF，且在 process_sse_line 入口前置 if state.message_stop_sent { return None; } 守卫。

2.11 传输层 SSE `event: error` 即刻抛错与协议中断机制 Copy Section

SDK 底层 SSE 解析器 fromSSEResponse（偏移 190503780）：

if (T.event === "error") {
  let P = hf(T.data) ?? T.data, M = P?.error?.type;
  throw new xt(void 0, P, void 0, n.headers, M);
}

• 核心判定：一旦客户端解析到 event: error，立即抛出 xt 异常中止生成器，后续任何事件均无法到达。
• 网关规范：推流开始后（has_content || has_thinking），绝对禁止下发 event: error。若发生中断，必须合成合法的 content_block_stop -> 兜底文本 -> message_delta(end_turn) -> message_stop 序列。

2.12 HTTP 429 限流与 `Bur = 60000` (60s) 硬截断崩溃陷阱 Copy Section

客户端定义了严格的退避时间天花板常量：

var Bur = 60000; // 非 Watchdog 模式单次退避容忍上限: 60 秒

$o = LF(Vt + G, Oo, void 0, r.random, ...);
if (GV()) {
  $o = Math.min($o, NKe);
} else if ($o > Bur) {
  throw i("tengu_api_retry_after_too_long", {delayMs: $o, status: Jt.status}),
        new qc(Jt, h); // 抛出异常直接中止，拒绝重试！
}

严重风险：当未开启 CLAUDE_CODE_RETRY_WATCHDOG 时，若网关返回的 Retry-After 计算后大于 60 秒，客户端直接硬崩溃抛错退出。网关下发 429 时必须将 Retry-After 安全钳制在 1 ~ 15 秒内。

2.13 非流式降级分支 (`retryWithoutStreaming`) 与 `jAt(e)` 强契约校验 Copy Section

当流在首包阶段遭遇 404 或未出字前网络中断时，客户端会通过 Qhe 触发非流式降级：

let Ye = await Y.beta.messages.create({ ...Ce, stream: !1 }, ...);

客户端对非流式响应执行 jAt(e) 强模式校验：

• content 必须为合法 Array；
• model 必须为非空 String；
• usage 必须为包含 input_tokens 与 output_tokens 的 Object。
  缺损任何字段均会导致 Non-streaming fallback also failed 致命报错。网关必须保持对 /v1/messages 的 stream: false 完整支持。

2.14 SSE 保活心跳帧定界规范与双换行 `\n\n` 约束 Copy Section

客户端内置解析器 class rjt 与 SDK 流迭代器中：

• SSE 帧采用连续换行符定界（\n\n 或 \r\n\r\n）。单换行会被挂起在 pending 缓冲中，无法触发事件解析；
• 收到注释行 : keepalive\n\n 时，字段解析函数 f(n) 返回 {}，触发 this.resetLivenessTimer()，同时重置 Cy 计时器；
• 网关在模型长思考期间必须至少每 15 秒（推荐每 3 秒）刷出一次保活帧，严禁长流静默超 45 秒。

三、Antigravity 网关交互准则与绝对红线 Copy Chapter

基于上述 14 维度深度逆向成果，Antigravity 网关确立以下生命周期交互红线与合规规范：

1. 绝对红线 (Strictly Prohibited) Copy Section

1. 严禁在推流开始后透传底层连接断开 Err (如 TCP RST / Broken pipe)：
   一旦 has_content == true 或 has_thinking == true，任何网络断裂必须被网关拦截并转入本地优雅收尾。
2. 严禁在响应中合成或下发带有 "type":"overloaded_error" 的任何载荷：
   无论首包或中途，该字串均会触发客户端 PU(e) 判为过载，引爆 30 分钟冷却与 10 阶指数退避风暴。
3. 严禁遗留悬挂未闭合的内容块（禁止 El !== null）：
   发送 message_delta 或 message_stop 之前，必须显式发送 content_block_stop 闭合所有已开启块。
4. 严禁 Thinking-Only 孤立断流：
   流若在仅有思考块时中断，必须补发兜底正文文本块升级进度至 "output"，严禁直接以思考块收尾导致会话中毒。
5. 严禁在 message_stop 下发后追加任何帧或维持心跳：
   下发 message_stop 后必须立即使连接到达 HTTP EOF，防止触发 TJ("closed") 或客户端 30s Byte Watchdog 误杀。
6. 严禁下发超过 60 秒的 Retry-After 头部：
   防止触发客户端 Bur = 60000ms 的 api_request_retry_after_too_long 硬崩溃。

2. 必须行为 (Mandatory Requirements) Copy Section

1. 严格履行黄金三元组收尾契约：
   断流收敛序列必须严格保证：
   $$\text{content_block_stop (若有打开块)} \longrightarrow \text{正文兜底 (若思考孤立)} \longrightarrow \text{message_delta (end_turn)} \longrightarrow \text{message_stop} \longrightarrow \text{HTTP EOF}$$
2. 首包不可逆错误注入 x-should-retry: false 响应头：
   首包前发生确定性失败时，在 HTTP 头中注入该标志，促使客户端立即终止重试并暴露错误。
3. 维持每 3 秒高频 SSE 保活心跳：
   向下游推送 : keepalive\n\n，持续刷新客户端活跃定时器。

四、版本选型建议与用户自愈指引 Copy Chapter

1. 推荐客户端版本 Copy Section

• 稳定生产推荐：Claude Code v2.1.28x（流完成校验相对宽松，鲁棒性最高）。
• 最新版本支持：Claude Code v2.1.293 ~ v2.1.295。使用最新版本时，必须配合部署包含 PR #3634 修复的 Antigravity 网关。

2. 用户操作指南 (故障自愈) Copy Section

• 中断当前重试：若终端出现 Retrying X/10 倒计时，直接按 Ctrl+C 强行终止，切勿等待 27 分钟；
• 自愈中毒历史：若旧会话出现持续报 400 错误，在终端执行 /compact 压缩上下文或执行 /clear 新开会话，即可激活 5 级自愈管道清除脏数据。

五、9 月历史回退的反思与现代融合架构 Copy Chapter

• 9 月版本回退的初衷与局限：
  9 月版本的核心思想是“中途断流优雅收尾”。但在前期调试中误判了报错场景，曾一度尝试完全透传底层网络错误，导致直接撞上 2.1.293 严格引入的 PU(e) 与 El 契约，引爆了 27 分钟死锁与会话中毒。
• PR #3634 的现代融合解法：
  将 9 月“平稳收尾、严禁裸露断连”的稳态原则，与 2.1.293 的“三元组不变式契约（El === null + 正文兜底升级 output）”深度融合，彻底实现了全生命周期流控制闭环。

CLAUDE COWORK DEEP COMPACT SPEC (`docs/CLAUDE_COWORK_DEEP_COMPACT_SPEC.md`) Copy Section

RFC：Claude Desktop Cowork Deep Compact

官方 Compact 机制逆向、50% 保留限制解除与低延迟深度压缩

• Issue Type: Architectural Breakthrough / In-Depth RFC
• Target Component: Claude Desktop Cowork / Antigravity Gateway
• Implementation Status: Experimental / Opt-in
• Primary Platform: macOS
• Validated Claude Client Versions: August build / October build
• Contributors: @cubelikeplayDaniel & Gemini & Claude Fable 5
• Linked Issue: Fixes #3576

0. 摘要 Copy Chapter

本项目针对 Claude Desktop Cowork 模式中的上下文 Compact 机制进行了逆向分析，并构建了一套独立的 Deep Compact 实现。

项目的核心并不是重新实现一套摘要系统，也不是简单地伪造客户端显示的 Context 数值，而是：

利用 Claude 客户端原生 Compact 流程完成语义摘要，同时解除官方客户端在历史消息 pruning 阶段设置的“一次 Compact 后不得低于压缩前上下文约 50%”的保留限制，从而实现更激进的上下文裁剪。

整个系统分为两个职责完全不同的部分：

• Gateway：负责触发、状态管理、Compact 请求放行以及恢复闭环。
• Client Patch：负责修改官方 pruning 函数，使其突破官方 50% 保留下限。

因此，Binary Patch 并不是为了“让 Compact 发生”。

官方 Compact 的触发本身可以通过 Gateway 完成。

Patch 存在的根本原因是：

Gateway 可以控制 Compact 的进入条件与部分输入，但无法通过普通协议参数消除客户端 pruning 函数内部的 50% 保留限制。

实验结果进一步表明，在当前已验证的客户端和工作负载下，更激进的历史裁剪能够获得非常小的请求延迟，同时实际使用效果良好。

因此，本项目最终形成的并不是“另一个 Compact”，而是：

官方 Compact 摘要能力 + Gateway Reactive Compact 闭环 + 可选客户端 Deep Pruning Patch

三者组合形成的 Deep Compact 架构。

1. 原报告存在的核心问题 Copy Chapter

此前版本的报告已经正确描述了大量逆向结果，但存在一个影响架构理解的重要遗漏：

1.1 错误地把 Binary Patch 描述成 Deep Compact 的一般组成部分 Copy Section

原报告容易给人这样的印象：

Deep Compact = Gateway 触发 Compact + Binary Patch

这种表述不够准确。

正确关系应该是：

Reactive Compact = Gateway 触发官方 Compact

而：

Deep Compact = Reactive Compact + 解除官方 pruning 深度限制

后者才需要 Binary Patch。

也就是说：

Patch 不是 Compact 的触发器，而是 Compact 的“深度解除器”。

1.2 原报告没有明确指出官方 50% 保留限制 Copy Section

这是此前报告最重要的技术遗漏。

官方 Cowork Compact 并不是简单地：

计算一个目标 token 数 → 一直删除旧消息 → 直到达到目标

它内部存在一个重要约束：

一次 Compact 后，历史上下文的保留结果不能低于压缩前上下文的一定比例；在目前逆向与测试中确认的关键限制表现为约 50% 下限。

因此，即使 Gateway 通过 synthetic HTTP 400 提供更激进的 token gap，官方 pruning 函数最终仍然受到这一限制。

这意味着：

400 maximum 调得更小  ≠  真正解除 pruning 下限

两者不是同一件事情。

1.3 因此，“Gateway-only Deep Compact”并不能完整替代 Patch Copy Section

此前报告提出过一个分级架构：

• Level 0：正常 Gateway
• Level 1：Reactive Compact
• Level 2：Gateway-only Deep Compact
• Level 3：Binary Patch

这个分级作为工程策略仍然有意义，但其中 Level 2 必须重新定义。

它可以：

• 调整触发行为；
• 调整客户端看到的 token gap；
• 影响官方 pruning 的计算过程；
• 在某些情况下使 Compact 行为发生变化。

但是：

它不能从根本上消除官方 pruning 函数内部的 50% 保留约束。

因此，真正意义上的 Deep Compact 仍然需要修改客户端 pruning 逻辑。

2. 项目真正解决的问题 Copy Chapter

Claude Cowork 的官方 Compact 主要解决：

上下文接近限制时，通过摘要历史信息释放上下文空间。

而本项目解决的是另一个问题：

官方 Compact 虽然能够释放上下文，但其历史消息保留策略过于保守，导致一次 Compact 后仍然保留大量历史上下文。

于是出现：

长上下文
   ↓
官方 Compact
   ↓
生成 Summary
   ↓
保留大量最近历史
   ↓
实际 Prompt 仍然较大
   ↓
请求延迟 / Token 消耗仍然较高

Deep Compact 的目标是：

长上下文
   ↓
官方 Compact
   ├── 官方 Summary
   │
   └── Deep Pruning
          ↓
      大幅减少历史消息
          ↓
       更小 Prompt
          ↓
       更低延迟

3. 已确认的 Cowork Compact 触发机制 Copy Chapter

本项目已经确认：

Compact 并不是简单根据本地配置中的 context window 数值直接触发。

关键触发链路为：

Claude Client
      │
      │ 普通请求
      ▼
   Gateway
      │
      │ 正常请求
      ▼
  Backend
      │
      │
      ▼
HTTP 400
"prompt is too long"
      │
      ▼
Claude Client
      │
      │ 识别为 Context Overflow
      ▼
进入原生 Compact 流程
      │
      ▼
向 Gateway 发起 Compact 请求

因此 Gateway 可以利用一个与客户端原生行为兼容的：

HTTP 400 Bad Request
prompt is too long

作为 Reactive Compact 的触发器。

这使得项目无需重新实现 Claude 的摘要逻辑。

4. 为什么必须使用官方 Compact Copy Chapter

本项目没有选择：

Gateway 自己读取全部历史 → 自己调用 LLM → 自己生成 Summary → 自己重新组织上下文

原因是这样会重新实现 Claude 已经拥有的复杂 Compact 能力。

官方 Compact 已经处理：

• 历史对话摘要；
• 工具调用上下文；
• 对话连续性；
• 当前任务状态；
• Cowork 特有的上下文结构。

因此本项目采取：

复用官方语义压缩，只修改“保留多少原始历史”的策略。

这是整个架构中非常重要的“最小改动”原则。

5. 官方 50% 保留限制 Copy Chapter

逆向过程中确认，官方 pruning 函数并不是无限制地删除旧消息。

其核心行为可以抽象为：

Input:
    当前完整消息历史
    当前 token gap
    Compact 所需上下文

Process:
    从历史消息组向后遍历
    计算可保留的消息组
    保证工具调用/结果等结构完整
    同时受到官方保留比例限制

Output:
    Summary
    +
    最近的一部分历史消息

关键限制：

Compact 后保留上下文 ≥ Compact 前上下文的一定比例 ≈ 50%

这就是 Deep Compact 真正需要突破的地方。

6. 为什么不能只把 HTTP 400 的 maximum 调小 Copy Chapter

这是本项目架构中最容易产生误解的地方。

例如：

• 实际上下文：300K
• Gateway 返回：prompt is too long: 300000 tokens > 20000 maximum

直觉上可能认为：

“既然 gap 已经非常大，客户端应该自然删除更多历史。”

但实际上：

400 maximum
      ↓
影响 pruning 输入
      ↓
官方 pruning algorithm
      ↓
仍然存在官方保留下限
      ↓
不能无限向下裁剪

因此：

修改 400 参数 ≠ 删除官方 50% 下限。

这也是为什么真正的 Deep Compact 需要进入客户端 pruning 函数本身。

7. Client Patch 的真正作用 Copy Chapter

Patch 的目标非常单一：

不改变官方 Compact 的摘要逻辑，只解除官方 pruning 函数对历史保留深度的限制。

换言之：

原始客户端：

Compact → Summary → Official pruning → ≥ 50% retention

Patch 后：

Compact → Summary → Official pruning → Custom retention target

例如工程目标可以设置为约：35K active-history budget。

需要强调：
35K 是工程目标，而不是 Claude 官方声明的上下文限制。

实际最终 Prompt 仍然可能包含：

• system prompt；
• tool schema；
• Summary；
• 当前用户消息；
• 工具结果；
• 其他固定上下文。

因此不能把 35K 简单等同于最终 API "input_tokens"。

8. 为什么直接修改官方 pruning 函数，而不是重写 Compact Copy Chapter

这是整个项目最重要的工程原则之一：

只修改必要的控制点。

不修改：

• Summary 生成逻辑；
• Compact 请求格式；
• 消息语义；
• 工具调用结构；
• 官方上下文组织方式。

只修改：

“Compact 后究竟保留多少历史消息”

因此：

Claude 官方能力 + 一个非常小的 pruning 行为修改 = Deep Compact

这比重新实现整个 Compact pipeline 的风险要低得多。

9. Message Group 完整性 Copy Chapter

Pruning 不能简单地按单条消息删除。

例如：

• Assistant → Tool Call
• Tool → Tool Result
• Assistant → Next Message

这些消息之间具有结构关系。

因此 pruning 必须以：

完整 message group

作为基本裁剪单位。

否则可能产生：

• Tool Call 存在，Tool Result 消失；
• 或者 Tool Result 存在，对应 Tool Call 消失；
  从而破坏上下文结构。

因此 Patch 的目标不是随便删除消息，而是：

保持官方 message-group 语义 + 改变 group retention boundary

10. 官方 pruning 函数逆向 Copy Chapter

本项目已经对官方 pruning 函数进行了多版本逆向和验证。

不同 Claude Code / Claude Desktop 构建中观察到过不同的函数名称，例如：khf, rAt。

函数名称本身并不是可靠的识别依据。真正需要匹配的是其：

• 控制流；
• token gap 计算；
• message group 遍历；
• retention boundary；
• 返回结果结构。

目前测试表明：

该函数的核心逻辑在已经测试的多个版本之间没有发生根本性变化。

但是这并不等于可以宣称“所有未来版本永远兼容”。目前客户端层面的实际验证仍主要集中在：

• August build；
• October build。

中间版本以及更早版本尚未完成完整验证。因此兼容性应定义为：

已验证版本兼容，而非理论上的全版本兼容。

11. Deep Compact 状态机 Copy Chapter

Compact 并不是单纯的 400 → Compact → 结束。实际存在一个非常重要的问题：

Compact 完成后的下一次请求仍然可能再次触发 400。

因此 Gateway 必须区分：普通 Context Overflow 与 Compact 后恢复请求。

推荐状态模型：

NORMAL
   │
   │ HTTP 400
   ▼
COMPACTION_REQUESTED
   │
   ▼
COMPACTION_IN_PROGRESS
   │
   │ Summary 完成
   ▼
POST_COMPACTION_RETRY
   │
   │ 一次性豁免
   ▼
NORMAL

而不是：看到 → 永久认为“已经 Compact”。

12. 为什么不能用静态 "" 判断状态 Copy Chapter

Compact 后的 Summary 会持续存在于上下文中。

因此：

if "<summary>" exists: already compacted

会产生错误状态：第一次 Compact 产生 Summary 后，后续所有请求都会被误认为“这是 Compact 后的请求”，导致防护失效。

正确方式应该是建立一次性的 Compaction Generation：

struct CompactionGeneration {
    id: String,
    triggered_at: Instant,
    before_tokens: u32,
    summary_seen: bool,
    retry_consumed: bool,
}

并使用 atomic consume，保证并发请求不会同时获得 Compact 后豁免。

13. Double-400 问题 Copy Chapter

这是实现过程中发现的重要边界条件：

请求 A → 400 → Compact → 请求 B → 仍然超过 Gateway 判断阈值 → 再次 400

如果 Gateway 不知道请求 B 是 Compact 完成后的 recovery retry，那么客户端可能进入死循环：

Compact → 400 → Compact → 400 → Compact ...

因此 Gateway 必须维护：

• Compaction Generation
• One-shot Post-Compact Retry
• Expiry (如 180 秒生命周期)
• Atomic Consumption

14. "./compact" 的定位 Copy Chapter

./compact 不应该被描述为“Claude CLI 原生命令”。

更准确的定义是：

Cowork 环境中的显式 Compact intent / control-plane trigger。

它表达用户明确要求：“现在进行一次 Compact。” Gateway 再根据当前状态将其转换成实际 Compact 流程：

./compact
   ↓
Gateway Control Plane
   ↓
Synthetic 400 / Compact Trigger
   ↓
Claude Native Compact

这样可以保持用户意图与底层 HTTP 行为的分离。

15. Token Estimator Copy Chapter

Gateway 需要判断当前上下文规模，因此实现了 Token Estimator。需要综合考虑：

• 普通文本；
• 中文；
• ASCII；
• tool schema；
• tool result；
• image；
• Base64 media；
• MCP 等复杂工具上下文。

但是：

Estimator 是控制逻辑，不应被描述为 API 最终真实 "input_tokens"。

例如一次实测：

• 约 334K estimated tokens → 约 45.1K estimated tokens
• 对应净释放约 289K（约 86.5%）

这是非常显著的上下文规模下降。但如果没有 API usage 数据，不能把这些数字直接称作 Anthropic API 返回的真实 "input_tokens"。

16. 实验结果：激进压缩的低延迟收益 Copy Chapter

这是此前报告中同样应该加强的部分。

Deep Compact 的目标并不是“压得越狠越厉害”，真正重要的是：

压缩后的上下文足够小，同时仍然保持任务连续性，而且请求延迟很低。

当前实验已经验证：

• 更激进的历史裁剪可以大幅降低实际 Prompt；
• 压缩后的任务连续性与使用效果良好；
• 在测试工作负载中，压缩后请求取得了非常小的延迟；
• 没有观察到与这种激进裁剪规模相对应的明显交互性能损失。

因此 Deep Compact 的价值不仅是“能塞进更大的上下文”，还包括：

更小 Prompt → 更少需要处理的历史上下文 → 更低请求延迟

这使 Deep Compact 从一个单纯的“Context Overflow workaround”变成了：

一种实际的上下文性能优化机制。

17. UI Context 与 Model Context 的分离 Copy Chapter

Deep Compact 不必删除用户界面中的完整历史。

可以形成：

UI Conversation
      │
      │ 完整保存
      ▼
用户仍可查看完整历史


Model Prompt
      │
      │ Deep Compact
      ▼
只发送：
Summary
+
必要的近期历史

因此：

“界面里看起来有多少历史”与“本次请求真正发送多少历史”是两个不同维度。

这也是 Deep Compact 能够取得较低延迟的重要原因之一。

18. 为什么 Deep Compact 不是简单的“删聊天记录” Copy Chapter

普通清理（直接删除旧消息）会直接损失语义。

Deep Compact 的流转为：

旧历史 → 官方 Compact → Summary → 保留必要近期 Message Groups

因此被删除的是：

已经被 Summary 覆盖、且不再需要直接进入模型 Prompt 的原始历史。

而不是简单地“把前面的聊天记录砍掉”。

19. 模块独立性 Copy Chapter

Deep Compact 从设计开始就是独立模块。它不应该成为 Gateway 主流程的硬依赖，而应该是：

Core Gateway
      │
      ├── Normal Proxy
      │
      └── Optional Deep Compact

当 Deep Compact 未启用、Patch 失败、客户端版本不支持或 Gateway 状态异常时，都不应破坏普通代理功能。

20. Opt-in 与安全策略 Copy Chapter

Deep Compact 属于实验性客户端修改，因此采用 Opt-in（用户明确选择后才启用）。

同时遵循安全回滚流程：

原始客户端 → Backup → Patch

Patch 失败不应该导致整个 Gateway 不可用，而应该退化为：

Gateway 正常工作 + Deep Compact 不可用

这也是模块独立设计的重要意义。

21. Binary Patch 的边界 Copy Chapter

Binary Patch 并不意味着“任何 Claude Desktop 都可以随便修改”。需要考虑：

• 客户端版本；
• executable discovery；
• app bundle 路径；
• 文件锁；
• 更新机制；
• 签名；
• integrity check；
• macOS hardened runtime；
• 重新签名；
• patch offset；
• 等长替换；
• rollback。

目前 macOS 是主要实现平台。在 Windows/Linux 上：

pruning 函数本身的核心逻辑已经验证具有一致性，但客户端发现、路径锁定、签名/完整性以及平台特有工程仍未完成。

因此 Windows/Linux 目前不能描述成完整可用版本。

22. 为什么采用等长 Patch Copy Chapter

如果修改后的机器码长度与原机器码保持一致：

Before: AAAA BBBB CCCC DDDD
After:  AAAA XXXX YYYY DDDD

则不会因为插入/删除字节导致后续 offset 全部改变，降低了 Patch 的复杂度。

但：

等长 Patch 不等于“没有完整性风险”。

它只能解决二进制布局变化问题，不能自动保证签名仍然有效、Hardened Runtime 行为不变、更新程序不覆盖等。因此必须将 Binary correctness 与 Platform integrity 分开讨论。

23. 当前兼容性状态 Copy Chapter

24. 测试矩阵 Copy Chapter

完整工程测试应至少覆盖：

Context Size Copy Section

• 20K
• 50K
• 100K
• 200K
• 300K
• 500K

内容类型 Copy Section

• 纯文本
• 长对话
• Tool Call
• Tool Result
• MCP
• 图片
• Base64
• 大型单轮工具结果

状态机 Copy Section

正常请求 → 400 → Compact → Summary → Recovery Retry

并测试：

• 重复 400
• 并发请求
• 网络断开
• Compact 中断
• 客户端重启
• Gateway 重启
• Patch 失败
• Patch 回滚

25. 成功条件 Copy Chapter

不应该使用 num_msgs <= 10 作为成功标准，因为消息数量本身并不代表 Compact 是否成功。

更合理的语义条件是：

• Summary 已生成
• AND post_tokens < pre_tokens
• AND 达到目标 reduction / budget
• AND 属于当前 Compaction Generation
• AND Recovery Retry 已正确完成

这比单纯检查消息数量可靠得多。

26. 三层验证体系 Copy Chapter

项目中的结论应该分为三种：

• A. 已直接验证：例如 HTTP 400 可以触发 Cowork Compact。
• B. 已在特定版本验证：例如 August Client, October Client。
• C. 理论推导 / 尚未完成验证：例如所有未来 Claude Desktop 版本均兼容。

严禁把 C 类描述成 A 类。

27. 本项目真正的架构创新 Copy Chapter

本项目并不是简单修改 Claude，而是把 Compact 分成了几个独立层：

┌─────────────────────────────┐
│        User Intent          │
│          ./compact          │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│       Gateway Control       │
│  400 / State / Generation   │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│    Claude Native Compact    │
│        Summary Logic        │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│    Patched Deep Pruning     │
│    Remove 50% lower bound   │
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│       Smaller Prompt        │
│       Lower Latency         │
└─────────────────────────────┘

其中每一层只承担一个职责。

28. “如非必要，勿增实体”原则 Copy Chapter

整个设计遵循非常明确的工程原则：

能复用官方机制，就不重新实现。

• 不重新实现：Summary Generator
• 不重新实现：Claude Compact Protocol
• 不重新实现：Message Semantics
• 只修改：Retention Boundary

Gateway 也只负责：Trigger, State, Recovery。这使整个系统的改动面尽可能小。

29. 对旧报告的最终勘误 Copy Chapter

原报告最主要的问题并不是技术方向错误，而是没有把“为什么需要 Patch”讲清楚。应修改以下表述：

原来的隐含逻辑 Copy Section

需要 Deep Compact → 所以修改 Binary

正确逻辑 Copy Section

需要触发 Compact → Gateway Synthetic 400 即可
需要官方摘要 → 直接复用 Native Compact
需要比官方 Compact 更激进 → 发现官方 pruning 存在约 50% 保留下限
需要突破该下限 → Patch pruning function
Patch 后 → 得到真正的 Deep Compact

因此：

Binary Patch 不是整个系统的起点，而是解决官方 Compact 深度不足的最小必要修改。

这是旧报告必须修正的核心。

30. 最终架构定义 Copy Chapter

最终可以将本项目定义为：

Claude Desktop Cowork Deep Compact 是一种基于 Gateway Reactive Compact 与可选客户端 pruning patch 的上下文压缩架构。它通过兼容 Claude 原生 Compact 的 HTTP 400 触发机制进入官方 Compact 流程，复用官方 Summary 能力，同时通过修改客户端历史消息 pruning 函数解除官方一次 Compact 后约 50% 的上下文保留下限，使系统能够采用更激进的历史裁剪目标。

其核心不是自己做一个 Compact，而是：

• 让官方 Compact 继续负责“理解并总结过去”
• 让 Gateway 负责“什么时候进入 Compact”
• 让 Patch 负责“官方允许保留多少历史”

最终得到：

官方语义压缩 + 自定义历史保留深度 + 更小实际 Prompt + 低延迟

31. 结论 Copy Chapter

目前项目已经形成一个完整的、可解释的技术闭环：

Context Overflow
      ↓
Synthetic HTTP 400
      ↓
Claude Native Compact
      ↓
官方 Summary
      ↓
官方 pruning
      ↓
突破 50% retention limit
      ↓
Deep Pruning
      ↓
~35K 级工程目标
      ↓
显著减少实际 Prompt
      ↓
低延迟

实验已经证明：

在当前已验证的客户端版本和测试工作负载下，激进 Deep Compact 可以取得非常小的请求延迟，并保持良好的实际使用效果。

因此，本项目的技术价值并不是单纯“把上下文压得更小”。更准确地说，它实现的是：

在不重新实现 Claude Compact 语义摘要能力的前提下，解除官方历史保留策略的深度限制，并通过 Gateway 与客户端 Patch 的最小协作，使 Cowork 获得更激进、更低延迟的上下文管理能力。

当前版本定位为 Experimental / Opt-in：

• macOS 为主要实现平台；
• August / October 客户端已经验证；
• 其他客户端版本仍需继续验证；
• Windows/Linux 的 pruning 逻辑已确认，但客户端工程尚未完成；
• 模块具有独立性；
• Patch 失败不应影响普通 Gateway；
• Backup / Rollback 作为客户端修改的基础安全机制。

在这些边界条件下，Deep Compact 已经从“逆向实验”进入了一个具有实际性能收益、明确技术边界和可工程化路径的架构原型阶段。

CLAUDE OPUS 46 INTEGRATION (`docs/CLAUDE_OPUS_46_INTEGRATION.md`) Copy Section

Claude Opus 4.6 Thinking Integration

Overview Copy Chapter

This document describes the integration of Claude Opus 4.6 Thinking model into the Antigravity Proxy.

Changes Made Copy Chapter

Backend (Rust) Copy Section

model_mapping.rs

• Added direct mapping for claude-opus-4-6-thinking
• Added alias mappings: claude-opus-4-6, claude-opus-4-6-20260201
• Updated normalize_to_standard_id() to include the new model

request.rs

• Updated should_enable_thinking_by_default() to auto-enable thinking for Opus 4.6 models

Frontend (TypeScript/React) Copy Section

modelConfig.ts

• Added claude-opus-4-6-thinking entry with protectedKey: 'claude-opus'

useProxyModels.tsx

• Added model to the models array with group Claude 4.6

Usage Copy Chapter

API Request Example Copy Section

{
  "model": "claude-opus-4-6-thinking",
  "messages": [...]
}

Supported Aliases Copy Section

• claude-opus-4-6-thinking (canonical)
• claude-opus-4-6
• claude-opus-4-6-20260201

Notes Copy Chapter

• Thinking mode is auto-enabled for Opus 4.6 models
• Quota protection uses the shared claude-opus key
• No localization changes required (reuses existing keys)

CROSS VERSION TEST EVIDENCE (`docs/CROSS_VERSION_TEST_EVIDENCE.md`) Copy Section

官方 Claude Desktop (macOS / darwin-arm64) 跨版本微创注入与修剪算法逆向实测证据报告

本报告为 Antigravity Tools (Deep Compact) 针对官方 Claude 客户端在跨度数十个公开发布版本下的自动化实机逆向与等长 AST 微创注入验证白皮书。
实测版本数量: 21 个（覆盖从 2.1.110 到最新 2.1.287 的全周期版本）
验证结论: 21 / 21 全部 100% 通过验证
生成时间: 2026-10-03
测试环境: macOS Darwin arm64 (Apple Silicon)

一、验证目标与核心结论 Copy Chapter

1. AST 核心骨架 100% 稳定同构：
   实测覆盖的全部 21 个官方发布版本 中，尽管 esbuild / Rollup 打包生成的混淆函数名在不断漂移（见下方对照表：Gj1, h07, nI5, cy7, F07, qR5, T24, X62, M12, qM4, fG1, gC7, bC7, khf, G4e, k7e, uVe, XGe, MWe, pZe, yNt），但其修剪逻辑的核心 AST 骨架完全一致，特征匹配长度恒为严格等长的 135 字节。
2. 50% 膨胀死穴全版本存在：
   在所有 21 个版本中，函数尾部均无一例外包含：
   javascript Copy

   if (g >= n - 1) return Math.max(1, Math.floor(n / 2));

   直接证实了：无论官方哪个版本，只要未打补丁，其修剪算法必定强制保留前 50% 历史，单靠网络层 400 假报警绝对无法突破该下限！
3. 135 字节等长原位注入（35k 活跃预算）跨版本 100% 成功：
   所有版本均成功原位替换为 35k 活跃上下文硬预算，且文件物理体积 0 偏移漂移，macOS codesign 递归重签名 100% 成功；
4. 一键还原 0-diff 绝对无损：
   全部样本还原后校验 MD5，与官方 npm 纯净基线 100% 逐字节一致，证明方案绝对安全可逆。

二、21 个跨版本实测数据总览表 Copy Chapter

三、各版本逆向细节与原位替换实测证据 Copy Chapter

1. 版本 `2.1.110` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 201733664 字节 (192.4 MB)
• 原始 MD5: b08165d921ed1f653f539b51ab30f2e5
• 识别混淆函数: function Gj1(H, _, q)
• 物理偏移区间: 0x48C2E08 - 0x48C2E8F（精确 135 字节）
• 内部变量映射: 累加器 acc=K，计数器 cnt=O，索引 idx=T

[官方原生 135 字节代码]:

function Gj1(H,_,q){let K=0,O=0;for(let T=_-1;T>=0;T--)if(K+=H[T],O++,K>=q)break;if(O>=_-1)return Math.max(1,Math.floor(_/2));return O}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function Gj1(H,_,q){let s=0,g=0;for(let h=_-1;h>=0;h--)if(s+=H[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 201733664 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 b08165d921ed1f653f539b51ab30f2e5，与官方发布版 100% 0-diff 完全对齐。

2. 版本 `2.1.120` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 213981440 字节 (204.1 MB)
• 原始 MD5: 3ae72fdd1697ee29e967f7b71d6b4b52
• 识别混淆函数: function HQ1(H, _, q)
• 物理偏移区间: 0x49CDD90 - 0x49CDE17（精确 135 字节）
• 内部变量映射: 累加器 acc=K，计数器 cnt=O，索引 idx=T

[官方原生 135 字节代码]:

function HQ1(H,_,q){let K=0,O=0;for(let T=_-1;T>=0;T--)if(K+=H[T],O++,K>=q)break;if(O>=_-1)return Math.max(1,Math.floor(_/2));return O}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function HQ1(H,_,q){let s=0,g=0;for(let h=_-1;h>=0;h--)if(s+=H[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 213981440 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 3ae72fdd1697ee29e967f7b71d6b4b52，与官方发布版 100% 0-diff 完全对齐。

3. 版本 `2.1.131` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 217349888 字节 (207.3 MB)
• 原始 MD5: d84c46f3c60a146871a35e47c2ffba5b
• 识别混淆函数: function He1(H, _, q)
• 物理偏移区间: 0x49D4233 - 0x49D42BA（精确 135 字节）
• 内部变量映射: 累加器 acc=K，计数器 cnt=O，索引 idx=T

[官方原生 135 字节代码]:

function He1(H,_,q){let K=0,O=0;for(let T=_-1;T>=0;T--)if(K+=H[T],O++,K>=q)break;if(O>=_-1)return Math.max(1,Math.floor(_/2));return O}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function He1(H,_,q){let s=0,g=0;for(let h=_-1;h>=0;h--)if(s+=H[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 217349888 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 d84c46f3c60a146871a35e47c2ffba5b，与官方发布版 100% 0-diff 完全对齐。

4. 版本 `2.1.140` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 206069664 字节 (196.5 MB)
• 原始 MD5: afd59c75e7da5bac5fb25c1de70eb434
• 识别混淆函数: function AT5(H, _, q)
• 物理偏移区间: 0xB5BF8D2 - 0xB5BF959（精确 135 字节）
• 内部变量映射: 累加器 acc=K，计数器 cnt=O，索引 idx=T

[官方原生 135 字节代码]:

function AT5(H,_,q){let K=0,O=0;for(let T=_-1;T>=0;T--)if(K+=H[T],O++,K>=q)break;if(O>=_-1)return Math.max(1,Math.floor(_/2));return O}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function AT5(H,_,q){let s=0,g=0;for(let h=_-1;h>=0;h--)if(s+=H[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 206069664 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 afd59c75e7da5bac5fb25c1de70eb434，与官方发布版 100% 0-diff 完全对齐。

5. 版本 `2.1.150` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 213070752 字节 (203.2 MB)
• 原始 MD5: d24b8b561224ce85c715d4fb5eb0fdc7
• 识别混淆函数: function VAK(H, _, q)
• 物理偏移区间: 0xBFCB38A - 0xBFCB411（精确 135 字节）
• 内部变量映射: 累加器 acc=K，计数器 cnt=O，索引 idx=T

[官方原生 135 字节代码]:

function VAK(H,_,q){let K=0,O=0;for(let T=_-1;T>=0;T--)if(K+=H[T],O++,K>=q)break;if(O>=_-1)return Math.max(1,Math.floor(_/2));return O}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function VAK(H,_,q){let s=0,g=0;for(let h=_-1;h>=0;h--)if(s+=H[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 213070752 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 d24b8b561224ce85c715d4fb5eb0fdc7，与官方发布版 100% 0-diff 完全对齐。

6. 版本 `2.1.160` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 216146880 字节 (206.1 MB)
• 原始 MD5: 3b84333868e1d1c695c18d7c35247299
• 识别混淆函数: function cy7(H, _, q)
• 物理偏移区间: 0xC057953 - 0xC0579DA（精确 135 字节）
• 内部变量映射: 累加器 acc=K，计数器 cnt=O，索引 idx=T

[官方原生 135 字节代码]:

function cy7(H,_,q){let K=0,O=0;for(let T=_-1;T>=0;T--)if(K+=H[T],O++,K>=q)break;if(O>=_-1)return Math.max(1,Math.floor(_/2));return O}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function cy7(H,_,q){let s=0,g=0;for(let h=_-1;h>=0;h--)if(s+=H[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 216146880 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 3b84333868e1d1c695c18d7c35247299，与官方发布版 100% 0-diff 完全对齐。

7. 版本 `2.1.170` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 222102816 字节 (211.8 MB)
• 原始 MD5: faaa02e38ec63dca2a4a0c233637a6cf
• 识别混淆函数: function T07(H, _, q)
• 物理偏移区间: 0xC2901CF - 0xC290256（精确 135 字节）
• 内部变量映射: 累加器 acc=K，计数器 cnt=O，索引 idx=T

[官方原生 135 字节代码]:

function T07(H,_,q){let K=0,O=0;for(let T=_-1;T>=0;T--)if(K+=H[T],O++,K>=q)break;if(O>=_-1)return Math.max(1,Math.floor(_/2));return O}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function T07(H,_,q){let s=0,g=0;for(let h=_-1;h>=0;h--)if(s+=H[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 222102816 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 faaa02e38ec63dca2a4a0c233637a6cf，与官方发布版 100% 0-diff 完全对齐。

8. 版本 `2.1.181` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 215193056 字节 (205.2 MB)
• 原始 MD5: 394c2d1c78cc9d96c7f279ab5fc1e74d
• 识别混淆函数: function h2i(e, t, n)
• 物理偏移区间: 0xBBA9094 - 0xBBA911B（精确 135 字节）
• 内部变量映射: 累加器 acc=r，计数器 cnt=o，索引 idx=s

[官方原生 135 字节代码]:

function h2i(e,t,n){let r=0,o=0;for(let s=t-1;s>=0;s--)if(r+=e[s],o++,r>=n)break;if(o>=t-1)return Math.max(1,Math.floor(t/2));return o}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function h2i(e,t,n){let s=0,g=0;for(let h=t-1;h>=0;h--)if(s+=e[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 215193056 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 394c2d1c78cc9d96c7f279ab5fc1e74d，与官方发布版 100% 0-diff 完全对齐。

9. 版本 `2.1.190` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 217273568 字节 (207.2 MB)
• 原始 MD5: 572780d2ca0399d22b495c688eac2b84
• 识别混淆函数: function h8i(e, t, n)
• 物理偏移区间: 0xBD8FE64 - 0xBD8FEEB（精确 135 字节）
• 内部变量映射: 累加器 acc=r，计数器 cnt=o，索引 idx=s

[官方原生 135 字节代码]:

function h8i(e,t,n){let r=0,o=0;for(let s=t-1;s>=0;s--)if(r+=e[s],o++,r>=n)break;if(o>=t-1)return Math.max(1,Math.floor(t/2));return o}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function h8i(e,t,n){let s=0,g=0;for(let h=t-1;h>=0;h--)if(s+=e[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 217273568 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 572780d2ca0399d22b495c688eac2b84，与官方发布版 100% 0-diff 完全对齐。

10. 版本 `2.1.200` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 231708784 字节 (221.0 MB)
• 原始 MD5: a16a9eaa00e78c70a40240c40388abfa
• 识别混淆函数: function cKa(e, t, n)
• 物理偏移区间: 0xCDA1615 - 0xCDA169C（精确 135 字节）
• 内部变量映射: 累加器 acc=r，计数器 cnt=o，索引 idx=s

[官方原生 135 字节代码]:

function cKa(e,t,n){let r=0,o=0;for(let s=t-1;s>=0;s--)if(r+=e[s],o++,r>=n)break;if(o>=t-1)return Math.max(1,Math.floor(t/2));return o}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function cKa(e,t,n){let s=0,g=0;for(let h=t-1;h>=0;h--)if(s+=e[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 231708784 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 a16a9eaa00e78c70a40240c40388abfa，与官方发布版 100% 0-diff 完全对齐。

11. 版本 `2.1.210` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 241509968 字节 (230.3 MB)
• 原始 MD5: b6d57cbc618b3fdba8487848f5cfb823
• 识别混淆函数: function XTu(e, t, r)
• 物理偏移区间: 0xD128C77 - 0xD128CFE（精确 135 字节）
• 内部变量映射: 累加器 acc=n，计数器 cnt=o，索引 idx=i

[官方原生 135 字节代码]:

function XTu(e,t,r){let n=0,o=0;for(let i=t-1;i>=0;i--)if(n+=e[i],o++,n>=r)break;if(o>=t-1)return Math.max(1,Math.floor(t/2));return o}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function XTu(e,t,r){let s=0,g=0;for(let h=t-1;h>=0;h--)if(s+=e[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 241509968 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 b6d57cbc618b3fdba8487848f5cfb823，与官方发布版 100% 0-diff 完全对齐。

12. 版本 `2.1.220` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 256908272 字节 (245.0 MB)
• 原始 MD5: 30e4d87fac9c8a6b97f4cf33397a3e30
• 识别混淆函数: function Jsd(e, t, r)
• 物理偏移区间: 0xDE1A24C - 0xDE1A2D3（精确 135 字节）
• 内部变量映射: 累加器 acc=n，计数器 cnt=o，索引 idx=i

[官方原生 135 字节代码]:

function Jsd(e,t,r){let n=0,o=0;for(let i=t-1;i>=0;i--)if(n+=e[i],o++,n>=r)break;if(o>=t-1)return Math.max(1,Math.floor(t/2));return o}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function Jsd(e,t,r){let s=0,g=0;for(let h=t-1;h>=0;h--)if(s+=e[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 256908272 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 30e4d87fac9c8a6b97f4cf33397a3e30，与官方发布版 100% 0-diff 完全对齐。

13. 版本 `2.1.231` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 294720528 字节 (281.1 MB)
• 原始 MD5: dcae301dc3dba6a07b94cb16ea7dcc30
• 识别混淆函数: function xup(e, t, r)
• 物理偏移区间: 0xFCC6007 - 0xFCC608E（精确 135 字节）
• 内部变量映射: 累加器 acc=n，计数器 cnt=o，索引 idx=i

[官方原生 135 字节代码]:

function xup(e,t,r){let n=0,o=0;for(let i=t-1;i>=0;i--)if(n+=e[i],o++,n>=r)break;if(o>=t-1)return Math.max(1,Math.floor(t/2));return o}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function xup(e,t,r){let s=0,g=0;for(let h=t-1;h>=0;h--)if(s+=e[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 294720528 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 dcae301dc3dba6a07b94cb16ea7dcc30，与官方发布版 100% 0-diff 完全对齐。

14. 版本 `2.1.237` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 317091168 字节 (302.4 MB)
• 原始 MD5: d0b6d59c88e50a5b525c0ac20e62bfa6
• 识别混淆函数: function khf(e, t, r)
• 物理偏移区间: 0x111895AA - 0x11189631（精确 135 字节）
• 内部变量映射: 累加器 acc=n，计数器 cnt=o，索引 idx=i

[官方原生 135 字节代码]:

function khf(e,t,r){let n=0,o=0;for(let i=t-1;i>=0;i--)if(n+=e[i],o++,n>=r)break;if(o>=t-1)return Math.max(1,Math.floor(t/2));return o}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function khf(e,t,r){let s=0,g=0;for(let h=t-1;h>=0;h--)if(s+=e[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 317091168 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 d0b6d59c88e50a5b525c0ac20e62bfa6，与官方发布版 100% 0-diff 完全对齐。

15. 版本 `2.1.245` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 376109392 字节 (358.7 MB)
• 原始 MD5: 0da87ad56163079fc88dcaf9ce2cc14f
• 识别混淆函数: function e4n(e, t, n)
• 物理偏移区间: 0xC9C3B54 - 0xC9C3BDB（精确 135 字节）
• 内部变量映射: 累加器 acc=r，计数器 cnt=o，索引 idx=s

[官方原生 135 字节代码]:

function e4n(e,t,n){let r=0,o=0;for(let s=t-1;s>=0;s--)if(r+=e[s],o++,r>=n)break;if(o>=t-1)return Math.max(1,Math.floor(t/2));return o}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function e4n(e,t,n){let s=0,g=0;for(let h=t-1;h>=0;h--)if(s+=e[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 376109392 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 0da87ad56163079fc88dcaf9ce2cc14f，与官方发布版 100% 0-diff 完全对齐。

16. 版本 `2.1.250` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 206479552 字节 (196.9 MB)
• 原始 MD5: 0608214ee67da39e785d751b9589d3c9
• 识别混淆函数: function Nbt(e, t, r)
• 物理偏移区间: 0x99889E3 - 0x9988A6A（精确 135 字节）
• 内部变量映射: 累加器 acc=o，计数器 cnt=u，索引 idx=p

[官方原生 135 字节代码]:

function Nbt(e,t,r){let o=0,u=0;for(let p=t-1;p>=0;p--)if(o+=e[p],u++,o>=r)break;if(u>=t-1)return Math.max(1,Math.floor(t/2));return u}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function Nbt(e,t,r){let s=0,g=0;for(let h=t-1;h>=0;h--)if(s+=e[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 206479552 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 0608214ee67da39e785d751b9589d3c9，与官方发布版 100% 0-diff 完全对齐。

17. 版本 `2.1.260` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 198289440 字节 (189.1 MB)
• 原始 MD5: b71e21f261fa0dc23d0863a6954f4c97
• 识别混淆函数: function xYn(e, n, r)
• 物理偏移区间: 0x9CD8069 - 0x9CD80F0（精确 135 字节）
• 内部变量映射: 累加器 acc=o，计数器 cnt=d，索引 idx=f

[官方原生 135 字节代码]:

function xYn(e,n,r){let o=0,d=0;for(let f=n-1;f>=0;f--)if(o+=e[f],d++,o>=r)break;if(d>=n-1)return Math.max(1,Math.floor(n/2));return d}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function xYn(e,n,r){let s=0,g=0;for(let h=n-1;h>=0;h--)if(s+=e[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 198289440 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 b71e21f261fa0dc23d0863a6954f4c97，与官方发布版 100% 0-diff 完全对齐。

18. 版本 `2.1.270` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 207500480 字节 (197.9 MB)
• 原始 MD5: 5e3a18a36582b2a5a4e0a89176d71bdd
• 识别混淆函数: function Aer(e, n, r)
• 物理偏移区间: 0xA5617B1 - 0xA561838（精确 135 字节）
• 内部变量映射: 累加器 acc=s，计数器 cnt=d，索引 idx=m

[官方原生 135 字节代码]:

function Aer(e,n,r){let s=0,d=0;for(let m=n-1;m>=0;m--)if(s+=e[m],d++,s>=r)break;if(d>=n-1)return Math.max(1,Math.floor(n/2));return d}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function Aer(e,n,r){let s=0,g=0;for(let h=n-1;h>=0;h--)if(s+=e[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 207500480 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 5e3a18a36582b2a5a4e0a89176d71bdd，与官方发布版 100% 0-diff 完全对齐。

19. 版本 `2.1.280` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 217254576 字节 (207.2 MB)
• 原始 MD5: de782ed5fa747102302e57b0855aa135
• 识别混淆函数: function pEt(e, n, r)
• 物理偏移区间: 0xAAD52C8 - 0xAAD534F（精确 135 字节）
• 内部变量映射: 累加器 acc=s，计数器 cnt=g，索引 idx=h

[官方原生 135 字节代码]:

function pEt(e,n,r){let s=0,g=0;for(let h=n-1;h>=0;h--)if(s+=e[h],g++,s>=r)break;if(g>=n-1)return Math.max(1,Math.floor(n/2));return g}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function pEt(e,n,r){let s=0,g=0;for(let h=n-1;h>=0;h--)if(s+=e[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 217254576 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 de782ed5fa747102302e57b0855aa135，与官方发布版 100% 0-diff 完全对齐。

20. 版本 `2.1.285` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 223821616 字节 (213.5 MB)
• 原始 MD5: e46411d54292b2329124faee50276c80
• 识别混淆函数: function WOt(e, n, r)
• 物理偏移区间: 0xAFCA8E5 - 0xAFCA96C（精确 135 字节）
• 内部变量映射: 累加器 acc=s，计数器 cnt=g，索引 idx=h

[官方原生 135 字节代码]:

function WOt(e,n,r){let s=0,g=0;for(let h=n-1;h>=0;h--)if(s+=e[h],g++,s>=r)break;if(g>=n-1)return Math.max(1,Math.floor(n/2));return g}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function WOt(e,n,r){let s=0,g=0;for(let h=n-1;h>=0;h--)if(s+=e[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 223821616 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 e46411d54292b2329124faee50276c80，与官方发布版 100% 0-diff 完全对齐。

21. 版本 `2.1.287` 实测证据 Copy Section

• 官方包名: @anthropic-ai/[email protected]
• 文件体积: 227808000 字节 (217.3 MB)
• 原始 MD5: 5bc5ab235395a8ebdc5484ceb971891b
• 识别混淆函数: function yNt(e, n, r)
• 物理偏移区间: 0xB2E51C5 - 0xB2E524C（精确 135 字节）
• 内部变量映射: 累加器 acc=s，计数器 cnt=g，索引 idx=h

[官方原生 135 字节代码]:

function yNt(e,n,r){let s=0,g=0;for(let h=n-1;h>=0;h--)if(s+=e[h],g++,s>=r)break;if(g>=n-1)return Math.max(1,Math.floor(n/2));return g}

[注入 35k 预算等长微创补丁 (含注释填充，严格 135 字节)]:

function yNt(e,n,r){let s=0,g=0;for(let h=n-1;h>=0;h--)if(s+=e[h],g++,s>=35000)break;return g;}/*                                    */

• 注入结果: 🟢 成功原位注入，文件总大小保持 227808000 字节（0 偏移漂移）
• 代码重签名: 🔏 codesign --force --sign - 执行成功
• 安全可逆性: ⚪ 一键还原后校验 MD5 值为 5bc5ab235395a8ebdc5484ceb971891b，与官方发布版 100% 0-diff 完全对齐。

四、工程与安全启示 Copy Chapter

1. Structural AST 正则具有跨版本韧性：
   测试证实，基于 Structural AST 循环骨架（脱敏混淆名与入参名）的正则，在面对 Rollup/esbuild 产生的函数名大范围漂移时，依然具备 100% 的捕获率；
2. 无需为新版本维护静态函数名字典：
   维护者无需硬编码 khf 或 yNt，网关与客户端补丁工具可以通过 AST 结构化自动适配几乎所有次级微小更新；
3. 安全隔离机制保障无损升级：
   备份存放在 Bundle 外部隔离目录，既满足 Gatekeeper 密封性，又确保了无论何时用户都能 100% 一键回滚到原生未打补丁状态。

测试执行者: Antigravity-Manager Automated Test Harness
测试用例: test_cross_version_deep_compact_matrix (21 samples)

HAR NATIVE PROTOCOL ALIGNMENT AND BUG AUDIT (`docs/HAR_NATIVE_PROTOCOL_ALIGNMENT_AND_BUG_AUDIT.md`) Copy Section

Antigravity 抓包与原生应用逆向深度对齐分析报告

基于 `flows (6)`、原生应用 macOS App 及网关多协议转换全景代码审计 Copy Chapter

1. 调研背景与数据源 (Ground Truth Data Sources) Copy Chapter

本报告基于两大权威第一手数据源与当前项目源码进行交叉比对：

1. 抓包数据源 (flows (6))：
   • 捕获于 macOS 环境下原生 Antigravity IDE 真实网络流量；
   • 包含 2,060+ 个完整 HTTP/WebSocket 流，其中包含 359 次真实的 streamGenerateContent?alt=sse 上行上报与下行流式响应；
   • 覆盖真实多轮长会话（单会话高达 60+ 轮次）、模型中途切换（Gemini ↔ Claude 相互交替）、工具并发调用（26,695 次工具回执）；
   • 涉及 6 大核心模型系列：gemini-3.8-flash-low, gemini-3.1-flash-lite, gemini-2.5-flash-lite, claude-sonnet-4-6, tab_flash_lite_preview, tab_jump_flash_lite_preview。
2. 原生应用程序 (/Applications/Antigravity IDE.app)：
   • 逆向分析其核心语言服务二进制组件：Contents/Resources/app/extensions/antigravity/bin/language_server_macos_arm（Google 内部 JetSki / Cortex 架构 Go 编译二进制）；
   • 逆向分析前端扩展入口：Contents/Resources/app/extensions/antigravity/dist/extension.js；
   • 提取 fetchAvailableModels 接口返回的 33 个原生模型完整配置字典与元数据矩阵。
3. 被审计代码库 (Antigravity-Manager in src-tauri/)：
   • src-tauri/src/proxy/pipeline/inbound.rs（统一进站思考管线）
   • src-tauri/src/proxy/mappers/openai/request.rs（OpenAI 协议转译器）
   • src-tauri/src/proxy/mappers/claude/request.rs（Claude 协议转译器）
   • src-tauri/src/proxy/common/json_schema.rs（JSON Schema 清洗器）
   • src-tauri/src/proxy/cache_manager.rs（三层拆分上下文缓存管理器）
   • src-tauri/resources/official_models.json（官方模型配置表）

2. 抓包与原生请求参数全景图谱 (Native Request Specification) Copy Chapter

2.1 外层信封 (Outer Envelope & Headers) Copy Section

原生通信目标地址恒为：
POST https://daily-cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse

HTTP Headers 规范：

Host: daily-cloudcode-pa.googleapis.com
User-Agent: antigravity/ide/2.5.5 (aidev_client; os_type=darwin; arch=arm64)
Content-Type: application/json
Accept-Encoding: gzip
Transfer-Encoding: chunked

JSON 根级 Envelope 结构：

{
  "project": "aicode-consumers",
  "requestId": "agent/d08b2892-847c-41d9-9bd6-df72511b9f3c/1790410102432/0917011e-4959-4da9-8554-20499ed72869/3",
  "model": "gemini-3.8-flash-low",
  "userAgent": "antigravity",
  "requestType": "agent",
  "request": { ... }
}

• project：固定为 "aicode-consumers"。
• requestId：格式为 {requestType}/{client_instance_uuid}/{timestamp_ms}/{trajectory_id}/{step_index}。
• requestType：枚举包含 agent（编程助手交互）、checkpoint（会话总结保存）、chat（普通聊天）、tab（行内补全）、tab_jump（跳转补全）。
• request：核心内层载荷。

2.2 内部请求拓扑 (Inner Request Topology) Copy Section

原生报文严格遵循以下键序（对齐 TPU 隐式前缀缓存命中）：
$$\text{contents} \longrightarrow \text{systemInstruction} \longrightarrow \text{tools} \longrightarrow \text{toolConfig} \longrightarrow \text{labels} \longrightarrow \text{generationConfig} \longrightarrow \text{sessionId}$$

Labels 规范

{
  "last_step_index": "2",
  "model_enum": "MODEL_PLACEHOLDER_M320",
  "request_id": "0917011e-4959-4da9-8554-20499ed72869-2",
  "trajectory_id": "0917011e-4959-4da9-8554-20499ed72869",
  "used_claude": "false",
  "used_claude_conservative": "false",
  "used_non_gemini_model": "false"
}

3. 原生 17 个工具函数 Schema 与回执定义全景表 Copy Chapter

原生工具在请求报文的 tools 字段中，100% 格式化为单函数独立切片数组：
"tools": [ { "functionDeclarations": [ { "name": "tool1", ... } ] }, { "functionDeclarations": [ { "name": "tool2", ... } ] } ]
（原生 329 次带工具抓包中，独立切片占比 100%，聚合为一个大数组的占比为 0）。

所有参数 schema 均采用大写类型标记（OBJECT, STRING, INTEGER, BOOLEAN, ARRAY）。

3.1 完整工具函数定义矩阵 Copy Section

铁律 1（全工具 UI 状态元数据）：
全部 17 个原生工具的 required 列表中，无一例外全部强制包含 ["toolAction", "toolSummary"]。

• toolAction（动宾短语，如 "Analyzing directory", "Editing file"）
• toolSummary（名词短语，如 "Directory analysis", "File edit"）

铁律 2（工具执行回执信封标准）：
在抓包提取的全部 26,695 次工具执行结果中：
functionResponse.response 100% 为只包含一个 key 的 JSON 对象：

json Copy

{
  "functionResponse": {
    "id": "call_438678",
    "name": "run_command",
    "response": {
      "output": "Created At: 2026-09-28T...\nOutput:\n..."
    }
  }
}

response 中 0 次使用 "result" 键，100% 使用 "output" 键。

4. 核心不对等点深度剖析 (Multi-Model & Multi-Turn Asymmetries) Copy Chapter

本节聚焦用户最关心的不同模型与多轮会话参数不对等。通过对原生通信抓包与二进制逻辑的挖掘，提炼出四大关键不对等机理：

4.1 核心不对等 1：`functionResponse` 角色的绝对模型相关性（最严重漏洞点） Copy Section

通过对抓包内全部 26,695 个 functionResponse 进行分类统计，揭示出两大家族完全相反的协议规范：

Gemini 目标模型 (gemini-3.8-flash-low / gemini-3.1-flash-lite):
  - functionResponse in role: "model"  --> 25,817 次 (100.0%)
  - functionResponse in role: "user"   --> 0 次 (0.0%)

Claude 目标模型 (claude-sonnet-4-6):
  - functionResponse in role: "user"    --> 846 次 (100.0%)
  - functionResponse in role: "model"   --> 0 次 (0.0%)

原生会话地面真相：

1. Gemini 协议流：
   • Turn 0 (user): 用户输入需求
   • Turn 1 (model): 模型输出 functionCall（挂载 thoughtSignature）
   • Turn 2 (model): 客户端回传 functionResponse（角色依然是 model）
   • Turn 3 (model): 模型输出最终回答文本（挂载 thoughtSignature）
   • Turn 4 (user): 用户下一轮追问
2. Claude 协议流：
   • Turn 0 (user): 用户输入需求
   • Turn 1 (model): Claude 输出 functionCall（不带 thoughtSignature）
   • Turn 2 (user): 客户端回传 functionResponse（角色转为 user）
   • Turn 3 (model): Claude 接着输出结果
3. 跨模型切换的全局重写 (Global Rewriting on Switch)：
   抓包分析中，mixed_flows（单次请求中同时出现 user 和 model 的 functionResponse）的出现次数为 0。
   当原生会话中途从 Gemini 切换到 Claude 时，原生客户端将整个历史记录中所有的 functionResponse.role 统一重写为 user；反之切回 Gemini 时统一重写为 model。

4.2 核心不对等 2：思维链 (`thought`) 与思维签名 (`thoughtSignature`) 生命周期 Copy Section

1. Gemini 家族：
   • 上游 SSE 流式响应：在第 1 个 chunk 中即返回 thoughtSignature。
   • 多轮历史请求回传：在抓包的 54,373 个 Gemini 历史模型轮次中，带 thought: true 文本块的次数为 0。原生客户端在向 Gemini 序列化历史消息时，主动剥离了冗长的思考过程文本，仅将 thoughtSignature 挂载在首个有效非思考 part（如 functionCall 或普通正文 text）上。
2. Claude 家族：
   • 上游 SSE 流式响应：不产生 thoughtSignature，以 {"thought": true, "text": "..."} 文本块流式下发。
   • 多轮历史请求回传：Claude 历史轮次必须保留 {"thought": true, "text": "..."} 文本块（抓包中 33 次 Claude 思考块完整保留），且部件上绝对无 thoughtSignature。

4.3 核心不对等 3：`generationConfig` 极限与思考预算 Copy Section

通过抓取原生 fetchAvailableModels 权威数据字典与请求载荷比对：

4.4 核心不对等 4：`toolConfig` 状态机模式 Copy Section

• 常规智能体交互 (requestType == "agent")：
  只要声明了 tools，必配 toolConfig: { "functionCallingConfig": { "mode": "VALIDATED" } }。
• 会话断点总结 (requestType == "checkpoint")：
  即使声明了工具，原生显式配置：toolConfig: { "functionCallingConfig": { "mode": "NONE" } }。
• 代码补全与闲聊 (tab / tab_jump / chat)：
  绝不包含 tools，且 toolConfig 为 null。

5. 上下文与缓存治理机制深度剖析 (Context & Caching) Copy Chapter

5.1 隐式前缀缓存 (Implicit Prefix Caching) 的运行法则 Copy Section

抓包分析表明，原生通信中 cachedContent 或 cached_content 字段的出现次数为 0。
Google CloudCode PA 基础设施基于 TPU 集群内置的 透明隐式前缀缓存 (Implicit Prefix Caching)。
命中缓存的唯一条件是：前序字节 100% 逐字节（Byte-for-byte）一致。

破坏前缀缓存的常见陷阱：

1. JSON 对象键序漂移：未进行确定性拓扑排序；
2. 工具列表乱序：每次调用工具数组顺序发生变化；
3. 工具描述文本被随意修改或清洗；
4. 多轮历史中的思维链残留：如果保留了随机变化的旧 thinking 文本，将破坏后续所有轮次的前缀缓存。

5.2 现有三层缓存架构与实际原生需求的偏差 Copy Section

项目中 src-tauri/src/proxy/cache_manager.rs 设计了三层缓存：

• Layer 1 (SI Cache): raw instructions → sanitized text
• Layer 2 (Tools Cache): raw tools JSON → processed tools
• Layer 3 (Prefix Tracker): 尝试查找 cache_name 并注入 cachedContent

审计发现：

• Layer 3 在 openai/request.rs 第 1353 行尝试注入 "cachedContent": cache_name。
• 这是公有云 Gemini API (v1beta) 的显式缓存机制，在内部受限的 v1internal 接口上根本不受支持。一旦注入必然导致上游直接 400 崩溃。

6. 协议转换与工具清洗函数现状与漏洞点审计 Copy Chapter

经过对 Rust 后端各模块的逐行代码审计，定位出以下关键缺陷与安全隐患：

🔴 缺陷 1 (P0 核心漏洞)：`normalize_function_response_roles` 无差别将回执定死为 `role: "model"` Copy Section

• 定位：src-tauri/src/proxy/pipeline/inbound.rs 第 498 行 & 第 611 行。
• 代码现状：
  rust Copy

  pub fn normalize_function_response_roles(contents: &mut Vec<Value>) -> usize {
      // ...
      if all_response {
          let mut c = content;
          c["role"] = json!("model");
          out.push(c);
      }
  }

• 漏洞后果：
  当用户使用 Claude 客户端（如 Claude Code CLI、Roo Code 等）请求 claude-sonnet-4-6 时，所有工具回执被无条件强行改成 role: "model"。而抓包实证表明，Google 上游给 Claude 的通道要求 functionResponse 必须在 role: "user"。这一错位直接导致发往 Claude 的报文结构违法，引发上游 400 校验拒绝或上下文理解错乱。
• 修复方案：
  该函数必须接收 target_model: &str 参数。
  • 若 is_claude(target_model) 为真，则将连续工具回执归一化合并在 role: "user" 中；
  • 若为 Gemini 系列，则合并在 role: "model" 中。

🔴 缺陷 2 (P1 漏洞)：工具回执对象键名硬编码为 `"result"` 而非 `"output"` Copy Section

• 定位：
  • src-tauri/src/proxy/mappers/claude/request.rs 第 1391 行 & 第 1435 行：
    "response": {"result": merged_content}
  • src-tauri/src/proxy/mappers/openai/request.rs 第 798 行：
    "response": { "result": final_content }
  • src-tauri/src/proxy/pipeline/inbound.rs 第 448-450 行：
    仅在 !resp.is_object() 时才包装为 {"output": ...}，如果已经是包含 "result" 的 Object 则直接放行。
• 漏洞后果：
  原生模型接收到的所有原生工具回执 100% 为 {"output": "..."}，模型系统提示词也明确约定通过 output 字段解析工具运行结果。客户端回传 "result" 属于协议方言不一致，极易诱发模型误判工具未正确执行、反复调用或参数幻觉。
• 修复方案：
  在 inbound.rs 的通用清洗层进行无损归一化：若 response 包含 result 且不包含 output，自动将 result 平滑迁移至 output。

🔴 缺陷 3 (P1 隐患)：显式 `cachedContent` 注入代码残留 Copy Section

• 定位：src-tauri/src/proxy/mappers/openai/request.rs 第 1350-1363 行。
• 代码现状：
  rust Copy

  if let Some(cache_name) = cache_manager.lookup_prefix(&prefix_hash) {
      if let Some(req_obj) = final_body["request"].as_object_mut() {
          req_obj.insert("cachedContent".to_string(), json!(cache_name));
      }
  }

• 漏洞后果：
  v1internal 根本没有公开的 cachedContents/create 接口，抓包中原生 Antigravity IDE 出现该参数的次数为 0。目前是由于 lookup_prefix 永远未存入有效 cache_name 才侥幸未触发异常。此代码属于典型的外来臆测实现，一旦被触发必致上游 400。
• 修复方案：
  彻底移除对 cachedContent 的显式注入，全量依赖 Google TPU 集群的隐式字节流前缀缓存。

🟡 缺陷 4 (P2 缺陷)：Gemini 多轮历史未清理思维链文本 (`thought: true`) Copy Section

• 定位：src-tauri/src/proxy/pipeline/inbound.rs 第 223 行。
• 代码现状：
  管线仅剥离了占位符（如 ".", "...", 空字符串）思考块。对于客户端（如 Claude Code CLI 或自研前端）多轮带回的完整思考文本，依然作为 thought: true part 保留发给了 Gemini。
• 漏洞后果：
  原生抓包证明 Gemini 历史回传中绝对不带任何历史思考文本（0 / 54,373）。保留这些文本会浪费巨大的输入上下文 token，且容易引发跨轮次签名错位或 400。
• 修复方案：
  当目标模型是 Gemini 家族时，历史 model 轮的思考文本块一律丢弃，但必须提取其合法签名转移到该轮首个非思考部件（通常是 functionCall 或正文 text）上。

🟡 缺陷 5 (P2 缺陷)：官方模型配置表缺少 `tab_flash_lite_preview` Copy Section

• 定位：src-tauri/resources/official_models.json。
• 代码现状：
  配置表中仅存在 tab_jump_flash_lite_preview (MODEL_PLACEHOLDER_M28)，遗漏了原生抓包中频繁出现的行内补全模型 tab_flash_lite_preview (MODEL_PLACEHOLDER_M19)。
• 修复方案：
  在 official_models.json 补齐 tab_flash_lite_preview 及其元数据参数（maxOutputTokens: 4096, supportsThinking: false）。

🟡 缺陷 6 (P2 缺陷)：`toolConfig` 强行覆盖忽略 `checkpoint` 模式 Copy Section

• 定位：src-tauri/src/proxy/pipeline/inbound.rs 第 1095-1115 行。
• 代码现状：
  管线只要判定有 tools，就一律无条件构造或覆盖为 {"mode": "VALIDATED"}。
• 漏洞后果：
  在断点总结（checkpoint）请求中，原生必须配置 {"mode": "NONE"} 以防止总结阶段模型幻觉产生工具调用。管线强行覆盖为 VALIDATED 会破坏原生 checkpoint 行为。
• 修复方案：
  检查已有 toolConfig.functionCallingConfig.mode，若已经是 NONE 则保留，不强行覆盖为 VALIDATED。

7. 优化实施路线图 (Actionable Implementation Plan) Copy Chapter

遵循项目的 Pipeline First 核心架构原则，所有治理应在流水线阶段完成，确保四大协议适配器无需各写一套补丁：

客户端请求 (OpenAI / Claude / Gemini / Responses)
                       │
                       ▼
        四大协议适配器 (仅做协议语法映射)
                       │
                       ▼
    InboundThinkingPipeline (统一核心治理阶段)
    ┌──────────────────────────────────────────────────────────┐
    │ 1. normalize_tool_call_ids (call_... 归一化)             │
    │ 2. normalize_function_response_roles(contents, model)    │
    │    ├─ Claude 目标: 归一化为 role: "user"                │
    │    └─ Gemini 目标: 归一化为 role: "model"               │
    │ 3. normalize_function_response_envelope (result → output)│
    │ 4. 历史 thinking 文本过滤 (Gemini 剥离留签名, Claude 保留)│
    │ 5. align_google_request_prefix_topology_with_model       │
    │    ├─ 单函数独立切片排序 [ { functionDeclarations: [t] } ] │
    │    ├─ 大写 JSON Schema 类型 (OBJECT, STRING 等)          │
    │    ├─ 尊重既有 toolConfig mode (NONE 不覆盖)              │
    │    └─ 移除显式 cachedContent 注入死代码                   │
    └──────────────────────────────────────────────────────────┘
                       │
                       ▼
          Google v1internal 上游 (100% 协议同构)

通过落实上述实施方案，网关在应对不同客户端、跨模型动态切换以及复杂多轮工具调用场景时，将达到与原生 Antigravity IDE 100% 像素级对齐的鲁棒性。

JEIKL ANTIGRAVITY CLIENT CAPTURE (`docs/JEIKL_ANTIGRAVITY_CLIENT_CAPTURE.md`) Copy Section

jeikl Windows Antigravity 客户端抓包

来源：@jeikl 本机 Windows 原生 Antigravity 客户端（不是 Antigravity IDE）。

• 样本 1：docs/baogao.txt，模型 gemini-3.7-flash-high
• 样本 2：docs/样本2.txt（原 docs/报告2 并发和串行交接触发.txt），模型 gemini-3.8-flash-high
• 样本 3：docs/claude样本.txt，模型 claude-sonnet-4-6
• 客户端标识：userAgent = antigravity，requestType = agent
• 应用数据目录：C:\Users\Administrator\.gemini\antigravity
• 对照：作者 PR #3541 的 docs/HAR_NATIVE_PROTOCOL_ALIGNMENT_AND_BUG_AUDIT.md 依据的是 Antigravity IDE HAR
• 与作者差异的取少结论：docs/JEIKL_VS_AUTHOR_HAR_TAKE_DROP.md

三份报文的顶层键序、systemInstruction 骨架和 14 个工具声明相同。差别在目标模型家族：Gemini 的工具回执是 role: "model"，Claude 的工具回执是 role: "user"。并行/串行形态两种家族都有。

顶层字段 Copy Chapter

信封（request 之外）：

request 键序三份都是：

1. contents
2. systemInstruction
3. tools
4. labels
5. generationConfig
6. sessionId

没有 toolConfig，也没有 tool_config。三份 sessionId 都是 -3750763034362895579。

generationConfig：

labels 样本 1（Gemini）：

{
  "last_execution_id": "fb7b9c90-03c2-4e6f-983e-369ef8fc9e5e",
  "last_step_index": "20",
  "model_enum": "MODEL_PLACEHOLDER_M298",
  "request_id": "231efd36-2a13-4fea-ab31-04cc500a7ec2-9",
  "trajectory_id": "231efd36-2a13-4fea-ab31-04cc500a7ec2",
  "used_claude": "false",
  "used_claude_conservative": "false",
  "used_non_gemini_model": "false"
}

样本 3（Claude）同一套键，值为：

{
  "last_execution_id": "9648bd6f-4b24-495e-9b82-f5b59ecfa6cc",
  "last_step_index": "21",
  "model_enum": "MODEL_PLACEHOLDER_M35",
  "request_id": "a625a450-b0e2-435f-b99f-3c821f9149cc-8",
  "trajectory_id": "a625a450-b0e2-435f-b99f-3c821f9149cc",
  "used_claude": "true",
  "used_claude_conservative": "true",
  "used_non_gemini_model": "true"
}

原生 Claude 把 used_claude_conservative 设成 true。作者流水线写死成 false。

systemInstruction Copy Chapter

约 25KB 一段文本。开头身份和用户信息三份相同（Conversation ID 各会话不同）：

<identity>
You are Antigravity, a powerful agentic AI coding assistant designed by the Google Deepmind team working on Advanced Agentic Coding.
...
User requests are enclosed within <USER_REQUEST> tags.
</identity>
<user_information>
The USER's OS version is windows.
...
e:\code\Antigravity-Manager -> lbjlaq/Antigravity-Manager
App Data Directory: C:\Users\Administrator\.gemini\antigravity
</user_information>

后面按顺序还有：user_rules（嵌入本仓库 AGENTS.md）、skills、subagents、messaging、conversation_transcript、artifacts、slash_commands、guidelines、communication_style。systemInstruction.role 是 user。

用户轮次正文包在 里，后面跟 `<ADDITIONAL_METADATA>`。换模型时跟。

工具声明 Copy Chapter

三份都是 14 项。每一项单独一个对象，functionDeclarations 里只有一个函数。顺序是客户端原序，不是按名字排序：

1. view_file
2. run_command
3. manage_task
4. send_message
5. schedule
6. invoke_subagent
7. define_subagent
8. manage_subagents
9. write_to_file
10. replace_file_content
11. generate_image
12. read_url_content
13. search_web
14. ask_question

实际用到的只有 run_command。参数有 CommandLine、Cwd、WaitMsBeforeAsync、toolAction、toolSummary。回执是 response.output。

Gemini 的调用 id 是 call_...；Claude 是 toolu_vrtx_01...。Gemini 样本 WaitMsBeforeAsync 是 5000，Claude 样本是 3000。

分类：按模型家族的回执角色 Copy Chapter

这点和作者 IDE HAR 一致。桌面端也是按目标模型改写整段历史，不会在同一次请求里混用两种回执角色。

分类：并行 Copy Chapter

多次调用收在同一个 role: "model" content 里。对应回执收在紧跟着的一块里：Gemini 那块仍是 model，Claude 那块是 user。

样本 2 开头（Gemini 并行三次） Copy Section

用户：请你稍作思考后并发调用三个echo helloworld函数

同一块三个 functionCall（id call_1180168 / call_1180171 / call_1180174），下一块三个 functionResponse，stdout 都是 helloworld。

样本 1 后段（Gemini 并行三次） Copy Section

用户：请你并发调用三个工具hello

同一块三个 functionCall：Write-Output "hello 1/2/3"。下一块三个回执。

样本 3 开头和末段（Claude 并行三次） Copy Section

用户：你好 请你稍作思考后并行调用三个工具试试 只需要输出helloworld就可以了

contents[2] 一块四个 part：thought + 三个 functionCall（echo / node -e / python -c）。签名在第一个 functionCall 上，思考块和后两个调用没有签名。

contents[3] 一块三个 functionResponse，role: "user"。

末段用户：这次并行试试。contents[14]/[15] 同样是三个 FC 在 model、三个 FR 在 user。

分类：串行 Copy Chapter

每一次调用和它的回执各占一块，按调用、回执交替，不把多次串行调用并成一块。

样本 1 中段（Gemini 串行） Copy Section

用户：请你串行调用三个helloworld输出工具

样本 2 后段（Gemini 串行） Copy Section

用户：请你再串行调用三个试试。contents[5]–[10] 同样是 FC / FR 交替，全是 model。

样本 3 中段（Claude 串行） Copy Section

用户：请你再串行三个试试

Claude 串行轮可以在同一块里同时有正文和一次调用；仍然一次只出一个 functionCall，回执单独一块 user。

分类：连续 user Copy Chapter

样本 3 开头两条都是 role: "user"，没有插 model：

• contents[0]：同一句并行请求，切到 Claude Opus 4.6 Thinking
• contents[1]：同一句正文，再切到 Claude Sonnet 4.6 Thinking

两条独立 content，没有并成一块。作者删掉相邻 user 合并，这一点桌面端 Claude 样本支持。Gemini 两份没有连续 user。

思考块和签名 Copy Chapter

作者审计写 Claude「部件上绝对无 thoughtSignature」。样本 3 不是这样：并行时签名在首个 functionCall 上，串行第一步签名在正文上。流水线里对 Claude 轮会把非思考 part 上的签名剥掉，和这份桌面端报文不一致。

样本 1 完整对话 Copy Chapter

共 19 个 content。Cwd 都是 e:\code\Antigravity-Manager，WaitMsBeforeAsync 都是 5000。

样本 2 完整对话 Copy Chapter

共 11 个 content。同一条请求里先并行、再串行。

样本 3 完整对话 Copy Chapter

共 16 个 content。WaitMsBeforeAsync 都是 3000。

和 IDE 报告 / PR #3541 对照 Copy Chapter

三份 Windows 桌面端报文都支持「一个函数一块」的 functionDeclarations。Gemini 回执 model、Claude 回执 user、Claude maxOutputTokens: 64000 + thinkingBudget: 1024、连续 user 保持独立，这些和作者 HAR 一致。

它们都不支持下面这些已经合进 beta 的写法：

• 有 tools 时强制补 toolConfig.functionCallingConfig.mode = VALIDATED。三份都没有 toolConfig。
• 把 tools 按 name 字典序重排。三份都是上面的原序。
• 把 Claude 的 used_claude_conservative 写死成 false。样本 3 是 true。
• 断言 Claude 历史「绝对无 thoughtSignature」，并在流水线里剥掉。样本 3 把签名挂在该轮第一个非思考 part 上，和 Gemini 同一套落点。

JEIKL VS AUTHOR HAR TAKE DROP (`docs/JEIKL_VS_AUTHOR_HAR_TAKE_DROP.md`) Copy Section

jeikl 桌面端 vs 作者 Mac IDE：差异取少报告

对照双方原生 Antigravity 报文，只抽取有差异的字段；一致的沿用，有差异的取更少注入、更少改写、更少上下文的一侧。

• jeikl：Windows 原生客户端，见 docs/JEIKL_ANTIGRAVITY_CLIENT_CAPTURE.md（样本 docs/baogao.txt、docs/样本2.txt、docs/claude样本.txt）
• 作者：macOS Antigravity IDE HAR，见 docs/HAR_NATIVE_PROTOCOL_ALIGNMENT_AND_BUG_AUDIT.md，已随 PR #3541 合进 beta

「少」指少发给上游的字节和少做的网关发明。签名不是可删字段：思维链连续靠 thoughtSignature，思考正文可以少，签名不能少。

取舍原则（已拍板的三例） Copy Chapter

其余差异与最终取舍 Copy Chapter

A. 拓扑与工具声明 Copy Section

B. 思考与签名（和原则 1 配套） Copy Section

C. labels 与信封 Copy Section

D. 作者有、jeikl 这批 agent 样本没有的 Copy Section

E. 签名隔离（与报文拓扑无关） Copy Section

对 PR #3541 已合代码的含义 Copy Chapter

应留下：

• 工具切片（一块一函数）
• 按 target_model 把 FR 改成 Claude user / Gemini model
• 回执信封 result → output
• 连续 user 不合并
• 并行 FC/FR 打包
• Gemini 历史不回传思考正文；Claude 思考正文原文保留。签名都挂在该轮第一个非思考 part
• Claude 64000 / 1024，Gemini high -1
• 签名快照隔离、测试锁

应收回或不要做（相对已合进 beta 的写法）：

• 有 tools 就注入 toolConfig.VALIDATED
• tools 按名字排序
• 为插入 toolConfig 改内层键序
• 对 Claude 剥 thoughtSignature
• 把 used_claude_conservative 写死为 false
• 把调用 id 一律改成 call_...

一句话 Copy Chapter

官方认的是切片工具、按模型改回执角色、签名连续；不认的是多出来的 toolConfig、重排工具、思考正文、以及把 Claude 签名剥掉。差异取少：少发思考块、不发 toolConfig、回执角色跟作者（也跟 jeikl）那套 Claude/Gemini 分工。

RELEASE GUIDE (`docs/RELEASE_GUIDE.md`) Copy Section

Antigravity Tools 发版操作指南 (Release SOP)

发版详细规程。提交门禁与发版红线以根目录 AGENTS.md 为准。

一、流程概览 Copy Chapter

[通道 A: 正式版发布]
Pre-flight ─► checkout main ─► npm run bump <patch|minor> ─► 补充日志 ─► git push origin main ─► 打 Tag vX.Y.Z ─► 自动发布 Latest Release

[通道 B: Beta 预发布]
Pre-flight ─► checkout beta ─► npm run bump beta ──────────► 补充日志 ─► git push origin beta ─► 打 Tag vX.Y.Z-beta.N ─► 自动发布 Pre-release (隔离无感)

通道隔离与维护者协作原则：

• 正式版通道 (Main)：main 为绝对纯净正式打版分支，仅发布纯数字正式版本（如 v4.7.14），流水线严格拦截任何带 - 的预发标签。
• 预览版通道 (Beta)：beta 为独立预发布打版分支，所有预发测试版本（如 v4.7.14-beta.1、-cleaned 等）在此提交并由 beta 触发独立构建。预发布产物自动标记为 Pre-release 且绝不打 Latest，完全不影响正式版主用户更新。
• 新更改优先暂存验证 (Staging on Beta First)：凡涉及新功能、重大重构或高风险修复，必须主动询问维护者是否先在 beta 分支进行修改与验证。待验证稳定（或发布 Beta 预览版内测确认）后，方可合并进入 main。

二、操作步骤 Copy Chapter

第 0 步：发版前预检 (Pre-flight) Copy Section

确保工作区干净，且对将被标记的提交执行与 CI 完全一致的预检命令：

git checkout main && git pull origin main
git status          # 应显示 nothing to commit, working tree clean

cd src-tauri
cargo fmt -- --check
cargo clippy --all-targets --all-features
cd ..
npm run build

CI 门禁已全量覆盖 main 与 beta 分支。正式发布前确保在 main 预检通过，Beta 预发前确保在 beta 预检通过。

第 1 步：版本号原子同步 Copy Section

scripts/bump-version.mjs 一键同步全仓库版本号并生成 CHANGELOG 骨架：

可选参数：--dry-run 仅演练、不写盘；--commit 自动生成 chore(release): bump version to ... 提交。

同步范围：package.json、package-lock.json（根版本镜像，两处）、src-tauri/Cargo.toml、src-tauri/Cargo.lock、src-tauri/tauri.conf.json、Casks/antigravity-tools.rb、README.md、README_EN.md、src/components/layout/MiniView.tsx、src/pages/Settings.tsx、CHANGELOG.md、CHANGELOG_EN.md。

版本串匹配采用结构锚定而非精确匹配当前版本号：package-lock.json 按字段位置锚定，README 按 (v数字…) / Version-数字…-blue 形态锚定。这样即使历史轮次（如预发布跳过 README）造成版本串滞后，下一轮同步仍能正确命中。

内置防呆：目标版本必须严格高于当前版本，否则红色拦截，杜绝版本回退。

预发布版本号形态：npm run bump beta 生成 X.Y.Z-beta.N（首次为 beta.1，后续递增为 beta.2）。该版本串同时决定脚本插入的 CHANGELOG 骨架标题与后续 Tag 名，三者必须完全一致（详见第 2 步提示与第 4 步）。

第 2 步：回溯提交与补充更新日志 Copy Section

在填写更新日志前，必须以 Git 提交历史与已合入 PR 为客观事实依据进行完整回溯，严防遗漏贡献者署名或 Issue 关联：

# 1. 扫描上个版本以来的全部提交、Author 与 Co-Authored-By 署名
git log $(git describe --tags --abbrev=0)..HEAD --format="Commit: %h | %an <%ae> | %s%n%(trailers:key=Co-Authored-By)"

# 2. 列出在此期间合并的 PR 与关联 Issue
gh pr list --state merged --limit 20

根据盘点结果，在脚本插入的版本骨架中填写核心亮点：

• 强制关联 Issue / PR：条目标题必须包含对应的来源单号（如 (PR #3504) 或 (Fixes #3499, #3501)）；
• 强制行内致谢贡献者：从提交历史和 PR 中识别出的所有外部贡献者，必须以 (Thanks to @username) 形式显式标注在对应条目上。Release 页面的 Contributors 头像列表由此自动提取生成；
• 格式示例：

*   **版本演进**:
    *   **v4.7.14 (2026-09-23)**:
        -   **[核心分类] 功能重构与优化 (PR #3504)**:
            -   **功能详述**: 核心实现说明。
        -   **[核心分类] 涉及外部贡献的修复 (Fixes #3508, Thanks to @username)**:
            -   **功能详述**: 致谢与修复说明。

1. 标题必须与 Tag 逐字符一致：流水线用 awk 以 tag 名（github.ref_name，含 v 前缀）匹配 CHANGELOG 标题行，v 前缀与完整预发布后缀都要一字不差。npm run bump beta 自增出的版本号形如 X.Y.Z-beta.1，因此 Tag 应为 vX.Y.Z-beta.1（而非 vX.Y.Z-beta），标题也须写成 **vX.Y.Z-beta.1 (日期)**。不匹配时正文会静默退化为占位文案 See the assets to download this version and install.。
2. 已开启 generateReleaseNotes: true，GitHub 会自动追加 What's Changed 与 New Contributors（含 PR 链接与贡献者主页）。
3. 测试版不进入 README：Tag 含 - 的预发布 / 衍生版本（-beta / -cleaned / -rc 等）只在 CHANGELOG.md 记录，不得写入任何 README 的版本号、Shields 徽章或「最新版本」段落。README 始终只反映最新正式版。bump-version.mjs 已内置该判定：预发布版本自动跳过两个 README，仅同步其余版本配置文件。
4. 贡献者致谢写在条目行内：不单列致谢块，外部贡献者统一以 (Thanks to @username) 标注在对应条目上。Release 页的 Contributors 头像列表由正文中的 @username 自动生成 —— 增删提及即增删头像，条目内没有 @username 时该列表为空。
5. 正式版发版强制同步双语 README 更新日志：发布正式版时，除了更新 CHANGELOG.md（及 CHANGELOG_EN.md），还必须同步将最新正式版的重要更新摘要更新至 README.md（## 📝 更新日志）与 README_EN.md（## 📝 Changelog），严禁仅更新 CHANGELOG 而遗漏 README 首页的最新版本说明。

第 3 步：提交并推送目标分支 Copy Section

# 正式版：提交并推送到 main 分支
git checkout main
git add -A
git commit -m "chore(release): bump version to 4.7.14 and update changelog"
git push origin main

# Beta 预发版：提交并推送到 beta 分支（严禁推到 main，保持 main 纯净）
git checkout beta
git add -A
git commit -m "chore(release): bump version to 4.7.14-beta.1 and update changelog"
git push origin beta

第 4 步：打 Tag 并推送 Copy Section

# 正式版：从 main 打纯数字 Tag（触发正式发布，更新 Latest）
git tag v4.7.14
git push origin v4.7.14

# Beta 预发版：从 beta 打预发布 Tag（触发隔离构建，不更新 Latest）
git tag v4.7.14-beta.1
git push origin v4.7.14-beta.1

Tag 串必须与 CHANGELOG 中该版本的标题逐字符相同（v 前缀 + 完整预发布后缀），否则 Release 正文会退化为占位文案。

分支与标签严格门禁：流水线内置分支与标签匹配断言。

• 带有 - 的预发布 Tag 若打在 main 独有提交上，流水线立即拦截阻断，拒绝构建与发布；
• 不带 - 的正式版 Tag 若打在 beta 独有提交上，流水线立即拦截阻断。
• 预发布版本自动降级为 NSIS、不更新 Latest、不更新正式用户的 updater.json，主用户客户端绝不受任何影响。

第 5 步：验收 Copy Section

推送 Tag 后流水线自动接管，无需人工干预：

1. 进度：仓库 Actions 页的 Release 工作流；
2. 构建矩阵：Windows（.msi / NSIS .exe）、macOS（.dmg，Apple Silicon 与 Intel 双架构）、Linux（.AppImage / .deb / .rpm）、Docker 多架构镜像推送 Docker Hub；产出 updater.json（配置 TAURI_SIGNING_PRIVATE_KEY 时含签名）；
3. 验收：约 10~15 分钟后在 Releases 页确认 Antigravity Tools vX.Y.Z 及附件齐全。

三、异常与救急 Copy Chapter

1. 删除误打的 Tag Copy Section

git tag -d v4.7.14
git push origin :refs/tags/v4.7.14

2. 防呆保护报错 Copy Section

报错 ✗ 错误: 防呆保护生效：目标版本号 [...] 必须严格高于当前版本号 [...]！ 说明目标版本小于或等于当前版本。版本号必须严格单调递增，请传入更高版本（如 npm run bump patch）。

Adaptive Mode Test Examples (`docs/adaptive_mode_test_examples.md`) Copy Section

Claude 4.6 Adaptive Thinking Mode: 测试示例指南

为了验证 Claude 4.6 Adaptive (自适应) Thinking 模式的集成效果，特别是 effort 参数的生效情况及 Token 限制的自动调整，请参考以下测试场景。

1. 验证 Adaptive 模式激活与 Effort 控制 Copy Chapter

此测试验证系统能否正确传递 thinking: { type: "adaptive", effort: "..." } 参数，并观察模型行为差异。

前置条件 Copy Section

• 确保使用支持 Adaptive Thinking 的模型 ID (如 claude-opus-4-6-thinking 或映射后的 ID)。
• 在设置中将 "Thinking Budget" 模式设置为 "Adaptive (自适应)"。

测试指令示例 Copy Section

场景 A: Low Effort (低强度思考)

• 配置: 将 Effort 设置为 Low。
• 指令: 写一个并通过 Rust 编译的 Hello World 程序。
• 预期结果:
  • Thinking 块应该比较简短，模型认为这是一个简单任务，不需要深入推理。
  • 响应速度较快。

场景 B: High Effort (高强度思考)

• 配置: 将 Effort 设置为 High。
• 指令: 请详细分析 Rust 的 async/await 状态机生成机制，并对比 Go 的 Goroutine 调度模型。请通过思维链深入推导两者的内存开销差异。
• 预期结果:
  • Thinking 块应该非常长且详细（可能超过 5k tokens）。
  • 模型会尝试进行深度的对比分析和推理。
  • 关键验证点: 检查 Antigravity 日志，确认 generationConfig 中包含了 thinkingConfig: { type: "adaptive", effort: "high" }。

2. 验证多轮对话中的 Adaptive 状态维持 Copy Chapter

验证在多轮对话中，Adaptive 模式是否能持续生效，且 Token 限制 (128k) 是否正常工作。

场景：复杂算法设计迭代 Copy Section

Round 1: 初始设计

• 指令:
  bash Copy

  claude "设计一个分布式的高并发秒杀系统。需要考虑缓存一致性、库存防超卖、防刷接口等核心问题。请使用 High Effort 进行深度思考。"

• 验证点:
  • 生成了包含架构图和详细逻辑的设计文档。
  • Thinking 过程详细记录了对不同方案（如 Redis Lua vs 数据库悲观锁）的权衡。
  • 验证响应头或日志中，确认 maxOutputTokens 被提升至 128,000 (或更高)，以容纳长输出。

Round 2: 方案挑战 (模拟用户反馈)

• 指令:
  bash Copy

  claude "你的设计中，Redis 集群如果发生脑裂，如何保证库存数据的强一致性？请重新思考并修正方案。"

• 验证点:
  • Thinking 块继续保持深度推理，分析 Redlock 或其他一致性算法的适用性。
  • 签名验证: 确保多轮对话中 Thinking Block 的签名验证通过（无 Invalid signature 报错）。

Round 3: 代码实现

• 指令:
  bash Copy

  claude "请给出库存扣减核心逻辑的 Rust 代码实现。"

• 验证点:
  • 能生成符合之前设计思路的代码。
  • 在高上下文压力下，系统是否自动触发了 Thinking 剥离（如果配置了动态剥离），或者能够正常携带完整历史继续生成。

3. 验证 Budget 模式与 Adaptive 模式的自动切换 Copy Chapter

此测试验证当用户在“固定 Budget”与“Adaptive”模式间切换时，后端能否正确转换参数。

测试流程 Copy Section

1. 设置为 Fixed Budget: 在设置中选择 "Custom" 并设置 Budget 为 16384。

   • 发送请求。
   • 验证: 后端请求应只包含 thinkingConfig: { budget: 16384 }，不应包含 effort。

2. 切换为 Adaptive: 在设置中选择 "Adaptive" 并设置 Effort 为 Medium。

   • 发送请求。
   • 验证: 后端请求应只包含 thinkingConfig: { type: "adaptive", effort: "medium" }，不应包含 budget。

4. 调试建议 Copy Chapter

在运行上述测试时，建议开启 Debug 日志以观察参数传递：

RUST_LOG=debug npm run tauri dev

在日志中搜索关键词：

• [Claude-Request]: 查看转换后的请求体。
• thinkingConfig: 确认配置注入情况。
• maxOutputTokens: 确认 Token 上限调整情况。

Advanced Configuration (`docs/advanced_configuration.md`) Copy Section

高级配置与实验性功能 (Advanced Configuration)

Antigravity v3.3.35 引入了 ExperimentalConfig，这是一组默认开启的实验性功能开关，旨在提升系统的鲁棒性与兼容性。这些配置位于 src-tauri/src/proxy/config.rs 中，目前暂未暴露到 UI 界面。

功能列表 Copy Chapter

1. 双层签名缓存 (Signature Cache) Copy Section

• 配置项: enable_signature_cache
• 默认值: true
• 说明: 启用后，系统会缓存 ToolUse ID 与 Thought Signature 的映射关系。
• 作用: 解决部分客户端（如 Claude Desktop CLI, Cherry Studio）在多轮对话中可能丢失历史 Tool Call 签名的问题。当上游 API 报错 "Missing signature" 时，系统可从缓存中自动恢复，避免对话中断。

2. 工具循环自动恢复 (Tool Loop Recovery) Copy Section

• 配置项: enable_tool_loop_recovery
• 默认值: true
• 说明: 启用后，系统会实时监控对话状态，检测“死循环”模式。
• 触发条件: 检测到连续的 ToolUse -> ToolResult 循环，且 Assistant 消息中缺少 Thinking 块（通常因签名校验失败被 stripping）。
• 行为: 自动注入合成消息（Assistant: Tool execution completed. -> User: Proceed.）来打破死循环，强制模型进入下一轮思考。

3. 跨模型兼容性检查 (Cross-Model Checks) Copy Section

• 配置项: enable_cross_model_checks
• 默认值: true
• 说明: 防止在同一会话中切换不同系列模型（如 Claude -> Gemini）时引发的签名错误。
• 作用: 当检测到历史消息中的签名属于不兼容的模型家族（如 claude-3-5 vs gemini-2.0）时，系统会自动丢弃旧签名，防止 API 拒绝请求。