chatterbox-avatar-forge

name	chatterbox-avatar-forge
description	ChatterBox 의상실에서 "PNG 1장 업로드 → 자동 리깅 → 인앱 Live2D 아바타 수령"을 세우는 배선·배포 런북(CHATTERBOX-RIG-PORT-001 P3). Vtube Modal 파이프라인을 ChatterBox Supabase(avatar_jobs·Storage·Realtime)에 잇는다 — vgen 잡 클론 + FAL→Modal 스왑. 트리거 — "채터박스 아바타 배선", "PNG to live2d 웹연동", "의상실 아바타 생성", "avatar forge", "Modal 웹엔드포인트 배포", "avatar_jobs". 2026-07-09 미미 서버본으로 수령/렌더 반쪽 실증.

Avatar Forge 배선·배포 (CHATTERBOX-RIG-PORT-001 P3)

ChatterBox /atelier-forge(dev) → 자동 리깅 → 의상실 프리셋. 두 레포: Vtube(Modal 엔드포인트·발행) + ChatterBox(마이그·엣지·클라). 잡 뼈대는 ChatterBox VGEN(FAL 영상) 클론.

상태 (2026-07-09)

• ✅ 수령/렌더 반쪽 증명 — 서버 리그→bake_storage_avatar.py→avatars/<id>/ 발행→네이티브 RigAvatar 로드·웹캠 구동(미미 서버본, avatars/mimi-smoke/, 의상실 프리셋 "미미(서버본)").
• ✅ 배선 코드 완료·검증 — 아래 파일들, type-check·lint·py_compile 통과.
• ✅ 자동 트리거 배포 완료(2026-07-09) — Modal chatterbox-rig deploy(submit) + vtube-supabase 시크릿 + 마이그 push + supabase secrets + 엣지 create-avatar-job + CF 프론트. 스모크: 엣지 무인증 401·Modal 무시크릿 401. ChatterBox 의상실 커미션 UI 승격(features/avatar/CommissionCorner+useAvatarJobs, seed-and-drive E2E 17/17 — 시드 잡·Realtime 드라이브로 배포 없이도 UI 검증 가능).
• ✅ 첫 $2 실런 완료(2026-07-11) — GPU 전 구간(analyzing→rigging) 성공, 발행만 볼륨 스테일로 실패(아래 함정) → jobs.reload()+발행 3회 재시도 반영·재배포, 리그는 구조 절차로 재결제 없이 발행(잡 306592e7 done). scan_rig_health에 입 위치 새니티 게이트(눈→턱 0.45~0.75) 추가.
• 📌 미학 게이트 불가 실측(2026-07-11) — "입이 높다"류 정적 위치 취향 드리프트는 기하 2지표(비례 0.604 vs 정상 0.5870.601·닫힘↔열림 점프)와 VLM 심판(gpt-5-mini 절대/원본충실도, 45점) 전부 정상 판정 → 자동 게이트로 못 잡는다. 담당은 사용자 수령 루프(미리보기·보정/재주문) — 가짜 안심 게이트 금지. 단 후속 반전: "입이 딴 데서 열림" 체감의 진범은 미학이 아니라 형제 키폼 소실(구조 결함, 아래 함정)로 판명 — 그쪽은 게이트+자동수복 배선됨. 취향 불가 판정은 정적 위치에 한정.
• ⏳ 남용 게이트(크레딧/레이트리밋)는 공개 전 필수(ChatterBox ROADMAP 등재).

신규/변경 파일 (SSOT)

