cassieliang6709/tech-explainer-video

Vídeo de Explicação Técnica

Três fases, cada uma requer que o usuário diga explicitamente "pode" para avançar para a próxima fase. A configuração global do usuário "fazer sem confirmar" não se aplica a estas três fases; este é um fluxo de revisão especialmente solicitado pelo usuário para este skill. Se o usuário disser "não narre ainda/não faça ainda", o processo para na etapa atual.

Valores padrão (se o usuário não especificar, use estes, escrevendo no front matter do script.md):

• Público-alvo: alunos universitários que sabem Python, mas esqueceram quase tudo sobre o curso relacionado. Redação conforme references/kepu-style.md: primeiro o concreto, depois o abstrato, "se você fosse projetar", uma única figura física percorre todo o vídeo, máximo de 6 novos termos por episódio; detalhes de registradores e código-fonte são colocados no capítulo "Avançado" no final de cada episódio.
• Objetivo: depois de assistir, o espectador consegue implementar em PyTorch.
• Estrutura: três partes, princípios matemáticos → ferramentas PyTorch necessárias → codificação unificada.
• Dentro de cada episódio: use a estrutura "Geral—Específico—Geral": comece com a pergunta que o episódio responderá e um mapa das seções, o corpo se desenvolve seção por seção (com um mapa de rota no canto da tela, destacando a seção atual), e no final, cada seção é resumida em uma frase antes de anunciar o próximo episódio.
• Duração: 8–12 minutos por episódio (mudança do usuário em 2026-10-24: menos episódios, menos postagens, menos chance de bater limites da plataforma). Um tópico geralmente tem 2 episódios, no máximo 3.
• Metáforas: permitidas, mas apenas para explicar um ponto: uma frase e volta ao assunto principal, no máximo uma metáfora por conceito (regra 5 do kepu-style.md).
• Voz: voice: volc (voz pré-definida da Volc Engine zh_female_vv_uranus_bigtts); se ~/.volc_tts.env não tiver credenciais, o tts.py automaticamente usa edge-tts com a voz Xiaoyi e exibe um aviso.

Fase 0: Coleta de Materiais

Se o usuário mencionar anotações (como Obsidian), primeiro encontre e leia tudo. Use a estrutura, conclusões e números das anotações como referência.

Fase 1: Esboço (no chat)

Na primeira linha, escreva uma declaração de objetivo do projeto: "Este episódio fará com que quem X entenda Y". Para cada episódio, adicione uma linha com gancho da capa + visual da direita (veja references/cover-guide.md) e revise junto com o esboço. Use o references/outline-template.md para escrever uma tabela curta: problemas a resolver em cada capítulo, novos conceitos, código implementado, duração, plano de divisão em episódios e o que não será abordado. Leia primeiro o references/kepu-style.md. Projete a abertura, ritmo, terminologia e conclusão conforme "Fórmula de Abertura", "Ritmo", "Terminologia e Nível de Dificuldade" e "Fórmula de Conclusão" em references/script-guide.md; no esboço, marque onde cada ponto alto será colocado. Ao escrever a parte matemática, primeiro apresente o objetivo do cálculo (ex.: out_i = Σⱼ aᵢⱼ vⱼ), depois deduza cada componente, fazendo com que produto escalar, softmax e escala apareçam "apenas quando necessários".

Fase 2: Código → Roteiro → Verificação → Anotações → Finalização

Princípios de redação: Primeiro explique a motivação do projeto, depois o mecanismo, e por último o resultado. Priorize explicar "qual problema existia → o que o projetista queria resolver → por que essa solução foi escolhida → como ela funciona". É permitido adicionar etapas, exemplos e precisão necessária, mas introduza apenas novos conceitos essenciais para entender o princípio atual; na primeira aparição de um novo termo, explique-o usando conhecimento existente ou exemplos concretos. O capítulo Avançado deve ser ajustado com base no conhecimento prévio presumido para aquele capítulo.

