docs: translate repository documentation to English (#72)
This commit is contained in:
8 files changed
+456
-441
No files matched your search
+60
-60
@@ -1,96 +1,96 @@
|
||||
# 云端账号管理与智能切换 (Cloud Account Features)
|
||||
# Cloud Account Management and Intelligent Switching
|
||||
|
||||
本文档详细介绍了 Antigravity Manager 中实现的云端 AI 账号管理与切换功能。该功能允许用户管理多个 Google 账号，监控 API 配额，并一键无缝切换 IDE 的当前活动账号。
|
||||
This document explains the cloud AI account management and switching capabilities in Antigravity Manager. The feature allows users to manage multiple Google accounts, monitor API quotas, and seamlessly switch the active IDE account with one click.
|
||||
|
||||
## 1. 核心功能
|
||||
## 1. Core Features
|
||||
|
||||
### 1.1 账号池管理
|
||||
### 1.1 Account Pool Management
|
||||
|
||||
- **添加账号**：支持通过 Google OAuth 授权码添加账号。
|
||||
- **列表展示**：展示所有已添加的账号，包括头像、邮箱、最后使用时间。
|
||||
- **状态监控**：实时显示账号状态（Active, Rate Limited, Expired）以及是否为当前活动账号。
|
||||
- **删除账号**：支持从本地数据库中移除账号。
|
||||
- **Add accounts**: Add accounts via Google OAuth authorization code.
|
||||
- **List view**: Display all added accounts, including avatar, email, and last used time.
|
||||
- **Status monitoring**: Show real-time account status (Active, Rate Limited, Expired) and whether the account is currently active.
|
||||
- **Delete accounts**: Remove accounts from the local database.
|
||||
|
||||
### 1.2 配额实时监控
|
||||
### 1.2 Real-Time Quota Monitoring
|
||||
|
||||
- **多模型支持**：分别监控 `gemini-pro`, `claude-3-5-sonnet` 等模型的配额使用情况。
|
||||
- **可视化展示**：通过进度条和颜色（绿/黄/红）直观展示剩余配额百分比。
|
||||
- **自动/手动刷新**：支持手动刷新配额，系统也会在切换前自动检查。
|
||||
- **Multi-model support**: Track quota usage for models such as `gemini-pro`, `claude-3-5-sonnet`, and more.
|
||||
- **Visual indicators**: Use progress bars and color states (green/yellow/red) to show remaining quota percentage.
|
||||
- **Auto/manual refresh**: Support manual quota refresh; the system also checks quota automatically before switching.
|
||||
|
||||
### 1.4 智能自动切换 (Intelligent Auto-Switching)
|
||||
### 1.4 Intelligent Auto-Switching
|
||||
|
||||
- **无限池模式**：当检测到当前账号配额不足（<5%）或被限流时，系统会自动寻找最佳备用账号并切换。
|
||||
- **后台监控**：内置 `CloudMonitorService`, 默认每 5 分钟轮询一次所有账号的 Quota 状态。
|
||||
- **全局开关**：用户可在界面上一键开启或关闭此功能。
|
||||
- **Unlimited pool mode**: When the current account quota is low (`<5%`) or rate-limited, the system automatically finds and switches to the best backup account.
|
||||
- **Background monitoring**: Built-in `CloudMonitorService` polls quota status for all accounts every 5 minutes by default.
|
||||
- **Global toggle**: Users can enable or disable this feature with one click in the UI.
|
||||
|
||||
## 2. 技术实现
|
||||
## 2. Technical Implementation
|
||||
|
||||
### 2.1 数据库设计 (`cloud_accounts.db`)
|
||||
### 2.1 Database Design (`cloud_accounts.db`)
|
||||
|
||||
使用 SQLite 存储账号信息，独立于 IDE 的本地数据库。
|
||||
Account information is stored in SQLite, independent from the IDE's local database.
|
||||
|
||||
```sql
|
||||
CREATE TABLE accounts (
|
||||
id TEXT PRIMARY KEY, -- UUID
|
||||
provider TEXT NOT NULL, -- 'google' | 'anthropic'
|
||||
email TEXT NOT NULL, -- 邮箱
|
||||
name TEXT, -- 显示名称
|
||||
avatar_url TEXT, -- 头像 URL
|
||||
token_json TEXT NOT NULL, -- OAuth Token (JSON)
|
||||
quota_json TEXT, -- 配额数据 (JSON)
|
||||
created_at INTEGER NOT NULL, -- 创建时间戳
|
||||
last_used INTEGER NOT NULL, -- 最后使用时间戳
|
||||
status TEXT DEFAULT 'active', -- 账号状态
|
||||
is_active INTEGER DEFAULT 0 -- 是否为当前 IDE 活动账号
|
||||
email TEXT NOT NULL, -- Email
|
||||
name TEXT, -- Display name
|
||||
avatar_url TEXT, -- Avatar URL
|
||||
token_json TEXT NOT NULL, -- OAuth token (JSON)
|
||||
quota_json TEXT, -- Quota data (JSON)
|
||||
created_at INTEGER NOT NULL, -- Created timestamp
|
||||
last_used INTEGER NOT NULL, -- Last-used timestamp
|
||||
status TEXT DEFAULT 'active', -- Account status
|
||||
is_active INTEGER DEFAULT 0 -- Whether this is the currently active IDE account
|
||||
);
|
||||
|
||||
-- 全局配置表
|
||||
-- Global settings table
|
||||
CREATE TABLE settings (
|
||||
key TEXT PRIMARY KEY,
|
||||
value TEXT NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
### 2.2 IPC 接口设计
|
||||
### 2.2 IPC Interface Design
|
||||
|
||||
后端通过 `src/ipc/cloud` 提供以下 oRPC 接口：
|
||||
The backend exposes the following oRPC interfaces via `src/ipc/cloud`:
|
||||
|
||||
- `addGoogleAccount(authCode: string)`: 交换 Token 并保存账号。
|
||||
- `listCloudAccounts()`: 获取账号列表。
|
||||
- `refreshAccountQuota(accountId: string)`: 刷新指定账号的配额和 Token。
|
||||
- `switchCloudAccount(accountId: string)`: 执行账号切换流程。
|
||||
- `deleteCloudAccount(accountId: string)`: 删除账号。
|
||||
- `getAutoSwitchEnabled()` / `setAutoSwitchEnabled(enabled)`: 获取/设置自动切换开关。
|
||||
- `forcePollCloudMonitor()`: 手动触发后台轮询。
|
||||
- `addGoogleAccount(authCode: string)`: Exchange token and save account.
|
||||
- `listCloudAccounts()`: Get account list.
|
||||
- `refreshAccountQuota(accountId: string)`: Refresh quota and token for a specific account.
|
||||
- `switchCloudAccount(accountId: string)`: Run the account switch workflow.
|
||||
- `deleteCloudAccount(accountId: string)`: Delete an account.
|
||||
- `getAutoSwitchEnabled()` / `setAutoSwitchEnabled(enabled)`: Get/set auto-switch state.
|
||||
- `forcePollCloudMonitor()`: Manually trigger background polling.
|
||||
|
||||
### 2.3 Token 注入原理 (`ProtobufUtils`)
|
||||
### 2.3 Token Injection Mechanism (`ProtobufUtils`)
|
||||
|
||||
IDE 将鉴权信息存储在 `state.vscdb` 的 `ItemTable` 表中，key 为 `jetskiStateSync.agentManagerInitState`。
|
||||
value 是一个 Base64 编码的 Protobuf 二进制数据。
|
||||
The IDE stores authentication data in the `ItemTable` table of `state.vscdb`, under the key `jetskiStateSync.agentManagerInitState`.
|
||||
The value is Base64-encoded Protobuf binary.
|
||||
|
||||
我们实现了 `src/utils/protobuf.ts` 工具类，能够：
|
||||
We implemented `src/utils/protobuf.ts`, which can:
|
||||
|
||||
1. **解码**：解析 Varint 和 Length-Delimited 字段。
|
||||
2. **修改**：定位并移除旧的 Field 6 (OAuthTokenInfo)。
|
||||
3. **重构**：根据新的 Access Token 和 Refresh Token 构建新的 Field 6 并插入。
|
||||
1. **Decode**: Parse Varint and length-delimited fields.
|
||||
2. **Modify**: Locate and remove old Field 6 (`OAuthTokenInfo`).
|
||||
3. **Rebuild**: Build a new Field 6 using new access/refresh tokens and insert it.
|
||||
|
||||
### 2.4 切换流程
|
||||
### 2.4 Switching Workflow
|
||||
|
||||
1. **Token 检查**：检查目标账号 Token 是否临期，如需刷新则自动刷新。
|
||||
2. **停止进程**：优雅关闭 Antigravity 进程。
|
||||
3. **注入 Token**：调用 `CloudAccountRepo.injectCloudToken` 修改 IDE 数据库。
|
||||
4. **更新状态**：将目标账号标记为 `is_active = 1`，其他账号设为 0。
|
||||
5. **重启进程**：重新启动 IDE，使其加载新的凭证。
|
||||
1. **Token check**: Check whether the target account token is near expiration; refresh automatically if needed.
|
||||
2. **Stop process**: Gracefully stop the Antigravity process.
|
||||
3. **Inject token**: Call `CloudAccountRepo.injectCloudToken` to update the IDE database.
|
||||
4. **Update state**: Mark target account as `is_active = 1`, set others to `0`.
|
||||
5. **Restart process**: Restart the IDE so it loads new credentials.
|
||||
|
||||
### 2.5 自动切换逻辑 (`AutoSwitchService`)
|
||||
### 2.5 Auto-Switch Logic (`AutoSwitchService`)
|
||||
|
||||
1. **监控**：`CloudMonitorService` 定时（5分钟）轮询所有账号配额。
|
||||
2. **判断**：如果当前活动账号的所有关键模型配额低于 5%，或状态为 `rate_limited`。
|
||||
3. **择优**：从账号池中筛选状态为 `active` 且配额充足的账号，按配额剩余量排序。
|
||||
4. **执行**：自动调用 `switchCloudAccount` 完成切换，并通知用户。
|
||||
1. **Monitor**: `CloudMonitorService` polls quotas for all accounts every 5 minutes.
|
||||
2. **Evaluate**: If all key model quotas of the active account are below `5%`, or status is `rate_limited`.
|
||||
3. **Select**: Filter accounts with `active` status and sufficient quota, then sort by remaining quota.
|
||||
4. **Execute**: Automatically call `switchCloudAccount` and notify the user.
|
||||
|
||||
### 2.6 安全加固 (Security Hardening)
|
||||
### 2.6 Security Hardening
|
||||
|
||||
- **密钥管理**：使用操作系统原生凭据管理器（Windows Credential Manager / macOS Keychain）通过 `keytar` 库安全存储 Master Key（AES-256）。
|
||||
- **数据加密**：所有敏感数据（`token_json`, `quota_json`）在存入 SQLite 数据库前均使用 `AES-256-GCM` 算法加密。
|
||||
- **自动迁移**：应用启动时会自动检测并迁移旧的明文数据，确保安全性平滑升级。
|
||||
- **Key management**: Use native OS credential stores (Windows Credential Manager / macOS Keychain) via `keytar` to securely store the AES-256 master key.
|
||||
- **Data encryption**: Encrypt all sensitive fields (`token_json`, `quota_json`) with `AES-256-GCM` before writing to SQLite.
|
||||
- **Auto migration**: Automatically detect and migrate legacy plaintext data at startup to ensure a smooth security upgrade.
|
||||
Reference in new issue
Block a user