# 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、Ask Questions、Quiz、Research、Visualize、Solve、Course Study、Mastery Path、Immersive Reading 和 Immersive Watching 共享同一套能力运行时与会话上下文，同时保留各自为特定用途设计的循环和流水线。 - **互联的学习上下文** — 知识库、书籍、Co-Writer 草稿、笔记本、题库、人格预设和 Memory 可在支持它们的工作流中复用，并受账号授权与学习策略约束。 - **沉浸式视频学习** — 粘贴 YouTube 链接，即可使用隐私增强的原生播放、同步字幕、基于时间戳的辅导和可续接的学习进度；管理员可以将播放切换到自托管的 Invidious 实例，无需重新构建素材。 - **子智能体与 Partners** — 在 Chat 中调用实时智能体运行框架（Claude Code、Codex、Antigravity、Kimi、opencode、MiMo、Hermes、OpenClaw 或 DeepSeek）或 Partner、导入历史对话，并让持久化 IM 伴侣运行在同一套大脑之上。 - **多引擎知识库** — 跨 LlamaIndex、PageIndex、GraphRAG、LightRAG、远程 LightRAG Server、自托管的 WeKnora 知识库、Tencent IMA 或 MarginNote 4 知识库，或链接的 Obsidian vault 的版本化 RAG 知识库，支持可插拔的文档解析。 - **可扩展工具与技能** — 内置工具、MCP 服务器、CLI 应用、图像 / 视频 / 语音生成模型，以及从 EduHub 安装的社区技能。 - **可审计的记忆** — L1 追踪、L2 表面摘要和 L3 综合让个性化透明可编辑；Memory Graph 将 L2 事实关联至 L1 证据，并将 L3 综合关联至参与的表面层。 --- ## 🚀 快速开始 DeepTutor 提供四种安装方式，四者共享同一套运行时主目录布局：私有设置存储在启动目录下的 `data/user/settings/` 中（如果显式指定了 `DEEPTUTOR_HOME` / `deeptutor start --home`，则存储在该位置）。完整应用的推荐流程为：**选定运行时主目录 → 安装 → `deeptutor init` → `deeptutor start`**。 ### 内容工作区 **内容工作区（Content Workspace）** 与 DeepTutor 的私有运行时主目录相互独立。它是智能体可以读取的文件夹，也是每个由智能体创建的文件、下载、代码运行结果、缓存和渲染产物存放的位置 — 全部置于按轮次划分的 `outputs////` 目录下。Settings、API Key、数据库、Memory 和内部应用状态均不在其中。未经配置时，内容工作区默认为 `/data/user/workspace`。本地 PyPI、CLI 和源码安装可以在 **Settings → Workspace** 中选择任意已存在且可读写的文件夹，或者： ```bash deeptutor workspace show deeptutor workspace set /absolute/path/to/my-folder deeptutor workspace reset ``` 每项能力都可以通过内置的 workspace 工具查看同一个文件夹。模型只会收到形如 `outputs/...` 的相对路径；当它使用 `workspace_present` 时，界面会渲染出一份可打开的、经过鉴权的快照。同样的相对路径在普通的 Markdown 链接或图片中也同样有效。之后修改源文件不会改变已经呈现过的快照。 `outputs/` 之外的执行是只读的。要把生成的文件复制到内容工作区内的其他位置，需要针对那个确切的源与目标显式确认一次**允许一次**。系统沙箱或 Docker runner 在可用时会强制执行这一边界；本地受限子进程回退方案在 Workspace 设置中会被标注为**尽力而为**。

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

完整本地 Web 应用 + CLI，无需克隆仓库。需要 **Python 3.11–3.14** 以及 PATH 中的 **Node.js 20+** 运行时（打包的 Next.js 独立服务器由 `deeptutor start` 启动）。 ```bash mkdir -p my-deeptutor && cd my-deeptutor pip install -U deeptutor deeptutor init # prompts for ports + LLM provider + optional embedding/search deeptutor start # starts backend + frontend; keep the terminal open ``` `deeptutor init` 会提示配置后端端口（默认 `8001`）、前端端口（默认 `3782`）、LLM 提供商 / 基础 URL / API Key / 模型、可选的知识库 / RAG 嵌入提供商，以及可选的 Web Search 搜索提供商。 `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.14** 和 **Node.js 22 LTS** 以匹配 CI 和 Docker 环境。 ```bash git clone https://github.com/HKUDS/DeepTutor.git cd DeepTutor # Create a 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 # Install backend + frontend deps python -m pip install -e . ( cd web && npm ci --legacy-peer-deps ) deeptutor init deeptutor start --dev ``` `deeptutor start` 会为本地 `web/` 前端构建一次生产版本并复用；`--dev` 则以热更新（HMR）方式运行 Next.js。配置布局、端口和 `Ctrl+C` 停止均与方式一相同。

