Files
CenaForge/.claude/skills/cenaforge/references/ai.md
T
MateuusandClaude Opus 5.5 b11090ffa3 Skill cenaforge 1.54.0: Clipador (revisão × final, dublagem, falantes, expressões, Equipe de IA)
Dois arquivos novos em references/ (clipper-video.md, clipper-ai-team.md), banco em v17,
seção de expressões, gotchas 180–185 e ponteiros em panel/publishing/ai/tools.

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

7.0 KiB

IA: provedores, login/chave, IA reserva e monitor de uso

Fonte do contrato: doc/ia.md (arquivos, ambiente de cada chamada, o que conta como indisponível, Gemini headless). Não duplique aqui; este arquivo diz onde mexer e o que não quebrar. Sempre pela CLI oficial (claude, codex, gemini, agy), nunca SDK/HTTP direto. antigravity é o 4º provedor (começa desligado).

Onde mexer

Mudança Arquivo(s) Também atualizar
Configurações, cofre, detecção, instalação, login, teste, providerEnv, isAvailabilityError, pausa, readyChain/nextFallback panel/src/lib/ai.ts panel/src/lib/ai.test.ts, doc/ia.md
Agente do painel por provedor (geminiArgs, normalizeGemini, antigravityArgs, normalizeAntigravity, --resume/--conversation, shell liberado), troca de IA ao cair panel/src/lib/agents.ts (prompts.ts, types.ts para AgentProvider) ai.test.ts (argumentos e eventos do Gemini)
Execução que continua outra que caiu coluna agent_runs.fallback_of (migração v10 em panel/src/lib/db.ts), followUpRunOf (segue resume_of e fallback_of) publishing-db.test.ts (conta de migrações)
Monitor de uso (leitura sem gastar token, overLimit, usage.json) panel/src/lib/ai-usage.ts (refreshUsage, ensureUsageMonitor, normalizeClaude), overLimit em lib/ai.ts; refreshUsage({maxAgeMs: 60_000}) nos 4 pontos que chamam startRun (actions.ts, api/agent/runs, api/stories, api/characters/[id]/agent); juiz: AiConfig.over_limit em clipper/app/ai_settings.py ai.test.ts, test_ai_fallback.py, doc/ia.md
API panel/src/app/api/ai/route.ts (GET/PUT /api/ai), .../ai/[provider]/route.ts (POST {action: install|login|verify|test|resume|usage}, PUT/DELETE = chave) guarda Origin/JSON (gotchas, item 125)
Tela panel/src/components/ai-settings.tsx em panel/src/app/settings/ai/page.tsx; seletor de provedor em agent-console.tsx e story-composer.tsx —
Subpáginas de Configurações panel/src/app/settings/{ai,publishing,apps,browser,modes}/page.tsx + layout.tsx; seções em SETTINGS_SECTIONS de components/settings-shell.tsx (o menu lateral sidebar-nav.tsx as lê como children); /settings redireciona para /settings/ai seção nova = entrada em SETTINGS_SECTIONS + pasta
Papéis do juiz (varredura/analista/editor/juiz de contexto, cada um com provedor+modelo+raciocínio+instruções; reserva por papel) clipper/app/roles.py, judge.py (Judge.ask(role=…)), panel/src/components/clipper-ai-team.tsx — clipper-ai-team.md clipper/tests/test_roles.py
Juiz do Clipador (3 provedores, reserva por chamada) clipper/app/judge.py (_gemini, find_gemini, parse_gemini_output), leitura de settings e cofre clipper/app/ai_settings.py (DPAPI por ctypes), main.py, config.py, intel.py clipper/tests/test_ai_fallback.py, conftest.py, clipper/README.md

