Enhance device management and model handling in SnapForm

- Updated frame extraction logic to allow for single frame extraction.
- Integrated model readiness checks for BEN2 and DA3 models in relevant operators.
- Added directory name attribute to model specifications for better organization.
- Improved device selection logic for production and debug tasks.
- Refactored preferences to expose device settings and ensure they reflect available hardware.
- Enhanced runtime device detection and management, including support for CUDA and MPS.
- Updated tests to cover new device management features and model directory handling.
- Removed deprecated download model tests to streamline codebase.

docs/technical.md

@@ -50,18 +50,21 @@
    `linux-x64` 四个平台的 Extension ZIP（如 `SnapForm.v0.10.10.macos-arm64.zip`）。
    每个包只含对应平台的 uv 二进制，并内置 DA3、BEN2 源码包。
 2. 在 Blender 的 `Preferences > Extensions` 中选择 `Install from Disk`。
-3. 在 Extension Preferences 中确认 `uv` 路径和 Torch Backend。
+3. 在 Extension Preferences 中确认 Storage Root 与 Device。Device 是正式功能
+   （Image Empty 右键菜单）使用的推理设备，默认取本机最快的 CUDA/MPS，否则 CPU，且只列出
+   本机支持的设备。
 4. 在 `Host` 点击 `Install Runtime`。首次安装会下载 Python、PyTorch、FastAPI、Uvicorn；
    DA3、BEN2 源码包与 uv 已内置在扩展中，安装时从 `~/.snapform/sources/` 解包使用，
    并默认下载 `DA3 Small`、`DA3 Base` 和 `BEN2 Base` 模型。安装按 8 个阶段依次推进，每段进度
     从 0 到 100%：解包内置 uv、创建 Python Runtime、下载 PyTorch、安装 xFormers（macOS 跳过，
     内置 DA3 源码包为官方原版并已移除 xformers 硬依赖，自动回退纯 PyTorch 实现）、安装 AI 依赖，
-    然后是三个模型的下载。进度文字统一为 `阶段/总数 阶段名: 状态`，
+    然后是三个模型的下载。安装完成后进入 `验证 Runtime` 阶段，会导入 Torch 与全部 AI 依赖；
+    macOS 首次导入 Torch 会初始化 Metal 后端（编译 shader 缓存），该阶段可能持续较久，状态栏
+    会显示已用时间而不是卡住。进度文字统一为 `阶段/总数 阶段名: 状态`，
     模型下载阶段会实时显示下载速度，例如 `6/8 da3 small: downloading 14.2MB/s`。
     Runtime 就绪后即使模型下载中断也不影响 Host 使用，可稍后在 `Models` 面板单独补下。
-    安装不做启动网络预检：若网络无法稳定访问 pypi.org，可在扩展偏好设置的 `PyPI Index`
-    中指定镜像源（如清华、阿里），该地址会通过 `--pypi-index` 传给 bootstrap 并优先使用；
-    未指定时，pip 安装失败会自动重试一次清华镜像，模型下载由 worker 自行探测回退到 HF 镜像。
+    安装不做启动网络预检：pip 安装失败会自动依次重试清华、阿里镜像，模型下载由 worker
+    自行探测回退到 HF 镜像；需要手动指定镜像时可通过 `PIP_INDEX_URL` 环境变量覆盖。
 5. 在 3D View 按 `N`，打开 `SnapForm` 页签。
 6. 如需其他模型，展开 `Host > Models`，找到模型并点击该行的 `Download`。
 7. 展开默认收起的 `Debug`，选择 `Export Format` 和本次执行使用的模型。
@@ -85,7 +88,7 @@
 状态和原始内容。BEN2 的 `foreground.png` 也会保留在对应 job 目录中。
 
 Image Empty 引用视频或序列帧时，Remove Background 直接执行，默认取 Empty 的 Image Frames
