@afcode/flowconnector

v1.0.2

Published

8 days ago

Flow Connector - Skill e integração automatizada com Google Flow para agentes de IA

0High
0Medium
0Low

afcode

google-flow flowconnector flow-connector veo nano-banana ai-agent antigravity skills automation

Flow Connector

Conector para integração e automação do Google Flow via agentes de IA e linha de comando.

Permite gerar imagens e vídeos em alta definição sem custos adicionais de API por requisição, utilizando a sessão ativa do usuário no navegador e os créditos da assinatura do Google AI (Pro ou Ultra).

O ecossistema opera através da interface CLI (flow-auto), de um serviço daemon de ponte local e da extensão de navegador Flow Connector (para Google Chrome e Microsoft Edge). As mídias geradas são descarregadas e organizadas automaticamente no armazenamento local.

Sumário

Visão Geral e Arquitetura

O Flow Connector realiza automação direta de interface (UI Automation) sobre o Google Flow, simulando interações reais de navegação, digitação, seleção de modelos e carregamento de referências:

Agente de IA / Usuário (CLI)
        │
        ▼ (stdio / IPC)
  flow-auto (CLI)
        │
        ▼ (WebSocket local)
Bridge Daemon (Serviço local em background)
        │
        ▼ (Mensageria interna)
Extensão Flow Connector (Chrome / Edge)
        │
        ▼ (DOM Injection / Event Dispatch)
Aba ativa no Google Flow (flow.google.com)
        │
        ▼ (Download nativo monitorado)
Arquivos salvos em disco local

Componentes do Sistema

flow-auto (CLI): Ponto de entrada para comandos manuais ou disparados por agentes. Gerencia requisições, filas e tarefas.
Bridge Daemon: Serviço executado localmente em segundo plano que orquestra a comunicação entre a CLI e a extensão do navegador.
Extensão Flow Connector: Extensão instalada no navegador (Chrome ou Edge) responsável por traduzir comandos em ações no DOM do Google Flow e monitorar a conclusão dos downloads.
Skill flow-generate: Instruções e diretrizes operacionais em formato SKILL.md para capacitar agentes de IA (como Claude, Gemini, Antigravity, ChatGPT).

Pré-requisitos e Instalação

Requisitos Mínimos

Node.js: Versão 20 ou superior.
Navegador: Google Chrome ou Microsoft Edge (com sessão autenticada no Google Flow).
FFmpeg: Necessário para comandos de mesclagem (flow-auto merge) e pós-processamento de vídeo.
Python 3 + PyTorch: Opcional, necessário apenas para inpainting neural de remoção de marca d'água em imagens (--mode inpaint).

Instalação

Instale a ferramenta globalmente via npm:

npm install -g @afcode/flowconnector

Verifique se a CLI foi instalada com sucesso:

flowconnector --version

Configuração do Ambiente e Navegador

Como o Flow Connector executa automação visual de navegador, não se trata de uma API headless. O navegador renderiza os componentes reais da interface.

Regras Obrigatórias do Navegador

Aba Aberta: A aba do Google Flow deve estar carregada.
Sessão Conectada: O usuário deve estar autenticado com sua conta Google.
Visibilidade Contínua: A aba não pode estar minimizada nem coberta por janelas em tela cheia. Navegadores modernos suspendem a renderização e o temporizador de abas ocultas, o que paralisa a automação.

Disposição Recomendada de Janelas

Em um monitor: Posicione a janela do navegador na metade esquerda da tela (Win + Seta Esquerda) e o terminal/editor na metade direita (Win + Seta Direita).
Em dois monitores: Mantenha o navegador aberto e visível no monitor secundário.

Integração com Agentes de IA

Para habilitar agentes a controlar o Flow Connector automaticamente, inclua a skill flow-generate no ambiente do seu agente:

Copie o diretório skills/flow-generate/ para a pasta de skills do seu agente (ex.: .agents/skills/, .gemini/skills/ ou .claude/skills/).
Garanta que o arquivo SKILL.md esteja acessível para leitura do modelo.
O agente utilizará a CLI flow-auto através de chamadas de terminal (Bash/PowerShell).

Modos de Operação da Skill

Modelos, Formatos e Especificações Técnicas

Geração de Imagens

