Birdfolio
Birdfolio 將鳥類照片轉化為個人生命清單。使用者在野外拍攝鳥類照片,將照片傳送給你,你透過 Vision 辨識物種。You.com 提供即時稀有度與區域資料。每次目擊記錄都會被記錄到生命清單中,並帶有寶可夢風格的稀有度分級(常見 / 稀有 / 超稀有),最後透過 Telegram 回傳一張視覺化交易卡。
資料存放於: Railway PostgreSQL(透過 API)+ 本機 birdfolio/ 資料夾(卡片、鳥類、設定)
腳本存放於: {baseDir}/scripts/
API: https://api-production-d0e2.up.railway.app(初始化後也會儲存到 birdfolio/config.json)
結構參考: {baseDir}/references/data-schema.md
搜尋查詢: {baseDir}/references/you-search-queries.md
關於 --workspace 與 --api-url 的注意事項: 每個資料腳本都接受
--workspace(birdfolio/的絕對路徑)與--api-url(API 基礎 URL)。執行init_birdfolio.py後,API URL 與 Telegram ID 都會儲存到birdfolio/config.json中,後續腳本只需提供--workspace即可自動讀取。Telegram ID: 從傳入訊息的 metadata(
sender_id)中讀取。首次設定時,將其作為--telegram-id傳遞給init_birdfolio.py。
1. 設定流程
觸發條件: 使用者說「設定我的 Birdfolio」、「設定我的區域」,或在設定尚未完成時傳送照片。
事先檢查: 如果你的工作空間中已存在 birdfolio/config.json,表示設定已完成,請直接跳到對應的流程。
步驟:
-
詢問:「你的家鄉在哪裡?(例如:California, Texas, United Kingdom)」
-
執行以下指令來建立工作空間資料夾結構,並在 API 中註冊使用者:
exec: python {baseDir}/scripts/init_birdfolio.py \ --telegram-id {senderTelegramId} \ --region "{region}" \ --api-url "https://api-production-d0e2.up.railway.app" \ --workspace <你的工作空間中 birdfolio/ 的絕對路徑> -
搜尋 You.com(三個都執行):
"{region} most common backyard birds eBird species list" "{region} uncommon seasonal rare birds eBird checklist" "{region} rare vagrant endangered birds eBird" -
從結果中建立一份包含 10 種常見、5 種稀有、1 種超稀有 鳥類的清單。使用
{baseDir}/references/you-search-queries.md中的分類信號。 -
將填好的清單寫入你工作空間中的
birdfolio/checklist.json:{ "{region}": { "common": [ { "species": "American Robin", "slug": "american-robin", "found": false, "dateFound": null } ], "rare": [...], "superRare": [...] } } -
回覆一則歡迎訊息與清單預覽:
🦅 Birdfolio 已為 {region} 設定完成! 你的清單: 常見 (10): American Robin, House Sparrow, ... 稀有 (5): Great Blue Heron, ... 超稀有: California Condor 傳送一張鳥類照片給我,開始收集吧!
2. 鳥類辨識流程
觸發條件: 使用者傳送一張照片。
取得照片檔案路徑: 當使用者透過 Telegram 傳送照片時,OpenClaw 會下載該照片,並將本機檔案路徑提供於訊息附件 metadata 中。請擷取此路徑——你將在步驟 5 的卡片生成中用到。如果 OpenClaw 直接提供內嵌圖片而沒有路徑,請使用
exec在 OpenClaw 的暫存/媒體資料夾中尋找最近下載的檔案,或在 Windows 上檢查%APPDATA%\openclaw\media\。將照片儲存到birdfolio/birds/{slug}-{timestamp}.jpg以永久保存:
exec: copy "<附件路徑>" "birdfolio/birds/<slug>-<timestamp>.jpg"
第 1 步 — 使用 Vision 辨識
提交的照片直接在你的上下文(context)中可見。請分析它(如果照片不是內嵌的,可以使用 image 工具):
辨識這張照片中的鳥類物種。僅回傳 JSON:
{
"commonName": "...",
"scientificName": "...",
"confidence": "high|medium|low",
"features": ["可見特徵 1", "可見特徵 2"]
}
稀有度規則:
- 鳥類已在清單上 → 使用其層級:
common、rare或superRare - 鳥類不在清單上 → 使用
bonus(顯示中立的「Bonus Find」徽章,不指定稀有度)
信心度規則:
"high"→ 自動進行,無需確認"medium"→ 詢問:「我認為這可能是 [物種] —— 根據 [特徵]。你看起來對嗎?」 → 等待使用者確認後再繼續"low"→ 回覆:「這張照片不夠清晰,我無法確定。你能傳送一張更清楚的照片嗎?」 → 停止,不記錄任何資料
第 2 步 — 稀有度查詢
搜尋 You.com:
"{commonName} {homeRegion} eBird frequency how common rare"
使用以下信號進行分類:
| 層級 | 腳本值 | 信號 |
|---|---|---|
| 常見 🟢 | common | "abundant", "widespread", "year-round resident", 清單 >50% |
| 稀有 🟡 | rare | "uncommon", "seasonal", "migratory", "occasional", 清單 5–50% |
| 超稀有 🔴 | superRare | "rare", "vagrant", "accidental", "endangered", 清單 <5% |
若不確定 → 預設為 rare。傳遞 --rarity 給任何腳本時,一律使用腳本值(例如 superRare,而非 Super Rare)。
第 3 步 — 取得有趣事實
搜尋 You.com:
"{commonName} bird interesting facts habitat behavior"
提取一則精簡的事實(1–2 句)。
第 4 步 — 記錄目擊事件
將目擊記錄儲存到工作空間中的 birdfolio/lifeList.json:
exec: python {baseDir}/scripts/log_sighting.py \
--species "{commonName}" \
--scientific-name "{scientificName}" \
--rarity "{rarity}" \
--region "{homeRegion}" \
--notes "" \
--workspace <你的工作空間中 birdfolio/ 的絕對路徑>
從輸出中擷取:isLifer、totalSightings、totalSpecies。
第 5 步 — 更新清單
在 birdfolio/checklist.json 中將該物種標記為已找到:
exec: python {baseDir}/scripts/update_checklist.py \
--species "{commonName}" \
--region "{homeRegion}" \
--workspace <你的工作空間中 birdfolio/ 的絕對路徑>
第 6 步 — 生成交易卡
卡片為雙欄設計:使用者照片填滿左側面板(280px),右側為純色深色資訊面板。一律使用使用者實際提交的照片——而非庫存圖片。
第 6a 步 — 使用 Vision 偵測鳥類位置:
對提交的照片使用 image 工具:
"這張照片中的鳥類水平位置在哪裡?請提供鳥類中心距離左邊緣的近似百分比(0–100)。"
將答案轉換為 CSS 值:"40% center"、"60% center"、"center center" 等。以此作為 --object-position。
第 6b 步 — 生成內嵌照片的卡片 HTML:
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 "<提交照片的絕對路徑>" \
--object-position "{objectPosition}" \
--life-count {totalSpecies} \
--workspace <你的工作空間中 birdfolio/ 的絕對路徑>
--image-path 會將使用者的實際照片以 base64 格式直接嵌入 HTML 中。不需要額外的嵌入步驟。
照片路徑不可用時的備案: 省略 --image-path,改為傳遞 --image-url "<庫存照片 URL>"(透過 You.com 尋找 URL:"{commonName} bird photo wildlife")。
從輸出中擷取 cardPath。
第 6c 步 — 截圖、儲存、上傳並傳送: 執行截圖腳本,將卡片渲染為 600×400 並儲存為 PNG:
exec: node {baseDir}/scripts/screenshot_card.js "<cardPath>"
從輸出中擷取 pngPath。
上傳到 Cloudflare R2 並取得公開 URL:
exec: python {baseDir}/scripts/upload_card.py "<pngPath>"
從輸出中擷取 url。
更新 API 中該筆目擊記錄的卡片 URL(使用 log_sighting 輸出中的 id):
PATCH /users/{telegram_id}/sightings/{sighting_id}/card
Body: {"card_png_url": "<url>"}
透過 Telegram 傳送 PNG:
message(action="send", media="<pngPath>")
第 7 步 — 回覆
-
如果
isLifer為 true: "🎉 新物種!這是你第一次看到 [commonName]!你的 Birdfolio 中第 #[totalSpecies] 種鳥類。"如果
totalSpecies == 1(這是他們的第一隻鳥): 同時傳送他們的個人 PWA 連結: "🦅 你的 Birdfolio 已上線!將此連結加入書籤以查看你的生命清單: https://birdfolio.tonbistudio.com/app/[telegram_id]"telegram_id是來自傳入訊息 metadata(sender_id)的傳送者 Telegram ID。初始化後也會儲存在birdfolio/config.json中。 -
否則: "[commonName] 現蹤!你已在 Birdfolio 中看到 [N] 種鳥類。"
包含:稀有度徽章 emoji、有趣事實、清單狀態(如果物種在清單上,請提及)。
如果截圖失敗時的備案: 傳送格式化文字卡片:
🦅 [稀有度_EMOJI] [常見名稱]
學名: [學名]
區域: [區域] | 發現日期: [日期]
稀有度: [稀有度]
💡 [有趣事實]
你的 Birdfolio 中第 #[N] 種鳥類
3. 清單與統計
觸發條件:「我的清單如何?」、「Birdfolio 進度」、「我發現了幾種鳥?」
exec: python {baseDir}/scripts/get_stats.py \
--workspace <你的工作空間中 birdfolio/ 的絕對路徑>
使用輸出中的 checklistProgress 來格式化回應:
📋 {region} 清單
常見 ✅✅✅⬜⬜⬜⬜⬜⬜⬜ 3/10
稀有 ✅⬜⬜⬜⬜ 1/5
超稀有 ⬜ 0/1
🐦 {totalSpecies} 種 | {totalSightings} 次目擊
📍 最近發現:{mostRecentSighting.commonName} 於 {date}
🏆 最稀有發現:{rarestBird.commonName}({rarity})
使用 ✅ 表示已找到,⬜ 表示未找到。每種鳥類一個方塊。
可選的視覺化清單卡片: 生成一張視覺化 HTML 清單卡片並截圖:
exec: python {baseDir}/scripts/generate_checklist_card.py \
--workspace <你的工作空間中 birdfolio/ 的絕對路徑>
然後用 screenshot_card.js 截圖並傳送 PNG。
4. 生命清單檢視
觸發條件:「顯示我的 Birdfolio」、「顯示我的生命清單」
從工作空間中讀取 birdfolio/lifeList.json。
按照稀有度分組生命清單(超稀有優先,然後稀有,最後常見)。格式化成文字列表或生成 HTML 畫廊,儲存到工作空間中的 birdfolio/my-birdfolio.html,然後截圖。
5. 物種查詢(不記錄)
觸發條件:「告訴我關於 [物種]」
搜尋 You.com:
"{species} bird facts habitat range behavior diet"
"{species} bird {homeRegion} eBird frequency resident or migratory"
回覆一段對話式摘要。不要記錄目擊事件或生成卡片。
6. 最稀有鳥類
觸發條件:「我最稀有的鳥是什麼?」、「顯示我最棒的發現」
exec: python {baseDir}/scripts/get_stats.py \
--workspace <你的工作空間中 birdfolio/ 的絕對路徑>
從輸出中讀取 rarestBird,並回覆物種名稱、稀有度、發現日期與區域。
快速參考
| 腳本 | 主要參數 | 回傳值 |
|---|---|---|
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} 或 {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(首選)或 --image-url, --object-position, --life-count, --workspace | {status, cardPath, filename} |
generate_checklist_card.py | --workspace | {status, cardPath} — 視覺化 HTML 清單卡片 |
screenshot_card.js | <cardPath> [outputPath] | {status, pngPath} — 將 PNG 儲存到 birdfolio/cards/ |
upload_card.py | <pngPath> [--secrets path] | {status, url} — 上傳到 R2,回傳公開 URL |
所有 Python 腳本都會輸出 JSON 到 stdout。請務必傳遞絕對的 --workspace 路徑。
screenshot_card.js 使用 OpenClaw 隨附的 playwright-core 加上系統的 Chrome/Edge(無需額外安裝)。