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.

docs/guides/animation.md

@@ -0,0 +1,33 @@
+# 视频与序列帧
+
+AnyImage 对 Movie 与 Image Sequence 提供三类工作流：直接转换为普通 Plane、逐帧去除背景、逐帧高清放大。Depth Plane 与 Cutout 当前只支持静态图片。
+
+## 支持范围
+
+| 工作流 | 视频 / 序列帧 | 结果 |
+| --- | --- | --- |
+| Convert to Plane | 支持 | 保留源 Image 的播放设置 |
+| Remove Background | 支持 | 透明 PNG 序列 |
+| Upscale | 支持 | 4× PNG 序列 |
+| Convert to Depth Plane | 不支持 | 仅静态图片 |
+| Cutout / Image Tools | 不支持 | 仅静态图片 |
+
+## 处理范围
+
+逐帧 Job 从 Image Empty 的图片设置读取：
+
+- **Image Frames**：处理帧数；
+- **Offset**：源素材起始偏移；
+- **Start**：结果在场景中的播放起点；
+- **Cyclic**：是否循环播放。
+
+显式把 Image Frames 设为 `1` 时，只处理一帧。Remove Background 与 Upscale 复用同一模型 Session 逐帧执行，内存峰值主要取决于单帧尺寸。
+
+## 保存工程
+
+Blender 无法把整组图片序列完整 Pack 到 `.blend`。Remove Background 与 Upscale 的动画结果会继续引用 Storage Root 中的 Job 目录。
+
+!!! danger
+    删除或移动仍被工程引用的 Job 目录，会导致动画序列丢失。
+
+长期保存时，可以连同对应 Job 目录一起复制工程，或先把序列移动到项目素材目录，再用 Blender 的外部数据工具重新定位路径。

docs/guides/clipboard-image.md

@@ -0,0 +1,43 @@
+# 粘贴剪贴板图片
+
+复制图片后，直接在 Blender 当前编辑器按 `CTRL + V`；macOS 使用 `CMD + V`。AnyImage 会根据上下文决定如何使用图片，并将它 Pack 到当前 `.blend`。
+
+## 支持的上下文
+
+| 上下文 | 结果 |
+| --- | --- |
+| 3D View / Object Mode | 创建 Reference Image 或带材质的 Plane |
+| Sculpt | 设置为笔刷 Texture |
+| Vertex Paint | 设置为笔刷 Texture |
+| Texture Paint | 设置为笔刷 Texture |
+| Shader Editor | 创建 Image Texture 节点 |
+| Compositor | 创建 Image 节点 |
+| Geometry Nodes | 创建 Image Texture 节点 |
+
+## 在 3D View 中
+
+图片会放在鼠标所在的屏幕位置，并使用当前 3D Cursor 作为视图深度参考。默认导入为 `Reference Image`。
+
+如果在操作面板中切换为 `Plane`，会创建基础四边形和 `O Mesh Plane` Geometry Nodes 修改器。操作面板只保留：
+
+- **Import As**：在 Reference Image 与 Plane 之间切换
+- **Shadeless**：让图片不受场景灯光影响
+
+`Thickness` 与 `Subdivide` 直接在 Geometry Nodes 修改器中调整，不作为粘贴参数。
+
+## 在 Node Editor 中
+
+节点创建在鼠标位置。不同节点编辑器会选择对应的图片节点类型，不需要先保存临时图片再手动浏览文件。
+
+## 与 Blender 原生粘贴共存
+
+如果刚刚使用 `CTRL + C` 复制了 Blender 内部数据，随后按 `CTRL + V` 时会优先让 Blender 处理原生粘贴。只有剪贴板中存在新的图片数据时，图片粘贴功能才接管操作。
+
+## 平台说明
+
+- Windows：直接支持
+- macOS：使用 `CMD + V`
+- Linux Wayland：需要 `wl-clipboard`
+- Linux X11：需要 `xclip`
+
+剪贴板中没有可用图片时，操作会放行，不阻断 Blender 的其他粘贴行为。

