Pesquisa Local

Skill de Pesquisa Local

Pesquisa web local com fallback automático entre mecanismos. Scraping HTML direto de DuckDuckGo / Bing / Google · resiliente a limitação de taxa · esquema de resultado canônico.

Esta skill chama os mecanismos de busca públicos diretamente da sua máquina. Sem chave de API, sem SDK, sem saltos de rede. Se um mecanismo está limitando sua taxa, o orquestrador silenciosamente passa para o próximo — então a chamada geralmente é bem-sucedida na primeira tentativa, mesmo de IPs de datacenter onde o Google está bloqueado.

Cada resultado é um SearchFunctionResultItem com os 7 campos canônicos (url, name, snippet, host_name, rank, date, favicon) mais três campos de extensão opcionais: source_engine, raw_html, score. Código consumidor escrito para qualquer skill de pesquisa web com formato semelhante funciona aqui sem alterações.

✨ Destaques

• Zero dependência de SDK em nuvem — apenas cheerio (analisador HTML) e o fetch nativo do Node.
• Três mecanismos, fallback automático — DuckDuckGo → Bing → Google quando engine: "auto" (padrão).
• Consciente de localidade — --locale en-US / zh-CN / ja-JP / qualquer tag BCP-47. Crítico para IPs fora dos EUA onde o Bing serve resultados localizados mesmo para consultas em inglês.
• Filtro de atualidade — --recency-days 7 restringe a resultados da última semana. DDG suporta N dias exatos; Bing/Google usam intervalos de dia/semana/mês.
• Esquema de resultado canônico — campos url / name / snippet / host_name / rank / date / favicon, idênticos em forma a outras skills de pesquisa web no registro ClawHub.
• CLI + SDK — use tsx bin/web-search.ts <consulta> para usos rápidos, ou import { search } from "local-search" em código.
• TypeScript ESM puro — executa no Node 18+ via tsx, ou configuração zero via bun.

🚀 Início Rápido

# 1. Instalar (uma dependência em runtime: cheerio)
cd skills/local-search && npm install

# 2. Pesquisar (fallback automático entre DDG → Bing → Google)
tsx bin/web-search.ts "inteligência artificial"

# 3. Fixar um mecanismo específico + localidade
tsx bin/web-search.ts "aprendizado de máquina" --engine bing --locale en-US --num 5

# 4. Notícias recentes como JSON
tsx bin/web-search.ts "avanços em IA" --recency-days 7 --json -o ai_news.json

Uso programático:

import { search } from "local-search";

const resultado = await search("Qual é a capital da França?", { num: 5 });
if (resultado.sucesso) {
  console.log(`Respondido por ${resultado.mecanismo} em ${resultado.tempoMs}ms`);
  resultado.resultados.forEach(r => console.log(`- ${r.nome}\n  ${r.url}`));
}

🎯 Quando Usar Esta Skill

Use local-search sempre que o usuário precisar de informações que estão na web pública — além do que está nos dados de treinamento do modelo:

• Informações em tempo real: notícias atuais, preços de ações, clima, resultados esportivos
• Documentação mais recente: notas de versão de frameworks, mudanças em APIs, artigos publicados recentemente
• Verificação de fatos: confirmar uma declaração contra fontes web ao vivo
• Pesquisa: reunir várias fontes sobre um tópico, comparar perspectivas
• Descoberta de conteúdo: encontrar tutoriais, postagens de blog, palestras recentes
• Análise competitiva/de mercado: anúncios de concorrentes, tendências do setor
• Consulta acadêmica: encontrar artigos, citações, páginas de autores

🔄 Comparação de Mecanismos

Mecanismo	Endpoint	Chave de API	IP Residencial	IP de Datacenter	Atualidade
DuckDuckGo	html.duckduckgo.com/html/ (GET)	nenhuma	✅ alta	⚠️ limitações de taxa sob carga	df=d<N> (dias exatos)
Bing	www.bing.com/search	nenhuma	✅ alta	✅ alta	freshness=d1|w1|m1 (intervalos)
Google	www.google.com/search	nenhuma	⚠️ média	❌ baixa (barreira enablejs)	tbs=qdr:d|w|m|y (intervalos)

engine: "auto" tenta na ordem DuckDuckGo → Bing → Google, retornando o primeiro conjunto de resultados não vazio. De um IP de datacenter, a cadeia efetiva é DDG → Bing (Google geralmente está bloqueado); de um IP residencial, todos os três são viáveis. Edite AUTO_ENGINE_ORDER em src/engines/index.ts para alterar a prioridade.

