核心用法
Birdfolio是一套完整的观鸟数字化工作流，用户通过Telegram发送鸟类照片，系统自动完成识别、记录、卡片生成与社交分享。核心功能包括：
1. 智能识别与分级
- 使用Vision API分析用户拍摄的鸟类照片，返回物种学名、可信度评级及可见特征
- 基于You.com实时搜索的区域eBird数据，将鸟类划分为Common（常见）、Rare（稀有）、Super Rare（极稀有）三档
- 非清单物种标记为Bonus Find，保持记录灵活性
2. 生命清单管理
- 首次使用时通过
init_birdfolio.py建立用户档案，绑定Telegram ID与所在区域 - 自动生成16物种的区域专属清单（10常见+5稀有+1极稀有）
- 每次有效识别通过
log_sighting.py写入PostgreSQL数据库，同步更新本地lifeList.json
3. 视觉交易卡系统
- 采用宝可梦风格的稀有度徽章设计
- 用户原片嵌入左侧280px画板，右侧信息面板显示物种数据、发现日期、趣味知识
- 通过Playwright渲染600×400卡片，上传Cloudflare R2后通过Telegram返回
4. 进度追踪与社交
- 实时统计：物种总数、观测次数、清单完成度、最近发现、最稀有记录
- 提供个人PWA链接（
birdfolio.tonbistudio.com/app/{telegram_id}）用于长期回顾
显著优点
- 零摩擦记录：对话式交互消除传统观鸟App的表单填写负担
- 视觉激励机制：游戏化的稀有度系统和实体感卡片设计增强用户粘性
- 数据双保险：云端PostgreSQL + 本地JSON的双重存储架构
- 区域自适应：基于eBird数据的动态清单生成，适配全球任意地区
潜在局限
- 识别准确性依赖：Vision对幼鸟、亚成体、逆光/遮挡照片的识别可信度可能降至"low"，需人工复核
- 网络依赖重：You.com搜索、eBird数据查询、R2上传均需稳定网络
- 单用户架构：当前设计未明确支持多用户数据隔离，Telegram ID作为唯一标识存在隐私考量
- 存储成本：每张卡片生成PNG并上传对象存储，高频使用下产生持续费用
适合人群
- 轻度至中度观鸟爱好者，希望快速建立数字生命清单
- 家长引导儿童接触自然，游戏化卡片具有教育吸引力
- 区域鸟类清单挑战者（如"一年内集齐加州清单"目标）
常规风险
- 数据持久性：Railway免费套餐有休眠限制，API可用性依赖第三方
- 隐私泄露：Telegram ID与地理位置绑定，卡片图片含EXIF地理信息需脱敏
- 版权争议：用户使用网络图片触发识别时，生成的交易卡可能涉及图片来源问题
- 幻觉输出：Vision在近似物种间（如各类莺科）可能产生高置信度错误识别