模块与安装¶

手册 · 相关指南

DeepTutor 拥有一个源代码仓库和相互独立的 Python 发行包。deeptutor 负责共享的回合运行时、CLI 和 Python SDK。功能发行包会将代码添加到相同的包命名空间中，但不会覆盖核心文件。deeptutor-cli 是一个兼容性元包：它依赖于核心包，且自身不包含任何 Python 文件或控制台脚本。deeptutor[full] 是一种安装配置（profile），而不是一个会阻止您卸载单个应用程序的永久元包。

模块化发行包家族始于 1.7.0，且必须在每次发布时一同发布。1.6.15 及更早版本的软件包使用旧版布局，不具备这些边界。本地 wheel 构建同样受支持。

源码检出¶

python -m pip install -r requirements/full.txt
python -m pip install -e . --no-deps
(cd web && npm ci --legacy-peer-deps)
deeptutor module list
deeptutor module disable solve
deeptutor module enable solve

在检出环境中，所有源码模块都已存在。enable 和 disable 使用与 wheel 安装相同的组装规则。install 和 uninstall 特意要求使用 wheel 环境，因此它们绝不会删除受跟踪的源码文件。源码依赖项由 python scripts/sync_module_requirements.py 生成。在 CI 中使用 --check 检测漂移。requirements/core.txt 和 server.txt 是最小集合；full.txt 提供常规完整的源码/Docker 运行时。源码归档和 Docker 镜像通过项目文件和模块构建脚本识别，无需 .git。可选源码依赖项可通过 python scripts/install_extras.py <extra> 添加；该命令会解析模块依赖项，而不会在源码树之上安装重复的功能 wheel。

独立 wheel 安装¶

python scripts/build_modules.py --output dist/modules
python -m venv /tmp/deeptutor-modules
/tmp/deeptutor-modules/bin/python -m pip install --find-links dist/modules deeptutor
/tmp/deeptutor-modules/bin/deeptutor module install solve --wheelhouse dist/modules
/tmp/deeptutor-modules/bin/deeptutor module install renderer-manim --wheelhouse dist/modules
/tmp/deeptutor-modules/bin/deeptutor module disable solve
/tmp/deeptutor-modules/bin/deeptutor module enable solve
/tmp/deeptutor-modules/bin/deeptutor module uninstall solve --dry-run
/tmp/deeptutor-modules/bin/deeptutor module uninstall solve

在 Windows 上使用等效的 Scripts/python.exe 和 Scripts/deeptutor.exe。请使用与应用程序相同的 DEEPTUTOR_HOME 运行命令。Python 包按环境安装；启用状态存储在 <home>/data/system/modules.json 中，并应用于该部署环境，而非单个学习者。--wheelhouse 会用本地构建的 wheel 补充包索引。

先安装 server 以使用 API，再安装 web 以使用打包好的 Web 资源。Web wheel 要求使用 scripts/prepare_web_package.py 生成的资源，供 deeptutor start 使用；源码开发服务器则使用检出环境中的 web/ 目录。构建和发布自动化会在构建 wheel 包家族之前准备好 Web 资源。

从 1.6.15 升级¶

停止旧进程并备份其运行时主目录。首先使用打包好的 Web 资源构建候选 wheel。在旧环境的可丢弃副本中，使用 python -m pip install --upgrade --find-links dist/modules "deeptutor[full]==<candidate-version>" 进行升级。如果旧版 deeptutor-cli 已安装，请先使用 python -m pip uninstall deeptutor-cli 将其卸载，再运行升级命令，并可选择添加新的兼容别名。旧版 CLI 拥有与新核心相同的 Python 文件：pip 会在移除旧 CLI 之前安装其新的核心依赖，从而删除新文件。先移除旧 CLI 可避免此冲突，并保留运行时主目录中的数据。对于仅迁移 CLI 的场景，请在此卸载后安装 deeptutor-cli==<candidate-version>。请使用确切的候选版本，以避免解析到较旧的已发布版本。保持 DEEPTUTOR_HOME 不变，运行 pip check，检查 deeptutor module list，并测试聊天、持久化会话和 Web 启动，然后才能升级真实环境。切勿仅针对用户数据的唯一副本进行测试。仅核心升级不会保留旧的完整应用配置。

deeptutor/__version__.py 是所有构建的版本来源，包括源码 CLI 兼容包。额外依赖项是 tool.deeptutor.optional-dependencies 中的模板；setuptools 和模块构建器都会将其内部固定版本解析到该版本。发布版本升级时，不得让依赖项仍指向之前的模块包家族。

所有权与组装¶

