Mucaktr/challenge-aware-webbridge

WebBridge Consciente de Desafios

Visão Geral

Use esta habilidade para manter uma tarefa de navegação em andamento quando uma página de verificação interrompe a automação normal. Detecte páginas de desafio, entregue o controle ao usuário de forma limpa, aguarde a liberação do desafio e retome a tarefa original na mesma sessão do Kimi WebBridge.

Fluxo de Trabalho

1. Reutilize um único nome de session estável para toda a tarefa do usuário. Não divida uma única tarefa de navegação em vários nomes de sessão.
2. Após a navegação, execute scripts/detect_verification_page.py se o título da página, URL ou texto visível parecer suspeito.
3. Se nenhum desafio for detectado, continue a navegação normal.
4. Se um desafio for detectado:
   • Informe claramente ao usuário que o site está aguardando verificação manual.
   • Mantenha a aba e a sessão atuais ativas.
   • Traga a página para o campo de visão, se necessário, para que o usuário possa interagir com ela.
   • Se o usuário pedir explicitamente preparação, realize apenas ações não submissivas, como abrir a página, aguardar o layout ou focar uma área neutra fora do desafio.
   • Não afirme que a habilidade pode burlar, resolver ou derrotar o desafio automaticamente.
5. Execute scripts/wait_for_clearance.py para consultar até que o intersticial desapareça ou o tempo limite expire.
6. Quando a página for liberada, tire um novo snapshot e retome a tarefa original.

Padrões Seguros

• Prefira sondagens compactas com snapshot e evaluate em vez de despejos amplos de página.
• Trate títulos ou pistas de URL como checkLoading, turnstile, captcha, verify ou checking your browser como sinais fortes.
• Mantenha toda a linguagem voltada ao usuário calma e concreta. Explique o que está bloqueando a tarefa e o que o usuário deve fazer em seguida.
• Nunca armazene segredos, cookies ou dados pessoais em scripts auxiliares ou arquivos do repositório.
• Nunca apresente esta habilidade como uma ferramenta de evasão anti-bot.

Ferramentas

• Use scripts/webbridge_request.py para chamadas do daemon, especialmente no Windows, onde os corpos das requisições devem ser enviados a partir de um arquivo temporário UTF-8.
• Use scripts/detect_verification_page.py para classificar a página atual como livre ou com desafio.
• Use scripts/wait_for_clearance.py após a entrega ao usuário para detectar quando o site estiver pronto novamente.

Referências

• Leia references/challenge-patterns.md para pistas de detecção e padrões de recuperação.
• Leia references/user-messaging.md para linguagem curta de entrega ao usuário.