Modelos disponíveis: nano-banana-pro, nano-banana-2.1 (alias nano-banana-2), nano-banana-2-lite.
Padrão para imagens: Nano Banana 2.1. Nos modos flow-text-to-image e flow-image-to-image, omitir --model envia explicitamente nano-banana-2, o identificador compatível com a extensão. Use --model nano-banana-pro ou --model nano-banana-2-lite para escolher outro modelo.
Proporções de tela (--aspect-ratio): 16:9, 4:3, 1:1, 3:4, 9:16.
Variações de saída (--outputs): De 1 a 4 imagens simultâneas.
Limite de referências: Até 10 referências combinadas por prompt (--image + --asset).

Geração de Vídeos

Modelos disponíveis: omni-flash, veo-3.1-lite, veo-3.1-fast, veo-3.1-quality.
Proporções de tela (--aspect-ratio): Estritamente 16:9 ou 9:16.
Variações de saída (--outputs): De 1 a 4 saídas por requisição.

Comparativo de Modelos de Vídeo

Observação: O modelo veo-3.1-quality consome aproximadamente cinco vezes mais créditos do que os modelos Lite e Fast. Utilize omni-flash para testes e iterações rápidas e reserve veo-3.1-fast para produções definitivas.

Guia Completo de Comandos (`flow-auto`)

Diagnóstico e Verificação

Antes de iniciar fluxos de geração, verifique o estado da conexão e dos componentes:

# Diagnóstico completo da cadeia (Node, bridge, extensão, aba, visibilidade, ffmpeg)
flow-auto doctor --site flow

# Consulta rápida de status e plano ativo
flow-auto status --site flow

# Listagem de modos operacionais suportados
flow-auto modes

Geração de Imagens (Text-to-Image e Image-to-Image)

Texto para Imagem

flow-auto generate create flow-text-to-image \
  --prompt "um lobo solitário no topo de uma montanha nevada ao pôr do sol, cinematográfico" \
  --model nano-banana-pro \
  --aspect-ratio 16:9 \
  --wait

Imagem para Imagem com Arquivo Local

flow-auto generate create flow-image-to-image \
  --prompt "transforme a cena em pintura a óleo com cores quentes" \
  --image ./referencias/foto.png \
  --model nano-banana-2 \
  --wait

Imagem para Imagem com Ativo da Biblioteca

flow-auto generate create flow-image-to-image \
  --prompt "versão noturna com iluminação de néon" \
  --asset "Lobo solitário na neve" \
  --wait

Composição com Múltiplas Imagens de Referência

flow-auto generate create flow-image-to-image \
  --prompt "combine o estilo do fundo com o elemento principal em primeiro plano" \
  --image ./fundo.jpg \
  --image ./personagem.png \
  --wait

Geração de Vídeos (Text, Frame, Ingredients e Video-to-Video)

Texto para Vídeo com Omni Flash

flow-auto generate create flow-text-to-video \
  --prompt "um barco de papel navegando suavemente por um riacho sob chuva fina" \
  --model omni-flash \
  --duration 6 \
  --aspect-ratio 16:9 \
  --wait \
  --wait-timeout 15

Vídeo com Quadro Inicial e Final (Veo 3.1 Fast)

flow-auto generate create flow-frame-to-video \
  --prompt "transição suave da estação seca para a primavera florida" \
  --image ./frame_inicio.png \
  --image ./frame_fim.png \
  --model veo-3.1-fast \
  --wait \
  --wait-timeout 20

Vídeo a partir de Ingredientes

flow-auto generate create flow-ingredients-to-video \
  --prompt "o gato usa o chapéu mágico e caminha pelo quarto" \
  --asset "Gato rajado" \
  --asset "Chapéu pontudo" \
  --duration 8 \
  --wait \
  --wait-timeout 15

Restilização de Vídeo (Video-to-Video)

flow-auto generate create flow-video-to-video \
  --prompt "estilo animação em aquarela fluida, mantendo o movimento original" \
  --video ./cena_curta.mp4 \
  --model omni-flash \
  --wait \
  --wait-timeout 15

Extensão e Continuidade de Vídeo

Permite prolongar uma cena gerada anteriormente, mantendo consistência de personagens, iluminação e ambiente sem cortes abruptos.

Requisitos para Extensão

