Birdfolio
Birdfolio transforme les photos d'oiseaux en une liste de vie personnelle. Les utilisateurs prennent en photo des oiseaux en pleine nature, envoient la photo, et vous identifiez l'espèce avec Vision. You.com fournit des données de rareté et régionales en temps réel. Chaque observation est enregistrée dans une liste de vie avec un niveau de rareté inspiré des Pokémon (Commun / Rare / Super Rare) et une carte à collectionner visuelle est renvoyée via Telegram.
Les données se trouvent dans : Railway PostgreSQL (via API) + dossier local birdfolio/ (cartes, oiseaux, config)
Les scripts se trouvent dans : {baseDir}/scripts/
API : https://api-production-d0e2.up.railway.app (également sauvegardée dans birdfolio/config.json après l'initialisation)
Référence du schéma : {baseDir}/references/data-schema.md
Requêtes de recherche : {baseDir}/references/you-search-queries.md
Remarque concernant --workspace et --api-url : Chaque script de données accepte
--workspace(chemin absolu versbirdfolio/) et--api-url(URL de base de l'API). Après l'exécution deinit_birdfolio.py, l'URL de l'API et l'ID Telegram sont sauvegardés dansbirdfolio/config.jsonet lus automatiquement — les scripts suivants n'ont besoin que de--workspace.ID Telegram : Lu à partir des métadonnées du message entrant (
sender_id). Transmettez-le comme--telegram-idàinit_birdfolio.pylors de la première configuration.
1. Flux de configuration
Déclencheur : L'utilisateur dit « Configure mon Birdfolio », « définir ma région », ou envoie une photo avant que la configuration n'existe.
Vérifier d'abord : Si birdfolio/config.json existe dans votre espace de travail, la configuration est déjà effectuée — passez directement au flux concerné.
Étapes :
-
Demandez : « Quelle est votre région d'origine ? (ex. Californie, Texas, Royaume-Uni) »
-
Exécutez pour créer la structure de dossiers de l'espace de travail et enregistrer l'utilisateur dans l'API :
exec: python {baseDir}/scripts/init_birdfolio.py \ --telegram-id {senderTelegramId} \ --region "{region}" \ --api-url "https://api-production-d0e2.up.railway.app" \ --workspace <chemin absolu vers birdfolio/ dans votre espace de travail> -
Recherchez sur You.com (exécutez les trois) :
"{region} oiseaux de jardin les plus courants liste d'espèces eBird" "{region} oiseaux rares saisonniers peu communs checklist eBird" "{region} oiseaux rares vagabonds menacés eBird" -
À partir des résultats, construisez une checklist avec 10 communes, 5 rares, 1 super rare espèces. Utilisez les signaux de classification de
{baseDir}/references/you-search-queries.md. -
Écrivez la checklist remplie dans
birdfolio/checklist.jsondans votre espace de travail :{ "{region}": { "common": [ { "species": "Merle d'Amérique", "slug": "merle-damerique", "found": false, "dateFound": null } ], "rare": [...], "superRare": [...] } } -
Répondez avec un message de bienvenue et un aperçu de la checklist :
🦅 Birdfolio est configuré pour {region} ! Votre checklist : Communes (10) : Merle d'Amérique, Moineau domestique, ... Rares (5) : Grand Héron, ... Super Rare : Condor de Californie Envoyez-moi une photo d'oiseau pour commencer à collectionner !
2. Flux d'identification d'oiseau
Déclencheur : L'utilisateur envoie une photo.
Obtenir le chemin du fichier photo : Lorsqu'un utilisateur envoie une photo via Telegram, OpenClaw la télécharge et met le chemin du fichier local à disposition dans les métadonnées de la pièce jointe. Capturez ce chemin — vous en aurez besoin pour la génération de la carte à l'étape 5. Si OpenClaw fournit l'image en ligne sans chemin, utilisez
execpour trouver le fichier le plus récemment téléchargé dans le dossier temporaire/média d'OpenClaw, ou vérifiez%APPDATA%\openclaw\media\sur Windows. Sauvegardez la photo dansbirdfolio/birds/{slug}-{timestamp}.jpgpour stockage permanent :exec: copy "<chemin de la pièce jointe>" "birdfolio/birds/<slug>-<timestamp>.jpg"
Étape 1 — Identifier avec Vision
La photo soumise est directement visible dans votre contexte. Analysez-la (ou utilisez l'outil image si elle n'est pas en ligne) :
Identifiez l'espèce d'oiseau sur cette photo. Retournez uniquement du JSON :
{
"commonName": "...",
"scientificName": "...",
"confidence": "high|medium|low",
"features": ["caractéristique visible 1", "caractéristique visible 2"]
}
Règles de rareté :
- L'oiseau EST dans la checklist → utilisez son niveau :
common,rare, ousuperRare - L'oiseau N'est PAS dans la checklist → utilisez
bonus(affiche un badge neutre « Bonus Find », aucune rareté attribuée)
Règles de confiance :
"high"→ procédez automatiquement, aucune confirmation nécessaire"medium"→ demandez : « Je pense qu'il pourrait s'agir d'un [espèce] — d'après [caractéristiques]. Cela vous semble correct ? » → attendez la confirmation avant de continuer"low"→ répondez : « Cette photo n'est pas assez claire pour que je sois confiant. Pourriez-vous en envoyer une plus nette ? » → arrêtez-vous, n'enregistrez rien
Étape 2 — Recherche de rareté
Recherchez sur You.com :
"{commonName} {homeRegion} fréquence eBird à quel point commun rare"
Classifiez en utilisant ces signaux :
| Niveau | Valeur du script | Signaux |
|---|---|---|
| Commun 🟢 | common | « abondant », « répandu », « résident à l'année », >50% des checklists |
| Rare 🟡 | rare | « peu commun », « saisonnier », « migrateur », « occasionnel », 5–50% des checklists |
| Super Rare 🔴 | superRare | « rare », « vagabond », « accidentel », « menacé », <5% des checklists |
En cas de doute → par défaut rare. Utilisez toujours la valeur du script (ex. superRare, pas Super Rare) lorsque vous passez --rarity à un script.
Étape 3 — Obtenir un fait amusant
Recherchez sur You.com :
"{commonName} oiseau faits intéressants habitat comportement"
Extrayez un fait percutant (1–2 phrases).
Étape 4 — Enregistrer l'observation
Sauvegardez l'observation dans birdfolio/lifeList.json dans votre espace de travail :
exec: python {baseDir}/scripts/log_sighting.py \
--species "{commonName}" \
--scientific-name "{scientificName}" \
--rarity "{rarity}" \
--region "{homeRegion}" \
--notes "" \
--workspace <chemin absolu vers birdfolio/ dans votre espace de travail>
Capturez à partir de la sortie : isLifer, totalSightings, totalSpecies.
Étape 5 — Mettre à jour la checklist
Marquez l'espèce comme trouvée dans birdfolio/checklist.json :
exec: python {baseDir}/scripts/update_checklist.py \
--species "{commonName}" \
--region "{homeRegion}" \
--workspace <chemin absolu vers birdfolio/ dans votre espace de travail>
Étape 6 — Générer la carte à collectionner
La carte est un design à deux colonnes : la photo de l'utilisateur remplit le panneau gauche (280 px), un panneau d'information sombre uni se trouve à droite. Utilisez toujours la photo réelle soumise par l'utilisateur — pas une image générique.
Étape 6a — Détecter la position de l'oiseau avec Vision :
Utilisez l'outil image sur la photo soumise :
« Où se trouve l'oiseau horizontalement sur cette photo ? Donnez-moi approximativement le pourcentage depuis le bord gauche où se trouve le centre de l'oiseau (0–100). »
Convertissez la réponse en une valeur CSS : "40% center", "60% center", "center center", etc. Utilisez-la comme --object-position.
Étape 6b — Générer le HTML de la carte avec la photo intégrée :
exec: python {baseDir}/scripts/generate_card.py \
--species "{commonName}" \
--scientific-name "{scientificName}" \
--rarity "{rarity}" \
--region "{homeRegion}" \
--date "{AAAA-MM-JJ}" \
--fun-fact "{funFact}" \
--image-path "<chemin absolu vers la photo soumise>" \
--object-position "{objectPosition}" \
--life-count {totalSpecies} \
--workspace <chemin absolu vers birdfolio/ dans votre espace de travail>
--image-path intègre la photo réelle de l'utilisateur en base64 directement dans le HTML. Aucune étape d'intégration séparée nécessaire.
Solution de repli si le chemin de la photo est indisponible : omettez --image-path et transmettez --image-url "<URL d'image générique>" à la place (trouvez une URL via You.com : "{commonName} photo oiseau faune").
Capturez cardPath à partir de la sortie.
Étape 6c — Capture d'écran, sauvegarde, téléchargement et envoi : Exécutez le script de capture d'écran pour rendre la carte à 600×400 et sauvegarder un PNG :
exec: node {baseDir}/scripts/screenshot_card.js "<cardPath>"
Capturez pngPath à partir de la sortie.
Téléchargez vers Cloudflare R2 et obtenez une URL publique :
exec: python {baseDir}/scripts/upload_card.py "<pngPath>"
Capturez url à partir de la sortie.
Mettez à jour l'URL de la carte de l'observation dans l'API (utilisez l'id de la sortie de log_sighting) :
PATCH /users/{telegram_id}/sightings/{sighting_id}/card
Corps : {"card_png_url": "<url>"}
Envoyez le PNG via Telegram :
message(action="send", media="<pngPath>")
Étape 7 — Répondre
-
Si
isLiferest vrai : « 🎉 Nouveau lifer ! C'est votre tout premier [commonName] ! Oiseau #[totalSpecies] dans votre Birdfolio. »Si
totalSpecies == 1(c'est leur tout premier oiseau) : envoyez également leur lien PWA personnel : « 🦅 Votre Birdfolio est en ligne ! Ajoutez ce lien à vos favoris pour voir votre liste de vie : https://birdfolio.tonbistudio.com/app/[telegram_id] »telegram_idest l'ID Telegram de l'expéditeur provenant des métadonnées du message entrant (sender_id). Il est également stocké dansbirdfolio/config.jsonaprès l'initialisation. -
Sinon : « [commonName] repéré ! Vous avez maintenant vu [N] espèces dans votre Birdfolio. »
Incluez : l'emoji du badge de rareté, le fait amusant, le statut de la checklist (si l'espèce était sur la checklist, mentionnez-le).
Solution de repli si la capture d'écran échoue : Envoyez une carte textuelle formatée :
🦅 [EMOJI_RARETÉ] [Nom commun]
Scientifique : [Nom scientifique]
Région : [Région] | Repéré : [Date]
Rareté : [Rareté]
💡 [Fait amusant]
Oiseau #[N] dans votre Birdfolio
3. Checklist et statistiques
Déclencheur : « Comment va ma checklist ? », « Progrès Birdfolio », « Combien d'oiseaux ai-je trouvés ? »
exec: python {baseDir}/scripts/get_stats.py \
--workspace <chemin absolu vers birdfolio/ dans votre espace de travail>
Formatez la réponse en utilisant checklistProgress de la sortie :
📋 Checklist {region}
Communes ✅✅✅⬜⬜⬜⬜⬜⬜⬜ 3/10
Rares ✅⬜⬜⬜⬜ 1/5
Super Rares ⬜ 0/1
🐦 {totalSpecies} espèces | {totalSightings} observations au total
📍 Dernier repéré : {mostRecentSighting.commonName} le {date}
🏆 Trouvaille la plus rare : {rarestBird.commonName} ({rarity})
Utilisez ✅ pour trouvé, ⬜ pour non trouvé. Une case par espèce.
Carte checklist visuelle optionnelle : Générez une carte checklist HTML visuelle et capturez-la :
exec: python {baseDir}/scripts/generate_checklist_card.py \
--workspace <chemin absolu vers birdfolio/ dans votre espace de travail>
Capturez-la ensuite avec screenshot_card.js et envoyez le PNG.
4. Vue de la liste de vie
Déclencheur : « Montre mon Birdfolio », « Montre ma liste de vie »
Lisez birdfolio/lifeList.json depuis votre espace de travail.
Regroupez les lifers par rareté (Super Rare en premier, puis Rare, puis Commun). Formatez comme une liste textuelle ou générez une galerie HTML, sauvegardez-la dans birdfolio/my-birdfolio.html dans votre espace de travail, et capturez-la.
5. Recherche d'espèce (sans enregistrement)
Déclencheur : « Parle-moi de [espèce] »
Recherchez sur You.com :
"{species} oiseau faits habitat répartition comportement alimentation"
"{species} oiseau {homeRegion} fréquence eBird résident ou migrateur"
Retournez un résumé conversationnel. N'enregistrez pas d'observation et ne générez pas de carte.
6. Oiseau le plus rare
Déclencheur : « Quel est mon oiseau le plus rare ? », « Montre ma meilleure trouvaille »
exec: python {baseDir}/scripts/get_stats.py \
--workspace <chemin absolu vers birdfolio/ dans votre espace de travail>
Lisez rarestBird de la sortie et répondez avec le nom de l'espèce, la rareté, la date de repérage et la région.
Référence rapide
| Script | Arguments clés | Retourne |
|---|---|---|
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 (préféré) OU --image-url, --object-position, --life-count, --workspace | {status, cardPath, filename} |
generate_checklist_card.py | --workspace | {status, cardPath} — carte checklist HTML visuelle |
screenshot_card.js | <cardPath> [outputPath] | {status, pngPath} — sauvegarde PNG dans birdfolio/cards/ |
upload_card.py | <pngPath> [--secrets path] | {status, url} — télécharge vers R2, retourne une URL publique |
Tous les scripts Python produisent du JSON sur stdout. Transmettez toujours le chemin absolu --workspace.
screenshot_card.js utilise le playwright-core intégré d'OpenClaw + Chrome/Edge système (aucune installation séparée nécessaire).