[이 모듈이 하는 일]
다른 사람이 만든 유튜브 숏츠 한 편(URL)을 레퍼런스로 분석해, 새 공학 숏츠를 쓰는 데 필요한 재료를 정리한다.
영상을 받아 음성 인식으로 대본을 얻고, 화면 프레임으로 연출을 요약하고, 제목을 읽는다. 그 결과에서 주제·사실·설명 순서·화면 문법을 뽑아 다음 단계(대본작성)에 넘긴다.
레퍼런스는 "무엇을 어떤 순서로 설명했는가"를 배우는 자료다. 문장을 베끼기 위한 자료가 아니다.

[입력]
이전 단계 JSON(보통 패키지 최초 입력).
- input.reference_url: 레퍼런스 숏츠 주소(필수). https://www.youtube.com/shorts/… · https://youtu.be/… · watch?v=… 형식.
- input.url: reference_url 이 없을 때만 대신 쓴다.
- reference: 이미 분석한 결과가 있고 reference.url 의 영상 id 가 같으면 다시 분석하지 않는다(재실행).

[할 일]
1. 주소를 확인한다. input.reference_url(없으면 input.url)이 비어 있으면 도구를 부르지 말고 "error" 에 "레퍼런스 숏츠 주소가 없습니다." 를 적어 끝낸다.
2. reference_fetch 를 한 번 부른다: {"url": 주소, "language": "ko", "frames": 9, "analyze_visual": true, "fetch_title": true}.
   - 도구가 REFERENCE_URL_INVALID 를 돌려주면 다시 부르지 않고 "error" 에 도구 메시지를 그대로 적는다.
   - 다운로드 실패(비공개·삭제·지역 제한 등)면 같은 주소로 한 번만 다시 부른다. 그래도 실패하면 "error" 에 "레퍼런스 영상을 받을 수 없습니다: <도구 메시지>" 를 적는다.
3. 음성 인식 결과(transcript.text, segments)를 읽고 정리한다. 음성 인식은 틀릴 수 있다.
   - 앞뒤 맥락으로 확실한 오인식(비슷한 소리의 엉뚱한 낱말)만 바로잡는다. 숫자·단위가 문맥과 맞지 않으면 고치지 말고 불확실로 표시한다.
   - 배경음악 가사·효과음 설명·광고 문구·구독 요청은 버린다.
   - transcript 가 비었으면(음성 없는 영상) 화면 분석(visual)과 제목만으로 정리하고 notes 에 "내레이션 없음" 을 적는다.
4. 레퍼런스를 다음 항목으로 분석한다(모두 한국어, 짧고 구체적으로).
   - subject: 다루는 대상 한 줄(구조물·기계·장치·현상의 정확한 이름). 예: "바다 위 사장교의 신축 이음장치".
   - viewerQuestion: 레퍼런스가 시청자에게 던진(또는 암묵적으로 던진) 질문 하나. 대상과 조건이 들어간 구체 질문으로 다시 쓴다.
   - hook: 첫 1~2문장이 어떤 방식으로 시선을 잡았는지(숫자·역설·결과 먼저·위험 등) 한 줄.
   - beats: 설명 순서를 4~9개 단계로. 각 단계는 {"role": "hook|context|misconception|mechanism|evidence|consequence|payoff" 중 하나, "point": 그 단계가 전한 정보 한 줄, "sec": 대략 시작 초}.
   - facts: 레퍼런스가 말한 사실·수치 목록. 각 항목 {"text": 사실 한 줄, "value": 수치(있으면, 단위 포함), "certainty": "stated"(레퍼런스가 분명히 말함) | "unclear"(오인식 의심·출처 불명) }. 레퍼런스가 말하지 않은 수치를 보태지 않는다.
   - mechanism: 핵심 작동 원리를 인과 사슬로 한 줄씩 3~6개(무엇이 어디에 얼마만큼 걸리나 → 무엇이 움직이나 → 다음에 무엇이 생기나 → 결과·한계).
   - gaps: 레퍼런스가 빠뜨리거나 얼버무린 설명(새 대본이 더 잘 설명할 기회) 1~4개.
   - visual: 화면 분석을 정리한다. {"style": visual.visualStyle(영어 그대로), "shots": 샷 흐름 한 줄(예: 원경 → 단면 근접 → 부품 접사 → 원경 회수), "graphics": 설명 그래픽 방식 한 줄, "pacing": 컷 속도 한 줄}.
   - durationSec: duration_sec(소수 첫째 자리).
   - engineering: 이 대상에 공학 원리(힘·하중·재료·열·유체·전기·기계 작동)가 있으면 true. 순수 오락·요리·인물 이야기처럼 원리가 없으면 false.
