58,003 star，v1.7.2 于 11 月 6 日发布，近四周 1,010 次提交（图源：自绘封面）上个月我写过 PageIndex，当时是把它当独立工具拆的：树状索引、vectorless 检索，写得挺起劲。写完没几天，我在港大 HKUDS 团队另一个仓库的更新日志里又撞见了它——v1.5.15 的一条记录写着「PageIndex OSS you host yourself」，再往下翻，LightRAG、GraphRAG、WeKnora 全都排着队出现在同一个知识库里。
这个仓库叫 DeepTutor，把我写过的几个检索项目全收编成了它自己的可选项。
我盯着它看了一周，越看越觉得这事不太一样。市面上知识库工具已经卷烂了：上传 PDF、切块、向量化、问答，大家比的还是「答案捞得准不准」。但有一个环节所有人都在绕——我到底学会了没有。我攒了三年多的技术 PDF 和会议记录，RAG 工具换了好几个，每次都是同一个剧本：问一句答一句，答完散场。上周刚问错的问题，这周原样再错一遍，它根本不知道我哪里薄弱。
DeepTutor 做的就是补这一段。它是港大 HKUDS 团队（就是做 LightRAG 那拨人）去年 12 月底才正式发布的开源学习工作台，Apache-2.0 协议，到今天攒了 58,003 个 star、7,062 个 fork，一共发了 90 个版本，最近一次 v1.7.2 是 11 月 6 日刚出的。近四周 1,010 次提交，迭代速度是按天算的。
丑话在前：这次我没装。它要么接你的大模型 API，要么引导你配一堆服务，我在调研阶段就把安装脚本、文档和高频 issue 逐段对完了，下面所有命令和预期输出都来自官方 README 和文档站 deeptutor.info，我没替它们跑过一遍。想抄作业的，装之前自己再核一眼。
教、练、记是一条流水线，不是三个标签页
先把它的能力摊开看。DeepTutor 的界面分三大块：Home 是聊天、任务板、日历和学习笔记本；Learning 是书、掌握路径、沉浸式阅读和练习；Resources 是知识中心、收藏、学习日志和题库。听着像又一个功能堆砌的大而全，但我拆完发现它的能力其实是按「教—练—记」一条线组织的，每一环都有东西接住上一环。
教这一环里最有意思的是 Book：你选一批资料，它先给你一个章节大纲让你审，通过之后把内容编译成一本「活书」——每一章是可编辑的类型化块，文字、测验、闪卡、时间线、交互图表混排，每页还有自己的页内问答。不是把 PDF 转个格式糊弄你，是重新组织过、能随时提问的学习材料。
练这一环是 Mastery Path 和 Practice。前者把一个学习目标拆成知识点地图，过关了才放行下一站，没掌握就继续练，每个知识点挂着「掌握证据」；后者把做过的题沉淀成题库，答错的、 recall 评分低的自动排下一次复习时间。测验结果还能导出成 Anki 卡片——文件导入 Anki 后进一个 DeepTutor:: 前缀的牌组，重复导入会更新已有卡片而不是堆重复的。
沉浸式阅读也归在练这一环：文档、网页、视频、音频都能当「陪着读」的素材，对话逐条挂在出处上，引用精确到页码和时间戳，标注和进度跟着源走。B 站和 YouTube 的视频链接贴进去，哪一秒没听懂就问哪一秒——对跟网课自学的人，这个比单纯问答实用得多。书这边同样有保养工具，deeptutor book health 会标记源文件漂移，deeptutor book refresh-fingerprints 刷新基线，资料更新后书不会静默烂掉。
记这一环就是三层记忆系统，下面单独说。
哪几个是真本事，哪几个还毛糙？我的判断：多引擎知识库、kb eval、三层记忆这三样是实打实的工程活；Book 和视频学习这类生成密集的功能，质量完全跟着你接的模型走，模型不行它就是昂贵的玩具；Partners（给每个伴侣式助手独立人格和 IM 通道，能接飞书、Telegram、钉钉、QQ 等十几个渠道）设计很花哨，但对单人学习场景属于锦上添花，别为它装这套东西。
知识库不是一个人的舞台，kb eval 才是
它知识中心的设计我很少在同类项目里见到：一个知识库绑定一个检索引擎，LlamaIndex 是默认（向量加 BM25 混合，可选 cross-encoder 重排），往下是 PageIndex、GraphRAG、LightRAG、WeKnora，甚至能直接连腾讯 IMA 的库、MarginNote 4 的学习数据、一个 Obsidian vault 或者 Kiwix 的 ZIM 离线档案。我的几个检索工具不用二选一，建几个库挨个试。
但真正让我眼睛一亮的是这个命令：
deeptutor kb eval <知识库名> --dataset qa.jsonl --top-k 5 --save baseline.json
qa.jsonl 每行一个 JSON 对象，写你的问题和理想情况下应该召回的段落：
{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}
跑完输出 Recall@k、Precision@k、nDCG@k、MRR、MAP、Hit@k 一整排信息检索指标，纯函数计算，没有模型当裁判。换个引擎重建索引，再跑一遍存成第二份报告，deeptutor kb eval-diff baseline.json candidate.json 直接对比每个指标、每个用例的涨跌。
这个设计戳中了我一个老毛病：每次换检索方案，我心里都没底，全靠聊几句的体感下结论。现在有基线了。官方文档还留了一句挺清醒的话——语义等价它不判，只算文本重合。这正是它诚实的地方。
记忆不进向量库，全摊在文件里
三层记忆是我认为这个项目最值钱、也最能看出取舍的设计。
L1 是原始层：工作区镜像加一份只追加的事件轨迹，按天存 jsonl；L2 是中间层：每个学习场景提炼出的受控事实，Markdown 文件，带指回 L1 的引用；L3 是顶层：跨场景的综合理解，也记录它由哪些 L2 汇成。三者都能在 Memory Graph 里可视化，每条综合结论都能点开看证据链。
代价是什么？它不是向量记忆。mem0 那类方案把记忆埋进向量库，检索时语义模糊匹配，什么都「记得住」一点；DeepTutor 的记忆是显式文件，坏处是查全率靠 L2/L3 的整理预算——官方管这个叫 consolidator 的 Update / Audit / Dedup 预算，得自己在设置里调。记忆没整理，它就真不知道。
但我站它这边。学习场景里记错比忘掉更糟：它把我上次答错的题记成「已掌握」，我连反驳的机会都没有。文件摊开、可以手动改、有证据链，错了能纠正——这是黑盒向量库给不了的。同团队做过 LightRAG 的人，把「可审计」这个执念带进了产品，我能看出来。
四条安装路，坑各不相同
官方给了四条路，我逐条对完，各自的门槛和坑先列清楚。硬件方面官方没有给整机配置表——这不奇怪，DeepTutor 本身不跑模型，大模型要么接云端 API 要么另起本地服务，所以它对 GPU 零要求。下面两档是我的推算：最低可用 4 核 CPU、8GB 内存、10GB 磁盘（本体加 Docker 镜像的量级），建议配置 8 核、16GB 内存——要同时跑本地模型服务或大知识库索引，内存别省。
桌面版（预览状态）：Release 页直接下 dmg 或 exe，Python 和 Node 都打在里面，不用碰终端。坑是 Windows 版未签名，SmartScreen 会拦，得点「更多信息」再运行。
Docker，官方主推的最快路径：
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，数据和设置存命名卷。
PyPI 全量版要 Python 3.11–3.14 加 Node.js 20.9 以上：
mkdir -p my-deeptutor && cd my-deeptutor
python -m pip install -U "deeptutor[full]"
deeptutor init # 交互式向导：端口、模型、可选的 embedding 和搜索
deeptutor start # 前后端一起起
纯 CLI 最轻，pip install -U deeptutor 装核心包，deeptutor init --cli 初始化后 deeptutor chat 直接用，不需要 Node。
多用户部署的账也顺便算清。认证默认是关的，单用户模式；打开 auth 之后一个数据目录里能同时装下管理员工作区、隔离的每用户工作区和伴侣助手工作区。管理员建的本地账号分 Standard、Learner、Custom 三档：Learner 角色锁死学习类能力之外的东西，配自适应画像，设备凭证可撤销、带过期时间和每日限额；家长角色能看报告、审材料、重置凭证。给家里孩子搭环境时这个分层挺关键——模型 API key 只在管理员手里，孩子那边的账号拿不到原始凭证。
一条容易踩的版本坑：从 1.6.15 或更早版本升级到 1.7.x，官方明确要求先停服务、备份运行目录、卸载旧的 deeptutor-cli 包再装新家族——这个跨版本升级后面会讲到它出过的事故。
从一条 Docker 命令到第一道错题
我没真跑，下面这个最小流程是我照官方文档逐行核过的，能照着走：
第一步，Docker 一条命令起服务，开 127.0.0.1:3782，界面就绪。
第二步，Settings → Providers 配模型。这一步决定整个系统的成色——它自己不带模型，OpenAI、Claude、Gemini、通义、智谱、本地 Ollama 全都能接，还有个实验性的 Codex OAuth，用你已有的 ChatGPT 订阅直接登，不用 API key。确认配置是否健康有一条专门命令：
deeptutor doctor --online --format json
它会探测运行时和你配的模型端点，JSON 输出里逐项给结论。起不来的时候先跑它，别瞎猜。
第三步，建一个学习工作区，把一份教材 PDF 拖进知识中心建库，选个检索引擎（第一次建议默认 LlamaIndex），等索引完成。
第四步，走一个完整闭环：让它在聊天里讲一道你不会的题；追问两轮之后让它围绕这个知识点出三道变式题进练习；答错的会进题库并排复习计划；最后打开 Memory Graph 看它记了你什么。四步走完，它和普通聊天框的差别不用我说。
想要机器可读的输出，CLI 支持 NDJSON 流式事件，官方文档给的会话续接写法是这样：
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
同一份 session id 跨轮次接续，仓库根目录还带着一份 SKILL.md 让别的程序能照着驱动它——这是把「被自动化调用」当一等公民设计的路数。凭证安全上也留了心眼：API key 从不经过模型侧，配置变更时它只打开对应的表单让你自己填；Codex OAuth 的令牌放在多容器部署里 exec 沙箱够不到的目录，也不碰你本机的 Codex 登录态。
一千次提交堆出来的稳定性债
open issue 我翻到 190 个，加上第三方文章里的实测反馈，坑主要集中在四类。
第一类是升级事故，也是我最想提醒的一条：issue #2330，应用内更新器只升级核心包，从 1.6.x 升到 1.7.x 后所有功能模块都没装上，DeepTutor 直接起不来。这个 issue 目前还开着。所以跨大版本升级请老老实实按官方迁移手册走，别信界面里那个一键更新。
第二类是知识库的解析盲区：issue #431（11 个跟帖）扫描版 PDF 进知识库报「Skipped empty document」——扫描件是纯图片，文本抽取引擎抽不出字。要用扫描件，得在设置里把解析引擎换成 MinerU 这类支持 OCR 的，官方文档写明了 Text-only 和部分引擎不干这活。
第三类是权限与体验的毛边：issue #1228，Learner 账号访问课程接口直接 403，界面还把它伪装成「空列表」——孩子看到的是没课，实际是没权限，这种误导性的静默失败挺伤人。issue #451 有用户问怎么关掉周期性的大模型健康检查省 token，说明后台悄悄花钱这件事真实存在。另外第三方文章反复提醒：默认不开登录验证，第一个注册的用户自动成为管理员——打算部署给家人用的话，先开 auth 再注册。
第四类是模型依赖的赤裸现实。一家国外科技媒体用本地 3B 小模型实测：复利计算题步骤全对、数字全错，三道练习错两道；B 站有 UP 主测五段知识库，三道答案故意不在库里的题，中文召回只有 0.4，换英文测试召回反而虚高到 0.6——检索只比字面重合。还有博主抱怨 init 是纯交互式向导，端口冲突只能手改配置文件，没有任何命令行参数能跳过；中文回答默认会漂成英文，模型输出语言要自己单独设置。
这些坑没有一条是我编的，每条都有编号或出处。合起来看规律也清楚：迭代太快（四周 1,010 次提交、几乎两三天一个版本）的代价就是稳定性债，功能先行，债慢慢还。
装它之前，先想清楚模型钱和你的耐心
我的结论：值得上手，但只对特定的人。
如果你是自托管爱好者、长期自学者，或者想给孩子搭一个记得住错题的家庭学习环境，DeepTutor 是目前开源阵营里把「学习闭环」做得最完整的，没有之一。三层记忆可审计、kb eval 能量化、数据全在你自己机器上，这三条单独拎出来都能当选它的理由。
如果你想要的是开箱即用的问答，直接装它你会失望——配置项多到选择困难是多个第三方体验共同提到的问题，模型还得自己找、自己付钱。
替代方案我点名两个。Open WebUI：同样自托管，知识库加聊天开箱即用、社区插件生态更成熟，但它没有掌握度跟踪、没有错题沉淀、没有复习计划，学习闭环为零——它是「更好的聊天框」，DeepTutor 是「学习过程管理」，维度不同。NotebookLM：谷歌托管，资料理解质量好、省心到极致，代价是数据在别人云上、能力锁死在谷歌生态里、完全不可扩展——在乎数据主权或者想接自己模型的，它直接出局。
最后说句实在的，这项目去年 12 月底才正式发布，不到一年干到 58,003 个 star、90 个版本，最近四周就合了 1,010 次提交，11 月 6 日刚发 v1.7.2，这个节奏放在开源圈也是少见的凶猛。一句话总结我的态度：检索准不准从来不是瓶颈，学习这件事缺的从来是「练」和「记」的那一环——DeepTutor 把这两环正经当功能做了，光凭这个，它就值得我下次腾出一个下午，装上真跑一遍。
