README_ES.md

 

DeepTutor: Tutoría Personalizada de Por Vida

 

                     

Características · Comenzar · Explorar · CLI · Ecosistema · Comunidad

---

🤝 ¡Damos la bienvenida a cualquier tipo de contribución! Vota en los elementos del roadmap o propone nuevos en Roadmap, y consulta nuestra Guía de Contribución para la estrategia de ramas, estándares de código y cómo comenzar.

📰 Noticias

• 2026-09-20 🎉 ¡40k estrellas en 9 meses! Seguiremos ampliando el ecosistema de aprendizaje de DeepTutor.
• 2026-05-22 🌐 Sitio de documentación oficial disponible en deeptutor.info — guías, referencias y tours de capacidades, todo en un solo lugar.
• 2026-04-19 🎉 ¡20k estrellas en 111 días! Gracias por el apoyo hacia una tutoría verdaderamente personalizada e inteligente.
• 2026-04-10 📄 Nuestro artículo ya está en arXiv — lee el preprint para conocer el diseño y las ideas detrás de DeepTutor.
• 2026-02-06 🚀 ¡10k estrellas en solo 39 días! Un enorme agradecimiento a nuestra increíble comunidad.
• 2026-01-01 🎊 ¡Feliz Año Nuevo! Únete a nuestro Discord, WeChat o Discussions — juntos demos forma al futuro de DeepTutor.
• 2025-12-29 🎓 ¡DeepTutor está oficialmente lanzado!

✨ Características Principales

DeepTutor es un espacio de trabajo de aprendizaje nativo de agentes que conecta tutoría, resolución de problemas, generación de cuestionarios, investigación, visualización y práctica de dominio en un sistema extensible.

• Un runtime para todos los modos — Chat, Ask Questions, Quiz, Research, Visualize, Solve, Course Study, Mastery Path, Immersive Reading y Audio Overview comparten un mismo runtime de capacidades y contexto de sesión, pero conservan bucles y pipelines especializados para cada propósito.
• Task Board — Sigue las tareas de estudio en To do, In progress y Done, con notas, movimientos mediante arrastrar y soltar o botones accesibles desde el teclado, y un archivo desde el que puedes restaurarlas. Las tarjetas permanecen en el espacio de trabajo actual y respetan la configuración existente de apariencia e idioma; no se requiere configurar ningún modelo.
• Contexto de aprendizaje conectado — Las bases de conocimiento, los libros, los borradores de Co-Writer, los cuadernos, los bancos de preguntas, las personas y Memory pueden reutilizarse en los flujos de trabajo que los admiten, sujetos a los permisos de la cuenta y a las políticas de aprendizaje.
• Aprendizaje inmersivo por vídeo — añade enlaces de YouTube o Bilibili a Reading para reproducirlos de forma nativa, buscar en las transcripciones, recibir tutoría basada en marcas de tiempo, guardar notas y reanudar el progreso; los subtítulos y la exploración de YouTube pueden usar una instancia de Invidious configurada por el administrador.
• Subagentes y Partners — desde Chat, consulta un entorno de agente en vivo (Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo, Hermes, OpenClaw o DeepSeek) o un Partner, importa conversaciones pasadas y ejecuta compañeros IM persistentes con el mismo cerebro.
• Conocimiento multi-motor — bibliotecas RAG con versiones: LlamaIndex, PageIndex, GraphRAG, LightRAG, un LightRAG Server remoto, una base de conocimiento WeKnora autoalojada, una biblioteca de Tencent IMA o MarginNote 4, un archivo Kiwix ZIM conectado, o un vault Obsidian vinculado, con análisis de documentos conectable. Consulta los modelos de rol nativos de LightRAG para conocer la configuración independiente de extracción, consulta y visión, la creación limitada a valores predeterminados y las reconstrucciones confirmadas.
• Herramientas y habilidades extensibles — herramientas integradas, servidores MCP, aplicaciones CLI, modelos de generación de imagen / video / voz, y skills de la comunidad instalables desde EduHub.
• Memoria inspectable — las trazas L1, los resúmenes de superficie L2 y la síntesis L3 hacen visible y editable la personalización; el Memory Graph vincula los hechos L2 con la evidencia L1 y la síntesis L3 con las superficies que contribuyeron a ella.

---

🚀 Comenzar

Deja que tu Agente Configure DeepTutor

Copia este prompt en tu agente de IA con acceso a la terminal (como Codex o Claude Code):

Help me install and configure DeepTutor locally from https://github.com/HKUDS/DeepTutor.
Clone the repository, or reuse my existing checkout, and read SKILL.md and
docs-for-user/AGENT_SETUP.md first. Follow that guide to prepare the environment,
configure my model provider, verify the setup, and start the Web app.
Ask me for any missing provider, model, or credential-source information;
do not print API keys. Preserve my existing files and settings, and finish
with the access URL and the results of your checks.

La guía de configuración para agentes abarca todo el proceso, incluida la configuración no interactiva desde la CLI. Para instalarlo tú mismo, elige una de las rutas siguientes.

DeepTutor incluye cuatro rutas de instalación. Todas comparten un mismo diseño de hogar de ejecución: la configuración privada vive en data/user/settings/ bajo el directorio desde el que se inicia (o bajo DEEPTUTOR_HOME / deeptutor start --home si se establece explícitamente). Para la aplicación completa, el flujo recomendado es elegir un directorio de hogar de ejecución → instalar → deeptutor init → deeptutor start.

Prueba de Docker con un Solo Comando

Si todavía no tienes Docker instalado, instala Docker primero. Después prueba la aplicación completa sin configurar Python ni Node.js:

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

Abre http://127.0.0.1:3782, configura los proveedores de modelos en Settings → Providers y pulsa Ctrl+C cuando termines. El volumen con nombre deeptutor-data conserva la configuración y los datos locales para la próxima ejecución.

Espacio de Trabajo de Contenido

El Espacio de Trabajo de Contenido es independiente del hogar de ejecución privado de DeepTutor. Es la carpeta que los agentes pueden leer, con los archivos generados bajo outputs/<capability>/<session>/<turn>/. Los espacios de trabajo personalizados aíslan conversaciones, materiales de aprendizaje, progreso y cachés en un árbol privado .deeptutor/data/ que las herramientas de archivos no pueden explorar. La configuración, las credenciales y Memory siguen compartiéndose a nivel de cuenta.

Sin configuración, el espacio de trabajo de contenido es <runtime-home>/data/user/workspace. Las instalaciones locales de PyPI, CLI y desde código fuente pueden elegir carpetas en Settings → Workspaces; establece la carpeta predeterminada con:

deeptutor workspace show
deeptutor workspace set /absolute/path/to/my-folder
deeptutor workspace reset

Las capacidades inspeccionan el espacio de trabajo seleccionado a través de las herramientas de espacio de trabajo integradas. El modelo solo recibe rutas relativas como outputs/...; cuando usa workspace_present, la interfaz renderiza una instantánea autenticada y abrible. Esa misma ruta relativa exacta también funciona en un enlace o imagen Markdown normal. Cambiar el archivo de origen más tarde no cambia una instantánea ya presentada.

El Espacio de Aprendizaje gestiona la biblioteca de recursos. En Settings → Workspaces, asigna Skills, servicios MCP y bases de conocimiento a cada espacio de trabajo, o conserva sus reglas de acceso actuales. Los espacios existentes mantienen su acceso hasta que se guarda una selección. Las asignaciones hacen referencia a los recursos originales sin copiar credenciales ni índices de conocimiento; las skills específicas del espacio de trabajo pueden sustituir las versiones compartidas. Consulta las asignaciones de recursos del espacio de trabajo.

La ejecución es de solo lectura fuera de outputs/. Copiar un archivo generado a otro lugar dentro del espacio de trabajo de contenido requiere una confirmación explícita de Allow once para ese origen y destino exactos. Un sandbox del sistema o el runner de Docker impone este límite cuando está disponible; el fallback local de subproceso restringido se muestra como mejor esfuerzo en la configuración de Workspace.

Opción 1 — Instalar desde PyPI · aplicación web local completa + CLI, sin necesidad de clonar

Aplicación web local completa + CLI, sin necesidad de clonar. Requiere Python 3.11–3.14 y un runtime Node.js 20+ en PATH (el servidor standalone Next.js empaquetado es iniciado por deeptutor start).

mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init     # prompts for ports + LLM provider + optional embedding/search
deeptutor start    # starts backend + frontend; keep the terminal open

deeptutor init solicita el puerto de backend (predeterminado 8001), el puerto de frontend (predeterminado 3782), proveedor LLM / URL base / clave API / modelo, un proveedor de embeddings opcional para Base de Conocimiento / RAG y un proveedor de búsqueda opcional para Web Search.

Después de deeptutor start, abre la URL del frontend impresa en la terminal — por defecto http://127.0.0.1:3782. Presiona Ctrl+C en esa terminal para detener tanto el backend como el frontend. Omitir deeptutor init está bien para una prueba rápida; la aplicación arranca con puertos predeterminados y configuración de modelo vacía, configúralos luego en Settings → Providers y Language models.

