Skip to content

SKILL.md

Latest commit

 

History

History
199 lines (157 loc) · 7.96 KB

SKILL.md

File metadata and controls

199 lines (157 loc) · 7.96 KB
Raw
name szt-scraping-tool
description Scraper inteligente para garimpar itens específicos em classificados (OLX, Mercado Livre, Facebook). Coleta → normaliza via Gemini Flash → classifica com playbook curatorial → alerta via Telegram → relatório. Custo zero (Crawl4AI + Gemini free tier). Use quando disser 'scraper de [item]', 'garimpar [item]', 'monitora anúncios de [item]', 'busca classificados de [item]', 'roda o scraper'.

szt-scraping-tool

Scraper inteligente para garimpar itens específicos em classificados brasileiros. Nasceu para buscar TVs CRT para a instalação Totem CRT (PLAYER 1), mas é genérico o suficiente para qualquer garimpagem.

Quando usar

  • "scraper de CRT" / "roda o scraper de CRT"
  • "garimpar [item] no OLX"
  • "monitora anúncios de [item]"
  • "busca classificados de [item]"
  • "cria um scraper para [item]"
  • "relatório do scraper"

Conceito

                    ┌─────────────────┐
                    │   CAMPAIGN.json │  ← Playbook: o que buscar, como classificar
                    └────────┬────────┘
                             │
  ┌──────────────────────────┼──────────────────────────┐
  │                          ▼                           │
  │  ┌─────────┐   ┌──────────────┐   ┌──────────────┐ │
  │  │ Crawl4AI│──▶│  Normalizer  │──▶│   Reporter   │ │
  │  │ (coleta)│   │ (Gemini LLM) │   │  (ranking)   │ │
  │  └─────────┘   └──────────────┘   └──────┬───────┘ │
  │       $0             $0                   │         │
  │                                    ┌──────▼───────┐ │
  │                                    │   Alertas    │ │
  │                                    │  (Telegram)  │ │
  │                                    └──────────────┘ │
  │              szt-scraping-tool                      │
  └─────────────────────────────────────────────────────┘

Cada scraper é uma "campaign" — um JSON que define:

  • O que buscar (termos, plataformas, filtros)
  • Como classificar (playbook curatorial para o Gemini)
  • Como alertar (score mínimo, destinatário)

O motor é o mesmo. O que muda é o playbook.

Arquitetura

szt-scraping-tool/
├── SKILL.md                    ← esta documentação
└── scripts/
    ├── run.js                  ← CLI principal
    ├── db.js                   ← persistência JSON por campaign
    ├── normalize.js            ← classificação LLM (Gemini Flash)
    ├── alert.js                ← alertas Telegram
    ├── report.js               ← relatório curatorial
    ├── collectors/
    │   ├── olx.js              ← Crawl4AI → OLX
    │   └── mercadolivre.js     ← Crawl4AI → Mercado Livre
    └── campaigns/
        └── crt-totem.json      ← campaign ativa: CRTs para Totem

Uso

Rodar uma campaign existente

SKILL=~/.pi/agent/skills/felipe/szt-scraping-tool/scripts

# Pipeline completo: coleta → normalização → alertas
node $SKILL/run.js --campaign crt-totem

# Só coleta (sem normalizar/alertar)
node $SKILL/run.js --campaign crt-totem --collect-only

# Só normalizar pendentes
node $SKILL/run.js --campaign crt-totem --normalize-only

# Relatório
node $SKILL/run.js --campaign crt-totem --report

# Stats
node $SKILL/run.js --campaign crt-totem --stats

# Enviar relatório por e-mail
node $SKILL/run.js --campaign crt-totem --report --email felipe@aya.cx

Criar nova campaign

# O Pi cria o JSON de campaign a partir de uma descrição
# Exemplo: "preciso garimpar projetores Epson usados em SP"

O Pi gera um campaigns/projetor-epson.json com termos de busca, playbook de classificação e critérios curatoriais.

Formato de Campaign

