android-midscene-automation 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,8 +1,22 @@
 # 更新记录
+## v0.2.3
+- 修复长时间执行 ADB 操作、延时或 AI 识别后，Appium 因默认 60 秒命令空闲超时销毁会话，导致后续 Home 键、点击等节点报“invalid session id”的问题；托管服务关闭会话空闲计时，外部服务通过心跳保活并保留 60 秒空闲回收，避免创建请求取消或清理失败后遗留永久会话。
+- 为启动 App、清理数据、坐标点击与滑动补齐 ADB 超时和取消控制；终止前台检查后不再继续启动 App，异常结束仍清理会话。
+- 修复远程回放固定 10 分钟超时后丢失结果的问题：任务随代理心跳续期，离线任务支持恢复连接后终止与补交历史记录，结果上报失败自动重试且不会重复执行脚本。
+- 修复远程设备无法手动终止回放的问题，通过独立心跳传递取消信号，兼容任务派发前取消，并阻止同一设备重复提交回放。
+
+## v0.2.2
+- 更新浅色后台界面：蓝色主色、白色卡片、浅灰背景、可折叠侧边栏与顶部页签。
+- 新增“概览 → 分析页”，根据已保存脚本和真实执行记录分别汇总 Midscene、Appium 测试数据。
+- 修复配置加载失败后出现空白可保存表单的问题，增加独立错误提示和重试；后端断线后自动尝试重连并支持手动重连，保留页面编辑内容。
+- Appium 配置自动保存失败后保留最新待保存内容并提供“重试保存”；修复切换或关闭 Appium 页签后，离开页面时未保存草稿保护失效的问题。
+- Appium 顶部工具栏改为随页面布局排列，窄屏自动换行，避免遮挡面包屑；统一全站样式与中文组件文案，合并重复主题声明。
+- 完善隔离数据环境下的浏览器回归测试，以及请求校验、配置保护、自动保存重试和统计口径测试。
+
 ## v0.2.1
 - 侧边栏底部新增“帮助与版本”入口。
 - AI 识别预设提示词支持编辑测试场景名称和提示词内容，默认预设与自定义预设均可修改并自动保存。
-- AI 识别启用分支后可勾选“启用兜底”，再选择进入左侧 true 或右侧 false 分支；适用范围改为问号提示，正常识别结果不受影响。
+- AI 识别启用分支后可勾选“启用兜底”，再选择进入左侧 true 或右侧 false 分支；正常识别结果不受影响。
 
 ## v0.1.43
 - 新增独立的“提示词优化模型”，统一用于优化 AI 识别提示词、报告提示词和生成回放测试报告总结；AI 识别与回放报告均可输入简要要求后由模型补充提示词，模型测试成功改为弹窗提示。

package/README.md

@@ -1358,10 +1358,24 @@ Linux: ~/.local/share/android-midscene-automation
 
 # 项目更新记录
 
+## v0.2.3
+- 修复长时间执行 ADB 操作、延时或 AI 识别后，Appium 因默认 60 秒命令空闲超时销毁会话，导致后续 Home 键、点击等节点报“invalid session id”的问题；托管服务关闭会话空闲计时，外部服务通过心跳保活并保留 60 秒空闲回收，避免创建请求取消或清理失败后遗留永久会话。
+- 为启动 App、清理数据、坐标点击与滑动补齐 ADB 超时和取消控制；终止前台检查后不再继续启动 App，异常结束仍清理会话。
+- 修复远程回放固定 10 分钟超时后丢失结果的问题：任务随代理心跳续期，离线任务支持恢复连接后终止与补交历史记录，结果上报失败自动重试且不会重复执行脚本。
+- 修复远程设备无法手动终止回放的问题，通过独立心跳传递取消信号，兼容任务派发前取消，并阻止同一设备重复提交回放。
+
+## v0.2.2
+- 更新浅色后台界面：蓝色主色、白色卡片、浅灰背景、可折叠侧边栏与顶部页签。
+- 新增“概览 → 分析页”，根据已保存脚本和真实执行记录分别汇总 Midscene、Appium 测试数据。
+- 修复配置加载失败后出现空白可保存表单的问题，增加独立错误提示和重试；后端断线后自动尝试重连并支持手动重连，保留页面编辑内容。
+- Appium 配置自动保存失败后保留最新待保存内容并提供“重试保存”；修复切换或关闭 Appium 页签后，离开页面时未保存草稿保护失效的问题。
+- Appium 顶部工具栏改为随页面布局排列，窄屏自动换行，避免遮挡面包屑；统一全站样式与中文组件文案，合并重复主题声明。
+- 完善隔离数据环境下的浏览器回归测试，以及请求校验、配置保护、自动保存重试和统计口径测试。
+
 ## v0.2.1
 - 侧边栏底部新增“帮助与版本”入口。
 - AI 识别预设提示词支持编辑测试场景名称和提示词内容，默认预设与自定义预设均可修改并自动保存。
