HKUDS/DeepTutor · 上手攻略
- 仓库：HKUDS/DeepTutor
- 链接：https://github.com/HKUDS/DeepTutor
- 分类：agent / tutoring（Trending · agent 分类）
- 作者：Tom
- 更新：2026-07-07
它是什么
DeepTutor 是一个Agent 原生的个性化辅导系统，由香港大学数字智能系统实验室（HKUDS）开发，定位是让 AI tutor 真正介入学习过程、而非仅仅回答问题。它在 2025 年初的 arXiv 论文（arXiv:2604.26962）中被提出，当前最新版本为 v1.5.0（2026.7.4），处于活跃开发状态。
核心设计哲学：学习不是问答，而是有目标、有反馈、有记忆的循环过程。DeepTutor 的 Agent runtime 自始至终运行在一个统一的上下文中，学习者在各个"界面"（聊天、书籍、记忆、知识库）之间切换不会丢失进度。
解决什么问题
传统 AI tutoring 的困境： - 上下文割裂：在不同标签页切换时记忆丢失，无法跨会话持续追踪学习者的薄弱点 - 知识面窄：无法基于真实的知识库、教材或 PDF 做 RAG 检索式辅导 - 被动问答：只是回答问题，缺乏主动引导、测评和掌握度追踪 - 无法集成本地工具：Claude Code、Codex 等本地编码智能体无法与 tutoring 系统联动
DeepTutor 的解题思路：一个 Agent runtime + 八个共享上下文的界面，让学习数据（记忆、对话、书摘、知识库）始终在同一个 Agent 的工作内存中流转。
快速安装
方式一：pip 一行（推荐，最快）
mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init
deeptutor start
# 打开 http://127.0.0.1:3782
方式二：Docker 单容器（无需 clone）
docker run --rm --name deeptutor \
-p 127.0.0.1:3782:3782 \
-v deeptutor-data:/app/data \
ghcr.io/hkuds/deeptutor:latest
# 打开 http://127.0.0.1:3782
方式三：CLI 仅安装（无 Web UI，适合 server / Claude Code 集成）
git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
python3 -m venv .venv-cli && source .venv-cli/bin/activate
pip install -e ./packaging/deeptutor-cli
deeptutor init --cli
deeptutor chat
依赖：Python 3.11+ · Node.js 22 LTS
核心用法
1. 界面导航（八个入口）
启动后访问 http://127.0.0.1:3782，有八个界面：
| 界面 | 功能 |
|---|---|
| Home | 默认 Agent loop，工具 + 检索 + 附件 + 记忆一体化 |
| Partners | 持久化伙伴，有自己的人设、知识库和 IM 渠道 |
| My Agents | 接入本地 Claude Code / Codex，实时咨询 |
| Co-Writer | 基于知识库或网络检索的 Markdown 协作编辑 |
| Book | 把知识库和笔记编译成交互式"活书" |
| Learning Space | 可复用技能、人设、笔记本、题库 |
| Memory | 三层记忆（L1/L2/L3），可审计 |
| Knowledge Center | 版本化多引擎 RAG 库（GraphRAG / LightRAG / PageIndex） |
2. 接入本地 Claude Code / Codex
在 My Agents 界面填入本地 Claude Code 的工作目录路径，即可让 DeepTutor 实时调用本地 Agent 的能力（v1.4.7+）。
3. 配置 LLM Provider（Settings）
支持 OpenAI / Anthropic / Gemini / NVIDIA NIM / Ollama / LM Studio / llama.cpp 等，任选其一：
Settings → LLM → 选择 Provider → 填入 API Key
Docker 场景下，如需连接宿主机上的本地模型（如 Ollama）：
docker run --rm --name deeptutor \
--add-host=host.docker.internal:host-gateway \
-p 127.0.0.1:3782:3782 \
-v deeptutor-data:/app/data \
ghcr.io/hkuds/deeptutor:latest
然后在 Settings 中设置 Base URL：http://host.docker.internal:11434/v1
4. 知识中心 RAG 配置
支持三种检索引擎（v1.5.0）： - LightRAG（轻量，新增） - GraphRAG（知识图谱） - PageIndex（页面索引）
上传 PDF/DOCX/XLSX/PPTX 文件后，选择引擎并配置 chunk 参数，DeepTutor 自动索引。
5. Guided Learning（引导式学习）
在 Learning Space 创建学习路径，通过多选题/简答题逐步推进，每个类型有hard mastery gate（必须达到一定正确率才放行）。v1.4.5+ 将 Guided Learning 重建在 chat agent loop 上，有 /learning 仪表板。
6. CLI 用法（deeptutor start / chat / init）
deeptutor init # 初始化配置（交互式）
deeptutor start # 启动 Web 服务器
deeptutor chat # 进入 CLI chat 模式（无 UI）
典型适用场景
- 个人学习助手：上传教材 PDF，建立知识库，让 AI 陪你做章节总结、练习题、错题分析
- 编程辅导：接入 Claude Code / Codex，让本地编码 Agent 融入 tutoring 系统，做项目级别的编程教学
- 企业内训：部署知识中心（RAG），给员工配置不同的 Learning Space，追踪掌握度
- 活书协作：将多个知识源（Notion/Obsidian/文件）编译成"活书"，可交互式翻页和提问
- 研究辅助：Deep Research 模式（v1.4.0+ GA）做主题调研，自动生成报告
坑与注意
| 坑 | 说明 | 解决方案 |
|---|---|---|
| 首次启动 API Key 问题 | 错误的 API Key 会导致后端启动失败，页面无响应 | 先开 Settings → LLM 页面再填 Key；或删除 volume 中的 model_catalog.json 重置 |
| 端口 3782 被占用 | 启动时报端口冲突 | lsof -i :3782 查进程，或 -p 127.0.0.1:8088:3782 换端口 |
| Docker rootless Podman | v1.4.13 之后支持，之前版本可能起不来 | 更新到最新版；或改用 pip install 方式 |
| 非 ASCII 路径（FAISS） | 旧版本 FAISS 处理不了中文路径 | v1.4.14+ 已修复 |
| RAG 重新索引慢 | 知识库文档多时，首次索引耗时 | 使用 PyMuPDF4LLM（v1.4.12+ 轻量引擎）或先小批量测试 |
| 多用户隔离 | v1.3.8+ 才引入多用户，之前的版本是单用户 | 确认版本 ≥ 1.3.8 再部署多用户场景 |
| 企业特性（ee/目录） | 部分高级功能在 ee/ 目录，需商业许可 |
开发/测试不受限，生产使用需许可证 |
与同类对比
| 维度 | DeepTutor | Khanmigo（可汗学院） | Socratic（Google） | n8n + RAG |
|---|---|---|---|---|
| 架构 | Agent-native, 自研 runtime | LLM API 调用 | LLM API 调用 | 工作流引擎 + RAG 节点 |
| 记忆持久化 | 三层 Memory（L1/L2/L3） | 无持久化 | 无 | 视具体 workflow |
| 多工具集成 | Claude Code / Codex / IM 渠道 | 限可汗平台 | 限 Google 搜索 | MCP 驱动，灵活 |
| RAG | 多引擎内置 | 无 | 无 | 需手动配置 |
| 学习路径追踪 | Guided Learning + mastery gate | 有（课程内） | 无 | 需自建 |
| 部署方式 | Docker / pip / 源码 | 全托管云 | 全托管云 | 自托管 |
| 开源 | Apache 2.0 | 否 | 否 | 部分开源 |
DeepTutor 的核心优势：真正把 Agent 作为 tutoring 的引擎，而不是在 LLM 外面套壳。它的 Memory 设计（三层可审计）和多 Agent 协作（Partners / My Agents）是市面上 tutoring 工具少有的特性。
一句话推荐结论
如果你想做一个真正了解学习者、记得一切、能主动引导的 AI tutor，而不是一个只会回答问题的聊天机器人，DeepTutor 是目前最完整、最可定制的开源选择——尤其是需要串联 Claude Code/Codex 做编程辅导、或构建多引擎知识库 RAG 场景时。
数据来源
- GitHub README（https://github.com/HKUDS/DeepTutor）
- DeepTutor 官网（https://deeptutor.info）
- DeepTutor 文档（https://docs.deeptutor.info/get-started/docker）
- GitHub Releases Changelog（v1.4.0 ~ v1.5.0）
- arXiv:2604.26962（论文层面信息，公开摘要）
⚠️ 版本号（v1.5.0）和发布日期（2026.7.4）来自 2026-07-07 的 GitHub 数据，未来可能有变化，安装前建议核实 release 页最新版本。