📦 Caminho de Instalação

Localização Recomendada: {caminho_do_projeto}/skills/local-search

Extraia este pacote de skill para o caminho acima em seu projeto.

Pré-requisitos

• Node.js >= 18 (usa o fetch global integrado).
• Uma dependência npm: cheerio (analisador HTML).
• Uma conexão de internet funcional — a skill chama os mecanismos de busca públicos diretamente.

Instale uma vez no diretório da skill:

cd {caminho_do_projeto}/skills/local-search
npm install            # ou: bun install / pnpm install

A skill é TypeScript ESM puro. Você pode executá-la via tsx (recomendado, amigável para desenvolvimento) ou bun (configuração zero). Um node --experimental-strip-types bin/web-search.ts agnóstico de runtime também funciona no Node 22+.

Por que Local?

Aspecto	Skills de busca em nuvem	Esta skill (local-search)
Backend de busca	Função em nuvem / API	HTTP direto para DuckDuckGo / Bing / Google
Chave de API / SDK	Obrigatório	Nenhum
Caminho de rede	Cliente → nuvem → mecanismo de busca	Cliente → mecanismo de busca
Tratamento de falhas	Dependente de SDK	Fallback automático entre 3 mecanismos
Esquema de resultado	SearchFunctionResultItem (7 campos)	Mesmos 7 campos + 3 campos opcionais de extensão
CLI	Específico do SDK	tsx bin/web-search.ts

Arquitetura

local-search/
├── SKILL.md                 ← você está aqui
├── LICENSE.txt
├── package.json             ← declara a dependência `cheerio`
├── tsconfig.json
├── bin/
│   └── web-search.ts        ← entrada CLI
├── src/
│   ├── index.ts             ← exportações públicas do SDK
│   ├── search.ts            ← orquestrador com fallback automático
│   ├── types.ts             ← SearchFunctionResultItem + opções
│   └── engines/
│       ├── _shared.ts       ← ajudantes fetch/parse
│       ├── duckduckgo.ts    ← POST https://html.duckduckgo.com/html/
│       ├── bing.ts          ← GET https://www.bing.com/search
│       ├── google.ts        ← GET https://www.google.com/search
│       └── index.ts         ← registro de mecanismos + AUTO_ENGINE_ORDER
└── scripts/
    └── web_search.ts        ← exemplo de início rápido

A única dependência em runtime é cheerio (analisador HTML), declarada em package.json. O fetch integrado do Node 18+ cobre a camada de rede — nenhum outro SDK é importado em qualquer lugar deste pacote.

Uso da CLI

A CLI está em bin/web-search.ts. Execute-a via tsx, bun ou qualquer executor compatível com TS.

Pesquisa Básica

# Padrão: mecanismo automático, 10 resultados, saída legível
simtsx bin/web-search.ts "inteligência artificial"

# Limitar número de resultados
tsx bin/web-search.ts "aprendizado de máquina" --num 5
# (a opção curta também funciona)
tsx bin/web-search.ts "aprendizado de máquina" -n 5

Fixar um Mecanismo Específico

# Forçar apenas DuckDuckGo
tsx bin/web-search.ts "últimas notícias de tecnologia" --engine duckduckgo
# Forçar apenas Bing
tsx bin/web-search.ts "últimas notícias de tecnologia" --engine bing
# Forçar apenas Google (maior qualidade, mais propenso a ser limitado por taxa)
tsx bin/web-search.ts "últimas notícias de tecnologia" --engine google
# Padrão — tentar DDG → Bing → Google, retornar o primeiro não vazio
tsx bin/web-search.ts "últimas notícias de tecnologia" --engine auto

Filtro de Atualidade

# Resultados dos últimos 7 dias
tsx bin/web-search.ts "notícias sobre criptomoedas" --num 10 --recency-days 7
# (opção curta)
tsx bin/web-search.ts "notícias sobre criptomoedas" -r 7

Salvar Resultados em JSON

# Escrever JSON em um arquivo (o banner legível é suprimido)
tsx bin/web-search.ts "pesquisa sobre mudanças climáticas" --num 5 --json -o resultados_pesquisa.json

# Ou canalizar JSON para stdout
tsx bin/web-search.ts "avanços em IA" --num 3 --recency-days 1 --json > ai_news.json

Modo Silencioso (Scripts / Pipe)

# Suprimir o banner "mecanismo/tempo" — apenas imprimir os resultados
tsx bin/web-search.ts "hooks react" --quiet

Parâmetros da CLI

