docs(readme): padrão SaaS
This commit is contained in:
1 parent
2a5d482c52
commit
e3652f43f5
14 files changed
+982
-894
No files matched your search
+202
-276
@@ -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>
|
||||

|
||||

|
||||

|
||||
|
||||
<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>
|
||||
Reference in new issue
Block a user