一天一个开源项目

开源项目第189期：DeepTutor — Agent 原生的终身个性化学习工作台，三层记忆+多引擎RAG+Partners，33k Stars

香港大学数据智能实验室出品的 AI 学习工作台。核心：单一 agent 循环驱动所有模式（Chat/Quiz/Research/Visualize/Solve/Mastery Path）。三层记忆（L1事件追踪/L2曲面摘要/L3跨曲面综合），可视化记忆图谱，每条合成结论可追溯到原始事件。多引擎知识库：LlamaIndex/PageIndex/GraphRAG/LightRAG/Obsidian。Partners：持久 AI 伴侣，带 IM 通道（Slack/Discord/Telegram/微信/飞书等）。My Agents：驱动本地 Claude Code/Codex 作为子 agent。Python+Next.js，Apache-2.0，33k Stars。

·约 12 分钟阅读·AI Tools
open-sourceAI-agentRAGpersonalized-learningmemorymulti-agentknowledge-baseeducationPythonNext.js

引言

"One runtime for every mode — switch the objective, not the engine."

这是「每日一个开源项目」系列的第 189 篇。今天的项目是 DeepTutor —— 香港大学数据智能实验室（HKUDS）出品的 Agent 原生学习工作台，33,468 颗 Star，Apache-2.0 许可，Python 3.11+ + Next.js 16。

DeepTutor 的核心主张：Chat、Quiz、Research、Visualize、Solve、Mastery Path 这些不同的学习模式，跑在同一个 agent 循环上，切换目标而不切换引擎，上下文始终跟着学习者。记忆系统是三层可审计架构，每条合成结论都可以追溯到原始事件；知识库支持六种检索引擎；Partners 有自己的 soul、模型策略、频道，可以对接 15 个 IM 平台。

你会学到什么

  • DeepTutor 的核心架构：单一 agent 循环和各主要功能模块
  • 三层记忆系统（L1/L2/L3）的设计和可审计性
  • 多引擎知识库：LlamaIndex、GraphRAG、LightRAG、Obsidian 等
  • Partners：AI 伴侣、IM 通道、子 agent 模式
  • My Agents：驱动本地 Claude Code/Codex 作为子 agent
  • 四种安装方式：PyPI、源码、Docker、CLI-only

前提知识

  • 基本的终端使用经验
  • 了解 RAG（检索增强生成）的基本概念对理解知识库部分有帮助
  • Python 基础（如需修改源码）

项目背景

概述

DeepTutor 是一个 Agent 原生的学习工作台，不是简单的 ChatGPT wrapper。它的架构特征是：所有功能模式（Chat、Quiz、Research、Visualize、Solve、Mastery Path）都运行在同一个 ChatOrchestrator agent 循环上，工具按需挂载，而不是每个模式一套独立代码。

来自香港大学数据智能实验室（HKUDS），对应学术论文 arXiv:2604.26962。

项目信息

  • 来源: 香港大学数据智能实验室（HKUDS）
  • 主要语言: Python 3.11+ (后端) + Next.js 16 / React 19 (前端)
  • 许可证: Apache-2.0
  • 官网: deeptutor.info
  • 论文: arXiv:2604.26962

项目数据

  • ⭐ GitHub Stars: 33,468+
  • 🍴 Forks: 4,321+
  • 📄 许可证: Apache-2.0
  • 📅 创建时间: 2025-12-28（39 天破万星）

快速安装

四种安装路径，推荐从 PyPI 安装：

# Option 1：PyPI 安装（无需 clone，推荐）
mkdir my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init     # 配置端口、LLM 提供商、可选 embedding
deeptutor start    # 启动 backend + frontend
# 打开 http://127.0.0.1:3782
# Option 2：源码安装（开发用）
git clone https://github.com/HKUDS/DeepTutor.git && cd DeepTutor
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
cd web && npm ci --legacy-peer-deps && cd ..
deeptutor init && deeptutor start --dev
# Option 3：Docker（单容器）
docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest
# 只需暴露 3782，内部代理转发 /api/* 和 /ws/*
# Option 4：CLI-only（无 Web UI）
pip install -e ./packaging/deeptutor-cli
deeptutor init --cli
deeptutor chat

deeptutor init 会提示配置：后端端口（默认 8001）、前端端口（默认 3782）、LLM 提供商/Base URL/API Key/模型名，以及可选的 embedding 提供商。

核心架构：单一 Agent 循环

DeepTutor 的关键设计是：所有学习模式跑在同一个 agent 循环上。

用户输入 → ChatOrchestrator →（按模式挂载工具）→ 模型推理 → 工具调用 → ... → 最终回复

不同模式的区别在于挂载的工具不同，而不是换一套引擎：

模式核心工具功能
Chatrag, web_search, reason, ask_user正常对话，支持 RAG、搜索、推理
Quizdeep_question agent基于材料生成测验题
Researchdeep_research agent生成带引用的调研报告
Visualizevisualize, math_animator生成图表/动画/交互组件
Solvedeep_solve agent分步骤推理求解
Mastery Pathmastery_path agent学习路径规划 + 掌握度闸控

切换模式不切换上下文：同一个会话里，从 Chat 切到 Quiz 再切到 Research，历史记忆和知识库都随之。

工具挂载规则：

  • 粘性会话上下文（子 agent、知识库、角色、模型）：在编辑器工具栏设置，跨轮次保持
  • 一次性引用（文件、聊天历史、书、笔记本）：通过 + 菜单添加，仅当轮有效

ask_user 工具是特殊设计：agent 不确定时可以暂停当前轮，向用户提一个结构化问题，拿到答案后继续。而不是猜测或沉默。

三层记忆系统

这是 DeepTutor 最有工程价值的设计之一：记忆是文件存储、三层可审计的，不是隐藏的向量库。

data/memory/
├── trace/          ← L1：追加式事件追踪 JSONL（每个曲面/每天）
├── L2/             ← L2：每个曲面的策划事实（Markdown）
└── L3/             ← L3：跨曲面综合（profile/recent/scope/preferences）
  • L1（事件追踪）：trace/<surface>/<date>.jsonl，追加式，覆盖 chat/notebook/quiz/kb/book/cowriter 等曲面
  • L2（曲面摘要）：L2/<surface>.md，策划过的事实，L2 的每条记录引用 L1 的原始事件
  • L3（跨曲面综合）：L3/{profile,recent,scope,preferences}.md，跨曲面整合的用户画像，L3 的每条结论引用 L2

记忆图谱：可视化整个金字塔，L3 综合在中心，L2 在中间环，L1 事件在外圈。追踪任何合成结论，都能找到背后的具体原始事件。没有黑盒。

deeptutor memory show    # 查看 L2/L3 记忆文档
deeptutor memory clear   # 清除 L1 或全部记忆

CLI 中也可管理，Settings → Memory 可调整整合器的 Update/Audit/Dedup 预算。

多引擎知识库

DeepTutor 的知识库支持六种检索引擎，每个知识库绑定到一个引擎：

引擎特点
LlamaIndex（默认）本地向量 + BM25 混合检索
PageIndex托管检索，页面级引用，推理式检索
GraphRAG知识图谱检索（微软 GraphRAG）
LightRAG轻量知识图谱检索
LightRAG Server接入外部 LightRAG 实例（HTTP）
Obsidian直接读写 Obsidian Vault，本地修改立即生效

文档解析引擎（在 Settings → Knowledge Base 设置）：Text-only、MinerU、Docling、markitdown、PyMuPDF4LLM。

版本控制：重建索引写入新的 version-N 目录，保留旧版本，工作索引不会在重建中途被销毁。可以单独删除一个出错的文件，不需要重建整个知识库。

deeptutor kb create my-kb --doc textbook.pdf
deeptutor kb add my-kb --doc chapter2.pdf
deeptutor kb search my-kb "梯度下降的原理"
deeptutor kb list

知识库可以在 Chat、Partners、Co-Writer、Book 中跨场景复用。

Partners：持久 AI 伴侣

Partners 是带有独立 soul、模型策略、知识库、记忆和 IM 频道的持久伴侣。

从架构上，Partner 不是独立的 bot 引擎：每条 IM 消息都变成一个普通的 ChatOrchestrator 轮次，在以 Partner 为作用域的工作区里运行。Partner 是「有个性和电话号码的 chat」。

每个 Partner 有：

  • SOUL.md：persona/行为定义
  • 独立的模型选择
  • 独立的知识库、技能、笔记本
  • 独立的记忆（读取 owner 的记忆，写入自己的记忆）
  • 频道：连接 IM 平台

支持的 IM 平台（取决于安装的 extras）：Feishu（飞书）、Telegram、Slack、Discord、DingTalk（钉钉）、QQ/NapCat、WeCom（企业微信）、WhatsApp、Zulip、Mattermost、Matrix、Mochat、Microsoft Teams。

Partner 也可以被当作子 agent，从 Chat 的任意轮次中调用（通过 consult_subagent 工具）。

My Agents：驱动本地 Coding Agent

My Agents 让 DeepTutor 可以调用本地的 coding agent：

连接实时 agent：把本机运行的 Claude Code、Codex、Gemini、Kimi、opencode 或 MiMo Code CLI 连接进来，在 Chat 轮次中直接驱动它。DeepTutor 实际运行对应的 CLI，通过 consult_subagent 工具把工作流程流式显示在 Activity 面板。用 @ 选择 agent，设置最多运行几轮。

导入历史对话：把已有的 Claude Code 和 Codex 历史对话导入为命名、可搜索、可恢复的 agent。选择导入哪几天的记录；刷新时同步最新内容。在任意 Chat 轮次中通过 + 引用，DeepTutor 把它作为第三方脚本读取，保持原始对话的独立性。

Co-Writer：选区感知 Markdown 写作

Co-Writer 是双栏 Markdown 写作工作区，用于报告、教程、笔记等长文写作。文档自动保存并实时预览（KaTeX 数学公式、图表）。

核心特性是精准编辑：选中一段文字，让 DeepTutor 重写、扩展或压缩。编辑 agent 可以用知识库或网络证据作为依据，保留完整工具调用追踪，并以接受/拒绝 diff 的形式展示每一处修改，确认后才生效。

Book：从材料生成「活书」

Book 把选定的来源（知识库、笔记本、问题库、聊天历史）编译成一本活书，而不是静态 PDF。

生成流程：先提议章节大纲，用户确认后再生成内容，避免盲目一次性输出。

每章编译成类型化的内容块：文本、标注、测验、闪卡、时间线、代码、图形、交互式 HTML、动画、概念图、深入分析、用户笔记。每页有独立的「页面聊天」。块可以单独编辑、插入、移动、重新生成或切换类型，不需要重写整章。

CLI 和 Agent 化接口

DeepTutor 被设计为可被其他 agent 驱动：

# 交互式 REPL
deeptutor chat
 
# 单次运行，普通输出
deeptutor run deep_research "2026年 RAG 进展综述" --config mode=report
 
# 机器可读（NDJSON 流式输出）
deeptutor run deep_solve "求 d/dx[sin(x^2)]" --tool reason --format json
 
# 跨轮次状态保持
SID=$(deeptutor run deep_research "RAG综述" --format json | jq -r 'select(.type=="done").session_id')
deeptutor run deep_question "考我" --session "$SID" --format json

--format json 时，每轮输出 NDJSON 流：content、tool_call、tool_result、done，每行标记 session_id。无 TTY 时，ask_user 暂停自动以空回复解决而不阻塞，适合 CI/CD 场景。

根目录的 SKILL.md 是约 150 行的 agent 交接文档，Claude Code/Codex/OpenCode 读取后可以完整理解 DeepTutor 的 CLI 接口，实现 LangChain/AutoGen 等框架的封装。

完整 CLI 命令参考

命令功能
deeptutor init初始化工作区配置
deeptutor start [--dev]启动 backend + frontend（--dev 启用 HMR）
deeptutor chat交互式 REPL
deeptutor run <capability> <message>单次运行（chat/deep_solve/deep_question/deep_research/visualize/mastery_path）
deeptutor kb list/create/add/search管理知识库
deeptutor partner list/create/start/stop管理 Partners
deeptutor skill install/list/publish安装/管理技能，从 EduHub 社区导入
deeptutor memory show/clear查看/清除 L2/L3 记忆
deeptutor session list/show/rename管理会话
deeptutor book health检查书的源数据与编译页面是否漂移
deeptutor config show查看配置摘要

参考资源

官方链接

总结

DeepTutor 的几个值得记录的工程决策：

单一 agent 循环驱动所有模式：Chat/Quiz/Research/Visualize 不是独立代码路径，而是同一个循环挂载不同工具。这意味着上下文不会因为切换模式而丢失，工具的组合也可以自由叠加（一个轮次里同时用 RAG 检索和网络搜索）。

三层可审计记忆：L1→L2→L3 的引用链保证每条合成结论可以追溯到原始事件。这解决了个性化 AI 工具的一个根本问题：用户不知道系统「记住了什么」，也不知道这些记忆从哪里来。可视化记忆图谱让这一过程透明化。

Partners 的设计：Partner 不是独立 bot，而是有 soul 和 IM 频道的 chat 作用域。这个抽象让同一套 RAG、记忆、工具调用机制可以复用到任何 IM 平台的伴侣场景，而不需要维护多套代码。

CLI 的 agent 化设计：--format json 输出 NDJSON、无 TTY 时自动解决 ask_user 暂停、根目录 SKILL.md 作为 agent 交接文档，这些细节说明项目从一开始就考虑了被其他 agent 驱动的场景，而不是事后拼接的功能。

如果你需要一个可以自托管、记忆可审计、支持多种 RAG 引擎、能对接 IM 平台的 AI 学习工作台，DeepTutor 是目前开源社区里功能最完整的选项之一。

探索 PrimeSkills —— 精选 AI agent 和技能工具，每一个都经过真实工作流验证。没有炒作，只有真正好用的工具。

访问我的个人主页，获取更多见解和有趣的产品。

← 返回博客列表