Skip to content

Latest commit

 

History

History
760 lines (533 loc) · 32.1 KB

File metadata and controls

760 lines (533 loc) · 32.1 KB

📦 版本发布

[2026.4.21] v1.2.1agents.yaml 按阶段配置 chat token 上限(8000-token 回复);CLI / WebSocket / Web UI 重新生成上一条回复;RAG None 嵌入崩溃修复;Gemma json_object 兼容;暗色代码块可读性修复。

[2026.4.20] v1.2.0 — Book Engine 多智能体「活书」编译器(14 种块类型);多文档 Co-Writer 工作区;交互式 HTML 可视化;题库 @-引用进聊天;提示词外置第二阶段;侧栏重构。

[2026.4.18] v1.1.2 — 基于 Schema 的「频道」标签页与密钥脱敏;RAG 收敛为单一流水线;RAG/知识库一致性加固;聊天提示词外置;以及泰语 README。

[2026.4.17] v1.1.1 — 全能力通用「立即回答」;Co-Writer 滚动同步;保存到笔记本时的消息选择;统一设置面板;流式「停止」按钮;TutorBot 配置原子写入。

[2026.4.15] v1.1.0 — LaTeX 块级公式解析重构;通过 agents.yaml 的 LLM 诊断探测;额外请求头转发修复;SaveToNotebook UUID 修复;Docker 与本地 LLM 使用说明。

[2026.4.14] v1.1.0-beta — 基于 URL 的可收藏会话;Snow 主题;WebSocket 心跳与自动重连;ChatComposer 性能修复;嵌入提供商注册表重构;Serper 搜索提供商。

[2026.4.13] v1.0.3 — 带书签与分类的测验笔记本;Visualize 支持 Mermaid;嵌入模型不一致检测;Qwen/vLLM 兼容;LM Studio 与 llama.cpp 支持;Glass 主题。

[2026.4.11] v1.0.2 — 搜索整合与 SearXNG 回退;提供商切换修复;前端资源泄漏修复。

[2026.4.10] v1.0.1 — Visualize 能力(Chart.js/SVG);测验去重;o4-mini 模型支持。

[2026.4.10] v1.0.0-beta.4 — 嵌入进度与限流重试;跨平台依赖修复;MIME 校验修复。

[2026.4.8] v1.0.0-beta.3 — 原生 OpenAI/Anthropic SDK(移除 litellm);Windows 数学动画支持;JSON 解析更健壮;完整中文 i18n。

[2026.4.7] v1.0.0-beta.2 — 热重载设置;MinerU 嵌套输出;WebSocket 修复;最低 Python 3.11+。

[2026.4.4] v1.0.0-beta.1 — 智能体原生架构重写(约 20 万行):Tools + Capabilities 插件模型、CLI 与 SDK、TutorBot、Co-Writer、引导式学习与持久记忆。

历史版本

[2026.1.23] v0.6.0 — 会话持久化、增量文档上传、灵活 RAG 流水线导入与完整中文本地化。

[2026.1.18] v0.5.2 — RAG-Anything 支持 Docling、日志优化与问题修复。

[2026.1.15] v0.5.0 — 统一服务配置、按知识库选择 RAG 流水线、出题改版与侧栏定制。

[2026.1.9] v0.4.0 — 多提供商 LLM 与嵌入、新首页、RAG 解耦与环境变量重构。

[2026.1.5] v0.3.0 — 统一 PromptManager、GitHub Actions CI/CD 与 GHCR 预构建镜像。

[2026.1.2] v0.2.0 — Docker 部署、Next.js 16 与 React 19、WebSocket 加固与关键漏洞修复。

📰 动态

[2026.4.4] 好久不见!✨ DeepTutor v1.0.0 终于到来 —— 在 Apache-2.0 许可下的智能体原生演进:自底向上架构重写、TutorBot、灵活模式切换。新篇章开启,故事继续!

[2026.2.6] 🚀 仅用 39 天即突破 10k star!感谢社区的大力支持!

[2026.1.1] 新年快乐!欢迎加入 Discord微信Discussions,一起塑造 DeepTutor 的未来!

[2025.12.29] DeepTutor 正式发布!

