## 项目概述

DeepTutor 是一个由 HKUDS 团队开发的终身个性化辅导系统，采用 Agent-Native 架构，将辅导、问题求解、测验生成、研究、可视化和掌握练习整合到一个可扩展的学习工作区中。项目以 Python 为主要语言，前端使用 Next.js 16，遵循 Apache-2.0 许可证。DeepTutor 旨在通过统一的代理循环和可检查的记忆系统，提供真正个性化的智能辅导体验。

## 核心功能

- **统一代理循环**：聊天、测验、研究、可视化、求解和掌握路径均运行在同一代理引擎上，切换目标无需更换引擎，上下文随学习者移动。
- **连接的学习上下文**：知识库、书籍、Co-Writer 草稿、笔记本、题库、角色和记忆在所有工作流中保持可用，而非孤立工具。
- **子代理与伙伴**：可实时咨询 Claude Code、Codex、Gemini、Kimi、opencode 或 MiMo 等编码 CLI，或从任意轮次咨询伙伴，并可在同一大脑上运行持久 IM 伴侣。
- **多引擎知识**：支持 LlamaIndex、PageIndex、GraphRAG、LightRAG 或链接的 Obsidian 库的版本化 RAG 库，并配备可插拔文档解析。
- **可扩展工具与技能**：内置工具、MCP 服务器、CLI 应用、图像/视频/语音生成模型，以及可从 EduHub 安装的社区技能。
- **可检查记忆**：L1 痕迹、L2 表面摘要和 L3 综合使个性化可见且可编辑，记忆图将每个声明追溯到其证据。

## 适用与不适用场景

**适用场景：**

- 个性化学习辅导，需要长期记忆和上下文跟踪。
- 需要多引擎 RAG 支持的知识密集型学习任务。
- 需要集成多种 AI 工具（如编码 CLI、IM 伴侣）的复杂学习工作流。
- 教育工作者或学习者希望创建交互式书籍、测验和掌握路径。

**不适用场景：**

- 需要轻量级、无依赖的简单问答工具。
- 对数据隐私要求极高，且不希望任何代码执行沙箱的环境。
- 需要完全离线且无外部模型服务的场景（虽然支持本地模型，但配置复杂）。
- 非教育领域的一般性 AI 助手需求。

## 技术架构与依赖

- **后端**：Python 3.11+，FastAPI，采用代理循环架构，支持工具调用、能力插件模型。
- **前端**：Next.js 16，React 19，支持 HMR 开发模式。
- **RAG 引擎**：LlamaIndex（默认）、PageIndex、GraphRAG、LightRAG、LightRAG Server、Tencent IMA、Obsidian。
- **文档解析**：Text-only、MinerU、Docling、markitdown、PyMuPDF4LLM。
- **记忆系统**：三层文件备份（L1 痕迹、L2 表面摘要、L3 综合）。
- **部署**：支持 PyPI 安装、源码安装、Docker 容器、CLI-only 模式。
- **依赖**：Node.js 20+（PyPI 安装）或 22 LTS（源码安装），可选 extras 如 dev、partners、matrix、math-animator。

## 安装与快速开始

**选项 1：从 PyPI 安装**（完整本地 Web 应用 + CLI）

```bash
mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init     # 提示端口、LLM 提供商等
deeptutor start    # 启动后端和前端
```

**选项 2：从源码安装**（开发模式）

```bash
git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -e .
( cd web && npm ci --legacy-peer-deps )
deeptutor init
deeptutor start --dev
```

**选项 3：Docker**

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

**选项 4：仅 CLI**（从源码安装）

```bash
git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
python3 -m venv .venv-cli && source .venv-cli/bin/activate
python -m pip install -e ./packaging/deeptutor-cli
deeptutor init --cli
deeptutor chat
```

## 典型使用方法

**交互式聊天**：

```bash
deeptutor chat
```

**单次运行**：

```bash
deeptutor run chat "解释傅里叶变换" --tool rag --kb textbook
deeptutor run deep_research "调研 2026 年 RAG 论文" --config mode=report --config depth=standard
```

**知识库管理**：

```bash
deeptutor kb create my-kb --doc textbook.pdf
deeptutor kb search my-kb "query"
```

**技能安装**：

```bash
deeptutor skill search "socratic tutor"
deeptutor skill install socratic-tutor
```

**记忆查看**：

```bash
deeptutor memory show
```

**代理驱动**：

```bash
deeptutor run deep_solve "求 d/dx[sin(x^2)]" --tool reason --format json
```

## 配置与部署要点

- **配置文件**：位于 `data/user/settings/` 下，包括 `model_catalog.json`、`system.json`、`auth.json`、`integrations.json`、`interface.json`、`main.yaml`、`agents.yaml`。
- **模型配置**：在 Web 界面的 Settings → Models 中添加 LLM 和 Embedding 配置文件。
- **Docker 部署**：仅需发布前端端口 3782，后端通过容器内代理访问；如需访问宿主机模型服务，使用 `--add-host=host.docker.internal:host-gateway`。
- **多用户部署**：默认单用户，可通过 `auth.json` 启用认证，支持隔离的用户工作区。
- **代码执行沙箱**：默认启用子进程沙箱，可通过 `sandbox_allow_subprocess` 设置关闭。
- **环境变量**：项目根目录的 `.env` 文件不会被读取，配置集中在 `data/user/settings/`。

## 限制、风险与许可证

- **许可证**：Apache-2.0。
- **风险**：运行模型生成的代码存在信任风险，建议在隔离环境中使用；多用户部署需要谨慎管理权限和资源隔离。
- **限制**：CLI-only 包尚未发布到 PyPI；部分功能（如 OpenAI Codex OAuth）为实验性，可能不稳定。
- **依赖**：需要 Python 3.11+ 和 Node.js 20+，某些可选功能需要额外系统库（如 LaTeX、ffmpeg）。

## 官方链接

- GitHub 仓库：https://github.com/HKUDS/DeepTutor
- 官方文档：https://deeptutor.info/
- arXiv 论文：https://arxiv.org/abs/2604.26962
- Discord 社区：https://discord.gg/eRsjPgMU4t
- EduHub 技能中心：https://eduhub.deeptutor.info/

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、CONTRIBUTING.md、发布说明。
- 分析时间：2026-08-10（基于最新发布 v1.5.11 的日期）。