{"owner":"HKUDS","repo":"DeepTutor","hasSkills":true,"totalSkillsCount":4,"totalTokensCount":2703,"categories":["root-instruction","mcp-config","marketplace","plugin-manifest"],"hasMcp":true,"mcpConfig":{"mcpServers":{"DeepTutor":{"command":"npx","args":["-y","@modelcontextprotocol/server-DeepTutor"]}}},"found":["AGENTS.md",".cursor/mcp.json",".claude-plugin/marketplace.json",".claude-plugin/plugin.json"],"skills":{"AGENTS.md":"# DeepTutor — Agent-Native Architecture\n\n## Overview\n\nDeepTutor is an **agent-native** intelligent learning companion organized\naround a two-layer plugin model — single-shot **Tools** invoked by the\nLLM, and multi-stage **Capabilities** that take over a turn — exposed\nthrough three entry points: CLI, WebSocket API, and Python SDK. All three\nenter the durable turn application service before the shared turn engine\nroutes a normalized context to the selected capability.\n\n## Architecture\n\n```\nEntry Points:  CLI (Typer)  |  WebSocket /ws  |  Python SDK\n                    ↓                   ↓                   ↓\n              ┌─────────────────────────────────────────────────┐\n              │          TurnApplicationService                 │\n              │   persists, coordinates, and replays turns      │\n              └──────────────────────┬──────────────────────────┘\n                                     ↓\n              ┌─────────────────────────────────────────────────┐\n              │       TurnEngine → ChatOrchestrator              │\n              │   routes UnifiedContext → selected Capability    │\n              │   (defaults to `chat`)                           │\n              └──────────┬──────────────┬───────────────────────┘\n                         │              │\n              ┌──────────▼──┐  ┌────────▼──────────┐\n              │ ToolRegistry │  │ CapabilityRegistry │\n              │  (Level 1)   │  │   (Level 2)        │\n              └──────────────┘  └────────────────────┘\n```\n\n`TurnApplicationService` owns durable turn state and replay through the\nsession store and runtime coordinator. Each execution uses a per-turn\n`StreamBus`; the orchestrator emits events, the turn runtime persists them,\nand adapters replay them to consumers. Runtime settings live in\n`data/user/settings/*.json` — project-root `.env` files are intentionally\nignored.\n\n### Level 1 — Tools\n\nSingle-function tools the LLM picks on demand. Seven user-toggleable tools\nsurface in `/settings/tools`:\n\n| Tool                 | Description                                   |\n| -------------------- | --------------------------------------------- |\n| `brainstorm`         | Breadth-first idea exploration with rationale |\n| `web_search`         | Web search with citations                     |\n| `paper_search`       | arXiv preprint search                         |\n| `reason`             | Dedicated deep-reasoning LLM call             |\n| `geogebra_analysis`  | Analyze math images into GeoGebra commands    |\n| `imagegen`           | Generate images                               |\n| `videogen`           | Generate videos                               |\n\n`USER_TOGGLEABLE_TOOL_NAMES` in `deeptutor/tools/builtin/__init__.py` is the\nauthoritative toggle list. Other built-ins are **context-gated** or\ncapability-owned: `CONFIGURABLE_BUILTIN_TOOL_NAMES` declares the context-gated\nsurface, while `deeptutor/agents/_shared/tool_composition.py` owns the mount\nrules (`ToolMountFlags`) and the always-available workspace tools. Examples\ninclude `rag`, memory and notebook tools, `read_skill`, deferred MCP/CLI tools,\n`exec`, `ask_user`, and mastery navigation. `--tool` selects from the\nuser-toggleable whitelist; it does not bypass context or capability gates.\n\n### Level 2 — Capabilities\n\nMulti-stage pipelines that own the turn:\n\n| Capability       | Stages                                                |\n| ---------------- | ----------------------------------------------------- |\n| `chat`           | exploring → responding (single agentic loop, default) |\n| `ask_questions`  | responding (chat loop forced through `ask_user`)      |\n| `deep_solve`     | responding (chat loop + solve planning tools)         |\n| `deep_question`  | ideation → generation                                 |\n| `deep_research`  | rephrasing → decomposing → researching → reporting    |\n| `visualize`      | analyzing → generating → reviewing (SVG / Chart.js / Mermaid / HTML; or routes to Manim sub-stages via `render_type`) |\n| `math_animator`  | concept_analysis → concept_design → code_generation → code_retry → summary → render_output |\n| `mastery_path`   | responding (Guided Learning — chat loop + mastery tools, gated per topic type) |\n| `immersive_reading` | responding (document- or timestamp-grounded media reading loop) |\n| `course_study`   | responding (course-state sensing and hand-off loop)   |\n\nAll capabilities converge on `emit_capability_result()` in\n`deeptutor/capabilities/_shared.py` so every turn emits the same envelope\n(response payload + `cost_summary` from `UsageTracker`). Status copy and\nprompts are i18n'd via `capabilities/prompts/{en,zh}/<name>.yaml`.\n\n## CLI Usage\n\n```bash\n# Install\npip install deeptutor      # Full app (CLI + Web/API + packaged Web assets)\npip install deeptutor-cli  # CLI-only\n\n# Run any capability\ndeeptutor run chat \"Explain Fourier transform\"\ndeeptutor run deep_solve \"Solve x^2=4\" -t rag --kb my-kb\ndeeptutor run visualize \"Animate sine wave\" --config render_mode=manim_video\n\n# Interactive REPL\ndeeptutor chat\n# (inside the REPL: /regenerate or /retry re-runs the last user message)\n\n# Partners (IM-connected companions)\ndeeptutor partner list\n\n# Knowledge bases, memory, server\ndeeptutor kb list\ndeeptutor kb create my-kb --doc textbook.pdf\ndeeptutor memory show\ndeeptutor serve --port 8001       # API server only\ndeeptutor start                   # backend + frontend together\n```\n\n## Key Files\n\n| Path                                       | Purpose                              |\n| ------------------------------------------ | ------------------------------------ |\n| `deeptutor/runtime/orchestrator.py`        | `ChatOrchestrator` — unified entry   |\n| `deeptutor/runtime/launcher.py`            | Backend + frontend lifecycle / port discovery |\n| `deeptutor/runtime/registry/`              | Tool + Capability registries         |\n| `deeptutor/runtime/bootstrap/builtin_capabilities.py` | Built-in capability class paths |\n| `deeptutor/services/config/runtime_settings.py` | JSON settings + process-env overrides |\n| `deeptutor/services/subagent/`             | Local/remote agent connectors; register each backend in `registry.py` and its model options in `models.py` (Grok CLI uses native `streaming-json`) |\n| `deeptutor/core/stream.py`, `deeptutor/runtime/stream_bus.py` | StreamEvent protocol + async fan-out |\n| `deeptutor/core/tool_protocol.py`          | `BaseTool` + `ToolDefinition`         |\n| `deeptutor/core/capability_protocol.py`    | `TurnCapability` + `CapabilityManifest` |\n| `deeptutor/core/context.py`                | `UnifiedContext` dataclass            |\n| `deeptutor/tools/builtin/__init__.py`      | All built-in tool wrappers           |\n| `deeptutor/capabilities/`                  | Built-in capability implementations  |\n| `deeptutor/app.py`                         | `DeepTutorApp` — Python SDK facade    |\n| `deeptutor_cli/main.py`                    | Typer CLI entry point                |\n| `deeptutor/api/routers/unified_ws.py`      | Unified WebSocket endpoint           |\n\n## Dependency Layers\n\nPublic install paths and source extras are defined in `pyproject.toml`.\nRequirements files mirror the same dependency groups for Docker/CI installs.\n\n```\npip install deeptutor      — Full app (CLI + Web/API + packaged Web assets)\npip install deeptutor-cli  — CLI-only (LLM + RAG + providers + document parsing)\npip install -e .           — Source install for development\n\nSource extras (.[ extra ], defined in pyproject.toml):\n.[cli]            — CLI-only dependency set\n.[server]         — Web/API server dependencies\n.[partners]       — Partner channel SDKs  (legacy alias: .[tutorbot])\n.[matrix]         — Matrix channel for Partners (matrix-nio; needs libolm)\n.[matrix-e2e]     — Matrix with end-to-end encryption (matrix-nio[e2e])\n.[math-animator]  — Manim addon (powers `visualize` Manim renders + `deeptutor run math_animator`)\n.[dev]            — Test / lint tooling\n.[all]            — Everything above\n```\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.claude-plugin/plugin.json)"},"files":{"AGENTS.md":"# DeepTutor — Agent-Native Architecture\n\n## Overview\n\nDeepTutor is an **agent-native** intelligent learning companion organized\naround a two-layer plugin model — single-shot **Tools** invoked by the\nLLM, and multi-stage **Capabilities** that take over a turn — exposed\nthrough three entry points: CLI, WebSocket API, and Python SDK. All three\nenter the durable turn application service before the shared turn engine\nroutes a normalized context to the selected capability.\n\n## Architecture\n\n```\nEntry Points:  CLI (Typer)  |  WebSocket /ws  |  Python SDK\n                    ↓                   ↓                   ↓\n              ┌─────────────────────────────────────────────────┐\n              │          TurnApplicationService                 │\n              │   persists, coordinates, and replays turns      │\n              └──────────────────────┬──────────────────────────┘\n                                     ↓\n              ┌─────────────────────────────────────────────────┐\n              │       TurnEngine → ChatOrchestrator              │\n              │   routes UnifiedContext → selected Capability    │\n              │   (defaults to `chat`)                           │\n              └──────────┬──────────────┬───────────────────────┘\n                         │              │\n              ┌──────────▼──┐  ┌────────▼──────────┐\n              │ ToolRegistry │  │ CapabilityRegistry │\n              │  (Level 1)   │  │   (Level 2)        │\n              └──────────────┘  └────────────────────┘\n```\n\n`TurnApplicationService` owns durable turn state and replay through the\nsession store and runtime coordinator. Each execution uses a per-turn\n`StreamBus`; the orchestrator emits events, the turn runtime persists them,\nand adapters replay them to consumers. Runtime settings live in\n`data/user/settings/*.json` — project-root `.env` files are intentionally\nignored.\n\n### Level 1 — Tools\n\nSingle-function tools the LLM picks on demand. Seven user-toggleable tools\nsurface in `/settings/tools`:\n\n| Tool                 | Description                                   |\n| -------------------- | --------------------------------------------- |\n| `brainstorm`         | Breadth-first idea exploration with rationale |\n| `web_search`         | Web search with citations                     |\n| `paper_search`       | arXiv preprint search                         |\n| `reason`             | Dedicated deep-reasoning LLM call             |\n| `geogebra_analysis`  | Analyze math images into GeoGebra commands    |\n| `imagegen`           | Generate images                               |\n| `videogen`           | Generate videos                               |\n\n`USER_TOGGLEABLE_TOOL_NAMES` in `deeptutor/tools/builtin/__init__.py` is the\nauthoritative toggle list. Other built-ins are **context-gated** or\ncapability-owned: `CONFIGURABLE_BUILTIN_TOOL_NAMES` declares the context-gated\nsurface, while `deeptutor/agents/_shared/tool_composition.py` owns the mount\nrules (`ToolMountFlags`) and the always-available workspace tools. Examples\ninclude `rag`, memory and notebook tools, `read_skill`, deferred MCP/CLI tools,\n`exec`, `ask_user`, and mastery navigation. `--tool` selects from the\nuser-toggleable whitelist; it does not bypass context or capability gates.\n\n### Level 2 — Capabilities\n\nMulti-stage pipelines that own the turn:\n\n| Capability       | Stages                                                |\n| ---------------- | ----------------------------------------------------- |\n| `chat`           | exploring → responding (single agentic loop, default) |\n| `ask_questions`  | responding (chat loop forced through `ask_user`)      |\n| `deep_solve`     | responding (chat loop + solve planning tools)         |\n| `deep_question`  | ideation → generation                                 |\n| `deep_research`  | rephrasing → decomposing → researching → reporting    |\n| `visualize`      | analyzing → generating → reviewing (SVG / Chart.js / Mermaid / HTML; or routes to Manim sub-stages via `render_type`) |\n| `math_animator`  | concept_analysis → concept_design → code_generation → code_retry → summary → render_output |\n| `mastery_path`   | responding (Guided Learning — chat loop + mastery tools, gated per topic type) |\n| `immersive_reading` | responding (document- or timestamp-grounded media reading loop) |\n| `course_study`   | responding (course-state sensing and hand-off loop)   |\n\nAll capabilities converge on `emit_capability_result()` in\n`deeptutor/capabilities/_shared.py` so every turn emits the same envelope\n(response payload + `cost_summary` from `UsageTracker`). Status copy and\nprompts are i18n'd via `capabilities/prompts/{en,zh}/<name>.yaml`.\n\n## CLI Usage\n\n```bash\n# Install\npip install deeptutor      # Full app (CLI + Web/API + packaged Web assets)\npip install deeptutor-cli  # CLI-only\n\n# Run any capability\ndeeptutor run chat \"Explain Fourier transform\"\ndeeptutor run deep_solve \"Solve x^2=4\" -t rag --kb my-kb\ndeeptutor run visualize \"Animate sine wave\" --config render_mode=manim_video\n\n# Interactive REPL\ndeeptutor chat\n# (inside the REPL: /regenerate or /retry re-runs the last user message)\n\n# Partners (IM-connected companions)\ndeeptutor partner list\n\n# Knowledge bases, memory, server\ndeeptutor kb list\ndeeptutor kb create my-kb --doc textbook.pdf\ndeeptutor memory show\ndeeptutor serve --port 8001       # API server only\ndeeptutor start                   # backend + frontend together\n```\n\n## Key Files\n\n| Path                                       | Purpose                              |\n| ------------------------------------------ | ------------------------------------ |\n| `deeptutor/runtime/orchestrator.py`        | `ChatOrchestrator` — unified entry   |\n| `deeptutor/runtime/launcher.py`            | Backend + frontend lifecycle / port discovery |\n| `deeptutor/runtime/registry/`              | Tool + Capability registries         |\n| `deeptutor/runtime/bootstrap/builtin_capabilities.py` | Built-in capability class paths |\n| `deeptutor/services/config/runtime_settings.py` | JSON settings + process-env overrides |\n| `deeptutor/services/subagent/`             | Local/remote agent connectors; register each backend in `registry.py` and its model options in `models.py` (Grok CLI uses native `streaming-json`) |\n| `deeptutor/core/stream.py`, `deeptutor/runtime/stream_bus.py` | StreamEvent protocol + async fan-out |\n| `deeptutor/core/tool_protocol.py`          | `BaseTool` + `ToolDefinition`         |\n| `deeptutor/core/capability_protocol.py`    | `TurnCapability` + `CapabilityManifest` |\n| `deeptutor/core/context.py`                | `UnifiedContext` dataclass            |\n| `deeptutor/tools/builtin/__init__.py`      | All built-in tool wrappers           |\n| `deeptutor/capabilities/`                  | Built-in capability implementations  |\n| `deeptutor/app.py`                         | `DeepTutorApp` — Python SDK facade    |\n| `deeptutor_cli/main.py`                    | Typer CLI entry point                |\n| `deeptutor/api/routers/unified_ws.py`      | Unified WebSocket endpoint           |\n\n## Dependency Layers\n\nPublic install paths and source extras are defined in `pyproject.toml`.\nRequirements files mirror the same dependency groups for Docker/CI installs.\n\n```\npip install deeptutor      — Full app (CLI + Web/API + packaged Web assets)\npip install deeptutor-cli  — CLI-only (LLM + RAG + providers + document parsing)\npip install -e .           — Source install for development\n\nSource extras (.[ extra ], defined in pyproject.toml):\n.[cli]            — CLI-only dependency set\n.[server]         — Web/API server dependencies\n.[partners]       — Partner channel SDKs  (legacy alias: .[tutorbot])\n.[matrix]         — Matrix channel for Partners (matrix-nio; needs libolm)\n.[matrix-e2e]     — Matrix with end-to-end encryption (matrix-nio[e2e])\n.[math-animator]  — Manim addon (powers `visualize` Manim renders + `deeptutor run math_animator`)\n.[dev]            — Test / lint tooling\n.[all]            — Everything above\n```\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.claude-plugin/plugin.json)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# DeepTutor — Agent-Native Architecture\n\n## Overview\n\nDeepTutor is an **agent-native** intelligent learning companion organized\naround a two-layer plugin model — single-shot **Tools** invoked by the\nLLM, and multi-stage **Capabilities** that take over a turn — exposed\nthrough three entry points: CLI, WebSocket API, and Python SDK. All three\nenter the durable turn application service before the shared turn engine\nroutes a normalized context to the selected capability.\n\n## Architecture\n\n```\nEntry Points:  CLI (Typer)  |  WebSocket /ws  |  Python SDK\n                    ↓                   ↓                   ↓\n              ┌─────────────────────────────────────────────────┐\n              │          TurnApplicationService                 │\n              │   persists, coordinates, and replays turns      │\n              └──────────────────────┬──────────────────────────┘\n                                     ↓\n              ┌─────────────────────────────────────────────────┐\n              │       TurnEngine → ChatOrchestrator              │\n              │   routes UnifiedContext → selected Capability    │\n              │   (defaults to `chat`)                           │\n              └──────────┬──────────────┬───────────────────────┘\n                         │              │\n              ┌──────────▼──┐  ┌────────▼──────────┐\n              │ ToolRegistry │  │ CapabilityRegistry │\n              │  (Level 1)   │  │   (Level 2)        │\n              └──────────────┘  └────────────────────┘\n```\n\n`TurnApplicationService` owns durable turn state and replay through the\nsession store and runtime coordinator. Each execution uses a per-turn\n`StreamBus`; the orchestrator emits events, the turn runtime persists them,\nand adapters replay them to consumers. Runtime settings live in\n`data/user/settings/*.json` — project-root `.env` files are intentionally\nignored.\n\n### Level 1 — Tools\n\nSingle-function tools the LLM picks on demand. Seven user-toggleable tools\nsurface in `/settings/tools`:\n\n| Tool                 | Description                                   |\n| -------------------- | --------------------------------------------- |\n| `brainstorm`         | Breadth-first idea exploration with rationale |\n| `web_search`         | Web search with citations                     |\n| `paper_search`       | arXiv preprint search                         |\n| `reason`             | Dedicated deep-reasoning LLM call             |\n| `geogebra_analysis`  | Analyze math images into GeoGebra commands    |\n| `imagegen`           | Generate images                               |\n| `videogen`           | Generate videos                               |\n\n`USER_TOGGLEABLE_TOOL_NAMES` in `deeptutor/tools/builtin/__init__.py` is the\nauthoritative toggle list. Other built-ins are **context-gated** or\ncapability-owned: `CONFIGURABLE_BUILTIN_TOOL_NAMES` declares the context-gated\nsurface, while `deeptutor/agents/_shared/tool_composition.py` owns the mount\nrules (`ToolMountFlags`) and the always-available workspace tools. Examples\ninclude `rag`, memory and notebook tools, `read_skill`, deferred MCP/CLI tools,\n`exec`, `ask_user`, and mastery navigation. `--tool` selects from the\nuser-toggleable whitelist; it does not bypass context or capability gates.\n\n### Level 2 — Capabilities\n\nMulti-stage pipelines that own the turn:\n\n| Capability       | Stages                                                |\n| ---------------- | ----------------------------------------------------- |\n| `chat`           | exploring → responding (single agentic loop, default) |\n| `ask_questions`  | responding (chat loop forced through `ask_user`)      |\n| `deep_solve`     | responding (chat loop + solve planning tools)         |\n| `deep_question`  | ideation → generation                                 |\n| `deep_research`  | rephrasing → decomposing → researching → reporting    |\n| `visualize`      | analyzing → generating → reviewing (SVG / Chart.js / Mermaid / HTML; or routes to Manim sub-stages via `render_type`) |\n| `math_animator`  | concept_analysis → concept_design → code_generation → code_retry → summary → render_output |\n| `mastery_path`   | responding (Guided Learning — chat loop + mastery tools, gated per topic type) |\n| `immersive_reading` | responding (document- or timestamp-grounded media reading loop) |\n| `course_study`   | responding (course-state sensing and hand-off loop)   |\n\nAll capabilities converge on `emit_capability_result()` in\n`deeptutor/capabilities/_shared.py` so every turn emits the same envelope\n(response payload + `cost_summary` from `UsageTracker`). Status copy and\nprompts are i18n'd via `capabilities/prompts/{en,zh}/<name>.yaml`.\n\n## CLI Usage\n\n```bash\n# Install\npip install deeptutor      # Full app (CLI + Web/API + packaged Web assets)\npip install deeptutor-cli  # CLI-only\n\n# Run any capability\ndeeptutor run chat \"Explain Fourier transform\"\ndeeptutor run deep_solve \"Solve x^2=4\" -t rag --kb my-kb\ndeeptutor run visualize \"Animate sine wave\" --config render_mode=manim_video\n\n# Interactive REPL\ndeeptutor chat\n# (inside the REPL: /regenerate or /retry re-runs the last user message)\n\n# Partners (IM-connected companions)\ndeeptutor partner list\n\n# Knowledge bases, memory, server\ndeeptutor kb list\ndeeptutor kb create my-kb --doc textbook.pdf\ndeeptutor memory show\ndeeptutor serve --port 8001       # API server only\ndeeptutor start                   # backend + frontend together\n```\n\n## Key Files\n\n| Path                                       | Purpose                              |\n| ------------------------------------------ | ------------------------------------ |\n| `deeptutor/runtime/orchestrator.py`        | `ChatOrchestrator` — unified entry   |\n| `deeptutor/runtime/launcher.py`            | Backend + frontend lifecycle / port discovery |\n| `deeptutor/runtime/registry/`              | Tool + Capability registries         |\n| `deeptutor/runtime/bootstrap/builtin_capabilities.py` | Built-in capability class paths |\n| `deeptutor/services/config/runtime_settings.py` | JSON settings + process-env overrides |\n| `deeptutor/services/subagent/`             | Local/remote agent connectors; register each backend in `registry.py` and its model options in `models.py` (Grok CLI uses native `streaming-json`) |\n| `deeptutor/core/stream.py`, `deeptutor/runtime/stream_bus.py` | StreamEvent protocol + async fan-out |\n| `deeptutor/core/tool_protocol.py`          | `BaseTool` + `ToolDefinition`         |\n| `deeptutor/core/capability_protocol.py`    | `TurnCapability` + `CapabilityManifest` |\n| `deeptutor/core/context.py`                | `UnifiedContext` dataclass            |\n| `deeptutor/tools/builtin/__init__.py`      | All built-in tool wrappers           |\n| `deeptutor/capabilities/`                  | Built-in capability implementations  |\n| `deeptutor/app.py`                         | `DeepTutorApp` — Python SDK facade    |\n| `deeptutor_cli/main.py`                    | Typer CLI entry point                |\n| `deeptutor/api/routers/unified_ws.py`      | Unified WebSocket endpoint           |\n\n## Dependency Layers\n\nPublic install paths and source extras are defined in `pyproject.toml`.\nRequirements files mirror the same dependency groups for Docker/CI installs.\n\n```\npip install deeptutor      — Full app (CLI + Web/API + packaged Web assets)\npip install deeptutor-cli  — CLI-only (LLM + RAG + providers + document parsing)\npip install -e .           — Source install for development\n\nSource extras (.[ extra ], defined in pyproject.toml):\n.[cli]            — CLI-only dependency set\n.[server]         — Web/API server dependencies\n.[partners]       — Partner channel SDKs  (legacy alias: .[tutorbot])\n.[matrix]         — Matrix channel for Partners (matrix-nio; needs libolm)\n.[matrix-e2e]     — Matrix with end-to-end encryption (matrix-nio[e2e])\n.[math-animator]  — Manim addon (powers `visualize` Manim renders + `deeptutor run math_animator`)\n.[dev]            — Test / lint tooling\n.[all]            — Everything above\n```\n","isInternal":false,"tokens":1803,"sizeBytes":8681},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":194},{"name":"plugin.json","path":".claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":180},{"name":"mcp.json","path":".cursor/mcp.json","rawUrl":"https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.cursor/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.cursor/mcp.json)","tokens":300,"sizeBytes":173}],"systemPromptSnippet":"<yakaai_skills repo=\"HKUDS/DeepTutor\">\n<!-- File: AGENTS.md (Tokens: ~1803 | Category: root-instruction) -->\n# DeepTutor — Agent-Native Architecture\n\n## Overview\n\nDeepTutor is an **agent-native** intelligent learning companion organized\naround a two-layer plugin model — single-shot **Tools** invoked by the\nLLM, and multi-stage **Capabilities** that take over a turn — exposed\nthrough three entry points: CLI, WebSocket API, and Python SDK. All three\nenter the durable turn application service before the shared turn engine\nroutes a normalized context to the selected capability.\n\n## Architecture\n\n```\nEntry Points:  CLI (Typer)  |  WebSocket /ws  |  Python SDK\n                    ↓                   ↓                   ↓\n              ┌─────────────────────────────────────────────────┐\n              │          TurnApplicationService                 │\n              │   persists, coordinates, and replays turns      │\n              └──────────────────────┬──────────────────────────┘\n                                     ↓\n              ┌─────────────────────────────────────────────────┐\n              │       TurnEngine → ChatOrchestrator              │\n              │   routes UnifiedContext → selected Capability    │\n              │   (defaults to `chat`)                           │\n              └──────────┬──────────────┬───────────────────────┘\n                         │              │\n              ┌──────────▼──┐  ┌────────▼──────────┐\n              │ ToolRegistry │  │ CapabilityRegistry │\n              │  (Level 1)   │  │   (Level 2)        │\n              └──────────────┘  └────────────────────┘\n```\n\n`TurnApplicationService` owns durable turn state and replay through the\nsession store and runtime coordinator. Each execution uses a per-turn\n`StreamBus`; the orchestrator emits events, the turn runtime persists them,\nand adapters replay them to consumers. Runtime settings live in\n`data/user/settings/*.json` — project-root `.env` files are intentionally\nignored.\n\n### Level 1 — Tools\n\nSingle-function tools the LLM picks on demand. Seven user-toggleable tools\nsurface in `/settings/tools`:\n\n| Tool                 | Description                                   |\n| -------------------- | --------------------------------------------- |\n| `brainstorm`         | Breadth-first idea exploration with rationale |\n| `web_search`         | Web search with citations                     |\n| `paper_search`       | arXiv preprint search                         |\n| `reason`             | Dedicated deep-reasoning LLM call             |\n| `geogebra_analysis`  | Analyze math images into GeoGebra commands    |\n| `imagegen`           | Generate images                               |\n| `videogen`           | Generate videos                               |\n\n`USER_TOGGLEABLE_TOOL_NAMES` in `deeptutor/tools/builtin/__init__.py` is the\nauthoritative toggle list. Other built-ins are **context-gated** or\ncapability-owned: `CONFIGURABLE_BUILTIN_TOOL_NAMES` declares the context-gated\nsurface, while `deeptutor/agents/_shared/tool_composition.py` owns the mount\nrules (`ToolMountFlags`) and the always-available workspace tools. Examples\ninclude `rag`, memory and notebook tools, `read_skill`, deferred MCP/CLI tools,\n`exec`, `ask_user`, and mastery navigation. `--tool` selects from the\nuser-toggleable whitelist; it does not bypass context or capability gates.\n\n### Level 2 — Capabilities\n\nMulti-stage pipelines that own the turn:\n\n| Capability       | Stages                                                |\n| ---------------- | ----------------------------------------------------- |\n| `chat`           | exploring → responding (single agentic loop, default) |\n| `ask_questions`  | responding (chat loop forced through `ask_user`)      |\n| `deep_solve`     | responding (chat loop + solve planning tools)         |\n| `deep_question`  | ideation → generation                                 |\n| `deep_research`  | rephrasing → decomposing → researching → reporting    |\n| `visualize`      | analyzing → generating → reviewing (SVG / Chart.js / Mermaid / HTML; or routes to Manim sub-stages via `render_type`) |\n| `math_animator`  | concept_analysis → concept_design → code_generation → code_retry → summary → render_output |\n| `mastery_path`   | responding (Guided Learning — chat loop + mastery tools, gated per topic type) |\n| `immersive_reading` | responding (document- or timestamp-grounded media reading loop) |\n| `course_study`   | responding (course-state sensing and hand-off loop)   |\n\nAll capabilities converge on `emit_capability_result()` in\n`deeptutor/capabilities/_shared.py` so every turn emits the same envelope\n(response payload + `cost_summary` from `UsageTracker`). Status copy and\nprompts are i18n'd via `capabilities/prompts/{en,zh}/<name>.yaml`.\n\n## CLI Usage\n\n```bash\n# Install\npip install deeptutor      # Full app (CLI + Web/API + packaged Web assets)\npip install deeptutor-cli  # CLI-only\n\n# Run any capability\ndeeptutor run chat \"Explain Fourier transform\"\ndeeptutor run deep_solve \"Solve x^2=4\" -t rag --kb my-kb\ndeeptutor run visualize \"Animate sine wave\" --config render_mode=manim_video\n\n# Interactive REPL\ndeeptutor chat\n# (inside the REPL: /regenerate or /retry re-runs the last user message)\n\n# Partners (IM-connected companions)\ndeeptutor partner list\n\n# Knowledge bases, memory, server\ndeeptutor kb list\ndeeptutor kb create my-kb --doc textbook.pdf\ndeeptutor memory show\ndeeptutor serve --port 8001       # API server only\ndeeptutor start                   # backend + frontend together\n```\n\n## Key Files\n\n| Path                                       | Purpose                              |\n| ------------------------------------------ | ------------------------------------ |\n| `deeptutor/runtime/orchestrator.py`        | `ChatOrchestrator` — unified entry   |\n| `deeptutor/runtime/launcher.py`            | Backend + frontend lifecycle / port discovery |\n| `deeptutor/runtime/registry/`              | Tool + Capability registries         |\n| `deeptutor/runtime/bootstrap/builtin_capabilities.py` | Built-in capability class paths |\n| `deeptutor/services/config/runtime_settings.py` | JSON settings + process-env overrides |\n| `deeptutor/services/subagent/`             | Local/remote agent connectors; register each backend in `registry.py` and its model options in `models.py` (Grok CLI uses native `streaming-json`) |\n| `deeptutor/core/stream.py`, `deeptutor/runtime/stream_bus.py` | StreamEvent protocol + async fan-out |\n| `deeptutor/core/tool_protocol.py`          | `BaseTool` + `ToolDefinition`         |\n| `deeptutor/core/capability_protocol.py`    | `TurnCapability` + `CapabilityManifest` |\n| `deeptutor/core/context.py`                | `UnifiedContext` dataclass            |\n| `deeptutor/tools/builtin/__init__.py`      | All built-in tool wrappers           |\n| `deeptutor/capabilities/`                  | Built-in capability implementations  |\n| `deeptutor/app.py`                         | `DeepTutorApp` — Python SDK facade    |\n| `deeptutor_cli/main.py`                    | Typer CLI entry point                |\n| `deeptutor/api/routers/unified_ws.py`      | Unified WebSocket endpoint           |\n\n## Dependency Layers\n\nPublic install paths and source extras are defined in `pyproject.toml`.\nRequirements files mirror the same dependency groups for Docker/CI installs.\n\n```\npip install deeptutor      — Full app (CLI + Web/API + packaged Web assets)\npip install deeptutor-cli  — CLI-only (LLM + RAG + providers + document parsing)\npip install -e .           — Source install for development\n\nSource extras (.[ extra ], defined in pyproject.toml):\n.[cli]            — CLI-only dependency set\n.[server]         — Web/API server dependencies\n.[partners]       — Partner channel SDKs  (legacy alias: .[tutorbot])\n.[matrix]         — Matrix channel for Partners (matrix-nio; needs libolm)\n.[matrix-e2e]     — Matrix with end-to-end encryption (matrix-nio[e2e])\n.[math-animator]  — Manim addon (powers `visualize` Manim renders + `deeptutor run math_animator`)\n.[dev]            — Test / lint tooling\n.[all]            — Everything above\n```\n\n<!-- File: .claude-plugin/marketplace.json (Tokens: ~300 | Category: marketplace) -->\n# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.claude-plugin/marketplace.json)\n\n<!-- File: .claude-plugin/plugin.json (Tokens: ~300 | Category: plugin-manifest) -->\n# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.claude-plugin/plugin.json)\n\n<!-- File: .cursor/mcp.json (Tokens: ~300 | Category: mcp-config) -->\n# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/HKUDS/DeepTutor/HEAD/.cursor/mcp.json)\n</yakaai_skills>"}