DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
docs: align agent and manual setup with modular dev
Bingxi Zhao (Frank)a6389d7ee8ba
diff --git a/AGENTS.md b/AGENTS.mdindex 76df4e09b..1294a2d78 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -40,7 +40,7 @@ ignored.### Level 1 — Tools-Single-function tools the LLM picks on demand. Seven user-toggleable tools+Single-function tools the LLM picks on demand. Eight user-toggleable toolssurface in `/settings/tools`:| Tool | Description |@@ -48,6 +48,7 @@ surface in `/settings/tools`:| `brainstorm` | Breadth-first idea exploration with rationale || `web_search` | Web search with citations || `paper_search` | arXiv preprint search |+| `zotero_search` | Search a configured Zotero library || `reason` | Dedicated deep-reasoning LLM call || `geogebra_analysis` | Analyze math images into GeoGebra commands || `imagegen` | Generate images |@@ -87,13 +88,18 @@ prompts are i18n'd via `capabilities/prompts/{en,zh}/<name>.yaml`.## CLI Usage```bash-# Install-pip install deeptutor # Full app (CLI + Web/API + packaged Web assets)-pip install deeptutor-cli # CLI-only+# Install from the current dev source checkout+python -m pip install -r requirements/full.txt+python -m pip install -e . --no-deps++# Alternative after 1.7.0 publication: 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 capabilitydeeptutor run chat "Explain Fourier transform"-deeptutor run deep_solve "Solve x^2=4" -t rag --kb my-kb+deeptutor run deep_solve "Solve x^2=4" --kb my-kbdeeptutor run visualize "Animate sine wave" --config render_mode=manim_video# Interactive REPL@@ -111,6 +117,13 @@ deeptutor serve --port 8001 # API server onlydeeptutor start # backend + frontend together```+Examples beyond core require their owning modules; use `deeptutor module list`+to inspect installed/enabled/ready states and `deeptutor plugin list` to discover+registered capabilities and tools. Source Web startup also needs Node.js 22 LTS+and `npm ci --legacy-peer-deps` in `web/`. CLI-only source users can skip frontend+setup, but still need the full Python dependencies. Follow+[Agent Setup](docs-for-user/AGENT_SETUP.md) for credentials and verification.+## Key Files| Path | Purpose |@@ -133,21 +146,30 @@ deeptutor start # backend + frontend together## Dependency Layers-Public install paths and source extras are defined in `pyproject.toml`.-Requirements files mirror the same dependency groups for Docker/CI installs.+The current `dev` layout is modular; published 1.6.15 packages still use the+previous layout. Core owns the CLI, SDK and shared runtime; feature wheels must+match its version. `deeptutor-cli` is a metadata-only compatibility alias.+Before publication, use source or [local wheels](docs-for-dev/MODULES.md).+Module manifests own dependency groups; generated requirements files support+source, Docker and CI installs. `pyproject.toml` stores extra templates under+`tool.deeptutor.optional-dependencies`; `build_metadata.py` resolves same-version+wheel pins. Source checkouts expose all modules and install external dependencies+through `requirements/full.txt`, followed by `pip install -e . --no-deps`.+Use the source helper for optional extras rather than installing feature wheels+over the checkout:++```bash+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```-pip install deeptutor — Full app (CLI + Web/API + packaged Web assets)-pip install deeptutor-cli — CLI-only (LLM + RAG + providers + document parsing)-pip install -e . — Source install for development--Source extras (.[ extra ], defined in pyproject.toml):-.[cli] — CLI-only dependency set-.[server] — Web/API server dependencies-.[partners] — Partner channel SDKs (legacy alias: .[tutorbot])-.[matrix] — Matrix channel for Partners (matrix-nio; needs libolm)-.[matrix-e2e] — Matrix with end-to-end encryption (matrix-nio[e2e])-.[math-animator] — Manim addon (powers `visualize` Manim renders + `deeptutor run math_animator`)-.[dev] — Test / lint tooling-.[all] — Everything above-```++Stop DeepTutor before module changes. Source supports `module enable/disable`;+wheel environments also support `module install/uninstall`. Upgrading a legacy+`deeptutor-cli` installation requires uninstalling it before installing the new+packages, preserving the same `DEEPTUTOR_HOME`; see the setup guide. Validate+with `python -m pip check`, `deeptutor module list`, and the setup readiness checks.diff --git a/README.md b/README.mdindex d11d4a6d3..482b33841 100644--- a/README.md+++ b/README.md@@ -257,8 +257,8 @@ DeepTutor is an agent-native learning workspace that connects tutoring, problemCopy this prompt into your terminal-capable AI agent (such as Codex or Claude Code):```text-Help me install and configure DeepTutor locally from https://github.com/HKUDS/DeepTutor.-Clone the repository, or reuse my existing checkout, and read SKILL.md and+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, and read SKILL.md anddocs-for-user/AGENT_SETUP.md first. Follow that 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;diff --git a/SKILL.md b/SKILL.mdindex 12e738baa..8f4205f54 100644--- a/SKILL.md+++ b/SKILL.md@@ -54,6 +54,15 @@ is not proof of readiness: report actual verification and any unfinished step.## Commands+Examples below cover the full installation and optional add-ons. Core provides+`chat` and `ask_questions`; other capabilities and resource commands require+their owning modules. Check `deeptutor module list` for installed/enabled/ready+states and `deeptutor plugin list` for registered capabilities and tools. Stop+DeepTutor before changing modules. Source checkouts use `module enable/disable`+and `python scripts/install_extras.py <extra>` for optional dependencies;+wheel installations also support `module install/uninstall`. Before publication,+pass `--wheelhouse /path/to/wheels` to `module install` (see [Modules](docs-for-dev/MODULES.md)).+### Chat & Capabilities```bash@@ -86,7 +95,7 @@ deeptutor run math_animator "Visualize a Fourier series"`deeptutor chat` accepts the same `--session / --tool / --kb / --notebook-ref / --history-ref / --language / --config / --config-json` options, plus `--capability/-c <name>` to set the initial capability.-**Tools** for `--tool` / `-t`: user-toggleable tools are `brainstorm`, `web_search`, `paper_search`, `reason`, `geogebra_analysis`, `imagegen`, and `videogen`. Context-gated tools (`rag`, `exec`, memory, notebook, …) mount according to context/capability rules; `--tool` does not bypass those rules. Mount a knowledge base with `--kb` for RAG. Run `deeptutor plugin list` for the registered set.+**Tools** for `--tool` / `-t`: user-toggleable tools are `brainstorm`, `web_search`, `paper_search`, `zotero_search`, `reason`, `geogebra_analysis`, `imagegen`, and `videogen`. Context-gated tools (`rag`, `exec`, memory, notebook, …) mount according to context/capability rules; `--tool` does not bypass those rules. Mount a knowledge base with `--kb` for RAG; Knowledge Frontier also needs the research module. Run `deeptutor plugin list` for the registered set.### Knowledge Bases@@ -185,6 +194,7 @@ deeptutor config providers # Supported setup providersdeeptutor config apply <file.json> [--check] [--home <path>] # Apply/validate setup JSONdeeptutor plugin list # List registered tools and capabilitiesdeeptutor plugin info <name> # Show a tool/capability's schema + availability+deeptutor module list # Inspect installed / enabled / ready statesdeeptutor serve [--host 0.0.0.0] [--port 8001] [--reload] # Start the API serverdeeptutor start [--home <path>] [--detach] [--no-browser] # Launch backend + frontenddeeptutor stop [--home <path>] # Stop a detached launcher@@ -214,13 +224,20 @@ Inside `deeptutor chat`, use these:## Typical Workflows-**First-time setup:**+**First-time source setup (after preparing the environment in the setup guide):**```bashcd DeepTutor-pip install -e .+python -m pip install -r requirements/full.txt+python -m pip install -e . --no-deps+python -m pip check+deeptutor module listdeeptutor init # Interactive guided setup (add --cli for CLI-only)```+For the Web UI, install Node.js 22 LTS and run `npm ci --legacy-peer-deps`+in `web/` before starting. CLI-only users can skip frontend setup. Follow the+setup guide's readiness checks; initialization alone does not verify the model.+**Daily learning:**```bashdeeptutor chat --kb textbook --tool web_searchdiff --git a/deeptutor_cli/README.md b/deeptutor_cli/README.mdindex 75ee60630..8e6d3c593 100644--- a/deeptutor_cli/README.md+++ b/deeptutor_cli/README.md@@ -11,7 +11,7 @@ Agent-first 的命令行界面。两条核心路径:```bash# 从源码使用 CLI(包含各功能模块的 Python 依赖,不安装前端)-git clone https://github.com/HKUDS/DeepTutor.git+git clone --branch dev https://github.com/HKUDS/DeepTutor.gitcd DeepTutorpython3 -m venv .venv-clisource .venv-cli/bin/activate@@ -20,21 +20,24 @@ python -m pip install -r requirements/full.txtpython -m pip install -e . --no-depsdeeptutor init --cli-# CLI + Web/API 服务-pip install "deeptutor[full]"-deeptutor init--# 源码开发-pip install -r requirements/full.txt-pip install -e . --no-deps-deeptutor init-# 可选附加组件python scripts/install_extras.py partners # Partners 渠道 SDK + MCP 客户端python scripts/install_extras.py math-animator # 数学动画(另需系统 LaTeX/ffmpeg)python scripts/install_extras.py all # 全部依赖(含开发工具)```+源码 CLI 用户可跳过前端;需要 Web UI 时,安装 Node.js 22 LTS,在 `web/`+执行 `npm ci --legacy-peer-deps`,回到项目根目录执行 `deeptutor init` 和+`deeptutor start`。使用 Python 3.11–3.14;复用已有 checkout 时先检查分支和本地改动。++1.7.0 发布后,也可在独立环境中直接安装 wheel,以下命令与上面的源码流程二选一:++```bash+python -m pip install "deeptutor[full]" # 完整 Web 应用;最小 CLI 使用 deeptutor+deeptutor init+deeptutor start+```+`deeptutor init --cli` 和普通 `deeptutor init` 使用同一套 `data/user/settings/` 配置目录;区别是 `--cli` 不询问 Web 后端/前端端口,仍会创建 `system.json`、`auth.json`、`integrations.json`、`model_catalog.json`、`main.yaml` 和 `agents.yaml`,并继续询问 LLM 配置。Embedding 配置默认跳过;如果要使用 `deeptutor kb ...` 或 RAG,请在向导里选择配置 embedding,或稍后编辑 `data/user/settings/model_catalog.json`。Windows PowerShell 可使用:@@ -52,7 +55,7 @@ deeptutor init --cli## 从 1.6.15 CLI 升级-停止程序并备份 runtime home 后,先运行 `python -m pip uninstall deeptutor-cli`,再安装 `deeptutor-cli==1.7.0`(完整 Web 应用安装 `deeptutor[full]==1.7.0`)。旧 CLI 包拥有共享代码,直接升级会在卸载旧包时删掉新核心;先卸载可避免这一冲突,且不会删除用户数据。保持原 `DEEPTUTOR_HOME`,安装后运行 `python -m pip check` 和 `deeptutor module list`。拆分包发布前使用本地 wheelhouse 的 `--find-links` 参数。+1.7.0 发布后,停止程序并备份 runtime home,先运行 `python -m pip uninstall deeptutor-cli`,再安装 `deeptutor-cli==1.7.0`(完整 Web 应用安装 `deeptutor[full]==1.7.0`)。旧 CLI 包拥有共享代码,直接升级会在卸载旧包时删掉新核心;先卸载可避免这一冲突,且不会删除用户数据。保持原 `DEEPTUTOR_HOME`,安装后运行 `python -m pip check` 和 `deeptutor module list`。最小 core 不包含旧 CLI 的全部功能,需补装所需模块;拆分包发布前按 [本地 wheel 升级指南](../docs-for-dev/MODULES.md#upgrade-from-1615) 使用准确的候选版本。## `run` — 执行 Capability@@ -64,21 +67,28 @@ deeptutor run <capability> <message> [options]### 内置 Capability-| Capability | 说明 |-|------------|------|-| `chat` | 对话(默认,可挂载工具) |-| `deep_solve` | 多阶段深度解题 |-| `deep_question` | 智能出题 |-| `deep_research` | 多 agent 深度研究 |-| `visualize` | 生成图表、图解、Mermaid、HTML 或 Manim 可视化 |-| `math_animator` | 数学动画生成 |-| `mastery_path` | 掌握式学习路径与测评循环 |+以下功能取决于对应模块是否安装、启用及就绪。用 `deeptutor module list` 查看状态,+用 `deeptutor plugin list` 查看当前注册的 capability 和工具。++| Capability | 模块 | 说明 |+|------------|------|------|+| `chat` | core | 对话(默认,可挂载工具) |+| `ask_questions` | core | 通过提问澄清需求 |+| `deep_solve` | solve | 解题与规划 |+| `deep_question` | questions | 智能出题 |+| `deep_research` | research | 多 agent 深度研究 |+| `visualize` | visualize | 图表、图解、Mermaid、HTML;Manim 渲染另需 renderer-manim |+| `math_animator` | renderer-manim | 数学动画生成 |+| `mastery_path` | mastery | 掌握式学习路径与测评循环 |+| `immersive_reading` | reading | 基于文档或媒体的阅读辅导 |+| `video_lesson` | video-lesson | 带旁白的视频课程 |+| `audio_overview` | audio-overview | 音频概览 |### 选项| 选项 | 缩写 | 说明 ||------|------|------|-| `--tool` | `-t` | 启用工具(可多次指定):`web_search`, `reason`, `brainstorm`, `paper_search`, `geogebra_analysis`, `imagegen`, `videogen`;RAG 通过 `--kb` 挂载 |+| `--tool` | `-t` | 启用用户开关工具(可多次指定):`web_search`, `reason`, `brainstorm`, `paper_search`, `zotero_search`, `geogebra_analysis`, `imagegen`, `videogen`;RAG 通过 `--kb` 挂载 || `--kb` | | 挂载知识库 || `--language` | `-l` | 回复语言(默认 `en`) || `--session` | | 继续已有会话 |@@ -170,12 +180,16 @@ deeptutor chat [options]deeptutor serve [--host 0.0.0.0] [--port 8001] [--reload]```-`deeptutor serve` 需要 server 模块。wheel 安装可在停止服务后运行 `deeptutor module install server`;完整 Web 应用使用 `pip install -U "deeptutor[full]"`。源码安装使用 `requirements/full.txt`。+`deeptutor serve` 需要 server 模块。wheel 安装可在停止服务后运行 `deeptutor module install server`;完整 Web 应用在 1.7.0 发布后使用 `pip install -U "deeptutor[full]"`。模块未发布时,`module install` 需加 `--wheelhouse /path/to/wheels`。源码安装使用 `requirements/full.txt`,支持 `module enable/disable`,不使用 `module install/uninstall`。---## 资源管理命令+`kb`、`notebook`、`memory` 分别需要 knowledge、notebook、memory 模块;+`session`、`plugin`、`config` 属于 core。知识库导入还需 parsing;Knowledge Frontier+需要 knowledge 与 research,同时通过 `--kb` 提供上下文,不能靠 `--tool` 绕过挂载条件。+### `kb` — 知识库```bash@@ -245,11 +259,16 @@ deeptutor config apply setup.json [--home PATH] # 无交互应用配置所有步骤应使用同一个 `DEEPTUTOR_HOME`;根目录 `.env` 不会自动加载。```bash+python -m pip check # 检查当前环境的依赖一致性+deeptutor module list # 确认所需模块 installed / enabled / readydeeptutor doctor --format json # 本地就绪检查deeptutor doctor --online --format json # 发送一次小型 LLM 请求验证连接+deeptutor run chat "请回复一句简短问候。" --format json # 验证实际 turn 执行```-在线检查会产生提供方用量,只验证 LLM;需要 RAG 时还要验证 embedding 和小样本文档检索。+在线检查和聊天验收会产生提供方用量;确认收到有效回复且 turn 成功结束,不能只看配置保存成功。+需要 RAG 时还要验证 embedding 和小样本文档检索。Web 用户还需确认实际前端 URL+可访问且后端 `/health/ready` 就绪;CLI-only 无需启动 Web。### `provider` — 提供方认证 / 校验diff --git a/docs-for-user/AGENT_SETUP.md b/docs-for-user/AGENT_SETUP.mdindex 450cd3938..074d74fa7 100644--- a/docs-for-user/AGENT_SETUP.md+++ b/docs-for-user/AGENT_SETUP.md@@ -14,6 +14,8 @@ waiting:- Installation folder and any existing DeepTutor checkout.- Full Web app or CLI-only; default to the full app for the README setup prompt.+- Target version or branch. This guide describes current `dev`, including the+ upcoming 1.7.0 modular layout; use matching documentation for a stable release.- LLM provider, exact model ID, and any custom/local endpoint.- Credential source: an existing environment variable, a private local filethe user identifies, or provider login. Do not ask for keys in chat.@@ -27,10 +29,10 @@ used for learning materials.## 2. Clone and install-For a new full-app source installation (macOS/Linux example):+For a new full-app installation of current `dev` (macOS/Linux example):```bash-git clone https://github.com/HKUDS/DeepTutor.git+git clone --branch dev https://github.com/HKUDS/DeepTutor.gitcd DeepTutorpython3 -m venv .venvsource .venv/bin/activate@@ -50,8 +52,9 @@ and `deeptutor` by absolute path and pass environment variables to each process.For CLI use from source, keep the Python installation above and skip Node/npm.A source tree exposes all checked-in modules, so it still needs their Python-dependencies. For a minimal packaged CLI, install `deeptutor`; `deeptutor-cli`-is a compatibility alias for the same core. Add feature modules as needed.+dependencies. In the 1.7.0 package layout, `deeptutor` provides the minimal CLI;+`deeptutor-cli` is a compatibility alias for the same core. Add feature modules+as needed; this is not the layout of the published 1.6.15 packages.The upcoming 1.7.0 package layout uses `python -m pip install "deeptutor[full]"`for the complete Web app. Bare `deeptutor` contains core chat, CLI and SDK;@@ -71,8 +74,11 @@ installed core. This does not remove runtime-home data. You can then addcompatibility alias. For CLI-only migration, install `deeptutor-cli==1.7.0`after removing the old CLI, and add any feature modules you need.-Upgrading bare `deeptutor` no longer installs the full app. Do not reset-settings or change the runtime-home directory during this upgrade.+In 1.7.0, upgrading bare `deeptutor` selects only core; use `[full]` to retain+the full-app feature set. Do not reset settings or change the runtime-home+directory during this upgrade. For an existing checkout, inspect its branch,+commit and local edits before updating; do not silently switch branches or+replace the environment to match this example.## 3. Initialize without prompts@@ -189,11 +195,21 @@ is not automatically reused. Login does not select a model.## 5. Verify and start```bash+python -m pip check+deeptutor module listdeeptutor doctor --format jsondeeptutor doctor --online --format json```-The first checks local readiness; the second makes a small real model request+`pip check` checks dependency consistency. Inspect `module list` for the modules+needed by the user: installed, enabled, and ready are separate states. The Web+app needs server and web; RAG needs knowledge and parsing; optional capabilities+need their owning modules. Core-only intentionally omits these modules. Source+checkouts use `module enable/disable`; wheel installs also support+`module install/uninstall`. Stop DeepTutor before changes, and use+`--wheelhouse /path/to/wheels` for unpublished modules. See [Modules](../docs-for-dev/MODULES.md).++`doctor` checks local readiness; `doctor --online` makes a small real model requestand may incur provider usage. Inspect exit status and required failures. Fixactionable failures and rerun affected checks. Saved settings alone are notproof of readiness. The LLM probe does not verify optional embedding: when RAG@@ -210,8 +226,14 @@ Read the actual launcher URLs, verify backend `/health/ready`, and confirm thefrontend responds. Defaults are backend `http://127.0.0.1:8001` and frontend`http://127.0.0.1:3782`; use the reported ports if different. Inspect launcherlogs on failure. Choose free ports through `config apply` instead of stopping-unrelated processes. For CLI-only, skip Web startup; a short-`deeptutor run chat` with `--format json` can verify turn execution if needed.+unrelated processes. For CLI-only, skip Web startup and verify turn execution:++```bash+deeptutor run chat "Reply with a short greeting." --format json+```++This also uses the configured model. Check for a successful response and turn+completion, not merely a zero exit code or the first streamed event.Finish with the checkout/environment, runtime home, provider/model withoutcredentials, passed checks, Web URL or CLI invocation, and any remaining user