fix: 修复桌面 DOCX 媒体捕获超时

apps/desktop/src/docx-contract.ts

@@ -31,6 +31,18 @@ export type DesktopDocxExportOutcome =
 
 export type DesktopDocxCapability = DocxCapability;
 
+function readSafeDesktopMediaDetail(error: DocxExportServiceError) {
+  const cause = error.cause;
+  if (!(cause instanceof Error)) {
+    return undefined;
+  }
+  return /^桌面 DOCX (?:媒体布局超过 \d+ms|第 \d+\/\d+ 个媒体（(?:image|mermaid|echarts)）PNG 捕获超过 \d+ms)$/u.test(
+    cause.message
+  )
+    ? cause.message
+    : undefined;
+}
+
 export function toDesktopDocxExportFailure(
   error: unknown
 ): DesktopDocxExportFailure {
@@ -54,10 +66,11 @@ export function toDesktopDocxExportFailure(
     };
   }
   if (error instanceof DocxExportServiceError) {
+    const detail = readSafeDesktopMediaDetail(error);
     return {
       ok: false,
       error: error.code,
-      message: error.message,
+      message: detail ? `${error.message}：${detail}` : error.message,
       retryable: error.retryable
     };
   }

apps/desktop/src/electron-docx-media-capture.ts

@@ -9,6 +9,51 @@ interface CaptureScreenshotResult {
   data: string;
 }
 
+export interface ElectronDocxMediaCaptureTimeouts {
+  renderMs: number;
+  screenshotMs: number;
+}
+
+const DEFAULT_CAPTURE_TIMEOUTS: ElectronDocxMediaCaptureTimeouts = {
+  renderMs: 30_000,
+  screenshotMs: 20_000
+};
+
+function withTimeout<T>(
+  operation: Promise<T>,
+  timeoutMs: number,
+  message: string,
+  signal?: AbortSignal
+) {
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const finish = (callback: () => void) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", abort);
+      callback();
+    };
+    const abort = () =>
+      finish(() => reject(signal?.reason ?? new Error("操作已取消")));
+    const timeout = setTimeout(
+      () => finish(() => reject(new Error(message))),
+      timeoutMs
+    );
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) {
+      abort();
+      return;
+    }
+    operation.then(
+      (value) => finish(() => resolve(value)),
+      (error) => finish(() => reject(error))
+    );
+  });
+}
+
 function createRenderScript(request: DocxMediaCaptureRequest) {
   const serialized = JSON.stringify(request);
   return `(async () => {
@@ -24,12 +69,15 @@ function createRenderScript(request: DocxMediaCaptureRequest) {
 export async function captureDocxMediaWithElectronWebContents(
   webContents: WebContents,
   request: DocxMediaCaptureRequest,
-  signal?: AbortSignal
+  signal?: AbortSignal,
+  timeouts: ElectronDocxMediaCaptureTimeouts = DEFAULT_CAPTURE_TIMEOUTS
 ) {
   signal?.throwIfAborted();
-  const plan = (await webContents.executeJavaScript(
-    createRenderScript(request),
-    true
+  const plan = (await withTimeout(
+    webContents.executeJavaScript(createRenderScript(request), true),
+    timeouts.renderMs,
+    `桌面 DOCX 媒体布局超过 ${timeouts.renderMs}ms`,
+    signal
   )) as DocxMediaCapturePlan;
   signal?.throwIfAborted();
   const ownsDebugger = !webContents.debugger.isAttached();
@@ -41,20 +89,25 @@ export async function captureDocxMediaWithElectronWebContents(
     const captures = [];
     for (const target of plan.targets) {
       signal?.throwIfAborted();
-      const result = (await webContents.debugger.sendCommand(
-        "Page.captureScreenshot",
-        {
-          format: "png",
-          fromSurface: true,
-          captureBeyondViewport: true,
-          clip: {
-            x: target.captureX,
-            y: target.captureY,
-            width: target.captureWidthPx,
-            height: target.captureHeightPx,
-            scale: target.rasterScale
+      const result = (await withTimeout(
+        webContents.debugger.sendCommand(
+          "Page.captureScreenshot",
+          {
+            format: "png",
+            fromSurface: true,
+            captureBeyondViewport: true,
+            clip: {
+              x: target.captureX,
+              y: target.captureY,
+              width: target.captureWidthPx,
+              height: target.captureHeightPx,
+              scale: target.rasterScale
+            }
           }
-        }
+        ),
+        timeouts.screenshotMs,
+        `桌面 DOCX 第 ${target.ordinal}/${plan.targets.length} 个媒体（${target.kind}）PNG 捕获超过 ${timeouts.screenshotMs}ms`,
+        signal
       )) as CaptureScreenshotResult;
       captures.push({
         id: target.id,

apps/desktop/src/electron-docx-media-engine.ts

@@ -18,6 +18,25 @@ export interface ElectronDocxMediaEngineOptions {
   renderUrl: string;
 }
 
+export async function withActiveDocxCaptureSurface<T>(
+  window: Pick<
+    BrowserWindow,
+    "showInactive" | "hide" | "isDestroyed"
+  >,
+  operation: () => Promise<T>,
+  settleMs = 50
+) {
+  window.showInactive();
+  await new Promise((resolve) => setTimeout(resolve, settleMs));
+  try {
+    return await operation();
+  } finally {
+    if (!window.isDestroyed()) {
+      window.hide();
+    }
+  }
+}
+
 export class ElectronDocxMediaEngine
   implements DocxMediaCaptureAdapter, DocxThemeStyleCaptureAdapter
 {
@@ -98,10 +117,14 @@ export class ElectronDocxMediaEngine
     };
     signal?.addEventListener("abort", abort, { once: true });
     try {
-      return await captureDocxMediaWithElectronWebContents(
-        window.webContents,
-        request,
-        signal
+      return await withActiveDocxCaptureSurface(
+        window,
+        () =>
+          captureDocxMediaWithElectronWebContents(
+            window.webContents,
+            request,
+            signal
+          )
       );
     } finally {
       signal?.removeEventListener("abort", abort);