-- AI 识别启用分支后可勾选“启用兜底”，再选择进入左侧 true 或右侧 false 分支；适用范围改为问号提示，正常识别结果不受影响。
+- AI 识别启用分支后可勾选“启用兜底”，再选择进入左侧 true 或右侧 false 分支；正常识别结果不受影响。
 
 ## v0.1.43
 - 新增独立的“提示词优化模型”，统一用于优化 AI 识别提示词、报告提示词和生成回放测试报告总结；AI 识别与回放报告均可输入简要要求后由模型补充提示词，模型测试成功改为弹窗提示。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "android-midscene-automation",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oooooooko/android-midscene-automation.git"

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/analytics.test.ts

@@ -0,0 +1,46 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { summarizeTests, type TestRun } from '../src/analytics/summary';
+
+test('analytics includes unrun and historical scripts and excludes stopped/running from pass rate and average duration', () => {
+  const runs: TestRun[] = ['passed', 'failed', 'stopped', 'running'].map((status, i) => ({
+    scriptId: 'a', scriptName: 'old name', status: status as TestRun['status'], startedAt: `2026-09-2${i}T00:00:00Z`, durationMs: 1000 * (i + 1),
+  }));
+  runs.push({ scriptId: 'deleted', scriptName: '历史测试', status: 'passed', startedAt: '2026-09-01T00:00:00Z', durationMs: 10 });
+  const result = summarizeTests([{ id: 'a', name: '新名称' }, { id: 'b', name: '未执行' }], runs);
+  assert.equal(result.scripts, 2);
+  assert.equal(result.runs, 5);
+  assert.equal(result.testedScripts, 1);
+  assert.equal(result.passRate, 2 / 3);
+  const a = result.rows.find(row => row.id === 'a')!;
+  assert.equal(a.name, '新名称');
+  assert.equal(a.averageDurationMs, 1500);
+  assert.equal(a.passRate, 0.5);
+  assert.equal(a.lastStatus, 'running');
+  assert.equal(result.rows.find(row => row.id === 'b')?.passRate, null);
+  assert.equal(result.rows.find(row => row.id === 'deleted')?.archived, true);
+  const recent = summarizeTests([{ id: 'b', name: '未执行' }], runs, Date.parse('2026-09-22T00:00:00Z'));
+  assert.equal(recent.runs, 2);
+  assert.equal(recent.passRate, null);
+  assert.equal(recent.rows.find(row => row.id === 'a')?.averageDurationMs, null);
+});
+
+
+test('daily/monthly charts zero-fill calendar buckets and retain older runs in all-time totals', () => {
+  const now = new Date(2026, 0, 2, 12).getTime();
+  const runs: TestRun[] = [
+    { scriptId: 'a', scriptName: 'a', status: 'passed', startedAt: new Date(2026, 0, 2, 8).toISOString(), durationMs: 10 },
+    { scriptId: 'a', scriptName: 'a', status: 'failed', startedAt: new Date(2024, 0, 1).toISOString(), durationMs: 10 },
+  ];
+  const all = summarizeTests([], runs, 0, now);
+  assert.equal(all.runs, 2);
+  assert.equal(all.daily.length, 30);
+  assert.equal(all.monthly.length, 12);
+  assert.deepEqual(all.monthly.at(-1), { date: '2026-01', runs: 1 });
+  assert.equal(all.daily.reduce((sum, point) => sum + point.runs, 0), 1);
+  const recent = summarizeTests([], runs, new Date(2025, 11, 27).getTime(), now);
+  assert.equal(recent.daily.length, 7);
+  assert.equal(recent.monthly.length, 2);
+  assert.equal(recent.runs, 1);
+  assert.equal(recent.daily.at(-1)?.date, '2026-01-02');
+});