Transcripción del micrófono del navegador: los adaptadores STT compatibles con OpenAI envían el audio del navegador al proveedor sin conversión local. Los adaptadores STT nativos de DashScope y Volcengine convierten el WebM/Opus del navegador a WAV de 16 kHz y requieren un ejecutable ffmpeg en el PATH de DeepTutor. Un WAV PCM mono canónico de 16 kHz omite esta conversión. En instalaciones PyPI de Windows que utilicen cualquiera de los dos adaptadores nativos, instala FFmpeg, agrega su directorio bin al PATH del servicio y reinicia DeepTutor. Los errores de conversión aparecen debajo del campo de entrada del chat.

Opción 2 — Instalar desde el Código Fuente · desarrollar contra un checkout

Para desarrollo en un checkout. Usa Python 3.11–3.14 y Node.js 22 LTS para coincidir con CI y Docker.

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

# Create a venv (macOS/Linux). Windows PowerShell:
#   py -3.11 -m venv .venv ; .\.venv\Scripts\Activate.ps1
python3 -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip

# Install backend + frontend deps
python -m pip install -e .
( cd web && npm ci --legacy-peer-deps )

deeptutor init
deeptutor start --dev

deeptutor start compila el frontend web/ local para producción una vez y lo reutiliza; --dev ejecuta Next.js con HMR (recarga en caliente de módulos). El diseño de configuración, los puertos y Ctrl+C coinciden con la Opción 1.

Entorno Conda (en lugar de venv)

conda create -n deeptutor python=3.11
conda activate deeptutor
python -m pip install --upgrade pip

Extras de instalación opcionales — motores RAG / dev / partners / matrix / math-animator

pip install -e ".[rag-lightrag]"    # Built-in LightRAG engine (exact supported SDK)
pip install -e ".[graphrag]"        # Microsoft GraphRAG engine (Python 3.11–3.13)
pip install -e ".[dev]"             # tests/lint tools
pip install -e ".[partners]"        # Partner IM channel SDKs
pip install -e ".[video-learning]"  # compatibility extra; captions ship in the full/CLI installs
pip install -e ".[matrix]"          # Matrix channel without E2EE/libolm
pip install -e ".[matrix-e2e]"      # Matrix E2EE; requires libolm
pip install -e ".[math-animator]"   # Manim addon; requires LaTeX/ffmpeg/system libs

Ajustes de dependencias del frontend y solución de problemas del servidor de desarrollo

Cambiar dependencias del frontend: ejecuta npm install --legacy-peer-deps para actualizar web/package-lock.json, luego confirma tanto web/package.json como web/package-lock.json.

Servidor de desarrollo atascado: si deeptutor start --dev informa de un frontend existente que no responde, detén el PID que imprime. Si no hay ningún proceso Next.js en ejecución, los archivos de bloqueo están obsoletos — elimínalos y vuelve a intentarlo:

rm -f web/.next/dev/lock web/.next/lock
deeptutor start --dev

Opción 3 — Docker · un contenedor autocontenido

Un contenedor para la aplicación web completa. Imágenes en GitHub Container Registry:

• ghcr.io/hkuds/deeptutor:latest — versión estable más reciente
• ghcr.io/hkuds/deeptutor:<version> — versión exacta sin la v inicial (por ejemplo, :1.6.3); las versiones preliminares reciben únicamente su etiqueta de versión

Consulta CONTAINERIZATION.md para despliegues con podman/rootless/sistema de archivos raíz de solo lectura y la guía completa por instalación.

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

Para elegir una carpeta de contenido del host al iniciar el contenedor, móntala en la ruta estable del contenedor y fija DeepTutor a esa ruta:

mkdir -p "$PWD/deeptutor-workspace/outputs"
docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v deeptutor-data:/app/data \
  -v "$PWD/deeptutor-workspace:/workspace" \
  -e DEEPTUTOR_WORKSPACE_ROOT=/workspace \
  -e DEEPTUTOR_WORKSPACE_ALLOWED_ROOTS=/workspace \
  ghcr.io/hkuds/deeptutor:latest

Para Compose, establece DEEPTUTOR_WORKSPACE_HOST=/absolute/host/folder antes de ejecutar python scripts/docker_compose.py up -d. Cuando se omite, se usa ./data/user/workspace. Las rutas de Docker se seleccionan al iniciar y por eso aparecen bloqueadas en la página de configuración web.

Solo se necesita publicar 3782. El navegador habla exclusivamente con el origen del frontend; el middleware de Next.js (web/proxy.ts) reenvía /api/* y /ws/* al backend FastAPI dentro del contenedor. Publicar 8001 (-p 127.0.0.1:8001:8001) es opcional — útil solo para acceder a la API directamente con curl o scripts.

Abre http://127.0.0.1:3782. El contenedor crea /app/data/user/settings/*.json en el primer arranque; configura los proveedores de modelos desde la página de Settings web. La configuración, las claves API, los registros, el Espacio de Trabajo de Contenido predeterminado, la memoria y las bases de conocimiento persisten en el volumen deeptutor-data. Un Espacio de Trabajo de Contenido montado por separado persiste en su ruta del host en su lugar. Los extras opcionales pertenecen al despliegue, no a una shell: establece DEEPTUTOR_EXTRAS (y DEEPTUTOR_APT_PACKAGES para bibliotecas de sistema) y cada contenedor iniciado a partir de él los vuelve a aplicar, mientras que un docker exec … pip install se perdería en el siguiente compose down.

• Puertos de host diferentes: cambia el lado izquierdo de cada mapeo -p host:container (ej. -p 127.0.0.1:8088:3782). Si cambias los puertos del lado del contenedor en /app/data/user/settings/system.json, reinicia y actualiza el lado derecho de cada mapeo para que coincida.
• Desconectado: agrega -d, luego docker logs -f deeptutor para seguir, docker stop deeptutor para detener, docker rm deeptutor antes de reutilizar el nombre. El volumen deeptutor-data mantiene los datos privados de runtime y el Espacio de Trabajo de Contenido predeterminado entre reinicios; un Espacio de Trabajo de Contenido montado por separado persiste en su ruta del host.

Docker remoto / proxy inverso: el navegador solo habla con el origen del frontend (:3782); el middleware de Next.js dentro del contenedor reenvía /api/* y /ws/* al servidor backend del lado del servidor. Para el caso común de contenedor único no necesitas configurar ninguna base de API — simplemente apunta tu proxy inverso / terminador TLS a :3782. Solo necesitas una base de API para un despliegue dividido (backend en un contenedor/host separado): establece next_public_api_base en data/user/settings/system.json con la dirección en red que el servidor frontend usa para llegar al backend (se lee del lado del servidor, nunca se envía al navegador).

{
  "next_public_api_base": "http://backend:8001"
}

next_public_api_base_external (y su alias public_api_base) se aceptan como alternativas de menor precedencia. CORS usa orígenes de frontend, no URLs de API. Con la autenticación deshabilitada, DeepTutor permite los orígenes normales de navegador HTTP/HTTPS por defecto. Con la autenticación habilitada, agrega los orígenes exactos del frontend:

{
  "cors_origins": ["https://deeptutor.example.com"]
}

Conectarse a Ollama / LM Studio / llama.cpp / vLLM / Lemonade en el host

Dentro de Docker, localhost es el propio contenedor, no tu máquina host. Para llegar a un servicio de modelo que se ejecuta en el host, usa la puerta de enlace del host (recomendado):

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 -p 127.0.0.1:8001:8001 \
  --add-host=host.docker.internal:host-gateway \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

Luego en Settings → Providers, apunta la URL Base del proveedor a host.docker.internal:

• Ollama LLM: http://host.docker.internal:11434/v1
• Ollama embedding: http://host.docker.internal:11434/api/embed
• LM Studio: http://host.docker.internal:1234/v1
• llama.cpp: http://host.docker.internal:8080/v1
• Lemonade: http://host.docker.internal:13305/api/v1

Docker Desktop (macOS/Windows) generalmente resuelve host.docker.internal sin --add-host. En Linux, el flag es la forma portátil de crear ese nombre de host en Docker Engine moderno.

Alternativa para Linux — red del host: agrega --network=host y elimina los flags -p. El contenedor comparte la red del host directamente, así que abre http://127.0.0.1:3782 (o el frontend_port en system.json), y los servicios del host se pueden alcanzar con URLs de localhost normales como http://127.0.0.1:11434/v1. Ten en cuenta que la red del host expone los puertos del contenedor directamente en el host y puede entrar en conflicto con servicios existentes — para mantenerlos en loopback, establece BACKEND_HOST=127.0.0.1 y FRONTEND_HOST=127.0.0.1 (consulta CONTAINERIZATION.md).

Opción 4 — Solo CLI · sin UI web, desde un checkout de fuente

Cuando no necesitas la UI web. El paquete de solo CLI se instala desde un checkout de fuente, no desde PyPI.

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

# Create a venv (macOS/Linux). Windows PowerShell:
#   py -3.11 -m venv .venv-cli ; .\.venv-cli\Scripts\Activate.ps1
python3 -m venv .venv-cli && source .venv-cli/bin/activate
python -m pip install --upgrade pip

python -m pip install -e ./packaging/deeptutor-cli
deeptutor init --cli
deeptutor chat

deeptutor init --cli comparte el mismo diseño data/user/settings/ que la aplicación completa, pero omite las solicitudes de puertos de backend/frontend. Sigue ofreciendo los selectores Embedding y Search (elige Skip cuando no los necesites), escribe los archivos clave de runtime (system.json, auth.json, integrations.json, interface.json, model_catalog.json, main.yaml, agents.yaml) y solicita el proveedor LLM y el modelo activos.

Comandos comunes

deeptutor chat                                          # interactive REPL
deeptutor chat --capability deep_solve --tool rag --kb my-kb
deeptutor run chat "Explain Fourier transform"
deeptutor run deep_solve "Solve x^2 = 4" --tool rag --kb my-kb
deeptutor kb create my-kb --doc textbook.pdf
deeptutor memory show
deeptutor config show

La instalación local de deeptutor-cli no incluye activos web ni dependencias de servidor. Mantén el checkout de fuente cerca — la instalación editable apunta a él. Para agregar la aplicación web más tarde, instala el paquete PyPI (Opción 1) y ejecuta deeptutor init + deeptutor start desde el mismo espacio de trabajo.

Sandbox de Ejecución de Código (skills de oficina) · ejecutar código generado por el modelo para docx / pdf / pptx / xlsx

Las skills de oficina integradas — docx / pdf / pptx / xlsx — funcionan haciendo que el modelo escriba un script Python corto (python-docx, reportlab, openpyxl, …), lo ejecute a través de la única herramienta exec y presente el archivo del espacio de trabajo guardado. Esas herramientas se montan siempre que haya un backend de sandbox activo. DeepTutor selecciona el backend configurado más sólido en este orden:

• Runner sidecar: DEEPTUTOR_SANDBOX_RUNNER_URL dirige la ejecución al servicio endurecido y con privilegios mínimos de Dockerfile.runner.
• Linux bubblewrap: cuando está disponible, bwrap aísla el proceso y los archivos.
• Fallback de subproceso restringido: las instalaciones locales y de contenedor único solo lo usan cuando está permitido; bajo Docker, el contenedor sigue siendo otra barrera.

La configuración sandbox_allow_subprocess de data/user/settings/system.json (predeterminada en true) controla únicamente el último fallback. Establécela en false (o exporta DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=0) para rechazar la ejecución mediante subprocesos cuando no haya un backend runner o bwrap; no desactiva esos backends más sólidos.

Referencia de configuración — archivos de configuración bajo data/user/settings/ (JSON/YAML)

Todo bajo data/user/settings/ es JSON/YAML plano. La página Settings es el editor recomendado; los registros de espacios de trabajo se guardan aparte en data/user/.runtime/workspaces.sqlite3.

Archivo	Propósito
model_catalog.json	Conexiones de proveedores, además de perfiles LLM, de tareas, embeddings, búsqueda, TTS, STT, imagen y vídeo, credenciales y selecciones activas
system.json	Puertos de backend/frontend, base de API pública, CORS, verificación SSL, directorio de adjuntos y límites de subida/extracción
auth.json	Interruptor de autenticación opcional, nombre de usuario, hash de contraseña, configuración de token/cookie
integrations.json	Configuración opcional de PocketBase e integraciones sidecar
interface.json	Idioma de UI y de salida del modelo / tema / preferencias de barra lateral
document_parsing.json	Selección del motor de análisis y del modelo de descripción de imágenes, endpoints remotos y opciones específicas de cada motor
video_learning.json	Proveedor de subtítulos de YouTube, orígenes y acceso a cuentas de Invidious, y configuración de transcripciones
main.yaml	Valores predeterminados de comportamiento de runtime e inyección de rutas
agents.yaml	Configuración de temperatura y tokens de capacidades/herramientas

Las referencias de Web Search se filtran de forma predeterminada: solo se muestran URL públicas http/https sin credenciales incrustadas ni puertos inusuales. Los despliegues pueden añadir una política de dominios centrada en la educación en data/user/settings/system.json:

{
  "web_search_source_filtering": {
    "enabled": true,
    "blocked_domains": ["spam.example"],
    "trusted_domains": ["edu.cn", "arxiv.org"]
  }
}

Cuando trusted_domains no está vacío, las referencias se limitan a esos dominios y sus subdominios; blocked_domains siempre tiene prioridad.

El .env de la raíz del proyecto no se lee como archivo de configuración de la aplicación. Para una configuración mínima del modelo, guarda una URL Base y una clave API en Settings → Providers, luego agrega y selecciona un LLM en Language models. Agrega un perfil de embeddings solo si planeas usar funciones de Base de Conocimiento / RAG.

Para API Route, selecciona API Route en Settings → Providers e introduce una clave de API Route. El ajuste predefinido usa https://global.api-route.com/v1; después añade un modelo con su ID de modelo de API Route en Language models. Consulta la guía de inicio rápido de API Route para configurar la clave y el modelo.

Los perfiles de LLM y de modelos de tareas ofrecen una opción de formato de API cuando su proveedor admite distintas alternativas. Mantén Auto para el enrutamiento y el fallback normales, o elige OpenAI Chat Completions, OpenAI Responses o Anthropic Messages; el modo Responses forzado sigue fallando de forma cerrada. El campo persistido es api_format (auto, openai_chat, openai_responses o anthropic); wire_api es un estado de compatibilidad derivado. Los ajustes por modelo Auto / Supported / Not supported abarcan las llamadas a herramientas, la entrada de imágenes, la salida JSON y los controles de razonamiento.

Desinstalación y limpieza

DeepTutor separa su código instalado, su hogar de ejecución privado y el Espacio de Trabajo de Contenido opcional. De forma predeterminada, el hogar de ejecución es el directorio donde ejecutas deeptutor init / deeptutor start; --home PATH o DEEPTUTOR_HOME lo sobrescriben. El estado privado de la aplicación es el directorio data dentro de ese hogar, por lo que la línea del banner de inicio que comienza con Workspace: identifica esa ubicación de ejecución. Si Settings → Workspace apunta a otra carpeta, haz una copia de seguridad o elimina esa carpeta de contenido por separado; intencionalmente no se borra al desinstalar DeepTutor.

1. Detén la aplicación. Presiona Ctrl+C en la terminal que ejecuta deeptutor start, o ejecuta deeptutor stop [--home PATH] para un launcher iniciado con --detach; detén cualquier Partner en ejecución y los contenedores Docker separados antes de eliminar datos.

2. Elimina los datos de runtime solo si también quieres borrar todo el estado local. Esto incluye la configuración y las claves API, el historial de chat, las sesiones, Memory, Notebooks, Books, el estado de Reading, Skills, el estado de Partners, los registros, las Knowledge Bases, las cachés de análisis, los artefactos generados y la caché de runtime del frontend empaquetado.

   Primero copia la ruta exacta de Workspace: del banner de inicio y comprueba que su elemento hijo data sea el directorio de datos de DeepTutor previsto. Haz una copia de seguridad si pudieras necesitar algo más adelante y, después, mueve ese directorio exacto a la Papelera de tu sistema operativo. No ejecutes un comando de eliminación recursiva contra una ruta relativa ni una variable de entorno sin resolver.

3. Elimina el paquete instalado. Usa el comando correspondiente a la distribución:

   python -m pip uninstall deeptutor
   python -m pip uninstall deeptutor-cli

   Si el entorno virtual se creó solo para DeepTutor, elimínalo mediante tu gestor de entornos. Para una instalación desde el código fuente, desactiva el entorno, sal del directorio fuente y ejecuta git status --short dentro de ese checkout exacto. Mueve el checkout a la Papelera únicamente después de confirmar que no contiene trabajo ajeno o sin confirmar.

4. Para la ruta de Docker, inspecciona el contenedor y el volumen con nombre exactos antes de eliminarlos. Eliminar el volumen borra de forma permanente los datos administrados por Docker:

   docker ps -a --filter name=^/deeptutor$
   docker volume inspect deeptutor-data
   docker rm -f deeptutor
   docker volume rm deeptutor-data

📖 Explorar DeepTutor

Comienza con las superficies principales que usarás día a día: Chat, Partners, Mis Agentes, Co-Writer, Book, Centro de Conocimiento, Espacio de Aprendizaje, Memory y Settings. El tour luego cubre los despliegues Multi-Usuario para espacios de trabajo compartidos y aislados.

Si una respuesta pierde una restricción anterior, cita evidencia débil o contradice el material seleccionado, recopila los diagnósticos de REASONING_SAFETY_CHECKLIST.md antes de abrir un issue.

Estado de las capturas: la vista general está actualizada para v1.6.5. Las capturas de superficies siguientes siguen siendo referencias de v1.4.6 mientras se realiza la actualización. Úsalas para entender los flujos, no como navegación exacta actual.

🏗️ Arquitectura del sistema

💬 Chat — El Bucle de Agente que Realmente Usas

Chat es la capacidad predeterminada y el lugar donde comienza la mayor parte del trabajo. Un único hilo puede conversar normalmente, llamar herramientas, fundamentarse en bases de conocimiento seleccionadas, leer adjuntos, generar imágenes, consultar subagentes, escribir registros de notebook y continuar con el mismo contexto entre turnos.

El bucle es deliberadamente simple: el modelo piensa en rondas, llama herramientas cuando es útil, observa los resultados y termina con un mensaje sin herramientas. ask_user es especial — en lugar de adivinar, el agente puede pausar el turno, hacer una pregunta de aclaración estructurada y reanudar una vez que respondes.

Las herramientas activables por el usuario son brainstorm, web_search, paper_search, zotero_search, reason y geogebra_analysis — más imagegen y videogen una vez que configures el modelo de generación correspondiente. Las herramientas contextuales como rag, kb_files, knowledge_frontier, read_source, read_memory, write_memory, read_skill, load_tools, exec, web_fetch, ask_user, list_notebook, write_note, question_bank, github, consult_subagent, workspace_list, workspace_read, workspace_search, workspace_present y workspace_export se montan automáticamente cuando el turno tiene el contexto adecuado.

El contexto viene en dos tipos: el contexto de sesión persistente (capacidad, espacio de trabajo o curso, herramientas, bases de conocimiento, persona, modelo y estado de Reading / Mastery) persiste entre turnos; las referencias de un solo uso (archivos, historial de chat, libros, secciones de lectura, cuadernos, entradas seleccionadas del banco de preguntas, agentes importados) vienen del menú + para un único turno. El botón de voz solo transcribe el mensaje actual.

Inicio mantiene Chat, Ask Questions, Quiz y Visualize a un clic; Research para informes con citas y Solve para razonamiento trabajado se encuentran bajo More Capabilities. Aprendizaje personalizado agrupa Book, Mastery Path, Immersive Reading y Práctica; Reading reúne documentos, vídeo y audio con citas verificadas, notas guardadas, lectura natural en voz alta de pasajes de la fuente / acciones de orientación de estudio / vocabulario / quiz / traducción y captura en notebooks, mientras que Course Study mantiene su propio contexto vinculado al curso.

🤝 Partner — Compañeros Persistentes con el Mismo Cerebro

Los Partners son compañeros persistentes con su propio alma, política de modelo, biblioteca, memoria y canales. No son un motor de bot separado: cada mensaje web o IM entrante se convierte en un turno normal de ChatOrchestrator dentro de un espacio de trabajo con alcance de partner. Un partner es "un chat que tiene personalidad y número de teléfono."

Cada partner tiene un SOUL.md, selección de modelo, canales, política de herramientas y biblioteca asignada. Su biblioteca puede copiar bases de conocimiento, skills y notebooks en data/partners/<id>/workspace/, o permanecer vinculada a los archivos y recursos de un espacio de trabajo existente; la identidad, las conversaciones y la memoria del Partner siguen separadas. Los usuarios autenticados que no son administradores conservan sesiones privadas de Partner y memoria de relación, mientras el Partner lee su memoria personal en modo de solo lectura; el tráfico de administradores, grupos y usuarios no vinculados utiliza el ámbito compartido del Partner.

La capa de canales está impulsada por esquema y puede conectarse a plataformas IM como Feishu, Telegram, Slack, Discord, DingTalk, QQ/NapCat, WeCom, WhatsApp, Zulip, Mattermost, Matrix, Mochat y Microsoft Teams dependiendo de los extras instalados y las credenciales configuradas. Un partner también puede conectarse como subagente y ser consultado desde un turno de chat normal — consulta Mis Agentes a continuación.

Para una configuración más rápida, la página de canales de Partner puede crear una app de Feishu/Lark o un bot IA de WeCom, o iniciar sesión con una cuenta personal de WeChat, a partir de un código QR dibujado en el navegador en lugar del registro del servidor. Feishu/Lark detecta el dominio de la cuenta y guarda al usuario que escanea como el remitente permitido inicial. WeCom conserva una lista blanca existente y de lo contrario predetermina a todos los usuarios que pueden alcanzar al bot, con una advertencia visible de acceso abierto; los formularios de canal manuales siguen disponibles si el protocolo de escaneo de un proveedor cambia.

🧑‍🚀 Mis Agentes — Consultar e Importar Otros Agentes

Mis Agentes convierte a otros agentes en contexto para DeepTutor y hace dos cosas distintas. Conectar un agente en vivo — Claude Code, Codex, Grok CLI, Antigravity, Kimi, opencode, MiMo Code, Hermes Agent, OpenClaw o DeepSeek Harness en tu máquina, una pasarela remota de Hermes o uno de tus Partners — y consultarlo desde dentro de un turno de chat: DeepTutor realmente ejecuta el otro agente y transmite su trabajo al panel de Activity a través de la herramienta consult_subagent. Selecciónalo y establece su límite de rondas con el chip Agent, o filtra la misma lista de agentes conectados con @; la selección permanece vinculada a la sesión.

Conectar Grok CLI. Instala Grok CLI de xAI en la máquina que ejecuta el backend de DeepTutor, ejecuta grok login ahí, y verifica que grok --help liste --output-format streaming-json. Luego abre Mis Agentes → Conectar, selecciona Grok CLI, y elige un directorio de trabajo. La detección comprueba el soporte de protocolo del ejecutable; no verifica el inicio de sesión ni el acceso al modelo. El conector se ha probado con Grok CLI 1.0.3; otros comandos de terceros no relacionados que también se llaman grok no son compatibles.

En Settings → Partners y agentes → Grok CLI, deja el modelo y el esfuerzo de razonamiento vacíos para usar los valores predeterminados de la CLI, o introduce valores admitidos por la salida de grok models de tu cuenta. Las instrucciones del sistema se pasan a través de --rules. El modo de permisos predeterminado es dontAsk: Grok usa sus propias reglas existentes y su manejo integrado de solo lectura, y rechaza las operaciones que necesitan aprobación. Esta es una política de permisos de la CLI, no un sandbox del sistema de archivos. Se pueden seleccionar modos más amplios explícitamente en la configuración; los flags avanzados de la CLI permanecen disponibles a través de backends.grok.extra_args en la API de configuración de subagentes.

Grok usa su propia autenticación y almacenamiento de sesión; DeepTutor no copia sus credenciales. Las consultas de seguimiento reanudan la sesión de la conexión en el mismo directorio de trabajo. El texto y la actividad de herramientas se transmiten en vivo; las cargas de pensamiento privado se omiten. La memoria de Grok entre sesiones está desactivada por defecto. Este conector admite preguntas de texto y herramientas de CLI, no el envío de imágenes ni la importación de conversaciones pasadas de Grok. En Docker, instala y autentica Grok dentro del contenedor del backend; una CLI instalada solo en la máquina del navegador no es accesible.

Importar conversaciones pasadas — trae tu historial existente de ChatGPT, Claude Code y Codex como conversaciones buscables y reanudables. Selecciona conversations.json de una exportación de datos oficial de ChatGPT para una importación de instantánea segura e idempotente, elige el historial de Claude por proyecto / directorio de trabajo, o elige el historial de Codex por fecha del calendario. Los agentes basados en carpetas siguen siendo actualizables, de modo que su ámbito seleccionado puede recuperar conversaciones nuevas. Referencia una desde un turno de Chat a través de + → Mis Agentes, y DeepTutor la lee como una transcripción de terceros — sigue siendo su conversación, no la voz propia de DeepTutor.

✍️ Co-Writer — Redacción Markdown con Conciencia de Selección

Co-Writer es un espacio de trabajo Markdown de vista dividida para informes, tutoriales, notas y artefactos de aprendizaje de formato largo. Los documentos se guardan automáticamente y renderizan una vista previa en vivo (matemáticas KaTeX, cercas de diagramas), y se pueden guardar de vuelta en cuadernos cuando un borrador se convierte en contexto reutilizable. Importa un .docx para empezar un borrador, y exporta el editor actual como Markdown o Word.

Su idea definitoria es la edición quirúrgica: selecciona un fragmento y pide a DeepTutor que lo reescriba, expanda o acorte. Elige el modelo de edición; puede usar una base de conocimiento o evidencia web y conserva un rastro de sus llamadas a herramientas. Si el borrador no ha cambiado mientras trabaja, el resultado sustituye directamente el texto seleccionado y sigue siendo reversible con Undo.

📖 Book — Libros Vivos de tus Materiales

Book convierte las fuentes seleccionadas en un libro vivo interactivo — no un PDF estático, sino un entorno de lectura construido a partir de bloques tipados. Un libro puede comenzar desde bases de conocimiento, cuadernos, bancos de preguntas o historial de chat; el flujo de creación propone un esquema de capítulos antes de que se genere el contenido, así revisas la estructura en lugar de aceptar una salida de un solo intento sin verla antes.

   

Cada capítulo se compila en bloques tipados editables — texto, callouts, quizzes, tarjetas flash, líneas de tiempo, código, figuras, HTML interactivo, animaciones, gráficos de conceptos, profundizaciones y notas de usuario — con su propio Page Chat. Inserta, mueve, regenera, reescribe o cambia el tipo de un bloque; los pasajes seleccionados entran en una bandeja revisable de capturas de aprendizaje. El progreso, los marcadores, los intentos de quiz, las capturas y Page Chat se mantienen privados para cada lector incluso cuando un libro del administrador se comparte en modo de solo lectura o edición colaborativa; la eliminación de libros compartidos sigue siendo exclusiva del administrador. Cualquier libro se exporta a Markdown, las compilaciones largas se pausan y reanudan, y deeptutor book health / refresh-fingerprints señalan divergencias en las fuentes.

📚 Centro de Conocimiento — Bibliotecas RAG Multi-Motor

Las bases de conocimiento son las colecciones de documentos detrás del RAG — fundamentan los turnos de Chat, las ediciones de Co-Writer, la generación de Book y las conversaciones de Partner. Lo que las distingue es la elección de motores de recuperación: LlamaIndex (el predeterminado, vector híbrido + BM25 con reranking opcional mediante cross-encoder e índices FAISS exact-flat o HNSW), PageIndex (recuperación por razonamiento con citas a nivel de página, hospedado o autoalojado OSS), GraphRAG y LightRAG (recuperación por grafo de conocimiento), LightRAG Server (recuperación delegada a una instancia externa de LightRAG a la que te conectas por HTTP), WeKnora (recuperación desde una base de conocimiento de tu despliegue autoalojado, sin índice local ni copia de documentos), Tencent IMA (una biblioteca que curas en IMA — consultada, explorada y con escritura de vuelta a través de su OpenAPI), MarginNote 4 (tus datos de estudio de MN4 — documentos, extractos, tarjetas de mapa mental y los enlaces entre ellos — enviados por el Add-on de la app y navegados con herramientas dedicadas), Kiwix (un archivo ZIM consultable servido por HTTP sin indexación local), o un vault Obsidian vinculado que el tutor lee y escribe en el lugar. Cada KB está vinculada a un motor.

¿Estás migrando una biblioteca existente de Obsidian, Hermes o Markdown? Consulta la guía de migración de conocimiento para conocer las rutas de vault conectado y copia indexada.

Al crear una KB, puedes crear nueva (subir e indexar documentos), vincular existente (reutilizar un índice en su ubicación) o conectar Kiwix (buscar bajo demanda en un archivo ZIM servido). Elige su espacio de trabajo de almacenamiento al crearla; una KB existente puede trasladarse entre espacios de trabajo tras una vista previa, conservando las asignaciones y las referencias guardadas. Una KB también puede rastrear repositorios de GitHub (repositorio, rama y patrón glob) o URLs de sitios de documentación (con límites de profundidad de rastreo y número de páginas, resincronizadas cada 24 h por defecto); la sincronización compara hashes para detectar contenido añadido, modificado y eliminado, de modo que la documentación que sigues se mantiene actualizada sin volver a subirla, y las carpetas vinculadas recogen archivos locales nuevos o modificados al sincronizar. La re-indexación escribe un nuevo directorio version-N plano y conserva los anteriores, de modo que un índice funcional nunca se destruye a mitad de la reconstrucción. Un solo documento puede eliminarse incluso de una base en estado de error — descartando un archivo que no se pudo analizar sin necesidad de borrar y reconstruir todo. El análisis de documentos — Text-only, MinerU, Docling, Tika, markitdown, PyMuPDF4LLM o LiteParse — y un modelo opcional de descripción de imágenes se eligen en Settings → Knowledge & documents, con descargas de modelos locales desactivadas por defecto. Docling también puede ejecutarse en modo remoto contra un servidor Docling Serve (sin necesidad de instalación local ni modelos), configurado en esa página (mode=remote, una URL base de servidor y una clave API opcional) o las variables de entorno DOCLING_MODE / DOCLING_API_BASE_URL / DOCLING_API_TOKEN. Tika es solo remoto y apunta al servidor Apache Tika configurado en esa página. La CLI refleja el ciclo de vida con list/info/create/connect-kiwix/add/search/eval/set-default/delete, comandos para añadir o eliminar fuentes, list-sources y sync.

El motor LightRAG integrado se instala con pip install 'deeptutor[rag-lightrag]'. Ese extra contiene el SDK de LightRAG compatible pero no instala MinerU. Elige MinerU de forma independiente en Document Parsing y configura su modo en la nube o instala su CLI local vigente cuando se desee un análisis estructurado. MinerU acepta PDF, imágenes rasterizadas comunes, DOCX, PPTX y XLSX; el comando heredado magic-pdf sigue limitado a PDF. Text-only y los demás motores de análisis no requieren MinerU.

Las consultas nativas de LightRAG y la indexación incremental requieren la configuración de embeddings registrada por el índice publicado, incluyendo el modelo, la dimensión y la identidad del endpoint. Si cambia, restaura la configuración original o reconstruye con el embedding actual; los índices sin una identidad de embeddings registrada requieren una reconstrucción. Las vistas de detalle de la base de conocimiento y de versión de índice muestran orientación de recuperación, mientras los archivos permanecen disponibles para visualización y descarga.

Evaluar una base de conocimiento. Con varios motores disponibles, «¿cuál recupera mejor aquí?» es una pregunta empírica, y deeptutor kb eval permite responderla. Escribe un conjunto de preguntas y respuestas (un objeto JSON por línea: una query y los pasajes gold que debería devolver una recuperación ideal), y evalúa la KB con deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]. Cada caso se recupera por la misma ruta que usa un turno de chat; sus citas ordenadas se comparan con los pasajes de referencia mediante coincidencia exacta de texto o solapamiento léxico (los umbrales se ajustan con --min-ratio; no se evalúa la equivalencia semántica), y la ejecución informa de Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k. Las métricas son funciones puras sobre la clasificación, así que ningún modelo juzga la salida: las puntuaciones son reproducibles y se pueden comparar mediante diffs, y una referencia guardada convierte el conjunto en una comprobación de regresiones para cambiar embeddings, modificar el reranker o experimentar con el tamaño de los fragmentos. Los casos cuya búsqueda falla (por un índice ausente o credenciales incorrectas) no reciben puntuación y se informan por separado, en lugar de reducir las medias. PageIndex usa el razonamiento para recuperar y no devuelve fragmentos ordenados, por lo que se excluye.

{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}

🌐 Espacio de Aprendizaje — Skills, Personas y Contexto Reutilizable

El Espacio de Aprendizaje es la capa de biblioteca, organización y personalización. Conversaciones y Materiales guarda el historial de Chat, cuadernos con registros transferibles y exportación a Markdown, y un banco de preguntas con respuestas y explicaciones. Inicia Práctica desde una selección del banco de preguntas o desde Aprendizaje personalizado para sesiones de repaso, seguimiento de errores y repetición programada. Personalización guarda personas, skills (guías SKILL.md), Servicios MCP con instalación en un clic y Aplicaciones CLI del catálogo CLI-Anything, cada una con una guía de uso cargada bajo demanda. El espacio de trabajo independiente Mis cursos agrupa las conversaciones por materia y los hilos del tutor; cada recurso solo se ofrece en los flujos de trabajo que lo admiten.

No tienes que escribir cada skill tú mismo — Importar desde EduHub navega el catálogo comunitario y descarga una skill directamente en tu biblioteca a través de una puerta de seguridad (consulta Ecosistema).

🧠 Memory — Personalización Inspectable

Memory es un sistema de tres capas respaldado por archivos que puedes leer, curar y auditar — deliberadamente no un almacén de vectores oculto. L1 es el espejo del espacio de trabajo más un rastro de eventos de solo adición (trace/<surface>/<date>.jsonl); L2 son hechos curados por superficie (L2/<surface>.md) con referencias a entidades L1; L3 es síntesis entre superficies (L3/<profile|recent|scope|preferences>.md) que registra las superficies L2 que contribuyeron a ella.

El Memory Graph muestra toda la pirámide — síntesis L3 en el centro, L2 en el anillo intermedio, trazas L1 en el exterior — con aristas de evidencia L2 → L1 exactas y enlaces de L3 → superficies contribuyentes. La memoria se rastrea en las superficies chat, notebook, quiz, kb, book, partner y cowriter; los presupuestos de Actualización / Auditoría / Deduplicación del consolidador se ajustan en Settings → Memory.

⚙️ Settings — Un Panel de Control

Settings es el panel de control operativo y se abre en General, donde se configuran el idioma de la interfaz y el de salida del modelo. Su navegador con búsqueda enlaza páginas independientes: Personal incluye Espacios de trabajo, Migración de datos, Apariencia y Estadísticas de uso; Aprendizaje y conversación incluye sugerencias iniciales, adjuntos, Video Learning, controles de alumnos y tutores, Progreso de aprendizaje y Memory; Modelos y servicios incluye Proveedores, Modelos de lenguaje, Modelos de tarea, Embedding, Search, Voz y Generación multimodal; Funciones e integraciones incluye herramientas, parámetros de capacidades, Partners y agentes, y Conocimiento y documentos. Sistema reúne Red, Estado de ejecución y Acerca de; Chats archivados permite buscar, restaurar o eliminar permanentemente conversaciones archivadas. Estado de ejecución contiene la salud del backend, la memoria residente y la matriz de Preparación (Readiness), que clasifica bloqueos, advertencias y sugerencias de las capacidades. Espacios de trabajo mantiene separados los archivos de cada tema y el estado de aprendizaje, con migración y exportación verificadas en Migración de datos. Un proveedor guarda la dirección y credencial de un servicio para reutilizarlas con sus modelos; las páginas de modelos seleccionan proveedores guardados y configuran nombres y capacidades. Los modelos de tarea fijan un modelo pequeño y rápido para el trabajo en segundo plano — nombrar conversaciones y escribir sugerencias iniciales — y recurren al predeterminado activo cuando se dejan vacíos. Voz agrupa síntesis y transcripción de voz; Generación multimodal reúne modelos de imagen y vídeo. Partners y agentes configura entornos de agentes locales y una pasarela remota de Hermes.

Síntesis de voz de Xiaomi MiMo. Añade un proveedor Xiaomi MiMo con https://api.xiaomimimo.com/v1 y su clave API; después añade mimo-v2.5-tts en Settings → Voz. Elige una voz predefinida como mimo_default, 冰糖 o 苏打, usa salida wav o pcm16 y escúchala antes de aplicar los cambios. Las instrucciones de voz controlan el estilo y la velocidad del habla. Este adaptador solo admite voces predefinidas; el diseño y la clonación de voces requieren modelos separados y no son compatibles. Si un modelo de voz anterior de MiMo estaba configurado mediante el adaptador genérico compatible con OpenAI, vuelve a crear su entrada de voz usando el proveedor Xiaomi MiMo para que utilice el protocolo de chat-completions. Consulta la guía oficial de voz de MiMo.

Síntesis de voz de MiniMax — en Settings → Voz, elige MiniMax para texto a voz y selecciona speech-2.8-hd. Configura una clave API de MiniMax y selecciona explícitamente una voz del sistema o introduce un ID de voz personalizado. La base de API predeterminada es https://api.minimax.io/v1; para la región de China usa https://api.minimaxi.com/v1. La lectura en voz alta y las previsualizaciones de voz usan el endpoint nativo de voz, con salida MP3, WAV, FLAC o PCM, y controles de frecuencia de muestreo, velocidad e idioma. Consulta la API de voz de MiniMax para conocer los IDs de voz y la disponibilidad por cuenta.

Video Learning en Settings → Aprendizaje y conversación configura los subtítulos de YouTube y el acceso a Invidious para Reading. Para usar Invidious, establece el origen de su API de backend gestionado por el administrador (por ejemplo http://127.0.0.1:3000) y su origen público accesible desde el navegador, prueba la conexión, selecciona Invidious y guarda. Browse Invidious en el diálogo de Reading para añadir material permite buscar vídeos y acceder a las suscripciones y listas de reproducción conectadas. La reproducción de YouTube usa el reproductor oficial con privacidad mejorada; la falta de subtítulos se indica y limita la evidencia disponible para el tutor, sin bloquear la reproducción nativa. Instala .[video-learning] para el cargador predeterminado de subtítulos de YouTube. Los enlaces existentes de Watching se migran a Reading conservando el historial de conversaciones, las transcripciones compatibles, las notas y el progreso; las nuevas notas con marcas de tiempo son anotaciones de Reading. Bilibili usa su propia ruta de reproducción y subtítulos.

La mayoría de las secciones usan un flujo de borrador y aplicación, de modo que puedes probar un proveedor antes de confirmarlo. También puedes simplemente pedirlo en Chat: el asistente lee la configuración actual, aplica un cambio y te dice si necesita un reinicio o una reindexación — probando un modelo nuevo antes de confirmarlo, de modo que no puede cambiarse a sí mismo hacia algo inalcanzable. Las claves API nunca pasan por el modelo, que en su lugar abre el formulario correspondiente para ti. Cuatro temas se incluyen por defecto — Default, Cream, Dark y Glass. Los archivos .env de la raíz del proyecto se ignoran intencionalmente; la configuración de runtime vive bajo data/user/settings/*.json a menos que DEEPTUTOR_HOME o deeptutor start --home apunten la app en otro lugar.

OpenAI Codex OAuth (experimental). Añadir OpenAI Codex en Settings → Proveedores abre un inicio de sesión en el navegador que se ejecuta contra tu propio plan de ChatGPT, de modo que no se necesita OPENAI_API_KEY. Los tokens viven solo en data/system/user-secrets/<owner>/private/openai-codex/ — en el despliegue multi-contenedor con Compose, fuera de cualquier árbol al que el sandbox de ejecución pueda acceder — y DeepTutor nunca lee ni modifica tu inicio de sesión de la CLI ~/.codex. La lista de modelos proviene del catálogo en vivo de esa cuenta; iniciar sesión publica el perfil, pero este solo se convierte en el modelo activo cuando todavía no hay ningún LLM configurado. Como un token autoriza el plan de una sola persona, el perfil no se puede compartir a través de permisos de usuario — cada cuenta inicia sesión por sí misma, incluidos los usuarios comunes: su tarjeta de inicio de sesión se encuentra en Proveedores, y los modelos, el catálogo y el cierre de sesión resultantes permanecen privados para esa cuenta.

En el inicio de sesión y Actualizar modelos, DeepTutor lee la última versión estable de @openai/codex desde el registro oficial de npm y la usa como client_version de la solicitud del catálogo. Esto es solo metadatos: no instala, descarga ni actualiza la CLI de Codex, y la solicitud a npm no lleva credenciales OAuth. El descubrimiento tiene un límite de tres segundos y un límite de respuesta de 64 KiB. Si falla, DeepTutor usa la última versión exitosa para esa cuenta, o su valor de reserva integrado cuando no hay ninguna en caché. Solo un catálogo en vivo analizado con éxito guarda una versión nueva; los validadores nunca se reutilizan entre versiones ni entre generaciones de credenciales. Un rechazo de versión o una estructura de catálogo incompatible permite un reintento con la versión anterior; los fallos de autenticación, límite de tasa y TLS no se reintentan como problemas de versión. Una actualización manual fallida reporta un error en lugar de presentar un catálogo antiguo en caché como actualizado.

El historial de versiones exitoso sobrevive a la renovación de tokens de la misma cuenta y a los errores de autenticación del catálogo, sin volver a hacer utilizables los datos de modelo invalidados ni las ETags. Cerrar sesión borra la caché local de esa cuenta, incluido el historial de versiones. Las lecturas de estado ordinarias y la inferencia no consultan npm. Las nuevas entradas del catálogo no reemplazan un modelo que ya has seleccionado ni reinician las sesiones de aprendizaje en curso; aparecer en el catálogo no establece compatibilidad total del protocolo de inferencia. No hay un actualizador de versión en segundo plano ni una configuración de versión para el usuario.

Los despliegues locales predeterminados de Docker y Podman usan redes de loopback separadas y necesitan un puente temporal durante el inicio de sesión. Sigue la guía del puente temporal local de OAuth de Codex para conocer los comandos exactos de Docker, Compose, Podman y desmontaje.

Para un despliegue remoto, el localhost del navegador y el localhost del servidor son máquinas diferentes, de modo que un proxy inverso ordinario por sí solo no puede llevar la devolución de llamada localhost del navegador hasta el servidor. Usa un túnel SSH como puente de devolución de llamada. El túnel llega hasta el puerto Web ya publicado; Next.js reescribe únicamente la ruta exacta de devolución de llamada hacia el broker público de devolución de llamada, y el broker valida state antes de enrutar hacia la operación OAuth original. El listener de devolución de llamada permanece en el loopback del backend, los puertos 1455 y 1457 no se publican, y esta ruta admite la red bridge predeterminada de Docker.

ssh -N -L 1455:127.0.0.1:3782 <ssh-user>@<server-host>

Si DeepTutor reporta el puerto de devolución de llamada de reserva 1457, usa:

ssh -N -L 1457:127.0.0.1:3782 <ssh-user>@<server-host>

Ejecuta solo el comando que coincide con el puerto de devolución de llamada real; nunca ejecutes ambos. 3782 es solo el puerto Web de ejemplo: es el puerto de frontend/contenedor configurado, reportado como callback_forward_port. Ese valor no garantiza que el mismo puerto esté escuchando en el 127.0.0.1 del host SSH. Si Docker o Podman publican un puerto de host diferente, o un proxy inverso escucha en un puerto distinto, reemplaza solo el puerto de destino del lado derecho (3782 arriba) por el puerto Web que realmente escucha en el 127.0.0.1 del host SSH; conserva el puerto de devolución de llamada del lado izquierdo como 1455 o 1457. <server-host> es el host SSH cuyo loopback posee ese puerto en escucha. Si la URL del navegador nombra un proxy inverso o balanceador de carga, reemplázala por el host frontend SSH correcto.

La CLI imprime el comando del túnel y luego intenta abrir el navegador de inmediato. En un despliegue remoto, mantén abierta la página de autorización sin completarla, establece el túnel impreso en otra terminal, y solo entonces continúa la autorización.

La detección de topología remota tiene un límite de localhost. Si Web mismo se alcanza a través de un forward de localhost de SSH o del IDE, el navegador no puede saber que el servidor es remoto. Para la operación Web actual, deja su página de autorización sin terminar, lee redirect_uri en la URL de autorización de esa operación para identificar el puerto de devolución de llamada 1455 o 1457, y crea el segundo túnel desde ese puerto local hasta el puerto Web real. Alternativamente, cancela esa operación Web e inicia una nueva con la CLI; la salida de la CLI pertenece a la nueva operación y no debe usarse para la operación Web existente. Los errores de cuota y las fallas de catálogo se reportan tal cual y nunca recurren a un proveedor de pago. Esta ruta de compatibilidad es experimental: la interfaz upstream puede cambiar.

👥 Multi-Usuario — Despliegues Compartidos · autenticación opcional, espacios de trabajo aislados por usuario

La autenticación está desactivada por defecto — DeepTutor corre en modo monousuario. Actívala y un árbol data/ aloja un espacio de trabajo de administrador, espacios de trabajo aislados por usuario y espacios de trabajo de partner en paralelo:

data/
├── user/                    # Admin workspace + global settings
├── users/<uid>/             # Per-user scope: chat history, memory, notebooks, KBs
├── partners/<id>/workspace/ # Partner (synthetic-user) scope
├── cli-apps/                # Installed CLI apps, mounted read-only into the sandbox
└── system/                  # auth · grants · audit · user-secrets/<owner> (OAuth tokens)

El primer usuario registrado se convierte en administrador y controla los catálogos de modelos, las credenciales de proveedor, las bases de conocimiento compartidas, las skills, los libros compartidos canónicos y los permisos por usuario. Para los usuarios locales creados por el administrador se elige Standard, Learner o Custom. Learner bloquea las capacidades de aprendizaje y la política de materiales, añade un perfil adaptativo y admite credenciales de dispositivo revocables con caducidad y límites diarios; los guardianes autorizados pueden ver informes, aprobar materiales y restablecer credenciales. Los demás usuarios obtienen espacios de trabajo aislados y acceso con alcance a modelos, KBs, skills, Partners y libros compartidos sin recibir claves API en bruto. Si auth.json ya contiene un username + password_hash, esa cuenta es el administrador: /register permanece cerrado y las cuentas creadas desde /admin/users siempre tienen role=user hasta que las asciendas.

Activarlo: activa la autenticación en data/user/settings/auth.json, reinicia deeptutor start, registra al primer administrador en /register, luego agrega usuarios desde /admin/users y asigna modelos, KBs, skills, Partners, política de herramientas/MCP/CLI-apps y acceso de ejecución de código a través de permisos; configura los libros compartidos en el panel Book access de cada usuario.

Para orígenes privados/públicos divididos, establece auth.private_login_hosts (o AUTH_PRIVATE_LOGIN_HOSTS) en los hosts de frontend privados que pueden mostrar el inicio de sesión con contraseña y el registro. El frontend reenvía el Host HTTP entrante al backend como su afirmación de host de frontend. Preserva el Host del navegador a través de tu proxy inverso, y haz que la entrada pública rechace las solicitudes que nombren un host privado; no expongas un puerto de Next.js sin procesar que acepte valores de Host arbitrarios. El Host HTTP puede ser falsificado por un cliente directo, por lo que la autorización de host privado depende de ese límite de entrada. El backend acepta afirmaciones de host de frontend solo desde loopback por defecto. Si el frontend Web se conecta desde otro contenedor u host, establece AUTH_TRUSTED_FRONTEND_PROXY_IPS con la dirección IP exacta de ese proxy de frontend en el proceso del backend (separadas por comas si hay más de una). Mantén la API del backend privada para el proxy de frontend y no incluyas redes de clientes generales en esta lista. Loopback siempre está permitido; cuando la lista no está vacía, un usuario autenticado en un origen privado puede abrir Perfil → Inicio de sesión público de dispositivo y crear un enlace de emparejamiento de corta duración vinculado al host para un origen público HTTPS. La página pública /handoff intercambia el código de un solo uso por un ticket JWE igualmente corto en un cuerpo POST, consume el ticket una vez, y recibe la cookie de sesión HttpOnly normal.

PocketBase sigue siendo una integración monousuario — mantén integrations.pocketbase_url en blanco para despliegues multi-usuario a menos que hayas conectado un almacén de usuarios externo.

⌨️ DeepTutor CLI — Interfaz Nativa de Agentes

Un binario deeptutor, dos formas de entrar: un REPL interactivo para quienes viven en la terminal, y JSON estructurado para otros agentes que manejan DeepTutor como herramienta. Las mismas capacidades, herramientas y bases de conocimiento de cualquier manera.

Manejarlo tú mismo

deeptutor chat abre un REPL interactivo y selecciona un modo con --capability; deeptutor run <capability> "<message>" recibe esa capacidad como primer argumento posicional y sale después de un turno. Ambos aceptan --tool, --kb, --config y --workspace para seleccionar un espacio de trabajo registrado.

deeptutor chat                                              # interactive REPL
deeptutor chat --capability deep_solve --kb my-kb --tool rag
deeptutor run chat "Explain the Fourier transform" --tool rag --kb textbook
deeptutor run chat "Find recent work beyond this material" --kb textbook --tool knowledge_frontier
deeptutor run deep_research "Survey 2026 papers on RAG" \
  --config mode=report --config depth=standard

La gestión esencial del espacio de trabajo también está disponible aquí — bases de conocimiento (kb), sesiones (session), partners (partner), skills (skill), cuadernos, memoria y config; la organización de cursos y sesiones permanece en la aplicación Web. Lista completa a continuación.

Dejar que un agente lo maneje

DeepTutor está construido para ser operado por otro agente. Agrega --format json a cualquier run y cada turno transmite NDJSON — un evento por línea (content, tool_call, tool_result, done, …), cada línea etiquetada con su session_id. Las ejecuciones son seguras sin TTY: una pausa ask_user sin TTY se resuelve automáticamente con una respuesta vacía en lugar de bloquearse.

# One shot, machine-readable
deeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json

# Chain turns in one stateful session — capture the id, reuse it
SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \
  --config mode=report --config depth=standard --format json \
  | jq -r 'select(.type=="done").session_id')
deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json

El repo incluye un SKILL.md raíz — un documento compacto de traspaso para la CLI. Pide a tu agente que lo lea explícitamente; su guía de configuración para agentes abarca la instalación y la configuración. También puedes envolver deeptutor run como herramienta en un bucle LangChain / AutoGen. Recetas completas: Agent Handoff.

Referencia de comandos

Comando	Descripción
deeptutor init [--non-interactive] [--home PATH]	Ejecutar el asistente de configuración o crear los valores predeterminados que falten sin preguntas
deeptutor doctor [--online]	Verificar si el hogar de ejecución está listo para iniciar una sesión; --online también sondea el proveedor de modelo configurado, --format json imprime el informe
deeptutor start [--home PATH] [--dev] [--detach] [--no-browser]	Lanzar backend + frontend juntos; separar el proceso u omitir la apertura del navegador de forma opcional
deeptutor stop [--home PATH]	Detener un launcher iniciado con --detach
deeptutor serve [--port PORT]	Iniciar solo el backend FastAPI
deeptutor workspace show/set/reset	Inspeccionar, seleccionar o restaurar el Espacio de Trabajo de Contenido por usuario
deeptutor run <capability> <message>	Ejecutar un turno de capacidad único (chat, ask_questions, deep_solve, deep_question, deep_research, visualize, math_animator, mastery_path, immersive_reading, course_study, audio_overview); agrega --format json para salida NDJSON
deeptutor chat	REPL interactivo con controles de capacidad, herramienta, KB, notebook e historial
deeptutor partner list/create/start/stop	Gestionar partners conectados por IM
deeptutor kb list/info/create/connect-kiwix/add/search/eval/set-default/delete/list-sources/sync	Gestionar bases de conocimiento, conectar archivos Kiwix, evaluar la calidad de recuperación con un conjunto de preguntas y respuestas, y sincronizar fuentes de GitHub/web registradas (con comandos para añadir o eliminar fuentes)
deeptutor skill search/install/list/remove/login/logout/publish/update	Gestionar skills, instalar desde hubs y publicar las propias (eduhub:<slug> por defecto, consulta Ecosistema)
deeptutor memory show/clear	Inspeccionar documentos de memoria L2/L3 o borrar memoria L1/toda
deeptutor session list/show/open/rename/delete	Gestionar sesiones compartidas
deeptutor notebook list/create/show/add-md/replace-md/remove-record	Gestionar cuadernos desde archivos Markdown
deeptutor book list/health/refresh-fingerprints	Inspeccionar libros y actualizar huellas dactilares de fuentes
deeptutor plugin list/info/state/search/show/install/approve/enable/disable/rollback/uninstall	Inspeccionar herramientas y capacidades; gestionar paquetes de plugins revisados y sus aprobaciones de permisos
deeptutor config show [--home PATH]	Mostrar la configuración de runtime resuelta con las credenciales ocultas
deeptutor config providers	Listar los proveedores de configuración compatibles y sus valores predeterminados como JSON
deeptutor config apply FILE [--check] [--home PATH]	Aplicar JSON de configuración sin preguntas o validarlo sin escribir la configuración
deeptutor provider login <provider>	Autenticación del proveedor (openai-codex inicio de sesión OAuth; github-copilot inicio de sesión de dispositivo de GitHub; codebuddy valida la autenticación del SDK de CodeBuddy e inicia el login cuando es necesario)

Las credenciales de GitHub Copilot pertenecen al propietario que ha iniciado sesión en DeepTutor y solo se guardan en <runtime-home>/data/system/user-secrets/<owner-id>/private/github-copilot/credentials.v1.json, fuera de los espacios de trabajo del sandbox. Los partners de la CLI y del administrador usan las credenciales del administrador; los demás usuarios inician sesión por separado, y los perfiles de Copilot no se pueden compartir mediante permisos de modelos. Nunca se importan archivos de tokens externos de nanobot/Copilot: después de actualizar, vuelve a ejecutar deeptutor provider login github-copilot.

El inicio de sesión valida la inferencia con un modelo descubierto en ese momento; init valida el modelo seleccionado y aborta si falla, sin guardar el borrador de configuración. La autenticación exitosa en GitHub no demuestra por sí sola el acceso a los modelos de Copilot (el inicio de sesión guardado se conserva si la validación falla). Las solicitudes de runtime usan el endpoint de API devuelto por el intercambio de tokens, incluidas las renovaciones, y respetan los metadatos de endpoints Responses/Chat Completions de cada modelo.

La compatibilidad de Responses específica de Copilot se aplica al enviar la solicitud, sin reescribir el historial guardado.

Distribución de solo CLI

El paquete de solo CLI vive en packaging/deeptutor-cli. En este checkout, instálalo desde fuente:

python -m pip install -e ./packaging/deeptutor-cli

Aún no está publicado en PyPI, así que la sección principal de Comenzar mantiene la ruta de instalación desde fuente.

🧩 Ecosistema — EduHub y la Comunidad de Skills

Las skills de DeepTutor usan el formato abierto Agent-Skills — una carpeta con una guía SKILL.md (frontmatter YAML + Markdown) y archivos de referencia opcionales. No hay nada específico de DeepTutor en ello, así que cualquier registro que hable el formato se convierte en una fuente para tu biblioteca. DeepTutor incluye EduHub — nuestro propio registro de skills enfocado en educación — conectado como hub predeterminado.

EduHub — el ecosistema de skills de DeepTutor

EduHub es el hub comunitario que DeepTutor lanzó para compartir skills de agentes orientadas a la enseñanza — tutores socráticos, constructores de tarjetas flash, retroalimentación de ensayos, planos de examen, explicadores de conceptos y más. Está integrado en DeepTutor, así que no hay nada que configurar: un slug simple o un prefijo eduhub: se resuelve a él.

Encontrar e instalar — en el navegador, abre Learning Space → Skills → Import from EduHub para navegar el catálogo y descargar una skill directamente en tu biblioteca. Desde la terminal:

deeptutor skill search "socratic tutor"               # search EduHub (the default hub)
deeptutor skill install socratic-tutor                # fetch → verify → register
deeptutor skill install eduhub:socratic-tutor@1.2.0   # pin a hub and a version
deeptutor skill list                                  # local skills with their hub provenance

Publicar la tuya propia — empaqueta un SKILL.md y compártelo con la comunidad:

deeptutor skill login                                 # browser sign-in to EduHub
deeptutor skill publish ./my-skill                    # interactive: pick a track + tags, then upload
deeptutor skill update                                # roll back or release a new version

EduHub también es un registro independiente compatible con ClawHub, así que los agentes que no son DeepTutor (Claude Code, Codex, …) pueden usarlo directamente a través del CLI eduhub — npx eduhub install socratic-tutor.

La puerta de seguridad de importación

Sea cual sea la fuente, cada importación pasa la misma puerta de seguridad antes de que nada toque tu espacio de trabajo:

• el veredicto de seguridad del registro se verifica primero — los paquetes marcados se rechazan a menos que pases --allow-unverified;
• los archivos se extraen de forma defensiva con comprobaciones de recorrido de rutas, número de entradas, tamaño, relación de compresión, sufijos y enlaces simbólicos; se eliminan los bits ejecutables, pero se siguen permitiendo los archivos sin extensión;
• el frontmatter se normaliza al esquema de DeepTutor y always: se elimina, de modo que una skill descargada nunca puede forzarse en cada prompt del sistema;
• la proveniencia — hub, versión, veredicto y tiempo de instalación — se escribe en .hub-lock.json para auditorías y actualizaciones.

En despliegues multi-usuario, las importaciones desde el navegador llegan a la capa de skills del usuario autenticado, mientras que las instalaciones desde la CLI y la consola de administración se dirigen al espacio de trabajo del propietario/administrador; las skills del administrador permanecen ocultas y son de solo lectura para los usuarios comunes hasta que se les conceden.

También compatible con ClawHub

Como DeepTutor habla el formato abierto Agent-Skills, ClawHub también funciona como fuente de primera clase — está integrado junto con EduHub. Selecciónalo con el prefijo del hub:

deeptutor skill search "git release notes" --hub clawhub
deeptutor skill install clawhub:git-release-notes@1.0.1
deeptutor skill install clawhub:udiedrichsen/stock-analysis

Cuando varios publicadores comparten el mismo slug, la búsqueda muestra cada publicador y una referencia de instalación completamente calificada (clawhub:<ownerHandle>/<slug>).

Agrega más registros en data/user/settings/skill_hubs.json: una entrada type: "clawhub" apunta a cualquier API HTTP compatible (EduHub y ClawHub ambas lo hablan), type: "command" envuelve cualquier CLI de fetch que envíe un registro, y "default" elige el hub usado para slugs simples. Todos ellos alimentan la misma puerta de importación.

🤝 Socios de Código Abierto

Usando el código: DEEPTUTOR20 — ¡obtén $20 de descuento en tu primera suscripción a PageIndex!

🌐 Comunidad

🔗 Mantenedores

Bingxi Zhao

Xingyu Hou

Jiahao Zhang

📮 Contacto

DeepTutor es un proyecto de código abierto liderado por Bingxi Zhao dentro del grupo HKUDS, y se itera en forma completamente de código abierto, construido junto con la comunidad. Hasta ahora, NO tenemos productos en línea de pago de ningún tipo. No dudes en contactarnos en bingxizhao39@gmail.com para discusiones, ideas o colaboración.

🙏 Agradecimientos

Un agradecimiento de corazón a Chao Huang, director del Data Intelligence Lab @ HKU, y a nuestros compañeros de HKUDS por su cálido apoyo — especialmente Jiahao Zhang, Zirui Guo y Xubin Ren. También estamos profundamente agradecidos a la comunidad de código abierto: tus estrellas, issues, pull requests y discusiones dan forma a DeepTutor todos los días.

DeepTutor también se apoya en los hombros de destacados proyectos de código abierto que nos dieron herramientas e inspiración:

Proyecto	Rol / Inspiración
LlamaIndex	Columna vertebral del pipeline RAG y la indexación de documentos
nanobot	Motor de agente ultraligero que impulsó el TutorBot original (HKUDS)
LightRAG	RAG simple y rápido (HKUDS)
AutoAgent	Marco de agentes sin código (HKUDS)
AI-Researcher	Pipeline de investigación automatizada (HKUDS)
OpenClaw	Pasarela de agentes abierta y ecosistema de skills detrás de ClawHub
Codex	CLI de codificación nativo de agentes que inspiró nuestro flujo de trabajo CLI
Claude Code	CLI de codificación agéntica que inspiró el bucle de agentes de DeepTutor
ManimCat	Generación de animaciones matemáticas impulsada por IA para Math Animator

🗺️ Roadmap y Contribuir

Queremos que DeepTutor siga iterando y mejorando — y en última instancia se convierta en un regalo que devolvamos a la comunidad de código abierto. Nuestro roadmap se actualiza continuamente; vota en los elementos allí o propone nuevos. Si deseas contribuir, consulta la Guía de Contribución para la estrategia de ramas, estándares de código y cómo comenzar.

Esperamos que DeepTutor se convierta en un regalo para la comunidad. 🎁

Licenciado bajo Apache License 2.0.

Fundamentación de los turnos de Mastery

Los turnos de Mastery leen el estado de la ruta activa antes de la primera solicitud al modelo, usando la misma herramienta de estado y los mismos controles de dominio que una llamada explícita a la herramienta. Esta instantánea se actualiza en cada turno, incluye el modo de sesión activo y nunca se almacena en caché entre turnos. Si la lectura falla, se recurre a mastery_status; después de cambiar la ruta, el modo, el esquema o el progreso, el tutor puede actualizar el estado mediante esa herramienta. La evaluación de las tarjetas y su traspaso existente permanecen sin cambios.

Imágenes adjuntas repetidas

El bucle de agente envía las imágenes de usuario incrustadas idénticas una sola vez por solicitud y sustituye las copias posteriores por referencias a la imagen conservada. Las etiquetas estables, exclusivas de la solicitud, identifican las imágenes incrustadas conservadas a través de las adaptaciones a los proveedores y los turnos añadidos. Los bloques de imagen únicos, las URL remotas, las opciones de imagen diferentes, los mensajes del asistente y los resultados de herramientas se conservan completos. El historial guardado mantiene todos los adjuntos originales; las referencias se reconstruyen después de recortar el historial. Esto reduce las cargas de imágenes repetidas, pero el uso informado por el proveedor sigue siendo la fuente de verdad para la facturación y los aciertos de caché.