{
  "id": "crt-totem",
  "name": "CRTs para Totem CRT — PLAYER 1",
  "description": "TVs CRT 27-29 pol para instalação artística",
  "active": true,
  "created": "2026-03-24",

  "search": {
    "sources": ["olx"],
    "maxPages": 2,
    "delayMs": 3000,
    "terms": {
      "olx": ["tv tubo sony 29", "tv crt 29", "..."],
      "mercadolivre": ["tv tubo crt 29", "..."]
    },
    "location": "São Paulo",
    "fetchDetails": false
  },

  "classification": {
    "system_prompt": "Você é um especialista em TVs CRT vintage...",
    "user_prompt_template": "Analise este anúncio...\n\nTÍTULO: {title}\nDESCRIÇÃO: {description}\nPREÇO: {price}\nLOCAL: {location}",
    "score_weights": {
      "uniformity_frame": 0.30,
      "image_quality": 0.20,
      "availability": 0.15,
      "rarity": 0.10,
      "condition": 0.10,
      "price_attractiveness": 0.15
    },
    "priority_families": { "...": {} },
    "red_flags": ["liga mas não testei", "..."],
    "green_flags": ["testada", "funcionando", "..."]
  },

  "alerts": {
    "min_score": 2.5,
    "max_per_run": 10,
    "telegram": true,
    "email": null
  }
}

Stack

Componente Tecnologia Custo
Coleta OLX Crawl4AI (self-hosted no Unraid) $0
Coleta ML Crawl4AI $0
Normalização Gemini 2.5 Flash (free tier: 1500 req/dia) $0
Persistência JSON local (1 arquivo por campaign) $0
Alertas Telegram Bot API $0
Relatório Console + HTML (e-mail via aya-gmail) $0

Dependências

  • Node.js (já instalado)
  • Crawl4AI container no Unraid (192.168.15.169:11235)
  • GEMINI_API_KEY env var
  • Telegram (opcional): TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID
cd ~/.pi/agent/skills/felipe/szt-scraping-tool/scripts && npm install

Origem

Nasceu como ferramenta para o Totem CRT (PLAYER 1, exposição 19/06/2026). Generalizado em 24/03/2026 para aceitar qualquer "campaign" de garimpagem.

Gesto-origem (P2): Felipe precisava de 11 TVs CRT idênticas para uma instalação — coisa que não se compra em loja. O scraper nasce da necessidade de garimpar no mercado de usados com critério curatorial: uniformidade de moldura, família de produto, qualidade de imagem. Não é um comparador de preços — é uma ferramenta de curadoria de objetos.

Teste de existência (P3): o scraper existe fora do implante — roda como CLI, gera HTML, manda e-mail. Pode ser usado por qualquer pessoa com Node.js + Crawl4AI.

Campaigns ativas

Campaign Descrição Listings Status
crt-totem TVs CRT 27-29" para Totem CRT / PLAYER 1 90 🟢 ativa

Limitações conhecidas

  • Preços OLX — a página de lista não mostra preço (escondido em JS). Precisa de fetchDetails: true para pegar da página de detalhe (mais lento).
  • Mercado Livre — parsing de HTML frágil, muitos false positives em termos genéricos. Funciona bem com termos específicos.
  • Facebook Marketplace — collector não implementado ainda. Patchright está instalado para quando necessário.
  • Gemini JSON — o modelo às vezes retorna JSON malformado. O normalizer tem fallback de regex, mas ~5% dos anúncios podem precisar de retry.
  • Sem cron ainda — execução manual. Pode ser agendado no gateway quando estabilizar.

Evolução planejada

  1. Facebook Marketplace — collector via Patchright (anti-fingerprint)
  2. Gemini Vision — analisar fotos do anúncio para identificar modelo/estado
  3. Cron no gateway — rodar a cada 2-4h automaticamente
  4. Google Sheets — exportar ranking para planilha compartilhável
  5. Novas campaigns — projetores, sensores, equipamento de montagem