DeepTutor：开源的 AI 私人家教工作台

用聊天窗口学东西有个通病：金鱼记忆。今天讲明白的概念，下周开个新会话又得从头解释一遍；
错过的题、读到一半的资料、积累的笔记，散落在各个网页里，谁也不认识谁。
DeepTutor 是港大 HKUDS 实验室开源的学习工作台，想把这些串成一个整体——
装在自己电脑上，资料是自己的，记忆看得见摸得着。这篇按模块拆开讲讲它到底是怎么运转的。

定位

简单来说就是一个装在你自己机器上的 AI 家教，Apache 2.0 开源，pip install deeptutor 就能起。
它自己不带「脑子」——大模型用你配的（OpenAI、Claude、Gemini，或者本机跑的 Ollama 都行），
它提供的是脑子之外的所有东西：资料库、记忆、出题、批改、写作、画图、找人帮忙的路子，全在一处。
和网页版聊天机器人的根本区别有三条：资料存在本地自己管；AI 对你的了解是可以打开检查的文件，不是黑箱；
所有学习模式共用一套上下文，聊天里建的资料库，出题、写书、做研究时都认识。

（交互版，可缩放、可播放调用轨迹。）

统一引擎

DeepTutor 有六种玩法：聊天、出题（Quiz）、深度研究（Research）、可视化（Visualize）、解题（Solve）、学习路径（Mastery Path）。
传统做法是六个功能六套代码，它的做法是全部跑在同一个循环上——换模式换的是目标，不是引擎。

这个循环说穿了很朴素：模型一轮一轮地想，觉得需要查资料、算个数、搜个网，就调对应的工具，
看到结果接着想，直到给出一条不带任何工具调用的消息，这轮才算答完。
有个设计值得单独夸：ask_user。模型拿不准你想要什么的时候，可以暂停这一轮，正经问你一个问题，等你答了再继续——
不瞎猜，这在「家教」这个场景里比什么都重要。

（交互版）好处是实打实的：你在聊天里选好的资料库、人设、模型，切到出题或研究模式时原样跟过去，
不用在六个功能里各配一遍。

模块详解

聊天

打开就是聊天，但这个聊天窗比一般的能干得多。工具分两类：
一类是你手动开关的——头脑风暴、网页搜索、论文搜索、深度推理、几何分析，配好生成模型后还有画图和生视频；
另一类是「看情况自动上桌」的——你选了资料库它就带上检索，你贴了文件它就能读，聊到代码它能跑，随时能记笔记、翻记忆。
上下文也分两种：「粘性的」（资料库、人设、模型这些，选一次整个会话都带着）和「一次性的」（+ 菜单里临时引用某个文件、某段历史、某本书、某道错题，只管这一轮）。

知识库

原理不神秘：AI 回答之前，先在你给的资料里检索相关段落，把找到的内容连同问题一起交给模型——行话叫 RAG，说白了就是开卷考试。
DeepTutor 的特点是「开卷的方式」可以挑，七种检索引擎各有脾气：
默认的 LlamaIndex 在本地建向量索引，通用稳妥；PageIndex 能给出精确到页码的引用；
GraphRAG 和 LightRAG 先把资料织成知识网再检索，适合概念之间关系复杂的教材；
还能外接独立的 LightRAG 服务、腾讯 IMA 的在线资料库，或者直接把你的 Obsidian 笔记库挂进来读写。
工程细节也照顾到了：重建索引时新索引写进新目录，旧的完好保留，不会重建到一半两头空；
某个 PDF 解析失败，可以单独把它删掉，不用整库推倒重来。

三层记忆

这是 DeepTutor 最有辨识度的设计。AI 对你的了解不是藏在向量库里的一团数字，而是三层纯文本文件：
L1 是流水账——每个界面上发生的每件事，一条条按日期记着；
L2 是摘要卡——每个学习场景（聊天、笔记、做题、读书……）各一份提炼过的要点；
L3 是总评——跨场景综合出来的你：什么水平、最近在学什么、偏好什么讲法。
关键在引用链：L2 的每条摘要注明来自 L1 的哪几条流水，L3 的每句判断注明来自 L2 的哪几条摘要。
界面里有一张记忆图谱，总评在圆心、摘要在中环、流水在外圈，任何一句「它认为你怎样」都能一路点回当天的原始事件。
觉得它记错了？直接改文件，或者 deeptutor memory clear 清掉重来。

出题、错题本与学习路径

出题模式按你指定的范围和数量生成题目，答完给批改和讲解；
做错的题进题库，你的答案、参考答案、讲解一起存档，之后能在任何聊天里 @ 出来复盘。
学习路径（Mastery Path）更进一步：给一个目标，它排出一条带关卡的练习计划，每类题型有掌握度门槛，没过关不放行——
不是刷完就算，是刷会才算。

深度研究与解题