✨ 核心亮点

  • 统一聊天工作区 — 六种模式,同一条对话线。聊天、深度解题、测验生成、深度研究、数学动画与可视化共享上下文:从闲聊到多智能体解题、可视化概念、出题、再深入调研,消息不丢。
  • AI Co-Writer — 多文档 Markdown 工作区,AI 是一等协作者。划选文本即可改写、扩写或缩写,可结合知识库与网络;内容可沉淀到笔记本,反哺学习闭环。
  • Book Engine — 把资料变成结构化、交互式的「活书」。多智能体流水线设计大纲、检索相关来源,编译出含 14 种块类型的富页面 —— 测验、闪卡、时间线、概念图、交互演示等。
  • 知识中枢 — 上传 PDF、Markdown、纯文本构建 RAG 知识库;用彩色笔记本跨会话整理洞见;在题库中回顾测验成果;创建自定义 Skill 塑造 DeepTutor 的教学风格。文档主动参与每次对话。
  • 持久记忆 — 持续勾勒你的学习画像:学过什么、如何学习、目标何在。全功能与 TutorBot 共享,越用越准。
  • 个人 TutorBot — 不是聊天机器人,而是自主导师。每个 TutorBot 拥有独立工作区、记忆、人格与技能;可提醒、可学新能力、随你成长。由 nanobot 驱动。
  • 智能体原生 CLI — 能力、知识库、会话、TutorBot 一条命令可达;终端 Rich 输出给人看,JSON 给智能体与流水线。将根目录 SKILL.md 交给智能体即可自主操作。

🚀 快速开始

前提条件

在开始之前,请确保系统已安装:

依赖 版本 检查命令 说明
Git 任意 git --version 用于克隆仓库
Python 3.11+ python --version 后端运行时
Node.js 18+ node --version 前端构建(仅 CLI 或 Docker 可不装)
npm 9+ npm --version 一般随 Node.js 附带

你还需要至少一个 LLM 提供商的 API Key(例如 OpenAIDeepSeekAnthropic)。设置向导会引导你填写并完成连通性测试。

方案 A — 引导式安装(推荐)

一条交互脚本完成依赖安装、环境配置、连通性检测与启动,无需手改 .env

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

# 创建 Python 虚拟环境(任选其一):
conda create -n deeptutor python=3.11 && conda activate deeptutor   # 若使用 Anaconda/Miniconda
python -m venv .venv && source .venv/bin/activate                    # 否则(macOS/Linux)
python -m venv .venv && .venv\Scripts\activate                       # 否则(Windows)

# 启动引导
python scripts/start_tour.py

向导会询问使用方式:

  • Web 模式(推荐)— 安装全部依赖(pip + npm)、拉起临时服务并在浏览器打开 设置 页;四步引导配置 LLM、嵌入与搜索提供商并现场测通;完成后 DeepTutor 会按你的配置自动重启。
  • CLI 模式 — 全终端交互:选择依赖配置、安装依赖、配置提供商、验证连接并应用,全程不离开 shell。

任一方式完成后,在 http://localhost:3782 使用 DeepTutor。

日常启动 — 引导只需运行一次。之后请用:

python scripts/start_web.py

该命令会同时启动后端与前端并自动打开浏览器。仅在需要更换提供商或重装依赖时再运行 start_tour.py

方案 B — 本地手动安装

若希望完全自控,可自行安装与配置。

1. 安装依赖

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

# 创建并激活 Python 虚拟环境(与方案 A 相同)
conda create -n deeptutor python=3.11 && conda activate deeptutor

# 安装 DeepTutor(后端 + Web 服务依赖)
pip install -e ".[server]"

# 安装前端依赖(需要 Node.js 18+)
cd web && npm install && cd ..

2. 配置环境

cp .env.example .env

编辑 .env,至少填写必填项:

# LLM(必填)
LLM_BINDING=openai
LLM_MODEL=gpt-4o-mini
LLM_API_KEY=sk-xxx
LLM_HOST=https://api.openai.com/v1

