DeepTutor：港大数据科学实验室3层记忆Agent-native学习工作区

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

这是"每日一个开源项目"系列第 153 篇。今天要介绍的项目是 DeepTutor——来自 HKUDS（港大数据智能实验室）的 Agent 原生学习工作区，33,468 Stars，Apache-2.0 许可证，基于 Python 3.11+ 和 Next.js 16 构建。

DeepTutor 的核心主张：Chat、Quiz、Research、Visualize、Solve 和 Mastery Path 全部运行在同一个 Agent 循环上——切换的是目标，而非引擎，上下文随学习者一起迁移。记忆系统是三层可审计架构，每一条合成的陈述都能追溯到原始事件；知识库支持六种检索引擎；Partners 各自有灵魂、模型策略和连接 15 个 IM 平台的渠道。

DeepTutor 的核心架构：单一 Agent 循环与主要功能模块

三层记忆（L1/L2/L3）设计与可审计性

多引擎知识库：LlamaIndex、GraphRAG、LightRAG、Obsidian 等

Partners：AI 伴侣、IM 渠道、subagent 模式

My Agents：驱动本地 Claude Code/Codex 作为 subagent

四种安装方式：PyPI、源码、Docker、纯 CLI

基本终端体验

对 RAG（检索增强生成）有基本了解有助于理解知识库部分

Python 基础知识（如果你想修改源码）

DeepTutor 是一个 Agent 原生学习工作区，不是简单的 ChatGPT 包装器。它的架构特征是：所有功能模式（Chat、Quiz、Research、Visualize、Solve、Mastery Path）都运行在同一个 ChatOrchestrator Agent 循环上，工具按需挂载，而非每个模式各自独立实现。

来自港大数据智能实验室，配套论文发表于 arXiv:2604.26962。

组织：HKUDS — 港大数据智能实验室

主要语言：Python 3.11+（后端）+ Next.js 16 / React 19（前端）

网站：deeptutor.info

论文：arXiv:2604.26962

⭐ GitHub Stars：33,468+

📄 许可证：Apache-2.0

📅 创建时间：2025-12-28（39 天内达到 10k Stars）

四种安装路径——推荐使用 PyPI：

# Option 1: PyPI install (no clone required, recommended)
mkdir my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init     # configure ports, LLM provider, optional embedding
deeptutor start    # start backend + frontend
# Open http://127.0.0.1:3782

# Option 2: Source install (for development)
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 (single container)
docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest
# Only port 3782 needs publishing; internal proxy forwards /api/* and /ws/*

# Option 4: CLI-only (no 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 循环上。

User input → ChatOrchestrator → (mode-specific tools mounted) → LLM reasoning → tool calls → ... → final reply

不同模式之间的区别在于挂载了哪些工具，而非使用不同的引擎：

切换模式不会丢失上下文：在一个会话中，从 Chat 到 Quiz 再到 Research，历史记录和知识库始终跟随你。

粘性会话上下文（subagent、知识库、persona、模型）：在组合工具栏上设置，跨轮次持久化

一次性引用（文件、聊天历史、书籍、笔记本）：通过 + 菜单添加，仅在当前单轮有效

ask_user 工具是一个深思熟虑的设计：当 Agent 不确定时，它可以暂停当前轮次，提出结构化的澄清问题，待你回答后恢复——而非猜测或保持沉默。

三层记忆系统

DeepTutor 最有价值的工程设计之一：记忆是文件-backed 的、三层架构、完全可审计——不是隐藏的向量存储。

data/memory/
├── trace/          ← L1: append-only event traces (JSONL per surface per day)
├── L2/             ← L2: curated facts per surface (Markdown)
└── L3/             ← L3: cross-surface synthesis (profile/recent/scope/preferences)

L1（事件轨迹）：trace/<surface>/<date>.jsonl —— 仅追加写入，覆盖 chat/notebook/quiz/kb/book/cowriter 等 surface

L2（surface 摘要）：L2/<surface>.md —— 精选的事实；每条 L2 记录都引用了某条 L1 原始事件

L3（跨 surface 合成）：L3/{profile,recent,scope,preferences}.md —— 跨 surface 合成的用户画像；每条 L3 陈述都引用了 L2

记忆图谱（Memory Graph）：将整个金字塔可视化——L3 合成内容在中心，L2 在中间环，L1 事件在外环。追溯任何合成陈述到其背后的精确原始事件。没有黑箱。

deeptutor memory show    # view L2/L3 memory documents
deeptutor memory clear   # clear L1 or all memory

也可通过 CLI 管理；Settings → Memory 可让你调整 consolidator 的 Update/Audit/Dedup 预算。

多引擎知识库

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

文档解析引擎（在 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 "gradient descent mechanics"
deeptutor kb list

知识库可在 Chat、Partners、Co-Writer 和 Book 之间复用。

Partners：持久化 AI 伴侣

Partners 是持久化的伴侣，拥有各自的灵魂、模型策略、知识库、记忆和 IM 渠道。

在架构上，Partner 不是独立的机器人引擎：每条入站 IM 消息都会成为 partner-scoped 工作空间内的一个普通 ChatOrchestrator 轮次。partner 就是"一个有人格和有电话号码的聊天"。

SOUL.md：人格/行为定义

独立的模型选择

自有知识库、技能和笔记本

