Skip to content

cjescudero/asistente-docente

v0.6.0MIT

Mapa docente, materiales, evaluación y feedback para cualquier disciplina.

GitHubOpen Website

Asistente docente

Doce skills para organizar fuentes, crear materiales, evaluar y devolver feedback en cualquier asignatura. La fuente común genera paquetes para ChatGPT Work y Claude Cowork. Versión 0.6.0, bajo MIT. Instalación y primer uso · Descargar paquetes · Repositorio.

Escanea el QR para abrir el repositorio. Descargar el QR en PNG para usarlo en presentaciones.

Qué incluye

Puesta en marcha del proyecto con AGENTS.md, Mapa docente con índice, conceptos, consultas trazables y grafo HTML, actividades y enunciados, apuntes, evaluación de entregas con rúbricas, bancos GIFT, modelos impresos con GIFT ofuscado, feedback para Moodle, redacción clara e infografías didácticas. Guía de uso y catálogo de skills.

Las fuentes docentes y los datos del alumnado pertenecen al proyecto del profesor, no a la instalación del plugin. Las tareas simples pueden partir de una conversación; la ficha reutilizable permite mantener contexto entre encargos. Los materiales escritos usan Markdown y PDF; el Mapa docente conserva sus páginas navegables en Markdown estándar, un registro JSON, un lector index.html y un grafo HTML autónomo. Consulta la guía del Mapa docente y su índice de ejemplo.

Puesta en marcha del proyecto docente

Pedir «Pon en marcha este proyecto docente» activa iniciar proyecto docente. La skill crea o complementa las instrucciones generales del AGENTS.md del proyecto del curso, modificando solo lo indicado y preguntando ante conflictos. Establece skill-redactar-espanol-claro como opción predeterminada para escribir en español y pregunta dónde están los materiales y qué contiene cada carpeta cuando no esté claro. No lanza la creación del mapa y conserva las instrucciones existentes para consultarlo. Véase el flujo de puesta en marcha.

Mapa docente

Tres skills separadas permiten crear o mantener el mapa, consultarlo sin cambios y visualizarlo. Crear o actualizar el mapa escribe también en el AGENTS.md de la raíz del proyecto docente la ruta a su índice y la regla común de consulta: índice → enlaces pertinentes → originales cuando sean necesarios. El agente reúne la evidencia del encargo sin volver a recorrer toda la documentación. Esta integración conserva las reglas previas y no exige ejecutar antes la skill de puesta en marcha. Si no se conoce la raíz del proyecto, se solicita.

El profesor elige explícitamente una o varias carpetas de origen; no hay una carpeta fija ni se descubren materiales por defecto. Los originales no se mueven, editan ni copian salvo petición expresa de copia.

Por ejemplo, un curso puede mantener materiales-docentes/, archivo-evaluaciones/ y mapa-docente/. Dentro del mapa, contenidos/ organiza conceptos, presentaciones, apuntes, prácticas y talleres; reservado/ separa evaluaciones, soluciones y criterios que no deben trasladarse al alumnado. Los nombres son orientativos. El tipo de material y su acceso son clasificaciones independientes.

Las páginas usan enlaces Markdown normales, sin dependencia de Notion, Obsidian o frontmatter obligatorio. fuentes.json, versión 2, registra varias raíces en source_roots, las fuentes y las páginas en pages. Las rutas son relativas al mapa y a cada raíz. Si no se puede representar una ubicación con rutas relativas, como entre unidades distintas en Windows, se comunica la limitación; no se trasladan ni copian archivos automáticamente.

Crear o actualizar el mapa incluye regenerar el lector index.html y el grafo. El lector abre el índice Markdown renderizado y permite navegar entre páginas, buscar y consultar por separado los contenidos reservados. Ambos HTML funcionan sin servidor. El grafo permite arrastrar, ampliar, buscar y filtrar nodos; «Reorganizar» redistribuye solo los visibles, conservando filtros y selección. Su panel ofrece documentos de la wiki renderizados, Markdown editables y originales; los archivos originales deben seguir accesibles para abrirlos. Las evaluaciones aparecen diferenciadas y ocultas al inicio mediante un filtro que no es un control de seguridad.