Regras

  • Só o painel escreve data/ai/settings.json e data/ai/vault.bin; o Clipador só lê (relê por mtime). Cofre = DPAPI CurrentUser, entropia CenaForge.AI.vault.v1; a chave nunca volta à tela (só "existe" + 4 últimos caracteres). Nunca copie chave para skill, log ou prompt.
  • Chave de API entra só no ambiente da chamada (providerEnv); não troque o login global da CLI.
  • Reserva: erro de indisponibilidade (cota, 429, login, chave, rede, CLI fora, tempo) → a IA entra em pausa (cooldownMin, em memória por processo) e a mesma tarefa recomeça na próxima IA pronta de order. Erro de conteúdo (JSON/schema inválido) não troca. O juiz faz o mesmo por chamada.
  • Gemini no agente: -o stream-json --approval-mode auto_edit --skip-trust, --resume <sessão>, shell só os comandos de GEMINI_ALLOWED_SHELL via --allowed-tools run_shell_command(...). No juiz: -o json --approval-mode plan, prompt pelo stdin, frames copiados para pasta temporária fora do repo (@arquivo respeita o .gitignore).
  • Status de login: claude auth status --json (loggedIn, authMethod, subscriptionType); codex login status (texto, "Logged in using ChatGPT").
  • Instalação: Claude pelo instalador nativo (irm https://claude.ai/install.ps1 | iex); Codex e Gemini por npm install -g. O painel procura também em ~/.local/bin e %APPDATA%\npm.

Monitor de uso e limite

  • Leituras sem gastar token (ai-usage.ts): Claude claude -p "/usage" (texto, US$ 0, modelo <synthetic>) e rate_limit_event de cada execução (normalizeClaude); Codex codex app-server (account/rateLimits/read); Antigravity agy -p "/usage" --output-format stream-json. Gemini CLI: sem leitura, só reativo (429).
  • Renova a cada 5 min (ensureUsageMonitor, ligado pelo GET /api/ai) e antes de cada tarefa (maxAgeMs: 60_000).
  • overLimit (lib/ai.ts): a IA bateu o limite, ou janela ainda valendo >= fallback.usageLimitPercent (padrão 90, faixa 50-100). Leitura com mais de 30 min não decide. startRun troca para a próxima IA livre; em retomada (resume) não troca.
  • O painel escreve data/ai/usage.json; o Clipador lê por AiConfig.over_limit e põe a IA acima do limite depois das livres em fallback_chain. UI: bloco "Uso do limite" por cartão, campo do limite no cartão da reserva, POST /api/ai/[provider] {action:"usage"}.
  • Pronta: IA cujo último teste falhou por indisponibilidade (login/cota) não é "pronta"; Gemini em modo conta só conta como pronto depois de um teste que passou. "Testar" continua habilitado.

Antigravity (agy)

  • agy.exe em ~/.gemini/bin (fora do PATH; AGY_BIN sobrescreve). Sem instalador por linha de comando (install.command null; a UI mostra o site). Login conferido por agy models; atualizar = agy update.
  • Agente: agy -p <prompt> --output-format stream-json --mode accept-edits [--conversation <id>]; shell só por regra exata command(<linha>) via --settings (gotchas 177). Eventos e formatos: doc/ia.md, "Antigravity no painel".
  • Começa desligado. Aviso de termos: a FAQ do Google diz que embrulhar o agy em programa de terceiro "não é suportado" nos planos pessoais; a decisão de ligar é do usuário. O juiz do Clipador não usa antigravity.

Estado verificado (18/11/2026)

  • Nesta máquina: claude 2.1.314, codex 0.169.0, agy 1.5.10 (--version reconferido); gemini não instalado.
  • pnpm --filter cenaforge-panel run test:panel: 117/117 (reexecutado pela skill). ai.test.ts 30 testes (informado). Clipador: 346 passed (informado; reexecutado na 1.52.0).
  • Leituras reais informadas: Claude 4% / 67%; Codex janela de 5 h em 100% (rate_limit_reached), semanal 29%; Antigravity 12% / 5%. "Testar" do Antigravity respondeu "ok" em 15 s.
  • Não verificado: Gemini com chave real, @arquivo de imagem no juiz, envelope de erro do -o json, a UI /settings/ai no navegador, troca de IA no meio de um agente real, troca antecipada por overLimit em tarefa real. Armadilhas: gotchas, itens 168-172 e 175-179.