Compare commits

..
Author SHA1 Message Date
evandro e3652f43f5 docs(readme): padrão SaaS
Tests / Type Check (pull_request) Waiting to run
Lint / ESLint Check (pull_request) In progress
Check formatting / Prettier Format Check (pull_request) In progress
Tests / Unit Tests (pull_request) In progress
2026-11-16 00:02:29 -03:00
evandro 2a5d482c52 docs(readme): padroniza README (hero, badges, quickstart, arquitetura)
Release / Semantic Release (push) Successful in 11m32s
Tests / Unit Tests (push) Successful in 11m51s
Tests / Type Check (push) Successful in 11m32s
2026-10-24 04:13:00 +00:00
evandro 9d1ce44ea3 docs: redesign do README (padrão TwitterBR-MOD) — dados atualizados
Release / Semantic Release (push) Successful in 10m24s
Tests / Unit Tests (push) Successful in 10m51s
Tests / Type Check (push) Successful in 10m25s
2026-10-13 21:45:12 -03:00
40 changed files with 1430 additions and 1565 deletions

No files matched your search

+1 -1
View File
@@ -225,7 +225,7 @@ jobs:
fi
printf 'Uploading %s assets to %s\n' "${#files[@]}" "$RELEASE_TAG"
# Upload files sequentially with retries to prevent GitHub API rate limits and 404/502 errors
for file in "${files[@]}"; do
echo "Uploading $file..."
-1
View File
@@ -10,4 +10,3 @@ openspec/
.agent/
.claude/
.codex
pnpm-lock.yaml
-26
View File
@@ -2,32 +2,6 @@
# Changelog
## [0.15.5](https://github.com/evandrodevbr/GeminiNexus/compare/v0.15.4...v0.15.5) (2026-10-01)
### 🐛 Bug Fixes
* parse complete retry durations and preserve local IDE configuration ([b193bee](https://github.com/evandrodevbr/GeminiNexus/commit/b193bee03f1aaea5f7173e53ec6cdb787717067c))
### ✅ Tests
* mock OS exports consistently and verify LAN discovery ([fa39fb3](https://github.com/evandrodevbr/GeminiNexus/commit/fa39fb34fef662c11cd8780b562fa8008b982823))
## [0.15.4](https://github.com/evandrodevbr/GeminiNexus/compare/v0.15.3...v0.15.4) (2026-09-14)
### 📝 Documentation
* establish dual license (CC-BY-NC-SA + MIT) and correct attribution ([42466c2](https://github.com/evandrodevbr/GeminiNexus/commit/42466c274b36b5dde2d7d33c9016b2fab05cf551))
* refine READMEs and highlight Windows SmartScreen warning ([0dbae81](https://github.com/evandrodevbr/GeminiNexus/commit/0dbae81353c162b0b95d566493164ea6c02e2fa2))
* rewrite the README with verified behavior and honest limitations ([acb8508](https://github.com/evandrodevbr/GeminiNexus/commit/acb8508bff2f6e32691f394d21d7c8193608cd5e))
### 💄 Styles
* clear the lint and prettier findings so the gates pass ([8ad3eef](https://github.com/evandrodevbr/GeminiNexus/commit/8ad3eef53d88d049a3a25cb54df590073a67b75b))
### 🔧 Continuous Integration
* upload release assets sequentially with retry ([b13f06c](https://github.com/evandrodevbr/GeminiNexus/commit/b13f06c0a3538ff962eae2f6fc07cfc81281bf02))
## [0.15.3](https://github.com/evandrodevbr/GeminiNexus/compare/v0.15.2...v0.15.3) (2026-05-02)
### 👷 Build System
+201 -276
View File
@@ -1,337 +1,262 @@
<p align="center">
<img src="docs/assets/logo.png" alt="Gemini Nexus" width="128" height="128" />
</p>
<div align="center">
<h1 align="center">Gemini Nexus</h1>
<img src="assets/readme/hero.es.png" width="100%" alt="Gemini Nexus: gateway de escritorio que agrupa cuentas de Google tras una API local compatible con OpenAI y Anthropic en http://localhost:8045/v1, y cambia de cuenta cuando se agota la cuota">
<p align="center">
<strong>🚀 Gateway de IA multi-cuenta profesional para Google Gemini y Claude</strong>
</p>
![Stack](https://img.shields.io/badge/Stack-Electron_41_%C2%B7_React_19-47848F?logo=electron&logoColor=white)
![Status](https://img.shields.io/badge/status-v0.15.3_active-brightgreen)
![License](https://img.shields.io/badge/license-CC_BY--NC--SA_4.0_%2B_MIT-lightgrey)
<p align="center">
<a href="README.md">English</a> | <a href="README.pt-BR.md">Português</a> | <a href="README.zh-CN.md">中文</a> | Español
</p>
<p><strong><a href="#-inicio-rápido">Inicio rápido</a></strong> · <a href="#-documentación-y-desarrollo">Docs</a> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Issues</a></p>
<p align="center">
<a href="https://github.com/evandrodevbr/GeminiNexus/releases">
<img src="https://img.shields.io/github/v/release/evandrodevbr/GeminiNexus?style=flat-square" alt="Versión" />
</a>
<a href="https://github.com/evandrodevbr/GeminiNexus/releases">
<img src="https://img.shields.io/github/downloads/evandrodevbr/GeminiNexus/total?style=flat-square&color=blue" alt="Descargas" />
</a>
<a href="https://github.com/evandrodevbr/GeminiNexus/blob/main/LICENSE">
<img src="https://img.shields.io/github/license/evandrodevbr/GeminiNexus?style=flat-square" alt="Licencia" />
</a>
<img src="https://img.shields.io/badge/plataforma-Windows%20%7C%20macOS%20%7C%20Linux-informational?style=flat-square" alt="Plataforma" />
<img src="https://img.shields.io/badge/electron-latest-47848F?style=flat-square&logo=electron&logoColor=white" alt="Electron" />
</p>
<sub><a href="README.md">English</a> · <a href="README.pt-BR.md">Português</a> · <a href="README.zh-CN.md">中文</a> · Español</sub>
> [!IMPORTANT]
> **Usuarios de Windows:** Si ves una advertencia de SmartScreen **"Windows protegió su PC"** durante la instalación, haz clic en **"Más información"** y luego en **"Ejecutar de todas formas"**. Esta es una advertencia de seguridad esperada para aplicaciones nuevas no firmadas.
</div>
---
## 📸 Capturas de pantalla
## 📖 Tabla de Contenidos
<p align="center"><img src="docs/assets/main.png" width="100%" alt="Página Accounts: una cuenta de Google en el pool con barras de cuota por modelo, el interruptor Auto-Switch y el contador de cuota global"></p>
- [✨ ¿Por qué Gemini Nexus?](#-por-qué-gemini-nexus)
- [🎯 Características](#-características)
- [📸 Capturas de Pantalla](#-capturas-de-pantalla)
- [⚡ Instalación e Inicio Rápido](#-instalación-e-inicio-rápido)
- [🛠️ Stack Tecnológico](#️-stack-tecnológico)
- [💻 Desarrollo](#-desarrollo)
- [❓ Preguntas Frecuentes](#-preguntas-frecuentes)
- [🤝 Contribuir](#-contribuir)
- [📄 Licencia](#-licencia)
<details>
<summary>Más capturas: uso, proxy, enrutamiento, docs, conexiones, ajustes</summary>
---
<p align="center"><img src="docs/assets/2usage.png" alt="Analítica de uso" width="80%"></p>
<p align="center"><img src="docs/assets/3proxy.png" alt="Monitor del proxy" width="80%"></p>
<p align="center"><img src="docs/assets/4routing.png" alt="Configuración de enrutamiento" width="80%"></p>
<p align="center"><img src="docs/assets/5docs.png" alt="Documentación" width="80%"></p>
<p align="center"><img src="docs/assets/6connections.png" alt="Conexiones activas" width="80%"></p>
<p align="center"><img src="docs/assets/7config.png" alt="Ajustes" width="80%"></p>
## ✨ ¿Por qué Gemini Nexus?
Al usar IDEs y herramientas de programación con IA, ¿te has encontrado con estos problemas?
- 😫 **Límites de cuota:** La cuota de una sola cuenta se agota rápido, requiriendo cambios manuales frecuentes.
- 🔄 **Gestión de cuentas:** Gestionar múltiples cuentas de Google/Claude es tedioso.
- 📊 **Uso a ciegas:** No sabes cuántos tokens has consumido o cuánta cuota queda.
- 🔌 **Problemas de integración:** Necesitas un proxy local confiable que hable los protocolos OpenAI/Anthropic de forma nativa.
- 🔍 **Falta de transparencia:** No puedes ver qué se envía o recibe exactamente a través del proxy.
**Gemini Nexus** resuelve todo esto. Es una aplicación de escritorio profesional en Electron que actúa como gateway inteligente entre tus herramientas de desarrollo y Google Gemini / Claude AI.
### Propuesta de Valor
- ✅ **Pool de Cuentas Ilimitado** — Agrega cualquier cantidad de cuentas Google Gemini y Claude.
- ✅ **Cambio Automático Inteligente** — Rota automáticamente a la siguiente cuenta disponible cuando la cuota es baja o hay rate limit.
- ✅ **Analytics de Uso en Tiempo Real** — Dashboard nivel SaaS con gráficos de área, indicadores de tendencia y distribución por modelo.
- ✅ **Observabilidad Completa del Proxy** — Monitor de tráfico en vivo, replay de solicitudes e inspector de capacidades de modelos.
- ✅ **Compatible con OpenAI y Anthropic** — Proxy drop-in para Cursor, Windsurf, OpenCode y cualquier herramienta compatible con OpenAI.
- ✅ **Seguro por Defecto** — Cifrado AES-256-GCM con gestión nativa de credenciales del sistema operativo.
---
</details>
## 🎯 Características
Trabajar con IDEs con IA sobre una sola cuenta de Google significa cuota que se agota, cambios de cuenta manuales y ninguna visibilidad de lo que el proxy envía hacia arriba. Gemini Nexus reúne todas las cuentas en un pool y las sirve por un único endpoint local.
<table>
<tr>
<td width="50%">
<h3>☁️ Pool de Cuentas en la Nube</h3>
<ul>
<li>Agrega cuentas ilimitadas de Google Gemini / Claude vía OAuth</li>
<li>Muestra avatar, email, estado y último uso</li>
<li>Monitoreo de estado en tiempo real (Activa, Rate Limited, Expirada)</li>
<li>Configuración de proxy URL por cuenta</li>
<li>Gestión de perfil de identidad del dispositivo con historial</li>
</ul>
</td>
<td width="50%">
<h3>📊 Dashboard de Analytics de Uso</h3>
<ul>
<li>Consumo de tokens en tiempo real con auto-refresh cada 15s</li>
<li>Gráficos de área para tokens de prompt y completion (diario/horario)</li>
<li>Indicadores de tendencia (% de cambio vs período anterior)</li>
<li>Sparklines inline en las tarjetas de estadísticas</li>
<li>Ranking de distribución por modelo con gráficos de barras horizontales</li>
<li>Visualización de proporción Prompt/Completion</li>
</ul>
</td>
</tr>
<tr>
<td width="50%">
<h3>🔌 Proxy de API Local (Gateway)</h3>
<ul>
<li>Endpoint compatible con OpenAI <code>/v1/chat/completions</code></li>
<li>Endpoint compatible con Anthropic <code>/v1/messages</code></li>
<li>Soporte completo de streaming SSE (probado con Cursor, Windsurf, OpenCode)</li>
<li>Mapeo de modelos (ej: <code>claude-sonnet-4-6</code> → <code>gemini-3-flash</code>)</li>
<li>Puerto, timeout y API key configurables</li>
<li>Control de visibilidad de modelos</li>
</ul>
</td>
<td width="50%">
<h3>🔄 Cambio Automático Inteligente</h3>
<ul>
<li>Modo pool ilimitado con selección inteligente de respaldo</li>
<li>Cambio automático cuando cuota < 5% o con rate limit</li>
<li>Monitoreo en segundo plano cada 5 minutos</li>
<li>Fallback elegante con seguimiento de razón de estado</li>
</ul>
</td>
</tr>
<tr>
<td width="50%">
<h3>🔍 Observabilidad del Proxy (Avanzado)</h3>
<ul>
<li><strong>Monitor de Tráfico</strong> — Log en vivo de solicitudes/respuestas con latencia y modelo</li>
<li><strong>Replay de Solicitudes</strong> — Reproduce cualquier solicitud para debugging</li>
<li><strong>Capacidades de Modelos</strong> — Inspecciona soporte de visión, thinking, streaming, modo JSON</li>
<li><strong>Herramientas para Devs</strong> — Generación de código cURL y Python, copia con un clic</li>
</ul>
</td>
<td width="50%">
<h3>🔐 Seguridad y Cifrado</h3>
<ul>
<li>Cifrado AES-256-GCM para todos los datos sensibles</li>
<li>Integración con gestor de credenciales nativo del SO (Keytar + SafeStorage)</li>
<li>Migración automática de datos legacy en texto plano</li>
<li>Almacenamiento cifrado de tokens y cuotas por cuenta</li>
</ul>
</td>
</tr>
<tr>
<td width="50%">
<h3>⚙️ Configuración y Personalización</h3>
<ul>
<li>Soporte de temas Oscuro / Claro / Sistema</li>
<li>Multi-idioma: English & Português (Brasil)</li>
<li>Override de proxy URL por cuenta</li>
<li>Toggles de visibilidad de modelos</li>
<li>Acceso al directorio de logs</li>
</ul>
</td>
<td width="50%">
<h3>🖥️ Experiencia de Escritorio</h3>
<ul>
<li>App nativa Electron con integración en bandeja del sistema</li>
<li>Sidebar colapsable con estado persistente</li>
<li>Layouts responsivos en todas las vistas</li>
<li>Barra de estado con indicadores en vivo de proxy y conexión</li>
<li>Error boundaries con fallbacks amigables al usuario</li>
</ul>
</td>
</tr>
<tr>
<td width="50%" valign="top"><b>Un endpoint local</b><br><code>POST /v1/chat/completions</code> (OpenAI), <code>POST /v1/messages</code> (Anthropic), <code>GET /v1/models</code> y <code>GET /v1/models/capabilities</code>, para que Cursor, Windsurf, OpenCode, Claude Code y clientes similares puedan conectarse. Los nombres de modelo se mapean con <code>custom_mapping</code> y <code>anthropic_mapping</code>.</td>
<td width="50%" valign="top"><b>Pool de cuentas</b><br>Cuentas de Google añadidas por OAuth, cada una con su estado (Active, Rate Limited, Expired), hora del último uso y una URL de proxy opcional por cuenta.</td>
</tr>
<tr>
<td width="50%" valign="top"><b>Cambio automático</b><br><code>CloudMonitorService</code> consulta la cuota cada 5 minutos y <code>AutoSwitchService</code> pasa a otra cuenta cuando la cuota baja del 5 % o la cuenta sufre rate limit.</td>
<td width="50%" valign="top"><b>Planificación con circuit breaker</b><br><code>cache-first</code>, <code>balance</code> (por defecto) o <code>performance-first</code>, con circuit breaker por cuenta (backoff por defecto 60 s → 5 min → 30 min → 2 h).</td>
</tr>
<tr>
<td width="50%" valign="top"><b>Uso y coste</b><br>Consumo de tokens por cuenta y por modelo, gráficos de prompt y completion y estimación de coste con precios por modelo editables.</td>
<td width="50%" valign="top"><b>Inspector de tráfico</b><br>Latencia, estado y modelo de cada petición, replay de peticiones registradas, snippets cURL y Python generados y un Quick Setup para IDEs.</td>
</tr>
</table>
---
Las credenciales guardadas se cifran con AES-256-GCM bajo una clave maestra en el llavero del sistema (ver [Modelo de seguridad](#modelo-de-seguridad)).
## 📸 Capturas de Pantalla
## Cómo funciona
<p align="center">
<img src="docs/assets/main.png" alt="Main" width="80%" />
</p>
<p align="center">
<img src="docs/assets/2usage.png" alt="Usage" width="80%" />
</p>
<p align="center">
<img src="docs/assets/3proxy.png" alt="Proxy" width="80%" />
</p>
<p align="center">
<img src="docs/assets/4routing.png" alt="Routing" width="80%" />
</p>
<p align="center">
<img src="docs/assets/5docs.png" alt="Docs" width="80%" />
</p>
<p align="center">
<img src="docs/assets/6connections.png" alt="Connections" width="80%" />
</p>
<p align="center">
<img src="docs/assets/7config.png" alt="Config" width="80%" />
</p>
1. **Añade cuentas.** Inicia sesión con Google OAuth en la página Accounts. Los tokens se cifran antes de llegar a SQLite.
2. **Apunta tu IDE al proxy.** Activa el proxy en la página Proxy (viene apagado) y usa `http://localhost:8045/v1` con la API key que se muestra allí, en formato OpenAI o Anthropic.
3. **Nexus enruta cada petición.** El token manager elige una cuenta según el modo de planificación y el estado del circuit breaker, llama a las APIs upstream de Google con el token OAuth de esa cuenta, y el cambio automático actúa cuando la cuota baja del 5 % o una cuenta sufre rate limit.
---
El flujo completo, con los componentes implicados, está en [Arquitectura](#arquitectura).
## ⚡ Instalación e Inicio Rápido
## ⚡ Inicio rápido
### 📦 Descarga
Todavía no hay descargas precompiladas en la página de [Releases de Gitea](https://git.evandro.dev.br/evandro/gemini-nexus/releases) (los workflows de release en `.github/workflows/` apuntan a GitHub), así que compila desde el código fuente.
Puedes descargar los binarios precompilados más recientes para Windows, macOS y Linux desde nuestra [página de Releases](https://github.com/evandrodevbr/GeminiNexus/releases).
_(Consulta la advertencia en la parte superior de esta página si usas Windows y te encuentras con el aviso de SmartScreen)._
### 🔌 Uso con IDEs de IA
Con la aplicación en ejecución y al menos una cuenta agregada, configura tu IDE preferido (Cursor, Windsurf, OpenCode, etc.):
```plaintext
API Base URL: http://localhost:10100/v1
API Key: (copiar de la página Proxy en la app)
Model: gemini-3-flash (o cualquier modelo mapeado)
```
### 🛠️ Compilar desde el Código Fuente
#### Requisitos Previos
- **Node.js** v20 o superior
- **npm** (este proyecto usa `package-lock.json`)
#### Pasos
| Herramienta | Versión mínima |
|---|---|
| Node.js | 20+ (recomendado en `AGENTS.md`; `.nvmrc` fija 22.17.1) |
| pnpm | 10.11.0 (`packageManager`; el lockfile es `pnpm-lock.yaml`) |
| Toolchain nativa | necesaria para `better-sqlite3` y `keytar`: Visual Studio 2022 Build Tools (C++) en Windows, Xcode Command Line Tools en macOS, `build-essential` + `python3` + `libsecret-1-dev` en Ubuntu (`base-devel` + `python` + `libsecret` en Arch) |
```bash
# Clonar el repositorio
git clone https://github.com/evandrodevbr/GeminiNexus.git
cd GeminiNexus
# Instalar dependencias
npm install
# Iniciar en modo desarrollo
npm start
# Compilar para producción (ej: instalador de Windows)
npm run make
git clone https://git.evandro.dev.br/evandro/gemini-nexus.git
cd gemini-nexus
pnpm install # el postinstall ejecuta scripts/setup-dev.js --check-only para verificar la toolchain
pnpm start # modo dev (Electron + Vite HMR)
pnpm run make # instaladores/paquetes para la plataforma actual
pnpm run make:win # Windows: extrae WiX de wix314-binaries.zip y luego ejecuta make
```
---
Después añade al menos una cuenta, activa el proxy (viene apagado) y apunta tu IDE a él:
## 🛠️ Stack Tecnológico
| Categoría | Tecnologías |
| ----------------- | ---------------------------------------------- |
| **Core** | Electron, React 19, TypeScript |
| **Build** | Vite, Electron Forge |
| **Estilos** | Tailwind CSS v4, Radix UI, Lucide Icons |
| **Estado** | TanStack Query, TanStack Router |
| **Backend** | NestJS (gateway interno), ORPC (RPC type-safe) |
| **Base de Datos** | Better-SQLite3, Drizzle ORM |
| **Gráficos** | Nivo (Line, Bar, Pie) |
| **Testing** | Vitest, Playwright |
---
## 💻 Desarrollo
```bash
# Iniciar entorno de dev (Electron + Vite HMR)
npm start
# Ejecutar linting
npm run lint
# Verificación de tipos
npm run type-check
# Formatear código
npm run format:write
# Ejecutar pruebas
npm test
```text
API Base URL: http://localhost:8045/v1 (por defecto, configurable en la página Proxy; los builds de desarrollo usan 8046)
API Key: (cópiala de la página Proxy de la app)
Model: gemini-3-flash (o cualquier modelo mapeado)
```
---
> [!WARNING]
> Los builds no están firmados. Si Windows muestra "Windows protegió su PC", haz clic en **Más información → Ejecutar de todas formas**.
## ❓ Preguntas Frecuentes
No hay `.env.example` y ninguna variable es obligatoria. Variables opcionales que lee el código o que describen los docs:
| Variable | Obligatoria | Descripción |
|---|---|---|
| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | No | Envía las peticiones salientes de la app por un proxy local (ver inspección TLS en [Modelo de seguridad](#modelo-de-seguridad)). |
| `NODE_EXTRA_CA_CERTS` | No | Certificado de CA adicional para el TLS del lado Node al inspeccionar tráfico. |
| `SENTRY_DSN` | No | DSN de Sentry usado cuando el envío de errores está activado. |
## 🛠️ Stack
| Capa | Tecnología |
|---|---|
| Shell de escritorio | Electron 41, Electron Forge, Vite |
| Interfaz | React 19, TypeScript, Tailwind CSS 4, Radix UI, gráficos Nivo, i18next |
| Flujo de datos de la app | TanStack Router y Query, oRPC sobre IPC de Electron |
| Proxy | NestJS 11 sobre Fastify |
| Almacenamiento | SQLite (better-sqlite3 + Drizzle ORM), llavero del sistema vía `keytar` |
| Logs y errores | Winston (archivos rotativos), Sentry (opcional) |
| Pruebas | Vitest, Playwright |
## Arquitectura
```mermaid
flowchart LR
C["Cliente: Cursor, Windsurf, OpenCode, Claude Code"] -->|"/v1/chat/completions, /v1/messages"| P["Proxy NestJS, puerto 8045"]
P --> S["Planificador de cuentas y circuit breaker"]
S -->|"cuenta Google OAuth"| G["APIs upstream de Google"]
M["CloudMonitor y AutoSwitch, cuota cada 5 min"] -->|"consulta de cuota"| G
S -->|"lee cuentas"| DB[("SQLite: better-sqlite3 y Drizzle")]
M --> DB
K["AES-256-GCM, clave maestra en el llavero del sistema"] -->|"cifra tokens"| DB
```
1. Un cliente envía peticiones en formato OpenAI o Anthropic al proxy NestJS (Fastify, escuchando en `0.0.0.0`).
2. El guard del proxy comprueba la API key cuando hay una configurada; con la clave vacía el proxy funciona en modo abierto.
3. El token manager elige una cuenta según el modo de planificación y el estado del circuit breaker de cada cuenta, y llama a las APIs upstream de Google con el token OAuth de esa cuenta.
4. `CloudMonitorService` consulta la cuota cada 5 minutos y `AutoSwitchService` cambia la cuenta activa cuando la cuota está por debajo del 5 % o la cuenta sufre rate limit.
5. El renderer React 19 (TanStack Router y Query) habla con el proceso principal mediante oRPC sobre IPC; cuentas, uso y ajustes viven en SQLite (better-sqlite3 + Drizzle). Notas de diseño: [`docs/cloud_features.md`](docs/cloud_features.md).
## Modelo de seguridad
Gemini Nexus guarda tokens OAuth de varias cuentas y reenvía tráfico hacia arriba, así que el manejo de credenciales es el núcleo del diseño. Todo lo de abajo está implementado en este repositorio; los límites se indican donde existen.
- **Almacenamiento y aislamiento de credenciales.** `token_json` y `quota_json` se cifran con AES-256-GCM (IV único por operación, autenticado) antes de llegar a SQLite. La clave maestra vive en el almacén de credenciales del sistema vía `keytar` (Administrador de credenciales de Windows, Keychain de macOS, Secret Service/libsecret en Linux), nunca en un archivo plano. Las filas heredadas en texto plano se migran al arrancar. Las cuentas se guardan en su propia base de datos (`cloud_accounts.db`), independiente de la base local del IDE.
- **Enmascarado de logs.** Claves como `token`, `refresh_token`, `api_key`, `authorization`, `cookie` y `client_secret` se sustituyen por `[REDACTED]` antes de registrarse ([`src/utils/sensitiveDataMasking.ts`](src/utils/sensitiveDataMasking.ts)); el logger de tráfico también oculta las cabeceras `authorization`, `x-api-key` y `cookie`.
- **Registro de peticiones, no pista de auditoría.** Winston escribe logs de API, tráfico y app en archivos rotativos (log de API: 30 días, 50 MB por archivo). Son logs operativos, no una pista de auditoría a prueba de manipulación; los archivos `*-audit.json` son el control de rotación de `winston-daily-rotate-file`.
- **Acceso al proxy.** El proxy viene apagado. Una vez activado escucha en `0.0.0.0`, y las peticiones solo se autentican cuando `api_key` no está vacía (vacía significa modo abierto). Define una clave y mantenla privada.
- **Inspección TLS (solo para depurar).** [`docs/proxyman-install.md`](docs/proxyman-install.md) y [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md) explican cómo leer el tráfico HTTPS de la app con Proxyman: confiar en su CA raíz, definir las variables de proxy y `NODE_EXTRA_CA_CERTS` y después iniciar la app. `NODE_TLS_REJECT_UNAUTHORIZED=0` (y el flag `-AllowInsecureTls` del script) es un ajuste temporal; nunca lo dejes activado. No hagas commit de direcciones de proxy, rutas de certificados, cookies ni códigos OAuth, y oculta datos de los logs antes de compartirlos. `scripts/start-antigravity-with-proxyman.ps1` apunta al cliente oficial de Antigravity instalado, no a esta app.
- **Envío de errores.** Los informes de Sentry (necesitan `SENTRY_DSN`) dependen del ajuste `error_reporting_enabled`, que `DEFAULT_APP_CONFIG` trae como `true`; desactívalo en Settings para no enviarlos. El segmento con el nombre de usuario de Windows se enmascara en los mensajes de excepción enviados.
Versiones soportadas y cómo reportar una vulnerabilidad: [`SECURITY.md`](SECURITY.md).
## 💻 Documentación y desarrollo
- [`docs/cloud_features.md`](docs/cloud_features.md): diseño del pool de cuentas, la monitorización de cuota y el cambio automático.
- [`docs/proxyman-install.md`](docs/proxyman-install.md) y [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md): configuración de la inspección TLS (Windows).
- [`docs/OpencodeAPI.md`](docs/OpencodeAPI.md): integración con endpoint personalizado de OpenCode (en portugués).
- [`cli/README.md`](cli/README.md): la herramienta de línea de comandos en Python.
- [`CONTRIBUTING.md`](CONTRIBUTING.md), [`SECURITY.md`](SECURITY.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), [`CHANGELOG.md`](CHANGELOG.md), [`LICENSE`](LICENSE), [`LICENSE-MIT`](LICENSE-MIT).
- Traducciones: [English](README.md), [Português](README.pt-BR.md), [中文](README.zh-CN.md).
### Estructura
```text
src/
├── components/ # UI (proxy/, usage/, primitivas ui/)
├── ipc/ # routers oRPC (account, cloud, config, gateway, usage...)
├── server/ # gateway proxy NestJS (módulos: proxy, usage)
├── services/ # AutoSwitchService, CloudMonitorService, GoogleAPIService
├── routes/ # index, usage, proxy, settings
├── utils/ # paths, logger, sensitiveDataMasking
└── tests/ # pruebas unitarias (Vitest) y E2E (Playwright)
cli/ # CLI de Python aparte para cambiar de cuenta y consultar cuota
docs/ # notas de diseño y guías de Proxyman
scripts/ # setup-dev, build-windows, generate-assets
```
### Scripts
| Comando | Qué hace |
|---|---|
| `pnpm start` | Ejecuta la app en modo dev (`electron-forge start`, con `DEBUG=electron-forge:*`). |
| `pnpm run dev` | Igual que `start`. |
| `pnpm run package` | Empaqueta la app con Electron Forge, sin generar instaladores. |
| `pnpm run make` | Genera instaladores/paquetes para la plataforma actual. |
| `pnpm run make:win` | Helper de build en Windows: extrae WiX de `wix314-binaries.zip`, lo añade al `PATH` y ejecuta `electron-forge make`. |
| `pnpm run publish` | Publica mediante Electron Forge. |
| `pnpm run setup` | Ejecuta `scripts/setup-dev.js`: detecta la toolchain nativa e instala o guía la configuración. |
| `pnpm run postinstall` | `scripts/setup-dev.js --check-only`; se ejecuta solo tras `pnpm install`. |
| `pnpm run lint` | ESLint sobre el repositorio. |
| `pnpm run format` | Comprobación de Prettier. |
| `pnpm run format:write` | Prettier con escritura. |
| `pnpm test` | Pruebas unitarias Vitest (`vitest run`). |
| `pnpm run test:watch` | Vitest en modo watch. |
| `pnpm run test:unit` | Vitest (modo por defecto). |
| `pnpm run test:e2e` | Pruebas E2E con Playwright. |
| `pnpm run test:all` | Pruebas unitarias y después Playwright. |
| `pnpm run type-check` | `tsc --noEmit`. |
## ❓ Preguntas frecuentes
<details>
<summary><b>P: ¿Aviso de Windows SmartScreen ("Windows protegió su PC") durante la instalación?</b></summary>
<summary><b>Windows muestra "Windows protegió su PC". ¿Es normal?</b></summary>
Sí, este es un aviso común para nuevas aplicaciones no firmadas. Haz clic en **"Más información"** y luego en **"Ejecutar de todas formas"**. Consulta la advertencia en la parte superior del README para más detalles.
Sí. Los builds no están firmados. Haz clic en **Más información → Ejecutar de todas formas**.
</details>
<details>
<summary><b>P: ¿La app no inicia al compilar desde el código fuente?</b></summary>
<summary><b>Mi IDE no llega al proxy.</b></summary>
El proxy viene apagado: actívalo en la página Proxy. El puerto por defecto es `8045` (`8046` en builds de desarrollo) y se puede cambiar allí. Copia la API key de esa misma página y comprueba que haya al menos una cuenta en el pool.
1. Asegúrate de que todas las dependencias están instaladas: `npm install`.
2. Verifica que tu versión de Node.js sea >= 20.
3. Intenta eliminar `node_modules` y reinstalar.
4. En Windows, asegúrate de que el WiX Toolset esté disponible para el comando `npm run make`.
</details>
<details>
<summary><b>P: ¿El inicio de sesión de la cuenta falló?</b></summary>
<summary><b>¿Necesito una API key?</b></summary>
Con `api_key` vacía el proxy funciona en modo abierto. Una vez activado escucha en `0.0.0.0`, así que define una clave y mantenla privada.
1. Asegúrate de que tu conexión a la red funcione correctamente.
2. Intenta borrar los datos de la app y volver a iniciar sesión.
3. Comprueba si la cuenta está restringida por Google/Claude.
</details>
<details>
<summary><b>P: ¿El IDE no se puede conectar al proxy?</b></summary>
<summary><b>¿Puedo usar modelos Claude?</b></summary>
Sí, mediante el mapeo de modelos sobre las cuentas de Google del pool, no con cuentas de Claude separadas.
1. Asegúrate de que el proxy esté funcionando (indicador verde en la barra de estado).
2. Confirma que el puerto coincide con tu configuración del IDE (por defecto `10100`).
3. Copia la API key directamente desde la página Proxy y pégala en la configuración de tu IDE.
4. Asegúrate de tener al menos una cuenta activa en la página Cuentas.
</details>
---
<details>
<summary><b>¿Dónde se guardan mis tokens?</b></summary>
En un `cloud_accounts.db` aparte, con `token_json` y `quota_json` cifrados con AES-256-GCM. La clave maestra vive en el almacén de credenciales del sistema vía `keytar`. Detalles en [Modelo de seguridad](#modelo-de-seguridad).
</details>
<details>
<summary><b>¿Puedo usarlo comercialmente?</b></summary>
Revisa antes la [Licencia](#-licencia): el código heredado de AntigravityManager es CC BY-NC-SA 4.0 (no comercial) y el código nuevo es MIT.
</details>
## Limitaciones y próximos pasos
- El acceso upstream pasa por los endpoints `v1internal` de Cloud Code de Google y por scopes OAuth ([`src/services/GoogleAPIService.ts`](src/services/GoogleAPIService.ts)). Son APIs internas, sin documentar, que pueden cambiar sin aviso. El proyecto no es oficial y no está afiliado a Google ni a Anthropic.
- Las cuentas se añaden por Google OAuth; a los modelos Claude se llega mediante el mapeo de modelos, no con cuentas de Claude separadas.
- Las pruebas end-to-end no se ejecutan en CI (Electron necesita un entorno gráfico); ejecuta `pnpm run test:e2e` en local.
- El MSI de Windows solo se genera cuando el WiX Toolset está disponible en la máquina de build; si no, el artefacto de Windows es el ZIP.
- Los workflows de `.github/workflows/` están escritos para GitHub (llaman al CLI `gh` y al publicador de releases de GitHub), por eso este README no muestra badge de CI.
- Próximo paso declarado por el proyecto: migrar el código original restante a MIT (ver la [Licencia](#-licencia)).
## 🤝 Contribuir
¡Las contribuciones son bienvenidas! Por favor lee `CONTRIBUTING.md` para más detalles.
Lee [`CONTRIBUTING.md`](CONTRIBUTING.md) y [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Las versiones las genera semantic-release a partir de Conventional Commits. Antes de abrir un PR, esto tiene que pasar:
---
```bash
pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test
```
## 📄 Licencia
Este proyecto utiliza una estructura de licencia dual:
- **Código original** de [AntigravityManager](https://github.com/Draculabo/AntigravityManager) por [Draculabo](https://github.com/Draculabo): Licenciado bajo [CC BY-NC-SA 4.0](LICENSE).
- **Todo el código nuevo, funcionalidades y arquitectura** por [evandrodevbr](https://github.com/evandrodevbr): Licenciado bajo la [Licencia MIT](LICENSE-MIT).
> 🔄 **Aviso de Migración:** Este proyecto está siendo migrado activamente a una licencia completamente open-source (MIT). A medida que el código original restante se reescribe progresivamente, todo el proyecto hará la transición a MIT. Estamos comprometidos a hacer Gemini Nexus 100% open-source.
Licencia mixta: el código heredado de [AntigravityManager](https://github.com/Draculabo/AntigravityManager) (de Draculabo) es [CC BY-NC-SA 4.0](LICENSE) (no comercial, compartir igual); todo el código nuevo es [MIT](LICENSE-MIT). El proyecto está migrando a MIT a medida que se reescribe el código original restante, así que revisa ambos archivos antes de cualquier uso comercial.
---
## 🙏 Créditos
<div align="center">
Este proyecto fue originalmente un fork de [AntigravityManager](https://github.com/Draculabo/AntigravityManager) creado por [Draculabo](https://github.com/Draculabo). El concepto inicial del proxy y la estructura base de Electron se basaron en su trabajo.
<img src="docs/assets/logo.png" width="56" alt="Logo de Gemini Nexus">
Desde el fork, **la gran mayoría del código ha sido reescrito, rediseñado y expandido** por [evandrodevbr](https://github.com/evandrodevbr), incluyendo pero no limitado a:
<p><strong><a href="https://git.evandro.dev.br/evandro/gemini-nexus">Gemini Nexus en Gitea</a></strong> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Reportar un problema</a> · <a href="#-inicio-rápido">Inicio rápido</a></p>
- Rediseño completo de UI/UX (navegación, cuentas, analíticas de uso, gestión del proxy)
- Dashboard de Analíticas de Uso con seguimiento de costos, promedios de tokens e integración con OpenRouter
- Monitor de tráfico con inspección de tokens/costos por solicitud
- Aislamiento de entorno (dev/prod), pipeline CI/CD e infraestructura de pruebas
- Configuración rápida para IDEs (OpenCode, Cursor, VS Code, Claude Code)
- Configuración personalizada de precios de modelos
- Toda la documentación e internacionalización (EN, PT-BR, ES, ZH-CN)
</div>
+209 -205
View File
@@ -1,258 +1,262 @@
<p align="center">
<img src="docs/assets/logo.png" alt="Gemini Nexus" width="128" height="128" />
</p>
<div align="center">
<h1 align="center">Gemini Nexus</h1>
<img src="assets/readme/hero.png" width="100%" alt="Gemini Nexus: a desktop gateway that pools Google accounts behind one local OpenAI- and Anthropic-compatible API at http://localhost:8045/v1, switching accounts when quota runs low">
<p align="center">
<strong>Desktop gateway that pools several Google Gemini and Claude accounts behind a single local OpenAI- and Anthropic-compatible API.</strong>
</p>
![Stack](https://img.shields.io/badge/Stack-Electron_41_%C2%B7_React_19-47848F?logo=electron&logoColor=white)
![Status](https://img.shields.io/badge/status-v0.15.3_active-brightgreen)
![License](https://img.shields.io/badge/license-CC_BY--NC--SA_4.0_%2B_MIT-lightgrey)
<p align="center">
English | <a href="README.pt-BR.md">Português</a> | <a href="README.zh-CN.md">中文</a> | <a href="README.es.md">Español</a>
</p>
<p><strong><a href="#-quickstart">Quickstart</a></strong> · <a href="#-documentation">Docs</a> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Issues</a></p>
<p align="center">
<a href="https://github.com/evandrodevbr/GeminiNexus/releases"><img src="https://img.shields.io/github/v/release/evandrodevbr/GeminiNexus?style=flat-square" alt="Release" /></a>
<a href="https://github.com/evandrodevbr/GeminiNexus/actions/workflows/testing.yaml"><img src="https://github.com/evandrodevbr/GeminiNexus/actions/workflows/testing.yaml/badge.svg" alt="Tests" /></a>
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-informational?style=flat-square" alt="Platform" />
<img src="https://img.shields.io/badge/electron-41-47848F?style=flat-square&logo=electron&logoColor=white" alt="Electron 41" />
<img src="https://img.shields.io/badge/react-19-61DAFB?style=flat-square&logo=react&logoColor=white" alt="React 19" />
<img src="https://img.shields.io/badge/node-%3E%3D20.19-5FA04E?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node 20.19+" />
<img src="https://img.shields.io/badge/license-MIT%20%2B%20CC%20BY--NC--SA%204.0-blue?style=flat-square" alt="License" />
</p>
<sub>English · <a href="README.pt-BR.md">Português</a> · <a href="README.zh-CN.md">中文</a> · <a href="README.es.md">Español</a></sub>
> **Windows users:** the installers are not code-signed, so SmartScreen may show "Windows protected your PC". Choose "More info" and then "Run anyway"; this is the expected prompt for an unsigned application.
</div>
## About
## 🖼️ Demo
AI coding tools assume a single account with a single quota. When that quota runs out, you have to switch accounts by hand, and you usually have no idea how many tokens you burned.
<p align="center"><img src="docs/assets/main.png" width="100%" alt="Accounts page: a Google account in the pool with per-model quota bars, the Auto-Switch toggle and the global quota counter"></p>
Gemini Nexus is an Electron desktop application that runs a local gateway (an embedded NestJS server) in front of a pool of Google Gemini and Claude accounts. Your IDE points at the local gateway once; the gateway picks an account, translates the protocol, retries on quota or rate-limit errors, and records usage.
<details>
<summary>More screenshots: usage, proxy, routing, docs, connections, settings</summary>
What it does:
<p align="center"><img src="docs/assets/2usage.png" alt="Usage analytics" width="80%"></p>
<p align="center"><img src="docs/assets/3proxy.png" alt="Proxy monitor" width="80%"></p>
<p align="center"><img src="docs/assets/4routing.png" alt="Routing config" width="80%"></p>
<p align="center"><img src="docs/assets/5docs.png" alt="Documentation" width="80%"></p>
<p align="center"><img src="docs/assets/6connections.png" alt="Active connections" width="80%"></p>
<p align="center"><img src="docs/assets/7config.png" alt="Settings" width="80%"></p>
- Manages a pool of Google/Claude accounts with per-account status (active, rate limited, expired) and quota snapshots.
- Serves an OpenAI-compatible surface (`/v1/chat/completions`, `/v1/models`, `/v1/completions`, `/v1/responses`, images and audio routes), an Anthropic-compatible surface (`/v1/messages`) and the Gemini-native surface (`/v1beta/models`, `countTokens`).
- Streams responses over SSE and maps model names in both directions (for example `claude-sonnet-4-5` to the configured Gemini/Claude target).
- Stores tokens and keys encrypted at rest (AES-256-GCM) with an OS keychain wrapper, falling back to a local key file.
- Shows local analytics: token usage, cost estimates, model distribution, request traffic and request replay.
</details>
It is a personal desktop tool, not a hosted service: everything runs on your machine.
## ✨ What it does
Working with AI-powered IDEs on a single Google account means quota that runs out, manual account switching and no view of what the proxy sends upstream. Gemini Nexus keeps every account in one pool and serves them through one local endpoint.
<table>
<tr>
<td width="50%" valign="top"><b>One local endpoint</b><br><code>POST /v1/chat/completions</code> (OpenAI), <code>POST /v1/messages</code> (Anthropic), <code>GET /v1/models</code> and <code>GET /v1/models/capabilities</code>, so Cursor, Windsurf, OpenCode, Claude Code and similar clients can connect. Model names are mapped through <code>custom_mapping</code> and <code>anthropic_mapping</code>.</td>
<td width="50%" valign="top"><b>Account pool</b><br>Google accounts added through OAuth, each with its status (Active, Rate Limited, Expired), last-used time and an optional per-account proxy URL.</td>
</tr>
<tr>
<td width="50%" valign="top"><b>Auto-switch</b><br><code>CloudMonitorService</code> polls quota every 5 minutes and <code>AutoSwitchService</code> moves to another account when quota drops below 5 % or the account is rate-limited.</td>
<td width="50%" valign="top"><b>Scheduling with a circuit breaker</b><br><code>cache-first</code>, <code>balance</code> (default) or <code>performance-first</code>, with a per-account circuit breaker (default backoff 60 s → 5 min → 30 min → 2 h).</td>
</tr>
<tr>
<td width="50%" valign="top"><b>Usage and cost</b><br>Token usage per account and model, prompt and completion charts, and cost estimates from editable per-model pricing.</td>
<td width="50%" valign="top"><b>Traffic inspector</b><br>Latency, status and model for each request, replay of logged requests, generated cURL and Python snippets, plus an IDE Quick Setup.</td>
</tr>
</table>
Stored credentials are encrypted with AES-256-GCM under an OS-keychain master key (see [Security model](#-security-model)).
## How it works
```text
IDE / CLI (Cursor, Windsurf, OpenCode, Claude Code, custom scripts)
| OpenAI /v1/chat/completions Anthropic /v1/messages Gemini /v1beta
v
Gemini Nexus (Electron app)
+-- Renderer: React 19 UI (accounts, usage, proxy, settings)
+-- Main process: IPC, SQLite storage, encryption, tray
+-- Gateway: NestJS + Fastify, bound to port 8045 (8046 in development)
| 1. authenticate the request (Bearer / x-api-key / x-goog-api-key)
| 2. choose an account from the pool (quota, rate limit, circuit breaker)
| 3. translate the protocol and call the upstream API
| 4. stream the answer back and persist usage metrics
v
Google Gemini API / Claude API (per-account OAuth credentials)
1. **Add accounts.** Sign in with Google OAuth on the Accounts page. Tokens are encrypted before they reach SQLite.
2. **Point your IDE at the proxy.** Enable the proxy on the Proxy page (it is off by default) and use `http://localhost:8045/v1` with the API key shown there, in OpenAI or Anthropic format.
3. **Nexus routes each request.** The token manager picks an account by scheduling mode and circuit-breaker state, calls Google's upstream APIs with that account's OAuth token, and auto-switch moves on when quota drops below 5 % or an account is rate-limited.
The full flow, with the components involved, is in [Architecture](#-architecture).
## 🚀 Quickstart
There are no prebuilt downloads on the [Gitea Releases](https://git.evandro.dev.br/evandro/gemini-nexus/releases) page yet (the release workflows in `.github/workflows/` target GitHub), so build from source.
| Tool | Minimum version |
|---|---|
| Node.js | 20+ (recommended in `AGENTS.md`; `.nvmrc` pins 22.17.1) |
| pnpm | 10.11.0 (`packageManager`; lockfile is `pnpm-lock.yaml`) |
| Native toolchain | needed by `better-sqlite3` and `keytar`: Visual Studio 2022 Build Tools (C++) on Windows, Xcode Command Line Tools on macOS, `build-essential` + `python3` + `libsecret-1-dev` on Ubuntu (`base-devel` + `python` + `libsecret` on Arch) |
```bash
git clone https://git.evandro.dev.br/evandro/gemini-nexus.git
cd gemini-nexus
pnpm install # postinstall runs scripts/setup-dev.js --check-only to verify the toolchain
pnpm start # dev mode (Electron + Vite HMR)
pnpm run make # installers/packages for the current platform
pnpm run make:win # Windows: extracts WiX from wix314-binaries.zip, then runs make
```
- The gateway is started by the desktop app (Proxy page, or auto-start if enabled). It is a child process, so closing the app stops it.
- Account selection honours a scheduling mode (`balance`, `cache-first`, `performance-first`), a preferred account, per-account upstream proxy URLs, and a circuit breaker with backoff steps.
- Requests are recorded locally (SQLite) and can be replayed from the Proxy page for debugging.
Then add at least one account, enable the proxy (it is disabled by default) and point your IDE at it:
```text
API Base URL: http://localhost:8045/v1 (default, configurable on the Proxy page; development builds use 8046)
API Key: (copy it from the Proxy page in the app)
Model: gemini-3-flash (or any mapped model)
```
> [!WARNING]
> Builds are not code-signed. If Windows shows "Windows protected your PC", click **More info → Run anyway**.
There is no `.env.example` and no variable is required. Optional variables read by the code or described in the docs:
| Variable | Required | Description |
|---|---|---|
| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | No | Route the app's outbound requests through a local proxy (see [TLS inspection](#-security-model)). |
| `NODE_EXTRA_CA_CERTS` | No | Extra CA certificate for Node-side TLS when inspecting traffic. |
| `SENTRY_DSN` | No | Sentry DSN used when error reporting is enabled. |
## Stack
| Layer | Choice |
| Layer | Technology |
|---|---|
| Desktop shell | Electron 41, Electron Forge 7 (Vite plugin) |
| UI | React 19, TypeScript 5.9, TanStack Router + Query, Tailwind CSS v4, Radix UI, Nivo charts |
| Gateway | NestJS 11 on Fastify 5, RxJS, SSE streaming |
| Storage | better-sqlite3 + Drizzle ORM / raw SQL, JSON config in the app data dir |
| Secrets | Node crypto AES-256-GCM, `safeStorage` / `keytar` with file fallback |
| Validation | Zod schemas, class-validator |
| Internationalization | react-i18next (en, zh-CN, ru, vi) |
| Tests | Vitest (unit), Testing Library, Playwright (E2E, local only) |
| Package manager | pnpm 10.11.0 (`packageManager` field, Corepack) |
| Desktop shell | Electron 41, Electron Forge, Vite |
| Interface | React 19, TypeScript, Tailwind CSS 4, Radix UI, Nivo charts, i18next |
| App data flow | TanStack Router and Query, oRPC over Electron IPC |
| Proxy | NestJS 11 on Fastify |
| Storage | SQLite (better-sqlite3 + Drizzle ORM), OS keychain via `keytar` |
| Logs and errors | Winston (rotating files), Sentry (optional) |
| Tests | Vitest, Playwright |
## Requirements
## 🧱 Architecture
- Node.js `^20.19.0 || >=22.12.0` (Vite 8 engine range). The repository pins 22.17.1 in `.nvmrc`; this audit ran on Node 24.20.0.
- pnpm `10.11.0` (declared in `package.json`). With Corepack enabled, `pnpm` resolves to that version automatically.
- Native build toolchain for `better-sqlite3` and `keytar`: on Linux, `base-devel`/`build-essential`, `python3` and `libsecret`; on macOS, Xcode Command Line Tools; on Windows, Visual Studio Build Tools with the C++ workload. `pnpm install` runs `scripts/setup-dev.js --check-only`, which reports what is missing.
- A graphical session to run the desktop app itself (Electron).
- For installers: `dpkg`/`rpmbuild` on Linux, WiX Toolset on Windows.
## Quick start
```bash
git clone https://github.com/evandrodevbr/GeminiNexus.git
cd GeminiNexus
# 1. install dependencies (lockfile is pnpm; do not use npm install)
corepack enable
pnpm install --frozen-lockfile
# 2. run the desktop app (Electron + Vite HMR); the gateway listens on 8046 in dev
pnpm start
```mermaid
flowchart LR
C["Client: Cursor, Windsurf, OpenCode, Claude Code"] -->|"/v1/chat/completions, /v1/messages"| P["NestJS proxy, port 8045"]
P --> S["Account scheduler and circuit breaker"]
S -->|"Google OAuth account"| G["Google upstream APIs"]
M["CloudMonitor and AutoSwitch, quota every 5 min"] -->|"quota polling"| G
S -->|"reads accounts"| DB[("SQLite: better-sqlite3 and Drizzle")]
M --> DB
K["AES-256-GCM, master key in OS keychain"] -->|"encrypts tokens"| DB
```
Then, in the app:
1. A client sends OpenAI- or Anthropic-format requests to the NestJS proxy (Fastify, bound to `0.0.0.0`).
2. The proxy guard checks the API key when one is configured; with an empty key the proxy runs in open mode.
3. The token manager picks an account according to the scheduling mode and each account's circuit-breaker state, then calls Google's upstream APIs with that account's OAuth token.
4. `CloudMonitorService` polls quota every 5 minutes and `AutoSwitchService` switches the active account when quota is below 5 % or the account is rate-limited.
5. The React 19 renderer (TanStack Router and Query) talks to the main process over oRPC on IPC; accounts, usage and settings live in SQLite (better-sqlite3 + Drizzle). Design notes: [`docs/cloud_features.md`](docs/cloud_features.md).
1. Add at least one Google or Claude account on the Accounts page (OAuth flow).
2. Open the Proxy page, enable the gateway and copy the generated API key.
3. Point your IDE or CLI at the local endpoint.
## 🔒 Security model
```text
API base URL: http://localhost:8045/v1
API key: copied from the Proxy page
Model: gemini-3-flash (or any model id returned by GET /v1/models)
```
Gemini Nexus holds OAuth tokens for several accounts and forwards traffic upstream, so credential handling is the core of the design. Everything below is implemented in this repository; limits are stated where they exist.
## Usage
- **Credential storage and isolation.** `token_json` and `quota_json` are encrypted with AES-256-GCM (unique IV per operation, authenticated) before they reach SQLite. The master key lives in the OS credential store through `keytar` (Windows Credential Manager, macOS Keychain, Linux Secret Service/libsecret), never in a plain file. Legacy plaintext rows are migrated at startup. Accounts are kept in their own database (`cloud_accounts.db`), independent from the IDE's local database.
- **Log masking.** Keys such as `token`, `refresh_token`, `api_key`, `authorization`, `cookie` and `client_secret` are replaced by `[REDACTED]` before logging ([`src/utils/sensitiveDataMasking.ts`](src/utils/sensitiveDataMasking.ts)); the traffic logger also redacts the `authorization`, `x-api-key` and `cookie` headers.
- **Request logging, not an audit trail.** Winston writes API, traffic and app logs to rotating files (API log: 30 days, 50 MB per file). These are operational logs, not a tamper-evident audit trail; the `*-audit.json` files are rotation bookkeeping from `winston-daily-rotate-file`.
- **Proxy access.** The proxy is off by default. Once enabled it listens on `0.0.0.0`, and requests are authenticated only when `api_key` is non-empty (empty means open mode). Set a key and keep it private.
- **TLS inspection (debugging only).** [`docs/proxyman-install.md`](docs/proxyman-install.md) and [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md) explain how to read the app's HTTPS traffic with Proxyman: trust its root CA, set the proxy variables and `NODE_EXTRA_CA_CERTS`, then start the app. `NODE_TLS_REJECT_UNAUTHORIZED=0` (and the script's `-AllowInsecureTls` flag) is a temporary override; never leave it on. Do not commit proxy addresses, certificate paths, cookies or OAuth codes, and redact logs before sharing them. `scripts/start-antigravity-with-proxyman.ps1` targets the installed official Antigravity client, not this app.
- **Error reporting.** Sentry reports (they need `SENTRY_DSN`) are gated by the `error_reporting_enabled` setting, which `DEFAULT_APP_CONFIG` ships as `true`; turn it off in Settings to opt out. The Windows user-name segment is masked in reported exception messages.
Daily commands, all driven by `pnpm`:
Supported versions and how to report a vulnerability: [`SECURITY.md`](SECURITY.md).
```bash
pnpm start # dev app + gateway (port 8046)
pnpm run package # unpack the app for the current platform (out/)
pnpm run make # build installers (needs the extra tooling listed above)
pnpm test # Vitest unit/integration suite
pnpm run type-check # tsc --noEmit
pnpm run lint # ESLint
pnpm run format # Prettier check (pnpm run format:write to fix)
pnpm run test:e2e # Playwright E2E, needs a graphical session
```
## 📚 Documentation
Settings live in the app data directory (`%APPDATA%\Gemini Nexus` on Windows, `~/Library/Application Support/Gemini Nexus` on macOS, `~/.config/Gemini Nexus` on Linux; `${app}-dev` names in development). Account metadata is stored in `~/.geminiNexus-agent/geminiNexus_accounts.json`.
- [`docs/cloud_features.md`](docs/cloud_features.md): account pool, quota monitoring and auto-switch design.
- [`docs/proxyman-install.md`](docs/proxyman-install.md) and [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md): TLS inspection setup (Windows).
- [`docs/OpencodeAPI.md`](docs/OpencodeAPI.md): OpenCode custom-endpoint integration (in Portuguese).
- [`cli/README.md`](cli/README.md): the Python command-line tool.
- [`CONTRIBUTING.md`](CONTRIBUTING.md), [`SECURITY.md`](SECURITY.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), [`CHANGELOG.md`](CHANGELOG.md), [`LICENSE`](LICENSE), [`LICENSE-MIT`](LICENSE-MIT).
- Translations: [Português](README.pt-BR.md), [中文](README.zh-CN.md), [Español](README.es.md).
## Screenshots
| | |
|---|---|
| ![Main dashboard](docs/assets/main.png) | ![Usage analytics](docs/assets/2usage.png) |
| ![Proxy monitor](docs/assets/3proxy.png) | ![Routing config](docs/assets/4routing.png) |
| ![Documentation](docs/assets/5docs.png) | ![Active connections](docs/assets/6connections.png) |
| ![Settings](docs/assets/7config.png) | |
## API
Routes actually mapped by the gateway (read from the running server):
| Route | Purpose |
|---|---|
| `GET /v1/models` | OpenAI-style model list built from the built-in mapping plus models collected from accounts. |
| `GET /v1/models/capabilities` | Per-model flags: vision, streaming, JSON mode, audio, image generation. |
| `GET /v1/status` | Gateway health, uptime, account counters and request metrics. |
| `POST /v1/chat/completions` | OpenAI Chat Completions, streaming and non-streaming. |
| `POST /v1/completions` | Legacy completions compatibility endpoint. |
| `POST /v1/responses` | OpenAI Responses-style endpoint. |
| `POST /v1/messages` | Anthropic Messages API. |
| `POST /v1/messages/chat/completions` | Anthropic-shaped requests over the chat completions path. |
| `POST /v1/batch/completions` | Batched chat completion requests. |
| `POST /v1/images/generations`, `POST /v1/images/edits` | Image endpoints. |
| `POST /v1/audio/transcriptions` | Audio transcription endpoint. |
| `GET /v1/events` | Server-sent events stream of gateway activity. |
| `GET /v1/replay/requests`, `POST /v1/replay/:requestId` | List recorded requests and replay one of them. |
| `GET /v1beta/models`, `GET /v1beta/models/:model` | Gemini-native model listing. |
| `POST /v1beta/models/:modelAction`, `POST /v1beta/models/:model/countTokens` | Gemini-native generate and token counting. |
Authentication: the gateway accepts the API key as `Authorization: Bearer <key>`, `x-api-key: <key>` or `x-goog-api-key: <key>`. If the configured key is empty, the gateway runs open, which is only sensible while it is bound to localhost.
## Build and release
```bash
pnpm run package # app bundle in out/<product>-<platform>-<arch>
pnpm run make # installers (deb, rpm, AppImage, zip on Linux; dmg/zip on macOS; WiX installer on Windows)
pnpm run make:win # Windows helper script
```
The gateway is statically bundled into the Electron app; there is no separate server deployment.
Release automation in `.github/workflows/`:
- `format.yaml` and `lint.yaml` run Prettier and ESLint on pull requests to `main`.
- `testing.yaml` runs the unit suite and `tsc --noEmit` on pushes and pull requests. E2E is intentionally excluded because it needs a graphical environment.
- `release.yml` runs semantic-release on `main`, which tags the version, updates `CHANGELOG.md` and creates the GitHub release.
- `publish.yaml` builds `win32`, `darwin` and `linux` for x64 and arm64 when the Release workflow succeeds, and uploads the installers to the release.
## Project structure
### 🗂️ Structure
```text
src/
├── main.ts, preload.ts, renderer.ts Electron entry points
├── routes/ TanStack Router pages: index (accounts), usage, proxy, settings
├── components/ React UI (accounts, proxy/advanced, usage, ui primitives)
├── server/ Embedded gateway
│ ├── main.ts NestJS bootstrap (port and process lifecycle)
│ ├── modules/proxy/ controllers, proxy service, token manager, SSE, replay, metrics
│ └── modules/usage/ token usage service
├── ipc/ Electron IPC handlers (accounts, config, database, proxy, tray, ...)
├── lib/geminiNexus/ protocol mappers, model mapping, retry and streaming helpers
├── localization/ i18n resources
├── utils/ paths, logging, encryption, traffic logger
└── tests/ unit, integration and e2e suites
docs/ OpenCode integration, cloud features, Proxyman guides, brand notes
scripts/ dev environment setup, Windows build helper, asset generation
├── components/ # UI (proxy/, usage/, ui/ primitives)
├── ipc/ # oRPC routers (account, cloud, config, gateway, usage...)
├── server/ # NestJS proxy gateway (modules: proxy, usage)
├── services/ # AutoSwitchService, CloudMonitorService, GoogleAPIService
├── routes/ # index, usage, proxy, settings
├── utils/ # paths, logger, sensitiveDataMasking
└── tests/ # unit tests (Vitest) and E2E (Playwright)
cli/ # separate Python CLI for account switching and quota checks
docs/ # design notes and Proxyman guides
scripts/ # setup-dev, build-windows, generate-assets
```
## Verification
### 🧪 Scripts
Previously recorded Linux x64 checks (Node 24.20.0, pnpm 10.11.0), before the review below:
| Command | Result |
| Command | What it does |
|---|---|
| `pnpm install --frozen-lockfile` | exit 0 |
| `pnpm test` | 54 test files, 499 tests, all passing |
| `pnpm run type-check` | exit 0 |
| `pnpm run lint` | exit 0 (327 warnings, no errors) |
| `pnpm run format` | all files formatted |
| `pnpm run package` | exit 0, `out/Gemini Nexus-linux-x64` |
| `pnpm run test:e2e` | not run: Playwright drives Electron and needs a graphical session |
| `pnpm start` | Run the app in dev mode (`electron-forge start`, with `DEBUG=electron-forge:*`). |
| `pnpm run dev` | Same as `start`. |
| `pnpm run package` | Package the app with Electron Forge, without building installers. |
| `pnpm run make` | Build installers/packages for the current platform. |
| `pnpm run make:win` | Windows build helper: extracts WiX from `wix314-binaries.zip`, adds it to `PATH`, runs `electron-forge make`. |
| `pnpm run publish` | Publish through Electron Forge. |
| `pnpm run setup` | Run `scripts/setup-dev.js`: detect the native toolchain and install or guide the setup. |
| `pnpm run postinstall` | `scripts/setup-dev.js --check-only`; runs automatically after `pnpm install`. |
| `pnpm run lint` | ESLint over the repo. |
| `pnpm run format` | Prettier check. |
| `pnpm run format:write` | Prettier write. |
| `pnpm test` | Vitest unit tests (`vitest run`). |
| `pnpm run test:watch` | Vitest in watch mode. |
| `pnpm run test:unit` | Vitest (default mode). |
| `pnpm run test:e2e` | Playwright E2E tests. |
| `pnpm run test:all` | Unit tests, then Playwright. |
| `pnpm run type-check` | `tsc --noEmit`. |
The E2E suite is also excluded from CI for the same reason.
## FAQ
## Current state and limitations
<details>
<summary><b>Windows shows "Windows protected your PC". Is that expected?</b></summary>
- Upstream calls cannot be exercised without real Google/Claude accounts. With an empty pool the gateway starts, lists models and answers `429 No available accounts (all exhausted or rate limited)` on inference routes.
- The app is desktop-only (Windows, macOS, Linux). There is no headless or container mode, because the gateway is a child process of the Electron app.
- Accounts are added through the app UI and the OAuth flow; there is no CLI to import credentials.
- UI languages are en, zh-CN, ru and vi. The default language in `DEFAULT_APP_CONFIG` is `zh-CN`.
- Windows installers are unsigned (SmartScreen warning). macOS builds are unsigned and unnotarized.
- The E2E suite does not run in CI.
- The project is mid-migration to a single license: the code inherited from AntigravityManager is CC BY-NC-SA 4.0 (non-commercial), while the new code is MIT. See the license section.
- `pnpm install` reports `Ignored build scripts: sharp`. `sharp` is only used by `scripts/generate-assets.ts` for icon generation, and its prebuilt binaries are installed through optional dependencies.
Yes. Builds are not code-signed. Click **More info → Run anyway**.
## Documentation
</details>
| Document | Content |
|---|---|
| [`docs/OpencodeAPI.md`](docs/OpencodeAPI.md) | Wiring OpenCode to the local custom endpoint |
| [`docs/cloud_features.md`](docs/cloud_features.md) | Cloud account management and switching behaviour |
| [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md) | Debugging upstream traffic with Proxyman |
| [`docs/proxyman-install.md`](docs/proxyman-install.md) | Proxyman setup for contributors |
| [`docs/brand-briefing.md`](docs/brand-briefing.md) | Naming, positioning and visual notes |
| [`CONTRIBUTING.md`](CONTRIBUTING.md), [`AGENTS.md`](AGENTS.md) | Contribution rules and repository conventions |
| [`CHANGELOG.md`](CHANGELOG.md) | Release history |
<details>
<summary><b>My IDE cannot reach the proxy.</b></summary>
## License
The proxy is disabled by default: enable it on the Proxy page. The default port is `8045` (`8046` in development builds) and can be changed there. Copy the API key from the same page and make sure at least one account is in the pool.
Dual license:
</details>
- Original code from [AntigravityManager](https://github.com/Draculabo/AntigravityManager) by [Draculabo](https://github.com/Draculabo): [CC BY-NC-SA 4.0](LICENSE).
- All new code, features and architecture by [evandrodevbr](https://github.com/evandrodevbr): [MIT](LICENSE-MIT).
<details>
<summary><b>Do I need an API key?</b></summary>
The project is being migrated to MIT as the remaining original code is rewritten.
With an empty `api_key` the proxy runs in open mode. Once enabled it listens on `0.0.0.0`, so set a key and keep it private.
## Credits
</details>
Originally forked from [AntigravityManager](https://github.com/Draculabo/AntigravityManager). Since the fork the codebase has been largely rewritten by [evandrodevbr](https://github.com/evandrodevbr): UI/UX, usage analytics, traffic monitor, environment isolation, CI/CD, test infrastructure and documentation.
<details>
<summary><b>Can I use Claude models?</b></summary>
## Review checks (2026-09-30)
Yes, through model mapping on the Google accounts in the pool, not through separate Claude accounts.
Retry durations are parsed as complete values: `500ms` is milliseconds, and fractional components are rounded after summation. Invalid trailing text is rejected. Account and model lockouts honor the later expiration. IDE fallback configuration remains available at loopback when the OS denies network-interface enumeration.
</details>
Focused checks: `pnpm exec vitest run src/tests/unit/rate-limit-tracker.test.ts src/tests/unit/ipc/proxy-advanced-handler.test.ts`. Run `pnpm test`, `pnpm type-check`, `pnpm lint` and `pnpm format` for the full non-E2E gates. Native SQLite/keytar are mocked by the unit-test configuration; Electron packaging, real account switching and E2E still require separate validation.
<details>
<summary><b>Where are my tokens stored?</b></summary>
This review passes all 509 tests across 54 files, type checking, lint (327 existing warnings, no errors) and formatting with Node 24.19.0 and pnpm 10.11.0. The original lockfile is retained: its audit still reports two critical findings, in `tar` and `seroval`, requiring a separately validated dependency update.
In a separate `cloud_accounts.db`, with `token_json` and `quota_json` encrypted by AES-256-GCM. The master key lives in the OS credential store through `keytar`. Details in [Security model](#-security-model).
</details>
<details>
<summary><b>Can I use it commercially?</b></summary>
Check the [License](#-license) first: code inherited from AntigravityManager is CC BY-NC-SA 4.0 (non-commercial), new code is MIT.
</details>
## 🛣️ Limitations and next steps
- Upstream access goes through Google's `v1internal` Cloud Code endpoints and OAuth scopes ([`src/services/GoogleAPIService.ts`](src/services/GoogleAPIService.ts)). These are internal, undocumented APIs and may change without notice. The project is unofficial and not affiliated with Google or Anthropic.
- Accounts are added through Google OAuth; Claude models are reached through model mapping, not through separate Claude accounts.
- End-to-end tests are not run in CI (Electron needs a graphical environment); run `pnpm run test:e2e` locally.
- The Windows MSI is only produced when the WiX Toolset is available on the build machine; otherwise the Windows artifact is the ZIP.
- The workflows in `.github/workflows/` are written for GitHub (they call the `gh` CLI and the GitHub release publisher), so this README shows no CI badge.
- Next step stated by the project: migrate the remaining original code to MIT (see [License](#-license)).
## 🤝 Contributing
Read [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Releases are versioned by semantic-release from Conventional Commits. Before opening a PR, these must pass:
```bash
pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test
```
## 📄 License
Mixed licensing: code inherited from [AntigravityManager](https://github.com/Draculabo/AntigravityManager) (by Draculabo) is [CC BY-NC-SA 4.0](LICENSE) (non-commercial, share-alike); all new code is [MIT](LICENSE-MIT). The project is migrating to MIT as the remaining original code is rewritten, so check both files before any commercial use.
---
<div align="center">
<img src="docs/assets/logo.png" width="56" alt="Gemini Nexus logo">
<p><strong><a href="https://git.evandro.dev.br/evandro/gemini-nexus">Gemini Nexus on Gitea</a></strong> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Report an issue</a> · <a href="#-quickstart">Quickstart</a></p>
</div>
+187 -291
View File
@@ -1,366 +1,262 @@
<p align="center">
<img src="docs/assets/logo.png" alt="Gemini Nexus" width="128" height="128" />
</p>
<div align="center">
<h1 align="center">Gemini Nexus</h1>
<img src="assets/readme/hero.pt-BR.png" width="100%" alt="Gemini Nexus: gateway desktop que reúne contas Google atrás de uma API local compatível com OpenAI e Anthropic em http://localhost:8045/v1, trocando de conta quando a cota acaba">
<p align="center">
<strong>🚀 Gateway de IA multi-contas profissional para Google Gemini & Claude</strong>
</p>
![Stack](https://img.shields.io/badge/Stack-Electron_41_%C2%B7_React_19-47848F?logo=electron&logoColor=white)
![Status](https://img.shields.io/badge/status-v0.15.3_active-brightgreen)
![License](https://img.shields.io/badge/license-CC_BY--NC--SA_4.0_%2B_MIT-lightgrey)
<p align="center">
<a href="README.md">English</a> | Português | <a href="README.zh-CN.md">中文</a> | <a href="README.es.md">Español</a>
</p>
<p><strong><a href="#-início-rápido">Início rápido</a></strong> · <a href="#-documentação-e-desenvolvimento">Docs</a> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Issues</a></p>
<p align="center">
<a href="https://github.com/evandrodevbr/GeminiNexus/releases">
<img src="https://img.shields.io/github/v/release/evandrodevbr/GeminiNexus?style=flat-square" alt="Release" />
</a>
<a href="https://github.com/evandrodevbr/GeminiNexus/releases">
<img src="https://img.shields.io/github/downloads/evandrodevbr/GeminiNexus/total?style=flat-square&color=blue" alt="Downloads" />
</a>
<a href="https://github.com/evandrodevbr/GeminiNexus/blob/main/LICENSE">
<img src="https://img.shields.io/github/license/evandrodevbr/GeminiNexus?style=flat-square" alt="Licença" />
</a>
<img src="https://img.shields.io/badge/plataforma-Windows%20%7C%20macOS%20%7C%20Linux-informational?style=flat-square" alt="Plataforma" />
<img src="https://img.shields.io/badge/electron-latest-47848F?style=flat-square&logo=electron&logoColor=white" alt="Electron" />
</p>
<sub><a href="README.md">English</a> · Português · <a href="README.zh-CN.md">中文</a> · <a href="README.es.md">Español</a></sub>
> [!IMPORTANT]
> **Usuários do Windows:** Se você vir um aviso do SmartScreen **"O Windows protegeu o seu computador"** durante a instalação, clique em **"Mais informações"** e depois em **"Executar mesmo assim"**. Isso é um aviso de segurança esperado para aplicativos novos e não assinados.
---
## 📖 Sumário
- [✨ Por que o Gemini Nexus?](#-por-que-o-gemini-nexus)
- [🎯 Funcionalidades](#-funcionalidades)
- [📸 Screenshots](#-screenshots)
- [⚡ Instalação e Início Rápido](#-instalação-e-início-rápido)
- [🛠️ Stack Tecnológica](#️-stack-tecnológica)
- [💻 Desenvolvimento](#-desenvolvimento)
- [❓ FAQ](#-faq)
- [🤝 Contribuindo](#-contribuindo)
- [📄 Licença](#-licença)
---
## ✨ Por que o Gemini Nexus?
Ao usar IDEs e ferramentas de programação com IA, você já enfrentou estes problemas?
- 😫 **Limites de cota:** A cota da conta única acaba rápido, exigindo trocas manuais frequentes.
- 🔄 **Gestão de contas:** Gerenciar múltiplas contas do Google/Claude é cansativo.
- 📊 **Uso às cegas:** Você não sabe quantos tokens já consumiu ou quanta cota resta.
- 🔌 **Problemas de integração:** Precisa de um proxy local confiável que fale os protocolos OpenAI/Anthropic nativamente.
- 🔍 **Falta de transparência:** Não consegue ver o que está sendo enviado ou recebido pelo proxy nos bastidores.
O **Gemini Nexus** resolve tudo isso. É um aplicativo desktop profissional em Electron que funciona como um gateway inteligente entre suas ferramentas de desenvolvimento e o Google Gemini / Claude AI.
### Principais Vantagens
- ✅ **Pool de Contas Ilimitado** — Adicione quantas contas Google Gemini & Claude quiser.
- ✅ **Troca Automática Inteligente** — Rotaciona automaticamente para a próxima conta disponível quando a cota está baixa ou com rate limit.
- ✅ **Analytics de Uso em Tempo Real** — Dashboard nível SaaS com gráficos de área, indicadores de tendência e distribuição por modelo.
- ✅ **Observabilidade Completa do Proxy** — Monitor de tráfego ao vivo, replay de requisições e inspetor de capacidades dos modelos.
- ✅ **Compatível com OpenAI & Anthropic** — Proxy drop-in para Cursor, Windsurf, OpenCode e qualquer ferramenta compatível com OpenAI.
- ✅ **Seguro por Padrão** — Criptografia AES-256-GCM com gerenciamento nativo de credenciais do sistema operacional.
---
## 🎯 Funcionalidades
<table>
<tr>
<td width="50%">
<h3>☁️ Pool de Contas na Nuvem</h3>
<ul>
<li>Adicione contas ilimitadas do Google Gemini / Claude via OAuth</li>
<li>Exibe avatar, e-mail, status e último uso</li>
<li>Monitoramento de status em tempo real (Ativa, Rate Limited, Expirada)</li>
<li>Configuração de proxy URL por conta</li>
<li>Gerenciamento de perfil de identidade do dispositivo com histórico</li>
</ul>
</td>
<td width="50%">
<h3>📊 Dashboard de Analytics de Uso</h3>
<ul>
<li>Consumo de tokens em tempo real com auto-refresh a cada 15s</li>
<li>Gráficos de área para tokens de prompt & completion (diário/horário)</li>
<li>Indicadores de tendência (% de variação vs período anterior)</li>
<li>Sparklines inline nos cards de estatísticas</li>
<li>Ranking de distribuição por modelo com gráficos de barras horizontais</li>
<li>Visualização da proporção Prompt/Completion</li>
</ul>
</td>
</tr>
<tr>
<td width="50%">
<h3>🔌 Proxy de API Local (Gateway)</h3>
<ul>
<li>Endpoint compatível com OpenAI <code>/v1/chat/completions</code></li>
<li>Endpoint compatível com Anthropic <code>/v1/messages</code></li>
<li>Streaming SSE completo (testado com Cursor, Windsurf, OpenCode)</li>
<li>Mapeamento de modelos (ex: <code>claude-sonnet-4-6</code> → <code>gemini-3-flash</code>)</li>
<li>Porta, timeout e API key configuráveis</li>
<li>Controle de visibilidade de modelos</li>
</ul>
</td>
<td width="50%">
<h3>🔄 Troca Automática Inteligente</h3>
<ul>
<li>Modo de pool ilimitado com seleção inteligente de backup</li>
<li>Troca automática quando cota < 5% ou com rate limit</li>
<li>Monitoramento em segundo plano a cada 5 minutos</li>
<li>Fallback gracioso com rastreamento de motivo do status</li>
</ul>
</td>
</tr>
<tr>
<td width="50%">
<h3>🔍 Observabilidade do Proxy (Avançado)</h3>
<ul>
<li><strong>Monitor de Tráfego</strong> — Log ao vivo de requisições/respostas com latência e informações do modelo</li>
<li><strong>Replay de Requisições</strong> — Reproduza qualquer requisição registrada para debugging</li>
<li><strong>Capacidades dos Modelos</strong> — Inspecione suporte a visão, thinking, streaming e modo JSON</li>
<li><strong>Ferramentas para Devs</strong> — Geração de código cURL & Python, cópia com um clique</li>
</ul>
</td>
<td width="50%">
<h3>🔐 Segurança e Criptografia</h3>
<ul>
<li>Criptografia AES-256-GCM para todos os dados sensíveis</li>
<li>Integração com gerenciador de credenciais nativo (Keytar + SafeStorage)</li>
<li>Migração automática de dados legados em texto plano</li>
<li>Armazenamento criptografado de tokens & cotas por conta</li>
</ul>
</td>
</tr>
<tr>
<td width="50%">
<h3>⚙️ Configurações e Personalização</h3>
<ul>
<li>Suporte a temas Escuro / Claro / Sistema</li>
<li>Multi-idioma: English & Português (Brasil)</li>
<li>Override de proxy URL por conta</li>
<li>Toggles de visibilidade de modelos</li>
<li>Acesso ao diretório de logs</li>
</ul>
</td>
<td width="50%">
<h3>🖥️ Experiência Desktop</h3>
<ul>
<li>App nativo Electron com integração na bandeja do sistema</li>
<li>Sidebar retrátil com estado persistente</li>
<li>Layouts responsivos em todas as telas</li>
<li>Barra de status com indicadores ao vivo de proxy e conexão</li>
<li>Error boundaries com fallbacks amigáveis ao usuário</li>
</ul>
</td>
</tr>
</table>
---
</div>
## 📸 Screenshots
<p align="center">
<img src="docs/assets/main.png" alt="Main" width="80%" />
</p>
<p align="center">
<img src="docs/assets/2usage.png" alt="Usage" width="80%" />
</p>
<p align="center">
<img src="docs/assets/3proxy.png" alt="Proxy" width="80%" />
</p>
<p align="center">
<img src="docs/assets/4routing.png" alt="Routing" width="80%" />
</p>
<p align="center">
<img src="docs/assets/5docs.png" alt="Docs" width="80%" />
</p>
<p align="center">
<img src="docs/assets/6connections.png" alt="Connections" width="80%" />
</p>
<p align="center">
<img src="docs/assets/7config.png" alt="Config" width="80%" />
</p>
<p align="center"><img src="docs/assets/main.png" width="100%" alt="Página Accounts: uma conta Google no pool com barras de cota por modelo, o botão Auto-Switch e o contador de cota global"></p>
---
<details>
<summary>Mais screenshots: uso, proxy, roteamento, docs, conexões, configurações</summary>
## ⚡ Instalação e Início Rápido
<p align="center"><img src="docs/assets/2usage.png" alt="Analytics de uso" width="80%"></p>
<p align="center"><img src="docs/assets/3proxy.png" alt="Monitor do proxy" width="80%"></p>
<p align="center"><img src="docs/assets/4routing.png" alt="Configuração de roteamento" width="80%"></p>
<p align="center"><img src="docs/assets/5docs.png" alt="Documentação" width="80%"></p>
<p align="center"><img src="docs/assets/6connections.png" alt="Conexões ativas" width="80%"></p>
<p align="center"><img src="docs/assets/7config.png" alt="Configurações" width="80%"></p>
### 📦 Download
</details>
Você pode baixar os binários pré-compilados mais recentes para Windows, macOS e Linux na nossa [página de Releases](https://github.com/evandrodevbr/GeminiNexus/releases).
## 🎯 Funcionalidades
_(Consulte o aviso no topo desta página se você estiver usando o Windows e encontrar o prompt do SmartScreen)._
Usar IDEs com IA numa única conta Google significa cota que acaba, troca manual de conta e nenhuma visão do que o proxy manda para cima. O Gemini Nexus mantém todas as contas num pool e as serve por um único endpoint local.
### 🔌 Usando com IDEs de IA
<table>
<tr>
<td width="50%" valign="top"><b>Um endpoint local</b><br><code>POST /v1/chat/completions</code> (OpenAI), <code>POST /v1/messages</code> (Anthropic), <code>GET /v1/models</code> e <code>GET /v1/models/capabilities</code>, para que Cursor, Windsurf, OpenCode, Claude Code e clientes parecidos se conectem. Os nomes de modelo são mapeados por <code>custom_mapping</code> e <code>anthropic_mapping</code>.</td>
<td width="50%" valign="top"><b>Pool de contas</b><br>Contas Google adicionadas via OAuth, cada uma com status (Active, Rate Limited, Expired), horário do último uso e uma URL de proxy opcional por conta.</td>
</tr>
<tr>
<td width="50%" valign="top"><b>Troca automática</b><br>O <code>CloudMonitorService</code> consulta a cota a cada 5 minutos e o <code>AutoSwitchService</code> passa para outra conta quando a cota cai abaixo de 5 % ou a conta sofre rate limit.</td>
<td width="50%" valign="top"><b>Agendamento com circuit breaker</b><br><code>cache-first</code>, <code>balance</code> (padrão) ou <code>performance-first</code>, com circuit breaker por conta (backoff padrão 60 s → 5 min → 30 min → 2 h).</td>
</tr>
<tr>
<td width="50%" valign="top"><b>Uso e custo</b><br>Consumo de tokens por conta e por modelo, gráficos de prompt e completion e estimativa de custo com preço por modelo editável.</td>
<td width="50%" valign="top"><b>Inspetor de tráfego</b><br>Latência, status e modelo de cada requisição, replay de requisições registradas, snippets cURL e Python gerados e um Quick Setup para IDEs.</td>
</tr>
</table>
Com o aplicativo rodando e pelo menos uma conta adicionada, configure sua IDE preferida (Cursor, Windsurf, OpenCode, etc.):
As credenciais salvas são criptografadas com AES-256-GCM sob uma chave mestra guardada no chaveiro do sistema (veja [Modelo de segurança](#modelo-de-segurança)).
```plaintext
API Base URL: http://localhost:10100/v1
## Como funciona
1. **Adicione contas.** Entre com Google OAuth na página Accounts. Os tokens são criptografados antes de chegar ao SQLite.
2. **Aponte a IDE para o proxy.** Ative o proxy na página Proxy (ele vem desligado) e use `http://localhost:8045/v1` com a API key mostrada ali, no formato OpenAI ou Anthropic.
3. **O Nexus roteia cada requisição.** O token manager escolhe uma conta pelo modo de agendamento e pelo estado do circuit breaker, chama as APIs upstream do Google com o token OAuth dessa conta, e a troca automática entra em ação quando a cota cai abaixo de 5 % ou uma conta sofre rate limit.
O fluxo completo, com os componentes envolvidos, está em [Arquitetura](#arquitetura).
## ⚡ Início rápido
Ainda não há downloads prontos na página de [Releases do Gitea](https://git.evandro.dev.br/evandro/gemini-nexus/releases) (os workflows de release em `.github/workflows/` são para o GitHub), então compile pelo código-fonte.
| Ferramenta | Versão mínima |
|---|---|
| Node.js | 20+ (recomendado no `AGENTS.md`; o `.nvmrc` fixa 22.17.1) |
| pnpm | 10.11.0 (`packageManager`; o lockfile é `pnpm-lock.yaml`) |
| Toolchain nativa | exigida por `better-sqlite3` e `keytar`: Visual Studio 2022 Build Tools (C++) no Windows, Xcode Command Line Tools no macOS, `build-essential` + `python3` + `libsecret-1-dev` no Ubuntu (`base-devel` + `python` + `libsecret` no Arch) |
```bash
git clone https://git.evandro.dev.br/evandro/gemini-nexus.git
cd gemini-nexus
pnpm install # o postinstall roda scripts/setup-dev.js --check-only para conferir a toolchain
pnpm start # modo dev (Electron + Vite HMR)
pnpm run make # instaladores/pacotes para a plataforma atual
pnpm run make:win # Windows: extrai o WiX de wix314-binaries.zip e roda o make
```
Depois adicione pelo menos uma conta, ative o proxy (ele vem desligado) e aponte sua IDE para ele:
```text
API Base URL: http://localhost:8045/v1 (padrão, configurável na página Proxy; builds de desenvolvimento usam 8046)
API Key: (copie da página Proxy no app)
Model: gemini-3-flash (ou qualquer modelo mapeado)
Model: gemini-3-flash (ou qualquer modelo mapeado)
```
### 🛠️ Compilando pelo Código Fonte
> [!WARNING]
> Os builds não são assinados. Se o Windows mostrar "O Windows protegeu o seu computador", clique em **Mais informações → Executar mesmo assim**.
#### Pré-requisitos
Não existe `.env.example` e nenhuma variável é obrigatória. Variáveis opcionais lidas pelo código ou descritas nos docs:
- **Node.js** v20 ou superior
- **npm** (este projeto usa `package-lock.json`)
| Variável | Obrigatória | Descrição |
|---|---|---|
| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | Não | Encaminha as requisições de saída do app por um proxy local (veja inspeção TLS em [Modelo de segurança](#modelo-de-segurança)). |
| `NODE_EXTRA_CA_CERTS` | Não | Certificado de CA extra para o TLS do lado Node ao inspecionar tráfego. |
| `SENTRY_DSN` | Não | DSN do Sentry usado quando o envio de erros está ativo. |
#### Passos
## 🛠️ Stack
```bash
# Clone o repositório
git clone https://github.com/evandrodevbr/GeminiNexus.git
cd GeminiNexus
| Camada | Tecnologia |
|---|---|
| Shell desktop | Electron 41, Electron Forge, Vite |
| Interface | React 19, TypeScript, Tailwind CSS 4, Radix UI, gráficos Nivo, i18next |
| Fluxo de dados do app | TanStack Router e Query, oRPC sobre IPC do Electron |
| Proxy | NestJS 11 sobre Fastify |
| Armazenamento | SQLite (better-sqlite3 + Drizzle ORM), chaveiro do sistema via `keytar` |
| Logs e erros | Winston (arquivos rotativos), Sentry (opcional) |
| Testes | Vitest, Playwright |
# Instale as dependências
npm install
## Arquitetura
# Inicie o modo de desenvolvimento
npm start
# Compile para produção (ex: instalador Windows)
npm run make
```mermaid
flowchart LR
C["Cliente: Cursor, Windsurf, OpenCode, Claude Code"] -->|"/v1/chat/completions, /v1/messages"| P["Proxy NestJS, porta 8045"]
P --> S["Agendador de contas e circuit breaker"]
S -->|"conta Google OAuth"| G["APIs upstream do Google"]
M["CloudMonitor e AutoSwitch, cota a cada 5 min"] -->|"consulta de cota"| G
S -->|"lê contas"| DB[("SQLite: better-sqlite3 e Drizzle")]
M --> DB
K["AES-256-GCM, chave mestra no chaveiro do sistema"] -->|"criptografa tokens"| DB
```
---
1. Um cliente envia requisições no formato OpenAI ou Anthropic para o proxy NestJS (Fastify, escutando em `0.0.0.0`).
2. O guard do proxy confere a API key quando há uma configurada; com a chave vazia o proxy roda em modo aberto.
3. O token manager escolhe uma conta segundo o modo de agendamento e o estado do circuit breaker de cada conta, e chama as APIs upstream do Google com o token OAuth dessa conta.
4. O `CloudMonitorService` consulta a cota a cada 5 minutos e o `AutoSwitchService` troca a conta ativa quando a cota está abaixo de 5 % ou a conta sofre rate limit.
5. O renderer React 19 (TanStack Router e Query) conversa com o processo principal via oRPC sobre IPC; contas, uso e configurações ficam no SQLite (better-sqlite3 + Drizzle). Notas de design: [`docs/cloud_features.md`](docs/cloud_features.md).
## 🛠️ Stack Tecnológica
## Modelo de segurança
| Categoria | Tecnologias |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **Core** | [Electron](https://www.electronjs.org/), [React 19](https://react.dev/), [TypeScript](https://www.typescriptlang.org/) |
| **Build** | [Vite](https://vitejs.dev/), [Electron Forge](https://www.electronforge.io/) |
| **Estilização** | [Tailwind CSS v4](https://tailwindcss.com/), [Radix UI](https://www.radix-ui.com/), [Lucide Icons](https://lucide.dev/) |
| **Estado** | [TanStack Query](https://tanstack.com/query/latest), [TanStack Router](https://tanstack.com/router/latest) |
| **Backend** | [NestJS](https://nestjs.com/) (gateway interno), [ORPC](https://orpc.unnoq.com/) (RPC type-safe) |
| **Banco de Dados** | [Better-SQLite3](https://github.com/WiseLibs/better-sqlite3), [Drizzle ORM](https://orm.drizzle.team/) |
| **Gráficos** | [Nivo](https://nivo.rocks/) (Line, Bar, Pie) |
| **i18n** | [react-i18next](https://react.i18next.com/) |
| **Testes** | [Vitest](https://vitest.dev/), [Playwright](https://playwright.dev/) |
O Gemini Nexus guarda tokens OAuth de várias contas e repassa tráfego para cima, então o tratamento de credenciais é o centro do design. Tudo abaixo está implementado neste repositório; os limites aparecem onde existem.
---
- **Armazenamento e isolamento de credenciais.** `token_json` e `quota_json` são criptografados com AES-256-GCM (IV único por operação, autenticado) antes de chegar ao SQLite. A chave mestra fica no cofre de credenciais do sistema via `keytar` (Gerenciador de Credenciais do Windows, Keychain do macOS, Secret Service/libsecret no Linux), nunca num arquivo comum. Linhas legadas em texto puro são migradas na inicialização. As contas ficam num banco próprio (`cloud_accounts.db`), separado do banco local da IDE.
- **Mascaramento de logs.** Chaves como `token`, `refresh_token`, `api_key`, `authorization`, `cookie` e `client_secret` são trocadas por `[REDACTED]` antes de ir para o log ([`src/utils/sensitiveDataMasking.ts`](src/utils/sensitiveDataMasking.ts)); o logger de tráfego também oculta os headers `authorization`, `x-api-key` e `cookie`.
- **Log de requisições, não trilha de auditoria.** O Winston grava logs de API, tráfego e app em arquivos rotativos (log de API: 30 dias, 50 MB por arquivo). São logs operacionais, não uma trilha de auditoria à prova de adulteração; os arquivos `*-audit.json` são o controle de rotação do `winston-daily-rotate-file`.
- **Acesso ao proxy.** O proxy vem desligado. Quando ativado, escuta em `0.0.0.0`, e as requisições só são autenticadas quando `api_key` não está vazia (vazia significa modo aberto). Defina uma chave e mantenha-a privada.
- **Inspeção TLS (só para debug).** [`docs/proxyman-install.md`](docs/proxyman-install.md) e [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md) explicam como ler o tráfego HTTPS do app com o Proxyman: confiar na CA raiz dele, definir as variáveis de proxy e `NODE_EXTRA_CA_CERTS` e então iniciar o app. `NODE_TLS_REJECT_UNAUTHORIZED=0` (e a flag `-AllowInsecureTls` do script) é um ajuste temporário; nunca deixe ligado. Não faça commit de endereços de proxy, caminhos de certificado, cookies ou códigos OAuth, e oculte dados dos logs antes de compartilhá-los. `scripts/start-antigravity-with-proxyman.ps1` mira o cliente oficial do Antigravity instalado, não este app.
- **Envio de erros.** Os relatórios do Sentry (precisam de `SENTRY_DSN`) dependem da configuração `error_reporting_enabled`, que o `DEFAULT_APP_CONFIG` traz como `true`; desative em Settings para não enviar. O trecho com o nome de usuário do Windows é mascarado nas mensagens de exceção enviadas.
## 💻 Desenvolvimento
Versões suportadas e como reportar uma vulnerabilidade: [`SECURITY.md`](SECURITY.md).
```bash
# Iniciar ambiente de dev (Electron + Vite HMR)
npm start
## 💻 Documentação e desenvolvimento
# Executar linting
npm run lint
- [`docs/cloud_features.md`](docs/cloud_features.md): design do pool de contas, do monitoramento de cota e da troca automática.
- [`docs/proxyman-install.md`](docs/proxyman-install.md) e [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md): configuração da inspeção TLS (Windows).
- [`docs/OpencodeAPI.md`](docs/OpencodeAPI.md): integração com endpoint customizado do OpenCode (em português).
- [`cli/README.md`](cli/README.md): a ferramenta de linha de comando em Python.
- [`CONTRIBUTING.md`](CONTRIBUTING.md), [`SECURITY.md`](SECURITY.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), [`CHANGELOG.md`](CHANGELOG.md), [`LICENSE`](LICENSE), [`LICENSE-MIT`](LICENSE-MIT).
- Traduções: [English](README.md), [中文](README.zh-CN.md), [Español](README.es.md).
# Verificar tipos
npm run type-check
### Estrutura
# Formatar código
npm run format:write
# Rodar testes
npm test
```
### Estrutura do Projeto
```plaintext
```text
src/
├── actions/ # Ações do app e orquestração de fluxos
├── components/ # Componentes React
│ ├── proxy/ # Componentes da página Proxy (abas avançadas)
│ ├── usage/ # Componentes de analytics de uso (StatCard, ChartCard)
│ └── ui/ # Primitivos base de UI (baseados no Radix)
├── hooks/ # Custom React hooks
├── ipc/ # Electron IPC + handlers de banco de dados
├── layouts/ # Componentes de layout (MainLayout + sidebar)
├── localization/ # Recursos de tradução i18n
├── routes/ # Páginas TanStack Router (index, usage, proxy, settings)
├── server/ # Backend NestJS (serviço de gateway proxy)
├── services/ # Camada de serviços
├── types/ # Definições de tipos TypeScript + schemas Zod
└── utils/ # Funções utilitárias
├── components/ # UI (proxy/, usage/, primitivos ui/)
├── ipc/ # routers oRPC (account, cloud, config, gateway, usage...)
├── server/ # gateway proxy NestJS (módulos: proxy, usage)
├── services/ # AutoSwitchService, CloudMonitorService, GoogleAPIService
├── routes/ # index, usage, proxy, settings
├── utils/ # paths, logger, sensitiveDataMasking
└── tests/ # testes unitários (Vitest) e E2E (Playwright)
cli/ # CLI Python separada para trocar de conta e consultar cota
docs/ # notas de design e guias do Proxyman
scripts/ # setup-dev, build-windows, generate-assets
```
---
### Scripts
| Comando | O que faz |
|---|---|
| `pnpm start` | Roda o app em modo dev (`electron-forge start`, com `DEBUG=electron-forge:*`). |
| `pnpm run dev` | O mesmo que `start`. |
| `pnpm run package` | Empacota o app com o Electron Forge, sem gerar instaladores. |
| `pnpm run make` | Gera instaladores/pacotes para a plataforma atual. |
| `pnpm run make:win` | Helper de build no Windows: extrai o WiX de `wix314-binaries.zip`, coloca no `PATH` e roda `electron-forge make`. |
| `pnpm run publish` | Publica pelo Electron Forge. |
| `pnpm run setup` | Roda `scripts/setup-dev.js`: detecta a toolchain nativa e instala ou orienta a configuração. |
| `pnpm run postinstall` | `scripts/setup-dev.js --check-only`; roda sozinho depois do `pnpm install`. |
| `pnpm run lint` | ESLint no repositório. |
| `pnpm run format` | Checagem do Prettier. |
| `pnpm run format:write` | Prettier com escrita. |
| `pnpm test` | Testes unitários Vitest (`vitest run`). |
| `pnpm run test:watch` | Vitest em modo watch. |
| `pnpm run test:unit` | Vitest (modo padrão). |
| `pnpm run test:e2e` | Testes E2E com Playwright. |
| `pnpm run test:all` | Testes unitários e depois Playwright. |
| `pnpm run type-check` | `tsc --noEmit`. |
## ❓ FAQ
<details>
<summary><b>P: Aviso do Windows SmartScreen ("O Windows protegeu o seu computador") durante a instalação?</b></summary>
<summary><b>O Windows mostra "O Windows protegeu o seu computador". É normal?</b></summary>
Sim, este é um aviso comum para novos aplicativos não assinados. Clique em **"Mais informações"** e depois em **"Executar mesmo assim"**. Veja o aviso no topo do README para mais detalhes.
Sim. Os builds não são assinados. Clique em **Mais informações → Executar mesmo assim**.
</details>
<details>
<summary><b>P: O app não inicia ao compilar pelo código fonte?</b></summary>
<summary><b>Minha IDE não alcança o proxy.</b></summary>
O proxy vem desligado: ative-o na página Proxy. A porta padrão é `8045` (`8046` em builds de desenvolvimento) e pode ser trocada ali. Copie a API key da mesma página e confira se há pelo menos uma conta no pool.
1. Certifique-se de que todas as dependências estão instaladas: `npm install`.
2. Verifique se a versão do Node.js é >= 20.
3. Tente deletar `node_modules` e reinstalar.
4. No Windows, certifique-se de que o WiX Toolset está disponível para o comando `npm run make`.
</details>
<details>
<summary><b>P: O login da conta falhou?</b></summary>
<summary><b>Preciso de uma API key?</b></summary>
Com `api_key` vazia o proxy roda em modo aberto. Quando ativado ele escuta em `0.0.0.0`, então defina uma chave e mantenha-a privada.
1. Verifique se a conexão com a internet está funcionando.
2. Tente limpar os dados do app e fazer login novamente.
3. Verifique se a conta está restrita pelo Google/Claude.
</details>
<details>
<summary><b>P: A IDE não consegue conectar ao proxy?</b></summary>
<summary><b>Dá para usar modelos Claude?</b></summary>
Sim, por mapeamento de modelos nas contas Google do pool, não por contas Claude separadas.
1. Certifique-se de que o proxy está rodando (indicador verde na barra de status).
2. Verifique se a porta corresponde à configuração da sua IDE (padrão: `10100`).
3. Copie a API key da página Proxy e cole nas configurações da sua IDE.
4. Verifique se pelo menos uma conta está ativa na página de Contas.
</details>
<details>
<summary><b>P: A contagem de tokens mostra zero?</b></summary>
<summary><b>Onde ficam meus tokens?</b></summary>
Num `cloud_accounts.db` separado, com `token_json` e `quota_json` criptografados em AES-256-GCM. A chave mestra fica no cofre de credenciais do sistema via `keytar`. Detalhes em [Modelo de segurança](#modelo-de-segurança).
1. Este era um bug conhecido em versões anteriores — por favor, atualize para a versão mais recente.
2. O rastreamento de tokens agora lida corretamente com metadados de streaming e contagens estimadas.
3. Os dados de uso são atualizados a cada 15 segundos na página de Analytics de Uso.
</details>
---
<details>
<summary><b>Posso usar comercialmente?</b></summary>
Veja a [Licença](#-licença) antes: o código herdado do AntigravityManager é CC BY-NC-SA 4.0 (não comercial) e o código novo é MIT.
</details>
## Limitações e próximos passos
- O acesso upstream passa pelos endpoints `v1internal` do Cloud Code do Google e por escopos OAuth ([`src/services/GoogleAPIService.ts`](src/services/GoogleAPIService.ts)). São APIs internas, sem documentação, que podem mudar sem aviso. O projeto é não oficial e não tem vínculo com o Google nem com a Anthropic.
- As contas entram via Google OAuth; os modelos Claude são acessados por mapeamento de modelos, não por contas Claude separadas.
- Os testes end-to-end não rodam no CI (o Electron precisa de ambiente gráfico); rode `pnpm run test:e2e` localmente.
- O MSI do Windows só é gerado quando o WiX Toolset está disponível na máquina de build; caso contrário o artefato do Windows é o ZIP.
- Os workflows em `.github/workflows/` foram escritos para o GitHub (chamam o CLI `gh` e o publisher de releases do GitHub), por isso este README não mostra badge de CI.
- Próximo passo declarado pelo projeto: migrar o código original restante para MIT (veja a [Licença](#-licença)).
## 🤝 Contribuindo
Contribuições são bem-vindas! Leia o `CONTRIBUTING.md` para mais detalhes.
Leia o [`CONTRIBUTING.md`](CONTRIBUTING.md) e o [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). As versões são geradas pelo semantic-release a partir de Conventional Commits. Antes de abrir um PR, isto precisa passar:
---
```bash
pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test
```
## 📄 Licença
Este projeto utiliza uma estrutura de licença dual:
- **Código original** do [AntigravityManager](https://github.com/Draculabo/AntigravityManager) por [Draculabo](https://github.com/Draculabo): Licenciado sob [CC BY-NC-SA 4.0](LICENSE).
- **Todo o código novo, funcionalidades e arquitetura** por [evandrodevbr](https://github.com/evandrodevbr): Licenciado sob a [Licença MIT](LICENSE-MIT).
> 🔄 **Aviso de Migração:** Este projeto está sendo ativamente migrado para uma licença totalmente open-source (MIT). À medida que o código original restante é progressivamente reescrito, todo o projeto será transicionado para MIT. Estamos comprometidos em tornar o Gemini Nexus 100% open-source.
Licença mista: o código herdado do [AntigravityManager](https://github.com/Draculabo/AntigravityManager) (de Draculabo) é [CC BY-NC-SA 4.0](LICENSE) (não comercial, compartilhamento pela mesma licença); todo o código novo é [MIT](LICENSE-MIT). O projeto está migrando para MIT à medida que o código original restante é reescrito, então confira os dois arquivos antes de qualquer uso comercial.
---
## 🙏 Créditos
<div align="center">
Este projeto foi originalmente um fork de [AntigravityManager](https://github.com/Draculabo/AntigravityManager) criado por [Draculabo](https://github.com/Draculabo). O conceito inicial de proxy e a estrutura base do Electron foram baseados em seu trabalho.
<img src="docs/assets/logo.png" width="56" alt="Logo do Gemini Nexus">
Desde o fork, **a grande maioria do código base foi reescrita, redesenhada e expandida** por [evandrodevbr](https://github.com/evandrodevbr), incluindo mas não se limitando a:
<p><strong><a href="https://git.evandro.dev.br/evandro/gemini-nexus">Gemini Nexus no Gitea</a></strong> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Reportar um problema</a> · <a href="#-início-rápido">Início rápido</a></p>
- Redesign completo de UI/UX (navegação, contas, analytics de uso, gerenciamento de proxy)
- Dashboard de Analytics de Uso com rastreamento de custos, médias de tokens e integração com OpenRouter
- Monitor de tráfego com inspeção de tokens/custos por requisição
- Isolamento de ambiente (dev/prod), pipeline CI/CD e infraestrutura de testes
- Configuração Rápida para IDEs (OpenCode, Cursor, VS Code, Claude Code)
- Configuração personalizada de preços de modelos
- Toda a documentação e internacionalização (EN, PT-BR, ES, ZH-CN)
</div>
+194 -277
View File
@@ -1,345 +1,262 @@
<p align="center">
<img src="docs/assets/logo.png" alt="Gemini Nexus" width="128" height="128" />
</p>
<div align="center">
<h1 align="center">Gemini Nexus</h1>
<img src="assets/readme/hero.zh-CN.png" width="100%" alt="Gemini Nexus:桌面网关,把多个 Google 账号汇成号池,在 http://localhost:8045/v1 提供兼容 OpenAI 与 Anthropic 的本地 API,配额不足时自动切换账号">
<p align="center">
<strong>🚀 专业的多账户 AI 网关,支持 Google Gemini 和 Claude</strong>
</p>
![Stack](https://img.shields.io/badge/Stack-Electron_41_%C2%B7_React_19-47848F?logo=electron&logoColor=white)
![Status](https://img.shields.io/badge/status-v0.15.3_active-brightgreen)
![License](https://img.shields.io/badge/license-CC_BY--NC--SA_4.0_%2B_MIT-lightgrey)
<p align="center">
<a href="README.md">English</a> | <a href="README.pt-BR.md">Português</a> | 中文 | <a href="README.es.md">Español</a>
</p>
<p><strong><a href="#-快速开始">快速开始</a></strong> · <a href="#-文档与开发">文档</a> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Issues</a></p>
<p align="center">
<a href="https://github.com/evandrodevbr/GeminiNexus/releases">
<img src="https://img.shields.io/github/v/release/evandrodevbr/GeminiNexus?style=flat-square" alt="版本" />
</a>
<a href="https://github.com/evandrodevbr/GeminiNexus/releases">
<img src="https://img.shields.io/github/downloads/evandrodevbr/GeminiNexus/total?style=flat-square&color=blue" alt="下载量" />
</a>
<a href="https://github.com/evandrodevbr/GeminiNexus/blob/main/LICENSE">
<img src="https://img.shields.io/github/license/evandrodevbr/GeminiNexus?style=flat-square" alt="许可证" />
</a>
<img src="https://img.shields.io/badge/平台-Windows%20%7C%20macOS%20%7C%20Linux-informational?style=flat-square" alt="平台" />
<img src="https://img.shields.io/badge/electron-latest-47848F?style=flat-square&logo=electron&logoColor=white" alt="Electron" />
</p>
<sub><a href="README.md">English</a> · <a href="README.pt-BR.md">Português</a> · 中文 · <a href="README.es.md">Español</a></sub>
> [!IMPORTANT]
> **Windows 用户:** 如果在安装过程中看到 **“Windows 已保护你的电脑”** (SmartScreen) 警告,请点击 **“更多信息”** (More info),然后点击 **“仍要运行”** (Run anyway)。这是未签名的新应用预期的安全提示,属于正常现象。
---
## 📖 目录
- [✨ 为什么选择 Gemini Nexus?](#-为什么选择-gemini-nexus)
- [🎯 功能特性](#-功能特性)
- [📸 截图](#-截图)
- [⚡ 安装与快速开始](#-安装与快速开始)
- [🛠️ 技术栈](#️-技术栈)
- [💻 开发](#-开发)
- [❓ 常见问题](#-常见问题)
- [🤝 参与贡献](#-参与贡献)
- [📄 许可证](#-许可证)
---
## ✨ 为什么选择 Gemini Nexus?
在使用 AI 驱动的 IDE 和编程工具时,你是否遇到过这些问题?
- 😫 **配额限制:** 单个账户配额很快用完,需要频繁手动切换。
- 🔄 **账户管理:** 管理多个 Google/Claude 账户非常繁琐。
- 📊 **盲目使用:** 不知道已经消耗了多少 Token 或还剩多少配额。
- 🔌 **集成问题:** 需要一个可靠的本地 API 代理,并且必须原生支持 OpenAI/Anthropic 协议。
- 🔍 **缺乏透明度:** 无法查看代理在后台实际发送或接收的数据。
**Gemini Nexus** 解决所有这些问题。它是一个专业的 Electron 桌面应用,作为你的开发工具和 Google Gemini / Claude AI 之间的智能网关。
### 核心价值主张
- ✅ **无限账户池** — 添加任意数量的 Google Gemini 和 Claude 账户。
- ✅ **智能自动切换** — 当配额不足或被限速时自动轮换到下一个可用账户。
- ✅ **实时使用分析** — SaaS 级仪表板,配备面积图、趋势指标和模型分布。
- ✅ **完整的代理可观测性** — 实时流量监控、请求重放和模型能力检查器。
- ✅ **兼容 OpenAI 和 Anthropic** — 即插即用的代理,支持 Cursor、Windsurf、OpenCode 以及任何兼容 OpenAI 的工具。
- ✅ **默认安全** — AES-256-GCM 加密,配合操作系统原生凭证管理。
---
## 🎯 功能特性
<table>
<tr>
<td width="50%">
<h3>☁️ 云端账户池</h3>
<ul>
<li>通过 OAuth 添加无限量的 Google Gemini / Claude 账户</li>
<li>显示头像、邮箱、状态和最后使用时间</li>
<li>实时状态监控(活跃、限速、过期)</li>
<li>每个账户可独立配置代理 URL</li>
<li>设备身份档案管理及历史记录</li>
</ul>
</td>
<td width="50%">
<h3>📊 使用分析仪表板</h3>
<ul>
<li>实时 Token 消耗,每 15 秒自动刷新</li>
<li>面积图展示每日/每小时的 Prompt 和 Completion Token</li>
<li>趋势指标(与上一周期相比的百分比变化)</li>
<li>统计卡片内嵌迷你折线图(Sparklines)</li>
<li>水平柱状图展示模型分布排名</li>
<li>Prompt/Completion 比例可视化</li>
</ul>
</td>
</tr>
<tr>
<td width="50%">
<h3>🔌 本地 API 代理(网关)</h3>
<ul>
<li>兼容 OpenAI <code>/v1/chat/completions</code></li>
<li>兼容 Anthropic <code>/v1/messages</code></li>
<li>完整的 SSE 流式传输支持(已在 Cursor, Windsurf, OpenCode 测试)</li>
<li>模型映射(如 <code>claude-sonnet-4-6</code> → <code>gemini-3-flash</code>)</li>
<li>可配置端口、超时时间和 API 密钥</li>
<li>模型可见性控制(隐藏/显示特定模型)</li>
</ul>
</td>
<td width="50%">
<h3>🔄 智能自动切换</h3>
<ul>
<li>无限池模式,智能备份选择</li>
<li>配额低于 5% 或被限速时自动切换</li>
<li>每 5 分钟后台监控</li>
<li>优雅降级,带状态原因追踪</li>
</ul>
</td>
</tr>
<tr>
<td width="50%">
<h3>🔍 代理可观测性(高级)</h3>
<ul>
<li><strong>流量监控</strong> — 实时请求/响应日志,含延迟和模型信息</li>
<li><strong>请求重放</strong> — 重放任意请求进行调试</li>
<li><strong>模型能力</strong> — 检查每个模型对视觉、思考、流式、JSON 模式的支持</li>
<li><strong>开发者工具</strong> — cURL 和 Python 代码生成,一键复制</li>
</ul>
</td>
<td width="50%">
<h3>🔐 安全与加密</h3>
<ul>
<li>所有敏感数据采用 AES-256-GCM 加密</li>
<li>集成操作系统原生凭证管理器 (Keytar + SafeStorage)</li>
<li>自动迁移旧版明文数据</li>
<li>每个账户的 Token 和配额均加密存储</li>
</ul>
</td>
</tr>
<tr>
<td width="50%">
<h3>⚙️ 设置与自定义</h3>
<ul>
<li>深色 / 浅色 / 跟随系统主题</li>
<li>多语言:English & Português (Brasil)</li>
<li>每个账户可独立覆盖代理 URL</li>
<li>模型可见性开关</li>
<li>日志目录访问</li>
</ul>
</td>
<td width="50%">
<h3>🖥️ 桌面体验</h3>
<ul>
<li>原生 Electron 应用,系统托盘集成</li>
<li>可折叠侧边栏,状态持久化</li>
<li>响应式布局适配所有视图</li>
<li>状态栏实时显示代理和连接指标</li>
<li>错误边界处理以及友好的用户提示</li>
</ul>
</td>
</tr>
</table>
---
</div>
## 📸 截图
<p align="center">
<img src="docs/assets/main.png" alt="Main" width="80%" />
</p>
<p align="center">
<img src="docs/assets/2usage.png" alt="Usage" width="80%" />
</p>
<p align="center">
<img src="docs/assets/3proxy.png" alt="Proxy" width="80%" />
</p>
<p align="center">
<img src="docs/assets/4routing.png" alt="Routing" width="80%" />
</p>
<p align="center">
<img src="docs/assets/5docs.png" alt="Docs" width="80%" />
</p>
<p align="center">
<img src="docs/assets/6connections.png" alt="Connections" width="80%" />
</p>
<p align="center">
<img src="docs/assets/7config.png" alt="Config" width="80%" />
</p>
<p align="center"><img src="docs/assets/main.png" width="100%" alt="Accounts 页面:号池中的一个 Google 账号,带按模型显示的配额条、Auto-Switch 开关和全局配额计数"></p>
---
<details>
<summary>更多截图:用量、代理、路由、文档、连接、设置</summary>
## ⚡ 安装与快速开始
<p align="center"><img src="docs/assets/2usage.png" alt="用量分析" width="80%"></p>
<p align="center"><img src="docs/assets/3proxy.png" alt="代理监控" width="80%"></p>
<p align="center"><img src="docs/assets/4routing.png" alt="路由配置" width="80%"></p>
<p align="center"><img src="docs/assets/5docs.png" alt="文档" width="80%"></p>
<p align="center"><img src="docs/assets/6connections.png" alt="活动连接" width="80%"></p>
<p align="center"><img src="docs/assets/7config.png" alt="设置" width="80%"></p>
### 📦 下载
</details>
您可以从我们的 [Releases 页面](https://github.com/evandrodevbr/GeminiNexus/releases) 下载适用于 Windows、macOS 和 Linux 的最新预编译版本。
## 🎯 功能特性
_(如果您使用的是 Windows 并在安装时遇到了 SmartScreen 提示,请参阅页面顶部的警告)。_
只用一个 Google 账号配合 AI IDE,意味着配额很快耗尽、要手动切换账号,也看不到代理到底向上游发送了什么。Gemini Nexus 把所有账号放进一个号池,通过一个本地端点统一提供服务。
### 🔌 配合 AI IDE 使用
<table>
<tr>
<td width="50%" valign="top"><b>一个本地端点</b><br><code>POST /v1/chat/completions</code>(OpenAI)、<code>POST /v1/messages</code>(Anthropic)、<code>GET /v1/models</code> 和 <code>GET /v1/models/capabilities</code>,Cursor、Windsurf、OpenCode、Claude Code 等客户端都能接入。模型名通过 <code>custom_mapping</code> 和 <code>anthropic_mapping</code> 映射。</td>
<td width="50%" valign="top"><b>账号池</b><br>通过 OAuth 添加 Google 账号,每个账号显示状态(Active、Rate Limited、Expired)、最近使用时间,并可单独设置代理 URL。</td>
</tr>
<tr>
<td width="50%" valign="top"><b>自动切换</b><br><code>CloudMonitorService</code> 每 5 分钟查询一次配额,当配额低于 5 % 或账号被限流时,<code>AutoSwitchService</code> 切换到其他账号。</td>
<td width="50%" valign="top"><b>带熔断器的调度</b><br><code>cache-first</code>、<code>balance</code>(默认)或 <code>performance-first</code>,每个账号都有熔断器(默认退避 60 s → 5 min → 30 min → 2 h)。</td>
</tr>
<tr>
<td width="50%" valign="top"><b>用量与成本</b><br>按账号和模型统计 token 用量,提供 prompt 与 completion 图表,并根据可编辑的模型单价估算成本。</td>
<td width="50%" valign="top"><b>流量检查器</b><br>每个请求的延迟、状态和模型,可重放已记录的请求,生成 cURL 和 Python 代码片段,并提供 IDE 快速配置(Quick Setup)。</td>
</tr>
</table>
在代理运行并至少添加一个账户后,配置您首选的 IDE(Cursor、Windsurf、OpenCode 等):
已保存的凭据使用 AES-256-GCM 加密,主密钥存放在系统钥匙串中(见[安全模型](#安全模型))。
```plaintext
API Base URL: http://localhost:10100/v1
API Key: (从应用的 Proxy 页面复制)
Model: gemini-3-flash (或您选择的任何映射模型)
```
## 工作原理
### 🛠️ 从源码构建
1. **添加账号。** 在 Accounts 页面通过 Google OAuth 登录。token 在写入 SQLite 之前就已加密。
2. **让 IDE 指向代理。** 在 Proxy 页面启用代理(默认关闭),使用 `http://localhost:8045/v1` 和页面上显示的 API key,OpenAI 或 Anthropic 格式均可。
3. **Nexus 路由每个请求。** token manager 根据调度模式和熔断器状态选择账号,用该账号的 OAuth token 调用 Google 上游 API;当配额低于 5 % 或账号被限流时,自动切换生效。
#### 前置要求
包含各组件的完整流程见[架构](#架构)。
- **Node.js** v20 或更高版本
- **npm** (本项目使用 `package-lock.json`)
## ⚡ 快速开始
#### 步骤
目前 [Gitea Releases](https://git.evandro.dev.br/evandro/gemini-nexus/releases) 页面还没有预编译下载(`.github/workflows/` 中的发布工作流面向 GitHub),因此请从源码构建。
| 工具 | 最低版本 |
|---|---|
| Node.js | 20+(`AGENTS.md` 中推荐;`.nvmrc` 固定为 22.17.1) |
| pnpm | 10.11.0(`packageManager`;锁文件为 `pnpm-lock.yaml`) |
| 原生工具链 | `better-sqlite3` 和 `keytar` 需要:Windows 上的 Visual Studio 2022 Build Tools(C++)、macOS 上的 Xcode Command Line Tools、Ubuntu 上的 `build-essential` + `python3` + `libsecret-1-dev`(Arch 上为 `base-devel` + `python` + `libsecret`) |
```bash
# 克隆仓库
git clone https://github.com/evandrodevbr/GeminiNexus.git
cd GeminiNexus
# 安装依赖
npm install
# 启动开发环境
npm start
# 构建生产版本(例如 Windows 安装程序)
npm run make
git clone https://git.evandro.dev.br/evandro/gemini-nexus.git
cd gemini-nexus
pnpm install # postinstall 会运行 scripts/setup-dev.js --check-only 检查工具链
pnpm start # 开发模式(Electron + Vite HMR)
pnpm run make # 为当前平台生成安装包/软件包
pnpm run make:win # Windows:从 wix314-binaries.zip 解压 WiX,然后运行 make
```
---
然后至少添加一个账号,启用代理(默认关闭),并把 IDE 指向它:
```text
API Base URL: http://localhost:8045/v1 (默认值,可在 Proxy 页面修改;开发构建使用 8046)
API Key: (从应用的 Proxy 页面复制)
Model: gemini-3-flash (或任意已映射的模型)
```
> [!WARNING]
> 构建产物没有代码签名。如果 Windows 提示“Windows 已保护你的电脑”,请点击 **更多信息 → 仍要运行**。
项目没有 `.env.example`,也没有必填变量。代码读取或文档中提到的可选变量:
| 变量 | 必填 | 说明 |
|---|---|---|
| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | 否 | 让应用的出站请求经过本地代理(TLS 检查见[安全模型](#安全模型))。 |
| `NODE_EXTRA_CA_CERTS` | 否 | 检查流量时,Node 侧 TLS 使用的额外 CA 证书。 |
| `SENTRY_DSN` | 否 | 启用错误上报时使用的 Sentry DSN。 |
## 🛠️ 技术栈
| 分类 | 技术 |
| ---------- | --------------------------------------- |
| **核心** | Electron, React 19, TypeScript |
| **构建** | Vite, Electron Forge |
| **样式** | Tailwind CSS v4, Radix UI, Lucide Icons |
| **状态** | TanStack Query, TanStack Router |
| **后端** | NestJS (内部网关), ORPC (类型安全 RPC) |
| **数据库** | Better-SQLite3, Drizzle ORM |
| **图表** | Nivo (Line, Bar, Pie) |
| **测试** | Vitest, Playwright |
| 层 | 技术 |
|---|---|
| 桌面外壳 | Electron 41、Electron Forge、Vite |
| 界面 | React 19、TypeScript、Tailwind CSS 4、Radix UI、Nivo 图表、i18next |
| 应用数据流 | TanStack Router 与 Query,基于 Electron IPC 的 oRPC |
| 代理 | NestJS 11 + Fastify |
| 存储 | SQLite(better-sqlite3 + Drizzle ORM),通过 `keytar` 使用系统钥匙串 |
| 日志与错误 | Winston(滚动日志文件)、Sentry(可选) |
| 测试 | Vitest、Playwright |
---
## 架构
## 💻 开发
```bash
# 启动开发环境 (Electron + Vite HMR)
npm start
# 运行代码规范检查
npm run lint
# 类型检查
npm run type-check
# 格式化代码
npm run format:write
# 运行测试
npm test
```mermaid
flowchart LR
C["客户端:Cursor、Windsurf、OpenCode、Claude Code"] -->|"/v1/chat/completions, /v1/messages"| P["NestJS 代理,端口 8045"]
P --> S["账号调度器与熔断器"]
S -->|"Google OAuth 账号"| G["Google 上游 API"]
M["CloudMonitor 与 AutoSwitch,每 5 分钟查询配额"] -->|"配额轮询"| G
S -->|"读取账号"| DB[("SQLite:better-sqlite3 与 Drizzle")]
M --> DB
K["AES-256-GCM,主密钥在系统钥匙串"] -->|"加密 token"| DB
```
---
1. 客户端向 NestJS 代理(Fastify,绑定 `0.0.0.0`)发送 OpenAI 或 Anthropic 格式的请求。
2. 配置了 API key 时,代理守卫会校验它;key 为空时代理以开放模式运行。
3. token manager 根据调度模式和各账号的熔断器状态选择账号,再用该账号的 OAuth token 调用 Google 上游 API。
4. `CloudMonitorService` 每 5 分钟查询一次配额,当配额低于 5 % 或账号被限流时,`AutoSwitchService` 切换当前账号。
5. React 19 渲染进程(TanStack Router 与 Query)通过 IPC 上的 oRPC 与主进程通信;账号、用量和设置保存在 SQLite(better-sqlite3 + Drizzle)中。设计说明:[`docs/cloud_features.md`](docs/cloud_features.md)。
## 安全模型
Gemini Nexus 保存多个账号的 OAuth token 并向上游转发流量,因此凭据处理是设计的核心。以下内容均已在本仓库中实现;存在限制的地方都已注明。
- **凭据存储与隔离。** `token_json` 和 `quota_json` 在写入 SQLite 之前使用 AES-256-GCM 加密(每次操作使用唯一 IV,带认证)。主密钥通过 `keytar` 存放在系统凭据存储中(Windows 凭据管理器、macOS 钥匙串、Linux Secret Service/libsecret),绝不写入普通文件。旧的明文记录会在启动时迁移。账号保存在独立的数据库(`cloud_accounts.db`)中,与 IDE 的本地数据库分开。
- **日志脱敏。** `token`、`refresh_token`、`api_key`、`authorization`、`cookie`、`client_secret` 等键在写入日志前会被替换为 `[REDACTED]`([`src/utils/sensitiveDataMasking.ts`](src/utils/sensitiveDataMasking.ts));流量日志还会隐去 `authorization`、`x-api-key` 和 `cookie` 请求头。
- **请求日志,而非审计追踪。** Winston 把 API、流量和应用日志写入滚动文件(API 日志:保留 30 天,每个文件 50 MB)。这些是运维日志,不是防篡改的审计追踪;`*-audit.json` 文件是 `winston-daily-rotate-file` 的轮转记录。
- **代理访问。** 代理默认关闭。启用后监听 `0.0.0.0`,只有在 `api_key` 非空时才会校验请求(为空即开放模式)。请设置 key 并妥善保管。
- **TLS 检查(仅用于调试)。** [`docs/proxyman-install.md`](docs/proxyman-install.md) 和 [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md) 说明如何用 Proxyman 查看应用的 HTTPS 流量:信任其根 CA,设置代理变量和 `NODE_EXTRA_CA_CERTS`,然后启动应用。`NODE_TLS_REJECT_UNAUTHORIZED=0`(以及脚本的 `-AllowInsecureTls` 参数)只是临时覆盖,切勿一直开启。不要提交代理地址、证书路径、cookie 或 OAuth code,分享日志前请先脱敏。`scripts/start-antigravity-with-proxyman.ps1` 针对的是已安装的官方 Antigravity 客户端,而不是本应用。
- **错误上报。** Sentry 上报(需要 `SENTRY_DSN`)受 `error_reporting_enabled` 设置控制,`DEFAULT_APP_CONFIG` 中默认为 `true`;可在 Settings 中关闭。上报的异常消息中会屏蔽 Windows 用户名部分。
支持的版本以及如何报告漏洞:[`SECURITY.md`](SECURITY.md)。
## 💻 文档与开发
- [`docs/cloud_features.md`](docs/cloud_features.md):账号池、配额监控与自动切换的设计。
- [`docs/proxyman-install.md`](docs/proxyman-install.md) 和 [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md):TLS 检查配置(Windows)。
- [`docs/OpencodeAPI.md`](docs/OpencodeAPI.md):OpenCode 自定义端点集成(葡萄牙语)。
- [`cli/README.md`](cli/README.md):Python 命令行工具。
- [`CONTRIBUTING.md`](CONTRIBUTING.md)、[`SECURITY.md`](SECURITY.md)、[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)、[`CHANGELOG.md`](CHANGELOG.md)、[`LICENSE`](LICENSE)、[`LICENSE-MIT`](LICENSE-MIT)。
- 其他语言:[English](README.md)、[Português](README.pt-BR.md)、[Español](README.es.md)。
### 目录结构
```text
src/
├── components/ # UI(proxy/、usage/、ui/ 基础组件)
├── ipc/ # oRPC 路由(account、cloud、config、gateway、usage...)
├── server/ # NestJS 代理网关(模块:proxy、usage)
├── services/ # AutoSwitchService、CloudMonitorService、GoogleAPIService
├── routes/ # index、usage、proxy、settings
├── utils/ # paths、logger、sensitiveDataMasking
└── tests/ # 单元测试(Vitest)与 E2E(Playwright)
cli/ # 独立的 Python CLI,用于切换账号和查询配额
docs/ # 设计说明与 Proxyman 指南
scripts/ # setup-dev、build-windows、generate-assets
```
### 脚本
| 命令 | 作用 |
|---|---|
| `pnpm start` | 以开发模式运行应用(`electron-forge start`,带 `DEBUG=electron-forge:*`)。 |
| `pnpm run dev` | 与 `start` 相同。 |
| `pnpm run package` | 用 Electron Forge 打包应用,不生成安装包。 |
| `pnpm run make` | 为当前平台生成安装包/软件包。 |
| `pnpm run make:win` | Windows 构建辅助:从 `wix314-binaries.zip` 解压 WiX,加入 `PATH`,运行 `electron-forge make`。 |
| `pnpm run publish` | 通过 Electron Forge 发布。 |
| `pnpm run setup` | 运行 `scripts/setup-dev.js`:检测原生工具链并安装或引导配置。 |
| `pnpm run postinstall` | `scripts/setup-dev.js --check-only`;在 `pnpm install` 后自动运行。 |
| `pnpm run lint` | 对仓库运行 ESLint。 |
| `pnpm run format` | Prettier 检查。 |
| `pnpm run format:write` | Prettier 写入格式化。 |
| `pnpm test` | Vitest 单元测试(`vitest run`)。 |
| `pnpm run test:watch` | Vitest 监听模式。 |
| `pnpm run test:unit` | Vitest(默认模式)。 |
| `pnpm run test:e2e` | Playwright E2E 测试。 |
| `pnpm run test:all` | 先跑单元测试,再跑 Playwright。 |
| `pnpm run type-check` | `tsc --noEmit`。 |
## ❓ 常见问题
<details>
<summary><b>问:安装时出现 Windows SmartScreen 警告("Windows 已保护你的电脑")?</b></summary>
<summary><b>Windows 提示“Windows 已保护你的电脑”,正常吗?</b></summary>
是的,对于未签名的新应用,这是一个常见的警告。请点击 **"更多信息"** (More info),然后点击 **"仍要运行"** (Run anyway)。详情请参阅 README 顶部的提示。
正常。构建产物没有代码签名。请点击 **更多信息 → 仍要运行**。
</details>
<details>
<summary><b>问:从源码构建时应用无法启动?</b></summary>
<summary><b>IDE 连不上代理。</b></summary>
代理默认关闭:请在 Proxy 页面启用。默认端口为 `8045`(开发构建为 `8046`),可在该页面修改。从同一页面复制 API key,并确认号池中至少有一个账号。
1. 确保所有依赖均已安装:`npm install`
2. 检查 Node.js 版本是否 >= 20。
3. 尝试删除 `node_modules` 并重新安装。
4. 在 Windows 上,请确保已安装 WiX Toolset 以便执行 `npm run make` 命令。
</details>
<details>
<summary><b>问:账户登录失败?</b></summary>
<summary><b>需要 API key 吗?</b></summary>
`api_key` 为空时代理以开放模式运行。启用后它监听 `0.0.0.0`,所以请设置 key 并妥善保管。
1. 确保您的网络连接正常。
2. 尝试清除应用数据并重新登录。
3. 检查该账户是否已被 Google/Claude 限制。
</details>
<details>
<summary><b>问:IDE 无法连接到代理?</b></summary>
<summary><b>能使用 Claude 模型吗?</b></summary>
可以,通过号池中 Google 账号上的模型映射实现,而不是使用单独的 Claude 账号。
1. 确保代理正在运行(查看状态栏的绿色指示器)。
2. 确认端口与您 IDE 中的配置一致(默认为 `10100`)。
3. 直接从 Proxy 页面复制 API 密钥并粘贴到 IDE 设置中。
4. 确保在 Accounts 页面中至少有一个活跃的账户。
</details>
<details>
<summary><b>问:Token 计数显示为零?</b></summary>
<summary><b>我的 token 存在哪里?</b></summary>
存放在独立的 `cloud_accounts.db` 中,`token_json` 和 `quota_json` 使用 AES-256-GCM 加密。主密钥通过 `keytar` 存放在系统凭据存储中。详见[安全模型](#安全模型)。
1. 这是早期版本中的一个已知漏洞 — 请更新至最新版本。
2. 目前 Token 追踪功能已能正确处理流式元数据及预估计数。
3. 使用数据会在 Usage Analytics 页面每 15 秒自动刷新。
</details>
---
<details>
<summary><b>可以商用吗?</b></summary>
请先查看[许可证](#-许可证):继承自 AntigravityManager 的代码采用 CC BY-NC-SA 4.0(非商业),新代码采用 MIT。
</details>
## 局限与后续计划
- 上游访问经由 Google 的 `v1internal` Cloud Code 端点和 OAuth scope([`src/services/GoogleAPIService.ts`](src/services/GoogleAPIService.ts))。这些是内部、未公开文档的 API,可能随时变更。本项目为非官方项目,与 Google 或 Anthropic 无关联。
- 账号通过 Google OAuth 添加;Claude 模型通过模型映射访问,而不是通过单独的 Claude 账号。
- 端到端测试不在 CI 中运行(Electron 需要图形环境);请在本地运行 `pnpm run test:e2e`。
- 只有构建机器上有 WiX Toolset 时才会生成 Windows MSI,否则 Windows 产物为 ZIP。
- `.github/workflows/` 中的工作流是为 GitHub 编写的(调用 `gh` CLI 和 GitHub 发布器),因此本 README 不显示 CI 徽章。
- 项目声明的下一步:把剩余的原始代码迁移到 MIT(见[许可证](#-许可证))。
## 🤝 参与贡献
欢迎贡献代码!详情请参阅 `CONTRIBUTING.md`。
请阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 和 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。版本由 semantic-release 根据 Conventional Commits 生成。提交 PR 之前,以下命令必须通过:
---
```bash
pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test
```
## 📄 许可证
本项目采用双重许可结构:
- **原始代码**来自 [Draculabo](https://github.com/Draculabo) 的 [AntigravityManager](https://github.com/Draculabo/AntigravityManager):采用 [CC BY-NC-SA 4.0](LICENSE) 许可。
- **所有新代码、功能和架构**由 [evandrodevbr](https://github.com/evandrodevbr) 开发:采用 [MIT 许可证](LICENSE-MIT)。
> 🔄 **迁移通知:** 本项目正在积极迁移到完全开源许可证(MIT)。随着剩余原始代码的逐步重写,整个项目将过渡到 MIT。我们致力于将 Gemini Nexus 打造为 100% 开源项目。
混合许可:继承自 [AntigravityManager](https://github.com/Draculabo/AntigravityManager)(作者 Draculabo)的代码采用 [CC BY-NC-SA 4.0](LICENSE)(非商业、相同方式共享);所有新代码采用 [MIT](LICENSE-MIT)。随着剩余原始代码被重写,项目正在迁移到 MIT,因此任何商业使用前请同时查看两个文件。
---
## 🙏 致谢
<div align="center">
本项目最初是从 [Draculabo](https://github.com/Draculabo) 创建的 [AntigravityManager](https://github.com/Draculabo/AntigravityManager) 分支而来的。最初的代理概念和早期的 Electron 框架基于他的工作。
<img src="docs/assets/logo.png" width="56" alt="Gemini Nexus 标志">
自从分支以来,[evandrodevbr](https://github.com/evandrodevbr) **重写、重新设计并扩展了绝大部分代码库**,包括但不限于:
<p><strong><a href="https://git.evandro.dev.br/evandro/gemini-nexus">Gitea 上的 Gemini Nexus</a></strong> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">报告问题</a> · <a href="#-快速开始">快速开始</a></p>
- 完整的 UI/UX 重新设计(导航、账户、使用分析、代理管理)
- 使用分析仪表板,包含成本跟踪、Token 平均值以及 OpenRouter 集成
- 流量监视器,提供按请求查看的 Token/成本检查
- 环境隔离(dev/prod)、CI/CD 流水线和测试基础设施
- IDE 快速设置(OpenCode、Cursor、VS Code、Claude Code)
- 自定义模型定价配置
- 所有文档和国际化(EN, PT-BR, ES, ZH-CN)
</div>
+11
View File
@@ -0,0 +1,11 @@
Hero raster layer (hero-subject.png), generated with generate_image (openai-codex/gpt-image-2), docs/assets/logo.png as shape reference.
Background removed with a magenta (#ff00ff) chroma key, then cropped and resized to 760 px.
Composition: hero.svg places the layer at x=700 y=40 (340x340); node centres 741,86 / 1000,86 / 870,334.
Final PNGs: rsvg-convert -w 2400 hero[.lang].svg -o hero[.lang].png
Subject: A single isolated 3D hardware object: a machined matte-black metal hub ring, seen slightly from above at a three-quarter angle. Three straight thin metal arms extend outward from the ring (upper-left, upper-right, and straight down), each ending in a small hollow ring node, like a network junction. Inside the main ring sits a softly glowing emerald-green (#10b981) core disc made of frosted glass. Thin emerald light lines run along each arm into the end nodes. Precise industrial product design, clean bevels, subtle brushed-metal texture, no text, no letters, no logo, no watermark.
Scene: Perfectly flat solid magenta #ff00ff background with no gradient, no texture, no floor, no reflection and no shadow. One isolated subject with generous padding on all sides.
Composition: Centered, the whole object fully inside the frame with at least 12% empty margin on every side, square framing.
Lighting: Cool studio key light from the upper left, dark low-key product lighting, emerald glow confined to the core and arm light lines; no magenta tones anywhere on the object.
Style: Photorealistic product render, dark minimal tech hardware, sharp edges suitable for chroma-key cutout.
Change: Use the logo only as the shape reference for the ring-with-three-node-arms silhouette; do not reproduce the G/N letters inside the ring, replace them with the glowing emerald core disc.
Binary file not shown.

After

Width:  |  Height:  |  Size: 349 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 454 KiB

+66
View File
@@ -0,0 +1,66 @@
<svg xml:lang="es" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
width="1200" height="420" viewBox="0 0 1200 420"
role="img" aria-labelledby="title desc">
<title id="title">Gemini Nexus</title>
<desc id="desc">Hero layout source: the Gemini Nexus hub (IDE, account pool and Google APIs on its three nodes) next to the project name, value line and the local endpoint. Render to hero.png; the raster hub is hero-subject.png.</desc>
<defs>
<radialGradient id="core-glow" cx="0.5" cy="0.5" r="0.5">
<stop offset="0" stop-color="#10b981" stop-opacity="0.32"/>
<stop offset="0.55" stop-color="#10b981" stop-opacity="0.08"/>
<stop offset="1" stop-color="#10b981" stop-opacity="0"/>
</radialGradient>
</defs>
<rect width="1200" height="420" rx="24" fill="#0a0a0b"/>
<rect x="0.5" y="0.5" width="1199" height="419" rx="23.5" fill="none" stroke="#1f2023"/>
<g id="title-block" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', 'PingFang SC', 'Noto Sans CJK SC', sans-serif">
<text id="eyebrow" x="64" y="92" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="18" letter-spacing="3" fill="#10b981">GATEWAY DE IA LOCAL · ESCRITORIO</text>
<text id="name" x="60" y="174" font-size="80" font-weight="700" letter-spacing="-2" fill="#fafafa">Gemini Nexus</text>
<text id="value-1" x="64" y="226" font-size="27" fill="#b9bdc5">Agrupa tus cuentas de Google tras una</text>
<text id="value-2" x="64" y="262" font-size="27" fill="#b9bdc5">API compatible con OpenAI y Anthropic.</text>
<g id="endpoint" transform="translate(64 296)">
<rect width="344" height="48" rx="10" fill="#121315" stroke="#2a2c30"/>
<circle cx="24" cy="24" r="6" fill="#10b981"/>
<text x="42" y="31" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="20" fill="#e7e8ea">http://localhost:8045/v1</text>
</g>
<text id="meta" x="64" y="384" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="18" fill="#6c717a">Electron · NestJS proxy · AES-256-GCM</text>
</g>
<g id="hub">
<circle cx="870" cy="172" r="210" fill="url(#core-glow)"/>
<!-- Raster layer: replace hero-subject.png to change the hub art; node centres are 741,86 / 1000,86 / 870,334 -->
<image id="subject" x="700" y="40" width="340" height="340" xlink:href="hero-subject.png" href="hero-subject.png" preserveAspectRatio="xMidYMid meet"/>
</g>
<g id="node-labels" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="18">
<g id="label-ide">
<path d="M706 86 H676" stroke="#3a3d42" stroke-width="2"/>
<rect x="566" y="68" width="110" height="36" rx="18" fill="#121315" stroke="#2a2c30"/>
<text x="621" y="92" text-anchor="middle" fill="#d4d6da">tu IDE</text>
</g>
<g id="label-pool">
<rect x="976" y="134" width="184" height="36" rx="18" fill="#121315" stroke="#2a2c30"/>
<text x="1068" y="158" text-anchor="middle" fill="#d4d6da">pool de cuentas</text>
<g id="quota-bars" transform="translate(1004 186)">
<rect width="140" height="8" rx="4" fill="#1d1f22"/>
<rect width="140" height="8" rx="4" fill="#10b981"/>
<rect y="22" width="140" height="8" rx="4" fill="#1d1f22"/>
<rect y="22" width="88" height="8" rx="4" fill="#10b981"/>
<rect y="44" width="140" height="8" rx="4" fill="#1d1f22"/>
<rect y="44" width="8" height="8" rx="4" fill="#f43f5e"/>
</g>
<text x="1004" y="264" fill="#6c717a">auto-switch</text>
</g>
<g id="label-upstream">
<path d="M906 334 H932" stroke="#3a3d42" stroke-width="2"/>
<rect x="932" y="316" width="176" height="36" rx="18" fill="#121315" stroke="#2a2c30"/>
<text x="1020" y="340" text-anchor="middle" fill="#d4d6da">APIs de Google</text>
</g>
</g>
</svg>

After

Width:  |  Height:  |  Size: 3.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 452 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 457 KiB

+66
View File
@@ -0,0 +1,66 @@
<svg xml:lang="pt-BR" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
width="1200" height="420" viewBox="0 0 1200 420"
role="img" aria-labelledby="title desc">
<title id="title">Gemini Nexus</title>
<desc id="desc">Hero layout source: the Gemini Nexus hub (IDE, account pool and Google APIs on its three nodes) next to the project name, value line and the local endpoint. Render to hero.png; the raster hub is hero-subject.png.</desc>
<defs>
<radialGradient id="core-glow" cx="0.5" cy="0.5" r="0.5">
<stop offset="0" stop-color="#10b981" stop-opacity="0.32"/>
<stop offset="0.55" stop-color="#10b981" stop-opacity="0.08"/>
<stop offset="1" stop-color="#10b981" stop-opacity="0"/>
</radialGradient>
</defs>
<rect width="1200" height="420" rx="24" fill="#0a0a0b"/>
<rect x="0.5" y="0.5" width="1199" height="419" rx="23.5" fill="none" stroke="#1f2023"/>
<g id="title-block" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', 'PingFang SC', 'Noto Sans CJK SC', sans-serif">
<text id="eyebrow" x="64" y="92" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="18" letter-spacing="3" fill="#10b981">GATEWAY LOCAL DE IA · APP DESKTOP</text>
<text id="name" x="60" y="174" font-size="80" font-weight="700" letter-spacing="-2" fill="#fafafa">Gemini Nexus</text>
<text id="value-1" x="64" y="226" font-size="27" fill="#b9bdc5">Reúna suas contas Google atrás de uma</text>
<text id="value-2" x="64" y="262" font-size="27" fill="#b9bdc5">API compatível com OpenAI e Anthropic.</text>
<g id="endpoint" transform="translate(64 296)">
<rect width="344" height="48" rx="10" fill="#121315" stroke="#2a2c30"/>
<circle cx="24" cy="24" r="6" fill="#10b981"/>
<text x="42" y="31" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="20" fill="#e7e8ea">http://localhost:8045/v1</text>
</g>
<text id="meta" x="64" y="384" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="18" fill="#6c717a">Electron · NestJS proxy · AES-256-GCM</text>
</g>
<g id="hub">
<circle cx="870" cy="172" r="210" fill="url(#core-glow)"/>
<!-- Raster layer: replace hero-subject.png to change the hub art; node centres are 741,86 / 1000,86 / 870,334 -->
<image id="subject" x="700" y="40" width="340" height="340" xlink:href="hero-subject.png" href="hero-subject.png" preserveAspectRatio="xMidYMid meet"/>
</g>
<g id="node-labels" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="18">
<g id="label-ide">
<path d="M706 86 H676" stroke="#3a3d42" stroke-width="2"/>
<rect x="566" y="68" width="110" height="36" rx="18" fill="#121315" stroke="#2a2c30"/>
<text x="621" y="92" text-anchor="middle" fill="#d4d6da">sua IDE</text>
</g>
<g id="label-pool">
<rect x="976" y="134" width="184" height="36" rx="18" fill="#121315" stroke="#2a2c30"/>
<text x="1068" y="158" text-anchor="middle" fill="#d4d6da">pool de contas</text>
<g id="quota-bars" transform="translate(1004 186)">
<rect width="140" height="8" rx="4" fill="#1d1f22"/>
<rect width="140" height="8" rx="4" fill="#10b981"/>
<rect y="22" width="140" height="8" rx="4" fill="#1d1f22"/>
<rect y="22" width="88" height="8" rx="4" fill="#10b981"/>
<rect y="44" width="140" height="8" rx="4" fill="#1d1f22"/>
<rect y="44" width="8" height="8" rx="4" fill="#f43f5e"/>
</g>
<text x="1004" y="264" fill="#6c717a">auto-switch</text>
</g>
<g id="label-upstream">
<path d="M906 334 H932" stroke="#3a3d42" stroke-width="2"/>
<rect x="932" y="316" width="176" height="36" rx="18" fill="#121315" stroke="#2a2c30"/>
<text x="1020" y="340" text-anchor="middle" fill="#d4d6da">APIs do Google</text>
</g>
</g>
</svg>

After

Width:  |  Height:  |  Size: 3.9 KiB

+66
View File
@@ -0,0 +1,66 @@
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
width="1200" height="420" viewBox="0 0 1200 420"
role="img" aria-labelledby="title desc">
<title id="title">Gemini Nexus</title>
<desc id="desc">Hero layout source: the Gemini Nexus hub (IDE, account pool and Google APIs on its three nodes) next to the project name, value line and the local endpoint. Render to hero.png; the raster hub is hero-subject.png.</desc>
<defs>
<radialGradient id="core-glow" cx="0.5" cy="0.5" r="0.5">
<stop offset="0" stop-color="#10b981" stop-opacity="0.32"/>
<stop offset="0.55" stop-color="#10b981" stop-opacity="0.08"/>
<stop offset="1" stop-color="#10b981" stop-opacity="0"/>
</radialGradient>
</defs>
<rect width="1200" height="420" rx="24" fill="#0a0a0b"/>
<rect x="0.5" y="0.5" width="1199" height="419" rx="23.5" fill="none" stroke="#1f2023"/>
<g id="title-block" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', 'PingFang SC', 'Noto Sans CJK SC', sans-serif">
<text id="eyebrow" x="64" y="92" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="18" letter-spacing="3" fill="#10b981">LOCAL AI GATEWAY · DESKTOP APP</text>
<text id="name" x="60" y="174" font-size="80" font-weight="700" letter-spacing="-2" fill="#fafafa">Gemini Nexus</text>
<text id="value-1" x="64" y="226" font-size="27" fill="#b9bdc5">Pool your Google accounts behind one</text>
<text id="value-2" x="64" y="262" font-size="27" fill="#b9bdc5">OpenAI- and Anthropic-compatible API.</text>
<g id="endpoint" transform="translate(64 296)">
<rect width="344" height="48" rx="10" fill="#121315" stroke="#2a2c30"/>
<circle cx="24" cy="24" r="6" fill="#10b981"/>
<text x="42" y="31" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="20" fill="#e7e8ea">http://localhost:8045/v1</text>
</g>
<text id="meta" x="64" y="384" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="18" fill="#6c717a">Electron · NestJS proxy · AES-256-GCM</text>
</g>
<g id="hub">
<circle cx="870" cy="172" r="210" fill="url(#core-glow)"/>
<!-- Raster layer: replace hero-subject.png to change the hub art; node centres are 741,86 / 1000,86 / 870,334 -->
<image id="subject" x="700" y="40" width="340" height="340" xlink:href="hero-subject.png" href="hero-subject.png" preserveAspectRatio="xMidYMid meet"/>
</g>
<g id="node-labels" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="18">
<g id="label-ide">
<path d="M706 86 H676" stroke="#3a3d42" stroke-width="2"/>
<rect x="566" y="68" width="110" height="36" rx="18" fill="#121315" stroke="#2a2c30"/>
<text x="621" y="92" text-anchor="middle" fill="#d4d6da">your IDE</text>
</g>
<g id="label-pool">
<rect x="976" y="134" width="184" height="36" rx="18" fill="#121315" stroke="#2a2c30"/>
<text x="1068" y="158" text-anchor="middle" fill="#d4d6da">account pool</text>
<g id="quota-bars" transform="translate(1004 186)">
<rect width="140" height="8" rx="4" fill="#1d1f22"/>
<rect width="140" height="8" rx="4" fill="#10b981"/>
<rect y="22" width="140" height="8" rx="4" fill="#1d1f22"/>
<rect y="22" width="88" height="8" rx="4" fill="#10b981"/>
<rect y="44" width="140" height="8" rx="4" fill="#1d1f22"/>
<rect y="44" width="8" height="8" rx="4" fill="#f43f5e"/>
</g>
<text x="1004" y="264" fill="#6c717a">auto-switch</text>
</g>
<g id="label-upstream">
<path d="M906 334 H932" stroke="#3a3d42" stroke-width="2"/>
<rect x="932" y="316" width="176" height="36" rx="18" fill="#121315" stroke="#2a2c30"/>
<text x="1020" y="340" text-anchor="middle" fill="#d4d6da">Google APIs</text>
</g>
</g>
</svg>

After

Width:  |  Height:  |  Size: 3.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 449 KiB

+66
View File
@@ -0,0 +1,66 @@
<svg xml:lang="zh-CN" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
width="1200" height="420" viewBox="0 0 1200 420"
role="img" aria-labelledby="title desc">
<title id="title">Gemini Nexus</title>
<desc id="desc">Hero layout source: the Gemini Nexus hub (IDE, account pool and Google APIs on its three nodes) next to the project name, value line and the local endpoint. Render to hero.png; the raster hub is hero-subject.png.</desc>
<defs>
<radialGradient id="core-glow" cx="0.5" cy="0.5" r="0.5">
<stop offset="0" stop-color="#10b981" stop-opacity="0.32"/>
<stop offset="0.55" stop-color="#10b981" stop-opacity="0.08"/>
<stop offset="1" stop-color="#10b981" stop-opacity="0"/>
</radialGradient>
</defs>
<rect width="1200" height="420" rx="24" fill="#0a0a0b"/>
<rect x="0.5" y="0.5" width="1199" height="419" rx="23.5" fill="none" stroke="#1f2023"/>
<g id="title-block" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', 'PingFang SC', 'Noto Sans CJK SC', sans-serif">
<text id="eyebrow" x="64" y="92" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="18" letter-spacing="3" fill="#10b981">本地 AI 网关 · 桌面应用</text>
<text id="name" x="60" y="174" font-size="80" font-weight="700" letter-spacing="-2" fill="#fafafa">Gemini Nexus</text>
<text id="value-1" x="64" y="226" font-size="27" fill="#b9bdc5">多个 Google 账号汇成一个账号池,</text>
<text id="value-2" x="64" y="262" font-size="27" fill="#b9bdc5">对外提供兼容 OpenAI 与 Anthropic 的 API。</text>
<g id="endpoint" transform="translate(64 296)">
<rect width="344" height="48" rx="10" fill="#121315" stroke="#2a2c30"/>
<circle cx="24" cy="24" r="6" fill="#10b981"/>
<text x="42" y="31" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="20" fill="#e7e8ea">http://localhost:8045/v1</text>
</g>
<text id="meta" x="64" y="384" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="18" fill="#6c717a">Electron · NestJS proxy · AES-256-GCM</text>
</g>
<g id="hub">
<circle cx="870" cy="172" r="210" fill="url(#core-glow)"/>
<!-- Raster layer: replace hero-subject.png to change the hub art; node centres are 741,86 / 1000,86 / 870,334 -->
<image id="subject" x="700" y="40" width="340" height="340" xlink:href="hero-subject.png" href="hero-subject.png" preserveAspectRatio="xMidYMid meet"/>
</g>
<g id="node-labels" font-family="ui-monospace, SFMono-Regular, Menlo, 'Noto Sans Mono', monospace" font-size="18">
<g id="label-ide">
<path d="M706 86 H676" stroke="#3a3d42" stroke-width="2"/>
<rect x="566" y="68" width="110" height="36" rx="18" fill="#121315" stroke="#2a2c30"/>
<text x="621" y="92" text-anchor="middle" fill="#d4d6da">你的 IDE</text>
</g>
<g id="label-pool">
<rect x="976" y="134" width="184" height="36" rx="18" fill="#121315" stroke="#2a2c30"/>
<text x="1068" y="158" text-anchor="middle" fill="#d4d6da">账号池</text>
<g id="quota-bars" transform="translate(1004 186)">
<rect width="140" height="8" rx="4" fill="#1d1f22"/>
<rect width="140" height="8" rx="4" fill="#10b981"/>
<rect y="22" width="140" height="8" rx="4" fill="#1d1f22"/>
<rect y="22" width="88" height="8" rx="4" fill="#10b981"/>
<rect y="44" width="140" height="8" rx="4" fill="#1d1f22"/>
<rect y="44" width="8" height="8" rx="4" fill="#f43f5e"/>
</g>
<text x="1004" y="264" fill="#6c717a">自动切换</text>
</g>
<g id="label-upstream">
<path d="M906 334 H932" stroke="#3a3d42" stroke-width="2"/>
<rect x="932" y="316" width="176" height="36" rx="18" fill="#121315" stroke="#2a2c30"/>
<text x="1020" y="340" text-anchor="middle" fill="#d4d6da">Google API</text>
</g>
</g>
</svg>

After

Width:  |  Height:  |  Size: 3.9 KiB

-7
View File
@@ -50,11 +50,4 @@ export default defineConfig([
'prefer-const': 'off',
},
},
{
// Node maintenance scripts are CommonJS; require() is the native API there.
files: ['scripts/**/*.js'],
rules: {
'@typescript-eslint/no-require-imports': 'off',
},
},
]);
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "gemini-nexus",
"productName": "Gemini Nexus",
"version": "0.15.5",
"version": "0.15.3",
"description": "Gemini Nexus - Electron App",
"main": ".vite/build/main.js",
"private": true,
+1 -5
View File
@@ -417,11 +417,7 @@ export function CloudAccountList() {
const setSelectionState = (id: string, selected: boolean) =>
setSelectedIds((prev) => {
const next = new Set(prev);
if (selected) {
next.add(id);
} else {
next.delete(id);
}
selected ? next.add(id) : next.delete(id);
return next;
});
const toggleSelectAllAccounts = () =>
+1
View File
@@ -1,5 +1,6 @@
import React from 'react';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { calculateCost } from '@/constants/pricing';
export interface ModelCostEntry {
model: string;
+4 -11
View File
@@ -1,4 +1,4 @@
import React, { useState } from 'react';
import React, { useState, useEffect } from 'react';
import {
Dialog,
DialogContent,
@@ -10,6 +10,7 @@ import {
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Badge } from '@/components/ui/badge';
import { Label } from '@/components/ui/label';
import { Loader2, RefreshCw, RotateCcw } from 'lucide-react';
import { MODEL_PRICING } from '@/constants/pricing';
@@ -34,16 +35,8 @@ export const ModelPricingDialog: React.FC<ModelPricingDialogProps> = ({
Record<string, { input: number; output: number; source: string }>
>({});
const [isFetching, setIsFetching] = useState(false);
const [pricingSource, setPricingSource] = useState<{
open: boolean;
customPricing: typeof customPricing;
}>({ open, customPricing });
// Re-seed the editable copy when the dialog opens or the source pricing changes.
// Adjusting state during render replaces the previous synchronous setState inside
// an effect (https://react.dev/learn/you-might-not-need-an-effect).
if (pricingSource.open !== open || pricingSource.customPricing !== customPricing) {
setPricingSource({ open, customPricing });
useEffect(() => {
if (open) {
// Initialize local state with custom pricing or empty if default
const initial: Record<string, { input: number; output: number; source: string }> = {};
@@ -56,7 +49,7 @@ export const ModelPricingDialog: React.FC<ModelPricingDialogProps> = ({
});
setLocalPricing(initial);
}
}
}, [open, customPricing]);
const handlePriceChange = (model: string, type: 'input' | 'output', value: string) => {
const numValue = parseFloat(value);
+3 -2
View File
@@ -58,8 +58,9 @@ export const MonitorTab: React.FC = () => {
tokensPrompt: log.metadata?.tokensPrompt as number | undefined,
tokensCompletion: log.metadata?.tokensCompletion as number | undefined,
tokensTotal:
((log.metadata?.tokensPrompt as number) || 0) +
((log.metadata?.tokensCompletion as number) || 0) || undefined,
(((log.metadata?.tokensPrompt as number) || 0) +
((log.metadata?.tokensCompletion as number) || 0)) ||
undefined,
}))
: [];
const stats = statsData?.success ? statsData.data : undefined;
+28 -46
View File
@@ -26,16 +26,7 @@ interface TrafficLogTableProps {
isLoading: boolean;
}
type SortKey =
| 'timestamp'
| 'direction'
| 'endpoint'
| 'model'
| 'method'
| 'status'
| 'tokens'
| 'cost'
| 'duration';
type SortKey = 'timestamp' | 'direction' | 'endpoint' | 'model' | 'method' | 'status' | 'tokens' | 'cost' | 'duration';
type SortDir = 'asc' | 'desc';
function SortIcon({
@@ -88,10 +79,13 @@ function getBodyPreview(body: unknown): string | null {
// Request body: extract first user message
if (Array.isArray(obj.messages)) {
const userMsg = obj.messages.find((m: Record<string, unknown>) => m.role === 'user');
const userMsg = obj.messages.find(
(m: Record<string, unknown>) => m.role === 'user',
);
if (userMsg) {
const content =
typeof userMsg.content === 'string' ? userMsg.content : JSON.stringify(userMsg.content);
const content = typeof userMsg.content === 'string'
? userMsg.content
: JSON.stringify(userMsg.content);
return content.length > 120 ? content.slice(0, 120) + '…' : content;
}
}
@@ -101,7 +95,9 @@ function getBodyPreview(body: unknown): string | null {
const firstChoice = obj.choices[0] as Record<string, unknown> | undefined;
const message = firstChoice?.message as Record<string, unknown> | undefined;
if (message?.content && typeof message.content === 'string') {
return message.content.length > 120 ? message.content.slice(0, 120) + '…' : message.content;
return message.content.length > 120
? message.content.slice(0, 120) + '…'
: message.content;
}
}
@@ -258,16 +254,18 @@ export const TrafficLogTable: React.FC<TrafficLogTableProps> = ({ logs, isLoadin
<React.Fragment key={logKey}>
<tr
className={`cursor-pointer border-b border-white/[0.04] transition-colors last:border-0 ${
isExpanded ? 'bg-white/[0.03]' : 'hover:bg-white/[0.02]'
isExpanded
? 'bg-white/[0.03]'
: 'hover:bg-white/[0.02]'
}`}
onClick={() => toggleExpand(logKey)}
>
{/* Expand chevron */}
<td className="py-2 pr-1">
{isExpanded ? (
<ChevronDown className="text-muted-foreground h-3.5 w-3.5" />
<ChevronDown className="h-3.5 w-3.5 text-muted-foreground" />
) : (
<ChevronRight className="text-muted-foreground/50 h-3.5 w-3.5" />
<ChevronRight className="h-3.5 w-3.5 text-muted-foreground/50" />
)}
</td>
<td className="text-muted-foreground py-2 pr-4 font-mono text-xs">
@@ -302,9 +300,11 @@ export const TrafficLogTable: React.FC<TrafficLogTableProps> = ({ logs, isLoadin
)}
</td>
<td className="py-2 pr-4 text-xs">
{log.tokensTotal
? `${formatTokens(log.tokensPrompt)} / ${formatTokens(log.tokensCompletion)}`
: '—'}
{log.tokensTotal ? (
`${formatTokens(log.tokensPrompt)} / ${formatTokens(log.tokensCompletion)}`
) : (
'—'
)}
</td>
<td className="py-2 pr-4 text-xs">
{log.durationMs != null ? `${log.durationMs}ms` : '—'}
@@ -323,7 +323,7 @@ export const TrafficLogTable: React.FC<TrafficLogTableProps> = ({ logs, isLoadin
<div className="border-t border-white/[0.06] bg-white/[0.01] px-6 py-4">
{/* Preview line */}
{preview && (
<div className="text-muted-foreground mb-3 rounded-lg bg-white/[0.03] px-3 py-2 text-xs break-words italic">
<div className="mb-3 rounded-lg bg-white/[0.03] px-3 py-2 text-xs text-muted-foreground italic break-words">
"{preview}"
</div>
)}
@@ -339,32 +339,18 @@ export const TrafficLogTable: React.FC<TrafficLogTableProps> = ({ logs, isLoadin
</Badge>
)}
{log.tokensPrompt != null && (
<Badge
variant="outline"
className="border-blue-500/20 text-[10px] text-blue-400"
>
<Badge variant="outline" className="border-blue-500/20 text-blue-400 text-[10px]">
Input: {log.tokensPrompt.toLocaleString()} tokens
</Badge>
)}
{log.tokensCompletion != null && (
<Badge
variant="outline"
className="border-emerald-500/20 text-[10px] text-emerald-400"
>
<Badge variant="outline" className="border-emerald-500/20 text-emerald-400 text-[10px]">
Output: {log.tokensCompletion.toLocaleString()} tokens
</Badge>
)}
{log.tokensTotal != null && log.model && (
<Badge
variant="outline"
className="border-amber-500/20 text-[10px] text-amber-400"
>
Cost: $
{calculateCost(
log.model,
log.tokensPrompt || 0,
log.tokensCompletion || 0,
).toFixed(6)}
<Badge variant="outline" className="border-amber-500/20 text-amber-400 text-[10px]">
Cost: ${calculateCost(log.model, log.tokensPrompt || 0, log.tokensCompletion || 0).toFixed(6)}
</Badge>
)}
{log.durationMs != null && (
@@ -377,15 +363,11 @@ export const TrafficLogTable: React.FC<TrafficLogTableProps> = ({ logs, isLoadin
{/* Body content */}
<div className="space-y-2">
<div className="flex items-center gap-2">
<span className="text-muted-foreground text-[10px] font-medium tracking-wider uppercase">
{log.direction === 'inbound'
? 'Request Body'
: log.direction === 'outbound'
? 'Response Body'
: 'Payload'}
<span className="text-muted-foreground text-[10px] font-medium uppercase tracking-wider">
{log.direction === 'inbound' ? 'Request Body' : log.direction === 'outbound' ? 'Response Body' : 'Payload'}
</span>
</div>
<pre className="custom-scrollbar text-foreground/80 max-h-[400px] overflow-auto rounded-lg bg-black/30 p-3 font-mono text-[11px] leading-relaxed break-all whitespace-pre-wrap">
<pre className="custom-scrollbar max-h-[400px] overflow-auto rounded-lg bg-black/30 p-3 font-mono text-[11px] leading-relaxed text-foreground/80 whitespace-pre-wrap break-all">
{formatBody(log.body)}
</pre>
</div>
+14 -14
View File
@@ -1,6 +1,9 @@
import { logger } from '../../utils/logger';
import { getServiceOrThrow, getServiceOptional } from './service-registry';
import type { IdeConfigResult } from '../../server/modules/proxy/proxy-ide-config.service';
import type {
IdeConfigResult,
SupportedIde,
} from '../../server/modules/proxy/proxy-ide-config.service';
import { TrafficLogsRepo } from '../database/proxyMetricsHandler';
import { CloudAccountRepo } from '../database/cloudHandler';
import { ConfigManager } from '../config/manager';
@@ -254,7 +257,9 @@ export async function getRecentRequests(): Promise<{
}
}
export async function replayRequest(requestId: string): Promise<{
export async function replayRequest(
requestId: string,
): Promise<{
success: boolean;
data?: { original: unknown; newResponse: unknown };
error?: string;
@@ -453,21 +458,16 @@ export async function generateIdeConfig(
const apiKey = config?.api_key || 'YOUR_API_KEY';
let localIp = '127.0.0.1';
try {
const interfaces = networkInterfaces();
for (const iface of Object.values(interfaces)) {
if (iface) {
for (const entry of iface) {
if (entry.family === 'IPv4' && !entry.internal) {
localIp = entry.address;
break;
}
const interfaces = networkInterfaces();
for (const iface of Object.values(interfaces)) {
if (iface) {
for (const entry of iface) {
if (entry.family === 'IPv4' && !entry.internal) {
localIp = entry.address;
break;
}
}
}
} catch (error) {
// Local proxy configuration remains usable when LAN enumeration is restricted.
logger.warn('Could not enumerate network interfaces; using loopback', error);
}
// Fallback generator mimicking the proxyIdeConfig.service
+283 -285
View File
@@ -406,7 +406,7 @@ function UsagePage() {
</div>
</div>
<Tabs defaultValue="analytics" className="flex flex-1 flex-col">
<Tabs defaultValue="analytics" className="flex-1 flex flex-col">
<div className="px-6 pt-5">
<TabsList className="grid w-full max-w-md grid-cols-2">
<TabsTrigger value="analytics">Analytics</TabsTrigger>
@@ -415,301 +415,299 @@ function UsagePage() {
</div>
<TabsContent value="analytics" className="flex-1 space-y-4 px-6 py-5">
{hasQuotaWarning && (
<Alert
variant="destructive"
className="border-amber-500/50 bg-amber-500/10 text-amber-500"
>
<AlertTriangle className="h-4 w-4" />
<AlertTitle>Quota Warning</AlertTitle>
<AlertDescription>
One or more models have exceeded 80% of their allocated usage limit.
</AlertDescription>
</Alert>
)}
<Alert
variant="destructive"
className="border-amber-500/50 bg-amber-500/10 text-amber-500"
>
<AlertTriangle className="h-4 w-4" />
<AlertTitle>Quota Warning</AlertTitle>
<AlertDescription>
One or more models have exceeded 80% of their allocated usage limit.
</AlertDescription>
</Alert>
)}
{/* ─── Stat cards ─── */}
<TooltipProvider delayDuration={300}>
<div className="grid grid-cols-1 gap-3 sm:grid-cols-2 xl:grid-cols-5">
{/* ─── Stat cards ─── */}
<TooltipProvider delayDuration={300}>
<div className="grid grid-cols-1 gap-3 sm:grid-cols-2 xl:grid-cols-5">
<StatCard
label="Total Tokens"
value={formatNumber(totals.totalTokens)}
icon={Zap}
isLoading={dailyLoading}
accent="amber"
trend={
prevDailyData ? calcTrend(totals.totalTokens, prevTotals.totalTokens) : undefined
}
sparkline={sparklineTotal}
/>
<div className="group relative">
<StatCard
label="Total Tokens"
value={formatNumber(totals.totalTokens)}
icon={Zap}
isLoading={dailyLoading}
accent="amber"
trend={
prevDailyData ? calcTrend(totals.totalTokens, prevTotals.totalTokens) : undefined
}
sparkline={sparklineTotal}
/>
<div className="group relative">
<StatCard
label={
<div className="flex cursor-help items-center gap-1.5">
Input Tokens
<Tooltip>
<TooltipTrigger asChild>
<Info className="text-muted-foreground/70 h-3.5 w-3.5" />
</TooltipTrigger>
<TooltipContent>
<p>Tokens sent to the model (prompt, context, files).</p>
</TooltipContent>
</Tooltip>
</div>
}
value={formatNumber(totals.promptTokens)}
icon={MessageSquare}
isLoading={dailyLoading}
accent="blue"
trend={
prevDailyData
? calcTrend(totals.promptTokens, prevTotals.promptTokens)
: undefined
}
sparkline={sparklinePrompt}
/>
</div>
<div className="group relative">
<StatCard
label={
<div className="flex cursor-help items-center gap-1.5">
Output Tokens
<Tooltip>
<TooltipTrigger asChild>
<Info className="text-muted-foreground/70 h-3.5 w-3.5" />
</TooltipTrigger>
<TooltipContent>
<p>Tokens generated by the model in response.</p>
</TooltipContent>
</Tooltip>
</div>
}
value={formatNumber(totals.completionTokens)}
icon={Activity}
isLoading={dailyLoading}
accent="green"
trend={
prevDailyData
? calcTrend(totals.completionTokens, prevTotals.completionTokens)
: undefined
}
sparkline={sparklineCompletion}
/>
</div>
<StatCard
label="Total Requests"
value={totals.requests.toLocaleString()}
icon={Layers}
isLoading={dailyLoading}
accent="slate"
trend={prevDailyData ? calcTrend(totals.requests, prevTotals.requests) : undefined}
sparkline={sparklineRequests}
/>
<div className="group relative">
<StatCard
label={
<div className="flex w-full items-center justify-between">
<div className="flex cursor-help items-center gap-1.5">
Estimated Cost
<Tooltip>
<TooltipTrigger asChild>
<Info className="text-muted-foreground/70 h-3.5 w-3.5" />
</TooltipTrigger>
<TooltipContent>
<p>Approximate cost based on configured pricing.</p>
</TooltipContent>
</Tooltip>
</div>
<Button
variant="ghost"
size="icon"
className="ml-2 h-5 w-5 hover:bg-white/10"
onClick={() => setIsPricingDialogOpen(true)}
>
<Settings className="text-muted-foreground h-3 w-3" />
</Button>
</div>
}
value={`$${totalCost.toFixed(2)}`}
icon={DollarSign}
isLoading={modelLoading}
accent="purple"
/>
</div>
</div>
</TooltipProvider>
{/* ─── Prompt/Completion ratio bar + top models ─── */}
{!dailyLoading && totals.totalTokens > 0 && (
<div className="grid grid-cols-1 gap-3 lg:grid-cols-3">
<div className="bg-card col-span-1 flex flex-col gap-3 rounded-xl border border-white/[0.06] p-4 lg:col-span-2">
<div className="flex items-center justify-between">
<span className="text-muted-foreground text-[11px] font-medium tracking-wider uppercase">
Input / Output
</span>
<span className="text-muted-foreground font-mono text-xs">
{formatNumber(totals.totalTokens)} total
</span>
</div>
<div className="flex h-2.5 w-full overflow-hidden rounded-full bg-white/[0.04]">
<div
className="h-full rounded-l-full transition-all duration-500"
style={{
width: `${promptRatio}%`,
backgroundColor: COLOR_PROMPT,
}}
/>
<div
className="h-full rounded-r-full transition-all duration-500"
style={{
width: `${completionRatio}%`,
backgroundColor: COLOR_COMPLETION,
}}
/>
</div>
<div className="flex items-center justify-between text-xs">
<div className="flex items-center gap-4">
<div className="flex items-center gap-1.5">
<span
className="h-2 w-2 rounded-full"
style={{ backgroundColor: COLOR_PROMPT }}
/>
<span className="text-muted-foreground">Input</span>
<span className="text-foreground font-mono font-semibold">
{promptRatio}%
</span>
</div>
<div className="flex items-center gap-1.5">
<span
className="h-2 w-2 rounded-full"
style={{ backgroundColor: COLOR_COMPLETION }}
/>
<span className="text-muted-foreground">Output</span>
<span className="text-foreground font-mono font-semibold">
{completionRatio}%
</span>
</div>
label={
<div className="flex cursor-help items-center gap-1.5">
Input Tokens
<Tooltip>
<TooltipTrigger asChild>
<Info className="text-muted-foreground/70 h-3.5 w-3.5" />
</TooltipTrigger>
<TooltipContent>
<p>Tokens sent to the model (prompt, context, files).</p>
</TooltipContent>
</Tooltip>
</div>
<span className="text-muted-foreground">
Avg/req:{' '}
<span className="text-foreground font-mono font-medium">
{formatNumber(avgReqSize)}
</span>
</span>
</div>
</div>
<ForecastCard hourlyData={hourlyData} dailyData={dailyData} range={range} />
}
value={formatNumber(totals.promptTokens)}
icon={MessageSquare}
isLoading={dailyLoading}
accent="blue"
trend={
prevDailyData
? calcTrend(totals.promptTokens, prevTotals.promptTokens)
: undefined
}
sparkline={sparklinePrompt}
/>
</div>
)}
{/* ─── Charts — Area + Model ranking ─── */}
<div className="grid grid-cols-1 gap-3 xl:grid-cols-5">
<div className="xl:col-span-3">
<ChartCard
title={range === '24h' ? 'Hourly Usage' : 'Daily Usage'}
isLoading={areaLoading}
error={areaError}
isEmpty={isAreaEmpty}
onRetry={() => (range === '24h' ? refetchHourly() : refetchDaily())}
emptyTitle="No usage data"
emptyDescription="Data will appear here once proxy requests are recorded."
errorMessage="Failed to load usage data"
retryLabel="Retry"
>
<div className="h-[320px]">
<ResponsiveLine
data={areaChartData}
theme={nivoTheme}
colors={[COLOR_PROMPT, COLOR_COMPLETION]}
margin={{ top: 10, right: 10, bottom: 40, left: 50 }}
xScale={{ type: 'point' }}
yScale={{ type: 'linear', min: 0, stacked: false }}
curve="monotoneX"
enableArea={true}
areaOpacity={0.08}
areaBlendMode="normal"
enablePoints={true}
pointSize={4}
pointColor={{ theme: 'background' }}
pointBorderWidth={2}
pointBorderColor={{ from: 'serieColor' }}
enableGridX={false}
enableGridY={true}
gridYValues={5}
axisBottom={{
tickSize: 0,
tickPadding: 8,
tickRotation: 0,
}}
axisLeft={{
tickSize: 0,
tickPadding: 8,
tickRotation: 0,
format: (v: number) => (v >= 1000 ? `${(v / 1000).toFixed(1)}k` : `${v}`),
}}
tooltip={LineTooltip}
legends={[
{
anchor: 'bottom',
direction: 'row',
justify: false,
translateX: 0,
translateY: 36,
itemsSpacing: 16,
itemWidth: 80,
itemHeight: 16,
itemDirection: 'left-to-right',
symbolSize: 8,
symbolShape: 'circle',
},
]}
animate={true}
motionConfig="gentle"
/>
</div>
</ChartCard>
<div className="group relative">
<StatCard
label={
<div className="flex cursor-help items-center gap-1.5">
Output Tokens
<Tooltip>
<TooltipTrigger asChild>
<Info className="text-muted-foreground/70 h-3.5 w-3.5" />
</TooltipTrigger>
<TooltipContent>
<p>Tokens generated by the model in response.</p>
</TooltipContent>
</Tooltip>
</div>
}
value={formatNumber(totals.completionTokens)}
icon={Activity}
isLoading={dailyLoading}
accent="green"
trend={
prevDailyData
? calcTrend(totals.completionTokens, prevTotals.completionTokens)
: undefined
}
sparkline={sparklineCompletion}
/>
</div>
<div className="xl:col-span-2">
<ChartCard
title="Model Distribution"
<StatCard
label="Total Requests"
value={totals.requests.toLocaleString()}
icon={Layers}
isLoading={dailyLoading}
accent="slate"
trend={prevDailyData ? calcTrend(totals.requests, prevTotals.requests) : undefined}
sparkline={sparklineRequests}
/>
<div className="group relative">
<StatCard
label={
<div className="flex w-full items-center justify-between">
<div className="flex cursor-help items-center gap-1.5">
Estimated Cost
<Tooltip>
<TooltipTrigger asChild>
<Info className="text-muted-foreground/70 h-3.5 w-3.5" />
</TooltipTrigger>
<TooltipContent>
<p>Approximate cost based on configured pricing.</p>
</TooltipContent>
</Tooltip>
</div>
<Button
variant="ghost"
size="icon"
className="ml-2 h-5 w-5 hover:bg-white/10"
onClick={() => setIsPricingDialogOpen(true)}
>
<Settings className="text-muted-foreground h-3 w-3" />
</Button>
</div>
}
value={`$${totalCost.toFixed(2)}`}
icon={DollarSign}
isLoading={modelLoading}
error={modelError}
isEmpty={isModelEmpty}
onRetry={() => refetchModel()}
emptyTitle="No model data"
emptyDescription="Model distribution will appear after proxy usage."
errorMessage="Failed to load model data"
retryLabel="Retry"
>
<div className="custom-scrollbar h-[320px] overflow-y-auto pr-2">
{topModelsData.map((m) => (
<ModelQuotaBar
key={m.model}
modelName={m.model}
usedTokens={m.tokens}
limitTokens={m.limit}
/>
))}
</div>
</ChartCard>
accent="purple"
/>
</div>
</div>
</TooltipProvider>
{/* ─── Cost Report ─── */}
{!dailyLoading && modelData && modelData.length > 0 && (
<div className="mt-6">
<CostReportCard
models={costReport}
totalInputCost={costReport.reduce((acc, r) => acc + r.inputCost, 0)}
totalOutputCost={costReport.reduce((acc, r) => acc + r.outputCost, 0)}
totalCost={totalCost}
isLoading={modelLoading}
/>
{/* ─── Prompt/Completion ratio bar + top models ─── */}
{!dailyLoading && totals.totalTokens > 0 && (
<div className="grid grid-cols-1 gap-3 lg:grid-cols-3">
<div className="bg-card col-span-1 flex flex-col gap-3 rounded-xl border border-white/[0.06] p-4 lg:col-span-2">
<div className="flex items-center justify-between">
<span className="text-muted-foreground text-[11px] font-medium tracking-wider uppercase">
Input / Output
</span>
<span className="text-muted-foreground font-mono text-xs">
{formatNumber(totals.totalTokens)} total
</span>
</div>
<div className="flex h-2.5 w-full overflow-hidden rounded-full bg-white/[0.04]">
<div
className="h-full rounded-l-full transition-all duration-500"
style={{
width: `${promptRatio}%`,
backgroundColor: COLOR_PROMPT,
}}
/>
<div
className="h-full rounded-r-full transition-all duration-500"
style={{
width: `${completionRatio}%`,
backgroundColor: COLOR_COMPLETION,
}}
/>
</div>
<div className="flex items-center justify-between text-xs">
<div className="flex items-center gap-4">
<div className="flex items-center gap-1.5">
<span
className="h-2 w-2 rounded-full"
style={{ backgroundColor: COLOR_PROMPT }}
/>
<span className="text-muted-foreground">Input</span>
<span className="text-foreground font-mono font-semibold">{promptRatio}%</span>
</div>
<div className="flex items-center gap-1.5">
<span
className="h-2 w-2 rounded-full"
style={{ backgroundColor: COLOR_COMPLETION }}
/>
<span className="text-muted-foreground">Output</span>
<span className="text-foreground font-mono font-semibold">
{completionRatio}%
</span>
</div>
</div>
<span className="text-muted-foreground">
Avg/req:{' '}
<span className="text-foreground font-mono font-medium">
{formatNumber(avgReqSize)}
</span>
</span>
</div>
</div>
)}
{/* ─── Modals ─── */}
<ForecastCard hourlyData={hourlyData} dailyData={dailyData} range={range} />
</div>
)}
{/* ─── Charts — Area + Model ranking ─── */}
<div className="grid grid-cols-1 gap-3 xl:grid-cols-5">
<div className="xl:col-span-3">
<ChartCard
title={range === '24h' ? 'Hourly Usage' : 'Daily Usage'}
isLoading={areaLoading}
error={areaError}
isEmpty={isAreaEmpty}
onRetry={() => (range === '24h' ? refetchHourly() : refetchDaily())}
emptyTitle="No usage data"
emptyDescription="Data will appear here once proxy requests are recorded."
errorMessage="Failed to load usage data"
retryLabel="Retry"
>
<div className="h-[320px]">
<ResponsiveLine
data={areaChartData}
theme={nivoTheme}
colors={[COLOR_PROMPT, COLOR_COMPLETION]}
margin={{ top: 10, right: 10, bottom: 40, left: 50 }}
xScale={{ type: 'point' }}
yScale={{ type: 'linear', min: 0, stacked: false }}
curve="monotoneX"
enableArea={true}
areaOpacity={0.08}
areaBlendMode="normal"
enablePoints={true}
pointSize={4}
pointColor={{ theme: 'background' }}
pointBorderWidth={2}
pointBorderColor={{ from: 'serieColor' }}
enableGridX={false}
enableGridY={true}
gridYValues={5}
axisBottom={{
tickSize: 0,
tickPadding: 8,
tickRotation: 0,
}}
axisLeft={{
tickSize: 0,
tickPadding: 8,
tickRotation: 0,
format: (v: number) => (v >= 1000 ? `${(v / 1000).toFixed(1)}k` : `${v}`),
}}
tooltip={LineTooltip}
legends={[
{
anchor: 'bottom',
direction: 'row',
justify: false,
translateX: 0,
translateY: 36,
itemsSpacing: 16,
itemWidth: 80,
itemHeight: 16,
itemDirection: 'left-to-right',
symbolSize: 8,
symbolShape: 'circle',
},
]}
animate={true}
motionConfig="gentle"
/>
</div>
</ChartCard>
</div>
<div className="xl:col-span-2">
<ChartCard
title="Model Distribution"
isLoading={modelLoading}
error={modelError}
isEmpty={isModelEmpty}
onRetry={() => refetchModel()}
emptyTitle="No model data"
emptyDescription="Model distribution will appear after proxy usage."
errorMessage="Failed to load model data"
retryLabel="Retry"
>
<div className="custom-scrollbar h-[320px] overflow-y-auto pr-2">
{topModelsData.map((m) => (
<ModelQuotaBar
key={m.model}
modelName={m.model}
usedTokens={m.tokens}
limitTokens={m.limit}
/>
))}
</div>
</ChartCard>
</div>
</div>
{/* ─── Cost Report ─── */}
{!dailyLoading && modelData && modelData.length > 0 && (
<div className="mt-6">
<CostReportCard
models={costReport}
totalInputCost={costReport.reduce((acc, r) => acc + r.inputCost, 0)}
totalOutputCost={costReport.reduce((acc, r) => acc + r.outputCost, 0)}
totalCost={totalCost}
isLoading={modelLoading}
/>
</div>
)}
{/* ─── Modals ─── */}
<ModelPricingDialog
open={isPricingDialogOpen}
onOpenChange={setIsPricingDialogOpen}
+11 -9
View File
@@ -44,9 +44,7 @@ function toLowerText(value: string | undefined): string {
}
function parseDurationToSeconds(text: string): number | null {
const match = text
.trim()
.match(/^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+(?:\.\d+)?)s)?(?:(\d+(?:\.\d+)?)ms)?$/i);
const match = text.match(/(?:(\d+)h)?(?:(\d+)m)?(?:(\d+(?:\.\d+)?)s)?(?:(\d+(?:\.\d+)?)ms)?/i);
if (!match) {
return null;
}
@@ -56,8 +54,9 @@ function parseDurationToSeconds(text: string): number | null {
const seconds = Number(match[3] ?? 0);
const milliseconds = Number(match[4] ?? 0);
const totalSeconds = Math.ceil(hours * 3600 + minutes * 60 + seconds + milliseconds / 1000);
if (!Number.isFinite(totalSeconds) || totalSeconds <= 0) {
const totalSeconds =
hours * 3600 + minutes * 60 + Math.ceil(seconds) + Math.ceil(milliseconds / 1000);
if (totalSeconds <= 0) {
return null;
}
return totalSeconds;
@@ -109,16 +108,19 @@ export class RateLimitTracker {
const now = Date.now();
const globalLock = this.lockoutByKey.get(accountId);
let resetTimeMs = globalLock?.resetTimeMs ?? now;
if (globalLock && globalLock.resetTimeMs > now) {
return Math.max(0, Math.ceil((globalLock.resetTimeMs - now) / 1000));
}
if (model) {
const modelKey = this.buildLockoutKey(accountId, model);
const modelLock = this.lockoutByKey.get(modelKey);
resetTimeMs = Math.max(resetTimeMs, modelLock?.resetTimeMs ?? now);
if (modelLock && modelLock.resetTimeMs > now) {
return Math.max(0, Math.ceil((modelLock.resetTimeMs - now) / 1000));
}
}
// Both scopes apply; retrying before either lock expires still fails upstream.
return Math.max(0, Math.ceil((resetTimeMs - now) / 1000));
return 0;
}
getRemainingWaitSec(accountId: string, model?: string): number {
+2 -2
View File
@@ -16,8 +16,8 @@ import { getSwitchGuardSnapshot } from '../../ipc/switchGuard';
vi.mock('../../utils/paths', async () => {
const path = await import('path');
const agentDir = path.join(process.cwd(), 'temp_test_agent');
return {
IS_DEV_ENVIRONMENT: false,
return {
IS_DEV_ENVIRONMENT: false,
getAgentDir: vi.fn(() => agentDir),
getAccountsFilePath: vi.fn(() => path.join(agentDir, 'accounts.json')),
getBackupsDir: vi.fn(() => path.join(agentDir, 'backups')),
+1 -1
View File
@@ -57,7 +57,7 @@ vi.mock('../../ipc/database/dbConnection', () => ({
}),
}));
vi.mock('../../utils/paths', () => ({
vi.mock('../../utils/paths', () => ({
IS_DEV_ENVIRONMENT: false,
getGeminiNexusDbPaths: () => ['mock-db'],
getCloudAccountsDbPath: () => 'mock-cloud-db',
+1 -1
View File
@@ -21,7 +21,7 @@ vi.mock('../../ipc/database/dbConnection', () => ({
}),
}));
vi.mock('../../utils/paths', () => ({
vi.mock('../../utils/paths', () => ({
IS_DEV_ENVIRONMENT: false,
getGeminiNexusDbPaths: () => ['mock-db'],
}));
+1 -1
View File
@@ -47,7 +47,7 @@ vi.mock('../../utils/logger', () => ({
},
}));
vi.mock('../../utils/paths', () => ({
vi.mock('../../utils/paths', () => ({
IS_DEV_ENVIRONMENT: false,
getGeminiNexusDbPaths: vi.fn().mockReturnValue(['/tmp/test.vscdb']),
}));
+1 -1
View File
@@ -64,7 +64,7 @@ vi.mock('../../../ipc/database/dbConnection', () => ({
configureDatabase: vi.fn(),
}));
vi.mock('../../../utils/paths', () => ({
vi.mock('../../../utils/paths', () => ({
IS_DEV_ENVIRONMENT: false,
getCloudAccountsDbPath: vi.fn(() => '/mock/db/path.sqlite'),
}));
+1 -1
View File
@@ -48,7 +48,7 @@ vi.mock('../../../utils/logger', () => ({
},
}));
vi.mock('../../../utils/paths', () => ({
vi.mock('../../../utils/paths', () => ({
IS_DEV_ENVIRONMENT: false,
getGeminiNexusDbPaths: vi.fn().mockReturnValue(['/tmp/test.vscdb']),
}));
+1 -1
View File
@@ -52,7 +52,7 @@ vi.mock('../../../utils/logger', () => ({
},
}));
vi.mock('../../../utils/paths', () => ({
vi.mock('../../../utils/paths', () => ({
IS_DEV_ENVIRONMENT: false,
getGeminiNexusStoragePaths: vi.fn().mockReturnValue(['/tmp/storage.json']),
getGeminiNexusDbPaths: vi.fn().mockReturnValue(['/tmp/state.vscdb']),
@@ -1,5 +1,4 @@
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { networkInterfaces } from 'os';
import {
getRecentTrafficLogs,
getTrafficLogStats,
@@ -15,16 +14,6 @@ import {
import { TrafficLogsRepo } from '../../../ipc/database/proxyMetricsHandler';
import { proxyAdvancedRegistry } from '../../../ipc/proxy-advanced/service-registry';
vi.mock('os', async (importOriginal) => {
const actual = await importOriginal<typeof import('os')>();
const mockedNetworkInterfaces = vi.fn().mockReturnValue({});
return {
...actual,
default: { ...actual, networkInterfaces: mockedNetworkInterfaces },
networkInterfaces: mockedNetworkInterfaces,
};
});
vi.mock('../../../utils/logger', () => ({
logger: {
info: vi.fn(),
@@ -78,7 +67,6 @@ vi.mock('../../../ipc/proxy-advanced/service-registry', () => {
describe('Proxy Advanced Handler', () => {
beforeEach(() => {
vi.clearAllMocks();
vi.mocked(networkInterfaces).mockReset().mockReturnValue({});
});
describe('getRecentTrafficLogs', () => {
@@ -427,38 +415,9 @@ describe('Proxy Advanced Handler', () => {
});
describe('generateIdeConfig', () => {
it('uses loopback when network enumeration fails', async () => {
vi.mocked(networkInterfaces).mockImplementationOnce(() => {
throw new Error('network enumeration denied');
});
const result = await generateIdeConfig('vscode');
expect(networkInterfaces).toHaveBeenCalledOnce();
expect(result.success, result.error).toBe(true);
expect(result.data?.content).toMatchObject({ 'openai.url': 'http://127.0.0.1:8045/v1' });
});
it('uses the discovered LAN address when enumeration succeeds', async () => {
vi.mocked(networkInterfaces).mockReturnValueOnce({
eth0: [
{
address: '192.0.2.10',
netmask: '255.255.255.0',
family: 'IPv4',
mac: '00:11:22:33:44:55',
internal: false,
cidr: '192.0.2.10/24',
},
],
});
const result = await generateIdeConfig('vscode');
expect(networkInterfaces).toHaveBeenCalledOnce();
expect(result.success, result.error).toBe(true);
expect(result.data?.content).toMatchObject({ 'openai.url': 'http://192.0.2.10:8045/v1' });
});
it('should generate fallback config when proxyIdeConfig is null', async () => {
const result = await generateIdeConfig('vscode');
expect(result.success, result.error).toBe(true);
expect(result.success).toBe(true);
expect(result.data?.name).toBe('VS Code');
});
@@ -501,5 +460,5 @@ describe('Proxy Advanced Handler', () => {
expect(result.data?.proxySetting).toBe('OPENAI_BASE_URL');
vi.mocked(proxyAdvancedRegistry).proxyIdeConfig = null;
});
});
});
});
@@ -24,7 +24,7 @@ vi.mock('../../../ipc/database/cloudHandler', () => ({
ensureDatabaseInitialized: vi.fn(),
}));
vi.mock('../../../utils/paths', () => ({
vi.mock('../../../utils/paths', () => ({
IS_DEV_ENVIRONMENT: false,
getCloudAccountsDbPath: vi.fn(() => '/mock/db/path.sqlite'),
}));
+2 -2
View File
@@ -4,8 +4,8 @@ import path from 'path';
vi.mock('../../utils/paths', async () => {
const path = await import('path');
return {
IS_DEV_ENVIRONMENT: false,
return {
IS_DEV_ENVIRONMENT: false,
getAgentDir: vi.fn(() => path.join(process.cwd(), 'temp_test_logs')),
};
});
+1 -51
View File
@@ -1,57 +1,7 @@
import { describe, expect, it, vi } from 'vitest';
import { describe, expect, it } from 'vitest';
import { RateLimitReason, RateLimitTracker } from '../../server/modules/proxy/rate-limit-tracker';
describe('RateLimitTracker parity replay', () => {
it.each([
['500ms', 2],
['2500ms', 3],
['2.2s100ms', 3],
['1h2m3s', 3723],
[' 30s ', 30],
['30seconds', 5],
['invalid30s', 5],
])(
'parses complete retry duration %s without confusing minutes and milliseconds',
(duration, expected) => {
const tracker = new RateLimitTracker();
const info = tracker.parseAndMarkFromError({
accountId: 'acc-duration',
status: 503,
body: JSON.stringify({
error: { details: [{ reason: 'MODEL_CAPACITY_EXHAUSTED', retryDelay: duration }] },
}),
backoffSteps: [60],
});
expect(info?.retryAfterSec).toBe(expected);
},
);
it('waits for the longer of the account and model lockouts', () => {
const now = Date.parse('2026-01-01T00:00:00Z');
const clock = vi.spyOn(Date, 'now').mockReturnValue(now);
try {
const tracker = new RateLimitTracker();
tracker.setLockoutUntilIso(
'acc-overlap',
new Date(now + 5000).toISOString(),
RateLimitReason.RateLimitExceeded,
);
tracker.setLockoutUntilIso(
'acc-overlap',
new Date(now + 60000).toISOString(),
RateLimitReason.QuotaExhausted,
'model-a',
);
expect(tracker.getRemainingWaitSeconds('acc-overlap', 'model-a')).toBe(60);
expect(tracker.getRemainingWaitSeconds('acc-overlap', 'model-b')).toBe(5);
clock.mockReturnValue(now + 10000);
expect(tracker.getRemainingWaitSeconds('acc-overlap', 'model-a')).toBe(50);
expect(tracker.getRemainingWaitSeconds('acc-overlap', 'model-b')).toBe(0);
} finally {
clock.mockRestore();
}
});
it('uses Retry-After header before body/default', () => {
const tracker = new RateLimitTracker();
const info = tracker.parseAndMarkFromError({
+2 -2
View File
@@ -104,8 +104,8 @@ vi.mock('electron', () => {
session: {
webRequest: {
onBeforeSendHeaders: vi.fn(),
},
},
}
}
},
on: vi.fn(),
})),
+1 -1
View File
@@ -25,7 +25,7 @@ vi.mock('../../ipc/database/cloudHandler', () => ({
ensureDatabaseInitialized: vi.fn(),
}));
vi.mock('../../utils/paths', () => ({
vi.mock('../../utils/paths', () => ({
IS_DEV_ENVIRONMENT: false,
getCloudAccountsDbPath: vi.fn(() => '/mock/db/path.sqlite'),
}));