wehub/hkuds--deeptutor

Fork 0

Files

T

wehub-resource-sync 5057f6412a docs: make Chinese README the default

2026-07-13 10:09:02 +00:00

56 KiB

Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

DeepTutor：终身个性化辅导

功能特性 · 快速开始 · 探索 · CLI · 生态 · 社区

🤝 我们欢迎任何形式的贡献！ 在 Roadmap, 对路线图条目投票或提出新建议，并参阅我们的贡献指南了解分支策略、编码标准及入门方式。

📦 版本发布

[2026.7.9] v1.5.1 — 从知识库中移除单个失败文档——即使是处于 error 状态的文档——而无需删除并重建整个知识库。

[2026.7.4] v1.5.0 — LlamaIndex 摄取现已遵循你的 Document Parsing（文档解析）引擎，支持多模态图像提取；Partner 与 Soul 的 id 对非拉丁字符名称保持 URL 安全；可选 RAG 扩展包可在 Python 3.14+ 上顺利安装。

往期版本（超过 1 周）

[2026.6.30] v1.4.15 — 为 Partner 提供原生 Mattermost 频道，并修复 Guided Learning 多选题评分问题，同时确保配置的零 chunk overlap 生效。

[2026.6.29] v1.4.14 — 点击已分配的 partner 即可一步发起聊天；Deep Research 会标记部分报告；LightRAG 可在无需 MinerU 的情况下建立索引；FAISS 支持非 ASCII 路径；PocketBase 会话按用户隔离。

[2026.6.27] v1.4.13 — Partner 支持非拉丁字符名称并可分配给用户；登录后正确渲染 logo（#599）；小型知识库检索更可靠；容器可在 rootless Podman 下正常启动。

[2026.6.24] v1.4.12 — 新增 LightRAG Server 检索引擎、轻量级 PyMuPDF4LLM 解析引擎，以及 FAISS 向量后端，大幅提升大型知识库检索速度。

[2026.6.23] v1.4.11 — 所有云端 OpenAI 兼容提供商均支持原生 tool calling；重新设计的管理端 Users 页面；测验选项支持 LaTeX；更真实的会话加载 spinner；可配置容器 host 绑定。

[2026.6.21] v1.4.10 — 自助式 Profile（个人资料）页面，支持头像；适用于 rootless 的容器指南，配备单端口 request-time 代理；非管理员用户默认拒绝 MCP tools。

[2026.6.19] v1.4.9 — 设置优化：Search 仅显示你的提供商所需字段；连接配置可重命名并按提供商自动命名；已评分的 Mastery Path 题目会流入 Question Bank。

[2026.6.18] v1.4.8 — 在 My Agents 下连接你自己的 Partners，并在聊天中实时咨询——通过其专属 persona、library 和 skills 作答——每个 Partner 拥有独立私有 memory。

[2026.6.18] v1.4.7 — 连接本地 Claude Code / Codex 并在对话中途实时咨询；My Agents 升级为顶级 /agents；Partner 对话支持 branch / resume / delete，并配有可回放的 trace。

[2026.6.17] v1.4.6 — 四界面整合：Space 学习仪表盘，可导入 My Agents 及顶级 Memory；Knowledge Center 支持 GraphRAG / PageIndex / LightRAG / linked-KB / Obsidian；Settings 全面开放；按模型进行能力门控。

[2026.6.14] v1.4.5 — 引导式学习（Guided Learning）基于聊天智能体循环重建，配备严格的按类型掌握度门槛与 /learning 仪表板，新增循环插件框架，并为 Partner 对话提供 Markdown 导出 / 保存至笔记本功能。

[2026.6.13] v1.4.4 — 可在安全门控后通过 deeptutor skill install 从 ClawHub 安装社区技能，同时为知识库文件提供真实的浏览器内 DOCX/XLSX 预览。

[2026.6.12] v1.4.3 — TutorBot 在生产级 IM 管道上升级为 Partners（15 个频道、实时流式传输），Chat 迁移至单一智能体循环，实现真正的按用户隔离，并重建 Visualize。

[2026.5.28] v1.4.2 — 稳定性与体验优化：在 Visualize 和 Chat 中解除 Gemini 2.5+ 限制，认证路由修复（#485），流畅流式聊天体验，新增 Recents 侧边栏，以及 Lemonade 本地提供商支持。