docs/guides/cutout.md

@@ -0,0 +1,59 @@
+# Cutout
+
+Cutout 用套索从一张 Image Empty 中选择区域，再生成 Surface、Balloon、Depth Balloon 或 Depth Surface。它适合从图片局部制作薄片、鼓包或带透视深度的网格。
+
+## 创建
+
+1. 在 Object Mode 的 3D Viewport 左侧工具栏选择 **Cutout**。
+2. 沿 Image Empty 按住左键绘制；双击图片可选择完整画面。
+3. 松开左键后，从饼菜单选择 Shape。
+
+绘制时按 `F` 切换反选，右键或 `Esc` 取消。Cutout 使用非零环绕填充：反向绘制的内环可以形成孔洞。
+
+## 选择 Shape
+
+| Shape | 结果特点 | 是否需要深度模型 |
+| --- | --- | --- |
+| Surface | 保持平面轮廓，可增加真实厚度 | 否 |
+| Balloon | 按轮廓平滑鼓起 | 否 |
+| Depth Balloon | 在 Balloon 上加入图片深度高度 | 是，固定使用 MoGe-2 |
+| Depth Surface | 使用相机点形成透视表面 | 是，使用 Preferences 中的 Mesh Depth Model |
+
+四种结果都保留源 Image Empty，并在同一位置创建新网格。它们共享选区轮廓、UV、材质和基础三角网格，因此可以从同一张图多次生成不同 Shape 进行比较。
+
+无论是否启用 Refine Selection，套索超出图片的部分都不会生成网格，源图中 `Alpha <= 0.1` 的像素也始终从几何中排除。双击选择完整画面时同样只为 `Alpha > 0.1` 的区域生成网格。
+
+## 工具设置
+
+- **Point Spacing**：相邻网格点大约对应多少源图像素。数值越小，网格越密，轮廓和变形细节越多。
+- **Normal**：使用 MoGe-2 生成法线贴图。默认关闭。
+- **Refine Selection**：用 BEN2 把几何套索收紧到其中的前景内容。默认关闭。
+
+Surface 与 Balloon 在 Normal、Refine 都关闭时完全在 Blender 中生成，不需要 AI Environment。开启任一 AI 选项，或选择 Depth Shape 时，会提交后台任务。
+
+Point Spacing 先按完整源图换算基础密度；选区裁切后的长边若超过全局 **Maximum AI Input Size**，网格密度会按分析图的等比缩放比例降低。颜色贴图始终保留原裁切分辨率，不会使用限制后的临时分析图。建议先用默认 `32` 观察形状；轮廓需要更细时再逐步减小。
+
+## 调整修改器
+
+四个 Shape 都使用同一个 `O Image Cutout` Geometry Nodes 修改器。创建时 Shape 菜单已经设为饼菜单所选类型；切换 Shape 后，Blender 只显示该类型实际使用的输入。常用参数包括：
+
+- **Thickness**：Surface / Depth Surface 使用场景距离；Balloon / Depth Balloon 使用鼓起高度倍率。
+- **Cleanup**：绝对面积阈值；创建时根据 Point Spacing 和图片平面尺寸自动写入，面积小于该值的 Mesh Island 会在生成任意 Shape 前移除。
+- **Smooth Iterations**：位于外层，控制平滑次数，默认 `0`；**Smooth** 位于 Options 中，控制每次平滑的混合强度。四种 Shape 都可使用。
+- **Depth Scale**：Depth Shape 的深度强度；`0` 回到基础平面或 Balloon。
+
+两个 Depth Shape 共用 **Reference Depth**；Depth Balloon 还提供 **Depth Direction**。插件自动写入的 Depth Image 与 Uniform Scale 位于折叠的 Data 面板，一般无需手动修改。
+
+Balloon 的轮廓高度算法由扩展 Preferences 中的 **Balloon Profile** 控制：Poisson 更平滑，Teddy 更强调轮廓骨架。修改默认值只影响之后创建的 Shape。
+
+## Refine 与 Normal
+
+Refine Selection 只在“套索与源图可见 Alpha 的交集”内收紧用于建网格的最终选择，不把 AI 生成的颜色写回原图。材质继续使用当前 Image Empty 的源颜色和原 Alpha。
+
+Normal 关闭时使用几何法线；开启后，Surface、Balloon 与 Depth Balloon 使用适配成品网格的 Tangent Space 法线，Depth Surface 使用 Object Space 法线。Cutout 始终使用 MoGe-2；Depth 与 Normal 同时需要时共享同一次 Prediction，不会重复运行模型。
+
+## 当前范围
+
+Cutout 只支持静态图片。图片工具创建的透明结果和 Upscale 结果都可以继续作为输入；Cutout 始终以当前 Image Empty 的实际图片为颜色来源。
+
+轮廓、深度场、节点资产与法线空间的实现见 [Cutout Tool 实现原理](../internals/operators/cutout-tool.md)。

