企业官网建设流程全解析

DeepTutor CLI 完全指南：用命令行配置、管理与使用 DeepTutor 学习平台

【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor

本指南是 DeepTutor 官方 CLI Skill（SKILL.md）的中文深度解读与实践手册。DeepTutor 是一个面向"终身个性化学习"的智能学习平台，其命令行接口deeptutor覆盖了配置初始化、交互式对话、知识库（RAG）管理、深度学习能力执行、IM 伴侣（Partners）、技能市场（Skill Hub）以及记忆与会话管理。读完本文，你将能够像操作一个 Agent 一样，在纯终端环境下完成 DeepTutor 从首次安装、能力调用到日常维护的全部工作。

什么是 DeepTutor CLI

DeepTutor CLI 是 DeepTutor 面向命令行（以及 AI Agent）的统一入口，用一句话概括它的定位，就是 SKILL.md 开头所写的——"Teach your AI agent to configure, manage, and use DeepTutor entirely through the command line"。

从源码结构看，CLI 是基于 Typer 构建的多级命令树。入口实现在 deeptutor_cli/main.py：

• 主应用名为deeptutor，创建了partner、chat、kb、skill、memory、plugin、config、session、notebook、provider、book等 11 个子命令组，并注册了顶层命令run、start、serve和init；
• skill同时注册了skills别名（见 deeptutor_cli/main.py），所以deeptutor skill …与deeptutor skills …等价；
• 支持deeptutor可执行文件、python -m deeptutor（见 deeptutor/main.py）与python -m deeptutor_cli（见 deeptutor_cli/main.py）三种运行方式。

命令入口会先切换到 CLI 运行模式并完成日志配置（set_mode(RunMode.CLI)+configure_logging()），然后才开始分发命令。这意味着 CLI 与 Web 端共享同一套应用内核（DeepTutorApp），命令行只是它的另一个"前台"。

安装与首次初始化

前置条件

• Python 3.11+；
• 安装方式二选一：
  • 完整 Web 应用：pip install deeptutor；
  • 仅命令行：pip install deeptutor-cli（对应仓库中的 packaging/deeptutor-cli/pyproject.toml 与 requirements/cli.txt）；
  • 源码开发安装：在仓库根目录执行pip install -e .。

运行deeptutor init

首次使用必须先执行一次deeptutor init做交互式初始化。它会以"向导"形式引导你完成设置，并写入与 Web 端"设置"页面完全相同的文件（位于工作区data/user/settings下）。

根据 deeptutor_cli/init_cmd.py 的实现，完整模式共 5 步，加--cli跳过端口步骤后为 4 步：

1. 端口（Ports）：配置后端端口（默认8001）与前端端口（默认3782）；
2. LLM：选择提供方（binding）、填写 Base URL、输入 API Key、拉取/models选择模型，并提供连通性探测（失败可重试并更换 Key）；
3. Embedding：配置嵌入端点与模型，默认提示复用 LLM 的 API Key，可选填入向量维度 dimension，同样带探测；可跳过；
4. Search：配置联网搜索服务（提供方可能要求 API Key / Base URL，也支持显式设为none以彻底禁用搜索）；可跳过；
5. Review（汇总确认）：以面板形式回显本次所有选择，确认后写入设置文件。

deeptutor init的关键参数：

源码细节：init接受--home后会把DEEPTUTOR_HOME环境变量指向新工作区，并清除 PathService 等单例缓存，避免旧路径残留导致配置写错位置（见 deeptutor_cli/init_cmd.py）。也就是说，同一台机器可以通过不同的--home维护多套互不干扰的运行环境。

命令全景与整体布局

deeptutor主命令树如下（来自 deeptutor_cli/main.py）：

deeptutor ├── init # 交互式初始化工作区设置 ├── chat # 交互式对话 REPL（-c 指定初始能力） ├── run # 单轮执行任意能力（Agent 首选入口） ├── start # 同时启动后端 + 前端 ├── serve # 仅启动 API 服务 ├── config # 查看解析后的配置（show） ├── plugin # 查看已注册工具与能力（list / info） ├── kb # 知识库管理（list/info/create/add/search/set-default/delete） ├── skill(s) # 技能管理（search/install/list/remove/login/logout/publish/update） ├── partner # IM 伴侣管理（list/create/start/stop） ├── memory # 记忆查看与管理（show/clear） ├── session # 会话管理（list/show/open/rename/delete） ├── notebook # 笔记本管理（list/create/show/add-md/replace-md/remove-record） ├── book # 交互式图书维护（list/health/refresh-fingerprints） └── provider # 提供商 OAuth 登录（login）