1. Escreva o código do tutorial py/tutorial.py e execute-o de verdade. Use show(key, value) para exportar py/values.json. Todos os números, formas, True/False na tela devem vir daqui.
   • Para exemplos pequenos com significado interpretável, defina os pesos manualmente, e tanto no comentário do código quanto na narração, explique: "definido manualmente; modelos reais aprendem por treinamento".
   • Para demonstrar "por que", use comparações reais: por exemplo, allclose da associatividade com e sem softmax, norma do Jacobiano do softmax antes e depois do escalonamento.
2. De acordo com references/kepu-style.md e references/script-guide.md, escreva script/script.md (formato abaixo) e revise usando as duas listas de verificação. Cada linha "Desenho:" deve descrever claramente o que o espectador verá mudar na tela e como essa imagem ajuda a entender; primeiro defina o objetivo expressivo, não fixe a ferramenta de criação. A imagem pode ser implementada com canvas web, Remotion, Manim, Blender ou outra ferramenta mais adequada; a escolha específica é feita após a finalização, por cena. Imagens que precisam de números, código ou formas devem ser consistentes com py/values.json e py/tutorial.py. Verifique a duração por episódio: número de caracteres do texto do episódio ÷ 4.5 ÷ 60, mais cerca de 0,5 minuto para cartões de capítulo e pausas. Se exceder 12 minutos, ajuste a divisão dos episódios nesta etapa (não espere até depois da narração).
3. Após concluir o rascunho, realize, em ordem, a verificação de acessibilidade para iniciantes, checagem de fatos e polimento linguístico: 3b. Verificação de barreira de entrada para iniciantes (obrigatório): Crie um novo agente, forneça apenas o script.md e a instrução "Você sabe Python, mas esqueceu quase tudo sobre este tópico", sem dar código ou anotações. Peça que ele marque, linha por linha: ① palavras ou saltos de raciocínio incompreensíveis; ② lugares onde muitos conceitos novos são introduzidos em uma frase, exigindo que o espectador volte; ③ discrepâncias entre a descrição visual e a narração. Exija que ele aponte exatamente qual etapa de explicação está faltando, verificando especialmente se ele consegue entender seguindo "problema → motivação do projeto → mecanismo → resultado". Ele pode sugerir adicionar etapas, exemplos ou precisão necessária, mas não introduza novos conceitos irrelevantes para o fio condutor. Após corrigir ponto por ponto, verifique novamente nas mesmas condições até que não haja mais marcadores ① ou ②; os marcadores ③ também devem ser corrigidos. Registre a lista de alterações e entregue ao usuário junto com o material publicado. O capítulo Avançado deve ser verificado com base no conhecimento prévio presumido. 3c. Checagem de fatos (obrigatório): Crie um novo agente, forneça o script.md e as anotações, pedindo que ele marque apenas erros factuais ou afirmações que possam levar a mal-entendidos, explicando a base; não exija a adição de conhecimento, condições de contorno ou detalhes extras. Simplificações pedagógicas são permitidas; se o espectador puder confundir a simplificação com uma definição rigorosa, adicione uma breve observação na narração: "aqui fizemos uma simplificação". Ao corrigir, prefira expressões igualmente simples, mas precisas; não acumule qualificadores. Em caso de conflito com 3b, busque uma expressão que seja ao mesmo tempo precisa e fácil de entender; erros factuais não podem ser mantidos, e a precisão não deve ofuscar o fio condutor da explicação. Se a correção factual afetar a compreensão ou as imagens, refaça a verificação 3b correspondente. 3d. Use o skill humanizer-zh para polir, frase por frase, as linhas numeradas e as linhas "Leia:" (removendo o tom de IA). Preserve o significado dos números, termos, código e linhas "Desenho:"; não adicione ou remova conhecimento por conta própria. Após o polimento, verifique novamente a consistência entre os resultados do código, as descrições visuais e a narração, e recalcule a duração de cada episódio.
4. Envie os arquivos para o usuário (SendUserFile), pedindo que ele escreva anotações abaixo das frases começando com > (também aceita o formato > [!anotação] do Obsidian). Se ele quiser anotar no Obsidian, copie para o vault do usuário, e leia de volta após as alterações.
5. Processe as anotações: corrija uma por uma → remova as linhas de anotação já processadas → liste no chat como cada uma foi alterada → peça ao usuário para revisar novamente, até que ele diga que está finalizado.
6. Antes da finalização, não narre, não crie imagens oficiais. Para verificar a viabilidade de cenas complexas, curtas demonstrações podem ser feitas; demonstrações não substituem a revisão do roteiro.

