DeepTutor（HKUDS/DeepTutor）：单循环智能体、三层记忆与九种 RAG，把「AI 家教」做成可审计的学习操作系统

开源项目 2026-10-28 阅读 8 次 · 访客 8 位

一、导读

10 月 28 日的 GitHub 日榜上，香港大学数据智能实验室（HKUDS）的 DeepTutor 单日涨星 1587，是榜内排名最高的「大模型应用」类项目——它把家教、解题、出题、研究、可视化、精读、闯关这十种学习模式压进同一条 agent 循环，再把记忆、知识库、IM 渠道全部做成可审计的明文文件。本文拆它的架构取舍、可复现的学习场景，以及它和 Khanmigo、ChatGPT 学习模式的真实差距。

二、项目速览

项目	信息
仓库	HKUDS/DeepTutor
定位	Agent-native 的终身个性化学习工作台（AI 家教操作系统）
当日涨星	1587（GitHub Trending daily，2026-10-28）
总星数	约 45,400；fork 5,700+（GitHub API，截至 2026-10-28）
License	Apache-2.0
技术栈	Python 3.11–3.14（FastAPI 后端）+ Next.js 16 前端 + Node 20+
出品方	HKUDS（Data Intelligence Lab @ HKU），LightRAG、RAG-Anything、CLI-Anything 同门
论文	arXiv:2604.26962《DeepTutor: Towards Agentic Personalized Tutoring》
版本节奏	87 个 release，最新 v1.6.15（2026-10-19），2025-12-29 正式发布

增长曲线值得一看：2026-02-06 宣布 39 天破 1 万星，04-19 用 111 天破 2 万，09-20 宣布 9 个月破 4 万。从 v0.2 到 v1.6.15 的 87 个版本几乎每周一更，其中 2026-04-04 的 v1.0.0-beta.1 是一次约 20 万行代码的 agent-native 架构重写——这个体量在「套壳 GPT 的教育应用」里极少见。

三、为什么是它

教育是 LLM 应用最拥挤的赛道之一，但市场上成型的「AI 家教」几乎全是闭源产品：可汗学院的 Khanmigo 绑定自家课程与订阅，OpenAI 的 Study Mode 长在 ChatGPT 端内。DeepTutor 补上的位置很清楚——把「个性化辅导」所需的全部基础设施（记忆、知识库、人格、渠道、安全围栏）开源出来，模型随便换，数据落自己盘上。它的涨星有三个可核实的动因。

第一，工程厚度撑得起「操作系统」的说法。仓库根目录下 SKILL.md、AGENTS.md、docs-for-user/AGENT_SETUP.md 一应俱全，安装引导本身就写着「把这段提示词丢给你的 Claude Code 或 Codex，让它替你装」；CLI 每条命令支持 --format json 输出 NDJSON 事件流，别的 agent 可以直接驱动它。这种「让 agent 操作软件」的设计正踩中 2026 年的交互范式转移。

第二，同门生态互相导流。HKUDS 旗下 LightRAG（4 万星）、CLI-Anything（5.7 万星）、nanobot（4.9 万星）各自有庞大用户群，而 DeepTutor 把 LightRAG 做成内置 RAG 引擎、把 CLI-Anything 目录做成 Learning Space 的 CLI 应用来源，README 提供 12 种语言版本，中文社区（微信群、飞书群）齐备。

第三，触发点明确。10 月 19 日 v1.6.15 发布（学习路径修订、分组测验、有界辅导记忆、原生 Gemini 语音），随后登上 GitHub Trending 与 Trendshift 日榜（仓库主页两枚徽章可查），叠加此前 HKUDS 项目矩阵积累的关注度，形成这一波单日 1587 星。

四、架构原理

4.1 整体架构：一个运行时，四种入口

DeepTutor 学习操作系统手绘架构图：接入层四种入口汇聚到 ChatOrchestrator，核心运行时的 AgentLoop 单循环与能力插件，知识与记忆层的三层记忆和九种 RAG 引擎，以及外部能力层的任意 LLM 提供方、子智能体、三级沙箱与 EduHub 技能市场

