nick334455/manual-explainer

Manual Explainer (Explicador de Manuales)

Construye una "aplicación de lección" HTML autónoma a partir de un manual: las páginas se muestran como imágenes, cada paso se narra en chino, coreano o inglés (conmutable en cualquier momento, mediante síntesis de voz del navegador con resaltado de oraciones), y el alumno puede presionar ✋ 打断提问 en cualquier momento. Eso pausa la narración a media oración, abre un panel de preguntas que sabe dónde está el alumno, responde desde el manual con enlaces de página [p.N], y ▶ 继续讲解 reanuda desde la oración interrumpida.

La calidad de la aplicación depende casi enteramente del paso 2 (comprensión) y del paso 3 (diseño de la lección). Los scripts se encargan de la mecánica.

Flujo de trabajo

1. Extraer

SK=<directorio de esta habilidad>
python $SK/scripts/extract_manual.py "/mnt/user-data/uploads/<archivo>" /home/claude/mx

Soporta pdf, pptx, ppt, docx, doc (todo pasa por un PDF para que los números de página coincidan con las imágenes). Salida en /home/claude/mx: content.md (texto completo con marcadores [[pN]], notas del orador de pptx, esquema de encabezados de docx), content.json, pages/pN.jpg. El informe impreso lista image_heavy_pages y cuántos secretos fueron enmascarados.

Para diapositivas PPTX que son una imagen grande con notas en un cuadro de texto al lado, el extractor utiliza la propia imagen en su resolución nativa como imagen de página (reportado en warnings), por lo que las diapositivas se ven más grandes y nítidas.

Si no hay ningún archivo adjunto, pídelo. Si el archivo es un PDF escaneado sin texto (total_chars cerca de 0), lee las imágenes de página visualmente y escribe knowledge tú mismo a partir de lo que ves.

2. Comprender el manual completamente — antes de diseñar nada

Lee content.md de principio a fin (en fragmentos con view si es largo). Luego view las imágenes de página para cada página image_heavy y para cualquier página cuyo texto se refiera a una figura, pantalla, panel, diagrama de cableado, tabla o diseño de botones — esos elementos visuales suelen ser el corazón de un manual y la extracción de texto los pasa por alto.

Construye un modelo de trabajo y guarda notas en /home/claude/mx/notes.md:

• cuál es el producto/proceso, quién es el lector, qué debe ser capaz de hacer después
• la estructura real: configuración → operación normal → ajustes → mantenimiento → solución de problemas, o la que sea que use el manual realmente
• cada procedimiento con su orden, condiciones previas y resultado esperado
• cada advertencia / precaución / aviso de peligro (deben sobrevivir en la lección palabra por palabra en significado)
• especificaciones y números (presiones, voltajes, tiempos, límites) y en qué página
• términos que el alumno debe conocer (→ glosario)
• contradicciones, lagunas o puntos poco claros — menciónalos al usuario al final en lugar de adivinar

3. Diseñar la lección → /home/claude/mx/lesson.json

Lee references/lesson_schema.md para el formato exacto y las reglas de narración. Principios de diseño:

• Enseña, no leas en voz alta. Ordena según lo que el alumno necesita primero, no necesariamente por orden de página. Tamaño típico: 3–10 capítulos, 2–8 pasos cada uno, una idea por paso.
• Cada paso muestra la imagen de página más relevante (image) y lista cada página de soporte en page_refs.
• La narración explica por qué y qué sale mal, señala lo que es visible en la imagen de página, y está escrita para ser hablada.
• Lleva cada advertencia de seguridad a warning del paso donde aplique.
• 1–3 preguntas de cuestionario por capítulo sobre cosas que importan en la práctica (orden de procedimientos, límites, advertencias) — no trivialidades.
• knowledge = el texto completo limpio de content.md con sus marcadores [[pN]] (elimina encabezados/pies de página y texto repetitivo; conserva tablas). Añade una breve descripción de las figuras importantes que viste en páginas con muchas imágenes bajo su marcador de página, para que el tutor también pueda responder sobre ellas.
• Verificación de cobertura: cada página debe aparecer en image o page_refs de algún paso, excepto portada, índice, páginas en blanco y legales. El informe de construcción imprime uncovered_pages; corrige las lagunas que contengan contenido real.
• Idiomas (predeterminado: 中文 / 한국어 / English): construye cada lección en los tres idiomas — "languages": ["zh","ko","en"] — para que el alumno pueda cambiar en cualquier momento en el encabezado de la aplicación. Establece language (el predeterminado) al idioma en que el usuario te está hablando. Solo construye menos idiomas cuando el usuario lo pida. Cada texto visible (títulos, narración, viñetas, advertencias, cuestionarios, glosario) es entonces un objeto {"zh":…,"ko":…,"en":…}; la compilación se niega a ejecutarse si falta uno. Escribe cada idioma de forma nativa para hablarlo, no como una traducción literal de los otros dos, y mantén las advertencias igual de estrictas en todos ellos. knowledge permanece en el idioma original del manual — el tutor lo lee y responde en el idioma seleccionado. Conserva las etiquetas originales en pantalla del manual (nombres de botones, códigos de alarma) la primera vez que aparecen en cada idioma.
• Para manuales largos, escribe primero la lección en el idioma predeterminado, verifica la cobertura, luego añade los otros dos idiomas campo por campo.

