style(design): apply Minimal Dark Mode design system\n\n- Switched to complete Dark Mode (OLED-friendly)\n- Established standard color palette matching modern technical aesthetics\n- Changed font to Plus Jakarta Sans for increased legibility\n- Enforced dark mode as default in App.tsx\n- Fixed several React cascading render (setState in useEffect) warnings
This commit is contained in:
Gemini Nexus Bot committed
1 parent
b80531f8a8
commit
bac7b5591e
738 files changed
+138513
-138123
No files matched your search
+276
-276
@@ -1,276 +1,276 @@
|
||||
**✅ Documento Completo: Integração com Custom Endpoint do OpenCode (Provedores Custom / OpenAI-Compatible)**
|
||||
|
||||
OpenCode (https://opencode.ai) é um agente de IA para terminal que usa o **Vercel AI SDK** para se comunicar com provedores de LLM. Ele suporta nativamente provedores customizados via o pacote `@ai-sdk/openai-compatible`, que segue o padrão **OpenAI Chat Completions API** (`/v1/chat/completions`).
|
||||
|
||||
Isso significa que **sua API precisa implementar exatamente o formato OpenAI-compatible** para que o OpenCode consiga conversar com ela diretamente.
|
||||
|
||||
---
|
||||
|
||||
### 1. Como Configurar um Provedor Custom no OpenCode
|
||||
|
||||
Crie ou edite o arquivo de configuração (recomendado: `~/.config/opencode/opencode.json` ou `opencode.json` na raiz do projeto):
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"minha-ia-custom": {
|
||||
"npm": "@ai-sdk/openai-compatible",
|
||||
"name": "Minha IA Custom (OpenCode)",
|
||||
"options": {
|
||||
"baseURL": "https://sua-api.com/v1",
|
||||
"apiKey": "sk-sua-chave-aqui-ou-{env:MINHA_API_KEY}",
|
||||
"headers": {
|
||||
"X-Custom-Header": "valor-opcional"
|
||||
}
|
||||
},
|
||||
"models": {
|
||||
"meu-modelo-principal": {
|
||||
"name": "Meu Modelo Principal",
|
||||
"limit": {
|
||||
"context": 128000,
|
||||
"output": 8192
|
||||
}
|
||||
},
|
||||
"meu-modelo-rapido": {
|
||||
"name": "Modelo Rápido",
|
||||
"limit": {
|
||||
"context": 32000,
|
||||
"output": 4096
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"model": "minha-ia-custom/meu-modelo-principal"
|
||||
}
|
||||
```
|
||||
|
||||
**Campos importantes:**
|
||||
|
||||
- `npm`: Sempre use `"@ai-sdk/openai-compatible"` para APIs que expõem `/v1/chat/completions`.
|
||||
- `baseURL`: URL base da sua API (deve terminar com `/v1`).
|
||||
- `apiKey`: Pode ser valor direto ou `{env:NOME_VARIAVEL}`.
|
||||
- `models`: Defina os modelos que sua API expõe. O `limit` ajuda o OpenCode a gerenciar contexto.
|
||||
- `model`: Define o modelo padrão no formato `provider_id/model_id`.
|
||||
|
||||
Depois de salvar, reinicie o OpenCode ou use `/models` para selecionar.
|
||||
|
||||
**Comando rápido para adicionar chave:**
|
||||
|
||||
```bash
|
||||
opencode /connect
|
||||
# Escolha "Other" → digite o provider_id (ex: minha-ia-custom) → cole a API key
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Como o OpenCode Envia Requisições
|
||||
|
||||
O OpenCode (via AI SDK) faz chamadas **POST** para:
|
||||
|
||||
```
|
||||
POST {baseURL}/chat/completions
|
||||
```
|
||||
|
||||
**Headers enviados:**
|
||||
|
||||
- `Authorization: Bearer <sua-api-key>`
|
||||
- `Content-Type: application/json`
|
||||
- Headers customizados que você definir em `options.headers`
|
||||
|
||||
**Payload típico (exemplo real):**
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "meu-modelo-principal",
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
"content": "Você é um assistente de código experiente..."
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Crie uma função em Python que..."
|
||||
}
|
||||
],
|
||||
"stream": true,
|
||||
"temperature": 0.7,
|
||||
"max_tokens": 8192,
|
||||
"tools": [
|
||||
/* array de tools se o agente estiver usando ferramentas */
|
||||
],
|
||||
"tool_choice": "auto"
|
||||
}
|
||||
```
|
||||
|
||||
**Parâmetros comuns que o OpenCode envia:**
|
||||
|
||||
- `messages` (array completo do histórico)
|
||||
- `stream: true` (quase sempre, para UX em tempo real)
|
||||
- `temperature`, `max_tokens`, `top_p`
|
||||
- `tools` + `tool_choice` (quando usa agentes com ferramentas/MCP)
|
||||
- `response_format` (às vezes)
|
||||
- `providerOptions` (opções específicas do provedor – raras no openai-compatible)
|
||||
|
||||
---
|
||||
|
||||
### 3. Como o OpenCode Recebe e Processa Respostas
|
||||
|
||||
#### A. Streaming (recomendado – usado na maioria das interações)
|
||||
|
||||
Sua API deve responder com `Content-Type: text/event-stream` e eventos SSE:
|
||||
|
||||
```
|
||||
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1712345678,"model":"meu-modelo-principal","choices":[{"index":0,"delta":{"content":"Olá"},"finish_reason":null}]}
|
||||
|
||||
data: {"id":"chatcmpl-123","choices":[{"index":0,"delta":{"content":"! Como"},"finish_reason":null}]}
|
||||
|
||||
data: [DONE]
|
||||
```
|
||||
|
||||
O OpenCode processa cada chunk em tempo real.
|
||||
|
||||
#### B. Resposta não-streaming (completa)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "chatcmpl-123",
|
||||
"object": "chat.completion",
|
||||
"created": 1712345678,
|
||||
"model": "meu-modelo-principal",
|
||||
"choices": [
|
||||
{
|
||||
"index": 0,
|
||||
"message": {
|
||||
"role": "assistant",
|
||||
"content": "Resposta completa aqui..."
|
||||
},
|
||||
"finish_reason": "stop"
|
||||
}
|
||||
],
|
||||
"usage": {
|
||||
"prompt_tokens": 150,
|
||||
"completion_tokens": 320,
|
||||
"total_tokens": 470
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Suporte a Tool Calling (essencial para agentes)
|
||||
|
||||
Se sua API suportar `tools`, o OpenCode pode:
|
||||
|
||||
1. Enviar `tools` na requisição.
|
||||
2. Receber `tool_calls` na resposta.
|
||||
3. Executar a ferramenta (via MCP ou built-in).
|
||||
4. Enviar o resultado de volta como mensagem `tool`.
|
||||
|
||||
**Exemplo de resposta com tool call:**
|
||||
|
||||
```json
|
||||
{
|
||||
"choices": [
|
||||
{
|
||||
"message": {
|
||||
"role": "assistant",
|
||||
"tool_calls": [
|
||||
{
|
||||
"id": "call_123",
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "read_file",
|
||||
"arguments": "{\"path\": \"src/app.ts\"}"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Como é Exibido no Chat do OpenCode (TUI)
|
||||
|
||||
- **Streaming**: Texto aparece caractere por caractere com efeito de digitação.
|
||||
- **Markdown**: Suporte completo a código (syntax highlight), listas, tabelas, etc.
|
||||
- **Tool Calls**: Mostra “Executando ferramenta: read_file...” + resultado.
|
||||
- **Multi-turn**: Mantém histórico completo na conversa.
|
||||
- **Erros**: Mostra mensagens de erro claras no terminal.
|
||||
- **Contexto**: Respeita os limites de `context` e `output` que você definiu no config.
|
||||
|
||||
O OpenCode usa o TUI (Terminal User Interface) baseado em React/Ink para renderizar tudo de forma bonita.
|
||||
|
||||
---
|
||||
|
||||
### 5. Requisitos Mínimos da Sua API para Funcionar Perfeitamente
|
||||
|
||||
| Recurso | Obrigatório? | Recomendado? | Observação |
|
||||
| ---------------------- | ------------ | ------------ | ---------------------------------- |
|
||||
| `/v1/chat/completions` | Sim | - | Endpoint principal |
|
||||
| Streaming (SSE) | Sim | - | Essencial para UX |
|
||||
| Tool Calling | Não | Sim | Para agentes completos |
|
||||
| System messages | Sim | - | - |
|
||||
| Multi-turn history | Sim | - | - |
|
||||
| Usage stats | Não | Sim | Mostra tokens gastos |
|
||||
| Error handling | Sim | - | Retorne JSON de erro padrão OpenAI |
|
||||
|
||||
**Endpoint exato esperado:**
|
||||
`POST https://sua-api.com/v1/chat/completions`
|
||||
|
||||
---
|
||||
|
||||
### 6. Exemplo Completo de Configuração + Teste
|
||||
|
||||
1. Configure o `opencode.json` como acima.
|
||||
2. Rode:
|
||||
```bash
|
||||
opencode
|
||||
```
|
||||
3. Digite algo ou use `/models` para selecionar seu provedor.
|
||||
4. Teste com:
|
||||
```bash
|
||||
curl -X POST https://sua-api.com/v1/chat/completions \
|
||||
-H "Authorization: Bearer sk-..." \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model":"meu-modelo-principal","messages":[{"role":"user","content":"Olá"}],"stream":true}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. Troubleshooting Comum
|
||||
|
||||
- **“Route not found” ou requests indo para lugar errado** → Verifique se `baseURL` termina com `/v1` e não com `/v1/chat/completions`.
|
||||
- **Custom provider não aparece** → Certifique-se que o ID do provider no `/connect` bate com a chave no `opencode.json`.
|
||||
- **Sem streaming / resposta lenta** → Implemente SSE corretamente.
|
||||
- **Tool calls não funcionam** → Sua API precisa retornar `tool_calls` no formato OpenAI exato.
|
||||
- **Erro de autenticação** → Use `apiKey` ou `headers` corretamente.
|
||||
|
||||
---
|
||||
|
||||
### Referências Oficiais
|
||||
|
||||
- **Docs Principais**: https://opencode.ai/docs/providers/
|
||||
- **Models**: https://opencode.ai/docs/models/
|
||||
- **Config**: https://opencode.ai/docs/config/
|
||||
- **Schema de Config**: https://opencode.ai/config.json
|
||||
- **GitHub**: https://github.com/anomalyco/opencode
|
||||
- **AI SDK OpenAI-Compatible**: https://ai-sdk.dev/providers/openai-compatible-providers
|
||||
|
||||
---
|
||||
|
||||
**Resumo Final para Você (que está construindo a API):**
|
||||
|
||||
Sua API **precisa ser 100% compatível** com o endpoint OpenAI `/v1/chat/completions` (streaming + tool calling recomendado).
|
||||
O OpenCode vai:
|
||||
|
||||
1. Configurar via `opencode.json` (baseURL + apiKey)
|
||||
2. Enviar requisições padrão OpenAI
|
||||
3. Receber streaming ou resposta completa
|
||||
4. Renderizar tudo lindamente no TUI com suporte a ferramentas
|
||||
|
||||
Se você implementar exatamente o padrão OpenAI Chat Completions, vai funcionar perfeitamente com o OpenCode.
|
||||
|
||||
Quer que eu monte um **exemplo de servidor mínimo** (em Node.js/Fastify ou Python/FastAPI) que já funcione com o OpenCode? Posso criar um template completo para você.
|
||||
**✅ Documento Completo: Integração com Custom Endpoint do OpenCode (Provedores Custom / OpenAI-Compatible)**
|
||||
|
||||
OpenCode (https://opencode.ai) é um agente de IA para terminal que usa o **Vercel AI SDK** para se comunicar com provedores de LLM. Ele suporta nativamente provedores customizados via o pacote `@ai-sdk/openai-compatible`, que segue o padrão **OpenAI Chat Completions API** (`/v1/chat/completions`).
|
||||
|
||||
Isso significa que **sua API precisa implementar exatamente o formato OpenAI-compatible** para que o OpenCode consiga conversar com ela diretamente.
|
||||
|
||||
---
|
||||
|
||||
### 1. Como Configurar um Provedor Custom no OpenCode
|
||||
|
||||
Crie ou edite o arquivo de configuração (recomendado: `~/.config/opencode/opencode.json` ou `opencode.json` na raiz do projeto):
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"minha-ia-custom": {
|
||||
"npm": "@ai-sdk/openai-compatible",
|
||||
"name": "Minha IA Custom (OpenCode)",
|
||||
"options": {
|
||||
"baseURL": "https://sua-api.com/v1",
|
||||
"apiKey": "sk-sua-chave-aqui-ou-{env:MINHA_API_KEY}",
|
||||
"headers": {
|
||||
"X-Custom-Header": "valor-opcional"
|
||||
}
|
||||
},
|
||||
"models": {
|
||||
"meu-modelo-principal": {
|
||||
"name": "Meu Modelo Principal",
|
||||
"limit": {
|
||||
"context": 128000,
|
||||
"output": 8192
|
||||
}
|
||||
},
|
||||
"meu-modelo-rapido": {
|
||||
"name": "Modelo Rápido",
|
||||
"limit": {
|
||||
"context": 32000,
|
||||
"output": 4096
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"model": "minha-ia-custom/meu-modelo-principal"
|
||||
}
|
||||
```
|
||||
|
||||
**Campos importantes:**
|
||||
|
||||
- `npm`: Sempre use `"@ai-sdk/openai-compatible"` para APIs que expõem `/v1/chat/completions`.
|
||||
- `baseURL`: URL base da sua API (deve terminar com `/v1`).
|
||||
- `apiKey`: Pode ser valor direto ou `{env:NOME_VARIAVEL}`.
|
||||
- `models`: Defina os modelos que sua API expõe. O `limit` ajuda o OpenCode a gerenciar contexto.
|
||||
- `model`: Define o modelo padrão no formato `provider_id/model_id`.
|
||||
|
||||
Depois de salvar, reinicie o OpenCode ou use `/models` para selecionar.
|
||||
|
||||
**Comando rápido para adicionar chave:**
|
||||
|
||||
```bash
|
||||
opencode /connect
|
||||
# Escolha "Other" → digite o provider_id (ex: minha-ia-custom) → cole a API key
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Como o OpenCode Envia Requisições
|
||||
|
||||
O OpenCode (via AI SDK) faz chamadas **POST** para:
|
||||
|
||||
```
|
||||
POST {baseURL}/chat/completions
|
||||
```
|
||||
|
||||
**Headers enviados:**
|
||||
|
||||
- `Authorization: Bearer <sua-api-key>`
|
||||
- `Content-Type: application/json`
|
||||
- Headers customizados que você definir em `options.headers`
|
||||
|
||||
**Payload típico (exemplo real):**
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "meu-modelo-principal",
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
"content": "Você é um assistente de código experiente..."
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Crie uma função em Python que..."
|
||||
}
|
||||
],
|
||||
"stream": true,
|
||||
"temperature": 0.7,
|
||||
"max_tokens": 8192,
|
||||
"tools": [
|
||||
/* array de tools se o agente estiver usando ferramentas */
|
||||
],
|
||||
"tool_choice": "auto"
|
||||
}
|
||||
```
|
||||
|
||||
**Parâmetros comuns que o OpenCode envia:**
|
||||
|
||||
- `messages` (array completo do histórico)
|
||||
- `stream: true` (quase sempre, para UX em tempo real)
|
||||
- `temperature`, `max_tokens`, `top_p`
|
||||
- `tools` + `tool_choice` (quando usa agentes com ferramentas/MCP)
|
||||
- `response_format` (às vezes)
|
||||
- `providerOptions` (opções específicas do provedor – raras no openai-compatible)
|
||||
|
||||
---
|
||||
|
||||
### 3. Como o OpenCode Recebe e Processa Respostas
|
||||
|
||||
#### A. Streaming (recomendado – usado na maioria das interações)
|
||||
|
||||
Sua API deve responder com `Content-Type: text/event-stream` e eventos SSE:
|
||||
|
||||
```
|
||||
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1712345678,"model":"meu-modelo-principal","choices":[{"index":0,"delta":{"content":"Olá"},"finish_reason":null}]}
|
||||
|
||||
data: {"id":"chatcmpl-123","choices":[{"index":0,"delta":{"content":"! Como"},"finish_reason":null}]}
|
||||
|
||||
data: [DONE]
|
||||
```
|
||||
|
||||
O OpenCode processa cada chunk em tempo real.
|
||||
|
||||
#### B. Resposta não-streaming (completa)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "chatcmpl-123",
|
||||
"object": "chat.completion",
|
||||
"created": 1712345678,
|
||||
"model": "meu-modelo-principal",
|
||||
"choices": [
|
||||
{
|
||||
"index": 0,
|
||||
"message": {
|
||||
"role": "assistant",
|
||||
"content": "Resposta completa aqui..."
|
||||
},
|
||||
"finish_reason": "stop"
|
||||
}
|
||||
],
|
||||
"usage": {
|
||||
"prompt_tokens": 150,
|
||||
"completion_tokens": 320,
|
||||
"total_tokens": 470
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Suporte a Tool Calling (essencial para agentes)
|
||||
|
||||
Se sua API suportar `tools`, o OpenCode pode:
|
||||
|
||||
1. Enviar `tools` na requisição.
|
||||
2. Receber `tool_calls` na resposta.
|
||||
3. Executar a ferramenta (via MCP ou built-in).
|
||||
4. Enviar o resultado de volta como mensagem `tool`.
|
||||
|
||||
**Exemplo de resposta com tool call:**
|
||||
|
||||
```json
|
||||
{
|
||||
"choices": [
|
||||
{
|
||||
"message": {
|
||||
"role": "assistant",
|
||||
"tool_calls": [
|
||||
{
|
||||
"id": "call_123",
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "read_file",
|
||||
"arguments": "{\"path\": \"src/app.ts\"}"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Como é Exibido no Chat do OpenCode (TUI)
|
||||
|
||||
- **Streaming**: Texto aparece caractere por caractere com efeito de digitação.
|
||||
- **Markdown**: Suporte completo a código (syntax highlight), listas, tabelas, etc.
|
||||
- **Tool Calls**: Mostra “Executando ferramenta: read_file...” + resultado.
|
||||
- **Multi-turn**: Mantém histórico completo na conversa.
|
||||
- **Erros**: Mostra mensagens de erro claras no terminal.
|
||||
- **Contexto**: Respeita os limites de `context` e `output` que você definiu no config.
|
||||
|
||||
O OpenCode usa o TUI (Terminal User Interface) baseado em React/Ink para renderizar tudo de forma bonita.
|
||||
|
||||
---
|
||||
|
||||
### 5. Requisitos Mínimos da Sua API para Funcionar Perfeitamente
|
||||
|
||||
| Recurso | Obrigatório? | Recomendado? | Observação |
|
||||
| ---------------------- | ------------ | ------------ | ---------------------------------- |
|
||||
| `/v1/chat/completions` | Sim | - | Endpoint principal |
|
||||
| Streaming (SSE) | Sim | - | Essencial para UX |
|
||||
| Tool Calling | Não | Sim | Para agentes completos |
|
||||
| System messages | Sim | - | - |
|
||||
| Multi-turn history | Sim | - | - |
|
||||
| Usage stats | Não | Sim | Mostra tokens gastos |
|
||||
| Error handling | Sim | - | Retorne JSON de erro padrão OpenAI |
|
||||
|
||||
**Endpoint exato esperado:**
|
||||
`POST https://sua-api.com/v1/chat/completions`
|
||||
|
||||
---
|
||||
|
||||
### 6. Exemplo Completo de Configuração + Teste
|
||||
|
||||
1. Configure o `opencode.json` como acima.
|
||||
2. Rode:
|
||||
```bash
|
||||
opencode
|
||||
```
|
||||
3. Digite algo ou use `/models` para selecionar seu provedor.
|
||||
4. Teste com:
|
||||
```bash
|
||||
curl -X POST https://sua-api.com/v1/chat/completions \
|
||||
-H "Authorization: Bearer sk-..." \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model":"meu-modelo-principal","messages":[{"role":"user","content":"Olá"}],"stream":true}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. Troubleshooting Comum
|
||||
|
||||
- **“Route not found” ou requests indo para lugar errado** → Verifique se `baseURL` termina com `/v1` e não com `/v1/chat/completions`.
|
||||
- **Custom provider não aparece** → Certifique-se que o ID do provider no `/connect` bate com a chave no `opencode.json`.
|
||||
- **Sem streaming / resposta lenta** → Implemente SSE corretamente.
|
||||
- **Tool calls não funcionam** → Sua API precisa retornar `tool_calls` no formato OpenAI exato.
|
||||
- **Erro de autenticação** → Use `apiKey` ou `headers` corretamente.
|
||||
|
||||
---
|
||||
|
||||
### Referências Oficiais
|
||||
|
||||
- **Docs Principais**: https://opencode.ai/docs/providers/
|
||||
- **Models**: https://opencode.ai/docs/models/
|
||||
- **Config**: https://opencode.ai/docs/config/
|
||||
- **Schema de Config**: https://opencode.ai/config.json
|
||||
- **GitHub**: https://github.com/anomalyco/opencode
|
||||
- **AI SDK OpenAI-Compatible**: https://ai-sdk.dev/providers/openai-compatible-providers
|
||||
|
||||
---
|
||||
|
||||
**Resumo Final para Você (que está construindo a API):**
|
||||
|
||||
Sua API **precisa ser 100% compatível** com o endpoint OpenAI `/v1/chat/completions` (streaming + tool calling recomendado).
|
||||
O OpenCode vai:
|
||||
|
||||
1. Configurar via `opencode.json` (baseURL + apiKey)
|
||||
2. Enviar requisições padrão OpenAI
|
||||
3. Receber streaming ou resposta completa
|
||||
4. Renderizar tudo lindamente no TUI com suporte a ferramentas
|
||||
|
||||
Se você implementar exatamente o padrão OpenAI Chat Completions, vai funcionar perfeitamente com o OpenCode.
|
||||
|
||||
Quer que eu monte um **exemplo de servidor mínimo** (em Node.js/Fastify ou Python/FastAPI) que já funcione com o OpenCode? Posso criar um template completo para você.
|
||||
+146
-146
@@ -1,146 +1,146 @@
|
||||
# Brand Briefing — Gemini Nexus
|
||||
|
||||
## 1. Nome e Descrição
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Nome** | Gemini Nexus |
|
||||
| **Product Name** | Gemini Nexus |
|
||||
| **Package Name** | gemini-nexus |
|
||||
| **Versão** | 0.11.1 |
|
||||
| **Descrição EN** | Professional multi-account manager for Google Gemini & Claude AI |
|
||||
| **Descrição PT-BR** | Gerenciador multi-contas profissional para Google Gemini & Claude AI |
|
||||
| **Autor** | evandrodevbr / Draculabo |
|
||||
| **Licença** | CC-BY-NC-SA-4.0 (apenas fins educacionais) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Propósito do Aplicativo
|
||||
|
||||
Gemini Nexus é um **aplicativo desktop profissional** (Electron) que funciona como um **hub central (nexus)** para desenvolvedores que usam IDEs com IA.
|
||||
|
||||
### Funcionalidades Principais
|
||||
- **Pool ilimitado de contas**: Adicionar múltiplas contas Google Gemini / Claude via OAuth
|
||||
- **Auto-switching inteligente**: Troca automática de conta quando a cota acaba ou há rate limit
|
||||
- **Monitoramento em tempo real**: Barras de progresso coloridas para visualizar uso de quota
|
||||
- **Proxy API local**: Servidor proxy integrado compatível OpenAI/Anthropic (porta 8045)
|
||||
- **Segurança**: Criptografia AES-256-GCM para dados sensíveis
|
||||
|
||||
### Público-Alvo
|
||||
- Desenvolvedores que usam IDEs com integração AI (Cursor, Windsurf, VS Code, Claude Code, etc.)
|
||||
- Power users que precisam alternar entre múltiplas contas de IA
|
||||
- Usuários que precisam de um proxy API local confiável
|
||||
|
||||
---
|
||||
|
||||
## 3. Tom de Voz / Personalidade
|
||||
|
||||
- **Profissional e técnica**: Termos como "Nexus", "Proxy", "Gateway", "Quota", "Circuit Breaker"
|
||||
- **Confiável e estável**: Monitoramento, health checks, logging robusto
|
||||
- **Developer-first**: Suporte a múltiplas IDEs, geração de cURL/Python
|
||||
- **Moderna e minimalista**: Interface limpa, componentes modulares
|
||||
- **Global**: Suporte a i18n (EN, PT-BR, ZH, RU, VI)
|
||||
|
||||
---
|
||||
|
||||
## 4. Estilo Visual Atual
|
||||
|
||||
### Tema
|
||||
- Dual theme (claro/escuro) com detecção automática do sistema
|
||||
- Extremamente minimalista e quase monocromático
|
||||
|
||||
### Paleta de Cores (Tailwind OKLCH)
|
||||
|
||||
| Modo | Background | Foreground | Primary | Destructive | Destaque |
|
||||
|------|-----------|------------|---------|-------------|----------|
|
||||
| **Claro** | oklch(0.99 0 0) — quase branco | oklch(0 0 0) — preto | Preto | Vermelho | Azul |
|
||||
| **Escuro** | oklch(0 0 0) — preto puro | oklch(1 0 0) — branco | Branco | Vermelho escuro | — |
|
||||
|
||||
### Cores Funcionais
|
||||
- **Emerald/Green (`#10b981`)** — status ativo, quota alta, running
|
||||
- **Amber/Yellow** — quota média, alertas
|
||||
- **Rose/Red** — quota baixa, erro, stopped
|
||||
- **Blue** — AI credits, informações premium
|
||||
|
||||
### Tipografia
|
||||
- **Geist** (sans-serif) — fonte principal moderna e geométrica (da Vercel)
|
||||
- **Geist Mono** (monospace) — dados técnicos, números de quota
|
||||
- **Tomorrow** (display/futurista) — possíveis títulos estilizados
|
||||
|
||||
### Características de UI
|
||||
- Bordas arredondadas (`0.5rem` / 8px)
|
||||
- Sombras sutis
|
||||
- Cards com hover states suaves
|
||||
- Interface limpa com espaçamento generoso
|
||||
|
||||
---
|
||||
|
||||
## 5. Assets Visuais Existentes
|
||||
|
||||
| Arquivo | Descrição |
|
||||
|---------|-----------|
|
||||
| `docs/assets/logo.png` | Logo antiga (Antigravity) — 128x128, usada no README |
|
||||
| `docs/assets/screenshot-main.png` | Screenshot da interface principal |
|
||||
| `docs/assets/screenshot-proxy.png` | Screenshot da aba proxy |
|
||||
| `docs/assets/screenshot-setting.png` | Screenshot de settings |
|
||||
| `src/assets/icon.png` | Ícone do app (também é o logo antigo) |
|
||||
| `src/assets/tray.png` | Ícone da system tray |
|
||||
| `images/icon.ico` / `images/icon.icns` | Ícones de build para Windows/Mac |
|
||||
| `images/favicon-*.png` | Favicons em múltiplos tamanhos |
|
||||
| `images/32x32.png`, `64x64.png`, `128x128.png`, `[email protected]` | Ícones para AppImage Linux |
|
||||
| `src/assets/fonts/geist/` | Fonte Geist (principal) |
|
||||
| `src/assets/fonts/geist-mono/` | Fonte Geist Mono (código/dados) |
|
||||
| `src/assets/fonts/tomorrow/` | Fonte Tomorrow (display, 4 pesos) |
|
||||
|
||||
---
|
||||
|
||||
## 6. Conceitos Visuais Sugeridos para a Logo
|
||||
|
||||
### A. Nodo / Conexão (Nexus)
|
||||
- Ponto central conectado a múltiplos pontos (contas gerenciadas)
|
||||
- Círculo central com 2-3 linhas finas irradiando
|
||||
- Dois círculos interligados (Gemini + Claude)
|
||||
|
||||
### B. Infinito / Loop (Gemini + Proxy)
|
||||
- Símbolo de infinito (∞) modificado como circuito/loop de dados
|
||||
- Referência à dualidade "Gemini" (gêmeos)
|
||||
- Curva contínua elegante com seta indicando fluxo
|
||||
|
||||
### C. Cubo / Hexágono (Nexus / Hub)
|
||||
- Hexágono ou cubo isométrico minimalista
|
||||
- Linhas finas, perspectiva suave
|
||||
- Face "aberta" ou conectada
|
||||
|
||||
### D. Monograma "GN"
|
||||
- Letras "G" e "N" abstraídas como nodo de rede
|
||||
- Estilo geométrico, similar a Tomorrow ou Geist
|
||||
|
||||
### E. Proxy / Pipe (Fluxo de Dados)
|
||||
- Duas barras paralelas com seta passando entre elas
|
||||
- "Pipe" minimalista — conduz tráfego entre APIs
|
||||
|
||||
---
|
||||
|
||||
## 7. Diretrizes para a Nova Logo
|
||||
|
||||
| Elemento | Especificação |
|
||||
|----------|---------------|
|
||||
| **Estilo** | Minimalista, geométrica, precisa, técnica |
|
||||
| **Cores principais** | Preto (`#000000`) e branco (`#ffffff`) |
|
||||
| **Cor de acento (opcional)** | Emerald (`#10b981`) para "ativo/online" |
|
||||
| **Versões necessárias** | Dark mode e light mode |
|
||||
| **Tamanhos** | De 16x16 (tray) até 512x512 (macOS) |
|
||||
| **Monocromática** | Deve funcionar em preto e branco puro |
|
||||
| **Tipografia do wordmark** | Geométrica sans-serif, peso medium/semibold, tracking levemente expandido |
|
||||
|
||||
---
|
||||
|
||||
## 8. Conclusão
|
||||
|
||||
O app pede uma logo que evoque **conexão/nexo** (Nexus) com **múltiplos pontos** (contas) de forma geométrica e limpa, usando primariamente preto/branco com um toque sutil de verde (emerald) para representar o estado "ativo/online" central ao propósito do app.
|
||||
|
||||
A logo deve transmitir:
|
||||
- **Tecnologia** e **precisão**
|
||||
- **Conectividade** e **hub central**
|
||||
- **Profissionalismo** e **confiança**
|
||||
- **Modernidade** e **minimalismo**
|
||||
# Brand Briefing — Gemini Nexus
|
||||
|
||||
## 1. Nome e Descrição
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **Nome** | Gemini Nexus |
|
||||
| **Product Name** | Gemini Nexus |
|
||||
| **Package Name** | gemini-nexus |
|
||||
| **Versão** | 0.11.1 |
|
||||
| **Descrição EN** | Professional multi-account manager for Google Gemini & Claude AI |
|
||||
| **Descrição PT-BR** | Gerenciador multi-contas profissional para Google Gemini & Claude AI |
|
||||
| **Autor** | evandrodevbr / Draculabo |
|
||||
| **Licença** | CC-BY-NC-SA-4.0 (apenas fins educacionais) |
|
||||
|
||||
---
|
||||
|
||||
## 2. Propósito do Aplicativo
|
||||
|
||||
Gemini Nexus é um **aplicativo desktop profissional** (Electron) que funciona como um **hub central (nexus)** para desenvolvedores que usam IDEs com IA.
|
||||
|
||||
### Funcionalidades Principais
|
||||
- **Pool ilimitado de contas**: Adicionar múltiplas contas Google Gemini / Claude via OAuth
|
||||
- **Auto-switching inteligente**: Troca automática de conta quando a cota acaba ou há rate limit
|
||||
- **Monitoramento em tempo real**: Barras de progresso coloridas para visualizar uso de quota
|
||||
- **Proxy API local**: Servidor proxy integrado compatível OpenAI/Anthropic (porta 8045)
|
||||
- **Segurança**: Criptografia AES-256-GCM para dados sensíveis
|
||||
|
||||
### Público-Alvo
|
||||
- Desenvolvedores que usam IDEs com integração AI (Cursor, Windsurf, VS Code, Claude Code, etc.)
|
||||
- Power users que precisam alternar entre múltiplas contas de IA
|
||||
- Usuários que precisam de um proxy API local confiável
|
||||
|
||||
---
|
||||
|
||||
## 3. Tom de Voz / Personalidade
|
||||
|
||||
- **Profissional e técnica**: Termos como "Nexus", "Proxy", "Gateway", "Quota", "Circuit Breaker"
|
||||
- **Confiável e estável**: Monitoramento, health checks, logging robusto
|
||||
- **Developer-first**: Suporte a múltiplas IDEs, geração de cURL/Python
|
||||
- **Moderna e minimalista**: Interface limpa, componentes modulares
|
||||
- **Global**: Suporte a i18n (EN, PT-BR, ZH, RU, VI)
|
||||
|
||||
---
|
||||
|
||||
## 4. Estilo Visual Atual
|
||||
|
||||
### Tema
|
||||
- Dual theme (claro/escuro) com detecção automática do sistema
|
||||
- Extremamente minimalista e quase monocromático
|
||||
|
||||
### Paleta de Cores (Tailwind OKLCH)
|
||||
|
||||
| Modo | Background | Foreground | Primary | Destructive | Destaque |
|
||||
|------|-----------|------------|---------|-------------|----------|
|
||||
| **Claro** | oklch(0.99 0 0) — quase branco | oklch(0 0 0) — preto | Preto | Vermelho | Azul |
|
||||
| **Escuro** | oklch(0 0 0) — preto puro | oklch(1 0 0) — branco | Branco | Vermelho escuro | — |
|
||||
|
||||
### Cores Funcionais
|
||||
- **Emerald/Green (`#10b981`)** — status ativo, quota alta, running
|
||||
- **Amber/Yellow** — quota média, alertas
|
||||
- **Rose/Red** — quota baixa, erro, stopped
|
||||
- **Blue** — AI credits, informações premium
|
||||
|
||||
### Tipografia
|
||||
- **Geist** (sans-serif) — fonte principal moderna e geométrica (da Vercel)
|
||||
- **Geist Mono** (monospace) — dados técnicos, números de quota
|
||||
- **Tomorrow** (display/futurista) — possíveis títulos estilizados
|
||||
|
||||
### Características de UI
|
||||
- Bordas arredondadas (`0.5rem` / 8px)
|
||||
- Sombras sutis
|
||||
- Cards com hover states suaves
|
||||
- Interface limpa com espaçamento generoso
|
||||
|
||||
---
|
||||
|
||||
## 5. Assets Visuais Existentes
|
||||
|
||||
| Arquivo | Descrição |
|
||||
|---------|-----------|
|
||||
| `docs/assets/logo.png` | Logo antiga (Antigravity) — 128x128, usada no README |
|
||||
| `docs/assets/screenshot-main.png` | Screenshot da interface principal |
|
||||
| `docs/assets/screenshot-proxy.png` | Screenshot da aba proxy |
|
||||
| `docs/assets/screenshot-setting.png` | Screenshot de settings |
|
||||
| `src/assets/icon.png` | Ícone do app (também é o logo antigo) |
|
||||
| `src/assets/tray.png` | Ícone da system tray |
|
||||
| `images/icon.ico` / `images/icon.icns` | Ícones de build para Windows/Mac |
|
||||
| `images/favicon-*.png` | Favicons em múltiplos tamanhos |
|
||||
| `images/32x32.png`, `64x64.png`, `128x128.png`, `[email protected]` | Ícones para AppImage Linux |
|
||||
| `src/assets/fonts/geist/` | Fonte Geist (principal) |
|
||||
| `src/assets/fonts/geist-mono/` | Fonte Geist Mono (código/dados) |
|
||||
| `src/assets/fonts/tomorrow/` | Fonte Tomorrow (display, 4 pesos) |
|
||||
|
||||
---
|
||||
|
||||
## 6. Conceitos Visuais Sugeridos para a Logo
|
||||
|
||||
### A. Nodo / Conexão (Nexus)
|
||||
- Ponto central conectado a múltiplos pontos (contas gerenciadas)
|
||||
- Círculo central com 2-3 linhas finas irradiando
|
||||
- Dois círculos interligados (Gemini + Claude)
|
||||
|
||||
### B. Infinito / Loop (Gemini + Proxy)
|
||||
- Símbolo de infinito (∞) modificado como circuito/loop de dados
|
||||
- Referência à dualidade "Gemini" (gêmeos)
|
||||
- Curva contínua elegante com seta indicando fluxo
|
||||
|
||||
### C. Cubo / Hexágono (Nexus / Hub)
|
||||
- Hexágono ou cubo isométrico minimalista
|
||||
- Linhas finas, perspectiva suave
|
||||
- Face "aberta" ou conectada
|
||||
|
||||
### D. Monograma "GN"
|
||||
- Letras "G" e "N" abstraídas como nodo de rede
|
||||
- Estilo geométrico, similar a Tomorrow ou Geist
|
||||
|
||||
### E. Proxy / Pipe (Fluxo de Dados)
|
||||
- Duas barras paralelas com seta passando entre elas
|
||||
- "Pipe" minimalista — conduz tráfego entre APIs
|
||||
|
||||
---
|
||||
|
||||
## 7. Diretrizes para a Nova Logo
|
||||
|
||||
| Elemento | Especificação |
|
||||
|----------|---------------|
|
||||
| **Estilo** | Minimalista, geométrica, precisa, técnica |
|
||||
| **Cores principais** | Preto (`#000000`) e branco (`#ffffff`) |
|
||||
| **Cor de acento (opcional)** | Emerald (`#10b981`) para "ativo/online" |
|
||||
| **Versões necessárias** | Dark mode e light mode |
|
||||
| **Tamanhos** | De 16x16 (tray) até 512x512 (macOS) |
|
||||
| **Monocromática** | Deve funcionar em preto e branco puro |
|
||||
| **Tipografia do wordmark** | Geométrica sans-serif, peso medium/semibold, tracking levemente expandido |
|
||||
|
||||
---
|
||||
|
||||
## 8. Conclusão
|
||||
|
||||
O app pede uma logo que evoque **conexão/nexo** (Nexus) com **múltiplos pontos** (contas) de forma geométrica e limpa, usando primariamente preto/branco com um toque sutil de verde (emerald) para representar o estado "ativo/online" central ao propósito do app.
|
||||
|
||||
A logo deve transmitir:
|
||||
- **Tecnologia** e **precisão**
|
||||
- **Conectividade** e **hub central**
|
||||
- **Profissionalismo** e **confiança**
|
||||
- **Modernidade** e **minimalismo**
|
||||
+96
-96
@@ -1,96 +1,96 @@
|
||||
# Cloud Account Management and Intelligent Switching
|
||||
|
||||
This document explains the cloud AI account management and switching capabilities in Gemini Nexus. The feature allows users to manage multiple Google accounts, monitor API quotas, and seamlessly switch the active IDE account with one click.
|
||||
|
||||
## 1. Core Features
|
||||
|
||||
### 1.1 Account Pool Management
|
||||
|
||||
- **Add accounts**: Add accounts via Google OAuth authorization code.
|
||||
- **List view**: Display all added accounts, including avatar, email, and last used time.
|
||||
- **Status monitoring**: Show real-time account status (Active, Rate Limited, Expired) and whether the account is currently active.
|
||||
- **Delete accounts**: Remove accounts from the local database.
|
||||
|
||||
### 1.2 Real-Time Quota Monitoring
|
||||
|
||||
- **Multi-model support**: Track quota usage for models such as `gemini-pro`, `claude-3-5-sonnet`, and more.
|
||||
- **Visual indicators**: Use progress bars and color states (green/yellow/red) to show remaining quota percentage.
|
||||
- **Auto/manual refresh**: Support manual quota refresh; the system also checks quota automatically before switching.
|
||||
|
||||
### 1.4 Intelligent Auto-Switching
|
||||
|
||||
- **Unlimited pool mode**: When the current account quota is low (`<5%`) or rate-limited, the system automatically finds and switches to the best backup account.
|
||||
- **Background monitoring**: Built-in `CloudMonitorService` polls quota status for all accounts every 5 minutes by default.
|
||||
- **Global toggle**: Users can enable or disable this feature with one click in the UI.
|
||||
|
||||
## 2. Technical Implementation
|
||||
|
||||
### 2.1 Database Design (`cloud_accounts.db`)
|
||||
|
||||
Account information is stored in SQLite, independent from the IDE's local database.
|
||||
|
||||
```sql
|
||||
CREATE TABLE accounts (
|
||||
id TEXT PRIMARY KEY, -- UUID
|
||||
provider TEXT NOT NULL, -- 'google' | 'anthropic'
|
||||
email TEXT NOT NULL, -- Email
|
||||
name TEXT, -- Display name
|
||||
avatar_url TEXT, -- Avatar URL
|
||||
token_json TEXT NOT NULL, -- OAuth token (JSON)
|
||||
quota_json TEXT, -- Quota data (JSON)
|
||||
created_at INTEGER NOT NULL, -- Created timestamp
|
||||
last_used INTEGER NOT NULL, -- Last-used timestamp
|
||||
status TEXT DEFAULT 'active', -- Account status
|
||||
is_active INTEGER DEFAULT 0 -- Whether this is the currently active IDE account
|
||||
);
|
||||
|
||||
-- Global settings table
|
||||
CREATE TABLE settings (
|
||||
key TEXT PRIMARY KEY,
|
||||
value TEXT NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
### 2.2 IPC Interface Design
|
||||
|
||||
The backend exposes the following oRPC interfaces via `src/ipc/cloud`:
|
||||
|
||||
- `addGoogleAccount(authCode: string)`: Exchange token and save account.
|
||||
- `listCloudAccounts()`: Get account list.
|
||||
- `refreshAccountQuota(accountId: string)`: Refresh quota and token for a specific account.
|
||||
- `switchCloudAccount(accountId: string)`: Run the account switch workflow.
|
||||
- `deleteCloudAccount(accountId: string)`: Delete an account.
|
||||
- `getAutoSwitchEnabled()` / `setAutoSwitchEnabled(enabled)`: Get/set auto-switch state.
|
||||
- `forcePollCloudMonitor()`: Manually trigger background polling.
|
||||
|
||||
### 2.3 Token Injection Mechanism (`ProtobufUtils`)
|
||||
|
||||
The IDE stores authentication data in the `ItemTable` table of `state.vscdb`, under the key `jetskiStateSync.agentManagerInitState`.
|
||||
The value is Base64-encoded Protobuf binary.
|
||||
|
||||
We implemented `src/utils/protobuf.ts`, which can:
|
||||
|
||||
1. **Decode**: Parse Varint and length-delimited fields.
|
||||
2. **Modify**: Locate and remove old Field 6 (`OAuthTokenInfo`).
|
||||
3. **Rebuild**: Build a new Field 6 using new access/refresh tokens and insert it.
|
||||
|
||||
### 2.4 Switching Workflow
|
||||
|
||||
1. **Token check**: Check whether the target account token is near expiration; refresh automatically if needed.
|
||||
2. **Stop process**: Gracefully stop the Antigravity process.
|
||||
3. **Inject token**: Call `CloudAccountRepo.injectCloudToken` to update the IDE database.
|
||||
4. **Update state**: Mark target account as `is_active = 1`, set others to `0`.
|
||||
5. **Restart process**: Restart the IDE so it loads new credentials.
|
||||
|
||||
### 2.5 Auto-Switch Logic (`AutoSwitchService`)
|
||||
|
||||
1. **Monitor**: `CloudMonitorService` polls quotas for all accounts every 5 minutes.
|
||||
2. **Evaluate**: If all key model quotas of the active account are below `5%`, or status is `rate_limited`.
|
||||
3. **Select**: Filter accounts with `active` status and sufficient quota, then sort by remaining quota.
|
||||
4. **Execute**: Automatically call `switchCloudAccount` and notify the user.
|
||||
|
||||
### 2.6 Security Hardening
|
||||
|
||||
- **Key management**: Use native OS credential stores (Windows Credential Manager / macOS Keychain) via `keytar` to securely store the AES-256 master key.
|
||||
- **Data encryption**: Encrypt all sensitive fields (`token_json`, `quota_json`) with `AES-256-GCM` before writing to SQLite.
|
||||
- **Auto migration**: Automatically detect and migrate legacy plaintext data at startup to ensure a smooth security upgrade.
|
||||
# Cloud Account Management and Intelligent Switching
|
||||
|
||||
This document explains the cloud AI account management and switching capabilities in Gemini Nexus. The feature allows users to manage multiple Google accounts, monitor API quotas, and seamlessly switch the active IDE account with one click.
|
||||
|
||||
## 1. Core Features
|
||||
|
||||
### 1.1 Account Pool Management
|
||||
|
||||
- **Add accounts**: Add accounts via Google OAuth authorization code.
|
||||
- **List view**: Display all added accounts, including avatar, email, and last used time.
|
||||
- **Status monitoring**: Show real-time account status (Active, Rate Limited, Expired) and whether the account is currently active.
|
||||
- **Delete accounts**: Remove accounts from the local database.
|
||||
|
||||
### 1.2 Real-Time Quota Monitoring
|
||||
|
||||
- **Multi-model support**: Track quota usage for models such as `gemini-pro`, `claude-3-5-sonnet`, and more.
|
||||
- **Visual indicators**: Use progress bars and color states (green/yellow/red) to show remaining quota percentage.
|
||||
- **Auto/manual refresh**: Support manual quota refresh; the system also checks quota automatically before switching.
|
||||
|
||||
### 1.4 Intelligent Auto-Switching
|
||||
|
||||
- **Unlimited pool mode**: When the current account quota is low (`<5%`) or rate-limited, the system automatically finds and switches to the best backup account.
|
||||
- **Background monitoring**: Built-in `CloudMonitorService` polls quota status for all accounts every 5 minutes by default.
|
||||
- **Global toggle**: Users can enable or disable this feature with one click in the UI.
|
||||
|
||||
## 2. Technical Implementation
|
||||
|
||||
### 2.1 Database Design (`cloud_accounts.db`)
|
||||
|
||||
Account information is stored in SQLite, independent from the IDE's local database.
|
||||
|
||||
```sql
|
||||
CREATE TABLE accounts (
|
||||
id TEXT PRIMARY KEY, -- UUID
|
||||
provider TEXT NOT NULL, -- 'google' | 'anthropic'
|
||||
email TEXT NOT NULL, -- Email
|
||||
name TEXT, -- Display name
|
||||
avatar_url TEXT, -- Avatar URL
|
||||
token_json TEXT NOT NULL, -- OAuth token (JSON)
|
||||
quota_json TEXT, -- Quota data (JSON)
|
||||
created_at INTEGER NOT NULL, -- Created timestamp
|
||||
last_used INTEGER NOT NULL, -- Last-used timestamp
|
||||
status TEXT DEFAULT 'active', -- Account status
|
||||
is_active INTEGER DEFAULT 0 -- Whether this is the currently active IDE account
|
||||
);
|
||||
|
||||
-- Global settings table
|
||||
CREATE TABLE settings (
|
||||
key TEXT PRIMARY KEY,
|
||||
value TEXT NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
### 2.2 IPC Interface Design
|
||||
|
||||
The backend exposes the following oRPC interfaces via `src/ipc/cloud`:
|
||||
|
||||
- `addGoogleAccount(authCode: string)`: Exchange token and save account.
|
||||
- `listCloudAccounts()`: Get account list.
|
||||
- `refreshAccountQuota(accountId: string)`: Refresh quota and token for a specific account.
|
||||
- `switchCloudAccount(accountId: string)`: Run the account switch workflow.
|
||||
- `deleteCloudAccount(accountId: string)`: Delete an account.
|
||||
- `getAutoSwitchEnabled()` / `setAutoSwitchEnabled(enabled)`: Get/set auto-switch state.
|
||||
- `forcePollCloudMonitor()`: Manually trigger background polling.
|
||||
|
||||
### 2.3 Token Injection Mechanism (`ProtobufUtils`)
|
||||
|
||||
The IDE stores authentication data in the `ItemTable` table of `state.vscdb`, under the key `jetskiStateSync.agentManagerInitState`.
|
||||
The value is Base64-encoded Protobuf binary.
|
||||
|
||||
We implemented `src/utils/protobuf.ts`, which can:
|
||||
|
||||
1. **Decode**: Parse Varint and length-delimited fields.
|
||||
2. **Modify**: Locate and remove old Field 6 (`OAuthTokenInfo`).
|
||||
3. **Rebuild**: Build a new Field 6 using new access/refresh tokens and insert it.
|
||||
|
||||
### 2.4 Switching Workflow
|
||||
|
||||
1. **Token check**: Check whether the target account token is near expiration; refresh automatically if needed.
|
||||
2. **Stop process**: Gracefully stop the Antigravity process.
|
||||
3. **Inject token**: Call `CloudAccountRepo.injectCloudToken` to update the IDE database.
|
||||
4. **Update state**: Mark target account as `is_active = 1`, set others to `0`.
|
||||
5. **Restart process**: Restart the IDE so it loads new credentials.
|
||||
|
||||
### 2.5 Auto-Switch Logic (`AutoSwitchService`)
|
||||
|
||||
1. **Monitor**: `CloudMonitorService` polls quotas for all accounts every 5 minutes.
|
||||
2. **Evaluate**: If all key model quotas of the active account are below `5%`, or status is `rate_limited`.
|
||||
3. **Select**: Filter accounts with `active` status and sufficient quota, then sort by remaining quota.
|
||||
4. **Execute**: Automatically call `switchCloudAccount` and notify the user.
|
||||
|
||||
### 2.6 Security Hardening
|
||||
|
||||
- **Key management**: Use native OS credential stores (Windows Credential Manager / macOS Keychain) via `keytar` to securely store the AES-256 master key.
|
||||
- **Data encryption**: Encrypt all sensitive fields (`token_json`, `quota_json`) with `AES-256-GCM` before writing to SQLite.
|
||||
- **Auto migration**: Automatically detect and migrate legacy plaintext data at startup to ensure a smooth security upgrade.
|
||||
+244
-244
@@ -1,244 +1,244 @@
|
||||
# Proxyman Debugging Guide for Antigravity and Gemini Nexus
|
||||
|
||||
This guide explains how to use Proxyman for two debugging targets:
|
||||
|
||||
1. The installed official `Antigravity` desktop client
|
||||
2. The `Gemini Nexus` development build from this repository
|
||||
|
||||
Before you start, complete [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md).
|
||||
|
||||
## Scope
|
||||
|
||||
Use this guide when you want to:
|
||||
|
||||
- inspect login, quota, project context, or model-list requests from `Antigravity`
|
||||
- inspect OAuth, quota refresh, or proxy traffic from `Gemini Nexus`
|
||||
- compare requests from the official client with requests produced by this project
|
||||
|
||||
## Understand the Two Traffic Paths
|
||||
|
||||
### Official `Antigravity` Client
|
||||
|
||||
`Antigravity` is an Electron application. Its traffic may come from:
|
||||
|
||||
- Chromium or renderer-side requests
|
||||
- Electron or Node-side requests
|
||||
|
||||
### `Gemini Nexus` in This Repository
|
||||
|
||||
This project is also an Electron app, but it additionally includes Node, Undici, and internal proxy flows. You may need to inspect:
|
||||
|
||||
- Electron main-process outbound requests
|
||||
- renderer-side requests
|
||||
- upstream requests emitted by `src/server/`
|
||||
|
||||
## Debug the Installed Official Antigravity Client
|
||||
|
||||
### Recommended Path: Use the Repository Script
|
||||
|
||||
Use the provided script:
|
||||
|
||||
- [scripts/start-antigravity-with-proxyman.ps1](../scripts/start-antigravity-with-proxyman.ps1)
|
||||
|
||||
This should be the default path for the installed official client because it already does the following:
|
||||
|
||||
- sets `HTTP_PROXY`, `HTTPS_PROXY`, and `ALL_PROXY`
|
||||
- sets `NODE_EXTRA_CA_CERTS`
|
||||
- passes `--proxy-server` and `--proxy-bypass-list`
|
||||
- stops existing `Antigravity` processes so the new environment takes effect
|
||||
|
||||
Typical usage:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1
|
||||
```
|
||||
|
||||
If Proxyman is using a different port:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1 -Port 9091
|
||||
```
|
||||
|
||||
If you are temporarily debugging TLS failures:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1 -AllowInsecureTls
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- This script targets the installed official `Antigravity` client.
|
||||
- It does not launch this repository's `Gemini Nexus` development build.
|
||||
- Override `-AppPath`, `-CaPath`, `-ProxyHost`, or `-NoProxy` if your local environment differs.
|
||||
|
||||
### Suggested Flow
|
||||
|
||||
1. Open Proxyman.
|
||||
2. Confirm that installation and certificate setup are already complete.
|
||||
3. Confirm the local proxy port, for example `9090`.
|
||||
4. Launch `Antigravity` with the script.
|
||||
5. Trigger a request that is easy to identify, such as:
|
||||
- Google sign-in
|
||||
- model list loading
|
||||
- quota refresh
|
||||
- a generated request or prompt action
|
||||
|
||||
### Why Manual Parameters Are Still Documented
|
||||
|
||||
The script is the recommended default, but the raw parameters are still useful because:
|
||||
|
||||
- contributors may want to understand exactly what the script configures
|
||||
- some people launch from VS Code, another shell, or a custom wrapper
|
||||
- some debugging sessions need a partial override rather than the full script
|
||||
|
||||
### If Windows System Proxy Is Not Enough
|
||||
|
||||
In some environments you may still need to point the system proxy to Proxyman manually. At minimum, verify:
|
||||
|
||||
- HTTP proxy: `127.0.0.1:9090`
|
||||
- HTTPS proxy: `127.0.0.1:9090`
|
||||
- the bypass list is not excluding the domains you want to inspect
|
||||
|
||||
### If You Need Direct Chromium Proxy Arguments
|
||||
|
||||
If system proxy behavior is unreliable, you can launch the installed client with explicit Chromium proxy arguments:
|
||||
|
||||
```powershell
|
||||
& "C:\Users\<YourUser>\AppData\Local\Programs\Antigravity\Antigravity.exe" `
|
||||
--proxy-server="http://127.0.0.1:9090" `
|
||||
--proxy-bypass-list="<local>;localhost;127.0.0.1;::1"
|
||||
```
|
||||
|
||||
Use this as a fallback, not the default path.
|
||||
|
||||
## Debug Gemini Nexus From This Repository
|
||||
|
||||
This project has more layers than the official client. The script above is not the general launcher for this repository's development app.
|
||||
|
||||
### Capture Main-Process, Node, and Internal Proxy Traffic
|
||||
|
||||
Set proxy-related environment variables before starting the app:
|
||||
|
||||
```powershell
|
||||
$env:HTTP_PROXY = "http://127.0.0.1:9090"
|
||||
$env:HTTPS_PROXY = "http://127.0.0.1:9090"
|
||||
$env:ALL_PROXY = "http://127.0.0.1:9090"
|
||||
$env:NO_PROXY = "localhost,127.0.0.1,::1"
|
||||
$env:NODE_EXTRA_CA_CERTS = "$env:APPDATA\\Proxyman\\certificate\\certs\\ca.pem"
|
||||
|
||||
# Enable only for temporary TLS debugging
|
||||
$env:NODE_TLS_REJECT_UNAUTHORIZED = "0"
|
||||
|
||||
npm start
|
||||
```
|
||||
|
||||
This primarily affects:
|
||||
|
||||
- Node HTTP and HTTPS requests
|
||||
- `undici`, `fetch`, and some dependency-driven upstream requests
|
||||
- internal proxy requests forwarded to upstream services
|
||||
|
||||
### Also Capture Electron and Chromium Traffic
|
||||
|
||||
If you want both Node-side and renderer-side traffic, add Chromium proxy arguments:
|
||||
|
||||
```powershell
|
||||
$env:HTTP_PROXY = "http://127.0.0.1:9090"
|
||||
$env:HTTPS_PROXY = "http://127.0.0.1:9090"
|
||||
$env:ALL_PROXY = "http://127.0.0.1:9090"
|
||||
$env:NO_PROXY = "localhost,127.0.0.1,::1"
|
||||
$env:NODE_EXTRA_CA_CERTS = "$env:APPDATA\\Proxyman\\certificate\\certs\\ca.pem"
|
||||
$env:NODE_TLS_REJECT_UNAUTHORIZED = "0"
|
||||
|
||||
npm start -- --proxy-server="http://127.0.0.1:9090" --proxy-bypass-list="<local>;localhost;127.0.0.1;::1"
|
||||
```
|
||||
|
||||
If your local `npm start` flow does not forward arguments to Electron Forge, use one of these fallback approaches:
|
||||
|
||||
- capture only Node and main-process traffic
|
||||
- wrap the Electron launch in your own PowerShell or VS Code task
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### I Can See Requests but HTTPS Bodies Are Empty
|
||||
|
||||
Check:
|
||||
|
||||
- the Proxyman root certificate is really trusted
|
||||
- `NODE_EXTRA_CA_CERTS` is set when Node-side traffic needs it
|
||||
- `NODE_TLS_REJECT_UNAUTHORIZED=0` is only being used as a temporary debugging override
|
||||
- the target app is not using SSL pinning
|
||||
|
||||
Background setup guide:
|
||||
|
||||
- [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md)
|
||||
|
||||
### I Can See Browser Traffic but Not Node or Main-Process Traffic
|
||||
|
||||
Common causes:
|
||||
|
||||
- Node is not using system proxy settings
|
||||
- the HTTP client does not read `HTTP_PROXY`
|
||||
- only the system proxy was configured, but runtime environment variables were not
|
||||
|
||||
### I Cannot See `localhost` Traffic
|
||||
|
||||
Common cause:
|
||||
|
||||
- loopback traffic is bypassing the proxy
|
||||
|
||||
Keep this bypass list in mind when launching Electron:
|
||||
|
||||
```plaintext
|
||||
--proxy-bypass-list="<local>;localhost;127.0.0.1;::1"
|
||||
```
|
||||
|
||||
Adjust it only if your current debugging target requires a different loopback behavior.
|
||||
|
||||
### TLS Still Fails After the Certificate Was Installed
|
||||
|
||||
Common causes:
|
||||
|
||||
- the process started before the certificate was installed and needs a full restart
|
||||
- `ca.cer` was imported but `ca.pem` was not passed to Node when required
|
||||
- a corporate proxy, VPN, or security product is changing network behavior
|
||||
- the target app uses SSL pinning
|
||||
|
||||
## Security Notes
|
||||
|
||||
Keep local debugging settings out of the repository and out of public issue threads.
|
||||
|
||||
- Do not commit your local proxy address, certificate paths, cookies, or OAuth codes.
|
||||
- Do not leave `NODE_TLS_REJECT_UNAUTHORIZED=0` enabled beyond temporary local debugging.
|
||||
- Do not post raw tokens, sessions, or authorization headers in public issues.
|
||||
- Redact logs before sharing them.
|
||||
|
||||
## Minimal Workflows
|
||||
|
||||
### Official Antigravity Client
|
||||
|
||||
1. Complete [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md).
|
||||
2. Open Proxyman.
|
||||
3. Run:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1
|
||||
```
|
||||
|
||||
4. Trigger login, quota, or model-list traffic.
|
||||
|
||||
### Gemini Nexus in This Repository
|
||||
|
||||
1. Complete [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md).
|
||||
2. Open PowerShell.
|
||||
3. Set `HTTP_PROXY`, `HTTPS_PROXY`, and `NODE_EXTRA_CA_CERTS`.
|
||||
4. Run `npm start`.
|
||||
5. Filter Proxyman traffic by domains such as:
|
||||
- `googleapis.com`
|
||||
- `googleusercontent.com`
|
||||
- the upstream domain you are debugging
|
||||
|
||||
## Related Files
|
||||
|
||||
- Setup guide: [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md)
|
||||
- Official-client launcher: [scripts/start-antigravity-with-proxyman.ps1](../scripts/start-antigravity-with-proxyman.ps1)
|
||||
# Proxyman Debugging Guide for Antigravity and Gemini Nexus
|
||||
|
||||
This guide explains how to use Proxyman for two debugging targets:
|
||||
|
||||
1. The installed official `Antigravity` desktop client
|
||||
2. The `Gemini Nexus` development build from this repository
|
||||
|
||||
Before you start, complete [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md).
|
||||
|
||||
## Scope
|
||||
|
||||
Use this guide when you want to:
|
||||
|
||||
- inspect login, quota, project context, or model-list requests from `Antigravity`
|
||||
- inspect OAuth, quota refresh, or proxy traffic from `Gemini Nexus`
|
||||
- compare requests from the official client with requests produced by this project
|
||||
|
||||
## Understand the Two Traffic Paths
|
||||
|
||||
### Official `Antigravity` Client
|
||||
|
||||
`Antigravity` is an Electron application. Its traffic may come from:
|
||||
|
||||
- Chromium or renderer-side requests
|
||||
- Electron or Node-side requests
|
||||
|
||||
### `Gemini Nexus` in This Repository
|
||||
|
||||
This project is also an Electron app, but it additionally includes Node, Undici, and internal proxy flows. You may need to inspect:
|
||||
|
||||
- Electron main-process outbound requests
|
||||
- renderer-side requests
|
||||
- upstream requests emitted by `src/server/`
|
||||
|
||||
## Debug the Installed Official Antigravity Client
|
||||
|
||||
### Recommended Path: Use the Repository Script
|
||||
|
||||
Use the provided script:
|
||||
|
||||
- [scripts/start-antigravity-with-proxyman.ps1](../scripts/start-antigravity-with-proxyman.ps1)
|
||||
|
||||
This should be the default path for the installed official client because it already does the following:
|
||||
|
||||
- sets `HTTP_PROXY`, `HTTPS_PROXY`, and `ALL_PROXY`
|
||||
- sets `NODE_EXTRA_CA_CERTS`
|
||||
- passes `--proxy-server` and `--proxy-bypass-list`
|
||||
- stops existing `Antigravity` processes so the new environment takes effect
|
||||
|
||||
Typical usage:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1
|
||||
```
|
||||
|
||||
If Proxyman is using a different port:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1 -Port 9091
|
||||
```
|
||||
|
||||
If you are temporarily debugging TLS failures:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1 -AllowInsecureTls
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- This script targets the installed official `Antigravity` client.
|
||||
- It does not launch this repository's `Gemini Nexus` development build.
|
||||
- Override `-AppPath`, `-CaPath`, `-ProxyHost`, or `-NoProxy` if your local environment differs.
|
||||
|
||||
### Suggested Flow
|
||||
|
||||
1. Open Proxyman.
|
||||
2. Confirm that installation and certificate setup are already complete.
|
||||
3. Confirm the local proxy port, for example `9090`.
|
||||
4. Launch `Antigravity` with the script.
|
||||
5. Trigger a request that is easy to identify, such as:
|
||||
- Google sign-in
|
||||
- model list loading
|
||||
- quota refresh
|
||||
- a generated request or prompt action
|
||||
|
||||
### Why Manual Parameters Are Still Documented
|
||||
|
||||
The script is the recommended default, but the raw parameters are still useful because:
|
||||
|
||||
- contributors may want to understand exactly what the script configures
|
||||
- some people launch from VS Code, another shell, or a custom wrapper
|
||||
- some debugging sessions need a partial override rather than the full script
|
||||
|
||||
### If Windows System Proxy Is Not Enough
|
||||
|
||||
In some environments you may still need to point the system proxy to Proxyman manually. At minimum, verify:
|
||||
|
||||
- HTTP proxy: `127.0.0.1:9090`
|
||||
- HTTPS proxy: `127.0.0.1:9090`
|
||||
- the bypass list is not excluding the domains you want to inspect
|
||||
|
||||
### If You Need Direct Chromium Proxy Arguments
|
||||
|
||||
If system proxy behavior is unreliable, you can launch the installed client with explicit Chromium proxy arguments:
|
||||
|
||||
```powershell
|
||||
& "C:\Users\<YourUser>\AppData\Local\Programs\Antigravity\Antigravity.exe" `
|
||||
--proxy-server="http://127.0.0.1:9090" `
|
||||
--proxy-bypass-list="<local>;localhost;127.0.0.1;::1"
|
||||
```
|
||||
|
||||
Use this as a fallback, not the default path.
|
||||
|
||||
## Debug Gemini Nexus From This Repository
|
||||
|
||||
This project has more layers than the official client. The script above is not the general launcher for this repository's development app.
|
||||
|
||||
### Capture Main-Process, Node, and Internal Proxy Traffic
|
||||
|
||||
Set proxy-related environment variables before starting the app:
|
||||
|
||||
```powershell
|
||||
$env:HTTP_PROXY = "http://127.0.0.1:9090"
|
||||
$env:HTTPS_PROXY = "http://127.0.0.1:9090"
|
||||
$env:ALL_PROXY = "http://127.0.0.1:9090"
|
||||
$env:NO_PROXY = "localhost,127.0.0.1,::1"
|
||||
$env:NODE_EXTRA_CA_CERTS = "$env:APPDATA\\Proxyman\\certificate\\certs\\ca.pem"
|
||||
|
||||
# Enable only for temporary TLS debugging
|
||||
$env:NODE_TLS_REJECT_UNAUTHORIZED = "0"
|
||||
|
||||
npm start
|
||||
```
|
||||
|
||||
This primarily affects:
|
||||
|
||||
- Node HTTP and HTTPS requests
|
||||
- `undici`, `fetch`, and some dependency-driven upstream requests
|
||||
- internal proxy requests forwarded to upstream services
|
||||
|
||||
### Also Capture Electron and Chromium Traffic
|
||||
|
||||
If you want both Node-side and renderer-side traffic, add Chromium proxy arguments:
|
||||
|
||||
```powershell
|
||||
$env:HTTP_PROXY = "http://127.0.0.1:9090"
|
||||
$env:HTTPS_PROXY = "http://127.0.0.1:9090"
|
||||
$env:ALL_PROXY = "http://127.0.0.1:9090"
|
||||
$env:NO_PROXY = "localhost,127.0.0.1,::1"
|
||||
$env:NODE_EXTRA_CA_CERTS = "$env:APPDATA\\Proxyman\\certificate\\certs\\ca.pem"
|
||||
$env:NODE_TLS_REJECT_UNAUTHORIZED = "0"
|
||||
|
||||
npm start -- --proxy-server="http://127.0.0.1:9090" --proxy-bypass-list="<local>;localhost;127.0.0.1;::1"
|
||||
```
|
||||
|
||||
If your local `npm start` flow does not forward arguments to Electron Forge, use one of these fallback approaches:
|
||||
|
||||
- capture only Node and main-process traffic
|
||||
- wrap the Electron launch in your own PowerShell or VS Code task
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### I Can See Requests but HTTPS Bodies Are Empty
|
||||
|
||||
Check:
|
||||
|
||||
- the Proxyman root certificate is really trusted
|
||||
- `NODE_EXTRA_CA_CERTS` is set when Node-side traffic needs it
|
||||
- `NODE_TLS_REJECT_UNAUTHORIZED=0` is only being used as a temporary debugging override
|
||||
- the target app is not using SSL pinning
|
||||
|
||||
Background setup guide:
|
||||
|
||||
- [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md)
|
||||
|
||||
### I Can See Browser Traffic but Not Node or Main-Process Traffic
|
||||
|
||||
Common causes:
|
||||
|
||||
- Node is not using system proxy settings
|
||||
- the HTTP client does not read `HTTP_PROXY`
|
||||
- only the system proxy was configured, but runtime environment variables were not
|
||||
|
||||
### I Cannot See `localhost` Traffic
|
||||
|
||||
Common cause:
|
||||
|
||||
- loopback traffic is bypassing the proxy
|
||||
|
||||
Keep this bypass list in mind when launching Electron:
|
||||
|
||||
```plaintext
|
||||
--proxy-bypass-list="<local>;localhost;127.0.0.1;::1"
|
||||
```
|
||||
|
||||
Adjust it only if your current debugging target requires a different loopback behavior.
|
||||
|
||||
### TLS Still Fails After the Certificate Was Installed
|
||||
|
||||
Common causes:
|
||||
|
||||
- the process started before the certificate was installed and needs a full restart
|
||||
- `ca.cer` was imported but `ca.pem` was not passed to Node when required
|
||||
- a corporate proxy, VPN, or security product is changing network behavior
|
||||
- the target app uses SSL pinning
|
||||
|
||||
## Security Notes
|
||||
|
||||
Keep local debugging settings out of the repository and out of public issue threads.
|
||||
|
||||
- Do not commit your local proxy address, certificate paths, cookies, or OAuth codes.
|
||||
- Do not leave `NODE_TLS_REJECT_UNAUTHORIZED=0` enabled beyond temporary local debugging.
|
||||
- Do not post raw tokens, sessions, or authorization headers in public issues.
|
||||
- Redact logs before sharing them.
|
||||
|
||||
## Minimal Workflows
|
||||
|
||||
### Official Antigravity Client
|
||||
|
||||
1. Complete [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md).
|
||||
2. Open Proxyman.
|
||||
3. Run:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1
|
||||
```
|
||||
|
||||
4. Trigger login, quota, or model-list traffic.
|
||||
|
||||
### Gemini Nexus in This Repository
|
||||
|
||||
1. Complete [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md).
|
||||
2. Open PowerShell.
|
||||
3. Set `HTTP_PROXY`, `HTTPS_PROXY`, and `NODE_EXTRA_CA_CERTS`.
|
||||
4. Run `npm start`.
|
||||
5. Filter Proxyman traffic by domains such as:
|
||||
- `googleapis.com`
|
||||
- `googleusercontent.com`
|
||||
- the upstream domain you are debugging
|
||||
|
||||
## Related Files
|
||||
|
||||
- Setup guide: [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md)
|
||||
- Official-client launcher: [scripts/start-antigravity-with-proxyman.ps1](../scripts/start-antigravity-with-proxyman.ps1)
|
||||
+140
-140
@@ -1,140 +1,140 @@
|
||||
# Proxyman Installation and Basic Setup on Windows
|
||||
|
||||
This guide covers the Proxyman prerequisites for contributors:
|
||||
|
||||
1. Install Proxyman for Windows
|
||||
2. Trust the Proxyman certificate so HTTPS traffic can be decrypted
|
||||
3. Verify that Proxyman is working before you start debugging Antigravity traffic
|
||||
|
||||
If your goal is to debug the installed Antigravity client or this repository's development build, continue with [Proxyman Debugging Guide](./proxyman-debugging.md).
|
||||
|
||||
## Scope
|
||||
|
||||
This document is intentionally limited to the setup layer. It does not cover Antigravity-specific debugging flows.
|
||||
|
||||
Use it when you need to answer:
|
||||
|
||||
- How do I install Proxyman on Windows?
|
||||
- How do I trust the certificate?
|
||||
- Why can I only see CONNECT requests but not HTTPS bodies?
|
||||
- How do I verify that Proxyman itself is working?
|
||||
|
||||
## Install Proxyman
|
||||
|
||||
Official resources:
|
||||
|
||||
- Download: [https://proxyman.com/download](https://proxyman.com/download)
|
||||
- Windows product page: [https://proxyman.com/windows](https://proxyman.com/windows)
|
||||
|
||||
Recommended steps:
|
||||
|
||||
1. Install the Windows build from the official download page.
|
||||
2. Launch Proxyman.
|
||||
3. Confirm that Proxyman is listening on a local proxy port.
|
||||
4. This guide uses `9090` as the example port. Replace it with your local port if it differs.
|
||||
|
||||
## Install and Trust the Certificate
|
||||
|
||||
Without the Proxyman root certificate, you will usually only see CONNECT tunnels or TLS handshakes instead of decrypted HTTPS requests.
|
||||
|
||||
Official references:
|
||||
|
||||
- Windows certificate installation: [https://docs.proxyman.com/proxyman-windows/install-certificate](https://docs.proxyman.com/proxyman-windows/install-certificate)
|
||||
- SSL troubleshooting: [https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response](https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response)
|
||||
|
||||
### Recommended Path: Install Automatically
|
||||
|
||||
In Proxyman, run:
|
||||
|
||||
```plaintext
|
||||
Certificate -> Install Certificate on this Windows...
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
1. Choose `Install & Trust`
|
||||
2. Approve the administrator prompt
|
||||
|
||||
According to the official documentation, Proxyman uses Windows `certutil` to import the root certificate into the trusted store.
|
||||
|
||||
### Prepare a PEM File for Node and Electron
|
||||
|
||||
Some Node.js and Electron traffic needs more than system trust. You may also need to point the runtime at the PEM file:
|
||||
|
||||
```plaintext
|
||||
%APPDATA%\Proxyman\certificate\certs\ca.pem
|
||||
```
|
||||
|
||||
If you only see `ca.cer` and not `ca.pem`, confirm that Proxyman has generated the PEM variant before moving on.
|
||||
|
||||
## Verify That Proxyman Works
|
||||
|
||||
Do this before trying to debug any application-specific flow.
|
||||
|
||||
### Verify Browser Traffic
|
||||
|
||||
1. Open Proxyman.
|
||||
2. Visit any HTTPS page in a browser, for example:
|
||||
|
||||
```plaintext
|
||||
https://httpbin.org/get
|
||||
```
|
||||
|
||||
3. Confirm that the request and response appear in Proxyman.
|
||||
|
||||
### If You Cannot See Any Traffic
|
||||
|
||||
Check these first:
|
||||
|
||||
- Proxyman is actually listening on the expected port
|
||||
- Windows proxy settings are pointing to Proxyman
|
||||
- A VPN, endpoint security agent, or antivirus is not taking over proxy behavior
|
||||
- The certificate is trusted
|
||||
|
||||
If localhost traffic is missing, see:
|
||||
|
||||
- [https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server](https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server)
|
||||
|
||||
The official page includes macOS-specific examples, but the localhost bypass concept is still relevant on Windows.
|
||||
|
||||
## Basic Troubleshooting
|
||||
|
||||
### HTTPS Bodies Are Missing
|
||||
|
||||
Common causes:
|
||||
|
||||
- The Proxyman root certificate is not actually trusted
|
||||
- The target process was already running before the certificate was installed
|
||||
- The application uses SSL pinning
|
||||
|
||||
### Certificate Is Installed but TLS Still Fails
|
||||
|
||||
Common causes:
|
||||
|
||||
- You imported `ca.cer` but did not provide `ca.pem` to the runtime when needed
|
||||
- A corporate proxy, VPN, or security product is overriding the network path
|
||||
- The target application uses SSL pinning
|
||||
|
||||
### Localhost Traffic Is Missing
|
||||
|
||||
Common cause:
|
||||
|
||||
- Local loopback traffic is bypassing the proxy
|
||||
|
||||
Official reference:
|
||||
|
||||
- [https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server](https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server)
|
||||
|
||||
## Next Step
|
||||
|
||||
Once Proxyman is installed, trusted, and verified, continue with:
|
||||
|
||||
- [Proxyman Debugging Guide](./proxyman-debugging.md)
|
||||
|
||||
## References
|
||||
|
||||
- Proxyman download page: [https://proxyman.com/download](https://proxyman.com/download)
|
||||
- Proxyman Windows page: [https://proxyman.com/windows](https://proxyman.com/windows)
|
||||
- Proxyman Windows certificate guide: [https://docs.proxyman.com/proxyman-windows/install-certificate](https://docs.proxyman.com/proxyman-windows/install-certificate)
|
||||
- Proxyman localhost troubleshooting: [https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server](https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server)
|
||||
- Proxyman SSL troubleshooting: [https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response](https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response)
|
||||
# Proxyman Installation and Basic Setup on Windows
|
||||
|
||||
This guide covers the Proxyman prerequisites for contributors:
|
||||
|
||||
1. Install Proxyman for Windows
|
||||
2. Trust the Proxyman certificate so HTTPS traffic can be decrypted
|
||||
3. Verify that Proxyman is working before you start debugging Antigravity traffic
|
||||
|
||||
If your goal is to debug the installed Antigravity client or this repository's development build, continue with [Proxyman Debugging Guide](./proxyman-debugging.md).
|
||||
|
||||
## Scope
|
||||
|
||||
This document is intentionally limited to the setup layer. It does not cover Antigravity-specific debugging flows.
|
||||
|
||||
Use it when you need to answer:
|
||||
|
||||
- How do I install Proxyman on Windows?
|
||||
- How do I trust the certificate?
|
||||
- Why can I only see CONNECT requests but not HTTPS bodies?
|
||||
- How do I verify that Proxyman itself is working?
|
||||
|
||||
## Install Proxyman
|
||||
|
||||
Official resources:
|
||||
|
||||
- Download: [https://proxyman.com/download](https://proxyman.com/download)
|
||||
- Windows product page: [https://proxyman.com/windows](https://proxyman.com/windows)
|
||||
|
||||
Recommended steps:
|
||||
|
||||
1. Install the Windows build from the official download page.
|
||||
2. Launch Proxyman.
|
||||
3. Confirm that Proxyman is listening on a local proxy port.
|
||||
4. This guide uses `9090` as the example port. Replace it with your local port if it differs.
|
||||
|
||||
## Install and Trust the Certificate
|
||||
|
||||
Without the Proxyman root certificate, you will usually only see CONNECT tunnels or TLS handshakes instead of decrypted HTTPS requests.
|
||||
|
||||
Official references:
|
||||
|
||||
- Windows certificate installation: [https://docs.proxyman.com/proxyman-windows/install-certificate](https://docs.proxyman.com/proxyman-windows/install-certificate)
|
||||
- SSL troubleshooting: [https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response](https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response)
|
||||
|
||||
### Recommended Path: Install Automatically
|
||||
|
||||
In Proxyman, run:
|
||||
|
||||
```plaintext
|
||||
Certificate -> Install Certificate on this Windows...
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
1. Choose `Install & Trust`
|
||||
2. Approve the administrator prompt
|
||||
|
||||
According to the official documentation, Proxyman uses Windows `certutil` to import the root certificate into the trusted store.
|
||||
|
||||
### Prepare a PEM File for Node and Electron
|
||||
|
||||
Some Node.js and Electron traffic needs more than system trust. You may also need to point the runtime at the PEM file:
|
||||
|
||||
```plaintext
|
||||
%APPDATA%\Proxyman\certificate\certs\ca.pem
|
||||
```
|
||||
|
||||
If you only see `ca.cer` and not `ca.pem`, confirm that Proxyman has generated the PEM variant before moving on.
|
||||
|
||||
## Verify That Proxyman Works
|
||||
|
||||
Do this before trying to debug any application-specific flow.
|
||||
|
||||
### Verify Browser Traffic
|
||||
|
||||
1. Open Proxyman.
|
||||
2. Visit any HTTPS page in a browser, for example:
|
||||
|
||||
```plaintext
|
||||
https://httpbin.org/get
|
||||
```
|
||||
|
||||
3. Confirm that the request and response appear in Proxyman.
|
||||
|
||||
### If You Cannot See Any Traffic
|
||||
|
||||
Check these first:
|
||||
|
||||
- Proxyman is actually listening on the expected port
|
||||
- Windows proxy settings are pointing to Proxyman
|
||||
- A VPN, endpoint security agent, or antivirus is not taking over proxy behavior
|
||||
- The certificate is trusted
|
||||
|
||||
If localhost traffic is missing, see:
|
||||
|
||||
- [https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server](https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server)
|
||||
|
||||
The official page includes macOS-specific examples, but the localhost bypass concept is still relevant on Windows.
|
||||
|
||||
## Basic Troubleshooting
|
||||
|
||||
### HTTPS Bodies Are Missing
|
||||
|
||||
Common causes:
|
||||
|
||||
- The Proxyman root certificate is not actually trusted
|
||||
- The target process was already running before the certificate was installed
|
||||
- The application uses SSL pinning
|
||||
|
||||
### Certificate Is Installed but TLS Still Fails
|
||||
|
||||
Common causes:
|
||||
|
||||
- You imported `ca.cer` but did not provide `ca.pem` to the runtime when needed
|
||||
- A corporate proxy, VPN, or security product is overriding the network path
|
||||
- The target application uses SSL pinning
|
||||
|
||||
### Localhost Traffic Is Missing
|
||||
|
||||
Common cause:
|
||||
|
||||
- Local loopback traffic is bypassing the proxy
|
||||
|
||||
Official reference:
|
||||
|
||||
- [https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server](https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server)
|
||||
|
||||
## Next Step
|
||||
|
||||
Once Proxyman is installed, trusted, and verified, continue with:
|
||||
|
||||
- [Proxyman Debugging Guide](./proxyman-debugging.md)
|
||||
|
||||
## References
|
||||
|
||||
- Proxyman download page: [https://proxyman.com/download](https://proxyman.com/download)
|
||||
- Proxyman Windows page: [https://proxyman.com/windows](https://proxyman.com/windows)
|
||||
- Proxyman Windows certificate guide: [https://docs.proxyman.com/proxyman-windows/install-certificate](https://docs.proxyman.com/proxyman-windows/install-certificate)
|
||||
- Proxyman localhost troubleshooting: [https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server](https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server)
|
||||
- Proxyman SSL troubleshooting: [https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response](https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response)
|
||||
Reference in new issue
Block a user