自有记忆（读取所有者的记忆，写入自己的）

渠道：连接 IM 平台的桥梁

支持的 IM 平台（取决于安装的扩展）：飞书、Telegram、Slack、Discord、钉钉、QQ/NapCat、企业微信、WhatsApp、Zulip、Mattermost、Matrix、MoChat 和 Microsoft Teams。

Partners 也可以作为 subagent 行事，通过 consult_subagent 工具在任何 Chat 轮次中被调用。

My Agents：驱动本地编码 Agent

My Agents 让 DeepTutor 能够调用本地编码 Agent：

连接一个实时 Agent：将你机器上运行的 Claude Code、Codex、 Gemini、Kimi、opencode 或 MiMo Code CLI 接入，或接入你的某个 Partner，在聊天轮次中向其咨询。DeepTutor 实际运行另一个 Agent 并通过 consult_subagent 工具将其工作流式传输到 Activity 面板。用 Agent 芯片选择（或输入 @），并设置咨询可进行的轮数。

导入历史对话：将你现有的 Claude Code 和 Codex 对话历史作为命名、可搜索、可恢复的 Agent 导入。选择要导入的日期；刷新会重新同步最新内容。通过 + → My Agents 从任何聊天轮次引用导入的对话——DeepTutor 将其作为第三方转录本读取，保持其作为他们的对话，而非 DeepTutor 自己的声音。

Co-Writer：选区感知的 Markdown 起草

Co-Writer 是一个分栏视图的 Markdown 工作区，用于报告、教程、笔记和长篇学习内容。文档自动保存并带实时预览（KaTeX 数学、图表围栏），当草稿成为可复用的上下文时，可以保存回笔记本。

其核心思想是精准编辑：选中一段内容，让 DeepTutor 重写、扩展或精简。编辑 Agent 可以基于知识库或网络证据进行修改，保留完整的工具调用追踪，并将每次更改显示为接受/拒绝的 diff——所有更改在你批准之前都不会落地。

Book：从你的资料生成活书

Book 将选定的来源（知识库、笔记本、题库、聊天历史）编译成一本交互式活书——不是静态 PDF，而是由类型化块构建的阅读环境。

创建流程在生成内容之前先提出章节大纲，因此你审查的是结构，而非接受一个盲目的单次输出。

每章编译成类型化块：文本、提示卡、测验、闪卡、时间线、代码、图表、交互式 HTML、动画、概念图、深度 dive 和用户笔记——每页都有各自的 Page Chat。块可独立编辑：插入、移动、重新生成或切换块的类型，无需重写整章。

CLI 与 Agent 原生接口

DeepTutor 的设计目标是可以被其他 Agent 驱动：

# Interactive REPL
deeptutor chat

# Single run, human-readable
deeptutor run deep_research "Survey 2026 RAG advances" --config mode=report

# Machine-readable (NDJSON streaming)
deeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json

# Stateful multi-turn sessions
SID=$(deeptutor run deep_research "RAG survey" --format json \
  | jq -r 'select(.type=="done").session_id')
deeptutor run deep_question "Quiz me on that" --session "$SID" --format json

使用 --format json 时，每轮输出 NDJSON：content、tool_call、tool_result、done 事件，每行带有 session_id 标记。在无 TTY 情况下，ask_user 暂停时自动以空回复解析而非挂起——适合 CI/CD。

根目录的 SKILL.md 是一份约 150 行的交接文档，教任何工具调用型 LLM 在一次阅读中掌握整个 CLI 表面。Claude Code、Codex 和 OpenCode 会自动识别它；也可以作为工具包装 deeptutor run 用于 LangChain 或 AutoGen 流水线。

完整 CLI 命令参考

🌟 GitHub：HKUDS/DeepTutor

🌐 网站：deeptutor.info

📄 论文：arXiv:2604.26962

📦 Docker 镜像：ghcr.io/hkuds/deeptutor

💬 Discord：discord.gg/eRsjPgMU4t

DeepTutor 有几个工程决策值得关注：

单一 Agent 循环驱动所有模式：Chat/Quiz/Research/Visualize 不是独立的代码路径——它们是挂载不同工具的同一循环。切换模式时上下文不会丢失，工具可以在单轮中自由组合（RAG 检索和网络搜索同时进行）。

三层可审计记忆：L1→L2→L3 引用链确保每条合成陈述都能追溯到原始事件。这解决了个性化 AI 工具的一个根本问题：用户不知道系统"记住"了什么，也不知道这些记忆从何而来。可视化的记忆图谱使这一点透明化。

Partner 作为 scoped 聊天工作空间：Partner 不是独立的机器人——它是一个有灵魂和 IM 渠道的聊天作用域。这种抽象使得相同的 RAG、记忆和工具调用机制可以被复用到任何 IM 平台的伴侣场景，而无需维护多条代码路径。

Agent 原生 CLI 设计：NDJSON 输出、headless 安全的 ask_user 自动解析，以及将根 SKILL.md 作为 Agent 交接文档——这些细节表明该项目从一开始就是为被其他 Agent 驱动而设计的，而非事后补丁。

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

探索 PrimeSkills——一个经过验证的 AI Agent 和技能精选市场，每个都针对真实企业工作流进行了验证。没有炒作，只有真正有效的东西。

访问我的个人网站了解更多见解和有趣的产品。