Was macht Birdfolio?
Birdfolio verwandelt Vogelfotos in eine persönliche Lebensliste. Benutzer fotografieren Vögel in der freien Wildbahn, senden das Foto an Sie, und Sie identifizieren die Art mit Vision. You.com liefert Echtzeit-Seltenheits- und Regionaldaten. Jede Sichtung wird mit einer Pokémon-inspirierten Seltenheitsstufe (Häufig / Selten / Super Selten) in einer Lebensliste protokolliert und erhält eine visuelle Sammelkarte, die über Telegram zurückgesendet wird.
Daten leben in: Railway PostgreSQL (via API) + lokaler birdfolio/-Ordner (Karten, Vögel, Konfiguration)
Skripte leben in: {baseDir}/scripts/
API: https://api-production-d0e2.up.railway.app (auch nach der Initialisierung in birdfolio/config.json gespeichert)
Schema-Referenz: {baseDir}/references/data-schema.md
Suchabfragen: {baseDir}/references/you-search-queries.md
Hinweis zu --workspace & --api-url: Jedes Datenskript akzeptiert
--workspace(absoluter Pfad zubirdfolio/) und--api-url(API-Basis-URL). Nachdeminit_birdfolio.pyausgeführt wurde, werden sowohl die API-URL als auch die Telegram-ID inbirdfolio/config.jsongespeichert und automatisch gelesen – nachfolgende Skripte benötigen nur noch--workspace.Telegram-ID: Wird aus den Metadaten der eingehenden Nachricht (
sender_id) gelesen. Wird beim ersten Setup als--telegram-idaninit_birdfolio.pyübergeben.
1. Einrichtungsablauf
Auslöser: Benutzer sagt „Birdfolio einrichten", „Region festlegen" oder sendet ein Foto, bevor die Einrichtung abgeschlossen ist.
Zuerst prüfen: Wenn birdfolio/config.json in Ihrem Arbeitsbereich existiert, ist die Einrichtung bereits abgeschlossen – springen Sie zum entsprechenden Ablauf.
Schritte:
-
Frage: „Was ist Ihre Heimatregion? (z.B. Kalifornien, Texas, Vereinigtes Königreich)"
-
Ausführen, um die Ordnerstruktur des Arbeitsbereichs zu erstellen und den Benutzer in der API zu registrieren:
exec: python {baseDir}/scripts/init_birdfolio.py \ --telegram-id {senderTelegramId} \ --region "{region}" \ --api-url "https://api-production-d0e2.up.railway.app" \ --workspace <absoluter Pfad zu birdfolio/ in Ihrem Arbeitsbereich> -
You.com durchsuchen (alle drei ausführen):
"{region} häufigste Hinterhofvögel eBird Artenliste" "{region} ungewöhnliche saisonale seltene Vögel eBird Checkliste" "{region} seltene vagabundierende gefährdete Vögel eBird" -
Aus den Ergebnissen eine Checkliste mit 10 häufigen, 5 seltenen, 1 super seltenen Art erstellen. Verwenden Sie Klassifikationssignale aus
{baseDir}/references/you-search-queries.md. -
Die gefüllte Checkliste in
birdfolio/checklist.jsonin Ihrem Arbeitsbereich schreiben:{ "{region}": { "common": [ { "species": "Amerikanisches Rotkehlchen", "slug": "amerikanisches-rotkehlchen", "found": false, "dateFound": null } ], "rare": [...], "superRare": [...] } } -
Mit einer Begrüßungsnachricht und einer Checklisten-Vorschau antworten:
🦅 Birdfolio ist für {region} eingerichtet! Ihre Checkliste: Häufig (10): Amerikanisches Rotkehlchen, Haussperling, ... Selten (5): Kanadareiher, ... Super Selten: Kalifornischer Kondor Senden Sie mir ein Vogelfoto, um mit dem Sammeln zu beginnen!
2. Vogelidentifikationsablauf
Auslöser: Benutzer sendet ein Foto.
Dateipfad des Fotos abrufen: Wenn ein Benutzer ein Foto über Telegram sendet, lädt OpenClaw es herunter und stellt den lokalen Dateipfad in den Metadaten des Nachrichtenan hangs zur Verfügung. Erfassen Sie diesen Pfad – Sie werden ihn für die Kartengenerierung in Schritt 5 benötigen. Wenn OpenClaw das Bild inline ohne Pfad bereitstellt, verwenden Sie
exec, um die zuletzt heruntergeladene Datei im temporären/Medienordner von OpenClaw zu finden, oder überprüfen Sie%APPDATA%\openclaw\media\unter Windows. Speichern Sie das Foto zur dauerhaften Aufbewahrung inbirdfolio/birds/{slug}-{timestamp}.jpg:exec: copy "<Anhang-Pfad>" "birdfolio/birds/<slug>-<timestamp>.jpg"
Schritt 1 — Mit Vision identifizieren
Das eingereichte Foto ist direkt in Ihrem Kontext sichtbar. Analysieren Sie es (oder verwenden Sie das image-Werkzeug, falls es nicht inline ist):
Identifizieren Sie die Vogelart auf diesem Foto. Geben Sie nur JSON zurück:
{
"commonName": "...",
"scientificName": "...",
"confidence": "high|medium|low",
"features": ["sichtbares Merkmal 1", "sichtbares Merkmal 2"]
}
Seltenheitsregeln:
- Vogel IST auf der Checkliste → dessen Stufe verwenden:
common,rareodersuperRare - Vogel ist NICHT auf der Checkliste →
bonusverwenden (zeigt ein neutrales „Bonusfund"-Abzeichen, keine Seltenheit zugewiesen)
Vertrauensregeln:
"high"→ automatisch fortfahren, keine Bestätigung erforderlich"medium"→ fragen: „Ich denke, das könnte ein [Art] sein – basierend auf [Merkmale]. Sieht das für Sie richtig aus?" → auf Bestätigung warten, bevor fortgefahren wird"low"→ antworten: „Dieses Foto ist nicht klar genug, um sicher zu sein. Könnten Sie ein schärferes Foto senden?" → stoppen, nichts protokollieren
Schritt 2 — Seltenheitsabfrage
You.com durchsuchen:
"{commonName} {homeRegion} eBird Häufigkeit wie häufig selten"
Anhand dieser Signale klassifizieren:
| Stufe | Skriptwert | Signale |
|---|---|---|
| Häufig 🟢 | common | „häufig", „weit verbreitet", „ganzjährig ansässig", >50 % der Checklisten |
| Selten 🟡 | rare | „ungewöhnlich", „saisonal", „Zugvogel", „gelegentlich", 5–50 % der Checklisten |
| Super Selten 🔴 | superRare | „selten", „Irrgast", „versehentlich", „gefährdet", <5 % der Checklisten |
Bei Unsicherheit → standardmäßig rare verwenden. Verwenden Sie bei der Übergabe von --rarity an ein Skript immer den Skriptwert (z.B. superRare, nicht Super Rare).
Schritt 3 — Ein interessantes Fakt holen
You.com durchsuchen:
"{commonName} Vogel interessante Fakten Lebensraum Verhalten"
Ein prägnantes Fakt extrahieren (1–2 Sätze).
Schritt 4 — Die Sichtung protokollieren
Die Sichtung in birdfolio/lifeList.json in Ihrem Arbeitsbereich speichern:
exec: python {baseDir}/scripts/log_sighting.py \
--species "{commonName}" \
--scientific-name "{scientificName}" \
--rarity "{rarity}" \
--region "{homeRegion}" \
--notes "" \
--workspace <absoluter Pfad zu birdfolio/ in Ihrem Arbeitsbereich>
Aus der Ausgabe erfassen: isLifer, totalSightings, totalSpecies.
Schritt 5 — Checkliste aktualisieren
Die Art in birdfolio/checklist.json als gefunden markieren:
exec: python {baseDir}/scripts/update_checklist.py \
--species "{commonName}" \
--region "{homeRegion}" \
--workspace <absoluter Pfad zu birdfolio/ in Ihrem Arbeitsbereich>
Schritt 6 — Sammelkarte generieren
Die Karte hat ein zweispaltiges Design: Das Foto des Benutzers füllt das linke Panel (280px), ein dunkles Informationspanel befindet sich rechts. Verwenden Sie immer das tatsächliche eingereichte Foto des Benutzers – kein Archivbild.
Schritt 6a — Vogelposition mit Vision erkennen:
Das image-Werkzeug auf dem eingereichten Foto verwenden:
„Wo befindet sich der Vogel horizontal auf diesem Foto? Geben Sie mir ungefähr den Prozentsatz vom linken Rand, bei dem sich das Vogelzentrum befindet (0–100)."
Die Antwort in einen CSS-Wert umwandeln: "40% center", "60% center", "center center" usw. Diesen als --object-position verwenden.
Schritt 6b — Das Karten-HTML mit dem eingebetteten Foto generieren:
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 "<absoluter Pfad zum eingereichten Foto>" \
--object-position "{objectPosition}" \
--life-count {totalSpecies} \
--workspace <absoluter Pfad zu birdfolio/ in Ihrem Arbeitsbereich>
--image-path bettet das tatsächliche Foto des Benutzers als Base64 direkt in das HTML ein. Kein separater Einbettungsschritt erforderlich.
Fallback, wenn der Fotopfad nicht verfügbar ist: --image-path auslassen und stattdessen --image-url "<Archivbild-URL>" übergeben (über You.com finden: "{commonName} Vogelbild Wildtiere").
cardPath aus der Ausgabe erfassen.
Schritt 6c — Screenshot erstellen, speichern, hochladen und senden: Das Screenshot-Skript ausführen, um die Karte in 600×400 darzustellen und ein PNG zu speichern:
exec: node {baseDir}/scripts/screenshot_card.js "<cardPath>"
pngPath aus der Ausgabe erfassen.
In Cloudflare R2 hochladen und eine öffentliche URL erhalten:
exec: python {baseDir}/scripts/upload_card.py "<pngPath>"
url aus der Ausgabe erfassen.
Die Karten-URL der Sichtung in der API aktualisieren (die id aus der Ausgabe von log_sighting verwenden):
PATCH /users/{telegram_id}/sightings/{sighting_id}/card
Body: {"card_png_url": "<url>"}
Das PNG über Telegram senden:
message(action="send", media="<pngPath>")
Schritt 7 — Antworten
-
Wenn
isLiferwahr ist: „🎉 Neuer Lifer! Das ist Ihr erster [commonName] überhaupt! Vogel #[totalSpecies] in Ihrem Birdfolio."Wenn
totalSpecies == 1(dies ist der allererste Vogel des Benutzers): zusätzlich den persönlichen PWA-Link senden: „🦅 Ihr Birdfolio ist live! Setzen Sie ein Lesezeichen auf diesen Link, um Ihre Lebensliste zu sehen: https://birdfolio.tonbistudio.com/app/[telegram_id]"Die
telegram_idist die Telegram-ID des Absenders aus den Metadaten der eingehenden Nachricht (sender_id). Diese wird nach der Initialisierung auch inbirdfolio/config.jsongespeichert. -
Andernfalls: „[commonName] gesichtet! Sie haben jetzt [N] Arten in Ihrem Birdfolio gesehen."
Einschließen: Seltenheitsabzeichen-Emoji, das interessante Fakt, Checklisten-Status (wenn die Art auf der Checkliste war, erwähnen).
Fallback, wenn der Screenshot fehlschlägt: Eine formatierte Textkarte senden:
🦅 [RARITY_EMOJI] [Common Name]
Wissenschaftlich: [Scientific Name]
Region: [Region] | Gesichtet: [Date]
Seltenheit: [Rarity]
💡 [Fun Fact]
Vogel #[N] in Ihrem Birdfolio
3. Checkliste & Statistiken
Auslöser: „Wie ist meine Checkliste?", „Birdfolio-Fortschritt", „Wie viele Vögel habe ich gefunden?"
exec: python {baseDir}/scripts/get_stats.py \
--workspace <absoluter Pfad zu birdfolio/ in Ihrem Arbeitsbereich>
Antwort mit checklistProgress aus der Ausgabe formatieren:
📋 {region} Checkliste
Häufig ✅✅✅⬜⬜⬜⬜⬜⬜⬜ 3/10
Selten ✅⬜⬜⬜⬜ 1/5
Super Selten ⬜ 0/1
🐦 {totalSpecies} Arten | {totalSightings} Sichtungen gesamt
📍 Zuletzt gesichtet: {mostRecentSighting.commonName} am {date}
🏆 Seltenster Fund: {rarestBird.commonName} ({rarity})
✅ für gefunden, ⬜ für nicht gefunden verwenden. Ein Kästchen pro Art.
Optionale visuelle Checklistenkarte: Eine visuelle HTML-Checklistenkarte generieren und einen Screenshot erstellen:
exec: python {baseDir}/scripts/generate_checklist_card.py \
--workspace <absoluter Pfad zu birdfolio/ in Ihrem Arbeitsbereich>
Dann mit screenshot_card.js einen Screenshot erstellen und das PNG senden.
4. Lebenslistenansicht
Auslöser: „Zeig mir mein Birdfolio", „Zeig mir meine Lebensliste"
birdfolio/lifeList.json aus Ihrem Arbeitsbereich lesen.
Lifer nach Seltenheit gruppieren (zuerst Super Selten, dann Selten, dann Häufig). Als Textliste formatieren oder eine HTML-Galerie generieren, in Ihrem Arbeitsbereich unter birdfolio/my-birdfolio.html speichern und einen Screenshot erstellen.
5. Artnachschlage (keine Protokollierung)
Auslöser: „Erzähl mir von [Art]"
You.com durchsuchen:
"{species} Vogel Fakten Lebensraum Verbreitung Verhalten Ernährung"
"{species} Vogel {homeRegion} eBird Häufigkeit ansässig oder Zugvogel"
Eine konversationelle Zusammenfassung zurückgeben. Keine Sichtung protokollieren oder eine Karte generieren.
6. Seltenster Vogel
Auslöser: „Was ist mein seltenster Vogel?", „Zeig meinen besten Fund"
exec: python {baseDir}/scripts/get_stats.py \
--workspace <absoluter Pfad zu birdfolio/ in Ihrem Arbeitsbereich>
rarestBird aus der Ausgabe lesen und mit Artname, Seltenheit, Sichtungsdatum und Region antworten.
Kurzreferenz
| Skript | Wichtige Argumente | Rückgabe |
|---|---|---|
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} oder {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 (bevorzugt) ODER --image-url, --object-position, --life-count, --workspace | {status, cardPath, filename} |
generate_checklist_card.py | --workspace | {status, cardPath} – visuelle HTML-Checklistenkarte |
screenshot_card.js | <cardPath> [outputPath] | {status, pngPath} – speichert PNG in birdfolio/cards/ |
upload_card.py | <pngPath> [--secrets path] | {status, url} – lädt nach R2 hoch, gibt öffentliche URL zurück |
Alle Python-Skripte geben JSON an stdout aus. Immer den absoluten --workspace-Pfad übergeben.
screenshot_card.js verwendet das gebündelte playwright-core von OpenClaw + systemeigenes Chrome/Edge (keine separate Installation erforderlich).