HyperFrames CLI - Kit de Lançamento SaaS

Instalação de plugins: Antes de comandos de configuração ou atualização, siga as regras de execução de plugins quando esta skill estiver dentro de um plugin HyperFrames. Instalações independentes mantenham as instruções de atualização abaixo.

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 mais recente e FFmpeg.

Ciclo de desenvolvimento

1. Estruturar: npx hyperframes init <projeto> (em branco centralizado). Ou capture um site. Passe --example=<nome> apenas para começar a partir de um exemplo nomeado.
2. Encontrar o movimento: se a solicitação nomear um ativo, som, imagem, voz ou edição visual rápida, resolva através de /media-use antes de propor um plano. Caso contrário, antes de criar movimento manualmente, pesquise por uma primitiva que já faça isso: npx hyperframes catalog --query "revelar um título linha por linha". Peça o efeito que você deseja, não o mecanismo que você tem em mente. Instale com npx hyperframes add <nome> (veja /hyperframes-registry). Crie manualmente apenas quando nada se encaixar.
3. Criar: escreva a composição usando /hyperframes-core. Para saber o que está na timeline de um projeto (faixas, clipes, inícios, fins, o que toca), execute npx hyperframes timeline --json em vez de ler index.html e cada arquivo de sub-composição: linhas aninhadas carregam absStart/absEnd absolutos da timeline principal e seu file proprietário, não apenas seu tempo local por sub-composição. Prefira --json sobre a forma textual; custa menos tokens pela mesma ou melhor precisão. Veja references/upgrade-info-misc.md para one-liners que respondem perguntas comuns sem ler toda a saída.
4. Obter feedback rápido durante a edição: execute npx hyperframes lint após a primeira passagem HTML e após mudanças estruturais.
5. Executar o portão final: execute npx hyperframes check; ele executa lint novamente antes de abrir o navegador. Não anexe uma invocação redundante de lint. Adicione --snapshots para quadros de visão geral anotados e encontrar cortes.
6. Inspecionar sub-composições: quando index.html monta data-composition-src, capture snapshots de ponto médio e inspecione cada cena montada.
7. Abrir a pré-visualização final do Studio: execute npx hyperframes preview --background, verifique se a URL retorna HTTP 200, entregue a URL do projeto da timeline ao usuário e pergunte se deve revisar ou renderizar. Mantenha ativo até o final da revisão.
8. Renderizar apenas após aprovação: use --quality draft durante iteração, --quality looks para a primeira codificação real (padrão da CLI), e --quality delivery para entrega final.
9. Verificar a saída: confirme se o arquivo existe e não está vazio. Leia a segunda linha do resumo da renderização (beginframe vs screenshot, GPU, tempos de estágio). screenshot + software gpu no Linux é o caminho lento. ffprobe -v error -show_format -show_streams e compare a duração (e fps se o briefing definiu) com o data-duration raiz.

Histórico do projeto na sua vez

Cada escrita no projeto é mantida como uma entrada que pode ser desfeita. Use em apenas dois momentos, nunca a cada passo:

• Início de uma rodada: npx hyperframes history begin --who <seu-nome> --label "<o que você está prestes a fazer>", então npx hyperframes history --since mine --who <seu-nome> para ver o que a pessoa mudou desde sua última rodada. Baseie-se nas edições deles; nunca as sobrescreva.
• Uma verificação falhou, ou a pessoa diz que piorou: npx hyperframes history undo --who <seu-nome> desfaz sua rodada mais recente e deixa as edições da pessoa intactas. Não edite manualmente de volta. Em conflito, sai com código 2 e imprime ambas as escolhas.

Termine cada rodada com npx hyperframes history end, para que suas escritas sejam lidas como suas, não como "Alterado fora do app". Enquanto uma rodada está aberta, cada escrita no projeto conta como sua até 10 minutos sem uma; após isso a rodada termina por si só.

Referências cruzadas obrigatórias de edição do criador

• Antes de criar ou diagnosticar um zoom, punch-in/punch-out, reenquadramento, movimento de câmera ou qualquer movimento de keyframe, leia /hyperframes-keyframes primeiro.
• Antes de hyperframes keyframes, leia /hyperframes-keyframes; o comando revela trajetórias de animação e não diagnostica cortes de clipe.
• Para um corte, aparar, emendar, reordenar ou edição de tempo de origem, leia /hyperframes-core e use seu contrato de clipe/timeline.
• Para fade-in/fade-out, crossfade, ganho de faixa, automação de volume, ducking, esculpir voz over ou FX em áudio colocado, leia /hyperframes-audio. Carregue core junto quando o posicionamento do clipe ou o tempo da imagem também mudarem.
• Uma solicitação nomeando um ativo, som, imagem, voz ou edição visual rápida resolve através de /media-use antes de um plano ser proposto. Copie a marcação de edição do criador de /hyperframes-core → references/creator-editing-recipes.md.