docs/guides/depth-plane.md

@@ -0,0 +1,42 @@
+# Depth Plane
+
+Depth Plane 将一张静态图片转换为带深度位移的网格，适合快速场景搭建、2.5D 合成和立体插画。
+
+## 创建
+
+1. 在 3D View 中选中 Image Empty。
+2. 右键选择 **AnyImage > Convert to Depth Plane**。
+3. 等待状态栏提示任务完成。
+
+转换不会弹出设置对话框。深度模型和分辨率使用 **Edit > Preferences > Extensions > AnyImage > Depth & Normal** 中的默认值。
+
+## 选择模型
+
+### MoGe-2
+
+默认推荐。MoGe-2 估算尺度一致的深度与相机信息，使用 **MoGe Resolution Level** 控制处理精度。第一次使用建议保持 `5`。
+
+### DA3
+
+DA3 提供另一种深度结果，使用 **DA3 Resolution Scale** 按原图长边计算处理尺寸。比例越高，通常会保留更多细节，也会增加耗时和内存占用。
+
+切换模型后，如果对应文件尚未下载，先在同一设置区点击 **Download**。
+
+## 调整结果
+
+生成对象使用运行时创建的 `O Image Depth Plane` Geometry Nodes 修改器：
+
+- **Subdivide**：控制基础平面细分级别；
+- **Thickness**：增加背面和侧壁，`0` 输出单面；
+- **Depth Amount**：控制图片深度位移强度。
+
+结果颜色来自当前 Image Empty，深度由所选模型分析。转换会以一个 Undo 步骤替换源 Empty；如果需要保留原对象，请在转换前复制一份。
+
+## 当前输入范围
+
+Depth Plane 当前只支持静态图片。视频与序列帧可以转换为普通 [Plane](mesh-plane.md)，或使用 [Remove Background / Upscale](animation.md) 逐帧处理。
+
+实现中的深度场、坐标锚定和节点流程见 [Convert to Plane 实现原理](../internals/operators/convert-to-plane.md)。
+## 分析分辨率与颜色
+
+Depth 输入还受 Environment 区的 **Maximum AI Input Size** 约束，默认最大长边为 `2048 px`。超过时只会等比缩放模型分析输入；结果材质仍使用原始颜色图片，不会改用限制后的临时图。

docs/guides/faq.md

