# DeepTutor：终身个性化辅导

[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/) [![Next.js 16](https://img.shields.io/badge/Next.js-16-000000?style=flat-square&logo=next.js&logoColor=white)](https://nextjs.org/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](LICENSE) [![GitHub release](https://img.shields.io/github/v/release/HKUDS/DeepTutor?style=flat-square&color=brightgreen)](https://github.com/HKUDS/DeepTutor/releases) [![arXiv](https://img.shields.io/badge/arXiv-2604.26962-b31b1b?style=flat-square&logo=arxiv&logoColor=white)](https://arxiv.org/abs/2604.26962) [![Discord](https://img.shields.io/badge/Discord-社区-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/eRsjPgMU4t) [![Feishu](https://img.shields.io/badge/飞书-交流群-00D4AA?style=flat-square&logo=feishu&logoColor=white)](./Communication.md) [![WeChat](https://img.shields.io/badge/微信-交流群-07C160?style=flat-square&logo=wechat&logoColor=white)](https://github.com/HKUDS/DeepTutor/issues/78) [核心功能](#-核心功能) · [快速开始](#-快速开始) · [功能探索](#-探索-deeptutor) · [CLI 命令行](#️-deeptutor-cli--智能体原生界面) · [生态系统](#-生态系统--eduhub-与技能社区) · [社区](#-社区)

--- > 🤝 **欢迎各种形式的贡献！** 在 [`路线图`](https://github.com/HKUDS/DeepTutor/issues/498) 为议题投票或提出新建议，详见 [贡献指南](CONTRIBUTING.md)，了解分支策略、编码规范及参与方式。 ### 📰 新闻动态 - **2026-05-22** 🌐 官方文档站点上线 [**deeptutor.info**](https://deeptutor.info/) — 指南、参考文档与能力演示一站汇聚。 - **2026-04-19** 🎉 111 天突破 2 万 Star！感谢大家对真正个性化智能辅导的支持。 - **2026-04-10** 📄 论文已发布于 arXiv — 阅读 [预印本](https://arxiv.org/abs/2604.26962)，了解 DeepTutor 的设计理念与背后的思考。 - **2026-02-06** 🚀 仅 39 天突破 1 万 Star！衷心感谢我们出色的社区。 - **2026-01-01** 🎊 新年快乐！加入我们的 [Discord](https://discord.gg/eRsjPgMU4t)、[微信群](https://github.com/HKUDS/DeepTutor/issues/78) 或 [Discussions](https://github.com/HKUDS/DeepTutor/discussions) — 一起塑造 DeepTutor 的未来。 - **2025-12-29** 🎓 DeepTutor 正式发布！ ## ✨ 核心功能 DeepTutor 是一个智能体原生的学习工作区，将辅导、解题、测验生成、研究、可视化和掌握度练习整合在一个可扩展的系统中。 - **统一的运行时** — Chat、Quiz、Research、Visualize、Solve 和 Mastery Path 运行在同一个智能体循环上，切换的是目标，而非引擎，上下文始终随学习者流转。 - **互联的学习上下文** — 知识库、书籍、Co-Writer 草稿、笔记本、题库、人格预设和 Memory，在每个工作流中始终可用，而不是各自孤立。 - **子智能体与 Partners** — 在任意对话轮次中调用实时运行的编程 CLI（Claude Code、Codex、Gemini、Kimi、opencode 或 MiMo）或 Partner（或导入其历史对话），并在同一大脑上运行持久化的 IM 伴侣。 - **多引擎知识库** — 跨 LlamaIndex、PageIndex、GraphRAG、LightRAG 或链接的 Obsidian vault 的版本化 RAG 知识库，支持可插拔的文档解析。 - **可扩展工具与技能** — 内置工具、MCP 服务器、CLI 应用、图像 / 视频 / 语音生成模型，以及从 EduHub 安装的社区技能。 - **可审计的记忆** — L1 追踪、L2 表面摘要和 L3 综合让个性化透明可编辑，Memory Graph 将每一条结论追溯到其原始证据。 --- ## 🚀 快速开始 DeepTutor 提供四种安装方式，共享同一个工作区布局：设置存储在启动目录下的 `data/user/settings/`（或通过 `DEEPTUTOR_HOME` / `deeptutor start --home` 指定的位置）。完整应用的推荐流程为：**选择工作目录 → 安装 → `deeptutor init` → `deeptutor start`**。

方式一 — 从 PyPI 安装 · 完整本地 Web 应用 + CLI，无需克隆仓库

完整本地 Web 应用 + CLI，无需克隆仓库。需要 **Python 3.11–3.13** 以及 PATH 中的 **Node.js 20+** 运行时（打包的 Next.js 独立服务器由 `deeptutor start` 启动）。 ```bash mkdir -p my-deeptutor && cd my-deeptutor pip install -U deeptutor deeptutor init # 提示配置端口 + LLM 提供商 + 可选嵌入 deeptutor start # 启动后端 + 前端；保持终端窗口打开 ``` `deeptutor init` 会提示配置后端端口（默认 `8001`）、前端端口（默认 `3782`）、LLM 提供商 / 基础 URL / API Key / 模型，以及可选的知识库 / RAG 嵌入提供商。 `deeptutor start` 完成后，打开终端打印的前端 URL — 默认为 [http://127.0.0.1:3782](http://127.0.0.1:3782)。在该终端按 `Ctrl+C` 可同时停止后端和前端。跳过 `deeptutor init` 也可用于快速体验；应用会以默认端口和空模型设置启动，稍后在 **Settings → Models** 中配置即可。

方式二 — 从源码安装 · 基于代码仓库进行开发

适用于基于代码仓库的开发。使用 **Python 3.11–3.13** 和 **Node.js 22 LTS** 以匹配 CI 和 Docker 环境。 ```bash git clone https://github.com/HKUDS/DeepTutor.git cd DeepTutor # 创建 venv（macOS/Linux）。Windows PowerShell： # py -3.11 -m venv .venv ; .\.venv\Scripts\Activate.ps1 python3 -m venv .venv && source .venv/bin/activate python -m pip install --upgrade pip # 安装后端 + 前端依赖 python -m pip install -e . ( cd web && npm ci --legacy-peer-deps ) deeptutor init deeptutor start ``` 源码安装会以开发模式运行 Next.js，指向本地 `web/` 目录；其他所有内容（配置布局、端口、`Ctrl+C` 停止）与方式一相同。

Conda 环境（替代 venv）

```bash conda create -n deeptutor python=3.11 conda activate deeptutor python -m pip install --upgrade pip ```

可选安装额外依赖 — dev / partners / matrix / math-animator

```bash pip install -e ".[dev]" # 测试/代码检查工具 pip install -e ".[partners]" # Partner IM 渠道 SDK + MCP 客户端 pip install -e ".[matrix]" # Matrix 渠道（不含 E2EE/libolm） pip install -e ".[matrix-e2e]" # Matrix E2EE；需要 libolm pip install -e ".[math-animator]" # Manim 插件；需要 LaTeX/ffmpeg/系统库 ```

前端依赖调整与开发服务器故障排查

**修改前端依赖：** 运行 `npm install --legacy-peer-deps` 以刷新 `web/package-lock.json`，然后同时提交 `web/package.json` 和 `web/package-lock.json`。 **开发服务器卡住：** 如果 `deeptutor start` 报告有已存在但无响应的前端进程，停止它打印的 PID。如果实际上没有 Next.js 进程在运行，则锁文件已过时 — 删除后重试： ```bash rm -f web/.next/dev/lock web/.next/lock deeptutor start ```

方式三 — Docker · 单一自包含容器

单容器运行完整 Web 应用。镜像托管在 GitHub Container Registry： - `ghcr.io/hkuds/deeptutor:latest` — 稳定版本 - `ghcr.io/hkuds/deeptutor:pre` — 预发布版本（如有） > 有关 podman / 无根容器 / 只读根文件系统部署及完整的每种安装指南，请参阅 [CONTAINERIZATION.md](./CONTAINERIZATION.md)。 ```bash docker run --rm --name deeptutor \ -p 127.0.0.1:3782:3782 \ -v deeptutor-data:/app/data \ ghcr.io/hkuds/deeptutor:latest ``` > **只需发布 `3782` 端口。** 浏览器只与前端源通信；Next.js 中间件（`web/proxy.ts`）在**容器内部**将 `/api/*` 和 `/ws/*` 转发给 FastAPI 后端。发布 `8001`（`-p 127.0.0.1:8001:8001`）是可选的 — 仅在需要用 curl 或脚本直接访问 API 时才有用。打开 [http://127.0.0.1:3782](http://127.0.0.1:3782)。容器首次启动时会创建 `/app/data/user/settings/*.json`；通过 Web Settings 页面配置模型提供商。配置、API Key、日志、工作区文件、记忆和知识库均持久化在 `deeptutor-data` 卷中。 - **不同宿主机端口：** 修改每个 `-p host:container` 映射的左侧（例如 `-p 127.0.0.1:8088:3782`）。如果修改了 `/app/data/user/settings/system.json` 中容器侧的端口，重启并更新映射右侧以匹配。 - **后台运行：** 添加 `-d`，然后用 `docker logs -f deeptutor` 查看日志，`docker stop deeptutor` 停止，重用名称前执行 `docker rm deeptutor`。`deeptutor-data` 卷在重启之间保留设置和工作区。 **远程 Docker / 反向代理：** 浏览器只与前端源（`:3782`）通信；容器内的 Next.js 中间件在服务端将 `/api/*` 和 `/ws/*` 转发给后端服务器。对于常见的单容器场景，完全不需要配置 API base — 只需将反向代理 / TLS 终止器指向 `:3782` 即可。只有在**拆分部署**（后端在独立容器/主机上）时才需要设置 API base：将 `data/user/settings/system.json` 中的 `next_public_api_base` 设置为前端服务器用于访问后端的内网地址（它在服务端读取，永远不会发送到浏览器）。 ```json { "next_public_api_base": "http://backend:8001" } ``` `next_public_api_base_external`（及其别名 `public_api_base`）作为低优先级的备用配置被接受。CORS 使用前端**来源**，而非 API URL。禁用认证时，DeepTutor 默认允许普通 HTTP/HTTPS 浏览器来源。启用认证时，需添加精确的前端来源： ```json { "cors_origins": ["https://deeptutor.example.com"] } ```

连接宿主机上的 Ollama / LM Studio / llama.cpp / vLLM / Lemonade

在 Docker 内部，`localhost` 指容器本身，而非宿主机。要连接宿主机上的模型服务，使用宿主机网关（推荐）： ```bash docker run --rm --name deeptutor \ -p 127.0.0.1:3782:3782 -p 127.0.0.1:8001:8001 \ --add-host=host.docker.internal:host-gateway \ -v deeptutor-data:/app/data \ ghcr.io/hkuds/deeptutor:latest ``` 然后在 **Settings → Models** 中，将提供商 Base URL 指向 `host.docker.internal`： - Ollama LLM: `http://host.docker.internal:11434/v1` - Ollama 嵌入: `http://host.docker.internal:11434/api/embed` - LM Studio: `http://host.docker.internal:1234/v1` - llama.cpp: `http://host.docker.internal:8080/v1` - Lemonade: `http://host.docker.internal:13305/api/v1` Docker Desktop（macOS/Windows）通常无需 `--add-host` 即可解析 `host.docker.internal`。在 Linux 上，该标志是在现代 Docker Engine 上创建该主机名的便携方式。 **Linux 替代方案 — 宿主机网络：** 添加 `--network=host` 并去掉 `-p` 标志。容器直接共享宿主机网络，打开 [http://127.0.0.1:3782](http://127.0.0.1:3782)（或 `system.json` 中的 `frontend_port`），宿主机服务可通过普通 localhost URL（如 `http://127.0.0.1:11434/v1`）访问。注意宿主机网络会将容器端口直接暴露在宿主机上，可能与现有服务冲突 — 若需保持在回环地址上，可设置 `BACKEND_HOST=127.0.0.1` 和 `FRONTEND_HOST=127.0.0.1`（详见 [CONTAINERIZATION.md](./CONTAINERIZATION.md)）。

方式四 — 仅 CLI · 无 Web UI，基于源码安装

当不需要 Web UI 时使用。仅 CLI 包从源码安装，不从 PyPI 安装。 ```bash git clone https://github.com/HKUDS/DeepTutor.git cd DeepTutor # 创建 venv（macOS/Linux）。Windows PowerShell： # py -3.11 -m venv .venv-cli ; .\.venv-cli\Scripts\Activate.ps1 python3 -m venv .venv-cli && source .venv-cli/bin/activate python -m pip install --upgrade pip python -m pip install -e ./packaging/deeptutor-cli deeptutor init --cli deeptutor chat ``` `deeptutor init --cli` 与完整应用共享同一 `data/user/settings/` 布局，但跳过后端/前端端口提示，并默认将嵌入设为**关闭**（如计划使用 `deeptutor kb …` 或 RAG 工具，选择 `Yes`）。它仍会写入完整的运行时布局（`system.json`、`auth.json`、`integrations.json`、`model_catalog.json`、`main.yaml`、`agents.yaml`），并提示选择活跃的 LLM 提供商和模型。

常用命令

```bash deeptutor chat # 交互式 REPL deeptutor chat --capability deep_solve --tool rag --kb my-kb deeptutor run chat "解释傅里叶变换" deeptutor run deep_solve "Solve x^2 = 4" --tool rag --kb my-kb deeptutor kb create my-kb --doc textbook.pdf deeptutor memory show deeptutor config show ```

本地 `deeptutor-cli` 安装不包含 Web 资产或服务器依赖。请保留源码仓库 — 可编辑安装指向它。若之后需要添加 Web 应用，从同一工作区安装 PyPI 包（方式一），并运行 `deeptutor init` + `deeptutor start`。

代码执行沙箱（Office 技能） · 运行 docx / pdf / pptx / xlsx 的模型生成代码

内置的 Office 技能 — **docx / pdf / pptx / xlsx** — 通过让模型编写短 Python 脚本（`python-docx`、`reportlab`、`openpyxl` 等），经 `exec` / `code_execution` 工具运行，并返回下载 URL 来工作。这些工具在沙箱后端激活时自动挂载，在每种部署形式下**默认**均已激活： - **本地（方式一 / 二）和 Docker（方式三，单容器）：** 受限子进程沙箱运行模型代码（本地在宿主机上，Docker 在容器内部 — 容器本身即隔离边界）。 - **docker-compose：** 通过 `DEEPTUTOR_SANDBOX_RUNNER_URL` 路由至加固的最小权限**运行器 sidecar**（`Dockerfile.runner`） — 安全性最强，有 sidecar 时自动优先使用。子进程沙箱由 `data/user/settings/system.json` 中的 `sandbox_allow_subprocess` 设置控制（默认 `true`）。在宿主机上运行模型生成的代码是一个真实的信任决策 — 将其设为 `false`（或导出 `DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=0`）可禁用宿主机侧执行，代价是 Office 技能将无法生成文件。

配置参考 — data/user/settings/ 下的配置文件（JSON/YAML）

`data/user/settings/` 下的所有内容均为纯 JSON/YAML 格式。推荐使用浏览器中的 **Settings** 页面进行编辑。 | 文件 | 用途 | |:---|:---| | `model_catalog.json` | LLM、嵌入和搜索提供商配置；API Key；活跃模型 | | `system.json` | 后端/前端端口、公开 API 基础地址、CORS、SSL 校验、附件目录及上传/提取限制 | | `auth.json` | 可选认证开关、用户名、密码哈希、token/cookie 设置 | | `integrations.json` | 可选的 PocketBase 和 sidecar 集成设置 | | `interface.json` | UI 语言 / 主题 / 侧边栏偏好 | | `main.yaml` | 运行时行为默认值和路径注入 | | `agents.yaml` | 能力/工具的 temperature 和 token 设置 | 项目根目录的 `.env` **不会**作为应用配置文件被读取。最简模型配置：打开 **Settings → Models**，添加 LLM 配置（Base URL / API Key / 模型名称），然后保存。仅在计划使用知识库 / RAG 功能时才需要添加嵌入配置。

## 📖 探索 DeepTutor 从日常使用的主要界面开始：Chat、Partners、My Agents、Co-Writer、Book、知识中心、学习空间、Memory 和 Settings。之后将介绍用于共享隔离工作区的多用户部署。

🏗️ 系统架构

💬 Chat — 真正好用的智能体循环

Chat 是默认能力，也是大多数工作的起点。单个对话线程可以正常交流、调用工具、基于选定知识库进行检索、读取附件、生成图像、调用子智能体、写入笔记本记录，并在多轮对话中保持相同的上下文。

循环设计刻意保持简单：模型按轮次思考，在有用时调用工具，观察结果，最终以不调用工具的消息结束。`ask_user` 是特殊工具 — 智能体不是凭空猜测，而是可以暂停当前轮次，提出结构化的澄清问题，在你回答后恢复。

用户可切换的工具有 `brainstorm`、`web_search`、`paper_search`、`reason` 和 `geogebra_analysis` — 配置了对应生成模型后还有 `imagegen` 和 `videogen`。上下文工具如 `rag`、`kb_files`、`read_source`、`read_memory`、`write_memory`、`read_skill`、`load_tools`、`exec`、`web_fetch`、`ask_user`、`list_notebook`、`write_note`、`github` 和 `consult_subagent` 会在当前轮次具备相应上下文时自动挂载。上下文分为两类：**粘性会话上下文**（子智能体、知识库、人格预设、模型、语音）存在于编辑器工具栏，在各轮次间持续保留；**一次性引用**（文件、聊天历史、书籍、笔记本、题库、导入的智能体）通过 `+` 菜单添加，仅用于单次对话轮次。 Chat 也是进入更深层能力的入口：**Quiz** 用于题目生成，**Research** 用于带引用的报告，**Visualize** 用于图表 / 示意图 / 动画，以及 *更多能力* 下的 **Solve**（有步骤的推理）和 **Mastery Path**（学习计划流程）。

🤝 Partner — 运行在同一大脑上的持久伴侣

Partners 是拥有独立灵魂、模型策略、知识库、记忆和渠道的持久伴侣。它们不是独立的机器人引擎：每条入站的 Web 或 IM 消息都会成为在 Partner 作用域工作区内的一次普通 `ChatOrchestrator` 对话轮次。Partner 就是"一个有个性和电话号码的聊天"。

每个 Partner 拥有 `SOUL.md`、模型选择、渠道、工具策略和分配的知识库。知识库、技能和笔记本会被复制到 `data/partners//workspace/`，因此相同的 RAG、技能、笔记本和记忆工具无需特殊处理即可正常工作。Partner 可以读取其拥有者的记忆，但只能写入自己的记忆。

渠道层基于 Schema 驱动，根据已安装的额外依赖和配置的凭证，可连接飞书、Telegram、Slack、Discord、钉钉、QQ/NapCat、企业微信、WhatsApp、Zulip、Mattermost、Matrix、Mochat 和 Microsoft Teams 等 IM 平台。Partner 也可以作为子智能体连接，并从普通聊天轮次中调用 — 详见下方的**我的智能体**。

🧑‍🚀 我的智能体 — 调用与导入其他智能体

"我的智能体"将其他智能体转化为 DeepTutor 的上下文，具备两种不同的功能。**连接实时智能体** — 连接你机器上的 Claude Code、Codex、Gemini、Kimi、opencode 或 MiMo Code CLI，或你的某个 Partner，在聊天轮次中调用它：DeepTutor 实际上会*运行*另一个智能体，并通过 `consult_subagent` 工具将其工作流式传输到 Activity 面板。通过智能体选项（或输入 `@`）选择它，并设置调用可进行的最大轮数。

**导入历史对话** — 将已有的 Claude Code 和 Codex 历史记录作为命名的、可搜索的、可续聊的智能体导入。选择要导入的日期范围；刷新时自动重新同步。通过 `+` → 我的智能体在任意聊天轮次中引用已导入的对话，DeepTutor 会将其作为第三方对话记录读取 — 它始终是*对方的*对话，不会被 DeepTutor 以自己的口吻解读。

✍️ Co-Writer — 感知选区的 Markdown 写作台

Co-Writer 是一个分屏 Markdown 工作区，适用于报告、教程、笔记和长篇学习素材的创作。文档自动保存并实时渲染预览（KaTeX 数学公式、图表围栏），草稿完成后可保存回笔记本成为可复用的上下文。

其核心理念是**精准编辑**：选中一段文字，让 DeepTutor 对其进行改写、扩展或缩短。编辑智能体可以基于知识库或网络证据进行修改，保留工具调用追踪，并以接受/拒绝差异对比的形式展示每处变更 — 直到你批准后才会生效。

📖 Book — 从你的素材生成活书

Book 将选定的来源转化为交互式**活书** — 不是静态 PDF，而是由类型化块构建的阅读环境。书籍可以从知识库、笔记本、题库或聊天历史开始创建；创建流程会在内容生成前提出章节大纲，让你审查结构，而不是被动接受一次性的盲目输出。

Book 测验块 Book Manim 动画块 Book 交互式组件块

每章编译为类型化块 — 文本、标注、测验、闪卡、时间轴、代码、图形、交互式 HTML、动画、概念图、深度解析和用户笔记 — 每页都有独立的 Page Chat。块可编辑：插入、移动、重新生成或切换块类型，无需重写整章。维护命令如 `deeptutor book health` 和 `deeptutor book refresh-fingerprints` 有助于检测来源知识库与已编译页面的漂移情况。

📚 知识中心 — 多引擎 RAG 知识库

知识库是 RAG 背后的文档集合 — 为 Chat 对话、Co-Writer 编辑、Book 生成和 Partner 对话提供依据。其独特之处在于**检索引擎的选择**：**LlamaIndex**（默认，本地向量 + BM25）、**PageIndex**（托管，支持页面级引用的推理检索）、**GraphRAG** 和 **LightRAG**（知识图谱检索）、**LightRAG Server**（将检索卸载至你通过 HTTP 连接的外部 LightRAG 实例）、**Tencent IMA**（在 IMA 中维护的知识库，通过其 OpenAPI 进行检索），或直接在原位读写的链接 **Obsidian** vault。每个 KB 绑定到单一引擎。

创建 KB 时，可以选择**新建**（上传文档并构建全新索引）或**链接已有**（复用在其他地方构建的索引，原位读取无需重新索引）。重新索引会写入新的平铺 `version-N` 目录并保留旧版本，因此重建过程中现有索引不会被破坏。即使知识库处于 **error** 状态，也可以单独移除其中一份文档 — 无需完整地删除重建，就能丢弃解析失败的文件。文档解析 — 纯文本、MinerU、Docling、markitdown 或 PyMuPDF4LLM — 在 **Settings → Knowledge Base** 中选择，本地模型下载默认关闭。CLI 通过 `deeptutor kb list`、`info`、`create`、`add`、`search`、`set-default` 和 `delete` 来管理完整生命周期。

🌐 学习空间 — 技能、人格预设与可复用上下文

学习空间是知识库和个性化层 — 持久化内容的存放之处。**对话与素材**保存聊天历史、笔记本和题库（每道保存的题目包含你的答案、参考答案和解析）。**个性化**保存掌握路径、人格预设（如*同伴*、*研究助手*、*教师*等行为预设）、技能（模型按需读取的 `SKILL.md` 剧本）、**MCP 服务** — 一键为自己安装的托管 MCP 服务器精选商店，外加通过 URL 配置的任意远程服务器 — 以及**CLI 应用**，即来自 [CLI-Anything](https://github.com/HKUDS/CLI-Anything) 目录、由聊天智能体直接调用的命令行工具，每个应用的使用指南按需加载。这里的所有内容均可在 Chat、Partners、Co-Writer 和 Book 中复用。

你不必自己编写每个技能 — **从 EduHub 导入**可浏览社区目录，通过安全门将技能直接下载到你的库中（详见[生态系统](#-生态系统--eduhub-与技能社区)）。

🧠 Memory — 可审计的个性化记忆

Memory 是一个基于文件、三层结构的系统，你可以读取、整理和审计它 — 刻意设计为*非*隐藏的向量库。**L1** 是工作区镜像加仅追加的事件追踪（`trace//.jsonl`）；**L2** 是按表面整理的事实（`L2/.md`）；**L3** 是跨表面的综合（`L3/.md`）。由于 L2 引用 L1，L3 引用 L2，你的档案中没有任何不可追溯的内容。

Memory Graph 展示整个金字塔 — L3 综合位于中心，L2 在中间圆环，L1 追踪在外圈 — 你可以将任何综合结论追溯到其背后的精确原始事件。Memory 在 `chat`、`notebook`、`quiz`、`kb`、`book`、partner 和 `cowriter` 表面进行追踪；整合器的更新 / 审计 / 去重预算可在 **Settings → Memory** 中调整。

⚙️ Settings — 统一的控制面板

Settings 是操作控制面板，带有实时状态条（后端、LLM、嵌入、搜索）和每个区域的配置卡：**外观**（主题、UI 语言、代码块样式）、**网络**（API 基础地址、端口、CORS）、**模型**（LLM、嵌入、搜索、文字转语音、语音转文字、图像生成、视频生成）、**知识库**（文档解析引擎）、**聊天**（工具、每个能力的参数、附件上限）、**Partners 与智能体**（可在对话轮次中调用的子智能体），以及**记忆**（整合器预算）。

大多数部分采用草稿-应用流程，因此你可以在提交前测试提供商配置。开箱即提供四种主题 — Default、Cream、Dark 和 Glass。项目根目录的 `.env` 文件被刻意忽略；运行时配置存储在 `data/user/settings/*.json` 下，除非 `DEEPTUTOR_HOME` 或 `deeptutor start --home` 将应用指向其他位置。 **OpenAI Codex OAuth（实验性）。** 在 **模型 → LLM** 下选择 **OpenAI Codex**，会用基于你自己 ChatGPT 订阅运行的浏览器登录取代 API Key 输入框，因此无需 `OPENAI_API_KEY`。令牌仅保存在 `data/system/user-secrets//private/openai-codex/` 中 — 位于 exec 沙箱可触及的所有目录树之外 — DeepTutor 绝不会读取或修改你的 `~/.codex` CLI 登录状态。模型列表来自该账号的实时目录；只有尚未配置任何 LLM 时，登录后的 Codex 才会成为活跃模型。令牌只授权一个人的订阅，无法通过用户授权共享，因此每个账号都需自行登录。远程部署时，浏览器的 `localhost` 和服务器的 `localhost` 不是同一台机器，仅有普通反向代理无法把浏览器的 localhost callback 送到服务器，必须用 SSH 隧道建立 callback 桥。隧道通向已发布的 Web 端口；Next.js 只把精确的 callback 路径改写到 public callback broker，broker 校验 `state` 后才路由到原 OAuth operation。callback listener 仍位于后端 loopback，不发布 `1455`/`1457`，并支持默认 Docker bridge 网络。 ```bash ssh -N -L 1455:127.0.0.1:3782 @ ``` 若 DeepTutor 显示 fallback callback 端口 `1457`，则使用： ```bash ssh -N -L 1457:127.0.0.1:3782 @ ``` 只运行与实际 callback 端口对应的其中一条命令，不能两条都运行。`3782` 只是示例 Web 端口：它是 DeepTutor 配置并作为 `callback_forward_port` 显示的 frontend/container 端口，不保证 SSH 主机的 `127.0.0.1` 正在监听同一端口。若 Docker/Podman 映射到不同宿主机端口，或反向代理监听不同端口，只替换 SSH 命令右侧的目标端口（上例中的 `3782`）为 SSH 主机 `127.0.0.1` 实际监听的 Web 端口；左侧 callback 端口仍保持 `1455` 或 `1457`。`` 是该 loopback 监听端口所在的 SSH 主机；若浏览器域名指向反向代理或负载均衡器，请替换为正确的 SSH 前端主机。 CLI 会先打印隧道命令，随后立即尝试打开浏览器。远程用户应先保持授权页打开但不要完成授权，在另一终端建立所显示的隧道，然后再继续授权。 localhost 检测存在边界：若 Web 本身已通过 SSH 或 IDE localhost 转发访问，浏览器无法判断服务器是远程的。对于当前 Web operation，应保持其授权页未完成，从该 operation 的 authorize URL 中读取 `redirect_uri`，确认 callback 是 `1455` 还是 `1457`，再把该本地端口通过第二条隧道转到实际 Web 端口。另一种方法是取消该 Web operation，再通过 CLI 启动一个新 operation；CLI 输出只属于新 operation，不能用于当前 Web operation。配额错误和目录获取失败会如实报告，绝不会回退到付费提供商。此兼容路径为实验性功能：上游接口可能发生变化。

👥 多用户 — 共享部署 · 可选认证，隔离的用户工作区

认证默认**关闭** — DeepTutor 以单用户模式运行。开启后，单个 `data/` 目录树可同时托管管理员工作区、隔离的用户工作区和 Partner 工作区： ```text data/ ├── user/ # 管理员工作区 + 全局设置 ├── users// # 用户作用域：聊天历史、记忆、笔记本、知识库 ├── partners//workspace/ # Partner（合成用户）作用域 ├── cli-apps/ # 已安装的 CLI 应用，以只读方式挂载进沙箱 └── system/ # auth · grants · audit · user-secrets/ (OAuth 令牌) ``` **第一个注册用户成为管理员**，拥有模型目录、提供商凭证、共享知识库、技能和用户授权的管理权。其他所有人获得隔离的工作区和删减版的 Settings 页面 — 管理员分配的模型、知识库和技能以作用域只读选项的形式出现，原始 API Key 不可见。 **启用方式：** 在 `data/user/settings/auth.json` 中开启认证，重启 `deeptutor start`，在 `/register` 注册第一个管理员，然后从 `/admin/users` 添加用户，并通过授权分配模型、知识库、技能、Partner、工具/MCP/CLI 应用策略和代码执行权限。 > PocketBase 仍为单用户集成 — 多用户部署时请将 `integrations.pocketbase_url` 留空，除非你已接入外部用户存储。

## ⌨️ DeepTutor CLI — 智能体原生界面一个 `deeptutor` 可执行文件，两种使用方式：供习惯在终端中工作的人使用的交互式 **REPL**，以及供将 DeepTutor 作为工具来驱动的其他智能体使用的结构化 **JSON** 输出。两种方式共享相同的能力、工具和知识库。

自己驱动

`deeptutor chat` 打开交互式 REPL；`deeptutor run ""` 执行单次对话并退出。两者共享相同的 `--capability`、`--tool`、`--kb` 和 `--config` 标志。 ```bash deeptutor chat # 交互式 REPL deeptutor chat --capability deep_solve --kb my-kb --tool rag deeptutor run chat "解释傅里叶变换" --tool rag --kb textbook deeptutor run deep_research "调研 2026 年 RAG 论文" \ --config mode=report --config depth=standard ``` Web 应用的所有功能在这里都有对应 — 知识库（`kb`）、会话（`session`）、Partners（`partner`）、技能（`skill`）、笔记本、记忆和配置。完整列表见下方。

让智能体驱动

DeepTutor 专为*被其他智能体操作*而设计。在任何 `run` 命令中添加 `--format json`，每个轮次将流式输出 **NDJSON — 每行一个事件**（`content`、`tool_call`、`tool_result`、`done` 等），每行带有其 `session_id` 标记。运行是无头安全的：无 TTY 时，`ask_user` 暂停会以空回复自动解决，而不是挂起。 ```bash # 单次执行，机器可读 deeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json # 在单个有状态会话中链接多轮 — 捕获 id 并复用 SID=$(deeptutor run deep_research "调研 2026 年 RAG 论文" \ --config mode=report --config depth=standard --format json \ | jq -r 'select(.type=="done").session_id') deeptutor run deep_question "就那篇调研测验我" --session "$SID" --format json ``` 仓库根目录附带 [`SKILL.md`](SKILL.md) — 约 150 行的交接文档，让任何支持工具调用的 LLM 一次性掌握所有接口。将其传递给 Claude Code、Codex 或 OpenCode（它们会自动读取 `SKILL.md`），或将 `deeptutor run` 包装为 LangChain / AutoGen 循环中的工具。完整示例：[Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/)。

命令参考

| 命令 | 说明 | |:---|:---| | `deeptutor init` | 为当前工作区创建或更新 `data/user/settings` | | `deeptutor start [--home PATH]` | 同时启动后端 + 前端 | | `deeptutor serve [--port PORT]` | 仅启动 FastAPI 后端 | | `deeptutor run ` | 运行单次能力对话（`chat`、`deep_solve`、`deep_question`、`deep_research`、`visualize`、`math_animator`、`mastery_path`）；添加 `--format json` 可获得 NDJSON 输出 | | `deeptutor chat` | 交互式 REPL，支持能力、工具、知识库、笔记本和历史控制 | | `deeptutor partner list/create/start/stop` | 管理 IM 连接的 Partners | | `deeptutor kb list/info/create/add/search/set-default/delete` | 管理 LlamaIndex 知识库 | | `deeptutor skill search/install/list/remove/login/logout/publish/update` | 管理技能、从 Hub 安装并发布自己的技能（默认 `eduhub:`，详见生态系统） | | `deeptutor memory show/clear` | 查看 L2/L3 记忆文档或清除 L1/全部记忆 | | `deeptutor session list/show/open/rename/delete` | 管理共享会话 | | `deeptutor notebook list/create/show/add-md/replace-md/remove-record` | 从 Markdown 文件管理笔记本 | | `deeptutor book list/health/refresh-fingerprints` | 查看书籍并刷新来源指纹 | | `deeptutor plugin list/info` | 查看已注册的工具和能力 | | `deeptutor config show` | 打印配置摘要 | | `deeptutor provider login ` | 提供商认证（`openai-codex` OAuth 登录；`github-copilot` 验证现有 Copilot 认证会话） |

仅 CLI 发行版

仅 CLI 包位于 `packaging/deeptutor-cli`。在此代码仓库中，从源码安装： ```bash python -m pip install -e ./packaging/deeptutor-cli ``` 尚未发布到 PyPI，因此[快速开始](#-快速开始)部分保留了源码安装路径。

## 🧩 生态系统 — EduHub 与技能社区 DeepTutor 技能使用开放的 **Agent-Skills** 格式 — 一个包含 `SKILL.md` 剧本（YAML frontmatter + Markdown）和可选参考文件的文件夹。该格式与 DeepTutor 无关，因此任何支持该格式的注册表都可以成为你的技能库来源。DeepTutor 内置了 **[EduHub](https://eduhub.deeptutor.info/)** — 我们自己的教育技能注册表 — 作为默认 Hub。

EduHub — DeepTutor 的技能生态

[**EduHub**](https://eduhub.deeptutor.info/) 是 DeepTutor 为分享教学导向的智能体技能而创建的社区 Hub — 苏格拉底式导师、闪卡生成器、作文反馈、考试蓝图、概念讲解器等。它内置于 DeepTutor，无需任何配置：裸 slug 或 `eduhub:` 前缀均可解析到它。 **查找与安装** — 在浏览器中，打开**学习空间 → 技能 → 从 EduHub 导入**，浏览目录并将技能直接下载到你的库中。从终端： ```bash deeptutor skill search "socratic tutor" # 在 EduHub（默认 Hub）中搜索 deeptutor skill install socratic-tutor # 获取 → 验证 → 注册 deeptutor skill install eduhub:socratic-tutor@1.2.0 # 指定 Hub 和版本 deeptutor skill list # 本地技能及其 Hub 来源 ``` **发布自己的技能** — 打包一个 `SKILL.md` 并分享给社区： ```bash deeptutor skill login # 浏览器登录 EduHub deeptutor skill publish ./my-skill # 交互式：选择分类 + 标签，然后上传 deeptutor skill update # 回滚或发布新版本 ``` EduHub 也是一个独立的、ClawHub 兼容的注册表，因此非 DeepTutor 的智能体（Claude Code、Codex 等）可以通过 `eduhub` CLI 直接使用它 — `npx eduhub install socratic-tutor`。

导入安全门

无论来源如何，每次导入在触及你的工作区之前都会经过**相同的安全门**： - 首先检查注册表的**安全验证结果** — 被标记的包将被拒绝，除非你传入 `--allow-unverified`； - 压缩包被防御性解压（防 zip-slip / zip-bomb）并经过文本/脚本**后缀白名单**过滤，因此二进制文件永远不会落入工作区； - frontmatter 被规范化并**去除** `always:`，因此下载的技能永远无法强制将自己注入每个系统提示； - 来源信息 — Hub、版本、验证结果和安装时间 — 被写入 `.hub-lock.json` 以供审计和更新。在多用户部署中，安装为管理员专属操作：新技能进入管理员目录，在授权分配前对其他用户不可见，管理员可以在推广前进行审核。

同样兼容 ClawHub

因为 DeepTutor 支持开放的 Agent-Skills 格式，**[ClawHub](https://clawhub.ai/)** 也是一等来源 — 它与 EduHub 并列内置。使用 Hub 前缀选择： ```bash deeptutor skill search "git release notes" --hub clawhub deeptutor skill install clawhub:git-release-notes@1.0.1 ``` 在 `settings/skill_hubs.json` 中添加更多注册表：`type: "clawhub"` 条目指向任何兼容的 HTTP API（EduHub 和 ClawHub 都支持），`type: "command"` 包装注册表自带的任何获取 CLI，`"default"` 选择用于裸 slug 的 Hub。所有这些来源都经过同一个导入安全门。

## 🌐 社区 ### 📮 联系方式 DeepTutor 是一个由 [HKUDS](https://github.com/HKUDS) 团队中的 [Bingxi Zhao](https://github.com/pancacake) 主导的开源项目，以**完全开源的形式**持续迭代，与社区共同构建。迄今为止，我们**没有**任何形式的付费在线产品。欢迎通过 **bingxizhao39@gmail.com** 联系我们，探讨想法或合作。 ### 🙏 致谢衷心感谢香港大学数据智能实验室主任 [**Chao Huang**](https://sites.google.com/view/chaoh) 的大力支持，以及 HKUDS 实验室同学们的热心相助 — 特别是 [**Jiahao Zhang**](https://github.com/zzhtx258)、[**Zirui Guo**](https://github.com/LarFii) 和 [**Xubin Ren**](https://github.com/Re-bin)。我们也对**开源社区**深表感激：你们的 Star、Issue、Pull Request 和讨论，每天都在塑造 DeepTutor。 DeepTutor 也站在众多优秀开源项目的肩膀上，它们给予了我们工具和灵感： | 项目 | 角色 / 启发 | |:---|:---| | [**LlamaIndex**](https://github.com/run-llama/llama_index) | RAG 流水线和文档索引基础 | | [**nanobot**](https://github.com/HKUDS/nanobot) | 驱动原版 TutorBot 的超轻量智能体引擎 *(HKUDS)* | | [**LightRAG**](https://github.com/HKUDS/LightRAG) | 简单快速的 RAG *(HKUDS)* | | [**AutoAgent**](https://github.com/HKUDS/AutoAgent) | 零代码智能体框架 *(HKUDS)* | | [**AI-Researcher**](https://github.com/HKUDS/AI-Researcher) | 自动化研究流水线 *(HKUDS)* | | [**OpenClaw**](https://github.com/openclaw/openclaw) | 支撑 ClawHub 的开放智能体网关与技能生态 | | [**Codex**](https://github.com/openai/codex) | 启发我们 CLI 工作流的智能体原生编程 CLI | | [**Claude Code**](https://github.com/anthropics/claude-code) | 启发 DeepTutor 智能体循环的智能体编程 CLI | | [**ManimCat**](https://github.com/Wing900/ManimCat) | Math Animator 的 AI 驱动数学动画生成 | ### 🗺️ 路线图与贡献我们希望 DeepTutor 持续迭代与进步 — 并最终成为我们回馈开源社区的礼物。我们的[**路线图**](https://github.com/HKUDS/DeepTutor/issues/498)持续更新；欢迎在那里为议题投票或提出新想法。如果你想贡献，请查看[**贡献指南**](CONTRIBUTING.md)，了解分支策略、编码规范及参与方式。

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

基于 [Apache License 2.0](LICENSE) 许可证。