Documentação do Fisherboy

Esta página documenta como o Fisherboy funciona de ponta a ponta: os conceitos centrais, a interface web, as capacidades de download, as APIs REST e MCP, e a configuração avançada.

Conceitos

O job e o envelope

Tudo o que o Fisherboy faz é um job. Você submete um job (uma URL mais opções), ele é enfileirado no Redis, um worker roda o pipeline, e o resultado é armazenado como um envelope — um único objeto que contém o conteúdo extraído (content_md), registros estruturados, a árvore de crawl, os links descobertos e os metadados. Você consulta o job até que seu status seja ok.

Busca em camadas (escala somente quando bloqueado)

O Fisherboy nunca recorre a um navegador pesado até que seja necessário. Ele tenta o método mais barato primeiro e sobe apenas quando um gate detecta um bloqueio ou um CAPTCHA:

• Camada 0 — HTTP estático com httpx. Rápida e barata; funciona para a maioria das páginas estáticas.
• Camada 1 — fingerprint TLS com curl_cffi, para que a requisição pareça a de um navegador real na camada de rede.
• Camada 2 — navegador stealth (Camoufox / Patchright) para páginas pesadas em JavaScript e anti-bot; esta camada também conduz a captura de API oculta.
• Camada 3 — um navegador real (nodriver / Playwright) como último recurso.

A camada vencedora é cacheada por domínio (TIER_CACHE_TTL_S), de modo que a próxima requisição ao mesmo site começa de onde teve sucesso pela última vez. As camadas altas são importadas de forma lazy — a imagem base permanece leve, e cada camada só é ativada se sua biblioteca estiver instalada. O teto de escalonamento é definido com MAX_FETCH_TIER, e tier_hint em um job pode sugerir um ponto de partida.

Captura de API oculta

Aplicações de página única e grades dinâmicas renderizam a partir de JSON que buscam via XHR/fetch. Em vez de lutar com o HTML renderizado, o Fisherboy pode observar essas respostas de rede e manter o JSON que a página já consome — geralmente a fonte mais confiável e completa dos dados. Habilite-a por job com capture_api.

Modos de privacidade

O modo de privacidade é escolhido por job e limitado por papel (definido em privacy_matrix.yaml, nunca hardcoded). O pipeline é fail-closed: se a anonimização falhar, nada cru é entregue.

• opaque (opaco) — cada entidade vira um marcador tipado estável como «PERSON_1» ou «ID_2». O LLM raciocina sobre os marcadores e nunca vê a PII; o original não é recuperável.
• reversible — o mesmo mascaramento, mas um mapa criptografado de token para valor é mantido para que você possa re-hidratar depois via POST /api/revert (uso único, vinculado ao papel). O mapa é criptografado com uma chave Fernet (REVERSIBLE_KEY) e expira após REVERSIBLE_TTL_S.
• direct (directo) — saída crua, apenas para dados não sensíveis.

Uma passagem determinística de regex sempre roda para PII de alto risco (ID nacional, e-mail, IP, cartão válido por Luhn, telefone). Quando ANONIMAL_URL aponta para uma instância de Anonimal, o NER completo roda em cima disso; o modo standalone faz fallback apenas para a passagem de regex embutida.

Se um papel não permitir o modo solicitado, o gateway retorna 403 — ele nunca rebaixa silenciosamente.

Papéis

O Fisherboy tem três níveis de acesso, cada um com sua própria senha e limites de capacidade (quais camadas, proxies, captura de API, solucionador de captcha, crawl e tarântula são permitidos). Os papéis são aplicados em ambos, REST e MCP.

Papel	opaque	reversible	direct
humano	sim	—	—
angel	sim	sim	—
dios	sim	sim	sim

Em linhas gerais: humano obtém as camadas baratas e nenhuma “arma” cara; angel adiciona navegador, proxy e captura (mas nenhum solucionador de captcha); dios tem tudo. A tarântula e a leitura de cookies do navegador são vetadas no modo sidekick.

Usando a interface web

