chengfeng-videocut-skills

Editar Narração

De um vídeo até um livro de cortes (Cuts + EDL) revisado por humano, sem mexer nos arquivos de mídia. Sete etapas em sequência:

0  Pronto     Verificação de atualizações (esta skill não tem lógica de ambiente)
1  Projeto    Vídeo real → transcrição palavra por palavra na nuvem → criar projeto no produto → iniciar serviço → ler estado de volta
2  Corrigir   Dicionário corrige caracteres (um geral + um do usuário) → gera tabela de correção
3  Cortar     Ler preferências e regras → cinco rodadas de varredura, cada rodada apenas um tipo, só registra linhas
4  Consolidar Tabela de resumo de cortes + tabela de frases repetidas → auto-verificação lendo a tabela
5  Revisar    Submeter tudo → apresentar duas tabelas ao usuário → abrir o Studio para revisão manual
6  Retrospectiva Comparar proposta com versão final → arquivar em três gavetas → relatar quatro coisas

Não corta mídia: alterar o livro de cortes leva dezenas de milissegundos; cortar é um arquivo irreversível. No final desta skill, não há nenhum novo vídeo no disco. A skill faz julgamentos semânticos e orquestração; o Runtime do produto é o único gravador de projetos, Cuts e estado do Studio.

O usuário fala apenas em três momentos: escolher continuar ou recomeçar no mesmo projeto (apenas quando já cortado), revisão no Studio, confirmação final. Todo o resto é comunicação unidirecional, sem parar para resposta. O critério de conclusão de cada etapa é sua saída: sem tabela, não está concluída.

Primeiro, leia e execute o contrato de fases da skill de negócio. A correspondência entre as etapas deste documento e as fases do contrato: 1=preflight+Product state readback, 5=proposal+Product CAS, revisão=project-level review binding. As três fases finais do contrato (confirmação, execução, aceitação) pertencem à skill de exportação.

O histórico de incidentes de cada regra está no livro de acidentes—as regras estão aqui, a história lá.

0. Pronto

Primeiro, execute a verificação de atualizações—se as skills estão atualizadas, se o Runtime é compatível; a raiz do plugin também é localizada lá (os <raiz-do-plugin> nos comandos deste documento substituem por esse caminho literal). Só continue com "pronto"; "precisa de nova sessão" ou "parar" seguem suas próprias instruções (incluindo a proibição de "criar interface substituta própria").

Se o resultado de prontidão for runtime.kind=desktop-managed, ele compartilha o mesmo ponto de entrada estável e serviço launchd/windows-task com a instalação CLI; continue diretamente; não procure diretórios de instalação do Electron, instale Bun/FFmpeg, ou inicie um segundo Runtime.

1. Projeto: Entrada real → Transcrição → Criar projeto no produto

O que faz: entrega o vídeo local real do usuário e a transcrição palavra por palavra da nuvem ao produto, cria o projeto atomicamente, inicia o serviço, lê o estado de volta.

# Após a transcrição palavra por palavra na nuvem (gerando candidatos a transcrição no diretório de tarefas):
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" project create "<diretório-do-projeto>" --video "<arquivo-de-vídeo-no-diretório-da-tarefa>" --transcript "<transcrição-palavra-por-palavra-no-diretório-da-tarefa>" --json

node "<raiz-do-plugin>/scripts/ensure-running.cjs" --json          # O produto garante declarativamente o serviço residente (5190)

node "<raiz-do-plugin>/scripts/videocut-cli.cjs" workflow get "<diretório-do-projeto>" --json    # Leitura de estado do produto
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" cuts get "<diretório-do-projeto>" --json

Regras:

