Files
CenaForge/doc/ia.md
T
MateuusandClaude Opus 5.5 20a9805d2a Clipador: fontes em inglês (juízes em inglês, painel em português) e monitor de uso da IA
Clipador em inglês (doc/clipador/IDIOMAS.md):
- Fonte en-US: analista, editor e varredura com prompts, glossário de chat e saída em inglês;
  a mesma resposta traz o bloco `pt` (tradução para o painel, sem chamada extra).
- Fala do corte traduzida por frase (clips.translation_json, migração v13) e
  POST /v1/clips/{id}/translate.
- caption.translation (só para desenvolver): português embaixo da legenda em inglês.
- Risada e gírias do chat em inglês na heurística (LMAO, LOL, 💀, 😭, no way, bruh...).
- Idioma do público → código do Whisper (en-US dava 422 no serviço de voz).
- Painel: bloco "Em português" no corte, análise/resumo em PT, título traduzido na lista,
  coluna "Ao vivo" mostra a gravação ativa da fonte.

IA: monitor de uso do limite (ai-usage) e 4º provedor (Antigravity CLI).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 03:07:09 -03:00

150 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# IA do CenaForge — provedores, login e reserva
> **18/11/2026 — Gemini CLI removido do painel.** O login pela conta pessoal acabou (ver abaixo) e o Antigravity CLI
> (`agy`) o substitui com a mesma conta Google. Os provedores do painel são `claude`, `codex` e `antigravity`. Um
> `settings.json` antigo com `"gemini"` é ignorado. O juiz do Clipador não oferece mais o Gemini na tela; o código
> Python do Gemini (`judge.py`) ficou inativo, porque o painel não liga mais essa IA. As seções sobre o Gemini CLI
> abaixo ficam como histórico do estudo.
Três IAs, sempre pela **CLI oficial** instalada no PC (nunca SDK/HTTP direto):
| Provedor | CLI | Instalação (Windows) | Login com a conta (OAuth) | Chave de API (variável) |
|---|---|---|---|---|
| `claude` | Claude Code (`claude`) | `irm https://claude.ai/install.ps1 \| iex` | `claude auth login` | `ANTHROPIC_API_KEY` |
| `codex` | Codex (`codex`) | `npm install -g @openai/codex@latest` | `codex login` (ChatGPT) | `CODEX_API_KEY` (só no `codex exec`) |
| `gemini` | Gemini CLI (`gemini`) | `npm install -g @google/gemini-cli@latest` | `gemini` interativo → "Login with Google" | `GEMINI_API_KEY` |
> **Gemini + OAuth (verificado em 18/11/2026, gemini-cli 0.68.0):** o login gratuito "Gemini Code Assist for
> individuals" foi encerrado (`IneligibleTierError: UNSUPPORTED_CLIENT`, o Google manda migrar para o Antigravity).
> OAuth só funciona com plano elegível (Code Assist Standard/Enterprise, Workspace). Para conta pessoal, use a
> **chave de API** do Google AI Studio.
Quem usa: os **agentes do painel** (`panel/src/lib/agents.ts`) e o **juiz do Clipador** (`clipper/app/judge.py`).
A configuração fica no painel em **Configurações → IA** (`/settings/ai`).
## Arquivos compartilhados (contrato painel ↔ Clipador)
Ambos em `data/ai/`. Quem escreve é só o painel; o Clipador apenas lê (relê se o `mtime` mudar).
### `data/ai/settings.json` (sem segredo)
```json
{
"version": 1,
"providers": {
"claude": { "enabled": true, "authMode": "oauth" },
"codex": { "enabled": true, "authMode": "oauth" },
"gemini": { "enabled": false, "authMode": "apiKey" }
},
"order": ["claude", "codex", "gemini"],
"fallback": { "enabled": true, "cooldownMin": 15 }
}
```
- `enabled`: a IA pode ser usada (como principal ou reserva). Desligada, nunca é chamada.
- `authMode`: `"oauth"` = a sessão já logada da CLI; `"apiKey"` = a chave guardada no cofre.
- `order`: prioridade da **reserva**. A tarefa usa a IA escolhida (ou a preferida dela); se falhar por
indisponibilidade, tenta a próxima da lista que estiver ligada e pronta.
- `fallback.enabled`: liga a troca automática. `cooldownMin`: depois de uma falha de indisponibilidade, a IA fica
"em pausa" esse tempo e é pulada (cada processo guarda a sua pausa em memória).
- Arquivo ausente ou inválido = padrão acima, com `claude` e `codex` ligados em `oauth` e `gemini` desligado.
### `data/ai/vault.bin` (chaves de API)
Um JSON `{"claude": "sk-ant-…", "codex": "sk-…", "gemini": "AIza…"}` (só as que existirem) cifrado com a
**DPAPI do Windows**, escopo do usuário (`CurrentUser`), entropia `b"CenaForge.AI.vault.v1"`. O arquivo é o blob
cru da DPAPI. Só a mesma conta do Windows nesta máquina abre. A chave **nunca** volta para a tela: a API do painel
só diz se existe e os 4 últimos caracteres.
## Ambiente de cada chamada
Montado a partir do ambiente do processo, por provedor:
| Provedor | `authMode = "oauth"` | `authMode = "apiKey"` |
|---|---|---|
| `claude` | remove `ANTHROPIC_API_KEY` | `ANTHROPIC_API_KEY=<chave>` |
| `codex` | remove `CODEX_API_KEY` | `CODEX_API_KEY=<chave>` |
| `gemini` | `GOOGLE_GENAI_USE_GCA=true`, remove `GEMINI_API_KEY` | `GEMINI_API_KEY=<chave>`, remove `GOOGLE_GENAI_USE_GCA` |
Assim o login global de cada CLI não é tocado: o modo chave só vale para a chamada.
## O que conta como "indisponível" (dispara a reserva)
Falha que não é culpa do pedido: limite de uso ou cota (`rate limit`, `429`, `quota`, `usage limit`,
`credit balance`), sobrecarga (`overloaded`, `529`, `503`, `unavailable`), login ou chave (`401`, `403`,
`unauthorized`, `not logged in`, `invalid api key`, `IneligibleTier`), rede (`ECONN`, `ETIMEDOUT`, `ENOTFOUND`,
`network`), CLI que não iniciou ou não foi encontrada, e tempo esgotado. Erro de conteúdo (JSON inválido, schema)
**não** troca de IA.
## Gemini CLI em modo headless (0.68.0)
- Agente: `gemini -p <prompt> -o stream-json --approval-mode auto_edit --skip-trust [-m <modelo>] [--resume <sessão>]`.
- Eventos JSONL: `init {session_id, model}`, `message {role, content, delta}` (texto do assistente chega em
pedaços), `tool_use {tool_name, tool_id, parameters}`, `tool_result {tool_id, status, output, error}`,
`error {severity: warning|error, message}`, `result {status, error?, stats}`.
- Respostas estruturadas (juiz): `-o json` devolve `{"response": "<texto>", "stats": …}`; não há `--output-schema`,
então o schema vai no prompt e o JSON é extraído do texto. Leitura somente: `--approval-mode plan --skip-trust`, rodando numa pasta temporária fora do repositório (o `@arquivo` respeita o `.gitignore`).
- Modelos: `gemini models -o json` (não exige login).
- No Windows o npm instala `gemini.cmd`; rode `node <prefixo npm>/node_modules/@google/gemini-cli/bundle/gemini.js`.
## Estudo: uso e limites de cada IA pela CLI (18/11/2026)
Objetivo: mostrar quanto de cada IA já foi usado, trocar de IA ANTES de bater o limite e, se bater, mostrar o
uso e quando volta. Medido nesta máquina (claude 2.1.314, codex-cli 0.169.0, gemini-cli 0.68.0).
| IA | Como ler o uso | Custo da leitura | O que vem |
|---|---|---|---|
| Claude (assinatura) | `claude -p "/usage" --output-format stream-json --verbose` | **zero** (modelo `<synthetic>`, 0 tokens, US$ 0) | texto: "Current session: 2% used · resets …", "Current week (all models): 67%", "Current week (Fable): 24%" |
| Claude (em toda execução) | evento `rate_limit_event` do stream-json (vem logo após o `init`) | zero (já vem junto) | `unifiedWindows.five_hour/seven_day.utilization` (0–1), `resetsAt` (epoch), `status` (`allowed`…), `overageStatus`, `isUsingOverage` |
| Codex (ChatGPT) | `codex app-server` (JSON-RPC por stdin): `initialize` → `initialized` → `account/rateLimits/read` | **zero** (não roda modelo) | `primary` (janela 300 min) e `secondary` (10080 min): `usedPercent`, `resetsAt`; `ordinaryUsageAllowed`, `rateLimitReachedType`, `planType`, créditos de reset grátis |
| Codex (histórico) | `~/.codex/sessions/AAAA/MM/DD/rollout-*.jsonl`, evento `token_count.rate_limits` (`limit_id: "codex"`) | zero | mesmo conteúdo, com a hora em que foi gravado |
| Gemini (chave) | não há consulta de cota restante pela CLI nem pela API do AI Studio | — | só reativo: erro 429 `RESOURCE_EXHAUSTED`; o CLI distingue `RetryableQuotaError` (por minuto, traz `retryDelay`) de `TerminalQuotaError` (cota do dia acabou) |
Observações:
- No teste, o Codex estava com a janela de 5 h em **100%** (`rate_limit_reached`, `ordinaryUsageAllowed: false`):
com a leitura prévia, o painel o teria pulado em vez de esperar a falha.
- Cuidado no Git Bash: `/usage` vira caminho (`C:/Program Files/Git/usage`) e a CLI cobra uma resposta normal.
O painel chama sem shell, então não é afetado; no terminal use `MSYS_NO_PATHCONV=1`.
- `claude -p "/usage"` devolve texto em inglês, com datas no fuso local: o parser precisa ser tolerante e
preferir o `rate_limit_event` (estruturado) quando houver execução recente.
- Gemini com chave: contar nós mesmos as requisições e tokens do dia (o `result` do stream-json traz `stats`) e
pausar até o reset diário quando vier `TerminalQuotaError`.
### Implementado (18/11/2026)
- `panel/src/lib/ai-usage.ts`: leitura do Claude (`/usage` + `rate_limit_event` de cada execução) e do Codex
(`app-server`), monitor de 5 min (liga ao abrir Configurações → IA) e releitura antes de cada tarefa (> 60 s).
- `overLimit` (lib/ai.ts): bateu o limite ou janela ainda valendo ≥ `fallback.usageLimitPercent` (padrão 90) →
a tarefa nova começa na próxima IA livre; leitura com mais de 30 min não decide.
- `data/ai/usage.json` (escrito pelo painel): `{updatedAt, limitPercent, providers: {<ia>: {at, windows[], blocked, …}}}`.
O juiz do Clipador lê (`AiConfig.over_limit`) e põe a IA perto do limite depois das livres.
## Gemini pela conta: Antigravity CLI (pesquisa de 18/11/2026)
- O gemini-cli não aceita mais conta pessoal (nem AI Pro/Ultra) desde 18/06/2026; Code Assist Standard/Enterprise
não vende assinatura nova desde 09/10/2026. Fonte: developers.google.com/gemini-code-assist/docs/deprecations/code-assist-individuals
- Substituto oficial: **Antigravity CLI** (`%USERPROFILE%\.gemini\bin\agy.exe`, 1.5.10 nesta máquina, fora do PATH).
Headless parecido com o Claude: `agy -p <prompt> --output-format stream-json --mode accept-edits [--model] [--effort]
[--conversation <id>]`; `agy models` funciona com a conta logada (Gemini 4, Gemini 3.8 Flash, Claude, GPT-OSS).
- **Termos:** a FAQ (antigravity.google/docs/faq) diz que embrulhar o `agy` em app de terceiro "is not supported
under consumer plans"; recomenda chave do AI Studio ou Gemini Enterprise. Respostas de funcionários no fórum se
contradizem. Zona cinza: decisão do usuário.
- Os três pontos que estavam em aberto (saída sem TTY, edição com `accept-edits`, formato do stream-json) foram
testados e funcionam: ver "Antigravity no painel" abaixo.
### Antigravity no painel (implementado em 18/11/2026, agy 1.5.10)
Testado de verdade nesta máquina (prompts mínimos, conta Google logada):
- **Sem terminal funciona:** `agy -p "…" --output-format stream-json` chamado pelo Node respondeu em ~6 s.
- **Eventos:** `{"event":"init","conversation_id"}`, `step_update` (`step_type`: `user_input` | `agent_response` com
`text_delta` | `tool` com `tool_name`, `tool_info.parameters` e `state` ACTIVE/DONE/ERROR; `usage` por passo) e
`{"event":"result","result":{status:"SUCCESS",response,num_turns,usage}}`. Retomada: `--conversation <id>`.
- **Edição:** `--mode accept-edits` grava arquivos sem pedir.
- **Shell:** só com `--settings '{"permissions":{"allow":["command(<linha exata>)"]}}'` (vale só na sessão).
Testado: `command(node --version)` libera exatamente essa linha; prefixo, `command(node)`, `command(node:*)` e
`command(node -e *)` NÃO liberam. O que não estiver liberado é recusado (passo `ERROR` + aviso `jetski:` no
stderr; o processo sai com 0). Não usamos `--dangerously-skip-permissions`.
- **Uso, sem cota:** `agy -p "/usage" --output-format stream-json` → `{"event":"command_result","command":{"name":"usage",
"data":{"groups":[{"name":"Gemini Models","buckets":[{"window":"5h"|"weekly","remaining_fraction":0.88,"reset_time"}]},
{"name":"Claude and GPT models",…}]}}}`. O painel usa o grupo Gemini (modelos padrão do agente).
- **Login:** `agy models` só lista com a conta logada (sem gastar cota); "Entrar com a conta" abre `agy` interativo.
- **Modelos:** `agy models` → linhas `id<TAB>nome` (18 nesta conta), depois de uma linha "Fetching available models...".
- Começa **desligado**; o juiz do Clipador ainda não usa o Antigravity (só agentes do painel).