Bandeira	Curta	Descrição
--num <N>	-n	Número de resultados (padrão: 10, máximo: 50)
--engine <id>	-e	duckduckgo | bing | google | auto (padrão: auto)
--recency-days <N>	-r	Restringir a resultados dos últimos N dias (padrão: 0 = sem filtro)
--timeout <ms>	—	Timeout por mecanismo em ms (padrão: 8000)
--json	—	Emitir JSON em vez de saída legível
--output <caminho>	-o	Escrever JSON em arquivo em vez de stdout
--pretty	—	Imprimir JSON formatado (padrão ativado; use --no-pretty para desativar — ainda não suportado, omita --json em vez disso)
--quiet	-q	Suprimir banner de informação do mecanismo
--help	-h	Mostrar ajuda

Estrutura do Resultado da Pesquisa

Cada item de resultado é um SearchFunctionResultItem:

interface SearchFunctionResultItem {
  // ----- Campos canônicos (formato compartilhado entre skills de pesquisa web ClawHub) -----
  url: string;          // URL completa do resultado
  name: string;         // Título da página
  snippet: string;      // Texto de pré-visualização / descrição
  host_name: string;    // Nome do domínio (ex.: "pt.wikipedia.org")
  rank: number;         // Classificação baseada em 1 dentro do conjunto de resultados do mecanismo
  date: string;         // Data de publicação / atualização; "N/A" quando desconhecida
  favicon: string;      // URL do favicon (Google S2)

  // ----- Campos de extensão (novos no local-search) -----
  source_engine: "duckduckgo" | "bing" | "google";
  raw_html?: string;    // HTML original do elemento de snippet (opcional)
  score?: number;       // Pontuação de relevância heurística [0, 100] (opcional)
}

Uso do SDK

Se você está escrevendo código TypeScript/JavaScript (não executando a CLI), importe de src/index.ts:

Pesquisa Simples

import { search } from "local-search";

const resultado = await search("Qual é a capital da França?", { num: 5 });

if (resultado.sucesso) {
  console.log(`Mecanismo usado: ${resultado.mecanismo}`);
  console.log(`Tentado na ordem: ${resultado.mecanismosTentados.join(" → ")}`);
  console.log(`Tempo decorrido: ${resultado.tempoMs}ms`);
  for (const item of resultado.resultados) {
    console.log(`- ${item.nome}  [${item.mecanismoFonte}]`);
    console.log(`  ${item.url}`);
    console.log(`  ${item.snippet}`);
  }
} else {
  console.error("Pesquisa falhou:", resultado.erro);
  if (resultado.erros) {
    // Modo automático: veja quais mecanismos tentaram e o que relataram
    for (const e of resultado.erros) {
      console.error(`  ${e.mecanismo}:`, e.erro);
    }
  }
}

Variante que Lança Exceção em Falha

import { searchOrThrow, AllEnginesFailedError } from "local-search";

try {
  const resultados = await searchOrThrow("Frameworks JavaScript", { num: 10 });
  console.log(resultados);
} catch (err) {
  if (err instanceof AllEnginesFailedError) {
    console.error("Todos os mecanismos falharam:", err.errors);
  } else {
    console.error("Erro de mecanismo único:", err);
  }
}

Fixar um Mecanismo Específico

import { search } from "local-search";

// Pular a cadeia de fallback — usar apenas DuckDuckGo.
const resultado = await search("aplicações de computação quântica", {
  num: 8,
  engine: "duckduckgo",
});

Filtro de Atualidade

const resultado = await search("pesquisa em genômica", {
  num: 5,
  recency_days: 30, // últimos 30 dias
});

Fetch Personalizado (Testes / Runtimes de Borda)

const resultado = await search("olá mundo", {
  fetchImpl: meuFetchMock, // qualquer função compatível com WhatWG-fetch
  userAgent: "meu-bot/1.0",
  timeoutMs: 5000,
});

Backends de Mecanismo

DuckDuckGo (duckduckgo)

• Endpoint: https://html.duckduckgo.com/html/ (formulário POST q=...)
• Sem chave de API. Sujeito a limites de taxa aproximados — uso sustentado retorna conjuntos de resultados vazios.
• Atualidade: campo de formulário df=d<N>.
• Melhor para: primeira tentativa padrão; raramente bloqueado diretamente; respeita privacidade.

Bing (bing)