@@ -0,0 +1,54 @@
+# 常见问题
+
+## 找不到 AnyImage 右键菜单
+
+AnyImage 菜单只会在选中 Image Empty 时出现。确认对象类型是 Empty，并且显示方式为 Image。普通 Mesh、图片编辑器中的图片或未选中的 Image Empty 都不会显示入口。
+
+## 转换入口是灰色的
+
+通常有以下原因：
+
+- 另一个 AnyImage 任务正在运行。
+- 当前对象不是 Image Empty。
+
+Environment 或默认模型缺失不会让四个 AI 功能变灰；点击功能会根据状态打开 **Set Up AI Environment…** 或 **Download Required Models…**。Balloon 的 **Contour**、**Depth** 与 Depth Model 会在 AI 未就绪时单独禁用，同一位置提供安装按钮。
+
+## Environment 安装失败
+
+- 海外源访问不稳定时重新打开 **Set Up AI Environment…**，勾选 **Use Mirror**。
+- 检查 Blender 的 **Online Access** 是否开启。
+- 确认 Storage Root 至少有约 1 GB 可用空间且可写。
+- 查看 Storage Root 下的 `install.log`。
+
+安装模型失败不会删除已经成功创建的 Environment。可以稍后使用 **Download Required Models…** 补齐默认模型，或在 AnyImage 扩展偏好设置中逐项重试。
+
+## 模型下载很慢或失败
+
+模型会尝试 Hugging Face 和 OmooLab 备用来源。检查网络、代理和磁盘空间后重新点击 Download。模型直链连接或长时间无数据时会自动尝试下一来源。
+
+## 第一次转换较慢
+
+第一次任务需要启动 Job Server 并把模型载入内存。Server 运行且模型仍在缓存中时，后续同类任务通常会更快。
+
+## Upscale 很卡或提示内存不足
+
+三个高清模型都使用分块推理，但完整输出数组、PNG 编码和 Blender 图片载入仍取决于输入与 4× 结果尺寸。Environment 区的 **Maximum AI Input Size** 默认限制输入长边为 `2048 px`；可以降低该值，或改用 CPU。DirectML 或其他 provider 无法分配资源时，任务也会提示降低这个全局值。
+## Depth Plane 太平或深度方向反了
+
+在 Geometry Nodes 修改器中调整 **Depth Scale**。增大绝对值会加强深度，使用负值可以反转前后关系。
+
+## Cutout Depth Surface 边缘破碎或细节太多
+
+先增大 **Point Spacing** 降低基础网格密度，再调整 **Cleanup** 清理小块，并用 **Smooth** 稳定表面。必要时降低模型分辨率。
+
+## 动画面片不播放
+
+检查源 Image Empty 的 **Image Frames** 是否大于 `1`，并确认场景时间正在变化。生成后的动画还需要对应 Job 文件夹存在；文件被移动或删除时应重新定位序列。
+
+## 可以删除 jobs 文件夹吗
+
+静态图的部分结果会 Pack 到 `.blend`，但视频与序列帧会直接引用 Job 文件。只有确认没有工程继续引用对应目录时才应删除。
+
+## 如何完全撤销一次转换
+
+转换完成后直接按 `Ctrl+Z`。AnyImage 会把网格、材质、图片和修改器的创建合并为一次 Blender Undo 操作。

docs/guides/image-tools.md

