GitShelf — GitHub 项目目录

项目概述

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）

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

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

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

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

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

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

典型使用方法

交互式聊天：

deeptutor chat

单次运行：

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

知识库管理：

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

技能安装：

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

记忆查看：

deeptutor memory show

代理驱动：

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 的日期）。

项目概览