android-midscene-automation 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,6 +1,15 @@
 # 更新记录
+## v0.2.4
+- Midscene Android、Android Playground、Core、Playground、Shared 和 Web 模块统一升级至 1.14.0。
+- 修复 Midscene 测试脚本生成过程中切换“AI 生成 / 自定义步骤编排”会清空生成状态和结果的问题；生成任务继续在后台执行，模式切换后保留已生成步骤与代码。
+
+## v0.2.3
+- 修复长时间执行 ADB 操作、延时或 AI 识别后，Appium 因默认 60 秒命令空闲超时销毁会话，导致后续 Home 键、点击等节点报“invalid session id”的问题；托管服务关闭会话空闲计时，外部服务通过心跳保活并保留 60 秒空闲回收，避免创建请求取消或清理失败后遗留永久会话。
+- 为启动 App、清理数据、坐标点击与滑动补齐 ADB 超时和取消控制；终止前台检查后不再继续启动 App，异常结束仍清理会话。
+- 修复远程回放固定 10 分钟超时后丢失结果的问题：任务随代理心跳续期，离线任务支持恢复连接后终止与补交历史记录，结果上报失败自动重试且不会重复执行脚本。
+- 修复远程设备无法手动终止回放的问题，通过独立心跳传递取消信号，兼容任务派发前取消，并阻止同一设备重复提交回放。
+
 ## v0.2.2
-- 更新 Vben 风格的浅色后台界面：蓝色主色、白色卡片、浅灰背景、可折叠侧边栏与顶部页签。
 - 新增“概览 → 分析页”，根据已保存脚本和真实执行记录分别汇总 Midscene、Appium 测试数据。
 - 修复配置加载失败后出现空白可保存表单的问题，增加独立错误提示和重试；后端断线后自动尝试重连并支持手动重连，保留页面编辑内容。
 - Appium 配置自动保存失败后保留最新待保存内容并提供“重试保存”；修复切换或关闭 Appium 页签后，离开页面时未保存草稿保护失效的问题。

package/README.md

@@ -2,6 +2,30 @@
 
 一个面向 Android App 的自动化测试工具，同时支持 Midscene AI 测试和 Appium 组件树录制回放。
 
+## 界面预览
+
+![](./screen/c1.jpg)
+
+### Midscene
+
+![](./screen/m1.jpg)
+
+![](./screen/m2.jpg)
+
+![](./screen/m3.jpg)
+
+### Appium
+
+![](./screen/a1.jpg)
+
+![](./screen/a2.jpg)
+
+![](./screen/a3.jpg)
+
+![](./screen/a4.jpg)
+
+![](./screen/a5.jpg)
+
 ## 支持的测试方式
 
 | 测试方式 | 页面入口 | 工作方式 | 模型要求 | 适用场景 |
@@ -1358,8 +1382,17 @@ Linux: ~/.local/share/android-midscene-automation
 
 # 项目更新记录
 
+## v0.2.4
+- Midscene Android、Android Playground、Core、Playground、Shared 和 Web 模块统一升级至 1.14.0。
+- 修复 Midscene 测试脚本生成过程中切换“AI 生成 / 自定义步骤编排”会清空生成状态和结果的问题；生成任务继续在后台执行，模式切换后保留已生成步骤与代码。
+
+## v0.2.3
+- 修复长时间执行 ADB 操作、延时或 AI 识别后，Appium 因默认 60 秒命令空闲超时销毁会话，导致后续 Home 键、点击等节点报“invalid session id”的问题；托管服务关闭会话空闲计时，外部服务通过心跳保活并保留 60 秒空闲回收，避免创建请求取消或清理失败后遗留永久会话。
+- 为启动 App、清理数据、坐标点击与滑动补齐 ADB 超时和取消控制；终止前台检查后不再继续启动 App，异常结束仍清理会话。
+- 修复远程回放固定 10 分钟超时后丢失结果的问题：任务随代理心跳续期，离线任务支持恢复连接后终止与补交历史记录，结果上报失败自动重试且不会重复执行脚本。
+- 修复远程设备无法手动终止回放的问题，通过独立心跳传递取消信号，兼容任务派发前取消，并阻止同一设备重复提交回放。
+
 ## v0.2.2
-- 更新 Vben 风格的浅色后台界面：蓝色主色、白色卡片、浅灰背景、可折叠侧边栏与顶部页签。
 - 新增“概览 → 分析页”，根据已保存脚本和真实执行记录分别汇总 Midscene、Appium 测试数据。
 - 修复配置加载失败后出现空白可保存表单的问题，增加独立错误提示和重试；后端断线后自动尝试重连并支持手动重连，保留页面编辑内容。
 - Appium 配置自动保存失败后保留最新待保存内容并提供“重试保存”；修复切换或关闭 Appium 页签后，离开页面时未保存草稿保护失效的问题。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "android-midscene-automation",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oooooooko/android-midscene-automation.git"
