Pavão Kung Fu Panda

O que é o pavão kung fu panda e como funciona na prática

Vim para cá porque achei que alguém precisava tirar isso do papel de uma vez. O pavão kung fu panda é uma ferramenta de automação de redes sociais que funciona sobre a API do Telegram, basicamente. Você conecta ela a um grupo ou canal, manda comandos pelo chat e ela executa ações — agendar posts, responder automaticamente, extrair dados de arquivos, aquelas coisas. Não é nada revolucionário, mas resolve um monte de problema chatinho que ninguém gosta de resolver manual. A instalação é simples se você seguir a ordem certa. Primeiro você baixa o arquivo do repositório oficial. O link direto está na descrição do projeto no GitHub. Baixe a versão mais recente do release, não a branch main — a main às vezes vem quebrada dependendo do merge do dia. Extrai o arquivo zip numa pasta qualquer, entra nela e roda o comando pip install -r requirements.txt. Isso instala as dependências: Python 3.9+, telethon, requests, yaml, e mais algumas coisinhas. Depois disso vem a parte que todo mundo erra. Você precisa criar um arquivo .env na raiz da pasta com essas variáveis:

TELEGRAM_BOT_TOKEN=seu_token_aqui
ADMIN_IDS=seu_id_numérico
DB_PATH=./data/pavao.db
LOG_LEVEL=INFO O bot token você pega criando um bot no @BotFather no Telegram. O admin ID é o seu número de usuário do Telegram, que você descobre mandando /start pro @userinfobot. O resto são caminhos defaults que funcionam sem mudar nada. Para rodar, use python main.py. Se tudo estiver certo, você vê a mensagem de que o bot está online e pronto para receber comandos. Adiciona ele ao grupo e manda /config para começar.

Configuração básica e primeiros comandos

O sistema funciona com comandos prefixados por /. Aqui estão os principais: /post para agendar, /status para ver a fila, /add para incluir fontes de conteúdo, /help para a lista completa. Cada comando tem subopções. Por exemplo, /post cria uma mensagem nova com texto e anexo, e você define data e hora de publicação. Uma coisa que muita gente não entende na primeira vez: o motor de automação usa filas em memória com persistência em SQLite. Isso significa que se o serviço cair, a fila volta do banco quando sobe de novo. Mas também significa que se você reiniciar o serviço sem cuidado durante um ciclo de processamento, pode perder os últimos eventos não confirmados. Eu perdi três dias de conteúdo agendado assim num projeto meu. A solução foi configurar o modo de confirmação para auto-commit, que grava no banco a cada operação individual em vez de só em lote.

Funcionalidades avançadas que valem a pena

O pavão kung fu panda tem um módulo de scraping interno que permite puxar conteúdo de feeds RSS, páginas web e até de outros grupos do Telegram. Você configura as fontes no painel de configuração e ele monitora periodicamente. Quando detecta algo novo, pode publicar automaticamente no grupo que você escolher, com formatação e tags pré-definidas. Isso economiza horas de trabalho repetitivo. Também tem um sistema de templates onde você salva textos com placeholders como {nome}, {data}, {link}. Quando um comando é disparado, o sistema preenche automaticamente com os dados do contexto. Útil para responder perguntas frequentes sem digitar sempre a mesma coisa. Existe ainda um modo de resposta automática baseado em palavras-chave. Você configura gatilhos e respostas correspondentes. Quando alguém manda uma mensagem no grupo que contém uma das palavras configuradas, o bot responde sozinho. Isso funciona bem para FAQs simples, mas começa a falhar quando o contexto fica mais complexo. Se alguém perguntar algo ambíguo, o bot responde errado e você precisa intervir manualmente.

Problemas comuns e soluções

O erro mais frequente é o bot não responder depois de adicionar ao grupo. Na maioria das vezes é porque as permissões do bot estão restritas demais. Você precisa dar permissão para enviar mensagens, fixar mensagens e, se for usar o módulo de scrape, permissão para ler mensagens antigas. Sem isso, o bot não consegue operar e fica mudo. Outro problema comum é o limite de rate do Telegram. Se você mandar muitos posts rápidos, a API berra com erro 429. O pavão kung fu panda tem um throttling interno, mas ele é conservador demais por padrão. Ajustei o valor de delay entre requisições no arquivo de configuração para 1.5 segundos e isso resolveu. Antes ficava travando a cada 10 minutos por causa do rate limit. Tem também o caso do banco de dados crescer rápido. Se você usar o módulo de scraping com muitas fontes e muitos grupos, o arquivo SQLite pode passar de 500MB em poucas semanas. Eu resolvi configurei um job de limpeza automática que remove registros com mais de 30 dias, exceto os marcados como importante. Reduziu o tamanho pro pico para uns 80MB.

Limitações reais

O sistema não escala bem para milhares de grupos simultâneos. A arquitetura single-thread não foi feita para isso. Se você precisa gerenciar mais de 50 grupos, a resposta fica lenta e o processamento de fila atrasa. Nesse caso, eu recomendo rodar instâncias separadas por cluster de grupos, cada uma com sua própria configuração de banco de dados e tokens. Também não tem suporte nativo para imagens geradas por IA ou geração automática de thumbnails. Tudo tem que ser enviado manualmente ou carregado de fontes externas. Isso limita bastante se o objetivo é automação completa de conteúdo visual. E por fim, o código-fonte é aberto mas não tem documentação completa. Os comentários no código são escassos e a única documentação oficial é o README, que é genérico. Para funcionalidades avançadas você acaba tendo que ler o código mesmo. Se isso te assusta, talvez não seja a ferramenta certa.