educational-html-pipeline

# Educational HTML Pipeline — Generación y Mejora de HTML Educativos ## Resumen Pipeline completo para crear y mejorar HTML educativos interactivos en dos proyectos: - **Dibujo Técnico** (`/root/workspace/DibujoTecnico`) — generación desde template - **DeSumarIntegrar** (`/root/workspace/DeSumarIntegrar`) — mejora iterativa nocturna ## 1. Generación de Temas (Dibujo Técnico) ### Flujo 1. Cargar skill TD fuente (`skill_view(name='stem/td/<nombre>')`) 2. Verificar archivos existentes vs progress.json (detectar nombres mismatch) 3. Leer template en `generate_td.py` (líneas 8-136) 4. Mapear contenido → rellenar placeholders 5. Generar SVG interactivo inline (mínimo 6-8 tipos visuales, viewBox 700x520) 6. Generar HTML completo con `write_file` 7. Verificar calidad (>12KB, tiene `<svg`, tiene `quiz-btn`) 8. Actualizar progress.json → Git commit + push ### Placeholders del template {title}, {subtitle}, {key_idea}, {learning_goals}, {theory_title}, {theory_text}, {example_1/2/3}, {interactive_title}, {interactive_desc}, {svg_content}, {interactive_content}, {exercises_html}, {summary_items}, {prev_link}, {next_link}, {js_code} ### Funciones JS requeridas - `checkAnswer(btn, isCorrect, resultId)` — quizzes selección múltiple - `checkExercise(btn, isCorrect, resultId)` — ejercicios selección - `checkVF(btn, isCorrect, resultId)` — Verdadero/Falso - `showPaso(n)` — SVG paso a paso (usar inline style.display, NO CSS global) ### Pitfalls de generación - **NUNCA usar `read_file` para leer progress.json** → prependea números de línea → rompe JSON. Usar `terminal("cat ...")` + `json.loads()` - **NUNCA usar `patch` para HTML** → siempre `write_file` con contenido completo - **Mínimo 12KB de contenido real** — cada tema debe tener: SVG, 3+ ejemplos, 5 ejercicios, teoría, error clásico, resumen - **GitHub Pages requiere `index.html` (minúsculas)** — `INDEX.html` → 404 - **CSS con dobles llaves `{{}}`** — puede venir de template engine, romper estilos. Detectar con `grep -n '{{' *.html` - **Nombres de archivo en progress.json ≠ archivos reales** — verificar con `os.path.exists()` ### Deploy a GitHub Pages 1. Renombrar INDEX.html → index.html 2. Push a master/main 3. Activar Pages via API 4. Verificar con `curl -s -o /dev/null -w "%{http_code}" URL` ## 2. Mejora Nocturna Iterativa (DeSumarIntegrar + DibujoTecnico) ### Flujo de mejora 1. **Seleccionar temas** — priorizar menos improvement_count, rotación de niveles, excluir mejorados hoy 2. **Backup** — `cp tema.html tema.html.bak` 3. **Analizar** — evaluar 8 dimensiones: exercises, text, visual, real_world, connections, difficulty_range, manim_quality, css_coherence 4. **Mejorar** — exactamente lo que falta (máx 3 ejercicios nuevos, tipos diferentes) 5. **Quality Gates** — HTML válido, ejercicios funcionales, CSS coherence (17 clases), títulos únicos 6. **Si gate falla → REVERTIR** — `cp tema.html.bak tema.html` 7. **Si OK → actualizar progress.json + git commit** ### Dimensiones de evaluación | Dimensión | Qué buscar | |-----------|-----------| | exercises | 3+ tipos diferentes (quiz, VF, completar, ordenar, problema, emparejar, input) | | text | Patrón 4 pasos: qué es → para qué → cómo → error | | visual | SVG/gráfico informativo (no decorativo) | | real_world | Casos cotidianos concretos | | connections | Connection-box con enlaces a temas relacionados | | difficulty_range | Badges easy/medium/hard | | manim_quality | SVG animado para bachiller/universidad | | css_coherence | TODAS las clases del template base | ### CSS Coherente — 17 clases requeridas `header`, `container`, `chapter-title`, `box`, `box-teoria`, `box-ejemplo`, `box-error`, `box-idea`, `box-success`, `interactive`, `exercises`, `exercise`, `quiz-options`, `quiz-btn`, `summary`, `nav`, `footer` ### CSS Coherence Drift — Patrón detectado Muchos temas tienen CSS custom en vez del template base. Diferencias típicas: - `.comparison` grid vs flex - `.step-dot` 32px vs 12px - `.real-world-badge` con gradient vs sin gradient - `.stack-item` con fondo gris vs borde azul **Corrección:** reemplazar CSS custom con template base completo. ### Variables CSS obligatorias `--azul:#2563eb`, `--naranja:#f97316`, `--verde:#10b981`, `--rojo:#ef4444` ### Clases CSS siempre faltantes - `.feedback`, `.feedback.correct`, `.feedback.incorrect` — siempre añadir - `.svg-container` — añadir si falta - `.difficulty-badge`, `.difficulty-badge.easy/medium/hard` — añadir si falta - `.connection-box` — usar `class="connection-box"` (con 'n', no `conexion-box`) ### Pitfalls críticos de mejora - **DOBLE ESCAPE KATEX** — `$\\\\\\\\pm$` vs `$\\\\pm$` — verificar con grep tras patch - **CONVERSIÓN KATEX EN PATCHES** — el patch tool puede escapar barras invertidas - **read_file con offset/limit no carga todo** — siempre leer archivo completo antes de patchear - **PATCH ENTRE </div> PIERDE WRAPPER** — verificar estructura HTML tras patch - **FUNCIONES JS DUPLICADAS** — contar con grep, eliminar duplicadas - **CLOSURE ONCLICK ROTO** — `onclick="checkFillIn(['respuesta'])()"` → cambiar a `onclick="checkFillIn(['respuesta'])(this)"` - **Ejercicios FUERA de div.exercises** — verificar y mover dentro del wrapper - **Añadir V/F requiere función JS** — verificar `checkVF` existe antes de patchear ejercicio - **box-success definido pero nunca usado** — añadir al menos un box-success cuando se mejora real_world - **NO bajar scores ya en 10** — nunca reducir un score máximo existente - **progress.json improvements puede ser string o lista** — normalizar antes de append - **DibujoTecnico progress.json: claves con .html y scores anidados** — estructura diferente a DeSumarIntegrar - **SVG interactividad ronda 2** — toggleHighlight con data-info, mínimo 5 elementos - **`.bak` files en git** — siempre hacer `git rm --cached *.bak && rm -f *.bak && git commit --amend` ### MODO RÁPIDO (batch 4-6 temas) - 1 acción por dimensión: 1 CSS batch, 1 caso real, 1 error comparativo - Usar `execute_code` (Python) para todo: leer, patchear, actualizar progress.json - Git commit después de cada batch - NO hacer SVGs interactivos nuevos en modo rápido ### Casos reales por bloque (Dibujo Técnico) | Bloque | Caso real | |--------|-----------| | b02 Proyecciones | Biela de motor, brida de tubería | | b03 Perspectivas | Tuercas/arandelas, planos arquitectónicos | | b04 Diedrico | Control calidad CMM, cableado/tuberías | | b05 Cortes | Motor de combustión, carcasa bomba | | b06 Acotación | Pieza aeronáutica, taladrero CNC | | b07 Intersecciones | Unión tuberías HVAC, vigas acero | ### Errores comparativos por bloque | Bloque | Error típico | |--------|-------------| | b02 | Planta encima del alzado, confundir X con Z | | b03 | Círculo en vez de elipse en isométrica | | b04 | Punto en 2º diedro, recta paralela a LT | | b05 | Corte total innecesario, sin corte | | b06 | Cota dentro del objeto, cotas en cadena | | b07 | Intersección recta en vez de curva | ## 3. Pipeline Auditoría → Corrección → Generación → Deploy Cuando el usuario pide completar y desplegar un proyecto HTML: 1. **Auditoría** — cargar `audit-html-project`, escaneo masivo, generar informe 2. **Corrección críticos** — enlaces rotos, archivos huérfanos, commit 3. **Generación temas faltantes** — batch de 3-6 temas, actualizar progress.json 4. **Deploy** — push a GitHub, activar Pages, verificar ## Reglas de oro - NO crear temas nuevos — solo mejorar existentes (modo mejora) - NO más de 3 ejercicios nuevos por tema - NO ejercicios del mismo tipo seguidos - NO SVG decorativos sin propósito - Si un quality gate falla, REVERTIR — no hacer commit con HTML roto - Siempre usar backup antes de cualquier cambio - Cada commit debe ser autónomo y funcional ## Referencias - `references/curriculum-map.md` — Mapa completo del curso Dibujo Técnico - `references/svg-perspectiva-isometrica.md` — Patrón SVG ejes isométricos - `references/patrones-ejercicios.md` — Patrones de ejercicios interactivos - `references/casos-reales-industriales.md` — Banco de casos reales por bloque - `references/css-coherence-drift.md` — Detección y corrección de CSS drift - `references/patron-svg-paso-a-paso-interactive.md` — Patrón SVG interactivo paso a paso - `references/katex-double-escape-fix.md` — Detección y corrección doble escape KaTeX - `references/closure-onclick-fix.md` — Patrón closure onclick roto y fix - `references/svg-interactivity-pattern.md` — Patrón toggleHighlight con data-info - `references/duplicate-content-after-patch.md` — Detectar contenido duplicado tras patch - `references/svg-animation-pattern.md` — Patrón CSS keyframes para SVG animado - `references/svg-area-model-decimal.md` — Patrón SVG modelo de área (primaria) - `references/svg-bar-chart-calendar.md` — Patrón SVG gráfico de barras - `references/svg-zigzag-pattern.md` — Patrón SVG zigzag animado - `references/ronda2-selection-pattern.md` — Patrón selección temas score 9 (ronda 2) - `references/dibujotecnico-ronda2-patterns.md` — Diferencias DibujoTecnico vs DeSumarIntegrar - `references/naming-mismatch-progress-json.md` — Nombres de archivo mismatch - `references/quality-gates-checklist.md` — Checklist visual quality gates ## Comparativa de alternativas: OpenMAIC (THU-MAIC) Plataforma multiagente de generación de clases (Next.js 16 / React 19 / LangGraph 1.1, ~37.000 ⭐, consultado 2026-09-15) que compite directamente con este pipeline: produce **.pptx editable, .html interactivo y MP4** one-click. - Self-host: Node >=22.19 y pnpm >=10; `pnpm install` + `cp .env.example .env.local` con una clave de proveedor (OpenAI, Azure, Anthropic, Bedrock, Gemini, DeepSeek, Qwen, **Ollama/Lemonade local** o cualquier API OpenAI-compatible). - MP4 con `docker compose --profile video-export up --build` (render en contenedor aislado Chromium+FFmpeg sobre **Hyperframes**, el mismo motor de `hyperframes-html-to-video`). - Genera slides, quizzes, simulaciones HTML interactivas y actividades PBL con multiagente (profesor IA + compañeros IA con TTS y pizarra) y 20 skills internas (planificación curricular, deep research, slide craft, import de .pptx). - Persistencia server-backed con Postgres (`DATABASE_URL`) y botón "Deploy with Vercel". **Cuándo usar cada uno:** OpenMAIC cuando quieras un curso completo desde un documento en un clic (multiagente, export pptx/MP4); este pipeline cuando necesites control fino del template, gates de calidad nocturnos y deploy estático a GitHub Pages.