MENTORA (profesorado)

Qué es MENTORA

MENTORA es una extensión de navegador pensada para facilitar la creación de casos para la extensión SOCIA por parte del profesorado. Su uso es bastante intuitivo, solamente es necesario ponerla en marcha y realizar el caso mientras se explica usando la voz, tal y como se haría para explicar el caso en el aula al alumnado.

MENTORA va registrando las diferentes acciones realizadas: qué se hace con el ratón y el teclado, graba un vídeo, realiza capturas de pantalla, captura peticiones de red… Al detener la grabación, MENTORA prepara un ZIP con todo ese material. Dicho material se utilizará como fuente de información para poder crear posteriormente el caso preparado en formato JSON. También se podrá utilizar para generar una guía didáctica.

MENTORA antes de iniciar una grabación.

Cómo instalarla

La instalación depende de si se está usando una versión ya empaquetada o si se está trabajando desde el repositorio del proyecto.

Si se dispone de una build de la extensión (oficialmente publicada en releases), basta con cargarla en el navegador en modo desarrollador. En Chrome o Edge, el flujo habitual es abrir chrome://extensions, activar el modo desarrollador y usar Cargar descomprimida para subir la carpeta del build de MENTORA.

Si se quiere construir desde el repositorio, se trabaja desde el workspace de aplicaciones:

cd apps
pnpm install
pnpm --filter @socia/extensions build:mentora

Para trabajar directamente en modo desarrollo, sin generar una build cada vez que se modifica el código, se puede lanzar MENTORA con estos comandos:

cd apps
pnpm install
pnpm --filter @socia/extensions dev:mentora

Este modo es el más cómodo cuando se está ajustando la extensión, porque mantiene el proceso activo y recompila los cambios. La consola indicará la carpeta generada dentro de .output para cargarla como extensión descomprimida si el navegador no se abre automáticamente.

Para generar un ZIP distribuible de la extensión:

cd apps
pnpm --filter @socia/extensions zip:mentora

La extensión necesita permiso para capturar la pantalla y el micrófono. Cuando se use normalmente abrirá una pantalla auxiliar de permisos. Es necesario concederlos antes de grabar una sesión, ya que el contexto es muy importante para la fiabilidad de la creación del caso.

La transcripción es opcional, pero muy recomendable. Para activarla hay que guardar una clave de OpenRouter en la extensión. Cuando se detiene la grabación, MENTORA envía el audio a OpenRouter para transcribirlo.

Permisos de micrófono y captura de pantalla necesarios para grabar con MENTORA.

Cómo usarla para grabar un caso

Antes de pulsar Empezar, merece la pena preparar el caso como si fuera una demostración en clase. MENTORA graba lo que ocurre y es fundamental que la explicación sea clara y lo más detallada posible.

Lo recomendable es tener pensado:

• Qué incidente se va a resolver.
• Qué herramientas se van a usar.
• Qué datos son variables del caso, como IPs, nombres de alerta o usuarios, e indicarlos con la voz.
• Qué partes deben convertirse en hitos para el alumnado.
• Qué explicación de conceptos puede ayudar después a generar la guía.

Cuando todo esté listo, abre la extensión MENTORA y pulsa Empezar. A partir de ese momento la extensión captura pantalla, micrófono, acciones del navegador y peticiones de red. Durante la grabación puede pausarse si hace falta preparar algo que no forma parte del caso, aunque lo recomendable es hacerlo en una sola vez.

Al terminar, pulsa Detener. MENTORA prepara automáticamente el ZIP y abre el diálogo de descarga. El nombre del archivo sigue el patrón mentora-recording-<fecha>.zip.

MENTORA conserva la grabación después de descargarla. Se puede usar Volver a descargar hasta que se inicie una grabación nueva. Al empezar otra sesión, la extensión elimina los datos de la anterior.

Grabación activa de una resolución docente.

Qué contiene el ZIP

El ZIP de MENTORA es un paquete pensado para que un agente pueda reconstruir el caso con suficiente contexto.

Si todo ha ido bien contiene:

Archivo o carpeta	Contenido
metadata.json	Duración, páginas visitadas, fecha, versión, avisos, límites de captura y estado del vídeo
activity-log.json	Registro estructurado de acciones del navegador
activity-log-readable.txt	Versión legible del registro, útil para revisar la historia de la sesión
network-log.json	Peticiones HTTP con tiempos, redirecciones y errores
screenshots/	Capturas asociadas a acciones significativas
video.mp4	Grabación de pantalla
video-manifest.json	Estado del MP4, duración activa, fragmentos guardados y posibles errores
transcription.json	Texto, segmentos y palabras con sus tiempos, si se ha configurado OpenRouter
transcription.srt	Subtítulos creados con los segmentos de la transcripción
transcription-status.json	Resultado de las peticiones de transcripción y posibles fallos
README-FOR-LLM.md	Instrucciones para que el agente entienda el paquete