package/server/analytics.ts

@@ -0,0 +1,24 @@
+import { summarizeTests, type AnalysisResponse, type TestStatus } from '../src/analytics/summary';
+import { listScriptRecords } from './script-db';
+import { listAppiumRecordedScripts } from './appium-recorder/repository';
+import { listOperationAnalytics } from './operations/repository';
+import { listRunAnalytics } from './appium-recorder/run-history';
+
+export function getTestAnalytics(days = 0): AnalysisResponse {
+  const generatedAt = new Date().toISOString();
+  const start = new Date(generatedAt);
+  start.setDate(start.getDate() - Math.max(0, days - 1));
+  start.setHours(0, 0, 0, 0);
+  const since = days ? start.getTime() : 0;
+  const status: Record<string, TestStatus> = { succeeded: 'passed', failed: 'failed', cancelled: 'stopped', running: 'running' };
+  return {
+    generatedAt, days,
+    // Midscene's historical records identify scripts by name, not database ID.
+    midscene: summarizeTests(listScriptRecords().map(script => ({ id: script.name, name: script.name })), listOperationAnalytics().map(run => ({
+      scriptId: run.script_name, scriptName: run.script_name, startedAt: run.started_at,
+      durationMs: run.finished_at ? Date.parse(run.finished_at) - Date.parse(run.started_at) : null,
+      status: status[run.status],
+    })), since, Date.parse(generatedAt)),
+    appium: summarizeTests(listAppiumRecordedScripts().map(script => ({ id: script.id, name: script.name })), listRunAnalytics(), since, Date.parse(generatedAt)),
+  };
+}

package/server/api-safety-analytics.test.ts

