wehub/hkuds--deeptutor
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
main
hkuds--deeptutor/README.md
T
wehub-resource-sync 5057f6412a docs: make Chinese README the default
2026-07-13 10:09:02 +00:00

828 lines
56 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/HKUDS/DeepTutor) · [上游 README](https://github.com/HKUDS/DeepTutor/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
<div align="center">
<p align="center"><img src="assets/figs/logo/logo.png" alt="DeepTutor logo" height="56" style="vertical-align: middle;">&nbsp;<img src="assets/figs/logo/banner.png" alt="DeepTutor" height="48" style="vertical-align: middle;"></p>
# DeepTutor：终身个性化辅导
<p align="center">
<a href="https://deeptutor.info" target="_blank"><img alt="Docs — deeptutor.info" src="https://img.shields.io/badge/Docs-deeptutor.info%20%E2%86%97-0A0A0A?style=for-the-badge&labelColor=F5F5F4" height="36"></a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/17099?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-17099" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/17099" alt="HKUDS%2FDeepTutor | Trendshift" width="250" height="55"/></a>&nbsp;
<a href="https://trendshift.io/repositories/17099?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-17099" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/daily" alt="HKUDS%2FDeepTutor | Trendshift" width="250" height="55"/></a>&nbsp;
<a href="https://trendshift.io/repositories/17099?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-17099" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/17099/weekly?language=Python" alt="HKUDS%2FDeepTutor | Trendshift" width="250" height="55"/></a>
</p>
<p align="center">
<a href="README.md"><img alt="English" height="40" src="https://img.shields.io/badge/English-BCDCF7"></a>&nbsp;
<a href="assets/README/README_CN.md"><img alt="简体中文" height="40" src="https://img.shields.io/badge/简体中文-CDCFD4"></a>&nbsp;
<a href="assets/README/README_JA.md"><img alt="日本語" height="40" src="https://img.shields.io/badge/日本語-CDCFD4"></a>&nbsp;
<a href="assets/README/README_ES.md"><img alt="Español" height="40" src="https://img.shields.io/badge/Español-CDCFD4"></a>&nbsp;
<a href="assets/README/README_FR.md"><img alt="Français" height="40" src="https://img.shields.io/badge/Français-CDCFD4"></a>&nbsp;
<a href="assets/README/README_AR.md"><img alt="Arabic" height="40" src="https://img.shields.io/badge/Arabic-CDCFD4"></a>&nbsp;
<a href="assets/README/README_RU.md"><img alt="Русский" height="40" src="https://img.shields.io/badge/Русский-CDCFD4"></a>&nbsp;
<a href="assets/README/README_HI.md"><img alt="Hindi" height="40" src="https://img.shields.io/badge/Hindi-CDCFD4"></a>&nbsp;
<a href="assets/README/README_PT.md"><img alt="Português" height="40" src="https://img.shields.io/badge/Português-CDCFD4"></a>&nbsp;
<a href="assets/README/README_TH.md"><img alt="Thai" height="40" src="https://img.shields.io/badge/Thai-CDCFD4"></a>&nbsp;
<a href="assets/README/README_PL.md"><img alt="Polski" height="40" src="https://img.shields.io/badge/Polski-CDCFD4"></a>
</p>
[![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-Community-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/eRsjPgMU4t)
[![Feishu](https://img.shields.io/badge/Feishu-Group-00D4AA?style=flat-square&logo=feishu&logoColor=white)](./Communication.md)
[![WeChat](https://img.shields.io/badge/WeChat-Group-07C160?style=flat-square&logo=wechat&logoColor=white)](https://github.com/HKUDS/DeepTutor/issues/78)
[功能特性](#-key-features) · [快速开始](#-get-started) · [探索](#-explore-deeptutor) · [CLI](#%EF%B8%8F-deeptutor-cli--agent-native-interface) · [生态](#-ecosystem--eduhub--the-skills-community) · [社区](#-community)
</div>
---
> 🤝 **我们欢迎任何形式的贡献！** 在 [`Roadmap`](https://github.com/HKUDS/DeepTutor/issues/498), 对路线图条目投票或提出新建议，并参阅我们的[贡献指南](CONTRIBUTING.md)了解分支策略、编码标准及入门方式。
### 📦 版本发布
> **[2026.7.9]** [v1.5.1](https://github.com/HKUDS/DeepTutor/releases/tag/v1.5.1) — 从知识库中移除单个失败文档——即使是处于 **error** 状态的文档——而无需删除并重建整个知识库。
> **[2026.7.4]** [v1.5.0](https://github.com/HKUDS/DeepTutor/releases/tag/v1.5.0) — LlamaIndex 摄取现已遵循你的 **Document Parsing**（文档解析）引擎，支持多模态图像提取；Partner 与 Soul 的 id 对非拉丁字符名称保持 URL 安全；可选 RAG 扩展包可在 Python 3.14+ 上顺利安装。
<details>
<summary><b>往期版本（超过 1 周）</b></summary>
> **[2026.6.30]** [v1.4.15](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.15) — 为 Partner 提供原生 **Mattermost** 频道，并修复 Guided Learning 多选题评分问题，同时确保配置的零 chunk overlap 生效。
> **[2026.6.29]** [v1.4.14](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.14) — 点击已分配的 partner 即可一步发起聊天；Deep Research 会标记部分报告；LightRAG 可在无需 MinerU 的情况下建立索引；FAISS 支持非 ASCII 路径；PocketBase 会话按用户隔离。
> **[2026.6.27]** [v1.4.13](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.13) — Partner 支持非拉丁字符名称并可分配给用户；登录后正确渲染 logo（#599）；小型知识库检索更可靠；容器可在 rootless Podman 下正常启动。
> **[2026.6.24]** [v1.4.12](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.12) — 新增 **LightRAG Server** 检索引擎、轻量级 **PyMuPDF4LLM** 解析引擎，以及 FAISS 向量后端，大幅提升大型知识库检索速度。
> **[2026.6.23]** [v1.4.11](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.11) — 所有云端 OpenAI 兼容提供商均支持原生 tool calling；重新设计的管理端 Users 页面；测验选项支持 LaTeX；更真实的会话加载 spinner；可配置容器 host 绑定。
> **[2026.6.21]** [v1.4.10](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.10) — 自助式 **Profile**（个人资料）页面，支持头像；适用于 rootless 的容器指南，配备单端口 request-time 代理；非管理员用户默认拒绝 MCP tools。
> **[2026.6.19]** [v1.4.9](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.9) — 设置优化：Search 仅显示你的提供商所需字段；连接配置可重命名并按提供商自动命名；已评分的 Mastery Path 题目会流入 Question Bank。
> **[2026.6.18]** [v1.4.8](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.8) — 在 **My Agents** 下连接你自己的 **Partners**，并在聊天中实时咨询——通过其专属 persona、library 和 skills 作答——每个 Partner 拥有独立私有 memory。
> **[2026.6.18]** [v1.4.7](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.7) — 连接本地 **Claude Code / Codex** 并在对话中途实时咨询；**My Agents** 升级为顶级 `/agents`；Partner 对话支持 branch / resume / delete，并配有可回放的 trace。
> **[2026.6.17]** [v1.4.6](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.6) — 四界面整合：Space 学习仪表盘，可导入 **My Agents** 及顶级 Memory；**Knowledge Center** 支持 GraphRAG / PageIndex / LightRAG / linked-KB / Obsidian；Settings 全面开放；按模型进行能力门控。
> **[2026.6.14]** [v1.4.5](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.5) — 引导式学习（Guided Learning）基于聊天智能体循环重建，配备严格的按类型掌握度门槛与 `/learning` 仪表板，新增循环插件框架，并为 Partner 对话提供 Markdown 导出 / 保存至笔记本功能。
> **[2026.6.13]** [v1.4.4](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.4) — 可在安全门控后通过 `deeptutor skill install` 从 [ClawHub](https://clawhub.ai/) 安装社区技能，同时为知识库文件提供真实的浏览器内 DOCX/XLSX 预览。
> **[2026.6.12]** [v1.4.3](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.3) — TutorBot 在生产级 IM 管道上升级为 **Partners**（15 个频道、实时流式传输），Chat 迁移至单一智能体循环，实现真正的按用户隔离，并重建 Visualize。
> **[2026.5.28]** [v1.4.2](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.2) — 稳定性与体验优化：在 Visualize 和 Chat 中解除 Gemini 2.5+ 限制，认证路由修复（#485），流畅流式聊天体验，新增 Recents 侧边栏，以及 Lemonade 本地提供商支持。
> **[2026.5.27]** [v1.4.1](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.1) — 安全性与稳定性：收紧 TutorBot 工具沙箱，按用户资源隔离，多模态图像回退，为 TutorBots 提供 HTTP/SSE API，并修复 v1.4.0 聊天回归问题。
> **[2026.5.22]** [v1.4.0](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.0) — v1.4 正式版（GA）发布：Auto Mode、三层 Memory、智能体式 Deep Research / Solve / Question、LlamaIndex RAG 重构、Visualize/Animator 合并，以及重启安全的回合运行时。
> **[2026.5.21]** [v1.4.0-beta](https://github.com/HKUDS/DeepTutor/releases/tag/v1.4.0-beta) — 三层 Memory 工作台（L1/L2/L3），所有聊天能力基于单一智能体引擎重建，仅 LlamaIndex RAG，以及统一的 Settings + Capabilities 界面。
> **[2026.5.10]** [v1.3.10](https://github.com/HKUDS/DeepTutor/releases/tag/v1.3.10) — 远程 Docker CORS 恢复，`DISABLE_SSL_VERIFY` 覆盖各 SDK 提供商，更安全的代码块引用，以及可选 Matrix E2EE 插件。
> **[2026.5.9]** [v1.3.9](https://github.com/HKUDS/DeepTutor/releases/tag/v1.3.9) — TutorBot 支持 Zulip 与 NVIDIA NIM，更安全的思考模型路由，`deeptutor start`，侧边栏工具提示，以及会话存储一致性。
> **[2026.5.8]** [v1.3.8](https://github.com/HKUDS/DeepTutor/releases/tag/v1.3.8) — 可选多用户部署，配备隔离的用户工作区、管理员授权、认证路由，以及限定范围的运行时访问。
> **[2026.5.4]** [v1.3.7](https://github.com/HKUDS/DeepTutor/releases/tag/v1.3.7) — 思考模型/提供商修复，可见的 Knowledge 索引历史，以及更安全的 Co-Writer 清空/模板编辑。
> **[2026.5.3]** [v1.3.6](https://github.com/HKUDS/DeepTutor/releases/tag/v1.3.6) — 聊天与 TutorBot 的基于目录的模型选择，更安全的 RAG 重新索引，OpenAI Responses token 限制修复，以及 Skills 编辑器验证。
> **[2026.5.2]** [v1.3.5](https://github.com/HKUDS/DeepTutor/releases/tag/v1.3.5) — 更顺畅的本地启动设置，更安全的 RAG 查询，更简洁的本地 embedding 认证，以及 Settings 深色模式优化。
> **[2026.5.1]** [v1.3.4](https://github.com/HKUDS/DeepTutor/releases/tag/v1.3.4) — Book 页面聊天持久化与重建流程，聊天到 Book 引用，更强的语言/推理处理，RAG 文档提取加固。
> **[2026.4.30]** [v1.3.3](https://github.com/HKUDS/DeepTutor/releases/tag/v1.3.3) — NVIDIA NIM + Gemini embedding 支持，统一的 Space 上下文（聊天历史/技能/记忆），会话快照，RAG 重新索引弹性。
> **[2026.4.29]** [v1.3.2](https://github.com/HKUDS/DeepTutor/releases/tag/v1.3.2) — 透明的 embedding 端点 URL，针对无效持久化向量的 RAG 重新索引弹性，思考模型输出的记忆清理，Deep Solve 运行时修复。
> **[2026.4.28]** [v1.3.1](https://github.com/HKUDS/DeepTutor/releases/tag/v1.3.1) — 稳定性：更安全的 RAG 路由与 embedding 验证，Docker 持久化，IME 安全输入，Windows/GBK 健壮性。
> **[2026.4.27]** [v1.3.0](https://github.com/HKUDS/DeepTutor/releases/tag/v1.3.0) — 带重新索引工作流的版本化 KB 索引，重建 Knowledge 工作区，配备新适配器的 embedding 自动发现，以及 Space 中心。
> **[2026.4.25]** [v1.2.5](https://github.com/HKUDS/DeepTutor/releases/tag/v1.2.5) — 持久化聊天附件与文件预览抽屉，附件感知的能力管道，TutorBot Markdown 导出。
> **[2026.4.25]** [v1.2.4](https://github.com/HKUDS/DeepTutor/releases/tag/v1.2.4) — 文本/代码/SVG 附件，一键 Setup Tour，Markdown 聊天导出，紧凑 KB 管理 UI。
> **[2026.4.24]** [v1.2.3](https://github.com/HKUDS/DeepTutor/releases/tag/v1.2.3) — 文档附件（PDF/DOCX/XLSX/PPTX），推理思考块显示，Soul 模板编辑器，Co-Writer 保存至笔记本。
> **[2026.4.22]** [v1.2.2](https://github.com/HKUDS/DeepTutor/releases/tag/v1.2.2) — 用户自编写 Skills 系统，聊天输入性能大修，TutorBot 自动启动，Book Library UI，可视化全屏。
> **[2026.4.21]** [v1.2.1](https://github.com/HKUDS/DeepTutor/releases/tag/v1.2.1) — 分阶段 token 限制，所有入口点的重新生成回复，RAG 与 Gemma 兼容性修复。
> **[2026.4.20]** [v1.2.0](https://github.com/HKUDS/DeepTutor/releases/tag/v1.2.0) — Book Engine「活书」编译器，多文档 Co-Writer，交互式 HTML 可视化，Question Bank @-提及。
> **[2026.4.18]** [v1.1.2](https://github.com/HKUDS/DeepTutor/releases/tag/v1.1.2) — 由 Schema 驱动的 Channels 标签页，RAG 单管道整合，外置聊天提示词。
> **[2026.4.17]** [v1.1.1](https://github.com/HKUDS/DeepTutor/releases/tag/v1.1.1) — 通用「立即回答」，Co-Writer 滚动同步，统一设置面板，流式 Stop 按钮。
> **[2026.4.15]** [v1.1.0](https://github.com/HKUDS/DeepTutor/releases/tag/v1.1.0) — LaTeX 块级数学公式大修，LLM 诊断探测，Docker + 本地 LLM 指引。
> **[2026.4.14]** [v1.1.0-beta](https://github.com/HKUDS/DeepTutor/releases/tag/v1.1.0-beta) — 可书签化会话，Snow 主题，WebSocket 心跳与自动重连，embedding 注册表大修。
> **[2026.4.13]** [v1.0.3](https://github.com/HKUDS/DeepTutor/releases/tag/v1.0.3) — 带书签与分类的 Question Notebook，Visualize 中的 Mermaid，embedding 不匹配检测，Qwen/vLLM 兼容性，LM Studio 与 llama.cpp 支持，以及 Glass 主题。
> **[2026.4.11]** [v1.0.2](https://github.com/HKUDS/DeepTutor/releases/tag/v1.0.2) — 搜索整合与 SearXNG 回退，提供商切换修复，以及前端资源泄漏修复。
> **[2026.4.10]** [v1.0.1](https://github.com/HKUDS/DeepTutor/releases/tag/v1.0.1) — Visualize 能力（Chart.js/SVG），测验重复防护，以及 o4-mini 模型支持。
> **[2026.4.10]** [v1.0.0-beta.4](https://github.com/HKUDS/DeepTutor/releases/tag/v1.0.0-beta.4) — 带速率限制重试的 Embedding 进度跟踪，跨平台依赖修复，以及 MIME 验证修复。
> **[2026.4.8]** [v1.0.0-beta.3](https://github.com/HKUDS/DeepTutor/releases/tag/v1.0.0-beta.3) — 原生 OpenAI/Anthropic SDK（移除 litellm），Windows Math Animator 支持，健壮的 JSON 解析，以及完整中文 i18n。
> **[2026.4.7]** [v1.0.0-beta.2](https://github.com/HKUDS/DeepTutor/releases/tag/v1.0.0-beta.2) — 设置热重载，MinerU 嵌套输出，WebSocket 修复，以及 Python 3.11+ 最低要求。
> **[2026.4.4]** [v1.0.0-beta.1](https://github.com/HKUDS/DeepTutor/releases/tag/v1.0.0-beta.1) — 智能体原生架构重写（约 20 万行）：Tools + Capabilities 插件模型，CLI 与 SDK，TutorBot、Co-Writer、Guided Learning，以及持久化记忆。
> **[2026.1.23]** [v0.6.0](https://github.com/HKUDS/DeepTutor/releases/tag/v0.6.0) — 会话持久化，增量文档上传，灵活的 RAG 管道导入，以及完整中文本地化。
> **[2026.1.18]** [v0.5.2](https://github.com/HKUDS/DeepTutor/releases/tag/v0.5.2) — RAG-Anything 的 Docling 支持，日志系统优化，以及错误修复。
> **[2026.1.15]** [v0.5.0](https://github.com/HKUDS/DeepTutor/releases/tag/v0.5.0) — 统一服务配置、按知识库选择 RAG 流水线、题目生成重构与侧边栏自定义。
> **[2026.1.9]** [v0.4.0](https://github.com/HKUDS/DeepTutor/releases/tag/v0.4.0) — 多提供商 LLM 与 embedding 支持、新首页、RAG 模块解耦与环境变量重构。
> **[2026.1.5]** [v0.3.0](https://github.com/HKUDS/DeepTutor/releases/tag/v0.3.0) — 统一 PromptManager 架构、GitHub Actions CI/CD，以及 GHCR 预构建 Docker 镜像。
> **[2026.1.2]** [v0.2.0](https://github.com/HKUDS/DeepTutor/releases/tag/v0.2.0) — Docker 部署、Next.js 16 与 React 19 升级、WebSocket 安全加固与关键漏洞修复。
</details>
### 📰 新闻
- **2026-05-22** 🌐 官方文档站已在 [**deeptutor.info**](https://deeptutor.info/) 上线 — 指南、参考与能力导览，一站式呈现。
- **2026-04-19** 🎉 111 天内达成 20k stars！感谢大家对真正个性化、智能辅导的支持。
- **2026-04-10** 📄 我们的论文已在 arXiv 上线 — 阅读[预印本](https://arxiv.org/abs/2604.26962) 了解 DeepTutor 背后的设计与理念。
- **2026-02-06** 🚀 仅用 39 天即达成 10k stars！衷心感谢我们出色的社区。
- **2026-01-01** 🎊 新年快乐！加入我们的 [Discord](https://discord.gg/eRsjPgMU4t), [WeChat](https://github.com/HKUDS/DeepTutor/issues/78), 或 [Discussions](https://github.com/HKUDS/DeepTutor/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`**。
<details>
<summary><b>选项 1 — 从 PyPI 安装</b> · 完整本地 Web 应用 + CLI，无需克隆仓库</summary>
完整本地 Web 应用 + CLI，无需克隆仓库。需要 PATH 上有 **Python 3.11+** 与 **Node.js 20+** 运行时（打包的 Next.js standalone 服务器由 `deeptutor start` 启动）。
```bash
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](http://127.0.0.1:3782). 在该终端按 `Ctrl+C` 可同时停止后端与前端。快速试用可跳过 `deeptutor init`；应用将以默认端口与空模型设置启动，稍后在 **Settings → Models** 中配置。
</details>
<details>
<summary><b>选项 2 — 从源码安装</b> · 基于 checkout 开发</summary>
基于 checkout 开发。请使用 **Python 3.11+** 与 **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
```
源码安装会在本地 `web/` 目录以 dev 模式运行 Next.js；其余（配置布局、端口、用 `Ctrl+C` 停止）与选项 1 相同。
<details>
<summary><b>Conda 环境</b>（替代 <code>venv</code>）</summary>
```bash
conda create -n deeptutor python=3.11
conda activate deeptutor
python -m pip install --upgrade pip
```
</details>
<details>
<summary><b>可选安装 extras</b> — dev / partners / matrix / math-animator</summary>
```bash
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
```
</details>
<details>
<summary><b>前端依赖调整与开发服务器排障</b></summary>
**修改前端依赖：** 运行 `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
```
</details>
</details>
<details>
<summary><b>选项 3 — Docker</b> · 单容器自包含部署</summary>
单容器运行完整 Web 应用。镜像位于 GitHub Container Registry：
- `ghcr.io/hkuds/deeptutor:latest` — 稳定版
- `ghcr.io/hkuds/deeptutor:pre` — 预发布版（如有）
> 关于 podman/rootless/read-only-rootfs 部署及完整分步安装指南，请参阅 [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`。** 浏览器仅与前端 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](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` 设为前端服务器用于访问后端的内网地址（该值仅在服务端读取，不会发送给浏览器）。
```json
{
"next_public_api_base": "http://backend:8001"
}
```
`next_public_api_base_external`（及其别名 `public_api_base`）可作为优先级较低的回退项。CORS 使用前端 **origins**，而非 API URL。禁用身份验证时，DeepTutor 默认允许常规 HTTP/HTTPS 浏览器 origin。启用身份验证时，需添加精确的前端 origin：
```json
{
"cors_origins": ["https://deeptutor.example.com"]
}
```
<details>
<summary><b>连接宿主机上的 Ollama / LM Studio / llama.cpp / vLLM / Lemonade</b></summary>
在 Docker 内，`localhost` 指向容器自身，而非宿主机。要访问运行在宿主机上的模型服务，请使用 host gateway（推荐）：
```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 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](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](./CONTAINERIZATION.md)）。
</details>
</details>
<details>
<summary><b>选项 4 — 仅 CLI</b> · 无 Web UI，从源码检出安装</summary>
当你不需要 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/` 布局，但会跳过后端/前端端口提示，并将 embeddings 默认设为**关闭**（若计划使用 `deeptutor kb …` 或 RAG 工具，请选择 `Yes`）。它仍会写入完整的运行时布局（`system.json`、`auth.json`、`integrations.json`、`model_catalog.json`、`main.yaml`、`agents.yaml`），并仍会提示选择当前 LLM 提供商和模型。
<details>
<summary><b>常用命令</b></summary>
```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
```
</details>
本地 `deeptutor-cli` 安装不包含 Web 资源或服务器依赖。请保留源码检出 — 可编辑安装会指向它。若日后要添加 Web 应用，请安装 PyPI 包（选项 1），并在同一工作区中运行 `deeptutor init` + `deeptutor start`。
</details>
<details>
<summary><b>代码执行沙箱（office skills）</b> · 运行模型生成的 docx / pdf / pptx / xlsx 代码</summary>
内置 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 将无法再生成文件。
</details>
<details>
<summary><b>配置参考</b> — <code>data/user/settings/</code> 下的配置文件（JSON/YAML）</summary>
`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 配置。
</details>
## 📖 探索 DeepTutor
从日常会使用的主要界面入手：Chat、Partners、My Agents、Co-Writer、Book、Knowledge Center、Learning Space、Memory 和 Settings。随后介绍 Multi-User 部署，用于共享、隔离的工作区。
<div align="center">
<img src="assets/figs/web-1.4.6+/OVERVIEW.png" alt="DeepTutor 主页 — 侧边栏包含所有界面的 Chat 工作区" width="900">
</div>
<details>
<summary><b>🏗️ 系统架构</b></summary>
<div align="center">
<img src="assets/figs/system/system%20architecture.png" alt="DeepTutor 系统架构" width="900">
</div>
</details>
<details>
<summary><b>💬 Chat — 你实际使用的 Agent 循环</b></summary>
Chat 是默认能力，也是大多数工作的起点。单个会话可以正常对话、调用工具、基于所选知识库进行 grounding、读取附件、生成图像、咨询 subagent、写入 notebook 记录，并在多轮对话中保持相同上下文。
<div align="center">
<img src="assets/figs/web-1.4.6+/home/00-overview.png" alt="DeepTutor Chat 工作区" width="900">
</div>
该循环刻意保持简单：模型分轮思考，在有用时调用工具，观察结果，最后以一条无工具消息结束。`ask_user` 很特殊 — 代理无需猜测，可以暂停当前轮次、提出结构化澄清问题，并在你回答后继续。
<div align="center">
<img src="assets/figs/system/chat-agent-loop.png" alt="DeepTutor chat agent loop" width="900">
</div>
用户可切换的工具包括 `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（精通路径）** 用于学习计划流程。
</details>
<details>
<summary><b>🤝 Partner — 同一大脑上的持久伙伴</b></summary>
<div align="center">
<img src="assets/figs/web-1.4.6+/partners/00-partners%20overview.png" alt="DeepTutor partners workspace" width="900">
</div>
Partners（伙伴）是持久陪伴，各自拥有灵魂、模型策略、资料库、记忆与通道。它们并非独立的机器人引擎：每一条入站 Web 或 IM 消息，都会变成伙伴作用域工作区内的一次普通 `ChatOrchestrator` 轮次。伙伴就是「带有性格和电话号码的聊天」。
<div align="center">
<img src="assets/figs/system/partners-architecture.png" alt="DeepTutor partners architecture" width="900">
</div>
每个伙伴拥有 `SOUL.md`、模型选择、通道、工具策略以及分配的资料库。知识库、技能和笔记本会复制到 `data/partners/<id>/workspace/`，因此同样的 RAG、技能、笔记本和记忆工具无需特殊分支即可工作。伙伴可读其所有者的记忆，但只写入自己的记忆。
<div align="center">
<img src="assets/figs/web-1.4.6+/partners/02-IM%20config%20for%20each%20partner.png" alt="Per-partner IM channel configuration" width="900">
</div>
通道层由 schema 驱动，可按已安装的 extras 与已配置凭证连接到 Feishu、Telegram、Slack、Discord、DingTalk、QQ/NapCat、WeCom、WhatsApp、Zulip、Mattermost、Matrix、Mochat 和 Microsoft Teams 等 IM 平台。伙伴也可作为子智能体接入，并在普通聊天轮次中被咨询——详见下方 **My Agents**。
</details>
<details>
<summary><b>🧑‍🚀 My Agents — 咨询与导入其他智能体</b></summary>
<div align="center">
<img src="assets/figs/web-1.4.6+/myagents/00-overview.png" alt="DeepTutor My Agents workspace" width="900">
</div>
My Agents 将其他智能体变成 DeepTutor 的上下文，并完成两件不同的事。**连接在线智能体**——本机上的 Claude Code 或 Codex CLI，或你的某个 Partner——并在聊天轮次内咨询它：DeepTutor 会实际*运行*对方智能体，并通过 `consult_subagent` 工具将其工作流式传输到 Activity（活动）面板。用 Agent 芯片选择（或输入 `@`），并设置本次咨询可进行的轮数。
<div align="center">
<img src="assets/figs/web-1.4.6+/home/08-subagent%20demo%20with%20claude%20code.png" alt="Consulting a Claude Code subagent live" width="900">
</div>
**导入过往对话**——将你已有的 Claude Code 与 Codex 历史导入为可命名、可搜索、可恢复的智能体。选择要导入的日期；刷新会重新同步。可在任意聊天轮次通过 `+` → My Agents 引用已导入的对话，DeepTutor 将其作为第三方转写读取——它仍是*对方的*对话，而非 DeepTutor 自己的声音。
</details>
<details>
<summary><b>✍️ Co-Writer — 感知选区的 Markdown 起草</b></summary>
<div align="center">
<img src="assets/figs/web-1.4.6+/co-writer/00-overview.png" alt="DeepTutor Co-Writer workspace" width="900">
</div>
Co-Writer 是面向报告、教程、笔记与长篇学习产物的分栏 Markdown 工作区。文档会自动保存并渲染实时预览（KaTeX 公式、diagram 围栏代码块），当草稿成为可复用上下文时，也可回存到笔记本。
<div align="center">
<img src="assets/figs/web-1.4.6+/co-writer/01-edit%20panel.png" alt="Co-Writer editor with live preview" width="900">
</div>
其核心思路是**精准编辑**：选中一段文字，请 DeepTutor 改写、扩展或压缩。编辑智能体可将修改锚定到知识库或网页证据，保留工具调用轨迹，并以 accept/reject diff 展示每一处变更——在你批准前，不会写入任何内容。
</details>
<details>
<summary><b>📖 Book — 由你的材料生成的活书</b></summary>
<div align="center">
<img src="assets/figs/web-1.4.6+/book/00-book_overview.png" alt="DeepTutor book library" width="900">
</div>
Book 将所选来源转化为交互式**活书**——不是静态 PDF，而是由类型化块构成的阅读环境。一本书可从知识库、笔记本、题库或聊天记录起步；创建流程会先提出章节大纲再生成内容，让你审阅结构，而不是接受盲目的一次性输出。
<p align="center">
<img src="assets/figs/web-1.4.6+/book/01-book-demo-quiz%20card.png" alt="Book quiz block" width="31%">
&nbsp;
<img src="assets/figs/web-1.4.6+/book/02-book-demo-manim%20video.png" alt="Book Manim animation block" width="31%">
&nbsp;
<img src="assets/figs/web-1.4.6+/book/03-book-demo%20interactive%20module.png" alt="Book interactive widget block" width="31%">
</p>
每一章会编译为类型化块——文本、提示框、测验、闪卡、时间线、代码、图示、交互 HTML、动画、概念图、深度解读与用户笔记——且每一页都有自己的 Page Chat（页内对话）。块可编辑：插入、移动、重新生成，或切换块类型而无需重写整章。维护命令如 `deeptutor book health` 和 `deeptutor book refresh-fingerprints` 有助于检测源知识是否已与编译后的页面发生偏离。
</details>
<details>
<summary><b>📚 Knowledge Center — 多引擎 RAG 资料库</b></summary>
<div align="center">
<img src="assets/figs/web-1.4.6+/knowledge/00-overview.png" alt="DeepTutor Knowledge Center" width="900">
</div>
知识库是 RAG 背后的文档集合——为 Chat 轮次、Co-Writer 编辑、Book 生成与 Partner 对话提供依据。其独特之处在于**可选择检索引擎**：**LlamaIndex**（默认，本地向量 + BM25）、**PageIndex**（托管，带页级引用的推理检索）、**GraphRAG** 与 **LightRAG**（知识图谱检索）、**LightRAG Server**（将检索卸载到你通过 HTTP 连接的外部 LightRAG 实例），或链接的 **Obsidian** 仓库（导师就地读写）。每个知识库绑定一个引擎。
<div align="center">
<img src="assets/figs/web-1.4.6+/knowledge/01-create%20knowledge%20base.png" alt="Create a knowledge base" width="900">
</div>
创建知识库时，你可以**新建**（上传文档并构建全新索引）或**链接已有**（复用在他处构建的索引，就地读取且无需重建索引）。重建索引会写入新的扁平 `version-N` 目录并保留旧目录，因此重建过程中不会销毁仍在使用的索引。即使在 **error**（错误）状态的库中，也可单独移除一份文档——删除解析失败的文件而无需完整删除并重建。文档解析——仅文本、MinerU、Docling、markitdown 或 PyMuPDF4LLM——在 **Settings → Knowledge Base** 中选择，本地模型下载默认关闭。CLI 通过 `deeptutor kb list`、`info`、`create`、`add`、`search`、`set-default` 和 `delete` 镜像完整生命周期。
</details>
<details>
<summary><b>🌐 Learning Space — 技能、人设与可复用上下文</b></summary>
<div align="center">
<img src="assets/figs/web-1.4.6+/learning-space/00-overview.png" alt="DeepTutor Learning Space hub" width="900">
</div>
Learning Space 是资料库与个性化层——持久化内容存放于此。**Conversations & Materials**（对话与资料）保存你的聊天记录、笔记本和题库（每道已保存的题目会保留你的答案、参考答案和解析）。**Personalization**（个性化）保存掌握路径、人设（行为预设，如 *peer*、*research-assistant*、*teacher*）以及技能（模型按需读取的 `SKILL.md` 剧本）。此处一切内容均可从 Chat、Partners、Co-Writer 和 Book 复用。
<div align="center">
<img src="assets/figs/web-1.4.6+/learning-space/07-%20download%20skills%20from%20eduhub.png" alt="Import skills from EduHub" width="900">
</div>
你不必亲自编写每一项技能——**Import from EduHub**（从 EduHub 导入）可浏览社区目录，并通过安全网关将技能直接下载到你的资料库（参见 [Ecosystem](#-ecosystem--eduhub--the-skills-community)）。
</details>
<details>
<summary><b>🧠 Memory — 可检视的个性化</b></summary>
<div align="center">
<img src="assets/figs/web-1.4.6+/memory/00-overview.png" alt="DeepTutor memory overview" width="900">
</div>
Memory 是基于文件的三层系统，可读、可整理、可审计——刻意*不是*隐藏的向量存储。**L1** 是工作区镜像加上仅追加的事件轨迹（`trace/<surface>/<date>.jsonl`）；**L2** 是按界面整理的要点（`L2/<surface>.md`）；**L3** 是跨界面综合（`L3/<profile|recent|scope|preferences>.md`）。由于 L2 引用 L1、L3 引用 L2，你档案中的每一项都有据可查。
<div align="center">
<img src="assets/figs/web-1.4.6+/memory/01-3%20layer%20memory%20graph.png" alt="DeepTutor memory graph" width="900">
</div>
Memory Graph（记忆图谱）展示完整金字塔——中心为 L3 综合，中间环为 L2，外围为 L1 轨迹——因此你可以将任何综合结论追溯到其背后的原始事件。Memory 在 `chat`、`notebook`、`quiz`、`kb`、`book`、partner 以及 `cowriter` 界面上持续追踪；整合器的 Update / Audit / Dedup 预算在 **Settings → Memory** 中调整。
</details>
<details>
<summary><b>⚙️ Settings — 统一控制平面</b></summary>
<div align="center">
<img src="assets/figs/web-1.4.6+/settings/00-setting%20overview.png" alt="DeepTutor settings hub" width="900">
</div>
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**（整合器预算）。
<div align="center">
<img src="assets/figs/web-1.4.6+/settings/01-appearance%20settings.png" alt="DeepTutor appearance settings and themes" width="900">
</div>
多数区块采用草稿-应用流程，便于在正式提交前测试提供商。内置四种主题——Default、Cream、Dark 和 Glass。项目根目录的 `.env` 文件会被刻意忽略；运行时配置位于 `data/user/settings/*.json` 下，除非 `DEEPTUTOR_HOME` 或 `deeptutor start --home` 将应用指向其他位置。
</details>
<details>
<summary><b>👥 Multi-User — 共享部署</b> · 可选认证，按用户隔离工作区</summary>
认证**默认关闭**——DeepTutor 以单用户模式运行。开启后，一个 `data/` 树同时托管管理员工作区、按用户隔离的工作区以及 partner 工作区：
```text
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` 为空，除非你已接入外部用户存储。
</details>
## ⌨️ DeepTutor CLI — 面向代理的原生接口
一个 `deeptutor` 二进制，两种入口：供终端用户使用的交互式 **REPL**，以及供其他将 DeepTutor 作为工具驱动的代理使用的结构化 **JSON**。两种方式具备相同的能力、工具和知识库。
<details>
<summary><b>自行驱动</b></summary>
`deeptutor chat` 打开交互式 REPL；`deeptutor run <capability> "<message>"` 执行单轮后退出。两者使用相同的 `--capability`、`--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
```
Web 应用的一切功能这里都有——知识库（`kb`）、会话（`session`）、partners（`partner`）、技能（`skill`）、笔记本、memory 和配置。完整列表见下文。
</details>
<details>
<summary><b>让代理驱动</b></summary>
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)——约 150 行的交接文档，可让任意具备工具调用能力的 LLM 一次读完整个界面。可交给 Claude Code、Codex 或 OpenCode（它们会自动加载 `SKILL.md`），或将 `deeptutor run` 封装为 LangChain / AutoGen 循环中的工具。完整配方：[Agent Handoff](https://deeptutor.info/docs/cli/agent-handoff/).
</details>
<details>
<summary><b>命令参考</b></summary>
| 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 认证会话） |
</details>
<details>
<summary><b>仅 CLI 分发版</b></summary>
仅 CLI 包位于 `packaging/deeptutor-cli`。在本检出版本中，请从源码安装：
```bash
python -m pip install -e ./packaging/deeptutor-cli
```
该包尚未发布到 PyPI，因此主 [入门指南](#-get-started) 部分仍保留从源码安装的路径。
</details>
## 🧩 生态系统 — EduHub 与 Skills 社区
DeepTutor 技能采用开放的 **Agent-Skills** 格式 — 一个包含 `SKILL.md` playbook（YAML frontmatter + Markdown）及可选参考文件的文件夹。该格式并非 DeepTutor 专属，因此任何支持此格式的注册表都可作为你的技能库来源。DeepTutor 内置 **[EduHub](https://eduhub.deeptutor.info/)** — 我们自有的教育导向技能注册表 — 作为默认 hub 接入。
<details>
<summary><b>EduHub — DeepTutor 的技能生态系统</b></summary>
[**EduHub**](https://eduhub.deeptutor.info/) 是 DeepTutor 为分享教学导向 agent 技能而推出的社区 hub — 包括苏格拉底式导师、闪卡生成器、作文反馈、考试蓝图、概念讲解器等。它已内置在 DeepTutor 中，无需额外配置：裸 slug 或 `eduhub:` 前缀即可解析到该 hub。
**查找并安装** — 在浏览器中，打开 **Learning Space → Skills → Import from 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 的 agent（Claude Code、Codex 等）可通过 `eduhub` CLI — `npx eduhub install socratic-tutor` 直接使用。
</details>
<details>
<summary><b>导入安全门控</b></summary>
无论来源如何，每次导入在触及工作区之前都会经过**同一套安全门控**：
- 首先检查注册表的**安全裁决（security verdict）** — 被标记的包会被拒绝，除非你传入 `--allow-unverified`；
- 归档文件以防御方式解压（zip-slip / zip-bomb 防护），并受文本/脚本**后缀白名单**约束，因此二进制文件永远不会进入工作区；
- frontmatter 会规范化为 DeepTutor 的 schema，且 `always:` 会被**剥离**，因此下载的技能无法强制写入每个系统 prompt；
- 来源信息 — hub、版本、裁决和安装时间 — 会写入 `.hub-lock.json`，供审计与更新使用。
在多用户部署中，安装仅限管理员：新技能会进入管理员目录，在其他用户被授予访问权限之前对其他用户不可见，管理员可在推广前先行审查。
</details>
<details>
<summary><b>亦兼容 ClawHub</b></summary>
由于 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"` 封装各注册表自带的 fetch CLI，`"default"` 用于选择裸 slug 所使用的 hub。它们都汇入同一导入门控。
</details>
## 🌐 社区
### 📮 联系方式
DeepTutor 是由 [Bingxi Zhao](https://github.com/pancacake) 在 [HKUDS](https://github.com/HKUDS) 小组内主导的开源项目，并以**完全开源**的形式与社区共同迭代。截至目前，我们**没有**任何形式的付费在线产品。欢迎通过 **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) | 超轻量 agent 引擎，为原始 TutorBot 提供动力 *(HKUDS)* |
| [**LightRAG**](https://github.com/HKUDS/LightRAG) | 简洁快速的 RAG *(HKUDS)* |
| [**AutoAgent**](https://github.com/HKUDS/AutoAgent) | 零代码 agent 框架 *(HKUDS)* |
| [**AI-Researcher**](https://github.com/HKUDS/AI-Researcher) | 自动化研究流水线 *(HKUDS)* |
| [**OpenClaw**](https://github.com/openclaw/openclaw) | ClawHub 背后的开放 agent 网关与技能生态系统 |
| [**Codex**](https://github.com/openai/codex) | 启发我们 CLI 工作流的 agent 原生编码 CLI |
| [**Claude Code**](https://github.com/anthropics/claude-code) | 启发 DeepTutor agent 循环的 agentic 编码 CLI |
| [**ManimCat**](https://github.com/Wing900/ManimCat) | 为 Math Animator 提供 AI 驱动的数学动画生成 |
### 🗺️ 路线图与贡献
我们希望 DeepTutor 持续迭代改进 — 并最终成为回馈开源社区的礼物。我们的 [**路线图**](https://github.com/HKUDS/DeepTutor/issues/498) 会持续更新；可在那里为条目投票或提出新建议。如需贡献，请参阅 [**贡献指南**](CONTRIBUTING.md) 了解分支策略、编码规范与入门方式。
<div align="center">
我们希望 DeepTutor 能成为献给社区的礼物。🎁
<a href="https://github.com/HKUDS/DeepTutor/graphs/contributors">
<img src="https://contrib.rocks/image?repo=HKUDS/DeepTutor&max=999" alt="Contributors" />
</a>
</div>
<div align="center">
<a href="https://www.star-history.com/#HKUDS/DeepTutor&type=timeline&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=HKUDS/DeepTutor&type=timeline&theme=dark&legend=top-left" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=HKUDS/DeepTutor&type=timeline&legend=top-left" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=HKUDS/DeepTutor&type=timeline&legend=top-left" />
</picture>
</a>
</div>
<p align="center">
<a href="https://www.star-history.com/hkuds/deeptutor">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" />
<img alt="Star History Rank" src="https://api.star-history.com/badge?repo=HKUDS/DeepTutor" />
</picture>
</a>
</p>
<div align="center">
根据 [Apache License 2.0](LICENSE) 许可发布。
<p>
<img src="https://visitor-badge.laobi.icu/badge?page_id=HKUDS.DeepTutor&style=for-the-badge&color=00d4ff" alt="Views">
</p>
</div>
Reference in New Issue View Git Blame Copy Permalink