Files
CenaForge/.claude/skills/cenaforge/references/token-economy.md
T
MateuusandClaude Opus 5.5 84f30bbc2d CenaForge: primeira versão pública
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>
2026-11-17 16:35:09 -03:00

8.5 KiB
Raw Blame History

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 (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.