设置 DeepTutor 并排查你的智能体相关问题¶

Handbook · Development · Modules · Storage

本指南面向外部智能体，用于为用户安装、配置和验证 DeepTutor，或排查现有安装中的问题。如果面对的是已有问题，请从故障排查开始，而不是重复安装。阅读 SKILL.md 获取 CLI 概览。你需要终端和文件访问权限；此流程不需要 MCP 或特定于智能体的插件。

1. 明确目标¶

只询问缺失的信息，并在等待时继续独立准备：

安装文件夹以及任何已有的 DeepTutor 检出（checkout）。
完整 Web 应用还是仅 CLI；对于 README 设置提示，默认选择完整应用。
目标版本或分支。本指南描述当前 dev，包括 1.7.0 模块化布局；对于较旧的稳定版本，请使用对应的文档。
LLM 提供商、精确模型 ID 以及任何自定义/本地端点。
凭据来源：现有的环境变量、用户指定的私有本地文件，或提供商登录。不要在聊天中索要密钥。
现在是否需要知识库/RAG；这些还需要嵌入（embedding）。搜索是可选的。

复用合适的检出/环境，并保留本地编辑和设置。使用用户现有的 DEEPTUTOR_HOME，或显式选择一个运行时主目录。它拥有 data/；它不是 data/ 目录本身，也不是用于学习材料的 Content Workspace。

2. 克隆并安装¶

对于当前 dev 的新完整应用安装（macOS/Linux 示例）：

git clone --branch dev https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements/full.txt
python -m pip install -e . --no-deps
cd web
npm ci --legacy-peer-deps
cd ..

此流程使用 Python 3.11–3.14 和 Node.js 22 LTS。在创建环境前检查实际解释器；python3 可能版本较旧。在 Windows 上，使用受支持的 py -3.X 和 .venv\Scripts\Activate.ps1。如果 shell 状态在工具调用之间无法保持，请通过绝对路径调用环境的 Python 和 deeptutor，并将环境变量传递给每个进程。

若要从源码使用 CLI，请保留上述 Python 安装并跳过 Node/npm。源码树会暴露所有已检入的模块，因此仍需要它们的 Python 依赖。在 1.7.0 包布局中，deeptutor 提供最小 CLI；deeptutor-cli 是同一核心的兼容别名。根据需求添加功能模块；这不是已发布 1.6.15 包的布局。

1.7.0 包布局使用 python -m pip install "deeptutor[full]" 安装完整 Web 应用。裸 deeptutor 包含核心聊天、CLI 和 SDK；它不包含服务器或 Web 资源。对于开发构建，请使用上述源码流程或 Modules 中描述的本地 wheel。

从 1.6.15 升级时，停止 DeepTutor，备份现有运行时主目录，并继续使用相同的 DEEPTUTOR_HOME。要安装 1.7.0，请运行 python -m pip install --upgrade "deeptutor[full]==1.7.0"，然后在重启前运行 python -m pip check 和 deeptutor module list。如果安装了旧版 deeptutor-cli 包，请在安装新包之前卸载它：python -m pip uninstall deeptutor-cli。其旧 wheel 拥有共享的 Python 文件，一条命令的升级可能会移除新安装的核心。这不会移除运行时主目录数据。然后，你可以将 deeptutor-cli==1.7.0 添加到安装命令中，以获得仅包含元数据的新兼容别名。对于仅 CLI 迁移，请在移除旧 CLI 后安装 deeptutor-cli==1.7.0，并添加所需的功能模块。

在 1.7.0 中，升级裸 deeptutor 仅会选择核心；请使用 [full] 以保留完整应用的功能集。在此升级过程中，不要重置设置或更改运行时主目录。对于已有检出，请在更新前检查其分支、提交和本地编辑；不要为了匹配此示例而静默切换分支或替换环境。

3. 无提示初始化¶

在初始化、配置、诊断和启动过程中保持相同的运行时主目录。此示例使用检出根目录；如果用户已有主目录，请改用现有主目录：

export DEEPTUTOR_HOME="$PWD"
deeptutor init --non-interactive
deeptutor config providers