deeptutor/modules/manifests/*.json 是权威目录。每个清单拥有路径、依赖要求、回合能力、循环扩展、工具名称、API 路由器、授权策略、CLI 组、导航路径和后台服务回调。最长匹配路径优先。共享协议和轻量级上下文元数据保留在核心中；功能实现保留在各自的发行包中。构建器会拒绝重叠的 wheel 文件。

依赖关系是显式且无环的。例如，reading 当前需要 knowledge、parsing、mastery 和 notebook，因为其应用程序会使用这些存储。Books 还需要 questions、visualize 和 mastery，以支持其标准章节块和基于选定来源的引用依据。可选集成单独列出：Calendar 可以在没有 Mastery 的情况下工作，Research 和 Questions 可以在没有 Knowledge 的情况下工作，而 Parsing 从不导入 knowledge 存储。选择不可用的集成会返回安装提示。Knowledge Frontier 需要同时具备 Research 和 Knowledge；工具贡献可以声明额外需求，而不必将这些模块强加到其所属应用的每次使用中。在依赖项的已启用依赖者被禁用之前，无法禁用该依赖项。只要还有任何已安装的依赖者（包括已禁用的依赖者）存在，就无法卸载该依赖项。启用/安装会按顺序解析依赖。Core 无法被禁用或移除。

加载器不会导入缺失或已禁用的能力/循环实现。请求模式是惰性的。循环扩展在每个回合实例化一次，并且随着上下文变化会重新评估激活状态；实例绝不会跨回合共享。受管理插件的撤销状态仍会被检查。后台启动/停止回调保持成对，以便在部分启动时回滚。现有的 API 认证策略仍保留在所贡献的路由上；模块状态并不构成权限授予。

GET /api/modules 需要认证，并分别显示已安装、已启用和就绪状态。Runtime 设置页面会显示这些状态和离线命令。侧边栏和页面访问使用导航所有权；API 路由组装也会排除缺失的模块，包括共享路由中特定功能的路径。就绪检查会检查包要求、core/模块版本是否匹配以及外部可执行文件。已配置的提供方凭据和服务连接性仍保留在现有的设置就绪系统中。

生命周期保证¶

官方模块共享同一个解释器。正在运行的应用容器持有一个共享环境租约；模块变更需要跨进程的独占租约。当不同的 Python 环境共享同一个 home 目录时，第二个租约用于保护部署选择。在更改包或选择之前，请先停止 CLI 回合和 API worker。外部直接执行 pip 命令无法被此咨询锁阻止。

安装时首先解析依赖，拒绝替换已存在的包版本，并在修改环境之前构建精确的已解析构件。如果在添加包之后安装失败，则会移除这些新添加的发行版，包括在保存选择失败时也是如此。格式错误的选择会在任何包变更之前被拒绝。选择只有在包操作成功之后才会被原子替换。对于依赖冲突，请使用新环境或显式升级环境。这不是跨机器崩溃的原子文件系统事务；标准 pip 修复/重装仍是机器中断后的恢复路径。

卸载只会移除所选发行版。共享依赖会被保留，因为其他应用可能会使用它们。用户设置、会话、notebook、知识库、生成的构件和凭据绝不会被清除。重新安装会使用保留的数据。不存在隐式的数据删除命令。

从正在运行的设置/安装会话中安装 Parser 包时，现在会返回一条离线模块命令。它不再在活动回合期间升级包。模型权重下载仍作为后台任务进行，因为它们不会修改 Python 代码。第三方受管理插件会保留其现有的隔离环境。

第三方 Worker 扩展¶

受管理插件的 worker 使用自己的环境和生命周期，与官方模块 wheel 分开。请参阅 插件流式传输与取消 和 可运行示例。

验证¶

python scripts/sync_module_requirements.py --check
python -m pytest tests/modules tests/test_packaging_metadata.py
python scripts/build_modules.py --output dist/modules
python scripts/check_module_install.py --wheelhouse dist/modules --extended

安装冒烟测试会创建一个一次性虚拟环境，使用本地模拟模型（无需提供方凭据），检查核心聊天和持久重放，安装 Solve，运行它，卸载它，验证持久化文件，再次检查核心，然后重新安装 Solve。扩展模式会在没有 Knowledge 或 Mastery 的情况下安装 Parsing、Research 和 Calendar，执行解析及其缓存，以及独立的 research 和 calendar 路径，然后移除每个模块，同时验证 Solve 和保留的数据。源代码隔离测试还会在全新的子进程中，针对 25 个模块中的每一个禁止未声明的导入，并汇总它们的贡献。Manim 还需要系统渲染库、FFmpeg 和 LaTeX。对渲染器的更改应附带渲染和取消测试。Web 应用仍然是一个前端发行版；可独立替换的第三方前端 bundle 不在这个 Python 模块契约范围内。

实现与验证¶

• deeptutor/modules/manifests/
• scripts/build_modules.py
• scripts/check_module_install.py