@@ -45,12 +45,12 @@
     "mediabunny": "1.58.0",
     "@dagrejs/dagre": "1.1.5",
     "@element-plus/icons-vue": "2.3.2",
-    "@midscene/android": "https://registry.npmjs.org/@midscene/android/-/android-1.12.7.tgz",
-    "@midscene/android-playground": "https://registry.npmjs.org/@midscene/android-playground/-/android-playground-1.12.7.tgz",
-    "@midscene/core": "https://registry.npmjs.org/@midscene/core/-/core-1.12.7.tgz",
-    "@midscene/playground": "https://registry.npmjs.org/@midscene/playground/-/playground-1.12.7.tgz",
-    "@midscene/shared": "https://registry.npmjs.org/@midscene/shared/-/shared-1.12.7.tgz",
-    "@midscene/web": "https://registry.npmjs.org/@midscene/web/-/web-1.12.7.tgz",
+    "@midscene/android": "https://registry.npmjs.org/@midscene/android/-/android-1.14.0.tgz",
+    "@midscene/android-playground": "https://registry.npmjs.org/@midscene/android-playground/-/android-playground-1.14.0.tgz",
+    "@midscene/core": "https://registry.npmjs.org/@midscene/core/-/core-1.14.0.tgz",
+    "@midscene/playground": "https://registry.npmjs.org/@midscene/playground/-/playground-1.14.0.tgz",
+    "@midscene/shared": "https://registry.npmjs.org/@midscene/shared/-/shared-1.14.0.tgz",
+    "@midscene/web": "https://registry.npmjs.org/@midscene/web/-/web-1.14.0.tgz",
     "@techstark/opencv-js": "5.0.0-release.1",
     "@vitejs/plugin-vue": "6.0.7",
     "@vue-flow/core": "1.48.2",

package/remote-agent/index.ts

@@ -6,7 +6,9 @@ import type { RemoteAgentDevice, RemoteCommand } from '../server/remote-agents/p
 import { replayAppiumScript } from '../server/appium-recorder/appium-runner';
 import type { AppiumRecordedScriptRecord } from '../server/appium-recorder/repository';
 
