seaworld008/Commonly-used-high-value-skills

Agent Browser

Use esta skill quando a tarefa exigir operação direta em páginas web (e não apenas dados de API somente leitura). Agent Browser é baseado no protocolo CDP (Chrome DevTools Protocol) padrão, que confere ao agente a capacidade de navegar na web, preencher formulários, clicar em botões e lidar com interações front-end complexas (como páginas renderizadas com React/Vue, pop-ups e pré-visualização de CAPTCHA) como um ser humano.

Instalação

npx clawhub@latest install agent-browser

Cenários de Uso

• Abrir páginas web e executar operações em várias etapas: fazer login em sistemas de administração, comparar dados entre várias abas, enviar formulários de negócio complexos.
• Localizar elementos com linguagem natural: sem precisar escrever seletores CSS complexos, basta usar comandos como "clique no campo de busca no canto superior esquerdo" ou "encontre o botão com o texto 'Adicionar ao carrinho'".
• Exportar saídas multimídia: salvar a página atual como captura de tela de alta resolução, captura de tela longa com rolagem, documento PDF ou até gravar um vídeo da operação.
• Executar JavaScript na página: injetar scripts personalizados diretamente no Console para extrair dados dinâmicos difíceis de obter ou simular comportamentos específicos do usuário.
• Salvar estado da sessão: suporte à persistência de Cookies e LocalStorage (mecanismo retain) para acesso entre sessões sem necessidade de login repetido.

Recomendações de Uso

1. Defina primeiro a página alvo e o resultado esperado: estabeleça um Critério de Sucesso claro.
2. Execute em fases: divida operações complexas em etapas atômicas que podem ser verificadas (navegar → localizar → operar → validar).
3. Para contas e segurança: priorize o uso de Perfis de navegador isolados e ative o modo de privilégios mínimos.
4. Prioridade visual: faça screenshot antes e depois das operações críticas, tanto para manter evidências quanto para facilitar a autocorreção do agente.

Condições de Ativação / When to Use

• Cenários sem API: quando o site alvo não oferece API pública e os dados só podem ser obtidos através da interação com o front-end da página.
• Captura de relatórios gráficos: quando é necessário extrair gráficos específicos de um dashboard complexo e analisá-los.
• Automação de registro/login: quando é necessário simular um usuário para concluir uma série de etapas de verificação de identidade ou configuração de preferências.
• Testes de SEO e performance de front-end: usando o console para ler erros da página e métricas de desempenho (LCP, FID) e diagnosticá-los.
• Monitoramento em tempo real de conteúdo dinâmico: como monitorar uma página de cotações de ações em tempo real ou a variação de estoque em uma promoção relâmpago.

Capacidades Principais / Core Capabilities

1. Instantâneo Semântico e Localização (Semantic Snapshot)

• Etapas:
  1. Chamar snapshot para obter a árvore de acessibilidade (Accessibility Tree).
  2. Combinar ax* (referência de acessibilidade) e n* (referência DOM) para entender a hierarquia da página.
  3. Usar a skill highlight para verificar se a localização está correta.
• Melhores práticas: em páginas complexas, primeiro execute scroll até o final para garantir que o conteúdo carregado sob demanda (Lazy Loading) seja completamente exibido.

2. Simulação de Ações Precisas (Action Emulation)

• Etapas:
  1. Chamar a interface act para executar ações como click, type, hover, drag, etc.
  2. Definir clearFirst: true para garantir que o campo de entrada esteja limpo.
  3. Para etapas críticas, ativar slowly: true para imitar a frequência de clique humana real e reduzir o risco de ser detectado por mecanismos anti-bot.
• Melhores práticas: após clicar em "Enviar", use imediatamente a ferramenta wait para aguardar até que uma URL ou texto específico apareça, garantindo que a operação foi concluída.

3. Retenção e Persistência de Sessão (Session Retention)

• Etapas:
  1. Usar retain: true para marcar abas importantes.
  2. As abas marcadas não serão fechadas automaticamente após a sessão do agente, facilitando um segundo acesso posterior.
