Add tools and tests for AnyImage model management and documentation

- Implement sync_models.py for preparing and uploading ONNX artifacts.
- Create build_node.py for building and validating Blender scripts.
- Add docs.py for building and previewing documentation with Mike or MkDocs.
- Introduce model_exports.py for exporting PyTorch models to ONNX format.
- Develop pack.py for packaging the project with dependencies for different platforms.
- Add test_sync_models.py to validate sync_models functionality.
- Add test_tool_commands.py to ensure repository tools have correct command scripts.
- Initialize tools package with __init__.py.

docs/internals/architecture.md

@@ -1,6 +1,6 @@
 # 程序架构
 
-AnyImage 由 Blender 交互层、BlendJob Runtime 和独立 Job Server 三部分组成。这个分层让 Blender Python 不需要加载 ONNX Runtime、Pillow 或模型权重，同时保证所有 Blender 数据仍在主线程创建和修改。
+AnyImage 由 Blender 交互层、BlendJob Runtime 和独立 Job Server 三部分组成。AI 依赖运行在 Server Environment 中，Blender 数据在主线程创建和修改。
 
 ## 对应文件
 
@@ -12,17 +12,18 @@ src/anyimage/
 ├── preferences.py    # Storage Root、Device 与功能默认值
 ├── properties.py     # Scene 状态、模型状态与动态枚举
 ├── runtime.py        # Environment 和 JobRuntime
+├── common/           # Blender 侧共享原子能力
 ├── operators/        # Blender 侧业务入口
 └── server/           # 独立计算端
 ```
 
-## 职责边界
+## 职责
 
-| 层次 | 负责 | 不负责 |
-| --- | --- | --- |
-| Blender 交互层 | UI、手势、RNA 状态、输入准备、结果导入、Undo | 在 Blender 进程加载 AI 依赖 |
-| BlendJob Runtime | Environment、Server 生命周期、队列、进度、取消、Job 目录 | AnyImage 的图像与几何业务 |
-| Job Server | 媒体解码、ONNX 推理、数组派生、文件输出 | 创建 Blender 对象或访问 `bpy` |
+| 层次 | 职责 |
+| --- | --- |
+| Blender 交互层 | UI、手势、RNA 状态、输入准备、结果导入和 Undo |
+| BlendJob Runtime | Environment、Server 生命周期、队列、进度、取消和 Job 目录 |
+| Job Server | 媒体解码、ONNX 推理、数组派生和文件输出 |
 
 Operator 向 Server 发送普通字典。Server 返回文件名和 Job 目录；Operator 的 `response()` 再读取这些文件，并在 Blender 主线程中创建 Image、Mesh、Material 和 Geometry Nodes Modifier。
 
@@ -58,12 +59,8 @@ sequenceDiagram
     Op->>Op: 导入数据并提交 Undo
 ```
 
-这条边界也决定了模块依赖方向：`server/` 不导入 `bpy` 或 `operators/`；Blender 侧可以读取 Server 产物，但不会复用 Server 中的 Blender 无关算法来创建 RNA 数据。
+`server/` 保持纯 Python 实现；Operator 在 Blender 主线程读取产物并创建 RNA 数据。
 
-## 共享能力 { #shared-capabilities }
+## 共享能力
 
-`operators/common/` 只保存多个生产功能真实复用的稳定原子能力；完整工作流、功能参数和专用算法留在所属模块。公共层不保留旧路径转发函数，也不为了测试或资产工具建立入口。
-
-全部可由功能模块调用的函数见[Common 公共函数](common.md)。该索引只列 `common/` 外部的生产调用，不重复列出公共模块内部辅助函数；创建新功能前先核对该页，避免重新实现 Image 引用分流、像素方向、Job 输入生命周期、数据块命名、节点资产加载和对象激活逻辑。
-
-新增公共函数前应确认至少有两个真实消费者，或它是两个公共流程共同依赖的原子能力。只有单一功能使用的逻辑应留在所属模块；删除或移动能力时同步清理注册、测试、工具脚本和文档，不保留兼容胶水。
+`common/` 提供 Blender 侧复用的 Image 数据、Region、Depth、Object 和 AI Job 原子能力。公开函数见[Common 公共函数](common.md)。

docs/internals/common.md

@@ -1,12 +1,10 @@
 # Common 公共函数
 
-`src/anyimage/operators/common/` 集中已经被多个功能复用的 Blender 侧原子能力，目的是让开发新功能时能够先查找并复用现有实现，避免重复造轮子。
-
-本页只列功能模块直接调用的公共函数，不列 `common/` 内部辅助函数、测试或资产工具专用函数，也不列公共类型。
+`src/anyimage/common/` 提供多个功能复用的 Blender 侧原子能力。
 
 ## Image 数据块
 
-`image_data.py` 处理 Blender `Image` 数据块及其在 Image Empty 上的使用方式，包括像素读取、动画帧、Job 输入、结果 Image 创建和 Empty 引用替换。它不处理 Viewport 手势或 Region 算法。
+`image_data.py` 处理 Blender `Image` 数据块及其在 Image Empty 上的使用方式，包括像素读取、动画帧、Job 输入、结果 Image 创建和 Empty 引用替换。
 
 | 函数 | 职责 |
 | --- | --- |
@@ -30,16 +28,14 @@
 | `image_data.replace_empty_image()` | 执行 Image Empty 结果替换、共享引用分流、旧数据清理、帧设置继承和可选画布对齐。 |
 | `image_data.image_empty_bounds()` | 计算 Image Empty 在对象局部坐标中的实际显示边界。 |
 
-`load_*_result_image()` 和 `create_pixel_result_image()` 只创建结果 Image；`replace_empty_image()` 负责把结果提交给当前 Empty。两者分别表达“创建产物”和“替换引用”。
-
 ## Image Region 与视图交互
 
 这组公共能力使用固定术语：
 
 - Region 是用户在图片空间圈定的业务范围；`RegionPath` 保存路径点、反选状态和填充规则。
 - `RegionMask` 是 Region 的栅格化结果，只包含局部像素权重 `values` 和源图 `bounds`。
-- Mask 只表示二维像素权重或 Alpha 运算，不作为手势、协议或业务范围的别名。
-- Selection 只用于 Blender 对象选择；图片业务范围统一称为 Region，细化动作称为 Fit to Foreground。
+- Mask 表示二维像素权重或 Alpha 运算。
+- Selection 表示 Blender 对象选择；图片业务范围称为 Region，细化动作称为 Fit to Foreground。
 
 `image_interaction.py` 处理 3D Viewport 中的点击、坐标投影、`ImageRegionGesture`、工具设置和预览绘制；`image_region.py` 负责图片空间 Region 的值、栅格化和 Alpha 裁切。前者负责用户如何圈定 Region，后者负责 Region 如何变成 Mask。
 