• Aceita apenas vídeos de narração reais fornecidos pelo usuário ou projetos reais existentes; sem mídia real, pare, proibido usar exemplos, vídeos placeholder
• A transcrição usa apenas o ASR na nuvem autorizado para o ambiente atual; proibido recorrer a ASR local; se não houver ASR na nuvem disponível, reporte missing_cloud_transcription_adapter, não abra o Studio, não invente transcrição
• --video / --transcript devem ser arquivos reais dentro do diretório de tarefas; não passe relação de aspecto—o produto a deduz automaticamente das dimensões reais do vídeo (Runtime 0.4.4+). Só adicione --aspect-ratio W:H se o usuário solicitar explicitamente uma proporção especial
• Se já houver um projeto padrão, faça inspect para confirmar e reutilizar, não recrie projectId; se o mesmo vídeo já foi cortado antes, pergunte ao usuário: continuar de onde parou ou recomeçar? (um dos três momentos de fala). project prepare é um compilador idempotente, usado apenas para retomar uma interrupção ou atualização explícita; se interrompido, basta executar novamente
• project create é a única entrada: sem passar por biblioteca de mídia, sessão de upload ou skill adicional; a skill não deve escrever project.json primeiro
• O serviço só continua após o script confirmar healthy=true, runtimeMode=launchd (macOS) ou runtimeMode=windows-task (Windows), versão compatível, URL canônico 5190; se falhar, propague o erro estruturado e pare, proibido recorrer a foreground, trocar porta, matar processos desconhecidos
• As duas leituras de estado devem apontar para o mesmo projectId, salvar o stage do workflow e as três revisões (Project / Cuts / EditList); se faltar ou for inconsistente, pare

2. Corrigir caracteres: acertar os caracteres, gerar tabela de correção

O que faz: antes de qualquer julgamento de corte, use o dicionário para corrigir caracteres que a transcrição ouviu errado—caracteres errados, julgamentos seguintes estarão errados; caracteres ouvidos errados não são palavras extras, o corte não os corrige.

node "<raiz-do-plugin>/scripts/videocut-cli.cjs" transcript dictionary "<diretório-do-projeto>" --dictionary "<raiz-do-plugin>/references/ai-term-dictionary.md" --json

Use suas ferramentas de arquivo para verificar se $HOME/.chengfeng-videocut/dictionary.md existe; se existir, execute novamente (abordagem transitória: a CLI atual só aceita um arquivo por vez, executa duas vezes; ela só pode adicionar, não desfazer a execução anterior— a fusão completa priorizando o usuário para vários dicionários será lançada quando a CLI suportar):

node "<raiz-do-plugin>/scripts/videocut-cli.cjs" transcript dictionary "<diretório-do-projeto>" --dictionary "$HOME/.chengfeng-videocut/dictionary.md" --json

Saída: tabela de correção—mescla a lista applied retornada pelas duas execuções em uma pequena tabela (palavra original → para → contexto), reporte ao usuário. Depois de corrigir, você DEVE ver esta tabela—o dicionário também pode corrigir errado sem contexto; se vir algo errado, corrija o dicionário, não faça ajustes em outro lugar.

Apenas quando o dicionário não resolver e o autor tiver o roteiro em mãos, execute um alinhamento contextual adicional:

node "<raiz-do-plugin>/scripts/videocut-cli.cjs" transcript align "<diretório-do-projeto>" --script "<arquivo-do-roteiro>" --json   # Apenas reporta, não corrige
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" transcript correct "<diretório-do-projeto>" --file "<arquivo-de-correção>" --json

Regras:

• Só altera texto, não altera tempo, contagem de palavras, wordId—o produto compara timestamps palavra por palavra, mudar isso é rejeitado
• Só altera a grafia, não o significado—se ele disse errado e repetiu, isso é frase incompleta/mudança de fala, pertence ao corte
• Se o dicionário não tem e o roteiro também não confirma, não adivinhe: reporte para que o usuário complete o dicionário. Colocar um nome inventado é pior do que deixar um nome ouvido errado
• Mantenha a fala coloquial chinesa como dito: se ele disse "叉" ou "大模型", é o que ele disse
• O dicionário é uma barreira que deve ser aplicada a cada transcrição (o mesmo áudio transcrito duas vezes dá resultados diferentes, veja o livro de acidentes)

