nick334455/manual-explainer

Manual Explainer (Explicador de Manuais)

Crie um "aplicativo de lição" HTML autônomo a partir de um manual: as páginas são exibidas como imagens, cada etapa é narrada em Chinês, Coreano ou Inglês — alternável a qualquer momento (text-to-speech do navegador, com destaque de sentenças), e o aluno pode pressionar ✋ 打断提问 (Interromper e Perguntar) a qualquer momento. Isso pausa a narração no meio da frase, abre um painel de perguntas que sabe onde o aluno está, responde com base no manual usando links [p.N] para as páginas, e ▶ 继续讲解 (Continuar Explicação) retoma do ponto interrompido.

A qualidade do aplicativo depende quase inteiramente da etapa 2 (compreensão) e da etapa 3 (design da lição). Os scripts cuidam da mecânica.

Fluxo de Trabalho

1. Extrair

SK=<diretório deste skill>
python $SK/scripts/extract_manual.py "/mnt/user-data/uploads/<arquivo>" /home/claude/mx

Suporta pdf, pptx, ppt, docx, doc (tudo passa por um PDF para que os números de página coincidam com as imagens). Saída em /home/claude/mx: content.md (texto completo com marcadores [[pN]], notas do apresentador do pptx, estrutura de títulos do docx), content.json, pages/pN.jpg. O relatório impresso lista image_heavy_pages (páginas com muitas imagens) e quantos segredos foram mascarados.

Para slides PPTX que são uma imagem grande com notas em uma caixa de texto ao lado, o extrator usa a própria imagem em resolução nativa como imagem da página (relatado em warnings), então os slides ficam maiores e mais nítidos.

Se nenhum arquivo for anexado, peça por ele. Se o arquivo for um PDF escaneado sem texto (total_chars próximo de 0), leia as imagens das páginas visualmente e escreva o knowledge você mesmo(a) com base no que vê.

2. Compreender o manual completamente — antes de projetar qualquer coisa

Leia content.md do início ao fim (em partes com view se for longo). Em seguida, view as imagens das páginas para cada página image_heavy e para qualquer página cujo texto se refira a uma figura, tela, painel, diagrama de fiação, tabela ou layout de botões — esses elementos visuais geralmente são o coração de um manual e a extração de texto os perde.

Construa um modelo de trabalho e mantenha anotações em /home/claude/mx/notes.md:

• qual é o produto/processo, quem é o leitor, o que eles devem saber fazer depois
• a estrutura real: configuração → operação normal → configurações → manutenção → solução de problemas, ou o que o manual realmente usa
• cada procedimento com sua ordem, pré-condições e resultado esperado
• cada aviso / cuidado / perigo (estes devem sobreviver na lição palavra por palavra em significado)
• especificações e números (pressões, voltagens, tempos, limites) e em qual página
• termos que o aluno precisa conhecer (→ glossário)
• contradições, lacunas ou pontos pouco claros — mencione-os ao usuário no final, em vez de adivinhar

3. Projetar a lição → /home/claude/mx/lesson.json

Leia references/lesson_schema.md para o formato exato e regras de narração. Princípios de design:

• Ensine, não leia em voz alta. Ordene pelo que o aluno precisa primeiro, não necessariamente pela ordem das páginas. Tamanho típico: 3–10 capítulos, 2–8 etapas cada, uma ideia por etapa.
• Cada etapa mostra a imagem de página mais relevante (image) e lista cada página de suporte em page_refs.
• A narração explica por quê e o que dá errado, aponta para o que está visível na imagem da página e é escrita para ser falada.
• Carregue cada aviso de segurança no campo warning da etapa onde ele se aplica.
• 1–3 perguntas de quiz por capítulo sobre coisas que importam na prática (ordem de procedimentos, limites, avisos) — não trivialidades.
• knowledge = o texto completo limpo de content.md com seus marcadores [[pN]] (remova cabeçalhos/rodapés de página e textos repetitivos; mantenha tabelas). Adicione uma breve descrição das figuras importantes que você viu nas páginas com muitas imagens sob seu marcador de página, para que o tutor possa responder sobre elas também.
• Verificação de cobertura: toda página deve aparecer como image ou em page_refs de alguma etapa, exceto capa, índice, páginas em branco e páginas legais. O relatório de construção imprime uncovered_pages (páginas não cobertas); corrija lacunas que contêm conteúdo real.
• Idiomas (padrão: 中文 / 한국어 / English): construa toda a lição nos três — "languages": ["zh","ko","en"] — para que o aluno possa alternar no cabeçalho do aplicativo a qualquer momento. Defina language (o idioma padrão) para o idioma que o usuário está falando com você. Só construa com menos idiomas quando o usuário pedir. Cada texto visível (títulos, narração, marcadores, avisos, quiz, glossário) é então um objeto {"zh":…,"ko":…,"en":…}; a construção se recusa a executar se um estiver faltando. Escreva cada idioma de forma nativa para ser falado, não como uma tradução literal dos outros dois, e mantenha os avisos igualmente rigorosos em todos eles. knowledge permanece no idioma original do manual — o tutor o lê e responde no idioma selecionado. Mantenha os rótulos originais da tela do manual (nomes de botões, códigos de alarme) na primeira vez que aparecerem em cada idioma.
• Para manuais longos, escreva a lição primeiro no idioma padrão, verifique a cobertura, depois adicione os outros dois idiomas campo por campo.