@@ -0,0 +1,82 @@
+# Image 编辑工具
+
+Image Box、Lasso、Line、Polyline 与 Perspective 直接编辑静态 Image Empty，并把结果 Pack 到当前 `.blend`。前四个工具组成 Mask 工具组；Perspective 是紧随其后的独立工具。
+
+## 选择工具
+
+| 工具 | 用途 |
+| --- | --- |
+| **Image Box** | 用矩形保留或清理图片区域 |
+| **Image Lasso** | 手绘自由选区 |
+| **Image Line** | 用一条直线清理一侧 |
+| **Image Polyline** | 逐点构建精确多边形 |
+| **Image Perspective** | 将任意顺序输入的四个角矫正为矩形 |
+
+在 3D Viewport 左侧工具栏长按 Image Mask 图标，可以在 Box、Lasso、Line 与 Polyline 之间切换。**Refine Selection** 只显示在 Box / Lasso；Line / Polyline 保持几何直线边界。Perspective 使用独立图标。
+
+<div class="screenshot-placeholder" markdown>
+**截图占位：Image 工具组与 Tool Settings**
+
+显示包含四个工具的 Image Mask 组、独立 Perspective，以及 Box / Lasso 的 Refine Selection。
+
+目标文件：`images/image-tools/tool-group.png`
+</div>
+
+## 选择图片
+
+直接在当前 Active 图片上开始绘制。如果第一次点击的是另一张 Image Empty，这次点击只会选中它；下一次操作才开始编辑。点击空白处或非图片对象时，继续编辑当前 Active 图片，不会移动对象。
+
+没有 Active Image Empty 时，工具会提示先选择图片。切换到其他工具会立即取消正在进行的绘制。
+
+## 清理选区
+
+### Box 与 Lasso
+
+- Box：按住左键拖出矩形，松开后执行。
+- Lasso：按住左键绘制轮廓，松开后执行。
+
+### Line
+
+从起点拖到终点，松开后保留直线左侧的内容。按住 `Ctrl` 以 5° 为单位吸附方向；需要另一侧时按 `F` 翻转。
+
+### Polyline
+
+逐点单击构建多边形。鼠标接近起点时会显示闭合圆环；单击圆环或按 `Enter` 完成，`Backspace` 删除最近一点。
+
+绘制过程中按 `F` 切换反选。反选是一个持续到本次操作完成的状态，不需要按住：
+
+- 关闭：保留选区内；
+- 开启：保留选区外。
+
+Cutout、Box 与 Lasso 分别保存各自的 **Refine Selection** 设置；在一个工具中切换不会改变另外两个工具。启用后，BEN2 会先把几何选区收紧到其中的前景，再应用反选。例如框住一个苹果并开启反选，最终会清理苹果本身、保留其余内容。Line / Polyline 不提供 Refine，以保持直线边界和明确的裁切方向。
+
+结果会直接更新当前 Empty 的图片，并把画布紧裁切到最终可见 Alpha。只有一个 Image Empty 使用该图片时，工具更新原 Image；两个或更多 Image Empty 共用它时，工具为当前 Empty 创建独立结果，其他 Empty 保持不变。对象 Transform 不变，显示尺寸与 Image Offset 会更新，使剩余像素保持在原图片平面上的位置。透明区只修改 Alpha，保留源 RGB 供纹理过滤使用。未形成有效区域的单击会静默结束；有效选区没有可见像素时只显示警告，不修改图片。
+
+<div class="screenshot-placeholder" markdown>
+**截图占位：Polyline 与反选**
+
+显示半透明选区面、虚线边界，以及状态栏中的 `F toggles Invert`。
+
+目标文件：`images/image-tools/polyline-invert.png`
+</div>
+
+## 四点透视
+
+1. 任意顺序单击四个角点。
+2. 第四点后，在 Viewport 中央检查矫正预览。
+3. 左右移动鼠标调整宽高比；按住 `Ctrl` 可吸附到 `1:1`、`4:3`、`3:4`、`16:9`、`9:16`。
+4. 左键确认。
+
+`Backspace` 返回上一步，右键或 `Esc` 取消。四点会自动排序，点击顺序不会改变输出旋转。
+
+Perspective 只执行图片 Homography 与紧裁切，不做 Refine，也不尝试从当前 View 推导真实相机。结果保持源 Empty 的 Transform，并按原四边形覆盖范围近似更新显示位置与尺寸。选区完全位于图片外或没有可见像素时不会执行。
+
+<div class="screenshot-placeholder" markdown>
+**截图占位：Perspective 比例确认**
+
+显示中央图片预览、蓝色边框、当前比例与底部操作提示。
+
+目标文件：`images/image-tools/perspective-aspect.png`
+</div>
+
+实现结构与像素规则见 [Image Tool 实现原理](../internals/operators/image-tool.md)。

docs/guides/mesh-plane.md

