docs(readme): padrão SaaS
Lint / ESLint Check (pull_request) Failing after 8m20s
Check formatting / Prettier Format Check (pull_request) Failing after 8m37s
Tests / Unit Tests (pull_request) Successful in 13m53s
Tests / Type Check (pull_request) Successful in 11m31s

This commit is contained in:
evandro committed 2026-11-16 00:02:29 -03:00
1 parent 2a5d482c52
commit e3652f43f5
14 files changed
+982 -894

No files matched your search

+202 -276
View File
@@ -1,336 +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í. Los builds no están firmados. Haz clic en **Más información → Ejecutar de todas formas**.
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.
</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>