Add reusable local HTTP job service for Blender add-ons

- Implement JobClient for handling HTTP requests to the JobServer.
- Create ModalJobOperatorBase for managing Blender job lifecycle.
- Introduce JobContext and JobServer for job management and state handling.
- Add ServiceConnection and ServiceController for managing service processes.
- Implement job submission, cancellation, and resource management endpoints in the server.
- Ensure proper error handling and job state updates throughout the service.

docs/service.md

@@ -2,7 +2,9 @@
 
 ## 运行架构
 
-SnapForm 在独立的 Python 3.12 Environment 中运行常驻 HTTP Service，Blender 只通过标准库 `urllib.request` 提交任务，不把 AI 运行库载入 Blender Python。Service 只监听 `127.0.0.1`，请求使用随机 Token；同一 Storage Root 由 `service.lock` 保证只有一个实例。
+SnapForm 在独立的 Python 3.12 Environment 中运行 HTTP Job Server，Blender 只通过标准库 HTTP Client 提交和轮询任务，不把 AI 运行库载入 Blender Python。Service 只监听 `127.0.0.1`，由 BlendJob `ServiceController` 保存随机端口与 Instance ID；专属本地进程协议不使用额外 Token 鉴权。
+
+每个 Blender 实例启动并持有一个 SnapForm 专属服务，不发现或复用其它 Blender、其它插件启动的本地服务。多个 Blender 可以对应多个服务进程，但模型、Environment 与任务产物仍可共享同一个 Storage Root。
 
 Environment、模型和任务结果默认保存在 `~/.snapform`：
 
@@ -12,12 +14,30 @@ Environment、模型和任务结果默认保存在 `~/.snapform`：
 ├── models/
 ├── jobs/
 ├── manifest.json
-├── service.log
-├── service.json       # Service 运行时存在
-└── service.lock       # Service 运行时持有
+├── runtime.json       # 持久的模型下载源状态
+├── environment.log
+├── environment-status.json
+└── service.log
 ```
 
-不同 Blender 版本可共享此目录。也可以在 Extension Preferences 的 `Storage Root` 中修改位置。
+不同 Blender 版本可共享此目录。也可以在 Extension Preferences 的 `Storage Root` 中修改位置。连接端口与 Instance ID 只保存在启动它们的 Blender 进程内存中。
+
+通用 HTTP 层位于 `blendjob` module。`JobServer` 包装 FastAPI 并提供 Job 与 Resource API，`JobClient` 是无第三方依赖的 Blender 侧访问器。SnapForm 的 `ai_service/server.py` 只创建专属 Server、注册任务型 Job，并把 `ModelManager` 注册为 `models` Resource，不直接使用 FastAPI。完整接入方式见 [BlendJob 开发者指南](blendjob.md)。
+
+SnapForm 公开的 Request 构造函数与 Job Type 一一对应：
+
+- `download_model` → `download-model`
+- `remove_background` → `remove-background`
+- `extract_frames` → `extract-frames`
+- `generate_da3_depth` → `generate-da3-depth`
+- `generate_moge2_depth` → `generate-moge2-depth`
+- `generate_da3_surface` → `generate-da3-surface`
+- `generate_moge2_surface` → `generate-moge2-surface`
+- `debug_da3` → `debug-da3`
+- `debug_moge2` → `debug-moge2`
+- `debug_ben2` → `debug-ben2`
+
+DA3 与 MoGe-2 的生产任务不再合并成带 Backend 参数的通用 Request。每种 Request 只携带自己的有效参数，Debug 任务也与生产任务完全分开。
 
 ## ONNX-only Environment
 
@@ -41,7 +61,9 @@ Windows 当前发行环境提供 DirectML 与 CPU；`Auto` 优先使用 `DmlExec
 - DA3 Small、DA3 Base
 - BEN2 Base
 