@@ -0,0 +1,27 @@
+# Plane
+
+Plane 把 Image Empty 转换为带图片材质的普通网格，不运行 AI，也不生成深度估算。它适合广告牌、图片卡片、背景板，以及视频或序列贴图。
+
+## 创建
+
+1. 在 3D View 中选中 Image Empty。
+2. 右键选择 **AnyImage > Convert to Plane**。
+3. 在 Last Operation 中按需调整 **Subdivide**。
+
+转换会立即创建结果并替换源 Empty。新对象继承原对象的 Transform、图片显示比例和 Offset；需要保留源 Empty 时，请先复制对象。
+
+## Geometry Nodes
+
+结果使用 `O Mesh Plane` 修改器：
+
+- **Subdivide** 使用二分级别控制网格密度，`3` 表示短边约 `8` 段；
+- **Thickness** 沿平面法线增加厚度，`0` 输出真正的单面；
+- **Material** 由 AnyImage 自动连接。
+
+原始 Mesh 数据只有一个四边形，细分和厚度都由修改器实时生成，可以在转换后继续调整。
+
+## 剪贴板 Plane
+
+在 3D View 中粘贴剪贴板图片，并在 Last Operation 把 **Import As** 改为 **Plane**，也会创建同样的基础网格和 `O Mesh Plane` 修改器。该入口还可选择 **Shadeless**；Image Empty 的 Convert to Plane 入口不提供 Shadeless 选项。
+
+模块与节点分工见 [Convert to Plane 实现原理](../internals/operators/convert-to-plane.md)。

docs/guides/models-and-storage.md

@@ -0,0 +1,66 @@
+# 模型、设备与存储
+
+AnyImage 把运行环境、模型和任务结果放在 Blender 之外，多个 Blender 版本可以共享同一套数据。
+
+## 功能与模型设置
+
+打开 **Edit > Preferences > Extensions > AnyImage**，可以查看和下载模型。右键菜单中的 **AI Environment Settings…** 会直接打开这里。Environment 检测后紧接 Diagnostics；其余设置分为默认展开、可折叠的 Depth & Normal、Remove Background、Upscale 和 Cutout 功能区，模型不会再集中显示在单独列表中。
+
+- **Ready** 表示模型文件已经就绪。
+- **Download** 用于按需下载模型。
+- Depth & Normal 与 Upscale 的下载按钮位于当前模型选择项下方；切换选择后，可直接下载对应模型。
+- Depth Model 先列出三档 MoGe-2，再列出两档 DA3；DA3 不输出 normal，选择后会在设置下方提示。
+- Remove Background 使用的 BEN2 固定模型显示在对应功能区；Cutout 区只包含 Balloon Profile。
+- 默认安装会准备 MoGe-2 ViT-S Normal、BEN2 Base 和 Real-ESRGAN General WDN x4v3。
+- DA3、更大的 MoGe-2，以及可选的 SAFMN Real x4、Real-ESRGAN x4plus 需要时再下载即可。
+- 可公开取得的 ONNX 制品使用经过大小与 SHA-256 校验的原址，并以 OmooLab R2 为镜像；不会把源码仓库名称推测成 Hugging Face 下载地址。
+- Real-ESRGAN General WDN x4v3 与 SAFMN Real x4 的上游只发布 PyTorch 权重，当前 ONNX 均从官方权重导出并仅从 R2 下载。
+
+较大的模型不一定适合所有图片。建议先用默认模型完成构图，再针对细节与性能需求比较其他模型。
+
+## 全局 AI 输入尺寸
+
+Environment 区的 **Maximum AI Input Size** 控制 Upscale、Depth 与 Normal 分析输入的最大长边，默认 `2048 px`，可在 `256–8192 px` 之间调整。超过上限的输入会保持宽高比缩小；颜色贴图仍使用原始分辨率。Cutout 在完成套索裁切后再应用上限，因此整张原图很大但选区较小时不会被无谓缩小。
+## Device
+
+扩展偏好设置中的 **Device** 控制 Depth Plane、Cutout 的 AI 增强、Remove Background 和 Upscale 等正式任务。
+
+- Windows 通常优先使用 DirectML。
+- Apple Silicon macOS 通常优先使用 CoreML。
+- Provider 不可用时会回退到 CPU。
+
+Debug 面板中的 **Debug Device** 只影响 Debug 任务，不会覆盖正式任务的 Device。
+
+## Session 缓存
+
+连续使用同一模型和 Device 时，Server 会复用已经加载的 ONNX Session。缓存分为 BEN2、几何模型和 Upscale 三个族，每个族只保留最近使用的一套；同族切换模型或 Device 时释放旧 Session。如果高清推理遇到 provider 资源错误，也会立即卸载该 Session。
+
+## Storage Root
+
+默认 Storage Root 是 `~/.anyimage`，主要包含：
+
+```text
+~/.anyimage/
+├── .venv/           # 独立 Python Environment
+├── models/          # 模型文件
+├── jobs/            # 每次任务的结果与 job.log
+├── install.log      # Environment 安装日志
+└── server.log       # 带 Job ID 的任务主线与 Job Server 日志
+```
+
+更改 Storage Root 相当于切换到另一套环境、模型和任务数据。AnyImage 不会自动移动旧目录。
+
+## Job 文件夹
+
+每个任务会在 `jobs/` 下创建一个独立目录。单张图生成的关键贴图通常会 Pack 到 `.blend`；视频和序列帧则继续引用 Job 目录中的文件。
+
+可以清理已经确认不再使用的任务目录，但清理前应检查是否有 `.blend` 仍引用其中的序列帧。
+
+## 日志
+
+遇到安装或 Server 问题时：
+
+- 在扩展偏好设置中点击 **Open Server Log** 查看带时间、Job ID 与 Job Type 的运行主线。
+- 具体 Job 的 Handler 细节和完整 traceback 查看 `jobs/<job-id>/job.log`。
+- Environment 安装问题查看 Storage Root 下的 `install.log`。
+- 修改 Storage Root 后，确认你检查的是当前目录中的日志。