Modelo Veo: O vídeo base deve ter sido gerado com veo-3.1-lite, veo-3.1-fast ou veo-3.1-quality.
Editor Aberto: O vídeo deve estar aberto no editor do Flow (flow.google.com/project/<id>/edit/<clip>).

# Extensão simples (adiciona ~8 segundos)
flow-auto generate create flow-extend-video \
  --prompt "a câmera avança pelo portal revelando uma floresta bioluminescente" \
  --wait \
  --wait-timeout 20

# Extensão repetida do mesmo prompt (ex.: 3 extensões consecutivas)
flow-auto generate create flow-extend-video \
  --prompt "a tempestade se intensifica com fortes rajadas de vento" \
  --extend 3 \
  --wait \
  --wait-timeout 40

# Extensão em etapas (storyboard sequencial)
flow-auto generate create flow-extend-video \
  --step "o aventureiro entra na caverna escura" \
  --step "ele acende uma tocha revelando inscrições antigas" \
  --step "uma porta de pedra secreta desliza lentamente" \
  --wait \
  --wait-timeout 40

Criação de Personagens e Customização de Vozes

Cria uma ficha de personagem com retrato e voz persistentes para reutilização em cenas posteriores através de --asset "<NOME>".

Importante: A criação de personagens e o ajuste fino de voz exigem a janela do Flow maximizada para que os elementos laterais fiquem visíveis na interface.

# Criação de personagem com voz e descrição interpretativa
flow-auto generate create flow-create-character \
  --prompt "um sábio ancião com manto cinza e olhos perspicazes, fundo neutro" \
  --name "MESTRE_ELIAS" \
  --character-info "calmo, reflexivo, fala de maneira pausada e ponderada" \
  --voice "Achird" \
  --voice-style "homem idoso, tom rouco, calmo, ritmo lento e acolhedor" \
  --voice-name "Elias Sábio" \
  --wait

# Atualização de voz de personagem já aberto
flow-auto generate create flow-set-voice \
  --character "MESTRE_ELIAS" \
  --voice "Elias Sábio" \
  --wait

# Reutilização do personagem em uma tomada
flow-auto generate create flow-image-to-image \
  --prompt "lendo um antigo pergaminho à luz de velas em uma biblioteca" \
  --asset "MESTRE_ELIAS" \
  --wait

Gerenciamento de Ativos e Biblioteca do Projeto

Importação em Lote de Referências

O Flow aceita múltiplos arquivos em uma única operação de envio:

flow-auto generate create flow-upload-assets \
  --image ./referencias/*.jpg \
  --wait

Renomeação de Ativos na Biblioteca

Como o Flow rotula novos uploads e gerações com títulos automáticos gerados por IA, renomeie os itens para permitir referências precisas com --asset:

flow-auto generate create flow-rename-asset \
  --asset "Sino de latão sobre mesa" \
  --name "OBJ_SINO" \
  --wait

Execução em Lote, Filas e Recuperação

Para sequências de prompts, nunca execute múltiplos comandos com --wait. O uso de --wait bloqueia o terminal, impede o envio paralelo e reduz a velocidade de execução para o nível de conta gratuita.

Fluxo Recomendado de Execução em Lote

Submeta todos os prompts de forma assíncrona com --index e --folder:

flow-auto generate create flow-text-to-image --prompt "Cena 01..." --index 1 --folder lote_producao
flow-auto generate create flow-text-to-image --prompt "Cena 02..." --index 2 --folder lote_producao
flow-auto generate create flow-text-to-image --prompt "Cena 03..." --index 3 --folder lote_producao
flow-auto generate create flow-text-to-image --prompt "Cena 04..." --index 4 --folder lote_producao

Monitore o progresso da fila:

# Consulta periódica da fila
flow-auto generate list

# Consulta de falhas ocorridas no lote atual
flow-auto generate list --failed

Recupere eventuais prompts com falha sem reexecutar os concluídos:

# Simula a reexecução mostrando apenas os itens pendentes
flow-auto generate resume lote_producao --dry-run

# Reenvia automaticamente apenas os itens faltantes do lote
flow-auto generate resume lote_producao

Interrupção de Emergência

Para cancelar a fila ativa imediatamente:

flow-auto stop --site flow

Controle de Ritmo e Diferenças de Plano

Comparativo entre Planos do Google Flow

Parâmetros de Temporização

--batch <n>: Número de itens disparados em paralelo por lote (Padrão: 4 no plano Pro).
--delay <faixa>: Intervalo aleatório em segundos entre lotes sucessivos (ex.: 10-15).
--image-delay <faixa>: Intervalo aleatório em segundos entre prompts dentro do mesmo lote (ex.: 1.5-3).
--speed <1-5>: Seletor unificado de velocidade (1 mais lento/seguro, 5 mais veloz).

Ajuste Manual do Painel: No plano Pro, a extensão oferece o controle Manual, que define um teto inegociável de velocidade para proteger a conta do usuário. As configurações da CLI respeitam os limites estabelecidos manualmente pelo usuário.

Pós-Processamento de Mídia

Remoção da Marca d'Água do Gemini

O Google Flow insere uma pequena marca d'água semi-transparente do Gemini deslocada em relação ao canto inferior direito. O comando clean com a flag obrigatória --mark flow aplica os cálculos dimensionais exatos:

# Imagens estáticas: Remoção bit-a-bit via LaMa Inpainting neural (~25s)
flow-auto clean imagem.jpg --mark flow -o imagem_limpa.jpg

# Vídeos: Corte dimensional de 13,5% na borda (instantâneo e sem distorção)
flow-auto clean video.mp4 --mark flow -o video_limpo.mp4

# Vídeos (alternativa): Delogo sem corte (indicado para fundos com textura rica)
flow-auto clean video.mp4 --mark flow --mode delogo -o video_limpo.mp4

# Vídeos (alternativa): Substituição por logotipo próprio
flow-auto clean video.mp4 --mark flow --mode cover --logo ./meu_logo.png -o video_limpo.mp4

Concatenação de Vídeos via FFmpeg

Para unir clipes gerados em um arquivo único:

flow-auto merge cena1.mp4 cena2.mp4 cena3.mp4 -o montagem_final.mp4

Por padrão, o comando reencodifica os clipes para garantir sincronia de áudio e padronização de taxas de quadros.
Adicione a flag --fast para realizar stream copy direto quando todos os clipes possuírem os mesmos codecs e dimensões.

Diagnóstico e Solução de Problemas

| Mensagem / Erro | Causa Identificada | Ação Corretiva | | :--- | :--- | :--- | | extension (flow) NOT CONNECTED | Extensão inativa ou aba não carregada | Abra o Chrome/Edge com a extensão ativada e carregue flow.google.com. | | flow tab: HIDDEN | Janela minimizada ou encoberta | Traga a janela do navegador para o primeiro plano. A interface precisa ser visível para receber cliques e digitação. | | not logged in to Google | Sessão expirada ou desconectada | Faça login na sua conta Google na aba do Flow e confirme a sessão. | | policy-block: ... | Prompt recusado pelos filtros de segurança | Não reenvie o mesmo prompt. Remova nomes de pessoas reais, marcas e termos de violência gráfica. | | We noticed some unusual activity... | Gatilho preventivo de tráfego | O Flow recusou a requisição sem cobrar créditos. Não reenvie imediatamente. Aumente o --delay do lote. | | could not enter Flow's Extend mode | Modo de extensão indisponível | Certifique-se de que o vídeo foi gerado com Veo 3.1 e de que a página /project/<id>/edit/<clip> está aberta. | | no Flow asset matches "<nome>" | Ativo não encontrado no painel do Flow | Verifique o nome exato do ativo ou utilize flow-rename-asset para registrar o nome antes de usá-lo. | | bridge not running | Daemon local desativado | Qualquer comando flow-auto generate inicializa o serviço de ponte automaticamente. | | generation timed out / SELECTOR_TIMEOUT | Mudança na interface do Google Flow | Execute Run Healthcheck na aba Debug Logs da extensão para atualizar os seletores do DOM. | | free plan daily limit reached | Cota diária do plano gratuito atingida | Interrompa as execuções. A cota é reiniciada à meia-noite pelo Google Flow. |

Privacidade e Isenção de Vínculo

Execução Local: Todos os prompts, arquivos de projeto e mídias geradas permanecem armazenados localmente e transitam apenas entre sua máquina e a infraestrutura oficial do Google.
Isenção Institucional: O Flow Connector é um projeto independente de código aberto desenvolvido para automação de tarefas e não possui afiliação, endosso, parceria ou vínculo corporativo com a Google LLC.