Merge pull request '按实际抠图输入提交并移除重复任务调用' (#45) from codex/rmbg-input-contract-20261105 into main

app/api/canvas/[id]/capabilities/route.ts

@@ -2,6 +2,7 @@ import { NextResponse } from "next/server";
 import { ZodError } from "zod";
 
 import { auth } from "@/app/(auth)/auth";
+import { RmbgServiceError } from "@/lib/ai/rmbg/service";
 import { canvasCapabilityClientCommandSchema } from "@/lib/canvas/capabilities/client-command";
 import { CanvasCapabilityRuntimeError } from "@/lib/canvas/capabilities/context";
 import { getCanvasCapabilityManifest } from "@/lib/canvas/capabilities/registry";
@@ -90,7 +91,7 @@ export async function POST(
     const failure = getRequestFailureDetails(error, "执行画布能力失败");
     return NextResponse.json(
       { success: false, error: formatRequestFailure(failure, requestId), failure, requestId },
-      { status: 500 }
+      { status: error instanceof RmbgServiceError ? error.status : 500 }
     );
   }
 }

app/api/scene-fusion/route.ts

@@ -6,6 +6,7 @@
  */
 
 import { NextResponse } from "next/server";
+import { preprocessProductImageWithRmbg } from "@/lib/scene-fusion/preprocess-product";
 import { z } from "zod";
 import { auth } from "@/app/(auth)/auth";
 import { db } from "@/lib/db";
@@ -69,7 +70,6 @@ const SCENE_FUSION_REQUEST_STAGGER_MS = 350;
 const SCENE_FUSION_AGENT_TIMEOUT_MS = 20000;
 const SCENE_FUSION_AGENT_MAX_WORKERS = 3;
 const SCENE_FUSION_PROCESS_MAX_WORKERS = 4;
-const SCENE_FUSION_PRE_RMBG_TIMEOUT_MS = 60_000;
 const SCENE_FUSION_ECHO_HASH_TIMEOUT_MS = 20_000;
 const SCENE_FUSION_ECHO_HASH_THRESHOLD = 8;
 const SCENE_FUSION_REVIEW_TIMEOUT_MS = 25_000;
@@ -236,41 +236,6 @@ function isSceneFusionReviewRejectError(message: string): boolean {
   );
 }
 
-function buildPreRmbgCandidateUrls(request: Request): string[] {
-  const urls: string[] = [];
-  const requestUrl = new URL(request.url);
-  const requestHost = requestUrl.hostname.toLowerCase();
-  const requestProtocol = requestUrl.protocol.replace(":", "");
-  if (!(requestProtocol === "https" && (requestHost === "localhost" || requestHost === "127.0.0.1"))) {
-    urls.push(new URL("/api/rmbg", request.url).toString());
-  }
-
-  const host = request.headers.get("host")?.trim();
-  const protoHint = request.headers
-    .get("x-forwarded-proto")
-    ?.split(",")[0]
-    ?.trim()
-    .toLowerCase();
-  const protocol = protoHint === "https" || protoHint === "http" ? protoHint : requestUrl.protocol.replace(":", "");
-
-  if (host) {
-    const normalizedHost = host.split(":")[0]?.toLowerCase() || "";
-    const isLocalHost = normalizedHost === "localhost" || normalizedHost === "127.0.0.1";
-    if (!(protocol === "https" && isLocalHost)) {
-      urls.push(`${protocol}://${host}/api/rmbg`);
-    }
-    if (isLocalHost) {
-      urls.push(`http://${host}/api/rmbg`);
-    }
-  }
-
-  const localPort = requestUrl.port || process.env.PORT || "3125";
-  urls.push(`http://127.0.0.1:${localPort}/api/rmbg`);
-  urls.push(`http://localhost:${localPort}/api/rmbg`);
-
-  return Array.from(new Set(urls));
-}
-
 function normalizeUrlForCompare(input: string): string {
   try {
     const parsed = new URL(input);
@@ -988,102 +953,6 @@ async function getSceneFusionConfig() {
   };
 }
 
-async function preprocessProductImageWithRmbg(
-  request: Request,
-  requestId: string,
-  productImageUrl: string,
-  preRmbgEnabled: boolean
-): Promise<{
-  productImageUrl: string;
-  usedPreRmbg: boolean;
-  provider?: string;
-  reason?: string;
-}> {
-  if (!preRmbgEnabled) {
-    return {
-      productImageUrl,
-      usedPreRmbg: false,
-      reason: "disabled_by_config",
-    };
-  }
-
-  const cookie = request.headers.get("cookie");
-  if (!cookie) {
-    return {
-      productImageUrl,
-      usedPreRmbg: false,
-      reason: "missing_cookie",
-    };
-  }
-
-  const candidateUrls = buildPreRmbgCandidateUrls(request);
-  let lastReason = "no_candidate_url";
-
-  logger.info("pre_rmbg_started", {
-    requestId,
-    candidateCount: candidateUrls.length,
-  });
-
-  for (const rmbgUrl of candidateUrls) {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), SCENE_FUSION_PRE_RMBG_TIMEOUT_MS);
-    try {
-      const response = await fetch(rmbgUrl, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          cookie,
-        },
-        body: JSON.stringify({
-          imageUrl: productImageUrl,
-          prompt: "场景裂变预处理-抠图",
-          skipGallerySave: true,
-        }),
-        signal: controller.signal,
-      });
-
-      const payload = await response.json().catch(() => null) as Record<string, unknown> | null;
-
-      if (!response.ok) {
-        lastReason = `request_failed_${response.status}`;
-        logger.warn("pre_rmbg_candidate_failed", {
-          requestId,
-          status: response.status,
-          detail: payload?.detail || payload?.error || "unknown",
-        });
-        continue;
-      }
-
-      const cleanedUrl = String(payload?.original_url || payload?.thumbnail_url || "").trim();
-      if (!cleanedUrl || cleanedUrl === productImageUrl) {
-        lastReason = cleanedUrl ? "same_as_source" : "empty_result";
-        logger.warn("pre_rmbg_candidate_invalid", {
-          requestId,
-          reason: lastReason,
-        });
-        continue;
-      }
-
-      return {
-        productImageUrl: cleanedUrl,
-        usedPreRmbg: true,
-        provider: String(payload?.provider || "unknown"),
-      };
-    } catch (error) {
-      lastReason = error instanceof Error ? error.message : "exception";
-      logger.warn("pre_rmbg_candidate_exception", error, { requestId });
-    } finally {
-      clearTimeout(timeoutId);
-    }
-  }
-
-  return {
-    productImageUrl,
-    usedPreRmbg: false,
-    reason: lastReason,
-  };
-}
-
 /**
  * 创建缩略图
  */
@@ -2436,12 +2305,13 @@ export async function POST(request: Request) {
       productImageUrl = await uploadBase64ToS3(productImage, "scene-fusion-product");
     }
     const shouldForcePreRmbg = resolvedSceneMode === "random-bg";