El archivo más importante para el workflow es network-log.json, porque SOCIA valida los pasos del alumnado a partir de peticiones reales. Para la guía, en cambio, pesan más activity-log-readable.txt, las capturas y la transcripción.

Alcance del registro de red

network-log.json no es un HAR completo. Registra las llamadas hechas con fetch, XHR y sendBeacon, pero no tráfico de workers, WebSocket o SSE.

Convertir la grabación en un workflow JSON

El primer producto que suele salir de una grabación es el workflow.json. Ese archivo es el caso que después se carga en SOCIA o en el panel web para lanzarlo al alumnado.

Para generarlo se usa la skill workflow-generator, incluida en el repositorio en apps/skills/workflow-generator. La idea es adjuntar el ZIP de MENTORA al agente y pedirle que use la skill correspondiente para generar el workflow. La grabación puede entregarse como ZIP o como carpeta descomprimida, y la skill le proporciona las instrucciones para transformar las peticiones de red en diferentes fases e hitos.

La skill cruza los tiempos de las peticiones, las acciones y la voz. La explicación del profesorado sirve para entender la intención, redactar el contexto y preparar las pistas. Normalmente, cada hito debe corresponder a una petición válida de network-log.json.

Se recomienda usar un agente potente, como Codex o Claude, ya que los resultados serán mejores. La instalación de la skill depende del sistema que uses. Por ejemplo, en las releases del repositorio puedes encontrar el archivo .skill, que se instala directamente en Claude abriendo el archivo con su aplicación de escritorio.

Revisión docente

El JSON generado debe probarse siempre en SOCIA antes de usarlo con alumnado. La automatización reduce mucho el trabajo, pero no elimina la validación del funcionamiento del caso.

Crear una guía paso a paso

El segundo producto posible es una guía didáctica en PDF. En este caso se usa la skill guide-generator, ubicada en apps/skills/guide-generator.

La guía se puede utilizar como material didáctico para que el alumnado aprenda a resolver el caso y los conceptos teóricos asociados, así como para qué sirve cada uno de los parámetros.

La skill trabaja a partir del mismo ZIP de MENTORA, pero utiliza otros elementos. Observa la línea temporal, selecciona capturas, decide las fases, redacta los pasos y aplica una identidad visual del centro o del proyecto. El resultado esperado es un PDF con portada, índice, pasos ilustrados y demás.

Si existe transcription.json, la skill usa los tiempos de sus segmentos y palabras para relacionar cada explicación con la acción y la captura correctas. Si la transcripción está incompleta, consulta transcription-status.json y rellena los huecos con el SRT, el registro de acciones o el vídeo.

La idea es adjuntar el ZIP al agente y pedirle que use la skill guide-generator para crear la guía. Un buen uso de la guía es generar primero una versión amplia y después revisarla con ojo crítico, pudiendo pedirle al agente que itere haciendo las modificaciones que prefieras hacer.

Ejemplo de guía paso a paso generada a partir de una grabación de MENTORA.

Ejemplo completo

Los cinco archivos siguientes parten de la misma grabación de una respuesta a un ataque de fuerza bruta por SSH. Puedes descargar la grabación y comparar las guías que crearon dos agentes con la misma fuente usando la skill sin iteraciones, así como revisar los casos generados:

• Grabación original de MENTORA (ZIP, 139,6 MiB)
• Guía creada con Claude Code y Opus 5 (PDF, 22 páginas)
• Guía creada con Codex y GPT-5.6 Sol, razonamiento xhigh (PDF, 12 páginas)
• Workflow creado con Claude Code y Opus 5
• Workflow creado con Codex y GPT-5.6 Sol, razonamiento xhigh

Los agentes pueden elegir otra estructura, extensión o selección de capturas. Por eso las dos guías son distintas, aunque parten del mismo material. De la misma forma, aunque ambos son JSON válidos para SOCIA, los agentes han tomado decisiones diferentes en su generación.

Flujo recomendado

El flujo completo queda así:

1. Preparar el caso y resolverlo una vez con MENTORA grabando.
2. Descargar y conservar el ZIP original.
3. Usar workflow-generator para crear el workflow.json.
4. Validar el JSON con el script de la skill.
5. Probar el caso en SOCIA como si fuera un estudiante.
6. Usar guide-generator para crear la guía paso a paso.
7. Revisar la guía, especialmente capturas, valores concretos y explicaciones.
8. Subir el workflow al panel web y compartir la guía si se quiere usar como material de apoyo.

Si quieres compartirlo con la comunidad, haz un Pull Request al repositorio siguiendo estas instrucciones.

No hay que confundir la grabación con el producto final. MENTORA captura la resolución docente y las skills la convierten en materiales que se pueden revisar, probar y publicar.