# AI Agent 企业级终身个性化智能辅导平台

**Repository Path**: north-dream-testing/Personalized-Intelligent-Tutoring-Platform

## Basic Information

- **Project Name**: AI Agent 企业级终身个性化智能辅导平台
- **Description**:  Agent 原生终身个性化辅导平台。它将智能对话、深度求解、学术研究、知识管理、沉浸式阅读/观看、掌握路径练习等学习场景统一在一个可扩展的系统中，通过多智能体协作和三层记忆机制为每位学习者提供持续进化的个性化学习体验。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-25
- **Last Updated**: 2026-09-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

<p align="center">
  <img src="assets/figs/logo/logo.png" alt="DeepTutor Logo" height="64" style="vertical-align: middle;">
  <img src="assets/figs/logo/banner.png" alt="DeepTutor" height="56" style="vertical-align: middle;">
</p>

# DeepTutor — 终身个性化智能辅导平台

<p align="center">
  <strong>Agent 原生 · 多智能体协作 · 三层记忆 · 多引擎 RAG · 沉浸式学习</strong>
</p>

<p align="center">
  <a href="README.md"><img alt="English" src="https://img.shields.io/badge/English-BCDCF7?style=flat-square"></a>
  <a href="README.ZH-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-4CAF50?style=flat-square"></a>
</p>

<p align="center">
  <a href="https://www.python.org/downloads/"><img alt="Python 3.11+" src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white"></a>
  <a href="https://nextjs.org/"><img alt="Next.js 16" src="https://img.shields.io/badge/Next.js-16-000000?style=flat-square&logo=next.js&logoColor=white"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square"></a>
  <a href="https://github.com/HKUDS/DeepTutor/releases"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/HKUDS/DeepTutor?style=flat-square&color=brightgreen"></a>
  <a href="https://arxiv.org/abs/2604.26962"><img alt="arXiv" src="https://img.shields.io/badge/arXiv-2604.26962-b31b1b?style=flat-square&logo=arxiv&logoColor=white"></a>
</p>

<p align="center">
  <a href="https://deeptutor.info" target="_blank">官方文档</a> ·
  <a href="https://github.com/HKUDS/DeepTutor/issues/498" target="_blank">功能路线图</a> ·
  <a href="CONTRIBUTING.md" target="_blank">贡献指南</a> ·
  <a href="https://discord.gg/eRsjPgMU4t" target="_blank">Discord 社区</a>
</p>

</div>

---

## 项目简介

**DeepTutor** 是 **Agent 原生终身个性化辅导平台**。它将智能对话、深度求解、学术研究、知识管理、沉浸式阅读/观看、掌握路径练习等学习场景统一在一个可扩展的系统中，通过多智能体协作和三层记忆机制为每位学习者提供持续进化的个性化学习体验。

### 核心亮点

| 特性 | 说明 |
|------|------|
| **统一运行时** | 聊天、求解、测验、研究、可视化、掌握路径、沉浸式阅读/观看共享同一能力运行时和会话上下文 |
| **三层记忆系统** | L1 原始事件 → L2 事实摘要 → L3 综合洞察，记忆图谱可视化关联关系 |
| **多引擎知识检索** | 支持 LlamaIndex、PageIndex、GraphRAG、LightRAG、WeKnora、Obsidian 等多种 RAG 引擎 |
| **智能体生态** | 支持 Claude Code、Codex、Kimi 等外部智能体接入，支持 Partner 持久化 IM 伴侣 |
| **沉浸式视频学习** | YouTube 隐私增强播放、同步字幕、时间戳定位辅导、可恢复学习进度 |
| **可扩展工具链** | 内置工具、MCP 服务、CLI 应用、文生图/文生视频/语音模型、社区技能市场 |

---

## 系统架构

