DeepTutor：统一上下文的AI终身学习系统

AGENT LEARNING NOTES 2026.08.11

34K+ Star · Apache-2.0 · 本地优先

ARCHITECTURE FIELD GUIDE

很多 AI 学习产品的结构都很熟悉：上传资料，打开聊天框，然后围绕文档问答。DeepTutor 想做得更深一层。它把聊天、研究、解题、测验、写作、知识库、外部 Agent 与长期记忆放进同一个本地工作台，让一次学习任务可以继续变成笔记、报告、题库，甚至一本可交互的书。

截至 2026 年 8 月 11 日，DeepTutor 在 GitHub 获得 34,181 Star、4,385 Fork，采用 Apache-2.0 许可证，主要后端语言为 Python，Web 端基于 Next.js 16 与 React 19。当前发布版本为 v1.5.11。

这篇文章不把 DeepTutor 当成“功能很多的 AI 家教”来介绍，而是从它的运行主干出发，看看这套系统怎样组织 Agent、工具、知识与记忆，以及它适合什么人、不适合什么人。

DeepTutor 给自己的定位是“终身个性化辅导系统”。从产品表面看，它包含九个主要区域：Chat、Partners、My Agents、Co-Writer、Book、Knowledge Center、Learning Space、Memory 与 Settings。

这些页面并非九套互不相干的应用。代码中可以看到一条清晰主线：入口先把会话、附件、Persona、知识库、Skills 与记忆组装成统一上下文，再由 Agent Loop 判断是否调用工具或进入特定能力。Partner 的网页消息和 IM 消息也会回到同一套 ChatOrchestrator，而不是另建一个机器人内核。

官方架构图把系统分为五层：入口、运行编排、Agent 原生核心、服务，以及数据与配置。CLI、WebSocket API、REST API 和 Python SDK 都能进入相同运行时；上层的 Chat、Auto、Deep Solve、Deep Research、Visualize 与 Mastery Path，则通过能力与工具机制复用底层服务。

这种架构带来一个重要结果：学习资料不会只停留在某个问答页面里。同一个知识库可以支撑聊天、研究、协同写作、Book 与 Partner；同一段会话也可以被放进后续任务，继续生成测验、笔记或章节。

Chat 是 DeepTutor 最常用的入口。用户可以直接对话，也可以在输入区挂载知识库、文件、Persona、外部 Agent 和一次性引用。会话中的模型、知识库、Persona、语音与子 Agent 属于粘性上下文，会跨轮保留；从加号菜单临时加入的文件、历史对话、Book、Notebook 或题库，只影响当前一轮。

核心循环并不神秘：模型先思考，再决定直接回复还是调用工具；工具结果返回后继续观察和判断，直到输出一个不再调用工具的最终消息。ask_user 是一个特殊工具。当任务缺少条件时，Agent 可以暂停并提出结构化问题，等用户补充后再恢复，而不是自行猜测。

DeepTutor 把工具分成两类。一类由用户主动开关，例如头脑风暴、网页搜索、论文搜索、推理与 GeoGebra 分析；图像和视频生成则需要先配置对应模型。另一类根据上下文自动挂载，包括 RAG、知识库文件、来源读取、Memory 读写、Skill 读取、MCP 工具加载、代码执行、网页抓取、Notebook、GitHub 查询与子 Agent 咨询。

从一次任务的角度看，完整链路如下：

内置能力并不只有聊天。当前代码注册了 Chat、Deep Solve、Deep Question、Deep Research、Math Animator、Visualize 与 Mastery Path；另有 Solve、Mastery、Obsidian、Subagent 与 Explore Context 等 Loop Capability，根据当前上下文加入工具表面。某些能力会使用独占工具集，避免无关工具干扰本轮任务。

这使 DeepTutor 更接近一个学习任务运行时：普通问答是默认路径，复杂任务则进入研究、解题、出题、可视化或学习路径，并且仍能访问统一上下文。

Partners 是带有独立人格与工作区的长期伙伴。每个 Partner 可以配置自己的 Soul、模型策略、知识库、Skills、Notebook、Memory 与消息渠道。它读取所有者允许访问的记忆，但写入自己的 Partner 记忆，从而避免多个角色把长期状态混在一起。

Partner 并没有另起炉灶。外部消息经过 Channel Adapter 归一化后，进入 Partner Runtime，再调用共享的 UnifiedContext、ChatOrchestrator、AgenticChatPipeline、ToolRegistry 与 StreamBus。换句话说，Partner 是带人格、渠道和独立作用域的 DeepTutor Chat。

通道层采用自动发现机制：内置通道从 Python 包中扫描，外部通道可以通过 entry point 注册；内置实现优先，插件不能覆盖同名内置通道。项目当前提供多种连接器，但实际可用性取决于安装的可选依赖、平台凭证与网络环境。

这部分最适合需要“长期角色 + 多入口”的场景，例如研究助理、课程陪练或团队知识助手。不过，它也意味着部署者要承担渠道凭证、消息平台限制和长期运行维护，不能把“支持通道”理解成开箱即用的托管服务。

My Agents 解决两类问题。

第一类是连接正在运行的 Agent。DeepTutor 可以在当前机器上调用多种专业编码工具，并将执行过程流式展示在 Activity 面板中。用户可以限制咨询轮数，避免子 Agent 无边界运行。

第二类是导入历史对话。用户可以选择日期，把已有的外部编码会话同步成可搜索、可恢复的外部记录。它们在 DeepTutor 中仍被标识为第三方内容，不会被伪装成 DeepTutor 自己生成的对话。

这项设计很实用：学习和工作并不总能分开。阅读代码、验证公式、检索论文或生成实验脚本时，专业编码 Agent 可以成为当前学习任务的一部分，而不是在多个窗口之间反复复制上下文。

Co-Writer 是左右分栏的 Markdown 工作区，支持自动保存、实时预览、数学公式和图表围栏。稿件成熟后，还可以回存到 Notebook，成为下一轮学习或研究的材料。

它最值得注意的不是全文生成，而是选区编辑。用户选中一段文字后，可以要求重写、扩写或压缩；编辑 Agent 可以引用知识库或网页证据，展示工具调用轨迹，并用差异视图让用户逐项接受或拒绝。

这比直接覆盖全文更适合课程笔记、研究报告和长文。Agent 提供修改建议，最终决定仍留在用户手里。

Book 的输入可以来自知识库、Notebook、题库或聊天历史。系统先提出章节大纲，让用户确认结构，再生成内容。最终产物不是一个静态 PDF，而是由多种类型化区块组成的阅读环境。

区块类型覆盖正文、提示、测验、闪卡、时间线、代码、图形、交互 HTML、动画、概念图、深入阅读与用户笔记。每个页面还有独立的 Page Chat。用户可以插入、移动、重新生成区块，或者切换区块类型，而不必重写整个章节。

项目还提供 deeptutor book health 与 deeptutor book refresh-fingerprints，用于检查来源知识是否已经和编译后的页面发生漂移。这个细节说明 Book 被设计成可维护的知识产品，而不是一次性生成物。

Knowledge Center 为 Chat、Co-Writer、Book 与 Partners 提供检索依据。DeepTutor 没有把所有文档锁进同一种向量数据库，而是让每个知识库绑定一种检索引擎。

当前产品界面和配置覆盖多种检索方案：

创建知识库时，可以上传文档建立新索引，也可以链接已有索引。重建索引会写入新的 version-N 目录并保留旧版本，避免在重建中破坏一个仍可工作的索引。若单个文档解析失败，也可以只删除该文档，不必重建整个知识库。

文档解析支持纯文本、MinerU、Docling、markitdown 与 PyMuPDF4LLM。这里要注意工程成本：GraphRAG、LightRAG、MinerU 和多模态解析并非同等轻量，部分能力需要额外依赖、模型下载或外部服务。想要最短部署链路，可以先从默认 LlamaIndex 与文本解析开始。

