O que Birdfolio faz?
Birdfolio transforma fotos de aves em uma lista de vida pessoal. Os usuários fotografam aves na natureza, enviam a foto para você, e você identifica a espécie com Visão. O You.com fornece dados de raridade e região em tempo real. Cada avistamento é registrado em uma lista de vida com uma classificação de raridade inspirada em Pokémon (Comum / Raro / Super Raro) e ganha uma carta colecionável visual enviada de volta via Telegram.
Dados armazenados em: Railway PostgreSQL (via API) + pasta local birdfolio/ (cartas, aves, configuração)
Scripts armazenados em: {baseDir}/scripts/
API: https://api-production-d0e2.up.railway.app (também salva em birdfolio/config.json após a inicialização)
Referência de esquema: {baseDir}/references/data-schema.md
Consultas de pesquisa: {baseDir}/references/you-search-queries.md
Nota sobre --workspace e --api-url: Cada script de dados aceita
--workspace(caminho absoluto parabirdfolio/) e--api-url(URL base da API). Após a execução deinit_birdfolio.py, a URL da API e o ID do Telegram são salvos embirdfolio/config.jsone lidos automaticamente — scripts subsequentes precisam apenas de--workspace.ID do Telegram: Lido dos metadados da mensagem recebida (
sender_id). Passe como--telegram-idparainit_birdfolio.pyna configuração inicial.
1. Fluxo de Configuração
Gatilho: O usuário diz "Configurar meu Birdfolio", "definir minha região" ou envia uma foto antes da configuração existir.
Verificar primeiro: Se birdfolio/config.json existir no seu workspace, a configuração já está concluída — pule para o fluxo relevante.
Passos:
-
Pergunte: "Qual é a sua região de origem? (ex.: São Paulo, Brasil, Portugal)"
-
Execute para criar a estrutura de pastas do workspace e registrar o usuário na API:
exec: python {baseDir}/scripts/init_birdfolio.py \ --telegram-id {senderTelegramId} \ --region "{region}" \ --api-url "https://api-production-d0e2.up.railway.app" \ --workspace <caminho absoluto para birdfolio/ no seu workspace> -
Pesquise no You.com (execute todos os três):
"{region} aves mais comuns em quintais lista de espécies WikiAves" "{region} aves incomuns sazonais raras checklist WikiAves" "{region} aves raras vagantes ameaçadas de extinção WikiAves" -
A partir dos resultados, monte um checklist com 10 comuns, 5 raras, 1 super rara espécies. Use sinais de classificação de
{baseDir}/references/you-search-queries.md. -
Escreva o checklist preenchido em
birdfolio/checklist.jsonno seu workspace:{ "{region}": { "common": [ { "species": "Sabiá-laranjeira", "slug": "sabia-laranjeira", "found": false, "dateFound": null } ], "rare": [...], "superRare": [...] } } -
Responda com uma mensagem de boas-vindas e pré-visualização do checklist:
🦅 Birdfolio configurado para {region}! Seu checklist: Comuns (10): Sabiá-laranjeira, Pardal, ... Raras (5): Garça-azul, ... Super Rara: Ararinha-azul Envie uma foto de ave para começar a colecionar!
2. Fluxo de Identificação de Aves
Gatilho: O usuário envia uma foto.
Obtendo o caminho do arquivo da foto: Quando um usuário envia uma foto via Telegram, o OpenClaw a baixa e disponibiliza o caminho do arquivo local nos metadados do anexo da mensagem. Capture este caminho — você precisará dele para a geração da carta na Etapa 5. Se o OpenClaw fornecer a imagem inline sem um caminho, use
execpara encontrar o arquivo baixado mais recentemente na pasta temp/media do OpenClaw, ou verifique%APPDATA%\openclaw\media\no Windows. Salve a foto embirdfolio/birds/{slug}-{timestamp}.jpgpara armazenamento permanente:exec: copy "<caminho do anexo>" "birdfolio/birds/<slug>-<timestamp>.jpg"
Etapa 1 — Identificar com Visão
A foto enviada está diretamente visível no seu contexto. Analise-a (ou use a ferramenta image se não estiver inline):
Identifique a espécie de ave nesta foto. Retorne apenas JSON:
{
"commonName": "...",
"scientificName": "...",
"confidence": "alta|média|baixa",
"features": ["característica visível 1", "característica visível 2"]
}
Regras de raridade:
- A ave ESTÁ no checklist → use seu nível:
common,rareousuperRare - A ave NÃO ESTÁ no checklist → use
bonus(mostra um selo neutro "Achado Bônus", sem raridade atribuída)
Regras de confiança:
"alta"→ prossiga automaticamente, nenhuma confirmação necessária"média"→ pergunte: "Acho que pode ser um(a) [espécie] — com base em [características]. Isso parece correto para você?" → aguarde confirmação antes de continuar"baixa"→ responda: "Esta foto não está clara o suficiente para eu ter confiança. Você poderia enviar uma foto mais nítida?" → pare, não registre nada
Etapa 2 — Consulta de raridade
Pesquise no You.com:
"{commonName} {homeRegion} frequência WikiAves quão comum raro"
Classifique usando estes sinais:
| Nível | Valor do script | Sinais |
|---|---|---|
| Comum 🟢 | common | "abundante", "generalizada", "residente anual", >50% dos checklists |
| Raro 🟡 | rare | "incomum", "sazonal", "migratório", "ocasional", 5–50% dos checklists |
| Super Raro 🔴 | superRare | "raro", "vagante", "acidental", "ameaçado", <5% dos checklists |
Quando estiver em dúvida → use como padrão rare. Sempre use o valor do script (ex.: superRare, não Super Rare) ao passar --rarity para qualquer script.
Etapa 3 — Obter um fato curioso
Pesquise no You.com:
"{commonName} ave fatos interessantes habitat comportamento"
Extraia um fato impactante (1–2 frases).
Etapa 4 — Registrar o avistamento
Salve o avistamento em birdfolio/lifeList.json no seu workspace:
exec: python {baseDir}/scripts/log_sighting.py \
--species "{commonName}" \
--scientific-name "{scientificName}" \
--rarity "{rarity}" \
--region "{homeRegion}" \
--notes "" \
--workspace <caminho absoluto para birdfolio/ no seu workspace>
Capture da saída: isLifer, totalSightings, totalSpecies.
Etapa 5 — Atualizar checklist
Marque a espécie como encontrada em birdfolio/checklist.json:
exec: python {baseDir}/scripts/update_checklist.py \
--species "{commonName}" \
--region "{homeRegion}" \
--workspace <caminho absoluto para birdfolio/ no seu workspace>
Etapa 6 — Gerar carta colecionável
A carta tem um design de duas colunas: a foto do usuário preenche o painel esquerdo (280px), um painel de informações escuro sólido fica à direita. Sempre use a foto real enviada pelo usuário — não uma imagem de banco de imagens.
Etapa 6a — Detectar posição da ave com Visão:
Use a ferramenta image na foto enviada:
"Onde a ave está posicionada horizontalmente nesta foto? Dê-me aproximadamente a porcentagem a partir da borda esquerda em que o centro da ave está (0–100)."
Converta a resposta em um valor CSS: "40% center", "60% center", "center center", etc. Use isso como --object-position.
Etapa 6b — Gerar o HTML da carta com a foto incorporada:
exec: python {baseDir}/scripts/generate_card.py \
--species "{commonName}" \
--scientific-name "{scientificName}" \
--rarity "{rarity}" \
--region "{homeRegion}" \
--date "{YYYY-MM-DD}" \
--fun-fact "{funFact}" \
--image-path "<caminho absoluto para a foto enviada>" \
--object-position "{objectPosition}" \
--life-count {totalSpecies} \
--workspace <caminho absoluto para birdfolio/ no seu workspace>
--image-path incorpora a foto real do usuário como base64 diretamente no HTML. Nenhuma etapa de incorporação separada é necessária.
Fallback se o caminho da foto não estiver disponível: omita --image-path e passe --image-url "<URL da foto de banco de imagens>" (encontre uma URL via You.com: "{commonName} ave foto vida selvagem").
Capture cardPath da saída.
Etapa 6c — Capturar tela, salvar, fazer upload e enviar: Execute o script de captura de tela para renderizar a carta em 600×400 e salvar um PNG:
exec: node {baseDir}/scripts/screenshot_card.js "<cardPath>"
Capture pngPath da saída.
Faça upload para Cloudflare R2 e obtenha uma URL pública:
exec: python {baseDir}/scripts/upload_card.py "<pngPath>"
Capture url da saída.
Atualize a URL da carta do avistamento na API (use o id da saída do log_sighting):
PATCH /users/{telegram_id}/sightings/{sighting_id}/card
Body: {"card_png_url": "<url>"}
Envie o PNG via Telegram:
message(action="send", media="<pngPath>")
Etapa 7 — Responder
-
Se
isLiferfor verdadeiro: "🎉 Novo lifer! Esse é o seu primeiro [commonName]! Pássaro #[totalSpecies] no seu Birdfolio."Se
totalSpecies == 1(este é o primeiro pássaro deles de todos): também envie o link PWA pessoal: "🦅 Seu Birdfolio está no ar! Marque este link para ver sua lista de vida: https://birdfolio.tonbistudio.com/app/[telegram_id]"O
telegram_idé o ID do Telegram do remetente dos metadados da mensagem recebida (sender_id). Também está armazenado embirdfolio/config.jsonapós a inicialização. -
Caso contrário: "[commonName] avistado(a)! Você já viu [N] espécies no seu Birdfolio."
Inclua: emoji do selo de raridade, o fato curioso, status do checklist (se a espécie estava no checklist, mencione).
Fallback se a captura de tela falhar: Envie uma carta de texto formatada:
🦅 [RARITY_EMOJI] [Nome Comum]
Científico: [Nome Científico]
Região: [Região] | Avistado: [Data]
Raridade: [Raridade]
💡 [Fato Curioso]
Pássaro #[N] no seu Birdfolio
3. Checklist e Estatísticas
Gatilho: "Como está meu checklist?", "Progresso do Birdfolio", "Quantas aves eu encontrei?"
exec: python {baseDir}/scripts/get_stats.py \
--workspace <caminho absoluto para birdfolio/ no seu workspace>
Formate a resposta usando checklistProgress da saída:
📋 {region} Checklist
Comuns ✅✅✅⬜⬜⬜⬜⬜⬜⬜ 3/10
Raras ✅⬜⬜⬜⬜ 1/5
Super Raras ⬜ 0/1
🐦 {totalSpecies} espécies | {totalSightings} avistamentos totais
📍 Último avistamento: {mostRecentSighting.commonName} em {date}
🏆 Achado mais raro: {rarestBird.commonName} ({rarity})
Use ✅ para encontrado, ⬜ para não encontrado. Uma caixa por espécie.
Cartão de checklist visual opcional: Gere um cartão de checklist HTML visual e capture a tela:
exec: python {baseDir}/scripts/generate_checklist_card.py \
--workspace <caminho absoluto para birdfolio/ no seu workspace>
Depois capture a tela com screenshot_card.js e envie o PNG.
4. Visualização da Lista de Vida
Gatilho: "Mostrar meu Birdfolio", "Mostrar minha lista de vida"
Leia birdfolio/lifeList.json do seu workspace.
Agrupe os lifers por raridade (Super Raro primeiro, depois Raro, depois Comum). Formate como uma lista de texto ou gere uma galeria HTML, salve em birdfolio/my-birdfolio.html no seu workspace e capture a tela.
5. Consulta de Espécie (sem registro)
Gatilho: "Fale sobre [espécie]"
Pesquise no You.com:
"{species} ave fatos habitat alcance comportamento dieta"
"{species} ave {homeRegion} frequência WikiAves residente ou migratório"
Retorne um resumo conversacional. Não registre um avistamento nem gere uma carta.
6. Ave Mais Rara
Gatilho: "Qual é a minha ave mais rara?", "Mostrar meu melhor achado"
exec: python {baseDir}/scripts/get_stats.py \
--workspace <caminho absoluto para birdfolio/ no seu workspace>
Leia rarestBird da saída e responda com o nome da espécie, raridade, data do avistamento e região.
Referência Rápida
| Script | Principais argumentos | Retorna |
|---|---|---|
init_birdfolio.py | --telegram-id, --region, --api-url, --workspace | {status, workspace, files_created, next} |
log_sighting.py | --species, --scientific-name, --rarity, --region, --date, --workspace | {status, sighting, isLifer, totalSightings, totalSpecies} |
update_checklist.py | --species, --region, --workspace | {status, tier, dateFound} ou {status: not_on_checklist} |
get_stats.py | --workspace | {totalSightings, totalSpecies, checklistProgress, mostRecentSighting, rarestBird} |
generate_card.py | --species, --scientific-name, --rarity, --region, --date, --fun-fact, --image-path (preferido) OU --image-url, --object-position, --life-count, --workspace | {status, cardPath, filename} |
generate_checklist_card.py | --workspace | {status, cardPath} — cartão de checklist HTML visual |
screenshot_card.js | <cardPath> [outputPath] | {status, pngPath} — salva PNG em birdfolio/cards/ |
upload_card.py | <pngPath> [--secrets path] | {status, url} — envia para R2, retorna URL pública |
Todos os scripts Python produzem JSON no stdout. Sempre passe o caminho absoluto --workspace.
screenshot_card.js usa o playwright-core incluído do OpenClaw + Chrome/Edge do sistema (nenhuma instalação separada necessária).