Auto-Tutorial-Studio (Estúdio de Tutoriais Automatizados)
Dado um endereço de site ou nome de software, e um esboço da sequência de capítulos, esta skill é responsável por:
Executar operações reais → Notificar o usuário para gravar → Importar o material capturado → Criar um índice pesquisável → Editar com correspondência frase a frase → Adicionar efeitos e transições → Verificar quadro a quadro → Exportar o vídeo final
Divisão: O que a skill faz e o que o usuário faz
| Quem faz | Descrição | |
|---|---|---|
| Gravar a tela | Usuário | O usuário grava com OBS / ShareX / ferramenta de gravação de sistema. A skill não grava a tela. A gravação externa preserva a resolução e nitidez originais, permitindo também capturar o som do sistema. |
| Executar as operações reais | Skill | A skill executa cada passo usando automação de navegador (CDP) ou automação de janelas, e registra as localizações dos cliques. |
| Edição, narração, efeitos, verificação | Skill | Tudo automatizado, com portões de validação. |
| Importar material | Usuário | Após as operações, o usuário fornece o caminho do vídeo gravado para a skill. |
A skill não ocupa o mouse físico do usuário: as operações no navegador usam CDP para clicar em elementos, sem mover o ponteiro real.
Sete Regras de Ouro
- A captura é de responsabilidade do usuário; a skill não grava a tela. A skill apenas executa as operações e faz a pós-produção. O usuário deve entregar o arquivo gravado à skill.
- As operações são da skill; a janela de gravação é do usuário. A skill só executa as ações depois que o usuário declara "iniciar gravação", e imediatamente notifica o usuário para parar de gravar quando as operações terminam.
- Durante a gravação, nenhum console pode aparecer na tela. Cada comando executado pela skill deve ser sem janela, e o
guarddeve ativar para ocultar imediatamente qualquer console ou pop-up que surgir – eles serão capturados. - Oculte a janela, não a feche. Use
SW_HIDEe useguard stoppara restaurar tudo de uma vez. - Cada cena deve estar vinculada a uma frase da narração. No
plan.json, cada batida declara a qual frase da narração ela serve. A duração total do capítulo deve ser igual à duração total da narração daquele capítulo. - Números ditados devem ser lidos diretamente da interface real. Contagem de vértices, preços, números de versão – sempre com base na interface exibida.
- A auditoria de oclusão é um portão, não um relatório. Antes da construção, o OCR quadro a quadro varre a janela de saída; se encontrar console / notificação / tela inicial, rejeita a saída. A música de fundo deve dar lugar à voz; o vídeo final deve ter -16 LUFS e pico verdadeiro ≤ -1,5 dBFS.
Fase 0 · Iniciação do Projeto
Confirme três itens obrigatórios:
- Alvo: endereço do site ou nome e versão do software de desktop.
- Roteiro: sequência de capítulos (o usuário fornece um esboço, a skill detalha).
- Plano de gravação: qual ferramenta de gravação de tela o usuário usará, qual monitor será gravado, se o som do sistema será capturado, formato de saída e resolução.
Determine também o escopo da captura (tela inteira ou uma janela específica) e se a gravação será em segmentos. Gravações separadas por funcionalidade são mais fáceis de manter; uma gravação contínua de todo o fluxo também funciona, contanto que a indexação localize corretamente as partes.
Fase 1 · Roteiro
build/script.md, cada capítulo com um cabeçalho ## no formato ## <ID do capítulo> | <Título exibido>:
## ch00 | Abertura
Veja primeiro o que eu fiz.
Este boneco foi gerado a partir de uma imagem.
## ch01 | Cadastro e Login
O site oficial é hi3d.ai, abra no navegador e use.
- ID do capítulo: apenas letras minúsculas, números, sublinhados e hífens (exigido pela lista de TTS). Deve corresponder exatamente ao
iddo capítulo noplan.json. Múltiplos segmentos do mesmo capítulo são automaticamente nomeadosch01,ch01_1,ch01_2. - Título exibido: usado para os cards de capítulo, pode ser em português.
- IDs de capítulo não devem ser prefixos entre si (
ch0ech01podem causar conflitos). Recomenda-se usarchNN. - Comece mostrando o resultado (a imagem mais reconhecível) e depois volte para a operação.
- Funcionalidades marginais devem ser descritas em poucas palavras; o foco deve estar nos "parâmetros que determinam o resultado" e em "como verificar se está correto".
- Prompts, códigos e configurações devem ser salvos em blocos de código com ``` – blocos de código não serão lidos, apenas exibidos como imagem.
- Cada parágrafo da narração deve ter uma cena real correspondente; parágrafos sem cena devem ser reescritos para usar uma cena que prove o ponto.
Fase 2 · Narração (TTS)
python scripts/studio.py voice --project <projeto>
Segmenta por ## <ID do capítulo> | <Título>, quebra em parágrafos por linha em branco, pula blocos de código e anotações >, e gera build/audio_map.json, com a duração real medida de cada segmento.
Verifique a saída chars/s: segmentos abaixo de 3,0 indicam anomalia no TTS (uma síntese mais longa). Refaça a narração e gere novamente, sem prosseguir com esses segmentos para a edição.
Fase 3 · Execução Real e Gravação Externa ★
Esta é a fase central da skill.
3.1 Preparar o Ambiente de Gravação
python scripts/studio.py windows # Encontrar a janela alvo
python scripts/studio.py prep --project <projeto> \
--keep-title "Chrome" --maximize-title "Chrome" # Ocultar janelas irrelevantes, maximizar a alvo
prep nunca oculta o próprio terminal da skill (exclui por PID ancestral).
3.2 Iniciar o Guardião de Tela ★
Este passo não pode ser pulado. Durante a execução das operações, a skill invocará comandos (ffmpeg, ffprobe, subprocessos Python), cada um dos quais pode abrir uma janela de console que cai exatamente sobre a área de captura do usuário e será gravada.
python scripts/studio.py guard start --project <projeto> \
--protect "DeepSeek Harness" --protect "Chrome"
O guardião é um processo de fundo independente que verifica a lista de janelas a cada 0,25 segundos e imediatamente oculta (SW_HIDE) qualquer janela de console que aparecer (ConsoleWindowClass, cmd, PowerShell, terminal, xshell, etc.) e pop-ups de método de entrada / notificação. Ele lembra quais janelas ocultou e as restaura com guard stop.
--protectprotege os programas que estão sendo demonstrados (correspondência por título, obrigatório).- Por padrão, oculta apenas janelas de console da própria árvore de processos da skill, não janelas GUI – a interface do usuário permanece visível.
- Se for necessário ocultar também a GUI da skill, adicione
--hide-own-gui. - O guardião usa critérios de sobreposição real: janelas que tocam apenas alguns pixels da área de captura (em outro monitor) não são ocultadas indevidamente.
3.3 Notificar o Usuário para Iniciar a Gravação
Instrua claramente o usuário: Por favor, inicie a gravação. Quando terminar, responda "Gravei". Não execute nenhuma ação antes da confirmação do usuário – caso contrário, essa preparação será gravada.
3.4 Executar as Operações Reais
Execute as operações na ordem dos capítulos. A cada passo:
- Navegador: use CDP para clicar em elementos, sem mover o mouse real.
Antes do clique, registre as coordenadas para anotações posteriores:
python scripts/studio.py aim <projeto> <x> <y> --note "Formato de exportação". - Software desktop: ative a janela + use teclado como prioridade; se precisar de cliques com mouse real, avise o usuário para não mexer no mouse durante a gravação.
- Se precisar confirmar o estado, não interrompa o usuário: capture um quadro e verifique rapidamente:
python scripts/studio.py shot --out <projeto>/build/check.png
- Login, autorização, captcha: mantenha a gravação, deixe o usuário fazer manualmente. A skill apenas confirma se foi bem-sucedido. Corte as credenciais, captchas e chaves – pode-se gravar em segmentos separados antes e depois do login, e depois juntar na ordem de dependência.
- Cada comando da skill deve ser executado sem janela:
scripts/h.ps1inicia subprocessos comCreateNoWindow, e subprocessos internos da skill sempre usamCREATE_NO_WINDOW.
3.5 Notificar o Usuário para Parar a Gravação
Assim que todas as operações forem concluídas, avise o usuário imediatamente: Operações concluídas. Pare a gravação e me forneça o caminho do arquivo de vídeo. Aguarde o usuário retornar o caminho. Não procure ou exclua nenhum arquivo de gravação.
3.6 Finalização
python scripts/studio.py guard stop --project <projeto> # Parar o guardião e restaurar janelas
python scripts/studio.py guard status --project <projeto> # Confirmar que não há console residual na área de captura
guard status lista todas as janelas do tipo console ainda visíveis na área de captura – deve estar vazio para ser considerado limpo.
Se houver resíduos, significa que algum programa está abrindo janelas repetidamente. Peça ao usuário para regravar aquele segmento.
Fase 4 · Importar Material e Criar Índice
python scripts/studio.py import --project <projeto> --file "D:\video\rec.mp4"
python scripts/studio.py index --project <projeto> --clip rec.mp4 --step 2
index varre todo o vídeo com um passo fixo, aplica OCR quadro a quadro e registra:
- Que texto está na tela em cada momento (para consultar o que está acontecendo em um segundo específico);
- Pontos de mudança visual (cortes naturais);
- Intervalos de poluição (console / balão de notificação / tela inicial, a serem evitados).
Gera build/index_<nome>.txt (pesquisável) e .json (estruturado).
Leia o índice antes de planejar as cenas – não adivinhe os timecodes.
Fase 5 · Planejamento de Cenas
build/plan.json:
{
"display": {"region": [0, 0, 1920, 1080]},
"voice": {"voice": "pt-BR-FranciscaNeural", "rate": "+8%"},
"chapters": [
{
"id": "ch02", "num": "02", "title": "Imagem para Texto", "sub": "Indicador de três partes determina a fidelidade",
"beats": [
{"seg": 0, "src": "rec.mp4", "in": 120, "out": 134},
{"seg": 1, "src": "rec.mp4", "in": 136, "out": 152, "zoom": 1.0}
],
"callouts": [
{"seg": 1, "offset": 1.0, "text": "Indicador em três partes\nPersonagem → Material → Composição",
"x": 120, "y": 680, "pointer": "up"}
]
}
]
}
srcé o nome do arquivo emraw/(importado pelo usuário),in/outsão em segundos.segé o índice da frase da narração que esta cena atende, contado dentro do capítulo, começando em 0.zoom> 1 faz aproximação (corte estático ampliado).calloutsusamseg+offsetpara posicionar no momento da anotação, sincronizado com a narração;x/ysão a posição da anotação (podem ser coordenadas registradas poraim).- O
iddo capítulo deve ser igual ao ID do capítulo noscript.mde também ao prefixo do segmento noaudio_map.json. - Exemplo completo em
assets/plan.example.json.
Regras para planejamento de cenas:
- Uma cena serve a um ponto específico da operação; a duração da cena é determinada pela frase da narração.
- O nome do elemento deve aparecer antes ou simultaneamente ao destaque; feedbacks importantes devem dar tempo de leitura.
- Elementos próximos devem, sempre que possível, ser capturados em um mesmo enquadramento, evitando cortes frequentes.
- Comprima esperas reais de forma razoável, mas mantenha o tempo reconhecível de "ação → feedback".
- Segmentos sem cena devem ser reescritos para usar cenas que provem o ponto, ou então complementados com nova gravação.
- Evite os intervalos de poluição identificados no índice.
Fase 6 · Edição, Verificação e Entrega
python scripts/studio.py build --project <projeto>
python scripts/studio.py verify --video <projeto>/final.mp4 --expect-duration <duração total da narração>
build faz tudo automaticamente: cortar quadro a quadro com correspondência de narração → cards de título de capítulo → sobreposição de anotações → árvore de transições crossfade → ducking da música de fundo → normalização de loudness.
Música de fundo: Coloque o arquivo de música em build/bgm.wav (ou build/bgm_final.wav). O construtor calcula a curva de ducking com base no envelope da voz e mistura a música. Sem esse arquivo, o vídeo será produzido sem música de fundo.
Quando a auditoria falhar: Consulte os timecodes em build/audit.txt, substitua a janela ou regrave, ajuste o plan.json e execute novamente. A abordagem comum é mover os in/out contaminados para intervalos limpos, ou pedir ao usuário para regravar aquele segmento.
Auto-verificação antes da entrega:
- O arquivo deve ser reproduzível integralmente, com trilhas de vídeo e áudio completas, e duração próxima à duração total da narração.
- Auditoria OCR quadro a quadro sem nenhum problema.
- Assista e ouça o vídeo completo em velocidade normal, com foco nos primeiros 3–10 segundos, em cada transição de funcionalidade, na submissão e nos resultados, em números e nomes próprios, em segmentos de espera e no final.
- Cada ponto explicado deve ter um cursor correspondente na tela; sem longos trechos de estática, sem pausas sem conteúdo, música de fundo não deve abafar a voz.
Comandos Rápidos
studio init <projeto> # Criar estrutura do projeto
studio windows # Listar janelas, localizar alvo
studio prep --project <projeto> --maximize-title "Chrome"
studio guard start --project <projeto> --protect "Chrome" # ★ Manter tela de captura limpa durante gravação
studio shot --out check.png # Capturar um quadro para verificar estado
studio aim --project <projeto> 1001 720 --note "Formato de exportação"
studio guard stop --project <projeto> # Parar guardião e restaurar janelas
studio guard status --project <projeto> # Confirmar que não há console residual
studio import --project <projeto> --file rec.mp4
studio index --project <projeto> --clip rec.mp4
studio voice --project <projeto>
studio build --project <projeto>
studio audit --project <projeto>
studio verify --video final.mp4
studio status --project <projeto>
Referências
references/production.md— Detalhes de gravação, narração, edição, mixagem e aceitaçãoreferences/troubleshooting.md— Sintomas → Causa raiz → Soluçãoassets/plan.example.json— Exemplo completo de plano de cenas