@@ -71,7 +67,7 @@
 
 ## Depth 产物
 
-`depth_data.py` 负责 Blender 侧共享的 Depth 文件加载和相机尺度换算；Server 已经写好 EXR，Blender 不再从点场创建第二张 Depth Image。
+`depth_data.py` 负责 Blender 侧共享的 Depth 文件加载和相机尺度换算，直接加载 Server 写出的 EXR。
 
 | 函数 | 职责 |
 | --- | --- |
@@ -80,23 +76,22 @@
 | `depth_data.camera_depth_values()` | 从已加载 Depth Image 读取用于本地标定的 Z 与有效区。 |
 | `depth_data.depth_uniform_scale()` | 根据相机内参、参考深度和 Image Empty 范围计算统一尺度。 |
 
-## Mesh 结果构建
+## Object 构建
 
-`mesh_result.py` 集中 Convert to Plane 与 Cutout 共同使用的结果构建能力：创建材质、加载节点资产、设置修改器输入，并完成结果对象替换。
+`object.py` 集中 Convert to Plane 与 Cutout 共用的材质、Modifier 和结果 Object 构建能力；`node.py` 负责加载节点资产。
 
 | 函数 | 职责 |
 | --- | --- |
-| `mesh_result.create_image_material()` | 从 Image Empty 创建包含颜色、位移、Normal Map、Alpha 和动画设置的完整材质。 |
-| `mesh_result.load_asset_node_group()` | 从随扩展分发的 Blend 资产加载指定 Node Group。 |
-| `mesh_result.modifier_input_identifier()` | 按接口名称解析 Geometry Nodes Modifier 输入 Identifier。 |
-| `mesh_result.set_modifier_input()` | 跨受支持 Blender RNA 形式设置 Modifier 输入。 |
-| `mesh_result.finalize_object_result()` | 激活结果对象，并按需替换或保留源 Empty。 |
+| `node.load_node_group()` | 从随扩展分发的 Blend 资产加载指定 Node Group。 |
+| `object.create_image_material()` | 从 Image Empty 创建包含颜色、位移、Normal Map、Alpha 和动画设置的完整材质。 |
+| `object.modifier_input_identifier()` | 按接口名称解析 Geometry Nodes Modifier 输入 Identifier。 |
+| `object.set_modifier_input()` | 跨受支持 Blender RNA 形式设置 Modifier 输入。 |
+| `object.finalize_object_result()` | 激活结果对象，并按需替换或保留源 Empty。 |
 
-节点资产构建和验证专用函数位于 `tools/node_assets/`，不属于运行时公共能力。
 
 ## AI 任务准备
 
-`ai_job.py` 处理多个 AI 功能共同使用的任务准备，包括输入路径校验、Environment 与模型检查、Device 选择和模型请求参数组装。DA3 参数只供 Debug Operator 使用；正式几何流程只组装 MoGe-2 参数。它不包含业务 Operator、结果导入或 Undo 操作。
+`ai_job.py` 处理多个 AI 功能共同使用的任务准备，包括输入路径校验、Environment 与模型检查、Device 选择和模型请求参数组装。
 
 | 函数 | 职责 |
 | --- | --- |

docs/internals/development.md

@@ -1,6 +1,6 @@
 # 开发与发布
 
-AnyImage 的仓库环境用于测试 Blender 侧代码、Server 纯 Python 模块、Manifest 和打包逻辑。AI Runtime 使用另一套 Python 3.12 Environment，不应与仓库开发环境混为一谈。
+AnyImage 的仓库环境用于测试 Blender 侧代码、Server 纯 Python 模块、Manifest 和打包逻辑。AI Runtime 使用独立的 Python 3.12 Environment。
 
 ## 对应文件
 
@@ -9,11 +9,14 @@ AnyImage 的仓库环境用于测试 Blender 侧代码、Server 纯 Python 模
 ├── pyproject.toml
 ├── uv.lock
 ├── .python-version
-├── pack.py
-├── sync_models.py
+├── tools/
+│   ├── pack.py
+│   ├── model_exports.py
+│   ├── sync_models.py
+│   ├── build_node.py
+│   └── node_assets/
 ├── src/anyimage/blender_manifest.toml
 ├── tests/
-├── tools/node_assets/
 └── .github/workflows/
     ├── test.yml
     ├── build.yml
@@ -40,10 +43,10 @@ uv run pytest tests/test_addon.py tests/test_manifest.py tests/test_pack.py -v
 ## 扩展打包
 
 ```bash
-uv run python pack.py
+uv run pack
 ```
 
-`pack.py` 为 `windows-x64`、`macos-arm64` 和 `linux-x64` 分别解析依赖 wheel，生成平台专属 Manifest，再把 `src/anyimage/` 与 wheel 写入 `dist/`：
+`tools/pack.py` 为 `windows-x64`、`macos-arm64` 和 `linux-x64` 分别解析依赖 wheel，生成平台专属 Manifest，再把 `src/anyimage/` 与 wheel 写入 `dist/`：
 
 ```text
 dist/
@@ -54,21 +57,29 @@ dist/
 
 本地 `src/anyimage/wheels/` 是 wheel 解析的优先来源，用于携带尚未发布的 BlendJob 构建。依赖、wheel 或 Manifest 变化后，需要同时检查 `pyproject.toml`、`uv.lock`、`blender_manifest.toml` 和打包测试；本地 wheel 内容变化后运行 `uv lock --refresh`。
 
+## 模型发布
+
+```bash
+uv run sync_models
+```
+
+`tools/sync_models.py` 从公开原址下载已有 ONNX；Real-ESRGAN General WDN x4v3 与 SAFMN Real x4 则从官方 PyTorch 权重调用 `tools/model_exports.py` 构建。所有制品通过固定大小、SHA-256、ONNX Checker 和 PyTorch/ONNX Runtime 数值对比后，逐文件上传到 R2。添加 `--prepare-only` 可仅准备和验证制品。
+
 ## 文档
 
 ```bash