```
┌─────────────────────────────────────────────────────────────────────┐
│                        DeepTutor 系统架构                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────┐    HTTP/WS     ┌──────────────────────────────┐  │
│  │   浏览器      │ ◄────────────► │   Next.js 前端 (:3782)        │  │
│  │   (用户界面)  │                │   · 聊天界面                  │  │
│  └──────────────┘                │   · 学习空间                  │  │
│                                   │   · 设置中心                  │  │
│                                   └──────────┬───────────────────┘  │
│                                              │ 反向代理 /api/*      │
│                                   ┌──────────▼───────────────────┐  │
│                                   │   FastAPI 后端 (:8001)        │  │
│                                   │   · Agent 运行时引擎          │  │
│                                   │   · 能力插件系统              │  │
│                                   │   · 会话管理                  │  │
│                                   ──────────┬───────────────────┘  │
│                                              │                      │
│                    ┌─────────────────────────┼─────────────────┐    │
│                    ▼                         ▼                 ▼    │
│           ┌────────────┐           ┌──────────────┐   ┌──────────┐ │
│           │   Redis     │           │   SQLite     │   │  文件系统 │ │
│           │  (会话协调)  │           │  (用户数据)   │   │ (Workspace)│ │
│           └────────────┘           ──────────────┘   └────────── │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    外部服务集成                               │   │
│  │  LLM Providers │ Embedding │ Search │ TTS/STT │ Image/Video │   │
│  │  (OpenAI/      │ (OpenAI/  │ (SearX │ (OpenAI │ (DALL·E/    │   │
│  │   Anthropic/   │  Jina/    │  NG/   │  TTS/   │  Stable     │   │
│  │   DeepSeek...) │  BGE...)  │ Bocha) │ Whisper)│  Diffusion) │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
```

---

## 模块界面预览

### 主导航模块

| 模块 | 说明 | 界面预览 |
|------|------|----------|
| **主页 / 智能对话** | AI 对话入口，支持聊天、深度求解、深度提问、深度研究等多种模式 | ![主页](assets/screenshots/01_home.png) |
| **伙伴** | 创建和管理 AI 伙伴，支持飞书、Telegram、Slack 等 IM 渠道对接 | ![伙伴](assets/screenshots/02_partners.png) |
| **智能体** | 连接外部智能体（Claude Code、Codex 等），导入历史对话 | ![智能体](assets/screenshots/03_agents.png) |
| **协作写作** | 多文档协同写作，支持保存至笔记本 | ![协作写作](assets/screenshots/04_co_writer.png) |

### 个性化学习模块

| 模块 | 说明 | 界面预览 |
|------|------|----------|
| **图书** | AI 生成个性化教材，支持流式编译、进度跟踪、Markdown 导出 | ![图书](assets/screenshots/05_books.png) |
| **掌握路径** | 自适应学习路径，含测验和掌握度评估 | ![掌握路径](assets/screenshots/06_mastery.png) |
| **沉浸式阅读** | 文档旁开线程阅读，逐页引用标注 | ![沉浸式阅读](assets/screenshots/07_reading.png) |
| **沉浸式观看** | YouTube 视频学习，同步字幕、时间戳辅导 | ![沉浸式观看](assets/screenshots/08_watching.png) |

### 学习空间

学习空间是对话、智能体、笔记与题目的集中管理中心。

![学习空间](assets/screenshots/09_space.png)

| 子模块 | 说明 | 界面预览 |
|--------|------|----------|
| **聊天历史** | 回顾并继续此前的对话 | ![聊天历史](assets/screenshots/20_space_chat_history.png) |
| **题库** | 跨会话回顾和整理测验题目 | ![题库](assets/screenshots/21_space_questions.png) |
| **Personas** | 每轮对话中套用的行为预设 | ![Personas](assets/screenshots/22_space_personas.png) |
| **技能** | 模型按需读取的能力手册 | ![技能](assets/screenshots/23_space_skills.png) |
| **MCP 服务** | 连接托管 MCP 服务，将工具带进对话 | ![MCP 服务](assets/screenshots/24_space_mcp.png) |
| **CLI 应用** | CLI-Anything 目录的命令行工具 | ![CLI 应用](assets/screenshots/25_space_cli_apps.png) |

### 记忆系统

三层记忆架构使个性化可见、可编辑。

![记忆系统](assets/screenshots/10_memory.png)

