android-midscene-automation 0.1.13 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "android-midscene-automation",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "type": "module",
   "bin": {
     "android-midscene-automation": "./bin/android-midscene-automation.js"
@@ -14,6 +14,7 @@
     "tsconfig*.json",
     "vite.config.ts",
     "README.md",
+    "USAGE.md",
     "CHANGELOG.md"
   ],
   "scripts": {

package/server/android-sdk.ts

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { loadConfig } from './config';
+import { appDataPath } from './paths';
+
+export type AndroidSdkInfo = {
+  root: string;
+  adbPath: string;
+  source: 'config' | 'environment' | 'default' | 'path';
+};
+
+const adbFileName = process.platform === 'win32' ? 'adb.exe' : 'adb';
+
+function expandPath(value: string) {
+  const trimmed = value.trim().replace(/^(["'])(.*)\1$/, '$2');
+  if (trimmed === '~') return os.homedir();
+  if (trimmed.startsWith(`~${path.sep}`) || trimmed.startsWith('~/')) {
+    return path.join(os.homedir(), trimmed.slice(2));
+  }
+  return path.isAbsolute(trimmed) ? path.normalize(trimmed) : appDataPath(trimmed);
+}
+
+function sdkInfoFromPath(value: string, source: AndroidSdkInfo['source']): AndroidSdkInfo | null {
+  const candidate = expandPath(value);
+  const lowerBaseName = path.basename(candidate).toLowerCase();
+  const root = lowerBaseName === adbFileName.toLowerCase()
+    ? path.dirname(path.dirname(candidate))
+    : lowerBaseName === 'platform-tools'
+      ? path.dirname(candidate)
+      : candidate;
+  const adbPath = path.join(root, 'platform-tools', adbFileName);
+  if (!fs.existsSync(adbPath)) return null;
+  return { root, adbPath, source };
+}
+
+function findAdbOnPath() {
+  const directories = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  for (const directory of directories) {
+    const adbPath = path.join(directory.replace(/^(["'])(.*)\1$/, '$2'), adbFileName);
+    if (fs.existsSync(adbPath)) return fs.realpathSync(adbPath);
+  }
+  return '';
+}
+
+function defaultSdkPaths() {
+  if (process.platform === 'darwin') return [path.join(os.homedir(), 'Library', 'Android', 'sdk')];
+  if (process.platform === 'win32') {
+    return process.env.LOCALAPPDATA ? [path.join(process.env.LOCALAPPDATA, 'Android', 'Sdk')] : [];
+  }
+  return [path.join(os.homedir(), 'Android', 'Sdk')];
+}
+
+export function resolveAndroidSdk(): AndroidSdkInfo {
+  const configuredPath = loadConfig().runtime.androidSdkPath.trim();
+  if (configuredPath) {
+    const configured = sdkInfoFromPath(configuredPath, 'config');
+    if (configured) return configured;
+    throw new Error(`参数配置中的 Android SDK 路径无效：${configuredPath}。请选择包含 platform-tools/${adbFileName} 的 SDK 目录。`);
+  }
+
+  const candidates = [process.env.ANDROID_SDK_ROOT, process.env.ANDROID_HOME]
+    .filter((value): value is string => Boolean(value));
+  for (const candidate of candidates) {
+    const resolved = sdkInfoFromPath(candidate, 'environment');
+    if (resolved) return resolved;
+  }
+
+  for (const candidate of defaultSdkPaths()) {
+    const resolved = sdkInfoFromPath(candidate, 'default');
+    if (resolved) return resolved;
+  }
+
+  const adbPath = findAdbOnPath();
+  if (adbPath) {
+    return {
+      root: path.dirname(path.dirname(adbPath)),
+      adbPath,
+      source: 'path',
+    };
+  }
+
+  throw new Error('未检测到 Android SDK。请在“参数配置 > 运行配置”中指定 Android SDK 路径，或配置 ANDROID_SDK_ROOT/ANDROID_HOME。');
+}
+
+export function ensureAndroidSdkAvailable() {
+  const sdk = resolveAndroidSdk();
+  process.env.ANDROID_HOME = sdk.root;
+  process.env.ANDROID_SDK_ROOT = sdk.root;
+  const platformTools = path.dirname(sdk.adbPath);
+  const pathEntries = (process.env.PATH || '').split(path.delimiter);
+  if (!pathEntries.includes(platformTools)) {
+    process.env.PATH = [platformTools, ...pathEntries].filter(Boolean).join(path.delimiter);
+  }
+  return sdk;
+}
+
+export function getAdbCommand() {
+  try {
+    return ensureAndroidSdkAvailable().adbPath;
+  } catch {
+    return process.platform === 'win32' ? 'adb.exe' : 'adb';
+  }
+}

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

@@ -3,6 +3,8 @@ 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';
 
 type AppiumSessionResponse = {
   value?: {
@@ -41,9 +43,13 @@ function wait(ms: number) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function normalizeTextForContains(value: string) {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
 function adbTap(deviceId: string, x: number, y: number) {
   return new Promise<void>((resolve, reject) => {
-    execFile('adb', ['-s', deviceId, 'shell', 'input', 'tap', String(Math.round(x)), String(Math.round(y))], (error, _stdout, stderr) => {
+    execFile(getAdbCommand(), ['-s', deviceId, 'shell', 'input', 'tap', String(Math.round(x)), String(Math.round(y))], (error, _stdout, stderr) => {
       if (error) {
         reject(new Error(stderr || error.message));
         return;
@@ -53,10 +59,10 @@ function adbTap(deviceId: string, x: number, y: number) {
   });
 }
 
-function adbLaunchApp(deviceId: string, packageName: string) {
+export function launchAppOnDevice(deviceId: string, packageName: string) {
   if (!packageName) return Promise.reject(new Error('启动 APP 缺少包名'));
   return new Promise<void>((resolve, reject) => {
-    execFile('adb', [
+    execFile(getAdbCommand(), [
       '-s',
       deviceId,
       'shell',
@@ -79,7 +85,7 @@ function adbLaunchApp(deviceId: string, packageName: string) {
 
 function adbSwipe(deviceId: string, step: Required<AppiumRecordedStepRecord>['swipe']) {
   return new Promise<void>((resolve, reject) => {
-    execFile('adb', [
+    execFile(getAdbCommand(), [
       '-s',
       deviceId,
       'shell',
@@ -102,7 +108,7 @@ function adbSwipe(deviceId: string, step: Required<AppiumRecordedStepRecord>['sw
 
 function adbText(deviceId: string, args: string[]) {
   return new Promise<string>((resolve) => {
-    execFile('adb', ['-s', deviceId, ...args], { maxBuffer: 4 * 1024 * 1024 }, (_error, stdout, stderr) => {
+    execFile(getAdbCommand(), ['-s', deviceId, ...args], { maxBuffer: 4 * 1024 * 1024 }, (_error, stdout, stderr) => {
       resolve((stdout || stderr || '').trim());
     });
   });
@@ -116,6 +122,12 @@ async function getCurrentActivity(deviceId: string) {
   return resumedLine?.match(/\s([\w.$]+\/[\w.$]+)\s/)?.[1] || '';
 }
 
+async function isAppInForeground(deviceId: string, packageName: string) {
+  if (!packageName) return false;
+  const currentActivity = await getCurrentActivity(deviceId);
+  return currentActivity.split('/')[0] === packageName;
+}
+
 async function waitForActivity(deviceId: string, step: AppiumRecordedStepRecord) {
   const expectedActivity = step.value || '';
   if (!expectedActivity) throw new Error(`${step.label} 缺少目标 Activity`);
@@ -143,12 +155,13 @@ async function appendSettingsDiagnostics(lines: string[], deviceId: string) {
 
 function appendAndroidSdkDiagnostics(lines: string[]) {
   lines.push('Android SDK 环境变量未配置：');
+  lines.push('- 可在本项目“参数配置 > 运行配置”中指定 Android SDK 路径。');
   lines.push('- Windows 常见 SDK 路径：%LOCALAPPDATA%\\Android\\Sdk');
   lines.push('- PowerShell 设置示例：');
   lines.push('  [Environment]::SetEnvironmentVariable("ANDROID_HOME", "$env:LOCALAPPDATA\\Android\\Sdk", "User")');
   lines.push('  [Environment]::SetEnvironmentVariable("ANDROID_SDK_ROOT", "$env:LOCALAPPDATA\\Android\\Sdk", "User")');
   lines.push('  [Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:LOCALAPPDATA\\Android\\Sdk\\platform-tools", "User")');
-  lines.push('- 设置后请重新打开终端，并重启 appium 服务。');
+  lines.push('- Appium 是独立进程时不会继承网页中后设置的环境变量；设置后请重新打开终端，并重启 appium 服务。');
 }
 
 async function appiumRequest<T>(path: string, init?: RequestInit) {
@@ -192,6 +205,7 @@ async function appiumRequest<T>(path: string, init?: RequestInit) {
 }
 
 async function createSession(script: AppiumRecordedScriptRecord, deviceId: string) {
+  const appAlreadyForeground = await isAppInForeground(deviceId, script.appPackage).catch(() => false);
   const payload = await appiumRequest<AppiumSessionResponse>('/session', {
     method: 'POST',
     body: JSON.stringify({
@@ -203,6 +217,7 @@ async function createSession(script: AppiumRecordedScriptRecord, deviceId: strin
           'appium:appPackage': script.appPackage,
           ...(script.appActivity ? { 'appium:appActivity': script.appActivity } : {}),
           'appium:noReset': true,
+          ...(appAlreadyForeground ? { 'appium:autoLaunch': false } : {}),
           'appium:skipDeviceInitialization': true,
           'appium:ignoreHiddenApiPolicyError': true,
         },
@@ -214,6 +229,17 @@ async function createSession(script: AppiumRecordedScriptRecord, deviceId: strin
   return sessionId;
 }
 
+function isUiAutomationDisconnected(error: unknown) {
+  return errorDetail(error).includes('UiAutomation not connected');
+}
+
+async function resetUiAutomator2(deviceId: string) {
+  await adbText(deviceId, ['shell', 'pkill', '-f', 'com.android.commands.uiautomator.Launcher']);
+  await adbText(deviceId, ['shell', 'am', 'force-stop', 'io.appium.uiautomator2.server']);
+  await adbText(deviceId, ['shell', 'am', 'force-stop', 'io.appium.uiautomator2.server.test']);
+  await wait(800);
+}
+
 function toAppiumUsing(selector: NonNullable<AppiumRecordedStepRecord['selector']>) {
   if (selector.strategy === 'accessibilityId') return { using: 'accessibility id', value: selector.value || '' };
   if (selector.strategy === 'id') return { using: 'id', value: selector.value || '' };
@@ -351,7 +377,10 @@ async function runStep(sessionId: string, deviceId: string, step: AppiumRecorded
 
   if (step.type === 'launchApp') {
     const packageName = step.value || '';
-    await adbLaunchApp(deviceId, packageName);
+    if (await isAppInForeground(deviceId, packageName).catch(() => false)) {
+      return `APP 已在前台，跳过启动 ${packageName}`;
+    }
+    await launchAppOnDevice(deviceId, packageName);
     return `ADB 已启动 ${packageName}`;
   }
 
@@ -517,10 +546,14 @@ async function evaluateCondition(sessionId: string, deviceId: string, step: Appi
       await waitForElementGone(sessionId, step);
       return true;
     }
-    if (step.type === 'assertText') {
+    if (step.type === 'assertText' || (step.type === 'assertExists' && step.value)) {
       const elementId = await findElement(sessionId, step);
       const payload = await appiumRequest<AppiumValueResponse<string>>(`/session/${sessionId}/element/${elementId}/text`);
-      return (payload.value || '').includes(step.value || '');
+      const actualText = payload.value || '';
+      const expectedText = step.value || '';
+      return step.flow?.textMatch === 'exact'
+        ? actualText === expectedText
+        : normalizeTextForContains(actualText).includes(normalizeTextForContains(expectedText));
     }
     await waitForElement(sessionId, step);
     return true;
@@ -574,12 +607,26 @@ async function replayLinkedScript(
   const linkedScript = getAppiumRecordedScript(scriptId);
   if (!linkedScript) throw new Error(`${step.label} 指向的脚本不存在`);
 
-  const currentActivity = await getCurrentActivity(deviceId).catch(() => '');
-  if (linkedScript.appActivity && currentActivity !== linkedScript.appActivity) {
-    throw new Error(
-      `${step.label} 无法执行：当前 Activity 为 ${currentActivity || '-'}，`
-      + `目标脚本入口 Activity 为 ${linkedScript.appActivity}`,
-    );
+  if (linkedScript.appActivity) {
+    const currentActivity = await getCurrentActivity(deviceId).catch(() => '');
+    if (currentActivity !== linkedScript.appActivity) {
+      lines.push(`等待连接脚本入口 Activity：${linkedScript.appActivity}`);
+      try {
+        await waitForActivity(deviceId, {
+          id: `${step.id}_wait_activity`,
+          type: 'waitActivity',
+          label: step.label,
+          value: linkedScript.appActivity,
+          timeoutMs: 10000,
+        });
+      } catch {
+        const latestActivity = await getCurrentActivity(deviceId).catch(() => currentActivity);
+        throw new Error(
+          `${step.label} 无法执行：当前 Activity 为 ${latestActivity || '-'}，`
+          + `目标脚本入口 Activity 为 ${linkedScript.appActivity}`,
+        );
+      }
+    }
   }
 
   lines.push(`连接脚本开始：${linkedScript.name}`);
@@ -600,24 +647,24 @@ async function replayLinearSteps(
 ) {
   for (const [index, step] of steps.entries()) {
     if (options.skipLaunchApp && step.type === 'launchApp') {
-      lines.push(`[步骤 ${index + 1}] 跳过：${step.label}（连接脚本不重复启动 App）`);
+      lines.push(`[节点 ${index + 1}] 跳过：${step.label}（连接脚本不重复启动 App）`);
       continue;
     }
-    lines.push(`[步骤 ${index + 1}] 开始：${step.label}`);
+    lines.push(`[节点 ${index + 1}] 开始：${step.label}`);
     try {
       if (step.type === 'runScript') {
         await replayLinkedScript(sessionId, deviceId, step, lines, stack);
       } else {
         const result = await runStep(sessionId, deviceId, step);
-        if (result) lines.push(`[步骤 ${index + 1}] 结果：${result}`);
+        if (result) lines.push(`[节点 ${index + 1}] 结果：${result}`);
       }
-      lines.push(`[步骤 ${index + 1}] 完成：${step.label}`);
+      lines.push(`[节点 ${index + 1}] 完成：${step.label}`);
     } catch (error) {
       if (step.optional) {
-        lines.push(`[步骤 ${index + 1}] 跳过：${errorDetail(error)}`);
+        lines.push(`[节点 ${index + 1}] 跳过：${errorDetail(error)}`);
         continue;
       }
-      lines.push(`[步骤 ${index + 1}] 失败：${errorDetail(error)}`);
+      lines.push(`[节点 ${index + 1}] 失败：${errorDetail(error)}`);
       await appendStepDiagnostics(lines, deviceId, step);
       throw error;
     }
@@ -633,6 +680,23 @@ async function replayFlowSteps(
   options: ReplayStepOptions = {},
 ) {
   const idToIndex = new Map(steps.map((step, index) => [step.id, index]));
+  const conditionContinuationIndex = (conditionId: string) => {
+    const conditionIndex = idToIndex.get(conditionId);
+    if (conditionIndex === undefined) return undefined;
+    const explicitTargetId = steps[conditionIndex]?.flow?.successTargetId;
+    return explicitTargetId ? idToIndex.get(explicitTargetId) : undefined;
+  };
+  const nextIndexAfterStep = (currentIndex: number, step: AppiumRecordedStepRecord) => {
+    const explicitTargetId = step.flow?.successTargetId;
+    if (explicitTargetId) return idToIndex.get(explicitTargetId);
+    if (!step.flow?.parentConditionId || !step.flow.parentBranch) return currentIndex + 1;
+    const nextStep = steps[currentIndex + 1];
+    const staysInBranch = nextStep?.flow?.parentConditionId === step.flow.parentConditionId
+      && nextStep.flow.parentBranch === step.flow.parentBranch;
+    return staysInBranch
+      ? currentIndex + 1
+      : conditionContinuationIndex(step.flow.parentConditionId);
+  };
   const visitedPath: string[] = [];
   let index: number | undefined = 0;
   let guard = 0;
@@ -645,8 +709,7 @@ async function replayFlowSteps(
     const step = steps[index];
     if (options.skipLaunchApp && step.type === 'launchApp') {
       lines.push(`[节点 ${index + 1}] 跳过：${step.label}（连接脚本不重复启动 App）`);
-      const targetId = step.flow?.successTargetId;
-      index = targetId ? idToIndex.get(targetId) : index + 1;
+      index = nextIndexAfterStep(index, step);
       continue;
     }
     visitedPath.push(step.label);
@@ -655,9 +718,10 @@ async function replayFlowSteps(
 
     if (nodeKind === 'condition') {
       const matched = await evaluateCondition(sessionId, deviceId, step);
-      const targetId = matched ? step.flow?.yesTargetId : step.flow?.noTargetId;
+      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) : (matched ? index + 1 : undefined);
+      index = targetId ? idToIndex.get(targetId) : undefined;
       continue;
     }
 
@@ -669,12 +733,11 @@ async function replayFlowSteps(
         if (result) lines.push(`[节点 ${index + 1}] 结果：${result}`);
       }
       lines.push(`[节点 ${index + 1}] 完成：${step.label}`);
-      const targetId = step.flow?.successTargetId;
-      index = targetId ? idToIndex.get(targetId) : index + 1;
+      index = nextIndexAfterStep(index, step);
     } catch (error) {
       if (step.optional) {
         lines.push(`[节点 ${index + 1}] 跳过：${errorDetail(error)}`);
-        index += 1;
+        index = nextIndexAfterStep(index, step);
         continue;
       }
       const failureTarget = step.flow?.failureTargetId;
@@ -716,7 +779,11 @@ async function replayScriptSteps(
   options: ReplayStepOptions = {},
 ) {
   let trailingLinkIndex = steps.length;
-  while (trailingLinkIndex > 0 && steps[trailingLinkIndex - 1]?.type === 'runScript') {
+  while (
+    trailingLinkIndex > 0
+    && steps[trailingLinkIndex - 1]?.type === 'runScript'
+    && !steps[trailingLinkIndex - 1]?.flow?.parentConditionId
+  ) {
     trailingLinkIndex -= 1;
   }
 
@@ -730,26 +797,49 @@ async function replayScriptSteps(
   }
 }
 
-export async function replayAppiumScript(script: AppiumRecordedScriptRecord, deviceId: string) {
+export async function replayAppiumScript(
+  script: AppiumRecordedScriptRecord,
+  deviceId: string,
+  onOutput?: (line: string) => void,
+) {
   const targetDeviceId = deviceId || script.deviceId;
   if (!targetDeviceId) throw new Error('未检测到可用设备');
   if (!script.steps.length) throw new Error('脚本没有可回放步骤');
 
-  const lines: string[] = [
+  const startedAt = new Date();
+  const lines: string[] = [];
+  const pushLine = lines.push.bind(lines);
+  lines.push = (...items: string[]) => {
+    const length = pushLine(...items);
+    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...');
-    sessionId = await createSession(script, targetDeviceId);
+    try {
+      sessionId = await createSession(script, targetDeviceId);
+    } 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('回放完成');
-    return { success: true, output: lines.join('\n') };
+    success = true;
   } catch (error) {
     const detail = errorDetail(error);
     if (detail.includes('Appium Settings app is not running')) {
@@ -759,10 +849,29 @@ export async function replayAppiumScript(script: AppiumRecordedScriptRecord, dev
       appendAndroidSdkDiagnostics(lines);
     }
     lines.push(`回放终止：${detail}`);
-    return { success: false, output: lines.join('\n') };
   } finally {
     if (sessionId) {
       await appiumRequest(`/session/${sessionId}`, { method: 'DELETE' }).catch(() => undefined);
     }
   }
+
+  const completedAt = new Date();
+  let reportPath = '';
+  let reportId = '';
+  try {
+    const report = await createAppiumReplayReport({
+      script,
+      deviceId: targetDeviceId,
+      success,
+      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 };
 }

package/server/appium-recorder/report.ts

@@ -0,0 +1,138 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { appDataPath } from '../paths';
+import { loadConfig } from '../config';
+import { saveAppiumReplayReport, type AppiumRecordedScriptRecord, type AppiumRecordedStepRecord } from './repository';
+
+function pad(value: number, length = 2) {
+  return String(value).padStart(length, '0');
+}
+
+function fileDateTime(date: Date) {
+  return [
+    date.getFullYear(),
+    pad(date.getMonth() + 1),
+    pad(date.getDate()),
+  ].join('-') + `_${pad(date.getHours())}-${pad(date.getMinutes())}-${pad(date.getSeconds())}-${pad(date.getMilliseconds(), 3)}`;
+}
+
+function safeFileName(value: string) {
+  return value.replace(/[<>:"/\\|?*\u0000-\u001f]/g, '_').replace(/\s+/g, ' ').trim() || '未命名脚本';
+}
+
+function markdownValue(value: unknown) {
+  if (value === undefined || value === null || value === '') return '-';
+  return String(value).replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>');
+}
+
+function selectorText(selector?: AppiumRecordedStepRecord['selector']) {
+  if (!selector) return '-';
+  if (selector.strategy === 'bounds') return `bounds (${selector.centerX ?? '-'}, ${selector.centerY ?? '-'})`;
+  return `${selector.strategy} ${selector.value || ''}`.trim();
+}
+
+function stepExecutionLines(outputLines: string[], index: number) {
+  const prefixes = [`[节点 ${index + 1}]`, `[步骤 ${index + 1}]`];
+  return outputLines.filter((line) => prefixes.some((prefix) => line.startsWith(prefix)));
+}
+
+function executionStatus(lines: string[]) {
+  if (!lines.length) return '未执行';
+  if (lines.some((line) => line.includes('失败：') || line.includes('失败分支：'))) return '失败';
+  if (lines.some((line) => line.includes('跳过：'))) return '跳过';
+  if (lines.some((line) => line.includes('判断：'))) return '判断完成';
+  if (lines.some((line) => line.includes('完成：'))) return '成功';
+  return '中断';
+}
+
+function stepSection(step: AppiumRecordedStepRecord, index: number, outputLines: string[]) {
+  const executionLines = stepExecutionLines(outputLines, index);
+  const config = JSON.stringify(step, null, 2);
+  return [
+    `### ${index + 1}. ${step.label}`,
+    '',
+    '| 配置项 | 值 |',
+    '| --- | --- |',
+    `| 节点 ID | ${markdownValue(step.id)} |`,
+    `| 操作类型 | ${markdownValue(step.type)} |`,
+    `| 节点类型 | ${markdownValue(step.flow?.nodeKind || 'action')} |`,
+    `| 备注 | ${markdownValue(step.note)} |`,
+    `| Selector | ${markdownValue(selectorText(step.selector))} |`,
+    `| 上下文 Selector | ${markdownValue(selectorText(step.contextSelector))} |`,
+    `| 输入/目标值 | ${markdownValue(step.value)} |`,
+    `| 超时时间 | ${markdownValue(step.timeoutMs === undefined ? '-' : `${step.timeoutMs}ms`)} |`,
+    `| 可选步骤 | ${step.optional ? '是' : '否'} |`,
+    `| 是分支 | ${markdownValue(step.flow?.yesTargetId)} |`,
+    `| 否分支 | ${markdownValue(step.flow?.noTargetId)} |`,
+    `| 成功后续节点 | ${markdownValue(step.flow?.successTargetId)} |`,
+    `| 执行状态 | **${executionStatus(executionLines)}** |`,
+    '',
+    '#### 执行信息',
+    '',
+    executionLines.length ? '```text' : '',
+    executionLines.length ? executionLines.join('\n') : '该节点未进入执行路径，或在前序失败后未执行。',
+    executionLines.length ? '```' : '',
+    '',
+    '<details>',
+    '<summary>完整节点配置</summary>',
+    '',
+    '```json',
+    config,
+    '```',
+    '</details>',
+    '',
+  ].filter((line, lineIndex, lines) => line !== '' || lines[lineIndex - 1] !== '').join('\n');
+}
+
+export async function createAppiumReplayReport(input: {
+  script: AppiumRecordedScriptRecord;
+  deviceId: string;
+  success: boolean;
+  output: string;
+  startedAt: Date;
+  completedAt: Date;
+}) {
+  const configuredOutputPath = loadConfig().runtime.reportOutputPath.trim();
+  const outputDir = appDataPath(configuredOutputPath || 'output');
+  await mkdir(outputDir, { recursive: true });
+  const fileName = `${fileDateTime(input.completedAt)}-${safeFileName(input.script.name)}.md`;
+  const filePath = join(outputDir, fileName);
+  const outputLines = input.output.split(/\r?\n/);
+  const durationMs = input.completedAt.getTime() - input.startedAt.getTime();
+  const markdown = [
+    '# Appium 回放报告',
+    '',
+    '| 项目 | 内容 |',
+    '| --- | --- |',
+    `| 脚本名称 | ${markdownValue(input.script.name)} |`,
+    `| 脚本 ID | ${markdownValue(input.script.id)} |`,
+    `| App 包名 | ${markdownValue(input.script.appPackage)} |`,
+    `| App Activity | ${markdownValue(input.script.appActivity)} |`,
+    `| 设备 ID | ${markdownValue(input.deviceId)} |`,
+    `| 开始时间 | ${input.startedAt.toLocaleString()} |`,
+    `| 完成时间 | ${input.completedAt.toLocaleString()} |`,
+    `| 总耗时 | ${durationMs}ms |`,
+    `| 执行结果 | **${input.success ? '成功' : '失败'}** |`,
+    `| 节点数量 | ${input.script.steps.length} |`,
+    '',
+    '## 节点明细',
+    '',
+    ...input.script.steps.map((step, index) => stepSection(step, index, outputLines)),
+    '## 完整回放日志',
+    '',
+    '```text',
+    input.output || '-',
+    '```',
+    '',
+  ].join('\n');
+  await writeFile(filePath, markdown, 'utf8');
+  const record = saveAppiumReplayReport({
+    scriptId: input.script.id,
+    scriptName: input.script.name,
+    success: input.success,
+    filePath,
+    startedAt: input.startedAt.toISOString(),
+    completedAt: input.completedAt.toISOString(),
+  });
+  return { id: record.id, filePath, fileName };
+}