Conda 环境（替代 venv）

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

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

```bash pip install -e ".[rag-lightrag]" # Built-in LightRAG engine (exact supported SDK) pip install -e ".[graphrag]" # Microsoft GraphRAG engine (Python 3.11–3.13) pip install -e ".[dev]" # tests/lint tools pip install -e ".[partners]" # Partner IM channel SDKs pip install -e ".[video-learning]" # compatibility extra; captions ship in the full/CLI installs pip install -e ".[matrix]" # Matrix channel without E2EE/libolm pip install -e ".[matrix-e2e]" # Matrix E2EE; requires libolm pip install -e ".[math-animator]" # Manim addon; requires LaTeX/ffmpeg/system libs ```

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

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

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

单容器运行完整 Web 应用。镜像托管在 GitHub Container Registry： - `ghcr.io/hkuds/deeptutor:latest` — 最新稳定版本 - `ghcr.io/hkuds/deeptutor:` — 不含前导 `v` 的精确版本（例如 `:1.6.3`）；预发布版本只会获得对应的版本标签 > 有关 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 ``` 要在容器启动时选定宿主机上的内容文件夹，将其挂载到固定的容器路径，并把 DeepTutor 锁定到该路径： ```bash mkdir -p "$PWD/deeptutor-workspace/outputs" docker run --rm --name deeptutor \ -p 127.0.0.1:3782:3782 \ -v deeptutor-data:/app/data \ -v "$PWD/deeptutor-workspace:/workspace" \ -e DEEPTUTOR_WORKSPACE_ROOT=/workspace \ -e DEEPTUTOR_WORKSPACE_ALLOWED_ROOTS=/workspace \ ghcr.io/hkuds/deeptutor:latest ``` 对于 Compose，在运行 `python scripts/docker_compose.py up -d` 前设置 `DEEPTUTOR_WORKSPACE_HOST=/absolute/host/folder`；省略时默认使用 `./data/user/workspace`。Docker 路径在启动时就已选定，因此在 Web Settings 页面中会显示为已锁定。 > **只需发布 `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` 卷中。若单独挂载了内容工作区，则会持久化在其宿主机路径下。可选的额外依赖应配置在部署层面，而不是在 shell 中临时安装：设置 `DEEPTUTOR_EXTRAS`（系统库则用 `DEEPTUTOR_APT_PACKAGES`），由此启动的每个容器都会重新应用这些依赖；而 `docker exec … pip install` 这类临时安装会在下一次 `compose down` 后丢失。 - **不同宿主机端口：** 修改每个 `-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 # Create a 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/` 布局，但跳过后端/前端端口提示。它仍会提供 Embedding 和 Search 选择器（不需要时选择 **Skip**），写入关键运行时文件（`system.json`、`auth.json`、`integrations.json`、`interface.json`、`model_catalog.json`、`main.yaml`、`agents.yaml`），并提示选择活跃的 LLM 提供商和模型。

常用命令

```bash deeptutor chat # interactive REPL deeptutor chat --capability deep_solve --tool rag --kb my-kb deeptutor run chat "Explain Fourier transform" 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` 工具运行，并呈现保存下来的工作区文件来完成工作。只要有沙箱后端处于激活状态，这些工具就会挂载。DeepTutor 按以下顺序选择已配置的最强后端： - **Runner sidecar：** `DEEPTUTOR_SANDBOX_RUNNER_URL` 将执行路由至 `Dockerfile.runner` 提供的加固最小权限服务。 - **Linux bubblewrap：** `bwrap` 可用时，由它隔离进程和文件。 - **受限子进程回退：** 本地和单容器安装仅在允许时使用此方案；在 Docker 下，容器仍构成另一层边界。 `data/user/settings/system.json` 中的 `sandbox_allow_subprocess` 设置（默认 `true`）只控制最后一种回退方案。将其设为 `false`（或导出 `DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=0`），可在没有 runner 或 `bwrap` 后端时拒绝子进程执行；它不会禁用这些更强的后端。

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

