DeepTutor：Agent 原生个性化 AI 学习与家教平台

📖 一、平台介绍

核心架构： 与传统单轮对话的 AI 聊天框不同，DeepTutor 采用 双环多智能体（Dual-Loop Multi-Agent）架构与 多层记忆机制。它不仅能将用户上传的教材、论文和课件构建为专属知识库，还能通过多个协同 Agent 进行深度推理。

主要能力：

1. 深度推理：分步解题、自动测验与研究报告生成。
2. 知识管理：基于个人文献或教材进行精准内容检索（RAG）。
3. 视觉化展示：数学公式动画推导与动态图表渲染，降低理解门槛。

✨ 二、核心功能详解

1. 深度解题 (Deep Solve) 🔢 采用“分析环”（检索 + 笔记整理）与“解决环”（规划 + 执行 + 校验）的双重 Multi-Agent 机制。擅长复杂数学题、物理题及编程逻辑推理，给出带精确引用的步骤级解答，非简单直接回答。
2. 知识库与 RAG 问答 (Knowledge Base) 📂 支持批量上传多种格式的本地资料文件（如 PDF, DOCX, PPTX, Excel）。基于个人文献或教材进行精准内容匹配，确保答案来源可查，减少幻觉产生。
3. 自适应出题与测验 (Deep Question) 📝 根据上传的资料自动生成知识点测试题。AI 会根据答题情况实时调整题目难易度，智能避免重复出相同的题目，从而最大化学习效果。
4. 深度研究报告 (Deep Research) 🧪 输入课题后，系统自动拆解为多个子任务，跨网络、学术数据库及本地文档同时搜索信息，直接输出结构化的专业研究报告初稿。
5. 动态可视化 (Math Animator & Visuals) 🎬 集成 Manim 动画引擎及 Chart.js/SVG 渲染技术。将抽象的数学公式、物理概念与算法推导转化为流畅的动态视频或交互式图表。
6. 多端伴侣与技能扩展 (Partners & Skills) 🤖 支持创建具备独立人设（Persona）与长期记忆的 TutorBot，可无缝接入 Discord、Telegram、Slack 等外部平台；内置 Excel、Word、PPT 读写处理及 MCP 技能，实现文件直接编辑与管理。

👥 三、适用人群与应用场景

1. 学生群体

• 适用阶段：高中 / 大学 / 考研 / 竞赛。
• 主要应用：上传教材和课件，进行知识点梳理、疑难题目深度拆解与自我测验；适合准备各类考试或学科竞赛的学习者。

1. 科研人员 & 学者

• 核心需求：高效处理文献资源。
• 主要应用：快速研读海量论文、自动整理复杂的文献笔记摘要、利用系统生成课题相关的深度研究报告以节省时间成本。

1. 开发者 & 终身学习者

• 应用场景：自主构建私有技术知识库，避免知识断层。
• 核心工具：利用 Agent 进行编程指导（Code Tutor）与长期的个人技能树管理；适合需要定制化学习路径的技术人员。

💰 四、免费 / 付费情况说明

1. 软件授权模式 DeepTutor 本身遵循 Apache-2.0 / MIT 开源协议，属于完全免费的开源项目。用户可自由下载源码或镜像进行部署与二次开发。GitHub 源码仓库地址：https://github.com/HKUDS/DeepTutor
2. 运行成本构成 AI 对话、解题及报告生成需要调用大语言模型（LLM）能力，实际费用取决于您的部署模式：

• 云端 API 消耗费（有门槛但便捷）：用户需填入自备的 OpenAI、Claude、DeepSeek 等 API Key。产生的费用由对应服务商收取。建议优先选择性价比高的模型 API 以控制成本。
• 零成本本地部署方案：搭配本地大模型运行，例如通过 Ollama 启动 Qwen / Llama 版本。此方式可实现 100% 免费且完全离线/隐私安全。

🛠️ 五、快速开始：部署与启动指南

⚙️ 前置环境准备 请确保您的系统已安装 Python 3.11+ 及 Node.js 20+ (前端依赖)。若需本地运行，建议使用 Docker 或直接克隆源码。以下提供三种常用方式：

🔹 方案 A：命令一行安装（最简体验）

适合只想快速启动并测试基本功能的用户。执行完此流程后，直接访问浏览器即可使用服务界面。

bash

# 1. 从 PyPI 下载安装包
pip install -U deeptutor

# 2. 初始化配置 (按提示设置端口、API Key/LLM 提供商)
deeptutor init

# 3. 启动服务 (会自动拉起前端与后端进程)
deeptutor start
# 1. 从 PyPI 下载安装包
pip install -U deeptutor

# 2. 初始化配置 (按提示设置端口、API Key/LLM 提供商)
deeptutor init

# 3. 启动服务 (会自动拉起前端与后端进程)
deeptutor start

• ✅ 访问地址：http://127.0.0.1:3782。(注意：首次启动需在设置中配置大模型，否则对话无法响应)

🔹 方案 B：Docker 一键运行（适合容器化环境）

无需在宿主机安装 Python 环境，直接拉取官方镜像即可无缝部署数据目录到本地硬盘。

bash

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v ~/deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest
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，进入设置 -> Models (Settings → Models) 填入 API Key。
• 💾 数据持久化：挂载的 -v ~/deeptutor-data:/app/data 确保您的本地教材、笔记在服务重启后不丢失。

🔹 方案 C：源码克隆部署（适合开发者）

需要深度定制模型、修改前端代码或进行二次开发时使用此方式，以便管理依赖库和环境变量。

bash

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

# 创建虚拟环境并激活 (建议)
python3 -m venv .venv && source .venv/bin/activate

pip install -e . 

# (可选) 前端依赖安装，需联网下载 npm packages
(cd web && npm ci --legacy-peer-deps) 

deeptutor init
deeptutor start
git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

# 创建虚拟环境并激活 (建议)
python3 -m venv .venv && source .venv/bin/activate

pip install -e . 

# (可选) 前端依赖安装，需联网下载 npm packages
(cd web && npm ci --legacy-peer-deps) 

deeptutor init
deeptutor start

⚠️ 六、注意事项与最佳实践

1. 模型配置必填：首次启动后务必在 Web 端 Settings (设置 → Models) 中配置大模型（推荐 DeepSeek, OpenAI, Ollama）。若无连接，推理功能将无法正常工作。
2. Token 消耗预期管理：Deep Solve 和 Deep Research 会触发多轮交互与并发检索，单次问答消耗的 Token 量远高于普通聊天。**建议优先配置高性价比的 API Key（如 DeepSeek）**以控制长期成本。
3. 动画依赖环境检查：如需使用 Manim 数学公式动态视频功能，本地环境必须安装 ffmpeg (Linux/Mac) 或相应系统组件 (Sudo apt-get install ffmpeg) 及 LaTeX 基础库；若仅需普通图表渲染则无需此配置。
4. 数据隐私与存储建议：若您选择云端 API 模式，请确保您了解相关服务商的数据策略；本地部署模式下，所有数据处理均在您的设备内完成，更适合处理敏感的学术资料或个人私有教材，同时利用 Docker 方案可更好地保护数据安全（挂载目录）。