DeepTutor：终身个性化辅导

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

🤝 我们欢迎任何形式的贡献！在 Roadmap 上为路线图条目投票或提出新的条目，并查看贡献指南了解分支策略、编码规范和入门方式。

📦 发布版本#

[2026.10.28] v1.7.0 —— 模块化安装、焕新的学习工作区、带 Dito 的块状笔记本、带旁白的视频课程、可续跑的嵌入检查点，以及更可靠的辅导。

过去的版本（一周以前）

[2026.10.19] v1.6.15 —— 可评审的学习路径改动、分组测评、有界的辅导记忆、可靠的聊天恢复、更稳健的解析、检索对比，以及原生 Gemini 语音。

[2026.10.8] v1.6.14 —— 基于原始来源的可视化练习、可恢复的索引、统一的视频阅读、科研工具、受管理的插件、学习日志，以及服务商配置改进。

[2026.10.4] v1.6.13 —— 阅读与听力改进、题库练习、有韧性的文档解析、可配置的语音、工作区可见的附件、波兰语，以及新的服务商。

[2026.9.27] v1.6.12 —— 工作区知识库迁移、Kiwix 归档、来源图片、任务看板、德语界面，以及聊天恢复。

[2026.9.24] v1.6.11 —— 法语和乌克兰语界面、带聊天内选择操作的阅读文件夹、发送给视觉模型的图表、分页的 Office 预览，以及自同步的知识库。

[2026.9.22] v1.6.10 —— 原生 LightRAG 角色模型、会记录并强制「由什么构建」的已发布索引、跟随你解析引擎的 PDF 附件、可见的截断，以及不过滤的服务商选择。

[2026.9.21] v1.6.9 —— 基于文件夹的学习工作区、每日练习、重新设计的设置、更清晰的流式对话、持久的用量记账，以及可恢复的归档与明确的永久删除。

[2026.9.14] v1.6.8 —— 已删除聊天的回收站、跨整个会话历史的搜索、一个能越过知识库向外看的工具，以及一批针对「静默失败」的修复。

[2026.9.11] v1.6.7 —— 修复版：书籍只出现一个空章节、测验什么都没生成、模型的草稿混进正文、公式原样打印、卡片无法提交。

[2026.9.8] v1.6.6 —— 修复版：无法提交的答案、说谎的复制按钮、面向 Partner 的连接知识库、Docker 内的 Codex 登录，以及轻了 100 KB 的首页路由。

[2026.9.6] v1.6.5 —— 可以指向任意文件夹的内容工作区、面向所有语言的单一 exec 工具、会对其工具设门的 Mastery Path 模式，以及为就绪状态打分的设置。

[2026.9.3] v1.6.4 —— 更快的隔离运行时、可控的书籍生成、来源完整的 Mastery 路径与 Chat 移交、持久的阅读、统一的活动界面、可恢复的会话，以及显式的逐模型 API 能力。

[2026.9.2] v1.6.3 —— 破坏性的前后端重构、严格的规范路由与可恢复的流，另有学习者／监护人账号、有据可依的阅读、WeKnora、更广的解析、Python 3.14，以及 DashScope 媒体。

[2026.8.31] v1.6.2 —— 沉浸式 YouTube 学习、由插件驱动的 Visualize 目录、三个新的智能体宿主、更安全的阅读引用、多格式 MinerU、实时的 Partner 频道状态，以及引导式更新。

[2026.8.30] v1.6.1 —— 一个厂商密钥关联到它所服务的每项服务、用于后台工作的任务模型、作为可搜索导航器的设置、可自行安排的侧边栏，以及官方的 LightRAG。

[2026.8.27] v1.6.0 —— 忠实的 EPUB 阅读与标注、带 Little Tutor 和 Ask Questions 的 Courses、有界的网络来源同步、共享但学习状态私有的书籍，以及 Serply／原生搜索。

[2026.8.25] v1.5.17 —— 每个成员各自拥有的 Partner，带私密对话和可关联的聊天账号、把 GitHub 仓库作为知识来源、Antigravity CLI、浏览器微信扫码登录，以及 deeptutor doctor。

[2026.8.22] v1.5.16 —— 可连接的 MarginNote 4 库及其插件填充、可再次翻动的书籍页面，以及不再在网关后面出错的工具调用 id、嵌入和温度上限。

[2026.8.20] v1.5.15 —— 可自托管的 PageIndex 开源版与推理式检索、终于能归档进去的题库、第三方工具／能力插件，以及 Apache Tika 解析。

[2026.8.19] v1.5.14 —— 沉浸式阅读：文档在对话旁边打开、逐页引用；DeepTutor 从聊天中自我配置；可浏览并可写入的 IMA 库；笔记本控制台。

[2026.8.17] v1.5.13 —— 书籍在编译时即可流式查看、跟踪你的进度并导出为 Markdown；在你批准目录骨架前给出成本估算；首页的起步建议来自记忆。

[2026.8.13] v1.5.12 —— 用六个新服务商（豆包、博查、智谱、Firecrawl、千帆、阿里云 IQS）重建的网络搜索、LiteParse 解析引擎、在凭证变化时重连的 MCP 服务器，以及 CodeBuddy + OrcaRouter。

[2026.8.10] v1.5.11 —— DSML 工具调用周围的正文不再消失、被截断的回复会继续而不是就此结束、设置中显示实时内存占用，以及移出事件循环的 LightRAG 索引。

[2026.8.7] v1.5.10 —— 每个账号登录到自己的 Codex、模型输出语言成为独立设置、空工具调用被拒绝而不是重试，以及上传不再阻塞事件循环。

[2026.8.4] v1.5.9 —— 在原生端点上使用 Gemini Embedding 2、逐模型的推理强度控制、Novita AI 网关、查询的检索角色，以及会保留整个 data/ 的 Compose 部署。

[2026.8.2] v1.5.8 —— 内存：为开发服务器设定真正的堆上限、源码安装提供生产构建、有界的 LLM 客户端与索引缓存，以及针对偶发 500 的 keep-alive 修复。