4. Construir

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

La compilación valida la lección (corrige y vuelve a ejecutar si hay LESSON ERROR), enmascara secretos nuevamente, incrusta imágenes de página dentro de un presupuesto de ~14.5 MiB (las páginas publicadas deben mantenerse por debajo de 16 MB) e imprime un informe. Las imágenes están en WebP y las páginas idénticas se almacenan una sola vez. Las imágenes de paso siempre están incrustadas y se mantienen lo más nítidas posible (hasta 1800px, nunca se amplían); las páginas listadas solo en page_refs se incrustan más pequeñas, y las que no caben aparecen como citas solo de texto. Para manuales muy largos (cientos de páginas), mantén las imágenes de paso en páginas esenciales y distintas. Las credenciales que aparecen dentro de las imágenes de página (capturas de pantalla, texto de diapositivas) no son detectadas por el escaneo de texto: oscurécelas en pages/pN.jpg antes de construir. No edites manualmente la lógica de la plantilla para un solo manual; cambia lesson.json.

5. Entregar

• Donde existe la herramienta Artifact (claude.ai): publica el HTML con capabilities: {"sample": {}} y favicon 📘. sample es lo que permite al tutor dentro de la aplicación preguntar a Claude. No declares otras capacidades.
• En otro lugar (Claude Code, Cowork, sin herramienta Artifact): presenta el archivo HTML. Abierto como un archivo plano, el panel de preguntas recurre a buscar en el manual y mostrar los pasajes originales más relevantes con números de página.

Luego responde brevemente, en el idioma del usuario: la lista de capítulos en una o dos líneas, cómo usarlo (▶ reproducir, ✋ interrumpir en cualquier momento, teclado: Espacio / ← → / Q), que la primera pregunta pide permiso para usar su uso de Claude, y cualquier laguna o contradicción que hayas encontrado en el manual.

6. Iterar

Para cambios ("第3章讲细一点", "语速太快", "加一章故障排除"), edita lesson.json, reconstruye y vuelve a publicar en el mismo artifact (pasa su url).

Seguridad (documentos de empresa)

Los manuales pueden contener nombres de cuenta, contraseñas predeterminadas, IPs con credenciales, claves de licencia o datos de clientes.

• Ambos scripts enmascaran automáticamente contraseñas, tokens, claves, claves privadas y cadenas de conexión con credenciales. Nunca copies dichos valores en la narración, viñetas o tus respuestas; informa solo que N elementos fueron enmascarados y de qué tipo.
• Si una credencial predeterminada de un manual es genuinamente parte de un procedimiento (p. ej. "inicie sesión como admin con la contraseña inicial"), describe el paso y señala la página ("初始密码见手册第12页，或向管理员获取") en lugar de indicar el valor.
• No subas el manual a ningún servicio externo; todo se ejecuta localmente y en la página publicada.

Qué hace la aplicación (para responder a preguntas del usuario sobre ella)

• Encabezado: título, selector de idioma (中文 / 한국어 / EN — cambiar mantiene el paso actual y funciona a media lección o dentro del panel de preguntas), panel de voz 🔊, velocidad 0.8–1.5×; barra de progreso.
• Voz: la aplicación clasifica las voces del navegador y selecciona automáticamente la más natural (voces neuronales Edge "Natural/Online" > voces Apple Enhanced/Premium > voces de Google > otras). El panel 🔊 las lista (★ = natural), ofrece una vista previa y recuerda la elección por idioma. Cuando solo existen voces robóticas, lo indica y sugiere Edge / una voz de Google / descargar una voz mejorada. No es posible audio pregrabado: una página publicada no puede llamar a un servicio TTS y el audio excedería el límite de tamaño.
• Cajón de contenidos (☰ en móvil): capítulos, pasos (los visitados marcados), cuestionarios, glosario.
• Tarjeta de paso: imagen de página, título, puntos clave, advertencia, narración con la oración actual resaltada, chips de página.
• 🖼 modo diapositiva grande (predeterminado activado): los contenidos se mueven al cajón ☰ y la diapositiva ocupa toda la altura de la pantalla junto a una columna de texto estrecha (apilada en pantallas estrechas). Conmutable y recordado por visor.
• Visor de páginas (toca una diapositiva, chip de página o enlace [p.N]): zoom con pellizco/rueda del ratón hasta 6×, arrastrar para desplazar, doble toque para hacer zoom, botones − ⤢ +, ‹ › para pasar las páginas incrustadas; teclado + − 0 ← → Esc. En un teléfono en modo retrato sugiere girar el teléfono.
• La reproducción automática continúa a través de los pasos y se detiene en cada cuestionario de capítulo.
• ✋ panel de preguntas: línea de contexto mostrando la posición actual, chips de sugerencia (再讲一遍 / 更简单 / 举例 / 为什么重要 / 常见错误), respuestas en streaming con [p.N] enlazables, botón Detener, ▶ 继续讲解 reanuda desde la oración interrumpida.
• La posición, la voz y la velocidad se recuerdan por visor.
• Las voces dependen del navegador/sistema operativo del visor; sin una voz que coincida, la aplicación avanza igualmente mediante tiempo de lectura con resaltado.