Habilidade Eficiente de Pesquisa na Web

Um protocolo para acessar conteúdo da web da maneira mais eficiente em tokens, precisa e estruturada — usando a ferramenta certa na profundidade certa e parando assim que a pergunta puder ser respondida.

Quando Usar

• Use esta habilidade quando a tarefa corresponder a esta descrição: Protocolo para pesquisa na web com eficiência de tokens. Use ao acessar URLs, repositórios do GitHub ou executar consultas de pesquisa. Evita o desperdício de busca de página completa.

Princípio Central

Busque o mínimo necessário para responder. Leia superficialmente antes de mergulhar. Pare quando puder responder.

Cada busca desnecessária desperdiça tokens e adiciona ruído. Esta habilidade impõe uma abordagem em camadas onde você aumenta a profundidade da busca apenas quando as camadas mais rasas falham.

Etapa 1 — Classificar a Entrada

Antes de buscar qualquer coisa, identifique que tipo de entrada você recebeu:

Protocolo GitHub

Use quando a entrada for um URL do GitHub (repositório, arquivo, PR, issue, etc.)

Etapa 1 — Analisar o URL

github.com/{owner}/{repo}                → Repo root
github.com/{owner}/{repo}/tree/{branch}  → Directory
github.com/{owner}/{repo}/blob/{branch}/{path} → Single file
github.com/{owner}/{repo}/issues/{n}     → Issue
github.com/{owner}/{repo}/pull/{n}       → Pull request

Etapa 2 — Usar a API do GitHub (preferível à raspagem)

Sempre prefira a API do GitHub. Ela retorna JSON limpo — sem necessidade de análise de HTML.

# Repo metadata (name, description, language, stars, topics)
GET https://api.github.com/repos/{owner}/{repo}

# File tree (see what files exist — very cheap)
GET https://api.github.com/repos/{owner}/{repo}/git/trees/{ref}?recursive=1

# Single file content (base64 encoded)
GET https://api.github.com/repos/{owner}/{repo}/contents/{path}?ref={ref}

# README only (usually enough to understand the repo)
GET https://api.github.com/repos/{owner}/{repo}/readme

Etapa 3 — Busca em Camadas para Repositórios

Layer 1 (always do first):
  → Fetch repo metadata + README only
  → Can you answer the user's question now? YES → STOP. NO → continue.

Layer 2 (only if needed):
  → Fetch file tree to understand structure
  → Identify the 1-3 most relevant files based on the question
  → Can you answer now? YES → STOP. NO → continue.

Layer 3 (last resort):
  → Fetch specific relevant files only (never fetch all files)
  → Prioritize: main entry point, config files, key modules

Regras de Tokens para GitHub

• O README sozinho responde a ~70% das perguntas "o que este repositório faz" — sempre tente primeiro
• Nunca busque mais de 3 arquivos em um único turno de pesquisa
• Se um arquivo exceder ~300 linhas, leia apenas o topo (imports + assinaturas de classe/função)
• Decodifique o conteúdo base64 da API antes de passá-lo para o contexto

Protocolo URL

Use quando o usuário fornecer um URL específico não-GitHub (documentos, artigos, blogs, etc.)

Etapa 1 — Avaliar o tipo de URL

Etapa 2 — Busca em Camadas

Camada 1 — Leitura superficial
  → Busque o URL com read_url_content
  → Leia apenas os títulos (H1, H2, H3) e o primeiro parágrafo
  → Esta página contém o que o usuário precisa? NÃO → tente um URL diferente ou pesquise. SIM → continue.

Camada 2 — Extração direcionada
  → Se a página tiver links de âncora (ex: /docs/page#section), busque com a âncora
  → Extraia apenas a seção relevante (máximo de 200–500 tokens)
  → Você consegue responder? SIM → PARE.

Camada 3 — Busca completa
  → Busque a página inteira, remova o conteúdo redundante (navegação, rodapé, anúncios, banners de cookies, barras laterais)
  → Limite em 2000 tokens. Resuma antes de passar para a resposta.

Camada 4 — Subagente de Navegador (último recurso apenas)
  → Use APENAS se read_url_content retornar conteúdo vazio, corrompido ou placeholder de JS

…