下面按功能域逐个深入。

对话与能力执行（chat / run）

交互式 REPL：deeptutor chat

deeptutor chat提供带 Rich 渲染的交互式对话环境，支持多行输入（行尾\续行）、Ctrl-C 中断当前回合而 REPL 不退出等体验。

# 直接进入对话 deeptutor chat # 指定初始能力、预挂载知识库与工具 deeptutor chat --capability deep_solve --kb my-kb --tool rag --tool web_search

chat接受的启动参数（与run一致）：--session、--tool/-t、--kb、--notebook-ref、--history-ref、--language/-l、--config、--config-json，外加--capability/-c <name>指定初始能力。从 deeptutor_cli/chat.py 的实现看，若用--session恢复既有会话，CLI 会先读取会话的 preferences（能力、工具、知识库、语言等）并用它们覆盖启动参数，做到"上次怎么聊、这次还怎么聊"。

单轮执行：deeptutor run

deeptutor run是面向 Agent / 脚本的单轮一次执行入口，参数与chat完全对齐，是"agent-first"的推荐姿势：

# 常规问答 deeptutor run chat "Explain Fourier transform" # 深度解题（挂知识库 + RAG 工具） deeptutor run deep_solve "Solve x^2 = 4" --tool rag --kb textbook # 批量出题（覆盖能力配置） deeptutor run deep_question "Linear algebra" --config num_questions=5 # 深度研究（报告模式、standard 深度） 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"

run第一参数为能力名，第二参数为消息正文。底层调用链为：构造TurnRequest→DeepTutorApp().start_turn()→ 流式消费回合事件（见 deeptutor_cli/common.py 的run_turn_and_render/stream_turn_as_json），即run只是把 Web 端同一个回合引擎搬到了终端。

run支持的参数

其中--config解析逻辑见 deeptutor_cli/common.py 的parse_config_items——要求必须是KEY=VALUE形式，值会做智能标量转换（true/false/null与 JSON 值自动识别），便于脚本传参；--format json时每个流式事件输出为一行 JSON，ask_user型提问在非交互 stdin 下会自动以空回复放行，避免无人值守脚本被卡死（见 deeptutor_cli/common.py）。

能力与工具清单

run/chat -c接受的能力名：chat、deep_solve、deep_question、deep_research、visualize、math_animator、mastery_path（分别对应深度解题、批量出题、深度研究、数据可视化、数学动画、掌握路径规划）。

--tool/-t可用的工具分两类：

• 用户可开关工具（user-toggleable）：brainstorm、web_search、paper_search、reason、geogebra_analysis、imagegen、videogen；
• 上下文门控工具（context-gated）：rag、code_execution、read_source、web_fetch、github、ask_user等——它们满足上下文条件时自动挂载，也可用--tool强制启用。

deeptutor plugin list可查看完整注册集合；plugin info <name>查看某个工具/能力的具体 schema 与可用性。

REPL 斜杠命令

在deeptutor chat内输入/开头的斜杠命令管理会话状态。下表完整列出：

这些命令的语义与 deeptutor_cli/chat.py 中的_apply_command一一对应。实现细节值得一提：

• 工具结果环形缓冲：每个工具调用的完整输出会被暂存（deeptutor_cli/common.py 中的模块级tool_results缓冲），终端只打印截断预览，/show last或/show <n>可展开完整内容与思考过程；
• 回合渲染状态机：TurnStreamRenderer把 agent loop 每一轮"narration（铺垫）+ 工具调用 + finish（最终答复）"分类渲染，工具调用显示为● tool(args)单行摘要（见 deeptutor_cli/common.py）；
• 回合结束时会在底部打印session/turn/rounds/tools/tokens/cost汇总信息。

知识库管理（kb）

