gemini-nexus/openspec/project.md

Project Context

Purpose

Antigravity Manager 是一个综合性的 Antigravity 增强工具，旨在打破 AI 开发的资源限制。它不仅解决了 Antigravity IDE 客户端无法原生支持多账号切换的痛点，还引入了企业级的 AI 服务账号池管理功能。通过接管应用的配置状态和云端 API 资源，它允许用户在无限个本地账号和云端 AI 服务之间无缝切换，实现 "无限" 的 AI 调用体验。

核心目标：

• 本地多账号切换：无缝切换 Antigravity IDE 的本地用户状态，保护数据完整性（自动备份）。
• AI 资源池管理（新）：集中管理 Google Gemini、Claude 3.5 等 AI 服务的账号池。
• 智能配额监控（新）：实时监控 API 配额（Quota）和健康度，提供可视化仪表盘。
• 自动资源调度（新）：当当前账号配额耗尽时，自动切换到最佳可用账号（Token 保活与轮询）。
• 跨平台支持：统一的 macOS、Windows、Linux 体验。

Tech Stack

• Electron 39 - 跨平台桌面应用框架
• React 19.2 - UI 框架
• TypeScript 5.9 - 类型安全的开发语言
• Shadcn UI - 现代化 UI 组件库
• Tailwind CSS 4 - 样式框架
• oRPC - 类型安全的 IPC 通信
• TanStack Router - 文件路由
• React Query - 服务器状态管理
• better-sqlite3 - SQLite 数据库访问
• Vite - 构建工具
• Vitest - 单元测试
• Playwright - 端到端测试
• Electron Forge - 应用打包和分发

Project Conventions

Code Style

• TypeScript strict mode
• ESLint + Prettier 自动格式化
• 函数和变量使用 camelCase
• 组件使用 PascalCase
• 接口使用 PascalCase，以 I 开头（可选）
• 类型使用 PascalCase
• 2 空格缩进
• 单引号字符串
• 尾随逗号

Architecture Patterns

src/
├── main.ts              # Electron 主进程
├── preload.ts           # 预加载脚本
├── renderer.ts          # 渲染进程入口
├── ipc/                 # IPC 通信层
│   ├── account/         # 本地 IDE 账号管理 IPC
│   ├── cloud/           # 云端 AI 资源管理 IPC（新）
│   ├── database/        # 数据库操作 IPC
│   └── process/         # 进程管理 IPC
├── services/            # 业务逻辑服务层（新）
│   ├── QuotaService.ts  # 配额监控服务
│   └── TokenService.ts  # Token 保活服务
├── actions/             # 渲染进程操作（oRPC 客户端）
├── components/          # React 组件
├── routes/              # 页面路由
├── layouts/             # 布局组件
├── utils/               # 工具函数
├── types/               # TypeScript 类型定义
└── tests/               # 测试文件

设计模式：

• 关注点分离：主进程处理系统操作和网络代理，渲染进程处理 UI。
• Service 层：引入 Service 层处理复杂的配额轮询和 Token 刷新逻辑。
• 类型安全 IPC：使用 oRPC 确保主进程和渲染进程之间的类型安全通信。
• 状态管理：React Query 管理服务器状态和异步配额数据。

Testing Strategy

• 单元测试（Vitest）：测试 IPC 处理程序、Service 逻辑、工具函数。
• 集成测试（Vitest）：测试完整的 IPC 流程。
• 端到端测试（Playwright）：测试用户工作流。
• 覆盖率目标：核心逻辑 >80%。

Git Workflow

• 主分支：main
• 开发分支：develop
• 提交规范：语义化提交 (feat, fix, docs, refactor, test, chore)

Domain Context

1. Antigravity IDE 数据结构（本地）

数据库位置：

• macOS: ~/Library/Application Support/Antigravity/User/globalStorage/state.vscdb
• Windows: %APPDATA%/Antigravity/User/globalStorage/state.vscdb
• Linux: ~/.config/Antigravity/User/globalStorage/state.vscdb

关键数据库键：

• antigravityAuthStatus: 认证状态和用户信息。

2. AI 服务资源结构（云端/新）

账号模型：

{
  "id": "uuid",
  "provider": "google" | "anthropic",
  "email": "[email protected]",
  "auth_token": "oauth2_token...",
  "refresh_token": "...",
  "quota_limit": 1000,
  "quota_used": 450,
  "reset_time": "ISO 8601",
  "status": "active" | "rate_limited" | "expired"
}

3. 进程管理策略

• 三阶段关闭：优雅关闭 -> SIGTERM -> SIGKILL。

Important Constraints

技术约束

• 数据库访问：访问本地 IDE 数据库时需注意文件锁。
• 网络访问：需要访问外部 API (Google/Anthropic) 以获取配额信息。
• 凭证安全：OAuth Token 和 Refresh Token 必须使用系统级加密存储 (Keytar / SQLite Encrypted)。
• 并发控制：轮询配额时需注意频率，避免触发 API 封控。

用户体验约束

• 响应时间：账号切换应在 5 秒内完成。
• 静默运行：支持最小化到托盘，后台自动刷新 Token。
• 数据安全：切换前必须自动备份当前状态。

External Dependencies

系统依赖

• Antigravity IDE：本地管理目标。
• SQLite：本地数据读取。

Node.js 依赖（重点）

• better-sqlite3: 数据库访问。
• electron: 桌面框架。
• node-fetch / axios: 网络请求。
• tar / adm-zip: 备份压缩。

外部服务

• Google Gemini API: 用于配额检查。
• Anthropic API: 用于配额检查。
• OAuth 2.0 端点: 用于账号授权。

文件系统依赖

• ~/.antigravity-agent/
  • accounts.json: 本地 IDE 账号索引。
  • cloud_accounts.db: (新) 云端账号池数据库 (SQLite)。
  • backups/: 备份文件。
  • app.log: 应用日志。