[2026.5.27] v1.4.1 — 安全性与稳定性：收紧 TutorBot 工具沙箱，按用户资源隔离，多模态图像回退，为 TutorBots 提供 HTTP/SSE API，并修复 v1.4.0 聊天回归问题。

[2026.5.22] v1.4.0 — v1.4 正式版（GA）发布：Auto Mode、三层 Memory、智能体式 Deep Research / Solve / Question、LlamaIndex RAG 重构、Visualize/Animator 合并，以及重启安全的回合运行时。

[2026.5.21] v1.4.0-beta — 三层 Memory 工作台（L1/L2/L3），所有聊天能力基于单一智能体引擎重建，仅 LlamaIndex RAG，以及统一的 Settings + Capabilities 界面。

[2026.5.10] v1.3.10 — 远程 Docker CORS 恢复，DISABLE_SSL_VERIFY 覆盖各 SDK 提供商，更安全的代码块引用，以及可选 Matrix E2EE 插件。

[2026.5.9] v1.3.9 — TutorBot 支持 Zulip 与 NVIDIA NIM，更安全的思考模型路由，deeptutor start，侧边栏工具提示，以及会话存储一致性。

[2026.5.8] v1.3.8 — 可选多用户部署，配备隔离的用户工作区、管理员授权、认证路由，以及限定范围的运行时访问。

[2026.5.4] v1.3.7 — 思考模型/提供商修复，可见的 Knowledge 索引历史，以及更安全的 Co-Writer 清空/模板编辑。

[2026.5.3] v1.3.6 — 聊天与 TutorBot 的基于目录的模型选择，更安全的 RAG 重新索引，OpenAI Responses token 限制修复，以及 Skills 编辑器验证。

[2026.5.2] v1.3.5 — 更顺畅的本地启动设置，更安全的 RAG 查询，更简洁的本地 embedding 认证，以及 Settings 深色模式优化。

[2026.5.1] v1.3.4 — Book 页面聊天持久化与重建流程，聊天到 Book 引用，更强的语言/推理处理，RAG 文档提取加固。

[2026.4.30] v1.3.3 — NVIDIA NIM + Gemini embedding 支持，统一的 Space 上下文（聊天历史/技能/记忆），会话快照，RAG 重新索引弹性。

[2026.4.29] v1.3.2 — 透明的 embedding 端点 URL，针对无效持久化向量的 RAG 重新索引弹性，思考模型输出的记忆清理，Deep Solve 运行时修复。

[2026.4.28] v1.3.1 — 稳定性：更安全的 RAG 路由与 embedding 验证，Docker 持久化，IME 安全输入，Windows/GBK 健壮性。

[2026.4.27] v1.3.0 — 带重新索引工作流的版本化 KB 索引，重建 Knowledge 工作区，配备新适配器的 embedding 自动发现，以及 Space 中心。

[2026.4.25] v1.2.5 — 持久化聊天附件与文件预览抽屉，附件感知的能力管道，TutorBot Markdown 导出。

[2026.4.25] v1.2.4 — 文本/代码/SVG 附件，一键 Setup Tour，Markdown 聊天导出，紧凑 KB 管理 UI。

[2026.4.24] v1.2.3 — 文档附件（PDF/DOCX/XLSX/PPTX），推理思考块显示，Soul 模板编辑器，Co-Writer 保存至笔记本。

[2026.4.22] v1.2.2 — 用户自编写 Skills 系统，聊天输入性能大修，TutorBot 自动启动，Book Library UI，可视化全屏。

[2026.4.21] v1.2.1 — 分阶段 token 限制，所有入口点的重新生成回复，RAG 与 Gemma 兼容性修复。

[2026.4.20] v1.2.0 — Book Engine「活书」编译器，多文档 Co-Writer，交互式 HTML 可视化，Question Bank @-提及。

[2026.4.18] v1.1.2 — 由 Schema 驱动的 Channels 标签页，RAG 单管道整合，外置聊天提示词。

[2026.4.17] v1.1.1 — 通用「立即回答」，Co-Writer 滚动同步，统一设置面板，流式 Stop 按钮。

[2026.4.15] v1.1.0 — LaTeX 块级数学公式大修，LLM 诊断探测，Docker + 本地 LLM 指引。

