Add new node asset scripts for geometry and shader operations

- Implemented `build_mesh_plane.py` to create a geometry node group for mesh planes with customizable parameters. - Created `build_shadeless.py` for a shader node group that displays color without scene lighting while preserving shadows and reflections. - Added `validate.py` to validate the integrity of the newly created node groups and their inputs. - Introduced `validate_cutout.py` to ensure the functionality of cutout node groups and their dependencies. - Developed `validate_mesh_plane.py` to test the mesh plane creation and its modifier settings.
2026-08-30 00:17:29 +08:00
parent 7d39fe8c5e
commit 32bcd45d7b
168 changed files with 7213 additions and 13121 deletions
--- a/docs/internals/architecture.md
+++ b/docs/internals/architecture.md
@@ -0,0 +1,65 @@
+# 程序架构
+
+AnyImage 由 Blender 交互层、BlendJob Runtime 和独立 Job Server 三部分组成。这个分层让 Blender Python 不需要加载 ONNX Runtime、Pillow 或模型权重，同时保证所有 Blender 数据仍在主线程创建和修改。
+
+## 对应文件
+
+```text
+src/anyimage/
+├── __init__.py       # 类型、工具、菜单与 Runtime 注册
+├── menu.py           # Image Empty 上下文入口
+├── panel.py          # Server 与 Debug 面板
+├── preferences.py    # Storage Root、Device 与功能默认值
+├── properties.py     # Scene 状态、模型状态与动态枚举
+├── runtime.py        # Environment 和 JobRuntime
+├── operators/        # Blender 侧业务入口
+└── server/           # 独立计算端
+```
+
+## 职责边界
+
+| 层次 | 负责 | 不负责 |
+| --- | --- | --- |
+| Blender 交互层 | UI、手势、RNA 状态、输入准备、结果导入、Undo | 在 Blender 进程加载 AI 依赖 |
+| BlendJob Runtime | Environment、Server 生命周期、队列、进度、取消、Job 目录 | AnyImage 的图像与几何业务 |
+| Job Server | 媒体解码、ONNX 推理、数组派生、文件输出 | 创建 Blender 对象或访问 `bpy` |
+
+Operator 向 Server 发送普通字典。Server 返回文件名和 Job 目录；Operator 的 `response()` 再读取这些文件，并在 Blender 主线程中创建 Image、Mesh、Material 和 Geometry Nodes Modifier。
+
+## 注册与状态
+
+```mermaid
+flowchart TD
+    Register["anyimage.register()"] --> Types["注册 Preferences / PropertyGroup / Operator / Panel"]
+    Types --> Tools["注册 Image Tools 与 Cutout WorkspaceTool"]
+    Tools --> RNA["挂载 Scene 与 Image Property"]
+    RNA --> Menu["挂载上下文菜单和剪贴板快捷键"]
+    Menu --> Runtime["注册 JobRuntime"]
+```
+
+`__init__.py` 按依赖顺序注册，并在注销时逆序清理。扩展级设置统一由 `preferences.addon_preferences()` 读取；`runtime.py` 只消费 `configured_storage_root` 回调，不持有 Blender 偏好设置的定位逻辑。交互中的临时状态和 Debug 参数保存在 `Scene.anyimage_settings`，Upscale 的原图引用保存在 `Image.anyimage_upscale_source`。 全局 `max_ai_input_size` 也在 `preferences.py` 定义与读取，由 Operator 冻结到每次 Job 请求。
+
+## 同步与异步路径
+
+无需 AI 或媒体处理的功能直接在 Blender 中完成，例如 Plane、普通 Image Mask、Perspective，以及未启用 Refine/Normal 的 Surface 和 Balloon。需要模型或独立文件处理时，功能 Operator 派生自 `JobOperatorBase`：
+
+```mermaid
+sequenceDiagram
+    participant User as 用户
+    participant Op as Blender Operator
+    participant RT as JobRuntime
+    participant Job as Server Job
+    User->>Op: 执行功能
+    Op->>Op: 准备文件与普通字典
+    Op->>RT: 提交 Job
+    RT->>Job: 排队执行
+    Job-->>RT: 写入产物并返回索引
+    RT-->>Op: 主线程 response
+    Op->>Op: 导入数据并提交 Undo
+```
+
+这条边界也决定了模块依赖方向：`server/` 不导入 `bpy` 或 `operators/`；Blender 侧可以读取 Server 产物，但不会复用 Server 中的 Blender 无关算法来创建 RNA 数据。
+
+## 共享能力
+
+`operators/common/` 保存多个功能真实复用的能力：图片输入与命名、像素写回、手势状态、Mask 运算、Image Empty 坐标、材质、节点资产、法线烘焙和 Job 参数辅助。共享模块只承载跨功能概念；完整工作流仍留在各自功能包中，以便从用户入口追踪到实现。
--- a/docs/internals/development.md
+++ b/docs/internals/development.md
@@ -0,0 +1,81 @@
+# 开发与发布
+
+AnyImage 的仓库环境用于测试 Blender 侧代码、Server 纯 Python 模块、Manifest 和打包逻辑。AI Runtime 使用另一套 Python 3.12 Environment，不应与仓库开发环境混为一谈。
+
+## 对应文件
+
+```text
+.
+├── pyproject.toml
+├── uv.lock
+├── .python-version
+├── pack.py
+├── sync_models.py
+├── src/anyimage/blender_manifest.toml
+├── tests/
+├── tools/node_assets/
+└── .github/workflows/
+    ├── test.yml
+    ├── build.yml
+    └── docs.yml
+```
+
+## 开发环境
+
+仓库固定使用 CPython 3.11，因为开发依赖 `bpy==4.5.3` 对应这一解释器版本。项目根目录执行：
+
+```bash
+uv sync
+uv run pytest
+```
+
+快速检查注册、Manifest 和打包时使用：
+
+```bash
+uv run pytest tests/test_addon.py tests/test_manifest.py tests/test_pack.py -v
+```
+
+测试按边界组织：`test_addon.py` 以 Blender Stub 验证注册和 Operator 流程；`test_mesh.py`、`test_image.py` 等验证可脱离 Blender 的算法；`test_server.py`、`test_models.py` 和各 ONNX 测试覆盖计算端；`test_pack.py` 与 `test_manifest.py` 固定发布包结构。
+
+## 扩展打包
+
+```bash
+uv run python pack.py
+```
+
+`pack.py` 为 `windows-x64`、`macos-arm64` 和 `linux-x64` 分别解析依赖 wheel，生成平台专属 Manifest，再把 `src/anyimage/` 与 wheel 写入 `dist/`：
+
+```text
+dist/
+├── AnyImage.v<version>.windows-x64.zip
+├── AnyImage.v<version>.macos-arm64.zip
+└── AnyImage.v<version>.linux-x64.zip
+```
+
+本地 `src/anyimage/wheels/` 是 wheel 解析的优先来源，用于携带尚未发布的 BlendJob 构建。依赖、wheel 或 Manifest 变化后，需要同时检查 `pyproject.toml`、`uv.lock`、`blender_manifest.toml` 和打包测试；本地 wheel 内容变化后运行 `uv lock --refresh`。
+
+## 文档
+
+```bash
+uv run --only-group docs mkdocs serve
+uv run --only-group docs mkdocs build --strict
+```
+
+站点导航由 `mkdocs.yml` 显式维护，因此移动页面时必须同时更新导航和相对链接。Mike 仍可用于本地版本化发布；CI 则直接构建严格模式站点并部署到 Cloudflare Worker。
+
+## CI
+
+```mermaid
+flowchart TD
+    Main["push main / Pull Request"] --> Test["uv run --frozen pytest"]
+    Tag["push v* tag"] --> Release["测试 → pack.py → Release ZIP"]
+    Docs["main 上文档变更"] --> Site["mkdocs --strict → Cloudflare"]
+```
+
+`test.yml` 在 main push、Pull Request 与手动触发时运行完整测试。`build.yml` 只响应 `v*` tag，测试通过后构建并上传三个平台包。`docs.yml` 只在文档相关路径变化或手动触发时部署站点。
+
+## 许可证
+
+AnyImage Extension 代码采用 GPL-3.0-or-later，完整文本见仓库 `LICENSE`。模型权重保持各自上游许可证；模型目录声明下载来源、文件校验和许可信息，技术文档不复制可能变化的制品清单。
+
+Geometry Nodes 资产必须由 Blender 构建和验证，见[节点资产](node-assets.md)。
--- a/docs/internals/index.md
+++ b/docs/internals/index.md
@@ -0,0 +1,48 @@
+# 内部实现总览
+
+AnyImage 的实现围绕一条清晰边界展开：Blender 进程负责交互与数据创建，独立 Job Server 负责模型推理和文件处理。两侧通过 BlendJob 传递可序列化参数与 Job 目录中的产物，不跨进程传递 Blender RNA 数据。
+
+```mermaid
+flowchart TD
+    Input["Image Empty / 手势"] --> Operator["Blender Operator"]
+    Operator --> Choice{"需要独立计算？"}
+    Choice -- "否" --> Build["Blender 主线程构建"]
+    Choice -- "是" --> Runtime["BlendJob Runtime"]
+    Runtime --> Server["Job Server"]
+    Server --> Files["Job 产物"]
+    Files --> Build
+    Build --> Result["Image / Mesh / Material / Modifier"]
+```
+
+## 项目主干
+
+总览只展示稳定边界；各功能包的具体文件在对应实现页中展开。
+
+```text
+.
+├── src/anyimage/
+│   ├── __init__.py          # Blender 注册入口
+│   ├── menu.py              # Image Empty 右键菜单
+│   ├── preferences.py       # 扩展级配置
+│   ├── properties.py        # Scene 状态与模型枚举
+│   ├── runtime.py           # BlendJob Runtime 配置
+│   ├── operators/           # 交互、任务提交与结果导入
+│   ├── server/              # 无 Blender 依赖的计算端
+│   ├── assets/              # 随扩展分发的节点资产
+│   └── wheels/              # 随扩展分发的 BlendJob wheel
+├── tools/                   # Blender 资产构建与验证
+├── tests/                   # Python 自动化测试
+├── pack.py                  # 多平台扩展打包
+└── sync_models.py           # ONNX 模型同步
+```
+
+## 文档分层
+
+- [程序架构](architecture.md)：注册、配置、线程和模块边界。
+- [Job Runtime 与 Server](runtime.md)：任务生命周期、媒体输入和模型 Session。
+- [Operator 实现索引](operators/index.md)：按 `src/anyimage/operators/` 中的完整功能拆分实现页。
+- [Job 产物](outputs.md)：文件用途和 Blender 导入关系。
+- [开发与发布](development.md)：本地环境、测试、打包和 CI。
+- [节点资产](node-assets.md)：Geometry Nodes 的构建、加载与验证。
+
+内部实现文档描述模块之间的职责和主要数据流。函数级分支、参数校验与异常处理以源码和测试为准，避免文档重复实现细节。
--- a/docs/internals/node-assets.md
+++ b/docs/internals/node-assets.md
@@ -0,0 +1,58 @@
+# 节点资产
+
+AnyImage 将稳定、可复用的 Geometry Nodes 和 Shader 节点组构建到 `O_AnyImage.blend`，运行时按名称加载。Depth Plane 节点图是例外：它由 Python 在当前 `.blend` 中按需创建。
+
+## 对应文件
+
+```text
+src/anyimage/
+├── assets/O_AnyImage.blend
+└── operators/common/
+    ├── node_asset.py   # 资产路径、加载与 Modifier 输入
+    └── node_graph.py   # 共享节点图构造函数
+
+tools/node_assets/
+├── build.py                # 统一构建入口
+├── build_mesh_plane.py
+├── build_shadeless.py
+├── build_cutout.py
+├── validate.py             # 资产清单与基础接口
+├── validate_mesh_plane.py
+└── validate_cutout.py
+```
+
+## 构建与加载
+
+```mermaid
+flowchart TD
+    Scripts["tools/node_assets/build_*.py"] --> Build["Blender 后台构建"]
+    Build --> Blend["assets/O_AnyImage.blend"]
+    Blend --> Loader["operators/common/node_asset.py"]
+    Loader --> Modifier["运行时 Node Group / Modifier"]
+```
+
+使用 Blender 而不是普通 Python 执行：
+
+```bash
+BLENDER_BIN="/c/Program Files/Blender Foundation/Blender 4.5/blender.exe"
+
+"$BLENDER_BIN" --background --python tools/node_assets/build.py
+"$BLENDER_BIN" --background --python tools/node_assets/validate.py
+"$BLENDER_BIN" --background --python tools/node_assets/validate_mesh_plane.py
+"$BLENDER_BIN" --background --python tools/node_assets/validate_cutout.py
+```
+
+`build.py` 从空 Factory 文件开始，依次构建 `O Mesh Plane`、`O Shadeless`、四个 Cutout 内部节点组与公开修改器节点组 `O Image Cutout`，再保存唯一资产文件。`O Image Cutout` 用 Menu Switch 包装四个内部组；运行时 Loader 只加载这个稳定入口，Blender 4.5 根据 Shape 菜单依赖只显示当前分支实际使用的输入。
+
+## 验证范围
+
+基础验证检查发布资产清单、节点树类型、Modifier 标记、接口顺序和 Fake User。专项验证继续检查：
+
+- Mesh Plane 的接口、细分、Thickness 和几何求值；
+- `O Image Cutout` 的公开接口、Shape 菜单和四个内部组的依赖关系；
+- 节点不重叠、主要连线保持从左向右；
+- 局部 Group Input 未使用输出隐藏；
+- Cleanup 只在四条分支之前执行，Smooth 只在菜单选择之后执行；
+- Repeat Zone 数量和四种 Shape 的关键几何求值稳定。
+
+节点资产接口变化时，应运行全部四个 Blender 入口和完整 Python 测试。只修改 Python、Markdown 或打包逻辑时无需重建 `.blend`。Blender 自动生成的 `.blend1` 等备份不属于发布资产。
--- a/docs/internals/operators/ai-setup.md
+++ b/docs/internals/operators/ai-setup.md
@@ -0,0 +1,36 @@
+# AI 环境管理
+
+本页对应 `src/anyimage/operators/ai_setup.py`。该模块把环境安装、必需模型下载和模型缓存清理组织成 Blender 可调用的 Operator。
+
+## 对应文件
+
+```text
+src/anyimage/
+├── operators/ai_setup.py        # 环境与模型管理入口
+├── preferences.py               # 环境位置和扩展级设置
+├── properties.py                # 环境状态与模型目录
+├── runtime.py                   # BlendJob Runtime 访问入口
+└── server/
+    ├── app.py                   # 下载 Job 注册
+    ├── model_catalog.py         # 模型元数据
+    ├── model_download.py        # 模型文件下载
+    └── model_manager.py         # 模型资源与 Session 缓存
+```
+
+## 主流程
+
+```mermaid
+flowchart TD
+    Entry["Set Up AI Environment"] --> Status["读取环境与必需模型状态"]
+    Status --> Ready{"是否全部就绪？"}
+    Ready -- "是" --> Done["结束"]
+    Ready -- "否" --> Environment{"运行环境是否就绪？"}
+    Environment -- "否" --> Install["安装隔离 Python 环境"]
+    Environment -- "是" --> Download["下载缺失的必需模型"]
+    Install --> Download
+    Download --> Done
+```
+
+`SetupAIEnvironment` 是统一入口：首次使用时选择普通源或镜像安装隔离环境；环境已存在时，只补齐必需模型。单模型下载和必需模型批量下载都通过 Job Server 执行，因此状态、错误与进度沿用同一套 Runtime 通道。
+
+`OpenAIEnvironmentSettings` 将用户带到扩展首选项。`ClearModels` 清除 Runtime 中的 `model_manager` 资源，使已加载的模型 Session 释放；它不负责删除磁盘上的模型文件。
--- a/docs/internals/operators/clipboard-image.md
+++ b/docs/internals/operators/clipboard-image.md
@@ -0,0 +1,34 @@
+# 剪贴板图片
+
+剪贴板功能把操作系统中的图片转换为 Packed Blender Image，再根据当前编辑器创建对象、节点或画笔纹理。它完全运行在 Blender 进程中，不使用 Job Server。
+
+## 对应文件
+
+```text
+operators/clipboard_image/
+├── __init__.py   # Operator、原生复制优先级与快捷键
+├── clipboard.py  # Windows、macOS、Linux 剪贴板读取
+└── actions.py    # Image 复用、Pack 与各编辑器落点
+```
+
+## 处理流程
+
+```mermaid
+flowchart TD
+    Paste["Ctrl/Cmd + V"] --> Priority{"刚执行过 Blender Copy？"}
+    Priority -- "是" --> Native["交回原生 Paste"]
+    Priority -- "否" --> Read["读取系统图片"]
+    Read --> Image["按内容哈希复用或创建 Packed Image"]
+    Image --> Target{"当前编辑器"}
+    Target --> View["Reference / Plane"]
+    Target --> Node["Image Node"]
+    Target --> Paint["Brush Texture"]
+```
+
+`TrackNativeCopy` 在相同快捷键下记录系统剪贴板变化标记。如果剪贴板没有在 Blender Copy 之后变化，Paste Operator 返回 `PASS_THROUGH`，让 Blender 原生对象或节点粘贴优先执行。
+
+`clipboard.py` 封装平台差异：Windows 读取 DIB/DIBV5，macOS 与 Linux 调用平台提供的图片导出命令。模块最终都返回编码后的图片字节和扩展名，后续流程不再关心来源平台。
+
+`actions.py` 以 SHA-256 标记 Packed Image，相同内容可复用已有数据块。3D View 中的 Reference 和 Plane 使用鼠标位置或视图落点；Plane 复用 `convert_to_plane/mesh_plane.py` 的基础网格与 `O Mesh Plane` 资产。Node Editor 根据树类型选择对应 Image 节点，绘制模式则为当前画笔配置 Texture。
+
+快捷键只注册到 3D View 与 Node Editor；编辑器内部的具体支持范围由 `target_for_context()` 决定。创建成功后图片始终 Pack 到当前 `.blend`，避免依赖临时剪贴板文件。
--- a/docs/internals/operators/convert-to-plane.md
+++ b/docs/internals/operators/convert-to-plane.md
@@ -0,0 +1,58 @@
+# Plane 转换
+
+Plane 转换包含两条路径：普通 Plane 在 Blender 内同步完成；Depth Plane 先通过 `prepare-geometry-data` Job 取得深度场，再回到 Blender 构建面片。两者共享图片命名、材质与基础四边形能力，但使用不同的 Geometry Nodes。
+
+## 对应文件
+
+```text
+operators/convert_to_plane/
+├── __init__.py    # 对外导出
+├── conversion.py  # 两个入口 Operator 与 Depth Job
+├── build.py       # 颜色、深度场、材质和对象导入
+├── mesh_plane.py  # 基础四边形与 O Mesh Plane 修改器
+└── nodes.py       # 运行时 O Image Depth Plane 节点图
+
+server/
+├── jobs/prepare_geometry_data.py
+├── models/da3.py
+├── models/moge2.py
+└── geometry/projection.py
+```
+
+## 总体流程
+
+```mermaid
+flowchart TD
+    Empty["Image Empty"] --> Kind{"转换类型"}
+    Kind -- "Plane" --> Copy["复制 Image 与材质"]
+    Copy --> Quad["创建四边形 + O Mesh Plane"]
+    Kind -- "Depth Plane" --> Input["准备颜色与分析输入"]
+    Input --> Job["prepare-geometry-data"]
+    Job --> Field["image.0001 + field.npz"]
+    Field --> Anchor["按 Empty 范围锚定相机点"]
+    Anchor --> Depth["创建深度 Image + 材质 + 节点修改器"]
+    Quad --> Replace["替换源 Empty"]
+    Depth --> Replace
+```
+
+## 普通 Plane
+
+`ConvertToPlane` 复制当前 Image 数据，保留 Movie / Sequence 的 Image User 设置，创建与 Image Empty 显示范围一致的四边形，再加载内置 `O Mesh Plane` 节点组。原始 Mesh 始终只有一个四边形；`Subdivide`、`Thickness` 和材质赋值由修改器执行。
+
+对象继承源 Empty 的 `matrix_world`。转换完成后删除源 Empty，并让新 Plane 沿用对象名称。剪贴板的 Plane 导入复用同一构建函数，因此两种入口得到一致的基础网格与修改器。
+
+## Depth Plane
+
+`ConvertToDepthPlane` 当前只接受静态图片。深度模型和分辨率来自扩展 Preferences：MoGe-2 使用 Resolution Level，DA3 使用按原图尺寸换算并对齐到模型 Patch 的处理分辨率。
+
+`GenerateDepthPlane` 把颜色输入、分析输入和模型参数提交给 `prepare-geometry-data`。Server 将模型结果统一为 `GeometryFrame`，写出包含相机点、深度、内参、有效区域和参考深度的 `field.npz`。这一步不创建网格。 `max_input_size` 同时传入 Job；Server 通过 `media/resolution.py` 在模型推理前限制分析图长边，默认 `2048`。颜色输入仍由未缩放的原图复制，受限分析图不会成为材质 Color。
+
+Blender 响应阶段执行三件事：
+
+1. 根据 Image Empty 的平面范围、相机内参和参考深度，把相机点等比锚定到对象局部空间。
+2. 将锚定点的局部 Z 写入 Packed 浮点 `_depth.exr` Image，并创建颜色材质。
+3. 创建基础四边形和运行时 `O Image Depth Plane` 节点组，以 UV 采样深度并移动正面。
+
+Depth 节点组先复用 `O Mesh Plane` 完成细分与材质，再生成背面厚度、限制正面向内穿透，最后在 Thickness 为零时删除背面和侧面。`Depth Amount` 控制位移强度；`Depth Image` 与 `Material` 是由插件填入的内部输入。
+
+与 Cutout 的 Depth Surface 不同，Depth Plane 只使用锚定后的 Z 高度，不在 Geometry Nodes 中重建完整相机空间 XYZ。它强调一张图上的可编辑浮雕，而不是局部透视表面。
--- a/docs/internals/operators/cutout-tool.md
+++ b/docs/internals/operators/cutout-tool.md
@@ -0,0 +1,80 @@
+# Cutout
+
+Cutout 从一条图片空间套索生成规则三角基础面，再交给统一的 `O Image Cutout` Geometry Nodes 修改器形成 Surface、Balloon、Depth Balloon 或 Depth Surface。公开节点组用 Shape 菜单路由到四个原有内部节点组；轮廓和 Mesh 始终由 Blender 主线程创建，Server 只在需要时准备 Refine、深度或法线数据。
+
+## 对应文件
+
+```text
+operators/cutout_tool/
+├── selection_tool.py     # 套索交互、设置与 Shape 饼菜单
+├── shape_conversion.py   # 本地 / Job 路径选择和任务参数
+├── build_shapes.py       # 裁切贴图、Mesh、材质与修改器
+├── shape_types.py        # Shape 与节点组映射
+├── mask_regions.py       # Alpha 外轮廓与孔洞
+├── planar_mesh.py        # 规则采样与约束三角化
+├── balloon_profile.py    # Poisson / Teddy profile
+├── depth_calibration.py  # Reference 与 Direction
+└── node_assets.py        # Cutout 节点资产加载
+
+server/
+├── jobs/prepare_geometry_data.py  # Cutout / Depth Plane 数据编排
+├── selection/
+│   ├── polygon_mask.py            # Polygon 栅格化与选区裁切
+│   └── cutout_images.py           # Refine 与 Cutout 局部图片
+└── geometry/normal_texture.py     # 相机轴法线编码
+```
+
+## 路径选择
+
+```mermaid
+flowchart TD
+    Lasso["套索 + Shape"] --> Refine{"Refine Selection？"}
+    Refine -- "是" --> Ben2["BEN2 × 1"]
+    Refine -- "否" --> Selection["套索 Selection"]
+    Ben2 --> Selection
+    Selection --> NeedMoge{"需要 Depth 或 Normal？"}
+    NeedMoge -- "否" --> Mesh["轮廓 → 规则点 → 约束三角化"]
+    NeedMoge -- "是" --> Moge["MoGe-2 × 1\\n同一 Prediction"]
+    Moge --> Data["Depth Field / Camera Normal"]
+    Data --> Mesh
+    Mesh --> Profile["计算 o_balloon"]
+    Profile --> Nodes["加载 O Image Cutout 并设置 Shape"]
+    Nodes --> Bake["按需烘焙最终 Tangent Normal"]
+```
+
+Cutout 只接受静态图片。Refine Selection 是网格生成前唯一可选的选区分析：开启时执行一次 BEN2，关闭时直接使用套索 Selection。Surface 与 Balloon 在不需要 Normal 时不运行 MoGe-2；两个 Depth Shape 和任意开启 Normal 的 Shape 都统一使用 MoGe-2。Depth 与 Normal 同时启用时只执行一次推理，同一个 Prediction 同时提供相机点、深度和图片空间法线。
+
+Cutout 不使用 DA3。若全局 Depth Model 当前选择 DA3，Cutout 会回退到默认 MoGe-2；选择 MoGe-2 档位时则沿用该档位和 Resolution Level。DA3 仍可用于独立的 Depth Plane 流程。
+
+## 选择与局部数据
+
+Cutout 复用 `ImageMaskGesture` 的采点和屏幕预览，并复用 `operators/common/image_mask.py` 的可见选区语义：最终几何范围始终是套索、图片边界与源图 `Alpha > 0.1` 区域的交集。套索采用 NONZERO 填充规则，使反向内环可以表达孔洞。`Point Spacing` 先根据完整源图最长边换算为基础 `mesh_detail`；获得裁切 Selection 后，再按 `min(1, max_input_size / crop_long_edge)` 缩放有效 `mesh_detail`。因此只有裁切图超过全局上限时网格才会变稀，Color Image 仍使用原始裁切尺寸。
+
+Job 路径将数据拆成三层：源颜色、最终选择和只供模型分析的 RGBA。写出最终选择前会再次以 `Alpha > 0.1` 与源图求交，因此未 Refine、Refine 和双击全图遵循相同边界。`bounds.json` 把可见选区的局部矩形映射回源图，Blender 据此恢复局部平面范围和 UV。未走 Job 时，`build_shapes.py` 在内存中完成相同的求交、裁切与坐标换算。
+
+## 基础网格
+
+最终 Alpha 先转为带包含关系的外轮廓与孔洞。`planar_mesh.py` 在内部生成近似六角排列的规则点，并用轮廓作为约束进行 Delaunay 三角化。边界按目标间距重采样，短轮廓会提高边界采样密度，内部点仍保持用户设置的间距。
+
+四种 Shape 共享同一张单面基础网格、UV 和 `o_balloon` 点属性。创建阶段以目标 Point Spacing 的平方作为一个采样单元面积，再除以 Image Empty 图片平面从局部到世界的面积缩放，得到修改器局部坐标中的 Cleanup 阈值。这个值只取决于工具分辨率和图片尺寸/变换，不受碎片数量或碎面面积分布影响。Balloon Profile 由 Preferences 选择 Poisson 或 Teddy；节点组只消费计算后的属性，不再重复推导轮廓。
+
+## 统一修改器与四种 Shape
+
+创建结果时始终添加 `O Image Cutout`，并按饼菜单选择写入 Shape。节点组先统一执行 Cleanup，再由 Menu Switch 仅求值当前 Shape 的内部节点组，最后统一执行 Smooth；因此四种 Shape 都可使用 Cleanup、Smooth 和 Smooth Iterations。各分支独有输入直接连接到对应内部组，Blender 4.5 会在修改器中隐藏当前 Shape 不使用的输入。Cleanup 直接比较 Mesh Island 总面积与创建时写入的绝对面积阈值，不再统计当前网格面的中位面积。
+
+| Shape | 内部节点组 | 主要几何来源 |
+| --- | --- | --- |
+| Surface | `O Image Surface` | 基础薄片与可调 Thickness |
+| Balloon | `O Image Balloon` | `o_balloon` 鼓起高度 |
+| Depth Balloon | `O Image Depth Balloon` | Balloon profile + 相对基准面的非负深度高度 |
+| Depth Surface | `O Image Depth Surface` | MoGe-2 相机点的完整投影 |
+
+四个内部节点组不再标记为 Modifier，也不再各自执行 Cleanup。原本只在 `O Image Depth Surface` 内的 Smooth 后处理已移到公开节点组；统一节点组的 Smooth 默认值为 `1`；外层 `Smooth Iterations` 默认值为 `0`，只有用户增加迭代次数后才执行平滑。两个 Depth 内部节点组也统一使用 `Reference Depth`，总节点组只暴露一个共用输入。
+
+两个 Depth 形状把相机点 RGB 写入 Packed 浮点 `_depth.exr`，并以隐藏的 `Uniform Scale` 匹配 Image Empty 尺寸。未启用 Refine 时 Reference 使用固定值，Depth Balloon Direction 使用默认轴向；启用 Refine 后，`calibration_valid` 限制在模型有效区域与最终选择的交集，Reference 使用其深度第 95 百分位，Depth Balloon 还拟合局部基准方向。
+
+Depth Balloon 保留图片平面 XY，只使用相机 Z 形成向外高度；Depth Surface 将完整 XYZ 映射到 Cutout 局部轴，因此能表达透视位移。两者都只采样深度 Image 的 RGB，Alpha 仅保存有效性和深度跳变信息。
+
+## 法线空间
+
+MoGe-2 在 Job 阶段输出图片空间的相机轴法线预测；这一步不依赖 Blender 网格。Depth Surface 在导入时将它重排到 Cutout 对象轴并以 Object Space 使用；Surface、Balloon 与 Depth Balloon 则先创建基础网格并完成 Geometry Nodes 求值，再根据成品网格 UV、法线和切线基底烘成 Tangent Space。也就是说，网格前产生的是模型 Prediction，最终法线贴图的空间转换仍发生在网格生成之后。
--- a/docs/internals/operators/debug.md
+++ b/docs/internals/operators/debug.md
@@ -0,0 +1,27 @@
+# Debug Operator
+
+本页对应 `src/anyimage/operators/debug.py`。这些 Operator 为开发者直接验证 DA3、MoGe-2、BEN2 和 Upscale 的 Server 接口，不参与面向用户的对象创建流程。
+
+## 对应文件
+
+```text
+src/anyimage/
+├── operators/debug.py          # 调试请求与结果目录打开
+├── panel.py                    # Debug 面板入口
+└── server/
+    ├── jobs/debug_predictions.py # 四种公开 Debug Job 的共享编排
+    └── outputs/                # 调试产物写出
+```
+
+## 主流程
+
+```mermaid
+flowchart TD
+    Panel["Debug 面板"] --> Operator["选择模型调试 Operator"]
+    Operator --> Request["从 Scene 设置组装请求"]
+    Request --> Job["提交对应 debug Job"]
+    Job --> Output["写出原始预测产物"]
+    Output --> Directory["打开 Job 目录"]
+```
+
+调试入口读取 Scene 中的输入路径、设备与模型参数，直接调用对应 Server Job。任务完成后只打开 Job 目录供检查，不把结果导入为 Blender Image、Mesh 或节点资产。因此它适合验证模型、设备和输出格式，不代表正式功能的用户流程。
--- a/docs/internals/operators/image-tool.md
+++ b/docs/internals/operators/image-tool.md
@@ -0,0 +1,46 @@
+# Image Tool
+
+`operators/image_tool/` 对应工具栏中的 Box、Lasso、Line 与 Polyline。四个 WorkspaceTool 共用一个 `EditImageMask` Operator，把屏幕手势转换为图片 Alpha；只有 Box 与 Lasso 可以用 BEN2 细化选择。
+
+## 对应文件
+
+```text
+operators/image_tool/
+├── __init__.py   # 类型清单与对外导出
+├── box.py        # Box WorkspaceTool
+├── lasso.py      # Lasso WorkspaceTool
+├── line.py       # Line WorkspaceTool
+├── polyline.py   # Polyline WorkspaceTool
+└── edit_mask.py  # 本地编辑与 Refine Job 响应
+```
+
+手势、坐标和像素能力由 `operators/common/` 提供，四点矫正则属于独立的 [`operators/perspective_tool/`](perspective-tool.md)。
+
+## 编辑流程
+
+```mermaid
+flowchart TD
+    Tool["Box / Lasso / Line / Polyline"] --> Gesture["ImageMaskGesture"]
+    Gesture --> Polygon["图片像素 Polygon"]
+    Polygon --> Refine{"Refine Selection?"}
+    Refine -- "否" --> Mask["本地几何 Mask"]
+    Refine -- "是" --> Job["refine-image-mask"]
+    Job --> Mask
+    Mask --> Invert["可选反选"]
+    Invert --> Alpha["源 Alpha × 最终 Mask"]
+    Alpha --> Crop["紧裁切并写回 Empty"]
+```
+
+`EditImageMask` 只接受静态图片。未启用 Refine 时，Polygon 在 Blender 侧直接栅格化；启用后，Operator 准备单图输入并提交 Job，响应阶段读取局部 Alpha 与源图 `bounds`，再映射回完整画布。反选始终在最终 Mask 上执行。
+
+Box 和 Lasso 分别保存自己的 Refine 状态。Line 与 Polyline 强制关闭 Refine，只使用几何 Mask；Line 将有向线扩展为半平面，Polyline 显式闭合用户确认的顶点。
+
+## 手势与预览
+
+四个工具使用相同的白色虚线轮廓和半透明填充。Lasso 按移动距离采点，并在线合并近似共线点；普通凹多边形使用三角剖分，自交路径使用 EVEN_ODD 扫描填充。预览缓存只在轨迹变化时更新。
+
+首次点击通过公共选择逻辑决定是切换 Active Image Empty，还是开始编辑当前图片。这样工具不需要替代 Blender 的普通对象选择。
+
+## 写回结果
+
+最终像素保留源 RGB，只修改 Alpha，再按非零 Alpha 紧裁切。公共写回函数只替换当前 Empty 的 Image，并更新 `empty_display_size` 与 `empty_image_offset`，因此剩余像素继续对齐原图片平面，对象 `matrix_world` 不变。
--- a/docs/internals/operators/index.md
+++ b/docs/internals/operators/index.md
@@ -0,0 +1,18 @@
+# Operator 实现索引
+
+`src/anyimage/operators/` 负责 Blender 侧交互、Job 请求组装和结果导入。内部实现按完整功能包或顶层业务模块拆页；只提供共享能力的 `common/` 不单独成页，其职责统一放在[程序架构](../architecture.md)中说明。
+
+| Operator 路径 | 实现页 | 主要职责 |
+| --- | --- | --- |
+| `operators/__init__.py` | 本页 | 汇总 Blender 类型注册顺序 |
+| `operators/ai_setup.py` | [AI 环境管理](ai-setup.md) | 环境安装、模型下载与缓存释放 |
+| `operators/clipboard_image/` | [Clipboard Image](clipboard-image.md) | 系统剪贴板读取、粘贴与快捷键 |
+| `operators/convert_to_plane/` | [Convert to Plane](convert-to-plane.md) | Mesh Plane 与 Depth Plane 创建 |
+| `operators/cutout_tool/` | [Cutout Tool](cutout-tool.md) | 区域选择、轮廓生成与 Shape 构建 |
+| `operators/debug.py` | [Debug Operator](debug.md) | 模型接口与原始产物验证 |
+| `operators/image_tool/` | [Image Tool](image-tool.md) | Box、Lasso、Line 与 Polyline 编辑 |
+| `operators/perspective_tool/` | [Perspective Tool](perspective-tool.md) | 四点透视框与透视校正 |
+| `operators/remove_background.py` | [Remove Background](remove-background.md) | BEN2 去背与结果替换 |
+| `operators/upscale.py` | [Upscale](upscale.md) | 4× 高清与原图引用维护 |
+
+`operators/__init__.py` 只聚合注册类，不承载独立业务流程。具体类的注册和逆序注销由扩展入口统一管理，整体边界见[程序架构](../architecture.md)。
--- a/docs/internals/operators/perspective-tool.md
+++ b/docs/internals/operators/perspective-tool.md
@@ -0,0 +1,32 @@
+# Perspective Tool
+
+`operators/perspective_tool/` 对应独立的 Image Perspective WorkspaceTool。它采集四个图片角点，把透视四边形重采样为指定宽高比的矩形，不使用 Job Server。
+
+## 对应文件
+
+```text
+operators/perspective_tool/
+├── __init__.py            # 类型清单与对外导出
+└── edit_perspective.py    # 四点交互、预览、Homography 与写回
+```
+
+图片选择、裁切和 Empty 写回复用 `operators/common/` 的基础能力，不与 Image Mask Operator 共享业务状态。
+
+## 矫正流程
+
+```mermaid
+flowchart TD
+    Click["任意顺序的四个角点"] --> Quad["规范为凸四边形"]
+    Quad --> Preview["生成一次 512 × 512 预览"]
+    Preview --> Ratio["鼠标调整目标宽高比"]
+    Ratio --> Size["计算受限输出尺寸"]
+    Size --> Warp["全分辨率 Homography"]
+    Warp --> Crop["按可见 Alpha 紧裁切"]
+    Crop --> Write["Pack 并写回当前 Empty"]
+```
+
+四点输入顺序不决定输出方向；规范化阶段依据源图 X/Y 方向得到不交错的凸四边形。第四点之后只创建一次低分辨率纹理，交互阶段改变 UI 宽高比，确认时才执行全分辨率重采样。
+
+Homography 使用预乘 Alpha 插值，避免透明边缘混入黑色。输出最长边限制为 8192 px，总像素限制为 16,777,216，并按 256 行分块计算，控制中间数组大小。
+
+Perspective 是 deform 工具，不提供 Refine 或反选。结果比例可能不同于原四边形的轴对齐范围，因此 Empty 写回保持中心和覆盖尺度近似一致，而不是假设当前 3D View 相机等于图片拍摄相机。
--- a/docs/internals/operators/remove-background.md
+++ b/docs/internals/operators/remove-background.md
@@ -0,0 +1,31 @@
+# Remove Background
+
+本页对应 `src/anyimage/operators/remove_background.py`。该模块负责从 Image Empty 准备媒体输入、提交 BEN2 去背任务，并用结果 Image 替换当前图像；模型推理留在 Server 进程。
+
+## 对应文件
+
+```text
+src/anyimage/
+├── operators/
+│   ├── remove_background.py       # Blender 入口、任务参数与结果替换
+│   └── common/image.py            # 媒体输入准备与结果 Image 创建
+└── server/
+    ├── jobs/remove_background.py  # 单图与多帧任务编排
+    └── models/ben2.py             # BEN2 前景适配
+```
+
+## 主流程
+
+```mermaid
+flowchart TD
+    Empty["Image Empty"] --> Prepare["准备图片、视频或序列输入"]
+    Prepare --> Operator["RunBackgroundRemoval"]
+    Operator --> Job["remove-background Job"]
+    Job --> Frames["生成 PNG 结果序列"]
+    Frames --> Import["创建结果 Image"]
+    Import --> Replace["替换 Empty.data"]
+```
+
+Packed 图片或内存中修改过的单图会先导出为临时输入；文件图片、视频和序列则沿用可读取的源路径。多帧输入由统一媒体层展开，结果保持连续帧命名，导入后继续沿用源 Image User 的帧起点、偏移与循环设置。
+
+BEN2 推理前使用输入 Alpha 屏蔽透明区域，模型输出的前景 Alpha 再与源 Alpha 合成，RGB 保持为源图内容。响应阶段只替换当前 Empty 的 Image 数据；当旧 Image 没有其他用户和 Fake User 时，旧数据块会被清理并由结果继承名称。
--- a/docs/internals/operators/upscale.md
+++ b/docs/internals/operators/upscale.md
@@ -0,0 +1,36 @@
+# Upscale
+
+本页对应 `src/anyimage/operators/upscale.py`。该模块读取扩展首选项中的模型与全局 AI 输入长边上限，提交 4× 高清任务，并维护高清结果到原始 Image 的引用。
+
+## 对应文件
+
+```text
+src/anyimage/
+├── operators/
+│   ├── upscale.py                 # Blender 入口、任务参数与结果替换
+│   └── common/image.py            # 媒体输入准备与结果 Image 创建
+└── server/
+    ├── jobs/upscale.py            # 单图与多帧任务编排
+    ├── media/resolution.py        # 共用长边限制与等比缩放
+    ├── models/upscale.py          # 输入约束与 Alpha 合并
+    └── models/onnx_upscale.py     # 分块 4× ONNX 推理
+```
+
+## 主流程
+
+```mermaid
+flowchart TD
+    Empty["Image Empty"] --> Source["解析原始 Image"]
+    Source --> Prepare["准备媒体输入"]
+    Prepare --> Job["upscale-image Job"]
+    Job --> Limit["按全局输入长边上限等比缩放"]
+    Limit --> RGB["分块执行 4× RGB 推理"]
+    Limit --> Alpha["独立缩放 Alpha"]
+    RGB --> Merge["合并 RGBA 结果"]
+    Alpha --> Merge
+    Merge --> Replace["导入并替换当前 Image"]
+```
+
+模型以 256×256 分块处理 RGB，并带入相邻上下文以减弱块边界；Alpha 按同一受限输入尺寸单独缩放，最后合并为 RGBA。`max_input_size` 来自全局 **Maximum AI Input Size**，默认 `2048`，只约束送入模型的长边；4× 输出长边因此默认为最多 `8192`。输入尺寸不超过上限时不会发生预缩放。
+
+结果以 `_upscale.png` 结尾，并通过 `Image.anyimage_upscale_source` 保存原图引用。再次对高清结果执行时，Operator 会从原图重新生成，而不是继续放大上一次输出。模型与全局输入上限在每次执行时从 Preferences 读取，再写入可序列化的隐藏属性交给 Job。Provider 资源错误会释放当前 Upscale Session，并提示降低全局输入上限或改用 CPU。
--- a/docs/internals/outputs.md
+++ b/docs/internals/outputs.md
@@ -0,0 +1,72 @@
+# Job 产物
+
+Job 目录是 Server 与 Blender Operator 的交换边界。Server 写入普通图片、JSON 或 NPZ；Blender 只根据 Job 返回值读取需要的文件，并创建最终数据块。
+
+## 产物流向
+
+```mermaid
+flowchart TD
+    Input["媒体输入"] --> Job["Server Job"]
+    Job --> Color["PNG 颜色 / Alpha"]
+    Job --> Field["NPZ 深度场"]
+    Job --> Meta["JSON bounds"]
+    Color --> Import["Blender response()"]
+    Field --> Import
+    Meta --> Import
+    Import --> Data["Image / Mesh / Material"]
+```
+
+## 正式 Job
+
+| Job | 主要文件 | 消费方 |
+| --- | --- | --- |
+| `remove-background` | `image.0001.png` 起 | 替换 Image Empty 的颜色数据 |
+| `upscale-image` | `upscale.0001.png` 起 | 创建 `_upscale.png` Image 并记录原图引用 |
+| `refine-image-mask` | `selection-input.png`、`image.png`、`bounds.json` | Image Box / Lasso 读取 Alpha 与原图坐标 |
+| `prepare-geometry-data`：Depth Plane | `image.0001.*`、`field.npz` | 创建颜色图、深度图、材质和 Plane |
+| `prepare-geometry-data`：Cutout | `image.0001.png`、`selection.png`、`analysis.png`、`bounds.json`，以及按形状生成的 `field.npz` / `normal.png` | Blender 主线程构建局部网格与贴图 |
+
+`prepare-geometry-data` 不输出 Blender 网格。它只准备颜色、选区和模型数组；轮廓提取、约束三角化、Geometry Nodes Modifier 与法线烘焙都在 Blender 响应阶段完成。
+
+## 深度场
+
+`field.npz` 是 Depth Plane、Depth Balloon 与 Depth Surface 共用的模型中间结果：
+
+| 字段 | 含义 |
+| --- | --- |
+| `points` | 每个模型像素的相机空间 XYZ |
+| `depth` | 相机深度 |
+| `intrinsics` | 像素坐标下的 3×3 相机内参 |
+| `valid` | 模型与数值检查后的有效区域 |
+| `calibration_valid` | 用于结果定位或深度基准的区域；Cutout 时与选择相交 |
+| `image_size` | 深度场宽高 |
+| `reference_depth` | 校准区域中的参考深度 |
+
+Server 保留模型空间数据，不提前换算 Blender 单位。Depth Plane 在导入时根据 Image Empty 平面范围和相机内参锚定点场；Cutout 深度形状则计算 `Uniform Scale` 和局部坐标，再把相机点写入 Packed 浮点 Image 供 Geometry Nodes 采样。
+
+## Cutout 三类图片
+
+Cutout 把“显示内容”“几何范围”和“模型分析”分开：
+
+- `image.0001.png` 保存裁切矩形中的源颜色与原 Alpha，用作材质。
+- `selection.png` 保存最终选择 Alpha，用于轮廓与网格。
+- `analysis.png` 只保留选择内的有效 RGBA，供深度或法线模型分析。
+
+`bounds.json` 把裁切矩形映射回源图像素坐标。这样 Server 可以只处理局部数据，Blender 仍能恢复局部平面范围、UV 和世界位置。
+
+## Debug 产物
+
+Debug Job 保留模型适配层的直接输出，不执行正式功能的 Blender 导入：
+
+| Job | 文件 |
+| --- | --- |
+| `debug-da3` | `prediction.npz` |
+| `debug-moge2` | `prediction*.npz` |
+| `debug-ben2` | `foreground*.png` |
+| `debug-upscale` | `prediction*.png` |
+
+这些文件用于验证模型、Device 和适配层。正式 Job 会继续派生选择、Alpha、深度场或可导入图片，因此两者的文件结构有意不同。
+
+## 单图与序列
+
+正式颜色序列从 `image.0001.*` 开始，Upscale 使用独立的 `upscale.0001.png` 前缀。Remove Background 与 Upscale 的动画结果继续引用 Job 目录；单图结果通常在 Blender 导入后 Pack 到 `.blend`。不要清理仍被工程引用的序列目录。
--- a/docs/internals/runtime.md
+++ b/docs/internals/runtime.md
@@ -0,0 +1,86 @@
+# Job Runtime 与 Server
+
+AnyImage 使用 BlendJob 管理独立 Python Environment、Server 进程和任务队列。Blender 侧只配置 Runtime 与提交参数；`server/` 是不依赖 `bpy` 的计算包，可以在独立解释器中导入。
+
+## 对应文件
+
+```text
+src/anyimage/
+├── runtime.py                 # Environment 与 JobRuntime 配置
+└── server/
+    ├── app.py                 # Job 注册和共享资源
+    ├── model_catalog.py       # 模型声明
+    ├── model_download.py      # 下载、校验与镜像回退
+    ├── model_manager.py       # 模型目录与 Session 缓存
+    ├── media/input.py         # 图片、视频和序列输入
+    ├── jobs/                  # app.py 可提交的公开任务
+    ├── selection/             # 选区栅格化与 Cutout 图片准备
+    ├── models/                # 模型适配与 ONNX 推理
+    ├── geometry/              # 深度反投影与法线纹理编码
+    └── outputs/               # Debug Prediction 序列化
+```
+
+## 任务生命周期
+
+```mermaid
+flowchart TD
+    Request["Operator request()"] --> Runtime["JobRuntime"]
+    Runtime --> Queue["单 Worker 队列"]
+    Queue --> Job["app.py 注册的 Job"]
+    Job --> Resource["ModelManager / Media"]
+    Resource --> Directory["jobs/<job-id>/"]
+    Directory --> Response["Operator response()"]
+```
+
+Runtime 在首次任务或显式启动时拉起 Server。任务在队列中串行执行，进度、取消和日志由 BlendJob 提供；AnyImage Job 在阶段边界调用 `context.check_cancelled()`，并把业务产物写入当前 Job 目录。Operator 完成响应后再清理 Blender 侧为 Packed Image 准备的临时输入。
+
+`server/app.py` 是任务清单的唯一入口：
+
+| Job | 主要用途 |
+| --- | --- |
+| `download-model`、`download-required-models` | 准备模型文件 |
+| `remove-background` | BEN2 透明前景 |
+| `upscale-image` | 4× 图片或帧序列 |
+| `refine-image-mask` | 为 Image Box / Lasso 细化选区 |
+| `prepare-geometry-data` | 为 Depth Plane 或 Cutout 准备颜色、选区、深度和法线数据 |
+| `debug-*` | 保存模型适配层的直接输出 |
+
+## 媒体输入
+
+`server/media/input.py` 把单图、视频和图片目录统一为有序帧路径，并用上下文管理器负责临时帧目录的生命周期。它还支持将颜色输入与分析输入分开：例如 Upscale 结果可以作为颜色来源，同时使用它保存的原图引用进行 Depth Plane 分析。帧展开是媒体输入的内部能力，不再暴露没有业务消费者的独立 Job。 `server/media/resolution.py` 提供默认 `2048` 的共用输入长边限制；Upscale 直接限制每帧，`prepare-geometry-data` 则在 Cutout 裁切和分析输入选择完成后限制 Depth / Normal 模型输入。该临时缩放图不参与颜色产物写入。
+
+当前 `prepare-geometry-data` 只接受一帧，因此 Depth Plane 与 Cutout 都是静态图工作流。Remove Background 与 Upscale 通过同一媒体入口处理单图、视频和序列帧。
+
+公开 Job 不与 Operator 一一对应：Depth Plane 和 Cutout 共享 `prepare-geometry-data`，四个 Debug Job 共享 `jobs/debug_predictions.py`。Job 只负责协议和编排；可复用的输入、选区、模型与几何数据能力分别位于 `media/`、`selection/`、`models/` 和 `geometry/`，Job 之间不互相导入实现。
+
+## 模型层
+
+Job 只编排流程，模型适配层把不同推理 API 统一为内存对象：
+
+- DA3 适配为深度、置信度、相机内外参与相机点。
+- MoGe-2 适配为深度、法线、有效区域、相机内参与可选相机点。
+- BEN2 返回带 Alpha 的前景图。
+- Upscale 返回保留源 Alpha 的 4× RGBA 图。
+
+`ModelManager` 管理下载目录和 ONNX Session。缓存按 BEN2、几何模型和 Upscale 三个族分开；每个族只保留最近一次使用的模型与 Device，切换同族模型时释放旧 Session。这样连续任务可以复用模型，同时避免同一类模型重复占用资源。
+
+## Environment 与 Storage Root
+
+`runtime.py` 声明 Python 3.12 环境和固定版本的 NumPy、Pillow、PyAV、trimesh、Hugging Face Hub 与 ONNX Runtime。Windows 安装 DirectML 版本，其他平台安装标准 ONNX Runtime。首次安装后依次下载默认 MoGe-2、BEN2 和 Real-ESRGAN WDN 模型。
+
+Storage Root 默认是 `~/.anyimage`：
+
+```text
+~/.anyimage/
+├── .venv/           # 独立 Environment
+├── models/          # 模型目录
+├── jobs/            # Job 产物与 job.log
+├── environment.json
+├── manifest.json
+├── install.log
+└── server.log
+```
+
+Storage Root 由扩展偏好设置提供给 Runtime。切换路径等同于切换整套 Environment、模型和任务数据，不会自动迁移旧目录。
+
+各 Job 的稳定产物见 [Job 产物](outputs.md)。