Birdfolio
Birdfolioは、鳥の写真を個人のライフリストに変えるスキルです。ユーザーが野生の鳥を撮影し、その写真を送信すると、Visionで種を識別します。You.comからリアルタイムの希少性データと地域情報を取得。各目撃情報はポケモン風のレアリティ階層(Common / Rare / Super Rare)とともにライフリストに記録され、ビジュアルトレーディングカードが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) から読み取ります。初回セットアップ時にinit_birdfolio.pyに--telegram-idとして渡します。
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 を検索 (3つすべて実行):
"{region} most common backyard birds eBird species list" "{region} uncommon seasonal rare birds eBird checklist" "{region} rare vagrant endangered birds eBird" -
結果から、10種のCommon、5種のRare、1種のSuper Rare でチェックリストを構築します。分類シグナルは
{baseDir}/references/you-search-queries.mdを参照。 -
作成したチェックリストをワークスペース内の
birdfolio/checklist.jsonに書き込み:{ "{region}": { "common": [ { "species": "アメリカコマドリ", "slug": "american-robin", "found": false, "dateFound": null } ], "rare": [...], "superRare": [...] } } -
ウェルカムメッセージとチェックリストプレビューを返信:
🦅 Birdfolio が {region} でセットアップされました! あなたのチェックリスト: Common (10): アメリカコマドリ、イエスズメ、... Rare (5): オオアオサギ、... Super Rare: カリフォルニアコンドル 鳥の写真を送って収集を始めましょう!
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を使用 (中立な「Bonus Find」バッジを表示、レアリティなし)
信頼度ルール:
"high"→ 自動的に進む、確認は不要"medium"→ 質問: 「これは [種名] かもしれません — [特徴] に基づいています。そのように見えますか?」 → 続行する前に確認を待つ"low"→ 返信: 「この写真ははっきりしなくて確信が持てません。もっと鮮明な写真を送っていただけますか?」 → 停止、何も記録しない
ステップ2 — レアリティ検索
You.com を検索:
"{commonName} {homeRegion} eBird frequency how common rare"
以下のシグナルで分類:
| 階層 | スクリプト値 | シグナル |
|---|---|---|
| Common 🟢 | common | "abundant (豊富)", "widespread (広範囲)", "year-round resident (年中生息)", チェックリストの50%以上 |
| Rare 🟡 | rare | "uncommon (珍しい)", "seasonal (季節的)", "migratory (渡り鳥)", "occasional (時々)", チェックリストの5~50% |
| Super Rare 🔴 | 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 — トレーディングカードを生成
カードは2カラムデザイン: 左パネル(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は受信メッセージメタデータからの送信者のTelegram IDです (sender_id)。初期化後、birdfolio/config.jsonにも保存されています。 -
それ以外の場合: 「[commonName] を発見!Birdfolio で現在 [N] 種を見ました。」
含めるもの: レアリティバッジの絵文字、豆知識、チェックリストステータス(種がチェックリストに載っていた場合はその旨を記載)。
スクリーンショットに失敗した場合のフォールバック: フォーマットされたテキストカードを送信:
🦅 [RARITY_EMOJI] [Common Name]
学名: [Scientific Name]
地域: [Region] | 発見日: [Date]
レアリティ: [Rarity]
💡 [Fun Fact]
Birdfolio で #[N] 番目の鳥
3. チェックリストと統計
トリガー: 「チェックリストはどう?」、「Birdfolio の進行状況」、「何羽見つけた?」
exec: python {baseDir}/scripts/get_stats.py \
--workspace <birdfolio/ への絶対パス>
出力の checklistProgress を使用して応答をフォーマット:
📋 {region} チェックリスト
Common ✅✅✅⬜⬜⬜⬜⬜⬜⬜ 3/10
Rare ✅⬜⬜⬜⬜ 1/5
Super Rare ⬜ 0/1
🐦 {totalSpecies} 種 | {totalSightings} 総目撃数
📍 最後に発見: {mostRecentSighting.commonName} ({date})
🏆 最もレアな発見: {rarestBird.commonName} ({rarity})
✅ は発見済み、⬜ は未発見に使用。種ごとに1つのボックス。
オプションのビジュアルチェックリストカード: ビジュアルHTMLチェックリストカードを生成しスクリーンショット:
exec: python {baseDir}/scripts/generate_checklist_card.py \
--workspace <birdfolio/ への絶対パス>
その後、screenshot_card.js でスクリーンショットを撮り、PNGを送信。
4. ライフリスト表示
トリガー: 「Birdfolio を見せて」、「ライフリストを見せて」
ワークスペース内の birdfolio/lifeList.json を読み取ります。
ライファーをレアリティ順にグループ化(Super Rare が最初、次に Rare、Common)。テキストリストとしてフォーマットするか、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を使用します(別途インストールは不要)。