-const VERSION = '0.1.0';
+const VERSION = '0.2.3';
+const replays = new Map<string, AbortController>();
+let lastHeartbeatAt = Date.now();
 
 function argValue(name: string, fallback = '') {
   const index = process.argv.indexOf(`--${name}`);
@@ -25,7 +27,7 @@ if (!server) {
 
 function execText(command: string, args: string[] = []) {
   return new Promise<string>((resolve, reject) => {
-    execFile(command, args, { maxBuffer: 20 * 1024 * 1024 }, (error, stdout, stderr) => {
+    execFile(command, args, { maxBuffer: 20 * 1024 * 1024, timeout: 10000 }, (error, stdout, stderr) => {
       if (error) {
         reject(new Error(stderr || error.message));
         return;
@@ -37,7 +39,7 @@ function execText(command: string, args: string[] = []) {
 
 function execBuffer(command: string, args: string[] = []) {
   return new Promise<Buffer>((resolve, reject) => {
-    execFile(command, args, { encoding: 'buffer', maxBuffer: 20 * 1024 * 1024 }, (error, stdout, stderr) => {
+    execFile(command, args, { encoding: 'buffer', maxBuffer: 20 * 1024 * 1024, timeout: 10000 }, (error, stdout, stderr) => {
       if (error) {
         reject(new Error(Buffer.isBuffer(stderr) ? stderr.toString() : stderr || error.message));
         return;
@@ -50,10 +52,11 @@ function execBuffer(command: string, args: string[] = []) {
 async function postJson<T>(url: string, body: unknown) {
   const response = await fetch(url, {
     method: 'POST',
+    signal: AbortSignal.timeout(10000),
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify(body),
   });
-  const payload = await response.json().catch(() => ({})) as T & { message?: string };
+  const payload = await response.json() as T & { message?: string };
   if (!response.ok) throw new Error(payload.message || `HTTP ${response.status}`);
   return payload;
 }
@@ -94,7 +97,7 @@ async function getCurrentActivity(deviceId: string) {
   return resumedLine?.match(/\s([\w.$]+\/[\w.$]+)\s/)?.[1] || '';
 }
 
-async function handleCommand(command: RemoteCommand) {
+async function handleCommand(command: RemoteCommand, signal?: AbortSignal) {
   const payload = command.payload || {};
   if (command.type === 'screenshot') {
     const image = await execBuffer('adb', ['-s', command.deviceId, 'exec-out', 'screencap', '-p']);
@@ -135,8 +138,10 @@ async function handleCommand(command: RemoteCommand) {
   if (command.type === 'replay') {
     const script = payload.script as AppiumRecordedScriptRecord | undefined;
     if (!script) throw new Error('远程回放缺少脚本内容');
-    return await replayAppiumScript(script, command.deviceId, undefined, undefined, {
+    return await replayAppiumScript(script, command.deviceId, undefined, signal, {
       screenshotReport: payload.screenshotReport === true,
+      reportSummaryEnabled: typeof payload.reportSummaryEnabled === 'boolean' ? payload.reportSummaryEnabled : undefined,
+      reportSummaryPrompt: typeof payload.reportSummaryPrompt === 'string' ? payload.reportSummaryPrompt : undefined,
       parameters: payload.parameters as import('../src/appium-recorder/variables').TestVariable[] | undefined,
       globalVariables: payload.globalVariables as import('../src/appium-recorder/variables').TestVariable[] | undefined,
       linkedScripts: payload.linkedScripts as AppiumRecordedScriptRecord[] | undefined,
@@ -150,48 +155,71 @@ async function heartbeat() {
     console.warn(`扫描设备失败：${error instanceof Error ? error.message : String(error)}`);
     return [];
   });
-  await postJson(`${server}/api/remote-agents/heartbeat`, {
+  const control = await postJson<{ cancelledCommandIds?: string[] }>(`${server}/api/remote-agents/heartbeat`, {
     agentId,
     agentName,
     version: VERSION,
     token,
     devices,
   });
+  lastHeartbeatAt = Date.now();
+  for (const id of control.cancelledCommandIds || []) replays.get(id)?.abort();
   console.log(`已上报 ${devices.length} 台设备到 ${server}`);
 }
 
 async function reportResult(command: RemoteCommand, ok: boolean, data?: unknown, error?: string) {
-  await postJson(`${server}/api/remote-agents/result`, {
-    agentId,
-    token,
-    commandId: command.id,
-    ok,
-    data,
-    error,
-  });
+  // 上报失败只重试结果，绝不重新执行已经操作过设备的脚本。
+  for (;;) {
+    try {
+      await postJson(`${server}/api/remote-agents/result`, { agentId, token, commandId: command.id, ok, data, error });
+      return;
+    } catch (error) {
+      if (command.type !== 'replay') throw error;
+      console.warn(`结果上报失败，正在重试：${error instanceof Error ? error.message : String(error)}`);
+      await new Promise(resolve => setTimeout(resolve, 3000));
+    }
+  }
 }
 
 async function pollOnce() {
   const url = new URL(`${server}/api/remote-agents/poll`);
   url.searchParams.set('agentId', agentId);
   if (token) url.searchParams.set('token', token);
-  const response = await fetch(url);
+  const response = await fetch(url, { signal: AbortSignal.timeout(10000) });
   const payload = await response.json().catch(() => ({})) as { command?: RemoteCommand | null; message?: string };
   if (!response.ok) throw new Error(payload.message || `HTTP ${response.status}`);
   if (!payload.command) return;
-  try {
-    const result = await handleCommand(payload.command);
-    await reportResult(payload.command, true, result);
-  } catch (error) {
-    await reportResult(payload.command, false, undefined, error instanceof Error ? error.message : String(error));
+  const command = payload.command;
+  const controller = command.type === 'replay' ? new AbortController() : undefined;
+  if (controller) {
+    replays.set(command.id, controller);
+    if (command.cancelled) controller.abort();
   }
+  try {
+    let result: unknown;
+    try {
+      result = await handleCommand(command, controller?.signal);
+    } catch (error) {
+      await reportResult(command, false, undefined, error instanceof Error ? error.message : String(error));
+      return;
+    }
+    await reportResult(command, true, result);
+  } finally { replays.delete(command.id); }
 }
 
 async function main() {
   console.log(`Remote Agent 启动：${agentId}`);
   console.log(`中央服务：${server}`);
   await heartbeat();
-  setInterval(() => void heartbeat().catch((error) => console.warn(`心跳失败：${error.message}`)), 3000);
+  let heartbeatTask: Promise<void> | undefined;
+  setInterval(() => {
+    if (Date.now() - lastHeartbeatAt >= 45000) {
+      for (const controller of replays.values()) controller.abort();
+    }
+    if (!heartbeatTask) heartbeatTask = heartbeat()
+      .catch(error => console.warn(`心跳失败：${error.message}`))
+      .finally(() => { heartbeatTask = undefined; });
+  }, 3000);
   for (;;) {
     await pollOnce().catch((error) => console.warn(`轮询失败：${error.message}`));
     await new Promise((resolve) => setTimeout(resolve, 300));

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

@@ -139,8 +139,9 @@ function normalizeTextForContains(value: string) {
 }
 
 function adbTap(deviceId: string, x: number, y: number) {
+  throwIfReplayStopped();
   return new Promise<void>((resolve, reject) => {
-    execFile(getAdbCommand(), ['-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))], { timeout: 10000, signal: replayContext.getStore()?.signal }, (error, _stdout, stderr) => {
       if (error) {
         reject(new Error(stderr || error.message));
         return;
@@ -150,7 +151,8 @@ function adbTap(deviceId: string, x: number, y: number) {
   });
 }
 
-export function launchAppOnDevice(deviceId: string, packageName: string) {
+export function launchAppOnDevice(deviceId: string, packageName: string, signal = replayContext.getStore()?.signal) {
+  signal?.throwIfAborted();
   if (!packageName) return Promise.reject(new Error('启动 APP 缺少包名'));
   return new Promise<void>((resolve, reject) => {
     execFile(getAdbCommand(), [
@@ -163,7 +165,7 @@ export function launchAppOnDevice(deviceId: string, packageName: string) {
       '-c',
       'android.intent.category.LAUNCHER',
       '1',
-    ], { maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => {
+    ], { maxBuffer: 4 * 1024 * 1024, timeout: 30000, signal }, (error, stdout, stderr) => {
       const output = `${stdout || ''}\n${stderr || ''}`.trim();
       if (error || /no activities found|monkey aborted/i.test(output)) {
         reject(new Error(output || error?.message || `ADB 启动 ${packageName} 失败`));
@@ -174,7 +176,8 @@ export function launchAppOnDevice(deviceId: string, packageName: string) {
   });
 }
 
-export function clearAppDataOnDevice(deviceId: string, packageName: string) {
+export function clearAppDataOnDevice(deviceId: string, packageName: string, signal = replayContext.getStore()?.signal) {
+  signal?.throwIfAborted();
   if (!packageName) return Promise.reject(new Error('清理 App 缓存缺少包名'));
   return new Promise<void>((resolve, reject) => {
     execFile(getAdbCommand(), [
@@ -184,7 +187,7 @@ export function clearAppDataOnDevice(deviceId: string, packageName: string) {
       'pm',
       'clear',
       packageName,
-    ], { maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => {
+    ], { maxBuffer: 4 * 1024 * 1024, timeout: 30000, signal }, (error, stdout, stderr) => {
       const output = `${stdout || ''}\n${stderr || ''}`.trim();
       if (error || !/^success$/im.test(output)) {
         reject(new Error(output || error?.message || `ADB 清理 ${packageName} 失败`));
@@ -196,6 +199,7 @@ export function clearAppDataOnDevice(deviceId: string, packageName: string) {
 }
 
 function adbSwipe(deviceId: string, step: Required<AppiumRecordedStepRecord>['swipe']) {
+  throwIfReplayStopped();
   return new Promise<void>((resolve, reject) => {
     execFile(getAdbCommand(), [
       '-s',
@@ -208,7 +212,7 @@ function adbSwipe(deviceId: string, step: Required<AppiumRecordedStepRecord>['sw
       String(Math.round(step.endX)),
       String(Math.round(step.endY)),
       String(Math.round(step.duration)),
-    ], (error, _stdout, stderr) => {
+    ], { timeout: Math.max(10000, step.duration + 5000), signal: replayContext.getStore()?.signal }, (error, _stdout, stderr) => {
       if (error) {
         reject(new Error(stderr || error.message));
         return;
@@ -294,7 +298,8 @@ async function appiumRequest<T>(
   try {
     const result = await timedAppiumFetch(requestUrl, {
       ...init,
-      signal: options?.ignoreAbort ? undefined : context?.signal || init?.signal,
+      signal: options?.ignoreAbort ? undefined : (context?.signal && init?.signal
+        ? AbortSignal.any([context.signal, init.signal]) : context?.signal || init?.signal),
       headers: {
         'Content-Type': 'application/json',
         ...(init?.headers || {}),
@@ -415,6 +420,8 @@ async function createSession(deviceId: string) {
           'appium:udid': deviceId,
           'appium:autoLaunch': false,
           'appium:noReset': true,
+          // 托管进程由 finally 释放；外部服务保留回收期限，避免创建请求取消后遗留永久会话。
+          'appium:newCommandTimeout': usesManagedAppiumServer() ? 0 : 60,
           'appium:skipDeviceInitialization': true,
           'appium:ignoreHiddenApiPolicyError': true,
         },
@@ -803,7 +810,7 @@ async function runStep(
 
   if (step.type === 'launchApp') {
     const packageName = step.value || '';
-    if (await isAppInForeground(deviceId, packageName).catch(() => false)) {
+    if (await isAppInForeground(deviceId, packageName).catch(error => { throwIfReplayStopped(error); return false; })) {
       return `APP 已在前台，跳过启动 ${packageName}`;
     }
     await launchAppOnDevice(deviceId, packageName);
@@ -1566,6 +1573,7 @@ export async function replayAppiumScript(
     );
     let sessionId = '';
     let sessionCreationStarted = false;
+    let stopHeartbeat: (() => Promise<void>) | undefined;
     let success = false;
     let stopped = false;
     let recording: Awaited<ReturnType<typeof startReplayVideo>> | undefined;
@@ -1594,6 +1602,18 @@ export async function replayAppiumScript(
         await resetUiAutomator2(targetDeviceId);
         sessionId = await createSession(targetDeviceId);
       }
+      if (!managedAppium) {
+        const heartbeatAbort = new AbortController();
+        let heartbeatTask: Promise<unknown> | undefined;
+        const timer = setInterval(() => {
+          if (heartbeatTask || signal?.aborted) return;
+          heartbeatTask = appiumRequest(`/session/${sessionId}/timeouts`, { signal: heartbeatAbort.signal }, { timeoutMs: 5000 })
+            .catch(error => { if (!heartbeatAbort.signal.aborted && !signal?.aborted) lines.push(`Appium 保活失败：${errorDetail(error)}`); })
+            .finally(() => { heartbeatTask = undefined; });
+        }, 15000);
+        timer.unref();
+        stopHeartbeat = async () => { clearInterval(timer); heartbeatAbort.abort(); await heartbeatTask; };
+      }
       lines.push(`Appium session 已创建：${sessionId}`);
       if (runOptions.recordVideo) {
         if (scope.privacy.enabled) throw new Error('本次运行包含敏感变量，为避免泄露已禁止录屏，请关闭录制回放视频');
@@ -1660,6 +1680,7 @@ export async function replayAppiumScript(
           lines.push('[录屏提示] 本次录像未能完整保存。请检查报告目录的写入权限、磁盘空间及设备连接；录像保存失败不等同于流程节点失败，请以节点执行日志为准。');
         }
       }
+      await stopHeartbeat?.();
       let managedAppiumStopped = false;
       if (signal?.aborted && managedAppium) {
         await managedAppium.stop();
@@ -1669,7 +1690,7 @@ export async function replayAppiumScript(
           `/session/${sessionId}`,
           { method: 'DELETE' },
           { ignoreAbort: true, timeoutMs: 2000 },
-        ).catch(() => undefined);
+        ).catch(error => { lines.push(`Appium 会话清理失败：${errorDetail(error)}${managedAppium ? '' : '；外部服务将在命令空闲 60 秒后回收会话'}`); });
       }
       if (managedAppium) {
         if (!managedAppiumStopped) await managedAppium.stop();

package/server/appium-recorder/managed-cleanup.test.ts

@@ -8,12 +8,14 @@ import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
-test('owned device instrumentation is cleaned after success, abort and failed session creation; external servers are untouched', async () => {
+test('replay survives command idle periods and cleans sessions after success, abort and creation failure', async () => {
   const root = await mkdtemp(join(tmpdir(), 'managed-cleanup-'));
   const env = { ...process.env };
   const original = { execFile: childProcess.execFile, spawn: childProcess.spawn, fetch: globalThis.fetch };
   const calls: string[][] = [];
   let mode = 'success', stopped = false;
+  let elapsedMs = 0, lastCommandMs = 0, commandTimeoutMs = 60_000;
+  let keyCommands = 0, deletedSessions = 0;
   let controller = new AbortController();
   try {
     const sdk = join(root, 'sdk');
@@ -44,8 +46,20 @@ test('owned device instrumentation is cleaned after success, abort and failed se
       const path = new URL(String(input)).pathname;
       if (path === '/session' && init?.method === 'POST') {
         if (mode === 'creation-failure') return Response.json({ value: { error: 'session not created', message: 'creation failed' } }, { status: 500 });
+        const capabilities = JSON.parse(String(init.body)).capabilities.alwaysMatch;
+        commandTimeoutMs = (capabilities['appium:newCommandTimeout'] ?? 60) * 1000;
+        lastCommandMs = elapsedMs;
         return Response.json({ value: { sessionId: 'test-session' } });
       }
+      if (path.endsWith('/press_keycode')) {
+        keyCommands++;
+        // Model Appium's idle expiry without waiting a real minute or touching a device.
+        if (commandTimeoutMs && elapsedMs - lastCommandMs > commandTimeoutMs) {
+          return Response.json({ value: { error: 'invalid session id', message: 'New Command Timeout expired' } }, { status: 404 });
+        }
+        lastCommandMs = elapsedMs;
+      }
+      if (path === '/session/test-session' && init?.method === 'DELETE') deletedSessions++;
       return Response.json({ value: {} });
     };
     const { replayAppiumScript } = await import('./appium-runner');
@@ -53,19 +67,35 @@ test('owned device instrumentation is cleaned after success, abort and failed se
       id: 'cleanup', name: 'cleanup', deviceId: 'test-device', appPackage: '', appActivity: '', createdAt: '', updatedAt: '',
       steps: [{ id: 'log', type: 'log' as const, label: 'log', value: 'ok' }],
     };
-    for (mode of ['success', 'abort', 'creation-failure', 'cleanup-failure', 'external']) {
+    for (mode of ['success', 'long-idle', 'abort', 'creation-failure', 'cleanup-failure', 'external', 'external-abort']) {
       calls.length = 0;
+      elapsedMs = lastCommandMs = keyCommands = deletedSessions = 0;
       controller = new AbortController();
-      if (mode === 'external') process.env.APPIUM_SERVER_URL = 'http://external.invalid';
-      const result = await replayAppiumScript(script, 'test-device', line => {
-        if (mode === 'abort' && line.includes('Appium session 已创建')) controller.abort();
+      const external = mode.startsWith('external');
+      const aborted = mode.endsWith('abort');
+      const longIdle = mode.endsWith('long-idle');
+      if (external) process.env.APPIUM_SERVER_URL = 'http://external.invalid';
+      else delete process.env.APPIUM_SERVER_URL;
+      const replayScript = longIdle ? { ...script, steps: [
+        ...script.steps,
+        { id: 'home', type: 'key' as const, label: 'Home', keyCode: 3 },
+      ] } : script;
+      const result = await replayAppiumScript(replayScript, 'test-device', line => {
+        // ADB operations and model inference do not reset Appium's command timer.
+        if (longIdle && line.includes('[节点 1] 完成')) elapsedMs += 120_000;
+        if (aborted && line.includes('Appium session 已创建')) controller.abort();
       }, controller.signal);
-      assert.equal(calls.length, mode === 'external' ? 0 : 2);
-      if (mode !== 'external') {
+      assert.equal(calls.length, external ? 0 : 2);
+      assert.equal(deletedSessions, mode === 'creation-failure' || (aborted && !external) ? 0 : 1, 'release the replay session even when idle expiry is disabled');
+      if (!external) {
         assert.deepEqual(calls.map(args => args.slice(0, 5)), Array(2).fill(['-s', 'test-device', 'shell', 'am', 'force-stop']));
         assert.deepEqual(calls.map(args => args.at(-1)).sort(), ['io.appium.uiautomator2.server', 'io.appium.uiautomator2.server.test']);
       }
-      if (mode === 'abort') assert.equal(result.stopped, true);
+      if (longIdle) {
+        assert.equal(keyCommands, 1, 'execute Home after the long interval without Appium commands');
+        assert.equal(result.success, true, result.output);
+      }
+      if (aborted) assert.equal(result.stopped, true);
       if (mode === 'creation-failure') assert.equal(result.success, false);
       if (mode === 'cleanup-failure') assert.match(result.output, /UiAutomator2 清理失败/);
     }

package/server/appium-recorder/replay-lifecycle.test.ts

@@ -0,0 +1,123 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import childProcess from 'node:child_process';
+import { syncBuiltinESMExports } from 'node:module';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createServer } from 'node:http';
+import type { AppiumRecordedScriptRecord, AppiumRecordedStepRecord } from './repository';
+
+test('ADB cancellation and deadlines cover actions; external sessions survive idle work and expire after creation cancellation', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'replay-lifecycle-'));
+  const env = { ...process.env };
+  const original = { execFile: childProcess.execFile, fetch: globalThis.fetch, setInterval: globalThis.setInterval };
+  let controller = new AbortController();
+  let mode = '', deletes = 0, launchedAfterAbort = false;
+  let requestCount = 0;
+  try {
+    const sdk = join(root, 'sdk');
+    await mkdir(join(sdk, 'platform-tools'), { recursive: true });
+    await writeFile(join(sdk, 'platform-tools', 'adb'), '');
+    Object.assign(process.env, { ANDROID_MIDSCENE_DATA_ROOT: root, ANDROID_HOME: sdk, ANDROID_SDK_ROOT: sdk, APPIUM_SERVER_URL: 'http://external.invalid' });
+    childProcess.execFile = ((_cmd, args: string[], options, callback) => {
+      requestCount++;
+      if (mode === 'foreground-abort' && args.includes('activities')) {
+        queueMicrotask(() => { controller.abort(); callback(new Error('aborted'), '', ''); });
+      } else if (args.includes('monkey') || args.includes('clear') || args.includes('input')) {
+        launchedAfterAbort ||= controller.signal.aborted;
+        assert.ok(options.timeout > 0, 'every device action has a deadline');
+        assert.equal(options.signal, controller.signal);
+        if (mode === 'timeout') {
+          queueMicrotask(() => callback(new Error('ADB command timed out'), '', ''));
+        } else {
+          options.signal.addEventListener('abort', () => callback(new Error('aborted'), '', ''), { once: true });
+          queueMicrotask(() => controller.abort());
+        }
+      } else queueMicrotask(() => callback(null, '', ''));
+      return {};
+    }) as typeof childProcess.execFile;
+    syncBuiltinESMExports();
+    globalThis.fetch = async (input, init) => {
+      if (init?.method === 'DELETE') deletes++;
+      return Response.json({ value: new URL(String(input)).pathname === '/session' ? { sessionId: 'test-session' } : {} });
+    };
+    const { replayAppiumScript, launchAppOnDevice, clearAppDataOnDevice } = await import('./appium-runner');
+    const script: AppiumRecordedScriptRecord = { id: 'audit', name: 'audit', deviceId: 'fake-device', appPackage: '', appActivity: '', createdAt: '', updatedAt: '', steps: [] };
+    const run = (steps: AppiumRecordedStepRecord[]) => replayAppiumScript({ ...script, steps }, 'fake-device', undefined, controller.signal, { screenshotReport: false, reportSummaryEnabled: false });
+    const actions: AppiumRecordedStepRecord[] = [
+      { id: 'launch', type: 'launchApp', label: 'launch', value: 'example.test' },
+      { id: 'clear', type: 'clearAppData', label: 'clear', value: 'example.test' },
+      { id: 'tap', type: 'coordinateTap', label: 'tap', fallback: { strategy: 'bounds', centerX: 10, centerY: 10 } },
+      { id: 'swipe', type: 'swipe', label: 'swipe', swipe: { startX: 10, startY: 10, endX: 50, endY: 50, duration: 100 } },
+    ];
+    for (const action of actions) {
+      mode = 'abort'; controller = new AbortController(); deletes = 0;
+      assert.equal((await run([action])).stopped, true, action.type);
+      assert.equal(deletes, 1, 'abort releases the known external session');
+    }
+    mode = 'foreground-abort'; controller = new AbortController(); launchedAfterAbort = false;
+    assert.equal((await run([actions[0]!])).stopped, true);
+    assert.equal(launchedAfterAbort, false, 'foreground cancellation must not launch monkey');
+    const count = requestCount;
+    assert.throws(() => launchAppOnDevice('fake', 'example.test', controller.signal));
+    assert.throws(() => clearAppDataOnDevice('fake', 'example.test', controller.signal));
+    assert.equal(requestCount, count, 'already-cancelled actions never spawn');
+    mode = 'timeout'; controller = new AbortController(); deletes = 0;
+    const failed = await run([actions[0]!]);
+    assert.equal(failed.success, false); assert.match(failed.output, /timed out/); assert.equal(deletes, 1);
+
+    // A local HTTP server models the idle lease at accelerated time, without a real device.
+    globalThis.fetch = original.fetch;
+    globalThis.setInterval = ((fn, ms, ...args) => original.setInterval(fn, ms === 15000 ? 15 : ms, ...args)) as typeof setInterval;
+    let active = false, timeoutSeconds = 0, heartbeats = 0, homeKeys = 0, deleted = 0;
+    let expiry: ReturnType<typeof setTimeout> | undefined;
+    let createdResolve: () => void = () => {};
+    const renew = () => { clearTimeout(expiry); expiry = setTimeout(() => { active = false; }, timeoutSeconds * 3); };
+    const server = createServer(async (req, res) => {
+      res.setHeader('Content-Type', 'application/json');
+      if (req.url === '/session' && req.method === 'POST') {
+        let body = ''; for await (const chunk of req) body += chunk;
+        timeoutSeconds = JSON.parse(body).capabilities.alwaysMatch['appium:newCommandTimeout'];
+        if (mode === 'creation-abort') { controller.abort(); await new Promise(resolve => setTimeout(resolve, 20)); }
+        active = true; renew(); createdResolve();
+        res.end(JSON.stringify({ value: { sessionId: 'delayed-session' } }));
+      } else if (req.method === 'DELETE') {
+        deleted++; active = false; clearTimeout(expiry); res.end('{"value":null}');
+      } else if (!active) {
+        res.statusCode = 404; res.end('{"value":{"error":"invalid session id"}}');
+      } else {
+        renew();
+        if (req.url?.endsWith('/timeouts')) heartbeats++;
+        if (req.url?.endsWith('/press_keycode')) homeKeys++;
+        res.end('{"value":{}}');
+      }
+    });
+    await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
+    process.env.APPIUM_SERVER_URL = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+    try {
+      mode = 'long-idle'; controller = new AbortController();
+      const result = await run([{ id: 'wait', type: 'delay', label: 'idle', timeoutMs: 450 }, { id: 'home', type: 'key', label: 'Home', keyCode: 3 }]);
+      assert.equal(result.success, true, result.output);
+      assert.equal(timeoutSeconds, 60); assert.ok(heartbeats > 3); assert.equal(homeKeys, 1); assert.equal(deleted, 1);
+      const heartbeatCount = heartbeats;
+      await new Promise(resolve => setTimeout(resolve, 40));
+      assert.equal(heartbeats, heartbeatCount, 'heartbeat stops after cleanup');
+      mode = 'creation-abort'; controller = new AbortController();
+      const created = new Promise<void>(resolve => { createdResolve = resolve; });
+      assert.equal((await run([actions[0]!])).stopped, true);
+      await created;
+      assert.equal(active, true, 'server can create a session after the client cancelled');
+      await new Promise(resolve => setTimeout(resolve, 220));
+      assert.equal(active, false, 'unclaimed external session has a finite idle lease');
+    } finally {
+      clearTimeout(expiry); server.closeAllConnections(); await new Promise<void>(resolve => server.close(() => resolve()));
+    }
+  } finally {
+    childProcess.execFile = original.execFile; globalThis.fetch = original.fetch; globalThis.setInterval = original.setInterval; syncBuiltinESMExports();
+    for (const key of ['ANDROID_MIDSCENE_DATA_ROOT', 'ANDROID_HOME', 'ANDROID_SDK_ROOT', 'APPIUM_SERVER_URL']) {
+      if (env[key] === undefined) delete process.env[key]; else process.env[key] = env[key];
+    }
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/server/appium-recorder/routes.ts

@@ -24,7 +24,7 @@ import {
   type AppiumRecordedStepRecord,
 } from './repository';
 import { clearAppDataOnDevice, launchAppOnDevice, replayAppiumScript } from './appium-runner';
-import { isRemoteDeviceId, sendRemoteCommand } from '../remote-agents/registry';
+import { isRemoteDeviceId, sendRemoteCommand, stopRemoteReplay } from '../remote-agents/registry';
 import { getAdbCommand } from '../android-sdk';
 import { createAppiumScriptExport } from './script-export';
 import { resolveReportSummary } from '../../src/appium-recorder/report-summary';
@@ -47,7 +47,7 @@ function sendStreamEvent(res: ServerResponse, payload: unknown) {
 
 function execFileText(command: string, args: string[] = []) {
   return new Promise<string>((resolve, reject) => {
-    execFile(command, args, { maxBuffer: 20 * 1024 * 1024 }, (error, stdout, stderr) => {
+    execFile(command, args, { maxBuffer: 20 * 1024 * 1024, timeout: 10000 }, (error, stdout, stderr) => {
       if (error) {
         reject(new Error(stderr || error.message));
         return;
@@ -376,6 +376,10 @@ export async function handleAppiumRecorderRequest(
       const parsed = await readBody<{ deviceId?: string }>(req);
       const deviceId = parsed.deviceId || selectedDeviceId;
       assertDeviceAllowed(deviceId);
+      if (isRemoteDeviceId(deviceId)) {
+        sendJson(res, { success: true, stopped: stopRemoteReplay(deviceId) });
+        return true;
+      }
       const controller = replayAbortControllers.get(deviceId);
       controller?.abort();
       sendJson(res, { success: true, stopped: Boolean(controller) });
@@ -434,10 +438,6 @@ export async function handleAppiumRecorderRequest(
           globalVariables: getPresetVariables(),
           linkedScripts: linkedScriptSnapshot(script),
         }) as Awaited<ReturnType<typeof replayAppiumScript>>;
-        if (result.history) {
-          try { saveRunHistory({ ...result.history, scriptId: script.id, deviceId }); }
-          catch { result.output += '\n历史记录保存失败'; }
-        }
         const { history: _history, ...response } = result;
         if (streamOutput) {
           result.output?.split(/\r?\n/).forEach((line) => sendStreamEvent(res, { type: 'log', line }));

package/server/http-api.ts

@@ -79,7 +79,7 @@ function delay(ms: number) {
   });
 }
 
-// Work around @midscene/android-playground v1.12.x ESM __dirname usage on Node 24.
+// Keep the Android Playground launcher compatible with Node 24 ESM execution.
 const START_ANDROID_PLAYGROUND_WITHOUT_BROWSER = [
   "import { createRequire } from 'node:module';",
   'const require = createRequire(import.meta.url);',

package/server/remote-agents/protocol.ts

@@ -20,6 +20,7 @@ export type RemoteCommand = {
   type: RemoteCommandType;
   deviceId: string;
   payload?: Record<string, unknown>;
+  cancelled?: boolean;
 };
 
 export type RemoteCommandResult = {