`data/user/settings/` 下的所有内容均为纯 JSON/YAML 格式。推荐使用浏览器中的 **Settings** 页面进行编辑。 | 文件 | 用途 | |:---|:---| | `model_catalog.json` | 提供商连接，以及 LLM、任务、嵌入、搜索、TTS、STT、图像和视频配置、凭证与活跃选择 | | `system.json` | 后端/前端端口、公开 API 基础地址、CORS、SSL 校验、附件目录及上传/提取限制 | | `auth.json` | 可选认证开关、用户名、密码哈希、token/cookie 设置 | | `integrations.json` | 可选的 PocketBase 和 sidecar 集成设置 | | `interface.json` | UI 语言与模型输出语言 / 主题 / 侧边栏偏好 | | `content_workspace.json` | 内容工作区的文件夹绑定与当前选中的工作区 | | `video_learning.json` | 默认的 YouTube/Invidious 播放提供商、Invidious 来源和可选的转录适配器 | | `main.yaml` | 运行时行为默认值和路径注入 | | `agents.yaml` | 能力/工具的 temperature 和 token 设置 | Web Search 引用默认经过过滤：只会展示公开的 `http`/`https` URL，且不允许嵌入凭证或使用异常端口。部署者可以在 `data/user/settings/system.json` 中添加面向教育场景的域名策略： ```json { "web_search_source_filtering": { "enabled": true, "blocked_domains": ["spam.example"], "trusted_domains": ["edu.cn", "arxiv.org"] } } ``` 当 `trusted_domains` 非空时，引用仅限这些域名及其子域；`blocked_domains` 始终拥有更高优先级。项目根目录的 `.env` **不会**作为应用配置文件被读取。最简模型配置：打开 **Settings → Models**，添加 LLM 配置（Base URL / API Key / 模型名称），然后保存。仅在计划使用知识库 / RAG 功能时才需要添加嵌入配置。如果提供商支持选择，LLM 和任务模型配置会提供 **API format** 设置。常规路由与回退请保留 `Auto`，也可选择 `OpenAI Chat Completions`、`OpenAI Responses` 或 `Anthropic Messages`；强制 Responses 模式仍会故障关闭。持久化字段为 `api_format`（`auto`、`openai_chat`、`openai_responses` 或 `anthropic`）；`wire_api` 是派生的兼容性状态。每个模型均可通过 `Auto` / `Supported` / `Not supported` 覆盖工具调用、图像输入、JSON 输出和推理控制。

卸载与清理

DeepTutor 将已安装的代码、私有运行时主目录与可选的内容工作区三者分开。默认情况下，运行时主目录就是你运行 `deeptutor init` / `deeptutor start` 的目录；`--home PATH` 或 `DEEPTUTOR_HOME` 可以覆盖该位置。私有应用状态位于该目录内的 `data` 子目录，因此启动横幅中以 `Workspace:` 开头的行会标明这个运行时位置。如果 **Settings → Workspace** 指向了另一个文件夹，请单独备份或移除那个内容文件夹；卸载 DeepTutor 并不会清除它，这是刻意的设计。 1. 停止应用。在运行 `deeptutor start` 的终端中按 `Ctrl+C`；若启动器通过 `--detach` 启动，则运行 `deeptutor stop [--home PATH]`。删除数据前，还应停止所有正在运行的 Partner 和后台 Docker 容器。 2. 只有在确实要清除所有本地状态时，才移除运行时数据。其中包括设置和 API Key、聊天历史、会话、Memory、Notebooks、Books、Reading 状态、Skills、Partners 状态、日志、Knowledge Bases、解析缓存、生成的产物以及打包的前端运行时缓存。先从启动横幅中复制精确的 `Workspace:` 路径，并确认其 `data` 子目录就是要处理的 DeepTutor 数据目录。如有任何内容之后可能还会用到，请先备份，再将这个精确目录移入操作系统的废纸篓/回收站。不要对相对路径或尚未解析的环境变量执行递归删除命令。 3. 移除已安装的软件包。根据发行版运行对应命令： ```bash python -m pip uninstall deeptutor python -m pip uninstall deeptutor-cli ``` 如果虚拟环境仅供 DeepTutor 使用，请通过环境管理器将其移除。对于源码安装，先退出该环境并离开源码目录，再在那个精确的代码仓库中运行 `git status --short`。只有确认其中没有无关文件或未提交工作后，才能将代码仓库移入废纸篓/回收站。 4. 对于 Docker 安装路径，请先检查确切的容器和命名卷，再执行移除。删除卷会永久清除由 Docker 管理的数据： ```bash docker ps -a --filter name=^/deeptutor$ docker volume inspect deeptutor-data docker rm -f deeptutor docker volume rm deeptutor-data ```

