Flow Runner — Documentação Completa

Visão Geral

O Flow Runner é uma ferramenta de automação visual para desktop baseada em detecção de imagens na tela. Ela executa fluxos repetitivos (FOLLOW / UNFOLLOW) de forma lenta, aleatória e controlada, simulando comportamento humano para evitar padrões óbvios.

A ferramenta não depende de APIs, apenas de:

• captura de tela
• reconhecimento de imagem
• cliques e scroll

---

Modos de Operação

1. FOLLOW

Fluxo:

1. Procura na tela por um botão que corresponda ao asset follow_button.*
2. Clica no botão (com atraso aleatório)
3. Faz scroll
4. Aguarda um tempo aleatório
5. Repete o processo em loop

2. UNFOLLOW

Fluxo:

1. Procura por following.*
2. Clica no botão Following
3. Aguarda a abertura do popup/modal
4. Procura por unfollow.*
5. Clica para confirmar
6. Faz scroll
7. Aguarda um tempo aleatório
8. Repete o processo em loop

---

Estrutura de Pastas

flow_runner/
│
├── runner.py
├── screen_manager.py
├── launcher.bat
├── requirements.txt
├── README.md
└── assets/
    ├── follow_button.png
    ├── following.png
    └── unfollow.png

⚠️ Importante: os nomes base dos arquivos devem ser exatamente:

• follow_button
• following
• unfollow

A extensão pode ser: .png, .jpg, .jpeg ou .webp.

---

Requisitos

• Windows 10 ou 11
• Python 3.10+
• Resolução de tela estável (evite mudar zoom/escala durante execução)

Dependências Python

Instaladas via:

pip install -r requirements.txt

Dependências usadas:

• pyautogui
• opencv-python
• numpy
• keyboard
• pygetwindow

---

Como Executar

1. Extraia o projeto
2. Instale as dependências:

   pip install -r requirements.txt

3. Coloque os assets corretos na pasta assets/
4. Execute:

   launcher.bat
   

5. Escolha:
   • 1 → FOLLOW
   • 2 → UNFOLLOW

Para parar a execução a qualquer momento:

• pressione ESC

---

Sistema de Tempo (Anti‑Padrão)

O Flow Runner foi projetado para NÃO executar ações em sequência rápida.

Comportamentos implementados:

• ⏱️ Delay aleatório entre cliques
• 🌀 Delay aleatório entre loops
• 💤 Pausas longas ocasionais
• 🛑 Backoff quando nada é encontrado
• 🔢 Limite de ações por ciclo

Parâmetros principais (em runner.py):

CLICK_DELAY = (1.2, 3.4)
LOOP_DELAY = (4.0, 9.0)
LONG_BREAK_EVERY = (6, 14)
LONG_BREAK_SECONDS = (15, 45)
NO_HIT_BACKOFF = (6.0, 16.0)
MAX_ACTIONS_PER_LOOP = 3

Esses valores foram escolhidos para evitar padrões previsíveis.

---

Assets (Ponto Mais Crítico)

Regras para bons assets:

• Recorte apenas o botão clicável
• Evite fundos grandes
• Evite sombras, bordas desnecessárias ou áreas muito grandes
• Quanto mais específico o recorte, melhor o reconhecimento

Erros comuns:

• Renomear .jpeg para .png (isso quebra o OpenCV)
• Arquivo virar unfollow.png.png (Windows esconde extensão)
• Recortar o popup inteiro em vez do botão

---

Detecção de Janela

O foco do app é identificado pelo título da janela:

APP_TITLE = "instagram"

Altere esse valor para corresponder exatamente ao título do seu aplicativo.

Se o título não for encontrado:

• o loop entra em espera
• nenhum clique é executado

---

Logs

Durante a execução, o terminal mostra:

• timestamp
• quantidade encontrada
• cliques executados
• totais acumulados
• pausas longas

Exemplo:

[2026-01-06T02:41:12] follow_found=3 clicked_now=2 total=18
[2026-01-06T02:41:58] long break: 27.4s

---

Segurança de Uso

Recomendações:

• Não rode por horas seguidas sem supervisão
• Comece com tempos mais lentos
• Ajuste parâmetros gradualmente
• Teste sempre em ambiente controlado

---

Ajustes Futuros Possíveis

• Limite máximo diário
• Janela de horário (ex: só rodar entre 10h–22h)
• Randomização de scroll
• Captura de screenshot para debug
• Modo somente leitura (detecção sem clique)

---

Encerramento

O Flow Runner foi construído para:

• ser simples
• ser previsível no código
• ser imprevisível no tempo
• evitar comportamento mecânico

Qualquer ajuste fino deve ser feito no tempo, não na quantidade de ações.