init --non-interactive 会创建缺失的默认值，而不会选择模型或联系提供商，并会保留已保存的设置。--cli 也可接受；两种模式都不会运行向导。仅初始化本身并不能确保模型就绪。

config providers 会以 JSON 格式打印受支持的 LLM、嵌入和搜索提供商，以及默认端点和 LLM API 格式。使用其提供商 ID。init、config apply 和 config show 也接受 --home PATH；对于其他命令，请一致地使用 DEEPTUTOR_HOME。

4. 应用配置¶

编写一个 UTF-8 JSON 文件（例如 setup.json），并将模型占位符替换为用户的选择：

{
  "llm": {
    "provider": "openai",
    "model": "YOUR_MODEL_ID",
    "api_key_env": "DEEPTUTOR_SETUP_LLM_KEY"
  },
  "system": {
    "backend_port": 8001,
    "frontend_port": 3782
  }
}

api_key_env 所指定的变量必须存在于 CLI 进程的环境中。请从用户授权的来源读取该变量，不要回显它。JSON 中包含的是变量名，而非字面密钥。解析后的密钥会保存在 DeepTutor 的私有设置中，供后续启动使用。项目根目录的 .env 文件不会自动加载。

deeptutor config apply setup.json --check
deeptutor config apply setup.json
deeptutor config show

--check 会验证输入、提供商、命名凭据、端点和端口冲突，而不会写入设置或联系提供商。两种模式都会输出 JSON；无效输入以退出码 2 结束。应用会为每个提供的服务选择一个专用的 Agent Setup 配置文件。重复应用会更新这些相同的配置文件；其他配置文件以及未涉及的服务/设置将被保留。每次请提供完整的配置文件，包括凭据引用。端口更改在重启后生效。

Section	Required fields	Optional fields
`llm`	`provider`, `model`	`base_url`, `api_key_env`, `api_version`, `api_format`
`embedding`	`provider`, `model`	`base_url`, `api_key_env`, `api_version`, positive integer `dimension`
`search`	`provider`	`base_url`, `api_key_env`
`system`	At least one port	`backend_port`, `frontend_port` (integers 1–65535, distinct)

远程基于密钥认证的 LLM/embedding 提供商需要 api_key_env；本地、OAuth 和 custom 端点可以省略它。搜索要求来自 config providers。没有默认端点的提供商需要 base_url。LLM API 格式包括 auto、openai_chat、openai_responses 和 anthropic，具体取决于提供商的支持列表。未知字段、字面量 api_key 字段以及 URL 中的凭据会被拒绝。高级设置和其他服务类型在 Web Settings 中仍然可用。

对于知识库/RAG，还需要配置一个可访问的 embedding 模型。例如：

{
  "embedding": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "api_key_env": "DEEPTUTOR_SETUP_EMBEDDING_KEY",
    "dimension": 1536
  },
  "search": { "provider": "duckduckgo" }
}

Embedding base_url 是完整端点，例如 https://api.openai.com/v1/embeddings；provider 目录会像 Web UI 一样对其进行规范化。更改现有 KB 的 embedding 模型/维度需要规划重建。不需要时可以省略 search，或选择 none 禁用它。DuckDuckGo 不需要密钥；可用性取决于用户的网络。

对于本地 Ollama，使用 {"llm":{"provider":"ollama","model":"YOUR_LOCAL_MODEL"}}，并验证 Ollama 正在运行且模型可用。

对于 OAuth，从 config providers 中采用提供商 ID/模型，然后在同一运行时主目录中使用其现有的登录命令。用户需要完成任何登录交互：

deeptutor provider login openai-codex
# Other supported flows: github-copilot, codebuddy

OpenAI Codex 使用 DeepTutor 自己的 OAuth 凭据；外部代理的登录不会自动复用。登录不会选择模型。

5. 验证并启动¶

python -m pip check
deeptutor module list
deeptutor doctor --format json
deeptutor doctor --online --format json

pip check 检查依赖一致性。检查 module list 中用户所需的模块：已安装、已启用和就绪是三种独立的状态。Web 应用需要 server 和 web；RAG 需要 knowledge 和 parsing；可选功能需要其所属的模块。仅核心（Core-only）模式会故意省略这些模块。源码检出使用 module enable/disable；wheel 安装还支持 module install/uninstall。更改前请停止 DeepTutor，并对未发布的模块使用 --wheelhouse /path/to/wheels。参见 Modules。