# 嵌入(知识库必填)
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_API_KEY=sk-xxx
EMBEDDING_HOST=https://api.openai.com/v1
EMBEDDING_DIMENSION=3072
支持的 LLM 提供商
提供商 Binding 默认 Base URL
AiHubMix aihubmix https://aihubmix.com/v1
Anthropic anthropic https://api.anthropic.com/v1
Azure OpenAI azure_openai
BytePlus byteplus https://ark.ap-southeast.bytepluses.com/api/v3
BytePlus Coding Plan byteplus_coding_plan https://ark.ap-southeast.bytepluses.com/api/coding/v3
Custom (OpenAI-compat) custom
DashScope (Qwen) dashscope https://dashscope.aliyuncs.com/compatible-mode/v1
DeepSeek deepseek https://api.deepseek.com
Gemini gemini https://generativelanguage.googleapis.com/v1beta/openai/
GitHub Copilot github_copilot https://api.githubcopilot.com
Groq groq https://api.groq.com/openai/v1
llama.cpp llama_cpp http://localhost:8080/v1
LM Studio lm_studio http://localhost:1234/v1
MiniMax minimax https://api.minimax.io/v1
Mistral mistral https://api.mistral.ai/v1
Moonshot (Kimi) moonshot https://api.moonshot.ai/v1
Ollama ollama http://localhost:11434/v1
OpenAI openai https://api.openai.com/v1
OpenAI Codex openai_codex https://chatgpt.com/backend-api
OpenRouter openrouter https://openrouter.ai/api/v1
OpenVINO Model Server ovms http://localhost:8000/v3
Qianfan (Ernie) qianfan https://qianfan.baidubce.com/v2
SiliconFlow siliconflow https://api.siliconflow.cn/v1
Step Fun stepfun https://api.stepfun.com/v1
vLLM vllm http://localhost:8000/v1
VolcEngine volcengine https://ark.cn-beijing.volces.com/api/v3
VolcEngine Coding Plan volcengine_coding_plan https://ark.cn-beijing.volces.com/api/coding/v3
Xiaomi MIMO xiaomi_mimo https://api.xiaomimimo.com/v1
Zhipu AI (GLM) zhipu https://open.bigmodel.cn/api/paas/v4
支持的嵌入(Embedding)提供商
提供商 Binding 模型示例 默认维度
OpenAI openai text-embedding-3-large 3072
Azure OpenAI azure_openai 部署名称
Cohere cohere embed-v4.0 1024
Jina jina jina-embeddings-v3 1024
Ollama ollama nomic-embed-text 768
vLLM / LM Studio vllm 任意嵌入模型
任意 OpenAI 兼容 custom

与 OpenAI 兼容的提供商(DashScope、SiliconFlow 等)可通过 customopenai binding 使用。

支持的联网搜索提供商
提供商 环境变量键 说明
Brave BRAVE_API_KEY 推荐,有免费额度
Tavily TAVILY_API_KEY
Serper SERPER_API_KEY 通过 Serper 获取 Google 搜索结果
Jina JINA_API_KEY
SearXNG 自托管,无需 API Key
DuckDuckGo 无需 API Key
Perplexity PERPLEXITY_API_KEY 需要 API Key

3. 启动服务

最快方式(一条命令启动前后端):

python scripts/start_web.py

该命令会同时启动后端与前端并自动打开浏览器。

也可在两个终端分别手动启动:

# 后端(FastAPI)
python -m deeptutor.api.run_server

# 前端(Next.js)— 另开终端
cd web && npm run dev -- -p 3782
服务 默认端口
后端 8001
前端 3782

浏览器打开 http://localhost:3782

方案 C — Docker 部署

Docker 将前后端打包为单容器,本机无需安装 Python 或 Node.js。仅需 Docker Desktop(或 Linux 上的 Docker Engine + Compose)。

1. 配置环境变量(两种方式均需)

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
cp .env.example .env

编辑 .env,填写必填项(与方案 B相同)。

2a. 拉取官方镜像(推荐)

镜像发布于 GitHub Container Registry,支持 linux/amd64linux/arm64

docker compose -f docker-compose.ghcr.yml up -d

固定版本可编辑 docker-compose.ghcr.yml 中的镜像标签:

image: ghcr.io/hkuds/deeptutor:1.0.0  # 或 :latest

