Communitygithub.com

simpletibr/simplicio-loop-marketing

HyperFrames CLI 개발 루프(초기화, 린트, 검사, 미리보기, 렌더링)를 실행합니다. `hyperframes` 스킬로 작성된 컴포지션에 대해 HTML이 디스크에 생성된 후, 작업이 완료로 표시되기 전에 호출됩니다.

simplicio-loop-marketing란 무엇인가요?

이 스킬은 마케팅 엔진 파이프라인에서 HyperFrames CLI(`npx hyperframes`)를 실행하는 전문 도구입니다. 컴포지션 프로젝트(반드시 `index.html`과 `composition.json`을 포함)가 디스크에 준비된 후, 린트(lint), 검사(inspect), 미리보기(preview), 렌더링(render) 단계를 순차적으로 수행합니다. `DRY_RUN` 모드가 기본적으로 활성화되어 있어, 실제 렌더링 외의 단계는 외부 호출 없이 안전하게 실행됩니다. Node.js >= 22와 FFmpeg가 PATH에 있어야 하며, `npx hyperframes doctor` 명령어로 환경을 확인할 수 있습니다. 이 스킬은 `hyperframes-prompt-builder` 다음에, `qa-tech-specs` 이전에 위치하며, 컴포지션의 유효성 검증과 최종 MP4 아티팩트 생성을 담당합니다. 린트와 검사 단계에서 발견된 오류는 반드시 해결되어야 하며, 렌더링은 항상 `--strict` 및 `--strict-variables` 플래그를 적용하여 변수 누락 등의 실수를 방지합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/simpletibr/simplicio-loop-marketing/tree/HEAD/.skills/hyperframes-cli

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

HyperFrames CLI

마케팅 엔진 파이프라인을 위한 npx hyperframes 래퍼입니다. Node.js >= 22와 PATH에 FFmpeg가 필요합니다(npx hyperframes doctor로 확인). 모든 명령은 기본적으로 DRY_RUN-safe 모드로 실행됩니다. lint/inspect 단계는 외부 호출이 없으며, render만 MP4를 작성합니다.

호출 시기

  • hyperframes-prompt-builder가 outputs/<client>/<date>/<piece-id>/ 아래에 프로젝트를 생성한 직후
  • 컴포지션을 게시하기 전에 유효성 검사가 필요할 때(lint + inspect)
  • 작업을 반복하면서 로컬 미리보기가 필요할 때(preview)
  • 게시 단계에서 사용할 최종 아티팩트를 생성하는 렌더링(render)
  • 렌더링 실패 시 환경 문제 해결(doctor, browser, info)

입력값

  • project_path: 문자열. HyperFrames 프로젝트 경로(index.html과 composition.json을 반드시 포함).
  • mode: "lint" | "inspect" | "preview" | "render" | "doctor".
  • render_opts: 객체, 선택 사항, mode = "render"일 때만 사용. 인식하는 키:
    • fps: 24 | 30 | 60 (기본값 30).
    • quality: "draft" | "standard" | "high" (기본값 "standard"; 반복 작업 중에는 "draft" 사용).
    • format: "mp4" | "webm" (기본값 "mp4").
    • variables: 객체. 변수 ID를 키로 하는 JSON 객체로, data-composition-variables 기본값을 재정의합니다.
    • strict: 불리언. --strict에 매핑. 파이프라인에서 기본값 true — lint 오류가 있으면 렌더링 실패.
    • strict_variables: 불리언. --strict-variables에 매핑. 조각 실행 시 기본값 true.
    • workers: 1-8 사이의 정수 또는 "auto". 기본값 "auto".
    • output: 문자열. outputs/<client>/<date>/<piece-id>/ 내부의 출력 파일 경로.