@@ -0,0 +1,57 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { AnalysisResponse } from '../src/analytics/summary';
+
+test('API rejects malformed requests safely and analytics reads all stored executions without a 100-record cap', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'console-api-'));
+  const oldRoot = process.env.ANDROID_MIDSCENE_DATA_ROOT;
+  process.env.ANDROID_MIDSCENE_DATA_ROOT = root;
+  const { createApiMiddleware } = await import('./http-api');
+  const handler = createApiMiddleware();
+  const server = createServer((req, res) => handler(req, res, () => { res.statusCode = 404; res.end(); }));
+  try {
+    await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    assert.ok(address && typeof address === 'object');
+    const base = `http://127.0.0.1:${address.port}`;
+    for (const path of ['/api/config', '/api/config/appium', '/api/test-model', '/api/appium-recorder/scripts', '/api/generate']) {
+      assert.equal((await fetch(base + path, { method: 'POST', body: '{' })).status, 400, path);
+    }
+    assert.equal((await fetch(base + '/api/config', { headers: { Origin: 'https://foreign.example' } })).status, 403);
+    assert.equal((await fetch(base + '/api/config')).status, 200);
+    const { upsertScriptRecord } = await import('./script-db');
+    upsertScriptRecord({ name: 'Midscene 测试', promptTitle: '', sourcePrompt: '', code: 'private-code', filePath: '', steps: [] });
+    upsertScriptRecord({ name: '未执行', promptTitle: '', sourcePrompt: '', code: '', filePath: '', steps: [] });
+    const { initOperationRepository } = await import('./operations/repository');
+    const { runSql, sqlString } = await import('./storage/sqlite');
+    initOperationRepository();
+    const started = new Date(Date.now() - 10_000).toISOString();
+    const finished = new Date().toISOString();
+    runSql(Array.from({ length: 105 }, (_, i) => `INSERT INTO operations (id, kind, status, script_name, device_id, session_id, created_at, started_at, finished_at) VALUES ('op-${i}', 'script_run', '${i === 0 ? 'failed' : 'succeeded'}', 'Midscene 测试', '', '', ${sqlString(started)}, ${sqlString(started)}, ${sqlString(finished)});`).join('\n'));
+    const { saveAppiumRecordedScript } = await import('./appium-recorder/repository');
+    const script = saveAppiumRecordedScript({ name: 'Appium 测试', appPackage: 'example.test', steps: [] });
+    const { saveRunHistory } = await import('./appium-recorder/run-history');
+    saveRunHistory({ scriptId: script.id, scriptName: script.name, appPackage: 'example.test', appVersion: '1', deviceId: '', startedAt: started, durationMs: 4000, status: 'passed', nodes: [], output: 'private-output', frames: [] });
+    const response = await fetch(base + '/api/analytics');
+    const body = await response.text();
+    const summary = JSON.parse(body) as AnalysisResponse;
+    assert.equal(response.status, 200);
+    assert.equal(summary.midscene.runs, 105);
+    assert.equal(summary.midscene.scripts, 2);
+    assert.equal(summary.midscene.failed, 1);
+    assert.equal(summary.midscene.rows.find(row => row.name === '未执行')?.runs, 0);
+    assert.equal(summary.appium.runs, 1);
+    assert.equal(summary.appium.passRate, 1);
+    assert.equal(body.includes('private-'), false);
+    assert.equal((await fetch(base + '/api/analytics?days=invalid')).status, 400);
+  } finally {
+    server.closeAllConnections();
+    await new Promise<void>(resolve => server.close(() => resolve()));
+    if (oldRoot === undefined) delete process.env.ANDROID_MIDSCENE_DATA_ROOT; else process.env.ANDROID_MIDSCENE_DATA_ROOT = oldRoot;
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/server/appium-auto-save.test.ts

@@ -52,7 +52,13 @@ test('loads quietly, serializes rapid edits, validates colors and surfaces save
     await delay(400);
     assert.equal(errors.length, 1);
     assert.match(auto.status.value, /失败/);
+    assert.equal(auto.failed.value, true);
+    assert.equal(auto.dirty.value, true);
     fail = false;
+    await auto.retry();
+    assert.equal(auto.failed.value, false);
+    assert.equal(auto.dirty.value, false);
+    assert.equal(submissions.at(-1)?.screenshotReport, true);
     form.appium.flowBackgroundColor = '#abcdef';
     await delay(400);
     assert.equal(auto.status.value, '已自动保存');

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/appium-version.test.ts

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import childProcess from 'node:child_process';
+import { syncBuiltinESMExports } from 'node:module';
+import { getAppiumVersion } from './managed-appium';
+
+test('Appium version uses the configured runtime and reports unavailable versions without a guessed fallback', async () => {
+  const original = { execFile: childProcess.execFile, fetch: globalThis.fetch };
+  const env = { executable: process.env.APPIUM_EXECUTABLE, url: process.env.APPIUM_SERVER_URL };
+  let output = '3.5.0-beta.1\n';
+  let commandError: Error | null = null;
+  let executions = 0;
+  try {
+    delete process.env.APPIUM_SERVER_URL;
+    process.env.APPIUM_EXECUTABLE = '/custom/appium';
+    childProcess.execFile = ((command, args, options, callback) => {
+      executions++;
+      assert.equal(command, '/custom/appium');
+      assert.deepEqual(args, ['--version']);
+      assert.equal(options.timeout, 5000);
+      queueMicrotask(() => callback(commandError, output, ''));
+      return {};
+    }) as typeof childProcess.execFile;
+    syncBuiltinESMExports();
+    assert.equal((await getAppiumVersion()).version, '3.5.0-beta.1');
+    output = 'Warning: Node 24.19.0 is unsupported';
+    assert.equal((await getAppiumVersion()).version, null, 'do not mistake diagnostic output for the Appium version');
+    commandError = Object.assign(new Error('missing'), { code: 'ENOENT' });
+    assert.match((await getAppiumVersion()).message, /未检测到/);
+    commandError = new Error('timeout');
+    assert.match((await getAppiumVersion()).message, /读取.*失败/);
+
+    process.env.APPIUM_SERVER_URL = 'http://appium.example/wd/hub/';
+    const localExecutions = executions;
+    globalThis.fetch = async (url, options) => {
+      assert.equal(url, 'http://appium.example/wd/hub/status');
+      assert.ok(options?.signal);
+      return Response.json({ value: { ready: true, build: { version: '2.19.0' } } });
+    };
+    assert.deepEqual(await getAppiumVersion(), { version: '2.19.0', source: 'server', message: '当前配置的 Appium 服务' });
+    globalThis.fetch = async () => Response.json({ value: {} });
+    assert.equal((await getAppiumVersion()).version, null);
+    globalThis.fetch = async () => new Response('unavailable', { status: 503 });
+    assert.match((await getAppiumVersion()).message, /无法连接/);
+    globalThis.fetch = async () => { throw new Error('offline'); };
+    assert.equal((await getAppiumVersion()).version, null);
+    assert.equal(executions, localExecutions, 'external service failures must not show an unrelated local version');
+  } finally {
+    childProcess.execFile = original.execFile;
+    globalThis.fetch = original.fetch;
+    syncBuiltinESMExports();
+    if (env.executable === undefined) delete process.env.APPIUM_EXECUTABLE; else process.env.APPIUM_EXECUTABLE = env.executable;
+    if (env.url === undefined) delete process.env.APPIUM_SERVER_URL; else process.env.APPIUM_SERVER_URL = env.url;
+  }
+});

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

@@ -1,5 +1,41 @@
 import { execFile, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { createServer } from 'node:net';
+import type { AppiumVersionInfo } from '../../src/types';
+
+function appiumExecutable() {
+  return process.env.APPIUM_EXECUTABLE?.trim() || (process.platform === 'win32' ? 'appium.cmd' : 'appium');
+}
+
+export async function getAppiumVersion(): Promise<AppiumVersionInfo> {
+  const source = usesManagedAppiumServer() ? 'local' : 'server';
+  try {
+    let output: unknown;
+    if (source === 'server') {
+      const url = process.env.APPIUM_SERVER_URL!.trim().replace(/\/+$/, '');
+      const response = await fetch(`${url}/status`, { signal: AbortSignal.timeout(3000) });
+      if (!response.ok) throw new Error('Appium status request failed');
+      const payload = await response.json() as { value?: { build?: { version?: unknown } } } | null;
+      output = payload?.value?.build?.version;
+    } else {
+      output = await new Promise<string>((resolve, reject) => {
+        execFile(appiumExecutable(), ['--version'], {
+          timeout: 5000, maxBuffer: 64 * 1024, windowsHide: true, shell: process.platform === 'win32',
+        }, (error, stdout) => error ? reject(error) : resolve(stdout));
+      });
+    }
+    const version = typeof output === 'string'
+      ? output.match(/^\s*v?(\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?)\s*$/m)?.[1]
+      : undefined;
+    return { version: version ?? null, source, message: version
+      ? (source === 'local' ? '本机已安装 · Android 自动化引擎' : '当前配置的 Appium 服务')
+      : '未返回有效版本号，请检查 Appium 安装或服务状态' };
+  } catch (error) {
+    const missing = error instanceof Error && 'code' in error && error.code === 'ENOENT';
+    return { version: null, source, message: source === 'server'
+      ? '暂时无法连接 Appium 服务，请检查服务后刷新'
+      : missing ? '未检测到 Appium，请安装或检查可执行文件路径' : '读取 Appium 版本失败，请检查安装后刷新' };
+  }
+}
 
 type ManagedAppiumServer = {
   serverUrl: string;
@@ -110,7 +146,7 @@ export async function startManagedAppiumServer(
 ): Promise<ManagedAppiumServer> {
   const port = await reserveLocalPort();
   const serverUrl = `http://127.0.0.1:${port}`;
-  const executable = process.env.APPIUM_EXECUTABLE?.trim() || (process.platform === 'win32' ? 'appium.cmd' : 'appium');
+  const executable = appiumExecutable();
   const args = [
     '--address',
     '127.0.0.1',