DeepTutor — 智能体原生架构¶

概述¶

DeepTutor 是一个智能体原生（agent-native）智能学习伴侣，围绕两层插件模型组织——由 LLM 调用的单次工具（Tools），以及接管整轮对话的多阶段能力（Capabilities）——并通过三个入口暴露：CLI、WebSocket API 和 Python SDK。三者都先进入持久化回合应用服务（TurnApplicationService），再由共享回合引擎（TurnEngine）将规范化后的上下文路由到所选能力。

架构¶

Entry Points:  CLI (Typer)  |  WebSocket /ws  |  Python SDK
                    ↓                   ↓                   ↓
              ┌─────────────────────────────────────────────────┐
              │          TurnApplicationService                 │
              │   persists, coordinates, and replays turns      │
              └──────────────────────┬──────────────────────────┘
                                     ↓
              ┌─────────────────────────────────────────────────┐
              │       TurnEngine → ChatOrchestrator              │
              │   routes UnifiedContext → selected Capability    │
              │   (defaults to `chat`)                           │
              └──────────┬──────────────┬───────────────────────┘
                         │              │
              ┌──────────▼──┐  ┌────────▼──────────┐
              │ ToolRegistry │  │ CapabilityRegistry │
              │  (Level 1)   │  │   (Level 2)        │
              └──────────────┘  └────────────────────┘