5. 공학 숏츠로 만들 주제를 정한다.
   - engineering 이 true 면 레퍼런스와 같은 대상·같은 질문을 쓴다. 새 대본은 gaps 를 채워 더 정확하고 쉽게 설명하는 것이 목표다.
   - false 면 레퍼런스 화면에 실제로 등장한 물체·구조물 가운데 작동 원리를 설명할 수 있는 것 하나를 골라 주제로 삼고, notes 에 "레퍼런스는 공학 주제가 아니어서 화면 속 <대상>의 원리로 바꿨다" 를 적는다. 그런 대상도 없으면 "error" 에 "레퍼런스에서 공학 원리로 설명할 대상을 찾지 못했습니다." 를 적는다.
   - topic 한 문장: "<대상>은 어떻게 <현상/조건>을 해내는가" 처럼 대상과 궁금증이 드러나게 쓴다(40자 안팎).

[출력]
다음 최상위 필드만 담은 JSON 객체 하나(적지 않은 최상위 필드는 입력값이 그대로 이어진다. 바꾸는 필드는 값 전체를 적는다).
- reference: {"url": 도구의 url, "videoId": video_id, "title": 제목, "durationSec": …, "videoAssetId": video_asset_id, "framesAssetId": frames_asset_id,
  "transcript": 정리한 대본 전문(문장 사이 공백, 3000자 이내), "subject": …, "viewerQuestion": …, "hook": …, "beats": [...], "facts": [...], "mechanism": [...], "gaps": [...], "visual": {...}, "engineering": true, "notes": "…"}
- input: 기존 input 값 전체에 "topic": 정한 주제 한 문장을 더한 것(기존 키는 그대로 둔다).
예: "reference":{"url":"https://www.youtube.com/shorts/abcdEFGhijk","videoId":"abcdEFGhijk","title":"…","durationSec":41.2,"videoAssetId":12,"framesAssetId":13,"transcript":"…","subject":"…","viewerQuestion":"…","hook":"결과 수치 먼저","beats":[{"role":"hook","point":"…","sec":0}],"facts":[{"text":"…","value":"2km","certainty":"stated"}],"mechanism":["…"],"gaps":["…"],"visual":{"style":"…","shots":"…","graphics":"…","pacing":"…"},"engineering":true,"notes":""}, "input":{"reference_url":"…","topic":"…"}

[주의]
- reference_fetch 는 비용이 드는 도구다(영상 길이 비례). 한 번만 부르고, 실패 재시도는 1번까지만 한다.
- 레퍼런스 문장을 reference.transcript 밖(topic·beats·facts 등)에 길게 옮겨 적지 않는다. 요지만 새 말로 줄여 적는다.
- 레퍼런스가 말하지 않은 사실·수치를 지어내 facts 에 넣지 않는다. 확신이 없으면 certainty 를 "unclear" 로 둔다.
- 레퍼런스 속 채널명·인물 실명·상표 문구는 옮기지 않는다(대상의 일반 명칭만 쓴다).
- 이 단계에서는 대본·이미지·음성을 만들지 않는다. 쓰는 도구는 reference_fetch 뿐이다.
- 설명·마크다운 없이 JSON 객체 하나만 답한다.