android-midscene-automation 0.1.18 → 0.1.20

package/server/appium-recorder/appium-runner.ts

@@ -1,10 +1,12 @@
 import { execFile } from 'node:child_process';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getAppiumRecordedScript, type AppiumRecordedScriptRecord, type AppiumRecordedStepRecord } from './repository';
 import { appDataPath } from '../paths';
 import { ensureAndroidSdkAvailable, getAdbCommand } from '../android-sdk';
-import { createAppiumReplayReport } from './report';
+import { createAppiumReplayReport, type AppiumReplayFrame } from './report';
+import { startManagedAppiumServer, usesManagedAppiumServer } from './managed-appium';
 
 type AppiumSessionResponse = {
   value?: {
@@ -23,7 +25,31 @@ type AppiumValueResponse<T> = {
 };
 
 const ELEMENT_KEY = 'element-6066-11e4-a52e-4f735466cecf';
-const appiumServerUrl = () => (process.env.APPIUM_SERVER_URL || 'http://127.0.0.1:4723').replace(/\/+$/, '');
+const configuredAppiumServerUrl = () => (process.env.APPIUM_SERVER_URL || 'http://127.0.0.1:4723').replace(/\/+$/, '');
+
+class ReplayStoppedError extends Error {
+  constructor() {
+    super('用户手动终止');
+    this.name = 'ReplayStoppedError';
+  }
+}
+
+const replayContext = new AsyncLocalStorage<{
+  signal?: AbortSignal;
+  appiumLog: (line: string) => void;
+  serverUrl: string;
+  frames: AppiumReplayFrame[];
+}>();
+
+const appiumServerUrl = () => replayContext.getStore()?.serverUrl || configuredAppiumServerUrl();
+
+function isReplayStopped(error?: unknown) {
+  return error instanceof ReplayStoppedError || replayContext.getStore()?.signal?.aborted === true;
+}
+
+function throwIfReplayStopped(error?: unknown) {
+  if (isReplayStopped(error)) throw new ReplayStoppedError();
+}
 
 function errorDetail(error: unknown) {
   if (!(error instanceof Error)) return String(error || '未知错误');
@@ -40,7 +66,20 @@ function isStaleElementError(error: unknown) {
 }
 
 function wait(ms: number) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  const signal = replayContext.getStore()?.signal;
+  if (!signal) return new Promise<void>((resolve) => setTimeout(resolve, ms));
+  throwIfReplayStopped();
+  return new Promise<void>((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new ReplayStoppedError());
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
 }
 
 function normalizeTextForContains(value: string) {
@@ -135,6 +174,7 @@ async function waitForActivity(deviceId: string, step: AppiumRecordedStepRecord)
   const timeoutMs = step.timeoutMs || 10000;
   let currentActivity = '';
   while (Date.now() - startedAt <= timeoutMs) {
+    throwIfReplayStopped();
     currentActivity = await getCurrentActivity(deviceId);
     if (currentActivity === expectedActivity) return;
     await wait(500);
@@ -164,22 +204,40 @@ function appendAndroidSdkDiagnostics(lines: string[]) {
   lines.push('- Appium 是独立进程时不会继承网页中后设置的环境变量；设置后请重新打开终端，并重启 appium 服务。');
 }
 
-async function appiumRequest<T>(path: string, init?: RequestInit) {
+async function appiumRequest<T>(
+  path: string,
+  init?: RequestInit,
+  options?: { ignoreAbort?: boolean; timeoutMs?: number },
+) {
   const requestUrl = `${appiumServerUrl()}${path}`;
+  const context = replayContext.getStore();
+  const method = init?.method || 'GET';
+  const startedAt = Date.now();
+  if (!options?.ignoreAbort) throwIfReplayStopped();
+  context?.appiumLog(`[Appium] 请求：${method} ${path}`);
   let response: Response;
   try {
     response = await fetch(requestUrl, {
       ...init,
+      signal: options?.ignoreAbort
+        ? (options.timeoutMs ? AbortSignal.timeout(options.timeoutMs) : undefined)
+        : context?.signal || init?.signal,
       headers: {
         'Content-Type': 'application/json',
         ...(init?.headers || {}),
       },
     });
   } catch (error) {
+    if (isReplayStopped(error) && !options?.ignoreAbort) {
+      context?.appiumLog(`[Appium] 取消：${method} ${path}`);
+      throw new ReplayStoppedError();
+    }
+    context?.appiumLog(`[Appium] 异常：${method} ${path}（${errorDetail(error)}）`);
     throw new Error(`无法连接 Appium 服务 ${requestUrl}，${errorDetail(error)}`);
   }
 
   const responseText = await response.text();
+  context?.appiumLog(`[Appium] 响应：HTTP ${response.status} ${method} ${path}（${Date.now() - startedAt}ms）`);
   const payload = (() => {
     try {
       return responseText ? JSON.parse(responseText) : {};
@@ -199,13 +257,66 @@ async function appiumRequest<T>(path: string, init?: RequestInit) {
       payload.value?.stacktrace || payload.stacktrace ? `堆栈信息：\n${payload.value?.stacktrace || payload.stacktrace}` : '',
       responseText ? `原始响应：\n${responseText}` : '',
     ].filter(Boolean).join('\n');
-    throw new Error(`Appium ${init?.method || 'GET'} ${path} 失败（HTTP ${response.status}）：\n${detail || '未返回错误详情'}`);
+    throw new Error(`Appium ${method} ${path} 失败（HTTP ${response.status}）：\n${detail || '未返回错误详情'}`);
   }
   return payload;
 }
 
-async function createSession(script: AppiumRecordedScriptRecord, deviceId: string) {
-  const appAlreadyForeground = await isAppInForeground(deviceId, script.appPackage).catch(() => false);
+function replayFrameSelector(step: AppiumRecordedStepRecord) {
+  const selector = step.selector;
+  if (!selector) return '-';
+  if (selector.strategy === 'bounds') return `bounds (${selector.centerX ?? '-'}, ${selector.centerY ?? '-'})`;
+  return `${selector.strategy} ${selector.value || ''}`.trim();
+}
+
+async function captureReplayFrame(
+  sessionId: string,
+  step: AppiumRecordedStepRecord,
+  nodeNumber: number,
+  scriptName: string,
+  phase: AppiumReplayFrame['phase'],
+  status: string,
+) {
+  const context = replayContext.getStore();
+  if (!context || !sessionId) return;
+  const appendFrame = (imageBase64: string) => {
+    context.frames.push({
+      sequence: context.frames.length + 1,
+      scriptName,
+      nodeId: step.id,
+      nodeNumber,
+      nodeLabel: step.label,
+      nodeType: step.type,
+      note: step.note || '',
+      selector: replayFrameSelector(step),
+      phase,
+      status,
+      capturedAt: new Date().toISOString(),
+      imageBase64,
+    });
+  };
+
+  if (phase === 'stopped' && context.signal?.aborted) {
+    const previousFrame = context.frames.at(-1);
+    if (previousFrame) appendFrame(previousFrame.imageBase64);
+    return;
+  }
+
+  try {
+    const payload = await appiumRequest<AppiumValueResponse<string>>(
+      `/session/${sessionId}/screenshot`,
+      undefined,
+      { ignoreAbort: true, timeoutMs: 5000 },
+    );
+    const imageBase64 = typeof payload.value === 'string' ? payload.value : '';
+    if (!imageBase64) throw new Error('Appium 未返回截图内容');
+    appendFrame(imageBase64);
+  } catch (error) {
+    context.appiumLog(`[节点 ${nodeNumber}] 截图失败：${errorDetail(error)}`);
+  }
+}
+
+async function createSession(deviceId: string) {
   const payload = await appiumRequest<AppiumSessionResponse>('/session', {
     method: 'POST',
     body: JSON.stringify({
@@ -214,10 +325,8 @@ async function createSession(script: AppiumRecordedScriptRecord, deviceId: strin
           platformName: 'Android',
           'appium:automationName': 'UiAutomator2',
           'appium:udid': deviceId,
-          'appium:appPackage': script.appPackage,
-          ...(script.appActivity ? { 'appium:appActivity': script.appActivity } : {}),
+          'appium:autoLaunch': false,
           'appium:noReset': true,
-          ...(appAlreadyForeground ? { 'appium:autoLaunch': false } : {}),
           'appium:skipDeviceInitialization': true,
           'appium:ignoreHiddenApiPolicyError': true,
         },
@@ -275,7 +384,8 @@ async function findElement(sessionId: string, step: AppiumRecordedStepRecord) {
       attempts.push(`context ${step.contextSelector.strategy} ${step.contextSelector.value || ''} -> ${step.selector.strategy} ${step.selector.value || ''}`);
       const parentId = await findElementBySelector(sessionId, step.contextSelector);
       return await findElementBySelector(sessionId, step.selector, parentId);
-    } catch {
+    } catch (error) {
+      throwIfReplayStopped(error);
       // Continue with the fallback chain below.
     }
   }
@@ -284,7 +394,8 @@ async function findElement(sessionId: string, step: AppiumRecordedStepRecord) {
     try {
       attempts.push(`${selector.strategy} ${selector.value || ''}`);
       return await findElementBySelector(sessionId, selector);
-    } catch {
+    } catch (error) {
+      throwIfReplayStopped(error);
       // Continue.
     }
   }
@@ -293,6 +404,7 @@ async function findElement(sessionId: string, step: AppiumRecordedStepRecord) {
     attempts.push(`${step.selector.strategy} ${step.selector.value || ''}`);
     return await findElementBySelector(sessionId, step.selector);
   } catch (error) {
+    throwIfReplayStopped(error);
     throw new Error(`${step.label} 未找到元素；尝试过：${attempts.filter(Boolean).join('；') || '-'}；${errorDetail(error)}`);
   }
 }
@@ -313,6 +425,7 @@ async function waitForElement(sessionId: string, step: AppiumRecordedStepRecord)
       await findElement(sessionId, step);
       return;
     } catch (error) {
+      throwIfReplayStopped(error);
       lastError = error;
       await wait(500);
     }
@@ -326,7 +439,8 @@ async function findOptionalElement(sessionId: string, step: AppiumRecordedStepRe
   while (Date.now() - startedAt <= timeoutMs) {
     try {
       return await findElement(sessionId, step);
-    } catch {
+    } catch (error) {
+      throwIfReplayStopped(error);
       await wait(250);
     }
   }
@@ -339,7 +453,8 @@ async function waitForElementGone(sessionId: string, step: AppiumRecordedStepRec
   while (Date.now() - startedAt <= timeoutMs) {
     try {
       await findElement(sessionId, step);
-    } catch {
+    } catch (error) {
+      throwIfReplayStopped(error);
       return;
     }
     await wait(500);
@@ -357,6 +472,7 @@ async function saveScreenshot(sessionId: string) {
 }
 
 async function runStep(sessionId: string, deviceId: string, step: AppiumRecordedStepRecord) {
+  throwIfReplayStopped();
   if (step.type === 'delay') {
     await wait(Math.max(0, step.timeoutMs || 1000));
     return;
@@ -497,6 +613,7 @@ async function runStep(sessionId: string, deviceId: string, step: AppiumRecorded
         });
         return;
       } catch (error) {
+        throwIfReplayStopped(error);
         if (attempt === 0 && isStaleElementError(error)) {
           await wait(300);
           continue;
@@ -518,6 +635,7 @@ async function runStep(sessionId: string, deviceId: string, step: AppiumRecorded
         });
         return;
       } catch (error) {
+        throwIfReplayStopped(error);
         if (attempt === 0 && isStaleElementError(error)) {
           await wait(300);
           continue;
@@ -557,7 +675,8 @@ async function evaluateCondition(sessionId: string, deviceId: string, step: Appi
     }
     await waitForElement(sessionId, step);
     return true;
-  } catch {
+  } catch (error) {
+    throwIfReplayStopped(error);
     return false;
   }
 }
@@ -592,6 +711,7 @@ async function appendStepDiagnostics(lines: string[], deviceId: string, step: Ap
 
 type ReplayStepOptions = {
   skipLaunchApp?: boolean;
+  scriptName?: string;
 };
 
 async function replayLinkedScript(
@@ -601,6 +721,7 @@ async function replayLinkedScript(
   lines: string[],
   stack: string[],
 ) {
+  throwIfReplayStopped();
   const scriptId = step.value || '';
   if (!scriptId) throw new Error(`${step.label} 缺少连接脚本 ID`);
   if (stack.includes(scriptId)) throw new Error(`${step.label} 检测到循环连接脚本`);
@@ -619,7 +740,8 @@ async function replayLinkedScript(
           value: linkedScript.appActivity,
           timeoutMs: 10000,
         });
-      } catch {
+      } catch (error) {
+        throwIfReplayStopped(error);
         const latestActivity = await getCurrentActivity(deviceId).catch(() => currentActivity);
         throw new Error(
           `${step.label} 无法执行：当前 Activity 为 ${latestActivity || '-'}，`
@@ -633,6 +755,7 @@ async function replayLinkedScript(
   const nextStack = [...stack, linkedScript.id];
   await replayScriptSteps(sessionId, deviceId, linkedScript.steps, lines, nextStack, {
     skipLaunchApp: true,
+    scriptName: linkedScript.name,
   });
   lines.push(`连接脚本完成：${linkedScript.name}`);
 }
@@ -646,11 +769,13 @@ async function replayLinearSteps(
   options: ReplayStepOptions = {},
 ) {
   for (const [index, step] of steps.entries()) {
+    throwIfReplayStopped();
     if (options.skipLaunchApp && step.type === 'launchApp') {
       lines.push(`[节点 ${index + 1}] 跳过：${step.label}（连接脚本不重复启动 App）`);
       continue;
     }
     lines.push(`[节点 ${index + 1}] 开始：${step.label}`);
+    await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'before', '执行前');
     try {
       if (step.type === 'runScript') {
         await replayLinkedScript(sessionId, deviceId, step, lines, stack);
@@ -659,12 +784,20 @@ async function replayLinearSteps(
         if (result) lines.push(`[节点 ${index + 1}] 结果：${result}`);
       }
       lines.push(`[节点 ${index + 1}] 完成：${step.label}`);
+      await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'after', '成功');
     } catch (error) {
+      if (isReplayStopped(error)) {
+        lines.push(`[节点 ${index + 1}] 已终止：${step.label}`);
+        await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'stopped', '已终止');
+        throw new ReplayStoppedError();
+      }
       if (step.optional) {
         lines.push(`[节点 ${index + 1}] 跳过：${errorDetail(error)}`);
+        await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'error', '已跳过');
         continue;
       }
       lines.push(`[节点 ${index + 1}] 失败：${errorDetail(error)}`);
+      await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'error', '失败');
       await appendStepDiagnostics(lines, deviceId, step);
       throw error;
     }
@@ -703,6 +836,7 @@ async function replayFlowSteps(
   const maxVisits = Math.max(steps.length * 4, 20);
 
   while (typeof index === 'number' && index >= 0 && index < steps.length) {
+    throwIfReplayStopped();
     guard += 1;
     if (guard > maxVisits) throw new Error('流程图可能存在循环，已终止回放');
 
@@ -715,13 +849,31 @@ async function replayFlowSteps(
     visitedPath.push(step.label);
     const nodeKind = step.flow?.nodeKind || (step.type === 'assertExists' || step.type === 'assertText' ? 'assertion' : 'action');
     lines.push(`[节点 ${index + 1}] 开始：${step.label}`);
+    await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'before', '执行前');
 
     if (nodeKind === 'condition') {
-      const matched = await evaluateCondition(sessionId, deviceId, step);
-      const branchTargetId = matched ? step.flow?.yesTargetId : step.flow?.noTargetId;
-      const targetId = branchTargetId || step.flow?.successTargetId || '';
-      lines.push(`[节点 ${index + 1}] 判断：${matched ? '是' : '否'}${targetId ? `，进入 ${targetId}` : '，流程结束'}`);
-      index = targetId ? idToIndex.get(targetId) : undefined;
+      try {
+        const matched = await evaluateCondition(sessionId, deviceId, step);
+        const branchTargetId = matched ? step.flow?.yesTargetId : step.flow?.noTargetId;
+        const targetId = branchTargetId || step.flow?.successTargetId || '';
+        lines.push(`[节点 ${index + 1}] 判断：${matched ? '是' : '否'}${targetId ? `，进入 ${targetId}` : '，流程结束'}`);
+        await captureReplayFrame(
+          sessionId,
+          step,
+          index + 1,
+          options.scriptName || '',
+          'after',
+          `判断：${matched ? '是' : '否'}`,
+        );
+        index = targetId ? idToIndex.get(targetId) : undefined;
+      } catch (error) {
+        if (isReplayStopped(error)) {
+          lines.push(`[节点 ${index + 1}] 已终止：${step.label}`);
+          await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'stopped', '已终止');
+          throw new ReplayStoppedError();
+        }
+        throw error;
+      }
       continue;
     }
 
@@ -733,20 +885,29 @@ async function replayFlowSteps(
         if (result) lines.push(`[节点 ${index + 1}] 结果：${result}`);
       }
       lines.push(`[节点 ${index + 1}] 完成：${step.label}`);
+      await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'after', '成功');
       index = nextIndexAfterStep(index, step);
     } catch (error) {
+      if (isReplayStopped(error)) {
+        lines.push(`[节点 ${index + 1}] 已终止：${step.label}`);
+        await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'stopped', '已终止');
+        throw new ReplayStoppedError();
+      }
       if (step.optional) {
         lines.push(`[节点 ${index + 1}] 跳过：${errorDetail(error)}`);
+        await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'error', '已跳过');
         index = nextIndexAfterStep(index, step);
         continue;
       }
       const failureTarget = step.flow?.failureTargetId;
       if (failureTarget && idToIndex.has(failureTarget)) {
         lines.push(`[节点 ${index + 1}] 失败分支：${errorDetail(error)}`);
+        await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'error', '进入失败分支');
         index = idToIndex.get(failureTarget);
         continue;
       }
       lines.push(`[节点 ${index + 1}] 失败：${errorDetail(error)}`);
+      await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'error', '失败');
       lines.push(`执行路径：${visitedPath.join(' -> ')}`);
       await appendStepDiagnostics(lines, deviceId, step);
       throw error;
@@ -791,9 +952,25 @@ async function replayScriptSteps(
   const trailingLinkedSteps = steps.slice(trailingLinkIndex);
   await replayStepGroup(sessionId, deviceId, mainSteps, lines, stack, options);
 
-  for (const step of trailingLinkedSteps) {
+  for (const [offset, step] of trailingLinkedSteps.entries()) {
+    const nodeNumber = trailingLinkIndex + offset + 1;
     lines.push(`当前脚本步骤完成，开始执行：${step.label}`);
-    await replayLinkedScript(sessionId, deviceId, step, lines, stack);
+    lines.push(`[节点 ${nodeNumber}] 开始：${step.label}`);
+    await captureReplayFrame(sessionId, step, nodeNumber, options.scriptName || '', 'before', '执行前');
+    try {
+      await replayLinkedScript(sessionId, deviceId, step, lines, stack);
+      lines.push(`[节点 ${nodeNumber}] 完成：${step.label}`);
+      await captureReplayFrame(sessionId, step, nodeNumber, options.scriptName || '', 'after', '成功');
+    } catch (error) {
+      if (isReplayStopped(error)) {
+        lines.push(`[节点 ${nodeNumber}] 已终止：${step.label}`);
+        await captureReplayFrame(sessionId, step, nodeNumber, options.scriptName || '', 'stopped', '已终止');
+        throw new ReplayStoppedError();
+      }
+      lines.push(`[节点 ${nodeNumber}] 失败：${errorDetail(error)}`);
+      await captureReplayFrame(sessionId, step, nodeNumber, options.scriptName || '', 'error', '失败');
+      throw error;
+    }
   }
 }
 
@@ -801,6 +978,7 @@ export async function replayAppiumScript(
   script: AppiumRecordedScriptRecord,
   deviceId: string,
   onOutput?: (line: string) => void,
+  signal?: AbortSignal,
 ) {
   const targetDeviceId = deviceId || script.deviceId;
   if (!targetDeviceId) throw new Error('未检测到可用设备');
@@ -814,64 +992,122 @@ export async function replayAppiumScript(
     items.forEach((line) => onOutput?.(line));
     return length;
   };
-  lines.push(
-    `Appium 服务：${appiumServerUrl()}`,
-    `目标设备：${targetDeviceId}`,
-    `App 包名：${script.appPackage}`,
-    `录制步骤：${script.steps.length}`,
-  );
-  let sessionId = '';
-  let success = false;
-  try {
-    lines.push('正在检测 Android SDK...');
-    const androidSdk = ensureAndroidSdkAvailable();
-    lines.push(`Android SDK 已就绪：${androidSdk.root}`);
-    lines.push('正在创建 Appium session...');
+  const context = {
+    signal,
+    appiumLog: (line) => lines.push(line),
+    serverUrl: configuredAppiumServerUrl(),
+    frames: [] as AppiumReplayFrame[],
+  };
+  return replayContext.run(context, async () => {
+    lines.push(
+      `目标设备：${targetDeviceId}`,
+      `App 包名：${script.appPackage}`,
+      `录制步骤：${script.steps.length}`,
+    );
+    let sessionId = '';
+    let success = false;
+    let stopped = false;
+    let managedAppium: Awaited<ReturnType<typeof startManagedAppiumServer>> | null = null;
     try {
-      sessionId = await createSession(script, targetDeviceId);
+      lines.push('正在检测 Android SDK...');
+      const androidSdk = ensureAndroidSdkAvailable();
+      lines.push(`Android SDK 已就绪：${androidSdk.root}`);
+      if (usesManagedAppiumServer()) {
+        lines.push('正在启动本次回放的 Appium 服务...');
+        lines.push('----- Appium 服务端原始日志开始 -----');
+        managedAppium = await startManagedAppiumServer((line) => lines.push(line), signal);
+        context.serverUrl = managedAppium.serverUrl;
+      }
+      lines.push(`Appium 服务：${appiumServerUrl()}`);
+      lines.push('正在创建 Appium session...');
+      try {
+        sessionId = await createSession(targetDeviceId);
+      } catch (error) {
+        throwIfReplayStopped(error);
+        if (!isUiAutomationDisconnected(error)) throw error;
+        lines.push('检测到 UiAutomation 连接冲突，正在清理残留进程并重试...');
+        await resetUiAutomator2(targetDeviceId);
+        sessionId = await createSession(targetDeviceId);
+      }
+      lines.push(`Appium session 已创建：${sessionId}`);
+      if (hasFlowSteps(script.steps)) lines.push('按流程图路径回放...');
+      await replayScriptSteps(sessionId, targetDeviceId, script.steps, lines, [script.id], {
+        scriptName: script.name,
+      });
+      lines.push('回放完成');
+      success = true;
     } catch (error) {
-      if (!isUiAutomationDisconnected(error)) throw error;
-      lines.push('检测到 UiAutomation 连接冲突，正在清理残留进程并重试...');
-      await resetUiAutomator2(targetDeviceId);
-      sessionId = await createSession(script, targetDeviceId);
-    }
-    lines.push(`Appium session 已创建：${sessionId}`);
-    if (hasFlowSteps(script.steps)) lines.push('按流程图路径回放...');
-    await replayScriptSteps(sessionId, targetDeviceId, script.steps, lines, [script.id]);
-    lines.push('回放完成');
-    success = true;
-  } catch (error) {
-    const detail = errorDetail(error);
-    if (detail.includes('Appium Settings app is not running')) {
-      await appendSettingsDiagnostics(lines, targetDeviceId);
-    }
-    if (detail.includes('Neither ANDROID_HOME nor ANDROID_SDK_ROOT')) {
-      appendAndroidSdkDiagnostics(lines);
+      stopped = isReplayStopped(error);
+      const detail = errorDetail(error);
+      if (stopped) {
+        lines.push('回放已终止：用户手动终止');
+      } else {
+        if (detail.includes('Appium Settings app is not running')) {
+          await appendSettingsDiagnostics(lines, targetDeviceId);
+        }
+        if (detail.includes('Neither ANDROID_HOME nor ANDROID_SDK_ROOT')) {
+          appendAndroidSdkDiagnostics(lines);
+        }
+        lines.push(`回放终止：${detail}`);
+      }
+    } finally {
+      let managedAppiumStopped = false;
+      if (signal?.aborted && managedAppium) {
+        await managedAppium.stop();
+        managedAppiumStopped = true;
+      } else if (sessionId) {
+        await appiumRequest(
+          `/session/${sessionId}`,
+          { method: 'DELETE' },
+          { ignoreAbort: true, timeoutMs: 2000 },
+        ).catch(() => undefined);
+      }
+      if (managedAppium) {
+        if (!managedAppiumStopped) await managedAppium.stop();
+        lines.push('----- Appium 服务端原始日志结束 -----');
+      }
     }
-    lines.push(`回放终止：${detail}`);
-  } finally {
-    if (sessionId) {
-      await appiumRequest(`/session/${sessionId}`, { method: 'DELETE' }).catch(() => undefined);
+
+    if (signal?.aborted && !stopped) {
+      stopped = true;
+      success = false;
+      lines.push('回放已终止：用户手动终止');
     }
-  }
 
-  const completedAt = new Date();
-  let reportPath = '';
-  let reportId = '';
-  try {
-    const report = await createAppiumReplayReport({
-      script,
-      deviceId: targetDeviceId,
+    const completedAt = new Date();
+    let reportPath = '';
+    let reportId = '';
+    let logPath = '';
+    let htmlReportPath = '';
+    try {
+      const report = await createAppiumReplayReport({
+        script,
+        deviceId: targetDeviceId,
+        success,
+        stopped,
+        output: lines.join('\n'),
+        startedAt,
+        completedAt,
+        frames: context.frames,
+      });
+      reportPath = report.filePath;
+      reportId = report.id;
+      logPath = report.logPath;
+      htmlReportPath = report.htmlReportPath;
+      lines.push(`回放报告已生成：${reportPath}`);
+      lines.push(`截图回放已生成：${report.htmlReportPath}`);
+      lines.push(`回放日志已生成：${logPath}`);
+    } catch (error) {
+      lines.push(`回放报告和日志生成失败：${errorDetail(error)}`);
+    }
+    return {
       success,
+      stopped,
       output: lines.join('\n'),
-      startedAt,
-      completedAt,
-    });
-    reportPath = report.filePath;
-    reportId = report.id;
-    lines.push(`回放报告已生成：${reportPath}`);
-  } catch (error) {
-    lines.push(`回放报告生成失败：${errorDetail(error)}`);
-  }
-  return { success, output: lines.join('\n'), reportPath, reportId };
+      reportPath,
+      reportId,
+      logPath,
+      htmlReportPath,
+    };
+  });
 }