Birdfolio
Birdfolio 将鸟类照片转化为个人生命清单。用户在野外拍摄鸟类照片,发送给技能,技能通过 Vision 识别物种。You.com 提供实时稀有度和区域数据。每次观察记录都记录到带有 Pokémon 风格稀有度等级(常见 / 稀有 / 超级稀有)的生命清单中,并通过 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: 从传入消息元数据(
sender_id)中读取。首次设置时作为--telegram-id传递给init_birdfolio.py。
1. 设置流程
触发条件: 用户说“设置我的 Birdfolio”、“设置我的区域”,或在设置完成前发送照片。
首先检查: 如果工作区中存在 birdfolio/config.json,则设置已完成——跳转到相关流程。
步骤:
-
询问:“您的家乡区域是哪里?(例如:加利福尼亚、得克萨斯、英国)”
-
运行以下命令创建工作区文件夹结构并在 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 会下载它并将本地文件路径提供给消息附件元数据。捕获此路径——你将在第 5 步中生成卡片时用到它。如果 OpenClaw 内联提供图像而没有路径,请使用
exec在 OpenClaw 的临时/媒体文件夹中找到最近下载的文件,或在 Windows 上检查%APPDATA%\openclaw\media\。将照片保存到birdfolio/birds/{slug}-{timestamp}.jpg以永久存储:
exec: copy "<附件路径>" "birdfolio/birds/<slug>-<timestamp>.jpg"
第 1 步——使用 Vision 识别
提交的照片在您的上下文中直接可见。分析它(如果照片没有内联显示,则使用 image 工具):
识别这张照片中的鸟类物种。仅返回 JSON:
{
"commonName": "...",
"scientificName": "...",
"confidence": "high|medium|low",
"features": ["可见特征 1", "可见特征 2"]
}
稀有度规则:
- 鸟类在清单上 → 使用其等级:
common、rare或superRare - 鸟类不在清单上 → 使用
bonus(显示中性“额外发现”徽章,不分配稀有度)
置信度规则:
"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为真: "🎉 新记录!这是您的第一个 [commonName]!Birdfolio 中的第 #[totalSpecies] 种鸟。"如果
totalSpecies == 1(这是他们的第一只鸟): 同时还发送他们的个人 PWA 链接: "🦅 您的 Birdfolio 已上线!将此链接加入书签以查看您的生命清单: https://birdfolio.tonbistudio.com/app/[telegram_id]"telegram_id是来自传入消息元数据(sender_id)的发送者 Telegram ID。初始化后,它也存储在birdfolio/config.json中。 -
否则: "[commonName] 已发现!您现在已经看到了 Birdfolio 中的 [N] 种鸟类。"
包含:稀有度徽章表情符号、趣闻、清单状态(如果物种在清单上,请提及)。
截图失败时的备选方案: 发送格式化的文本卡片:
🦅 [稀有度表情] [通用名]
学名:[学名]
区域:[区域] | 发现日期:[日期]
稀有度:[稀有度]
💡 [趣闻]
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 到标准输出。始终传递绝对 --workspace 路径。
screenshot_card.js 使用 OpenClaw 捆绑的 playwright-core + 系统 Chrome/Edge(无需单独安装)。