TurnApplicationService 通过会话存储和运行时协调器（runtime coordinator）负责持久化的回合状态与回放。每次执行使用按回合独立的 StreamBus；编排器发出事件，回合运行时持久化事件，适配器向消费者回放事件。运行时设置位于 data/user/settings/*.json —— 项目根目录下的 .env 文件会被刻意忽略。

第 1 层 — 工具¶

由 LLM 按需选择的单功能工具。八个用户可开关工具在 /settings/tools 中展示：

工具	描述
`brainstorm`	带理由的广度优先想法探索
`web_search`	带引用的网络搜索
`paper_search`	arXiv 预印本搜索
`zotero_search`	搜索已配置的 Zotero 文献库
`reason`	专用的深度推理 LLM 调用
`geogebra_analysis`	将数学图像分析为 GeoGebra 命令
`imagegen`	生成图像
`videogen`	生成视频

deeptutor/tools/builtin/__init__.py 中的 USER_TOGGLEABLE_TOOL_NAMES 是权威的开关列表。其他内置工具为上下文门控（context-gated）或能力所属：CONFIGURABLE_BUILTIN_TOOL_NAMES 声明上下文门控的表层，而 deeptutor/agents/_shared/tool_composition.py 负责挂载规则（ToolMountFlags）以及始终可用的工作区工具。示例包括 rag、记忆与笔记本工具、read_skill、延迟的 MCP/CLI 工具、exec、ask_user 以及精通度导航（mastery navigation）。--tool 从用户可开关白名单中选择；它不会绕过上下文或能力门控。

第 2 层 — 能力¶

接管整轮对话的多阶段流水线：

能力	阶段
`chat`	exploring → responding（单一智能体循环，默认）
`ask_questions`	responding（聊天循环强制通过 `ask_user`）
`deep_solve`	responding（聊天循环 + 求解规划工具）
`deep_question`	ideation → generation
`deep_research`	rephrasing → decomposing → researching → reporting
`visualize`	analyzing → generating → reviewing（SVG / Chart.js / Mermaid / HTML；或通过 `render_type` 路由到 Manim 子阶段）
`math_animator`	concept_analysis → concept_design → code_generation → code_retry → summary → render_output
`mastery_path`	responding（引导式学习——聊天循环 + 精通度工具，按主题类型门控）
`immersive_reading`	responding（基于文档或时间戳的媒体阅读循环）
`video_lesson`	code_generation → render_check → render_output（Remotion 课程在浏览器中实时播放，带 TTS 旁白）

所有能力最终都汇聚到 deeptutor/agents/_shared/capability_result.py 中的 emit_capability_result()，因此每一轮都会发出相同的信封结构（响应载荷 + 来自 UsageTracker 的 cost_summary）。状态文案和提示词通过 capabilities/prompts/{en,zh}/<name>.yaml 实现国际化。

CLI 用法¶

# Install from the current dev source checkout
python -m pip install -r requirements/full.txt
python -m pip install -e . --no-deps

# Alternative in 1.7.0: choose one in a separate wheel environment
python -m pip install "deeptutor[full]"  # Full app, CLI + Web/API
python -m pip install deeptutor         # Core CLI/SDK (chat + ask_questions)
python -m pip install deeptutor-cli     # Compatibility alias for core

# Run any capability
deeptutor run chat "Explain Fourier transform"
deeptutor run deep_solve "Solve x^2=4" --kb my-kb
deeptutor run visualize "Animate sine wave" --config render_mode=manim_video

# Interactive REPL
deeptutor chat
# (inside the REPL: /regenerate or /retry re-runs the last user message)

# Partners (IM-connected companions)
deeptutor partner list

# Knowledge bases, memory, server
deeptutor kb list
deeptutor kb create my-kb --doc textbook.pdf
deeptutor memory show
deeptutor serve --port 8001       # API server only
deeptutor start                   # backend + frontend together

核心之外的示例需要其所属模块；使用 deeptutor module list 检查已安装/已启用/就绪状态，使用 deeptutor plugin list 发现已注册的能力和工具。源码方式启动 Web 还需要 Node.js 22 LTS，并在 web/ 中执行 npm ci --legacy-peer-deps。仅使用 CLI 的源码用户可以跳过前端设置，但仍需要完整的 Python 依赖。请按照 Agent 设置获取凭据并进行验证。

关键文件¶

路径	用途
`deeptutor/runtime/orchestrator.py`	`ChatOrchestrator` — 统一入口
`deeptutor/runtime/launcher.py`	后端 + 前端生命周期 / 端口发现
`deeptutor/runtime/registry/`	工具 + 能力注册表
`deeptutor/runtime/bootstrap/builtin_capabilities.py`	内置能力类路径
`deeptutor/services/config/runtime_settings.py`	JSON 设置 + 进程环境变量覆盖
`deeptutor/services/subagent/`	本地/远程智能体连接器；在 `registry.py` 中注册每个后端，并在 `models.py` 中注册其模型选项（Grok CLI 使用原生 `streaming-json`）
`deeptutor/core/stream.py`, `deeptutor/runtime/stream_bus.py`	StreamEvent 协议 + 异步扇出
`deeptutor/core/tool_protocol.py`	`BaseTool` + `ToolDefinition`
`deeptutor/core/capability_protocol.py`	`TurnCapability` + `CapabilityManifest`
`deeptutor/core/context.py`	`UnifiedContext` 数据类
`deeptutor/tools/builtin/__init__.py`	所有内置工具包装器
`deeptutor/capabilities/`	内置能力实现
`deeptutor/app/`	`DeepTutorApp` SDK 外观 + 持久化应用服务
`deeptutor_cli/main.py`	Typer CLI 入口点
`deeptutor/api/routers/unified_ws.py`	统一 WebSocket 端点

依赖层级¶

1.7.0 的布局是模块化的；1.6.15 及更早的包使用旧布局。核心拥有 CLI、SDK 和共享运行时；功能 wheels 必须与其版本匹配。deeptutor-cli 是仅包含元数据的兼容别名。开发时请使用源码或本地 wheels。

模块清单各自拥有依赖组；生成的 requirements 文件支持源码、Docker 和 CI 安装。pyproject.toml 在 tool.deeptutor.optional-dependencies 下存储额外模板；build_metadata.py 解析同版本 wheel 的版本锁定。源码检出会暴露所有模块，并通过 requirements/full.txt 安装外部依赖，随后执行 pip install -e . --no-deps。对于可选附加项，请使用源码辅助脚本，而不要在检出目录上安装功能 wheels：

python scripts/install_extras.py partners       # Partner channel SDKs
python scripts/install_extras.py matrix         # Matrix channel without E2EE/libolm
python scripts/install_extras.py matrix-e2e     # Matrix with end-to-end encryption
python scripts/install_extras.py math-animator  # Manim; also needs system LaTeX/ffmpeg
python scripts/install_extras.py dev            # Test / lint tooling
python scripts/install_extras.py all            # Full + Manim + dev dependencies

进行模块更改前，请先停止 DeepTutor。源码支持 module enable/disable；wheel 环境也支持 module install/uninstall。升级旧版 deeptutor-cli 安装时，需要先卸载它，再安装新包，并保留相同的 DEEPTUTOR_HOME；请参阅设置指南。使用 python -m pip check、deeptutor module list 以及设置就绪检查进行验证。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 dee/DeepTutor