evandro/gemini-nexus
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refine READMEs and highlight Windows SmartScreen warning

Browse Source 
- Move Windows SmartScreen workaround instructions to a highly visible warning block at the top of the files
- Add SmartScreen instructions to the Installation / Downloads sections
- Standardize headings, hierarchy, and formatting across all 4 languages (EN, PT-BR, ES, ZH-CN)
- Polish text for better flow and clarity in 'Why Gemini Nexus?' and Tech Stack sections
This commit is contained in:
Gemini Nexus Bot committed 2026-05-02 02:46:14 -03:00
1 parent a4727713d2
commit 0dbae81353
4 files changed
+412 -214
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.es.md
+126 -46
View File
@@ -23,27 +23,48 @@
<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>
> [!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.
---
## 📖 Tabla de Contenidos
- [✨ ¿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)
---
## ✨ ¿Por qué Gemini Nexus?
Al usar IDEs y herramientas de programación con IA, ¿te has encontrado con estos problemas?
- 😫 La cuota de una sola cuenta se agota rápido, requiriendo cambios manuales frecuentes
- 🔄 Gestionar múltiples cuentas de Google/Claude es tedioso
- 📊 No sabes cuántos tokens has consumido o cuánta cuota queda
- 🔌 Necesitas un proxy local confiable que hable los protocolos OpenAI/Anthropic
- 😫 **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:
**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.
- ✅ **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
- ✅ **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
- ✅ **Seguro por Defecto** — Cifrado AES-256-GCM con gestión nativa de credenciales del SO
### 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.
---
@@ -79,7 +100,7 @@ Al usar IDEs y herramientas de programación con IA, ¿te has encontrado con est
<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</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>
@@ -99,17 +120,17 @@ Al usar IDEs y herramientas de programación con IA, ¿te has encontrado con est
<td width="50%">
<h3>🔍 Observabilidad del Proxy (Avanzado)</h3>
<ul>
<li><strong>Monitor de Tráfico</strong> — Log en vivo de solicitudes/respuestas</li>
<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 visión, thinking, streaming, modo JSON</li>
<li><strong>Herramientas para Devs</strong> — Generación de código cURL y Python</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</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>
@@ -119,8 +140,9 @@ Al usar IDEs y herramientas de programación con IA, ¿te has encontrado con est
<td width="50%">
<h3>⚙️ Configuración y Personalización</h3>
<ul>
<li>Tema Oscuro / Claro / Sistema</li>
<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>
@@ -130,8 +152,9 @@ Al usar IDEs y herramientas de programación con IA, ¿te has encontrado con est
<ul>
<li>App nativa Electron con integración en bandeja del sistema</li>
<li>Sidebar colapsable con estado persistente</li>
<li>Layouts responsivos</li>
<li>Barra de estado con indicadores en vivo</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>
@@ -165,31 +188,46 @@ Al usar IDEs y herramientas de programación con IA, ¿te has encontrado con est
---
## ⚡ Inicio Rápido
## ⚡ Instalación e Inicio Rápido
### Requisitos Previos
### 📦 Descarga
- **Node.js** v20 o superior
- **npm**
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).
### Compilar desde el Código Fuente
*(Consulta la advertencia en la parte superior de esta página si usas Windows y te encuentras con el aviso de SmartScreen).*
```bash
git clone https://github.com/evandrodevbr/GeminiNexus.git
cd GeminiNexus
npm install
npm start
### 🔌 Uso con IDEs de IA
# Compilar para producción
npm run make
```
### 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
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
```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
```
---
@@ -209,27 +247,67 @@ Model: gemini-3-flash
---
## 💻 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
```
---
## ❓ Preguntas Frecuentes
<details>
<summary><b>P: ¿La app no inicia?</b></summary>
1. Asegúrate de que las dependencias están instaladas: `npm install`
2. Node.js versión >= 20
3. Intenta eliminar `node_modules` y reinstalar
<summary><b>P: ¿Aviso de Windows SmartScreen ("Windows protegió su PC") durante la instalación?</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.
</details>
<details>
<summary><b>P: ¿El IDE no conecta al proxy?</b></summary>
1. Asegúrate de que el proxy está corriendo (indicador verde en la barra de estado)
2. Confirma que el puerto coincide (por defecto `10100`)
3. Copia la API key de la página Proxy
4. Asegúrate de tener al menos una cuenta activa
<summary><b>P: ¿La app no inicia al compilar desde el código fuente?</b></summary>
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>
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>
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>
---
## 🤝 Contribuir
¡Las contribuciones son bienvenidas! Por favor lee `CONTRIBUTING.md` para más detalles.
---
## 📄 Licencia
@@ -244,6 +322,8 @@ Model: gemini-3-flash
> **Solo con Fines Educativos**
>
> Este proyecto está destinado exclusivamente a fines educativos y de investigación. Se proporciona "tal cual" sin ninguna garantía. **El uso comercial está estrictamente prohibido.**
>
> Al utilizar este software, aceptas que no lo usarás para ningún fin comercial y eres el único responsable de asegurar que tu uso cumpla con todas las leyes y regulaciones aplicables. Los autores y colaboradores no son responsables del mal uso o los daños derivados de la utilización de este software.
---
README.md
+78 -64
View File
@@ -26,19 +26,22 @@
<img src="https://img.shields.io/badge/electron-latest-47848F?style=flat-square&logo=electron&logoColor=white" alt="Electron" />
</p>
> [!IMPORTANT]
> **Windows Users:** If you see a **"Windows protected your PC"** (SmartScreen) warning during installation, click **"More info"** and then **"Run anyway"**. This is an expected security prompt for new, unsigned applications.
---
## 📖 Table of Contents
- [Why Gemini Nexus?](#-why-gemini-nexus)
- [Features](#-features)
- [Screenshots](#-screenshots)
- [Quick Start](#-quick-start)
- [Tech Stack](#️-tech-stack)
- [Development](#-development)
- [FAQ](#-faq)
- [Contributing](#-contributing)
- [License](#-license)
- [✨ Why Gemini Nexus?](#-why-gemini-nexus)
- [🎯 Features](#-features)
- [📸 Screenshots](#-screenshots)
- [⚡ Installation & Quick Start](#-installation--quick-start)
- [🛠️ Tech Stack](#️-tech-stack)
- [💻 Development](#-development)
- [❓ FAQ](#-faq)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)
---
@@ -46,20 +49,22 @@
When using AI-powered IDEs and coding tools, have you ever run into these problems?
- 😫 Single account quota runs out quickly, requiring frequent manual switching
- 🔄 Managing multiple Google/Claude accounts is cumbersome
- 📊 Don't know how much quota or tokens you've consumed
- 🔌 Need a reliable local API proxy that speaks OpenAI/Anthropic protocols
- 🔍 Can't see what's actually being sent/received by the proxy
- 😫 **Quota limits:** Single account quotas run out quickly, requiring frequent manual switching.
- 🔄 **Account management:** Managing multiple Google/Claude accounts is cumbersome.
- 📊 **Blind usage:** You don't know how much quota or how many tokens you've actually consumed.
- 🔌 **Integration issues:** You need a reliable local API proxy that speaks OpenAI/Anthropic protocols natively.
- 🔍 **Lack of transparency:** You can't see what's actually being sent or received by the proxy under the hood.
**Gemini Nexus** solves all of these. It's a professional Electron desktop application that acts as an intelligent gateway between your development tools and Google Gemini / Claude AI:
**Gemini Nexus** solves all of these issues. It's a professional Electron desktop application that acts as an intelligent gateway between your development tools and Google Gemini / Claude AI.
- ✅ **Unlimited Account Pool** — Add any number of Google Gemini & Claude accounts
- ✅ **Smart Auto-Switching** — Automatically rotates to the next available account when quota is low or rate-limited
- ✅ **Real-time Usage Analytics** — SaaS-grade dashboard with area charts, trend indicators, and model distribution
- ✅ **Full Proxy Observability** — Live traffic monitor, request replay, and model capabilities inspector
- ✅ **OpenAI & Anthropic Compatible** — Drop-in replacement proxy for Cursor, Windsurf, OpenCode, and any OpenAI-compatible tool
- ✅ **Secure by Default** — AES-256-GCM encryption with OS-native credential management
### Key Value Proposition
- ✅ **Unlimited Account Pool** — Add any number of Google Gemini & Claude accounts.
- ✅ **Smart Auto-Switching** — Automatically rotates to the next available account when quota is low or rate-limited.
- ✅ **Real-time Usage Analytics** — SaaS-grade dashboard with area charts, trend indicators, and model distribution.
- ✅ **Full Proxy Observability** — Live traffic monitor, request replay, and model capabilities inspector.
- ✅ **OpenAI & Anthropic Compatible** — Drop-in replacement proxy for Cursor, Windsurf, OpenCode, and any OpenAI-compatible tool.
- ✅ **Secure by Default** — AES-256-GCM encryption with OS-native credential management.
---
@@ -161,37 +166,55 @@ When using AI-powered IDEs and coding tools, have you ever run into these proble
<p align="center">
<img src="docs/assets/main.png" alt="Main" width="80%" />
<img src="docs/assets/main.png" alt="Main Dashboard" width="80%" />
</p>
<p align="center">
<img src="docs/assets/2usage.png" alt="Usage" width="80%" />
<img src="docs/assets/2usage.png" alt="Usage Analytics" width="80%" />
</p>
<p align="center">
<img src="docs/assets/3proxy.png" alt="Proxy" width="80%" />
<img src="docs/assets/3proxy.png" alt="Proxy Monitor" width="80%" />
</p>
<p align="center">
<img src="docs/assets/4routing.png" alt="Routing" width="80%" />
<img src="docs/assets/4routing.png" alt="Routing Config" width="80%" />
</p>
<p align="center">
<img src="docs/assets/5docs.png" alt="Docs" width="80%" />
<img src="docs/assets/5docs.png" alt="Documentation" width="80%" />
</p>
<p align="center">
<img src="docs/assets/6connections.png" alt="Connections" width="80%" />
<img src="docs/assets/6connections.png" alt="Active Connections" width="80%" />
</p>
<p align="center">
<img src="docs/assets/7config.png" alt="Config" width="80%" />
<img src="docs/assets/7config.png" alt="Settings Configuration" width="80%" />
</p>
---
## ⚡ Quick Start
## ⚡ Installation & Quick Start
### Prerequisites
### 📦 Download the App
You can download the latest pre-compiled binaries for Windows, macOS, and Linux from our [Releases page](https://github.com/evandrodevbr/GeminiNexus/releases).
*(Refer to the warning at the top of this page if you are using Windows and encounter the SmartScreen prompt).*
### 🔌 Using with AI IDEs
Once the application is running and you have added at least one account, configure your preferred IDE (Cursor, Windsurf, OpenCode, etc.):
```plaintext
API Base URL: http://localhost:10100/v1
API Key: (copy this from the Proxy page in the app)
Model: gemini-3-flash (or any mapped model of your choice)
```
### 🛠️ Build from Source
#### Prerequisites
- **Node.js** v20 or higher
- **npm** (this project uses `package-lock.json`)
### Build from Source
#### Steps
```bash
# Clone the repository
@@ -201,24 +224,13 @@ cd GeminiNexus
# Install dependencies
npm install
# Start development
# Start the application in development mode
npm start
# Build for production (Windows installer)
# Build for production (e.g., Windows installer)
npm run make
```
### Using with AI IDEs
Once the proxy is running, configure your IDE:
```plaintext
# In Cursor / Windsurf / OpenCode settings:
API Base URL: http://localhost:10100/v1
API Key: (copy from the Proxy page in the app)
Model: gemini-3-flash (or any mapped model)
```
---
## 🛠️ Tech Stack
@@ -281,41 +293,43 @@ src/
## ❓ FAQ
<details>
<summary><b>Q: The app won't start?</b></summary>
<summary><b>Q: "Windows protected your PC" (SmartScreen) warning during installation?</b></summary>
Yes, this is a common warning for new unsigned applications. Click **"More info"** and then **"Run anyway"**. See the warning at the top of the README for more details.
</details>
<details>
<summary><b>Q: The app won't start when building from source?</b></summary>
1. Make sure all dependencies are installed: `npm install`
2. Check if Node.js version is >= 20
3. Try deleting `node_modules` and reinstalling
4. On Windows, ensure the WiX Toolset is available for `npm run make`
2. Check if your Node.js version is >= 20.
3. Try deleting `node_modules` and reinstalling.
4. On Windows, ensure the WiX Toolset is available for `npm run make`.
</details>
<details>
<summary><b>Q: Account login failed?</b></summary>
1. Ensure network connection is working
2. Try clearing app data and logging in again
3. Check if the account is restricted by Google/Claude
1. Ensure your network connection is working.
2. Try clearing the app data and logging in again.
3. Check if the account is restricted by Google/Claude.
</details>
<details>
<summary><b>Q: IDE can't connect to the proxy?</b></summary>
1. Make sure the proxy is running (green indicator in the status bar)
2. Verify the port matches your IDE config (default: `10100`)
3. Copy the API key from the Proxy page and paste it in your IDE settings
4. Check that at least one account is active in the Accounts page
<summary><b>Q: My IDE can't connect to the proxy?</b></summary>
1. Make sure the proxy is actually running (look for the green indicator in the status bar).
2. Verify the port matches your IDE config (default is `10100`).
3. Copy the API key directly from the Proxy page and paste it into your IDE settings.
4. Check that at least one account is active in the Accounts page.
</details>
<details>
<summary><b>Q: Token counts show zero?</b></summary>
1. This was a known bug in earlier versions — update to the latest version
2. Token tracking now correctly handles streaming metadata and estimated counts
3. Usage data refreshes every 15 seconds on the Usage Analytics page
<summary><b>Q: Token counts are showing zero?</b></summary>
1. This was a known bug in earlier versions — please update to the latest release.
2. Token tracking now correctly handles streaming metadata and estimated counts.
3. Usage data refreshes every 15 seconds on the Usage Analytics page.
</details>
---
README.pt-BR.md
+73 -59
View File
@@ -26,19 +26,22 @@
<img src="https://img.shields.io/badge/electron-latest-47848F?style=flat-square&logo=electron&logoColor=white" alt="Electron" />
</p>
> [!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)
- [Início Rápido](#-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?](#-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)
---
@@ -46,20 +49,22 @@
Ao usar IDEs e ferramentas de programação com IA, você já enfrentou estes problemas?
- 😫 A cota da conta única acaba rápido, exigindo trocas manuais frequentes
- 🔄 Gerenciar múltiplas contas do Google/Claude é cansativo
- 📊 Não sabe quantos tokens já consumiu ou quanta cota resta
- 🔌 Precisa de um proxy local confiável que fale os protocolos OpenAI/Anthropic
- 🔍 Não consegue ver o que está sendo enviado/recebido pelo proxy
- 😫 **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.
**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:
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.
- ✅ **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 SO
### 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.
---
@@ -98,7 +103,7 @@ Ao usar IDEs e ferramentas de programação com IA, você já enfrentou estes pr
<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 (mostrar/ocultar modelos específicos)</li>
<li>Controle de visibilidade de modelos</li>
</ul>
</td>
<td width="50%">
@@ -115,9 +120,9 @@ Ao usar IDEs e ferramentas de programação com IA, você já enfrentou estes pr
<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, status e informações do modelo</li>
<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 por modelo</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>
@@ -125,7 +130,7 @@ Ao usar IDEs e ferramentas de programação com IA, você já enfrentou estes pr
<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 do SO (Keytar + SafeStorage)</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>
@@ -183,14 +188,32 @@ Ao usar IDEs e ferramentas de programação com IA, você já enfrentou estes pr
---
## ⚡ Início Rápido
## ⚡ Instalação e Início Rápido
### Pré-requisitos
### 📦 Download
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).
*(Consulte o aviso no topo desta página se você estiver usando o Windows e encontrar o prompt do SmartScreen).*
### 🔌 Usando com IDEs de IA
Com o aplicativo rodando e pelo menos uma conta adicionada, configure sua IDE preferida (Cursor, Windsurf, OpenCode, etc.):
```plaintext
API Base URL: http://localhost:10100/v1
API Key: (copie da página Proxy no app)
Model: gemini-3-flash (ou qualquer modelo mapeado)
```
### 🛠️ Compilando pelo Código Fonte
#### Pré-requisitos
- **Node.js** v20 ou superior
- **npm** (este projeto usa `package-lock.json`)
### Compilando pelo Código Fonte
#### Passos
```bash
# Clone o repositório
@@ -203,21 +226,10 @@ npm install
# Inicie o modo de desenvolvimento
npm start
# Compile para produção (instalador Windows)
# Compile para produção (ex: instalador Windows)
npm run make
```
### Usando com IDEs de IA
Com o proxy em execução, configure sua IDE:
```plaintext
# Nas configurações do Cursor / Windsurf / OpenCode:
API Base URL: http://localhost:10100/v1
API Key: (copie da página Proxy no app)
Model: gemini-3-flash (ou qualquer modelo mapeado)
```
---
## 🛠️ Stack Tecnológica
@@ -280,41 +292,43 @@ src/
## ❓ FAQ
<details>
<summary><b>P: O app não inicia?</b></summary>
<summary><b>P: Aviso do Windows SmartScreen ("O Windows protegeu o seu computador") durante a instalação?</b></summary>
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 `npm run make`
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.
</details>
<details>
<summary><b>P: O app não inicia ao compilar pelo código fonte?</b></summary>
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>
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
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 conecta no proxy?</b></summary>
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
<summary><b>P: A IDE não consegue conectar ao proxy?</b></summary>
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>
1. Este era um bug conhecido em versões anteriores — 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
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>
---
README.zh-CN.md
+135 -45
View File
@@ -23,25 +23,48 @@
<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>
> [!IMPORTANT]
> **Windows 用户：** 如果在安装过程中看到 **“Windows 已保护你的电脑”** (SmartScreen) 警告，请点击 **“更多信息”** (More info)，然后点击 **“仍要运行”** (Run anyway)。这是未签名的新应用预期的安全提示，属于正常现象。
---
## 📖 目录
- [✨ 为什么选择 Gemini Nexus？](#-为什么选择-gemini-nexus)
- [🎯 功能特性](#-功能特性)
- [📸 截图](#-截图)
- [⚡ 安装与快速开始](#-安装与快速开始)
- [🛠️ 技术栈](#️-技术栈)
- [💻 开发](#-开发)
- [❓ 常见问题](#-常见问题)
- [🤝 参与贡献](#-参与贡献)
- [📄 许可证](#-许可证)
---
## ✨ 为什么选择 Gemini Nexus？
- 😫 单个账户配额很快用完，需要频繁手动切换
- 🔄 管理多个 Google/Claude 账户非常繁琐
- 📊 不知道已经消耗了多少 Token 或还剩多少配额
- 🔌 需要一个可靠的本地 API 代理，支持 OpenAI/Anthropic 协议
在使用 AI 驱动的 IDE 和编程工具时，你是否遇到过这些问题？
**Gemini Nexus** 解决所有这些问题。它是一个专业的 Electron 桌面应用，作为你的开发工具和 Google Gemini / Claude AI 之间的智能网关：
- 😫 **配额限制：** 单个账户配额很快用完，需要频繁手动切换。
- 🔄 **账户管理：** 管理多个 Google/Claude 账户非常繁琐。
- 📊 **盲目使用：** 不知道已经消耗了多少 Token 或还剩多少配额。
- 🔌 **集成问题：** 需要一个可靠的本地 API 代理，并且必须原生支持 OpenAI/Anthropic 协议。
- 🔍 **缺乏透明度：** 无法查看代理在后台实际发送或接收的数据。
- ✅ **无限账户池** — 添加任意数量的 Google Gemini 和 Claude 账户
- ✅ **智能自动切换** — 当配额不足或被限速时自动轮换到下一个可用账户
- ✅ **实时使用分析** — SaaS 级仪表板，配备面积图、趋势指标和模型分布
- ✅ **完整的代理可观测性** — 实时流量监控、请求重放和模型能力检查器
- ✅ **兼容 OpenAI 和 Anthropic** — 即插即用的代理，支持 Cursor、Windsurf、OpenCode
- ✅ **默认安全** — AES-256-GCM 加密，配合操作系统原生凭证管理
**Gemini Nexus** 解决所有这些问题。它是一个专业的 Electron 桌面应用，作为你的开发工具和 Google Gemini / Claude AI 之间的智能网关。
### 核心价值主张
- ✅ **无限账户池** — 添加任意数量的 Google Gemini 和 Claude 账户。
- ✅ **智能自动切换** — 当配额不足或被限速时自动轮换到下一个可用账户。
- ✅ **实时使用分析** — SaaS 级仪表板，配备面积图、趋势指标和模型分布。
- ✅ **完整的代理可观测性** — 实时流量监控、请求重放和模型能力检查器。
- ✅ **兼容 OpenAI 和 Anthropic** — 即插即用的代理，支持 Cursor、Windsurf、OpenCode 以及任何兼容 OpenAI 的工具。
- ✅ **默认安全** — AES-256-GCM 加密，配合操作系统原生凭证管理。
---
@@ -77,10 +100,10 @@
<ul>
<li>兼容 OpenAI <code>/v1/chat/completions</code></li>
<li>兼容 Anthropic <code>/v1/messages</code></li>
<li>完整的 SSE 流式传输支持</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>
<li>模型可见性控制（隐藏/显示特定模型）</li>
</ul>
</td>
<td width="50%">
@@ -97,17 +120,17 @@
<td width="50%">
<h3>🔍 代理可观测性（高级）</h3>
<ul>
<li><strong>流量监控</strong> — 实时请求/响应日志</li>
<li><strong>流量监控</strong> — 实时请求/响应日志，含延迟和模型信息</li>
<li><strong>请求重放</strong> — 重放任意请求进行调试</li>
<li><strong>模型能力</strong> — 检查视觉、思考、流式、JSON 模式</li>
<li><strong>开发者工具</strong> — cURL 和 Python 代码生成</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>集成操作系统原生凭证管理器</li>
<li>集成操作系统原生凭证管理器 (Keytar + SafeStorage)</li>
<li>自动迁移旧版明文数据</li>
<li>每个账户的 Token 和配额均加密存储</li>
</ul>
@@ -119,6 +142,7 @@
<ul>
<li>深色 / 浅色 / 跟随系统主题</li>
<li>多语言：English & Português (Brasil)</li>
<li>每个账户可独立覆盖代理 URL</li>
<li>模型可见性开关</li>
<li>日志目录访问</li>
</ul>
@@ -128,8 +152,9 @@
<ul>
<li>原生 Electron 应用，系统托盘集成</li>
<li>可折叠侧边栏，状态持久化</li>
<li>响应式布局</li>
<li>响应式布局适配所有视图</li>
<li>状态栏实时显示代理和连接指标</li>
<li>错误边界处理以及友好的用户提示</li>
</ul>
</td>
</tr>
@@ -163,31 +188,46 @@
---
## ⚡ 快速开始
## ⚡ 安装与快速开始
### 前置要求
### 📦 下载
- **Node.js** v20 或更高版本
- **npm**
您可以从我们的 [Releases 页面](https://github.com/evandrodevbr/GeminiNexus/releases) 下载适用于 Windows、macOS 和 Linux 的最新预编译版本。
### 从源码构建
*(如果您使用的是 Windows 并在安装时遇到了 SmartScreen 提示，请参阅页面顶部的警告)。*
```bash
git clone https://github.com/evandrodevbr/GeminiNexus.git
cd GeminiNexus
npm install
npm start
### 🔌 配合 AI IDE 使用
# 构建生产版本
npm run make
```
### 配合 AI IDE 使用
在代理运行并至少添加一个账户后，配置您首选的 IDE（Cursor、Windsurf、OpenCode 等）：
```plaintext
API Base URL: http://localhost:10100/v1
API Key: （从应用的 Proxy 页面复制）
Model: gemini-3-flash
Model: gemini-3-flash （或您选择的任何映射模型）
```
### 🛠️ 从源码构建
#### 前置要求
- **Node.js** v20 或更高版本
- **npm** （本项目使用 `package-lock.json`）
#### 步骤
```bash
# 克隆仓库
git clone https://github.com/evandrodevbr/GeminiNexus.git
cd GeminiNexus
# 安装依赖
npm install
# 启动开发环境
npm start
# 构建生产版本（例如 Windows 安装程序）
npm run make
```
---
@@ -207,27 +247,75 @@ Model: gemini-3-flash
---
## 💻 开发
```bash
# 启动开发环境 (Electron + Vite HMR)
npm start
# 运行代码规范检查
npm run lint
# 类型检查
npm run type-check
# 格式化代码
npm run format:write
# 运行测试
npm test
```
---
## ❓ 常见问题
<details>
<summary><b>问：应用无法启动？</b></summary>
1. 确保依赖已安装：`npm install`
2. Node.js 版本 >= 20
3. 尝试删除 `node_modules` 并重新安装
<summary><b>问：安装时出现 Windows SmartScreen 警告（"Windows 已保护你的电脑"）？</b></summary>
是的，对于未签名的新应用，这是一个常见的警告。请点击 **"更多信息"** (More info)，然后点击 **"仍要运行"** (Run anyway)。详情请参阅 README 顶部的提示。
</details>
<details>
<summary><b>问：IDE 无法连接代理？</b></summary>
1. 确保代理正在运行（状态栏绿色指示器）
2. 确认端口一致（默认 `10100`）
3. 从 Proxy 页面复制 API 密钥
4. 确保至少有一个账户处于活跃状态
<summary><b>问：从源码构建时应用无法启动？</b></summary>
1. 确保所有依赖均已安装：`npm install`
2. 检查 Node.js 版本是否 >= 20。
3. 尝试删除 `node_modules` 并重新安装。
4. 在 Windows 上，请确保已安装 WiX Toolset 以便执行 `npm run make` 命令。
</details>
<details>
<summary><b>问：账户登录失败？</b></summary>
1. 确保您的网络连接正常。
2. 尝试清除应用数据并重新登录。
3. 检查该账户是否已被 Google/Claude 限制。
</details>
<details>
<summary><b>问：IDE 无法连接到代理？</b></summary>
1. 确保代理正在运行（查看状态栏的绿色指示器）。
2. 确认端口与您 IDE 中的配置一致（默认为 `10100`）。
3. 直接从 Proxy 页面复制 API 密钥并粘贴到 IDE 设置中。
4. 确保在 Accounts 页面中至少有一个活跃的账户。
</details>
<details>
<summary><b>问：Token 计数显示为零？</b></summary>
1. 这是早期版本中的一个已知漏洞 — 请更新至最新版本。
2. 目前 Token 追踪功能已能正确处理流式元数据及预估计数。
3. 使用数据会在 Usage Analytics 页面每 15 秒自动刷新。
</details>
---
## 🤝 参与贡献
欢迎贡献代码！详情请参阅 `CONTRIBUTING.md`。
---
## 📄 许可证
@@ -242,6 +330,8 @@ Model: gemini-3-flash
> **仅供教育目的**
>
> 本项目仅供教育和研究目的使用。按"原样"提供，不提供任何担保。**严禁商业用途。**
>
> 使用本软件即表示您同意不会将其用于任何商业目的，并且您全权负责确保您的使用符合所有适用的法律和法规。作者和贡献者对因使用本软件而引起的任何滥用或损害不承担任何责任。
---