La vista opcional de estudiantes excluye de los datos los nodos no autorizados y los que dependen de ellos, incluso de forma transitiva; no ofrece enlaces salientes a archivos ni distribuye los documentos. Compartir el HTML docente con filtros activados no equivale a esa exportación. El mapa no aplica autenticación ni se publica automáticamente.

Adaptar a tu materia

Elige disciplina, nivel, idioma, objetivos, fuentes, actividad y criterios de evaluación para cada proyecto. Se admiten formación escolar, universitaria, profesional y otros contextos; no se impone una rúbrica, matrícula institucional ni escala sobre diez. Los ejemplos son sintéticos y no se heredan como reglas. La interfaz y las instrucciones están en español; los materiales respetan el idioma del encargo. Para textos en español se aplica la skill de redacción clara.

Puedes comenzar con la ficha vacía o con un encargo en la conversación. Moodle solo es necesario para sus flujos de intercambio; el mapa, las actividades, los apuntes y las rúbricas pueden usarse sin él. Alcance y revisión de generalidad.

Instalación

Sigue la guía para ChatGPT Work/Codex y Claude. El repositorio incluye catálogos para instalar desde GitHub y ambos adaptadores. No basta con copiar una skill aislada: comparte referencias y utilidades con el resto del paquete. La instalación depende de las capacidades de la cuenta.

Los artefactos de la versión son:

  • asistente-docente-0.6.0-agent-plugins.zip: Agent Plugins y adaptador Codex.
  • asistente-docente-0.6.0-claude.zip: plugin para Claude.
  • asistente-docente-0.6.0-source.zip: fuente con catálogos y automatización GitHub.

Entorno local

Se necesita Python 3.10 o posterior para las utilidades. No hay claves API ni servidores que configurar. Instalar las instrucciones en un anfitrión y preparar estas herramientas son operaciones independientes.

macOS/Linux, desde la carpeta del plugin:

python3 scripts/setup_environment.py
.venv/bin/python scripts/docencia.py doctor

Windows PowerShell:

py -3 scripts/setup_environment.py
.venv\Scripts\python.exe scripts/docencia.py doctor

doctor distingue basic_ready y pdf_ready; usa doctor --pdf para exigir las capacidades PDF. Un PDF concreto requiere comprobar su generación.

La instalación básica prepara Markdown y el lector de la wiki. Añade --pdf para instalar Playwright y Chromium; --dev prepara validaciones y pruebas. --venv permite usar una carpeta externa en instalaciones de solo lectura. --dry-run muestra las operaciones. sh install.sh conserva el acceso rápido en macOS/Linux y acepta las mismas opciones.

Si el anfitrión ya tiene Python y las dependencias, puede usarlos directamente. Los bancos GIFT, el feedback, la validación del mapa y el grafo usan Python estándar. Para PDF se puede indicar un navegador ya disponible mediante ASISTENTE_DOCENTE_CHROMIUM; si no funciona, se conserva el HTML y se declara el PDF pendiente. La generación de imágenes requiere esa capacidad del anfitrión.

Ejemplo completo sin datos reales

Usa una carpeta de resultados externa al plugin, por ejemplo una carpeta hermana llamada demo-docente:

.venv/bin/python scripts/docencia.py validate-bank examples/humanidades/banco.gift
.venv/bin/python scripts/docencia.py build-exams examples/humanidades/banco.gift --metadata examples/humanidades/metadatos.json --output ../demo-docente/examen --title "Fuentes e interpretación histórica" --models 2 --questions 4 --seed 42
.venv/bin/python scripts/docencia.py build-feedback ../demo-docente/examen/manifest.json --input examples/resultados-sinteticos.csv --config examples/feedback-config.json --output ../demo-docente/feedback
.venv/bin/python scripts/docencia.py render-markdown examples/apuntes.md --output ../demo-docente/apuntes
.venv/bin/python scripts/validate_library.py examples/mapa-docente/mapa-docente

