263 lines
17 KiB
Markdown
263 lines
17 KiB
Markdown
<div align="center">
|
|
|
|
<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><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>
|
|
|
|
<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>
|
|
|
|
</div>
|
|
|
|
## 📸 Capturas de pantalla
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
</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%" 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)).
|
|
|
|
## Cómo funciona
|
|
|
|
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).
|
|
|
|
## ⚡ Inicio rápido
|
|
|
|
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.
|
|
|
|
| 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
|
|
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:
|
|
|
|
```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**.
|
|
|
|
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>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**.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<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.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<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.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<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.
|
|
|
|
</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
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
|
|
<img src="docs/assets/logo.png" width="56" alt="Logo de Gemini Nexus">
|
|
|
|
<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>
|
|
|
|
</div>
|