CLI HyperFrames
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
- Estruturar:
npx hyperframes init <projeto>ou capture um site. No modo não-TTY, use--non-interactive --example=<nome>. - Encontrar o movimento: antes de criar animações manualmente, pesquise uma primitiva que já o faça:
npx hyperframes catalog --query "revelar um título linha por linha". Peça o efeito desejado, não o mecanismo que você tem em mente. Instale comnpx hyperframes add <nome>(veja/hyperframes-registry). Crie manualmente apenas quando nada se encaixar. - Criar: escreva a composição usando
/hyperframes-core. - Obter feedback rápido durante a edição: execute
npx hyperframes lintapós a primeira passagem de HTML e após mudanças estruturais. - Executar a verificação final: execute
npx hyperframes check; ele executa o lint novamente antes de abrir o navegador. Não preceda com uma chamada de lint redundante. Adicione--snapshotspara quadros de visão geral anotados e encontrar cortes. - Inspecionar sub-composições: quando
index.htmlmontadata-composition-src, capture snapshots do ponto médio e inspecione cada cena montada. - Abrir a pré-visualização final do Studio: execute
npx hyperframes preview, entregue a URL do projeto da timeline ao usuário e pergunte se deseja revisar ou renderizar. - Renderizar apenas após aprovação: use qualidade draft para iteração e alta qualidade para entrega.
- Verificar a saída: confirme que o arquivo existe, não está vazio e tem uma duração plausível.
# Verificação de iteração rápida; repita durante a criação conforme necessário.
npx hyperframes lint
# Porta de entrada final obrigatória; 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 o 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 de *.motion.json e contraste WCAG. Achados persistentes bloqueiam o código de saída; achados de entrada ou saída transitórios são informativos. 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é-visualização diferentes
Não confunda estes estados:
| Superfície | Quando pode abrir | Propósito |
|---|---|---|
| Quadro de storyboard | Antes das verificações de composição, apenas se storyboard: yes | Revisar cartões de plano e esboços wireframe. Abrir ?view=storyboard#project/<nome>. |
| Pré-visualização final | Após check passar | Revisar a timeline montada antes de renderizar. 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 sub-composição
Auditorias estáticas não podem capturar todas as falhas de montagem. Quando o projeto usa sub-composições, capture pelo menos um ponto médio visível para cada slot de host:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Trate conteúdo pequeno não estilizado, ícones do tamanho da tela, elementos hero ausentes ou timeouts de registro na timeline como defeitos de montagem que bloqueiam a renderização. Veja hyperframes-core/references/sub-compositions.md para as correções correspondentes.
Convenções do agente
-
Pesquise no catálogo antes de escrever movimentos manualmente.
npx hyperframes catalog --query "<o movimento, em linguagem simples>". A pesquisa é inteiramente local: não há camada hospedada, nenhuma conta, e o texto da consulta nunca é enviado a lugar algum. Por padrão, ele classifica com base no vocabulário compartilhado com o nome, título e descrição do item, o que perde qualquer fraseado que não reuse as próprias palavras do catálogo. Adicione--on-devicepara classificar por significado (veja a camada offline abaixo). -
Leia qual camada respondeu; nunca infira a partir dos resultados aparecerem. Com
--json, o envelope carregaquery,tier(on-deviceouwords),tier_detail,dropped,unindexed,shown,totaleresults, maistop_scorequando a camada respondedora produz um ewarningsquando uma camada foi solicitada e não pôde ser executada. Um resultado fraco emwordsé esperado; o mesmo resultado emon-deviceé um bug.top_scoreé apenas on-device e não tem nenhum limite por trás: o ranker retorna todo o catálogo em alguma ordem para cada consulta, então leia como evidência, e não como aprovação ou falha. -
droppedeunindexedsão distorções opostas entre o registro e o índice on-device, e reformular a consulta não corrige nenhum dos dois.droppedconta nomes classificados que este registro não pode instalar, então as correspondências mais fortes são as que estão sendo perdidas.unindexedconta movimentações do registro que o índice não pode ver, que nenhuma consulta pode retornar. Atualizar o registro não é a resposta para nenhum dos dois: seu manifesto tem um TTL de 24h e se auto-corrige, enquanto os vetores são um artefato publicado separadamente, baixado para~/.hyperframes/catalog/. Reexecutar com--on-devicereobtém esse índice quandounindexedestá acima de zero, então esse é o remédio a ser passado ao usuário. Uma distorção pura de cobertura excessiva (droppedacima de zero enquantounindexedé zero) não aciona a reobtenção; limpar~/.hyperframes/catalog/é a única saída para esse caso. Ambas as contagens são de nomes, não de resultados, então qualquer uma pode excedertotal. -
Quando a pesquisa por significado não retorna nada que valha a pena instalar, diga isso.
npx hyperframes feedback --search-miss "<a consulta que você executou>" --wanted "<o movimento que você precisava>" --tier on-device. Este é o único caminho que envia uma consulta a algum lugar, e é um comando deliberado separado, precisamente para que o simplescatalog --querymantenha sua promessa de não enviar nada. Reporte a falha quando a camada on-device respondeu e os principais resultados ainda não fazem o que você precisa; um resultado fraco na camadawordsé esperado e não vale a pena reportar. O que retorna é uma lista de movimentos que o catálogo ainda não possui, lida diretamente em vez de adivinhada a partir de contagens de instalação, então o fraseado que importa é o efeito que você queria, não o nome do item que você imaginou. Não carrega nenhuma classificação e nunca chega à métrica de classificação. -
Ofereça a camada offline; nunca a ative silenciosamente. Um download único de ~33 MB (uma build ONNX quantizada de
bge-small-en-v1.5mais seu tokenizador, fixado a uma revisão fixa) e os vetores do catálogo do registro, ambos cacheados em~/.hyperframes/, nenhum adicionado ao projeto ou a qualquer pacote. Uma vez cacheado, ele classifica por significado sem enviar nada. Diga o tamanho em voz alta e deixe a pessoa decidir, então passe--on-device(com-ypara pular o prompt) quando ela concordar. A oferta interativa só é acionada em um TTY, e sob--jsonnada sobre ela é impresso, então em uma execução de agente você mesmo deve levantá-la com o usuário. -
Prefira
--jsonpara chamadas de agente e CI.render,previeweplayem modo servidor não fornecem saída JSON comum;preview --selection --jsonepreview --context --jsonsão exceções de modo de consulta. -
doctor --jsonsempre sai com código zero. Verifique sua carga:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
O modo não-TTY é automático.
initrequer--examplelá; use--non-interactivepara forçar comportamento determinístico em um TTY. -
Use um
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 devem bloquear a renderização. -
Caminhos JSON redigem o diretório home como
$HOME; não tente reverter a redação. -
Quando um projeto de nuvem hospedado se aproxima ou excede o limite de upload de 200 MB, use
cloud render --dry-run --jsone siga a investigação de.hyperframesignoreemreferences/cloud.md. Nunca ignore um ativo apenas porque é grande. -
Nunca renderize apenas porque as verificações passaram. Pause na pré-visualização final e aguarde aprovação.
Edições direcionadas pelo Studio
Quando o usuário se refere 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 de origem. Se o resultado relatar no-selection, peça ao usuário para clicar no elemento e reexecutar. Solicite apenas as fatias de contexto de que precisa; use --context-detail full apenas para estilos computados ou metadados de texto editável. O comportamento completo e os códigos de falha estão em references/preview-render.md.
Escolhas 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 a variáveis | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| Renderização em nuvem HeyGen sem infraestrutura | npx hyperframes cloud render |
| Renderização AWS distribuída auto-gerenciada | npx hyperframes lambda render <projeto> --width 1920 --height 1080 --wait |
| Renderização GCP distribuída auto-gerenciada | npx hyperframes cloudrun render <projeto> --width 1920 --height 1080 --wait |
A atribuição de skill é automática — os exemplos acima não precisam de --skill. Um projeto estruturado por um workflow (hyperframes init --skill=<workflow>) registra seu skill proprietário em hyperframes.json, e toda renderização posterior o herda na telemetria anônima: re-renderizações, npm run render e --batch da mesma forma. Passe --skill=<slug> explicitamente apenas para carimbar um projeto que não foi criado através de um workflow (sua primeira renderização então o persiste).
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 desabilitada ou o usuário tenha optado por não participar:
npx hyperframes feedback --rating <0-10> --comment "<resultado específico ou atrito>"
Mantenha o 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 (relativo ao diretório do projeto — o feedback é enviado a um canal público, então não cole caminhos absolutos, prefixos de diretório home ou identificadores de usuário/máquina), comportamento esperado versus real, erro exato (também remova caminhos absolutos de stack traces — mantenha basename + linha, remova o diretório inicial), se a saída foi concluída/usou fallback/falhou, solução alternativa e status do projeto de reprodução. Para uma classificação ≤ 7 que descreva um defeito visual (quadro preto, flicker, saída corrompida, quadro errado, saída em branco, outra anomalia visual), também inclua um bloco COMPOSITION_STRUCTURE: — uma anatomia estrutural que preserva a privacidade (censo de elementos + presença de atributos + forma da timeline) para que os mantenedores possam fazer correspondência de padrões com famílias de bugs conhecidas sem o ZIP da composição. Agentes preenchem isso automaticamente através do helper de censo de composição; o usuário humano não o preenche manualmente. Se o problema não se reproduziu novamente, diga isso e ainda inclua o último comando com falha e os logs. Use --file-issue apenas com consentimento: ele publica uma reprodução mínima em uma URL pública. O formato de pacote obrigatório 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 skills proprietários são contratos de comando obrigatórios, não leitura opcional de fundo. 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 a variáveis | references/compare-and-batch.md |
beats para a grade de beats 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 hospedada pela 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, al