## 📖 探索 DeepTutor 从日常使用的主要界面开始：Chat、Partners、My Agents、Co-Writer、Book、知识中心、学习空间、Memory 和 Settings。之后将介绍用于共享隔离工作区的多用户部署。如果回答遗漏了先前的约束、引用了薄弱证据，或与选定素材不一致，请先按照 [`REASONING_SAFETY_CHECKLIST.md`](./REASONING_SAFETY_CHECKLIST.md) 收集诊断信息，再提交 Issue。

🏗️ 系统架构

💬 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`、`question_bank`、`github`、`consult_subagent`、`workspace_list`、`workspace_read`、`workspace_search`、`workspace_present` 和 `workspace_export` 会在当前轮次具备相应上下文时自动挂载。上下文分为两类：**粘性会话上下文**（能力、工作区或课程、工具、知识库、人格预设、模型，以及 Reading / Mastery 状态）会在各轮次间持续保留；**一次性引用**（文件、聊天历史、书籍、阅读章节、笔记本、题库、导入的智能体）通过 `+` 菜单添加，仅用于单次对话轮次。语音按钮只会转录当前消息。主页让 **Chat**、**Ask Questions**、**Quiz** 和 **Visualize** 一键可达；用于生成引用报告的 **Research**、用于展示完整推理过程的 **Solve** 和 **Immersive Watching** 位于 *更多能力* 之下。**Mastery Path** 和 **Immersive Reading** 是侧边栏中的专用工作区；Reading 还提供经过验证的可点击引用、已保存的引用与笔记、基于来源的朗读 / 学习指导 / 词汇 / 测验 / 翻译操作，以及笔记本摘录，而 Course Study 则保留其自身与课程绑定的上下文。

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

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

每个 Partner 拥有 `SOUL.md`、模型选择、渠道、工具策略和分配的知识库。知识库、技能和笔记本会被复制到 `data/partners//workspace/`，因此相同的 RAG、技能、笔记本和记忆工具无需特殊处理即可正常工作。经过认证的非管理员用户拥有私有的 Partner 会话和关系记忆，而 Partner 只读访问其个人记忆；管理员、群组和未绑定流量则使用共享的 Partner 作用域。

渠道层基于 Schema 驱动，根据已安装的额外依赖和配置的凭证，可连接飞书、Telegram、Slack、Discord、钉钉、QQ/NapCat、企业微信、WhatsApp、Zulip、Mattermost、Matrix、Mochat 和 Microsoft Teams 等 IM 平台。Partner 也可以作为子智能体连接，并从普通聊天轮次中调用 — 详见下方的**我的智能体**。为加快配置，Partner 渠道页面可以直接在浏览器中绘制二维码（而非依赖服务器日志）来创建飞书/Lark 应用或企业微信 AI 机器人，或扫码登录个人微信账号。飞书/Lark 会检测账号所属域名，并将扫码用户保存为初始允许的发送者。企业微信会保留已有的白名单，否则默认允许所有能触达机器人的用户使用，并显示明显的开放访问警告；如果某个平台的扫码协议发生变化，手动渠道配置表单仍然可用。

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

"我的智能体"将其他智能体转化为 DeepTutor 的上下文，具备两种不同的功能。**连接实时智能体** — 连接你机器上的 Claude Code、Codex、Antigravity、Kimi、opencode、MiMo Code、Hermes Agent、OpenClaw 或 DeepSeek Harness，或你的某个 Partner，在聊天轮次中调用它：DeepTutor 实际上会*运行*另一个智能体，并通过 `consult_subagent` 工具将其工作流式传输到 Activity 面板。使用 Agent 芯片选择智能体及其轮数上限，或通过 `@` 筛选同一份已连接智能体列表；所选配置会随会话保留。

