Files
CenaForge/.claude/skills/cenaforge/references/publishing.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

23 KiB
Raw Blame History

Publicação em YouTube, TikTok e Instagram (Publicador + despachante do painel)

Fonte completa: doc/publicacao/PLANO.md (contrato HTTP do Publicador §3, banco §4, despachante §5, telas §6) e doc/publicacao/PESQUISA.md (fatos das plataformas, datados de 17/11/2026, reverificar a cada 3 meses). Instalação, apps das redes e regras do modo sessão: publisher/README.md. Aqui só o que um agente precisa para agir.

Quem faz o quê

Painel (4500) = cérebro ──► Publicador (4530) = executor ──► YouTube / TikTok / Instagram
 canais, regras, fila        cofre DPAPI, OAuth, perfis de        API oficial  OU  Chrome/Edge via CDP (4540–4549)
 publish_jobs, laço 20 s     navegador, jobs (um por vez)
       └──► Clipador (4520): lê cortes ready/approved (GET /v1/clips?channel=&status=&ids=), aprova e marca published
  • Despachante: panel/src/instrumentation.ts → startDispatcher (lib/dispatcher.ts, TICK_INTERVAL_MS 20 s, guarda em globalThis contra laço duplo no HMR) → dispatcherTick (lib/publishing.ts, que ao carregar troca dispatcherState().tick pela versão nova: sem isso o laço usa as regras antigas, gotchas 141). Só publica com o pnpm panel aberto (o painel é do usuário: não inicie nem encerre).
  • Publicador (publisher/, Python 3.12 FastAPI): não conhece canal, história nem corte; recebe arquivo + metadados + profileId (<accountId>--<platform>). Toda rota exige X-Service-Key (PUBLISHER_SERVICE_KEY em publisher/.env), exceto GET /health e GET /oauth/callback/{platform} (validada por state). Dados em data/publisher/ (publisher.db, vault.bin DPAPI, browser/<profileId>/, logs/ com capturas das falhas).
  • Subir: pnpm dev (sobe depois do Clipador; sem publisher/.venv ou chave, pula com aviso). Instalar: setup.bat (passo 6b2 do scripts/setup.ps1). Testes: pnpm test:publisher (pytest, sem rede nem navegador) e pnpm --filter cenaforge-panel test:panel (node:test via tsx em panel/src/lib/*.test.ts, banco temporário por CENAFORGE_ROOT). Typecheck do painel: pnpm --filter cenaforge-panel typecheck.

Onde mexer

Mudança Arquivo(s)
Contrato HTTP, fila, cofre, OAuth publisher/app/ (main.py rotas, service.py regras, worker.py fila, vault.py, db.py (v2: jobs.client_ref UNIQUE), paths.py (file/cover só de output/, stories/, assets/; data/ recusado), acl.py (ACL de data/publisher só para o usuário), config.py)
API oficial de uma rede publisher/app/platforms/{youtube,tiktok,instagram}_api.py
Modo sessão (navegador) publisher/app/platforms/session/ (browser.py abre Chrome/Edge normal com --user-data-dir e --remote-debugging-port, confere a porta pelo DevToolsActivePort do perfil ou, se o Chrome 157+ não o gravar (porta fixa), pela marca CenaForgeWindow.json + PID que escuta (owns_port, listener_pid; gotchas 137), fecha a janela (IDLE_CLOSE_S/LOGIN_IDLE_CLOSE_S); runner.py (_with_page conecta com connect_over_cdp(..., is_local=True): sem isso arquivo > 50 MB é recusado, gotchas 139; browser_error_text(detail) traduz o PlaywrightError em frase específica (clique com timeout, timeout, arquivo > 50 MB, janela fechada) ou, no resto, "O navegador travou ou mudou de página"; o "Detalhe" técnico vem depois); common.py: step_pause, fill_text, click_through, dismiss_tips, TIP_BUTTONS, screenshot, prune_screenshots); seletores no dicionário SELECTORS de youtube_studio.py, tiktok_studio.py, instagram_web.py
Cliente do Publicador no painel panel/src/lib/publisher.ts
Regras puras (horário bom, limite, ações do job, sincronização de cortes, leitura do resultado, reencaixe, idempotência) panel/src/lib/publishing-rules.ts (placeJob, nextFreeSlot, planClipSync, readPublisherJob, jobActions, aiGeneratedFor, tagsFromCaption, needsReflow/STALE_AFTER_MS, clientRefFor, mayBeLive, parseVideoUrl) + publishing-rules.test.ts
Fila, aprovação, envio, episódio panel/src/lib/publishing.ts (approveJob, placeApproved, retryJob, sendDue, promoteDue, pollPublishing, finishFromPublisher, markPublished) + publishing-db.test.ts
Pausar tudo, horários bons, fuso panel/src/lib/settings.ts (tabela app_settings)
Banco panel/src/lib/db.ts: v5 (account_networks reconstruída sem mock, publish_jobs, publications com clip_id/job_id, app_settings, clip_auto_approvals, colunas novas em accounts e episodes), v6 (publish_jobs reconstruída: schedule_source auto/manual/now, cancel_reason aceita unlinked) e v7 (publish_jobs.origin link/manual, padrão link)
"Publicar" no cartão do corte (sem fonte ligada) UI panel/src/components/clip-publish.tsx (ClipPublishButton + diálogo; usado em clipper-queue.tsx, em approved e, como "Publicar em outra rede", em published; useClipPublishing().reload()); cliente publishClip em publishing-client.ts; rota POST /api/publishing/clips/[id] (app/api/publishing/clips/[id]/route.ts); servidor publishClip em publishing.ts
Guarda da API do painel panel/src/proxy.ts (Next 16: o middleware se chama proxy; checkRequest exportado) + proxy.test.ts; readJson em panel/src/lib/http.ts (415 sem JSON)
Rotas /api/settings e /api/settings/apps/[platform], /api/publisher/status, /api/publishing/jobs[/[id][/[action]]], /api/publishing/summary, /api/episodes/[id]/approve, `/api/accounts/[id]/networks/[platform]/(connect
Telas /accounts "Canais de publicação" (account-manager.tsx, account-networks.tsx, connect-wizard.tsx), /publishing "Publicações" (publishing-board.tsx, publishing-client.ts), /settings "Configurações" (settings-panel.tsx)
Modal novo (qualquer tela) Dialog + Steps de panel/src/components/dialog.tsx (<dialog> nativo, foco preso, Esc fecha). Confirmação simples continua em askConfirm (panel.md)
Avisos e chips de estado por rede NoticeBar e PublishChips em panel/src/components/publishing-ui.tsx

Botões de um job vêm de actions[] da API (jobActions no servidor); a UI não decide sozinha o que oferecer. No texto visível do Clipador "Canais" virou "Fontes"; código, tabelas e rotas continuam channels.

Regras que não podem quebrar

  • Nunca published sem ID/URL remota (ou rascunho confirmado). done sem link ⇒ failed com aviso para conferir na rede antes de "Tentar de novo" (evita publicar duas vezes). Publicador fechado no meio de um envio ⇒ failed "interrompido — tente de novo": também conferir na rede.

  • Aprovar vale para o vídeo inteiro (todas as redes e canais daquela origem); tirar uma rede = cancelar o job dela.

  • Aprovação automática (accounts.approval_mode = 'auto') só pega cortes criados depois de ligá-la (accounts.auto_since) e depois de a fonte ser ligada ao canal. Episódio sempre precisa do clique "Aprovar para publicar" (exige render final).

  • "Na hora" (timing = 'now') respeita o limite diário (account_networks.daily_limit); passou do limite, agenda no próximo horário bom.

  • publishAt nativo do YouTube não é usado (o painel manda null); o agendamento é do despachante.

  • Modo sessão viola os termos das três redes: a UI exige marcar "Entendi o risco". Proibido stealth/patchright/ stealth.js, resolver captcha ou digitar senha; login, captcha ou checkpoint ⇒ needs_login e o usuário resolve. Não rode playwright install (só o driver; o navegador é o Chrome/Edge do usuário).

  • Segredos nunca voltam ao navegador (só configured: true/false) e nunca vão para logs nem para esta skill.

  • Idempotência: o painel manda clientRef = "<publish_jobs.id>:<attempts>"; o Publicador devolve 200 com o job existente (201 = novo). attempts só sobe em "Tentar de novo"/reaprovação. Timeout, conexão caída, 5xx ou 401/403/404 ao criar ⇒ o job fica na fila e reenvia com o mesmo clientRef; outro 4xx ⇒ failed.

  • mayBeLive (falhou depois de chegar ao Publicador): POST /api/publishing/jobs/<id>/retry sem {confirm: true} ⇒ 409; a UI pergunta "Confira na rede se o vídeo já saiu". Agente não manda confirm: true sem o usuário ter conferido.

  • Agendamento automático vencido há > 30 min (painel fechado) é reencaixado no próximo horário bom; horário manual, "Publicar agora" e "Tentar de novo" saem como estão.

  • Encerrar fonte/história cancela os jobs não enviados (unlinked); religar zera linked_at (a automática não pega cortes do intervalo desligado). Cancelar no meio de um ciclo vale (UPDATEs condicionais; se o Publicador já criou o envio, o painel cancela lá). Aprovação automática é registrada em clip_auto_approvals antes do PATCH no Clipador.

  • Botão "Publicar" do corte (POST /api/publishing/clips/<id>, corpo {accountId, platforms[], timing?: "now"|"best_slot"}, resposta {jobs, skipped[{platform, reason}], placed}; publishClip): serve para corte aprovado cuja fonte não está ligada a canal (account_channels) ou para outra rede. O clique é a aprovação humana. timing omitido = o do canal. "now" força queued com schedule_source='now' e ignora o limite do dia. Job existente cancelado, failed ou needs_login é reaproveitado (attempts+1 via placeApproved, que ganhou opts.timing); rede não conectada, pausada, já publicada, na fila, agendada, enviando ou "pode ter saído" (mayBeLive) entra em skipped com motivo. O diálogo lista essas redes bloqueadas com o motivo. Título e legenda são os do cartão.

  • publish_jobs.origin: link (criado pelo vínculo fonte↔canal) ou manual (botão "Publicar"). Job manual não é cancelado por "fonte desligada" (planClipSync com ExistingJob.origin, linkActive, accounts.endChannel só cancela origin = 'link'); corte editado, rejeitado ou apagado ainda cancela o job. Armadilha de migração: gotchas 138.

  • Rótulo de IA: se não der para ler a voz do episódio, vai ligado por cautela. Corte (source_kind = 'clip') nunca leva o rótulo, nem com o canal em "always" (sendDue; gotchas 148).

  • "Apaguei na rede" (removed): POST /api/publishing/jobs/<id>/removed; markRemoved (publishing.ts) aceita só published, volta o job a canceled/user, zera url/remote_id/published_at e apaga a publications do job; jobActions de published = ["removed"]; cliente markJobRemoved; botão em Publicadas com confirmação. O painel não apaga nada na rede (apague lá primeiro); depois "Publicar" no corte reenvia com attempts+1. Gotchas 149.

  • Modo sessão: a janela fecha depois de cada envio e do "Já entrei" (pede saída limpa, mata após 10 s); fica aberta se a rede pedir login/captcha; ociosa fecha em 5 min (15 min se aberta para login). Capturas só da área visível, nunca em login/captcha, apagadas após 7 dias. Ritmo: "intervalo mínimo entre envios" (30 s, publisher/README.md).

  • Segurança do Publicador: ACL de publisher/.env e data/publisher/ restrita ao usuário (setup.ps1 + acl.py); code_verifier do PKCE só em memória; loggers httpx/httpcore silenciados (o token do Instagram vai na URL).

  • Link do vídeo no TikTok (find_video_url(page, caption, sleep, attempts=12, reads=5, progress) em tiktok_studio.py): a lista "Publicações" (/tiktokstudio/content) não se atualiza sozinha e o vídeo novo só entra depois de processar. Espera 5 s; a cada tentativa abre ou recarrega CONTENT_URL e lê 5 vezes (a cada 3 s); até 12 cargas (~3 min), com progresso "Publicado. Esperando o vídeo aparecer na lista do Studio… (n de 12)". Só aceita o link cuja linha (até 10 ancestrais do <a>) contém caption_key(caption) (primeiros 24 caracteres da legenda sem #hashtags e @menções): nunca devolve o link de outro vídeo. Sem achar, PublishResult sem link e step "Publicado no TikTok (Studio), mas o vídeo não apareceu na lista do Studio em ~3 min; link não encontrado" ⇒ job failed (regra "nunca published sem URL"). No painel, readPublisherJob (publishing-rules.ts) reconhece done sem link com step começando em "Publicado no " e diz "Saiu na rede, mas o link do vídeo não apareceu a tempo… use 'Já saiu: informar o link' (não use 'Tentar de novo')". Não há seletor video_link (links relativos). Gotchas 140 e 143.

  • "Já saiu: informar o link" (mark-published): POST /api/publishing/jobs/<id>/mark-published com {url} (markPublished em publishing.ts; MarkPublishedDialog em publishing-board.tsx; cliente markJobPublished; PublishJobAction ganhou "mark-published"). Aparece em job failed (sempre; botão principal se mayBeLive) e needs_login (só se mayBeLive). parseVideoUrl(platform, url) (publishing-rules.ts) valida e devolve {url, remoteId}: TikTok /@conta/video/<id>; YouTube shorts, watch?v= ou youtu.be, normalizado para /shorts/<id>; Instagram reel(s) ou p; outro formato ou rede ⇒ erro. Faz UPDATE condicional para published com url e remote_id, recordPublication (registro real) e kickDispatcher (marca o corte published no Clipador). Use só depois de conferir na rede que o vídeo está lá; o agente não inventa o link.

  • Primeiro envio real (TikTok, modo sessão, 17/11/2026 13:35): público, https://www.tiktok.com/@vortplay/video/7709179978520284437 (informado; login, upload, legenda, privacidade e "Publicar" funcionaram com conta real). O job terminou failed por falta do link (gotchas 140) e foi marcado como publicado pela rota acima. Seletores do TikTok validados nesse envio; YouTube e Instagram em modo sessão: só o ensaio sem publicar (próxima regra); YouTube segue sem validação.

  • Instagram em modo sessão (publisher/app/platforms/session/instagram_web.py; layout novo de 17/11/2026, barra lateral só de ícones). Fluxo: o botão é <a> com <svg aria-label="Postar"> e abre DIRETO o diálogo "Criar novo post" (sem submenu; create_post só para o layout antigo), com o input[type=file] dentro do diálogo.

    • SELECTORS["create"] aceita "Postar" (svg, link, botão); erro: "o botão Postar".
    • next, share e reels_notice_ok são CSS presos a _DIALOG (div[role='dialog']): no feed cada post tem um botão de ícone "Compartilhar" e o seletor global podia clicá-lo (teste test_buttons_of_the_flow_are_searched_inside_the_dialog).
    • Envio dividido: prepare(page, spec, progress, sleep) faz tudo até devolver o locator do Compartilhar sem clicar; upload chama prepare, clica e espera "compartilhado". Todo clique passa por click_through.
    • Rótulo de IA: input type=checkbox role=switch SEM nome acessível, direto no painel (não em "Configurações avançadas", que só abre como plano B do layout antigo). find_ai_switch casa a linha (AI_ROW_TEXT, até 6 ancestrais por innerText); _is_on lê aria-checked/is_checked; confere de novo depois do clique e, se não ligou, PublishError (não publica sem o rótulo). Sem clique forçado (gotchas 145).
    • Formato "Original" (keep_original_shape(page, sleep), chamada em prepare antes dos "Avançar"): a etapa "Cortar" vem em 1:1 e cortaria o vídeo vertical (o 1º reel real saiu quadrado, gotchas 147). Clica em svg[aria-label='Selecionar corte']/'Select crop' no diálogo e escolhe "Original" (SELECTORS["crop_toggle"], ["crop_original"]; opções Original, 1:1, 9:16, 16:9) e fecha o menu. Sem o ícone ⇒ PublishError, nunca publica cortado.
    • close_suggestions(page, text): legenda terminando em #tag/@menção ganha um espaço no fim (Esc fecharia a caixa).
    • Link do reel: o endereço não muda após compartilhar. find_reel_url(page, caption, sleep, attempts=6, per_load=3, progress) acha o link do perfil (_PROFILE_HREF_JS: /<conta>/ com textContent "Perfil" ou foto do perfil no alt; a barra recolhida esconde o texto), abre /<conta>/reels/, abre os 3 mais novos ainda não conferidos e aceita o primeiro cuja página contém caption_key(caption) (agora em common.py, também usada pelo TikTok); recarrega até 6 vezes, 20 s entre elas (~3 min). MEDIA aceita /<conta>/reel/<código>/. Sem link ⇒ PublishResult sem URL ⇒ job failed ⇒ "Já saiu: informar o link".
    • Ensaio sem publicar (jeito seguro de validar seletores com conta real): rodar prepare com o navegador do perfil, conferir o resultado e descartar o rascunho ("Descartar"); nunca clicar em Compartilhar sem pedido do usuário.
    • Validado ao vivo (informado, 17/11/2026, ensaio com ai_generated=True): Postar, arquivo clip-29.mp4, Avançar ×2, legenda "…#teste" intacta, rótulo de IA LIGADO, Compartilhar achado e não clicado, rascunho descartado, 0 diálogos no fim. _PROFILE_HREF_JS voltou /vortplay27/. Não validados com conta real: clique em Compartilhar, a confirmação "compartilhado" e find_reel_url (a conta ainda não tinha reels). Só vale depois de reiniciar o pnpm dev.
  • Avisos de novidade do site (modo sessão): o TikTok Studio abre avisos por cima da página ("Veja a prévia do seu vídeo no seu celular" → Entendi) que bloqueiam cliques. Todo clique do tiktok_studio.py passa por click_through (timeout 8 s; se falhar, dismiss_tips fecha os avisos e tenta de novo; sem aviso, relança o erro) e dismiss_tips roda antes da legenda e antes de "Publicar". TIP_BUTTONS só aceita ^(Entendi|Entendido|Ok, entendi|Got it)$: nunca aceitar ou recusar opções por esse caminho, só fechar avisos. Gotchas 142.

Fatos das plataformas (resumo; detalhe e fontes em doc/publicacao/PESQUISA.md)

  • YouTube: projeto não verificado já publica público (desde 02/11/2026); videos.insert 100 envios/dia; app em "Testing" perde a autorização em 7 dias (pôr "In production").
  • TikTok: sem auditoria, Direct Post só SELF_ONLY (conta privada) ou rascunho (até 5 pendentes/24 h); auditoria para uso próprio provavelmente negada.
  • Instagram: conta Profissional; conta própria sem App Review; token colado (a Meta não aceita redirect localhost), vale 60 dias, renovado quando faltam < 10; rupload com arquivo local via graph.instagram.com ainda a testar.

Evidência (17/11/2026)

Depois das revisões de segurança e correção, reconferido pela skill: pnpm test:publisher → 71 passed (depois da correção do Chrome 157, informado: 73 passed; gotchas 137); pnpm --filter cenaforge-panel test:panel → 59/59; typecheck do painel e da raiz sem erro (informados também: test:launcher 17/17, test:clipper 270 passed). Bancos reais: data/cenaforge.db ainda em user_version 5 (a v6 entrava só com o painel reaberto; hoje a 1ª requisição depois da recarga do db.ts migra — gotchas, itens 51 e 138); data/publisher/publisher.db em 2. Não verificado: conexão de qualquer rede pela UI (nos dois modos), envio real, renovação de token, seletores do modo sessão, laço do despachante com o painel ao vivo, fechamento da janela do navegador num envio real.

Botão "Publicar" do corte (informado, 17/11/2026; não reexecutado aqui): typecheck do painel verde; test:panel 63/63, com testes novos em publishing-rules.test.ts ("publicado à mão (origin manual)…") e em publishing-db.test.ts (seção "Publicar" no cartão do corte: job manual com rede não conectada pulada, endChannel não cancela o manual, recusas); teste de migração agora espera a v7. Não testado com conta real. Plano: doc/publicacao/PLANO.md §7c.

Envio de arquivo grande no modo sessão (informado e reconferido, 17/11/2026): a 1ª tentativa real no TikTok chegou ao TikTok Studio logado e falhou em set_input_files (> 50 MB, gotchas 139). Correção is_local=True aplicada; pnpm test:publisher → 73 passed (então). O envio real depois disso funcionou (ver "Primeiro envio real" acima).

Link do TikTok e "Já saiu" (informado, 17/11/2026): pnpm test:publisher → 74 passed (reexecutado na skill; teste novo test_tiktok_link_waits_for_the_list_and_matches_caption em publisher/tests/test_browser.py); test:panel 65/65 e typecheck verdes (informados, não reexecutados); parseVideoUrl em publishing-rules.test.ts, markPublished em publishing-db.test.ts. find_video_url validado ao vivo só de leitura na lista real (informado): a legenda certa devolveu o link, a de outro corte None. find_video_url e is_local só valem depois de reiniciar o pnpm dev.

Espera do link com recarga da lista (informado, 17/11/2026): find_video_url com 12 cargas × 5 leituras; validado ao vivo, só leitura, achou https://www.tiktok.com/@vortplay/video/7709183805373877524 (2º post real, 13:50); o job 1 foi marcado publicado por mark-published. pnpm test:publisher → 76 passed (reexecutado; teste test_tiktok_link_waits_for_the_list_and_matches_caption agora recarrega e confere "2 de 12"). test:panel 65/65 e typecheck verdes (informados, não reexecutados; teste novo da mensagem "Saiu na rede…"). O envio das 13:50 rodou código antigo (gotchas 143): a espera nova ainda não foi exercitada num envio real.

Aviso por cima da legenda (informado e reconferido, 17/11/2026): o 2º envio real no TikTok (captura 20261117-134508) falhou no clique da legenda por causa do aviso "Entendi" (gotchas 142); o upload de 100+ MB passou (is_local valendo). pnpm test:publisher → 76 passed (reexecutado; testes novos test_click_through_closes_tip_and_retries e test_browser_error_text_explains_common_failures). O post não chegou a ser feito; correção não testada num envio real e só vale depois de reiniciar o pnpm dev.

Instagram em modo sessão (informado e reconferido, 17/11/2026): pnpm test:publisher → 78 passed (reexecutado; testes novos test_instagram_links_and_hashtag_suggestions e test_buttons_of_the_flow_are_searched_inside_the_dialog em publisher/tests/test_browser.py). Ensaio ao vivo sem publicar: ver regra "Instagram em modo sessão". O "Já entrei" do usuário falhou porque o Publicador rodava código antigo (gotchas 143): reiniciar o pnpm dev.

1º reel real e formato (informado, 17/11/2026): o reel /reel/Df2cezTNhY7/ (corte 68) saiu 1:1; o usuário o apagou e a página mostra "Esta página não está disponível" (conferido). Corrigido com keep_original_shape (gotchas 147); ensaio sem publicar validou a prévia 9:16 inteira com legenda e rótulo de IA; rascunho descartado. pnpm test:publisher → 78 passed (reexecutado). test:panel 66/66 e typecheck verdes (informados, não reexecutados; teste novo de markRemoved). Formato "Original" só vale depois de reiniciar o pnpm dev; o painel (removed, corte sem rótulo) já vale. Não validado: publicação real com o formato novo.