DeepTutor 的物理形态是一个 FastAPI 后端（默认 8001 端口）加一个 Next.js 前端（3782 端口），浏览器只跟前端通信，/api/* 与 /ws/* 由 Next.js 中间件在容器内转发给后端。关键在于：Web、CLI、十五路 IM 渠道、外部 agent 四种入口，最终都汇成同一种东西——一次 ChatOrchestrator 回合。

flowchart TB
    subgraph entry["接入层：四种入口"]
        WEB["Next.js Web :3782"]
        CLI["deeptutor CLI（NDJSON）"]
        IM["Partners：15 路 IM 渠道"]
        AG["外部 agent（SKILL.md 交接）"]
    end
    subgraph core["FastAPI 后端 :8001"]
        ORCH["ChatOrchestrator"]
        LOOP["AgentLoop 单循环"]
        CAPS["能力插件：Chat / Quiz / Research / Solve / Mastery / Reading / Book 等 10 种"]
        TOOLS["工具挂载：rag / exec / ask_user / consult_subagent / workspace 等 20+"]
    end
    subgraph know["知识与记忆层"]
        KB["知识中心：9 种 RAG 引擎"]
        MEM["三层记忆 L1 / L2 / L3"]
        WS["内容工作区：outputs 只读边界"]
    end
    subgraph ext["外部能力"]
        LLM["任意 LLM 提供方"]
        SUB["子智能体：Claude Code / Codex / Grok CLI"]
        SBX["执行沙箱三级"]
        HUB["EduHub 技能市场"]
    end
    WEB --> ORCH
    CLI --> ORCH
    IM --> ORCH
    AG --> ORCH
    ORCH --> LOOP
    LOOP --> CAPS
    LOOP --> TOOLS
    TOOLS --> KB
    TOOLS --> MEM
    TOOLS --> WS
    LOOP --> LLM
    TOOLS --> SUB
    TOOLS --> SBX
    HUB --> CAPS

这个「万物皆回合」的设计是 v1.4.3（2026-06-12）定型的：TutorBot 改名 Partners、聊天迁到单一 agent 循环之后，一条 IM 消息不再走单独的机器人引擎，而是变成 partner 工作区里的一个普通回合。好处是能力、工具、记忆对四种入口完全同权——你在飞书里问家教的它，和你在网页里问，背后是同一个大脑、同一份记忆。

4.2 单循环 agent：注释即解说、无工具即终点

核心文件 deeptutor/agents/loop/agent_loop.py（约 9.3 万字符）的模块 docstring 把设计说得非常直白：一次回合 = 一条不断增长的对话上的一圈循环，每一轮就是一次 LLM 调用。

# deeptutor/agents/loop/agent_loop.py（节选自模块 docstring）
# * 每一轮是一次 LLM 调用：文本流式给用户，工具调用带 role=tool 结果追加回对话；
# * 调用了工具的轮次，其文本是「解说」（commentary）——说明接下来做什么、为什么；
# * 一轮不调用任何工具，即是 finish：该轮文本收尾答案，循环结束；
#   首轮就无工具调用 = 「无需探索」快速通道；
# * 探索预算耗尽仍有协议内工作时，进入小型有界结算阶段（settlement），
#   之后才强制最后一轮无工具硬收尾。

MAX_SETTLEMENT_ROUNDS = 3        # 结算轮上限
MAX_REASONING_ONLY_RECOVERIES = 2  # 「只推理不行动」的模型重试上限

三个细节见功力。其一，答案与过程不分离：每一轮的文本按书写顺序留存在答案里，工具调用以内联形式渲染在解说下面，读起来像看一个终端 agent 干活——这解决了「agent 中间过程黑箱」的体验问题。其二，ask_user 是特权工具：模型不确定时可以暂停回合、抛出结构化澄清问题、等用户答完在协议内续跑，而不是硬猜。其三，针对「只出推理不出动作」的失败模式（模型反复改计划不执行），第二次数育后直接强制无工具收尾，避免烧光探索预算。

配套的 context_budget.py 做逐轮上下文审计：它测量的不是抽象估计，而是「实际发给 provider 的请求」——组装好的 PromptBlock 列表、真正进 call kwargs 的工具 schema、最终 message 列表（深拷贝快照，防止循环后续追加污染读数）。系统提示、人格、记忆、技能、来源、工作区各占哪段预算一目了然，且整个读数路径「绝不 raise」——信息展示模块不能弄沉一个回合。

回合内上下文分两种：粘性会话上下文（能力、工作区或课程、工具、知识库、人格、模型以及 Reading 与 Mastery 状态）跨回合留存，让多轮教学不断线；一次性引用（文件、历史会话、书、阅读选段、笔记、题库条目、导入的 agent）从加号菜单进当前回合就销毁。分层的意义在于成本与噪音控制：长期状态稳定付费一次，临时材料不污染后续轮次。

4.3 兼容性工程：DSML 回退解析

多模型支持的真功夫在脏活上。部分 DeepSeek 本地部署的 OpenAI 兼容端点不声明原生 function calling，会把工具调用当文本吐在 content 通道里（issue #666），不处理的话标记直接漏给用户、工具永远不执行。dsml_tool_calls.py 的解法是一个流式过滤器：

<｜｜DSML｜｜tool_calls>
  <｜｜DSML｜｜invoke name="exec">
    <｜｜DSML｜｜parameter name="code" string="true">print("...")</｜｜DSML｜｜parameter>
  </｜｜DSML｜｜invoke>
</｜｜DSML｜｜tool_calls>

DSMLStreamFilter 增量喂入流式 chunk，完整工具调用块被剥离并还原成结构化调用进正常分发路径，调用块之外的文本立即放行——一个工具调用不能劫持整轮的输出通道；未闭合的片段在 flush 时原样释放而非静默吞掉。这类「为真实世界的残缺端点兜底」的代码，是它敢宣称「任意 OpenAI 兼容 / Anthropic / Ollama / vLLM 都能接」的底气。

4.4 三层记忆：个性化不藏在向量里

个性化辅导最难的不是答题而是「记得学生」。DeepTutor 的记忆系统刻意不用黑箱向量库，全部是明文文件：

L1 原始事件：append-only JSONL，按「表面 × UTC 日期」一天一个文件（trace 目录按表面分子目录、按日期分文件），覆盖 chat、notebook、quiz、kb、book、partner、cowriter 七个表面；写入路径永不抛错、逐表面 asyncio 锁串行化，绝不拖垮产生事件的主流程。
L2 表面事实：每个表面一份人工可读可编辑的 Markdown 事实文档，每条事实引用 L1 里的实体。
L3 跨表面综合：画像、近况、范围、偏好四类综合文档，每一份都记录自己由哪些 L2 表面汇总而来，证据链不断。

Memory Graph 把三层金字塔画出来：L3 在中心、L2 在中环、L1 在外圈，连边就是证据链——「我觉得你三次都不会特征值」这句话可以一路下钻到三条原始对话记录。整合器（consolidator）的 Update / Audit / Dedup 预算在设置页可调。对教育场景这是致命优点：家长可以审计「AI 到底记了我孩子什么」，错了能改，合规上说得清。

4.5 九种 RAG 引擎与可评测的检索

知识中心支持每个知识库绑定一种检索引擎：LlamaIndex（默认，向量 + BM25 混合、可选交叉编码器重排、FAISS 平面或 HNSW）、PageIndex（推理式检索、页级引用）、GraphRAG 与 LightRAG（知识图谱路线）、外部 LightRAG Server、自托管 WeKnora、腾讯 IMA、MarginNote 4（含思维导图卡与链接）、Kiwix ZIM 离线档案库、原地读写的 Obsidian 库。索引重建写新的 version-N 目录、旧版本保留，重建中途永远不会毁掉可用索引。

文档解析引擎同样可插拔：Text-only、MinerU、Docling（支持远程 Docling Serve 模式，本地不装模型）、Apache Tika、markitdown、PyMuPDF4LLM、LiteParse 七选一，另配可选的图片描述模型处理扫描图。知识库还能直接跟踪 GitHub 仓库与文档站：填 repo、分支与 glob，或给爬取深度与页数上限，默认每 24 小时重同步一次，哈希差分只处理增改删的内容——跟进一份活跃文档不用反复手动上传。

更难得的是把「哪个引擎检索得好」做成了可测量问题：写一份 JSONL 问答集（query + gold 段落），deeptutor kb eval 走与聊天回合完全相同的检索路径打分，输出 Recall@k、Precision@k、nDCG@k、MRR、MAP、Hit@k 六个指标——纯函数度量，没有模型裁判；eval-diff 还能对两份报告做逐指标对比。

4.6 安全边界：工作区、沙箱与技能门

三道围栏值得点名。内容工作区里执行只读于 outputs/ 之外，把生成文件拷去别处需要逐对「Allow once」确认，系统沙箱或 Docker runner 在可用时强制该边界；模型只见相对路径，workspace_present 渲染的是认证快照，改源文件不偷换已展示内容。跑模型生成代码（docx/xlsx 等 office 技能）走三级沙箱：加固的 runner sidecar 优先、Linux bubblewrap 次之、受限子进程兜底且可一键关闭。EduHub 技能导入过统一安全门：先查注册方安全裁定，解包防路径穿越与符号链接，剥可执行位，frontmatter 里的 always: 强制剥离——下载的技能永远无法把自己塞进每条系统提示。

五、应用场景

5.1 考试复习：把讲义变成可度量的题库与闯关路径

痛点是经典的「讲义一百页、重点自己猜」：收藏夹里资料越堆越多，复习却始终停留在重读与划线。DeepTutor 的路径是先把材料建成知识库，再让出题与闯关吃同一个检索底座。

# 建库并灌入讲义
deeptutor kb create kaoyan-math --doc 高数讲义.pdf
# 按「极限与连续」出 5 道题，检索走同一个知识库
deeptutor run deep_question "极限与连续" --kb kaoyan-math --config num_questions=5

收益可以用两个内置机制量化：Mastery Path（掌握路径）带按题型硬性掌握门（mastery gate，v1.4.5 引入），不过线不放行下一阶段；错题进 Practice 的间隔复习队列。建议先跑 deeptutor kb eval 给知识库建检索基线——若 Recall@5 低于预期，换引擎或调解析器比反复调提示词有效。边界也要说清：讲义扫描件解析质量决定上限，公式密集的 PDF 建议开 MinerU 解析；纯背诵型科目（单词、法条）出题价值低于理解型科目。

5.2 论文精读与调研：一次会话从综述到自测

科研新人最常见的断点是「读完就忘、读完不知对错」。DeepTutor 的 deep_research 与 deep_question 共享会话状态，可以串成一条流水线：

# 第一步：出一份带引用的领域综述
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

--format json 输出 NDJSON 事件流（content / tool_call / tool_result / done），所以这两条命令可以直接嵌进你自己的脚本或 agent 循环。综述里的每个论断带引用，Co-Writer 的「手术式编辑」让你选中一段要求改写时，改的只是选区且可撤销。边界：深度调研的时效性受检索源限制，web_search_source_filtering 可把引用域锁进 arxiv.org、edu.cn 一类可信域，避免引用污染。

5.3 视频课程学习：时间戳级的沉浸精读

B 站和 YouTube 的长课是很多人的主要学习介质，痛点是「进度条拖不动、笔记对不上时间」。把视频链接粘进 Reading：字幕全文可检索、提问带时间戳锚点（答了什么直接跳到那一分钟）、笔记与进度可续。B 站走自家播放与字幕通道，YouTube 可配管理员级 Invidious 实例。这一场景不需要任何命令行，网页内闭环；适合跟课刷完系统课程的人，不适合只看短视频碎片的人——没有字幕的视频，辅导证据会受限（播放不受影响）。

5.4 给孩子搭一个可审计的 IM 陪学伙伴

家长的真实焦虑是两头：孩子用通用聊天机器人得不到辅导法，且聊了什么完全不可见。Partners 的玩法是给每个伙伴一份 SOUL.md 人格文件、独立的模型策略与知识库，接上飞书、QQ/NapCat、微信企业版等十五路 IM 渠道，消息进来就是普通回合——「一个有人格和电话号码的聊天」。多用户部署里的 Learner 角色锁定学习功能与材料策略，授权监护人可看报告、审材料、重置凭据；记忆是明文三层文件，L1 到 L3 随时可查。命令三步：

deeptutor partner create   # 起名、选模型、绑知识库
deeptutor partner start    # 拉起常驻 IM 通道
deeptutor memory show      # 随时审计它记了孩子什么

渠道层是 schema 驱动的，飞书或企业微信应用可以从渠道页扫码或一键建应用，扫码动作画在浏览器里而非打在服务器日志上，首个扫码人自动成为初始白名单发送者。边界同样明确：它替代不了真实教师与同伴反馈，Learner 模式与家长控制是缓解而非保险；接个人微信属扫码登录的灰色通道，协议变更即失效（README 自己也保留了手动表单兜底）。

六、快速上手

零依赖试用一条命令：

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，在 Settings → Providers 里配模型即可。持久化安装走 PyPI：

pip install -U deeptutor
deeptutor init     # 向导：端口 + LLM 提供方 + 可选 embedding/搜索
deeptutor start    # 拉起前后端

只要 CLI 不要 Web UI 时，从源码装 packaging/deeptutor-cli 子包即可。检测安装是否就绪用 deeptutor doctor --online（会发一次真实小请求验证提供方）。可选扩展按需装：rag-lightrag（内置 LightRAG）、graphrag、partners（IM 渠道 SDK）、math-animator（Manim 动画，需 LaTeX 与 ffmpeg）。

七、横向对比

维度	DeepTutor	Khanmigo（可汗学院）	ChatGPT 学习模式	自拼 LangChain 教育应用
开源与部署	Apache-2.0，本地 / Docker / 多用户自托管	闭源商业，绑平台订阅	闭源，长在 ChatGPT 端内	代码自持但全套自建
个性化记忆	三层明文记忆 + 记忆图谱，可审计可编辑	平台侧画像，不可见	会话内记忆为主	需自研
知识库	九种 RAG 引擎按库选型，可评测	官方课程内容	文件上传能力有限	自己接向量库
接入面	Web / CLI / 十五路 IM / 被 agent 驱动	App 与网站	ChatGPT 端内	自建前端
模型自由度	任意 OpenAI 兼容 / Anthropic / 本地 Ollama	指定模型	GPT 系	自由
教学法	掌握门 + 苏格拉底技能市场（EduHub）	专家设计的提示工程	提示层约束	全靠自己实现

三句话总结这张表：要「开箱即用、内容权威」，Khanmigo 和 ChatGPT 学习模式仍然更省心；要「数据自主、模型自选、渠道自定、个性化可审计」，DeepTutor 是目前开源侧完成度最高的一个；自拼框架则只在你有专职工程团队时才划算。

八、局限与风险

评测数字是自报口径。 论文提出 TutorBench 基准与「第一人称交互式评估协议」，报告个性化指标平均提升 10.8%、五个骨干模型上通用 agent 推理提升 29.4%——截至本文发布未见独立第三方复现，采信时请打折（待确认项：第三方复现结果）。

维护集中于极少数人。 贡献榜第一名 pancacake 独有 1554 次提交，第二名 116 次，断档近 13 倍；87 个 release 的高频迭代依赖这条单人主干，巴士因子低，功能面铺得极大（v1.6.15 一个版本就横跨学习路径、测验、记忆、解析、语音五条线），issue 积压 225 个，文档滞后官方也自认（README 注明多数截图仍是 v1.4.6 参考版）。

同名项目需甄别。 搜「DeepTutor」会撞上 knowhiz.us 的同名 Zotero 文献工具（deeptutor.knowhiz.us），两家无关联，认准 HKUDS 组织。

教育本质的边界。 AI 家教缓解的是「没人随时答疑」，替代不了教师的动机管理与同伴学习；接个人微信等通道存在协议风控风险；体验下限由你配的模型决定，小参数本地模型在多工具调度上掉队明显。

九、小结与行动建议

DeepTutor 把「AI 家教」从聊天机器人升级成了一套有架构纪律的学习操作系统：单循环 agent 保证过程透明，三层明文记忆保证个性化可审计，九种可评测的 RAG 引擎保证知识底座可替换，四种入口保证它长在你已有的习惯里。给不同读者的建议：

家长与自学者：直接 Docker 起一份，先玩 Reading 与 Mastery Path，再决定是否接 IM 渠道；给孩子用务必开 Learner 角色并定期 deeptutor memory show。
研究者：把 deeptutor kb eval 纳入你的 RAG 选型流程，六指标基线比手感靠谱；TutorBench 协议值得作为教育 agent 评测的参照系复现一遍。
工程团队：它的 agent_loop（探索预算 + 有界结算 + 硬收尾）、DSML 流式回退、上下文逐轮审计三个模块是可以直接抄走的工程模式，与教育场景无关也适用。
观望者：盯住 release 而非 star 数——单人主干项目，维护节奏一旦放缓，迁移成本会随记忆与知识库数据量上升，尽早规划导出（记忆与工作区都是明文文件，导出成本本身很低）。

参考资料

HKUDS/DeepTutor 仓库与 README（获取日期：2026-10-28）
GitHub Trending daily 榜单（获取日期：2026-10-28）
论文：Zhao, Zhang, Ren, Guo, Chu, Ma, Huang.《DeepTutor: Towards Agentic Personalized Tutoring》. arXiv:2604.26962（获取日期：2026-10-28）
HKUDS 组织主页（Data Intelligence Lab @ HKU）（获取日期：2026-10-28）
官方文档站 deeptutor.info（获取日期：2026-10-28）
EduHub 技能市场（获取日期：2026-10-28）
源码文件：agent_loop.py、dsml_tool_calls.py、context_budget.py、services/memory/trace.py（raw.githubusercontent.com，获取日期：2026-10-28）

读者留言

COMMENTS 暂无

还没有留言，来说第一句？