2b. 源码构建

docker compose up -d

本地根据 Dockerfile 构建并启动。

3. 验证与管理

容器健康后打开 http://localhost:3782

docker compose logs -f   # 查看日志
docker compose down       # 停止并移除容器
云端 / 远程部署

远程部署时,浏览器需知晓后端公网地址。在 .env 中增加:

NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001

前端启动脚本会在运行时应用,无需重新构建。

开发模式(热重载)

叠加 dev 覆盖以挂载源码并热重载:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up

deeptutor/deeptutor_cli/scripts/web/ 的修改会即时生效。

自定义端口

.env 中覆盖:

BACKEND_PORT=9001
FRONTEND_PORT=4000

然后重启:

docker compose up -d     # 或 docker compose -f docker-compose.ghcr.yml up -d
数据持久化

用户数据与知识库通过卷映射到本地:

容器内路径 宿主机路径 内容
/app/data/user ./data/user 设置、记忆、工作区、会话、日志
/app/data/knowledge_bases ./data/knowledge_bases 上传文档与向量索引

docker compose down 后目录仍保留,下次 up 会复用。

环境变量参考
变量 必填 说明
LLM_BINDING LLM 提供商(openaianthropic 等)
LLM_MODEL 模型名(如 gpt-4o
LLM_API_KEY API 密钥
LLM_HOST API 地址
EMBEDDING_BINDING 嵌入提供商
EMBEDDING_MODEL 嵌入模型名
EMBEDDING_API_KEY 嵌入 API 密钥
EMBEDDING_HOST 嵌入端点
EMBEDDING_DIMENSION 向量维度
SEARCH_PROVIDER 搜索(tavilyjinaserperperplexity 等)
SEARCH_API_KEY 搜索 API 密钥
BACKEND_PORT 后端端口(默认 8001
FRONTEND_PORT 前端端口(默认 3782
NEXT_PUBLIC_API_BASE_EXTERNAL 云端部署时后端公网 URL
DISABLE_SSL_VERIFY 关闭 SSL 校验(默认 false

方案 D — 仅 CLI

若只要 CLI、不要 Web 前端:

pip install -e ".[cli]"

仍需配置 LLM 提供商,最快方式:

cp .env.example .env   # 然后编辑 .env 填入 API Key 等

配置完成后即可使用:

deeptutor chat                                   # 交互 REPL
deeptutor run chat "Explain Fourier transform"   # 单次能力调用
deeptutor run deep_solve "Solve x^2 = 4"         # 多智能体解题
deeptutor kb create my-kb --doc textbook.pdf     # 构建知识库

完整 CLI 说明与命令表见 DeepTutor CLI


📖 探索 DeepTutor

DeepTutor 架构

💬 聊天 — 统一智能工作区

聊天工作区

六种模式共处同一工作区,由统一上下文管理串联:历史、知识库与引用跨模式保留,同一主题下可随时切换。

模式 作用
聊天 工具增强对话:RAG、联网搜索、代码执行、深度推理、头脑风暴、论文检索,按需组合。
深度解题 多智能体解题:规划、检索、求解与验证,步步可溯源引用。
测验生成 基于知识库出题,内置校验。
深度研究 主题拆解、并行调研 RAG/网络/论文,输出带引用报告。
数学动画 基于 Manim 将数学概念可视化为动画与分镜。
可视化 用自然语言描述生成交互式 SVG 图、Chart.js 图表、Mermaid 图或自包含 HTML 页面。

工具与工作流解耦:每种模式下你可自选启用哪些工具、用几个、或完全不用;流程负责推理节奏,工具由你编排。

从快速聊天起步,难题切到深度解题,可视化一个概念,自测用测验,再开深度研究深挖 —— 同一条对话线贯穿始终。

✍️ Co-Writer — 多文档 AI 写作工作区

Co-Writer

Co-Writer 把聊天的智能放进写作界面:创建和管理多份文档,各自独立持久化 —— 不是一次性草稿纸,而是完整的多文档 Markdown 编辑器,AI 是一等协作者

划选文本即可改写扩写精简,可选用知识库或网络上下文;支持撤销/重做,作品可存入笔记本,回流学习生态。

📖 Book Engine — 交互式「活书」

书库阅读器动画

给 DeepTutor 一个主题,指向你的知识库,即可产出一本结构化、可交互的书 —— 不是静态导出物,而是你可以阅读、自测、并在上下文中讨论的活文档。

幕后由多智能体流水线驱动:提案大纲、知识库深度检索、章节树合成、页面规划、逐块编译。你始终掌控全局 —— 审阅提案、拖拽调整章节、在任意页面旁聊天。

页面由 14 种块类型拼装:文本、提示、测验、闪卡、代码、图表、深入解读、动画、交互演示、时间线、概念图、章节、用户笔记与占位符 —— 每种都有专属交互组件。实时进度时间线让你见证编译过程。

📚 知识管理 — 学习基础设施

知识管理

在此构建与管理驱动全局的文档集合、笔记与教学人设。

  • 知识库 — 上传 PDF、TXT、Markdown,形成可检索、RAG 就绪的集合;可增量追加。
  • 笔记本 — 跨会话整理学习记录;聊天、Co-Writer、Book、深度研究的洞见可按色分类保存。
  • 题库 — 浏览并回顾所有生成的测验题目;可收藏,并在聊天中 @-引用以回顾历史表现。
  • Skills — 通过 SKILL.md 创建自定义教学人设:定义名称、描述、可选触发词与 Markdown 正文,激活后注入聊天系统提示 —— 让 DeepTutor 变身苏格拉底导师、同伴学习者、科研助手或你设计的任何角色。

知识库不是冷存储 —— 它主动参与每次对话、研究与学习路径。

🧠 记忆 — 与你一同成长

记忆

DeepTutor 从两个互补维度持续理解你:

  • 摘要 — 学习进度流水账:学过什么、探索过哪些主题、理解如何演进。
  • 学习画像 — 学习者身份:偏好、水平、目标与沟通风格,随交互自动精炼。

记忆在全功能与 TutorBot 间共享;用得越多,越贴合你。


🦞 TutorBot — 持久、自主的 AI 导师

TutorBot 架构

TutorBot 不是聊天机器人 —— 它是基于 nanobot持久、可多实例智能体。每个实例独立循环、工作区、记忆与人格;你可同时运行多个角色,各自演进。

TutorBot
  • Soul 模板 — 通过可编辑 Soul 文件定义人格、语气与教学理念;可选内置原型或完全自定义。
  • 独立工作区 — 每实例独立目录:记忆、会话、技能与配置隔离,仍可访问 DeepTutor 共享知识层。
  • 主动心跳 — 不止被动回复:心跳系统支持定期学习提醒、复习与计划任务。
  • 完整工具 — RAG、代码执行、联网、论文检索、深度推理、头脑风暴。
  • 技能扩展 — 在工作区添加技能文件即可教会新能力。
  • 多通道 — 可接 Telegram、Discord、Slack、飞书、企业微信、钉钉、邮件等。
  • 团队与子智能体 — 后台子任务或多智能体协作,应对长程复杂任务。
deeptutor bot create math-tutor --persona "Socratic math teacher who uses probing questions"
deeptutor bot create writing-coach --persona "Patient, detail-oriented writing mentor"
deeptutor bot list                  # 查看所有导师实例

⌨️ DeepTutor CLI — 智能体原生界面

DeepTutor CLI 架构

DeepTutor 全面 CLI 化:能力、知识库、会话、记忆、TutorBot 均可命令行操作,无需浏览器。终端 Rich 输出面向人类,JSON 面向智能体与流水线。

将项目根目录 SKILL.md 交给任意支持工具的代理(nanobot 或其他 LLM),即可自主配置与操作。

单次执行 — 终端直接跑任意能力:

deeptutor run chat "Explain the Fourier transform" -t rag --kb textbook
deeptutor run deep_solve "Prove that √2 is irrational" -t reason
deeptutor run deep_question "Linear algebra" --config num_questions=5
deeptutor run deep_research "Attention mechanisms in transformers"
deeptutor run visualize "Draw the architecture of a transformer"

交互 REPL — 持久会话,运行时切换模式:

deeptutor chat --capability deep_solve --kb my-kb
# 在 REPL 内:/cap、/tool、/kb、/history、/notebook、/config 可随时切换

知识库闭环 — 终端完成建库、追加与检索:

deeptutor kb create my-kb --doc textbook.pdf
deeptutor kb add my-kb --docs-dir ./papers/
deeptutor kb search my-kb "gradient descent"
deeptutor kb set-default my-kb

双输出模式 — Rich 给人看,JSON 给管道:

deeptutor run chat "Summarize chapter 3" -f rich
deeptutor run chat "Summarize chapter 3" -f json

会话续接 — 断点续聊:

deeptutor session list
deeptutor session open <id>
CLI 命令参考(完整)

顶层

命令 说明
deeptutor run <capability> <message> 单次执行能力(chatdeep_solvedeep_questiondeep_researchmath_animatorvisualize
deeptutor chat 交互 REPL,可选 --capability--tool--kb--language
deeptutor serve 启动 API 服务

deeptutor bot

命令 说明
deeptutor bot list 列出 TutorBot
deeptutor bot create <id> 创建并启动(--name--persona--model
deeptutor bot start <id> 启动
deeptutor bot stop <id> 停止

deeptutor kb

命令 说明
deeptutor kb list 列出知识库
deeptutor kb info <name> 详情
deeptutor kb create <name> 从文档创建(--doc--docs-dir
deeptutor kb add <name> 增量添加
deeptutor kb search <name> <query> 检索
deeptutor kb set-default <name> 设为默认
deeptutor kb delete <name> 删除(--force

deeptutor memory

命令 说明
deeptutor memory show [file] 查看(summaryprofileall
deeptutor memory clear [file] 清空(--force

deeptutor session

命令 说明
deeptutor session list 列表(--limit
deeptutor session show <id> 消息
deeptutor session open <id> REPL 续聊
deeptutor session rename <id> 重命名(--title
deeptutor session delete <id> 删除

deeptutor notebook

命令 说明
deeptutor notebook list 列表
deeptutor notebook create <name> 创建(--description
deeptutor notebook show <id> 记录
deeptutor notebook add-md <id> <path> 导入 Markdown
deeptutor notebook replace-md <id> <rec> <path> 替换记录
deeptutor notebook remove-record <id> <rec> 删除记录

deeptutor book

命令 说明
deeptutor book list 列出工作区中的所有书
deeptutor book health <book_id> 检查知识库偏移与书的健康状态
deeptutor book refresh-fingerprints <book_id> 刷新知识库指纹并清理过期页面

deeptutor config / plugin / provider

命令 说明
deeptutor config show 配置摘要
deeptutor plugin list 已注册工具与能力
deeptutor plugin info <name> 工具或能力详情
deeptutor provider login <provider> OAuth(openai-codexgithub-copilot

🗺️ 路线图

状态 里程碑
🎯 身份认证与登录 — 面向公网部署的可选登录页与多用户支持
🎯 主题与外观 — 多种主题与可定制界面
🎯 交互体验优化 — 优化图标设计与交互细节
🔜 更强记忆 — 集成更完善的记忆管理
🔜 LightRAG 集成 — 将 LightRAG 作为高阶知识库引擎接入
🔜 文档站点 — 含指南、API 参考与教程的完整文档站

若 DeepTutor 对你有帮助,欢迎 点亮 Star,这对我们是很大的鼓励!


🌐 社区与生态

DeepTutor 受益于优秀开源项目:

项目 在 DeepTutor 中的角色
nanobot 驱动 TutorBot 的轻量智能体引擎
LlamaIndex RAG 与文档索引骨干
ManimCat 数学动画(Math Animator)的 AI 生成

HKUDS 生态:

⚡ LightRAG 🤖 AutoAgent 🔬 AI-Researcher 🧬 nanobot
简洁高速 RAG 零代码智能体框架 自动化研究 超轻量 AI 智能体

🤝 参与贡献

希望 DeepTutor 能成为送给社区的一份礼物。🎁

Contributors

请参阅 CONTRIBUTING.md 了解开发环境、规范与 PR 流程。

⭐ Star 历史

Star History Rank