Learning Space 是 DeepTutor 的个人资料与复用层。它分成两组内容：一组是会话、Notebook 和题库等学习材料；另一组是 Mastery Path、Persona、Skills、MCP Services 与 CLI Apps 等个性化能力。

Skill 采用 SKILL.md 形式，Agent 在需要时读取，而不是把所有说明一次性塞进系统提示词。用户可以自己编写，也可以从社区目录导入。导入过程经过安全门，但第三方 Skill 仍然需要人工检查其说明、依赖与可执行范围。

MCP Services 与 CLI Apps 扩展了 Agent 能调用的外部能力。项目文档列出多种 CLI 工具，但实际调用仍受安装状态、使用说明、沙箱和用户授权约束。这里的价值不在数量，而在于把扩展能力放入统一管理面板，并按任务动态加载。

DeepTutor 的 Memory 没有把个人状态藏在不可见的向量库里，而是使用文件化的三层结构：

Memory 文档采用 Markdown 保存。L2/L3 中的事实通过脚注引用上游来源，每条记录还有稳定 ID，支持更新、审计、去重、删除和引用合并。代码默认要求引用存在，并丢弃无效引用；更新与审计预算、去重轮数、分块大小和重叠比例都能在设置中调整。

Memory Graph 把 L3 放在中心、L2 放在中间层、L1 轨迹放在外圈。它的意义不是让图谱看起来复杂，而是允许用户从一条综合判断追溯到场景事实，再回到原始事件。

这套记忆设计的代价也很直接：整理、审计与去重会消耗模型调用；如果来源质量差，长期记忆只会更稳定地保留错误。因此“可检查”很重要，自动沉淀不能取代人工校正。

Settings 是模型、网络、知识库解析、Chat 工具、Partners、Agents 与 Memory 的统一控制面。界面带有后端健康状态和进程树内存占用，模型配置支持连通性验证后再应用。项目默认提供多套外观。

DeepTutor 默认是单用户模式，认证关闭。开启多用户后，管理员工作区、普通用户工作区、Partner 工作区与系统目录分开保存。普通用户通过 Grant 获得模型、知识库、Skills、Partners、工具、MCP、CLI Apps 与代码执行权限。

代码中的安全策略有几个值得留意的细节：

这些机制说明项目已经认真处理多用户风险，但它仍不是“开启认证就自动安全”的托管平台。部署者需要正确配置沙箱、网络边界、网关转发、平台凭证与资源授权，并持续跟进版本更新。

最简单的安装方式是 PyPI：

pip install -U deeptutor

deeptutor start

默认 Web 地址为 http://127.0.0.1:3782。当前 Python 包要求 Python 3.11 至 3.13；从源码开发 Web 前端还需要 Node.js 22 LTS。项目同时提供 Docker、Podman、源码安装与 CLI-only 路线。

CLI 既能给人使用，也能被其他 Agent 调用。deeptutor chat 打开交互式 REPL；deeptutor run <capability> <message> --format json 则以 NDJSON 输出内容、工具调用、工具结果与完成事件，并带上 session ID，便于串联多轮任务。

一个比较稳妥的起步顺序是：

这样做的好处是每一步都能单独验证，出现问题时也更容易定位。

如果需求只是对几份 PDF 做临时问答，DeepTutor 可能过重；一个轻量 RAG 工具会更快。它真正有吸引力的场景，是你希望同一个系统陪伴数月甚至数年，并且学习结果能够不断回流、重组和再利用。

DeepTutor 最有价值的地方，不是列出多少个页面或工具，而是把这些能力放在一条连续的任务链中：问题进入统一上下文，Agent 调用检索和工具，结果变成答案、测验、文章或 Book，最后又回到 Notebook、Knowledge 与 Memory。

这条链路一旦跑通，AI 家教就不再只是“回答我现在的问题”，而开始参与知识的长期组织。代价也同样清楚：系统越长期、越可扩展，配置、权限、成本与维护就越不能省略。

对愿意承担这些工程工作的用户来说，DeepTutor 是一个值得研究的开源样本。它展示了 AI 学习产品从聊天界面走向 Agent 工作台时，架构上需要补齐哪些部分。