# Verificação rápida de iteração; repita enquanto cria conforme necessário.
npx hyperframes lint

# Portão final obrigatório; inclui lint.
npx hyperframes check
npx hyperframes preview --background
npx hyperframes render --quality looks --output out.mp4
test -s out.mp4
ffprobe -v error -show_format -show_streams out.mp4

check executa lint primeiro, depois usa uma sessão de navegador e uma passagem de busca para auditar erros de runtime, requisições com falha, layout, asserções de *.motion.json e contraste WCAG. Achados persistentes bloqueiam o código de saída; achados transitórios de entrada ou saída são informativos. Use --strict para bloquear avisos. validate, inspect e layout permanecem aliases para compatibilidade, mas não devem aparecer em novas instruções ou scripts.

Pré-visualização antes de renderizar

Abra a pré-visualização da composição final (#project/<nome>) apenas após check passar, para revisar a timeline montada. O plano no chat e a folha de esboço storyboard.html não são aprovação do vídeo final. Renderizar sempre requer a aprovação final definida por hyperframes/references/review-loop.md.

Teste de fumaça de sub-composição

Auditorias estáticas não podem detectar todas as falhas de montagem. Quando o projeto usa sub-composições, capture pelo menos um ponto médio visível para cada slot hospedeiro:

npx hyperframes snapshot --at <t1>,<t2>,<t3>

Trate conteúdo minúsculo não estilizado, ícones do tamanho da tela, elementos hero ausentes ou timeouts de registro de timeline como defeitos de montagem que bloqueiam a renderização. Veja hyperframes-core/references/sub-compositions.md para as correções correspondentes.

Convenções de agente

• Pesquise no catálogo antes de escrever movimento manualmente. npx hyperframes catalog --query "<o movimento, em inglês simples>". A pesquisa é inteiramente local: não há camada hospedada, nenhuma conta, e o texto da consulta nunca é enviado a lugar nenhum. Por padrão, ela classifica com base no vocabulário compartilhado com o nome, título, descrição e tags do item, o que perde qualquer frase que não reutilize o próprio vocabulário do catálogo. Adicione --on-device para classificar por significado (veja o tier offline abaixo).

• Consulte em inglês mesmo quando o vídeo não estiver em inglês. Ambos os tiers indexam um catálogo em inglês, portanto uma consulta em outro script não produz termos pesquisáveis e retorna nada. Descreva o movimento em inglês; o texto na tela permanece no idioma que o vídeo precisar. Nenhuma palavra pesquisável na consulta significa exatamente isso e não é um componente ausente, portanto não o relate como uma lacuna do catálogo.

• Leia qual tier respondeu; nunca infira isso dos resultados aparecerem. Com --json, o envelope carrega query, tier (on-device ou words), tier_detail, dropped, unindexed, shown, total e results, além de top_score quando o tier respondedor produz um, e warnings quando um tier foi solicitado e não pôde executar, ou quando uma pesquisa não retornou nada e um tier melhor ainda está esperando o consentimento de alguém. Um resultado fraco em words é esperado; o mesmo resultado em on-device é um bug. top_score é apenas no dispositivo e não tem um limite por trás: o classificador retorna o catálogo inteiro em alguma ordem para cada consulta, portanto leia como evidência em vez de aprovação ou reprovação.

• dropped e unindexed são distorções opostas entre o registro e o índice no dispositivo, e reformular a consulta não corrige nenhum dos dois. dropped conta nomes classificados que este registro não pode instalar, então as correspondências mais fortes são as que estão sendo perdidas. unindexed conta movimentos do registro que o índice não consegue ver, que nenhuma consulta pode retornar. Atualizar o registro não é a resposta para nenhum dos dois: seu manifesto carrega um TTL de 24h e se cura, enquanto os vetores são um artefato publicado separadamente, baixado para ~/.hyperframes/catalog/. Reexecutar com --on-device reobtém esse índice quando unindexed está acima de zero, portanto esse é o remédio a dar ao usuário. Uma distorção pura de excesso de cobertura (dropped acima de zero enquanto unindexed é zero) não aciona a reobtenção; limpar ~/.hyperframes/catalog/ é a única saída. Ambas as contagens são de nomes em vez de resultados, então qualquer uma pode exceder total.

• Quando uma pesquisa não retorna nada que vale a pena instalar, diga isso. npx hyperframes feedback --search-miss "<a consulta que você executou>" --wanted "<o movimento que você precisava>" --tier <o tier que respondeu>. Você não precisa montar essa linha: catalog --query a imprime pré-preenchida, e todo envelope de pesquisa --json a carrega como report_gap com a consulta e o tier já corretos — preencha --wanted e envie. Este é o único caminho que envia uma consulta a qualquer lugar, e é um comando deliberado separado, precisamente para que catalog --query simples mantenha sua promessa de não enviar nada. Reporte em qualquer tier, sempre que os resultados não fizerem o que é necessário; não espere pelo tier no dispositivo, que precisa de um download consentido de 33 MB e, portanto, está desligado na maioria das execuções de agente — esperar por ele significa nunca reportar. O tier viaja junto no relatório, então um erro de vocabulário permanece distinguível de um erro de significado sem que você precise julgar qual deles acertou. 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 a frase que importa é o efeito que você queria, não o nome do item que imaginou. Ele não carrega classificação e nunca vai para a métrica de classificação.

• Ofereça o tier offline; nunca ative-o silenciosamente. Um download único de ~33 MB (uma construção ONNX quantizada do bge-small-en-v1.5 mais seu tokenizador, fixado a uma revisão fixa) e os vetores do catálogo do registro, ambos armazenados em cache em ~/.hyperframes/, nenhum adicionado ao projeto ou a qualquer pacote. Uma vez em cache, ele classifica por significado sem enviar nada. Diga o tamanho em voz alta e deixe a pessoa decidir, então passe --on-device (com -y para pular o prompt) assim que eles concordarem. A oferta interativa só é acionada em um TTY. Sob --json não há prompt, mas uma pesquisa que não encontrou nada coloca a mesma pergunta em warnings, portanto leia esse array e coloque a decisão para o usuário você mesmo. Quando a pessoa perguntar o que é o download, por que este modelo ou o que sai da máquina, aponte-os para https://hyperframes.heygen.com/developers/catalog-search.

• Prefira --json para chamadas de agente e CI. Modo servidor render, preview e play não fornecem saída JSON comum; preview --selection --json e preview --context --json são exceções de modo consulta.

• doctor --json sempre sai com zero. Baseie-se em seu payload:

  npx hyperframes doctor --json | jq -e '.ok' >/dev/null
  

• O modo não-TTY é automático e estrutura o espaço em branco centralizado. Passe --example apenas para começar a partir de um exemplo nomeado. Use --non-interactive para forçar o modo apenas de flags em um TTY.

• Use um HYPERFRAMES_RUN_ID para todos os comandos no mesmo loop de verificação.

• Quando o disco estiver cheio, execute npx hyperframes clean (--dry-run para listar primeiro); ele remove o que as renderizações mortas deixaram e caches ociosos que se reconstroem, nunca saídas, fontes ou qualquer coisa que uma renderização em execução use. Escreva quadros de QC em um diretório temp, não no projeto.

• Use --strict, --strict-all e --strict-variables quando 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 hospedada se aproxima ou excede o limite de upload de 200 MB, use cloud render --dry-run --json e siga a investigação .hyperframesignore em references/cloud.md. Nunca ignore um ativo meramente por ser grande.

• Nunca renderize meramente porque as verificações passam. Pause na pré-visualização final e aguarde aprovação.

Edições dirigidas 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 executar novamente. Solicite apenas as fatias de contexto que você precisa; use --context-detail full apenas para estilos computados ou metadados de texto editável. Comportamento completo e 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
Primeira codificação real	npx hyperframes render --quality looks --output out.mp4
Entrega local final	npx hyperframes render --quality delivery --output out.mp4
Renderização reprodutível em contêiner	npx hyperframes render --docker --strict --output out.mp4
Renderização em lote local dirigida por variável	npx hyperframes render --batch rows.json --output "renders/{name}.mp4"
Renderização HeyGen hospedada sem infraestrutura	npx hyperframes cloud render
Renderização AWS distribuída autogerenciada	npx hyperframes l

...truncado...