**导入历史对话** — 将已有的 Claude Code 和 Codex 历史记录作为命名的、可搜索的、可续聊的智能体导入。Claude 历史按项目 / 工作目录选择，Codex 历史按日历日期选择；刷新会重新同步该范围并拉取新对话。在 Chat 轮次中通过 `+` → 我的智能体引用其中一段对话，DeepTutor 会将其作为第三方对话记录读取 — 它始终是*对方的*对话，而不是 DeepTutor 自己的口吻。

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

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

其核心理念是**精准编辑**：选中一段文字，让 DeepTutor 对其进行改写、扩展或缩短。编辑智能体可以基于知识库或网络证据进行修改，并保留工具调用追踪。如果智能体工作期间草稿未发生变化，结果会直接替换所选文本，并且仍可通过 **Undo** 撤销。

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

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

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

每章会编译为可编辑的类型化块 — 文本、标注、测验、闪卡、时间轴、代码、图形、交互式 HTML、动画、概念图、深度解析和用户笔记 — 并拥有自己的 Page Chat。你可以插入、移动、重新生成、改写或切换块类型；选中的段落会进入可审核的学习摘录收件箱。即使管理员将书籍共享为只读或协作编辑，每位读者的学习进度、书签、测验作答、学习摘录和 Page Chat 仍保持私有；共享书籍只能由管理员删除。任何书籍都可导出为 Markdown，长时间编译可暂停并恢复，`deeptutor book health` / `refresh-fingerprints` 会标记来源漂移。

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

知识库是 RAG 背后的文档集合 — 为 Chat 对话、Co-Writer 编辑、Book 生成和 Partner 对话提供依据。其独特之处在于**检索引擎的选择**：**LlamaIndex**（默认，混合向量 + BM25，可选交叉编码器重排序及 exact-flat 或 HNSW FAISS 索引）、**PageIndex**（支持页面级引用的推理检索，托管或自托管 OSS）、**GraphRAG** 和 **LightRAG**（知识图谱检索）、**LightRAG Server**（将检索卸载至你通过 HTTP 连接的外部 LightRAG 实例）、**WeKnora**（从你的自托管部署中的知识库检索，无需本地索引或复制文档）、**Tencent IMA**（在 IMA 中维护的知识库 — 通过其 OpenAPI 进行检索、浏览并写回），**MarginNote 4**（你的 MN4 学习数据 — 文档、摘录、脑图卡片及其相互链接 — 由该应用的插件推送进来，并通过专用工具进行导航），或直接在原位读写的链接 **Obsidian** vault。每个 KB 绑定到单一引擎。

要迁移现有的 Obsidian、Hermes 或 Markdown 资料库？请参阅[知识迁移指南](KNOWLEDGE_MIGRATION.md)，了解连接 vault 与索引副本两种路径。创建 KB 时，可以选择**新建**（上传文档并构建全新索引）或**链接已有**（复用在其他地方构建的索引，原位读取无需重新索引）。知识库还可以追踪 **GitHub 仓库**（仓库、分支和 glob 匹配模式）或**文档站点 URL**（限制爬取深度和页面数量）；按需同步时会通过内容哈希差异识别新增、变更和移除的内容，让你关注的文档保持最新，无需重新上传。重新索引会写入新的平铺 `version-N` 目录并保留旧版本，因此重建过程中现有索引不会被破坏。即使知识库处于 **error** 状态，也可以单独移除其中一份文档 — 无需完整地删除重建，就能丢弃解析失败的文件。文档解析 — 纯文本、MinerU、Docling、Tika、markitdown、PyMuPDF4LLM 或 LiteParse — 在 **Settings → Knowledge Base** 中选择，本地模型下载默认关闭。Docling 也可以以 **remote** 模式运行，对接 Docling Serve 服务器（无需本地安装或模型），可在 **Settings → Document Parsing** 中配置（`mode=remote`、服务器 Base URL 和可选的 API Key），或通过 `DOCLING_MODE` / `DOCLING_API_BASE_URL` / `DOCLING_API_TOKEN` 环境变量配置。Tika 仅支持远程模式，需指向该页面中配置的 Apache Tika 服务器。CLI 通过 `list/info/create/add/search/set-default/delete`、来源添加/移除命令、`list-sources` 和 `sync` 管理完整生命周期。内置的 LightRAG 引擎通过 `pip install 'deeptutor[rag-lightrag]'` 安装。该额外依赖包含受支持的 LightRAG SDK，但不会安装 MinerU。如需结构化解析，请在文档解析中单独选择 MinerU，并配置其云端模式或安装当前的本地 CLI。MinerU 支持 PDF、常见的光栅图像、DOCX、PPTX 和 XLSX；旧版 `magic-pdf` 命令仍仅支持 PDF。纯文本及其他解析引擎均不需要 MinerU。

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