4. Construir

python $SK/scripts/build_app.py /home/claude/mx/lesson.json /home/claude/mx /mnt/user-data/outputs/<nome>-explicacao.html

A construção valida a lição (corrija e execute novamente em caso de LESSON ERROR), mascara segredos novamente, incorpora imagens de página dentro de um orçamento de ~14,5 MiB (as páginas publicadas devem ficar abaixo de 16 MB) e imprime um relatório. As imagens são WebP e páginas idênticas são armazenadas uma vez. As imagens das etapas são sempre incorporadas e mantidas mais nítidas (até 1800px, nunca ampliadas); páginas listadas apenas em page_refs são incorporadas menores, e as que não couberem aparecem como citações apenas em texto. Para manuais muito longos (centenas de páginas), mantenha as imagens das etapas apenas para páginas distintas e essenciais. Credenciais que aparecem dentro das imagens das páginas (capturas de tela, texto de slides) não são capturadas pela varredura de texto: escureça-as em pages/pN.jpg antes de construir. Não edite manualmente a lógica do modelo para um único manual; altere lesson.json.

5. Entregar

• Onde a ferramenta Artifact existe (claude.ai): publique o HTML com capabilities: {"sample": {}} e favicon 📘. sample é o que permite que o tutor no aplicativo pergunte ao Claude. Não declare outras capacidades.
• Em outros lugares (Claude Code, Cowork, sem ferramenta Artifact): apresente o arquivo HTML. Aberto como um arquivo simples, o painel de perguntas recorre à busca no manual e mostra as passagens originais mais relevantes com números de página.

Em seguida, responda brevemente, no idioma do usuário: a lista de capítulos em uma ou duas linhas, como usar (▶ reproduzir, ✋ interromper a qualquer momento, teclado: Espaço / ← → / Q), que a primeira pergunta pede permissão para usar o uso do Claude deles, e quaisquer lacunas ou contradições que você encontrou no manual.

6. Iterar

Para alterações ("Capítulo 3 com mais detalhes", "Velocidade da fala muito rápida", "Adicionar um capítulo de solução de problemas"), edite lesson.json, reconstrua e publique novamente no mesmo artefato (passe seu url).

Segurança (documentos da empresa)

Manuais podem conter nomes de contas, senhas padrão, IPs com credenciais, chaves de licença ou dados de clientes.

• Ambos os scripts mascaram senhas, tokens, chaves, chaves privadas e strings de conexão com credenciais automaticamente. Nunca copie esses valores na narração, marcadores ou suas respostas; relate apenas que N itens foram mascarados e de qual tipo.
• Se uma credencial padrão de um manual for genuinamente parte de um procedimento (por exemplo, "faça login como admin com a senha inicial"), descreva a etapa e aponte para a página ("初始密码见手册第12页，或向管理员获取" - "A senha inicial está na página 12 do manual, ou obtenha com o administrador") em vez de declarar o valor.
• Não faça upload do manual para nenhum serviço externo; tudo é executado localmente e na página publicada.

O que o aplicativo faz (para responder a perguntas do usuário sobre ele)

• Cabeçalho: título, seletor de idioma (中文 / 한국어 / EN — a alternância mantém a etapa atual e funciona no meio da lição ou dentro do painel de perguntas), 🔊 painel de voz, velocidade 0,8–1,5×; barra de progresso.
• Voz: o aplicativo classifica as vozes do navegador e escolhe automaticamente a mais natural (vozes neurais Edge "Natural/Online" > vozes Apple Enhanced/Premium > vozes Google > outras). O painel 🔊 as lista (★ = natural), oferece uma prévia e lembra a escolha por idioma. Quando só existem vozes robóticas, ele avisa e sugere Edge / uma voz do Google / baixar uma voz aprimorada. Áudio pré-gravado não é possível: uma página publicada não pode chamar um serviço de TTS e o áudio excederia o limite de tamanho.
• Gaveta de conteúdo (☰ em dispositivos móveis): capítulos, etapas (as visitadas marcadas), quizzes, glossário.
• Cartão de etapa: imagem da página, título, pontos principais, aviso, narração com a frase atual destacada, fichas de página.
• 🖼 Modo slide grande (padrão ativado): o conteúdo vai para a gaveta ☰ e o slide preenche a altura da tela ao lado de uma coluna de texto estreita (empilhado em telas estreitas). Alternável e lembrado por visualizador.
• Visualizador de página (toque em um slide, ficha de página ou link [p.N]): zoom por pinça / roda do mouse até 6×, arraste para mover, toque duplo para ampliar, botões − ⤢ +, ‹ › para navegar por todas as páginas incorporadas; teclado + − 0 ← → Esc. Em um telefone retrato, sugere girar o telefone para o lado.
• A reprodução automática continua pelas etapas e para em cada quiz de capítulo.
• ✋ Painel de perguntas: linha de contexto mostrando a posição atual, chips de sugestão (再讲一遍 / 更简单 / 举例 / 为什么重要 / 常见错误 - Repetir / Mais Simples / Exemplo / Por que é Importante / Erros Comuns), respostas em streaming com [p.N] clicáveis, botão Parar, ▶ 继续讲解 (Continuar Explicação) retoma da frase interrompida.
• Posição, voz e velocidade são lembrados por visualizador.
• As vozes dependem do navegador/SO do visualizador; sem uma voz compatível, o aplicativo ainda avança usando o tempo de leitura com destaque.