Gerador de vídeos narrativos (Godot + FFmpeg), painel Next.js, serviço de voz, Clipador de lives e Publicador para YouTube, TikTok e Instagram. Inclui a leitura das visualizações dos posts para o Dashboard e o botão "Publicar no <rede>" nos cartões das publicações. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
83 lines
8.5 KiB
Markdown
83 lines
8.5 KiB
Markdown
# Economia de tokens no CenaForge
|
||
|
||
Mantido pelo agente `cenaforge-token-auditor`. Princípio: o modelo caro decide e revisa; texto
|
||
narrativo vai para modelo mais barato; trabalho mecânico vai para script.
|
||
|
||
## Quem faz o quê
|
||
|
||
| Tarefa | Quem | Por quê |
|
||
|---|---|---|
|
||
| Arquitetura, pipeline de render, depuração, revisão final de entrega | modelo principal | erro aqui custa mais que os tokens |
|
||
| Enredo, bíblia da história, episódios, diálogos, título e opções A/B | `cenaforge-story-writer` (sonnet) | texto criativo não precisa do modelo mais caro; já respeita os limites do JSON |
|
||
| Dezenas de variações de título/opção, resumo de log, classificação | subagente com `model: haiku` | tarefa curta e repetitiva |
|
||
| Interface do painel (design, logo, componentes) | `cenaforge-dashboard-designer` (opus) | decisão do usuário: qualidade visual pede o modelo mais capaz |
|
||
| Atualizar a skill | `cenaforge-skill-updater` | confere fatos sem poluir o contexto principal |
|
||
| Achar onde algo está no código | agente `Explore` | devolve a conclusão, não os arquivos |
|
||
| Achar desperdício e criar scripts | `cenaforge-token-auditor` (sonnet) | — |
|
||
|
||
## Scripts (rode em vez de improvisar comandos)
|
||
|
||
Todos em `.claude/skills/cenaforge/scripts/`, Python 3.10+ só com biblioteca padrão. Rode a
|
||
partir da raiz do repositório.
|
||
|
||
| Script | Substitui | Uso |
|
||
|---|---|---|
|
||
| `runs_summary.py` | ler `report.json`/`render.log` inteiros | `python .claude/skills/cenaforge/scripts/runs_summary.py --last 3 --details` |
|
||
| `inspect_strip.py` | extrair e ler vários quadros soltos | `python .claude/skills/cenaforge/scripts/inspect_strip.py output/runs/<execução>` → lê só `inspect/strip.png` |
|
||
| `new_scene.py` | ler e reescrever o JSON inteiro | `python .claude/skills/cenaforge/scripts/new_scene.py --id <id> --set overlay.title="..." --set rider.travelMeters=36` (cria e valida) |
|
||
| `check_skill.py` | conferir caminhos/comandos da skill à mão | `python .claude/skills/cenaforge/scripts/check_skill.py` |
|
||
| `clean_runs.py` | listar e apagar execuções à mão | `python .claude/skills/cenaforge/scripts/clean_runs.py` (simula) · `--apply` (apaga) |
|
||
| `frame_check.py` | abrir vários quadros/QA para ver se a cena ficou boa | `python .claude/skills/cenaforge/scripts/frame_check.py --last` · `<output/runs/execução>` · `--config data/tmp/<id>-teste.json [--profile preview]` (renderiza e confere). Resume `report.json` e mede cada `inspect/t*.png` (luminância ESCURO < 0,08 / ESTOURADO > 0,92, contraste CHAPADO < 0,04, movimento PARADO < 0,004, enquadramento FORA se o detalhe foge > 30% do centro) e diz qual UMA imagem abrir. Saída 0 ok · 2 atenção · 1 falha |
|
||
| `check_script.py` | reler o roteiro à mão | `python .claude/skills/cenaforge/scripts/check_script.py stories/<história>` (ou um `ep*.md`): mesmas regras do leitor do painel (`script-doc.ts`, 2,5 palavras/s, "Duração:", tabela com 1ª coluna t (s)); avisa narração fora de ±15% do alvo, trecho que não cabe no tempo, buracos, coluna Imagem vazia, `meta.json` (title ≤ 60, logline) e `*.choices.json` (≤ 60, distintas) |
|
||
|
||
## Regras de leitura barata
|
||
|
||
- **Render:** depois do `pnpm render`, leia só o resumo impresso ou `runs_summary.py`. Abra o
|
||
`render.log` apenas se houver falha, e com `grep` (ex.: `grep -E "ERROR|SCRIPT|frames at"`).
|
||
- **Imagens:** uma `contact-sheet.png` ou `strip.png` por verificação, não quadros individuais.
|
||
Recorte ampliado só para checar um detalhe específico.
|
||
- **Testes:** filtre a saída (`pnpm test 2>&1 | grep -E "✖|^ℹ (pass|fail)|passaram|FALHA"`).
|
||
- **Código:** `Grep` com o nome da função antes de ler arquivos inteiros; leia por intervalo de linhas.
|
||
- **Renders:** um render de prévia por iteração; o perfil final só no fim. Não renderize para
|
||
testar algo que os testes headless ou `--validate-only` já cobrem.
|
||
- **Comandos longos de saída** (pnpm install, import da Godot): sempre com `| tail -n 5`.
|
||
- **Imagens, regra dura:** no máximo UMA por render, escolhida pelo `frame_check.py`. Nada de abrir quadros em
|
||
lote nem gerar imagens de QA próprias (ex.: `output/castaways-qa/`): cada imagem fica no histórico e é reenviada
|
||
a cada turno. Medido na execução #8 (Codex, cena Godot): ~100 imagens em resolução cheia → 26 milhões de caracteres
|
||
de saída de ferramenta, 6,83 milhões de tokens de entrada, 54 chamadas, 29 min.
|
||
- **Pesquisa na web (documental):** busque o termo dentro da página e use 3–5 fontes; página aberta inteira custa
|
||
30–40 mil caracteres (execução #6: 1,06 milhão de tokens de entrada).
|
||
- **Retomada (resume)** nas duas CLIs reenvia todo o histórico (vem do cache, mas conta): conversa longa fica cara a
|
||
cada mensagem. Com contexto já grande, abra nova execução com o resumo do que falta.
|
||
|
||
## Custo fixo dos agentes do painel (medido em 17/11/2026)
|
||
|
||
Código: `panel/src/lib/agents.ts`. Detalhes e correções de sintoma em [gotchas.md](gotchas.md) (itens 133–135).
|
||
|
||
| Provedor | O que o painel passa | Efeito medido |
|
||
|---|---|---|
|
||
| Claude CLI | `CLAUDE_LEAN_FLAGS`: `--setting-sources project,local --strict-mcp-config --tools Read,Edit,Write,Glob,Grep,Bash,Agent,Skill,TodoWrite` | prompt trivial no Haiku: 1º turno 62,4 mil → 14,9 mil tokens de entrada só com as flags (18,6 mil com o conjunto completo do painel, que inclui Agent); partida 8,0 s → 4,3 s. Sem as flags carregava plugins/MCP/hooks/skills do usuário (61 ferramentas, 5 MCPs, 310 skills, 78 agentes, 442 comandos). Subagentes do projeto (`.claude/agents`) e a skill `cenaforge` continuam visíveis |
|
||
| Claude CLI | `--max-budget-usd` por tarefa (`CLAUDE_BUDGET_USD`: story 1,5 · script 1,5 · branches 2,5 · scene 1 · godot 3 · free 3) | `error_max_budget_usd` vira "continue a conversa". A CLI não tem `--max-turns` |
|
||
| Codex | `codexLeanOverrides`: `-c model_reasoning_effort` por tarefa (story/script/branches/godot = medium, scene = low, free = o do `config.toml`), `mcp_servers.<nome>.enabled=false` para cada servidor do `config.toml`, plugins `computer-use@openai-bundled` e `unified-computer-use@openai-bundled` desligados (tira `cua_repl`, ~6,5 mil caracteres por turno) | fixo do Codex ~18–19 mil tokens no 1º turno; `base_instructions` ~21 mil caracteres |
|
||
|
||
Referência de peso: na execução #7 (cena Godot, Opus, US$ 3,09, 26 chamadas) o fixo era ~49 mil tokens por chamada e
|
||
somou 2,8 milhões de tokens lidos do cache — por isso o corte do fixo vale mais que qualquer ajuste de prompt.
|
||
|
||
### Juiz do Clipador (`clipper/app/judge.py`, medido em 17/11/2026)
|
||
|
||
Cada chamada é um processo novo de CLI: 2 por candidato (analista com 6–8 quadros 768×432 + editor só texto). Live de
|
||
3,7 h = 75 candidatos = ~150 chamadas; padrão Codex `gpt-6-luna`, esforço low.
|
||
|
||
| Provedor | O que o juiz passa | Efeito medido |
|
||
|---|---|---|
|
||
| Codex | `codex_lean_overrides(search)`: sem `--search`, `features.{plugins,apps,shell_tool,unified_exec,code_mode_host,sleep_tool,skill_search,tool_suggest,in_app_browser,browser_use}=false` + `computer_use,image_generation,goals,hooks=false`, `mcp_servers.<nome>.enabled=false`, plugins computer-use off, e o `system` num instructions.md temporário via `-c model_instructions_file='<caminho>'` (stdin só com o prompt). Com `--search` saem só os extras e o `system` fica no stdin. `view_image` fica ligado | antes: ~77 mil caracteres fixos (~19 mil tokens: instruções 18 mil, ferramentas 46,5 mil, skills/apps ~12 mil) ≈ 2,9 mi tokens naquela live, a mesma cota que bloqueou o agente do painel. Depois: instruções 105 caracteres, ferramentas 29 mil (sobram `exec` e `collaboration`, que `-c` não remove), fixo ≈ 35 mil caracteres (~9 mil tokens, −55%, estimativa). Imagem chega como `input_image`. **Resposta do modelo não validada** (cota esgotada até 16h27 de 17/11) |
|
||
| Claude | `--setting-sources project,local` (além de `--system-prompt`, `--tools`, `--strict-mcp-config`, `--no-session-persistence`) | Haiku: fixo 3,7 → 2,6 mil tokens (−31%), 5,5 → 2,8 s por chamada |
|
||
|
||
Propostas não implementadas (mudam recall; exigem decisão do usuário): na sessão 3, o juiz descartou 33 de 75
|
||
candidatos (44%) e, na origem `face`, 15 de 21 (heurística média 3,07). Opções: pré-filtro por pontuação antes do LLM
|
||
ou juntar analista+editor numa chamada.
|
||
|
||
Os prompts do painel (`panel/src/lib/prompts.ts`) já mandam: godot usa `frame_check.py` e uma imagem por render;
|
||
story/script/branches terminam com `check_script.py`; nenhum agente aciona `cenaforge-skill-updater` nem
|
||
`cenaforge-token-auditor`. `CLAUDE_ALLOWED_TOOLS` libera `frame_check.py` e `check_script.py` via Bash.
|