• Endpoint: https://www.bing.com/search?q=...&count=...
• Sem chave de API. O layout HTML é estável e fácil de analisar.
• Atualidade: intervalo freshness=d1 / w1 / m1 (Bing não tem filtro de URL de N dias arbitrários).
• Melhor para: segundo fallback; bons resultados em inglês; peculiaridades de localidade ocasionais (mitigadas por ensearch=1).

Google (google)

• Endpoint: https://www.google.com/search?q=...&num=...
• Sem chave de API, MAS o Google é o mais agressivo em bloquear scrapers. De IPs de datacenter / nuvem, o Google normalmente retorna uma página de redirecionamento "please enable JS" (/httpservice/retry/enablejs) com zero resultados analisáveis — o mecanismo sinaliza isso como uma falha suave e a cadeia automática passa adiante. De IPs residenciais, o scraping HTML do Google geralmente funciona bem.
• Atualidade: intervalo tbs=qdr:d|w|m|y.
• Melhor para: fallback de último recurso em IPs residenciais; geralmente falhará em IPs de nuvem (onde DDG+Bing já cobrem a necessidade).

Estratégia de Fallback Automático

Quando engine: "auto" (o padrão), o orquestrador tenta mecanismos nesta ordem:

1. DuckDuckGo — bloqueio menos agressivo, filtro de data mais refinado
2. Bing — geralmente estável de qualquer IP, incluindo datacenter
3. Google — melhor qualidade de resultado quando acessível; frequentemente bloqueado em IPs de datacenter

Ele retorna o primeiro mecanismo que produz ≥ 1 resultado. Se todos os três falharem, o resultado é { success: false, errors: [...] } com o erro de cada mecanismo anexado — ou, no modo searchOrThrow, um AllEnginesFailedError.

Tabela de confiabilidade prática (observada durante testes):

Tipo de IP do chamador	DDG	Bing	Google	Cadeia automática efetiva
Residencial	alta	alta	média	DDG → Bing → Google (3 viáveis)
Datacenter / nuvem	média (limites de taxa sob carga)	alta	baixa (barreira enablejs)	efetivamente DDG → Bing

A ordem é definida em src/engines/index.ts (AUTO_ENGINE_ORDER); edite esse array se quiser uma prioridade diferente.

Casos de Uso Comuns

1. Informações em tempo real: notícias atuais, preços de ações, clima, resultados esportivos
2. Documentação mais recente: notas de versão de frameworks, mudanças em APIs, artigos publicados recentemente
3. Verificação de fatos: confirmar uma declaração contra fontes web ao vivo
4. Pesquisa: reunir várias fontes sobre um tópico, comparar perspectivas
5. Descoberta de conteúdo: encontrar tutoriais, postagens de blog, palestras recentes
6. Análise competitiva/de mercado: anúncios de concorrentes, tendências do setor
7. Consulta acadêmica: encontrar artigos, citações, páginas de autores

Perguntas Frequentes (FAQ)

Como o fallback automático lida com limites de taxa?

O orquestrador define um timeout por mecanismo (padrão 8s) e captura erros de rede ou HTTP. Se o mecanismo retornar zero resultados analisáveis (HTML vazio ou página de bloqueio), ele é tratado como falha e o próximo mecanismo na cadeia é tentado. O fallback é transparente para o chamador — apenas o campo source_engine no resultado final indica qual mecanismo respondeu.

Preciso de uma chave de API?

Não. Nenhum dos três mecanismos de busca exige chave de API para scraping HTML público. A skill usa os endpoints web públicos, sem qualquer SDK pago.

Quais dados de resultado são retornados?

Cada resultado inclui 7 campos canônicos: URL, título, snippet, nome do host, classificação, data e favicon. Além disso, três campos de extensão opcionais (source_engine, raw_html, score) fornecem contexto adicional para consumidores avançados.

Posso usar isso em produção?

Sim, muitos desenvolvedores usam esta skill para automação, agentes de IA e ferramentas de pesquisa internas. No entanto, devido às políticas anti-scraping dos mecanismos (especialmente Google), recomenda-se usar com moderação e respeitar os limites de taxa. Para cargas de trabalho pesadas, considere adicionar proxies ou usar APIs pagas.

Qual Node.js é necessário?

Node.js >= 18, devido ao suporte global a fetch. Alternativamente, bun também funciona com configuração zero.

Como contribuir?

Contribuições são bem-vindas! Envie pull requests para o repositório GitHub em https://github.com/Sakurakilove/local-search. Issues, sugestões e correções de bugs são apreciadas. Certifique-se de executar os testes antes de enviar.

Licença

MIT © Sakurakilove. Veja o arquivo LICENSE para mais detalhes.