-数值（未设置时为完整帧数），起始帧跟随 Empty 的 Offset；若 Offset 加 Frames 超出视频长度，
+数值（未设置时为完整帧数，显式设为 1 时只处理 1 帧），起始帧跟随 Empty 的 Offset；若 Offset 加 Frames 超出视频长度，
 会把窗口整体收进视频内（保证实际处理 Frames 帧数），Offset 过小时从第 1 帧开始。输出
 `foreground.0001.png` 等透明序列帧（帧号从 0001 开始，与 Blender 场景帧一一对应），并把
 源帧以 `frame.0001.jpg` 等命名复制到 job 目录根下供材质颜色导入。替换 Empty 的 Image 为
@@ -115,7 +118,7 @@ Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因
     `img.foreground` 与 `img.depth`，不会生成 `img.foreground.depth`。Original 仍用原图作为
     位移来源，不改变原有深度逻辑。
     Image Empty 引用视频或序列帧时，AI Generated 会按 Empty 的 Image Frames 数值逐帧估计
-    深度（未设置时为完整帧数），起始帧跟随 Empty 的 Offset，与 Remove Background 范围一致；
+    深度（未设置时为完整帧数，显式设为 1 时只处理 1 帧），起始帧跟随 Empty 的 Offset，与 Remove Background 范围一致；
     Offset 超出视频长度时同样把窗口收进视频内。材质节点与置换贴图的 Start 保持与原 Empty
     一致；Original 模式（无 Remove Background）时，单帧会复制原图改名为 `.depth` 供位移使用，
     视频或序列帧则抽帧保存为 job 目录根下的 `frame.0001.jpg` 等，并作为 `.depth` 序列使用。
@@ -307,8 +310,12 @@ Windows 上代理若只在系统设置里而未写入环境变量，安装程序
   并核对覆盖文件是否仍适用
 - `addict` 2.4.0（补充 DA3 上游包元数据暂未声明的运行依赖）
 
-默认 CUDA Backend 为 CUDA 12.8，也可以选择 CPU。CPU 可以用于验证，但实际推理
-通常很慢。
+安装 Runtime 时会自动选择 PyTorch 后端：检测到 NVIDIA 驱动则安装 CUDA 12.8 版本，否则安装
+CPU 版；macOS 始终安装 CPU 版 PyTorch（MPS 包含其中）。CPU 可以用于验证，但实际推理通常很慢。
+Extension Preferences 的 `Device` 决定正式功能的推理设备，默认取本机最快的 CUDA/MPS，否则
+CPU；Debug 面板的 `Debug Device` 只影响 Debug 任务。两处设备选项都只列出本机支持的设备：
+Windows 不显示 MPS，机器上没有可用 NVIDIA 驱动时不显示 CUDA。Runtime 安装完成时会检测真实
+可用的设备并写入 `snapform_ready.json`，设备列表以该检测结果为准。
 CUDA 12.8 的 PyTorch wheel 自带 CUDA 运行库，无需安装 CUDA Toolkit；只需要
 NVIDIA 驱动 ≥ 570（数据中心显卡可用更老驱动）。驱动不满足或没有 NVIDIA 显卡时，
 设备会自动回退到 CPU（macOS 为 MPS），只有显式选择 CUDA 才会报错。
@@ -352,6 +359,9 @@ Runtime、模型和任务结果默认保存在用户主目录的 `~/.snapform`
 └── host.lock       # Host 运行时持有
 ```
 
+`models/` 下每个模型一个文件夹，命名统一带前缀：DA3 为 `da3_*`（如 `da3_small`、`da3_base`），
+BEN2 为 `ben2_*`（如 `ben2_base`）。旧版无前缀的 DA3 文件夹会在首次使用时自动改名为新名称。
+
 不同 Blender 版本安装相同 Extension 后会共用这个目录。也可以在 Extension
 Preferences 的 `Storage Root` 中修改共享位置。不要把模型写入 Extension 安装目录，
 因为该目录可能只读，并且升级时会被替换。不要同时从多个 Blender 实例执行
@@ -360,7 +370,7 @@ Preferences 的 `Storage Root` 中修改共享位置。不要把模型写入 Ext
 ## 开发
 
 ```bash
-uv run python -m unittest discover -s tests -v
+uv run pytest tests -v
 uv run python pack.py
 ```