[2026.4.14] v1.1.0-beta — 可书签化会话，Snow 主题，WebSocket 心跳与自动重连，embedding 注册表大修。

[2026.4.13] v1.0.3 — 带书签与分类的 Question Notebook，Visualize 中的 Mermaid，embedding 不匹配检测，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 — 带速率限制重试的 Embedding 进度跟踪，跨平台依赖修复，以及 MIME 验证修复。

[2026.4.8] v1.0.0-beta.3 — 原生 OpenAI/Anthropic SDK（移除 litellm），Windows Math Animator 支持，健壮的 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、Guided Learning，以及持久化记忆。

[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 与 embedding 支持、新首页、RAG 模块解耦与环境变量重构。

[2026.1.5] v0.3.0 — 统一 PromptManager 架构、GitHub Actions CI/CD，以及 GHCR 预构建 Docker 镜像。

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

📰 新闻

2026-05-22 🌐 官方文档站已在 deeptutor.info 上线 — 指南、参考与能力导览，一站式呈现。
2026-04-19 🎉 111 天内达成 20k stars！感谢大家对真正个性化、智能辅导的支持。
2026-04-10 📄 我们的论文已在 arXiv 上线 — 阅读预印本了解 DeepTutor 背后的设计与理念。
2026-02-06 🚀 仅用 39 天即达成 10k stars！衷心感谢我们出色的社区。
2026-01-01 🎊 新年快乐！加入我们的 Discord, WeChat, 或 Discussions — 一起塑造 DeepTutor。
2025-12-29 🎓 DeepTutor 正式发布！

✨ 核心特性

DeepTutor 是一个 agent-native（智能体原生）学习工作区，将辅导、解题、出题、研究、可视化与掌握练习集成于同一可扩展系统中。

一种运行时，覆盖所有模式 — Chat、Quiz、Research、Visualize、Solve 与 Mastery Path 共用同一 agent loop，切换的是目标而非引擎，上下文随学习者流转。
互联的学习上下文 — 知识库、书籍、Co-Writer 草稿、笔记本、题库、人设与 Memory 在各工作流中始终可用，而非孤立在各工具里。
子智能体与 Partners — 在任意轮次咨询实时的 Claude Code、Codex 或 Partner（或导入其历史对话），在同一「大脑」上运行持久 IM 伴侣。
多引擎知识 — 跨 LlamaIndex、PageIndex、GraphRAG、LightRAG 或关联 Obsidian vault 的版本化 RAG 库，支持可插拔文档解析。
可扩展工具与技能 — 内置工具、MCP 服务器、图像/视频/语音生成模型，以及来自 EduHub 的可安装社区技能。
可检视的记忆 — L1 轨迹、L2 表层摘要与 L3 综合使个性化可见、可编辑；Memory Graph 将每条主张追溯至其证据。

🚀 快速开始

DeepTutor 提供四种安装方式，共用同一工作区布局：设置位于你启动命令所在目录下的 data/user/settings/（若显式指定，则在 DEEPTUTOR_HOME / deeptutor start --home 下）。完整应用推荐流程：选择工作区目录 → 安装 → deeptutor init → deeptutor start。

选项 1 — 从 PyPI 安装 · 完整本地 Web 应用 + CLI，无需克隆仓库

完整本地 Web 应用 + CLI，无需克隆仓库。需要 PATH 上有 Python 3.11+ 与 Node.js 20+ 运行时（打包的 Next.js standalone 服务器由 deeptutor start 启动）。

mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor
deeptutor init     # prompts for ports + LLM provider + optional embedding
deeptutor start    # starts backend + frontend; keep the terminal open

deeptutor init 会提示配置后端端口（默认 8001）、前端端口（默认 3782）、LLM 提供商 / base URL / API key / 模型，以及可选的 Knowledge Base / RAG embedding 提供商。

deeptutor start 后，打开终端打印的前端 URL — 默认为 http://127.0.0.1:3782. 在该终端按 Ctrl+C 可同时停止后端与前端。快速试用可跳过 deeptutor init；应用将以默认端口与空模型设置启动，稍后在 Settings → Models 中配置。

选项 2 — 从源码安装 · 基于 checkout 开发

基于 checkout 开发。请使用 Python 3.11+ 与 Node.js 22 LTS，与 CI 和 Docker 保持一致。

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

源码安装会在本地 web/ 目录以 dev 模式运行 Next.js；其余（配置布局、端口、用 Ctrl+C 停止）与选项 1 相同。

Conda 环境（替代 venv）

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

可选安装 extras — dev / partners / matrix / math-animator

pip install -e ".[dev]"             # tests/lint tools
pip install -e ".[partners]"        # Partner IM channel SDKs + MCP client
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 报告已有前端无响应，停止其打印的 PID。若没有 Next.js 进程在运行，说明锁文件已过期 — 删除后重试：

rm -f web/.next/dev/lock web/.next/lock
deeptutor start

选项 3 — Docker · 单容器自包含部署

单容器运行完整 Web 应用。镜像位于 GitHub Container Registry：

ghcr.io/hkuds/deeptutor:latest — 稳定版
ghcr.io/hkuds/deeptutor:pre — 预发布版（如有）

关于 podman/rootless/read-only-rootfs 部署及完整分步安装指南，请参阅 CONTAINERIZATION.md。

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

只需发布 3782。 浏览器仅与前端 origin 通信；Next.js 中间件（web/proxy.ts）将 /api/* 与 /ws/* 转发至容器内部的 FastAPI 后端。发布 8001（-p 127.0.0.1:8001:8001）为可选 — 仅在使用 curl 或脚本直接访问 API 时方便。

打开 http://127.0.0.1:3782. 容器首次启动时会创建 /app/data/user/settings/*.json；在 Web Settings 页面配置模型提供商。配置、API 密钥、日志、工作区文件、memory 与知识库持久化在 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 / 反向代理： 浏览器仅与前端 origin（:3782）通信；容器内的 Next.js 中间件在服务端将 /api/* 和 /ws/* 转发到后端。对于常见的单容器场景，你完全不需要配置 API base — 只需将反向代理 / TLS 终止器指向 :3782。仅在拆分部署（后端位于独立容器/主机）时才需要 API base：在 data/user/settings/system.json 中将 next_public_api_base 设为前端服务器用于访问后端的内网地址（该值仅在服务端读取，不会发送给浏览器）。

{
  "next_public_api_base": "http://backend:8001"
}

next_public_api_base_external（及其别名 public_api_base）可作为优先级较低的回退项。CORS 使用前端 origins，而非 API URL。禁用身份验证时，DeepTutor 默认允许常规 HTTP/HTTPS 浏览器 origin。启用身份验证时，需添加精确的前端 origin：

{
  "cors_origins": ["https://deeptutor.example.com"]
}

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

在 Docker 内，localhost 指向容器自身，而非宿主机。要访问运行在宿主机上的模型服务，请使用 host gateway（推荐）：

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 embedding: 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 替代方案 — host 网络： 添加 --network=host 并移除 -p 标志。容器直接共享宿主机网络，因此打开 http://127.0.0.1:3782（或 system.json 中的 frontend_port），并可通过 http://127.0.0.1:11434/v1 等常规 localhost URL 访问宿主机服务。请注意，host 网络会将容器端口直接暴露在宿主机上，可能与现有服务冲突 — 若要将它们保留在 loopback 上，请设置 BACKEND_HOST=127.0.0.1 和 FRONTEND_HOST=127.0.0.1（参见 CONTAINERIZATION.md）。

选项 4 — 仅 CLI · 无 Web UI，从源码检出安装

当你不需要 Web UI 时。仅 CLI 包需从源码检出安装，而非通过 PyPI 安装。

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/ 布局，但会跳过后端/前端端口提示，并将 embeddings 默认设为关闭（若计划使用 deeptutor kb … 或 RAG 工具，请选择 Yes）。它仍会写入完整的运行时布局（system.json、auth.json、integrations.json、model_catalog.json、main.yaml、agents.yaml），并仍会提示选择当前 LLM 提供商和模型。

常用命令

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 包（选项 1），并在同一工作区中运行 deeptutor init + deeptutor start。

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

内置 office skills — docx / pdf / pptx / xlsx — 的工作方式是：让模型编写简短的 Python 脚本（python-docx、reportlab、openpyxl、…），通过 exec / code_execution 工具运行，并返回下载 URL。只要沙箱后端处于活动状态，这些工具就会挂载，而在每种部署形态中，它默认都是启用的：

本地（选项 1 / 2）和 Docker（选项 3，单容器）： 受限的子进程沙箱运行模型代码（在宿主机本地，或在 Docker 内的容器中 — 容器本身即隔离边界）。
docker-compose： 改为通过 DEEPTUTOR_SANDBOX_RUNNER_URL 路由到加固的、最小权限的 runner sidecar（Dockerfile.runner）— 这是最强安全姿态，存在时会自动优先选用。

子进程沙箱由 data/user/settings/system.json 中的 sandbox_allow_subprocess 设置控制（默认 true）。在宿主机上运行模型生成的代码是一项真实的信任决策 — 将其设为 false（或导出 DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS=0）可禁用宿主机端执行，代价是 office skills 将无法再生成文件。

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

data/user/settings/ 下的所有内容均为普通 JSON/YAML。推荐使用浏览器中的 Settings 页面进行编辑。

文件	用途
`model_catalog.json`	LLM、embedding 与搜索提供商配置；API 密钥；当前模型
`system.json`	后端/前端端口、公共 API base、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 / 模型名称）并保存。仅在你计划使用 Knowledge Base / RAG 功能时才添加 embedding 配置。

📖 探索 DeepTutor

从日常会使用的主要界面入手：Chat、Partners、My Agents、Co-Writer、Book、Knowledge Center、Learning Space、Memory 和 Settings。随后介绍 Multi-User 部署，用于共享、隔离的工作区。

🏗️ 系统架构

💬 Chat — 你实际使用的 Agent 循环

Chat 是默认能力，也是大多数工作的起点。单个会话可以正常对话、调用工具、基于所选知识库进行 grounding、读取附件、生成图像、咨询 subagent、写入 notebook 记录，并在多轮对话中保持相同上下文。

该循环刻意保持简单：模型分轮思考，在有用时调用工具，观察结果，最后以一条无工具消息结束。ask_user 很特殊 — 代理无需猜测，可以暂停当前轮次、提出结构化澄清问题，并在你回答后继续。

用户可切换的工具包括 brainstorm、web_search、paper_search、reason 和 geogebra_analysis——配置好对应的生成模型后，还有 imagegen 和 videogen。上下文相关工具如 rag、read_source、read_memory、write_memory、read_skill、load_tools、exec、web_fetch、ask_user、list_notebook、write_note、github 和 consult_subagent，会在当前轮次具备正确上下文时自动挂载。

上下文分为两类：粘性会话上下文（子智能体、知识库、人设、模型、语音）位于编辑器工具栏，并在多轮对话中保持；一次性引用（文件、聊天记录、书籍、笔记本、题库、导入的智能体）来自 + 菜单，仅作用于单轮。

聊天也是更深层能力的入口：Quiz（测验） 用于出题，Research（研究） 用于带引用的报告，Visualize（可视化） 用于图表 / 示意图 / 动画，以及——在 More Capabilities（更多能力） 下——Solve（求解） 用于逐步推演，Mastery Path（精通路径） 用于学习计划流程。

🤝 Partner — 同一大脑上的持久伙伴

Partners（伙伴）是持久陪伴，各自拥有灵魂、模型策略、资料库、记忆与通道。它们并非独立的机器人引擎：每一条入站 Web 或 IM 消息，都会变成伙伴作用域工作区内的一次普通 ChatOrchestrator 轮次。伙伴就是「带有性格和电话号码的聊天」。

每个伙伴拥有 SOUL.md、模型选择、通道、工具策略以及分配的资料库。知识库、技能和笔记本会复制到 data/partners/<id>/workspace/，因此同样的 RAG、技能、笔记本和记忆工具无需特殊分支即可工作。伙伴可读其所有者的记忆，但只写入自己的记忆。

通道层由 schema 驱动，可按已安装的 extras 与已配置凭证连接到 Feishu、Telegram、Slack、Discord、DingTalk、QQ/NapCat、WeCom、WhatsApp、Zulip、Mattermost、Matrix、Mochat 和 Microsoft Teams 等 IM 平台。伙伴也可作为子智能体接入，并在普通聊天轮次中被咨询——详见下方 My Agents。

🧑‍🚀 My Agents — 咨询与导入其他智能体

My Agents 将其他智能体变成 DeepTutor 的上下文，并完成两件不同的事。连接在线智能体——本机上的 Claude Code 或 Codex CLI，或你的某个 Partner——并在聊天轮次内咨询它：DeepTutor 会实际运行对方智能体，并通过 consult_subagent 工具将其工作流式传输到 Activity（活动）面板。用 Agent 芯片选择（或输入 @），并设置本次咨询可进行的轮数。

导入过往对话——将你已有的 Claude Code 与 Codex 历史导入为可命名、可搜索、可恢复的智能体。选择要导入的日期；刷新会重新同步。可在任意聊天轮次通过 + → My Agents 引用已导入的对话，DeepTutor 将其作为第三方转写读取——它仍是对方的对话，而非 DeepTutor 自己的声音。

✍️ Co-Writer — 感知选区的 Markdown 起草

Co-Writer 是面向报告、教程、笔记与长篇学习产物的分栏 Markdown 工作区。文档会自动保存并渲染实时预览（KaTeX 公式、diagram 围栏代码块），当草稿成为可复用上下文时，也可回存到笔记本。

其核心思路是精准编辑：选中一段文字，请 DeepTutor 改写、扩展或压缩。编辑智能体可将修改锚定到知识库或网页证据，保留工具调用轨迹，并以 accept/reject diff 展示每一处变更——在你批准前，不会写入任何内容。

📖 Book — 由你的材料生成的活书

Book 将所选来源转化为交互式活书——不是静态 PDF，而是由类型化块构成的阅读环境。一本书可从知识库、笔记本、题库或聊天记录起步；创建流程会先提出章节大纲再生成内容，让你审阅结构，而不是接受盲目的一次性输出。

每一章会编译为类型化块——文本、提示框、测验、闪卡、时间线、代码、图示、交互 HTML、动画、概念图、深度解读与用户笔记——且每一页都有自己的 Page Chat（页内对话）。块可编辑：插入、移动、重新生成，或切换块类型而无需重写整章。维护命令如 deeptutor book health 和 deeptutor book refresh-fingerprints 有助于检测源知识是否已与编译后的页面发生偏离。

📚 Knowledge Center — 多引擎 RAG 资料库

知识库是 RAG 背后的文档集合——为 Chat 轮次、Co-Writer 编辑、Book 生成与 Partner 对话提供依据。其独特之处在于可选择检索引擎：LlamaIndex（默认，本地向量 + BM25）、PageIndex（托管，带页级引用的推理检索）、GraphRAG 与 LightRAG（知识图谱检索）、LightRAG Server（将检索卸载到你通过 HTTP 连接的外部 LightRAG 实例），或链接的 Obsidian 仓库（导师就地读写）。每个知识库绑定一个引擎。

创建知识库时，你可以新建（上传文档并构建全新索引）或链接已有（复用在他处构建的索引，就地读取且无需重建索引）。重建索引会写入新的扁平 version-N 目录并保留旧目录，因此重建过程中不会销毁仍在使用的索引。即使在 error（错误）状态的库中，也可单独移除一份文档——删除解析失败的文件而无需完整删除并重建。文档解析——仅文本、MinerU、Docling、markitdown 或 PyMuPDF4LLM——在 Settings → Knowledge Base 中选择，本地模型下载默认关闭。CLI 通过 deeptutor kb list、info、create、add、search、set-default 和 delete 镜像完整生命周期。

🌐 Learning Space — 技能、人设与可复用上下文

Learning Space 是资料库与个性化层——持久化内容存放于此。Conversations & Materials（对话与资料）保存你的聊天记录、笔记本和题库（每道已保存的题目会保留你的答案、参考答案和解析）。Personalization（个性化）保存掌握路径、人设（行为预设，如 peer、research-assistant、teacher）以及技能（模型按需读取的 SKILL.md 剧本）。此处一切内容均可从 Chat、Partners、Co-Writer 和 Book 复用。

你不必亲自编写每一项技能——Import from EduHub（从 EduHub 导入）可浏览社区目录，并通过安全网关将技能直接下载到你的资料库（参见 Ecosystem）。

🧠 Memory — 可检视的个性化

Memory 是基于文件的三层系统，可读、可整理、可审计——刻意不是隐藏的向量存储。L1 是工作区镜像加上仅追加的事件轨迹（trace/<surface>/<date>.jsonl）；L2 是按界面整理的要点（L2/<surface>.md）；L3 是跨界面综合（L3/<profile|recent|scope|preferences>.md）。由于 L2 引用 L1、L3 引用 L2，你档案中的每一项都有据可查。

Memory Graph（记忆图谱）展示完整金字塔——中心为 L3 综合，中间环为 L2，外围为 L1 轨迹——因此你可以将任何综合结论追溯到其背后的原始事件。Memory 在 chat、notebook、quiz、kb、book、partner 以及 cowriter 界面上持续追踪；整合器的 Update / Audit / Dedup 预算在 Settings → Memory 中调整。

⚙️ Settings — 统一控制平面

Settings 是运维控制平面，带有实时状态条（Backend、LLM、Embedding、Search），每个区域一张卡片：Appearance（外观：主题 + UI 语言）、Network（网络：API base、端口、CORS）、Models（模型：LLM、Embedding、Search、Text-to-Speech、Speech-to-Text、Image Generation、Video Generation）、Knowledge Base（知识库：文档解析引擎）、Chat（对话：工具、MCP servers、各能力参数）、Partners & Agents（可从单轮对话中调用的子代理），以及 Memory（整合器预算）。

DeepTutor appearance settings and themes

多数区块采用草稿-应用流程，便于在正式提交前测试提供商。内置四种主题——Default、Cream、Dark 和 Glass。项目根目录的 .env 文件会被刻意忽略；运行时配置位于 data/user/settings/*.json 下，除非 DEEPTUTOR_HOME 或 deeptutor start --home 将应用指向其他位置。

👥 Multi-User — 共享部署 · 可选认证，按用户隔离工作区

认证默认关闭——DeepTutor 以单用户模式运行。开启后，一个 data/ 树同时托管管理员工作区、按用户隔离的工作区以及 partner 工作区：

data/
├── user/                    # Admin workspace + global settings
├── users/<uid>/             # Per-user scope: chat history, memory, notebooks, KBs
├── partners/<id>/workspace/ # Partner (synthetic-user) scope
└── system/                  # auth/users.json · grants/<uid>.json · audit/usage.jsonl

首位注册用户成为管理员，拥有模型目录、提供商凭据、共享知识库、技能以及按用户授权。其余用户获得隔离工作区和精简版 Settings 页面——管理员分配的模型、知识库和技能以限定范围、只读选项呈现，绝不会暴露原始 API 密钥。

**启用方式：**在 data/user/settings/auth.json 中开启认证，重启 deeptutor start，在 /register 注册首位管理员，然后从 /admin/users 添加用户，并通过授权分配模型、知识库、技能、partners、工具/MCP 策略以及代码执行权限。

PocketBase 仍为单用户集成——多用户部署请保持 integrations.pocketbase_url 为空，除非你已接入外部用户存储。

⌨️ DeepTutor CLI — 面向代理的原生接口

一个 deeptutor 二进制，两种入口：供终端用户使用的交互式 REPL，以及供其他将 DeepTutor 作为工具驱动的代理使用的结构化 JSON。两种方式具备相同的能力、工具和知识库。

自行驱动

deeptutor chat 打开交互式 REPL；deeptutor run <capability> "<message>" 执行单轮后退出。两者使用相同的 --capability、--tool、--kb 和 --config 标志。

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

Web 应用的一切功能这里都有——知识库（kb）、会话（session）、partners（partner）、技能（skill）、笔记本、memory 和配置。完整列表见下文。

让代理驱动

DeepTutor 的设计目标是由其他代理操作。向任意 run 添加 --format json，每轮以 NDJSON — 每行一个事件 流式输出（content、tool_call、tool_result、done、…），每行均标注其 session_id。运行可无头安全：无 TTY 时的 ask_user 暂停会自动以空回复解决，而不会挂起。

# 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——约 150 行的交接文档，可让任意具备工具调用能力的 LLM 一次读完整个界面。可交给 Claude Code、Codex 或 OpenCode（它们会自动加载 SKILL.md），或将 deeptutor run 封装为 LangChain / AutoGen 循环中的工具。完整配方：Agent Handoff.

命令参考

Command	Description
`deeptutor init`	为当前工作区创建或更新 `data/user/settings`
`deeptutor start [--home PATH]`	同时启动 backend + frontend
`deeptutor serve [--port PORT]`	仅启动 FastAPI backend
`deeptutor run <capability> <message>`	运行单轮能力（`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:<slug>`，参见 Ecosystem）
`deeptutor memory show/clear`	检视 L2/L3 memory 文档或清除 L1/全部 memory
`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 <provider>`	提供商认证（`openai-codex` OAuth 登录；`github-copilot` 验证现有 Copilot 认证会话）

仅 CLI 分发版

仅 CLI 包位于 packaging/deeptutor-cli。在本检出版本中，请从源码安装：

python -m pip install -e ./packaging/deeptutor-cli

该包尚未发布到 PyPI，因此主入门指南部分仍保留从源码安装的路径。

🧩 生态系统 — EduHub 与 Skills 社区

DeepTutor 技能采用开放的 Agent-Skills 格式 — 一个包含 SKILL.md playbook（YAML frontmatter + Markdown）及可选参考文件的文件夹。该格式并非 DeepTutor 专属，因此任何支持此格式的注册表都可作为你的技能库来源。DeepTutor 内置 EduHub — 我们自有的教育导向技能注册表 — 作为默认 hub 接入。

EduHub — DeepTutor 的技能生态系统

EduHub 是 DeepTutor 为分享教学导向 agent 技能而推出的社区 hub — 包括苏格拉底式导师、闪卡生成器、作文反馈、考试蓝图、概念讲解器等。它已内置在 DeepTutor 中，无需额外配置：裸 slug 或 eduhub: 前缀即可解析到该 hub。

查找并安装 — 在浏览器中，打开 Learning Space → Skills → Import from EduHub 浏览目录并直接将技能下载到你的库中。在终端中：

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 打包并分享给社区：

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 的 agent（Claude Code、Codex 等）可通过 eduhub CLI — npx eduhub install socratic-tutor 直接使用。

导入安全门控

无论来源如何，每次导入在触及工作区之前都会经过同一套安全门控：

首先检查注册表的安全裁决（security verdict） — 被标记的包会被拒绝，除非你传入 --allow-unverified；
归档文件以防御方式解压（zip-slip / zip-bomb 防护），并受文本/脚本后缀白名单约束，因此二进制文件永远不会进入工作区；
frontmatter 会规范化为 DeepTutor 的 schema，且 always: 会被剥离，因此下载的技能无法强制写入每个系统 prompt；
来源信息 — hub、版本、裁决和安装时间 — 会写入 .hub-lock.json，供审计与更新使用。

在多用户部署中，安装仅限管理员：新技能会进入管理员目录，在其他用户被授予访问权限之前对其他用户不可见，管理员可在推广前先行审查。

亦兼容 ClawHub

由于 DeepTutor 支持开放的 Agent-Skills 格式，**ClawHub**** 同样是一等来源 — 它与 EduHub 一并内置。使用 hub 前缀选择它：

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" 封装各注册表自带的 fetch CLI，"default" 用于选择裸 slug 所使用的 hub。它们都汇入同一导入门控。

🌐 社区

📮 联系方式

DeepTutor 是由 Bingxi Zhao 在 HKUDS 小组内主导的开源项目，并以完全开源的形式与社区共同迭代。截至目前，我们没有任何形式的付费在线产品。欢迎通过 bingxizhao39@gmail.com 就讨论、想法或合作与我们联系。

🙏 致谢

衷心感谢 Chao Huang, — 香港大学数据智能实验室主任，以及 HKUDS 实验室同仁的热情支持 — 尤其是 Jiahao Zhang, Zirui Guo, 和 Xubin Ren. 我们也深切感谢开源社区：你们的 star、issue、pull request 与讨论每天都在塑造 DeepTutor。

DeepTutor 也站在杰出开源项目的肩膀上，它们为我们提供了工具与灵感：

项目	角色 / 灵感来源
LlamaIndex	RAG 流水线与文档索引骨干
nanobot	超轻量 agent 引擎，为原始 TutorBot 提供动力 (HKUDS)
LightRAG	简洁快速的 RAG (HKUDS)
AutoAgent	零代码 agent 框架 (HKUDS)
AI-Researcher	自动化研究流水线 (HKUDS)
OpenClaw	ClawHub 背后的开放 agent 网关与技能生态系统
Codex	启发我们 CLI 工作流的 agent 原生编码 CLI
Claude Code	启发 DeepTutor agent 循环的 agentic 编码 CLI
ManimCat	为 Math Animator 提供 AI 驱动的数学动画生成