createsomethingq3k/vibe-knowledge-film

Vibe 知识短片（código, quadro a quadro）

Especificação final: 1920×1080, 30fps, ~159 segundos (seguindo a música) ou personalizado, sem voz humana, uma legenda em chinês por tela, todo o visual desenhado por código Canvas. O exemplo 《半衰期》 (examples/halflife/) é montado inteiramente com componentes; a validação de fidelidade mostra que é pixel‑a‑pixel idêntico ao vídeo de referência original dentro de 67 quadros, e a mixagem de áudio coincide amostra por amostra. examples/gallery/ demonstra o mesmo conjunto de componentes aplicado a outros temas.

O que faz o público valorizar este tipo de vídeo: fatos reais (anos, dados brutos, artigos), imagens em movimento contínuo e revelações sincronizadas com a música. Cada regra abaixo existe para garantir esses três pilares.

Linhas‑de‑base (cada uma tem uma razão – algo já deu errado)

• Cada número, nome, ano e citação na tela precisa ter uma fonte, registrada na tabela de fatos; se não for possível verificar, não escreva – indique no visual com «示意 (ilustrativo)». A IA tem tendência a “inventar que é verdade” ao escrever citações – a famosa frase em inglês do Rutherford no 《半衰期》 antigo foi inventada.
• A marca d'água deve conter apenas o nome do usuário ou o título do vídeo. Ao copiar quadros de referência, a IA pode incluir o nome do autor original (no demo antigo aparecia “比特新语” no canto superior esquerdo), o que configura uso indevido.
• Trilha sonora: use apenas arquivos fornecidos e licenciados pelo usuário. Não extraia áudio de outros vídeos, não baixe de sites duvidosos, e a skill não vem com nenhuma música embutida. Ao publicar no Bilibili, adicione a música no fluxo de submissão da plataforma.
• No final do vídeo e na descrição da publicação, inclua uma declaração de que foi gerado por IA.
• renderFrame(t) deve depender apenas de t: use VF.rng(semente) para números aleatórios, não use temporizadores nem mantenha estado entre quadros. Caso contrário, a exportação tremerá e cada renderização será diferente.

Preparação

SK=~/.claude/skills/vibe-knowledge-film
$SK/engine/setup.sh    # verifica node / ffmpeg (libx264) / numpy, instala pacote playwright, localiza navegador da máquina

Fluxo de trabalho (três pontos de confirmação; confirme antes de prosseguir)

① Tópico e rota → Confirmação 1

Use AskUserQuestion para esclarecer (a primeira recomendação é a preferida):