프로세스

  1. 환경 확인 (세션 첫 실행 시): npx hyperframes doctor. FFmpeg 또는 Chrome이 없으면 하드 블록으로 표시 — 렌더링을 시도하지 않음.
  2. Lint. npx hyperframes lint <project_path> --json. 모든 error 수준의 결과를 차단 요인으로 처리. 경고는 오케스트레이터에 전달하여 운영자가 결정.
  3. Inspect. npx hyperframes inspect <project_path> --json. 렌더링 전에 텍스트 오버플로우나 캔버스 이스케이프 문제를 해결. 오버플로우가 의도적인(진입/퇴장 애니메이션) 경우, 요소에 data-layout-allow-overflow를 추가하거나(장식 요소의 경우 상위 요소에 data-layout-ignore 사용) — 전역적으로 규칙을 무음 처리하지 않음.
  4. Preview (운영자 전용). npx hyperframes preview <project_path> --port <port>. 스튜디오 프로젝트 URL(http://localhost:<port>/#project/<project-name>)을 반환하며, 소스 index.html 경로는 반환하지 않음.
  5. Render. render_opts에서 해석된 플래그를 사용하여 npx hyperframes render <project_path> 실행. render_opts.variables에서 --variables 인수를 한 줄 JSON 문자열로 구성. 조각 실행 시 항상 --strict와 --strict-variables를 전달.
  6. 출력 확인. 렌더링 후 MP4 파일이 존재하고 크기가 0이 아닌지 확인. { ts, provider: "hyperframes", composition_id, render_args, duration_seconds, file_bytes, latency_ms } 형식으로 data/video-usage.jsonl에 로그.

출력값

  • lint: { pass: boolean, errors: [...], warnings: [...] }.
  • inspect: { pass: boolean, findings: [...] }.
  • render: { artifact_path: string, duration_s: number, file_bytes: number, render_ms: number }.
  • preview: { url: string }.

명령어 치트 시트

npx hyperframes init <name>                            # 스캐폴드 (프롬프트 빌더가 각 조각에 대해 한 번 사용)
npx hyperframes lint <path>                            # 마크업 검증
npx hyperframes inspect <path>                         # 레이아웃/오버플로우 감사
npx hyperframes preview <path> --port 3017             # 로컬 개발
npx hyperframes render <path> \
  --fps 30 --quality standard --strict --strict-variables \
  --variables '{"leads":42,"delta_pct":12}' \
  --output outputs/<client>/<date>/<piece-id>/final.mp4
npx hyperframes doctor                                 # 환경 확인
npx hyperframes info                                   # 버전/환경 세부 정보

변경 불가 규칙

  • lint 및 inspect 단계를 통과하지 않고 렌더링하지 않음. 파이프라인에 잘못된 컴포지션을 복구할 경로가 없음.
  • lint 또는 inspect 결과를 전역적으로 무음 처리하지 않음 — 마크업을 수정하거나 특정 요소를 data-layout-allow-overflow / data-layout-ignore로 허용 목록에 추가.
  • 선언된 변수가 있는 조각의 경우 항상 --strict-variables를 전달. 변수 ID 오타는 조용히 기본값으로 넘어가지 않고 반드시 실패해야 함.
  • 최종 전달 렌더링의 경우 --quality high. 반복 루프의 경우 --quality draft를 사용하여 컴퓨팅 리소스 절약.
  • 자산 전처리(tts, transcribe, remove-background)는 이 스킬의 범위를 벗어남 — 여기에 인라인으로 작성하지 말고 향후 hyperframes-media 스킬을 통해 호출.

실패 모드

  • doctor가 FFmpeg 또는 Chrome 누락을 보고: 프로젝트의 설정 지침에 따라 설치; 우회하지 않음.
  • render가 unknown variable 오류로 실패: --variables를 통해 전달된 키가 data-composition-variables에 선언되지 않음. 마크업을 수정하거나 재정의를 제거.
  • render가 벽시계 시간 예산 초과: --quality를 standard로 낮추거나, 컴포지션을 하위 컴포지션으로 분할하고 --workers를 통해 병렬화.
  • 출력 MP4 크기가 0바이트: doctor를 다시 실행; 거의 항상 Chrome이 캡처 중에 충돌한 경우.

관련 스킬

  • hyperframes: 컴포지션 작성 규칙; 이 스킬이 검증하고 렌더링할 프로젝트를 생성.
  • hyperframes-prompt-builder: 브리프 → 컴포지션 스펙; 이 스킬보다 먼저 실행.
  • qa-tech-specs: 렌더링된 MP4를 검증하여 플랫폼 사양을 확인; 이 스킬 이후에 실행.

상위 참조

전체 상위 스킬(모든 플래그, 문제 해결 매트릭스, 매개변수화된 렌더링): https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes-cli

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

관련 스킬