docs/guides/remove-background.md

@@ -0,0 +1,23 @@
+# 去除背景
+
+Remove Background 使用 BEN2 为 Image Empty 生成透明前景，不创建网格。
+
+## 使用
+
+1. 选中 Image Empty。
+2. 在 3D View 中右键选择 **AnyImage > Remove Background**。
+3. 等待状态栏提示任务完成。
+
+结果替换当前 Empty 的图片，对象 Transform、显示尺寸、Offset 和播放设置保持不变。单图结果会 Pack 到 `.blend`；视频或序列帧结果继续引用 Job 目录。
+
+## Alpha 处理
+
+推理前，AnyImage 会用输入 Alpha 遮住透明区域中的 RGB。结果颜色仍来自源图，只采用 BEN2 生成的前景 Alpha；源图已有透明度时，两者会相乘。因此 Image Mask 或外部软件已经清理的范围不会被重新扩张。
+
+当前入口不提供 BEN2 的额外细化参数。需要手动控制范围时，可以先使用 [Image Box / Lasso](image-tools.md)，也可以在结果材质中继续调整 Alpha。
+
+## 图片序列
+
+Remove Background 支持单图、Movie 和 Image Sequence。处理帧数、偏移和播放起点见[视频与序列帧](animation.md)。
+
+任务与结果替换流程见 [Remove Background 实现原理](../internals/operators/remove-background.md)。

docs/guides/upscale.md