学习空间是内容库、组织与个性化层。**对话与素材**包含聊天历史、笔记本 — 记录可在笔记本之间移动或复制，并支持导出为 Markdown — 以及保存你的答案、参考答案和解析的题库。**个性化**包含人格预设、技能（`SKILL.md` 剧本）、一键安装的 **MCP 服务**，以及来自 [CLI-Anything](https://github.com/HKUDS/CLI-Anything) 目录的 **CLI 应用**，每个应用的使用指南按需加载。独立的**我的课程**工作区按学科归拢对话与导师线程；每项素材只会出现在支持它的工作流中。

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

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

Memory 是一个基于文件、三层结构的系统，你可以读取、整理和审计它 — 刻意设计为*非*隐藏的向量库。**L1** 是工作区镜像加仅追加的事件追踪（`trace//.jsonl`）；**L2** 是按表面整理的事实（`L2/.md`），包含对 L1 实体的引用；**L3** 是跨表面的综合（`L3/.md`），记录参与综合的 L2 表面层。

Memory Graph 展示整个金字塔 — L3 综合位于中心，L2 在中间圆环，L1 追踪在外圈 — 并显示精确的 L2 → L1 证据边和 L3 → 参与表面层链接。Memory 在 `chat`、`notebook`、`quiz`、`kb`、`book`、partner 和 `cowriter` 表面进行追踪；整合器的更新 / 审计 / 去重预算可在 **Settings → Memory** 中调整。

⚙️ Settings — 统一的控制面板

Settings 是操作控制面板：开屏是实时状态条（后端健康状况与常驻内存占用）、界面与模型输出语言，以及一个把每项能力评为阻断项、警告或建议的**就绪度**（Readiness）矩阵；再往下是一个常驻的可搜索导航栏，一键直达任意页面：**外观**（主题、代码块样式）、**网络**（API 基础地址、端口、CORS）、**工作区**（智能体可读取的文件夹及其共享的 `outputs/`）、**模型**（Connections 连接、LLM、任务模型、嵌入、搜索、文字转语音、语音转文字、图像生成、视频生成）、**知识库**（文档解析引擎）、**聊天**（Video Learning、可搜索工具、每个能力的参数、起始建议、附件上限）、**Partners 与智能体**（九种本地智能体运行框架）、**学习者档案**（年龄、年级、课程体系、语言、阅读水平、讲解风格）、**监护人**（已授权学习者、素材、报告、凭证重置）、**记忆**（整合器预算），以及**关于**（版本检查与安全更新）。**连接**保存一份厂商凭证，并将其镜像到该厂商可服务的每一处 — 一把密钥只需录入一次，无需在五个页面里分别粘贴；**任务模型**为那些没人特意关心的后台工作（比如给会话命名、撰写输入框的起始建议）指定一个小而快的模型，留空时则回退到当前的默认模型。 Settings → Chat 下的 **Video Learning** 默认使用 YouTube 官方的隐私增强型 IFrame Player。若要让播放保持在本地，请设置由管理员管理的 Invidious API 来源（例如 `http://127.0.0.1:3000`），测试后选择 Invidious 并保存。新建或重新打开的视频会立即采用该提供商，同时保留相同的素材 ID 和进度。Invidious 媒体通过 DeepTutor 的字节范围代理进行流式传输；上游 URL 既不会暴露给浏览器，也不会存储到磁盘。如果实例发生故障，DeepTutor 将保持与 YouTube 离线，直到学习者明确选择原生 YouTube 回退方案。公共字幕辅导是可选功能：安装 `.[video-learning]`；即使未安装，播放仍会继续，但基于转录的 **在此解释** 功能会被禁用并说明原因。

大多数部分采用草稿-应用流程，因此你可以在提交前测试提供商配置。你也可以直接在 Chat 中开口：助手会读取当前配置、应用变更，并告知是否需要重启或重新索引 — 在提交前先探测新模型，因此它不会把自己切换到不可达的配置上。API Key 永远不会经过模型 — 它会为你打开对应的表单来输入。开箱即提供四种主题 — 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/` 中 — 在多容器 Compose 部署中，位于 exec 沙箱可触及的所有目录树之外 — DeepTutor 绝不会读取或修改你的 `~/.codex` CLI 登录状态。模型列表来自该账号的实时目录；只有尚未配置任何 LLM 时，登录后的 Codex 才会成为活跃模型。令牌只授权一个人的订阅，无法通过用户授权共享，因此每个账号都需自行登录 — 普通用户也不例外：他们的卡片位于**模型 → LLM**下，产生的模型、目录和退出登录操作均只对该账号私有。默认的本地 Docker 和 Podman 部署各自使用独立的回环网络，登录时需要一个临时桥接。具体的 Docker、Compose、Podman 及拆除命令请参阅[临时本地 Codex OAuth 桥接指南](../../CONTAINERIZATION.md#temporary-local-codex-oauth-bridge)。远程部署时，浏览器的 `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/ # Admin workspace + global settings ├── users// # Per-user scope: chat history, memory, notebooks, KBs ├── partners//workspace/ # Partner (synthetic-user) scope ├── cli-apps/ # Installed CLI apps, mounted read-only into the sandbox └── system/ # auth · grants · audit · user-secrets/ (OAuth tokens) ``` **第一个注册用户成为管理员**，拥有模型目录、提供商凭证、共享知识库、技能、共享书籍主副本和用户授权的管理权。由管理员创建的本地用户可选择 Standard、Learner 或 Custom。Learner 会锁定学习能力与素材策略，加入自适应档案，并支持带有效期和每日限额、可撤销的设备凭证；获授权的监护人可以查看报告、批准素材和重置凭证。其他用户拥有隔离工作区，以及受作用域约束的模型、知识库、技能、Partners 和共享书籍访问权，但不会获得原始 API Key。如果 `auth.json` 已包含 `username` + `password_hash`，该账号就是管理员：`/register` 会保持关闭，而从 `/admin/users` 创建的账号始终为 `role=user`，直至你将其提升。 **启用方式：** 在 `data/user/settings/auth.json` 中开启认证，重启 `deeptutor start`，在 `/register` 注册第一个管理员，然后从 `/admin/users` 添加用户，并通过授权分配模型、知识库、技能、Partner、工具/MCP/CLI 应用策略和代码执行权限；在每个用户的 **Book access** 面板中配置共享书籍。 > PocketBase 仍为单用户集成 — 多用户部署时请将 `integrations.pocketbase_url` 留空，除非你已接入外部用户存储。

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

自己驱动

`deeptutor chat` 打开交互式 REPL，并通过 `--capability` 选择模式；`deeptutor run ""` 将能力作为第一个位置参数，并在执行一个轮次后退出。两者均接受 `--tool`、`--kb` 和 `--config`。 ```bash deeptutor chat # interactive REPL deeptutor chat --capability deep_solve --kb my-kb --tool rag deeptutor run chat "Explain the Fourier transform" --tool rag --kb textbook deeptutor run deep_research "Survey 2026 papers on RAG" \ --config mode=report --config depth=standard ``` 这里也提供核心工作区管理功能 — 知识库（`kb`）、会话（`session`）、Partners（`partner`）、技能（`skill`）、笔记本、记忆和配置；课程与会话组织仍需在 Web 应用中进行。完整列表见下方。

让智能体驱动

DeepTutor 专为*被其他智能体操作*而设计。在任何 `run` 命令中添加 `--format json`，每个轮次将流式输出 **NDJSON — 每行一个事件**（`content`、`tool_call`、`tool_result`、`done` 等），每行带有其 `session_id` 标记。运行是无头安全的：无 TTY 时，`ask_user` 暂停会以空回复自动解决，而不是挂起。 ```bash # One shot, machine-readable deeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json # Chain turns in one stateful session — capture the id, reuse it SID=$(deeptutor run deep_research "Survey 2026 papers on RAG" \ --config mode=report --config depth=standard --format json \ | jq -r 'select(.type=="done").session_id') deeptutor run deep_question "Quiz me on that survey" --session "$SID" --format json ``` 仓库根目录附带 [`SKILL.md`](SKILL.md) — 约 200 行的交接文档，让任何支持工具调用的 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 doctor [--online]` | 检查工作区是否已准备好启动会话；`--online` 还会探测已配置的模型提供商，`--format json` 打印报告 | | `deeptutor start [--home PATH] [--dev] [--detach] [--no-browser]` | 同时启动后端 + 前端；可选择后台运行或禁止自动打开浏览器 | | `deeptutor stop [--home PATH]` | 停止通过 `--detach` 启动的启动器 | | `deeptutor serve [--port PORT]` | 仅启动 FastAPI 后端 | | `deeptutor workspace show/set/reset` | 查看、选择或还原当前用户的内容工作区 | | `deeptutor run ` | 运行单次能力对话（`chat`、`ask_questions`、`deep_solve`、`deep_question`、`deep_research`、`visualize`、`math_animator`、`mastery_path`、`immersive_reading`、`course_study`、`immersive_watching`）；添加 `--format json` 可获得 NDJSON 输出 | | `deeptutor chat` | 交互式 REPL，支持能力、工具、知识库、笔记本和历史控制 | | `deeptutor partner list/create/start/stop` | 管理 IM 连接的 Partners | | `deeptutor kb list/info/create/add/search/set-default/delete/list-sources/sync` | 管理知识库并同步已注册的 GitHub/Web 来源（包含来源添加/移除命令） | | `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 认证会话；`codebuddy` 验证 CodeBuddy SDK 认证并在需要时启动登录） |

仅 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" # search EduHub (the default hub) deeptutor skill install socratic-tutor # fetch → verify → register deeptutor skill install eduhub:socratic-tutor@1.2.0 # pin a hub and a version deeptutor skill list # local skills with their hub provenance ``` **发布自己的技能** — 打包一个 `SKILL.md` 并分享给社区： ```bash deeptutor skill login # browser sign-in to EduHub deeptutor skill publish ./my-skill # interactive: pick a track + tags, then upload deeptutor skill update # roll back or release a new version ``` EduHub 也是一个独立的、ClawHub 兼容的注册表，因此非 DeepTutor 的智能体（Claude Code、Codex 等）可以通过 `eduhub` CLI 直接使用它 — `npx eduhub install socratic-tutor`。

导入安全门

无论来源如何，每次导入在触及你的工作区之前都会经过**相同的安全门**： - 首先检查注册表的**安全验证结果** — 被标记的包将被拒绝，除非你传入 `--allow-unverified`； - 压缩包会经过路径穿越、条目数量、大小、压缩比、后缀和符号链接检查后进行防御性解压；可执行权限位会被移除，但仍允许无扩展名文件； - frontmatter 被规范化并**去除** `always:`，因此下载的技能永远无法强制将自己注入每个系统提示； - 来源信息 — Hub、版本、验证结果和安装时间 — 被写入 `.hub-lock.json` 以供审计和更新。在多用户部署中，浏览器导入会进入经过认证的调用者技能层，而 CLI 和管理控制台安装则以所有者/管理员工作区为目标；在获得授权之前，管理员技能对普通用户保持隐藏且只读。

同样兼容 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 deeptutor skill install clawhub:udiedrichsen/stock-analysis ``` 当多个发布者共用同一个 slug 时，搜索结果会列出每个发布者及其完整限定的安装引用（`clawhub:/`）。在 `data/user/settings/skill_hubs.json` 中添加更多注册表：`type: "clawhub"` 条目指向任何兼容的 HTTP API（EduHub 和 ClawHub 都支持），`type: "command"` 包装注册表自带的任何获取 CLI，`"default"` 选择用于裸 slug 的 Hub。所有这些来源都经过同一个导入安全门。

## 🤝 开源伙伴

使用优惠码 DEEPTUTOR20 — 首次订阅 PageIndex 立减 $20！

## 🌐 社区 ### 🔗 维护者

Bingxi Zhao

Xingyu Hou

Jiahao Zhang

### 📮 联系方式 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) 许可证。