HyperFrames Ops
환경 관련 질문을 받기 전에, 먼저 같은 디렉토리의 experience.local.md를 읽어 이 머신의 최신 사실(프록시 명령, 버전 스냅샷, 과거 QA)을 확인하세요.
0. 왜 독립적인 Ops 레이어가 필요한가
써드파티 Skills는 일반적인 능력만 설명하며, 각 머신의 네트워크, 프록시, Node/FFmpeg 버전, 폰트 캐시, 로그인 상태 및 도구 조합을 예측할 수 없습니다. 공식 Skill을 직접 수정하면 업데이트 충돌이 발생하고, 이 머신의 고유한 사실이 업스트림 일반 설명에 섞이게 됩니다.
따라서 두 레이어를 분리합니다:
- 공식 Skills는 능력 원천이며, 업데이트 및 교체가 가능하도록 유지됩니다.
hyperframes-ops는 이 머신에 특화된 적응 레이어로, 모범 사례, 호환성 차이, 실패 패턴 및 검증된 해결 방법을 기록합니다.- 제작 문제 발생 시 먼저 공식 Skill을 읽고, 환경, 조합, 버전 또는 머신 적응 문제 발생 시 이 Skill을 읽습니다.
- 업스트림 업데이트로 인해 예전 경험이 유효하지 않게 된 경우, 로컬 경험에서 무효화 표시하고 재검증하며, 오래된 경험으로 새 동작을 덮어쓰지 않습니다.
1. 프로젝트 정체성 (일반화된 사실)
- HyperFrames는 HeyGen 공식 오픈소스 프로젝트입니다:
github.com/heygen-com/hyperframes, npm 패키지명hyperframes - 목적: HTML로 비디오 합성을 작성하고 headless Chrome을 통해 mp4로 렌더링하는 CLI (
npx hyperframes) - 환경 요구사항: Node.js >= 22, FFmpeg
2. 공식 skills 배포 메커니즘
- 공식 skills는 CLI와 함께 동일 저장소에서 유지 관리되며 버전화되어 배포됩니다. 매니페스트는 저장소 루트에 위치합니다:
https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills-manifest.json - 구성: 핵심 세트 (hyperframes / hyperframes-core / hyperframes-cli / hyperframes-animation / hyperframes-keyframes / hyperframes-creative / hyperframes-registry / remotion-to-hyperframes) + 워크플로 세트 (general-video, slideshow, motion-graphics, music-to-video, pr-to-video, product-launch-video, website-to-video, faceless-explainer, talking-head-recut, embedded-captions, media-use, figma). 실제
skills check출력을 기준으로 합니다. - 관리 명령어:
npx hyperframes skills check— 매니페스트와 비교하여 버전 확인npx hyperframes skills update— 설치된 모든 스킬 업데이트 + 공식에서 제거된 스킬 정리npx hyperframes init— 강제로 skills를 최신 상태로 동기화 (--skip-skills는 현재 공식에서 비활성화됨)
- 설치 위치: 전역
~/.claude/skills/(CLI가 claude-code 자동 인식) - 이름 안전성:
skills update의 정리 로직은 lock 파일을 기준으로 "출처 소속"을 판단하여, 공식 저장소에서 유래하고 제거된 skill만 삭제합니다. 본 skill은hyperframes-로 시작하지만 공식 lock 소속에 포함되지 않으므로 공식 업데이터에 의해 실수로 삭제되지 않습니다.
3. 문제 해결 경로
| 증상 | 경로 |
|---|---|
skills check/update/init에서 AbortError 발생 (fetchManifest 시간 초과) | 네트워크 문제: CLI가 Node 내장 fetch로 raw.githubusercontent.com에 접근하며, 직통 연결이 안 될 때는 반드시 프록시를 거쳐야 함. experience.local.md를 읽어 이 머신에 바로 적용 가능한 명령어를 확인하세요. |
npx hyperframes 기타 네트워크 관련 실패 | 위와 동일; Node 내장 fetch(undici)는 기본적으로 HTTP_PROXY 환경 변수를 읽지 않음. Node 24+에서는 NODE_USE_ENV_PROXY=1 (또는 --use-env-proxy)를 추가해야 함. |
| 렌더링/미리보기 환경 이상 | npx hyperframes doctor, npx hyperframes browser 자가 진단; Node >= 22, FFmpeg 사용 가능 여부 확인. |
| skill 동작이 구버전처럼 보임 | skills check로 버전 차이를 확인하고, skills update로 최신 상태로 맞춤. |
heygen auth login --oauth 토큰 교환 실패 (api2.heygen.com connection refused) 또는 음악 라이브러리 호출 시간 초과 | heygen CLI는 Go 프로그램으로, HTTP(S)_PROXY 환경 변수를 인식(Node fetch와 반대로 추가 스위치 불필요); 제한된 네트워크에서는 모든 heygen 명령어에 프록시를 포함해야 함. OAuth 콜백 서비스는 5분만 유지되며 대화형 셸이 필요함 (백그라운드/nohup 실행 시 콜백을 받지 못해 시간 초과 발생). 이 머신용 명령어는 experience.local.md 참조. |
| 렌더링 결과 폰트가 잘못됨 (제목이 넓어지거나 컨테이너를 벗어남, lint/inspect는 모두 정상) | 내장 18개 폰트는 런타임에 필요할 때 네트워크에서 가져옴 (@fontsource → ~/.cache/hyperframes/fonts), 가져오기 실패 시 조용히 시스템 폰트로 대체됨. 제한된 네트워크에서의 해결 방법: woff2를 프로젝트에 다운로드하여 명시적으로 @font-face로 자체 호스팅. |
| 제작 관련 질문 (합성, 애니메이션, 렌더링 파라미터 작성 방법) | 이 skill의 범위가 아니며, 공식 hyperframes 진입 skill의 경로표 참조. |
4. 경험 기록 프로토콜
- experience.local.md에 기록 (이 머신 전용이며, 이 디렉토리의 .gitignore에 의해 무시됨): 새롭게 발견한 함정과 검증된 해결 방법, 버전/설치 상태 스냅샷 (날짜 포함), 이 머신 전용 명령어, 프록시 및 네트워크 관련 사실, 과거 QA
- 본 SKILL.md에 기록 (git에 포함되어 공유 가능): 공식 메커니즘 변경 사항 (배포 방식, 명령어 의미, 정리 로직), 새로운 일반화된 문제 해결 경로
- 판단 기준: 다른 머신에서도 유효한 내용 → SKILL.md; 이 머신에서만 유효한 내용 → experience.local.md
- HyperFrames 환경 문제로 인해 호출되어 해결된 후에는, 결론을 위 계층 구조에 따라 기록하고 날짜를 명시하세요.