wangjs-jacky/jacky-skills

HyperFrames Ops

Antes de responder perguntas relacionadas ao ambiente, leia primeiro o arquivo experience.local.md no mesmo diretório para obter os fatos mais recentes desta máquina (comandos de proxy, snapshots de versão, Q&A histórico).

Zero: Por que uma camada Ops independente

Skills de terceiros geralmente descrevem apenas capacidades genéricas, sem prever as condições específicas de cada máquina: rede, proxy, versão do Node/FFmpeg, cache de fontes, estado de login e combinações de ferramentas. Modificar diretamente um skill oficial causaria conflitos de atualização e misturaria fatos locais com a documentação upstream genérica.

Portanto, as duas camadas são separadas:

• Skills oficiais são a fonte de capacidade: mantêm-se atualizáveis e substituíveis.
• hyperframes-ops é a camada de adaptação local: registra melhores práticas, diferenças de compatibilidade, modos de falha e soluções validadas.
• Problemas de criação: consulte primeiro o skill oficial. Problemas de ambiente, combinação, versão ou adaptação local: consulte este skill.
• Quando uma atualização upstream torna uma experiência antiga inválida, marque-a como obsoleta no registro local e revalide, sem usar a experiência antiga para sobrescrever o novo comportamento.

Um: Identidade do projeto (fatos generalizados)

• HyperFrames é um projeto oficial da HeyGen de código aberto: github.com/heygen-com/hyperframes, pacote npm hyperframes
• Proposta: escrever composições de vídeo em HTML, renderizá-las para mp4 via headless Chrome com CLI (npx hyperframes)
• Requisitos: Node.js >= 22, FFmpeg

Dois: Mecanismo de distribuição de skills oficiais

• Os skills oficiais são mantidos e versionados juntamente com a CLI, com manifesto na raiz do repositório: https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills-manifest.json
• Composição: conjunto core (hyperframes / hyperframes-core / hyperframes-cli / hyperframes-animation / hyperframes-keyframes / hyperframes-creative / hyperframes-registry / remotion-to-hyperframes) + conjunto de workflows (general-video, slideshow, motion-graphics, music-to-video, pr-to-video, product-launch-video, website-to-video, faceless-explainer, talking-head-recut, embedded-captions, media-use, figma). Consulte a saída real de skills check.
• Comandos de gerenciamento:
  • npx hyperframes skills check — verifica versões em relação ao manifesto
  • npx hyperframes skills update — atualiza todos os instalados + limpa skills que foram removidos do repositório oficial
  • npx hyperframes init — força a sincronização dos skills para a versão mais recente (a opção --skip-skills está atualmente desabilitada oficialmente)
• Local de instalação: global ~/.claude/skills/ (CLI detecta automaticamente o claude-code)
• Segurança de nomenclatura: A lógica de limpeza do skills update baseia-se no arquivo de lock para determinar a "origem" do skill, deletando apenas skills que pertencem ao repositório oficial e foram removidos. Este skill, embora comece com hyperframes-, não está na lista de locks oficiais, portanto não será acidentalmente deletado pelo atualizador oficial.

Três: Roteiro de solução de problemas

Sintoma	Roteiro
skills check/update/init lança AbortError (timeout do fetchManifest)	Problema de rede: a CLI usa o fetch nativo do Node para acessar raw.githubusercontent.com. Se a conexão direta falhar, é necessário usar proxy. Leia experience.local.md para obter o comando direto para esta máquina.
Outras falhas de rede do npx hyperframes	Igual acima; note que o fetch nativo do Node (undici) não lê a variável de ambiente HTTP_PROXY por padrão. No Node 24+, é necessário adicionar NODE_USE_ENV_PROXY=1 (ou --use-env-proxy).
Ambiente de renderização/preview anormal	Execute npx hyperframes doctor, npx hyperframes browser para autoverificação; confirme Node >= 22 e FFmpeg disponíveis.
Comportamento do skill parece desatualizado	Verifique a diferença de versão com skills check e sincronize com skills update.
Falha na troca de token OAuth do heygen auth login --oauth (connection refused para api2.heygen.com) ou timeout na chamada da biblioteca de músicas	O CLI heygen é um programa Go, que lê as variáveis de ambiente HTTP(S)_PROXY (ao contrário do fetch do Node, sem necessidade de chave extra). Em redes restritas, todos os comandos heygen precisam de proxy. O serviço de callback OAuth só vive 5 minutos e requer um shell interativo (iniciar em background/nohup causará timeout por não receber o callback). Comandos para esta máquina estão em experience.local.md.
Fonte renderizada incorreta (título fica mais largo, estoura o contêiner, mas lint/inspect está verde)	As 18 fontes embutidas são baixadas sob demanda em tempo de execução (via @fontsource → ~/.cache/hyperframes/fonts). Se o download falhar, ocorre fallback silencioso para a fonte do sistema. Solução para redes restritas: baixar os woff2 para o projeto e hospedar explicitamente com @font-face.
Perguntas criativas (como fazer composição, animação, parâmetros de renderização)	Não são escopo deste skill; consulte a tabela de roteamento do skill oficial hyperframes.

Quatro: Protocolo de registro de experiências

• Escrever em experience.local.md (privado da máquina, ignorado pelo .gitignore deste diretório): novos problemas encontrados e soluções validadas, snapshots de versão/estado de instalação (com data), comandos exclusivos da máquina, fatos de proxy e rede, Q&A histórico.
• Escrever de volta neste SKILL.md (versionado no git, compartilhável): mudanças no mecanismo oficial (forma de distribuição, semântica de comandos, lógica de limpeza), novas rotas de solução de problemas generalizadas.
• Critério de decisão: se a informação é válida para qualquer máquina → SKILL.md; se é válida apenas para esta máquina → experience.local.md.
• Toda vez que for chamado para resolver um problema de ambiente HyperFrames e a solução for encontrada, registre a conclusão conforme a divisão acima, com a data.