-uv run --only-group docs mkdocs serve
-uv run --only-group docs mkdocs build --strict
+uv run mkdocs serve
+uv run mkdocs build --strict
 ```
 
-站点导航由 `mkdocs.yml` 显式维护，因此移动页面时必须同时更新导航和相对链接。Mike 仍可用于本地版本化发布；CI 则直接构建严格模式站点并部署到 Cloudflare Worker。
+站点导航由 `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"]
+    Tag["push v* tag"] --> Release["测试 → tools/pack.py → Release ZIP"]
     Docs["main 上文档变更"] --> Site["mkdocs --strict → Cloudflare"]
 ```
 
@@ -76,6 +87,6 @@ flowchart TD
 
 ## 许可证
 
-AnyImage Extension 代码采用 GPL-3.0-or-later，完整文本见仓库 `LICENSE`。模型权重保持各自上游许可证；模型目录声明下载来源、文件校验和许可信息，技术文档不复制可能变化的制品清单。
+AnyImage Extension 代码采用 GPL-3.0-or-later，完整文本见仓库 `LICENSE`。模型权重保持各自上游许可证；模型目录声明下载来源、文件校验和许可信息。
 
 Geometry Nodes 资产必须由 Blender 构建和验证，见[节点资产](node-assets.md)。

docs/internals/index.md

@@ -1,6 +1,6 @@
 # 内部实现总览
 
-AnyImage 的实现围绕一条清晰边界展开：Blender 进程负责交互与数据创建，独立 Job Server 负责模型推理和文件处理。两侧通过 BlendJob 传递可序列化参数与 Job 目录中的产物，不跨进程传递 Blender RNA 数据。
+Blender 进程负责交互与数据创建，独立 Job Server 负责模型推理和文件处理。两侧通过 BlendJob 传递可序列化参数与 Job 目录中的产物。
 
 ```mermaid
 flowchart TD
@@ -16,8 +16,6 @@ flowchart TD
 
 ## 项目主干
 
-总览只展示稳定边界；各功能包的具体文件在对应实现页中展开。
-
 ```text
 .
 ├── src/anyimage/
@@ -26,24 +24,21 @@ flowchart TD
 │   ├── preferences.py       # 扩展级配置
 │   ├── properties.py        # Scene 状态与模型枚举
 │   ├── runtime.py           # BlendJob Runtime 配置
+│   ├── common/              # Blender 侧共享原子能力
 │   ├── operators/           # 交互、任务提交与结果导入
 │   ├── server/              # 无 Blender 依赖的计算端
 │   ├── assets/              # 随扩展分发的节点资产
 │   └── wheels/              # 随扩展分发的 BlendJob wheel
-├── tools/                   # Blender 资产构建与验证
-├── tests/                   # Python 自动化测试
-├── pack.py                  # 多平台扩展打包
-└── sync_models.py           # ONNX 模型同步
+├── tools/                   # 打包、模型同步与 Blender 节点资产
+└── tests/                   # Python 自动化测试
 ```
 
 ## 文档分层
 
 - [程序架构](architecture.md)：注册、配置、线程和模块边界。