No modo standalone, o Fisherboy monta sua própria interface web na URL do serviço (ex. http://localhost:8000). Após fazer login com uma senha de papel, você:

1. Cola uma URL e escolhe a saída (markdown, llms_txt ou json) e o modo de privacidade permitido pelo seu papel.
2. Opcionalmente habilita extras — paginação, captura de API, uma profundidade de crawl, tarântula, um proxy, cookies.
3. Roda o job; o resultado abre em um editor modal.

O editor embutido

O resultado abre em um editor modal com três abas:

• Markdown — uma barra de ferramentas com pré-visualização ao vivo.
• JSON — um editor com validação.
• Tabela — uma tabela editável; JSON ↔ tabela é apenas trocar de aba.

Você pode baixar o resultado como .md, .json ou .csv. Você pode baixar o envelope inteiro, apenas os dados (conteúdo + registros + árvore + links), ou um array plano de registros. Um clique envia o resultado para o Escriba para conversão, anonimização, chunking e exportação adicionais.

Downloads

Além do texto da página, o Fisherboy pode extrair mídia e dados de plataforma:

• Arquivos — downloads diretos de arquivos.
• Vídeo — via yt-dlp (YouTube, Vimeo e muitos outros). O ffmpeg, incluído na imagem, faz a mux de vídeo + áudio em mp4 de alta qualidade; sem ele, os downloads fazem fallback para o melhor arquivo progressivo único.
• Galerias / imagens — via gallery-dl (Instagram, X, Reddit, Pinterest, Tumblr, Flickr, DeviantArt e mais).
• Comentários / dados de plataforma — multiplataforma; comentários de posts do Instagram e dados de seguidores/seguindo usam instaloader, que precisa de um cookie de sessão (IG_SESSIONID) e é restrito ao papel dios.

API REST

POST /api/jobs            # valida schema, papel × modo de privacidade, callback e proxy (SSRF); enfileira → 202
GET  /api/jobs/{job_id}   # status e resultado (o "envelope")
POST /api/proxy/test      # roteia uma requisição por um proxy; retorna IP de saída + país + latência
POST /api/revert          # re-hidrata conteúdo pseudonimizado (modo reversible)
POST /api/login           # login de papel (sessão por cookie)
GET  /healthz             # liveness
GET  /metrics             # métricas Prometheus

Submeta um job e consulte-o:

curl -X POST http://localhost:8000/api/jobs \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com/article","rol":"angel","privacy_mode":"opaco"}'
# → { "job_id": "…", "status": "pendiente" }

curl http://localhost:8000/api/jobs/<job_id>
# → o envelope com content_md anonimizado assim que status == "ok"

Campos do job

Campo	Notas
url	A página a buscar.
rol	humano / angel / dios.
privacy_mode	opaco / reversible / directo (limitado por papel).
output_format	markdown / llms_txt / json.
tier_hint	Camada inicial sugerida, 0–3.
crawl_depth	Profundidade para o crawl spider.
max_pages	Orçamento de páginas (limitado por CRAWL_MAX_PAGES).
paginate	Varrer a paginação.
capture_api	Capturar o JSON oculto de XHR/fetch.
tarantula	Capturar o conteúdo + API de cada nó em uma árvore de dados.
extract_schema	JSON Schema para extração estruturada (com output_format=json).
proxy	Override de proxy por job.
cookies	Cookies de sessão para a requisição.
callback_url	Webhook para receber o envelope na conclusão.

Nota

Os valores de job e status usam os identificadores originais em espanhol do projeto (ex. rol, os valores de privacy_mode opaco/reversible/directo, e o status pendiente/ok).

MCP

O mesmo pipeline é exposto como ferramentas MCP (submit_job, get_job, revert) para que n8n, Claude Code ou Escriba possam enfileirar sem escrever HTTP à mão:

python -m app.mcp_server      # requer fastmcp

O teto de papel do servidor MCP é definido por MCP_ROLE (ele não confia em um papel reivindicado pelo chamador).

Configuração avançada

Proxies

Cole um proxy em qualquer formato — host:port, host:port:user:pass, user:pass@host:port ou uma URL completa — e o Fisherboy o normaliza (socks5 suportado). O botão Test (ou POST /api/proxy/test) roteia uma requisição por ele e retorna seu IP de saída + país + latência, com uma dica acionável se não conseguir conectar. Configure um pool com PROXIES, escolha a rotação com PROXY_ROTATION (round_robin / random / sticky), e ajuste PROXY_COOLDOWN_S e PROXY_ATTEMPTS. Um job pode sobrescrever o pool com seu próprio proxy.

Cookies

Use páginas atrás de um login ou uma região sem uma extensão de navegador. Cole cookies como Netscape cookies.txt, JSON ou pares name=value, ou leia-os diretamente do seu navegador local (Chrome / Firefox / Edge / Brave). A leitura de cookies do navegador é somente standalone e vetada no modo sidekick.

CAPTCHA

A estratégia anti-CAPTCHA padrão é a prevenção por escalonamento (CAPTCHA_SOLVER=none): o gate de busca detecta um CAPTCHA e sobe uma camada. Opcionalmente, um solucionador externo via API pode ser configurado com CAPTCHA_SOLVER=external, CAPTCHA_SOLVER_URL e CAPTCHA_SOLVER_KEY (condicionado ao papel).

Paginação

Defina paginate em um job para varrer listagens de múltiplas páginas. O Fisherboy lida com esquemas comuns — postbacks ASP.NET, links “next” e padrões de query ?page=. O total é limitado por max_pages e pelo limite rígido CRAWL_MAX_PAGES.

Camadas de navegador

Para as camadas 2 e 3, ajuste o navegador headless com BROWSER_HEADLESS, BROWSER_SETTLE_S (espera após o load), BROWSER_SCROLL (dispara o lazy-load), BROWSER_LOCALE e BROWSER_USER_AGENT.

Spider e tarântula (crawl profundo)

• Spider — segue links internos formando uma árvore (com escopo por seção) até crawl_depth, opcionalmente combinado com paginação.
• Tarântula — o modo profundo: ela percorre cada nó e captura tanto seu conteúdo quanto sua API oculta em uma única árvore de dados. A tarântula é condicionada a papéis altos e vetada no modo sidekick.

O crawling de múltiplas páginas respeita robots.txt quando RESPECT_ROBOTS=1.

Segurança e limites

O Fisherboy é fail-closed e endurecido: anti-SSRF (DNS resolvido; faixas privadas/loopback/link-local/ metadados de nuvem bloqueadas, revalidadas a cada salto de redirecionamento e a cada requisição de navegador, incluindo o override de proxy), limpeza de segredos por job (credenciais de proxy, chave de captcha, cookies nunca aparecem no envelope ou no webhook), gating de papel em REST e MCP, rate-limiting (MAX_JOBS_PER_MIN), limites rígidos de páginas e bytes (CRAWL_MAX_PAGES, JOB_MAX_TOTAL_BYTES), e um container não-root. Revise a checklist de produção antes de expô-lo — nunca defina ALLOW_PRIVATE_TARGETS=1 ou FISHERBOY_OPEN_GOD=1 em produção.

Persistência e observabilidade opcionais

A persistência com Postgres + pgvector é opcional (DATABASE_URL, mais EMBEDDINGS_ENABLED para um armazenamento vetorial); sem ela o sistema roda apenas no Redis e degrada graciosamente. Uma stack Prometheus + Loki + Grafana está disponível via docker-compose.observability.yml.