android-midscene-automation 0.2.1 → 0.2.3

package/server/http-api.ts

@@ -1,3 +1,6 @@
+import { getTestAnalytics } from './analytics';
+import { readBody, readRawBody, requestErrorStatus } from './request-body';
+import { canManageConfig, publicConfig, resolveSavedModelKey } from './config-access';
 import { resolveReportSummary } from '../src/appium-recorder/report-summary';
 // The Midscene Admin HTTP API — extracted from vite.config.ts so the exact
 // same middleware serves the standalone dev/preview flow AND the DSH plugin.
@@ -36,37 +39,12 @@ import {
 import { listScriptRecords, type ScriptStepRecord } from './script-db';
 import { importTestCaseFile, MAX_TEST_CASE_FILE_SIZE } from './test-case-import/service';
 import { handleAppiumRecorderRequest } from './appium-recorder/routes';
+import { getAppiumVersion } from './appium-recorder/managed-appium';
 import { handleRemoteAgentRequest } from './remote-agents/routes';
 import { isRemoteDeviceId, listRemoteAndroidDevices, sendRemoteCommand } from './remote-agents/registry';
 import { getAdbCommand } from './android-sdk';
 import { readAndroidDeviceInfo } from './android-device-info';
 
-async function readBody<T>(req: IncomingMessage) {
-  let body = '';
-  req.on('data', (chunk) => {
-    body += chunk;
-  });
-
-  return await new Promise<T>((resolve) => {
-    req.on('end', () => {
-      resolve(JSON.parse(body || '{}') as T);
-    });
-  });
-}
-
-async function readRawBody(req: IncomingMessage) {
-  const chunks: Buffer[] = [];
-  req.on('data', (chunk) => {
-    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-  });
-
-  return await new Promise<Buffer>((resolve) => {
-    req.on('end', () => {
-      resolve(Buffer.concat(chunks));
-    });
-  });
-}
-
 function execFileText(command: string, args: string[] = []) {
   return new Promise<string>((resolve, reject) => {
     execFile(command, args, { maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
@@ -637,6 +615,12 @@ export function createApiMiddleware() {
     const requestUrl = new URL(req.url || '/', 'http://localhost');
     const pathname = requestUrl.pathname;
     const allowLocalDevice = isLocalRequest(req);
+    if ((pathname === '/api/config' || pathname.startsWith('/api/config/') || pathname === '/api/test-model') && !canManageConfig(req)) {
+      res.statusCode = 403;
+      res.setHeader('Content-Type', 'application/json; charset=utf-8');
+      res.end(JSON.stringify({ message: '参数配置仅允许在本机页面访问' }));
+      return;
+    }
     let selectedDeviceId = getSelectedDeviceId(req, res);
     if (!allowLocalDevice && selectedDeviceId && !isRemoteDeviceId(selectedDeviceId)) {
       selectedDeviceId = '';
@@ -667,7 +651,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ sessions: listDeviceSessions() }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : '读取设备会话失败' }));
       }
@@ -679,7 +663,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ locks: listActiveDeviceLocks() }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : '读取设备锁失败' }));
       }
@@ -704,16 +688,37 @@ export function createApiMiddleware() {
         const limit = Number(requestUrl.searchParams.get('limit') || 30);
         res.end(JSON.stringify({ operations: listOperations(limit) }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : '读取执行记录失败' }));
       }
       return;
     }
 
+    if (pathname === '/api/analytics' && req.method === 'GET') {
+      res.setHeader('Content-Type', 'application/json; charset=utf-8');
+      res.setHeader('Cache-Control', 'no-store');
+      try {
+        const days = Number(requestUrl.searchParams.get('days') || 0);
+        if (![0, 7, 30, 90].includes(days)) { res.statusCode = 400; res.end(JSON.stringify({ message: '请选择有效的统计范围' })); return; }
+        res.end(JSON.stringify(getTestAnalytics(days)));
+      } catch (error) {
+        res.statusCode = 500;
+        res.end(JSON.stringify({ message: error instanceof Error ? error.message : '统计数据加载失败' }));
+      }
+      return;
+    }
+
+    if (pathname === '/api/appium-version' && req.method === 'GET') {
+      res.setHeader('Content-Type', 'application/json; charset=utf-8');
+      res.setHeader('Cache-Control', 'no-store');
+      res.end(JSON.stringify(await getAppiumVersion()));
+      return;
+    }
+
     if (req.url === '/api/config' && req.method === 'GET') {
       res.setHeader('Content-Type', 'application/json; charset=utf-8');
-      res.end(JSON.stringify(loadConfig()));
+      res.end(JSON.stringify(publicConfig(loadConfig())));
       return;
     }
 