doctor 检查本地就绪状态；doctor --online 会发起一次小型的真实模型请求，可能会产生提供商使用费用。检查退出状态以及必需检查的失败项。修复可处理的失败项并重新运行受影响的检查。仅保存设置并不能证明就绪。LLM 探测不会验证可选的 embedding：当需要 RAG 时，还要在 Settings 中测试其连接，并摄取/搜索一份小的、经用户批准的文档。

对于完整应用：

deeptutor start --detach --no-browser

读取实际的启动器 URL，验证后端 /health/ready，并确认前端有响应。默认后端为 http://127.0.0.1:8001，前端为 http://127.0.0.1:3782；如果不同，请使用报告的端口。失败时检查启动器日志。通过 config apply 选择空闲端口，而不是停止不相关的进程。对于仅 CLI 模式，跳过 Web 启动并验证轮次执行：

deeptutor run chat "Reply with a short greeting." --format json

这也会使用已配置的模型。检查是否成功收到响应并完成轮次，而不仅仅是零退出码或第一个流式事件。

最后请说明代码检出/环境、运行时主目录、不含凭据的提供商/模型、已通过的检查、Web URL 或 CLI 调用方式，以及任何剩余的用户操作。对于分离式（detached）应用，请使用相同的运行时主目录执行 deeptutor stop。如果凭据或网络访问阻止了验证，请说明确切未完成的步骤，而不是宣布设置已完成。

6. 故障排除¶

使用以下方法排查用户的症状。根据证据选择检查项；无需为每个问题运行所有命令。

识别正在运行的实例并复现症状。 确定安装方法、已安装版本或源代码提交、当前 Python 环境、运行时主目录和实际服务 URL。对于 Docker，请区分容器路径/端口与宿主机路径/端口。询问失败的操作、预期结果、大致时间和相关的近期更改。确认您的 CLI 检查针对的是与用户相同的实例、账户和工作区；一个健康的第二安装对失败排查几乎没有帮助。
收集最小而有用的证据。 使用 config show 和 doctor 检查配置/就绪状态，使用 doctor --online 发起真实的 LLM 请求，或使用 doctor runtime 检查轮次协调、会话存储和迁移预检。两种 doctor 模式都可以添加 --format json。检查各项单独的检查：顶层 ok: true 可能与 RAG 等可选失败项共存。LLM 探测通过并不能证明 embedding、搜索、工具或浏览器连接正常工作。
沿着失败操作的边界进行追踪。 从可见症状开始，确定操作进行到了哪一步：浏览器 → API → 轮次/能力 → 提供商、工具或存储。对于 UI 问题，检查浏览器控制台和网络错误；存在 request_id、session_id 或 turn_id 时，按时间和这些 ID 关联服务器日志。对于分离式启动，检查 <runtime-home>/data/user/runtime/launcher.log；应用程序日志通常位于 data/user/logs/deeptutor.jsonl，具体取决于日志设置。容器部署可能还需要容器输出。读取一小段相关摘录，并在分享前移除其中的凭据和私有内容。
一次只验证一个假设。 将失败的操作缩减为一个小型重现，并比较成功路径与失败路径。例如，在设置和上下文等价的前提下，成功的 CLI 操作与失败的 Web 操作会将注意力引向浏览器/API 路径。使用 --help、plugin info 以及检出的代码继续调查。根目录下的 AGENTS.md 描述了整体架构；有用的起点包括 deeptutor_cli/、deeptutor/api/、deeptutor/runtime/、deeptutor/capabilities/、deeptutor/services/ 和 web/。在得出结论前，请确保源码与已安装版本匹配。
做出有针对性的修复并验证原始操作。 保留现有数据和配置；避免将全面重装、重置或重建 KB 作为探索性步骤。更改后重新运行用户失败的操作，而不仅仅是常规健康检查。将观察结果与假设分开报告。如果问题未解决，请提供简洁的交接说明：环境/版本、重现步骤、预期行为与实际行为、相关的已脱敏错误、已尝试的检查，以及下一步有用的调查方向。

实现与验证¶

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