| 层级 | 说明 | 界面预览 |
|------|------|----------|
| **记忆图谱** | 可视化 L1→L2→L3 记忆关联关系 | ![记忆图谱](assets/screenshots/26_memory_graph.png) |
| **L1 工作记忆** | 原始事件记录，对话中的即时信息 | ![L1 工作记忆](assets/screenshots/27_memory_l1.png) |
| **L2 短期记忆** | 事实摘要，从 L1 事件中提取的关键信息 | ![L2 短期记忆](assets/screenshots/28_memory_l2.png) |
| **L3 长期记忆** | 综合洞察，跨表面的深度理解 | ![L3 长期记忆](assets/screenshots/29_memory_l3.png) |
| **记忆解析** | 记忆的冲突检测与消解 | ![记忆解析](assets/screenshots/30_memory_resolve.png) |

### 知识与工具

| 模块 | 说明 | 界面预览 |
|------|------|----------|
| **知识中心** | 管理知识库与检索引擎，支持多引擎 RAG | ![知识中心](assets/screenshots/11_knowledge_bases.png) |
| **笔记本** | 整理来自对话、研究、智能写作等的产出 | ![笔记本](assets/screenshots/12_notebooks.png) |

### 系统管理

| 模块 | 说明 | 界面预览 |
|------|------|----------|
| **设置中心** | 外观、网络、模型、知识库、聊天、记忆等全量配置 | ![设置](assets/screenshots/13_settings.png) |
| **用户管理** | 管理员用户管理界面 | ![用户管理](assets/screenshots/31_admin_users.png) |
| **个人资料** | 用户头像、个人信息管理 | ![个人资料](assets/screenshots/32_profile.png) |
| **课程** | 课程学习管理 | ![课程](assets/screenshots/33_courses.png) |

### 认证与辅助

| 模块 | 说明 | 界面预览 |
|------|------|----------|
| **登录** | 用户登录界面 | ![登录](assets/screenshots/18_login.png) |
| **注册** | 新用户注册界面 | ![注册](assets/screenshots/19_register.png) |
| **Whisper** | 语音转文字功能 | ![Whisper](assets/screenshots/35_whisper.png) |

---

## 快速开始

### 环境要求

| 组件 | 最低版本 | 推荐版本 |
|------|----------|----------|
| Python | 3.11 | 3.11 - 3.14 |
| Node.js | 20 | 22 LTS |
| Docker | 20.10+ | 最新版 |
| 内存 | 4 GB | 8 GB+ |
| 磁盘空间 | 5 GB | 20 GB+ |

### 方式一：Docker 部署（推荐）

最简单的一键部署方式，无需本地构建。

```bash
# 1. 克隆项目
git clone https://gitee.com/north-dream-testing/Personalized-Intelligent-Tutoring-Platform.git
cd DeepTutor

# 2. 复制环境变量配置
cp .env.example .env

# 3. 启动服务（使用预构建镜像）
python scripts/docker_compose.py -f docker-compose.ghcr.yml up -d

# 4. 查看运行状态
python scripts/docker_compose.py -f docker-compose.ghcr.yml ps
```

启动后访问：
- 前端界面：http://localhost:3782
- 后端 API：http://localhost:8001
- 健康检查：http://localhost:8001/health/ready

### 方式二：PyPI 安装

```bash
# 创建项目目录
mkdir -p my-deeptutor && cd my-deeptutor

# 安装 DeepTutor
pip install -U deeptutor

# 初始化配置（引导式设置端口、LLM 提供商等）
deeptutor init

# 启动服务
deeptutor start
```

### 方式三：源码安装

```bash
git clone https://gitee.com/north-dream-testing/Personalized-Intelligent-Tutoring-Platform.git
cd DeepTutor

# 安装 Python 依赖
pip install -e ".[all]"

# 安装前端依赖并构建
cd web
npm install
npm run build
cd ..

# 初始化并启动
deeptutor init
deeptutor start
```

---

## 配置指南

### 运行时配置

DeepTutor 使用 JSON 文件进行运行时配置，配置文件位于 `data/user/settings/` 目录：

| 配置文件 | 说明 |
|----------|------|
| `system.json` | 系统级配置（端口、API 地址等） |
| `interface.json` | 界面配置（主题、语言、侧边栏顺序） |
| `model_catalog.json` | 模型服务配置（LLM、Embedding、搜索等） |

