DeepTutor CLI 技能¶
指导你的 AI 智能体完全通过命令行来配置、管理和使用 DeepTutor——一个智能学习平台。
使用时机¶
当用户想要以下操作时，可使用本技能：
- 设置或配置 DeepTutor
- 诊断现有 DeepTutor 安装中的问题
- 与 DeepTutor 聊天或运行某项能力（深度求解、测验生成、深度研究、可视化、数学动画、精通路径）
- 创建、管理或搜索知识库
- 创建、管理或运行 Partners（接入 IM 的伴学伙伴）
- 从中心（EduHub 或 ClawHub）搜索、安装或管理技能
- 检查或维护交互式 Books
- 查看或管理学习记忆、会话或笔记本
- 启动 DeepTutor API 服务器或完整的 Web 应用
前提条件¶
- Python 3.11–3.14
- 对于 1.7.0 模块化版本，
pip install "deeptutor[full]"会安装打包好的 Web 应用；仅安装deeptutor（或deeptutor-cli兼容别名）则只安装核心 CLI/SDK。开发场景下，请使用源码或本地 wheel。源码安装需要先运行pip install -r requirements/full.txt，再运行pip install -e . --no-deps；如需 Web UI，还需在web/目录中添加 Node.js 22 LTS 并执行npm ci --legacy-peer-deps。有关在不更改运行时主目录的情况下从 1.6.15 升级，请参阅设置指南。 - 首次交互式设置请运行
deeptutor init。它会引导你完成向导流程（端口 → LLM → 嵌入 → 搜索 → 检查），并将与 Web 设置页面相同的设置写入data/user/settings。添加--cli可跳过端口步骤以仅使用 CLI，或使用--home <path>指定目标工作区。
智能体设置¶
首先从开发者与智能体手册开始，查找相关的设置、架构、开发、测试或功能指南。当用户要求你安装、配置或排查 DeepTutor 时，请遵循 docs-for-dev/AGENT_SETUP.md。该文档涵盖克隆、环境准备、凭据来源、可选 RAG/搜索、启动和验证，并提供了适用于现有安装的故障排查方法。在更改设置前先阅读该文档；复用现有检出（checkout）并保留用户的文件。在所有命令中保持 DEEPTUTOR_HOME 一致。
deeptutor init --non-interactive # Create missing defaults; no model selected
deeptutor config providers # Discover supported providers as JSON
deeptutor config apply setup.json --check # Validate without settings writes/network
deeptutor config apply setup.json # Apply complete setup profiles from JSON
deeptutor config show # Inspect configuration with credentials redacted
deeptutor doctor --format json # Check local readiness
deeptutor doctor --online --format json # Small live LLM request (provider usage)
使用指南中的设置 JSON schema，通过 api_key_env 引用 CLI 进程环境中的凭据。切勿打印密钥，也不要在设置 JSON 中放入字面量密钥。当缺少凭据或模型选择时，请询问用户来源/选择；同时继续独立的准备工作。处理旧版本时，请使用已安装 CLI 的 --help 来确认命令。保存设置并不能证明系统已就绪：请报告实际验证结果以及任何未完成的步骤。
命令¶
下面的示例涵盖完整安装和可选附加组件。核心提供 chat 和 ask_questions；其他能力与资源命令需要其对应的模块。通过 deeptutor module list 检查已安装/已启用/就绪状态，通过 deeptutor plugin list 查看已注册的能力和工具。更改模块前先停止 DeepTutor。源码检出使用 module enable/disable 和 python scripts/install_extras.py <extra> 管理可选依赖；wheel 安装也支持 module install/uninstall。对于本地构建，请向 module install 传递 --wheelhouse /path/to/wheels（参见 Modules）。
聊天与能力¶
# Interactive REPL
deeptutor chat
deeptutor chat --capability deep_solve --kb my-kb --tool web_search
# One-shot capability execution
deeptutor run chat "Explain Fourier transform"
deeptutor run deep_solve "Solve x^2 = 4" --kb textbook
deeptutor run deep_question "Linear algebra" --config num_questions=5
deeptutor run deep_research "Attention mechanisms" --kb papers --config mode=report --config depth=standard
deeptutor run visualize "Plot the unit circle"
deeptutor run math_animator "Visualize a Fourier series"
# Capabilities accepted by `run` / `chat -c`:
# Discover current capabilities and tool availability with `deeptutor plugin list`.
# Options for `run`:
# --session <id> Resume existing session
# --tool/-t <name> Enable tool (repeatable)
# --kb <name> Knowledge base (repeatable)
# --notebook-ref <ref> Notebook reference, "<notebook_id>:<rec1>,<rec2>" (repeatable)
# --history-ref <id> Referenced session id (repeatable)
# --language/-l <code> Response language (default: en)
# --config <key=value> Capability config (repeatable)
# --config-json <json> Capability config as JSON
# --format/-f <fmt> Output format: rich | json (default: rich)
deeptutor chat 接受相同的 --session / --tool / --kb / --notebook-ref / --history-ref / --language / --config / --config-json 选项，并额外支持 --capability/-c <name> 来设置初始能力。
--tool / -t 的可用工具：用户可切换的工具为 brainstorm、web_search、paper_search、zotero_search、reason、geogebra_analysis、imagegen 和 videogen。上下文门控的工具（rag、exec、memory、notebook 等）会根据上下文/能力规则挂载；--tool 不会绕过这些规则。使用 --kb 挂载知识库以启用 RAG；Knowledge Frontier 还需要研究模块。运行 deeptutor plugin list 可查看已注册的集合。
知识库¶
deeptutor kb list [--format rich|json] # List all knowledge bases
deeptutor kb info <name> # Show knowledge base details (JSON)
deeptutor kb create <name> --doc file.pdf # Create from documents (--doc/-d repeatable)
deeptutor kb create <name> --docs-dir ./papers # ...or from a directory of documents
deeptutor kb add <name> --doc more.pdf # Add documents incrementally
deeptutor kb search <name> "query text" [--mode hybrid] [--format rich|json]
deeptutor kb eval <name> --dataset qa.jsonl [--top-k 5] [--mode hybrid] [--save report.json]
# Scores retrieval quality against a QA set (JSONL: {"query": ..., "gold": [...]});
# reports Recall@k / Precision@k / nDCG@k / MRR / MAP / Hit@k per case and averaged.
deeptutor kb set-default <name> # Set as default KB
deeptutor kb delete <name> [--force] # Delete a knowledge base
合作伙伴¶
合作伙伴是通过 IM 连接的学习伙伴（原 "TutorBot"）。
deeptutor partner list # List all partners
deeptutor partner create <id> -n "My Tutor" # Create and start a new partner
# -n/--name <text> Display name
# -s/--soul <md> Soul markdown (the persona)
# -m/--model <id> Model override
deeptutor partner start <id> # Start a partner
deeptutor partner stop <id> # Stop a running partner
技能¶
安装和管理技能，包括来自 EduHub 和 ClawHub 的包。
Hub 引用使用 <hub>:<slug>[@version] 格式（hub 前缀默认为 eduhub）。
deeptutor skill search "flashcards" [--hub clawhub] [--limit 10]
deeptutor skill install clawhub:some-skill[@1.2.0] [--name local-name] [--force] [--allow-unverified]
deeptutor skill list # List local skills (with hub provenance)
deeptutor skill remove <name> # Remove a user-layer skill
书籍¶
BookEngine 的维护命令（编写/阅读通过 Web 应用进行）。
deeptutor book list # List all books (flags stale pages)
deeptutor book health <book_id> # Inspect KB drift + log.md health
deeptutor book refresh-fingerprints <book_id> # Re-snapshot KB fingerprints
记忆¶
deeptutor memory show [<target>] # target: L3 (all global docs, default) | L2 (all surfaces) | a doc name (e.g. profile, chat)
deeptutor memory clear [<target>] # target: all (default) | trace (all L1) | a surface name (clears that surface's L1)
# --force/-f Skip confirmation
会话¶
deeptutor session list [--limit 20] # List sessions
deeptutor session show <id> [--format rich|json] # View session messages
deeptutor session open <id> # Resume session in the REPL
deeptutor session rename <id> --title "..." # Rename a session
deeptutor session delete <id> # Delete a session
笔记本¶
deeptutor notebook list # List notebooks
deeptutor notebook create <name> [--description "..."]
deeptutor notebook show <notebook_id> [--format rich|json]
deeptutor notebook add-md <notebook_id> <file.md> [--title "..."] [--type chat|question|research|solve]
deeptutor notebook replace-md <notebook_id> <record_id> <file.md>
deeptutor notebook remove-record <notebook_id> <record_id>
提供商¶
deeptutor provider login openai-codex # OAuth login for OpenAI Codex
deeptutor provider login github-copilot # Sign in through GitHub device flow
deeptutor provider login codebuddy # Validate CodeBuddy SDK login / open login
系统¶
deeptutor config show [--home <path>] # Print resolved configuration (redacted)
deeptutor config providers # Supported setup providers as JSON
deeptutor config apply <file.json> [--check] [--home <path>] # Apply/validate setup JSON
deeptutor plugin list # List registered tools and capabilities
deeptutor plugin info <name> # Show a tool/capability's schema + availability
deeptutor module list # Inspect installed / enabled / ready states
deeptutor serve [--host 0.0.0.0] [--port 8001] [--reload] # Start the API server
deeptutor start [--home <path>] [--detach] [--no-browser] # Launch backend + frontend
deeptutor stop [--home <path>] # Stop a detached launcher
deeptutor init [--cli] [--home <path>] [--non-interactive] # Wizard or missing defaults
deeptutor doctor [--online] [--format json] # Local readiness / optional live LLM probe
REPL 斜杠命令¶
在 deeptutor chat 中，使用以下命令：
| 命令 | 效果 |
|---|---|
/quit |
退出 REPL |
/session |
显示当前会话 ID |
/status |
打印当前 REPL 状态 |
/new 或 /clear |
开始新的会话上下文 |
/regenerate 或 /retry |
重新运行最后一条用户消息 |
/tool on\|off <name> |
切换工具 |
/cap <name> |
切换能力 |
/kb <name>\|none |
设置或清除知识库 |
/history add <id> / /history clear |
管理历史引用 |
/notebook add <ref> / /notebook clear |
管理笔记本引用 |
/show last\|<n> |
展开捕获的工具结果或思考块 |
/refs |
显示所有活动引用 |
/config show\|set\|clear |
管理能力配置 |
典型工作流¶
首次源码安装（在按照安装指南准备环境之后）：
cd DeepTutor
python -m pip install -r requirements/full.txt
python -m pip install -e . --no-deps
python -m pip check
deeptutor module list
deeptutor init # Interactive guided setup (add --cli for CLI-only)
对于 Web UI，请先安装 Node.js 22 LTS，并在 web/ 目录中运行 npm ci --legacy-peer-deps，然后再启动。仅使用 CLI 的用户可以跳过前端安装。请遵循安装指南中的就绪检查；仅初始化并不能验证模型。
日常学习：
从文档构建知识库：
deeptutor kb create physics --doc ch1.pdf --doc ch2.pdf
deeptutor run chat "Explain Newton's third law" --kb physics
生成测验题：
在本地运行完整 Web 应用：
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 dee/DeepTutor