Parágrafos do roteiro por pontuação: cada palavra na transcrição vem com pontuação, o roteiro tem um trecho por vírgula, uma linha por frase; as legendas usam a mesma pontuação, a quebra de linha é consistente. Projetos anteriores a 2026-07-28 não têm pontuação; execute node "<raiz-do-plugin>/scripts/videocut-cli.cjs" transcript regroup "<diretório-do-projeto>" --json para reparticionar os parágrafos (verifica id/tempo/texto palavra por palavra, seguro para projetos já cortados); se precisar de pontuação, terá que retranscrever—a pontuação simplesmente não existe em transcrições antigas.

3. Cortar: Cinco rodadas de varredura, cada rodada apenas um tipo

O que faz: leia o material e, em seguida, leia a ordem de reprodução completa cinco vezes, cada vez com apenas um critério. Ler com um critério por vez resulta em qualidade de julgamento muito superior a ler com seis critérios de uma vez; cada rodada produz pouco e é verificável.

Primeiro, leia o material:

node "<raiz-do-plugin>/scripts/videocut-cli.cjs" transcript playback "<diretório-do-projeto>" --json

Em seguida, use suas ferramentas de leitura de arquivo para ler $HOME/.chengfeng-videocut/cut-preferences.md (preferências do usuário, o que ele disse vale; se o arquivo não existe, é um novo usuário, pule).

Os critérios estão em Regras de exclusão semântica (princípios + exemplos). Prioridade: preferência do usuário > caso do usuário > caso geral.

Rodada 1   Repetição         Repetição entre frases, repetição dentro da frase (mais objetivo: duas vezes iguais)
Rodada 2   Frase incompleta e reformulação   Dizer pela metade, parar, reformular
Rodada 3   Erro de fala e repetição correta  Número errado, nome próprio, palavra, depois repetir corretamente
Rodada 4   Gaguejo em inglês  Repetição de início de palavra / letra / sílaba
Rodada 5   Muletas e palavras de preenchimento   Mais subjetivo, de acordo com a densidade e tolerância da preferência do usuário

A ação de cada rodada é fixa: consulte os casos para o tipo da rodada → encontre uma ocorrência, registre uma linha (wordIds + tipo + risco) → não julgue outros tipos. Nas rodadas seguintes, pule palavras já marcadas; conflitos serão resolvidos na consolidação.

Regras:

• O julgamento usa apenas a ordem de reprodução do transcript playback; proibido montar a partir do transcript.json— "disse duas vezes" depende da adjacência na reprodução; montar sozinho pode interpretar números pulados como conteúdo faltante e julgar erroneamente (veja o livro de acidentes)
• A exclusão tem apenas dois estados: "excluído / não excluído"; a IA não forma um terceiro estado "sugerir exclusão"
• Erro de fala, repetição, frase incompleta: por padrão, exclui o anterior e mantém o posterior; frases longas, frases inteiras, reformulações bifurcadas devem ser revisadas com alto risco
• Pausas normais não são calculadas pela skill: a fusão de silêncios adjacentes e natural-pause-v2 são executados deterministicamente pelo produto

4. Consolidar: Duas tabelas, só agir quando as tabelas estiverem prontas

O que faz: mescla as linhas das cinco rodadas em duas tabelas—esta é a saída desta etapa e também o que será mostrado ao usuário.

Tabela de resumo de cortes (decisão de exclusão item por item):

| # | Tempo | Tipo | Excluído          | Restante lido como | Risco | Base      |
|---|-------|------|------------------|-------------------|------|----------|
| 1 | 00:12 | Repetição | essa função né     | essa função ela na verdade | Baixo | Caso R2   |
| 2 | 02:31 | Reformulação | por exemplo eu mandei ele rastrear | por exemplo eu mandei o Grok rastrear | Alto | Caso R5   |

Tabela de frases repetidas (frases ditas várias vezes; a tabela item por item não mostra "quantas vezes gravou, qual manteve", e é exatamente isso que o usuário mais quer verificar):