-- [Common 公共函数](common.md)：仅列生产功能从 `operators/common/` 外部调用的函数。
+- [Common 公共函数](common.md)：仅列生产功能从 `common/` 外部调用的函数。
 - [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 的构建、加载与验证。
-
-内部实现文档描述模块之间的职责和主要数据流。[Common 公共函数](common.md)按真实外部调用列出开发新功能时应优先复用的稳定入口；函数级分支、参数校验与异常处理仍以源码和测试为准。

docs/internals/node-assets.md

@@ -1,60 +1,52 @@
 # 节点资产
 
-AnyImage 将生产功能使用的可复用 Geometry Nodes 和 Shader 节点组统一构建到 `O_AnyImage.blend`，运行时只按名称加载，不动态创建节点组。
+生产节点组由脚本构建到 `src/anyimage/assets/O_AnyImage.blend`；运行时只加载，不创建节点组。
 
-## 对应文件
+## 构建
 
-```text
-src/anyimage/
-├── assets/O_AnyImage.blend
-├── operators/common/mesh_result.py         # 运行时资产加载与 Modifier 输入
-└── operators/convert_to_plane/nodes.py     # Plane 节点资产名称与加载入口
-
-tools/node_assets/
-├── build.py                # 统一构建入口
-├── node_graph.py           # Cutout 资产构建专用节点图函数
-├── build_mesh_plane.py
-├── build_depth_plane.py
-├── build_material_layers.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/mesh_result.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
+uv run build_node
 ```
 
-`build.py` 从空 Factory 文件开始，依次构建 `O Mesh Plane`、`O Image Depth Plane`、`O Image Layer`、`O Image Depth Layer`、`O Shadeless`、四个 Cutout 内部节点组与公开修改器节点组 `O Image Cutout`，再保存唯一资产文件。`O Image Cutout` 用 Menu Switch 包装四个内部组；运行时 Loader 只加载这个稳定入口，Blender 4.5 根据 Shape 菜单依赖只显示当前分支实际使用的输入。
+脚本依次构建资产、运行三项 Blender 验证和完整测试，任一步失败即退出。
 
-## 验证范围
+脚本按 `--blender`、环境变量 `BLENDER_BIN`、项目 `.env`、`PATH` 的顺序查找 Blender。无法自动找到时，在项目根目录的 `.env` 中配置：
 
-基础验证检查完整发布资产清单、节点树类型、Modifier 标记、接口顺序和 Fake User。专项验证继续检查：
+```dotenv
+BLENDER_BIN="/absolute/path/to/blender"
+```
 
-- Mesh Plane 的接口、细分、Thickness 和几何求值；
-- `O Image Cutout` 的公开接口、Shape 菜单和四个内部组的依赖关系；
-- 节点不重叠、主要连线保持从左向右；
-- 局部 Group Input 未使用输出隐藏；
-- Cleanup 只在四条分支之前执行，Smooth 只在菜单选择之后执行；
-- Repeat Zone 数量和四种 Shape 的关键几何求值稳定。
+`.env` 已被 Git 忽略。临时指定路径或跳过 Python 测试：
 
-节点资产接口变化时，应运行全部四个 Blender 入口和完整 Python 测试。只修改 Python、Markdown 或打包逻辑时无需重建 `.blend`。Blender 自动生成的 `.blend1` 等备份不属于发布资产。
+```bash
+uv run build_node --blender "/path/to/blender"
+uv run build_node --skip-tests
+```
+
+## 资产清单
+
+| 节点组 | 构建模块 |
+| --- | --- |
+| `O Mesh Plane` | `build_mesh_plane.py` |
+| `O Image Depth Plane` | `build_depth_plane.py` |
+| `O Image Layer`、`O Image Depth Layer` | `build_material_layers.py` |
+| `O Shadeless` | `build_shadeless.py` |
+| `O Image Cutout` | `build_cutout.py` |
+| `O Image Surface`、`O Image Balloon` | `build_cutout.py` |
+| `O Image Depth Balloon`、`O Image Depth Surface` | `build_cutout.py` |
+
+构建从空 Factory 文件生成全部节点组，关闭 `.blend1` 备份，并覆盖唯一发布资产。
+
+## 修改节点组
+
+1. 修改 `tools/node_assets/build_*.py`；
+2. 更新对应验证；
+3. 运行一键构建脚本；
+4. 搜索并清理旧名称、接口和路径；
+5. 检查 `.blend`、代码、测试和文档差异。
+
+接口、节点、连线、默认值或布局变化时必须重建。只修改运行时 Python、Markdown 或打包逻辑时无需重建。
+
+`O_AnyImage.blend1` 等备份不应提交或打包。

docs/internals/operators/ai-setup.md

@@ -23,11 +23,11 @@ flowchart TD
 
 入口位于 `src/anyimage/operators/ai_setup.py`。`SetupAIEnvironment` 通过 `properties.py` 中的 `ai_status()` 读取环境和模型状态，并根据结果结束、安装环境或调用 `DownloadRequiredModels`。对话框同时显示预计下载量和缺失模型名称。
 
-`runtime.py` 提供当前 Environment 与 Server 状态；Server 正忙时不会启动新的安装流程。`OpenAIEnvironmentSettings` 也在 `ai_setup.py` 中，它只负责打开 AnyImage 的扩展首选项。
+`runtime.py` 提供当前 Environment 与 Server 状态；Server 正忙时不会启动新的安装流程。`OpenAIEnvironmentSettings` 打开 AnyImage 的扩展首选项。
 
 ### 安装独立环境
 
-环境尚未就绪时，`SetupAIEnvironment` 调用 Runtime 注册的安装 Operator。普通源与中国镜像使用同一条安装流程，`use_mirror` 只决定 uv、Python 和 Python 包的下载源，不改变模型来源。
+环境尚未就绪时，`SetupAIEnvironment` 调用 Runtime 注册的安装 Operator。`use_mirror` 决定 uv、Python 和 Python 包的下载源，模型使用模型目录中声明的来源。
 
 安装完成后继续进入模型下载，不在 Blender Python 中加载 ONNX Runtime 或模型依赖。
 

docs/internals/operators/clipboard-image.md

@@ -16,7 +16,7 @@ flowchart TD
     Target --> Paint["Brush Texture"]
 ```
 
-整条流程运行在 Blender 进程中，不使用 Job Server。快捷键会先尊重 Blender 自己的 Copy/Paste；只有系统剪贴板出现新的图片内容时，AnyImage 才接管粘贴。
+快捷键优先处理 Blender 自己的 Copy/Paste；系统剪贴板出现新的图片内容时，AnyImage 接管粘贴。
 
 ## 节点说明
 
@@ -28,7 +28,7 @@ flowchart TD
 
 ### 读取系统图片
 
-`clipboard.py` 负责平台差异。Windows 读取 DIB 或 DIBV5 并补成 BMP；macOS 和 Linux 调用系统提供的图片导出命令。无论来源平台，输出都收敛为图片字节和扩展名，后续步骤不再判断操作系统。
+`clipboard.py` 负责平台差异。Windows 读取 DIB 或 DIBV5 并补成 BMP；macOS 和 Linux 调用系统提供的图片导出命令。各平台输出统一为图片字节和扩展名，再交给后续步骤。
 
 ### 创建或复用 Packed Image
 
@@ -38,4 +38,4 @@ flowchart TD
 
 落点仍在 `actions.py` 中完成：3D View 创建 Reference 或 Plane，Node Editor 创建与当前节点树匹配的 Image 节点，绘制模式把 Image 配置为当前画笔的 Texture。鼠标位置和视图位置也在这里换算。
 
-Plane 路径调用 `convert_to_plane/mesh_plane.py` 创建基础网格，并使用 `convert_to_plane/nodes.py` 提供的 `O Mesh Plane` 节点组。`clipboard_image/__init__.py` 只负责入口和快捷键，具体 Blender 数据始终由 `actions.py` 创建。
+Plane 路径调用 `convert_to_plane/mesh_plane.py` 创建基础网格，并从节点资产加载 `O Mesh Plane`。`actions.py` 创建 Blender 数据。

docs/internals/operators/convert-to-plane.md

@@ -15,7 +15,7 @@ flowchart TD
     Import --> Depth["创建 Depth Plane Object"]
 ```
 
-两条路径共用 Image Empty 的显示范围、颜色材质和基础 Plane。Depth Plane 多出一次 Server Job，并由节点根据相机元数据把 Z Depth 转换为局部位移。正式流程只使用 MoGe-2；DA3 只保留 Debug 入口。
+两条路径共用 Image Empty 的显示范围、颜色材质和基础 Plane。Depth Plane 通过一次 MoGe-2 Server Job 生成 Z Depth，再由节点根据相机元数据转换为局部位移。
 
 ## 节点说明
 

docs/internals/operators/cutout-tool.md

@@ -21,11 +21,7 @@ flowchart TD
     Ready --> Build --> Create
 ```
 
-Surface 与 Balloon 可以完全在 Blender 中完成；启用 Fit to Foreground、生成 Depth Shape 或 Normal Map 时，中间会经过一次 Server Job。
-
-两条路径的区别只在中间是否需要 Server 产物。回到 Blender 后，它们都使用最终的 `RegionMask` 构建同一种 `BaseShape`，再由同一入口创建对象。Server 不创建 Blender Mesh，也不访问 `bpy`。
-
-下文中的 Blender 侧文件相对 `src/anyimage/operators/cutout_tool/`，Server 侧文件相对 `src/anyimage/server/`。
+Surface 与 Balloon 直接使用 `RegionMask` 构建 `BaseShape`；Fit to Foreground、Depth Shape 和 Normal Map 先通过 Server Job 生成所需产物。
 
 ## 节点说明
 
@@ -33,13 +29,13 @@ Surface 与 Balloon 可以完全在 Blender 中完成；启用 Fit to Foreground
 
 Cutout 工具由 `__init__.py` 注册，交互从 `main.py` 中的 `SelectCutoutRegion` 开始。它接收 Lasso 或双击整图手势，把图片空间路径保存为 `RegionPath`，然后调用 `interaction.py` 打开 Shape 饼菜单。
 
-`interaction.py` 在这里完成 Region 有效性检查、读取三个工具选项，并根据 **Mesh Sampling Spacing** 换算期望网格分辨率；它不定义 Operator。菜单中的 Surface、Balloon、Depth Balloon 和 Depth Surface，以及它们对应的节点分支索引，统一来自 `shape.py`。
+`interaction.py` 完成 Region 有效性检查、读取三个工具选项，并根据 **Mesh Sampling Spacing** 换算期望网格分辨率。菜单中的 Surface、Balloon、Depth Balloon 和 Depth Surface，以及它们对应的节点分支索引，统一来自 `shape.py`。
 
 ### 栅格化 Region
 
-用户选定 Shape 后，`main.py` 中的 `CutoutRegionToShape` 接过主线。它使用 `operators/common/image_region.py` 把 `RegionPath` 栅格化为 `RegionMask`：`values` 保存局部像素权重，`bounds` 保存它在源图中的位置。套索外和源图透明区域不会进入最终 Region。
+用户选定 Shape 后，`main.py` 中的 `CutoutRegionToShape` 接过主线。它使用 `common/image_region.py` 把 `RegionPath` 栅格化为 `RegionMask`：`values` 保存局部像素权重，`bounds` 保存它在源图中的位置。套索外和源图透明区域不会进入最终 Region。
 
-此时也会应用 **Maximum Cutout Mesh Resolution**。它限制裁切区域的最长采样边，对四种 Shape 一视同仁，与是否使用 AI 无关。
+此时也会应用 **Maximum Cutout Mesh Resolution**，统一限制四种 Shape 裁切区域的最长采样边。
 
 ### 需要后台生成数据？
 
@@ -49,23 +45,23 @@ Cutout 工具由 `__init__.py` 注册，交互从 `main.py` 中的 `SelectCutout
 - 选择 Depth Balloon 或 Depth Surface；
 - 开启 **Generate Normal Map**。
 
-没有开启两个 AI 选项的 Surface 和 Balloon 会直接沿用本地 `RegionMask`。
+Surface 和 Balloon 的本地路径直接沿用 `RegionMask`。
 
 ### 执行 Fit to Foreground，生成 Depth / Normal 产物
 
-`main.py` 把请求提交给 `server/jobs/cutout.py`。这个 Job 只生成本次 Shape 实际需要的产物：
+`main.py` 把请求提交给 `server/jobs/cutout.py`，生成本次 Shape 需要的产物：
 
 - **Fit to Foreground** 调用 `server/region/refine_region.py`，写出收紧后的 `region.png` 和 `region_bounds.json`；
 - 需要 Vector Depth 时写出相机空间 XYZ 组成的 `vector-depth.exr`，需要 Z Depth 时写出 `z-depth.exr`，两者都配套 `depth.json`；
 - **Generate Normal Map** 根据既定空间写出 `tangent-normal.png` 或 `object-normal.png`。
 
-Depth 与 Normal Map 同时需要时，共享同一次 MoGe-2 Prediction。Prediction 只存在于 Server 内存，Job 目录只保留 Blender 可直接加载的图片和 JSON。Depth Surface 的 Normal Map 编码为 Cutout 对象空间，其正面是对象局部 `-X`；其余 Shape 使用 Tangent Space。Normal Space 由 `main.normal_mode_for_shape()` 根据 Shape 决定，不是单独的用户选项。
+Depth 与 Normal Map 共享同一次 MoGe-2 Prediction。Depth Surface 的 Normal Map 编码为 Cutout 对象空间，其正面是对象局部 `-X`；其余 Shape 使用 Tangent Space。`main.normal_mode_for_shape()` 根据 Shape 确定 Normal Space。
 
-**Maximum AI Input Size** 只限制 BEN2 和 MoGe-2 看到的分析图长边。它不改变网格密度，也不降低最终颜色图分辨率。DA3 不进入这条正式路径，只保留 Debug 功能。
+**Maximum AI Input Size** 约束 BEN2 和 MoGe-2 的分析图长边；网格密度使用 **Maximum Cutout Mesh Resolution**，最终颜色图使用源图裁切分辨率。
 
 ### 构建 BaseShape
 
-Job 完成后，`main.py` 在 Blender 主线程读取可选的 RegionMask，直接加载并 Pack Depth 与 Normal 图片；本地路径则直接使用已有数据。两者最终都进入 `main.create_cutout_shape()`，再调用 `geometry.py` 中的 `build_base_shape()`：
+Job 完成后，`main.py` 在 Blender 主线程读取可选的 RegionMask，加载并 Pack Depth 与 Normal 图片。`main.create_cutout_shape()` 调用 `geometry.py` 中的 `build_base_shape()`：
 
 1. 从最终 `RegionMask` 提取外轮廓和孔洞；
 2. 按 Mesh Sampling Spacing 生成轮廓与内部采样点；
@@ -77,7 +73,7 @@ Job 完成后，`main.py` 在 Blender 主线程读取可选的 RegionMask，直
 
 ### 创建 Blender 对象
 
-`main.create_cutout_shape()` 把 `BaseShape` 和可选产物交给 `object.py` 的 `create_shape_object()`。这里创建裁切后的 Color Image、Material、Mesh Object，并挂上统一的 `O Image Cutout` Modifier。材质通过 `operators/common/mesh_result.py` 创建，Cutout 使用 `1.2` 的 IOR。Color Image 是按最终 Region 包围矩形裁切的源图 RGBA；RegionMask 不写入颜色图 Alpha，源图原有 Alpha 会原样保留。
+`main.create_cutout_shape()` 把 `BaseShape` 和可选产物交给 `object.py` 的 `create_shape_object()`。这里创建裁切后的 Color Image、Material、Mesh Object，并挂上统一的 `O Image Cutout` Modifier。材质通过 `common/object.py` 创建，Cutout 使用 `1.2` 的 IOR。Color Image 按最终 Region 包围矩形裁切源图并保留 RGBA。
 
 | Shape | Modifier 如何形成结果 | 必需后台产物 |
 | --- | --- | --- |
@@ -88,6 +84,6 @@ Job 完成后，`main.py` 在 Blender 主线程读取可选的 RegionMask，直
 
 Depth Shape 的 Base Plane Depth，以及 Depth Balloon 的 Direction，都由 `object.py` 调用 `geometry.py` 的标定函数，根据最终 Region Alpha 计算。透明像素达到 `5%` 时使用有效 Region 自适应标定，否则使用稳定的固定基准。
 
-Normal Map 是材质细节，不改变上述四种 Shape 的几何分类。关闭时材质使用几何法线；开启时，`object.py` 把生成的图片和已经确定的 Normal Space 交给材质节点。最后 `main.py` 提交 Undo，整条 Cutout 流程结束。
+Normal Map 关闭时材质使用几何法线；开启时，`object.py` 把生成的图片和已经确定的 Normal Space 交给材质节点。最后 `main.py` 提交 Undo，整条 Cutout 流程结束。
 
 Balloon 与 Depth Balloon 的材质会创建 Geometry Attribute 节点，把 `o_balloon` 的 Float 输出直接连接到 `O Image Layer` 已有的 **Normal Scale**；Surface 与 Depth Surface 不建立这条连接。

docs/internals/operators/debug.md

@@ -1,6 +1,6 @@
 # Debug Operator
 
-Debug Operator 从面板中的模型参数发起一次原始推理，把结果文件留在 Job 目录中供开发者检查，不创建用户场景对象。
+Debug Operator 从面板中的模型参数发起一次原始推理，把结果文件写入 Job 目录并打开目录供开发者检查。
 
 ## 执行过程
 
@@ -13,7 +13,7 @@ flowchart TD
     Output --> Directory["打开 Job 目录"]
 ```
 
-DA3、MoGe-2、BEN2 和 Upscale 都走这条调试路径。它验证模型、设备、请求参数和输出格式，但不代表正式功能的对象创建流程。
+DA3、MoGe-2、BEN2 和 Upscale 都走这条调试路径，用于验证模型、设备、请求参数和输出格式。
 
 ## 节点说明
 
@@ -25,8 +25,8 @@ DA3、MoGe-2、BEN2 和 Upscale 都走这条调试路径。它验证模型、设
 
 `debug.py` 分别提交 `debug-da3`、`debug-moge2`、`debug-ben2` 和 `debug-upscale` Job。Server 侧由 `server/jobs/debug_predictions.py` 接收请求，再调用相应模型适配器。
 
-DA3 和 MoGe-2 的可视化与数组输出由 `server/outputs/debug_da3.py`、`server/outputs/debug_moge2.py` 写出；BEN2 与 Upscale 保留模型返回的图片结果。这里允许 DA3 继续存在，但它不会被 Plane、Depth Plane 或 Cutout 的正式 Operator 调用。
+DA3 和 MoGe-2 的可视化与数组输出由 `server/outputs/debug_da3.py`、`server/outputs/debug_moge2.py` 写出；BEN2 与 Upscale 保存模型返回的图片结果。
 
 ### 查看结果
 
-任务完成后，`debug.py` 的 `_open_job_directory()` 调用 Blender 的路径打开操作，直接显示该 Job 的目录。响应阶段不导入 Image，不创建 Mesh、Material 或 Modifier，也不修改当前场景。
+任务完成后，`debug.py` 的 `_open_job_directory()` 调用 Blender 的路径打开操作，直接显示该 Job 的目录。

docs/internals/operators/image-tool.md

@@ -24,13 +24,13 @@ flowchart TD
 
 `operators/image_tool/__init__.py` 汇总注册类型；`box.py`、`lasso.py`、`line.py` 和 `polyline.py` 分别定义四个 WorkspaceTool。它们都把操作交给 `edit_mask.py` 中的 `EditImageMask`。
 
-屏幕坐标投射、点击选择、轨迹预览和状态切换来自 `operators/common/image_interaction.py`。Lasso 按移动距离采点并合并近似共线点；Line 扩展为有向半平面；Polyline 在确认时闭合路径。
+屏幕坐标投射、点击选择、轨迹预览和状态切换来自 `common/image_interaction.py`。Lasso 按移动距离采点并合并近似共线点；Line 扩展为有向半平面；Polyline 在确认时闭合路径。
 
 ### RegionPath → RegionMask
 
-`EditImageMask` 通过 `operators/common/image_region.py` 把手势整理为 `RegionPath`，再栅格化为 `RegionMask`。凹多边形使用三角剖分，自交路径使用 `EVEN_ODD` 填充。预览缓存只在轨迹变化时更新。
+`EditImageMask` 通过 `common/image_region.py` 把手势整理为 `RegionPath`，再栅格化为 `RegionMask`。凹多边形使用三角剖分，自交路径使用 `EVEN_ODD` 填充。预览缓存只在轨迹变化时更新。
 
-Box 和 Lasso 分别读取自己的 **Fit to Foreground** 设置。Line 与 Polyline 强制关闭该选项，因此不会改变直线边界。
+Box 和 Lasso 分别读取自己的 **Fit to Foreground** 设置。Line 与 Polyline 直接使用几何边界。
 
 ### Fit to Foreground
 
@@ -40,6 +40,6 @@ Box 和 Lasso 分别读取自己的 **Fit to Foreground** 设置。Line 与 Poly
 
 ### 源 Alpha × RegionMask
 
-`edit_mask.py` 保留源 RGB，只把最终 `RegionMask` 乘入源 Alpha，再按非零 Alpha 紧裁切。像素读取、结果 Image 创建和共享引用处理使用 `operators/common/image_data.py`。
+`edit_mask.py` 保留源 RGB，只把最终 `RegionMask` 乘入源 Alpha，再按非零 Alpha 紧裁切。像素读取、结果 Image 创建和共享引用处理使用 `common/image_data.py`。
 
-公共 Image Empty 替换入口会同步更新 `empty_display_size` 和 `empty_image_offset`，因此裁切后的内容仍对齐原图片平面，对象 `matrix_world` 不变。Perspective 使用相同的像素写回能力，但属于独立工具和状态。
+公共 Image Empty 替换入口同步更新 `empty_display_size` 和 `empty_image_offset`，使裁切后的内容对齐原图片平面并保持对象 `matrix_world`。

docs/internals/operators/index.md

@@ -1,6 +1,6 @@
 # Operator 实现索引
 
-`src/anyimage/operators/` 负责 Blender 侧交互、Job 请求组装和结果导入。内部实现按完整功能包或顶层业务模块拆页；`common/` 的边界见[程序架构](../architecture.md)，实际公开入口见[Common 公共函数](../common.md)。
+`src/anyimage/operators/` 负责 Blender 侧交互、Job 请求组装和结果导入。
 
 | Operator 路径 | 实现页 | 主要职责 |
 | --- | --- | --- |
@@ -15,4 +15,4 @@
 | `operators/remove_background.py` | [Remove Background](remove-background.md) | BEN2 去背与结果替换 |
 | `operators/upscale.py` | [Upscale](upscale.md) | 当前 Image 的 4× 高清与输入长边检查 |
 
-`operators/__init__.py` 只聚合注册类，不承载独立业务流程。具体类的注册和逆序注销由扩展入口统一管理，整体边界见[程序架构](../architecture.md)。
+`operators/__init__.py` 聚合注册类，扩展入口按顺序注册并逆序注销。

docs/internals/operators/perspective-tool.md

@@ -15,7 +15,7 @@ flowchart TD
     Crop --> Write["Pack 并写回 Empty"]
 ```
 
-预览只在第四点确认后生成一次；之后拖动鼠标只改变目标宽高比。用户确认时才执行全分辨率 Warp。整个流程在 Blender 进程内完成，不使用 Job Server。
+第四点确认后生成预览，拖动鼠标调整目标宽高比，用户确认后执行全分辨率 Warp。整个流程在 Blender 进程内完成。
 
 ## 节点说明
 
@@ -23,18 +23,18 @@ flowchart TD
 
 `operators/perspective_tool/__init__.py` 导出注册类型，交互和计算集中在 `edit_perspective.py`。`ImagePerspectiveTool` 启动 `EditImagePerspective`，后者接受任意顺序的四个图片角点，再根据源图 X/Y 方向整理成不交错的凸 Quad。
 
-图片坐标投射和首次点击选择复用 `operators/common/image_interaction.py`。Perspective 始终把四点称为 Quad，不使用 Image Tool 的 Region 或 Mask 状态。
+图片坐标投射和首次点击选择复用 `common/image_interaction.py`。四个角点在该流程中统一表示为 Quad。
 
 ### 预览并调整比例
 
-第四点确定后，`edit_perspective.py` 创建一次 512 × 512 预览纹理。鼠标移动只更新目标宽高比和 HUD，可吸附到常用比例，不会重复重采样源图。
+第四点确定后，`edit_perspective.py` 创建 512 × 512 预览纹理。鼠标移动更新目标宽高比和 HUD，并可吸附到常用比例。
 
 输出尺寸根据 Quad 边长和目标比例计算，最长边不超过 8192 px，总像素不超过 16,777,216。
 
 ### 执行 Homography
 
-确认后，`edit_perspective.py` 计算 Homography，并按 256 行分块处理全分辨率像素。插值使用预乘 Alpha，避免透明边缘混入黑色。Perspective 只做形变，不提供 Fit to Foreground 或反选。
+确认后，`edit_perspective.py` 计算 Homography，并按 256 行分块处理全分辨率像素。插值使用预乘 Alpha，避免透明边缘混入黑色。
 
 ### 裁切并写回
 
-Warp 结果按可见 Alpha 紧裁切，再通过 `operators/common/image_data.py` 创建 Packed Image 并替换当前 Empty。结果宽高比可能不同于原 Quad 的轴对齐范围，因此写回时保持中心和覆盖尺度近似一致，而不是复用原图片像素范围。
+Warp 结果按可见 Alpha 紧裁切，再通过 `common/image_data.py` 创建 Packed Image 并替换当前 Empty。写回时保持中心和覆盖尺度近似一致。

docs/internals/operators/remove-background.md

@@ -14,13 +14,13 @@ flowchart TD
     Import --> Replace["替换 Empty.data"]
 ```
 
-Blender 负责媒体输入准备和结果导入，BEN2 推理留在 Server。Packed 图片和内存中修改过的单图会先导出临时文件；可直接读取的文件图片、视频和序列沿用原路径。
+Packed 图片和内存中修改过的单图会先导出临时文件；文件图片、视频和序列沿用原路径。
 
 ## 节点说明
 
 ### 准备媒体输入
 
-入口是 `operators/remove_background.py` 中的 `RemoveImageBackground`。它检查当前对象、AI Environment 和帧数，再调用 `operators/common/image_data.py` 的 `prepare_image_input()`。多帧输入会先写入 Scene 中的抽帧设置。
+入口是 `operators/remove_background.py` 中的 `RemoveImageBackground`。它检查当前对象、AI Environment 和帧数，再调用 `common/image_data.py` 的 `prepare_image_input()`。多帧输入会先写入 Scene 中的抽帧设置。
 
 准备完成后，内部 Operator `RunBackgroundRemoval` 保存输入路径、源对象名和临时文件清理标记。
 
@@ -32,6 +32,6 @@ BEN2 推理前先用源 Alpha 屏蔽透明区域，模型输出的前景 Alpha
 
 ### 导入并替换结果
 
-Job 返回后，`remove_background.py` 的 `apply_background_response()` 调用 `operators/common/image_data.py` 创建单图或序列 Image，并恢复源 Image User 的帧起点、偏移和循环设置。
+Job 返回后，`remove_background.py` 的 `apply_background_response()` 调用 `common/image_data.py` 创建单图或序列 Image，并恢复源 Image User 的帧起点、偏移和循环设置。
 
-同一公共入口随后替换 `Empty.data`。旧 Image 没有其他用户且未启用 Fake User 时会被清理，结果继承原名；否则保留旧数据块。最后提交一个 Remove Background Undo 步骤，并清理本次创建的临时输入。
+`replace_empty_image()` 随后替换 `Empty.data`，提交一个 Remove Background Undo 步骤，并清理本次创建的临时输入。

docs/internals/operators/upscale.md

@@ -25,20 +25,20 @@ flowchart TD
 
 入口位于 `operators/upscale.py`。`UpscaleImage.poll()` 读取 `preferences.py` 中的 **Maximum AI Input Size**；当前 Image 长边必须严格小于该值。菜单显示的预计尺寸来自同一文件的 `upscale_output_size()`。
 
-执行时，`upscale.py` 冻结当前模型和输入上限，并通过 `operators/common/image_data.py` 准备单图、视频或序列输入。Packed Image 与内存修改结果会导出临时文件，多帧输入保留帧起点和抽帧设置。
+执行时，`upscale.py` 冻结当前模型和输入上限，并通过 `common/image_data.py` 准备单图、视频或序列输入。Packed Image 与内存修改结果会导出临时文件，多帧输入保留帧起点和抽帧设置。
 
 ### 分块放大 RGB
 
 `UpscaleImage` 提交 `upscale-image` Job。`server/jobs/upscale.py` 展开媒体帧并逐帧调用模型；`server/models/upscale.py` 负责输入约束、RGB/Alpha 分离和结果合并，`server/models/onnx_upscale.py` 以 256 × 256 分块执行 4× ONNX 推理并带入相邻上下文。
 
-`server/media/resolution.py` 统一解释输入长边上限。正式 Upscale 在 Blender 侧直接禁用超限图片，因此不会进入预缩放路径，输出长边小于上限的四倍；模型层仍保留同一限制作为任务边界。
+`server/media/resolution.py` 统一解释输入长边上限。Blender 侧要求源图长边小于该值，结果长边小于该值的四倍。
 
 ### 合并 Alpha
 
-Alpha 不进入模型，由 `server/models/upscale.py` 使用 Lanczos 放大到目标尺寸，再与 4× RGB 合并为 RGBA。Provider 资源不足时，Server 释放当前 Upscale Session，并返回降低输入上限或改用 CPU 的提示。
+`server/models/upscale.py` 使用 Lanczos 将 Alpha 放大到目标尺寸，再与 4× RGB 合并为 RGBA。Provider 资源不足时，Server 释放当前 Upscale Session，并返回降低输入上限或改用 CPU 的提示。
 
 ### 导入并替换结果
 
-响应阶段回到 `operators/upscale.py`，通过 `operators/common/image_data.py` 读取 `upscale.*` 结果序列并替换当前 Empty。源 Image 没有其他用户且未启用 Fake User 时会被清理并由结果继承名称；存在其他用户时只替换当前 Empty 的引用。
+响应阶段回到 `operators/upscale.py`，通过 `common/image_data.py` 读取 `upscale.*` 结果序列并替换当前 Empty。
 
-结果不添加 Upscale 专属数据块后缀，也不保留来源引用。后续再次 Upscale 或转换 Depth Plane 时，读取的都是当前结果 Image。
+后续 Upscale 和 Depth Plane 都以当前结果 Image 为输入。

docs/internals/outputs.md

@@ -1,6 +1,6 @@
 # Job 产物
 
-Job 目录是 Server 与 Blender Operator 的交换边界。Server 写入普通图片、JSON 或 Debug NPZ；Blender 只读取 Job 返回值明确声明的文件，再创建最终 Image、Mesh、Material 与 Object。
+Server 在 Job 目录写入图片、JSON 或 Debug NPZ；Blender 根据 Job 返回值读取文件并创建 Image、Mesh、Material 与 Object。
 
 ## 正式 Job
 
@@ -12,7 +12,7 @@ Job 目录是 Server 与 Blender Operator 的交换边界。Server 写入普通
 | `generate-depth-plane-geometry` | `image.0001.*`、`z-depth.exr`、`depth.json` | 创建 Depth Plane |
 | `generate-cutout-artifacts` | 可选 Region、Depth 与 Normal 文件 | 创建 Cutout Shape 与材质 |
 
-两个 Depth Job 都不输出 Blender 网格。Server 保存可由 Blender 直接加载的模型空间 EXR；轮廓提取、三角化、Depth 标定以及 Blender 数据创建仍在主线程完成。
+Depth Job 保存可由 Blender 直接加载的模型空间 EXR；Blender 主线程负责轮廓提取、三角化、Depth 标定和数据创建。
 
 ## Depth 与 Normal 文件
 
@@ -26,7 +26,7 @@ MoGe-2 Prediction 只存在于 Server 内存。`geometry/prediction_artifacts.py
 | `tangent-normal.png` | Tangent Space Normal Map |
 | `object-normal.png` | Object Space Normal Map |
 
-Blender 通过 `operators/common/depth_data.py` 直接加载 EXR，设为 Non-Color 并 Pack；不会从 NumPy 点场再创建一张 Depth Image。Job 文件名不改变 Blender 数据块命名：Depth 与 Normal 仍分别使用 `depth_data_name()` 和 `normal_data_name()`。Blender 读取 Z 与 Alpha 只用于最终 Region 的本地标定，Geometry Nodes 直接采样已加载的 EXR。
+Blender 通过 `common/depth_data.py` 加载 EXR，设为 Non-Color 并 Pack。Depth 与 Normal 数据块分别由 `depth_data_name()` 和 `normal_data_name()` 命名。Blender 读取 Z 与 Alpha 进行最终 Region 的本地标定，Geometry Nodes 采样已加载的 EXR。
 
 ## Cutout Region 产物
 
@@ -37,7 +37,7 @@ Blender 先把 `RegionPath` 栅格化为 `RegionMask`，再把局部 RGBA 作为
 - 需要 Z Depth 时请求 `z-depth.exr` 与 `depth.json`；
 - Normal Map 按空间请求 `tangent-normal.png` 或 `object-normal.png`。
 
-未启用 Fit to Foreground，且不需要 Depth 或 Normal Map 时，Surface 与 Balloon 不提交 Job。最终颜色图仍由 Blender 从源 Image 裁切，并把 Alpha 乘以最终 `RegionMask`。
+Surface 与 Balloon 的本地路径直接使用 `RegionMask` 构建 Shape。最终颜色图由 Blender 按 Region 范围裁切源 Image，并保留源 RGBA。
 
 ## Debug 产物
 
@@ -48,4 +48,4 @@ Blender 先把 `RegionPath` 栅格化为 `RegionMask`，再把局部 RGBA 作为
 | `debug-ben2` | `foreground*.png` |
 | `debug-upscale` | `prediction*.png` |
 
-Debug Job 只用于直接检查模型适配层，不参与正式对象创建流程。
+Debug Job 保存模型适配层的直接输出。

docs/internals/runtime.md

@@ -1,6 +1,6 @@
 # Job Runtime 与 Server
 
-AnyImage 使用 BlendJob 管理独立 Python Environment、Server 进程与单 Worker 队列。Blender 侧只准备输入、提交普通字典参数并导入结果；`server/` 不依赖 `bpy`。
+AnyImage 使用 BlendJob 管理独立 Python Environment、Server 进程与单 Worker 队列。Blender 侧准备输入、提交普通字典参数并导入结果。
 
 ## 目录职责
 
@@ -20,7 +20,7 @@ src/anyimage/
     └── outputs/               # Debug Prediction 序列化
 ```
 
-公开 Job 不互相导入实现。`jobs/` 只编排，稳定的原子能力放在对应领域目录中。
+`jobs/` 编排任务，领域目录提供媒体、Region、Geometry、模型和输出能力。
 
 ## 生命周期
 
@@ -52,15 +52,15 @@ Job 在阶段边界调用 `context.check_cancelled()`，并把稳定产物写入
 
 ## 尺寸约束
 
-`server/media/resolution.py` 提供 **Maximum AI Input Size**，默认 `2048 px`。它限制 Upscale 的可提交源图长边，以及 Depth、Normal Map、Fit to Foreground 的模型分析图长边；不会降低材质颜色图分辨率。
+`server/media/resolution.py` 提供 **Maximum AI Input Size**，默认 `2048 px`。它限制 Upscale 的可提交源图长边，以及 Depth、Normal Map、Fit to Foreground 的模型分析图长边；材质颜色图使用原始分辨率。
 
-Cutout 另有 Blender 侧的 **Maximum Cutout Mesh Resolution**。它限制所有 Cutout Shape 的网格采样密度，包括完全不使用 AI 的 Surface 与 Balloon。两个设置没有隐式绑定。
+Blender 侧的 **Maximum Cutout Mesh Resolution** 统一限制所有 Cutout Shape 的网格采样密度。
 
 `generate-depth-plane-geometry` 与 `generate-cutout-artifacts` 只接受一帧，因此 Depth Plane 与 Cutout 是静态图工作流。Remove Background 与 Upscale 继续通过媒体入口处理单图、视频和序列帧。
 
-## 模型边界
+## 模型
 
-正式 Depth Plane、Cutout Depth 与 Normal Map 都只使用 MoGe-2。BEN2 用于 Remove Background 与 Fit to Foreground，Upscale 使用所选高清模型。DA3 只保留 `debug-da3` 及其 Debug 参数、模型下载与适配代码，不进入任何生产 Operator、Job 或自动回退。
+Depth Plane、Cutout Depth 与 Normal Map 使用 MoGe-2，Remove Background 与 Fit to Foreground 使用 BEN2，Upscale 使用所选高清模型。
 
 `ModelManager` 按模型族管理下载目录与 ONNX Session，同一族只保留最近使用的模型和 Device，避免同类模型重复占用资源。