Update SnapForm to version 0.10.10 and add technical documentation

- Bump SnapForm version in uv.lock from 0.9.30 to 0.10.10.
- Introduce comprehensive technical documentation for SnapForm, detailing features, usage instructions, and development guidelines.

README.md

@@ -1,331 +1,64 @@
 # SnapForm
 
-`SnapForm` 是一套从图片快速构建空间结构的 Blender Extension。目前以
-[Depth Anything 3](https://github.com/ByteDance-Seed/Depth-Anything-3)
-作为首个 AI 能力，在独立 Runtime 中运行 DA3，可将官方导出结果保存在独立 job 目录，
-也可把 Image Empty 转换成带几何与材质置换的立体面片。Debug 面板还可运行
-[BEN2](https://github.com/PramaLLC/BEN2) 背景剔除功能测试。
+SnapForm 是一个 Blender 扩展，可以把一张照片、一段视频或一组序列帧快速变成有真实深度的立体面片。
 
-## 当前功能
+## 它能做什么
 
-- 使用 Blender Extension manifest，可通过 `Install from Disk` 安装
-- 在独立 Python Runtime 的常驻 HTTP AI Host 中运行 Torch、DA3 与 BEN2，避免污染 Blender Python 进程
-- Blender 使用内置 `urllib.request` 访问仅监听 `127.0.0.1` 的 Host；请求带随机 Token
-- 常驻 Host 复用 Torch、CUDA、BEN2 与最近使用的 DA3 模型，连续执行时不再重复加载
-- 多个 Blender 实例自动连接同一个共享 Host；`Host` 面板显示状态、端口、客户端与模型缓存，并提供安装、启动、清理、重启和停止控制
-- Runtime、模型和任务结果默认保存在 `~/.snapform`，可由多个 Blender 版本共享
-- 支持 DA3 Small、Base、Large 1.1、Giant 1.1 和 Nested Giant Large 1.1
-- 支持 BEN2 Base 单图背景剔除测试，输出透明 PNG 与推理耗时
-- 支持单张 JPG、JPEG、PNG、WEBP 图片或常见视频文件输入
-- 视频均匀抽帧，可设置参与重建的最大帧数
-- `Host > Models` 默认折叠，展开后可逐项查看和下载所有可用模型
-- Runtime 已就绪时不额外占用面板空间；模型列表每个模型只占一行
-- `Debug` 默认折叠，内部的 DA3 与 BEN2 测试项也分别默认折叠
-- 使用一个导出类型下拉菜单和一个 `Export` 按钮
-- 只显示当前格式的专属参数；GLB 与 PLY 设置不会同时出现
-- Debug 的模型选项按格式过滤；PLY 只提供两个带 Gaussian head 的 Giant 模型
-- Debug 与 Convert to Depth Plane 的模型选项直接显示下载状态；未下载模型带
-  `(Missing)`，已下载模型保持原名
-- 分别调用 DA3 的 `glb`、`gs_ply`、`depth_vis` 和 `mini_npz` exporter
-- Image Empty 右键菜单可直接运行 DA3，根据 `mini_npz` 深度生成面片
-- Image Empty 右键菜单可直接运行 BEN2，保留原图并换用新建的透明背景图片
-- 使用浮点深度贴图、Simple Subdivision、Displace Modifier 和原图 Bump
-  构建立体面片
-- 转换对话框可选择推理模式、处理分辨率和面片网格细分
-- Debug 的 DA3 导出或 BEN2 背景剔除完成后只打开对应 job 文件夹，不向当前 Blender 文件添加任何数据
-- 完整保留每次任务生成的所有官方文件
-- 安装和模型下载使用后台子进程；推理提交给常驻 AI Host，状态栏实时显示阶段、百分比进度条与取消按钮
-- 后台任务运行时，Install、Download 和 Export 按钮保持原位置并变灰，任务完成后恢复
+- 一键把 Image Empty 转换为立体面片：让 AI 估算深度，或直接用原图作为深度
+- 一键去除图片背景，生成透明前景图
+- 支持视频与序列帧输入，逐帧处理，动画也能得到逐帧对应的立体面片
+- 全部操作都在右键菜单里完成，不需要写任何代码
 
-## 使用
+## 安装
 
-1. 使用 `uv run python pack.py` 构建 Extension ZIP。
-2. 在 Blender 的 `Preferences > Extensions` 中选择 `Install from Disk`。
-3. 在 Extension Preferences 中确认 `uv` 路径和 Torch Backend。
-4. 在 `Host` 点击 `Install Runtime`。首次安装会下载 Python、PyTorch、DA3、BEN2、FastAPI、Uvicorn，
-   并默认下载 `DA3 Small`、`DA3 Base` 和 `BEN2 Base` 模型。安装按 8 个阶段依次推进，每段进度
-   从 0 到 100%：下载 uv（如需）、创建 Python Runtime、下载 PyTorch、安装 xFormers（macOS 跳过）、
-   安装 AI 依赖、修补 DA3（跳过视频渲染），然后是三个模型的下载。进度文字统一为 `阶段/总数 阶段名: 状态`，
-   模型下载阶段会实时显示下载速度，例如 `6/8 da3 small: downloading 14.2MB/s`。
-   Runtime 就绪后即使模型下载中断也不影响 Host 使用，可稍后在 `Models` 面板单独补下。
-5. 在 3D View 按 `N`，打开 `SnapForm` 页签。
-6. 如需其他模型，展开 `Host > Models`，找到模型并点击该行的 `Download`。
-7. 展开默认收起的 `Debug`，选择 `Export Format` 和本次执行使用的模型。
-8. 选择一张图片或一个视频文件。视频可设置均匀抽取的帧数，然后点击 `Export`。
-9. 测试背景剔除时，确认 `Host > Models` 中的 `BEN2 Base` 已就绪，然后在 `Debug` 的
-   `BEN2 Background Removal` 区域选择单张图片并点击 `Remove Background`。
-   完成后会打开 job 文件夹，其中的 `foreground.png` 带透明 Alpha；状态栏显示
-   BEN2 推理、模型加载与任务总耗时。当前测试固定关闭较慢的 foreground refinement。
+1. 下载对应系统的扩展压缩包：
+- Windows：`SnapForm.v0.10.10.windows-x64.zip`
+- macOS（Apple 芯片）：`SnapForm.v0.10.10.macos-arm64.zip`
+- macOS（Intel）：`SnapForm.v0.10.10.macos-x64.zip`
+- Linux：`SnapForm.v0.10.10.linux-x64.zip`
+2. 打开 Blender，进入 `Preferences > Extensions`
+3. 点击 `Install from Disk`，选择下载的压缩包
+4. 在扩展偏好设置中确认 `uv` 路径与 Torch 后端（保持默认即可）；如果下载经常超时，
+   可以在 `PyPI Index` 里填一个国内镜像，例如 `https://pypi.tuna.tsinghua.edu.cn/simple`
+5. 打开 3D 视图右侧的 `SnapForm` 面板，点击 `Install Runtime`
 
-## Image Empty 去背景
+DA3、BEN2 源码包和 uv 已内置在扩展里，安装时直接从本地解包，不需要访问 GitHub。首次使用仍会自动
+下载运行环境依赖（PyTorch 等）和 AI 模型，请保持网络畅通，下载需要一些时间。
 
-1. 确认 `Host > Models` 中的 `BEN2 Base` 已就绪；首次安装 Runtime 时会默认下载。
-2. 在 3D View 选中 Image Empty，右键选择 `Remove Background`。
-3. 完成后以 Fake User 保留原 Image datablock，新建并 Pack 一张透明 PNG 到当前 `.blend`，然后只把
-   当前 Empty 的 `data` 换成新图；Empty 的 Transform、显示尺寸、Offset 及其他设置保持不变。
-4. 新 Image 使用原图去掉格式后再追加 `.rb` 的名称。例如 `img.png` 生成 `img.rb`，
-   `img.png.001` 生成 `img.001.rb`。已有同名 datablock 时由 Blender 自动追加编号。
+## 快速上手
 
-原图已 Pack 时会先写出临时 PNG 交给 BEN2，任务结束后删除临时输入；原 Image 仍保持 Pack
-状态和原始内容。BEN2 的 `foreground.png` 也会保留在对应 job 目录中。
+### 转换为立体面片
 
-## Image Empty 转深度面片
+1. 在 3D 视图中选中一个 Image Empty（空物体，显示方式为 Image）
+2. 右键选择 `Convert to Depth Plane`
+3. 在对话框中选择：
+   - `Depth from`：`Original` 直接用原图，`AI Generated` 让 AI 估算深度
+   - 需要去背景时勾选 `Remove Background`
+   - 其余选项保持默认即可
+4. 点击确认，稍等片刻就得到带位移的立体面片
 
-1. 在 3D View 选中 `Object Type = Empty`、`Display As = Image` 的对象。
-2. 右键选择 `Convert to Depth Plane`，通过 `Depth from` 选择深度来源：
-   - `AI Generated`：显示 Model、Use Ray Pose 和 Resolution Scale。实际 Process Res 为图片长边像素数
-     乘以 Resolution Scale；范围为 `0.1–1.0`，默认 `1.0`。计算后的 Process Res 会直接显示在
-     `Resolution Scale (… px)` 标签中。
-     转换导出 `mini_npz`，使用前需要在
-     `Host > Models` 下载所选模型，并固定使用 `process_res_method="upper_bound_resize"`；设备和参考视图策略
-     继续使用场景设置。Model 下拉菜单只列出已经下载的 DA3 模型；若没有可用模型，对话框会引导到
-     `Host > Models` 下载。
-   - `Original`：直接把原图作为深度贴图，不显示估算参数。Remove Background 关闭时不启动
-     Runtime，也不要求源图片存在于磁盘。
-   `Original` 是默认深度来源。选择 `AI Generated` 时，其 Model、Use Ray Pose 与 Resolution Scale
-   参数会集中显示在独立边框中。两种模式都有默认折叠的 Options，内部依次为 Displace via、
-   Subdivision、Remove Background 和 Unshaded；Delete Original 保持在折叠项外。
-   Remove Background 默认关闭，与 Depth from 无关；开启后需要下载 `BEN2 Base`，并从原图生成、
-   Pack `.rb` 透明图片。它只替换生成面片材质的颜色图片，不修改源 Image Empty 的 Image datablock。
-   AI Generated 仍从原图生成 `.depth`；例如 `img.png` 会得到 `img.rb` 与 `img.depth`，不会生成
-   `img.rb.depth`。Original 仍用原图作为位移来源，不改变原有深度逻辑。
-   Displace via 可选 `Modifier`（默认）或 `Material`；
-   Unshaded 默认关闭；Subdivision 默认为 `5`，并默认删除原对象。
-3. AI Generated 完成后会自动创建面片。面片几何先由 `mini_npz` 的相机内参与深度确定，再通过对象
-   Transform 匹配原 Image Empty 的可见尺寸、位置、旋转和 Offset。Original 模式直接使用源 Empty
-   的可见尺寸、Offset 与 Transform。开启 `Delete Original` 时，成功生成后
-   删除源 Empty。生成面片 Object 使用源 Empty 的原名；关闭 `Delete Original` 时不处理
-   同名冲突，由 Blender 自动为生成面片追加编号。
-4. 短边分段数为 `2^Subdivision`，长边分段数根据图像宽高比取最接近的整数。例如高:宽为
-   `2:3`、Subdivision 为 `1` 时，直接生成 `2×3` 个面；Subdivision 为 `3` 时生成
-   `8×12` 个面。随后的 Simple Subdivision 修改器使用原生名称，Viewport Levels 固定为
-   `1`，Render Levels 固定为 `2`，不再随 Resolution Scale 或 Subdivision 动态变化。
+### 去除背景
 
-所有任务使用统一的状态栏进度显示。变化中的阶段说明显示在右侧的紧凑进度条内部，取消按钮
-位于进度条右侧。Image Depth 的阶段包括 Runtime 启动、输入准备、模型加载、深度估算、缓存
-写出和面片构建。进度更新会强制刷新状态栏与窗口，无需移动鼠标即可实时显示。安装中断后残留的
-半成品 Runtime 会在下次安装前自动清理，不会因为中断而无法再次安装。
+选中 Image Empty 后，右键选择 `Remove Background`，完成后 Empty 会自动换成透明前景图。
 
-导入过程精确保留 NPZ 内深度值之间的差值。例如深度 `2.0` 和 `5.5` 在
-`Displacement Strength = -1` 时，沿局部 Z 轴相差 `3.5 Blender Unit`。它不会把数值压缩到
-`0..1`，也不再提供视觉归一化模式。
+### 视频与序列帧
 
-面片尺寸以有效深度的中位数 `Zref` 作为参考截面。先用 `mini_npz` 中的相机内参计算原始
-投影面积，再恢复源图纵横比：
+SnapForm 支持视频（mp4、mkv、mov 等）和序列帧，会逐帧处理并生成逐帧对应的立体面片。处理范围默认
+跟随 Empty 上设置的 `Image Frames` 与 `Offset`，不需要额外配置。
 
-```text
-RawWidth  = depth_width  × Zref × abs(Displacement Strength) / fx
-RawHeight = depth_height × Zref × abs(Displacement Strength) / fy
-Area      = RawWidth × RawHeight
-Aspect    = source_image_width / source_image_height
-Width     = sqrt(Area × Aspect)
-Height    = sqrt(Area / Aspect)
-```
+## 任务结果保存在哪里
 
-这样即使 DA3 估计出的 `fx/fy` 不一致，也不会把正方形原图拉成长方形。主点 `cx/cy` 仍用于
-确定原始相机面片，随后对象 XY Transform 将它匹配到源 Image Empty。生成对象会记录
-`snapform_reference_depth`、`snapform_camera_plane_width` 和
-`snapform_camera_plane_height`，便于检查实际采用的
-参考深度和尺寸。
+任务结果保存在 `~/.snapform/jobs/` 下，每个任务一个文件夹。视频或序列帧生成的面片会引用这些文件夹
+里的序列帧，请保留对应文件夹，不要随意删除。
 
-选择 `Modifier` 时，AI Generated 的 Displace Modifier 深度贴图使用 `Extension = Extend`，
-`Strength` 固定为 `-1`、`Midlevel` 固定为 `1`。Original 把原图指定给 Displace Texture，并设置
-`Texture Coordinates = UV`、`Midlevel = 0`；其余修改器设置保留 Blender 默认值。
-选择 `Material` 时，不创建 Displace Modifier；深度 Image Texture 的 Color 连接到 Displacement
-节点的 Height，再连接 Material Output 的 Displacement，并把材质 Surface Displacement 设置为
-`Displacement Only`。AI Generated 使用 `Midlevel = 1`、`Scale = -1`；Original 使用
-`Midlevel = 0`、`Scale = 1`，与对应修改器值一致。无论选择哪种呈现方式，原始彩色贴图都会连接
-Principled BSDF 的 `Base Color`，并通过
-`Bump.Height → Bump.Normal → Principled.Normal` 提供表面细节。Bump 的基础 Distance 为
-`0.001`，会乘以面片 Transform 的统一缩放倍率。原图 Color 还会经过 `Float Curve` 连接到
-Principled BSDF 的 `Roughness`，曲线两端输出分别为 `0.5` 和 `0.1`；材质 IOR 保持
-Principled BSDF 默认值 `1.5`。
-开启 `Unshaded` 后，原图 Color 连接 Emission，原图 Alpha 作为 Mix Shader 系数，在
-Transparent BSDF 与 Emission 之间混合后连接 Material Output；不创建 Principled BSDF、Bump 或
-Float Curve。若 Displace via 选择 `Material`，深度贴图与 Displacement
-节点仍会保留并连接 Material Output 的 Displacement。
+## 常见问题
 
-这里的“原始距离”是 DA3 模型输出的尺度。普通 Small、Base、Large 和 Giant 模型的深度不应
-被解释为现实世界的米；需要现实尺度时应选择带 metric depth 的
-`DA3 Nested Giant Large 1.1`。此外，当前结果仍是固定 XY 平面上的深度位移面，不是使用
-相机内参逐像素反投影得到的完整 camera-space 网格；中位深度截面为现有 Displace Modifier
-工作流提供正确的整体高宽尺度。
+- 首次使用需要下载模型，如果下载慢或失败，稍后在 `Host > Models` 里重试即可
+- 安装 Runtime 时提示下载超时：新版会自动探测并切换到镜像、失败时自动重试一次；如果仍然
+  超时，在扩展偏好设置的 `PyPI Index` 中填入镜像地址（如清华）后重新安装即可
+- 找不到右键入口时，请确认选中了 Empty，且显示方式为 Image
+- 动画面片不动：检查 Empty 的 `Image Frames` 是否大于 1，并确认播放场景帧
 
-生成完成后会直接创建面片，不提供缓存重建入口或单独的导入参数。重新选择
-`Convert to Depth Plane` 会按当前 Depth from 再次转换。
-面片、深度 Image、Texture 与 Material 会在同一个 Blender Undo 步骤中创建；转换完成后执行
-`Ctrl+Z` 会完整撤销本次转换，不会越过转换去回退更早的 Image Empty 操作。
-开启 Remove Background 时，`.rb` Image 的创建、Pack 和深度面片生成也属于
-同一个 Undo 步骤。
+## 技术文档
 
-Image Empty 使用 Packed Image 时，SnapForm 会通过 Blender 写出临时 PNG 交给 DA3，
-不会 Unpack 或修改源 Image；任务结束后自动删除临时文件。普通图片仍直接读取源文件。DA3 的原始
-`results.npz` 保留在对应 job 的 `exports/mini_npz/` 中，生成的浮点深度 Image 会 Pack 到
-当前 `.blend`。Depth Image 与 Displace Texture 根据源 Image datablock 命名。例如 Empty Object
-名为 `obj_img`、引用的 Image 名为 `img.png` 时，Depth Image 与 Texture 都命名为 `img.depth`；
-生成的 Object、Mesh 与 Material 仍命名为 `obj_img`。Pack 使用 OpenEXR，因而不会把大于 `1.0`
-的原始深度截断。已有同名 datablock 时由 Blender 自动追加 `.001` 等编号。
-
-选择 PLY 后，模型菜单只会提供 `DA3 Giant 1.1` 和
-`DA3 Nested Giant Large 1.1`。Small、Base 和 Large 没有 Gaussian head，无法由
-DA3 生成 `gs_ply`。
-
-每次任务会在 `~/.snapform/jobs/<任务目录>/` 中保留输出产物：
-
-```text
-<GLB 任务目录>/
-└── scene.glb
-
-<PLY 任务目录>/
-└── gs_ply/*.ply
-
-<Depth 任务目录>/
-└── depth_vis/*.jpg
-
-<Mini NPZ 任务目录>/
-└── exports/mini_npz/results.npz
-
-<BEN2 背景剔除任务目录>/
-└── foreground.png
-```
-
-建议从 `DA3 Base` 开始。它使用 Apache 2.0 模型权重；`DA3 Large 1.1` 权重采用
-CC BY-NC 4.0，仅限非商业用途。
-
-## 输出格式说明
-
-`Export Format` 下拉菜单分别把以下原始 `export_format` 传给 DA3：
-
-- GLB：`glb`
-- PLY：`gs_ply`，同时传入 `infer_gs=True`
-- Depth Images：`depth_vis`
-- Mini NPZ：`mini_npz`
-
-界面使用 DA3 API 的参数名、选项和默认值。GLB 专属设置仅在选择 `GLB` 时显示，
-`gs_views_interval` 仅在选择 `PLY (3DGS)` 时显示：
-
-- `process_res=504`
-- `process_res_method="upper_bound_resize"`
-- `use_ray_pose=False`
-- `ref_view_strategy="saddle_balanced"`
-- `conf_thresh_percentile=40.0`
-- `num_max_points=1_000_000`
-- `show_cameras=True`
-- `export_kwargs["gs_ply"]["gs_views_interval"]=1`
-
-DA3 官方 `glb` 是彩色点云与可选相机线框；`gs_ply` 是带 Gaussian 属性的 PLY；
-`depth_vis` 是原图与着色深度图的并排预览；`mini_npz` 保存深度、置信度和可用的相机参数。
-GLB 任务会关闭其默认附带的深度预览，使四种 job 产物保持分离。
-
-官方格式与限制可参阅
-[DA3 Python API 文档](https://github.com/ByteDance-Seed/Depth-Anything-3/blob/main/docs/API.md)。
-
-## Runtime
-
-Extension 本身不包含 Torch。`Install Runtime` 使用 `uv` 创建独立 Python 3.12
-环境，并安装。机器上即使没有安装 `uv` 或 Python 也没关系：安装程序由 Blender
-自带的 Python 启动，缺 `uv` 时会自动下载官方独立二进制（约 30MB），再用它下载
-Python 3.12 与全部依赖。`uv` 会缓存在扩展存储目录下，后续安装直接复用。
-安装前会自动预检磁盘空间与网络连通性，未通过会直接给出英文报错，不会开始下载。
-预检与安装支持环境变量切换镜像与代理：`PIP_INDEX_URL`（PyPI 镜像）、
-`SNAPFORM_TORCH_INDEX`（PyTorch 索引）、`HF_ENDPOINT`（Hugging Face 镜像，
-如 `https://hf-mirror.com`）、`HTTP(S)_PROXY`/`ALL_PROXY`（代理）。设置后预检会直接检查
-这些地址。直连不通时预检会**自动回退到镜像源**（清华 PyPI、阿里云 PyTorch、hf-mirror），
-无需手动配置，状态栏会提示 `using mirror sources`；镜像也不通才会报错。
-单独下载模型时也会先检查 Hugging Face 连通性，直连不通自动切换到 `hf-mirror` 镜像。
-Windows 上代理若只在系统设置里而未写入环境变量，安装程序会尝试自动从系统代理注入子进程。
-
-- PyTorch 2.9.1
-- TorchVision 0.24.1
-- xFormers 0.0.33.post2（与 PyTorch 2.9.1 对应，仅 Windows/Linux；macOS 无 wheel 自动跳过）
-- 固定到已验证 commit 的 Depth Anything 3
-- 固定到已验证 commit 的 BEN2
-- FastAPI 0.139.2 与 Uvicorn 0.51.0
-- DA3 与 BEN2 通过 GitHub 官方源码包安装（无需 Git）；SnapForm 直接调用 DA3
-  底层 export 接口，`gs_ply` 导出不会触发 `gs_video` 渲染，因此不需要 gsplat
-  与 C++ 编译工具链
-- `addict` 2.4.0（补充 DA3 上游包元数据暂未声明的运行依赖）
-
-默认 CUDA Backend 为 CUDA 12.8，也可以选择 CPU。CPU 可以用于验证，但实际推理
-通常很慢。
-CUDA 12.8 的 PyTorch wheel 自带 CUDA 运行库，无需安装 CUDA Toolkit；只需要
-NVIDIA 驱动 ≥ 570（数据中心显卡可用更老驱动）。驱动不满足或没有 NVIDIA 显卡时，
-设备会自动回退到 CPU（macOS 为 MPS），只有显式选择 CUDA 才会报错。
-
-macOS（Apple Silicon）会自动从 PyPI 安装 CPU 版 PyTorch，推理设备默认使用 MPS
-（Apple Metal）加速，也可以在设备选项里切换 CPU。PyTorch 自 2.3 起不再提供 Intel
-Mac（x86_64）轮子，Intel Mac 暂不支持。
-
-Extension 启用后只会查找已有的共享 AI Host，不会主动启动新进程。第一次执行 AI 操作或在侧边栏
-手动点击 `Start` 时才会启动 Host。Host 只绑定回环地址，并让操作系统分配动态端口；第一个实例把
-端口、进程和随机 Token 写入 `host.json`，其余 Blender 通过标准库
-`urllib.request` 连接同一个 Host。`host.lock` 保证同一 Storage Root 同时只有一个 Host，Token
-则阻止同机其他进程直接调用接口。Host 全局同时只执行一个 AI 任务。
-
-每个 Blender 会注册独立客户端并每 5 秒发送心跳。正常关闭 Blender 时先注销自身；如果当前 Host
-就是由这个 Blender 启动的，会直接终止它，无需等待。异常退出的客户端会在 10 秒后过期；Host
-在最后一个客户端离开后仍会保留模型缓存等待 20 秒再退出，作为 Host 由其他进程启动等场景的兜底。
-取消任务不会重启 Host，并会保留已经加载的模型；
-如果取消发生在一次不可中断的 Torch 调用中，任务会在该调用返回后的最近检查点结束。
-
-侧边栏 `Host` 面板以 `Running (Clients: n)` 表示空闲服务，以 `Running (Busy)` 表示正在执行任务，
-并显示缓存模型和活动任务。空闲且只有当前 Blender 连接时，可以清理模型缓存、重启或停止 Host；
-多客户端或任务执行期间不会允许破坏共享服务。
-
-BEN2 在首次使用后保持加载；DA3 保留最近使用的一个模型。切换 DA3 模型时会释放旧模型；加载时如果
-显存不足，会先释放另一类缓存模型并重试。
-
-Runtime Schema 已升级，旧 Runtime 需要重新执行 `Install Runtime` 才能安装 HTTP Host 依赖。
-Host 的启动和崩溃日志写入 `~/.snapform/ai-host.log`。
-
-Runtime、模型和任务结果默认保存在用户主目录的 `~/.snapform`：
-
-```text
-~/.snapform/
-├── runtime/
-├── models/
-├── jobs/
-├── ai-host.log
-├── host.json       # Host 运行时存在
-└── host.lock       # Host 运行时持有
-```
-
-不同 Blender 版本安装相同 Extension 后会共用这个目录。也可以在 Extension
-Preferences 的 `Storage Root` 中修改共享位置。不要把模型写入 Extension 安装目录，
-因为该目录可能只读，并且升级时会被替换。不要同时从多个 Blender 实例执行
-`Install Runtime`；推理 Host、任务队列和模型读取可以共享。
-
-## 开发
-
-```bash
-uv run python -m unittest discover -s tests -v
-uv run python pack.py
-```
-
-项目结构：
-
-```text
-.
-├── pack.py
-├── src/
-│   └── snapform/
-│       ├── blender_manifest.toml
-│       ├── ai_host.py
-│       ├── bootstrap_runtime.py
-│       ├── models.py
-│       ├── image_depth.py
-│       ├── operators.py
-│       ├── panel.py
-│       ├── preferences.py
-│       ├── properties.py
-│       ├── runtime.py
-│       └── worker.py
-└── tests/
-```
-
-## 上游与许可证
-
-- Depth Anything 3 代码采用 Apache 2.0。
-- BEN2 代码与模型权重采用 MIT License。
-- 本 Extension 代码采用 GPL-3.0-or-later。
-- 模型权重许可证由所选 Hugging Face 模型仓库决定，Extension 下载前会在界面显示。
+面向开发者的技术内容见 [docs/technical.md](docs/technical.md)。