Formato do script.md

---
title: Atenção → MHA → GQA
subtitle: Dos Princípios Matemáticos à Implementação em PyTorch
audience: Alunos universitários com alguma base em computação
voice: volc
volc_speaker: zh_female_vv_uranus_bigtts
volc_resource: seed-tts-2.0
episodes: ch0,ch1,ch2,ep1_end | ep2_start,ch3,ch4,ep2_end | ep3_start,ch5,ch6
episode_titles: Título do Episódio 1 | Título do Episódio 2 | Título do Episódio 3
---

## ch0 | Abertura
1. Texto original da legenda, uma frase por batida visual.
   - Leia: Como o TTS deve ler (escreva apenas se diferente da legenda; símbolos devem ser escritos como lidos, por exemplo, "行" (háng) deve ser escrito como "航")
   - Desenho: O que aparece na tela durante esta frase (obrigatório, o agente visual implementa conforme esta descrição)
> Anotação: O usuário escreve aqui

## ep1_end | Prévia do Próximo Episódio
1. O próximo episódio abordará…
   - Desenho: Cartão de encerramento do EP1

• IDs de capítulo: ch0, ch1, …; abertura/encerramento de episódio usam epK_start / epK_end, com imagens geradas automaticamente pelo EpCard genérico. Novas frases também devem ser revisadas pelo usuário.
• Geral-Específico-Geral: epK_start escreva 2–3 frases: ① a pergunta que este episódio responderá; ② "Este episódio aborda N coisas: …" (correspondendo uma a uma aos capítulos do episódio). epK_end escreva 2–3 frases: uma conclusão por capítulo + prévia do próximo episódio. O capítulo de abertura do primeiro episódio (ch0) também deve incluir o mapa do episódio. O episodes no front matter determina quais seções estão no mapa; os nomes das seções vêm dos títulos dos capítulos.
• As legendas não precisam ser manualmente divididas; o tts.py as divide em segmentos com largura ≤ 22 caracteres com base na pontuação.

Fase 3: Geração do Vídeo

Escolha, cena por cena, o método de produção que melhor explica o princípio: relações 2D, código e dados podem usar canvas web, Remotion ou Manim; estruturas espaciais e movimentos de câmera podem usar ferramentas 3D como Blender. Novas ferramentas mais adequadas também podem ser usadas, desde que não aumentem a complexidade da explicação pelo uso da ferramenta. O template/ existente é o pipeline de composição e entrega do Remotion; cenas feitas com outras ferramentas devem primeiro gerar um vídeo ou imagem, verificar a integração com o pipeline (mantendo sincronia de legendas, narração e batidas) antes de serem usadas nos capítulos oficiais. Os componentes, caminhos e comandos em references/visual-guide.md e references/agent-brief.md aplicam-se apenas a capítulos Remotion; outras ferramentas seguem os princípios de layout, cores, dados reais e auto-verificação visual.