• Tópico: se o usuário der apenas uma direção, ofereça 3 candidatos. Um bom tópico = conceito técnico difícil × ponto emocional que se conecta a “você” (entropia → cansaço da vida; meia‑vida → esquecer é trair?), de preferência com uma reviravolta contraintuitiva. Veja references/story.md.
• Trilha sonora: bgm (usuário fornece arquivo licenciado, como «开智小曲»; o vídeo segue a música, duração = duração da música) ou synth (sintetizada por código, duração personalizada).
• Atribuição (o que escrever na marca d'água), duração (padrão: seguir a música, 159 segundos).

② Verificação de fatos → Tabela de fatos

Cada fato que vai para a tela: afirmação | fonte | confiabilidade (T1: artigo original / T2: fonte secundária confiável / T3: apenas “diz‑se”) | em qual frase é usado. A verificação frequentemente reescreve a história: no 《半衰期》, a pesquisa revelou que “esquecer é uma lei de potência – quanto mais antigo, mais estável”, o que derrubou o subtítulo original e se tornou a reviravolta final. Se encontrar conflitos, pare e avise o usuário.

③ Roteiro de legendas + storyboard → Confirmação 2

Escreva seguindo o formato de seis partes (gancho → título → âncora histórica → demonstração do mecanismo → reviravolta contraintuitiva → retorno ao público → dedicatória e referências). Uma legenda por tela, ≤ 6,5 caracteres/segundo, destaque palavras‑chave com {}, frases com citação devem ter o item 4 em texto pequeno. Para cada parte do storyboard, descreva: o que está acontecendo visualmente (uma legenda corresponde a uma ação na tela), o que está “realmente sendo calculado” (com dados reais, fórmulas reais, semente fixa para simulação) e efeitos sonoros. Template em templates/事实表与字幕分镜.md. Mostre a tabela de fatos + roteiro de legendas + storyboard ao usuário; espere a aprovação antes de escrever código.

④ Criar o filme, escrever film.js

$SK/engine/new_film.sh <diretório_do_filme> <nome_do_filme>                 # esqueleto de seis partes
$SK/engine/new_film.sh <diretório_do_filme> <nome_do_filme> --from halflife  # começar a partir de / comparar com 《半衰期》

Primeiro, selecione os componentes de acordo com o conteúdo: references/components.md tem uma tabela “o que mostrar → qual componente usar”; examples/gallery/组件图鉴.png mostra todos os componentes visualmente. O template de esqueleto já monta as seis partes com componentes; basta trocar dados e texto. Se os componentes não forem suficientes, escreva funções locais em film.js (API em references/engine.md, exemplo completo em examples/halflife/film.js). Regras:

• Faça primeiro a cena mais difícil; gere um quadro estático para ver se funciona, depois faça as outras.
• Escreva legendas, cenas e efeitos sonoros com base nos “tempos do storyboard”; delegue o acerto dos pontos de drop da música para o warp (passo ⑤), não ajuste cada ponto de tempo manualmente.
• Em cada cena, a cada 2–3 segundos deve haver um novo movimento; para pausas longas, adicione micro‑movimentos (brilho fluido, varredura, zoom lento). O mecanismo de respiração da engine tem amplitude pequena e sozinho não segura a “paralisia”.
• Palavras que aparecem pela primeira vez visualmente (desenhadas na cena, não na legenda) devem ser adicionadas a strings.

⑤ Música e pontos de drop

• bgm: coloque a música no diretório do filme, execute python3 $SK/engine/analyze_bgm.py <música> --json out/bgm.json. Se for «开智小曲», compare com o sha256 de data/kaizhi-xiaoqu.json: se coincidir, use diretamente a grade de compassos e pontos de âncora sugeridos; se não coincidir (outras fontes podem ter um deslocamento geral de 0,1–0,3 segundos), recalcule a grade usando os pontos de ataque de baixa frequência recém‑medidos. Em meta.music.warp, escreva os pontos de âncora: título piscando em branco → 1º drop, pergunta/silêncio → seção de queda, revelação da reviravolta → 2º drop, ponto de chegada e dedicatória → início de frase musical. Detalhes em references/music.md.
• synth: em meta.music.synth, defina os níveis de cada voz e envelopes de silêncio por parágrafo (modifique com base no exemplo SYNTH).

⑥ Auto‑inspeção (sem gerar o vídeo completo)

node $SK/engine/export.mjs <diretório_do_filme> events          # tabela de efeitos sonoros + temporização das legendas
node $SK/engine/export.mjs <diretório_do_filme> stills          # out/stills.png, visão geral de 16 quadros; também pode especificar segundos: 3,16.9,43.6
cd <diretório_do_filme> && python3 -m http.server 8765 --bind 127.0.0.1   # abra film.html no navegador para arrastar a linha do tempo e ouvir a música de fundo

Verifique quadro a quadro: o texto ultrapassa as bordas? a tela está meio vazia? as curvas estão coladas aos pontos de dados? algum objeto está flutuando na posição errada? a legenda e a ação estão sincronizadas? O código não reporta erros – só a inspeção visual revela problemas. No 《半衰期》, esta etapa identificou 5 problemas.

⑦ Renderização final + verificação de qualidade

$SK/engine/build.sh <diretório_do_filme>        # tabela de efeitos → trilha sonora → renderização quadro a quadro → mixagem com -14 LUFS → qa.py (executa em segundo plano, ~5–12 minutos)
$SK/engine/build.sh <diretório_do_filme> --skip-render   # apenas alterações de áudio

Itens marcados com ✗ por qa.py devem ser corrigidos; itens com ! devem ser corrigidos ou justificados na entrega como intencionais. A máquina também pode acusar injustamente: se reportar “tela preta”, verifique os quadros – fundos escuros frequentemente são mal interpretados. Leia as interpretações em references/qa.md.

⑧ Entrega → Confirmação 3

Forneça ao usuário: caminho do vídeo final, duração, resultado da verificação de qualidade e pontos que ainda poderiam ser melhores. Complemente com 制作日志.md (registro de produção: cada incidente: fenômeno → causa → solução; quando se tornar um tutorial, estes serão os capítulos). Se precisar de texto para a publicação, veja references/publish.md.

Comandos rápidos

Comando	Função
engine/setup.sh	Verificação e instalação do ambiente
engine/new_film.sh <diretório> <nome> [--from halflife]	Criar novo filme (copia um snapshot da engine para o diretório; atualizações futuras da engine não afetam filmes antigos)
node engine/export.mjs <diretório> events / stills [segundo,…] / render [início fim]	Exportar tabela de efeitos sonoros / visão geral de quadros / vídeo (especifique início e fim para renderizar apenas um trecho)
python3 engine/audio.py <diretório>	Música de fundo + efeitos sonoros → out/mix.wav
python3 engine/analyze_bgm.py <música> [--json arquivo]	BPM, compassos, curva de energia, pontos de ataque de baixa frequência
engine/build.sh <diretório> [--skip-render]	Um comando para criar o filme + verificar qualidade
python3 engine/qa.py <diretório> [vídeo_final]	Verificação de qualidade isolada

Arquivos de referência (leia quando necessário)

Arquivo	Quando consultar
references/story.md	Seleção de tópico, formato de seis partes, regras de legendas, classificação da tabela de fatos
references/style.md	Diretrizes visuais: paleta de cores, fontes, cinco camadas da tela, coordenadas do layout, densidade de movimento
references/components.md	Antes de escrever cenas: 21 componentes + 5 fábricas de dados, “o que mostrar → qual usar”, parâmetros
references/engine.md	API básica do VF, campos meta, estrutura de cenas
references/music.md	Dois modos de música, estrutura da «开智小曲», detecção de drop, pontos de âncora warp, tabela de efeitos sonoros
references/qa.md	Significado de cada item de verificação, limites e falsos positivos comuns
references/pitfalls.md	Leia antes de começar: 30 armadilhas encontradas ao fazer 《半衰期》 + armadilhas em outros projetos similares
references/publish.md	Texto para publicação, declaração de IA, tratamento de música e citações
examples/halflife/	Exemplo completo: film.js (versão com componentes), tabela de fatos e storyboard, registro de produção
examples/gallery/	Galeria de componentes: mesmo conjunto aplicado a diferentes temas; 组件图鉴.png para visão geral
data/kaizhi-xiaoqu.json	Estrutura medida e pontos de âncora sugeridos para a «开智小曲»