DeepTutor v1.4.0-beta 深度解析Auto 模式路由、三层记忆子系统与 Agentic 引擎全栈统一【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutorv1.4.0-beta 是 DeepTutor 在agent-native重写之后规模最大的一次发布本篇文章以仓库中的 ver1-4-0-beta 发布说明 为骨架结合当前源码逐条剖析其核心机制。读完你将掌握 Auto Mode 的三段式 agent 循环与配额机制、L1/L2/L3 三层记忆子系统的整合管线与迁移路径、Deep Research / Deep Solve / Question 如何沉淀到同一套 labeled-step 引擎之上以及聊天会话内Attached Sources累积式来源清单与统一 Capabilities 基础设施的实现细节。所有关键结论均可在仓库源码、配置或测试用例中得到印证文中给出对应相对路径。适用版本范围v1.4.0-beta 及其后续演进版本当前仓库版本为 deeptutor/version.py 中标注的 1.5.8结构在此基础上继续演进文中路径以 v1.4.0-beta 时的形态为主。一、发布背景与整体定位v1.4.0-beta 的核心动作可以概括为两端收敛入口收敛新增一个凌驾于既有模式之上的autocapability让用户无需预先指定模式由系统为每次请求路由到合适的深层能力基础设施收敛记忆、Deep Research / Deep Solve / Question、聊天 LlamaIndex RAG、Capabilities 基础设施与 i18n、Animator 菜单、Settings 与本地启动器全部围绕统一的 agentic 引擎与共享组件重构删除了数以百计的专用 prompt 文件与 per-agent 类。围绕这两条主线本次发布还附带了一批新的聊天工具ask_user、web_fetch、write_note、list_notebook、github_query、删除聊天回合的完整流程、测验追问式聊天以及 GeoGebra 查看器。发布说明同时声明这是 beta 范围详见 原文档 Upgrade Notes 一节在 GA 之前建议生产环境固定使用v1.4.0-beta版本并欢迎针对新模块提交 bug 报告。二、Auto ModeAgentic Capability Routerauto能力被架设在既有模式之上代替用户预先选模式的交互由一个路由器为每个请求选择最合适的真实能力。这是本版本入口收敛的标志性设计。2.1 三段式 Agent 循环Auto 的内部循环划分为三个阶段且每阶段职责清晰、流式可见ANALYZING分析只做一次 LLM 调用以 thinking 的形式流式输出判断请求意图DELEGATING委派进入最多max_iterations轮的路由器调用。每一轮路由调用要么发出delegate_to_cap形式的工具调用要么发出原子工具调用从而决定把请求交给哪个子能力SYNTHESIZING综合产出最终内联答案。答案既可以由循环直接透传也可以由一次收尾的 LLM 调用拼接生成。在源码层面这套循环依赖的是 deeptutor/core/agentic/ 下的共享 agentic 引擎原语loop.py、labeled_step.py、labels.py、client.py、tool_dispatch.py、usage.py、messages.py等而不是为 Auto 单独再造一套执行器。这也解释了为什么文档声称 Deep Research / Deep Solve / Question 能够被重写为同一引擎之上的编排器——路由目标与执行器来自同一套底层。2.2 路由到真实能力而非仿真Auto 并不止于把聊天工具聚在一起。其路由器背后挂载的是真实存在的子能力deep_solve、deep_question、deep_research、math_animator、visualize以及聊天层级的原子工具web_search、web_fetch、rag等。这意味着模型可以在同一次对话回合内混合使用检索与完整子能力运行——既可以用rag快速检索也可以把复杂问题整体下发给deep_research跑一遍完整管线。2.3 有界的重试与配额为避免循环失控Auto 设计了三个维度的预算独立的重试预算路由器 LLM 出错、单次委派失败、参数校验反馈分别拥有各自独立的 retry budget同能力调用配额可配置的max_same_capability_calls配额阻止循环在某一种模式上无限自旋。这一参数对防抖至关重要若某个能力持续被选中但总不成功配额会强制循环跳出。2.4 干净的会话历史forward_events 与 call_idAuto 的最大工程难点在于子能力运行过程中的事件也要实时流式推给 UI但最终存入会话历史时只应保留 Auto 自己的最终综合结果。解决方案是一个forward_eventsshim——它为每个内容事件打上call_id标签让对话回合运行时过滤器只保留 Auto 自身的最终 synthesis 进入已保存历史而子运行的过程事件仅仅即时流式投递到界面。这种实时可见 落盘干净的双轨设计对长任务型编排器非常实用。2.5 answer_now 快速通道当用户要求立即回答时管线会跳过 ANALYZING 与 DELEGATING 两个阶段直接产出内联回复从而显著降低响应延迟。文档同时给出了 Auto 管线的测试覆盖说明新增 Auto 管线、委派、schema 与autocapability 表面的测试共1100 行其中包含端到端的 agent 循环行为测试。三、Memory v2三层记忆子系统v1.4.0-beta 用一套带显式整合管线consolidation pipeline和专用工作台的三层结构化存储取代了原先扁平的记忆页面。3.1 L1 / L2 / L3 分层布局L1捕获原始运行轨迹raw run tracesL2存放规范化后的文档记录normalised document recordsL3按交互表面chat、notebook、book、TutorBot维护精选插槽curated slots。多用户隔离是通过PathService保证的每位用户的路径都经由它派生使多用户部署下的 L1/L2/L3 数据彼此隔离。相关实现分布在 deeptutor/services/memory/含store.py、document.py、ids.py、ops.py、paths.py、trace.py与专门的consolidator/子目录。3.2 Consolidator 整合管线管线采用模块化设计deeptutor/services/memory/consolidator/ 下按职责拆分为 chunker分块、guards守卫校验、parse解析、references引用、runs运行轨迹、modes模式、line-doc行文档、meta元数据等模块。它们把运行轨迹转换为带版本的行导向文档versioned line-oriented documents便于增量追溯稳定 id对应ids.py的实现层与层之间的引用关系references快照历史snapshot。3.3 记忆工作台 UI 与新的 /memory 路由前端新增独立页面路由graph、l1、l2、l3、resolve承载工作台workbench、中枢hub、图查看器graph viewer、运行面板run panel与归档状态横幅。同时导出一个可复用的MemorySection组件嵌入到原遗留记忆面板所在的位置使旧 UI 位置的迁移成本最低。3.4 作为一等公民的聊天工具read_memory 与 write_memory记忆不再需要单独保存步骤read_memory与write_memory被暴露为 agent 工具并附带 i18n 提示文案因此 chat / Auto 可以在同一个回合内主动回忆与更新记忆这为终身个性化辅导项目定位 Lifelong Personalized Tutoring提供了会话内的记忆通路。3.5 设置集成与数据迁移记忆模块在/settings/memory下拥有独立设置页提供运行控制、模式开关与存储状态展示。升级路径上无需手动干预consolidator 会在首次访问时读取遗留的单 blob 记忆格式并回写为 L2/L3 记录旧快照保留在磁盘上详见原文档 Upgrade Notes 的 Memory data migration 小节。记忆子系统的完整测试覆盖了 chunker、consolidator、document、ids、line-doc、merge、meta settings、modes、ops、references、runs、store 各模块。四、Deep Research / Deep Solve / Question 迁移到共享 Agentic 引擎发布说明明确三条多 agent 管线被重写为共享 agentic-engine 原语之上的编排器成百上千的专用 prompt 文件与 per-agent 类被删除。4.1 Deep Research → agents/research/pipeline.py新管线包含四个阶段Rephrase改写、Decompose拆解、Research blocks研究块、Reporting成稿全部实现为带标签的步骤labeled stepsTHINK/TOOL/APPEND/OUTLINE/SECTION/FINISH。源码侧对应 deeptutor/agents/research/pipeline.py同目录还包含capability.py、mode_strategy.py、request_config.py、data_structures.py等模块。两处关键演进动态话题队列与 CitationManager 被保留同时新增APPEND标签让研究块可以在不离开循环的情况下把后续话题追加回队列——这是旧版 pipeline 做不到的ask_user v2驱动最多三轮 rephrase并且支持多问题卡片一次向用户提出多个澄清问题。4.2 Deep Solve → agents/solve 管线Solve 的阶段为Pre-retrieve仅限知识库 KB 检索→Plan规划→Solve求解内部是每步THINK/TOOL/FINISH/REPLAN的循环且有一条从 solve 回连到 plan 的返回边支持重新规划→ 最终Synthesize综合。架构上的精妙点是每个步骤的FINISH会流入下一步骤的 prompt 上下文从而让最终答案读起来是一段连续叙事而不是割裂的步骤拼贴。注意在 v1.4.0-beta 之后求解相关实现被收纳进统一的 deeptutor/capabilities/solve/ 能力目录说明 Capabilities 基础设施的统一同时重塑了目录组织。4.3 Question / Quiz 与旧目录删除问答/测验由coordinator pipeline取代了旧的generator/idea_agent/models模块对应的旧 prompt 目录被整体移除。三条管线均删除了各自模式的遗留agents/与prompts/目录最终只保留一个 pipeline 文件 共享的 labeled-step prompts。4.4 引擎层labeled-step 原语上述所有标签THINK/TOOL/APPEND/OUTLINE/SECTION/FINISH/REPLAN的语义定义与执行机制集中在 deeptutor/core/agentic/labels.py 与 labeled_step.py当前仓库 core/agentic 目录沿用此结构chat / research / solve / question 的管线测试均已对照这些引擎标签完成重构适配。五、聊天能力与 LlamaIndex RAG 重构聊天 agentic 管线围绕会话累积式session-cumulativeAttached Sources清单与更干净的 LlamaIndex 管线重建。5.1 分支隔离的来源清单source_inventory.py核心实现位于 deeptutor/services/session/source_inventory.py模块文档清晰地解释了设计动机历史上每次只展示当前回合用户附加的来源模型一旦不在本回合重新附加就会遗忘更早回合上传过的内容。新机制累积式清单沿当前分支的祖先链物化所有来源active branchs ancestor chain新来源fresh本回合新附加的来源获得完整预览源码中MANIFEST_PREVIEW_CHARS_FRESH 2000控制了预览字符上限方便模型回答是不是这个文件类的快速判断历史来源historical以单行压缩条展示——id、name、kind、size 与首次出现的回合序号。只有当问题确实需要全文时模型才调用read_source(id)按需展开工具通过 tool-call kwargs 注入每回合的{source_id: full_text}映射去重规则两集合按 source id 去重fresh 冲突时优先分支隔离通过从活跃分支叶子节点沿parent_message_id回溯实现兄弟分支之间永不互相泄漏来源图片附件走多模态块路径绝不会进入文本清单见源码中_IMAGE_MIME_PREFIX判定。清单渲染与其余 turn_runtime 逻辑解耦inventory await build_inventory(...)随后manifest_text, source_index render_manifest(inventory)前者喂给 LLM后者喂给工具。5.2 LlamaIndex 管线拆分原先单体式的 pipeline 模块被拆为职责清晰的四个文件config.py配置、ingestion.py摄取、retrievers.py检索器、document_loader.py文档加载。存储层保持与 v1.3 版本化索引的向后兼容老索引无需重建即可继续使用。5.3 精简的 agentic chat prompt 与内置工具注册表agentic_chat.yamlEN/ZH 双语被重写以匹配新工具面与来源清单契约旧的并行工具 prompt 脚手架被移除。聊天挂载工具、提示文案与参数增强包装器arg-augmentation wrappers的注册统一收口到 deeptutor/tools/builtin/init.py 这一个位置。六、Capabilities 基础设施统一从 v1.4.0-beta 开始每个能力都经由同一套结果信封result envelope、同一个状态 i18n 加载器、同一个成本跟踪面完成收尾。6.1 emit_capability_result 统一出口共享辅助函数定义在 deeptutor/agents/_shared/capability_result.py。它统一了此前各能力的收尾差异stream.result({response: ...}, sourcecap)之前只有部分能力会附带cost_summarysolve、research、question follow-up 各自内联合并过visualize、math_animator 甚至完全没做导致消息尾部$cost · tokens · calls的展示不一致。现在每个能力都通过这一个 helper 收尾它会将UsageTracker.summary()的结果合并进payload[metadata][cost_summary]保留可能已存在的payload[metadata]最终await stream.result(payload, sourcesource)统一发射。每个能力因此产出一致的信封结构label、summary、payload、render hints与一致的成本统计。6.2 StatusI18n去掉硬编码英文状态串能力运行时的状态文案stream.thinking、stream.progress、stream.error过去散落为硬编码英文。现在能力状态文案统一存于各能力的prompts/{en,zh}/name.yaml由共享的StatusI18n访问器加载实现见 deeptutor/i18n/status_i18n.pyYAML 文件内含单个顶层status:映射key → string文案支持{name}占位符经str.format渲染缺 key 或缺文件时回退到调用方传入的default参数保证翻译尚未补齐时新字符串仍可工作StatusI18n的构造被推迟到请求期懒加载get_prompt_manager避免在运行时 bootstrap 期间产生导入环。6.3 UsageTracker 成本面与 /settings/capabilities每次能力运行通过一个UsageTracker跟踪 token 用量与成本结果暴露在结果信封中并在新增的/settings/capabilities管理页上展示——该页包含实时清单、默认值、每个能力的覆盖开关。作为配套清理遗留的main.yaml能力文案被删除改为 per-capability prompt 文件当前仓库中 deeptutor/agents/visualize/prompts/en/visualize.yaml 与 zh 版本即为该结构的示例。七、Visualize 收敛 Animator六种渲染类型一个入口独立的 Animator 菜单被并入 Visualize用户只需选一次我要可视化系统自动挑选渲染器。机制核心是render_type判别器AnalysisAgent在六种渲染类型中选择——svg、chartjs、mermaid、html文本发射型、三段式管线以及manim_video/manim_imageManim 子进程管线。结果信封携带render_type前端据此委派到对应的查看器。旧的Animator侧边栏菜单项被删除静态图表与 Manim 视频统一经由Visualize入口全屏查看器 / 配置面板覆盖全部渲染类型。对老用户的影响与迁移在 Upgrade Notes 中说明动画 / 视频类需求改为指向Visualize当用户请求视频/动画时该能力会自动挑选 Manim已渲染的 Manim 记录不受影响。渲染决策相关实现可在 deeptutor/agents/visualize/ 下查看。八、新聊天工具面五个工具详解8.1 ask_user结构化提问 暂停回合把 1–3 个结构化问题打包进单个 payload暂停当前回合直到用户作答。前端渲染卡片用户可在一次批量提交中浏览问题并作答管线随后恢复回合把答案作为工具结果接回。它同时被 Deep Research 的 Rephrase 阶段使用也向 chat / Auto 开放。8.2 web_fetch受保护的 URL 抓取URL 抓取 可读内容抽取并带三层严格防护scheme 校验、私网 IP 屏蔽、大小上限——这些检查既在预检阶段执行也在重定向之后再次执行防止跟随跳转绕过防护。当输出超过上限时以…[truncated]标记截断。8.3 write_note取代 save_to_notebook两种模式append新建一条记录默认正文为渲染后的会话转写也可传入 agent 撰写的正文edit按record_id更新既有记录。8.4 list_notebook只读索引 / 下钻只读地列出当前活跃用户的 notebook 与记录支持索引与下钻。工程上的亮点是只有当用户确实拥有 notebook 时才挂载该工具从而从构造上杜绝空跑empty runs impossible by construction。8.5 github_querygh CLI 只读封装覆盖pr、issue、run、repo及 GET-only 的api回退任何变更动词都无法通过工具面触达。当系统未安装gh时返回干净的 tool unavailable 结果。工具源码对应 deeptutor/tools/ask_user.py、web_fetch.py、write_note.py、list_notebook.py、github_query.py发布说明同时给出各工具的单元测试含 ask-user UI 状态辅助函数覆盖。九、聊天界面功能增强9.1 删除聊天回合消息条目携带稳定id会话 API 暴露deleteMessagechat reducer 新增DELETE_TURNaction。并发安全上以 409 与 404 区分——拒绝删除仍在运行中的回合乐观临时 id 在删除前先被解析避免产生孤儿 UI 行。9.2 测验追问式聊天 ComposerFollowupChatComposer与QuizFollowupContext允许用户从某道测验题直接开启聊天线程。Composer 复用主ChatComposer的完整外观space 选择器、知识库选择器、附件、LLM 选择器等但发送动作路由到专用 follow-up 控制器配套的quiz-judge.ts前端 helper 支持对追问答案进行内联评判。9.3 Quiz UI 打磨与 GeoGebra 查看器测验答案文本框支持垂直拉伸题目内容把单个换行规范化为 Markdown 段落Geogebra.tsx、GeogebraOpenCTA.tsx与GeogebraTabContext组合出一个 GeoGebra applet 渲染器经官方 GGB applet 脚本加载使几何 / 代数代码片段可紧贴聊天答案内联打开。十、多用户数据隔离修正v1.3.x 引入多用户后遗留的若干回归在此次集中修复鉴权与中间件解耦多用户身份解析不再依赖全局 middleware 状态修复了特定路由顺序下导致跨用户数据混入cross-user data bleed的 rebase 回归遗留 session manager 路径捕获旧版 session manager 正确继承活跃用户作用域使其文件路径落到 per-user workspace 而非共享默认目录前端全面走 apiFetch所有需鉴权的客户端调用统一经apiFetch()确保认证头一致附加SSL 绕过补齐DISABLE_SSL_VERIFY的覆盖范围扩展到 codex provider 与 v1.3.10 之后仍遗漏的四个 embedding 适配器。十一、环境设置、安装器与本地启动器重写安装与启动链路被彻底重写目标是把.env解析迷宫移除让deeptutor start/deeptutor init成为一等公民。runtime_settings.py 路径下类型化设置模块系统 / 鉴权 / 启动设置收敛为一个类型化模块带显式默认值backend_port、frontend_port、cors_origins、disable_ssl_verify、chat_attachment_dir等JSON 存储于data/user/settings/。280 行的遗留env_store.py与两个.env.example文件被删除runtime/launcher.py单一异步启动器统一负责后端 前端的生命周期、端口发现、就绪探测与清理并生成web/.env.local使 Next.js 前端总能拿到解析后的后端端口runtime/banner.py本地化启动横幅deeptutor start与deeptutor init共用从界面设置读取语言偏好使横幅与 UI 语言一致init_wizard.py交互式deeptutor init向导提供 provider 菜单、API key 的环境变量自动探测、实时GET {base_url}/models拉取、精选回退列表以及保存前的可选连通性探测model_catalog.py 瘦身per-provider 样板逻辑移入provider_registry与适配器模块后目录文件缩减约 400 行。十二、Settings UI 重组单一/settings页面被拆分为聚焦的选项卡路由/settings/appearance、/settings/capabilities、/settings/embedding、/settings/llm、/settings/mcp、/settings/memory、/settings/search、/settings/status、/settings/tools共享同一布局与条目索引。其中两个页面对应前述基础设施Tools 页列出每个可挂载的聊天工具显式呈现可用性如github_query依赖系统是否安装gh并提供 per-tool 开关Capabilities 页把UsageTracker成本面与 per-capability 默认值、覆盖开关配对展示。十三、Zulip 频道TutorBot加固v1.3.9 加入的 Zulip 频道在本版本获得一轮集中修复与自订阅能力提及频道的自动订阅Bot 可在被 提及的任意频道中订阅自己从而真正在 topic 中收到消息订阅频道告警降级为 info 级避免启动日志把成功路径误报为异常四种提及类型全支持mentioned、wildcard_mentioned、topic_wildcard_mentioned、stream_wildcard_mentioned都会触发 Bot修复了频道级提及静默问题附件发送修复重发附件不再把 Zulip 上传路径误当本地文件上传 helper 不再因str object has no attribute name崩溃缺失的路由元数据会从_recipient_map重建消除Message must have recipients错误进度消息去重内部_tool_hint进度事件在频道发送前被过滤用户不再看到重复的 tool starting… 行测试补充新增附件上传 发送恢复、频道订阅行为的单元测试。相关实现位于 deeptutor/partners/channels/。十四、测试矩阵Auto 管线 / 委派 / schema / 能力表面1100 行新增覆盖含端到端 agent 循环记忆子系统全覆盖chunker、consolidator、document、ids、line-doc、merge、meta settings、modes、ops、references、runs、store每个新工具的单元测试ask_user、github_query、list_notebook、web_fetch、write_note以及 ask-user UI 状态辅助函数chat / research / solve / question 管线测试按 agentic-engine 标签重构适配会话 / source-inventory 测试覆盖分支隔离与累积式清单行为前端测试message-branches helper、version surface、ask-user 状态机。对应回归与新增测试可分别在 tests/agents/、tests/core/agentic/、tests/services/memory/、tests/services/session/ 等测试目录中继续挖掘。十五、升级与迁移指南发布说明的 Upgrade Notes 给出了五种迁移场景本版本用户按需对照执行设置文件迁移自动首次启动会把.env风格设置迁移到data/user/settings/下的新 JSON 文件。遗留env_storeshim 已删除若此前有外部脚本直接改写.env需改为指向runtime_settings.py或/settingsAPI启动器切换deeptutor start是推荐启动方式。start_web.py/start_tour.py继续可用但已降级为对runtime/launcher.py的薄包装。新机器上先运行一次deeptutor init播种 provider 与凭据Animator 菜单用户动画/视频需求改走Visualize该能力会在用户请求视频/动画时自动选择 Manim既有 Manim 记录不受影响记忆数据迁移自动legacy 单 blob 格式在首次访问时由 consolidator 读取并回写为 L2/L3 记录无需手动步骤旧快照保留在磁盘Capability 作者规范结果必须经capabilities/_shared.emit_capability_result统一发射当前仓库对应 deeptutor/agents/_shared/capability_result.py状态文案放入capabilities/prompts/{en,zh}/name.yaml硬编码英文状态串将无法通过评审Beta 范围确认Auto、Memory v2、Settings 拆分均为新表面GA 前建议生产固定v1.4.0-beta。十六、总结v1.4.0-beta 的价值不在于某个单一功能而在于确立了 DeepTutor 后续演进的结构性范式所有多步任务收敛到带标签的 agentic 引擎步骤所有能力共享统一的结果信封、状态 i18n 与成本跟踪会话记忆与来源管理围绕分支隔离 累积式的语义重建安装与启动统一收口到类型化设置与单一 launcher。这套范式使得后续的 Deep Research、Deep Solve、Memory 演进都可以复用引擎、新增编排而非为每个模式再造一套运行机制。对希望深入源码的读者建议按三条线索继续阅读deeptutor/core/agentic/引擎原语与标签语义、deeptutor/services/session/source_inventory.py会话累积来源清单、deeptutor/i18n/status_i18n.py 与 deeptutor/agents/_shared/capability_result.py统一基础设施。【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考