| Frase (início)      | Quantas vezes disse | Qual manteve      | Quais excluiu   | Risco            |
|--------------------|--------------------|------------------|-----------------|-----------------|
| Porque hoje tem…   | 3                  | 3ª 00:08          | 1ª, 2ª          | Baixo—três vezes basicamente iguais |
| A maioria dos agentes consegue… | 2 | 2ª 04:40         | 1ª              | Alto—as duas versões divergem, preste atenção |

Em seguida, auto-leitura: leia o texto completo após a exclusão na ordem de reprodução de acordo com a tabela; desfaça linhas que não soem bem. Esta é a definição de revisão: a IA olha novamente por si mesma, não pergunte ao usuário; se não tiver certeza = não liste (dois estados).

5. Revisar: Só abrir o Studio quando for revisão manual

O que faz: submete a proposta completa, apresenta as duas tabelas ao usuário e, em seguida, abre a página de revisão do produto para que o usuário revise pessoalmente.

node "<raiz-do-plugin>/scripts/videocut-cli.cjs" cuts get "<diretório-do-projeto>" --json              # Obtém a revisão atual do Cuts
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" cuts set "<diretório-do-projeto>" --file "<arquivo-de-proposta>" --expected-revision "<revisão-atual-do-Cuts>" --json

A proposta usa apenas wordIds estáveis:

{
  "schemaVersion": 1,
  "cutWordIds": ["word-12", "word-13"],
  "reasons": [
    { "wordIds": ["word-12", "word-13"], "kind": "repeat", "risk": "low" }
  ]
}

Regras de submissão:

• A proposta é a conclusão completa do julgamento atual, não um delta—cuts set é semântica de substituição; enviar um delta descarta silenciosamente os cortes semânticos da rodada anterior (veja o livro de acidentes); ao enviar a proposta, proibido ler ou mesclar manualmente initialization.baselineCutWordIds (o produto incorpora automaticamente a linha de base de pausas)
• reasons são persistidos, escritos fielmente; o produto removerá partes que mencionam palavras não excluídas
• Não escreva diretamente cut-selection.json, project.json ou logs de eventos
• cuts get.data.revision é a revisão do Cuts, workflow get.data.revision é a do projeto, proibido misturar
• Após a submissão bem-sucedida, VEJA noLongerCut (número de palavras que não serão mais cortadas desta vez): se não for zero e não for uma retirada intencional, significa que você enviou um delta; volte e reenvie a versão completa; mesmo lendo "unknown", você deve vê-lo
• Em seguida, execute imediatamente workflow get + cuts get novamente, confirme cut_review_ready e as três revisões; se inconsistente, pare; nunca escreva JSON diretamente ou sobrescreva automaticamente
• Após a submissão, mantenha o <arquivo-de-proposta> no diretório de tarefas—a etapa 6 de retrospectiva usará (os reasons são cortados pelo produto após a edição do usuário; a consulta posterior a partir do livro de cortes não é confiável)

Em seguida, primeiro apresente as tabelas, depois abra a página: envie as duas tabelas ao usuário e peça para ele entrar no Studio para revisar.

node "<raiz-do-plugin>/scripts/ensure-running.cjs" --json                    # Garanta idempotência novamente antes de abrir
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" open "<diretório-do-projeto>" --json          # Obtém a URL do projeto retornada pelo produto

node "<raiz-do-plugin>/scripts/ensure-studio.cjs" --url "<URL-do-projeto-do-produto>" --view koubo --json                                  # Portão de recurso: confirma que 5190 registrou a visualização koubo

Regras:

• Só abra a URL do Studio com o navegador embutido do Codex se o portão retornar ok=true; depois, pare o avanço automático, espere o usuário selecionar palavras, restaurar e salvar
• Antes de abrir, compare rigorosamente o productUrl #project/<projectId> com o projectId da leitura de estado, e vincule stage=cut_review_ready com as três revisões—ok=true do portão prova apenas a capacidade do lado do produto, não pode substituir a vinculação no nível do projeto; qualquer inconsistência, releia o estado
• studio_capability_missing: pare e explique a incompatibilidade de versão, pode sugerir $chengfeng-report-bug; proibido considerar que a nova interface existe só porque a URL contém ?view=koubo; proibido recorrer ao painel de tarefas antigo
• Não faça de "abrir a bancada de trabalho" o primeiro passo da tarefa; não acesse review.html antigo, 8898/8899; não controle o DOM do Studio, não modifique elementos de mídia diretamente; não crie faixas de áudio independentes ou faixas de legenda placeholder