### 语言设置

修改 `data/user/settings/interface.json` 中的 `language` 字段：

```json
{
  "theme": "snow",
  "language": "zh",
  "sidebar_description": "✨ Data Intelligence Lab @ HKU",
  "sidebar_nav_order": {
    "start": ["/", "/history", "/knowledge-bases", "/notebooks"],
    "learnResearch": ["/question", "/solver", "/research", "/co_writer"]
  }
}
```

支持的语言值：`zh`（简体中文）、`en`（英文）、`chinese`、`cn`

### 模型配置

在 `data/user/settings/model_catalog.json` 中配置 LLM 提供商：

```json
{
  "services": {
    "llm": {
      "active_profile_id": "openai",
      "profiles": {
        "openai": {
          "provider": "openai",
          "base_url": "https://api.openai.com/v1",
          "api_key": "sk-...",
          "model": "gpt-4o"
        }
      }
    }
  }
}
```

### Docker 部署配置

使用 `docker-compose.ghcr.yml` 部署时的关键配置项：

```yaml
services:
  redis:
    image: redis:7.4-alpine
    container_name: deeptutor-redis
    restart: unless-stopped

  deeptutor:
    image: ghcr.io/hkuds/deeptutor:latest
    ports:
      - "8001:8001"   # 后端 API
      - "3782:3782"   # 前端界面
    volumes:
      - ./data:/app/data
      - ./data/user/workspace:/workspace
```

---

## 项目结构

```
DeepTutor/
├── assets/                 # 静态资源（Logo、截图等）
│   ├── figs/              # 图片资源
│   ├── README/            # 多语言 README
│   └── screenshots/       # 界面截图
├── data/                   # 运行时数据目录
│   ── user/
│       ├── settings/      # JSON 配置文件
│       ├── workspace/     # 内容工作区
│       ├── memory/        # 记忆数据
│       └── knowledge_bases/ # 知识库数据
── deeptutor/             # Python 后端核心
│   ├── agents/            # Agent 实现
│   ├── capabilities/      # 能力插件
│   ├── memory/            # 记忆系统
│   ├── rag/               # RAG 引擎
│   └── tools/             # 工具实现
├── deeptutor_cli/         # CLI 命令行工具
├── deeptutor_web/         # Web 后端（FastAPI）
├── web/                   # 前端（Next.js）
│   ├── app/               # 页面路由
│   ├── components/        # React 组件
│   └── lib/               # 工具库
├── scripts/               # 部署脚本
├── tests/                 # 测试用例
├── docker-compose.yml     # Docker Compose 配置
├── docker-compose.ghcr.yml # GHCR 镜像部署配置
├── Dockerfile             # 多阶段构建 Dockerfile
├── pyproject.toml         # Python 项目配置
└── README.md              # 英文 README
```

---

## 技术栈

### 后端

| 技术 | 版本 | 用途 |
|------|------|------|
| Python | 3.11 - 3.14 | 核心运行时 |
| FastAPI | 最新 | Web 框架 |
| Pydantic | 2.0+ | 数据验证 |
| SQLAlchemy | 最新 | 数据库 ORM |
| Redis | 7.4 | 会话协调 |
| SQLite | 内置 | 用户数据存储 |

### 前端

| 技术 | 版本 | 用途 |
|------|------|------|
| Next.js | 16 | React 框架 |
| React | 19 | UI 库 |
| TypeScript | 5.x | 类型安全 |
| Tailwind CSS | 最新 | 样式框架 |

### AI / ML

| 技术 | 用途 |
|------|------|
| OpenAI SDK | GPT 系列模型调用 |
| Anthropic SDK | Claude 模型调用 |
| LlamaIndex | RAG 框架 |
| FAISS | 向量检索 |
| Tiktoken | Token 计数 |

### 部署

| 技术 | 用途 |
|------|------|
| Docker | 容器化部署 |
| Docker Compose | 多服务编排 |
| Supervisord | 进程管理 |
| GHCR | 容器镜像 registry |

---

## 核心功能详解

### 1. 智能对话系统

