¿Qué hace Birdfolio?
Birdfolio convierte fotos de aves en una lista de vida personal. Los usuarios fotografían aves en la naturaleza, te envían la foto, y tú identificas la especie con Visión. You.com proporciona datos de rareza y región en tiempo real. Cada avistamiento se registra en una lista de vida con un nivel de rareza inspirado en Pokémon (Común / Raro / Super Raro) y recibe una tarjeta coleccionable visual enviada de vuelta a través de Telegram.
Los datos residen en: Railway PostgreSQL (vía API) + carpeta local birdfolio/ (tarjetas, aves, configuración)
Los scripts residen en: {baseDir}/scripts/
API: https://api-production-d0e2.up.railway.app (también guardado en birdfolio/config.json después de la inicialización)
Referencia de esquema: {baseDir}/references/data-schema.md
Consultas de búsqueda: {baseDir}/references/you-search-queries.md
Nota sobre --workspace y --api-url: Cada script de datos acepta
--workspace(ruta absoluta abirdfolio/) y--api-url(URL base de la API). Después de ejecutarinit_birdfolio.py, tanto la URL de la API como el ID de Telegram se guardan enbirdfolio/config.jsony se leen automáticamente; los scripts posteriores solo necesitan--workspace.ID de Telegram: Se lee de los metadatos del mensaje entrante (
sender_id). Pásalo como--telegram-idainit_birdfolio.pyen la configuración inicial.
1. Flujo de Configuración
Desencadenante: El usuario dice "Configurar mi Birdfolio", "establecer mi región", o envía una foto antes de que exista la configuración.
Comprobar primero: Si birdfolio/config.json existe en tu espacio de trabajo, la configuración ya está hecha — salta al flujo correspondiente.
Pasos:
-
Pregunta: "¿Cuál es tu región de origen? (ej. California, Texas, Reino Unido)"
-
Ejecuta para crear la estructura de carpetas del espacio de trabajo y registrar al usuario en la API:
exec: python {baseDir}/scripts/init_birdfolio.py \ --telegram-id {senderTelegramId} \ --region "{region}" \ --api-url "https://api-production-d0e2.up.railway.app" \ --workspace <ruta absoluta a birdfolio/ en tu espacio de trabajo> -
Busca en You.com (ejecuta las tres):
"{region} aves de jardín más comunes lista de especies eBird" "{region} aves raras estacionales poco comunes lista de verificación eBird" "{region} aves raras vagabundas en peligro eBird" -
A partir de los resultados, construye una lista de verificación con 10 especies comunes, 5 raras, 1 super rara. Usa las señales de clasificación de
{baseDir}/references/you-search-queries.md. -
Escribe la lista de verificación poblada en
birdfolio/checklist.jsonen tu espacio de trabajo:{ "{region}": { "common": [ { "species": "Mirlo americano", "slug": "mirlo-americano", "found": false, "dateFound": null } ], "rare": [...], "superRare": [...] } } -
Responde con un mensaje de bienvenida y una vista previa de la lista de verificación:
🦅 ¡Birdfolio configurado para {region}! Tu lista de verificación: Comunes (10): Mirlo americano, Gorrión doméstico, ... Raras (5): Garza azulada, ... Super Rara: Cóndor de California ¡Envíame una foto de un ave para empezar a coleccionar!
2. Flujo de Identificación de Aves
Desencadenante: El usuario envía una foto.
Obteniendo la ruta del archivo de la foto: Cuando un usuario envía una foto a través de Telegram, OpenClaw la descarga y hace que la ruta local del archivo esté disponible en los metadatos del archivo adjunto del mensaje. Captura esta ruta; la necesitarás para la generación de la tarjeta en el Paso 5. Si OpenClaw proporciona la imagen en línea sin una ruta, usa
execpara encontrar el archivo descargado más recientemente en la carpeta temporal/media de OpenClaw, o verifica%APPDATA%\openclaw\media\en Windows. Guarda la foto enbirdfolio/birds/{slug}-{timestamp}.jpgpara almacenamiento permanente:exec: copy "<ruta del adjunto>" "birdfolio/birds/<slug>-<timestamp>.jpg"
Paso 1 — Identificar con Visión
La foto enviada es directamente visible en tu contexto. Analízala (o usa la herramienta image si no está en línea):
Identifica la especie de ave en esta foto. Devuelve solo JSON:
{
"commonName": "...",
"scientificName": "...",
"confidence": "high|medium|low",
"features": ["característica visible 1", "característica visible 2"]
}
Reglas de rareza:
- El ave ESTÁ en la lista de verificación → usa su nivel:
common,rareosuperRare - El ave NO está en la lista de verificación → usa
bonus(muestra una insignia neutral "Hallazgo Bonus", sin rareza asignada)
Reglas de confianza:
"high"→ procede automáticamente, no se necesita confirmación"medium"→ pregunta: "Creo que esto podría ser un/a [especie] — basado en [características]. ¿Te parece correcto?" → espera confirmación antes de continuar"low"→ responde: "Esta foto no es lo suficientemente clara para que yo esté seguro/a. ¿Podrías enviar una foto más nítida?" → detente, no registres nada
Paso 2 — Consulta de rareza
Busca en You.com:
"{commonName} {homeRegion} eBird frecuencia qué tan común raro"
Clasifica usando estas señales:
| Nivel | Valor en script | Señales |
|---|---|---|
| Común 🟢 | common | "abundante", "extendido", "residente todo el año", >50% de listas de verificación |
| Raro 🟡 | rare | "poco común", "estacional", "migratorio", "ocasional", 5–50% de listas de verificación |
| Super Raro 🔴 | superRare | "raro", "vagabundo", "accidental", "en peligro", <5% de listas de verificación |
Cuando no estés seguro → usa por defecto rare. Siempre usa el valor del script (ej. superRare, no Super Rare) al pasar --rarity a cualquier script.
Paso 3 — Obtener un dato curioso
Busca en You.com:
"{commonName} ave datos interesantes hábitat comportamiento"
Extrae un dato contundente (1–2 oraciones).
Paso 4 — Registrar el avistamiento
Guarda el avistamiento en birdfolio/lifeList.json en tu espacio de trabajo:
exec: python {baseDir}/scripts/log_sighting.py \
--species "{commonName}" \
--scientific-name "{scientificName}" \
--rarity "{rarity}" \
--region "{homeRegion}" \
--notes "" \
--workspace <ruta absoluta a birdfolio/ en tu espacio de trabajo>
Captura de la salida: isLifer, totalSightings, totalSpecies.
Paso 5 — Actualizar lista de verificación
Marca la especie como encontrada en birdfolio/checklist.json:
exec: python {baseDir}/scripts/update_checklist.py \
--species "{commonName}" \
--region "{homeRegion}" \
--workspace <ruta absoluta a birdfolio/ en tu espacio de trabajo>
Paso 6 — Generar tarjeta coleccionable
La tarjeta tiene un diseño de dos columnas: la foto del usuario llena el panel izquierdo (280px), un panel de información oscuro y sólido está a la derecha. Siempre usa la foto real enviada por el usuario — no una imagen de archivo.
Paso 6a — Detectar posición del ave con Visión:
Usa la herramienta image en la foto enviada:
"¿Dónde está posicionada el ave horizontalmente en esta foto? Dame aproximadamente el porcentaje desde el borde izquierdo donde está el centro del ave (0–100)."
Convierte la respuesta a un valor CSS: "40% center", "60% center", "center center", etc. Úsalo como --object-position.
Paso 6b — Generar el HTML de la tarjeta con la foto incrustada:
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 "<ruta absoluta a la foto enviada>" \
--object-position "{objectPosition}" \
--life-count {totalSpecies} \
--workspace <ruta absoluta a birdfolio/ en tu espacio de trabajo>
--image-path incrusta la foto real del usuario como base64 directamente en el HTML. No se necesita un paso de incrustación separado.
Alternativa si la ruta de la foto no está disponible: omite --image-path y pasa --image-url "<URL de foto de archivo>" en su lugar (encuentra una URL a través de You.com: "{commonName} foto de ave vida silvestre").
Captura cardPath de la salida.
Paso 6c — Captura de pantalla, guardar, subir y enviar: Ejecuta el script de captura de pantalla para renderizar la tarjeta a 600×400 y guardar un PNG:
exec: node {baseDir}/scripts/screenshot_card.js "<cardPath>"
Captura pngPath de la salida.
Sube a Cloudflare R2 y obtén una URL pública:
exec: python {baseDir}/scripts/upload_card.py "<pngPath>"
Captura url de la salida.
Actualiza la URL de la tarjeta del avistamiento en la API (usa el id de la salida de log_sighting):
PATCH /users/{telegram_id}/sightings/{sighting_id}/card
Body: {"card_png_url": "<url>"}
Envía el PNG a través de Telegram:
message(action="send", media="<pngPath>")
Paso 7 — Responder
-
Si
isLiferes verdadero: "🎉 ¡Nuevo lifer! Esa es tu primera vez con [commonName]! ¡Ave #[totalSpecies] en tu Birdfolio!"Si
totalSpecies == 1(esta es su primera ave de todas): también envía su enlace PWA personal: "🦅 ¡Tu Birdfolio está activo! Marca este enlace para ver tu lista de vida: https://birdfolio.tonbistudio.com/app/[telegram_id]"El
telegram_ides el ID de Telegram del remitente de los metadatos del mensaje entrante (sender_id). También se guarda enbirdfolio/config.jsondespués de la inicialización. -
Si no: "¡[commonName] avistado/a! Ahora has visto [N] especies en tu Birdfolio."
Incluye: emoji de insignia de rareza, el dato curioso, estado de la lista de verificación (si la especie estaba en la lista de verificación, menciónalo).
Alternativa si falla la captura de pantalla: Envía una tarjeta de texto formateada:
🦅 [RARITY_EMOJI] [Nombre Común]
Científico: [Nombre Científico]
Región: [Región] | Avistado/a: [Fecha]
Rareza: [Rareza]
💡 [Dato Curioso]
Ave #[N] en tu Birdfolio
3. Lista de Verificación y Estadísticas
Desencadenante: "¿Cómo está mi lista de verificación?", "Progreso de Birdfolio", "¿Cuántas aves he encontrado?"
exec: python {baseDir}/scripts/get_stats.py \
--workspace <ruta absoluta a birdfolio/ en tu espacio de trabajo>
Formatea la respuesta usando checklistProgress de la salida:
📋 Lista de Verificación de {region}
Comunes ✅✅✅⬜⬜⬜⬜⬜⬜⬜ 3/10
Raras ✅⬜⬜⬜⬜ 1/5
Super Raras ⬜ 0/1
🐦 {totalSpecies} especies | {totalSightings} avistamientos totales
📍 Último avistamiento: {mostRecentSighting.commonName} el {date}
🏆 Hallazgo más raro: {rarestBird.commonName} ({rarity})
Usa ✅ para encontrado, ⬜ para no encontrado. Una casilla por especie.
Tarjeta de lista de verificación visual opcional: Genera una tarjeta HTML visual de la lista de verificación y haz una captura de pantalla:
exec: python {baseDir}/scripts/generate_checklist_card.py \
--workspace <ruta absoluta a birdfolio/ en tu espacio de trabajo>
Luego haz una captura de pantalla con screenshot_card.js y envía el PNG.
4. Vista de Lista de Vida
Desencadenante: "Mostrar mi Birdfolio", "Mostrar mi lista de vida"
Lee birdfolio/lifeList.json de tu espacio de trabajo.
Agrupa los lifers por rareza (primero Super Raras, luego Raras, luego Comunes). Formatea como una lista de texto o genera una galería HTML, guárdala en birdfolio/my-birdfolio.html en tu espacio de trabajo, y haz una captura de pantalla.
5. Consulta de Especies (sin registro)
Desencadenante: "Cuéntame sobre [especie]"
Busca en You.com:
"{species} ave datos hábitat rango comportamiento dieta"
"{species} ave {homeRegion} eBird frecuencia residente o migratoria"
Devuelve un resumen conversacional. No registres un avistamiento ni generes una tarjeta.
6. Ave Más Rara
Desencadenante: "¿Cuál es mi ave más rara?", "Mostrar mi mejor hallazgo"
exec: python {baseDir}/scripts/get_stats.py \
--workspace <ruta absoluta a birdfolio/ en tu espacio de trabajo>
Lee rarestBird de la salida y responde con el nombre de la especie, rareza, fecha de avistamiento y región.
Referencia Rápida
| Script | Argumentos clave | Devuelve |
|---|---|---|
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} o {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) O --image-url, --object-position, --life-count, --workspace | {status, cardPath, filename} |
generate_checklist_card.py | --workspace | {status, cardPath} — tarjeta HTML visual de lista de verificación |
screenshot_card.js | <cardPath> [outputPath] | {status, pngPath} — guarda PNG en birdfolio/cards/ |
upload_card.py | <pngPath> [--secrets path] | {status, url} — sube a R2, devuelve URL pública |
Todos los scripts de Python generan JSON en stdout. Siempre pasa la ruta absoluta --workspace.
screenshot_card.js usa playwright-core incluido en OpenClaw + Chrome/Edge del sistema (no se necesita instalación por separado).