-首次安装自动下载 `MoGe-2 ViT-S Normal` 与 FP16 `BEN2 Base`，其他模型在 `Models` panel 按需下载。模型按 Hugging Face 仓库末段名称保存在 `~/.snapform/models/`，并保留仓库内部结构。声明了文件清单与校验值的模型会直接走 Hugging Face `resolve` 直链流式下载，跳过文件清单与 ETag 预校验；连接源不可达时使用 3 秒 TCP 与 TLS 建连超时，随后回退到 `https://models.omoolab.xyz/<repository-name>/<relative-path>`，并把 `models_from_r2` 写入 service.json，本次 service 周期内后续模型直接走 R2，不再重复等待 Hugging Face。建连成功后不限制模型文件读取时长。R2 文件会校验大小与 SHA-256。未声明清单的仓库仍使用 `huggingface_hub` 快照下载。可用 `HF_ENDPOINT` 指定 Hugging Face 镜像。
+首次安装由 Bootstrap 流程自动下载 `MoGe-2 ViT-S Normal` 与 FP16 `BEN2 Base`。Environment 就绪后，`Models` panel 的后续下载提交为 `download-model` Job，与推理共用单任务调度、HTTP 进度和取消协议。模型按声明的目录名保存在 `~/.snapform/models/`，并保留仓库内部结构。声明了文件清单与校验值的模型会直接走 Hugging Face `resolve` 直链流式下载，跳过文件清单与 ETag 预校验；连接源不可达时使用 3 秒 TCP 与 TLS 建连超时，随后回退到 `https://models.omoolab.xyz/<repository-name>/<relative-path>`。镜像选择写入持久的 `runtime.json`，后续下载直接走 R2，避免每次 Service 重启后重复等待 Hugging Face。建连成功后不限制模型文件读取时长。R2 文件会校验大小与 SHA-256。未声明清单的仓库仍使用 `huggingface_hub` 快照下载。可用 `HF_ENDPOINT` 指定 Hugging Face 镜像。
+
+`models` Resource 对外统一表示模型系统，内部区分磁盘模型与内存 Session。`ModelSessionCache` 保留 BEN2，并在 DA3 与 MoGe-2 之间只保留最近使用的一种 Depth Session。`GET /resources/models` 返回当前加载状态；`POST /resources/models/clear` 只允许在没有 Active Job 时执行。
 
 DA3 ONNX 使用模型的 camera decoder 恢复外参与内参；旧版 `Use Ray Pose` 参数只为任务协议兼容保留，不参与 ONNX 推理。MoGe-2 的 metric depth、normal、mask、normalized intrinsics，以及 BEN2 的 Alpha，均在 NumPy 后处理中恢复。
 
@@ -56,9 +78,15 @@ uv 默认从 Astral 的 GitHub Release 下载，TCP 与 TLS 建连超过 3 秒
 
 ## 生命周期
 
-扩展启用后只查找已有 Service；第一次执行 AI 操作或点击 `Start` 时才启动。每个 Blender 客户端每 5 秒发送心跳，正常关闭时注销。最后一个客户端离开后，Service 保留模型缓存 20 秒再退出。
+扩展启用后不启动 Service；第一次执行 AI 操作或点击 `Start` 时才为当前 Blender 启动专属实例。正常关闭或禁用扩展时直接停止自己启动的进程；服务也监视 Blender 父进程 PID，父进程异常退出后会自行停止。
 
-Service 全局同时执行一个 AI 任务。BEN2 独立缓存，深度模型只保留最近使用的一个；切换模型时释放旧会话。取消任务不会重启 Service，ONNX Runtime 当前调用返回后在最近检查点结束。
+AI、帧提取和 Models panel 下载的 Job 进度保存在服务内存中。Blender 每 0.25 秒轮询 `GET /jobs/{job_id}`，任务目录不写 `status.json`。`JobRequest` 不包含 ID；Job 被接受时由 `JobServer` 自动生成 ID 并创建 `jobs/<opaque-job-id>/`，提交响应同时返回 `job_id` 与 `directory`。路径通过 `JobContext.directory` 传给 handler，SnapForm Service 强制将 Worker 输出写入该目录。
+
+SnapForm 的 Blender 侧访问与全部 Request 构造函数集中在 `client.py`。提交线程、轮询、进度、取消和终态清理由 `blendjob.ModalJobOperatorBase` 直接提供；`operators.py` 的 `SnapFormJobOperator` 只保留 SnapForm 输入校验、Request 选取和完成后的 Blender 结果导入。通用运行态是 `ModalJobState`，SnapForm 特有的导入参数单独放在 `SnapFormJobData`。插件专属 Service 只在 `ai_service/server.py` 注册 Job，完全不直接编写 FastAPI Route。
+
+只有 Environment 安装及其首次默认模型下载属于 Service 启动前的 Bootstrap 流程，使用 Storage Root 下共享的 `environment-status.json` 和 `environment.log` 回传进度，不创建 Job 目录。
+
+Service 全局同时执行一个 Job，包括模型下载。取消任务不会重启 Service；流式模型下载会在分块检查点结束，ONNX Runtime 当前调用则在返回后的最近检查点结束。JobServer 最多保留 100 个已完成 Job 的内存状态，后续提交时清理更早记录。
 
 启动与崩溃信息写入 `~/.snapform/service.log`。