6. Retrospectiva e entrega: Não jogue fora a lição de casa corrigida pelo usuário

Após o usuário concluir a revisão, leia o estado de volta:

node "<raiz-do-plugin>/scripts/videocut-cli.cjs" workflow get "<diretório-do-projeto>" --json
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" cuts get "<diretório-do-projeto>" --json

Retrospectiva (abordagem transitória, será substituída pelo comando cuts diff do produto): compare o <arquivo-de-proposta> salvo na etapa 5 com o cutWordIds final lido—

• O que o usuário restaurou (estava na proposta, não está na versão final) = a IA excluiu errado. Compare com o reason que você mesmo escreveu na proposta e pergunte: em que tipo errou?
• O que o usuário adicionou (está na versão final, não estava na proposta, e não está em initialization.baselineCutWordIds linha de base de pausas) = a IA deixou passar. Pergunte: a que tipo pertence, por que não foi identificado? (A linha de base só é usada aqui para excluir palavras de pausa; ainda proibido mesclá-la na submissão)

Arquive em três gavetas:

• Diferença de preferência → anexe em ~/.chengfeng-videocut/cut-preferences.md (markdown mantido pelo Agent, apenas anexa e reescreve sua própria seção; se o arquivo não existir, crie)
• Erro de nome próprio → anexe em ~/.chengfeng-videocut/dictionary.md (tabela de duas colunas, verifique duplicatas antes de anexar)
• Lacuna na regra → registre um item na seção "casos a atualizar" do arquivo de preferências; quando o mesmo tipo aparecer pela terceira vez, reporte ao usuário e sugira atualizar para um caso geral (só mexa no repositório de skills após revisão humana)
• Diferença zero também registre: adicione uma linha "totalmente aceito" no arquivo de preferências para o projeto

Relate quatro coisas: quantas palavras foram excluídas, quantos segundos a menos; o stage atual (deve ser cut_review_ready); as três revisões (Projeto / Cuts / EDL); resumo da retrospectiva (proposta N itens, aceitos X, restaurados Y, adicionados Z, divergência principal em uma frase). Em seguida, informe ao usuário que o próximo passo é executar a exportação.

Não exiba cartão de confirmação, não execute o corte—o cartão de confirmação do corte físico pertence ao skill de exportação; esse cartão deve congelar a revisão no momento em que o usuário pressiona confirmar.

return_cut_review: primeiro execute novamente node "<raiz-do-plugin>/scripts/ensure-running.cjs" --json e, em seguida, retorne ao mesmo Studio para continuar a revisão; não acione a retrospectiva; a retrospectiva só é feita uma vez na entrega final.

Classificação de relatórios: a revisão estruturada do produto é API/readback PASS; a revisão real de quadros do navegador é visual frame PASS; se ninguém realmente ouviu o áudio, é human listening UNVERIFIED; não use reprodução, DOM, captura de tela ou detecção de mídia como substituto.

Recuperação e falha

• revision_conflict: releia o estado, explique a edição que o usuário acabou de fazer, não sobrescreva automaticamente
• runtime_unhealthy: não reinstale em loop
• service_identity_mismatch / service_port_conflict: pare, não recorra a foreground, não troque de porta, não mate processos desconhecidos
• Se a página for fechada, mas o serviço ainda estiver em execução: leia o workflow e continue a partir do estado atual, não crie um novo projeto
• Em qualquer falha, não diga "livro de cortes já escrito" como "já cortado"—até esta etapa, nenhum arquivo de mídia foi gerado

Nota: Esta skill aceita vídeo local real e transcrição palavra por palavra da nuvem para entrada direta no produto; isso é um requisito do contrato preflight; ambos realmente existirem é pré-condição para todos os julgamentos.