-    const preprocessedProduct = await preprocessProductImageWithRmbg(
+    const preprocessedProduct = await preprocessProductImageWithRmbg({
       request,
       requestId,
+      userId: session.user.id,
       productImageUrl,
-      shouldForcePreRmbg ? true : config.preRmbgEnabled
-    );
+      preRmbgEnabled: shouldForcePreRmbg ? true : config.preRmbgEnabled,
+    });
     const fusionProductImageUrl = preprocessedProduct.productImageUrl;
     logger.info("pre_rmbg_resolved", {
       requestId,

app/canvas/[id]/CanvasEditorLegacyPageClient.tsx

@@ -5196,6 +5196,7 @@ export default function CanvasEditorLegacyPage({
       }
 
       try {
+        const beforeRead = useCanvasStore.getState();
         const revisionResponse = await fetch(`/api/canvas/${id}/revision`, {
           cache: "no-store",
         });
@@ -5216,7 +5217,11 @@ export default function CanvasEditorLegacyPage({
         }
 
         const result = await canvasService.getProject(id);
-        if (cancelled || canvasRemoteOperationActive.current || !result.success || !result.data) return;
+        const current = useCanvasStore.getState();
+        if (
+          cancelled || canvasRemoteOperationActive.current || !result.success || !result.data ||
+          current.projectId !== id || current.nodes !== beforeRead.nodes || current.edges !== beforeRead.edges
+        ) return;
         useCanvasStore.getState().markAgentOperationRefresh();
         hydrateCanvasProject(result.data);
         lastLocalCanvasMutationAtRef.current = Date.now();

app/canvas/[id]/style-pro/page.tsx

@@ -48,8 +48,13 @@ export default function CanvasStyleProPage() {
       const canvasData = result.data.canvasData;
       const latestState = useCanvasStore.getState();
       setProject(result.data.id, result.data.title);
-      if (latestState.nodes.length === 0 && latestState.edges.length === 0) {
+      if (
+        latestState.projectId !== id ||
+        (latestState.nodes.length === 0 && latestState.edges.length === 0)
+      ) {
         loadCanvas(canvasData);
+        const revision = String(result.data.updatedAt || "");
+        useCanvasStore.getState().setCanvasRevision(revision, revision);
         return;
       }
 

components/image-annotator.tsx

@@ -918,9 +918,9 @@ export function ImageAnnotator({
 
     setIsRemovingBg(true);
     try {
-      // 使用原图URL获取原图数据，而不是canvas的预览图
-      const base64Data = await imageUrlToBase64(originalImageUrl);
-      logger.debug("rmbg_source_prepared", { base64Length: base64Data.length });
+      const input = /^https?:\/\//i.test(originalImageUrl)
+        ? { imageUrl: originalImageUrl }
+        : { image_base64: await imageUrlToBase64(originalImageUrl) };
 
       // 调用抠图API
       const response = await fetch("/api/rmbg", {
@@ -929,7 +929,7 @@ export function ImageAnnotator({
           "Content-Type": "application/json",
         },
         body: JSON.stringify({
-          image_base64: base64Data,
+          ...input,
           prompt: "画图标注-抠图处理", // 可选：添加提示词
         }),
       });

lib/ai/canvas-agent-runtime/video-image-functions.ts

@@ -72,6 +72,7 @@ export async function processVideoCanvasImage(
     const result = await executeRmbgJob({
       userId: params.userId,
       imageBuffer: await fetchImageBufferFromUrl(imageUrl),
+      inputImageUrl: imageUrl,
       sourceImageUrl: imageUrl,
       prompt: params.prompt,
     });

lib/ai/rmbg/service.ts

@@ -27,6 +27,7 @@ type RmbgConfig = {
 };
 
 export type ExecuteRmbgJobParams = {
+  requestId?: string;
   userId: string;
   imageBuffer: Buffer;
   imageBase64?: string;
@@ -35,6 +36,8 @@ export type ExecuteRmbgJobParams = {
   chatId?: string | null;
   messageId?: string | null;
   skipGallerySave?: boolean;
+  // 仅当 imageBuffer 与 URL 对应的输入文件一致时提供。
+  inputImageUrl?: string | null;
   sourceImageUrl?: string | null;
 };
 
@@ -53,7 +56,7 @@ export class RmbgServiceError extends Error {
   detail?: string;
 
   constructor(message: string, status = 500, detail?: string) {
-    super(message);
+    super(detail && detail !== message ? `${message}：${detail}` : message);
     this.name = "RmbgServiceError";
     this.status = status;
     this.detail = detail;
@@ -61,7 +64,11 @@ export class RmbgServiceError extends Error {
 }
 
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+// https://picwish.cn/background-removal-api-doc
 const AOS_MAX_RESOLUTION = 4096;
+const AOS_MAX_INPUT_BYTES = 50 * 1024 * 1024;
+// The shared AOS state -5 documents a separate limit for image_url downloads.
+const AOS_MAX_URL_INPUT_BYTES = 30 * 1024 * 1024;
 const AOS_CREATE_TIMEOUT_MS = 120_000;
 const AOS_POLL_TIMEOUT_MS = 60_000;
 const AOS_DOWNLOAD_TIMEOUT_MS = 60_000;
@@ -147,6 +154,18 @@ const withTimeout = async <T,>(
   }
 };
 
+async function readAosResult<T>(read: (signal: AbortSignal) => Promise<T>, timeoutMs: number): Promise<T> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await withTimeout(read, timeoutMs);
+    } catch (error) {
+      const name = error instanceof Error ? error.name : "";
+      if (attempt >= 2 || (name !== "TypeError" && name !== "AbortError")) throw error;
+      await sleep(1000 * (attempt + 1));
+    }
+  }
+}
+
 function getAosFriendlyErrorMessage(detail: string): string | null {
   const resolutionMatch = detail.match(/resolution excess,\s*width=(\d+),\s*height=(\d+)/i);
   if (resolutionMatch) {
@@ -164,50 +183,42 @@ function getAosFriendlyErrorMessage(detail: string): string | null {
 async function prepareImageForAos(
   imageBuffer: Buffer
 ): Promise<{ buffer: Buffer; mimeType: string; filename: string }> {
+  if (imageBuffer.length > AOS_MAX_INPUT_BYTES) {
+    throw new RmbgServiceError(
+      `抠图参考图文件大小超限（${(imageBuffer.length / 1024 / 1024).toFixed(2)} MB），当前 AOS 上游最大支持 50 MB。`,
+      400
+    );
+  }
+
+  let metadata: import("sharp").Metadata;
   try {
     const sharp = await import("sharp");
-    const image = sharp.default(imageBuffer);
-    const metadata = await image.metadata();
-    const width = metadata.width;
-    const height = metadata.height;
-    const format = (metadata.format || "png").toLowerCase();
-
-    const ext = format === "jpeg" ? "jpg" : format;
-    const filenameExt =
-      ext === "jpg" || ext === "png" || ext === "webp" || ext === "tiff" ? ext : "png";
-    const mimeType =
-      ext === "jpg"
-        ? "image/jpeg"
-        : ext === "webp"
-          ? "image/webp"
-          : ext === "tiff"
-            ? "image/tiff"
-            : "image/png";
-
-    if (!width || !height || (width <= AOS_MAX_RESOLUTION && height <= AOS_MAX_RESOLUTION)) {
-      return {
-        buffer: imageBuffer,
-        mimeType,
-        filename: `image.${filenameExt}`,
-      };
-    }
-
-    const resizedBuffer = await image
-      .resize(AOS_MAX_RESOLUTION, AOS_MAX_RESOLUTION, {
-        fit: "inside",
-        withoutEnlargement: true,
-      })
-      .toBuffer();
-
-    return {
-      buffer: resizedBuffer,
-      mimeType,
-      filename: `image.${filenameExt}`,
-    };
+    metadata = await sharp.default(imageBuffer, { limitInputPixels: false }).metadata();
   } catch (error) {
-    logger.warn("aos_image_preprocess_failed", error);
-    return { buffer: imageBuffer, mimeType: "image/png", filename: "image.png" };
+    // AOS also accepts BMP/RAW/RGB formats that Sharp cannot identify.
+    logger.warn("aos_image_metadata_unavailable", error);
+    return { buffer: imageBuffer, mimeType: "application/octet-stream", filename: "image" };
   }
+
+  const { width, height } = metadata;
+  if (width && height && (width > AOS_MAX_RESOLUTION || height > AOS_MAX_RESOLUTION)) {
+    throw new RmbgServiceError(
+      `抠图参考图分辨率超限（${width}×${height} 像素），当前 AOS 上游要求宽、高均不超过 ${AOS_MAX_RESOLUTION} 像素。`,
+      400
+    );
+  }
+
+  const format = metadata.format || "";
+  if (["gif", "svg", "heif", "avif", "jp2", "jxl"].includes(format)) {
+    const name = format === "heif" ? "HEIF/AVIF" : format.toUpperCase();
+    throw new RmbgServiceError(`抠图参考图格式不支持（${name}），当前 AOS 上游不支持此格式。`, 400);
+  }
+  const ext = format === "jpeg" ? "jpg" : format;
+  return {
+    buffer: imageBuffer,
+    mimeType: format ? `image/${format}` : "application/octet-stream",
+    filename: ext ? `image.${ext}` : "image",
+  };
 }
 
 async function processWithRMBG(
@@ -369,20 +380,38 @@ async function processWithAosSegmentation(
     foregroundType?: "" | "person" | "object" | "stamp";
     crop?: 0 | 1;
     format?: "png" | "jpg";
+    inputImageUrl?: string | null;
+    requestId?: string;
   }
 ): Promise<{ success: boolean; imageBuffer?: Buffer; processing_time?: number; error?: string }> {
   const startTime = Date.now();
   const baseUrl = (config.apiBaseUrl || "https://techsz.aoscdn.com").replace(/\/+$/, "");
   const createUrl = `${baseUrl}/api/tasks/visual/segmentation`;
   const headers = { "X-API-KEY": config.apiKey };
+  let stage = "create";
+  let providerTaskId: string | undefined;
+  const sourceImage = await prepareImageForAos(imageBuffer);
 
   try {
-    const normalizedImage = await prepareImageForAos(imageBuffer);
     const createForm = new FormData();
-    const imageBlob = new Blob([new Uint8Array(normalizedImage.buffer)], {
-      type: normalizedImage.mimeType,
-    });
-    createForm.append("image_file", imageBlob, normalizedImage.filename);
+    let publicSourceUrl: string | null = null;
+    if (config.inputImageUrl && imageBuffer.length <= AOS_MAX_URL_INPUT_BYTES) {
+      try {
+        const source = new URL(config.inputImageUrl);
+        const cdn = new URL(process.env.NEXT_PUBLIC_CANVAS_CDN_ORIGIN || "");
+        if (["http:", "https:"].includes(source.protocol) && source.hostname === cdn.hostname) {
+          publicSourceUrl = source.toString();
+        }
+      } catch { /* Uploaded files and other sources use the file API. */ }
+    }
+    if (publicSourceUrl) {
+      createForm.append("image_url", publicSourceUrl);
+    } else {
+      const imageBlob = new Blob([new Uint8Array(sourceImage.buffer)], {
+        type: sourceImage.mimeType,
+      });
+      createForm.append("image_file", imageBlob, sourceImage.filename);
+    }
     createForm.append("sync", "0");
     createForm.append("return_type", "1");
     createForm.append("output_type", "2");
@@ -392,6 +421,9 @@ async function processWithAosSegmentation(
       createForm.append("type", config.foregroundType);
     }
 
+    const createStartedAt = Date.now();
+    logger.info("aos_task_create_started", { requestId: config.requestId, sourceMode: publicSourceUrl ? "url" : "file", inputBytes: imageBuffer.length, uploadBytes: publicSourceUrl ? 0 : sourceImage.buffer.length });
+
     const createResponse = await withTimeout(
       (signal) =>
         fetch(createUrl, {
@@ -411,28 +443,37 @@ async function processWithAosSegmentation(
       });
       return {
         success: false,
-        error: `AOS任务创建失败: ${createPayload?.message || createResponse.statusText}`,
+        error: `AOS任务创建失败（HTTP ${createResponse.status}）: ${createPayload?.message || createResponse.statusText}`,
       };
     }
 
     const taskId = createPayload.data.task_id as string;
+    providerTaskId = taskId;
+    logger.info("aos_task_created", { requestId: config.requestId, taskId, createMs: Date.now() - createStartedAt });
     const taskUrl = `${createUrl}/${taskId}`;
     const maxPollCount = 60;
 
     for (let pollCount = 0; pollCount < maxPollCount; pollCount += 1) {
       await sleep(1000);
+      stage = "poll";
 
-      const pollResponse = await withTimeout(
-        (signal) =>
-          fetch(taskUrl, {
+      const pollResponse = await readAosResult(
+        async (signal) => {
+          const response = await fetch(taskUrl, {
             method: "GET",
             headers,
             signal,
-          }),
+          });
+          const payload = await response.json().catch((error) => {
+            if (error instanceof Error && error.name !== "SyntaxError") throw error;
+            return null;
+          });
+          return { ok: response.ok, status: response.status, statusText: response.statusText, payload };
+        },
         AOS_POLL_TIMEOUT_MS
       );
 
-      const pollPayload = await pollResponse.json().catch(() => null);
+      const pollPayload = pollResponse.payload;
       if (!pollResponse.ok || !pollPayload?.data) {
         logger.warn("aos_task_poll_failed", {
           hasPayload: pollPayload != null,
@@ -440,7 +481,7 @@ async function processWithAosSegmentation(
         });
         return {
           success: false,
-          error: `AOS任务查询失败: ${pollPayload?.message || pollResponse.statusText}`,
+          error: `AOS任务查询失败（HTTP ${pollResponse.status}，任务 ${taskId}）: ${pollPayload?.message || pollResponse.statusText}`,
         };
       }
 
@@ -454,12 +495,15 @@ async function processWithAosSegmentation(
           pollCount,
           taskId,
         });
-        const imageResponse = await withTimeout(
-          (signal) =>
-            fetch(imageUrl, {
+        stage = "download";
+        const imageResponse = await readAosResult(
+          async (signal) => {
+            const response = await fetch(imageUrl, {
               method: "GET",
               signal,
-            }),
+            });
+            return { ok: response.ok, status: response.status, statusText: response.statusText, buffer: response.ok ? Buffer.from(await response.arrayBuffer()) : null };
+          },
           AOS_DOWNLOAD_TIMEOUT_MS
         );
 
@@ -470,11 +514,11 @@ async function processWithAosSegmentation(
           });
           return {
             success: false,
-            error: `AOS结果下载失败: ${imageResponse.status} ${imageResponse.statusText}`,
+            error: `AOS结果下载失败（HTTP ${imageResponse.status}，任务 ${taskId}）: ${imageResponse.statusText}`,
           };
         }
 
-        const resultBuffer = Buffer.from(await imageResponse.arrayBuffer());
+        const resultBuffer = imageResponse.buffer!;
         return {
           success: true,
           imageBuffer: resultBuffer,
@@ -490,19 +534,30 @@ async function processWithAosSegmentation(
         });
         return {
           success: false,
-          error: `AOS任务失败: ${errMessage || stateDetail || pollPayload?.message || "状态异常"}`,
+          error: `AOS任务失败（状态 ${state}，任务 ${taskId}）: ${errMessage || stateDetail || pollPayload?.message || "未提供详情"}`,
         };
       }
     }
 
-    logger.warn("aos_task_timeout", { maxPollCount });
-    return { success: false, error: "AOS任务超时（最多60秒）" };
+    logger.warn("aos_task_timeout", { requestId: config.requestId, taskId, maxPollCount });
+    return { success: false, error: `AOS查询任务超时，结果尚未确认（任务 ${taskId}）` };
   } catch (error) {
     if (error instanceof Error && error.name === "AbortError") {
-      return { success: false, error: "AOS请求超时，请稍后重试" };
+      logger.warn("aos_request_timeout", { requestId: config.requestId, stage, taskId: providerTaskId, inputBytes: imageBuffer.length });
+      const message = stage === "create"
+        ? "AOS创建任务超时（120秒），结果尚未确认"
+        : stage === "poll"
+          ? `AOS查询任务超时，结果尚未确认（任务 ${providerTaskId}）`
+          : `AOS结果下载超时，任务已完成（任务 ${providerTaskId}）`;
+      return { success: false, error: message };
     }
-    logger.warn("aos_provider_request_error", error);
-    return { success: false, error: error instanceof Error ? error.message : "未知错误" };
+    logger.warn("aos_provider_request_error", error, { requestId: config.requestId, stage, taskId: providerTaskId });
+    const detail = error instanceof Error ? error.message : "未知错误";
+    return { success: false, error: stage === "create"
+      ? `AOS创建任务连接失败，结果尚未确认：${detail}`
+      : stage === "poll"
+        ? `AOS查询任务连接失败，结果尚未确认（任务 ${providerTaskId}）：${detail}`
+        : `AOS结果下载连接失败，任务已完成（任务 ${providerTaskId}）：${detail}` };
   }
 }
 
@@ -601,6 +656,7 @@ export async function executeRmbgJob(
   params: ExecuteRmbgJobParams
 ): Promise<ExecuteRmbgJobResult> {
   const {
+    requestId = crypto.randomUUID(),
     userId,
     imageBuffer,
     imageBase64 = imageBuffer.toString("base64"),
@@ -609,11 +665,13 @@ export async function executeRmbgJob(
     chatId = null,
     messageId = null,
     skipGallerySave = false,
+    inputImageUrl = null,
     sourceImageUrl = null,
   } = params;
 
   const { provider, config } = await getValidatedRmbgConfig();
   logger.info("job_started", {
+    requestId,
     hasChatId: Boolean(chatId),
     hasMessageId: Boolean(messageId),
     hasSourceImageUrl: Boolean(sourceImageUrl),
@@ -657,6 +715,8 @@ export async function executeRmbgJob(
       foregroundType: foregroundType ?? config.aosForegroundType ?? "",
       crop: config.aosCrop === 1 ? 1 : 0,
       format: config.aosFormat === "jpg" ? "jpg" : "png",
+      inputImageUrl,
+      requestId,
     });
 
     if (!result.success || !result.imageBuffer) {
@@ -793,6 +853,7 @@ export async function executeRmbgJob(
       }
 
       logger.info("job_completed", {
+        requestId,
         generatedImageId: savedImage.id,
         mediaAssetId,
         processingSeconds: Number(processingTime.toFixed(2)),
@@ -815,6 +876,7 @@ export async function executeRmbgJob(
   }
 
   logger.info("job_completed", {
+    requestId,
     processingSeconds: Number(processingTime.toFixed(2)),
     provider,
     savedToGallery: false,

lib/ai/runtime/direct-agent-image-edit-executor.ts

@@ -516,6 +516,7 @@ export async function executeDirectAgentImageEditTool(
     const result = await executeRmbgJob({
       userId: params.userId,
       imageBuffer: sourceBuffer,
+      inputImageUrl: params.sourceImageUrl,
       prompt: params.requestTextContent || "抠图处理",
       chatId: params.chatId,
       messageId: params.messageId,

lib/canvas/capabilities/headless-executor.ts

@@ -128,8 +128,10 @@ async function executeForTarget(
   if (command.capabilityId === "image.remove_background") {
     const imageBuffer = await fetchImageBufferFromUrl(target.sourceImageUrl);
     const result = await executeRmbgJob({
+      requestId: command.requestId,
       userId: params.userId,
       imageBuffer,
+      inputImageUrl: target.sourceImageUrl,
       sourceImageUrl: target.sourceImageUrl,
       prompt: prompt || "抠图处理",
       skipGallerySave: false,

lib/canvas/operations/rmbg.ts

@@ -9,9 +9,11 @@ import {
 import { getPointsSystemConfig } from "@/lib/db/queries";
 import { prepareFeaturePointsCharge } from "@/lib/points/feature-charge";
 import { getImageToolCreditCost } from "@/lib/points/config";
+import { formatRequestFailure, getRequestFailureDetails } from "@/lib/request-error";
 
 
 export async function executeRemoveBackgroundPOST(request: Request, trustedUserId: string) {
+  const requestId = request.headers.get("x-request-id") || crypto.randomUUID();
   try {
     const session = { user: { id: trustedUserId } };
     if (!session?.user?.id) {
@@ -27,6 +29,7 @@ export async function executeRemoveBackgroundPOST(request: Request, trustedUserI
     let messageId: string | null = null;
     let skipGallerySave = false;
     let sourceImageUrl: string | null = null;
+    let inputImageUrl: string | null = null;
 
     if (contentType.includes("application/json")) {
       const body = await request.json();
@@ -40,6 +43,7 @@ export async function executeRemoveBackgroundPOST(request: Request, trustedUserI
 
       if (imageUrl) {
         sourceImageUrl = String(imageUrl);
+        inputImageUrl = sourceImageUrl;
         imageBuffer = await fetchImageBufferFromUrl(sourceImageUrl);
       } else if (body.image_base64) {
         imageBase64 = String(body.image_base64);
@@ -94,6 +98,7 @@ export async function executeRemoveBackgroundPOST(request: Request, trustedUserI
     }
 
     const result = await executeRmbgJob({
+      requestId,
       userId: session.user.id,
       imageBuffer,
       imageBase64,
@@ -101,6 +106,7 @@ export async function executeRemoveBackgroundPOST(request: Request, trustedUserI
       chatId,
       messageId,
       skipGallerySave,
+      inputImageUrl,
       sourceImageUrl,
     });
 
@@ -114,22 +120,29 @@ export async function executeRemoveBackgroundPOST(request: Request, trustedUserI
 
     return NextResponse.json({
       success: true,
+      requestId,
       ...result,
     });
   } catch (error) {
     if (error instanceof RmbgServiceError) {
+      const failure = getRequestFailureDetails(error);
       return NextResponse.json(
         {
-          error: error.message,
+          success: false,
+          error: formatRequestFailure(failure, requestId),
           detail: error.detail || error.message,
+          code: failure.code,
+          failure,
+          requestId,
         },
         { status: error.status }
       );
     }
 
     console.error("[RMBG API] 处理错误:", error);
+    const failure = getRequestFailureDetails(error, "抠图请求未能完成");
     return NextResponse.json(
-      { error: "服务器内部错误", detail: error instanceof Error ? error.message : "未知错误" },
+      { success: false, error: formatRequestFailure(failure, requestId), detail: error instanceof Error ? error.message : "未知错误", code: failure.code, failure, requestId },
       { status: 500 }
     );
   }

lib/canvas/scale-adjust-product-lock.ts

@@ -40,22 +40,6 @@ function clamp(value: number, min: number, max: number) {
   return Math.min(max, Math.max(min, value));
 }
 
-async function executeScaleAdjustRmbgJob(
-  params: Parameters<typeof executeRmbgJob>[0]
-) {
-  let lastError: unknown;
-  for (let attempt = 1; attempt <= 3; attempt += 1) {
-    try {
-      return await executeRmbgJob(params);
-    } catch (error) {
-      lastError = error;
-      if (attempt === 3) break;
-      await new Promise((resolve) => setTimeout(resolve, attempt * 800));
-    }
-  }
-  throw lastError;
-}
-
 function rectToPixelBox(
   rect: CanvasScaleAdjustRect,
   sourceWidth: number,
@@ -220,7 +204,7 @@ async function buildPersonExclusionAlpha(params: {
   userId: string;
 }) {
   try {
-    const person = await executeScaleAdjustRmbgJob({
+    const person = await executeRmbgJob({
       foregroundType: "person",
       imageBuffer: params.sourceBuffer,
       prompt: "比例调整人物保护蒙版",
@@ -330,7 +314,7 @@ export async function buildScaleAdjustProductLockAssets(params: {
       .png({ compressionLevel: 6 })
       .toBuffer();
     semanticSourceCropBuffers.push(cropBuffer);
-    const subject = await executeScaleAdjustRmbgJob({
+    const subject = await executeRmbgJob({
       imageBuffer: cropBuffer,
       prompt: "比例调整完整产品蒙版",
       skipGallerySave: true,

lib/request-error.ts

@@ -228,9 +228,71 @@ export function getRequestFailureDetails(
   const status = getRequestErrorStatus(error);
   const detail = (code: string, message: string, recommendation: string, outcome: "failed" | "unknown" = "failed") =>
     ({ code, message, recommendation, outcome });
+  if (/抠图参考图文件大小超限/.test(text)) {
+    return detail("RMBG_INPUT_TOO_LARGE", getRequestErrorMessage(error) || "抠图参考图超过 AOS 的 50 MB 上限。", "请手动压缩至 50 MB 以内后重新提交。本次未提交上游抠图任务。");
+  }
+  if (/抠图参考图分辨率超限/.test(text)) {
+    return detail("RMBG_INPUT_RESOLUTION_EXCEEDED", getRequestErrorMessage(error) || "抠图参考图超过 AOS 的 4096 像素上限。", "请手动将宽、高均调整至 4096 像素以内，再重新提交。本次未提交上游抠图任务。");
+  }
+  if (/抠图参考图格式不支持/.test(text)) {
+    return detail("RMBG_INPUT_FORMAT_UNSUPPORTED", getRequestErrorMessage(error) || "AOS 不支持此参考图格式。", "请导出为 JPG、PNG 或 WebP 后重新提交。本次未提交上游抠图任务。");
+  }
+  const aosResolution = text.match(/(?:resolution excess,\s*width=(\d+),\s*height=(\d+)|图片分辨率超限（(\d+)x(\d+)）)/i);
+  if (aosResolution) {
+    return detail("RMBG_PROVIDER_RESOLUTION_EXCEEDED", `AOS 拒绝了参考图：分辨率为 ${aosResolution[1] || aosResolution[3]}×${aosResolution[2] || aosResolution[4]} 像素，宽、高均须不超过 4096 像素。`, "请手动调整尺寸后重新提交。");
+  }
+  if (/AOS.*invalid file|图片文件无法识别/i.test(text)) {
+    return detail("RMBG_PROVIDER_INVALID_FILE", "AOS 无法识别参考图，文件可能损坏或格式不受支持。", "请确认原图可以正常打开，并导出为 JPG、PNG 或 WebP 后重新提交。");
+  }
+  const aosState = text.match(/AOS任务失败（状态 (-\d+)，/);
+  if (aosState) {
+    const state = Number(aosState[1]);
+    if (state === -5) return detail("RMBG_PROVIDER_URL_TOO_LARGE", "AOS 拒绝读取参考图：链接取图大小超过上游的 30 MB 上限。", "请联系管理员核对文件提交方式；不要连续点击。上游文件上传接口允许最大 50 MB。");
+    if (state === -7) return detail("RMBG_PROVIDER_INVALID_FILE", "AOS 无法识别参考图，文件可能损坏或格式不受支持。", "请确认原图可以正常打开，并导出为 JPG、PNG 或 WebP 后重新提交。");
+    if (state === -3) return detail("RMBG_PROVIDER_SOURCE_DOWNLOAD_FAILED", "AOS 下载参考图失败，未能读取原图。", "请确认原图链接可打开；若原图正常，请联系管理员检查上游取图线路，并提供请求编号。");
+    if (state === -2) return detail("RMBG_PROVIDER_RESULT_STORAGE_FAILED", "AOS 已完成处理，但上游保存结果图片失败。", "请联系管理员核对原任务结果，避免立即重复抠图。", "unknown");
+    if (state === -8) return detail("RMBG_PROVIDER_PROCESSING_TIMEOUT", "AOS 抠图处理超时，上游已返回失败状态。", "请稍后重试；若持续发生，请联系管理员并提供请求编号。");
+    if (state === -11) return detail("RMBG_PROVIDER_EMPTY_RESULT", "AOS 抠图结果为空，未能得到有效主体。", "请检查图片中的主体是否清晰，尝试使用主体更明确的图片。");
+    if ([-17, -16, -14, -10].includes(state)) return detail("RMBG_PROVIDER_INPUT_REJECTED", `AOS 拒绝处理参考图，图片内容未通过上游检查（状态 ${state}）。`, "请更换符合上游要求的参考图；如认为判断有误，请联系管理员核对请求编号。");
+    if (state === -15) return detail("RMBG_PROVIDER_RESOURCE_UNAVAILABLE", "AOS 处理资源不足，未能完成本次抠图。", "请稍后再试；持续失败时联系管理员检查上游服务。");
+    return detail("RMBG_PROVIDER_TASK_FAILED", getRequestErrorMessage(error) || `AOS 抠图任务失败（状态 ${state}）。`, "请联系管理员并提供请求编号，核对上游任务详情。");
+  }
+  if (/AOS任务创建失败（HTTP 413）/.test(text)) {
+    return detail("RMBG_PROVIDER_FILE_TOO_LARGE", "AOS 拒绝了参考图：文件超过上游大小限制（文件上传最大 50 MB）。", "请手动压缩文件后重新提交；若文件已小于限制，请联系管理员核对上游返回。");
+  }
+  if (/AOS任务创建失败（HTTP (400|401|404)）/.test(text)) {
+    return detail("RMBG_PROVIDER_REQUEST_REJECTED", getRequestErrorMessage(error) || "AOS 拒绝了抠图请求。", "请联系管理员核对上游参数、服务权限及接口配置，并提供请求编号。");
+  }
+  if (/AOS任务创建失败（HTTP (200|5\d\d)）/.test(text)) {
+    return detail("RMBG_PROVIDER_CREATE_UNCONFIRMED", getRequestErrorMessage(error) || "AOS 未能确认抠图任务是否创建成功。", "请联系管理员核对原请求，避免连续提交造成重复处理。", "unknown");
+  }
+  const aosReadFailure = text.match(/AOS(任务查询|结果下载)失败（HTTP (\d+)/);
+  if (aosReadFailure) {
+    return aosReadFailure[1] === "任务查询"
+      ? detail("RMBG_PROVIDER_POLL_FAILED", `AOS 查询抠图任务失败（HTTP ${aosReadFailure[2]}），原任务结果尚未确认。`, "请联系管理员核对原任务，不要重复提交。", "unknown")
+      : detail("RMBG_PROVIDER_RESULT_DOWNLOAD_FAILED", `抠图已完成，但结果图片下载失败（HTTP ${aosReadFailure[2]}）。`, "请联系管理员按请求编号取回原任务结果，避免重复抠图。", "unknown");
+  }
   if (isGatewayResponseTimeout(error)) {
     return detail("RESULT_UNCONFIRMED", "模型服务响应超时（HTTP 524），生成结果尚未确认。", "请先查看历史记录，避免重复提交。", "unknown");
   }
+  if (/AOS创建任务超时/.test(text)) {
+    return detail("RMBG_CREATE_TIMEOUT", "抠图服务创建任务超时（120秒），结果尚未确认。", "请先查看原任务或联系管理员核对；不要连续点击，以免重复处理。", "unknown");
+  }
+  if (/AOS创建任务连接失败/.test(text)) {
+    return detail("RMBG_CREATE_CONNECTION_FAILED", "抠图服务创建任务时连接中断，结果尚未确认。", "请先查看原任务或联系管理员核对；不要连续点击，以免重复处理。", "unknown");
+  }
+  if (/AOS查询任务连接失败/.test(text)) {
+    return detail("RMBG_POLL_CONNECTION_FAILED", "抠图服务查询任务时连接中断，原任务可能仍在处理。", "请保留当前页面并联系管理员核对原任务，避免重新提交。", "unknown");
+  }
+  if (/AOS查询任务超时/.test(text)) {
+    return detail("RMBG_POLL_TIMEOUT", "抠图服务查询任务超时，原任务可能仍在处理。", "请保留当前页面并联系管理员核对原任务，避免重新提交。", "unknown");
+  }
+  if (/AOS结果下载连接失败/.test(text)) {
+    return detail("RMBG_RESULT_DOWNLOAD_CONNECTION_FAILED", "抠图已完成，但结果图片传输中断。", "请联系管理员按请求编号取回原任务结果，避免重复抠图。", "unknown");
+  }
+  if (/AOS结果下载超时/.test(text)) {
+    return detail("RMBG_RESULT_DOWNLOAD_TIMEOUT", "抠图已完成，但结果图片下载超时。", "请联系管理员按请求编号取回原任务结果，避免重复抠图。", "unknown");
+  }
   if ((isRecord(error) && error.providerOutcomeUnknown === true) || /结果(?:尚)?未确认|结果暂未确认|request_outcome_unknown|任务执行中断|may still be running/i.test(text)) {
     return detail("RESULT_UNCONFIRMED", "任务结果尚未确认，可能仍在处理。", "请先查看原任务或历史记录；持续没有结果时联系管理员，避免重复生成。", "unknown");
   }

lib/scene-fusion/preprocess-product.ts

@@ -0,0 +1,37 @@
+import { executeRemoveBackgroundPOST } from "@/lib/canvas/operations/rmbg";
+import { createLogger } from "@/lib/observability/logger";
+
+const logger = createLogger("scene-fusion");
+
+export async function preprocessProductImageWithRmbg(params: {
+  request: Request;
+  requestId: string;
+  userId: string;
+  productImageUrl: string;
+  preRmbgEnabled: boolean;
+}): Promise<{ productImageUrl: string; usedPreRmbg: boolean; provider?: string; reason?: string }> {
+  const { request, requestId, userId, productImageUrl, preRmbgEnabled } = params;
+  if (!preRmbgEnabled) return { productImageUrl, usedPreRmbg: false, reason: "disabled_by_config" };
+
+  logger.info("pre_rmbg_started", { requestId });
+  try {
+    const response = await executeRemoveBackgroundPOST(new Request(new URL("/api/rmbg", request.url), {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Request-ID": `${requestId}:pre-rmbg` },
+      body: JSON.stringify({ imageUrl: productImageUrl, prompt: "场景裂变预处理-抠图", skipGallerySave: true }),
+    }), userId);
+    const payload = await response.json();
+    if (!response.ok) {
+      logger.warn("pre_rmbg_failed", { requestId, status: response.status, code: payload?.failure?.code });
+      return { productImageUrl, usedPreRmbg: false, reason: String(payload?.error || `request_failed_${response.status}`) };
+    }
+    const cleanedUrl = String(payload?.original_url || payload?.thumbnail_url || "").trim();
+    if (!cleanedUrl || cleanedUrl === productImageUrl) {
+      return { productImageUrl, usedPreRmbg: false, reason: cleanedUrl ? "same_as_source" : "empty_result" };
+    }
+    return { productImageUrl: cleanedUrl, usedPreRmbg: true, provider: String(payload?.provider || "unknown") };
+  } catch (error) {
+    logger.warn("pre_rmbg_failed", error, { requestId });
+    return { productImageUrl, usedPreRmbg: false, reason: error instanceof Error ? error.message : "exception" };
+  }
+}

playwright.helpers.config.ts

@@ -3,6 +3,7 @@ import { defineConfig } from "@playwright/test";
 export default defineConfig({
   testDir: "./tests",
   testMatch: [
+    /routes\/rmbg-delivery\.test\.ts/,
     /routes\/legacy-oss-recovery\.test\.ts/,
     /routes\/retired-storage\.test\.ts/,
     /routes\/original-image-download\.test\.ts/,

services/canvas/index.ts

@@ -95,18 +95,19 @@ function normalizeRevisionText(value: unknown) {
   return String(value || "").trim();
 }
 
-function syncCanvasStoreRevisionFromUpdatedAt(updatedAt: unknown): void {
+function syncCanvasStoreRevisionFromUpdatedAt(projectId: string, updatedAt: unknown): void {
   if (typeof window === "undefined") return;
   const revision = normalizeRevisionText(updatedAt);
   if (!revision) return;
-  useCanvasStore.getState().setCanvasRevision(revision, revision);
+  const current = useCanvasStore.getState();
+  if (current.projectId === projectId) current.setCanvasRevision(revision, revision);
 }
 
 function syncCanvasStoreRevisionFromProject(
-  project?: { canvasData?: CanvasState | null; updatedAt?: Date | string } | null
+  project?: { id: string; canvasData?: CanvasState | null; updatedAt?: Date | string } | null
 ): void {
   if (!project?.canvasData) return;
-  syncCanvasStoreRevisionFromUpdatedAt(project.updatedAt);
+  syncCanvasStoreRevisionFromUpdatedAt(project.id, project.updatedAt);
 }
 
 export interface NormalizedCropRect {
@@ -203,9 +204,6 @@ export const canvasService = {
     try {
       const response = await fetch(`/api/canvas/${id}`);
       const data = await response.json();
-      if (data?.success) {
-        syncCanvasStoreRevisionFromProject(data.data);
-      }
       return data;
     } catch (error) {
       return { success: false, error: '获取画布失败' };
@@ -335,7 +333,7 @@ export const canvasService = {
         };
       }
       if (data?.success) {
-        syncCanvasStoreRevisionFromUpdatedAt(data?.data?.updatedAt);
+        syncCanvasStoreRevisionFromUpdatedAt(id, data?.data?.updatedAt);
       }
       return data as ApiResponse;
     } catch (error) {

tests/helpers/canvas-download-server-loader.ts

@@ -53,6 +53,7 @@ export function serverLoader(mocks: Record<string, unknown>, env: Record<string,
       ReadableStream,
       Headers,
       Blob,
+      FormData,
       Request,
       Date: mocks.Date || Date,
       document: mocks.document,

tests/routes/canvas-chat-helpers.test.ts

@@ -808,6 +808,7 @@ test.describe("canvas chat pure helpers", () => {
   });
 
   test("canvas service save uses store revision fallback when options are omitted", async () => {
+    useCanvasStore.getState().setProject("11111111-1111-4111-8111-111111111111");
     const canvasData = {
       nodes: [],
       edges: [],
@@ -885,7 +886,7 @@ test.describe("canvas chat pure helpers", () => {
     });
   });
 
-  test("canvas service keeps store revision aligned after project load and save", async () => {
+  test("canvas revision advances after applying the fetched snapshot and saving the current project", async () => {
     const canvasData = {
       nodes: [],
       edges: [],
@@ -915,6 +916,7 @@ test.describe("canvas chat pure helpers", () => {
       },
     ];
 
+    useCanvasStore.getState().setProject("11111111-1111-4111-8111-111111111111");
     useCanvasStore.getState().setCanvasRevision(null, null);
     Object.defineProperty(globalThis, "window", {
       configurable: true,
@@ -929,7 +931,11 @@ test.describe("canvas chat pure helpers", () => {
       }) as Response) as typeof fetch;
 
     try {
-      await canvasService.getProject("11111111-1111-4111-8111-111111111111");
+      const result = await canvasService.getProject("11111111-1111-4111-8111-111111111111");
+      expect(useCanvasStore.getState().canvasRevision).toBeNull();
+      useCanvasStore.getState().loadCanvas(result.data!.canvasData);
+      const revision = String(result.data!.updatedAt);
+      useCanvasStore.getState().setCanvasRevision(revision, revision);
       expect(useCanvasStore.getState().canvasRevision).toBe(
         "2026-06-22T00:01:00.000Z"
       );

tests/routes/canvas-scale-adjust-intent.test.ts

@@ -236,8 +236,6 @@ test.describe("canvas scale adjust product lock", () => {
     const rmbg = readSource("lib/ai/rmbg/service.ts");
 
     expect(productLock).toContain('foregroundType: "person"');
-    expect(productLock).toContain("attempt <= 3");
-    expect(productLock).toContain("executeScaleAdjustRmbgJob({");
     expect(productLock).toContain("regionPersonExclusionAlpha");
     expect(productLock).toContain("overlapPixelCount >= overlapLimit");
     expect(productLock).toContain("目标产品被人物遮挡");

tests/routes/canvas-toolbar-capability.test.ts

@@ -4,6 +4,7 @@ import { executeCanvasToolbarCapability } from "@/lib/client/canvas-toolbar-capa
 import { createCanvasCapabilityClientCommand } from "@/lib/canvas/capabilities/client-command";
 import { useCanvasStore } from "@/store/canvas";
 import { canvasService } from "@/services/canvas";
+import { formatRequestFailure, getRequestFailureDetails } from "@/lib/request-error";
 
 const originalFetch = globalThis.fetch;
 const node = (id: string) => ({ id, type: "image", position: { x: 0, y: 0 },
@@ -86,6 +87,22 @@ test("a lost submission response polls the original task and never resubmits", a
   expect(useCanvasStore.getState().nodes.map(n => n.id)).toEqual(["source", "result"]);
 });
 
+test("a recovered matting rejection shows its dimensions and advice without changing the canvas or resubmitting", async () => {
+  const submitted = createCanvasCapabilityClientCommand({ projectId: "project-a", capabilityId: "image.remove_background", nodeIds: ["source"], source: "toolbar" });
+  const failure = getRequestFailureDetails("抠图参考图分辨率超限（5056×3392 像素），当前 AOS 上游要求宽、高均不超过 4096 像素。");
+  const message = formatRequestFailure(failure, submitted.requestId);
+  let posts = 0;
+  globalThis.fetch = (async (url, options) => {
+    if (options?.method === "POST") { posts++; return new Response(null, { status: 504 }); }
+    expect(String(url)).toContain(encodeURIComponent(submitted.requestId));
+    return Response.json({ success: true, task: { status: "failed", failure, error: message } });
+  }) as typeof fetch;
+  await expect(executeCanvasToolbarCapability(submitted)).rejects.toThrow(message);
+  expect(posts).toBe(1);
+  expect(useCanvasStore.getState().nodes.map(n => n.id)).toEqual(["source"]);
+  expect(useCanvasStore.getState().canvasRevision).toBe("r1");
+});
+
 test("switching projects during processing does not load the old result into the new project", async () => {
   globalThis.fetch = (async (url) => {
     if (String(url).endsWith("/capabilities")) {
@@ -119,6 +136,71 @@ test("metadata changes never adopt an unseen remote canvas revision", async () =
   expect(useCanvasStore.getState().canvasRevision).toBe("r1");
 });
 
+test("reading a result without applying it cannot authorize an old snapshot to overwrite the result", async () => {
+  const previousWindow = Object.getOwnPropertyDescriptor(globalThis, "window");
+  Object.defineProperty(globalThis, "window", { configurable: true, value: {} });
+  let remoteNodes = [node("source"), node("result")];
+  globalThis.fetch = (async (_url, options) => {
+    if (options?.method === "PUT") {
+      const body = JSON.parse(String(options.body));
+      if (body.baseCanvasRevision !== "r2") return Response.json({ success: false, error: "画布已更新" }, { status: 409 });
+      remoteNodes = body.canvasData.nodes;
+      return Response.json({ success: true, data: { updatedAt: "r3" } });
+    }
+    return Response.json({ success: true, data: { id: "project-a", updatedAt: "r2", canvasData: { nodes: remoteNodes, edges: [] } } });
+  }) as typeof fetch;
+  try {
+    await canvasService.getProject("project-a");
+    const saved = await canvasService.saveCanvasState("project-a", useCanvasStore.getState().getCanvasState());
+    expect(saved).toMatchObject({ success: false, status: 409 });
+    expect(remoteNodes.map(n => n.id)).toEqual(["source", "result"]);
+    expect(useCanvasStore.getState().canvasRevision).toBe("r1");
+  } finally {
+    if (previousWindow) Object.defineProperty(globalThis, "window", previousWindow);
+    else Reflect.deleteProperty(globalThis, "window");
+  }
+});
+
+test("a delayed read cannot change the revision of a newly selected project", async () => {
+  const previousWindow = Object.getOwnPropertyDescriptor(globalThis, "window");
+  Object.defineProperty(globalThis, "window", { configurable: true, value: {} });
+  let complete!: (response: Response) => void;
+  globalThis.fetch = (() => new Promise<Response>(resolve => { complete = resolve; })) as typeof fetch;
+  try {
+    const pending = canvasService.getProject("project-a");
+    useCanvasStore.getState().setProject("project-b");
+    useCanvasStore.getState().loadCanvas({ nodes: [node("other") as any], edges: [] });
+    useCanvasStore.getState().setCanvasRevision("r9", "r9");
+    complete(Response.json({ success: true, data: { id: "project-a", updatedAt: "r2", canvasData: { nodes: [node("result")], edges: [] } } }));
+    await pending;
+    expect(useCanvasStore.getState().canvasRevision).toBe("r9");
+    expect(useCanvasStore.getState().nodes.map(n => n.id)).toEqual(["other"]);
+  } finally {
+    if (previousWindow) Object.defineProperty(globalThis, "window", previousWindow);
+    else Reflect.deleteProperty(globalThis, "window");
+  }
+});
+
+test("a delayed save cannot change the revision of a newly selected project", async () => {
+  const previousWindow = Object.getOwnPropertyDescriptor(globalThis, "window");
+  Object.defineProperty(globalThis, "window", { configurable: true, value: {} });
+  let complete!: (response: Response) => void;
+  globalThis.fetch = (() => new Promise<Response>(resolve => { complete = resolve; })) as typeof fetch;
+  try {
+    const pending = canvasService.saveCanvasState("project-a", useCanvasStore.getState().getCanvasState());
+    useCanvasStore.getState().setProject("project-b");
+    useCanvasStore.getState().loadCanvas({ nodes: [node("other") as any], edges: [] });
+    useCanvasStore.getState().setCanvasRevision("r9", "r9");
+    complete(Response.json({ success: true, data: { updatedAt: "r2" } }));
+    await pending;
+    expect(useCanvasStore.getState().canvasRevision).toBe("r9");
+    expect(useCanvasStore.getState().nodes.map(n => n.id)).toEqual(["other"]);
+  } finally {
+    if (previousWindow) Object.defineProperty(globalThis, "window", previousWindow);
+    else Reflect.deleteProperty(globalThis, "window");
+  }
+});
+
 test("a result merge conflict retains both the local edit and its original revision", async () => {
   globalThis.fetch = (async (url) => {
     if (String(url).endsWith("/capabilities")) {

tests/routes/rmbg-delivery.test.ts

@@ -0,0 +1,298 @@
+import { expect, test } from "@playwright/test";
+import sharp from "sharp";
+import { serverLoader } from "../helpers/canvas-download-server-loader";
+import { getRequestFailureDetails } from "@/lib/request-error";
+
+const cdn = "https://scqnycdn.jiansun.vip";
+
+function rmbgLoader(fetch: typeof globalThis.fetch, timer?: typeof setTimeout) {
+  return serverLoader({
+    "@/lib/db/queries": { getSystemSetting: async () => ({ value: { provider: "aoscdn", aosApiKey: "test-key" } }) },
+    "@/lib/db": { db: {} },
+    "@/lib/db/schema": { generatedImage: {} },
+    "@/lib/storage/service": { uploadFile: async (name: string) => ({ url: `${cdn}/${name}` }) },
+    fetch,
+    setTimeout: timer || ((callback: () => void, ms: number) => setTimeout(callback, ms <= 2000 ? 0 : ms)),
+  }, { NEXT_PUBLIC_CANVAS_CDN_ORIGIN: cdn })("lib/ai/rmbg/service.ts");
+}
+
+test("AOS uses a public Qiniu original URL without uploading the image file again", async () => {
+  const image = await sharp({ create: { width: 1024, height: 768, channels: 3, background: "#abcdef" } }).png().toBuffer();
+  let creates = 0;
+  const source = `${cdn}/uploads/original.png`;
+  const service = rmbgLoader(async (input, options) => {
+    const url = String(input);
+    if (options?.method === "POST") {
+      creates++;
+      const form = options.body as FormData;
+      expect(form.get("image_url")).toBe(source);
+      expect(form.has("image_file")).toBe(false);
+      expect(form.get("sync")).toBe("0");
+      return Response.json({ data: { task_id: "task-url" } });
+    }
+    if (url.endsWith("/task-url")) return Response.json({ data: { state: 1, image: "https://output.example/image.png" } });
+    return new Response(image, { headers: { "content-type": "image/png" } });
+  });
+  const result = await service.executeRmbgJob({ userId: "test", imageBuffer: image, inputImageUrl: source, sourceImageUrl: source, skipGallerySave: true });
+  expect(creates).toBe(1);
+  expect(result.provider).toBe("aoscdn");
+  expect(result.original_url).toContain(cdn);
+});
+
+test("non-CDN sources upload the original file without changing its bytes or dimensions", async () => {
+  for (const [width, source] of [[4096, "http://127.0.0.1/private.png"], [1000, "https://other.example/image.png"]] as const) {
+    const image = await sharp({ create: { width, height: 20, channels: 3, background: "#abcdef" } }).png().toBuffer();
+    const service = rmbgLoader(async (input, options) => {
+      if (options?.method === "POST") {
+        const form = options.body as FormData;
+        expect(form.has("image_url")).toBe(false);
+        const file = form.get("image_file") as File;
+        const submitted = Buffer.from(await file.arrayBuffer());
+        expect(submitted.equals(image)).toBe(true);
+        expect((await sharp(submitted).metadata()).width).toBe(width);
+        return Response.json({ data: { task_id: "task-file" } });
+      }
+      if (String(input).endsWith("/task-file")) return Response.json({ data: { state: 1, image: "https://output.example/image.png" } });
+      return new Response(image, { headers: { "content-type": "image/png" } });
+    });
+    await service.executeRmbgJob({ userId: "test", imageBuffer: image, inputImageUrl: source, sourceImageUrl: source, skipGallerySave: true });
+  }
+});
+
+test("a cropped input uses its own bytes instead of the original provenance URL", async () => {
+  const original = await sharp({ create: { width: 120, height: 80, channels: 3, background: "#abcdef" } }).png().toBuffer();
+  const cropped = await sharp(original).extract({ left: 20, top: 10, width: 40, height: 20 }).png().toBuffer();
+  let submitted!: FormData;
+  const service = rmbgLoader(async (input, options) => {
+    if (options?.method === "POST") { submitted = options.body as FormData; return Response.json({ data: { task_id: "cropped-task" } }); }
+    if (String(input).endsWith("/cropped-task")) return Response.json({ data: { state: 1, image: "https://output.example/cropped.png" } });
+    return new Response(cropped, { headers: { "content-type": "image/png" } });
+  });
+  await service.executeRmbgJob({ userId: "test", imageBuffer: cropped, sourceImageUrl: `${cdn}/original.png`, skipGallerySave: true });
+  expect(submitted.has("image_url")).toBe(false);
+  const bytes = Buffer.from(await (submitted.get("image_file") as File).arrayBuffer());
+  expect(bytes.equals(cropped)).toBe(true);
+  expect(await sharp(bytes).metadata()).toMatchObject({ width: 40, height: 20 });
+});
+
+test("scale adjustment does not start a new matting job after an unconfirmed result", async () => {
+  let creates = 0;
+  const image = await sharp({ create: { width: 64, height: 64, channels: 3, background: "white" } }).png().toBuffer();
+  const scale = serverLoader({
+    "@/lib/ai/rmbg/service": { executeRmbgJob: async () => { creates++; throw new Error("AOS查询任务超时，结果尚未确认"); } },
+    setTimeout: (fn: () => void) => setTimeout(fn, 0),
+  })("lib/canvas/scale-adjust-product-lock.ts");
+  await expect(scale.buildScaleAdjustProductLockAssets({ userId: "test", sourceBuffer: image, sourceWidth: 64, sourceHeight: 64, sourceImageUrl: `${cdn}/source.png`, regions: [{ index: 0, rect: { x: 0.1, y: 0.1, width: 0.5, height: 0.5 }, targetRect: { x: 0.2, y: 0.2, width: 0.5, height: 0.5 } }] })).rejects.toThrow("结果尚未确认");
+  expect(creates).toBe(1);
+});
+
+test("scene preprocessing invokes matting once even when its result is unconfirmed or the call is interrupted", async () => {
+  for (const interrupted of [false, true]) {
+    let calls = 0, networkCalls = 0;
+    const scene = serverLoader({
+      "@/lib/canvas/operations/rmbg": { executeRemoveBackgroundPOST: async (request: Request, userId: string) => {
+        calls++;
+        expect(userId).toBe("user-a");
+        expect(request.headers.get("x-request-id")).toBe("scene-a:pre-rmbg");
+        expect(await request.json()).toMatchObject({ imageUrl: `${cdn}/source.png`, skipGallerySave: true });
+        if (interrupted) throw new TypeError("fetch failed");
+        return Response.json({ error: "抠图已完成，但结果图片下载失败，请核对原任务。", failure: { outcome: "unknown" } }, { status: 500 });
+      } },
+      fetch: async () => { networkCalls++; throw new Error("Unexpected HTTP resubmission"); },
+    })("lib/scene-fusion/preprocess-product.ts");
+    const result = await scene.preprocessProductImageWithRmbg({ request: new Request("https://example.com/api/scene-fusion"), requestId: "scene-a", userId: "user-a", productImageUrl: `${cdn}/source.png`, preRmbgEnabled: true });
+    expect(result).toMatchObject({ productImageUrl: `${cdn}/source.png`, usedPreRmbg: false });
+    expect({ calls, networkCalls }).toEqual({ calls: 1, networkCalls: 0 });
+  }
+});
+
+test("scene preprocessing retains the disabled setting and delivers a successful original result", async () => {
+  let calls = 0;
+  const scene = serverLoader({ "@/lib/canvas/operations/rmbg": { executeRemoveBackgroundPOST: async () => { calls++; return Response.json({ original_url: `${cdn}/result.png`, provider: "aoscdn" }); } } })("lib/scene-fusion/preprocess-product.ts");
+  const params = { request: new Request("https://example.com/api/scene-fusion"), requestId: "scene-a", userId: "user-a", productImageUrl: `${cdn}/source.png` };
+  expect(await scene.preprocessProductImageWithRmbg({ ...params, preRmbgEnabled: false })).toMatchObject({ usedPreRmbg: false });
+  expect(calls).toBe(0);
+  expect(await scene.preprocessProductImageWithRmbg({ ...params, preRmbgEnabled: true })).toMatchObject({ usedPreRmbg: true, productImageUrl: `${cdn}/result.png` });
+  expect(calls).toBe(1);
+});
+
+test("the standalone matting API returns the limit, recommendation and request ID", async () => {
+  class InputError extends Error { status = 400; }
+  let submitted: any;
+  const operation = serverLoader({
+    "@/lib/ai/rmbg/service": { RmbgServiceError: InputError, fetchImageBufferFromUrl: async () => Buffer.from("original"), executeRmbgJob: async (params: any) => { submitted = params; throw new InputError("抠图参考图分辨率超限（5056×3392 像素），当前 AOS 上游要求宽、高均不超过 4096 像素。"); } },
+    "@/lib/db/queries": { getPointsSystemConfig: async () => ({ enabled: false }) },
+    "@/lib/points/feature-charge": { prepareFeaturePointsCharge: async () => ({ ok: true, chargeable: false }) },
+  })("lib/canvas/operations/rmbg.ts");
+  const response = await operation.executeRemoveBackgroundPOST(new Request("https://example.com/api/rmbg", { method: "POST", headers: { "Content-Type": "application/json", "X-Request-ID": "request-a" }, body: JSON.stringify({ imageUrl: `${cdn}/source.png` }) }), "user-a");
+  const result = await response.json();
+  expect(response.status).toBe(400);
+  expect(submitted).toMatchObject({ requestId: "request-a", inputImageUrl: `${cdn}/source.png` });
+  expect(result).toMatchObject({ success: false, requestId: "request-a", failure: { code: "RMBG_INPUT_RESOLUTION_EXCEEDED", outcome: "failed" } });
+  expect(result.error).toContain("5056×3392");
+  expect(result.error).toContain("本次未提交上游抠图任务");
+  expect(result.error).toContain("请求编号：request-a");
+});
+
+test("AOS rejects either oversized dimension before creating a task and gives the exact dimensions", async () => {
+  for (const [width, height] of [[4097, 20], [20, 4097]]) {
+    const image = await sharp({ create: { width, height, channels: 3, background: "white" } }).png().toBuffer();
+    let creates = 0;
+    const service = rmbgLoader(async () => { creates++; throw new Error("Unexpected provider call"); });
+    let failure: Error | undefined;
+    try { await service.executeRmbgJob({ userId: "test", imageBuffer: image, sourceImageUrl: `${cdn}/large.png`, skipGallerySave: true }); }
+    catch (error) { failure = error as Error; }
+    expect(creates).toBe(0);
+    expect(failure).toMatchObject({ status: 400 });
+    expect(failure?.message).toContain(`${width}×${height}`);
+    const details = getRequestFailureDetails(failure);
+    expect(details).toMatchObject({ code: "RMBG_INPUT_RESOLUTION_EXCEEDED", outcome: "failed" });
+    expect(details.message).toContain("4096");
+    expect(details.recommendation).toContain("本次未提交上游抠图任务");
+  }
+});
+
+test("AOS accepts 4096 pixels and 50 MB but rejects a larger file without submitting it", async () => {
+  const output = await sharp({ create: { width: 4096, height: 20, channels: 3, background: "white" } }).png().toBuffer();
+  const boundary = Buffer.alloc(50 * 1024 * 1024);
+  output.copy(boundary);
+  let creates = 0;
+  const service = rmbgLoader(async (input, options) => {
+    if (options?.method === "POST") {
+      creates++;
+      const form = options.body as FormData;
+      expect(form.has("image_url")).toBe(false);
+      expect((form.get("image_file") as File).size).toBe(boundary.length);
+      return Response.json({ data: { task_id: "boundary-task" } });
+    }
+    if (String(input).endsWith("/boundary-task")) return Response.json({ data: { state: 1, image: "https://output.example/image.png" } });
+    return new Response(output, { headers: { "content-type": "image/png" } });
+  });
+  await service.executeRmbgJob({ userId: "test", imageBuffer: boundary, inputImageUrl: `${cdn}/boundary.png`, sourceImageUrl: `${cdn}/boundary.png`, skipGallerySave: true });
+  expect(creates).toBe(1);
+  let failure: Error | undefined;
+  try { await service.executeRmbgJob({ userId: "test", imageBuffer: Buffer.alloc(boundary.length + 1), skipGallerySave: true }); }
+  catch (error) { failure = error as Error; }
+  expect(creates).toBe(1);
+  expect(failure).toMatchObject({ status: 400 });
+  expect(getRequestFailureDetails(failure)).toMatchObject({ code: "RMBG_INPUT_TOO_LARGE", outcome: "failed" });
+  expect(getRequestFailureDetails(failure).message).toContain("50 MB");
+});
+
+test("formats unsupported by AOS are rejected explicitly without converting or submitting", async () => {
+  for (const format of ["gif", "avif"] as const) {
+    const image = await sharp({ create: { width: 16, height: 16, channels: 3, background: "white" } }).toFormat(format).toBuffer();
+    let creates = 0;
+    const service = rmbgLoader(async () => { creates++; throw new Error("Unexpected provider call"); });
+    let failure: Error | undefined;
+    try { await service.executeRmbgJob({ userId: "test", imageBuffer: image, skipGallerySave: true }); }
+    catch (error) { failure = error as Error; }
+    expect(creates).toBe(0);
+    const details = getRequestFailureDetails(failure);
+    expect(details).toMatchObject({ code: "RMBG_INPUT_FORMAT_UNSUPPORTED", outcome: "failed" });
+    expect(details.message).toContain(format.toUpperCase());
+    expect(details.recommendation).toContain("JPG、PNG 或 WebP");
+  }
+});
+
+test("AOS input rejections retain their cause instead of becoming a generic processing failure", () => {
+  const resolution = getRequestFailureDetails("抠图处理失败：图片分辨率超限（5000x3000），AOS要求宽高都不超过 4096px。请缩小后重试。");
+  expect(resolution).toMatchObject({ code: "RMBG_PROVIDER_RESOLUTION_EXCEEDED", outcome: "failed" });
+  expect(resolution.message).toContain("5000×3000");
+  expect(getRequestFailureDetails("抠图处理失败：图片文件无法识别，请尝试转换为 JPG/PNG 后重试。")).toMatchObject({ code: "RMBG_PROVIDER_INVALID_FILE", outcome: "failed" });
+  expect(getRequestFailureDetails("抠图处理失败：AOS任务创建失败（HTTP 413）: Payload Too Large")).toMatchObject({ code: "RMBG_PROVIDER_FILE_TOO_LARGE", outcome: "failed" });
+  for (const [state, code] of [[-3, "RMBG_PROVIDER_SOURCE_DOWNLOAD_FAILED"], [-5, "RMBG_PROVIDER_URL_TOO_LARGE"], [-7, "RMBG_PROVIDER_INVALID_FILE"], [-8, "RMBG_PROVIDER_PROCESSING_TIMEOUT"], [-11, "RMBG_PROVIDER_EMPTY_RESULT"]] as const) {
+    const details = getRequestFailureDetails(`抠图处理失败：AOS任务失败（状态 ${state}，任务 original-task）: Failed`);
+    expect(details).toMatchObject({ code, outcome: "failed" });
+    expect(details.recommendation).not.toBe("");
+  }
+});
+
+test("the canvas API returns input-limit errors as HTTP 400 and preserves the same advice when polling", async () => {
+  const service = rmbgLoader(async () => { throw new Error("Unexpected provider call"); });
+  const error = new service.RmbgServiceError("抠图参考图分辨率超限（5056×3392 像素），当前 AOS 上游要求宽、高均不超过 4096 像素。", 400);
+  const route = serverLoader({
+    "@/app/(auth)/auth": { auth: async () => ({ user: { id: "user-a" } }) },
+    "@/lib/ai/rmbg/service": { RmbgServiceError: service.RmbgServiceError },
+    "@/lib/canvas/capabilities/client-command": { canvasCapabilityClientCommandSchema: { parse: (v: unknown) => v } },
+    "@/lib/canvas/capabilities/context": { CanvasCapabilityRuntimeError: class extends Error {} },
+    "@/lib/canvas/agent-mutations": { CanvasAgentMutationError: class extends Error {} },
+    "@/lib/canvas/capabilities/registry": { getCanvasCapabilityManifest: () => [] },
+    "@/lib/canvas/capabilities/runtime": { executeCanvasCapabilityRuntime: async () => { throw error; } },
+    "@/lib/canvas/capabilities/task-store": { getCanvasCapabilityTask: async () => ({ id: "task-a", status: "failed", error: error.message }) },
+  })("app/api/canvas/[id]/capabilities/route.ts");
+  const params = { params: Promise.resolve({ id: "project-a" }) };
+  const response = await route.POST(new Request("https://example.com/api/canvas/project-a/capabilities", { method: "POST", body: JSON.stringify({ requestId: "request-a" }) }), params);
+  expect(response.status).toBe(400);
+  const submitted = await response.json();
+  expect(submitted.failure).toMatchObject({ code: "RMBG_INPUT_RESOLUTION_EXCEEDED", outcome: "failed" });
+  expect(submitted.error).toContain("5056×3392");
+  expect(submitted.error).toContain("本次未提交上游抠图任务");
+  const polled = await (await route.GET(new Request("https://example.com/api/canvas/project-a/capabilities?requestId=request-a"), params)).json();
+  expect(polled.task.failure).toEqual(submitted.failure);
+  expect(polled.task.error).toContain(submitted.failure.recommendation);
+});
+
+test("a create timeout preserves its cause and never creates another paid task", async () => {
+  const image = await sharp({ create: { width: 16, height: 16, channels: 3, background: "white" } }).png().toBuffer();
+  let creates = 0;
+  let abort: Error;
+  const service = rmbgLoader(async () => { creates++; throw abort; });
+  abort = new service.RmbgServiceError("request timed out");
+  abort.name = "AbortError";
+  let failure: Error | undefined;
+  try {
+    await service.executeRmbgJob({ userId: "test", imageBuffer: image, sourceImageUrl: `${cdn}/source.png`, skipGallerySave: true });
+  } catch (error) { failure = error as Error; }
+  expect(creates).toBe(1);
+  expect(failure?.message).toContain("AOS创建任务超时（120秒）");
+  expect(getRequestFailureDetails(failure)).toMatchObject({ code: "RMBG_CREATE_TIMEOUT", outcome: "unknown" });
+});
+
+test("poll and result download timeouts retain their original task and distinct advice", () => {
+  const poll = getRequestFailureDetails("抠图处理失败：AOS查询任务超时，结果尚未确认（任务 task-1）");
+  const download = getRequestFailureDetails("抠图处理失败：AOS结果下载超时，任务已完成（任务 task-1）");
+  expect(poll).toMatchObject({ code: "RMBG_POLL_TIMEOUT", outcome: "unknown" });
+  expect(download).toMatchObject({ code: "RMBG_RESULT_DOWNLOAD_TIMEOUT", outcome: "unknown" });
+  expect(download.recommendation).toContain("取回原任务结果");
+  expect(getRequestFailureDetails("抠图处理失败：AOS任务查询失败（HTTP 404，任务 task-1）: Not Found")).toMatchObject({ code: "RMBG_PROVIDER_POLL_FAILED", outcome: "unknown" });
+  expect(getRequestFailureDetails("抠图处理失败：AOS结果下载失败（HTTP 500，任务 task-1）: Internal Error")).toMatchObject({ code: "RMBG_PROVIDER_RESULT_DOWNLOAD_FAILED", outcome: "unknown" });
+  expect(getRequestFailureDetails("抠图处理失败：AOS任务创建失败（HTTP 500）: Internal Error")).toMatchObject({ code: "RMBG_PROVIDER_CREATE_UNCONFIRMED", outcome: "unknown" });
+});
+
+test("network and body interruptions retry only the original task reads", async () => {
+  const image = await sharp({ create: { width: 32, height: 32, channels: 4, background: "#abcdef00" } }).png().toBuffer();
+  let creates = 0, polls = 0, downloads = 0;
+  let networkError: Error;
+  const service = rmbgLoader(async (input, options) => {
+    if (options?.method === "POST") { creates++; return Response.json({ data: { task_id: "original-task" } }); }
+    if (String(input).endsWith("/original-task")) {
+      if (++polls === 1) throw networkError;
+      return Response.json({ data: { state: 1, image: "https://output.example/original.png" } });
+    }
+    if (++downloads === 1) return new Response(new ReadableStream({ start(controller) { controller.error(networkError); } }));
+    return new Response(image, { headers: { "content-type": "image/png" } });
+  });
+  networkError = new service.RmbgServiceError("fetch failed"); networkError.name = "TypeError";
+  const result = await service.executeRmbgJob({ userId: "test", imageBuffer: image, sourceImageUrl: `${cdn}/source.png`, skipGallerySave: true });
+  expect(result.original_url).toContain(cdn);
+  expect({ creates, polls, downloads }).toEqual({ creates: 1, polls: 2, downloads: 2 });
+});
+
+test("exhausted result reads preserve the completed task and never re-create it", async () => {
+  const image = await sharp({ create: { width: 16, height: 16, channels: 3, background: "white" } }).png().toBuffer();
+  let creates = 0, downloads = 0;
+  let networkError: Error;
+  const service = rmbgLoader(async (input, options) => {
+    if (options?.method === "POST") { creates++; return Response.json({ data: { task_id: "completed-task" } }); }
+    if (String(input).endsWith("/completed-task")) return Response.json({ data: { state: 1, image: "https://output.example/original.png" } });
+    downloads++; throw networkError;
+  });
+  networkError = new service.RmbgServiceError("fetch failed"); networkError.name = "TypeError";
+  let failure: Error | undefined;
+  try { await service.executeRmbgJob({ userId: "test", imageBuffer: image, sourceImageUrl: `${cdn}/source.png`, skipGallerySave: true }); }
+  catch (error) { failure = error as Error; }
+  expect({ creates, downloads }).toEqual({ creates: 1, downloads: 3 });
+  expect(failure?.message).toContain("completed-task");
+  expect(getRequestFailureDetails(failure)).toMatchObject({ code: "RMBG_RESULT_DOWNLOAD_CONNECTION_FAILED", outcome: "unknown" });
+});