@@ -732,7 +737,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ success: true }));
       } catch (error) {
-        res.statusCode = error instanceof ConfigValidationError ? 400 : 500;
+        res.statusCode = requestErrorStatus(error, error instanceof ConfigValidationError ? 400 : 500);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
       }
@@ -756,7 +761,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ devices, currentDeviceId: selectedDeviceId }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
       }
@@ -781,7 +786,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ success: true, currentDeviceId: selectedDeviceId }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
       }
@@ -817,7 +822,7 @@ export function createApiMiddleware() {
           res.end(stdout);
         });
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
       }
@@ -847,7 +852,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ success: true, ...result }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
       }
@@ -876,7 +881,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ success: true, ...result }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
       }
@@ -894,7 +899,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ deviceId, details }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : '读取设备信息失败' }));
       }
@@ -918,7 +923,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ deviceId, ...displayInfo }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
       }
@@ -961,7 +966,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ success: true, ...result }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
       }
@@ -1042,7 +1047,7 @@ export function createApiMiddleware() {
           skippedReason: result.skippedReason,
         }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : '启动 Android Playground 失败' }));
       }
@@ -1088,7 +1093,7 @@ export function createApiMiddleware() {
           skippedReason: result.skippedReason,
         }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : '重启 Android Playground 失败' }));
       }
@@ -1108,7 +1113,11 @@ export function createApiMiddleware() {
             family?: string;
           };
         }>(req);
-        const model = parsed.model || {};
+        const model = { ...parsed.model };
+        const stored = loadConfig();
+        const savedModel = parsed.modelKey === 'promptOptimizer' ? stored.appium.promptOptimizer?.model
+          : parsed.modelKey && ['midscene', 'scriptOptimizer', 'appium'].includes(parsed.modelKey) ? stored[parsed.modelKey as 'midscene' | 'scriptOptimizer' | 'appium'].model : undefined;
+        model.apiKey = resolveSavedModelKey(model, savedModel);
 
         if (parsed.save && !['midscene', 'scriptOptimizer', 'appium', 'promptOptimizer'].includes(parsed.modelKey || '')) {
           throw new ConfigValidationError('请选择有效的模型配置');
@@ -1136,7 +1145,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ ...result, saved: parsed.save === true }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
       }
@@ -1148,7 +1157,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ apps: listAppPresetRecords() }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
       }
@@ -1166,7 +1175,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ app }));
       } catch (error) {
-        res.statusCode = 400;
+        res.statusCode = requestErrorStatus(error, 400);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : '保存 App 配置失败' }));
       }
@@ -1180,7 +1189,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify(removeAppPresetRecord(parsed.id)));
       } catch (error) {
-        res.statusCode = 400;
+        res.statusCode = requestErrorStatus(error, 400);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : '删除 App 配置失败' }));
       }
@@ -1196,7 +1205,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify(result));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
       }
@@ -1210,12 +1219,12 @@ export function createApiMiddleware() {
           throw new Error('文件大小不能超过 10MB');
         }
         const fileName = requestUrl.searchParams.get('fileName') || '';
-        const buffer = await readRawBody(req);
+        const buffer = await readRawBody(req, MAX_TEST_CASE_FILE_SIZE);
         const result = await importTestCaseFile({ fileName, buffer });
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify(result));
       } catch (error) {
-        res.statusCode = 400;
+        res.statusCode = requestErrorStatus(error, 400);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : '测试用例文件解析失败' }));
       }
@@ -1229,7 +1238,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ valid: true }));
       } catch (error) {
-        res.statusCode = 400;
+        res.statusCode = requestErrorStatus(error, 400);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : '代码格式错误' }));
       }
@@ -1241,7 +1250,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ scripts: listScriptRecords() }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
       }
@@ -1257,7 +1266,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify(deleteGeneratedScript({ id: parsed.id })));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = requestErrorStatus(error);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
       }