kb命令组对接 DeepTutor 的 LlamaIndex 知识库子系统，知识库存放于工作区data/knowledge_bases目录（见 deeptutor_cli/kb.py 的_get_kb_manager）。

deeptutor kb list [--format rich|json] # 列出所有知识库 deeptutor kb info <name> # 查看知识库详情（JSON，含统计与 RAG provider） deeptutor kb create <name> --doc file.pdf # 用文档创建（--doc/-d 可重复） deeptutor kb create <name> --docs-dir ./papers # 或用整个目录创建（递归收集支持的文件类型） deeptutor kb add <name> --doc more.pdf # 向已有知识库增量添加文档（自动去重） deeptutor kb search <name> "query text" [--mode hybrid] [--format rich|json] deeptutor kb set-default <name> # 设为默认知识库 deeptutor kb delete <name> [--force] # 删除知识库（默认二次确认）

实现要点：

• 名称校验：create前会用validate_knowledge_base_name校验名称合法性，且不允许重名创建（deeptutor_cli/kb.py）；
• 文档收集去重：--doc与--docs-dir可混用，目录递归采集依赖FileTypeRouter.collect_supported_files，最终按路径去重；
• 搜索模式：search的--mode默认hybrid（混合检索），底层走 deeptutor/tools/rag_tool.py 的rag_search，返回 provider、answer 等内容；
• 删除保护：delete默认弹确认（typer.confirm），--force跳过。

Skills 与插件生态（skill / skills）

skill（别名skills）命令组管理本地技能，并支持从外部技能市场（hub，如 ClawHub）搜索与安装。

Hub 引用格式为<hub>:<slug>[@version]，hub 前缀缺省为clawhub。

# 在市场搜索（自然语言查询，可指定 hub 与结果上限 1–50） deeptutor skill search "flashcards" [--hub clawhub] [--limit 10] # 安装技能包（可指定本地名称、强制覆盖） deeptutor skill install clawhub:some-skill[@1.2.0] [--name local-name] [--force] [--allow-unverified] # 查看本地技能（含来源 provenance） deeptutor skill list # 删除用户层技能（内置技能只读、不可删） deeptutor skill remove <name>

从 deeptutor_cli/skill.py 的实现看，安装走的是完整的安全导入流水线：hub 安全判定（verdict）→ 安全解包 → frontmatter 适配 → 来源记录（.hub-lock.json）。当 hub 将包标记为可疑时，CLI 会打印suspicious判定并提示先审查SKILL.md再使用；--allow-unverified用于显式放行。

skill组还提供面向发布者的命令：deeptutor skill login（GitHub/Google 浏览器授权，令牌存本地）、logout、publish（本地目录预检 → 交互打标 track/领域/学段 → 汇总确认 → 上传）、update（发布新版本或把latest回退到旧版本）。令牌解析优先级为--token→ 环境变量（DEEPTUTOR_HUB_TOKEN/EDUHUB_TOKEN）→skill login本地存储。

Partners（IM 伴侣）

Partners 是通过 IM 渠道接入的学习伴侣（前身是 "TutorBot"）。三个核心命令：

deeptutor partner list # 列出所有伴侣 deeptutor partner create <id> -n "My Tutor" # 创建并启动新伴侣 # -n/--name <text> 显示名 # -s/--soul <md> Soul markdown（人格设定） # -m/--model <id> 覆盖模型 deeptutor partner start <id> # 启动伴侣 deeptutor partner stop <id> # 停止正在运行的伴侣

记忆、会话与笔记本

记忆（memory）

DeepTutor 的记忆系统是分层的。memory show支持三种目标：

deeptutor memory show [<target>] # target: L3（全部全局记忆文档，默认）| L2（全部"界面面"文档） # | 单个文档名（如 profile、chat）

memory clear的目标则对应 L1 痕迹层：

deeptutor memory clear [<target>] # target: all（默认，全量重置）| trace（清除全部 L1） # | 某个 surface 名（清除该界面的 L1 trace） # --force/-f 跳过确认

从 deeptutor_cli/memory.py 可以看到存储映射：L3 是全局长期文档（多个 slot），L2 是按"界面面"（surfaces）组织的文档，L1 是各 surface 下的*.jsonl痕迹记录。例如memory clear chat会删除 chat 面的全部 L1 痕迹文件。删除前默认二次确认。