DeepTutor 的核心对话引擎支持多种交互模式：

- **普通聊天**：开放式对话，支持文件上传、多模态输入
- **深度求解（Deep Solve）**：分步推理解决复杂问题
- **深度提问（Deep Question）**：生成高质量问题促进思考
- **深度研究（Deep Research）**：多源信息整合的研究报告

### 2. 三层记忆架构

```
L3 综合洞察（Synthesis）
    ↑
L2 事实摘要（Surface Summary）
    ↑
L1 原始事件（Raw Events）
```

- **L1 工作记忆**：记录对话中的原始事件和即时信息
- **L2 短期记忆**：从 L1 中提取关键事实，形成结构化摘要
- **L3 长期记忆**：跨多个 L2 表面的深度综合，形成持久洞察

记忆图谱可视化展示三层记忆之间的关联关系，支持悬停预览和点击追踪。

### 3. 多引擎 RAG 系统

支持多种检索增强生成引擎：

| 引擎 | 特点 |
|------|------|
| LlamaIndex | 标准 RAG 流程，支持多种文档解析器 |
| PageIndex | 推理式检索，跨文档智能定位 |
| GraphRAG | 图结构知识表示，关系推理 |
| LightRAG | 轻量级高效检索 |
| WeKnora | 远程知识库服务 |
| Obsidian | 链接本地 Obsidian 仓库 |

### 4. 智能体生态

#### 外部智能体接入
支持连接以下外部智能体：
- Claude Code（Anthropic）
- Codex（OpenAI）
- Kimi（月之暗面）
- opencode、MiMo、Hermes、OpenClaw、DeepSeek 等

#### Partner 系统
- 创建具有独特人格的 AI 伙伴
- 支持飞书、Telegram、Slack、Mattermost、Zulip 等 15+ IM 渠道
- 每个 Partner 拥有独立的记忆和知识库
- 支持对话分支、恢复、删除和可重放轨迹

### 5. 沉浸式学习

#### 沉浸式阅读
- 文档与对话线程并排显示
- 逐页引用标注
- 支持 EPUB、PDF、DOCX 等多种格式

#### 沉浸式观看
- YouTube 视频隐私增强播放
- 同步字幕显示
- 时间戳定位辅导
- 可恢复学习进度
- 支持自托管 Invidious 实例

---

## 开发指南

### 本地开发环境

```bash
# 1. 克隆仓库
git clone https://gitee.com/north-dream-testing/Personalized-Intelligent-Tutoring-Platform.git
cd DeepTutor

# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

# 3. 安装开发依赖
pip install -e ".[dev]"

# 4. 安装前端依赖
cd web
npm install
cd ..

# 5. 启动开发服务器
deeptutor start --dev
```

### 代码规范

- **Python**：遵循 Black 格式化，Ruff lint 检查
- **TypeScript**：遵循 ESLint + Prettier 规范
- **提交信息**：使用 Conventional Commits 格式

### 测试

```bash
# 运行 Python 测试
pytest tests/

# 运行前端测试
cd web && npm test
```

---

## 版本历史

| 版本 | 日期 | 亮点 |
|------|------|------|
| v1.6.8 | 2026-09-14 | 聊天回收站、全历史搜索、知识库透视工具 |
| v1.6.7 | 2026-09-11 | 修复图书章节、测验、公式渲染等问题 |
| v1.6.6 | 2026-09-08 | 修复答案提交、复制按钮、Partner 知识库连接 |
| v1.6.5 | 2026-09-06 | 内容工作区、多语言 exec 工具、掌握路径模式 |
| v1.6.0 | 2026-08-27 | EPUB 阅读标注、课程系统、Web 源同步、共享图书 |
| v1.5.0 | 2026-05-22 | 自动模式、三层记忆、深度研究/求解/提问、LlamaIndex RAG |
| v1.4.0 | 2026-05-22 | GA 版本：自动模式、三层记忆、多智能体协作 |
| v1.0.0 | 2026-04-04 | Agent 原生架构重写（~20 万行代码） |

完整版本历史请参阅 [Releases](https://github.com/HKUDS/DeepTutor/releases)。