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 mantêm as instruções de atualização abaixo.
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
- Estruturação:
npx hyperframes init <projeto>(blank centralizado). Ou capture um site. Passe--example=<nome>apenas para começar a partir de um exemplo nomeado. - Encontre o movimento: se a solicitação nomear um asset, som, imagem, voz ou edição visual rápida, resolva através de
/media-useantes de propor um plano. Caso contrário, antes de escrever movimento manualmente, pesquise por uma primitiva que já o faça:npx hyperframes catalog --query "revelar um título uma linha por vez". Peça o efeito que você deseja, não o mecanismo que você tem em mente. Instale comnpx hyperframes add <nome>(veja/hyperframes-registry). Escreva manualmente apenas quando nada se encaixar. - Autoria: escreva a composição usando
/hyperframes-core. Para saber o que está na linha do tempo de um projeto (faixas, clipes, inícios, fins, o que toca), executenpx hyperframes timeline --jsonem vez de lerindex.htmle cada arquivo de sub-composição: linhas aninhadas carregamabsStart/absEndabsolutos da linha do tempo principal e seufileproprietário, não apenas seu tempo local por sub-composição. Prefira--jsonem vez do formato texto; custa menos tokens para a mesma ou melhor precisão. Vejareferences/upgrade-info-misc.mdpara comandos de uma linha que respondem perguntas comuns sem ler toda a saída. - Obtenha feedback rápido durante a edição: execute
npx hyperframes lintapós a primeira passada de HTML e após mudanças estruturais. - Execute a verificação final: execute
npx hyperframes check; ela executa lint novamente antes de abrir o navegador. Não adicione uma invocação redundante de lint separada. Adicione--snapshotspara quadros de visão geral anotados e para encontrar cortes. - Inspecione sub-composições: quando
index.htmlmontadata-composition-src, capture snapshots intermediários e inspecione cada cena montada. - Abra a pré-visualização final do Studio: execute
npx hyperframes preview --background, verifique se a URL retorna HTTP 200, forneça a URL do projeto da linha do tempo ao usuário e pergunte se deseja revisar ou renderizar. Mantenha ativo até que a revisão termine. - Renderize apenas após aprovação: use
--quality draftdurante iterações,--quality lookspara a primeira codificação real (padrão da CLI) e--quality deliverypara entrega final. - Entregue o projeto ao aplicativo desktop (quando oferecido): quando a linha Framey da renderização terminar em
hyperframes open …, ofereçanpx hyperframes open [dir]. Isso abre o projeto no aplicativo desktop HyperFrames e o adiciona à Home; sob Claude Code ou Codex, o chat desta conversa é retomado. Sem o aplicativo, ele sai com código 1 e imprime o link de download.--jsonpara agentes. - Verifique a saída: confirme se o arquivo existe e não está vazio. Leia a segunda linha do resumo da renderização (
beginframevsscreenshot, GPU, tempos de estágio).screenshot+software gpuno Linux é o caminho lento.ffprobe -v error -show_format -show_streamse compare a duração (e fps se o resumo definiu) com a raizdata-duration.
Histórico do projeto no seu turno
Cada escrita no projeto é mantida como uma entrada que pode ser desfeita. Use-a apenas em dois momentos, nunca em cada etapa:
- Início de um turno:
npx hyperframes history begin --who <seu-nome> --label "<o que você está prestes a fazer>", entãonpx hyperframes history --since mine --who <seu-nome>para ver o que a pessoa mudou desde seu último turno. Baseie-se nas edições deles; nunca as sobrescreva. - Uma verificação falhou, ou a pessoa disse que piorou:
npx hyperframes history undo --who <seu-nome>desfaz seu turno 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 opções.
Termine cada turno com npx hyperframes history end, para que suas escritas sejam lidas como suas, não como "Alterado fora do aplicativo". Enquanto um turno estiver aberto, cada escrita no projeto conta como sua até que 10 minutos passem sem uma; após isso, o turno termina por conta própria.
Referências cruzadas obrigatórias de criador-edição
- Antes de criar ou diagnosticar um zoom, aproximação/afastamento, reenquadramento, movimento de câmera ou qualquer movimento de keyframe, leia
/hyperframes-keyframesprimeiro. - Antes de
hyperframes keyframes, leia/hyperframes-keyframes; o comando exibe trajetórias de animação e não diagnostica cortes de clipe. - Para um corte, corte, emenda, reordenação ou edição de tempo de origem, leia
/hyperframes-coree use seu contrato de clipe/linha do tempo. - Para fade-in/fade-out, crossfade, ganho de faixa, automação de volume, ducking, esculpir narração ou FX em áudio colocado, leia
/hyperframes-audio. Carregue o core junto quando o posicionamento do clipe ou o tempo da imagem também mudar. - Uma solicitação que nomeia um asset, som, imagem, voz ou edição visual rápida é resolvida através de
/media-useantes que um plano seja proposto. Copie a marcação de edição do criador de/hyperframes-core→references/creator-editing-recipes.md.
# Verificação de iteração rápida; repita durante a autoria 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 tempo de execução, solicitações falhas, layout, asserções *.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 como aliases para compatibilidade, mas não devem aparecer em novas instruções ou scripts.
Pré-visualização antes da renderização
Abra a pré-visualização da composição final (#project/<nome>) apenas após check passar, para revisar a linha do tempo montada. O plano no chat e a folha de esboço storyboard.html não são aprovação do vídeo final. A renderização 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 pegar 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 pequeno não estilizado, ícones do tamanho da tela, elementos de herói ausentes ou timeouts de registro na linha do tempo 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 o catálogo antes de escrever movimento manualmente.
npx hyperframes catalog --query "<o batimento, em inglês simples>". A pesquisa é totalmente local: não há camada hospedada, nenhuma conta e o texto da consulta nunca é enviado a lugar nenhum. Por padrão, ela classifica por vocabulário compartilhado com o nome, título, descrição e tags do item, o que perde qualquer frase que não reutilize a própria redação do catálogo. Adicione--on-devicepara classificar por significado (veja a camada offline abaixo). -
Consulte em inglês mesmo quando o vídeo não estiver em inglês. Ambas as camadas indexam um catálogo em inglês, então uma consulta em outro script não produz termos pesquisáveis e retorna nada. Descreva o movimento em inglês; a cópia na tela permanece no idioma que o vídeo precisar.
Nenhuma palavra pesquisável na consultasignifica exatamente isso e não é um componente ausente, então não o relate como uma lacuna do catálogo. -
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, além detop_scorequando a camada respondedora produz um ewarningsquando uma camada foi solicitada e não pôde ser executada, ou quando uma pesquisa não retornou nada e uma camada melhor ainda está esperando o consentimento de alguém. Um resultado fraco emwordsé esperado; o mesmo resultado emon-deviceé um bug.top_scoreé apenas on-device e não tem limite por trás dele: o ranqueador retorna o catálogo inteiro em alguma ordem para cada consulta, então leia-o como evidência, não como aprovação ou reprovação. -
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 ranqueados que este registro não pode instalar, então as correspondências mais fortes são as que estão sendo perdidas.unindexedconta movimentos do registro que o índice não pode ver, que nenhuma consulta jamais pode retornar. Atualizar o registro não é a resposta para nenhum dos dois: seu manifesto carrega um TTL de 24h e se auto-repara, enquanto os vetores são um artefato publicado separadamente e buscado em~/.hyperframes/catalog/. Re-executar com--on-devicereobtém esse índice quandounindexedestá acima de zero, então esse é o remédio a oferecer ao usuário. Uma distorção pura de excesso de cobertura (droppedacima de zero enquantounindexedé zero) não aciona a reobtenção; limpar~/.hyperframes/catalog/é a única saída para essa. Ambas as contagens são de nomes, não de resultados, então qualquer uma pode excedertotal. -
Quando uma pesquisa retornar 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 <a camada que respondeu>. Você não precisa montar essa linha:catalog --querya imprime pré-preenchida, e todo envelope de pesquisa--jsona carrega comoreport_gapcom a consulta e a camada já corretas — preencha--wantede envie. 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 em qualquer camada, sempre que os resultados não fizerem o que você precisa; não espere pela camada on-device, que precisa de um download consentido de 33 MB e, portanto, está desligada na maioria das execuções de agente — esperar por ela significa nunca reportar. A camada vem 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 ocorreu. O que retorna é uma lista de movimentos que o catálogo ainda não tem, lida diretamente em vez de adivinhada a partir de contagens de instalação, então a redação 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 construção ONNX quantizada do
bge-small-en-v1.5mais seu tokenizador, fixado em uma revisão específica) 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, 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ó dispara em um TTY. Sob--jsonnão há prompt, mas uma pesquisa que não encontrou nada coloca a mesma pergunta emwarnings, então 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 para https://hyperframes.heygen.com/developers/catalog-search. -
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 consulta. -
doctor --jsonsempre sai com zero. Verifique sua carga:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
O modo não-TTY é automático e estrutura o blank centralizado. Passe
--exampleapenas para começar a partir de um exemplo nomeado. Use--non-interactivepara forçar o modo apenas de flags em um TTY. -
Use um
HYPERFRAMES_RUN_IDpara todos os comandos no mesmo loop de verificação. -
Quando o disco estiver cheio, execute
npx hyperframes clean(--dry-runpara listar primeiro); ele remove o que renderizações mortas deixaram e caches ociosos que se reconstroem sozinhos, nunca saídas, fontes ou qualquer coisa que uma renderização em execução use. Escreva quadros de controle de qualidade em um diretório temporário, não no projeto. -
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 hospedada 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 asset meramente porque é 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 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 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 que você 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 |
| 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 de container reproduzível | npx hyperframes render --quality delivery --output out.mp4 --container docker |
| Renderização na nuvem HeyGen | npx hyperframes cloud render --quality delivery --output out.mp4 |
| Renderização AWS Lambda | npx hyperframes lambda render --quality delivery --output out.mp4 |
| Renderização Google Cloud Run | npx hyperframes cloudrun render --quality delivery --output out.mp4 |
Diagnóstico e manutenção
| Comando | Descrição |
|---|---|
npx hyperframes doctor | Verifica instalação, dependências e permissões |
npx hyperframes info | Exibe informações do projeto e versão da CLI |
npx hyperframes browser | Abre o projeto em um navegador |
npx hyperframes clean | Remove caches e artefatos de renderização mortos |
npx hyperframes upgrade | Atualiza a CLI e componentes |
Referências adicionais
- Instalação de plugins
- Catálogo de primitivas
- Core de HyperFrames
- Keyframes
- Áudio
- Uso de mídia
- Cloud
- Pré-visualização e renderização
- Loop de revisão
- Sub-composições
- Edições de criador
- Informações diversas de atualização
Notas finais
- A CLI HyperFrames é uma ferramenta em evolução; consulte a documentação oficial para as versões mais recentes.
- Para suporte, entre em contato com a equipe HyperFrames ou consulte o repositório oficial.
- Contribuições são bem-vindas; veja o guia de contribuição no repositório.
Documentação gerada para o assistente Skill.