1. Copie template/ para o diretório especificado pelo usuário (padrão ~/Videos/<tópico>, pergunte primeiro) e coloque py/ e script/ lá. Instale as dependências apenas uma vez: Para séries (vários projetos no mesmo diretório pai, ex.: ~/Videos/nudgecode-algoritmo/<capítulo>/), instale node_modules uma vez no diretório pai (copie o package.json do template e execute npm install); cada projeto cria um link simbólico com ln -s ../node_modules node_modules. Para um único projeto, instale dentro dele. Execute apenas um npm install por vez; concorrência corrompe os pacotes. Após a instalação, verifique se node_modules/react-dom/index.js existe (este pacote já esteve corrompido no cache do npm; se faltar, copie de outro projeto com a mesma versão).
2. Execute python3 tools/md2json.py (recusa se houver anotações não processadas) → python3 tools/scaffold.py → python3 tools/tts.py Isso gera public/audio/*, src/timeline.json. A narração é armazenada em cache; apenas frases alteradas são regravadas.
3. Primeiro, crie a abertura e o capítulo 1 para definir o estilo visual (comece pela cena mais difícil; para ritmo e transições, veja references/plotome-lessons.md). Para cenas Remotion, use node tools/stills.mjs ch1 && tools/sheet.sh ch1 para verificar; para cenas feitas com ferramentas externas, verifique o material original e os quadros compostos após a integração, e envie uma prévia ao usuário. Se o estilo visual já foi aprovado pelo usuário em uma série (ex.: no primeiro projeto da mesma série), não peça aprovação novamente; continue diretamente. stills.mjs reutiliza out/bundle (gerado por tools/bundle.mjs, que só reempacota se os arquivos fonte mudaram). Não crie um novo diretório de ~90 MB em $TMPDIR a cada execução.
4. Após a aprovação do usuário, divida os capítulos restantes entre vários agentes iniciando todos em uma única mensagem (cada agente fica com 1–2 capítulos):
   • Capítulos Remotion: Preencha references/agent-brief.md e salve como AGENT_BRIEF.md na raiz do projeto; copie references/visual-guide.md como VISUAL_GUIDE.md. Para cenas de ferramentas externas, escreva uma breve descrição da tarefa, acordando formato, duração, local do arquivo e responsabilidade pela integração com Remotion. Não aplique a restrição de modificar apenas ChN.tsx.
   • Se a narração for alterada, envie uma SendMessage para o agente relevante, informando quais frases mudaram e que a timeline foi atualizada.
5. Depois que todos os capítulos estiverem prontos, a sessão principal verifica os quadros compostos capítulo por capítulo: sobreposições, legendas, consistência entre imagem e "Desenho:", se os números vêm de values.json. Para material externo, verifique também a duração e o ritmo após a importação.
6. Após npx tsc passar, execute tools/render.sh em segundo plano: ele gera out/epK.mp4 + out/epK.srt + out/covers/epK.jpg por episódio, normalizando para -16 LUFS. O tempo de renderização é de aproximadamente 1 minuto por minuto de vídeo. Não mexa em áudio ou código durante a renderização: a mixagem lê o áudio apenas na etapa final; sobrescrevê-lo durante o processo mistura áudio novo e velho. O render.sh usa um lock global (lockf /tmp/remotion-render.lock) para garantir que apenas um episódio seja renderizado por vez: renderizar vários projetos simultaneamente não é mais rápido (a CPU já está cheia), apenas consome mais memória e disco. Vários projetos podem iniciar render.sh ao mesmo tempo; eles entram em fila automaticamente.
7. Capas: De acordo com references/cover-guide.md, escreva src/covers/CoverEpK.tsx para cada episódio e registre-o em src/covers/index.ts (fundo preto, gancho em letras grandes + destaque amarelo no fundo, visual grande à direita); o render.sh gera automaticamente out/covers/epK.jpg. Episódios não registrados usam uma versão genérica. Envie todas as capas em uma única imagem para o usuário analisar. Para regerar uma capa individualmente: npx remotion still out/bundle cover-epK out/covers/epK.jpg.
8. Entrega: Use SendUserFile para enviar os mp4, srt, capas e py/tutorial.py de cada episódio. Peça ao usuário que leia o srt em voz alta; muitas vezes problemas são encontrados.
9. Quando precisar publicar, mude para o skill video-publish. Antes da publicação, revise a lista de conformidade em references/plotome-lessons.md (marcação de IA, licenciamento de música, atribuições).

Produção em Lote (Múltiplos Projetos em Paralelo)

• Limite o número de sessões simultâneas a 3–4: muitas sessões rapidamente atingem o limite de uso, e o TTS da Volc também reclama de concorrência excessiva (o tts.py já tem backoff e retry, concorrência 2).
• Paralelismo apenas na escrita e criação de imagens; a renderização fica por conta do lock global do render.sh para enfileiramento.
• Disco: Cada capítulo ocupa cerca de 90 MB para out/bundle, dezenas de MB para capturas de tela out/check, e cerca de dezenas de MB por episódio finalizado. Antes de iniciar um novo lote, verifique df -h; $TMPDIR/remotion-webpack-bundle-* são pacotes temporários deixados por scripts antigos e podem ser limpos.
• Quando o usuário concordar com "renderizar lote → enviar diretamente → deletar episódios finalizados", veja "Pipeline em Lote" no video-publish.

Pipeline de Agendamento da Sessão Principal (Base de Conhecimento 2026-10-30 ~ 11-03, dois artigos por lote)

1. Agentes de redação (um por artigo, dois simultaneamente): Esboço → tutorial real com exportação de values.json → roteiro → verificação de acessibilidade para iniciantes (crie outro agente, no máximo 8 rodadas; depois, corrija tudo com base na última rodada) → checagem de fatos (crie outro agente, comparando com as anotações) → humanizer → verificação de duração por episódio → copiar template, criar link simbólico para node_modules → md2json / scaffold / tts → escrever AGENT_BRIEF.md, VISUAL_GUIDE.md, componentes compartilhados de figura física src/lib/<nome>.tsx (primeiro defina constantes de layout) → fazer ch0, ch1. No relatório, liste "discrepâncias entre anotações e medições".
2. Sessão principal analisa a colagem de ch0/ch1. Se o estilo visual estiver ok, continue; não espere pelo usuário.
3. Fan-out de cenas: Preencha references/agent-brief.md como um brief compartilhado e escreva em /tmp/claude-501/brief_<artigo>.txt (para o segundo artigo, use sed para substituir caminhos/nomes de componentes/locks e adicione "Complementos deste projeto"). O prompt de cada agente deve ser apenas: "Primeiro leia o brief completo com Read e siga-o rigorosamente. Você é responsável por chX, chY". Cada agente fica com 2–3 capítulos; a capa é deixada para o último agente. Inicie todos em uma única mensagem.
4. Colete problemas conhecidos: Quando cada agente de cena retornar, anote os "problemas conhecidos / números fora de values.json / alterações não revisadas posteriormente" que ele relatou.
5. Agente de revisão completa (um por artigo, modelo references/review-brief.md): Escreva os problemas coletados no passo 4, um por um, em "Pendências conhecidas".
6. Renderização: Cada artigo inicia tools/render.sh em segundo plano; o lock global enfileira automaticamente. Use um loop until em segundo plano para aguardar o aparecimento de out/ep3.mp4.
7. Auditoria aleatória (feita pela sessão principal, não confie em relatórios): Para cada episódio, execute ffmpeg -af volumedetect (normal: mean cerca de −19 dB, max ≤ −1.2 dB); Para um episódio de cada artigo, use -vf "fps=1/60,scale=480:-1,tile=4x3" para criar uma grade e usar Read para visualizar; confirme se as três capas em out/covers/ estão presentes.
8. Upload: out/parts/P<k> <gancho>: <tópico>.mp4 link rígido + out/upload_meta.md (com um parágrafo adicional de descrição). Em seguida, enfileire conforme a seção "Adicionar a um rascunho existente" do video-publish. Após o upload, atualize PROGRESS.md e o quadro Kanban, e envie o parágrafo de descrição para o usuário.

Atingir Limite de Uso / Interrupção

• O limite de uso pode matar todos os agentes em execução. Após a recuperação, use SendMessage para cada agente com "Continue". O agente retoma com o contexto; não abra novos agentes (isso resulta em trabalho duplicado e sobreposição).
• Limite o número de agentes simultâneos a cerca de 12 (2 artigos × 5–6 agentes de cena).

Discrepâncias entre Anotações e Medições

• As anotações no vault são somente leitura. Quando houver discrepância entre medições e anotações, o vídeo segue as medições. Liste cada discrepância para o usuário no relatório; cabe a ele decidir se altera as anotações.

Alterações Após a Finalização

• Alterar narração: Altere script.md → md2json → tts (regrava apenas as frases alteradas) → verifique as cenas dos capítulos afetados.
• Mudar o número de frases pode causar desalinhamento visual: para capítulos já com cenas prontas, altere apenas a redação, não adicione ou remova frases; para adicionar conteúdo, inclua como uma nova seção de frases (ex.: epK_start).
• O agente visual implementa apenas o que está em visual; dúvidas devem ser reportadas à sessão principal, e ele não altera a narração por conta própria.

Voz

• Voz pré-definida da Volc Engine (padrão, voice: volc): zh_female_vv_uranus_bigtts, recurso seed-tts-2.0. Foi escolhida pelo usuário no episódio sobre GQA, e a qualidade é visivelmente superior ao edge-tts. Se o front matter não especificar volc_speaker, use esta. As credenciais estão em ~/.volc_tts.env (já configurado), precisando apenas de VOLC_APPID / VOLC_TOKEN; opcional: VOLC_SPEED para velocidade (1.0 normal).
• Trocar de voz: No front matter, escreva volc_speaker: <ID da voz>. Vozes pré-definidas usam automaticamente seed-tts-2.0; vozes clonadas que começam com S_ usam automaticamente seed-icl-2.0 (ou VOLC_RESOURCE do env). Você também pode usar volc_resource explicitamente; escreva v1 para usar a interface antiga, onde pode definir VOLC_CLUSTER (padrão volcano_icl).
• A voz clonada do usuário (VOLC_SPEAKER_ID no env, começando com S_) atualmente reporta "resource ID is mismatched with speaker". Antes de usar, confirme a versão da voz, status de treinamento e appid no console Volc. Enquanto não funcionar, não use.
• Não imprima o conteúdo do arquivo env. Em novos projetos, primeiro use --only para sintetizar algumas frases de um episódio para teste, depois faça todo o episódio.
• edge-tts (alternativa): voice: zh-CN-XiaoyiNeural, outras opções: YunxiNeural, YunyangNeural, XiaoxiaoNeural. Quando as credenciais da Volc estiverem faltando, o tts.py automaticamente usa Xiaoyi.
• Para trocar de voz, basta executar tts.py novamente; as imagens se alinham automaticamente com as batidas. Basta uma auditoria com a colagem.

Dublagem em Inglês (2026-11-03)

• edge-tts en-US-AndrewMultilingualNeural: O usuário testou 9 vozes e escolheu esta. Gratuita, sem necessidade de chave, mas usa uma interface não oficial do Edge朗读: pode sofrer rate limiting/quedas de conexão (tts precisa tentar novamente), uso comercial não claro, e a interface pode mudar. No front matter: voice: en-US-AndrewMultilingualNeural.
• Volc seed-tts-2.0 tem en_male_tim_uranus_bigtts e en_female_dacey_uranus_bigtts disponíveis (alternativas); seed-tts-1.0 com *_mars_bigtts (vozes em inglês) retorna 403 na conta atual (não ativado). A voz chinesa vv também pode ler inglês, mas com sotaque evidente.
• Teste: Para um mesmo trecho de abertura de ~20 segundos em inglês, gere um mp3 para cada voz. Use ffmpeg concat (com 1,2 segundos de apad entre cada faixa) para criar uma única coletânea e envie para o usuário.

Bilíngue Chinês-Inglês (em fase piloto)

• Projeto piloto: ~/Videos/base-conhecimento/llm-13-rag-agent-en. Use narração em inglês (original, não traduzida do chinês), com tradução em chinês para cada frase. Duas linhas de legenda (inglês em cima, chinês ligeiramente menor em baixo). Rótulos visuais em inglês.
• As alterações específicas nos componentes de legenda e no md2json serão escritas aqui e no template após a conclusão do piloto.
• A versão em inglês não deve ser adicionada a compilações em chinês. O destino da publicação (novo episódio no Bilibili / YouTube) é decidido pelo usuário.

Visão Geral dos Arquivos (template/)

Arquivo	Função
tools/md2json.py	script.md → script.json (verifica anotações, analisa divisão de episódios)
tools/scaffold.py	Gera componentes placeholder para capítulos e src/chapters/index.ts
tools/tts.py	Narração frase por frase, divisão de legendas curtas, escrita de timeline.json; suporta edge-tts / Volc Engine
tools/stills.mjs + sheet.sh	Captura de tela em 80% de cada frase e montagem em grade 3×3 (use SCALE=1 para tamanho real)
tools/render.sh	Renderização por episódio + merge de legendas + normalização de loudness
src/lib/beat.tsx	Sincronização de batidas (useBeat), cartão de título de capítulo, legendas
src/lib/ui.tsx	CodePanel / Matrix / Fade / Tag / H / Tex (fórmulas KaTeX)
src/lib/EpCard.tsx	Cartão de abertura e encerramento de episódio
src/lib/Cover.tsx + src/covers/	Componentes de capa (CoverFrame / Hl / CodeVisual / BigNumber) + registro de capa personalizada por episódio
src/lib/algo.tsx	Componentes de algoritmo: grade de array, dict, tabela trace, cartão de problema
tools/bundle.mjs	Empacota uma vez, reutiliza out/bundle
src/lib/library.tsx	Opcional: componente de metáfora de "biblioteca" de tensores (Building / Corridor)

Documentos de Referência

• references/script-guide.md: Guia de redação de roteiro; outline-template.md: Template de esboço
• references/visual-guide.md / agent-brief.md: Especificações visuais, instruções para agente visual
• references/cover-guide.md: Especificações de capa
• references/plotome-lessons.md: Ritmo, transições, música, conformidade (inspirado em plotome)
• references/production-retro-2026-10.md: Retrospectiva da produção em lote dos 13 capítulos do nudgecode, armadilhas e soluções
• references/production-retro-2026-11.md: Retrospectiva do pipeline de agendamento de dois artigos por lote na base de conhecimento
• references/review-brief.md: Template de agente de revisão completa
• rethinkfun-style.md / cishoon-style.md: Análise de criadores de conteúdo que o usuário gosta

Armadilhas Enfrentadas

• say do macOS é muito robótico; use edge-tts.
• Código e símbolos devem ser escritos em "Leia:" como seriam lidos em voz alta; caracteres polifônicos como "行" (háng) devem ser escritos como "航".
• Ao falar de números de modelos reais, verifique sua estrutura (ex.: Llama-2-70B já é GQA; se for falar de 10 GB com 64 cabeças, diga "supondo que usássemos MHA").
• A atenção inicializada aleatoriamente é muito uniforme e sem sentido: ou defina pesos manualmente, ou mude a semente aleatória para obter contrastes mais evidentes.
• Use tools/stills.mjs para capturas de tela (empacota apenas uma vez), muito mais rápido que remotion still; a primeira renderização baixa o headless Chrome.
• No Bash, não escreva cat > file sem entrada; ele ficará preso esperando stdin.
• Capturas em 80% de cada frase: animações que aparecem após 80% (X vermelho, letras grandes tardias) não serão capturadas; ou capture separadamente, ou antecipe o tempo de aparecimento.
• Quando agentes de cena estão em paralelo, erros de sintaxe nos capítulos de outros agentes podem fazer o bundle falhar: espere um ou dois minutos e tente novamente; não mexa nos arquivos dos outros.
• Um agente de revisão já "limpou" capturas antigas: o brief deve conter "não exclua nenhum arquivo (sobrescrever capturas é permitido)".
• Disco: Cada projeto ocupa cerca de 0,5 GB; episódios finalizados, dezenas de MB cada. Escrever o disco durante a renderização pode causar o erro "No space left on device". Antes de iniciar um novo lote, verifique df -h; se estiver abaixo de ~15 GB, primeiro liste os grupos que podem ser limpos (caches de ferramentas, conda clean, etc.) para o usuário escolher; a exclusão requer aprovação do usuário.
• Cartões de título de capítulo e cartões de abertura/encerramento adicionam cerca de 10 segundos por episódio; estime a duração final como TTS real + 10 segundos.
• Agentes de cena podem registrar em src/covers/index.ts: isso é necessário para as capas, é permitido.
• Para aguardar a renderização em segundo plano, não use pgrep -f render.sh: o próprio comando de espera contém essa string, então o pgrep sempre corresponde a si mesmo, fazendo o loop ficar ocioso por horas. Espere apenas pelo aparecimento de out/epK.mp4 (ou por erros no log).