Birdfolio
Birdfolio는 새 사진을 개인 생애 목록으로 바꿔줍니다. 사용자가 야생에서 새를 촬영하여 사진을 보내면, AI가 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 검색 (세 가지 모두 실행):
"{region} 가장 흔한 정원 새 eBird 종 목록" "{region} 흔하지 않은 계절별 희귀 새 eBird 체크리스트" "{region} 희귀 방랑성 멸종 위기 새 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": [...] } } -
환영 메시지와 체크리스트 미리보기로 응답합니다:
🦅 {region}에 대한 Birdfolio가 설정되었습니다! 체크리스트: 일반 (10종): American Robin, House Sparrow, ... 희귀 (5종): Great Blue Heron, ... 초희귀 (1종): California Condor 새 사진을 보내주시면 수집을 시작합니다!
2. 새 식별 흐름
트리거: 사용자가 사진을 보냅니다.
사진 파일 경로 얻기: 사용자가 Telegram을 통해 사진을 보내면, OpenClaw가 다운로드하여 메시지 첨부 파일 메타데이터에 로컬 파일 경로를 제공합니다. 이 경로를 캡처하여 5단계에서 카드 생성에 사용합니다. OpenClaw가 이미지를 인라인으로 제공하고 경로가 없는 경우,
exec를 사용하여 OpenClaw의 임시/미디어 폴더에서 가장 최근에 다운로드된 파일을 찾거나 Windows의 경우%APPDATA%\openclaw\media\를 확인하세요. 사진을birdfolio/birds/{slug}-{timestamp}.jpg에 영구 저장합니다:exec: copy "<attachment path>" "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 빈도 얼마나 흔한 희귀한"
다음 신호를 사용하여 분류:
| 등급 | 스크립트 값 | 신호 |
|---|---|---|
| 일반 🟢 | common | "풍부함", "광범위함", "연중 서식", 체크리스트의 >50% |
| 희귀 🟡 | rare | "흔하지 않음", "계절별", "철새", "가끔", 체크리스트의 5–50% |
| 초희귀 🔴 | superRare | "희귀함", "방랑성", "우연한", "멸종 위기", 체크리스트의 <5% |
확실하지 않을 때 → 기본값 rare 사용. 모든 스크립트에 --rarity를 전달할 때 항상 스크립트 값(예: superRare, Super Rare 아님)을 사용합니다.
3단계 — 재미있는 사실 얻기
You.com 검색:
"{commonName} 새 흥미로운 사실 서식지 행동"
간결한 사실 하나를 추출합니다 (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가 참인 경우: "🎉 새로운 첫 기록! 당신의 첫 번째 [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]종을 보셨습니다."
포함: 희귀도 배지 이모지, 재미있는 사실, 체크리스트 상태 (종이 체크리스트에 있었으면 언급).
스크린샷 실패 시 대체: 형식화된 텍스트 카드 전송:
🦅 [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} 체크리스트
일반 ✅✅✅⬜⬜⬜⬜⬜⬜⬜ 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} 새 사실 서식지 범위 행동 식단"
"{species} 새 {homeRegion} eBird 빈도 텃새 또는 철새"
대화형 요약을 반환합니다. 관찰을 기록하거나 카드를 생성하지 않습니다.
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 스크립트는 stdout에 JSON을 출력합니다. 항상 절대 --workspace 경로를 전달하세요.
screenshot_card.js는 OpenClaw에 번들된 playwright-core + 시스템 Chrome/Edge를 사용합니다 (별도 설치 불필요).