레이어	파일	역할
Vtube 발행	scripts/bake_storage_avatar.py	리그→project.json+parts/*.webp. _project_base_url=""(로더 파생용, 함정)
Vtube 엔드포인트	scripts/modal_rig_app.py submit/run_pipeline/_publish_avatar/_supabase_patch	웹 트리거 + 오케스트레이터(phase PATCH) + Storage 발행. web_image=경량 fastapi
CB DB	supabase/migrations/*_create_avatar_jobs.sql	잡 테이블(vgen 복제 축소) + RLS + Realtime
CB Storage	supabase/migrations/*_avatar_uploads_bucket.sql	avatar-uploads(private) + 본인폴더 RLS. 발행처 avatars(public)는 기존
CB 엣지	supabase/functions/create-avatar-job/index.ts	trigger-vgen 복제, FAL POST→Modal 엔드포인트
CB 클라	src/lib/avatarJobs.ts·src/types/avatarJob.ts·src/pages/AvatarForgeDevPage.tsx	업로드·트리거·Realtime + 버림 dev UI(/atelier-forge)

배포 런북 (자동 트리거 세우기)

# ── Vtube (Modal) ──
cd /Users/family/jason/Vtube
# 시크릿: ChatterBox .env 의 값 사용(값 유출 주의)
~/.venvs/modal/bin/modal secret create vtube-supabase \
  SUPABASE_URL="<VITE_SUPABASE_URL>" \
  SUPABASE_SERVICE_ROLE_KEY="<SUPABASE_SERVICE_ROLE_KEY>" \
  AVATAR_TRIGGER_SECRET="<임의 강한 시크릿>"
~/.venvs/modal/bin/modal deploy scripts/modal_rig_app.py   # → submit 웹엔드포인트 URL 출력

# ── ChatterBox (Supabase) ──
cd /Users/family/jason/ChatterBox
supabase link --project-ref <ref>            # VITE_SUPABASE_URL 의 <ref>. config.toml project_id 는 라벨일 뿐
supabase db push                             # avatar_jobs + avatar-uploads 버킷/RLS
supabase secrets set MODAL_ENDPOINT_URL="<submit URL>" MODAL_TRIGGER_SECRET="<위와 동일>"
supabase functions deploy create-avatar-job

무디버깅 계약 함정 (전부 실제로 확인)

함정	증상	해법
발행처 오리진	아바타 로드 시 origin 거부/404	Supabase Storage avatars(공개) 만 — R2·타 CDN은 로더 화이트리스트(*.supabase.co) 밖
_project_base_url	parts webp 404(페이지 오리진에 붙음)	발행 시 빈 문자열. 로더 `base
업로드 키 오리진	Storage RLS vs 엣지 검증 불일치	키 = <authUid>/uploads/<uuid>.png (auth.uid()). 엣지 isSafeObjectKey(key, authId, ["uploads"]) — users.id 아님
Modal 인풋 취소	로컬 런처 kill이 원격 취소	웹엔드포인트는 .spawn()(비동기)이라 무관. CLI 경로는 [[autorig-upload-e2e]] nohup+disown
프리셋 이름 충돌	구본 mimi와 신본 동명	매니페스트 name 구분(예: "미미(서버본)"). 최종 승격 시 avatars/mimi/ 덮어써 캐논화
볼륨 스테일 발행 실패	finishing에서 character.json 없음(볼륨엔 실존) — 오케스트레이터 컨테이너가 spawn 시점 뷰라 build_rig 커밋이 안 보임	_publish_avatar 선두 jobs.reload()(2026-07-11 반영) + 발행 3회 재시도. 스테이지 함수의 reload 패턴을 볼륨 읽는 모든 지점에
발행 실패 = $2 증발 아님	status=failed지만 jobs/<exp>/rig 완성본 생존	구조: modal volume get(⚠️ 목적지 동명 폴더 있으면 Errno 21) → bake_storage_avatar.py → ChatterBox scripts/publish-avatar-job.mjs <jobId> <pubDir>(검증+업로드+done PATCH)
에러 원문 사용자 노출	30분 기다린 유저가 파이썬 트레이스백을 봄	원문은 avatar_jobs.error(진단용)에만 — CB UI는 일반 안내(atelier.commissionFailedHint, 2026-07-11)
형제 키폼 소실(닫힌 입만 얼굴서 분리)	라이브 머리회전 시 닫힌 입만 제자리에 붙박여 위로 떠 보이고 열면 그 아래서 열림 — 정면 정지 렌더·bbox·잉크선 분석 전부 정상인 은닉 결함(306592e7: mouth_closed_master AngleY@-30만 0, 형제는 ~95px)	원인=증류가 얇은 파트의 특정 각도 키를 delta 0으로 남김(flow 신뢰 0/피팅 실패). distill_tha3_rotation.repair_sibling_dropout()이 형제 affine 피팅으로 자동수복(잔차≈0) + scan_rig_health "형제 키폼 소실" FAIL 게이트. 기발행 리그는 같은 피팅으로 로컬 패치→재발행
재발행이 유저에게 안 닿음	수정 재발행 후에도 유저는 구본 — ①같은 generated_at 재발행이면 CDN/파츠캐시가 "안 바뀜" 취급 ②project.json 은 max-age=3600 브라우저 캐시(하드 리프레시도 앱의 로드후 fetch 엔 무효) ③캐시버스트 쿼리 검증은 원본만 봐서 "발행됨" 오판	generated_at 반드시 범프 + publish-avatar-job.mjs/deploy-avatar.mjs의 내용 rev 대조·맨 URL 전파 확인 사용. CB 로더는 project.json cache:'no-cache' 재검증(2026-07-11 수정, 프론트 배포 필요)
웜 컨테이너 볼륨 스테일(일반형)	스테이지 함수가 시작부 jobs.reload() 없이 /vol 읽으면 웜 재사용 시 이전 잡 시점 뷰 — "입력 없음"류 즉사	/vol 읽는 모든 함수 시작부에 reload — 2026-07-11 감사에서 seethrough_decompose 누락분 보수. 신규 스테이지 추가 시 체크리스트

티어 정책

run_pipeline = 프로덕션 안전 티어 build_rig(..., use_tha4=False, use_crown=False) = ARAP meet 감은눈(이물 원천 불가). THA4/crown 옵트인 근거·함정은 [[autorig-upload-e2e]]. 리깅 자체(P0 리롤·P2 게이트·표현력)는 그 스킬이 SSOT — 여기선 웹 배선만.

검증 (성역)

• Step 0(자동 이전, GPU 0원): 서버 리그 회수→bake_storage_avatar.py --project <rig> --out <o>→avatars/<id>/ 업로드(service_role)→ChatterBox /avatar-inspect?project=<url> 네이티브 패널 렌더 확인(aria-player 우측 패널은 레거시라 빈 base 실패 — 무시). 프리셋 확인은 avatars/manifest.json 에 {id,name} 추가 후 의상실.
• 자동 E2E: /atelier-forge PNG 업로드 → avatar_jobs queued→running→phase 진행→done + result_project_url. 첫 $2 실런은 함께 관찰. 웹캠 구동 판정은 사용자 카메라 몫.

크로스링크

• ChatterBox 계약(UI 빌더용): docs/reference/patterns/avatar-forge-pipeline.md, docs/DATA-SCHEMA.md §1.9, docs/API-SURFACE.md Avatar Forge.
• 리깅 런북: [[autorig-upload-e2e]]. 정적 Vercel 웹앱 배포(다른 타깃): [[vtuber-deploy]].