El ejemplo de Mapa docente contiene siete fuentes sintéticas en dos carpetas: cinco revisadas completas, una parcial y una pendiente. Su índice enlaza las páginas, el lector HTML y los grafos grafo-docente.html y grafo-estudiante.html. Para mantener un mapa propio, trabajar en la carpeta del curso y generar allí el HTML con scripts/build_graph.py; véase uso.

También hay un banco de ciencias con metadatos. Todos los ejemplos son sintéticos. La carpeta demostración incluye los nueve PDF revisados, HTML, GIFT, manifiestos, snapshots y comentarios producidos en la validación. Es material de referencia; genera los resultados de cada curso fuera del plugin. El emparejamiento de humanidades queda expresamente excluido de los modelos; la CLI comunica los identificadores excluidos.

--html-only permite generar y comprobar el modelo sin navegador. Si se pide PDF y falla, los HTML y el manifiesto se conservan y la CLI devuelve código 2; no declara éxito de PDF. Código 1 significa entrada o procesamiento inválidos. No se sobrescriben resultados de exámenes ni comentarios existentes.

Formatos y límites

  • GIFT: opción única, múltiple, verdadero/falso, numérica y emparejamiento. Examen impreso: los primeros cuatro tipos. Se exige título/ID único.
  • Se rechazan respuesta corta, ensayo, Cloze, preguntas sin ID, texto después del bloque de respuestas, formatos por opción y sintaxis ambigua. No es un importador universal de todas las variantes Moodle.
  • HTML: texto, listas, tablas y formato básico; rowspan/colspan conservados. El formato GIFT moodle conserva HTML básico y saltos de línea; no reproduce todos los filtros, autoenlaces y extensiones de un curso Moodle. HTML activo, SVG, MathML e imágenes incrustadas en enunciados requieren una adaptación explícita y se rechazan, sin perder contenido silenciosamente.
  • Matemáticas: \(...\) y \[...\], con MathJax 3.2.2 local (base, ams y newcommand). Sin carga remota de extensiones. Escapar símbolos GIFT en el banco.
  • Feedback: exportaciones UTF-8/UTF-8 BOM y separador coma, punto y coma o tabulador. Las columnas y los máximos son explícitos; no se presume escala sobre diez.
  • Notebooks y Word se preparan con capacidades disponibles del anfitrión; no hay un corrector universal de código ni conversión a Word en esta CLI.
  • Mapa docente: el agente lee y sintetiza fuentes con las capacidades disponibles. El validador comprueba inventario, rutas, enlaces y huellas; no ingiere PDF, ejecuta notebooks ni certifica la corrección semántica de una síntesis. El grafo deriva relaciones de enlaces Markdown reales, no de proximidad visual. Se pueden validar registros anteriores de versión 1; su actualización se hace en una copia del mapa y el grafo requiere versión 2.

Contratos técnicos · Guía Moodle

Desarrollo y distribución

.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python scripts/sync_manifests.py --check
.venv/bin/python scripts/validate_plugin.py --public
.venv/bin/python scripts/build_release.py --source

Las pruebas PDF son optativas en la suite: establecer RUN_PDF_TESTS=1 cuando Chromium esté disponible. El pipeline incluido para GitHub comprueba el código y construye paquetes como artefactos; no publica releases ni notas de alumnos. Los ZIP excluyen entornos, cachés y datos operativos. SHA256SUMS permite comprobar su integridad; contents.json registra el contenido común.

El contenido propio está bajo MIT por decisión del propietario. MathJax y el esquema Agent Plugins conservan sus avisos Apache-2.0. Consulta cómo contribuir y preparar la publicación en GitHub. Los paquetes se distribuyen en las versiones publicadas.

Procedencia · Avisos · Validación realizada