[2026.7.31] v1.5.7 —— 按账号的 MCP Services 存储、辅导器可运行的 101 个 CLI 应用、移出沙箱触达范围的凭证，以及移动端布局。

[2026.7.29] v1.5.6 —— 远程 Codex 登录可在 SSH 隧道后完成、生成的文件在 Activity 中有自己的卡片、非英语语言不再坍缩为中文，以及书籍创建不再超时。

[2026.7.26] v1.5.5 —— 通过 OpenAI Codex OAuth 使用你的 ChatGPT 套餐登录、Eden AI 服务商、会报告自己所含内容的知识库、可追溯的 RAG 引用，以及无需变通做法的 GraphRAG 索引。

[2026.7.24] v1.5.4 —— 维护性清理：回答后「正在生成」的卡顿消失、IM Partner 忠实渲染 Markdown 表格、LLM JSON 解析更稳健，另有测验、创建知识库表单和 Math Animator 的修复。

[2026.7.24] v1.5.3 —— 可主题化的代码块、My Agents 中新增四个编程 CLI（Gemini、Kimi、opencode、MiMo）、Atlas Cloud LLM 服务商，以及一次覆盖聊天、记忆、嵌入和解析的广泛可靠性清理。

[2026.7.19] v1.5.2 —— 可配置的聊天附件上限、通过智能体工具调用跨文档推理的 PageIndex 检索、更广的 Anthropic／OpenAI 模型支持，以及更稳的书籍、知识库和聊天界面。

[2026.7.9] v1.5.1 —— 从知识库中移除单个失败的文档——即使是卡在错误状态的——而不必删除并重建整个库。

[2026.7.4] v1.5.0 —— LlamaIndex 摄取现在遵循你的文档解析引擎并支持多模态图片提取、Partner 与 Soul 的 id 对非拉丁名称保持 URL 安全，以及可选的 RAG 附加组件能在 Python 3.14+ 上干净安装。

[2026.6.30] v1.4.15 —— Partner 的原生 Mattermost 频道，另有修复让 Guided Learning 的多选题正确评分，并让配置为零的分块重叠被遵守。

[2026.6.29] v1.4.14 —— 点一下已分配的 Partner 即可一步进入聊天、Deep Research 会标记不完整的报告、LightRAG 无需 MinerU 也能索引、FAISS 支持非 ASCII 路径，以及 PocketBase 会话按用户隔离。

[2026.6.27] v1.4.13 —— Partner 支持非拉丁名称并可分配给用户、登录后 logo 正常渲染（#599）、极小的知识库也能可靠检索，以及容器在无根 Podman 下干净启动。

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

[2026.6.23] v1.4.11 —— 每个云端 OpenAI 兼容服务商都支持原生工具调用、重新设计的管理员 Users 页面、测验选项中的 LaTeX、诚实的会话加载指示器，以及可配置的容器主机绑定。

[2026.6.21] v1.4.10 —— 带头像的自助 Profile 页面、面向无根环境的容器指南与单端口请求时代理，以及面向非管理员用户的默认拒绝 MCP 工具。

[2026.6.19] v1.4.9 —— 设置打磨：Search 只显示你的服务商需要的字段、连接配置可重命名并按服务商自动命名，以及评分后的 Mastery Path 题目流入题目库。

[2026.6.18] v1.4.8 —— 在 My Agents 下连接你自己的 Partner，并在聊天中实时咨询——通过它们自己的人格、资料库和技能作答——每个都有自己的私密记忆。

[2026.6.18] v1.4.7 —— 连接你本地的 Claude Code / Codex 并在回合中实时咨询、My Agents 升级为顶层的 /agents，以及 Partner 对话获得分支／恢复／删除与可重放的轨迹。

[2026.6.17] v1.4.6 —— 四界面整合：带可导入 My Agents 和顶层 Memory 的 Space 学习仪表盘、带 GraphRAG / PageIndex / LightRAG / 关联知识库 / Obsidian 的知识中心、开放的设置，以及逐模型的能力门控。

