DeepTutor 完整指南：3 步搭好你的个性化 AI 导师，带记忆、带知识库-编程实验室

DeepTutor 完整指南：3 步搭好你的个性化 AI 导师，带记忆、带知识库

【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor

DeepTutor 是一个本地运行的开源代理原生个性化教学平台。你把讲义传进知识库后可以直接就原文提问；它用三层记忆记住你的学习轨迹，还能把材料编译成可交互的"活书"。适合个人学习者、教师和开发者。

3 步跑通本地部署 🚀

假设你手上有课程 PDF，想让 AI 基于这些材料给你答疑，而不是泛泛而谈。先让 DeepTutor 跑起来：

安装（需要 Python 3.11–3.13 和 Node.js 20+）

pip install -U deeptutor deeptutor init # 按提示填端口、模型 API key

启动并打开浏览器

deeptutor start # 终端会打印前端地址，默认 127.0.0.1:3782

在Settings → Models里确认模型配置，然后开聊。跳过init也能启动，只是模型项留空，稍后在设置页补上即可。

第一次对话时，你可以直接附上文件再提问。如果答案质量不如预期，多半是下一步——知识库——还没配。

知识库：上传 PDF 后直接就原文提问

这是 DeepTutor 个性化教学的地基。在知识中心新建一个库，上传教材、讲义或笔记，之后聊天时把该库挂到会话上下文里，回答就会引用你文档里的具体内容。

举个具体例子：上传一本物理教材 PDF，问"第三章里两种解法的区别是什么"，它会给出带原文依据的回答，而不是通用套话。检索引擎可以选：LlamaIndex（默认，本地向量 + BM25）、GraphRAG 和 LightRAG（知识图谱检索）、PageIndex（带页级引用）、LightRAG Server，甚至直接关联你的 Obsidian 库。每个知识库绑定一个引擎；重建索引会写入新的version-N目录，不会毁掉正在用的旧索引。

相关源码可以看知识库管理和 RAG 检索管线。

三层记忆：它记得你学过错什么

普通 AI 助手每次对话都从零开始。DeepTutor 的记忆是明文文件，三层结构，可以直接读、直接改：

L1 事件流：追加式记录（trace/<场景>/<日期>.jsonl）
L2 场景要点：每个场景一份摘要（L2/<场景>.md）
L3 跨场景综合：整合你的偏好与近况（L3/<profile>.md等）

DeepTutor 三层记忆图谱可视化

它实际长这样：对话中你提过"导数我总是绕晕"，之后系统给你生成测验时就不会再堆简单导数题。L2 引用 L1、L3 引用 L2，所以记忆图谱里的每条结论都能一路追溯到原始事件——个性化不是黑盒。整理记忆的预算参数在Settings → Memory调整，源码在记忆系统。

活书引擎：把材料变成能读的教材 📖

把课程的 PPT、讲义或聊天记录变成一本"活书"。它不是静态 PDF：创建时先给出章节大纲让你确认，再编译成带类型的块——文本、测验卡、记忆卡、Manim 动画、交互式 HTML 模块、概念图谱。每一页自带一个小聊天窗，可以随时就当前页追问。

例子：把一章编译出来后，你发现某节讲得抽象，可以只改那个块——插入、移动、重新生成，或直接把它的类型从文本换成测验卡，不用重写整章。之后用deeptutor book health检查源材料是否已经和编译页面脱节。书籍引擎源码在 deeptutor/book/。

一个代理循环驱动全部模式

聊天、测验、深度研究、解题、可视化，跑在同一个代理循环上——你切换的是目标，不是引擎，上下文跟着学习者走。

这个循环的规律很简单：模型按轮次思考，需要时调用工具（RAG、联网搜索、代码执行、画图），观察结果，最后给出不带工具的答复。遇到拿不准的地方，它不硬猜，而是通过ask_user暂停这一轮、先问你一个结构化问题。想扩展新功能时，往 capabilities/ 里加一个插件目录即可，能力注册机制在 deeptutor/capabilities/registry.py。

三类角色的上手路径

个人学习者 🎯

建自己的知识库：知识中心新建库并上传课程材料，之后所有提问都挂上这个库。
生成复习计划：在 Learning Space 创建 Mastery Path，系统按阶段出题并批改，通过当前关卡才解锁下一关。

DeepTutor 学习空间掌握路径

回看学习轨迹：终端里跑deeptutor memory show，直接看 L2/L3 记忆文档。

教师 🍎

用活书引擎编教材：确认大纲 → 编译章节 → 在某章后插入测验卡，学生读的时候就能自测。
用协作写作打磨讲义：选中一句话让它改写或扩写，修改以 diff 呈现，你确认后才落盘，源码见 co_writer/。

DeepTutor 协作写作编辑面板

给全班开多用户模式：开启认证后，每个学生的会话、记忆、知识库互相隔离，模型和知识库由管理员通过授权分配。

开发者 🛠

用 JSON 驱动：deeptutor run deep_solve "求 sin(x^2) 的导数" --format json，每行输出一个事件，适合接到自己的自动化流程里。
让别的 agent 来操作 DeepTutor：仓库根目录的 SKILL.md 是一份操作交接文档，任何会用工具的 LLM 读一遍就能上手。
扩展能力：参考 deeptutor/capabilities/ 的插件模型加一个新功能目录，或用deeptutor skill install安装社区技能。

4 种部署方式速查

方式	适合谁	起点命令
PyPI 安装	日常使用完整 Web 应用	`pip install -U deeptutor`
源码安装	参与开发、看内部实现	克隆仓库后`pip install -e .`，前端`npm ci`
Docker	服务器部署、隔离环境	拉取镜像运行，只暴露 3782 端口即可
仅 CLI	只要终端交互、不要 Web 界面	源码目录下安装`packaging/deeptutor-cli`

容器部署细节（无 root、远程代理、端口映射）见 CONTAINERIZATION.md。

避坑清单：先检查这 6 件事 ⚠️

没配模型 key：应用能启动，但模型项是空的，先填 Settings → Models。
想用知识库却忘了 embedding：RAG 相关功能需要先配好 embedding 模型，不配就只能用纯聊天。
版本不对：Python 3.11–3.13、Node 20+（源码安装建议 Node 22 LTS）。
Docker 里连本地 Ollama 失败：容器内localhost是容器自己，Base URL 要写host.docker.internal。
服务器部署忘开认证：认证默认关闭、单用户运行；公网部署务必先开启，首个注册用户是管理员。
一个文件解析失败就想删库：不用。单篇文档可以从库里移除，重建索引也不会覆盖旧版本。