@@ -0,0 +1,27 @@
+# 高清放大
+
+Upscale 用 ONNX 模型把 Image Empty 的图片放大 4 倍，不创建网格。它支持单图、Movie 和 Image Sequence，并保留源 Alpha。
+
+## 使用
+
+1. 在 AnyImage 扩展偏好设置中选择 **Default Upscale Model**。
+2. 按需要设置 Environment 区的 **Maximum AI Input Size**；默认 `2048 px`，最高 `8192 px`。
+3. 选中 Image Empty，在右键 **AnyImage** 菜单中点击 **Upscale**。
+
+输入长边超过全局上限时，会先保持宽高比缩小，再执行 4× 放大。因此默认设置下结果长边最多为 `8192 px`。完成后，当前 Empty 会改用名称以 `_upscale.png` 结尾的结果图片。
+
+## 模型选择
+
+- **Real-ESRGAN General WDN x4v3**：默认模型，速度快，细节处理较保守。
+- **SAFMN Real x4**：速度与细节较均衡。
+- **Real-ESRGAN x4plus**：生成的细节更明显。
+
+后两项可在扩展偏好设置中按需下载。
+
+对高清结果再次执行 Upscale 时，AnyImage 会从最初的原图重新生成并替换当前结果，不会连续放大已有高清图。
+
+把高清结果继续转换为 Depth Plane 时，颜色材质可以继续使用当前高清图，分析输入则遵守全局上限；Cutout 同样只缩放裁切后的分析输入，不会把限制后的临时图用作 Color。
+
+如果显存或内存不足，请降低 **Maximum AI Input Size**，或改用 CPU。
+
+分块推理、Alpha 合并与原图引用见 [Upscale 实现原理](../internals/operators/upscale.md)。

docs/guides/workflows.md

@@ -0,0 +1,41 @@
+# 选择工作流
+
+先确定需要的是图片数据、普通平面、整图深度，还是局部网格。
+
+| 工作流 | 输入 | 结果 | AI |
+| --- | --- | --- | --- |
+| Clipboard Image | 剪贴板静态图 | Reference、Plane、节点或笔刷纹理 | 不需要 |
+| Convert to Plane | 单图、Movie、Sequence | 带材质的普通网格 | 不需要 |
+| Convert to Depth Plane | 静态图 | 带深度位移的整图面片 | DA3 或 MoGe-2 |
+| Cutout | 静态图局部选区 | 四种局部 Shape | 按 Shape 与选项决定 |
+| Remove Background | 单图、Movie、Sequence | 透明图片或序列 | BEN2 |
+| Upscale | 单图、Movie、Sequence | 4× 图片或序列 | Upscale 模型 |
+| Image Mask / Perspective | 静态图 | 原位更新的裁切或矫正图 | Refine 时使用 BEN2 |
+
+## 普通 Plane
+
+只需要图片卡片、背景板或视频贴图时，选择 **Convert to Plane**。它不分析深度，Thickness 与 Subdivide 可以在 Geometry Nodes 中随时调整。
+
+[阅读 Plane 指南](mesh-plane.md)
+
+## Depth Plane
+
+需要把整张静态图快速变成可调浮雕时，选择 **Convert to Depth Plane**。深度模型与分辨率在扩展 Preferences 中设置。
+
+[阅读 Depth Plane 指南](depth-plane.md)
+
+## Cutout
+
+只需要图片局部，或希望按轮廓生成 Balloon / Depth Surface 时，使用工具栏中的 **Cutout**。普通 Surface 与 Balloon 可以完全在 Blender 内完成，Refine、Normal 与 Depth Shape 按需调用 AI。
+
+[阅读 Cutout 指南](cutout.md)
+
+## 图片处理
+
+只想得到透明前景，不需要网格时使用 [Remove Background](remove-background.md)。需要增加像素尺寸时使用 [Upscale](upscale.md)。两者都支持 Movie 和 Image Sequence。
+
+## Image 编辑
+
+Box、Lasso、Line 和 Polyline 适合直接清理 Alpha；Perspective 适合把图片中的四边形内容矫正为矩形。结果都会写回当前 Image Empty，并保持对象 Transform。
+
+[阅读 Image 编辑工具](image-tools.md)