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
+188
-291
@@ -1,365 +1,262 @@
|
||||
<p align="center">
|
||||
<img src="docs/assets/logo.png" alt="Gemini Nexus" width="128" height="128" />
|
||||
</p>
|
||||
<div align="center">
|
||||
|
||||
<h1 align="center">Gemini Nexus</h1>
|
||||
<img src="assets/readme/hero.pt-BR.png" width="100%" alt="Gemini Nexus: gateway desktop que reúne contas Google atrás de uma API local compatível com OpenAI e Anthropic em http://localhost:8045/v1, trocando de conta quando a cota acaba">
|
||||
|
||||
<p align="center">
|
||||
<strong>🚀 Gateway de IA multi-contas profissional para Google Gemini & Claude</strong>
|
||||
</p>
|
||||

|
||||

|
||||

|
||||
|
||||
<p align="center">
|
||||
<a href="README.md">English</a> | Português | <a href="README.zh-CN.md">中文</a> | <a href="README.es.md">Español</a>
|
||||
</p>
|
||||
<p><strong><a href="#-início-rápido">Início rápido</a></strong> · <a href="#-documentação-e-desenvolvimento">Docs</a> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Issues</a></p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/evandrodevbr/GeminiNexus/releases">
|
||||
<img src="https://img.shields.io/github/v/release/evandrodevbr/GeminiNexus?style=flat-square" alt="Release" />
|
||||
</a>
|
||||
<a href="https://github.com/evandrodevbr/GeminiNexus/releases">
|
||||
<img src="https://img.shields.io/github/downloads/evandrodevbr/GeminiNexus/total?style=flat-square&color=blue" alt="Downloads" />
|
||||
</a>
|
||||
<a href="https://github.com/evandrodevbr/GeminiNexus/blob/main/LICENSE">
|
||||
<img src="https://img.shields.io/github/license/evandrodevbr/GeminiNexus?style=flat-square" alt="Licença" />
|
||||
</a>
|
||||
<img src="https://img.shields.io/badge/plataforma-Windows%20%7C%20macOS%20%7C%20Linux-informational?style=flat-square" alt="Plataforma" />
|
||||
<img src="https://img.shields.io/badge/electron-latest-47848F?style=flat-square&logo=electron&logoColor=white" alt="Electron" />
|
||||
</p>
|
||||
<sub><a href="README.md">English</a> · Português · <a href="README.zh-CN.md">中文</a> · <a href="README.es.md">Español</a></sub>
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Usuários do Windows:** Se você vir um aviso do SmartScreen **"O Windows protegeu o seu computador"** durante a instalação, clique em **"Mais informações"** e depois em **"Executar mesmo assim"**. Isso é um aviso de segurança esperado para aplicativos novos e não assinados.
|
||||
|
||||
---
|
||||
|
||||
## 📖 Sumário
|
||||
|
||||
- [✨ Por que o Gemini Nexus?](#-por-que-o-gemini-nexus)
|
||||
- [🎯 Funcionalidades](#-funcionalidades)
|
||||
- [📸 Screenshots](#-screenshots)
|
||||
- [⚡ Instalação e Início Rápido](#-instalação-e-início-rápido)
|
||||
- [🛠️ Stack Tecnológica](#️-stack-tecnológica)
|
||||
- [💻 Desenvolvimento](#-desenvolvimento)
|
||||
- [❓ FAQ](#-faq)
|
||||
- [🤝 Contribuindo](#-contribuindo)
|
||||
- [📄 Licença](#-licença)
|
||||
|
||||
---
|
||||
|
||||
## ✨ Por que o Gemini Nexus?
|
||||
|
||||
Ao usar IDEs e ferramentas de programação com IA, você já enfrentou estes problemas?
|
||||
|
||||
- 😫 **Limites de cota:** A cota da conta única acaba rápido, exigindo trocas manuais frequentes.
|
||||
- 🔄 **Gestão de contas:** Gerenciar múltiplas contas do Google/Claude é cansativo.
|
||||
- 📊 **Uso às cegas:** Você não sabe quantos tokens já consumiu ou quanta cota resta.
|
||||
- 🔌 **Problemas de integração:** Precisa de um proxy local confiável que fale os protocolos OpenAI/Anthropic nativamente.
|
||||
- 🔍 **Falta de transparência:** Não consegue ver o que está sendo enviado ou recebido pelo proxy nos bastidores.
|
||||
|
||||
O **Gemini Nexus** resolve tudo isso. É um aplicativo desktop profissional em Electron que funciona como um gateway inteligente entre suas ferramentas de desenvolvimento e o Google Gemini / Claude AI.
|
||||
|
||||
### Principais Vantagens
|
||||
|
||||
- ✅ **Pool de Contas Ilimitado** — Adicione quantas contas Google Gemini & Claude quiser.
|
||||
- ✅ **Troca Automática Inteligente** — Rotaciona automaticamente para a próxima conta disponível quando a cota está baixa ou com rate limit.
|
||||
- ✅ **Analytics de Uso em Tempo Real** — Dashboard nível SaaS com gráficos de área, indicadores de tendência e distribuição por modelo.
|
||||
- ✅ **Observabilidade Completa do Proxy** — Monitor de tráfego ao vivo, replay de requisições e inspetor de capacidades dos modelos.
|
||||
- ✅ **Compatível com OpenAI & Anthropic** — Proxy drop-in para Cursor, Windsurf, OpenCode e qualquer ferramenta compatível com OpenAI.
|
||||
- ✅ **Seguro por Padrão** — Criptografia AES-256-GCM com gerenciamento nativo de credenciais do sistema operacional.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Funcionalidades
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="50%">
|
||||
<h3>☁️ Pool de Contas na Nuvem</h3>
|
||||
<ul>
|
||||
<li>Adicione contas ilimitadas do Google Gemini / Claude via OAuth</li>
|
||||
<li>Exibe avatar, e-mail, status e último uso</li>
|
||||
<li>Monitoramento de status em tempo real (Ativa, Rate Limited, Expirada)</li>
|
||||
<li>Configuração de proxy URL por conta</li>
|
||||
<li>Gerenciamento de perfil de identidade do dispositivo com histórico</li>
|
||||
</ul>
|
||||
</td>
|
||||
<td width="50%">
|
||||
<h3>📊 Dashboard de Analytics de Uso</h3>
|
||||
<ul>
|
||||
<li>Consumo de tokens em tempo real com auto-refresh a cada 15s</li>
|
||||
<li>Gráficos de área para tokens de prompt & completion (diário/horário)</li>
|
||||
<li>Indicadores de tendência (% de variação vs período anterior)</li>
|
||||
<li>Sparklines inline nos cards de estatísticas</li>
|
||||
<li>Ranking de distribuição por modelo com gráficos de barras horizontais</li>
|
||||
<li>Visualização da proporção Prompt/Completion</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="50%">
|
||||
<h3>🔌 Proxy de API Local (Gateway)</h3>
|
||||
<ul>
|
||||
<li>Endpoint compatível com OpenAI <code>/v1/chat/completions</code></li>
|
||||
<li>Endpoint compatível com Anthropic <code>/v1/messages</code></li>
|
||||
<li>Streaming SSE completo (testado com Cursor, Windsurf, OpenCode)</li>
|
||||
<li>Mapeamento de modelos (ex: <code>claude-sonnet-4-6</code> → <code>gemini-3-flash</code>)</li>
|
||||
<li>Porta, timeout e API key configuráveis</li>
|
||||
<li>Controle de visibilidade de modelos</li>
|
||||
</ul>
|
||||
</td>
|
||||
<td width="50%">
|
||||
<h3>🔄 Troca Automática Inteligente</h3>
|
||||
<ul>
|
||||
<li>Modo de pool ilimitado com seleção inteligente de backup</li>
|
||||
<li>Troca automática quando cota < 5% ou com rate limit</li>
|
||||
<li>Monitoramento em segundo plano a cada 5 minutos</li>
|
||||
<li>Fallback gracioso com rastreamento de motivo do status</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="50%">
|
||||
<h3>🔍 Observabilidade do Proxy (Avançado)</h3>
|
||||
<ul>
|
||||
<li><strong>Monitor de Tráfego</strong> — Log ao vivo de requisições/respostas com latência e informações do modelo</li>
|
||||
<li><strong>Replay de Requisições</strong> — Reproduza qualquer requisição registrada para debugging</li>
|
||||
<li><strong>Capacidades dos Modelos</strong> — Inspecione suporte a visão, thinking, streaming e modo JSON</li>
|
||||
<li><strong>Ferramentas para Devs</strong> — Geração de código cURL & Python, cópia com um clique</li>
|
||||
</ul>
|
||||
</td>
|
||||
<td width="50%">
|
||||
<h3>🔐 Segurança e Criptografia</h3>
|
||||
<ul>
|
||||
<li>Criptografia AES-256-GCM para todos os dados sensíveis</li>
|
||||
<li>Integração com gerenciador de credenciais nativo (Keytar + SafeStorage)</li>
|
||||
<li>Migração automática de dados legados em texto plano</li>
|
||||
<li>Armazenamento criptografado de tokens & cotas por conta</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="50%">
|
||||
<h3>⚙️ Configurações e Personalização</h3>
|
||||
<ul>
|
||||
<li>Suporte a temas Escuro / Claro / Sistema</li>
|
||||
<li>Multi-idioma: English & Português (Brasil)</li>
|
||||
<li>Override de proxy URL por conta</li>
|
||||
<li>Toggles de visibilidade de modelos</li>
|
||||
<li>Acesso ao diretório de logs</li>
|
||||
</ul>
|
||||
</td>
|
||||
<td width="50%">
|
||||
<h3>🖥️ Experiência Desktop</h3>
|
||||
<ul>
|
||||
<li>App nativo Electron com integração na bandeja do sistema</li>
|
||||
<li>Sidebar retrátil com estado persistente</li>
|
||||
<li>Layouts responsivos em todas as telas</li>
|
||||
<li>Barra de status com indicadores ao vivo de proxy e conexão</li>
|
||||
<li>Error boundaries com fallbacks amigáveis ao usuário</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
---
|
||||
</div>
|
||||
|
||||
## 📸 Screenshots
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/main.png" alt="Main" width="80%" />
|
||||
</p>
|
||||
<p align="center">
|
||||
<img src="docs/assets/2usage.png" alt="Usage" width="80%" />
|
||||
</p>
|
||||
<p align="center">
|
||||
<img src="docs/assets/3proxy.png" alt="Proxy" width="80%" />
|
||||
</p>
|
||||
<p align="center">
|
||||
<img src="docs/assets/4routing.png" alt="Routing" width="80%" />
|
||||
</p>
|
||||
<p align="center">
|
||||
<img src="docs/assets/5docs.png" alt="Docs" width="80%" />
|
||||
</p>
|
||||
<p align="center">
|
||||
<img src="docs/assets/6connections.png" alt="Connections" width="80%" />
|
||||
</p>
|
||||
<p align="center">
|
||||
<img src="docs/assets/7config.png" alt="Config" width="80%" />
|
||||
</p>
|
||||
<p align="center"><img src="docs/assets/main.png" width="100%" alt="Página Accounts: uma conta Google no pool com barras de cota por modelo, o botão Auto-Switch e o contador de cota global"></p>
|
||||
|
||||
---
|
||||
<details>
|
||||
<summary>Mais screenshots: uso, proxy, roteamento, docs, conexões, configurações</summary>
|
||||
|
||||
## ⚡ Instalação e Início Rápido
|
||||
<p align="center"><img src="docs/assets/2usage.png" alt="Analytics de uso" width="80%"></p>
|
||||
<p align="center"><img src="docs/assets/3proxy.png" alt="Monitor do proxy" width="80%"></p>
|
||||
<p align="center"><img src="docs/assets/4routing.png" alt="Configuração de roteamento" width="80%"></p>
|
||||
<p align="center"><img src="docs/assets/5docs.png" alt="Documentação" width="80%"></p>
|
||||
<p align="center"><img src="docs/assets/6connections.png" alt="Conexões ativas" width="80%"></p>
|
||||
<p align="center"><img src="docs/assets/7config.png" alt="Configurações" width="80%"></p>
|
||||
|
||||
### 📦 Download
|
||||
</details>
|
||||
|
||||
Você pode baixar os binários pré-compilados mais recentes para Windows, macOS e Linux na nossa [página de Releases](https://github.com/evandrodevbr/GeminiNexus/releases).
|
||||
## 🎯 Funcionalidades
|
||||
|
||||
*(Consulte o aviso no topo desta página se você estiver usando o Windows e encontrar o prompt do SmartScreen).*
|
||||
Usar IDEs com IA numa única conta Google significa cota que acaba, troca manual de conta e nenhuma visão do que o proxy manda para cima. O Gemini Nexus mantém todas as contas num pool e as serve por um único endpoint local.
|
||||
|
||||
### 🔌 Usando com IDEs de IA
|
||||
<table>
|
||||
<tr>
|
||||
<td width="50%" valign="top"><b>Um endpoint local</b><br><code>POST /v1/chat/completions</code> (OpenAI), <code>POST /v1/messages</code> (Anthropic), <code>GET /v1/models</code> e <code>GET /v1/models/capabilities</code>, para que Cursor, Windsurf, OpenCode, Claude Code e clientes parecidos se conectem. Os nomes de modelo são mapeados por <code>custom_mapping</code> e <code>anthropic_mapping</code>.</td>
|
||||
<td width="50%" valign="top"><b>Pool de contas</b><br>Contas Google adicionadas via OAuth, cada uma com status (Active, Rate Limited, Expired), horário do último uso e uma URL de proxy opcional por conta.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="50%" valign="top"><b>Troca automática</b><br>O <code>CloudMonitorService</code> consulta a cota a cada 5 minutos e o <code>AutoSwitchService</code> passa para outra conta quando a cota cai abaixo de 5 % ou a conta sofre rate limit.</td>
|
||||
<td width="50%" valign="top"><b>Agendamento com circuit breaker</b><br><code>cache-first</code>, <code>balance</code> (padrão) ou <code>performance-first</code>, com circuit breaker por conta (backoff padrão 60 s → 5 min → 30 min → 2 h).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="50%" valign="top"><b>Uso e custo</b><br>Consumo de tokens por conta e por modelo, gráficos de prompt e completion e estimativa de custo com preço por modelo editável.</td>
|
||||
<td width="50%" valign="top"><b>Inspetor de tráfego</b><br>Latência, status e modelo de cada requisição, replay de requisições registradas, snippets cURL e Python gerados e um Quick Setup para IDEs.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
Com o aplicativo rodando e pelo menos uma conta adicionada, configure sua IDE preferida (Cursor, Windsurf, OpenCode, etc.):
|
||||
As credenciais salvas são criptografadas com AES-256-GCM sob uma chave mestra guardada no chaveiro do sistema (veja [Modelo de segurança](#modelo-de-segurança)).
|
||||
|
||||
```plaintext
|
||||
API Base URL: http://localhost:10100/v1
|
||||
## Como funciona
|
||||
|
||||
1. **Adicione contas.** Entre com Google OAuth na página Accounts. Os tokens são criptografados antes de chegar ao SQLite.
|
||||
2. **Aponte a IDE para o proxy.** Ative o proxy na página Proxy (ele vem desligado) e use `http://localhost:8045/v1` com a API key mostrada ali, no formato OpenAI ou Anthropic.
|
||||
3. **O Nexus roteia cada requisição.** O token manager escolhe uma conta pelo modo de agendamento e pelo estado do circuit breaker, chama as APIs upstream do Google com o token OAuth dessa conta, e a troca automática entra em ação quando a cota cai abaixo de 5 % ou uma conta sofre rate limit.
|
||||
|
||||
O fluxo completo, com os componentes envolvidos, está em [Arquitetura](#arquitetura).
|
||||
|
||||
## ⚡ Início rápido
|
||||
|
||||
Ainda não há downloads prontos na página de [Releases do Gitea](https://git.evandro.dev.br/evandro/gemini-nexus/releases) (os workflows de release em `.github/workflows/` são para o GitHub), então compile pelo código-fonte.
|
||||
|
||||
| Ferramenta | Versão mínima |
|
||||
|---|---|
|
||||
| Node.js | 20+ (recomendado no `AGENTS.md`; o `.nvmrc` fixa 22.17.1) |
|
||||
| pnpm | 10.11.0 (`packageManager`; o lockfile é `pnpm-lock.yaml`) |
|
||||
| Toolchain nativa | exigida por `better-sqlite3` e `keytar`: Visual Studio 2022 Build Tools (C++) no Windows, Xcode Command Line Tools no macOS, `build-essential` + `python3` + `libsecret-1-dev` no Ubuntu (`base-devel` + `python` + `libsecret` no Arch) |
|
||||
|
||||
```bash
|
||||
git clone https://git.evandro.dev.br/evandro/gemini-nexus.git
|
||||
cd gemini-nexus
|
||||
pnpm install # o postinstall roda scripts/setup-dev.js --check-only para conferir a toolchain
|
||||
pnpm start # modo dev (Electron + Vite HMR)
|
||||
pnpm run make # instaladores/pacotes para a plataforma atual
|
||||
pnpm run make:win # Windows: extrai o WiX de wix314-binaries.zip e roda o make
|
||||
```
|
||||
|
||||
Depois adicione pelo menos uma conta, ative o proxy (ele vem desligado) e aponte sua IDE para ele:
|
||||
|
||||
```text
|
||||
API Base URL: http://localhost:8045/v1 (padrão, configurável na página Proxy; builds de desenvolvimento usam 8046)
|
||||
API Key: (copie da página Proxy no app)
|
||||
Model: gemini-3-flash (ou qualquer modelo mapeado)
|
||||
Model: gemini-3-flash (ou qualquer modelo mapeado)
|
||||
```
|
||||
|
||||
### 🛠️ Compilando pelo Código Fonte
|
||||
> [!WARNING]
|
||||
> Os builds não são assinados. Se o Windows mostrar "O Windows protegeu o seu computador", clique em **Mais informações → Executar mesmo assim**.
|
||||
|
||||
#### Pré-requisitos
|
||||
Não existe `.env.example` e nenhuma variável é obrigatória. Variáveis opcionais lidas pelo código ou descritas nos docs:
|
||||
|
||||
- **Node.js** v20 ou superior
|
||||
- **npm** (este projeto usa `package-lock.json`)
|
||||
| Variável | Obrigatória | Descrição |
|
||||
|---|---|---|
|
||||
| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | Não | Encaminha as requisições de saída do app por um proxy local (veja inspeção TLS em [Modelo de segurança](#modelo-de-segurança)). |
|
||||
| `NODE_EXTRA_CA_CERTS` | Não | Certificado de CA extra para o TLS do lado Node ao inspecionar tráfego. |
|
||||
| `SENTRY_DSN` | Não | DSN do Sentry usado quando o envio de erros está ativo. |
|
||||
|
||||
#### Passos
|
||||
## 🛠️ Stack
|
||||
|
||||
```bash
|
||||
# Clone o repositório
|
||||
git clone https://github.com/evandrodevbr/GeminiNexus.git
|
||||
cd GeminiNexus
|
||||
| Camada | Tecnologia |
|
||||
|---|---|
|
||||
| Shell desktop | Electron 41, Electron Forge, Vite |
|
||||
| Interface | React 19, TypeScript, Tailwind CSS 4, Radix UI, gráficos Nivo, i18next |
|
||||
| Fluxo de dados do app | TanStack Router e Query, oRPC sobre IPC do Electron |
|
||||
| Proxy | NestJS 11 sobre Fastify |
|
||||
| Armazenamento | SQLite (better-sqlite3 + Drizzle ORM), chaveiro do sistema via `keytar` |
|
||||
| Logs e erros | Winston (arquivos rotativos), Sentry (opcional) |
|
||||
| Testes | Vitest, Playwright |
|
||||
|
||||
# Instale as dependências
|
||||
npm install
|
||||
## Arquitetura
|
||||
|
||||
# Inicie o modo de desenvolvimento
|
||||
npm start
|
||||
|
||||
# Compile para produção (ex: instalador Windows)
|
||||
npm run make
|
||||
```mermaid
|
||||
flowchart LR
|
||||
C["Cliente: Cursor, Windsurf, OpenCode, Claude Code"] -->|"/v1/chat/completions, /v1/messages"| P["Proxy NestJS, porta 8045"]
|
||||
P --> S["Agendador de contas e circuit breaker"]
|
||||
S -->|"conta Google OAuth"| G["APIs upstream do Google"]
|
||||
M["CloudMonitor e AutoSwitch, cota a cada 5 min"] -->|"consulta de cota"| G
|
||||
S -->|"lê contas"| DB[("SQLite: better-sqlite3 e Drizzle")]
|
||||
M --> DB
|
||||
K["AES-256-GCM, chave mestra no chaveiro do sistema"] -->|"criptografa tokens"| DB
|
||||
```
|
||||
|
||||
---
|
||||
1. Um cliente envia requisições no formato OpenAI ou Anthropic para o proxy NestJS (Fastify, escutando em `0.0.0.0`).
|
||||
2. O guard do proxy confere a API key quando há uma configurada; com a chave vazia o proxy roda em modo aberto.
|
||||
3. O token manager escolhe uma conta segundo o modo de agendamento e o estado do circuit breaker de cada conta, e chama as APIs upstream do Google com o token OAuth dessa conta.
|
||||
4. O `CloudMonitorService` consulta a cota a cada 5 minutos e o `AutoSwitchService` troca a conta ativa quando a cota está abaixo de 5 % ou a conta sofre rate limit.
|
||||
5. O renderer React 19 (TanStack Router e Query) conversa com o processo principal via oRPC sobre IPC; contas, uso e configurações ficam no SQLite (better-sqlite3 + Drizzle). Notas de design: [`docs/cloud_features.md`](docs/cloud_features.md).
|
||||
|
||||
## 🛠️ Stack Tecnológica
|
||||
## Modelo de segurança
|
||||
|
||||
| Categoria | Tecnologias |
|
||||
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Core** | [Electron](https://www.electronjs.org/), [React 19](https://react.dev/), [TypeScript](https://www.typescriptlang.org/) |
|
||||
| **Build** | [Vite](https://vitejs.dev/), [Electron Forge](https://www.electronforge.io/) |
|
||||
| **Estilização** | [Tailwind CSS v4](https://tailwindcss.com/), [Radix UI](https://www.radix-ui.com/), [Lucide Icons](https://lucide.dev/) |
|
||||
| **Estado** | [TanStack Query](https://tanstack.com/query/latest), [TanStack Router](https://tanstack.com/router/latest) |
|
||||
| **Backend** | [NestJS](https://nestjs.com/) (gateway interno), [ORPC](https://orpc.unnoq.com/) (RPC type-safe) |
|
||||
| **Banco de Dados** | [Better-SQLite3](https://github.com/WiseLibs/better-sqlite3), [Drizzle ORM](https://orm.drizzle.team/) |
|
||||
| **Gráficos** | [Nivo](https://nivo.rocks/) (Line, Bar, Pie) |
|
||||
| **i18n** | [react-i18next](https://react.i18next.com/) |
|
||||
| **Testes** | [Vitest](https://vitest.dev/), [Playwright](https://playwright.dev/) |
|
||||
O Gemini Nexus guarda tokens OAuth de várias contas e repassa tráfego para cima, então o tratamento de credenciais é o centro do design. Tudo abaixo está implementado neste repositório; os limites aparecem onde existem.
|
||||
|
||||
---
|
||||
- **Armazenamento e isolamento de credenciais.** `token_json` e `quota_json` são criptografados com AES-256-GCM (IV único por operação, autenticado) antes de chegar ao SQLite. A chave mestra fica no cofre de credenciais do sistema via `keytar` (Gerenciador de Credenciais do Windows, Keychain do macOS, Secret Service/libsecret no Linux), nunca num arquivo comum. Linhas legadas em texto puro são migradas na inicialização. As contas ficam num banco próprio (`cloud_accounts.db`), separado do banco local da IDE.
|
||||
- **Mascaramento de logs.** Chaves como `token`, `refresh_token`, `api_key`, `authorization`, `cookie` e `client_secret` são trocadas por `[REDACTED]` antes de ir para o log ([`src/utils/sensitiveDataMasking.ts`](src/utils/sensitiveDataMasking.ts)); o logger de tráfego também oculta os headers `authorization`, `x-api-key` e `cookie`.
|
||||
- **Log de requisições, não trilha de auditoria.** O Winston grava logs de API, tráfego e app em arquivos rotativos (log de API: 30 dias, 50 MB por arquivo). São logs operacionais, não uma trilha de auditoria à prova de adulteração; os arquivos `*-audit.json` são o controle de rotação do `winston-daily-rotate-file`.
|
||||
- **Acesso ao proxy.** O proxy vem desligado. Quando ativado, escuta em `0.0.0.0`, e as requisições só são autenticadas quando `api_key` não está vazia (vazia significa modo aberto). Defina uma chave e mantenha-a privada.
|
||||
- **Inspeção TLS (só para debug).** [`docs/proxyman-install.md`](docs/proxyman-install.md) e [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md) explicam como ler o tráfego HTTPS do app com o Proxyman: confiar na CA raiz dele, definir as variáveis de proxy e `NODE_EXTRA_CA_CERTS` e então iniciar o app. `NODE_TLS_REJECT_UNAUTHORIZED=0` (e a flag `-AllowInsecureTls` do script) é um ajuste temporário; nunca deixe ligado. Não faça commit de endereços de proxy, caminhos de certificado, cookies ou códigos OAuth, e oculte dados dos logs antes de compartilhá-los. `scripts/start-antigravity-with-proxyman.ps1` mira o cliente oficial do Antigravity instalado, não este app.
|
||||
- **Envio de erros.** Os relatórios do Sentry (precisam de `SENTRY_DSN`) dependem da configuração `error_reporting_enabled`, que o `DEFAULT_APP_CONFIG` traz como `true`; desative em Settings para não enviar. O trecho com o nome de usuário do Windows é mascarado nas mensagens de exceção enviadas.
|
||||
|
||||
## 💻 Desenvolvimento
|
||||
Versões suportadas e como reportar uma vulnerabilidade: [`SECURITY.md`](SECURITY.md).
|
||||
|
||||
```bash
|
||||
# Iniciar ambiente de dev (Electron + Vite HMR)
|
||||
npm start
|
||||
## 💻 Documentação e desenvolvimento
|
||||
|
||||
# Executar linting
|
||||
npm run lint
|
||||
- [`docs/cloud_features.md`](docs/cloud_features.md): design do pool de contas, do monitoramento de cota e da troca automática.
|
||||
- [`docs/proxyman-install.md`](docs/proxyman-install.md) e [`docs/proxyman-debugging.md`](docs/proxyman-debugging.md): configuração da inspeção TLS (Windows).
|
||||
- [`docs/OpencodeAPI.md`](docs/OpencodeAPI.md): integração com endpoint customizado do OpenCode (em português).
|
||||
- [`cli/README.md`](cli/README.md): a ferramenta de linha de comando em Python.
|
||||
- [`CONTRIBUTING.md`](CONTRIBUTING.md), [`SECURITY.md`](SECURITY.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), [`CHANGELOG.md`](CHANGELOG.md), [`LICENSE`](LICENSE), [`LICENSE-MIT`](LICENSE-MIT).
|
||||
- Traduções: [English](README.md), [中文](README.zh-CN.md), [Español](README.es.md).
|
||||
|
||||
# Verificar tipos
|
||||
npm run type-check
|
||||
### Estrutura
|
||||
|
||||
# Formatar código
|
||||
npm run format:write
|
||||
|
||||
# Rodar testes
|
||||
npm test
|
||||
```
|
||||
|
||||
### Estrutura do Projeto
|
||||
|
||||
```plaintext
|
||||
```text
|
||||
src/
|
||||
├── actions/ # Ações do app e orquestração de fluxos
|
||||
├── components/ # Componentes React
|
||||
│ ├── proxy/ # Componentes da página Proxy (abas avançadas)
|
||||
│ ├── usage/ # Componentes de analytics de uso (StatCard, ChartCard)
|
||||
│ └── ui/ # Primitivos base de UI (baseados no Radix)
|
||||
├── hooks/ # Custom React hooks
|
||||
├── ipc/ # Electron IPC + handlers de banco de dados
|
||||
├── layouts/ # Componentes de layout (MainLayout + sidebar)
|
||||
├── localization/ # Recursos de tradução i18n
|
||||
├── routes/ # Páginas TanStack Router (index, usage, proxy, settings)
|
||||
├── server/ # Backend NestJS (serviço de gateway proxy)
|
||||
├── services/ # Camada de serviços
|
||||
├── types/ # Definições de tipos TypeScript + schemas Zod
|
||||
└── utils/ # Funções utilitárias
|
||||
├── components/ # UI (proxy/, usage/, primitivos ui/)
|
||||
├── ipc/ # routers oRPC (account, cloud, config, gateway, usage...)
|
||||
├── server/ # gateway proxy NestJS (módulos: proxy, usage)
|
||||
├── services/ # AutoSwitchService, CloudMonitorService, GoogleAPIService
|
||||
├── routes/ # index, usage, proxy, settings
|
||||
├── utils/ # paths, logger, sensitiveDataMasking
|
||||
└── tests/ # testes unitários (Vitest) e E2E (Playwright)
|
||||
cli/ # CLI Python separada para trocar de conta e consultar cota
|
||||
docs/ # notas de design e guias do Proxyman
|
||||
scripts/ # setup-dev, build-windows, generate-assets
|
||||
```
|
||||
|
||||
---
|
||||
### Scripts
|
||||
|
||||
| Comando | O que faz |
|
||||
|---|---|
|
||||
| `pnpm start` | Roda o app em modo dev (`electron-forge start`, com `DEBUG=electron-forge:*`). |
|
||||
| `pnpm run dev` | O mesmo que `start`. |
|
||||
| `pnpm run package` | Empacota o app com o Electron Forge, sem gerar instaladores. |
|
||||
| `pnpm run make` | Gera instaladores/pacotes para a plataforma atual. |
|
||||
| `pnpm run make:win` | Helper de build no Windows: extrai o WiX de `wix314-binaries.zip`, coloca no `PATH` e roda `electron-forge make`. |
|
||||
| `pnpm run publish` | Publica pelo Electron Forge. |
|
||||
| `pnpm run setup` | Roda `scripts/setup-dev.js`: detecta a toolchain nativa e instala ou orienta a configuração. |
|
||||
| `pnpm run postinstall` | `scripts/setup-dev.js --check-only`; roda sozinho depois do `pnpm install`. |
|
||||
| `pnpm run lint` | ESLint no repositório. |
|
||||
| `pnpm run format` | Checagem do Prettier. |
|
||||
| `pnpm run format:write` | Prettier com escrita. |
|
||||
| `pnpm test` | Testes unitários Vitest (`vitest run`). |
|
||||
| `pnpm run test:watch` | Vitest em modo watch. |
|
||||
| `pnpm run test:unit` | Vitest (modo padrão). |
|
||||
| `pnpm run test:e2e` | Testes E2E com Playwright. |
|
||||
| `pnpm run test:all` | Testes unitários e depois Playwright. |
|
||||
| `pnpm run type-check` | `tsc --noEmit`. |
|
||||
|
||||
## ❓ FAQ
|
||||
|
||||
<details>
|
||||
<summary><b>P: Aviso do Windows SmartScreen ("O Windows protegeu o seu computador") durante a instalação?</b></summary>
|
||||
<summary><b>O Windows mostra "O Windows protegeu o seu computador". É normal?</b></summary>
|
||||
|
||||
Sim. Os builds não são assinados. Clique em **Mais informações → Executar mesmo assim**.
|
||||
|
||||
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>
|
||||
<summary><b>Minha IDE não alcança o proxy.</b></summary>
|
||||
|
||||
O proxy vem desligado: ative-o na página Proxy. A porta padrão é `8045` (`8046` em builds de desenvolvimento) e pode ser trocada ali. Copie a API key da mesma página e confira se há pelo menos uma conta no pool.
|
||||
|
||||
1. Certifique-se de que todas as dependências estão instaladas: `npm install`.
|
||||
2. Verifique se a versão do Node.js é >= 20.
|
||||
3. Tente deletar `node_modules` e reinstalar.
|
||||
4. No Windows, certifique-se de que o WiX Toolset está disponível para o comando `npm run make`.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>P: O login da conta falhou?</b></summary>
|
||||
<summary><b>Preciso de uma API key?</b></summary>
|
||||
|
||||
Com `api_key` vazia o proxy roda em modo aberto. Quando ativado ele escuta em `0.0.0.0`, então defina uma chave e mantenha-a privada.
|
||||
|
||||
1. Verifique se a conexão com a internet está funcionando.
|
||||
2. Tente limpar os dados do app e fazer login novamente.
|
||||
3. Verifique se a conta está restrita pelo Google/Claude.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>P: A IDE não consegue conectar ao proxy?</b></summary>
|
||||
<summary><b>Dá para usar modelos Claude?</b></summary>
|
||||
|
||||
Sim, por mapeamento de modelos nas contas Google do pool, não por contas Claude separadas.
|
||||
|
||||
1. Certifique-se de que o proxy está rodando (indicador verde na barra de status).
|
||||
2. Verifique se a porta corresponde à configuração da sua IDE (padrão: `10100`).
|
||||
3. Copie a API key da página Proxy e cole nas configurações da sua IDE.
|
||||
4. Verifique se pelo menos uma conta está ativa na página de Contas.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>P: A contagem de tokens mostra zero?</b></summary>
|
||||
<summary><b>Onde ficam meus tokens?</b></summary>
|
||||
|
||||
Num `cloud_accounts.db` separado, com `token_json` e `quota_json` criptografados em AES-256-GCM. A chave mestra fica no cofre de credenciais do sistema via `keytar`. Detalhes em [Modelo de segurança](#modelo-de-segurança).
|
||||
|
||||
1. Este era um bug conhecido em versões anteriores — por favor, atualize para a versão mais recente.
|
||||
2. O rastreamento de tokens agora lida corretamente com metadados de streaming e contagens estimadas.
|
||||
3. Os dados de uso são atualizados a cada 15 segundos na página de Analytics de Uso.
|
||||
</details>
|
||||
|
||||
---
|
||||
<details>
|
||||
<summary><b>Posso usar comercialmente?</b></summary>
|
||||
|
||||
Veja a [Licença](#-licença) antes: o código herdado do AntigravityManager é CC BY-NC-SA 4.0 (não comercial) e o código novo é MIT.
|
||||
|
||||
</details>
|
||||
|
||||
## Limitações e próximos passos
|
||||
|
||||
- O acesso upstream passa pelos endpoints `v1internal` do Cloud Code do Google e por escopos OAuth ([`src/services/GoogleAPIService.ts`](src/services/GoogleAPIService.ts)). São APIs internas, sem documentação, que podem mudar sem aviso. O projeto é não oficial e não tem vínculo com o Google nem com a Anthropic.
|
||||
- As contas entram via Google OAuth; os modelos Claude são acessados por mapeamento de modelos, não por contas Claude separadas.
|
||||
- Os testes end-to-end não rodam no CI (o Electron precisa de ambiente gráfico); rode `pnpm run test:e2e` localmente.
|
||||
- O MSI do Windows só é gerado quando o WiX Toolset está disponível na máquina de build; caso contrário o artefato do Windows é o ZIP.
|
||||
- Os workflows em `.github/workflows/` foram escritos para o GitHub (chamam o CLI `gh` e o publisher de releases do GitHub), por isso este README não mostra badge de CI.
|
||||
- Próximo passo declarado pelo projeto: migrar o código original restante para MIT (veja a [Licença](#-licença)).
|
||||
|
||||
## 🤝 Contribuindo
|
||||
|
||||
Contribuições são bem-vindas! Leia o `CONTRIBUTING.md` para mais detalhes.
|
||||
Leia o [`CONTRIBUTING.md`](CONTRIBUTING.md) e o [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). As versões são geradas pelo semantic-release a partir de Conventional Commits. Antes de abrir um PR, isto precisa passar:
|
||||
|
||||
---
|
||||
```bash
|
||||
pnpm run lint && pnpm run format:write && pnpm run type-check && pnpm test
|
||||
```
|
||||
|
||||
## 📄 Licença
|
||||
|
||||
Este projeto utiliza uma estrutura de licença dual:
|
||||
|
||||
- **Código original** do [AntigravityManager](https://github.com/Draculabo/AntigravityManager) por [Draculabo](https://github.com/Draculabo): Licenciado sob [CC BY-NC-SA 4.0](LICENSE).
|
||||
- **Todo o código novo, funcionalidades e arquitetura** por [evandrodevbr](https://github.com/evandrodevbr): Licenciado sob a [Licença MIT](LICENSE-MIT).
|
||||
|
||||
> 🔄 **Aviso de Migração:** Este projeto está sendo ativamente migrado para uma licença totalmente open-source (MIT). À medida que o código original restante é progressivamente reescrito, todo o projeto será transicionado para MIT. Estamos comprometidos em tornar o Gemini Nexus 100% open-source.
|
||||
Licença mista: o código herdado do [AntigravityManager](https://github.com/Draculabo/AntigravityManager) (de Draculabo) é [CC BY-NC-SA 4.0](LICENSE) (não comercial, compartilhamento pela mesma licença); todo o código novo é [MIT](LICENSE-MIT). O projeto está migrando para MIT à medida que o código original restante é reescrito, então confira os dois arquivos antes de qualquer uso comercial.
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Créditos
|
||||
<div align="center">
|
||||
|
||||
Este projeto foi originalmente um fork de [AntigravityManager](https://github.com/Draculabo/AntigravityManager) criado por [Draculabo](https://github.com/Draculabo). O conceito inicial de proxy e a estrutura base do Electron foram baseados em seu trabalho.
|
||||
<img src="docs/assets/logo.png" width="56" alt="Logo do Gemini Nexus">
|
||||
|
||||
Desde o fork, **a grande maioria do código base foi reescrita, redesenhada e expandida** por [evandrodevbr](https://github.com/evandrodevbr), incluindo mas não se limitando a:
|
||||
<p><strong><a href="https://git.evandro.dev.br/evandro/gemini-nexus">Gemini Nexus no Gitea</a></strong> · <a href="https://git.evandro.dev.br/evandro/gemini-nexus/issues">Reportar um problema</a> · <a href="#-início-rápido">Início rápido</a></p>
|
||||
|
||||
- Redesign completo de UI/UX (navegação, contas, analytics de uso, gerenciamento de proxy)
|
||||
- Dashboard de Analytics de Uso com rastreamento de custos, médias de tokens e integração com OpenRouter
|
||||
- Monitor de tráfego com inspeção de tokens/custos por requisição
|
||||
- Isolamento de ambiente (dev/prod), pipeline CI/CD e infraestrutura de testes
|
||||
- Configuração Rápida para IDEs (OpenCode, Cursor, VS Code, Claude Code)
|
||||
- Configuração personalizada de preços de modelos
|
||||
- Toda a documentação e internacionalização (EN, PT-BR, ES, ZH-CN)
|
||||
</div>
|
||||
Reference in new issue
Block a user