/video-setup
Obtenha o workbench a partir de um clone limpo até passed N, failed 0 em uma única etapa. O setup.sh faz o trabalho; sua função é explicar, obter um sim, executá-lo e transformar cada linha FAIL em sua correção.
Primeiro, encontre o workbench (funciona a partir do workbench e de uma pasta de produto):
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
Fale com o usuário no idioma dele. Seja breve: eles querem uma configuração funcional, não um tour.
Com o argumento check
Execute bash "$PVS_HOME/setup.sh" --check e mostre o resultado. Não instala nada, não baixa nada e não escreve nada. Para cada linha FAIL, forneça a correção (a linha termina com ela). Pare por aí.
Caso contrário
1. Relate a máquina
Execute bash "$PVS_HOME/setup.sh" --check primeiro. Ele imprime uma linha por item: ok, warn ou FAIL com a correção exata.
- Se alguma linha sob Máquina falhar (node 22+, python 3.9+, ffmpeg, git), a configuração não pode continuar.
Forneça ao usuário a correção da linha (por exemplo
brew install ffmpeg) e peça para executá-la no terminal dele, depois execute a verificação novamente. A instalação de pacotes do sistema é responsabilidade do usuário, portanto não executebrewouaptvocê mesmo, a menos que ele solicite. - Um
warnno Claude Code é informativo. - As linhas FAIL sob Toolchain são o que a configuração instala. Isso é esperado na primeira execução.
2. Diga o que será baixado e pergunte uma vez
Informe ao usuário, em uma lista curta, apenas os itens que a verificação relatou como ausentes:
| Item | Tamanho | Onde |
|---|---|---|
| CLI HyperFrames na versão fixada, com suas dependências | cerca de 128 MB | node_modules/ |
| A compilação do Chrome com a qual o HyperFrames renderiza | cerca de 195 MB (ignorado se em cache) | cache do HyperFrames |
| Skills de agente HyperFrames da mesma tag de versão | alguns MB | vendor/hyperframes/skills/ |
| Pacotes Python, principalmente torch para fala para texto | cerca de 339 MB | .venv/ |
O modelo de fala whisper small.en que o QA usa | 484 MB | ~/.cache/whisper/ |
Faça uma pergunta fechada: "Instalar estes agora? (sim / não)". A configuração deve acontecer em uma única etapa
no primeiro /video-setup, portanto não divida em várias confirmações.
3. Execute
Se sim, execute bash "$PVS_HOME/setup.sh" --yes (o --yes é a resposta do usuário, já fornecida).
Leva alguns minutos na primeira execução e segundos quando tudo está em cache; use um tempo limite de pelo menos
10 minutos. É idempotente: executá-lo novamente refaz apenas o que está faltando.
4. Lide com cada FAIL
Cada linha FAIL nomeia sua correção. As comuns:
| FAIL | O que fazer |
|---|---|
npm install failed | Problema de rede ou registro. Mostre as últimas linhas do log que ele nomeia e execute a configuração novamente |
hyperframes browser ensure failed | Execute npx hyperframes browser ensure --force a partir do workbench e execute a configuração novamente |
could not clone heygen-com/hyperframes | Problema de rede ou acesso ao GitHub. Verifique git ls-remote https://github.com/heygen-com/hyperframes e execute a configuração novamente |
python3 -m venv failed | No Debian ou Ubuntu: sudo apt install python3-venv (o usuário executa) |
pip install -r requirements.txt failed | Mostre o final do log. Um Python mais novo que as versões fixadas pode precisar de uma wheel mais recente; reporte isso em vez de editar as versões |
hyperframes doctor: ... | A linha nomeia a verificação com falha e sua correção. Versão, Docker e as verificações opcionais de voz local e música são ignoradas propositalmente |
tests/run.sh: passed N, failed M | Execute bash "$PVS_HOME/tests/run.sh" e mostre os testes com falha e suas saídas |
Nunca "corrija" um FAIL executando hyperframes upgrade ou hyperframes skills update. O workbench
fixa uma versão do HyperFrames e obtém suas skills da mesma tag, porque uma CLI e skills
de versões diferentes discordam sobre o contrato de composição. Uma mudança de versão é um pull request
que passa em tests/run.sh. O hook de guarda bloqueia ambos os comandos de qualquer forma.
5. A chave de voz
A configuração cria .env a partir de .env.example e informa se a chave ElevenLabs está definida,
sem imprimi-la. Se estiver vazia, informe ao usuário:
- Abra
.env(na pasta do workbench) no próprio editor do usuário e cole a chave apósELEVENLABS_API_KEY=. Nunca no chat: qualquer coisa no chat é armazenada no histórico. Se ele colar aqui de qualquer forma, diga para rotacioná-la. - Sem uma chave,
voice.provider: saynoproduct.yamlde um produto usa as vozes gratuitas do macOS, boas o suficiente para rascunhos e testes.
Nunca abra, leia ou imprima .env você mesmo. As configurações negam isso e o hook de guarda bloqueia, e
os scripts carregam a chave através de lib/pvs.py por conta própria.
6. Encerramento
Confirme que as últimas linhas da saída dizem passed N, failed 0 e Setup done. Em seguida, forneça
o próximo passo em uma linha: /product-new <slug> para trazer o produto dele, ou /video-ask para ver
como estão as coisas.