DeepTutor 智能辅导助手

项目概述

DeepTutor 是一个面向终身学习的智能辅导工作台，把答疑、解题、出题、深度研究、可视化、掌握度训练等多种学习模式统一在同一个代理循环之上。它不是若干独立工具的拼合，而是一套上下文贯穿、知识可追溯、能力可扩展的一体化学习环境。

核心特性

统一的运行时

Chat、Quiz、Research、Visualize、Solve、Mastery Path、Immersive Reading 等所有模式共享同一个代理引擎。学习者切换目标时无需更换底层引擎，上下文随学习进度自然流转。

贯通的学习上下文

知识库、书籍、Co-Writer 草稿、笔记、题库、人格与 Memory 在所有工作流之间互通，避免信息被困在孤立工具中。

子代理与 Partners

可在任意回合中调用本地编码 CLI（Claude Code、Codex、Gemini、Kimi、opencode、MiMo），或与 Partner 助手对话，还可导入历史会话；同一大脑也可驱动长连接的 IM 伙伴。

多引擎知识体系

知识库支持 LlamaIndex、PageIndex、GraphRAG、LightRAG、远程 LightRAG Server、腾讯 IMA 库、Obsidian 仓库等多种后端，文档解析引擎可插拔，知识库索引具备版本管理。

可扩展的工具与技能

内置工具、MCP 服务器、CLI 应用、图像/视频/语音生成模型之外，还能从 EduHub 社区安装技能。

可审视的 Memory

L1 轨迹、L2 表层摘要、L3 综合构成三层记忆体系，每条结论都能在 Memory Graph 中追溯到证据。

安装与启动

项目提供四种安装路径，所有路径共享同一工作区布局：配置位于启动目录下的 data/user/settings/。

方式一：从 PyPI 安装

适用于完整本地 Web 应用 + CLI，无需克隆仓库。要求 Python 3.11–3.13 和 Node.js 20+。

mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init     # 交互式配置端口、LLM 提供商、可选 embedding
deeptutor start    # 启动后端与前端，保持终端开启

init 命令会提示输入后端端口（默认 8001）、前端端口（默认 3782）、LLM 提供商、Base URL、API Key、模型，以及用于知识库的可选 embedding 提供商。启动后访问终端输出的前端地址，默认 http://127.0.0.1:3782。Ctrl+C 即可停止服务。

方式二：从源码安装

面向二次开发。使用 Python 3.11–3.13 与 Node.js 22 LTS：

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
python3 -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
( cd web && npm ci --legacy-peer-deps )
deeptutor init
deeptutor start --dev

--dev 启用 Next.js HMR。额外可选依赖：

pip install -e ".[dev]"             # 测试/代码检查工具
pip install -e ".[partners]"        # Partner IM 通道 SDK 与 MCP 客户端
pip install -e ".[matrix]"          # Matrix 通道（无 E2EE/libolm）
pip install -e ".[matrix-e2e]"      # Matrix E2EE，需 libolm
pip install -e ".[math-animator]"   # Manim 插件，需 LaTeX/ffmpeg

方式三：Docker

单容器部署，镜像位于 GitHub Container Registry：

• ghcr.io/hkuds/deeptutor:latest 稳定版
• ghcr.io/hkuds/deeptutor:pre 预发布版

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

只需发布 3782 端口。浏览器仅与前端源通信，容器内 Next.js 中间件将 /api/* 与 /ws/* 转发到 FastAPI 后端。8001 端口按需发布，用于直接 curl 调用 API。

配置、API Key、日志、工作区文件、Memory 与知识库持久化在 deeptutor-data 卷中。

反向代理与远程 Docker

单容器场景下浏览器只与 :3782 前端通信，无需配置 API 基址。如采用前后端分离部署，需在 data/user/settings/system.json 中设置：

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

next_public_api_base_external 与 public_api_base 作为低优先级后备。CORS 基于前端源地址而非 API URL，启用鉴权时需在 cors_origins 中列出确切的前端源。

连接宿主本地模型服务

容器内 localhost 指向容器自身。访问宿主上的 Ollama、LM Studio、llama.cpp、vLLM、Lemonade 时使用宿主网关：

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

在 Settings → Models 中将对应 Base URL 指向 host.docker.internal：

服务	Base URL
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