pr-to-video - 디스패치 진입점
입력은 GitHub 풀 리퀘스트(코드 변경)이며, PR URL, <소유자>/<저장소>#<N> 참조, 또는 열린 PR이 체크아웃된 저장소에서 "this PR"로 제공됩니다. 출력은 코드 변경 설명자입니다: 무엇이 출시되었고, 왜, 어떻게 작동하는지 — diff/커밋을 바탕으로 before-after, diff-하이라이트, 파일 트리, 영향 장면으로 렌더링됩니다. 기본 길이는 최대 약 3분(최적 지점 약 30-90초)입니다; 진정으로 길거나 모든 파일을 철저히 설명하는 (5분 이상) 워크스루는 다른 레지스터이므로 → /general-video로 이동하세요. 수집을 위한 웹사이트 스크래핑이나 헤드리스 Chrome은 없습니다 — 수집은 gh CLI를 사용합니다. 제공된 스타일 프리셋은 항상 claude(따뜻한 에디토리얼; 시그니처 네이비 코드 창)입니다.
Step 0 전에 경로를 확인하세요. 이 스킬은 GitHub 풀 리퀘스트(
gh를 통해 읽는 코드 변경)를 설명합니다. 입력이 마케팅/제품 사이트인 경우 →/product-launch-video; 일반 웹사이트 →/website-to-video; PR이 없는 주제/기사 →/faceless-explainer; 전체 저장소 둘러보기 또는 여러 PR 릴리스 →/general-video. 범위를 벗어남: 실시간/렌더링 시 데이터 — PR 정보는 작성 시점에 한 번 읽혀서 저장됩니다. PR이 아닌 입력이 제공되거나 확실하지 않은 경우? 먼저/hyperframes를 읽으세요.
이 워크플로우는 PR별 전단(수집 + 스토리 디자인)만 소유합니다; _공유_로 표시된 모든 단계는 faceless-explainer에서 변경되지 않은 엔진을 재사용합니다(이 스킬의 자체 scripts/ + agents/ + phases/ 아래에 있으므로 <SKILL_DIR>은 pr-to-video로 해석됩니다).
모든 아티팩트는 PROJECT_DIR = videos/<프로젝트-이름>/로 이동합니다(Step 0에서 생성됨); 아래 모든 경로는 이에 상대적입니다. 디스패치는 하네스에 이식 가능합니다: 첫 번째 서브에이전트 디스패치 전에 <SKILL_DIR>/../hyperframes-core/references/subagent-dispatch.md를 한 번 읽으세요 — 디스패치 동사(병렬 팬아웃 / 백그라운드 / 대기)를 하네스의 기본 요소에 매핑합니다; N 이하의 동시성 제한은 제한 크기의 웨이브를 의미하며, 더 적은 작업자를 사용하지 않습니다. 이 파일은 배경 읽기가 아닌 바인딩 런북입니다: 단계를 순서대로 실행하고 모든 단계 아티팩트를 지정된 스크립트 또는 에이전트 역할로 생성하세요 — 자유 형식 파이프라인으로 대체하지 말고, 요청이 명확해 보인다고 해서 일시 중지 단계를 건너뛰지 마세요. 수행할 수 없는 단계가 있으면 → 중지하고 보고하세요.
| 단계 | 실행 | 주요 아티팩트 | 상세 흐름 |
|---|---|---|---|
| init | Bash | hyperframes.json | Step 0 |
| 수집 (자체) | Bash (gh CLI + ingest.mjs + fetch-people-avatars.mjs, 에이전트 없음, 스크래핑 없음) | capture/pr.json + diff.patch + extracted/{tokens.json,visible-text.txt,people.json} + public/avatars/ | Step 1 |
| 디자인-시스템 (공유) | Bash (에이전트 없음, 결정적 claude) | design-system/design.html + chunks/ | Step 1b |
| 스토리-디자인 (자체) | 서브에이전트 | narrator_scripts.json | agents/story-design.md |
| 오디오 (공유) | Bash의 audio.mjs | audio_meta.json | phases/audio/guide.md |
| 시각-디자인 (공유) | 서브에이전트 | section_plan.md | agents/visual-design.md |
| 준비 (공유) | Bash의 prep.mjs | group_spec.json | scripts/prep.mjs |
| 캡션 (공유, 상세) | Bash의 captions.mjs group -> captions.mjs html (서브에이전트 없음) | caption_groups.json + compositions/captions.html | scripts/captions.mjs |
| 장면 (공유) | N x 서브에이전트 (병렬) | compositions/scene_*.html 또는 compositions/group_w*.html | agents/hyperframes-scene.md |
| 마무리 (공유) | Bash 서곡 (wait-bgm + 조립 + 주입/전환 확인 + hoist-videos + sfx-확인 + 사전 비행) -> 마무리 서브에이전트 (간단한 발견 사항을 제자리 수정 + 하나의 간결한 연락처 시트 보기 + 렌더링) | renders/video.mp4 | Step 7 / agents/hyperframes-finalize.md |
전제 조건
macOS Apple Silicon 또는 Linux x64. 시스템 도구: brew install [email protected] node ffmpeg (Homebrew Python 사용, /usr/bin/python3 아님, 그렇지 않으면 PEP 668에 의해 pip install이 차단됨); 그런 다음 npx hyperframes doctor를 한 번 실행(Chrome 다운로드 — 스냅샷/렌더링에 필요, 수집에는 불필요). 렌더링된 겹침 게이트(scripts/check-overlap.mjs, 작업자 자체 확인 및 사전 비행에서 실행)는 동일한 캐시된 Chrome을 재사용합니다 — 브라우저를 다운로드하지 않습니다; 유일한 종속성은 puppeteer-core npm 모듈이며, 장면 팬아웃 전에 한 번 확인됩니다(Step 5.5, --ensure-deps, ~5초, 전체 puppeteer 설치 없음). CLI: gh (GitHub CLI, 인증됨 — gh auth status 통과 필수) 및 hyperframes. 선택적 클라우드 키(그렇지 않으면 로컬 폴백) — Step 0.5에서 주입:
| 키 / 요구 사항 | 사용 목적 | 기본값 / 폴백 |
|---|---|---|
gh auth status OK | PR 읽기 (공개 또는 비공개) | 필수 — 인증 힌트와 함께 빠르게 실패 |
HEYGEN_API_KEY (또는 hyperframes auth login) | TTS (클라우드, 단어 수준 타임스탬프) | 음성: 자동 (첫 번째 영문 스타피시 음성; --voice로 재정의 가능) |
ELEVENLABS_API_KEY | TTS (클라우드; pip install elevenlabs 필요) | 음성 21m00Tcm4TlvDq8ikWAM (Rachel) |
| 둘 다 없고 로그인되지 않음 | TTS | 로컬 Kokoro, 음성 am_michael (비영어: --voice 전달) |
GEMINI_API_KEY / GOOGLE_API_KEY (별칭) | Lyria BGM | 설정되지 않음 -> 로컬 MusicGen (첫 실행 시 약 300MB 다운로드) |
흐름
Step 0.0 - 브리핑 확인 (항상 한 번 질문한 다음 구축)
Step 0 전에 항상 잠시 멈추고 한 메시지로 브리핑을 질문한 다음 사용자를 기다리세요 — 요청이 완료된 것처럼 보여도 절대 건너뛰지 마세요. 각 필드에 권장 기본값을 제시하고 사용자가 이미 제공한 내용을 미리 채우세요(맹목적으로 다시 묻지 않고 확인): 각도(변경 로그 / 기능 공개 / 수정 / 리팩터링 — 기본값: PR에서 유추), 대상(개발자 vs 일반 사용자 — 기본값: 개발자), 길이(기본값 ~60-90초), 그리고 — /hyperframes가 설정하지 않은 경우 — 화면 비율(기본값 16:9) 및 언어. 스타일은 항상 claude입니다. 사용자가 응답한 후에만 Step 0으로 진행하세요; "가다" / "기본값 사용"은 모든 기본값을 수락하는 유효한 응답입니다.
Step 0 - 비디오 프로젝트 초기화
cwd는 에이전트 작업 공간 루트입니다(예: /tmp/pr-video-...). 모든 비디오 아티팩트를 PROJECT_DIR = videos/<프로젝트-이름>/ 아래에 작성하세요.
<프로젝트-이름>: 사용자가 제공한 디렉토리 사용(예: ./videos/retry-pr 사용), 그렇지 않으면 PR에서 파생된 짧은 케밥-케이스 이름(<저장소>-pr-<N>, 예: widgets-pr-1187). 작업 공간 기본 이름이나 타임스탬프는 사용하지 마세요.
$PROJECT_DIR/hyperframes.json이 없는 경우에만:
PROJECT_DIR="${PR_VIDEO_DIR:-videos/<프로젝트-이름>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --skip-skills --example=blank
hyperframes init는$PROJECT_DIR에 일반AGENTS.md/CLAUDE.md를 생성합니다; 그대로 두세요 — 나중에 완료된 프로젝트를 여는 사람을 위한 에이전트 스캐폴딩입니다.
제약 조건: 작업 공간 루트에서 hyperframes init / AGENTS.md / CLAUDE.md 생성을 실행하지 마세요; PROJECT_DIR 내부에 다른 hyperframes/를 중첩하지 마세요; 모든 Bash 명령어(마스터 + 서브에이전트)는 (cd "$PROJECT_DIR" && ...) 서브셸입니다 — 절대 cd를 단독으로 사용하지 마세요.
Step 0.5 - API 키 안내
$PROJECT_DIR/.env가 존재하거나 context.log가 비어 있지 않은 경우(=첫 번째 실행이 아님) 건너뛰세요. 그렇지 않으면 먼저 사용 가능한 것을 감지하세요(HeyGen TTS는 $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY가 설정되었거나 hyperframes auth login에서 ~/.heygen/credentials가 존재하는 경우 켜짐; ElevenLabs / Gemini는 해당 환경 키가 설정된 경우에만), 그런 다음 항상 잠시 멈추고 메뉴를 제공하세요 — 사용자를 기다리세요; 작동 가능한 구성이 감지되어도 스스로 진행하지 마세요(사용자가 Gemini와 같은 키를 추가하려 할 수 있음). 감지된 내용을 명시한 다음, 키 붙여넣기 (→ $PROJECT_DIR/.env 쓰기, 한 줄에 KEY=value, 동일한 이름 덮어쓰기) / "가다" (구성된 대로 진행 — env, .env, 또는 hyperframes auth login) / "건너뛰기" (구성되지 않은 항목에 대해 로컬 폴백으로 진행). 그런 다음 Step 1로 진행하세요.
Step 1 - 수집 (Bash, 에이전트 없음, 스크래핑 없음)
PR 참조를 확인하고 gh로 구조화된 정보를 가져온 다음, 공유 백엔드가 예상하는 합성 캡처 패키지로 통합합니다(faceless-explainer의 스크래핑 없는 스캐폴드를 미러링). gh는 여기, 오케스트레이터에서 실행되므로 인증/찾을 수 없음/비공개 저장소 오류는 gh의 자체 stderr로 표시됩니다; ingest.mjs는 순수 오프라인 변환입니다.
# PR 참조: 전체 URL, "<소유자>/<저장소>#<N>", 또는 체크아웃된 저장소 내 "<N>".
PR="<url | owner/repo#N | N>"
# gh가 인증되지 않은 경우 빠르게 실패.
gh auth status || { echo "gh가 인증되지 않음 — 실행: gh auth login"; exit 1; }
(cd "$PROJECT_DIR" && mkdir -p capture/extracted capture/assets)
(cd "$PROJECT_DIR" && gh pr view "$PR" \
--json number,title,body,author,url,baseRefName,headRefName,commits,files,additions,deletions,changedFiles,labels,reviews,latestReviews,comments,assignees,reviewDecision,mergedBy \
> capture/pr.json)
(cd "$PROJECT_DIR" && gh pr diff "$PR" > capture/diff.patch)
# pr.json + diff.patch를 tokens.json(colors:[] → claude 네이티브 팔레트) +
# visible-text.txt(내러티브 브리핑) + people.json(PR 작성자 + 커밋 작성자(개수 포함) +
# 리뷰어/댓글 작성자/할당자, 봇 필터링 + 중복 제거, 각각 GitHub 아바타 URL 포함)으로 통합.
# (PR `author`는 개설자만; commits[].authors[]의 커밋 작성자도 추적됨)
# ingest는 오프라인입니다.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# 네트워크 단계(people 전면의 유일한 단계 — ingest는 오프라인 상태 유지): 각
# 기여자의 GitHub 아바타를 public/avatars/<login>.png에 다운로드하여 선택적 크레딧/
# 출시 주체 클로즈에 사용합니다. 최선 노력 — 누락된 아바타나 오프라인 실행은 절대 차단하지 않음(exit 0).
# 아바타 + 해당 클로즈는 pr-to-video가 faceless 기본값을 완화하는 유일한 곳입니다.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
유효성 검사:
[ -s "$PROJECT_DIR/capture/pr.json" ] && \
[ -s "$PROJECT_DIR/capture/diff.patch" ] && \
[ -s "$PROJECT_DIR/capture/extracted/tokens.json" ] && \
[ -s "$PROJECT_DIR/capture/extracted/visible-text.txt" ] && \
[ -s "$PROJECT_DIR/capture/extracted/people.json" ] && \
[ -d "$PROJECT_DIR/capture/assets" ] && echo ok || echo missing
# public/avatars/는 최선 노력 — 부재는 실패가 아님(아바타가 확인되지 않음/오프라인).
gh가 오류를 반환하면(인증/찾을 수 없음/비공개), 정확한 stderr를 보고하고 중지하세요 — PR 내용을 조작하지 마세요. ingest.mjs가 종료되면
…
[번역을 위해 잘림]