[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 变为 Partners，建立在生产级 IM 管道上（15 个通道、实时流式）、Chat 迁到单一智能体循环、真正的按用户隔离，以及重建的 Visualize。

[2026.5.28] v1.4.2 —— 稳定性与打磨：在 Visualize 和 Chat 中解锁 Gemini 2.5+、认证路由修复（#485）、平滑流式的聊天体验、Recents 侧边栏，以及 Lemonade 本地服务商支持。

[2026.5.27] v1.4.1 —— 安全与稳定：TutorBot 工具沙箱加固、按用户的资源隔离、多模态图片回退、面向 TutorBot 的 HTTP/SSE API，以及 v1.4.0 的聊天回归修复。

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

[2026.5.21] v1.4.0-beta —— 三层 Memory 工作台（L1/L2/L3）、每个聊天能力重建在单一智能体引擎上、仅用 LlamaIndex 的 RAG，以及统一的设置 + 能力界面。

[2026.5.10] v1.3.10 —— 远程 Docker CORS 恢复、跨 SDK 服务商的 DISABLE_SSL_VERIFY、更安全的代码块引用，以及可选的 Matrix 端到端加密附加组件。

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

[2026.5.8] v1.3.8 —— 可选的多用户部署，带隔离的用户工作区、管理员授权、认证路由和受限的运行时访问。

[2026.5.4] v1.3.7 —— 思考模型／服务商修复、可见的知识索引历史，以及更安全的 Co-Writer 清空／模板编辑。

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

[2026.5.2] v1.3.5 —— 更顺滑的本地启动设置、更安全的 RAG 查询、更干净的本地嵌入认证，以及设置的深色模式打磨。

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

[2026.4.30] v1.3.3 —— 支持 NVIDIA NIM + Gemini 嵌入、聊天历史／技能／记忆的统一 Space 上下文、会话快照、RAG 重建索引的韧性。

[2026.4.29] v1.3.2 —— 透明的嵌入端点 URL、针对无效持久化向量的 RAG 重建韧性、思考模型输出的记忆清理、Deep Solve 运行时修复。

[2026.4.28] v1.3.1 —— 稳定性：更安全的 RAG 路由与嵌入校验、Docker 持久化、输入法安全输入、Windows／GBK 稳健性。

[2026.4.27] v1.3.0 —— 带重建流程的版本化知识库索引、重建的知识工作区、带新适配器的嵌入自动发现、Space 中心。

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

[2026.4.25] v1.2.4 —— 文本／代码／SVG 附件、一条命令的 Setup Tour、Markdown 聊天导出、紧凑的知识库管理界面。

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

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

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

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

[2026.4.18] v1.1.2 —— 模式驱动的 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 心跳与自动重连、嵌入注册表大改。

[2026.4.13] v1.0.3 —— 带书签与分类的题目笔记本、Visualize 中的 Mermaid、嵌入不匹配检测、Qwen／vLLM 兼容性、LM Studio 与 llama.cpp 支持，以及 Glass 主题。

[2026.4.11] v1.0.2 —— 带 SearXNG 回退的搜索整合、服务商切换修复，以及前端资源泄漏修复。

[2026.4.10] v1.0.1 —— Visualize 能力（Chart.js/SVG）、测验去重，以及 o4-mini 模型支持。

[2026.4.10] v1.0.0-beta.4 —— 带限流重试的嵌入进度跟踪、跨平台依赖修复，以及 MIME 校验修复。

[2026.4.8] v1.0.0-beta.3 —— 原生 OpenAI／Anthropic SDK（去掉 litellm）、Windows 上的 Math Animator 支持、稳健的 JSON 解析，以及完整中文本地化。

[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 与嵌入支持、新首页、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 安全加固，以及严重漏洞修复。

✨ v1.7.0 已上线。pip install -U "deeptutor[full]" 安装完整 Web 应用与 CLI；只写 deeptutor 则只安装核心。旧版 CLI 安装的升级步骤见下文。

📰 新闻#

2026-09-20 🎉 九个月 40k stars！我们会继续扩展 DeepTutor 的学习生态。

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、微信或 Discussions——一起塑造 DeepTutor。

2025-12-29 🎓 DeepTutor 正式发布！

✨ 核心特性#

DeepTutor 是一个智能体原生的学习工作区，把辅导、解题、测验生成、研究、可视化和掌握度练习连接在一个可扩展的系统里。

每种模式共用一套运行时 —— Chat、Ask Questions、Quiz、Research、Visualize、Solve、Mastery Path、沉浸式阅读和 Audio Overview 共用同一套能力运行时与会话上下文，同时保留各自专门构建的循环和管道。

任务看板（Task Board） —— 在 To do、In progress 和 Done 中跟踪学习任务，带笔记、拖放或键盘可访问的移动按钮，以及可从中恢复的归档。卡片留在当前工作区，并遵循现有的外观和语言设置；无需配置模型。

连接的学习上下文 —— 知识库、书籍、学习笔记本页面、收藏、题库、人格和 Memory 可以在支持它们的工作流之间复用，受账号授权和学习策略约束。

沉浸式视频学习 —— 把 YouTube 或 Bilibili 链接添加到 Reading，获得原生播放、转录搜索、以时间戳为据的辅导、已保存笔记和可续跑的进度；YouTube 字幕和浏览可以使用管理员配置的 Invidious 实例。

子智能体与 Partner —— 在 Chat 中咨询一个实时的智能体宿主（Claude Code、Codex、Grok CLI、Antigravity、Kimi、opencode、MiMo、Hermes、OpenClaw 或 DeepSeek），或一个 Partner；导入过往对话；并在同一个大脑上运行持久的 IM 伙伴。

多引擎知识 —— 跨 LlamaIndex、PageIndex、GraphRAG、LightRAG、远程 LightRAG Server、自托管的 WeKnora 知识库、腾讯 IMA 或 MarginNote 4 库、连接的 Kiwix ZIM 归档，或关联的 Obsidian 保险库的版本化 RAG 库，并支持可插拔的文档解析。参见原生 LightRAG 角色模型，了解独立的抽取、查询和视觉设置，以及仅默认创建与确认后重建。

可扩展的工具与技能 —— 内置工具、MCP 服务器、CLI 应用、图像／视频／语音生成模型，以及可从 EduHub 安装的社区技能。

可检视的记忆 —— L1 轨迹、L2 界面摘要和 L3 综合，让个性化可见、可编辑；Memory Graph 把 L2 事实连接到 L1 证据，把 L3 综合连接到贡献它的各界面。

🚀 快速开始#

让你的智能体来安装 DeepTutor#

把这段提示词复制到你有终端能力的 AI 智能体（比如 Codex 或 Claude Code）中：

Help me install and configure the current dev version of DeepTutor from https://github.com/HKUDS/DeepTutor.
Clone the dev branch, or inspect and reuse my existing checkout. Start at
docs-for-dev/README.md, then read docs-for-dev/AGENT_SETUP.md and SKILL.md.
Follow the setup guide to prepare the environment,
configure my model provider, verify the setup, and start the Web app.
Ask me for any missing provider, model, or credential-source information;
do not print API keys. Preserve my existing files and settings, and finish
with the access URL and the results of your checks.

开发者与智能体手册是安装、架构、扩展开发、测试和故障排查的文档入口。其中的 Agent Setup 指南覆盖完整安装流程，包括非交互式 CLI 配置。要自己安装，从下面选一条路径。

DeepTutor 提供四种安装路径。它们共享同一套运行时家目录（runtime-home）布局：私有设置在启动目录下的 data/user/settings/ 中（或在你显式设置的 DEEPTUTOR_HOME / deeptutor start --home 之下）。完整的存储布局、数据库支持和备份说明见本地数据持久化。对于完整应用，推荐的流程是：选一个运行时家目录 → 安装 → deeptutor init → deeptutor start。

一条命令的 Docker 试用#

如果还没装 Docker，先装 Docker。然后无需配置 Python 或 Node.js 就能试用完整应用：

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

打开 http://127.0.0.1:3782，在 Settings → Providers 中配置模型服务商，用完按 Ctrl+C。名为 deeptutor-data 的卷会为下次运行保留设置和本地数据。

内容工作区（Content Workspace）#

内容工作区独立于 DeepTutor 的私有运行时家目录。它是智能体可以读取的文件夹，生成的文件位于 outputs/<capability>/<session>/<turn>/ 之下。自定义工作区把对话、学习材料、进度和缓存隔离在一个私有的 .deeptutor/data/ 树中，文件工具无法浏览其中内容。设置、凭证和 Memory 仍保持在账号级别共享。

未做配置时，内容工作区是 <runtime-home>/data/user/workspace。本地 PyPI、CLI 和源码安装可以在 Settings → Workspaces 中选择文件夹；用以下命令设置默认文件夹：

deeptutor workspace show
deeptutor workspace set /absolute/path/to/my-folder
deeptutor workspace reset

各项能力通过内置的工作区工具检视它所选的工作区。模型只会收到类似 outputs/... 的相对路径；当它使用 workspace_present 时，界面会渲染一个经过认证、可打开的快照。同一个确切的相对路径在普通的 Markdown 链接或图片中同样有效。之后修改源文件不会改变已经呈现的快照。

Learning Space 管理资源库。在 Settings → Workspaces 中，为每个工作区分配 Skills、MCP 服务和知识库，或保留其现有的访问规则。已存在的工作区会保持当前访问权限，直到你保存一次选择。分配引用原始资源，不复制凭证或知识索引；工作区专属的技能可以覆盖共享版本。见工作区资源分配。

在 outputs/ 之外的执行是只读的。把生成的文件复制到内容工作区中的其他位置，需要针对确切的源和目标给出一次明确的「允许一次」确认。系统沙箱或 Docker 运行器可用时会强制执行这一边界；本地受限子进程的回退方案会在工作区设置中被标注为尽力而为。

方案 1 —— 从 PyPI 安装（本地完整 Web 应用 + CLI，无需克隆）#

1.7.0 的模块化安装：用 deeptutor[full] 获取 Web 应用和 CLI，或用 deeptutor 获取核心聊天。功能模块必须与核心版本一致；1.6.15 及更早版本使用旧的包布局。要针对当前 dev 开发，使用下面的源码说明或构建本地 wheel。需要 Python 3.11–3.14，以及 PATH 上有一个 Node.js 20+ 运行时（打包的 Next.js 独立服务器由 deeptutor start 启动）。

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

deeptutor init 会提示输入后端端口（默认 8001）、前端端口（默认 3782）、LLM 服务商／base URL／API key／模型、一个可选的用于知识库／RAG 的嵌入服务商，以及一个可选的用于网络搜索的搜索服务商。

升级到 1.7.0：停止应用并备份你的运行时家目录。先运行 python -m pip install --upgrade "deeptutor[full]==1.7.0"，然后运行 python -m pip check 和 deeptutor module list。如果安装了旧的 deeptutor-cli 包，先运行 python -m pip uninstall deeptutor-cli，再运行升级命令（可选加上 deeptutor-cli==1.7.0）。旧 CLI 占用了共享的 Python 文件，所以在同一次事务里升级它可能删掉新核心。卸载这个包不会动你的运行时家目录数据。保持相同的 DEEPTUTOR_HOME 和既有设置。在 1.7.0 中，只写 pip install -U deeptutor 只选择核心；用 [full] 请求完整应用安装配置。对于本地构建的包，请遵循本地 wheel 升级说明。

执行 deeptutor start 后，打开终端中打印的前端 URL——默认是 http://127.0.0.1:3782。在该终端按 Ctrl+C 可同时停止后端和前端。快速试用时跳过 deeptutor init 也没问题；应用会以默认端口和空的模型设置启动，之后在 Settings → Providers 和 Language models 中配置。

浏览器麦克风转写： OpenAI 兼容的 STT 适配器会把浏览器音频转发给服务商，不在本地转换。原生的 DashScope 和火山引擎 STT 适配器会把浏览器 WebM/Opus 转换为 16 kHz WAV，并要求 DeepTutor 的 PATH 上有一个可用的 ffmpeg 可执行文件。规范的 16 kHz 单声道 PCM WAV 会绕过这一转换。使用任一原生适配器的 Windows PyPI 安装，需要先安装 FFmpeg，把其 bin 目录加入服务的 PATH，然后重启 DeepTutor。转换失败会显示在聊天输入框下方。

方案 2 —— 从源码安装（针对检出目录开发）#

用于针对一个检出目录开发。使用 Python 3.11–3.14 和 Node.js 22 LTS，以匹配 CI 和 Docker。

git clone --branch dev 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 -r requirements/full.txt
python -m pip install -e . --no-deps
( cd web && npm ci --legacy-peer-deps )

deeptutor init
deeptutor start --dev

deeptutor start 会为生产环境构建一次本地 web/ 前端并复用；--dev 则以 HMR 运行 Next.js。配置布局、端口和 Ctrl+C 行为与方案 1 相同。

Conda 环境（代替 venv）

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

可选的安装附加项 —— RAG 引擎／dev／partners／matrix／math-animator

python scripts/install_extras.py rag-lightrag # Built-in LightRAG engine (exact supported SDK)
python scripts/install_extras.py graphrag # Microsoft GraphRAG engine (Python 3.11–3.13)
python scripts/install_extras.py dev # tests/lint tools
python scripts/install_extras.py partners # Partner IM channel SDKs
python scripts/install_extras.py video-learning # captions for reading/video-learning
python scripts/install_extras.py matrix # Matrix channel without E2EE/libolm
python scripts/install_extras.py matrix-e2e # Matrix E2EE; requires libolm
python scripts/install_extras.py math-animator # Manim addon; requires LaTeX/ffmpeg/system libs
python scripts/install_extras.py edge-tts # Optional free speech provider and video-lesson narration

视频课程： 在聊天中选择 Video Lesson，或运行 deeptutor run video_lesson "Explain a concept"。后端需要 Node.js 22+ 和 npm。首次使用会下载固定版本的 Remotion 包和一个 WebAssembly JavaScript 解释器；不需要 Docker。帧检查在解释器内运行，没有宿主文件系统、凭证、网络或进程 API，并受内存和执行限制。取消会停止构建进程。本地和容器部署使用同一条执行路径，没有非沙箱的回退。生成的课程在浏览器中播放，在可选旁白不可用时会带字幕。

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

修改前端依赖：运行 npm install --legacy-peer-deps 刷新 web/package-lock.json，然后同时提交 web/package.json 和 web/package-lock.json。

开发服务器卡住：如果 deeptutor start --dev 报告存在一个无响应的前端，停掉它打印的 PID。如果实际上没有 Next.js 进程在运行，说明锁文件是陈旧的——删除它们并重试：

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

方案 3 —— Docker（一个自包含容器）#

一个容器承载完整 Web 应用。镜像位于 GitHub Container Registry：

• ghcr.io/hkuds/deeptutor:latest —— 最新稳定版
• ghcr.io/hkuds/deeptutor:<version> —— 指定确切版本，不带前导 v（例如 :1.6.3）；预发布版只会有其版本标签

podman／无根／只读根文件系统的部署方式和完整的逐安装指南见 CONTAINERIZATION.md。

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

要在容器启动时选择一个宿主内容文件夹，把它挂载到稳定的容器路径，并把 DeepTutor 锁定到该路径：

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 设置页面中会显示为已锁定。

只需要发布 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。容器首次启动时会创建 /app/data/user/settings/*.json；从 Web 设置页面配置模型服务商。配置、API 密钥、日志、默认内容工作区、记忆和知识库都持久化在 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 设为前端服务器用来访问后端的内网地址（它在服务端读取，绝不会发送到浏览器）。

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

next_public_api_base_external（及其别名 public_api_base）作为优先级更低的回退被接受。CORS 使用前端源，而不是 API URL。在关闭认证时，DeepTutor 默认允许正常的 HTTP/HTTPS 浏览器源。在开启认证时，添加确切的前端源：

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

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

在 Docker 内，localhost 指的是容器自己，而不是你的宿主机器。要访问宿主上运行的模型服务，使用宿主网关（推荐）：

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 → Providers 中，把服务商的 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（或 system.json 中的 frontend_port），宿主服务也可以用 http://127.0.0.1:11434/v1 这类普通 localhost URL 访问。注意，宿主网络会把容器端口直接暴露在宿主上，可能和已有服务冲突——若要让它们留在回环地址上，设置 BACKEND_HOST=127.0.0.1 和 FRONTEND_HOST=127.0.0.1（见 CONTAINERIZATION.md）。

方案 4 —— 仅 CLI（无 Web UI，从源码检出运行）#

不需要 Web UI 时，用这个检出目录里的 CLI，跳过 Node/npm。源码暴露所有已检入的模块，因此需要它们的 Python 依赖。若要用 1.7.0 模块化版本做最小安装，使用核心 deeptutor wheel 并单独添加功能模块。

git clone --branch dev 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 -r requirements/full.txt
python -m pip install -e . --no-deps
deeptutor init --cli
deeptutor chat

deeptutor init --cli 与完整应用共享相同的 data/user/settings/ 布局，但会跳过后端／前端端口提示。它仍会提供嵌入和搜索选择项（不需要时选 Skip），写出关键的运行时文件（system.json、auth.json、integrations.json、interface.json、model_catalog.json、main.yaml、agents.yaml），并提示输入当前生效的 LLM 服务商和模型。

常用命令

deeptutor chat # interactive REPL
deeptutor chat --capability deep_solve --kb my-kb
deeptutor run chat "Explain Fourier transform"
deeptutor run deep_solve "Solve x^2 = 4" --kb my-kb
deeptutor kb create my-kb --doc textbook.pdf
deeptutor memory show
deeptutor config show

这个源码安装包含服务端依赖，但跳过前端配置。请保留这个检出目录——可编辑安装指向它。以后要加上 Web UI，安装 Node.js 22 LTS，在 web/ 中运行 npm ci --legacy-peer-deps，然后从项目根目录运行 deeptutor init 和 deeptutor start。

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

内置的 office 技能——docx / pdf / pptx / xlsx——的工作方式是让模型写一段简短的 Python 脚本（python-docx、reportlab、openpyxl……），通过单一的 exec 工具运行它，并展示保存下来的工作区文件。只要有沙箱后端处于激活状态，这些工具就会挂载。DeepTutor 按以下顺序选择已配置的最强后端：

• 运行器 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），在没有运行器或 bwrap 后端可用时拒绝子进程执行；它不会禁用那些更强的后端。

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

data/user/settings/ 下的一切都是纯 JSON/YAML。设置页面是推荐的编辑器；工作区注册信息单独存放在 data/user/.runtime/workspaces.sqlite3。

网络搜索的引用默认会被过滤：只呈现没有内嵌凭证或异常端口的公开 http/https URL。部署方可以在 data/user/settings/system.json 中添加一个面向教育的域名策略：

{
 "web_search_source_filtering": {
  "enabled": true,
  "blocked_domains": ["spam.example"],
  "trusted_domains": ["edu.cn", "arxiv.org"]
 }
}

当 trusted_domains 非空时，引用被限制为这些域名及其子域；blocked_domains 始终优先。

项目根目录的 .env 不会被当作应用配置文件读取。最小的模型配置：在 Settings → Providers 中保存 Base URL 和 API key，然后在 Language models 中添加并选择一个 LLM。只有计划使用知识库／RAG 功能时才添加嵌入档案。

对于 API Route，在 Settings → Providers 中选择 API Route 并输入 API Route 密钥。预设使用 https://global.api-route.com/v1；然后在 Language models 中用其 API Route 模型 ID 添加一个模型。密钥和模型设置见 API Route 快速入门。

当服务商支持选择时，LLM 和任务模型档案会暴露一个 API 格式设置。正常路由和回退时保持 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 时它有意不被擦除。

停止应用。在运行 deeptutor start 的终端中按 Ctrl+C，或者对于用 --detach 启动的启动器运行 deeptutor stop [--home PATH]；在删除数据前，停止所有正在运行的 Partner 和已分离的 Docker 容器。

只有在你同时想抹掉所有本地状态时，才移除运行时数据。这包括设置和 API 密钥、聊天历史、会话、Memory、Notebooks、Books、Reading 状态、Skills、Partners 状态、日志、知识库、解析缓存、生成的产物，以及打包的前端运行时缓存。

先复制启动横幅中确切的 Workspace: 路径，并确认它的 data 子目录就是预期的 DeepTutor 数据目录。如果之后可能还需要，先备份，然后把那个确切的目录移到你操作系统的废纸篓／回收站。不要针对相对路径或未解析的环境变量运行递归删除命令。

移除已安装的包。使用与发行版匹配的命令：

python -m pip uninstall deeptutor
python -m pip uninstall deeptutor-cli

如果虚拟环境是专为 DeepTutor 创建的，请通过你的环境管理器删除它。对于源码安装，停用环境，离开源码目录，并在那个确切的检出中运行 git status --short。只有在确认其中没有无关或未提交的工作之后，才把检出移到废纸篓／回收站。

对于 Docker 路径，在移除确切的容器和命名卷之前先检查它们。卷的移除会永久擦除由 Docker 管理的数据：

docker ps -a --filter name=^/deeptutor$
docker volume inspect deeptutor-data
docker rm -f deeptutor
docker volume rm deeptutor-data

📖 探索 DeepTutor#

从一个为某个学科或项目准备的工作区开始。它的 Home、Learning 和 Resources 承载你的对话、学习活动和材料。Partners 和 Personalization 跨工作区保留在你的账号上。下面的导览展示这些界面如何连接，随后是设置和多用户部署。

如果某个回答丢失了先前的约束、引用了薄弱的证据，或与选定的材料相矛盾，请先按 REASONING_SAFETY_CHECKLIST.md 收集诊断信息，再开 issue。

🏗️ 系统架构#

💬 Chat —— 你真正在用的智能体循环#

Chat 是默认能力，也是大多数工作的起点。一个线程可以正常对话、调用工具、以选定的知识库为依据、读取附件、生成图片、咨询子智能体、写入笔记本记录，并在各个回合之间以同一上下文继续。

辅导器按需调用工具，可以暂停以提出澄清问题。右上角的 Customize 页面选择可见的模式和 Skills、MCP、Partners、Preferences 以及语音输入控件。在 Starting prompts 下，可以添加、编辑或删除 Explain、Solve、Practice、Plan 和 Research 中的标题与提示词。Save 应用你的账号偏好；Cancel 丢弃编辑，Restore defaults 恢复原始选项。

用户可切换的工具是 brainstorm、web_search、paper_search、zotero_search、reason 和 geogebra_analysis——以及在你配置了相应的生成模型后的 imagegen 和 videogen。上下文相关的工具，如 rag、kb_files、knowledge_frontier、read_source、read_memory、write_memory、read_skill、load_tools、exec、web_fetch、ask_user、list_favorites、save_favorite、write_note、search_notes、question_bank、github、consult_subagent、workspace_list、workspace_read、workspace_search、workspace_present 和 workspace_export，会在回合具备合适上下文时自动挂载。

上下文有两种：粘性的会话上下文（能力、工作区或课程、工具、知识库、人格、模型，以及 Reading / Mastery 状态）跨回合持续；一次性引用（文件、聊天历史、书籍、阅读章节、笔记本、选中的题库条目、导入的智能体）来自 + 菜单，仅供单个回合。语音按钮只转写当前消息。

在完整配置下，Home 让 Chat、Ask Questions、Quiz、Visualize 和 Video Lesson 一键可达；用于带引用的报告的研究（Research）和用于展示完整推理过程的 Solve 位于 More Capabilities 之下。Learning → New learning（在 All learning 上方）会打开一个专门页面，包含 Books、Mastery Path、沉浸式阅读和 Practice。它的 Customize page 控件可以隐藏或恢复学习方法而不改变已有记录；不可用的模块仍会被排除。Reading 把文档、视频和音频汇集在一起，带经验证的引用、已保存的笔记、从源段落／学习指引／词汇／测验／翻译操作发起的自然朗读，以及笔记本捕获。

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

Partner 是持久的伙伴，拥有自己的灵魂、模型策略、资料库、记忆和频道。它们不是独立的机器人引擎：每一条来自网页或 IM 的入站消息，都会在其私有或绑定的内容工作区内变成一个普通的 ChatOrchestrator 回合。一个 Partner 就是「一个有性格、有电话号码的聊天」。

每个 Partner 都有 SOUL.md、模型选择、频道、工具策略和分配的库。它的库要么把知识库、技能和收藏集合复制进 data/partners/<id>/workspace/，要么保持链接到现有工作区的文件和资源；灵魂、对话和 Partner 记忆保持独立。已认证的非管理员用户拥有私密的 Partner 会话和关系记忆，同时 Partner 以只读方式读取他们的个人记忆；管理员、群组和未绑定的流量使用共享的 Partner 范围。

频道层是模式驱动的，可以连接到 Feishu、Telegram、Slack、Discord、钉钉、QQ/NapCat、企业微信、WhatsApp、Zulip、Mattermost、Matrix、Mochat 和 Microsoft Teams 等 IM 平台，具体取决于已安装的附加组件和配置的凭证。Partner 也可以作为子智能体被连接，并在普通聊天回合中被咨询——见下面的 My Agents。

为了更快地配置，Partner 频道页面可以创建一个飞书/Lark 应用或企业微信 AI 机器人，或登录一个个人微信账号——通过浏览器中绘制的二维码扫描，而不是从服务器日志里。飞书/Lark 会检测账号域名，并把扫码用户保存为初始的允许发送者。企业微信保留已有的允许列表，否则默认对所有能触达该机器人的用户开放，并显示醒目的开放访问警告；如果某个服务商的扫码协议发生变化，手动频道表单仍然可用。

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

My Agents 把其他智能体变成 DeepTutor 的上下文，它做两件不同的事。连接一个实时智能体——你机器上的 Claude Code、Codex、Grok CLI、Antigravity、Kimi、opencode、MiMo Code、Hermes Agent、OpenClaw 或 DeepSeek Harness，一个远程 Hermes 网关，或你的某个 Partner——然后在聊天回合内咨询它：DeepTutor 实际上会运行另一个智能体，并通过 consult_subagent 工具把它的工作流式送入 Activity 面板。用 Agent 芯片选择它及其回合上限，或用 @ 过滤同一份已连接智能体列表；选择会附着在会话上。

连接 Grok CLI。 在运行 DeepTutor 后端的机器上安装 xAI 的 Grok CLI，在那里运行 grok login，并确认 grok --help 列出 --output-format streaming-json。然后打开 My Agents → Connect，选择 Grok CLI，并选择一个工作目录。检测会检查可执行文件的协议支持；它不会验证登录或模型访问。该连接器已用 Grok CLI 1.0.3 测试过；其他恰好也叫 grok 的无关第三方命令不受支持。

在 Settings → Partners & Agents → Grok CLI 中，把模型和推理强度留空以使用 CLI 默认值，或输入你的账号 grok models 输出所支持的值。系统指令通过 --rules 传入。默认权限模式是 dontAsk：Grok 使用其既有规则和内置的只读处理，并拒绝需要批准的操作。这是 CLI 的权限策略，不是文件系统沙箱。可以在设置中显式选择更宽的模式；高级 CLI 参数仍可通过子智能体设置 API 中的 backends.grok.extra_args 使用。

Grok 使用自己的认证和会话存储；DeepTutor 不复制其凭证。后续咨询会在同一工作目录中恢复该连接的会话。文本和工具活动实时流式输出；私有的思考负载会被省略。跨会话的 Grok 记忆默认禁用。该连接器支持文本提问和 CLI 工具，不支持转发图片或导入过往的 Grok 对话。在 Docker 中，请在容器内安装并认证 Grok；只安装在浏览器所在计算机上的 CLI 是无法访问的。

导入过往对话 —— 把你现有的 ChatGPT、Claude Code 和 Codex 历史作为可搜索、可恢复的对话引入。从官方 ChatGPT 数据导出中选择 conversations.json，进行安全、幂等的快照导入；按项目／工作目录选择 Claude 历史；或按日历日期选择 Codex 历史。基于文件夹的智能体保持可刷新，因此其选定范围可以拉入新的对话。在 Chat 回合中通过 + → My Agents 引用其中一个，DeepTutor 会把它作为第三方转录读取——它仍然是它们的对话，而不是 DeepTutor 自己的声音。

✍️ 学习笔记本 —— 页面、来源与 Dito#

学习笔记本（原名 Co-Writer）把你自己写的内容组织成当前工作区内的页面、子页面和块。导入 Word 文档、安排页面树，并把来自收藏的原始记录作为证据插入。页面会显示其保存状态，并可导出为 Markdown 或 Word；交互式内容在 Word 中会变成静态的。

与 Dito 讨论某段文字或某个块：请求解释、示例、改写或练习题。对话会附着在相关页面和行上。在接受之前审查提议的改动，或者在那一行下方插入答案并继续工作。收藏保留来源记录；笔记本是你构建自己理解的地方。

📖 Book —— 从你的材料生成活书#

Book 把选定的来源变成一本可交互的活书——不是静态 PDF，而是由带类型的块构建而成的阅读环境。一本书可以从知识库、收藏、题库或聊天历史开始；创建流程会在生成内容之前先提出一个章节大纲，因此你审查的是整体形状，而不是接受一次盲目的单次输出。

每一章都会编译成可编辑的带类型块——正文、提示框、测验、记忆卡、时间线、代码、图表、交互式 HTML、动画、概念图、深入探讨和用户笔记——并拥有自己的 Page Chat。插入、移动、重新生成、改写或切换块类型；选中的段落会进入一个可审查的学习捕获收件箱。进度、书签、测验尝试、捕获和 Page Chat 对每位读者保持私密，即使一本管理员书籍是只读共享或用于协作编辑；共享删除仍然仅限管理员。任何书都可以导出为 Markdown，长编译可以暂停和继续，deeptutor book health / refresh-fingerprints 会标记来源漂移。

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

知识库是 RAG 背后的文档集合——它们为 Chat 回合、学习笔记本编辑、书籍生成和 Partner 对话提供依据。其独特之处在于检索引擎的选择：LlamaIndex（默认，混合向量 + BM25，可选交叉编码器重排序，以及精确扁平或 HNSW FAISS 索引）、PageIndex（带页级引用的推理式检索，托管或自托管开源版）、GraphRAG 和 LightRAG（知识图谱检索）、LightRAG Server（把检索卸载到通过 HTTP 连接的外部 LightRAG 实例）、WeKnora（从你自托管部署中的知识库检索，无需本地索引或文档副本）、腾讯 IMA（你在 IMA 中整理的库——通过其 OpenAPI 搜索、浏览和回写）、MarginNote 4（你的 MN4 学习数据——文档、摘录、思维导图卡片及它们之间的链接——由应用的附加组件推入，并用专门工具导航）、Kiwix（通过 HTTP 提供、无需本地索引的可搜索 ZIM 归档），或一个由辅导器原地读写的关联 Obsidian 保险库。每个知识库绑定一个引擎。

迁移现有的 Obsidian、Hermes 或 Markdown 资料库？见知识迁移指南，了解连接保险库和索引副本两种路径。

创建知识库时，你可以新建（上传并索引文档）、链接已有（原地复用一个索引），或连接 Kiwix（按需搜索一个已提供的 ZIM 归档）。创建时选择其存储工作区；已有的知识库可以在预览之后在工作区之间移动，保留分配和已保存的引用。知识库也可以跟踪 GitHub 仓库（仓库、分支、glob）或文档站点 URL（有界的抓取深度和页数，默认每 24 小时重新同步）；同步会对新增、改动和删除的内容做哈希差分，以便跟随的文档保持最新而无需重新上传，关联的文件夹也会在同步时拾取新的或已更改的本地文件。重建索引会写入一个新的扁平 version-N 目录并保留之前的，因此工作中的索引绝不会在重建中途被破坏。单个文档即使处于错误状态的知识库中也可以被移除——丢弃一个解析失败的文件而不必整个删除重建。文档解析——Text-only、MinerU、Docling、Tika、markitdown、PyMuPDF4LLM 或 LiteParse——以及可选的图片描述模型，在 Settings → Knowledge & documents 中选择，本地模型下载默认关闭。Docling 也可以针对 Docling Serve 服务器以远程模式运行（无需本地安装或模型），在该页面配置（mode=remote、服务器 base URL，以及可选的 API key），或通过 DOCLING_MODE / DOCLING_API_BASE_URL / DOCLING_API_TOKEN 环境变量。Tika 仅支持远程，指向该页面上配置的 Apache Tika 服务器。CLI 以 list/info/create/connect-kiwix/add/search/eval/eval-diff/set-default/delete、source add/remove、list-sources 和 sync 来对应这套生命周期。

内置的 LightRAG 引擎通过 pip install 'deeptutor[rag-lightrag]' 安装。该附加项包含受支持的 LightRAG SDK，但不安装 MinerU。在 Document Parsing 中独立选择 MinerU，并在需要结构化解析时要么配置其云模式，要么安装其当前的本地 CLI。MinerU 接受 PDF、常见位图、DOCX、PPTX 和 XLSX；旧版的 magic-pdf 命令仍仅限 PDF。Text-only 和其他解析引擎不需要 MinerU。

原生 LightRAG 查询和增量索引需要已发布索引所记录的嵌入配置，包括模型、维度和端点标识。如果它发生变化，请恢复原始配置或使用当前嵌入重建；没有记录嵌入标识的索引需要重建。知识库详情和索引版本视图会显示恢复指引，同时文件仍可查看和下载。

为知识库打分。 有多个引擎可用时，「哪一个在这里检索得最好？」是一个经验问题——deeptutor kb eval 来回答它。写一个 QA 集（每行一个 JSON 对象：一个查询，加上理想检索应返回的黄金段落），然后用 deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json] 为知识库打分。每个用例都通过与聊天回合相同的路径检索，其排序后的引用会用精确文本或词法重叠与黄金段落匹配（阈值可用 --min-ratio 调整；不评估语义等价），运行会报告 Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k。指标是纯粹基于排序的函数；没有模型评判输出。用 deeptutor kb eval-diff baseline.json candidate.json 比较已保存的报告，得到逐指标和逐用例的变化。在 kb eval 上使用 --rewrite off 或 --rewrite standalone 来比较原始查询和改写后的查询；报告会保留改写来源。检索失败的用例（索引缺失、凭证错误）不带分数，会单独报告，而不是把平均值拖低。PageIndex 使用推理作为检索，不返回排序的块，因此被排除在外。

{"query": "Why do transformers scale attention?", "gold": ["Scaling keeps the dot products from growing with the dimension."]}

🌐 资源与个性化 —— 材料与可复用助手#

Resources 汇集了聊天历史、带可移动记录和 Markdown 导出的收藏、学习日志、知识中心，以及带答案和解析的题库。从题库选择开始 Practice，或通过 Learning → Practice 进入复习会话、错题跟踪和计划重复。单独的 Personalization 页面存放人格、技能（SKILL.md 行动手册）、一键式 MCP Services，以及来自 CLI-Anything 目录的 CLI Apps，每个都有按需的使用指南。Learning 汇集书籍、mastery 路径、阅读集合及其辅导对话；每个资产只在支持它的工作流中提供。

你不必自己写每一个技能——Import from EduHub 会浏览社区目录，并通过安全门把技能直接下载到你的库中（见生态）。

🧠 Memory —— 可检视的个性化#

Memory 是一个文件支撑的三层系统，你可以读取、整理和审计——刻意不是隐藏的向量存储。L1 是工作区镜像加一份只追加的事件轨迹（trace/<surface>/<date>.jsonl）；L2 是按界面整理的事实（L2/<surface>.md），带指向 L1 实体的引用；L3 是跨界面的综合（L3/<profile|recent|scope|preferences>.md），记录贡献它的那些 L2 界面。

Memory Graph 展示整座金字塔——L3 综合在中心，L2 在中间环，L1 轨迹在外围——带确切的 L2 → L1 证据边和 L3 → 贡献界面的链接。记忆会跨 chat、notebook、quiz、kb、book、partner 和 cowriter 界面被跟踪；整理器的 Update / Audit / Dedup 预算在 Settings → Memory 中调整。

⚙️ 设置 —— 单一控制面#

设置是操作控制面，打开时位于 General，用于界面和模型输出语言。它可搜索的导航器链接到各自独立的页面：Personal 涵盖 Workspaces、数据迁移、外观和用量统计；Learning & conversation 涵盖起点、附件、视频学习、学习者与监护人控制、学习进度和 Memory；Models & services 涵盖 Providers、Language models、Task models、Embedding、Search、Voice 和多模态生成；Features & integrations 涵盖工具、能力参数、Partners & agents 以及 Knowledge & documents。System 存放 Network、Runtime status 和 About；Archived chats 让你搜索、恢复或永久删除已归档的对话。Runtime status 包含后端健康状况、常驻内存，以及为能力阻断、警告和建议打分的 Readiness 矩阵。Workspaces 把主题文件和学习状态分开，并在数据迁移下提供经验证的迁移和导出。一个服务商持有一个厂商的地址和凭证，供其服务模型复用；模型页面选择已保存的服务商，并配置模型名称和能力。任务模型固定一个小而快的模型来处理后台工作——为对话命名和撰写起点——为空时解析为当前的默认模型。Voice 汇集语音合成和转写；Multimodal generation 汇集图像和视频模型。Partners & agents 配置……