O que HyperFrames CLI faz?
Execute comandos como npx hyperframes ... a menos que as instruções do projeto forneçam um wrapper. Obedeça ao wrapper quando presente. A CLI requer Node.js 22 ou superior e FFmpeg.
Ciclo de desenvolvimento
- Scaffold:
npx hyperframes init <projeto>ou capture um site. Em modo não TTY, use--non-interactive --example=<nome>. - Autoria: escreva a composição usando
/hyperframes-core. - Obtenha feedback rápido durante a edição: execute
npx hyperframes lintapós a primeira passagem de HTML e após mudanças estruturais. - Execute o portão final: execute
npx hyperframes check; ele reexecuta lint antes de abrir o navegador. Não adicione uma invocação redundante de lint separada. Adicione--snapshotspara quadros de visão geral anotados e encontrar cortes. - Inspecione subcomposições: quando
index.htmlmontardata-composition-src, capture snapshots de pontos médios e inspecione cada cena montada. - Abra a prévia final do Studio: execute
npx hyperframes preview, entregue a URL do projeto da linha do tempo ao usuário e pergunte se deseja revisar ou renderizar. - Renderize somente após aprovação: use qualidade draft para iteração e qualidade alta para entrega.
- Verifique a saída: confirme que o arquivo existe, não está vazio e tem uma duração plausível.
# Verificação rápida de iteração; repita enquanto edita conforme necessário.
npx hyperframes lint
# Portão final obrigatório; inclui lint.
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4
check executa lint primeiro, depois usa uma sessão de navegador e uma passagem de busca para auditar erros de tempo de execução, requisições com falha, layout, asserções *.motion.json e contraste WCAG. Descobertas persistentes bloqueiam o código de saída; descobertas transitórias de entrada ou saída são informativas. Use --strict para bloquear avisos. validate, inspect e layout permanecem como aliases para compatibilidade, mas não devem aparecer em novas instruções ou scripts.
Duas superfícies de prévia diferentes
Não confunda esses estados:
| Superfície | Quando pode abrir | Propósito |
|---|---|---|
| Quadro de storyboard | Antes das verificações de composição, apenas com storyboard: yes | Revisar cartões de plano e esboços de wireframe. Abrir ?view=storyboard#project/<nome>. |
| Prévia final da composição | Após a aprovação do check | Revisar a linha do tempo montada antes da renderização. Abrir #project/<nome>. |
O quadro inicial não é aprovação do vídeo final. A renderização sempre requer a aprovação final definida por hyperframes-core/references/review-loop.md.
Teste de fumaça de subcomposição
Auditorias estáticas não podem capturar todas as falhas de montagem. Quando o projeto usar subcomposições, capture pelo menos um ponto médio visível para cada slot hospedeiro:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Trate conteúdo pequeno sem estilo, ícones do tamanho da tela, elementos herói ausentes ou timeouts de registro na linha do tempo como defeitos de montagem que bloqueiam a renderização. Consulte hyperframes-core/references/sub-compositions.md para as correções correspondentes.
Convenções para agente
-
Prefira
--jsonpara chamadas de agente e CI. Modos servidorrender,previeweplaynão fornecem saída JSON comum;preview --selection --jsonepreview --context --jsonsão exceções de modo consulta. -
doctor --jsonsempre sai com zero. Avalie seu payload:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
Modo não TTY é automático.
initrequer--examplelá; use--non-interactivepara forçar comportamento determinístico em um TTY. -
Use um único
HYPERFRAMES_RUN_IDpara todos os comandos no mesmo loop de verificação. -
Use
--strict,--strict-alle--strict-variablesquando os avisos, variáveis ou condições de CI correspondentes precisarem bloquear a renderização. -
Caminhos JSON redigem o diretório home como
$HOME; não tente reverter a redação. -
Nunca renderize apenas porque as verificações passaram. Pause na prévia final e aguarde aprovação.
Edições direcionadas pelo Studio
Quando o usuário se referir a “este elemento” ou à seleção atual, consulte o Studio em vez de adivinhar:
npx hyperframes preview --context --json --context-fields selection
Use selection.target.hfId quando disponível, caso contrário, seu seletor e arquivo fonte. Se o resultado reportar no-selection, peça ao usuário para clicar no elemento e executar novamente. Solicite apenas as fatias de contexto necessárias; use --context-detail full apenas para estilos computados ou metadados de texto editável. O comportamento completo e códigos de falha estão em references/preview-render.md.
Opções de renderização
| Necessidade | Comando |
|---|---|
| Iteração local rápida | npx hyperframes render --quality draft |
| Entrega local final | npx hyperframes render --quality high --output out.mp4 |
| Renderização em contêiner reproduzível | npx hyperframes render --docker --strict --output out.mp4 |
| Renderização em lote local orientada por variável | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| Renderização em nuvem HeyGen sem infraestrutura | npx hyperframes cloud render |
| Renderização distribuída AWS autogerenciada | npx hyperframes lambda render <projeto> --width 1920 --height 1080 --wait |
| Renderização distribuída GCP autogerenciada | npx hyperframes cloudrun render <projeto> --width 1920 --height 1080 --wait |
Use renderização em nuvem quando o usuário quiser renderização hospedada sem Chrome local, FFmpeg ou AWS. Use Lambda apenas quando a propriedade da AWS for um requisito. Use Cloud Run apenas quando a propriedade do GCP for um requisito. Leia a referência correspondente antes de executar qualquer caminho de nuvem.
Após verificar uma renderização bem-sucedida, envie um relatório de feedback, a menos que a telemetria esteja desativada ou o usuário tenha optado por não participar:
npx hyperframes feedback --rating <0-10> --comment "<resultado específico ou atrito>"
Mantenha feedback de execução limpa conciso. Para qualquer bug ou atrito, capture um pacote de reprodução antes de enviar; não envie apenas um resumo do sintoma. Inclua o comando reexecutável e diretório de trabalho, comportamento esperado versus real, erro exato, se a saída foi concluída/fallback/falhou, solução alternativa e status do projeto de reprodução. Se o problema não se reproduziu novamente, informe e ainda inclua o último comando e logs que falharam. Use --file-issue apenas com consentimento: ele publica uma reprodução mínima em uma URL pública. O formato obrigatório do pacote e o aviso de privacidade estão em references/preview-render.md.
Leia a referência correspondente antes de executar um comando
As seguintes referências e habilidades proprietárias são contratos de comando obrigatórios, não leitura de fundo opcional. Antes de executar um comando na tabela, leia sua linha correspondente.
| Necessidade | Referência |
|---|---|
init, capture, skills | references/init-and-scaffold.md |
lint, check, sidecars de movimento, snapshot | references/lint-validate-inspect.md |
compare, grade-compare, render --batch orientado por variável | references/compare-and-batch.md |
beats para a grade de batidas do Studio de um projeto existente | references/beats.md |
preview, play, render, publish, contexto do Studio, feedback | references/preview-render.md |
doctor, gerenciamento de navegador | references/doctor-browser.md |
auth, renderização em nuvem HeyGen e variáveis de template | references/cloud.md |
| Implantação e renderização AWS Lambda | references/lambda.md |
| Implantação e renderização Google Cloud Run | references/cloudrun.md |
info, upgrade, compositions, docs, benchmark, telemetria, pré-processamento de mídia | references/upgrade-info-misc.md |
Para variáveis de composição, leia também /hyperframes-core → references/variables-and-media.md. Para hyperframes add e hyperframes catalog, use /hyperframes-registry. Antes de hyperframes present, leia /slideshow; antes de hyperframes keyframes, leia /hyperframes-keyframes. Para TTS, transcrição, legendas ou opções de remoção de fundo, use /media-use.
Os comandos especializados estão documentados por seus fluxos de trabalho proprietários:
npx hyperframes present <diretório-do-projeto> --port 3004 --no-open
npx hyperframes beats <diretório-do-projeto> --json
npx hyperframes keyframes <diretório-do-projeto> --json
present serve um deck navegável com sincronização de apresentador e audiência. beats é o utilitário standalone da grade de batidas do Studio definido em references/beats.md. keyframes expõe diagnósticos de animação e caminho de movimento seguros para seek.