• Melhores práticas: ao exigir login manual do usuário com leitor de QR Code, ative retain para que, após o usuário escanear o código, o agente possa assumir.

4. Captura de Exceções e Diagnóstico (Errors & Requests)

• Etapas:
  1. Ler a lista errors em tempo real para identificar falhas na execução do JS.
  2. Monitorar as requisições de rede requests para interceptar e analisar pacotes de API específicos (incluindo a Resposta de XHR/Fetch).

Comandos/Modelos Comuns / Common Patterns

Modelo de Fluxo de Trabalho para Coleta de Informações Web (Scraping Workflow)

### Objetivo da Tarefa
[Descrição do objetivo: Extrair o preço e os comentários dos 10 primeiros produtos do site X]

### Etapas da Operação (Action Sequence)
1. **Navegar**: Acessar `https://example.com/products`.
2. **Aguardar**: Aguardar o carregamento do elemento contendo `.product-list`.
3. **Rolar**: Rolar até o final da página para ativar a paginação.
4. **Instantâneo**: Obter o conteúdo de texto de todas as referências de nível `n`.
5. **Console**: Injetar script `Array.from(document.querySelectorAll('.price')).map(e => e.innerText)`.
6. **Capturar Tela**: Capturar a lista inteira e salvar em `output/products.png`.

### Resultado Esperado
- Dados resumidos em JSON.
- Evidência em captura de tela.

Exemplo de Abertura Rápida e Retenção de Aba

// Exemplo: Abrir o GitHub e reter a sessão para não ser destruída automaticamente
const tab = await mcp_call({
  name: 'browser_open',
  arguments: {
    targetUrl: "https://github.com",
    profile: "chrome"
  }
});
await mcp_call({
  name: 'browser_retain',
  arguments: {
    targetId: tab.targetId,
    retain: true
  }
});

Casos de Uso Avançados / Advanced Use Cases

1. Teste de Regressão de UI Automatizado

• O agente abre periodicamente o ambiente de desenvolvimento da página, captura as telas das funcionalidades principais e as compara com as "capturas de base" em MEMORY.md, identificando desalinhamentos de UI ou perda de estilos.

2. "Carregador de Dados" entre Plataformas

• Ler dados de relatórios do Sistema A, fazer login automaticamente no Sistema B e preencher manualmente cada registro, permitindo a integração entre sistemas sem API.

Limites e Restrições / Boundaries

• Interceptação de CAPTCHA: CAPTCHAs gráficos ou de quebra-cabeça complexos ainda exigem intervenção humana (podem ser combinados com a skill question para enviar a captura ao usuário).
• Custo de Recursos: Iniciar o navegador (especialmente múltiplas instâncias) consome muita CPU e memória.
• Compatibilidade de Driver: Em alguns ambientes Headless, animações dependentes de aceleração GPU ou WebGL podem sofrer renderização anômala.
• Detecção Anti-Bot: Se as ações forem muito mecânicas ou o IP de origem for suspeito, o site alvo pode acionar bloqueios. Recomenda-se o uso de Proxy.
• Risco de Timeout: Em redes muito lentas ou quando o servidor responde lentamente, é necessário definir timeoutMs adequadamente.

Resumo de Melhores Práticas

1. Estratégia de Retry em Falhas: Para falhas de navegação ou elementos não encontrados, projete um mecanismo de retry automático de 2 a 3 vezes.
2. Consistência de Ambiente: Mantenha o tamanho da viewport (Resolução) consistente para evitar que o layout responsivo desloque a posição dos elementos.
3. Limpeza: A menos que retain esteja ativado, feche as abas inativas imediatamente após a conclusão da tarefa.
4. Modo Anônimo: Para tarefas sensíveis, priorize o uso do modo incognito.
5. Rastreabilidade de Logs: Registre todos os logs de erro do console do navegador; eles são a primeira pista para depuração.