研究模式产出带引用的报告，深度和形式可调，来源可以是你的资料库加上网络搜索；
解题模式把一道题拆成一步步的推演过程写给你看，配合几何分析工具还能处理作图题。

可视化与数学动画

图表、SVG 示意图、可交互的 HTML 小组件都能生成；
数学动画用的是 Manim——3Blue1Brown 那些丝滑数学视频背后的同一个引擎，讲傅里叶级数时让波形自己动起来。

活书

选一批材料（资料库、笔记、题库、聊天记录都行），它先给你一份章节大纲过目，你点头它才动笔——
不是一锤子买卖的生成。产出的「书」由一块块类型化的内容拼成：正文、测验卡、闪卡、时间线、代码、交互组件、动画、概念图，
每一块都能单独重写、挪动、换类型，每一页还带一个页内聊天，读到哪问到哪。
源材料更新之后，deeptutor book health 能检查出哪些章节已经跟资料脱节了。

Co-Writer

分屏的写作台，左边写右边实时预览。它的规矩是改动必须经你的手：
选中一段，说「扩写」「精简」「换个讲法」，AI 给出的修改以红绿对照的形式摆出来，你点接受才落进文档；
改写之前它还可以先去资料库或网上找证据，改动的依据全程留痕。

Partners

Partner 是常驻的伙伴：一份 SOUL.md 写人设，配自己的资料库、自己的记忆，然后接到你常用的聊天软件里——
飞书、Telegram、Slack、Discord、钉钉、QQ、企业微信、WhatsApp、Teams 等十几种渠道。
它读得到主人的记忆，但只往自己的记忆里写；给孩子配一个耐心的讲题伙伴、给自己配一个论文陪读，互不串味。

My Agents

两件事。一是现场咨询：你机器上装的 Claude Code、Codex、Gemini 等编码助手，能在聊天中途被请来干活，
它的操作过程实时流进活动面板，干完把结论带回对话。二是导入旧账：把 Claude Code、Codex 攒下的历史会话导进来，
变成可搜索、可引用的档案——引用时它保持「别人的对话」的身份，不会被冒充成 DeepTutor 自己说的话。

技能市场与安全闸

技能就是一份写给 AI 看的玩法说明书（SKILL.md），教它按某个套路做事：苏格拉底式提问、闪卡制作、作文点评。
社区市场 EduHub 里一条命令安装，也可以发布自己的。装之前有一道闸：
被举报的包直接拒装；压缩包防炸弹防越界解压；只放行文本类文件，二进制进不了工作区；
说明书里「强制每次都生效」的字段会被剥掉——装来的技能没资格塞进每一条系统提示词。

代码沙箱

要生成 Word、PDF、PPT、Excel 这类文件，模型的做法是现写一段 Python 脚本然后执行。
执行发生在受限的子进程沙箱里；多容器部署时更进一步，代码被送到一个专门的低权限容器里跑。
单机默认是开的——让 AI 在你机器上跑它自己写的代码终归是个信任决定，配置里一个开关就能关掉，代价是这类文件生成不了。

多用户

默认单用户免登录。打开认证后，第一个注册的人是管理员，之后每个用户各有隔离的工作区；
模型、资料库、技能由管理员按人派发，普通用户拿到的是「能用」的授权，看不到 API key 本体。

命令行

网页上有的功能命令行全有：deeptutor chat 是交互式对话，deeptutor run deep_question "热力学" --config num_questions=5 一条命令出五道题。
加 --format json 后输出变成一行一个事件的机器可读流——这是特意给「别的 AI 操作它」留的口子，
仓库里备着一份交接文档，丢给任何会用工具的模型读一遍，它就会驱动整个 DeepTutor。

安装

mkdir my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init     # 问你端口、模型服务商、API key
deeptutor start    # 打开 http://127.0.0.1:3782

不想装 Python 环境就 Docker 一行：

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

需要 Python 3.11+ 和 Node 20+（网页版），资料、设置、记忆全在启动目录的 data/ 下面，备份就是拷这个目录。

边界与提醒

它是工作台不是模型，聪明程度取决于你接的是什么：接顶级模型体验顶级，接本地小模型就得接受本地小模型的水平，
而且资料在本地不等于数据不出门——聊天内容和资料片段会发给你配置的模型服务商，真要全程离线，模型也得本地跑。

功能面这么大，代价是两头的：学习曲线不平，以及成熟度不均。
这项目迭代快得吓人，半年发了六十多个版本，翻 release notes 能看到每周都在修上一批的漏——
活跃是真活跃，追新也真要有心理准备，重要场景钉住一个用着稳的版本比天天升级明智。

让模型写代码再执行，是全篇最需要清醒的地方。沙箱和低权限容器是缓冲，不是保票，
单机用默认开着图方便，多人部署务必走容器方案，或者干脆关掉换个安心。

翻它 release notes 的时候总想起自己书架上那本只翻到第三章的高数——工具是一代比一代好了，剩下的事还是得人来。