@@ -1277,7 +1286,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify(result));
       } catch (error) {
-        res.statusCode = 400;
+        res.statusCode = requestErrorStatus(error, 400);
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : '保存代码失败' }));
       }
@@ -1474,7 +1483,7 @@ export function createApiMiddleware() {
         return;
       }
     } catch (error) {
-      res.statusCode = 500;
+      res.statusCode = requestErrorStatus(error);
       res.setHeader('Content-Type', 'application/json; charset=utf-8');
       res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
     }

package/server/operations/repository.ts

@@ -216,3 +216,11 @@ export function listOperationEventRecords(operationId: string) {
     ORDER BY seq ASC;
   `).map(rowToEvent);
 }
+
+// Analytics only reads metadata, never model prompts, outputs or credentials.
+export function listOperationAnalytics() {
+  initOperationRepository();
+  return querySql<Pick<OperationRow, 'script_name' | 'started_at' | 'finished_at' | 'status'>>(`
+    SELECT script_name, started_at, finished_at, status FROM operations WHERE kind = 'script_run';
+  `);
+}

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 = {

package/server/remote-agents/registry.test.ts

@@ -0,0 +1,65 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { registerRemoteAgent, makeRemoteDeviceId, sendRemoteCommand, pollRemoteCommand, completeRemoteCommand, stopRemoteReplay } from './registry';
+
+test('replay heartbeat renews beyond ten minutes, cancellation survives dispatch, late results save once', async () => {
+  const originalSetTimeout = globalThis.setTimeout;
+  const originalClearTimeout = globalThis.clearTimeout;
+  const originalNow = Date.now;
+  const token = process.env.REMOTE_AGENT_TOKEN;
+  let now = originalNow();
+  const timers = new Set<{ at: number; callback: () => void; refresh: () => void }>();
+  const advance = (ms: number) => {
+    now += ms;
+    for (const timer of [...timers]) if (timer.at <= now) { timers.delete(timer); timer.callback(); }
+  };
+  try {
+    Date.now = () => now;
+    globalThis.setTimeout = ((callback: () => void, ms: number) => {
+      const timer = { at: now + ms, callback, refresh: () => { timer.at = now + ms; } };
+      timers.add(timer); return timer;
+    }) as unknown as typeof setTimeout;
+    globalThis.clearTimeout = ((timer: any) => { timers.delete(timer); }) as typeof clearTimeout;
+    const agentId = 'test-lease-agent';
+    const heartbeat = () => registerRemoteAgent({ agentId, token, devices: [{ id: 'device', status: 'device' }] });
+    const device = makeRemoteDeviceId(agentId, 'device');
+    heartbeat();
+    const result = sendRemoteCommand(device, 'replay', { script: { id: 'script' } });
+    let completed = false;
+    void result.then(() => { completed = true; });
+    const command = pollRemoteCommand({ agentId, token })!;
+    assert.throws(() => sendRemoteCommand(device, 'replay'), /已有回放任务/);
+    for (let i = 0; i < 70; i++) { advance(10000); heartbeat(); }
+    assert.equal(completed, false, 'healthy replay remains pending after 11 minutes');
+    assert.equal(stopRemoteReplay(device), true);
+    assert.deepEqual(heartbeat().cancelledCommandIds, [command.id]);
+    assert.throws(() => completeRemoteCommand({ agentId: 'other', token, commandId: command.id, ok: true }), /不属于/);
+    let saves = 0;
+    const stopped = { stopped: true, history: { status: 'stopped' } };
+    completeRemoteCommand({ agentId, token, commandId: command.id, ok: true, data: stopped }, () => { saves++; });
+    assert.deepEqual(await result, stopped);
+    completeRemoteCommand({ agentId, token, commandId: command.id, ok: true, data: stopped }, () => { saves++; });
+    assert.equal(saves, 1, 'result retry must not duplicate history');
+    assert.equal(stopRemoteReplay(device), false);
+
+    const queuedResult = sendRemoteCommand(device, 'replay');
+    assert.equal(stopRemoteReplay(device), true);
+    const queued = pollRemoteCommand({ agentId, token })!;
+    assert.equal(queued.cancelled, true, 'cancel before poll survives delivery');
+    completeRemoteCommand({ agentId, token, commandId: queued.id, ok: true }); await queuedResult;
+
+    const lateResult = sendRemoteCommand(device, 'replay', { script: { id: 'late-script' } });
+    const rejected = assert.rejects(lateResult, /心跳超时/);
+    const late = pollRemoteCommand({ agentId, token })!;
+    advance(45001); await rejected;
+    assert.deepEqual(heartbeat().cancelledCommandIds, [late.id], 'reconnecting agent stops expired replay');
+    const input = { agentId, token, commandId: late.id, ok: true, data: { history: {} } };
+    assert.throws(() => completeRemoteCommand(input, () => { throw new Error('disk busy'); }), /disk busy/);
+    completeRemoteCommand(input, command => { assert.equal((command.payload?.script as { id: string }).id, 'late-script'); saves++; });
+    completeRemoteCommand(input, () => { saves++; });
+    assert.equal(saves, 2, 'late result is saved once even after a temporary persistence failure');
+    assert.deepEqual(heartbeat().cancelledCommandIds, []);
+  } finally {
+    globalThis.setTimeout = originalSetTimeout; globalThis.clearTimeout = originalClearTimeout; Date.now = originalNow;
+  }
+});

package/server/remote-agents/registry.ts

@@ -3,7 +3,9 @@ import type { RemoteAgentDevice, RemoteAndroidDevice, RemoteCommand, RemoteComma
 const REMOTE_DEVICE_PREFIX = 'remote:';
 const AGENT_TTL_MS = 15_000;
 const COMMAND_TIMEOUT_MS = 15_000;
-const REPLAY_COMMAND_TIMEOUT_MS = 10 * 60_000;
+// 回放由代理心跳续期，运行时长不受固定十分钟限制。
+const REPLAY_COMMAND_TIMEOUT_MS = 45_000;
+const LATE_RESULT_TTL_MS = 24 * 60 * 60_000;
 
 type RegisteredAgent = {
   id: string;
@@ -14,6 +16,9 @@ type RegisteredAgent = {
 };
 
 type PendingCommand = RemoteCommand & {
+  agentId: string;
+  delivered: boolean;
+  cancelRequested: boolean;
   resolve: (result: unknown) => void;
   reject: (error: Error) => void;
   timer: ReturnType<typeof setTimeout>;
@@ -22,6 +27,24 @@ type PendingCommand = RemoteCommand & {
 const agents = new Map<string, RegisteredAgent>();
 const queues = new Map<string, RemoteCommand[]>();
 const pending = new Map<string, PendingCommand>();
+// ponytail: 当前进程保留离线回放身份 24 小时；跨服务重启补交需要持久化任务表。
+const lateReplays = new Map<string, { command: RemoteCommand; agentId: string; expiresAt: number }>();
+function pruneLateReplays() {
+  for (const [id, receipt] of lateReplays) if (receipt.expiresAt <= Date.now()) lateReplays.delete(id);
+}
+
+export function stopRemoteReplay(deviceId: string) {
+  const target = parseRemoteDeviceId(deviceId);
+  if (!target) return false;
+  let stopped = false;
+  for (const command of pending.values()) {
+    if (command.type === 'replay' && command.agentId === target.agentId && command.deviceId === target.deviceSerial) {
+      command.cancelRequested = true;
+      stopped = true;
+    }
+  }
+  return stopped;
+}
 
 function validateToken(token?: string) {
   const expected = process.env.REMOTE_AGENT_TOKEN || '';
@@ -70,6 +93,17 @@ export function registerRemoteAgent(input: {
     devices: input.devices || [],
     lastSeenAt: Date.now(),
   });
+  pruneLateReplays();
+  const cancelledCommandIds: string[] = [];
+  for (const command of pending.values()) {
+    if (command.agentId !== agentId || command.type !== 'replay') continue;
+    command.timer.refresh();
+    if (command.cancelRequested) cancelledCommandIds.push(command.id);
+  }
+  for (const receipt of lateReplays.values()) {
+    if (receipt.agentId === agentId) cancelledCommandIds.push(receipt.command.id);
+  }
+  return { cancelledCommandIds };
 }
 
 export function listRemoteAndroidDevices(): RemoteAndroidDevice[] {
@@ -88,15 +122,27 @@ export function listRemoteAndroidDevices(): RemoteAndroidDevice[] {
 export function pollRemoteCommand(input: { agentId: string; token?: string }) {
   validateToken(input.token);
   const queue = queues.get(input.agentId) || [];
-  return queue.shift() || null;
+  const command = queue.shift();
+  if (!command) return null;
+  const task = pending.get(command.id);
+  if (!task) return null;
+  task.delivered = true;
+  return { ...command, cancelled: task.cancelRequested };
 }
 
 export function completeRemoteCommand(input: {
   agentId: string;
   token?: string;
-} & RemoteCommandResult) {
+} & RemoteCommandResult, saveResult?: (command: RemoteCommand) => void) {
   validateToken(input.token);
+  pruneLateReplays();
   const command = pending.get(input.commandId);
+  const late = lateReplays.get(input.commandId);
+  if (!command && !late) return;
+  if ((command?.agentId ?? late?.agentId) !== input.agentId) throw new Error('远程命令不属于当前代理');
+  // 先落库再确认；保存失败时保留任务身份，让代理重试上报。
+  if (input.ok) saveResult?.(command ?? late!.command);
+  lateReplays.delete(input.commandId);
   if (!command) return;
   pending.delete(input.commandId);
   clearTimeout(command.timer);
@@ -112,6 +158,10 @@ export function sendRemoteCommand(deviceId: string, type: RemoteCommandType, pay
   if (!parsed) throw new Error('远程设备 ID 无效');
   const agent = agents.get(parsed.agentId);
   if (!agent || !isOnline(agent)) throw new Error('远程设备代理已离线');
+  if (type === 'replay' && [...pending.values()].some(command =>
+    command.type === 'replay' && command.agentId === parsed.agentId && command.deviceId === parsed.deviceSerial)) {
+    throw new Error('该设备已有回放任务正在执行');
+  }
   const commandId = `remote_cmd_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
   const command: RemoteCommand = {
     id: commandId,
@@ -123,12 +173,17 @@ export function sendRemoteCommand(deviceId: string, type: RemoteCommandType, pay
   return new Promise<unknown>((resolve, reject) => {
     const timeoutMs = type === 'replay' ? REPLAY_COMMAND_TIMEOUT_MS : COMMAND_TIMEOUT_MS;
     const timer = setTimeout(() => {
+      const task = pending.get(commandId);
       pending.delete(commandId);
+      if (type === 'replay' && task?.delivered) {
+        pruneLateReplays();
+        lateReplays.set(commandId, { command, agentId: parsed.agentId, expiresAt: Date.now() + LATE_RESULT_TTL_MS });
+      }
       const queue = queues.get(parsed.agentId) || [];
       queues.set(parsed.agentId, queue.filter((item) => item.id !== commandId));
-      reject(new Error('远程设备命令超时'));
+      reject(new Error(type === 'replay' ? '远程代理心跳超时，恢复连接后将终止任务并补交结果' : '远程设备命令超时'));
     }, timeoutMs);
-    pending.set(commandId, { ...command, resolve, reject, timer });
+    pending.set(commandId, { ...command, agentId: parsed.agentId, delivered: false, cancelRequested: false, resolve, reject, timer });
     const queue = queues.get(parsed.agentId) || [];
     queue.push(command);
     queues.set(parsed.agentId, queue);

package/server/remote-agents/replay-integration.test.ts

@@ -0,0 +1,79 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+test('real agent receives stop during replay and retries result delivery without replaying', { skip: process.platform === 'win32', timeout: 25000 }, async () => {
+  const root = await mkdtemp(join(tmpdir(), 'remote-replay-'));
+  const env = { ...process.env };
+  process.env.ANDROID_MIDSCENE_DATA_ROOT = join(root, 'central');
+  process.env.REMOTE_AGENT_TOKEN = 'test-only-token';
+  const { handleRemoteAgentRequest } = await import('./routes');
+  const { handleAppiumRecorderRequest } = await import('../appium-recorder/routes');
+  const { listRemoteAndroidDevices } = await import('./registry');
+  const { saveAppiumRecordedScript } = await import('../appium-recorder/repository');
+  const { listRunHistory } = await import('../appium-recorder/run-history');
+  let sessions = 0, deletes = 0, keys = 0, resultAttempts = 0;
+  const server = createServer(async (req, res) => {
+    if (req.url === '/session') {
+      sessions++; res.setHeader('Content-Type', 'application/json'); res.end('{"value":{"sessionId":"test-session"}}'); return;
+    }
+    if (req.url?.startsWith('/session/')) {
+      if (req.method === 'DELETE') deletes++;
+      if (req.url.endsWith('/press_keycode')) keys++;
+      res.setHeader('Content-Type', 'application/json'); res.end('{"value":{}}'); return;
+    }
+    if (req.url === '/api/remote-agents/result' && ++resultAttempts === 1) {
+      req.resume(); res.statusCode = 503; res.end('{"message":"temporary failure"}'); return;
+    }
+    if (await handleRemoteAgentRequest(req, res)) return;
+    if (await handleAppiumRecorderRequest(req, res, '')) return;
+    res.statusCode = 404; res.end();
+  });
+  let agent: ReturnType<typeof spawn> | undefined;
+  const waitFor = async (check: () => boolean) => {
+    const until = Date.now() + 12000;
+    while (!check()) { assert.ok(Date.now() < until, 'agent action completed within deadline'); await new Promise(resolve => setTimeout(resolve, 25)); }
+  };
+  try {
+    const sdk = join(root, 'sdk'), bin = join(sdk, 'platform-tools');
+    await mkdir(bin, { recursive: true });
+    await writeFile(join(bin, 'adb'), '#!/usr/bin/env node\nif(process.argv.includes("devices")) console.log("List of devices attached\\nfake-device device model:Test");\n', { mode: 0o755 });
+    await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
+    const base = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+    const script = saveAppiumRecordedScript({ name: 'remote-test', appPackage: 'example.test', steps: [
+      { id: 'wait', type: 'delay', label: 'wait', timeoutMs: 60000 },
+      { id: 'home', type: 'key', label: 'Home', keyCode: 3 },
+    ] });
+    agent = spawn(process.execPath, ['--import', 'tsx', resolve('remote-agent/index.ts'), '--server', base, '--agent-id', 'integration-agent'], {
+      env: { ...process.env, ANDROID_MIDSCENE_DATA_ROOT: join(root, 'agent'), ANDROID_HOME: sdk, ANDROID_SDK_ROOT: sdk, APPIUM_SERVER_URL: base, PATH: `${bin}:${process.env.PATH}` },
+      stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    let stderr = ''; agent.stderr?.on('data', chunk => { stderr += chunk; });
+    await waitFor(() => listRemoteAndroidDevices().length > 0);
+    const deviceId = listRemoteAndroidDevices()[0]!.id;
+    const post = (path: string, data: unknown) => fetch(base + path, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data), signal: AbortSignal.timeout(18000) });
+    const running = post(`/api/appium-recorder/scripts/${script.id}/replay`, { deviceId, reportSummaryEnabled: false }).then(response => response.json() as Promise<{ stopped: boolean }>);
+    await waitFor(() => sessions === 1);
+    const stop = await (await post('/api/appium-recorder/replay/stop', { deviceId })).json() as { stopped: boolean };
+    assert.equal(stop.stopped, true);
+    const result = await running;
+    assert.equal(result.stopped, true, stderr);
+    assert.equal(sessions, 1, 'retrying the result never replays device actions');
+    assert.equal(deletes, 1); assert.equal(keys, 0, 'Home must not run after cancellation');
+    assert.equal(resultAttempts, 2, 'temporary result failure is retried');
+    const history = listRunHistory(script.id);
+    assert.equal(history.length, 1); assert.equal(history[0]?.status, 'stopped'); assert.equal(history[0]?.deviceId, deviceId);
+  } finally {
+    if (agent && agent.exitCode === null) {
+      const exited = new Promise<void>(resolve => agent!.once('exit', () => resolve()));
+      agent.kill('SIGKILL'); await exited;
+    }
+    server.closeAllConnections(); await new Promise<void>(resolve => server.close(() => resolve()));
+    for (const key of ['ANDROID_MIDSCENE_DATA_ROOT', 'REMOTE_AGENT_TOKEN']) { if (env[key] === undefined) delete process.env[key]; else process.env[key] = env[key]; }
+    await rm(root, { recursive: true, force: true });
+  }
+});