会话（session）

会话是跨命令行与 Web 共享的：

deeptutor session list [--limit 20] # 列出会话（表格：ID/标题/能力/状态/消息数） deeptutor session show <id> [--format rich|json] # 查看会话消息 deeptutor session open <id> # 在 REPL 中恢复该会话 deeptutor session rename <id> --title "..." # 重命名 deeptutor session delete <id> # 删除

笔记本（notebook）

笔记本把不同类型的学习记录（问答、研究、解题等）聚合成可检索的文档集合：

deeptutor notebook list # 列出笔记本 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>

笔记本既可以手动导入 Markdown 文件，也可以作为回合上下文被引用（--notebook-ref//notebook add），引用语法"<notebook_id>:<rec1>,<rec2>"即"这个笔记本的这几条记录作为本轮上下文"。

交互式图书维护（book）

图书（Books）的创作与阅读主要在 Web 端，CLI 只负责 BookEngine 的维护任务：

deeptutor book list # 列出所有图书（会标记过期页面 stale） deeptutor book health <book_id> # 检查 KB 漂移（drift）与 log.md 健康状况 deeptutor book refresh-fingerprints <book_id> # 重新快照 KB 指纹

提供商登录（provider）

用于模型提供商的 OAuth 认证：

deeptutor provider login openai-codex # OpenAI Codex 的 OAuth 登录 deeptutor provider login github-copilot # 校验已存在的 Copilot 认证会话

系统级命令（config / plugin / serve / start）

deeptutor config show # 打印解析后的完整配置 deeptutor plugin list # 列出已注册工具与能力 deeptutor plugin info <name> # 查看某工具/能力的 schema 与可用性 deeptutor serve [--host 0.0.0.0] [--port 8001] [--reload] # 启动 API 服务 deeptutor start [--home <path>] # 同时启动后端 + 前端 deeptutor init [--cli] [--home <path>] # 创建/更新工作区设置

serve的底层细节（见 deeptutor_cli/main.py）值得一提：它直接用 uvicorn 拉起deeptutor.api.main:app；端口不传时从设置解析后端端口（默认 8001）；--reload会排除web/*与data/*目录；WebSocket 最大消息尺寸会随配置的附件总量自动上调；在 Windows 上会自动切换到 ProactorEventLoop，以保证 Math Animator 渲染器等子进程 API 正常工作。若缺少服务端依赖，会提示pip install -U deeptutor。

start用于本地跑整套 Web 应用，源码安装默认以生产模式启动后端 + 前端，--dev可改用 Next.js 开发服务器；Ctrl+C停止。

典型工作流

首次安装配置

cd DeepTutor pip install -e . deeptutor init # 交互式引导（纯 CLI 使用加 --cli）

日常学习

deeptutor chat --kb textbook --tool rag --tool web_search

从文档建立知识库并问答

deeptutor kb create physics --doc ch1.pdf --doc ch2.pdf deeptutor run chat "Explain Newton's third law" --kb physics --tool rag

基于知识库批量出题

deeptutor run deep_question "Thermodynamics" --kb physics --config num_questions=5

本地启动完整 Web 应用

deeptutor start # 后端 + 前端一起启动；Ctrl+C 停止

小结

DeepTutor CLI 的核心价值在于把平台的全部能力收敛到一套幂等的、可脚本化的命令体系中：deeptutor init完成了从零到可用的环境引导；run/chat贯通了从纯对话到深度解题、出题、研究、可视化、数学动画、掌握路径的全谱系能力，且支持精细的知识库、工具、笔记本与历史引用组装；kb/skill/partner/book/memory/session/notebook则分别对应内容库、技能生态、IM 伴侣、图书、记忆、会话与笔记的完整生命周期管理。无论是人工终端操作，还是把deeptutor run --format json接入自动化脚本与上层 Agent，它都提供了统一、可靠、带安全护栏的入口。想继续深挖实现，可依次阅读 deeptutor_cli/main.py、deeptutor_cli/chat.py 与 deeptutor_cli/common.py，它们构成了整个 CLI 的中枢。

【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor