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-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, Quiz, Research, Visualize, Solve y Mastery Path corren en el mismo bucle de agente, de modo que cambias el objetivo, no el motor, y el contexto acompaña al estudiante.
Contexto de aprendizaje conectado — Bases de conocimiento, libros, borradores de Co-Writer, cuadernos, bancos de preguntas, personas y Memory están disponibles en todos los flujos de trabajo en lugar de vivir en herramientas aisladas.
Subagentes y Partners — consulta un Claude Code, Codex o Partner en vivo desde cualquier turno (o importa sus conversaciones pasadas), y ejecuta compañeros IM persistentes con el mismo cerebro.
Conocimiento multi-motor — bibliotecas RAG con versiones: LlamaIndex, PageIndex, GraphRAG, LightRAG o un vault Obsidian vinculado, con análisis de documentos conectable.
Herramientas y habilidades extensibles — herramientas integradas, servidores MCP, modelos de generación de imagen / video / voz, y skills de la comunidad instalables desde EduHub.
Memoria inspectable — trazas L1, resúmenes de superficie L2 y síntesis L3 hacen visible y editable la personalización, con un Memory Graph que traza cada afirmación hasta su evidencia.

🚀 Comenzar

DeepTutor incluye cuatro rutas de instalación. Todas comparten un diseño de espacio de trabajo: la configuración 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 espacio de trabajo → instalar → deeptutor init → deeptutor start.

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+ 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     # solicita puertos + proveedor LLM + embedding opcional
deeptutor start    # inicia backend + frontend; mantener la terminal abierta

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

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 → Models.

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

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

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

# Crear un 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

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

deeptutor init
deeptutor start

Las instalaciones desde fuente ejecutan Next.js en modo de desarrollo contra el directorio web/ local; todo lo demás (diseño de configuración, puertos, detener con Ctrl+C) coincide 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 — dev / partners / matrix / math-animator

pip install -e ".[dev]"             # herramientas de pruebas/lint
pip install -e ".[partners]"        # SDKs de canales IM de Partners + cliente MCP
pip install -e ".[matrix]"          # canal Matrix sin E2EE/libolm
pip install -e ".[matrix-e2e]"      # Matrix E2EE; requiere libolm
pip install -e ".[math-animator]"   # complemento Manim; requiere LaTeX/ffmpeg/libs del sistema

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 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

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
ghcr.io/hkuds/deeptutor:pre — versión preliminar, cuando esté disponible

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

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, los archivos del espacio de trabajo, la memoria y las bases de conocimiento persisten en el volumen deeptutor-data.

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 tu configuración y espacio de trabajo entre reinicios.

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 → Models, 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

# Crear un 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 y establece embeddings en desactivado (elige Yes si planeas usar deeptutor kb … o herramientas RAG). Aún escribe un diseño de runtime completo (system.json, auth.json, integrations.json, model_catalog.json, main.yaml, agents.yaml) y aún solicita el proveedor LLM y modelo activos.

Comandos comunes

deeptutor chat                                          # REPL interactivo
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 las herramientas exec / code_execution y devuelva una URL de descarga. Esas herramientas se montan siempre que un backend de sandbox esté activo, lo cual ocurre por defecto en cada forma de despliegue:

Local (Opción 1 / 2) y Docker (Opción 3, contenedor único): un sandbox de subproceso restringido ejecuta el código del modelo (localmente en el host, o dentro del contenedor bajo Docker — el contenedor siendo su propio límite de aislamiento).
docker-compose: enrutado en su lugar a un sidecar runner endurecido y con privilegios mínimos (Dockerfile.runner) a través de DEEPTUTOR_SANDBOX_RUNNER_URL — la postura más sólida, y preferida automáticamente cuando está presente.

El sandbox de subproceso está controlado por la configuración sandbox_allow_subprocess en data/user/settings/system.json (predeterminado true). Ejecutar código generado por el modelo en tu host es una decisión real de confianza — establécelo en false (o exporta DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=0) para deshabilitar la ejecución del lado del host, a costa de que las skills de oficina ya no puedan producir archivos.

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 en el navegador es el editor recomendado.

Archivo	Propósito
`model_catalog.json`	Perfiles de proveedores LLM, embeddings y búsqueda; claves API; modelos activos
`system.json`	Puertos de backend/frontend, base de API pública, CORS, verificación SSL, directorio de adjuntos
`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`	Preferencias de idioma / tema / barra lateral de UI
`main.yaml`	Valores predeterminados de comportamiento de runtime e inyección de rutas
`agents.yaml`	Configuración de temperatura y tokens de capacidades/herramientas

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, abre Settings → Models, agrega un perfil LLM (URL Base / clave API / nombre del modelo) y guarda. Agrega un perfil de embeddings solo si planeas usar funciones de Base de Conocimiento / RAG.

📖 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.

Inicio de DeepTutor — el espacio de trabajo Chat con todas las superficies en la barra lateral

🏗️ 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, reason y geogebra_analysis — más imagegen y videogen una vez que configures el modelo de generación correspondiente. Las herramientas contextuales como rag, read_source, read_memory, write_memory, read_skill, load_tools, exec, web_fetch, ask_user, list_notebook, write_note, github y consult_subagent se montan automáticamente cuando el turno tiene el contexto adecuado.

El contexto viene en dos tipos: el contexto de sesión persistente (subagente, bases de conocimiento, persona, modelo, voz) vive en la barra de herramientas del compositor y persiste entre turnos; las referencias de un solo uso (archivos, historial de chat, libros, cuadernos, banco de preguntas, agentes importados) vienen del menú + para un único turno.

Chat es también el punto de lanzamiento para capacidades más profundas: Quiz para generación de preguntas, Research para informes con citas, Visualize para gráficos / diagramas / animaciones, y — bajo More Capabilities — Solve para razonamiento trabajado y Mastery Path para flujos de planes de aprendizaje.

🤝 Partner — Compañeros Persistentes con el Mismo Cerebro

Espacio de trabajo de partners DeepTutor

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. Las bases de conocimiento, skills y notebooks se copian en data/partners/<id>/workspace/, por lo que las mismas herramientas de RAG, skill, notebook y memoria funcionan sin casos especiales. Un partner lee la memoria de su propietario pero solo escribe en la suya propia.

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.

🧑‍🚀 Mis Agentes — Consultar e Importar Otros Agentes

Espacio de trabajo de Mis Agentes DeepTutor

Mis Agentes convierte a otros agentes en contexto para DeepTutor y hace dos cosas distintas. Conectar un agente en vivo — un Claude Code o Codex CLI en tu máquina, 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 con el chip de Agente (o escribe @), y establece cuántas rondas puede tomar la consulta.

Consultando un subagente Claude Code en vivo

Importar conversaciones pasadas — trae tu historial existente de Claude Code y Codex como agentes nombrados, buscables y reanudables. Elige qué días importar; actualizar los vuelve a sincronizar. Referencia una conversación importada desde cualquier turno de chat a través de + → Mis Agentes, y DeepTutor la lee como un transcript 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.

Editor Co-Writer con vista previa en vivo

Su idea definitoria es la edición quirúrgica: selecciona un fragmento y pide a DeepTutor que lo reescriba, expanda o acorte. El agente de edición puede fundamentar el cambio en una base de conocimiento o evidencia web, mantiene un rastro de sus llamadas a herramientas y muestra cada cambio como un diff de aceptar/rechazar — de modo que nada se aplica hasta que lo apruebes.

📖 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 — texto, callouts, quizzes, tarjetas flash, líneas de tiempo, código, figuras, HTML interactivo, animaciones, gráficos de conceptos, profundizaciones y notas de usuario — y cada página tiene su propio Page Chat. Los bloques son editables: inserta, mueve, regenera o cambia el tipo de un bloque sin reescribir el capítulo. Los comandos de mantenimiento como deeptutor book health y deeptutor book refresh-fingerprints ayudan a detectar cuándo el conocimiento fuente ha divergido de las páginas compiladas.

📚 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 local + BM25), PageIndex (hospedado, recuperación por razonamiento con citas a nivel de página), 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), o un vault Obsidian vinculado que el tutor lee y escribe en el lugar. Cada KB está vinculada a un motor.

Al crear una KB, puedes crear nueva (subir documentos y construir un índice nuevo) o vincular existente (reutilizar un índice construido en otro lugar, leer en el lugar sin re-indexar). 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, markitdown o PyMuPDF4LLM — se elige en Settings → Knowledge Base, con descargas de modelos locales desactivadas por defecto. La CLI refleja el ciclo de vida con deeptutor kb list, info, create, add, search, set-default y delete.

🌐 Espacio de Aprendizaje — Skills, Personas y Contexto Reutilizable

Hub del Espacio de Aprendizaje DeepTutor

El Espacio de Aprendizaje es la capa de biblioteca y personalización — donde viven las cosas que persisten. Conversaciones y Materiales guarda tu historial de chat, cuadernos y un banco de preguntas (cada pregunta guardada conserva tu respuesta, la respuesta de referencia y una explicación). Personalización guarda rutas de dominio, personas (preajustes de comportamiento como compañero, asistente de investigación, profesor) y skills (guías SKILL.md que el modelo lee bajo demanda). Todo aquí se puede reutilizar desde Chat, Partners, Co-Writer y Book.

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); L3 es síntesis entre superficies (L3/<profile|recent|scope|preferences>.md). Como L2 cita a L1 y L3 cita a L2, nada en tu perfil queda sin rendir cuentas.

El Memory Graph muestra toda la pirámide — síntesis L3 en el centro, L2 en el anillo intermedio, trazas L1 en el exterior — de modo que puedes rastrear cualquier afirmación sintetizada hasta el evento bruto exacto detrás de ella. 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, con una tira de estado en vivo (Backend, LLM, Embedding, Search) y una tarjeta por área: Apariencia (tema + idioma de UI), Red (base de API, puertos, CORS), Modelos (LLM, Embedding, Search, Text-to-Speech, Speech-to-Text, Image Generation, Video Generation), Knowledge Base (motor de análisis de documentos), Chat (herramientas, servidores MCP, parámetros por capacidad), Partners & Agents (los subagentes que puedes consultar desde un turno), y Memory (los presupuestos del consolidador).

Configuración de apariencia de DeepTutor y temas

La mayoría de las secciones usan un flujo de borrador y aplicación, de modo que puedes probar un proveedor antes de confirmarlo. 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.

👥 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/                    # Espacio de trabajo del administrador + configuración global
├── users/<uid>/             # Alcance por usuario: historial de chat, memoria, cuadernos, KBs
├── partners/<id>/workspace/ # Alcance del partner (usuario sintético)
└── system/                  # auth/users.json · grants/<uid>.json · audit/usage.jsonl

El primer usuario registrado se convierte en administrador y es dueño de catálogos de modelos, credenciales de proveedor, bases de conocimiento compartidas, skills y permisos por usuario. Todos los demás obtienen un espacio de trabajo aislado y una página de Settings redactada — los modelos, KBs y skills asignados por el administrador aparecen como opciones con alcance de solo lectura, nunca como claves API en bruto.

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 y acceso de ejecución de código a través de permisos.

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; deeptutor run <capability> "<message>" ejecuta un único turno y sale. Ambos comparten los mismos flags --capability, --tool, --kb y --config.

deeptutor chat                                              # REPL interactivo
deeptutor chat --capability deep_solve --kb my-kb --tool rag
deeptutor run chat "Explain the Fourier transform" --tool rag --kb textbook
deeptutor run deep_research "Survey 2026 papers on RAG" \
  --config mode=report --config depth=standard

Todo lo que hace la aplicación Web también está aquí — bases de conocimiento (kb), sesiones (session), partners (partner), skills (skill), cuadernos, memoria y config. 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.

# Disparo único, legible por máquina
deeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json

# Encadenar turnos en una sesión con estado — captura el id, reutilízalo
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 de traspaso de ~150 líneas que enseña a cualquier LLM que use herramientas toda la superficie en una lectura. Entrégaselo a Claude Code, Codex u OpenCode (los recogen automáticamente), o envuelve deeptutor run como herramienta en un bucle LangChain / AutoGen. Recetas completas: Agent Handoff.

Referencia de comandos

Comando	Descripción
`deeptutor init`	Crear o actualizar `data/user/settings` para el espacio de trabajo actual
`deeptutor start [--home PATH]`	Lanzar backend + frontend juntos
`deeptutor serve [--port PORT]`	Iniciar solo el backend FastAPI
`deeptutor run <capability> <message>`	Ejecutar un turno de capacidad único (`chat`, `deep_solve`, `deep_question`, `deep_research`, `visualize`, `math_animator`, `mastery_path`); 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/add/search/set-default/delete`	Gestionar bases de conocimiento LlamaIndex
`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`	Inspeccionar herramientas y capacidades registradas
`deeptutor config show`	Imprimir resumen de configuración
`deeptutor provider login <provider>`	Autenticación del proveedor (`openai-codex` OAuth login; `github-copilot` valida una sesión de autenticación Copilot existente)

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"               # buscar en EduHub (el hub predeterminado)
deeptutor skill install socratic-tutor                # fetch → verificar → registrar
deeptutor skill install eduhub:socratic-tutor@1.2.0   # fijar un hub y una versión
deeptutor skill list                                  # skills locales con su proveniencia del hub

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

deeptutor skill login                                 # inicio de sesión en EduHub desde el navegador
deeptutor skill publish ./my-skill                    # interactivo: elige una pista + etiquetas, luego sube
deeptutor skill update                                # revertir o lanzar una nueva versión

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 defensivamente (guardas contra zip-slip / zip-bomb) detrás de una lista blanca de sufijos de texto/script, de modo que los binarios nunca aterrizan en el espacio de trabajo;
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, la instalación es solo para administradores: una nueva skill aterriza en el catálogo del administrador y permanece invisible para otros usuarios hasta que un permiso la asigne, de modo que un administrador puede verificarla antes de distribuirla.

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

Agrega más registros en 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.

🌐 Comunidad

📮 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. 🎁