android-midscene-automation 0.1.37 → 0.1.39

package/server/appium-recorder/replay-video.ts

@@ -0,0 +1,99 @@
+import { mkdir, open, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { loadConfig } from '../config';
+import { appDataPath } from '../paths';
+import { openRecordingSource, waitForVideoTask } from './scrcpy-recording-source';
+import { ReplayMp4Writer } from './replay-mp4';
+
+export type ReplayVideo = { filePath: string; fileName: string; startedAt: string; warning?: string };
+
+// 检查 MP4 的索引和媒体块，不将大视频整体读入内存。
+export async function isFinalizedMp4(path: string) {
+  const file = await open(path, 'r');
+  try {
+    const { size } = await file.stat();
+    let offset = 0, media = false, index = false;
+    const header = Buffer.alloc(16);
+    while (offset + 8 <= size) {
+      const { bytesRead } = await file.read(header, 0, 16, offset);
+      const type = header.toString('ascii', 4, 8);
+      let length = header.readUInt32BE(0);
+      if (length === 1) {
+        if (bytesRead < 16) return false;
+        length = Number(header.readBigUInt64BE(8));
+      }
+      if (!length) length = size - offset;
+      if (length < 8 || !Number.isSafeInteger(length) || offset + length > size) return false;
+      if (type === 'mdat' && length > 8) media = true;
+      if (type === 'moov' && length > 8) index = true;
+      offset += length;
+    }
+    return media && index && offset === size;
+  } finally { await file.close(); }
+}
+
+export async function startReplayVideo(deviceId: string, signal?: AbortSignal) {
+  signal?.throwIfAborted();
+  const dir = appDataPath(loadConfig().runtime.reportOutputPath.trim() || 'output');
+  await mkdir(dir, { recursive: true });
+  const fileName = `replay-${Date.now()}-${randomUUID()}.mp4`;
+  const filePath = join(dir, fileName);
+  const startupSignal = AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(30000)]);
+  const source = await openRecordingSource(deviceId, startupSignal);
+  return recordVideoStream(source, filePath, fileName, startupSignal);
+}
+
+// 独立于连接层，便于用真实 H.264 数据验证封装、断流和终止收尾。
+export async function recordVideoStream(source: Awaited<ReturnType<typeof openRecordingSource>>, filePath: string, fileName: string, startupSignal: AbortSignal) {
+  const writer = new ReplayMp4Writer(filePath);
+  const reader = source.stream.getReader();
+  let stopping = false;
+  let warning: string | undefined;
+  let readyResolve!: () => void;
+  let readyReject!: (error: unknown) => void;
+  const ready = new Promise<void>((resolve, reject) => { readyResolve = resolve; readyReject = reject; });
+  void ready.catch(() => undefined);
+  let pump: Promise<void> = Promise.resolve();
+  let stopTask: Promise<ReplayVideo> | undefined;
+  const stop = () => stopTask ??= (async () => {
+    stopping = true;
+    await Promise.allSettled([reader.cancel(), source.close()]);
+    await pump;
+    try {
+      await writer.finish();
+      if (!await isFinalizedMp4(filePath)) throw new Error('录屏未生成完整 MP4');
+      return { filePath, fileName, startedAt: new Date(writer.startedAt).toISOString(), warning };
+    } catch (error) {
+      await writer.cancel().catch(() => undefined);
+      await rm(filePath, { force: true });
+      throw error;
+    }
+  })();
+  try {
+    await writer.start();
+    pump = (async () => {
+      try {
+        while (!stopping) {
+          const { done, value } = await reader.read();
+          if (done) {
+            if (!stopping) throw new Error(`录屏视频流提前结束 ${source.diagnostics()}`);
+            break;
+          }
+          await writer.add(value);
+          if (writer.startedAt) readyResolve();
+        }
+      } catch (error) {
+        warning = `录像可能不完整：${error instanceof Error ? error.message : String(error)}`;
+        readyReject(error);
+        void source.close();
+      } finally { writer.end(); reader.releaseLock(); }
+    })();
+    await waitForVideoTask(ready, startupSignal);
+    return { startedAt: new Date(writer.startedAt).toISOString(), stop };
+  } catch (error) {
+    await stop().catch(() => undefined);
+    await rm(filePath, { force: true });
+    throw error;
+  }
+}

package/server/appium-recorder/report.ts

@@ -1,5 +1,6 @@
 import { mkdir, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
+import type { ReplayVideo } from './replay-video';
 import { PNG } from 'pngjs';
 import { appDataPath } from '../paths';
 import { loadConfig } from '../config';
@@ -240,6 +241,7 @@ function stepSection(
 }
 
 function createReplayHtml(input: {
+  video?: { url: string; startedAt: string };
   script: AppiumRecordedScriptRecord;
   deviceId: string;
   resultText: string;
@@ -253,6 +255,7 @@ function createReplayHtml(input: {
 }) {
   const imageCache = new Map<string, string>();
   const payload = jsonForHtml({
+    video: input.video,
     startedAt: input.startedAt.toISOString(),
     durationMs: input.durationMs,
     frames: input.frames.map((frame) => ({
@@ -325,9 +328,11 @@ function createReplayHtml(input: {
     .viewer { display: grid; grid-template-rows: minmax(0, 1fr) auto auto; min-width: 0; min-height: 0; padding: 16px 20px 12px; background: #f4f6f8; }
     .screen { display: flex; align-items: center; justify-content: center; min-height: 0; overflow: hidden; border-radius: 6px; background: #101827; }
     .screen img { display: block; width: 100%; height: 100%; object-fit: contain; transition: opacity .12s ease; }
+    [hidden] { display: none !important; }
     .empty { color: #a8abb2; }
     .caption { min-height: 40px; padding: 10px 4px 0; overflow: hidden; color: #4b515a; font-size: 13px; text-align: center; text-overflow: ellipsis; white-space: nowrap; }
     .controls { display: grid; grid-template-columns: auto auto auto minmax(120px, 1fr) auto; align-items: center; gap: 8px; min-height: 52px; }
+    .controls:has(#toggle-recording:not([hidden])) { grid-template-columns: auto auto auto auto minmax(80px, 1fr) auto; }
     button { min-height: 34px; padding: 0 14px; border: 1px solid #cfd5dd; border-radius: 4px; color: #30343b; background: #fff; cursor: pointer; }
     button:hover:not(:disabled) { border-color: #409eff; color: #1677ff; }
     button:disabled { cursor: not-allowed; opacity: .45; }
@@ -364,6 +369,9 @@ function createReplayHtml(input: {
       .thumbnail { height: 78px; }
       header { align-items: flex-start; flex-direction: column; }
       .meta { justify-content: flex-start; }
+      .controls, .controls:has(#toggle-recording:not([hidden])) { display: flex; flex-wrap: wrap; }
+      .controls button { max-width: 100%; }
+      #seek { flex: 1 1 120px; width: auto; }
     }
   </style>
 </head>
@@ -406,9 +414,10 @@ function createReplayHtml(input: {
         </div>
       </div>
       <section class="viewer">
-        <div class="screen"><img id="screen" alt="设备截图" hidden /><span id="empty" class="empty">本次回放没有可用截图</span></div>
+        <div class="screen"><video id="recording" controls preload="metadata" playsinline hidden style="width:100%;height:100%;object-fit:contain"></video><img id="screen" alt="设备截图" hidden /><span id="empty" class="empty">本次回放没有可用截图</span></div>
         <div id="caption" class="caption">暂无截图</div>
         <div class="controls">
+          <button id="toggle-recording" hidden>查看节点截图</button>
           <button id="previous" type="button" title="上一帧">上一帧</button>
           <button id="play" type="button">播放</button>
           <button id="next" type="button" title="下一帧">下一帧</button>
@@ -430,6 +439,12 @@ function createReplayHtml(input: {
     const data = JSON.parse(document.querySelector('#replay-data').textContent || '{}');
     const visualChecks = Array.isArray(data.visualChecks) ? data.visualChecks : [];
     const reportStartedAt = Date.parse(data.startedAt) || 0;
+    const recording = document.querySelector('#recording');
+    const toggleRecording = document.querySelector('#toggle-recording');
+    const videoOffset = Math.max(0, (Date.parse(data.video?.startedAt) || reportStartedAt) - reportStartedAt);
+    let videoMode = Boolean(data.video);
+    let pendingVideoTime = 0;
+    if (data.video) { recording.src = data.video.url; toggleRecording.hidden = false; }
     const frames = (Array.isArray(data.frames) ? data.frames : []).map((frame) => ({
       ...frame,
       offsetMs: Math.max(0, (Date.parse(frame.capturedAt) || reportStartedAt) - reportStartedAt),
@@ -487,8 +502,9 @@ function createReplayHtml(input: {
       const frameChanged = nextFrame !== currentFrame;
       currentFrame = nextFrame;
       const frame = frames[currentFrame];
-      elements.empty.hidden = Boolean(frame);
-      elements.screen.hidden = !frame;
+      elements.empty.hidden = videoMode || Boolean(frame?.imageUrl);
+      elements.screen.hidden = videoMode || !frame?.imageUrl;
+      recording.hidden = !videoMode;
       if (frame) {
         if (frameChanged || elements.screen.src !== frame.imageUrl) elements.screen.src = frame.imageUrl;
         elements.title.textContent = frame.nodeLabel || '未命名节点';
@@ -507,7 +523,7 @@ function createReplayHtml(input: {
       }
       elements.previous.disabled = !frames.length || currentFrame <= 0;
       elements.next.disabled = !frames.length || currentFrame >= frames.length - 1;
-      elements.play.disabled = frames.length < 2;
+      elements.play.disabled = !videoMode && frames.length < 2;
       elements.seek.value = String(Math.round(currentMs / durationMs * 1000));
       elements.clock.textContent = formatTime(currentMs) + ' / ' + formatTime(durationMs);
       elements.playhead.style.left = (currentMs / durationMs * 100) + '%';
@@ -516,14 +532,40 @@ function createReplayHtml(input: {
       if (scrollStep) document.querySelector('.frame-item.active')?.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
     };
     const pause = () => {
+      recording.pause();
       cancelAnimationFrame(animationFrame);
       animationFrame = 0;
       elements.play.textContent = '播放';
     };
     const seekTo = (milliseconds, scrollStep = true) => {
       currentMs = Math.max(0, Math.min(durationMs, milliseconds));
+      pendingVideoTime = Math.max(0, (currentMs - videoOffset) / 1000);
+      if (data.video && recording.readyState >= 1) recording.currentTime = Math.min(pendingVideoTime, recording.duration || pendingVideoTime);
       render(scrollStep);
     };
+    recording.addEventListener('loadedmetadata', () => { recording.currentTime = Math.min(pendingVideoTime, recording.duration); });
+    recording.addEventListener('timeupdate', () => {
+      if (!videoMode || recording.paused) return;
+      currentMs = recording.currentTime * 1000 + videoOffset;
+      render();
+    });
+    recording.addEventListener('seeked', () => {
+      if (!videoMode) return;
+      currentMs = recording.currentTime * 1000 + videoOffset;
+      render();
+    });
+    recording.addEventListener('play', () => { elements.play.textContent = '暂停'; });
+    recording.addEventListener('pause', () => { elements.play.textContent = '播放'; });
+    recording.addEventListener('error', () => {
+      pause(); videoMode = false; render();
+      toggleRecording.textContent = '视频不可用，请将 MP4 与报告放在一起';
+      toggleRecording.disabled = true;
+    });
+    toggleRecording.addEventListener('click', () => {
+      pause(); videoMode = !videoMode;
+      toggleRecording.textContent = videoMode ? '查看节点截图' : '查看回放视频';
+      seekTo(currentMs, false);
+    });
     const tickPlayback = (now) => {
       currentMs = Math.min(durationMs, now - playbackStartedAt);
       render();
@@ -605,7 +647,12 @@ function createReplayHtml(input: {
       article.append(title);
       const detail = document.createElement('dl');
       const region = check.region || {};
-      const entries = [['结果', check.result === null ? '无法判定' : String(check.result)], ['配置', check.settings],
+      const match = check.templateMatch;
+      const entries = [
+        ...(match ? [['实际匹配结果', match.matched ? '匹配到模板' : '未匹配到模板'],
+          ['预期匹配结果', match.expected === 'present' ? '匹配到模板' : '未匹配到模板'],
+          ['匹配得分 / 严格度', (match.score * 100).toFixed(4) + '% / ' + (match.threshold * 100).toFixed(4) + '%']] : []),
+        [match ? '条件是否成立' : '结果', check.timedOut ? '观察超时（按节点超时配置处理）' : check.result === null ? '无法判定' : match ? (check.result ? '成立 → true 分支' : '不成立 → false 分支') : String(check.result)], ['配置', check.settings],
         ['区域', [region.x, region.y, region.width, region.height].join(', ')],
         ['采样', check.sampleCount + ' 帧'], ['耗时', check.durationMs + 'ms'], ['说明', check.message], ...Object.entries(check.metrics)];
       entries.forEach(([key, value]) => {
@@ -685,6 +732,11 @@ function createReplayHtml(input: {
     elements.previous.addEventListener('click', () => { pause(); seekTo(frames[Math.max(0, currentFrame - 1)]?.offsetMs || 0); });
     elements.next.addEventListener('click', () => { pause(); seekTo(frames[Math.min(frames.length - 1, currentFrame + 1)]?.offsetMs || durationMs); });
     elements.play.addEventListener('click', () => {
+      if (videoMode) {
+        if (!recording.paused) return pause();
+        recording.play().catch(() => { elements.caption.textContent = '视频无法播放，请检查 MP4 文件是否存在或使用其他浏览器'; });
+        return;
+      }
       if (animationFrame) return pause();
       if (currentMs >= durationMs) currentMs = 0;
       playbackStartedAt = performance.now() - currentMs;
@@ -719,6 +771,7 @@ function createReplayHtml(input: {
 }
 
 export async function createAppiumReplayReport(input: {
+  video?: ReplayVideo;
   script: AppiumRecordedScriptRecord;
   deviceId: string;
   success: boolean;
@@ -753,6 +806,7 @@ export async function createAppiumReplayReport(input: {
   const visualCheckByStepId = new Map(visualChecks.map((check) => [check.nodeId, check]));
   const visualFailureCount = visualChecks.filter((check) => check.status === 'failed').length;
   const html = createReplayHtml({
+    video: input.video ? { startedAt: input.video.startedAt, url: relative(outputDir, input.video.filePath).split(/[/\\\\]/).map(encodeURIComponent).join('/') } : undefined,
     script: input.script,
     deviceId: input.deviceId,
     resultText,

package/server/appium-recorder/repository.ts

@@ -99,6 +99,7 @@ export type AppiumRecordedStepRecord = {
   returns?: ScriptReturn[];
   keyCode?: number;
   timeoutMs?: number;
+  timeoutBranch?: 'stop' | 'yes' | 'no';
   longPressMode?: 'element' | 'coordinates';
   breakLoopTargetId?: string;
   loop?: {

package/server/appium-recorder/routes.ts

@@ -1,8 +1,8 @@
 import { execFile } from 'node:child_process';
+import { sendReplayVideo } from './video-response';
 import { getPresetVariables, savePresetVariables } from './variable-store';
 import type { TestVariable } from '../../src/appium-recorder/variables';
 import { deleteRunHistory, getRunHistory, listRunHistory, saveRunHistory } from './run-history';
-import { recognizeDeviceScreen } from './ai-recognition';
 import { readImage, cropImage } from './image-check';
 import { PNG } from 'pngjs';
 import { adbScreenshotBase64 } from './screenshot';
@@ -200,20 +200,7 @@ export async function handleAppiumRecorderRequest(
     }
 
     if (pathname === '/api/appium-recorder/ai-recognition/test' && req.method === 'POST') {
-      const parsed = await readBody<{ deviceId?: string; prompt?: unknown; timeoutMs?: number }>(req);
-      const deviceId = parsed.deviceId?.trim() || selectedDeviceId;
-      if (!deviceId) throw new Error('请选择设备');
-      assertDeviceAllowed(deviceId);
-      if (isRemoteDeviceId(deviceId)) throw new Error('远程设备暂不支持 AI 识别测试');
-      if (replayingDevices.has(deviceId)) { sendJson(res, { message: '设备正在回放，请稍后测试' }, 409); return true; }
-      const controller = new AbortController();
-      const abort = () => controller.abort();
-      res.once('close', abort);
-      try {
-        sendJson(res, await recognizeDeviceScreen({ deviceId, prompt: parsed.prompt, timeoutMs: parsed.timeoutMs, signal: controller.signal }));
-      } finally {
-        res.off('close', abort);
-      }
+      sendJson(res, { message: 'AI 识别操作已移除，请使用图像判断或原生组件判断' }, 410);
       return true;
     }
 
@@ -345,6 +332,14 @@ export async function handleAppiumRecorderRequest(
       return true;
     }
 
+    const videoMatch = pathname.match(/^\/api\/appium-recorder\/scripts\/([^/]+)\/history\/([^/]+)\/video$/);
+    if (videoMatch && (req.method === 'GET' || req.method === 'HEAD')) {
+      const run = getRunHistory(decodeURIComponent(videoMatch[1]), decodeURIComponent(videoMatch[2]));
+      if (!run?.video) { sendJson(res, { error: '本次运行没有视频' }, 404); return true; }
+      assertDeviceAllowed(run.deviceId);
+      await sendReplayVideo(req, res, run.video.filePath);
+      return true;
+    }
     const historyMatch = pathname.match(/^\/api\/appium-recorder\/scripts\/([^/]+)\/history(?:\/([^/]+))?$/);
     if (historyMatch) {
       const scriptId = decodeURIComponent(historyMatch[1]);
@@ -362,12 +357,13 @@ export async function handleAppiumRecorderRequest(
     }
     const replayMatch = pathname.match(/^\/api\/appium-recorder\/scripts\/([^/]+)\/replay$/);
     if (replayMatch && req.method === 'POST') {
-      const parsed = await readBody<{ deviceId?: string; parameters?: TestVariable[] }>(req);
+      const parsed = await readBody<{ deviceId?: string; parameters?: TestVariable[]; recordVideo?: boolean }>(req);
       const script = getAppiumRecordedScript(decodeURIComponent(replayMatch[1]));
       if (!script) throw new Error('Appium 录制脚本不存在');
       const deviceId = parsed.deviceId || selectedDeviceId;
       assertDeviceAllowed(deviceId);
       const streamOutput = req.headers.accept?.includes('application/x-ndjson') === true;
+      if (parsed.recordVideo === true && isRemoteDeviceId(deviceId)) throw new Error('远程设备暂不支持回放录屏，请在连接设备的主机本地运行');
       if (streamOutput) {
         res.statusCode = 200;
         res.setHeader('Content-Type', 'application/x-ndjson; charset=utf-8');
@@ -403,7 +399,7 @@ export async function handleAppiumRecorderRequest(
           deviceId,
           streamOutput ? (line) => sendStreamEvent(res, { type: 'log', line }) : undefined,
           replayAbortController.signal,
-          { parameters: parsed.parameters, globalVariables: getPresetVariables() },
+          { parameters: parsed.parameters, globalVariables: getPresetVariables(), recordVideo: parsed.recordVideo === true },
         );
         try { saveRunHistory(result.history); }
         catch { result.output += '\n历史记录保存失败'; }

package/server/appium-recorder/run-history.ts

@@ -1,4 +1,6 @@
 import { createId, querySql, runSql, sqlJson, sqlString } from '../storage/sqlite';
+import { rmSync } from 'node:fs';
+import { basename } from 'node:path';
 import type { RunDetail, RunSummary } from '../../src/appium-recorder/run-history';
 
 function ensureTable() {
@@ -29,6 +31,10 @@ export function getRunHistory(scriptId: string, id: string): RunDetail | null {
 
 export function deleteRunHistory(scriptId: string, id: string) {
   ensureTable();
-  // 不接受文件路径，也不删除原始报告；只删除这条历史的自包含快照。
+  const video = getRunHistory(scriptId, id)?.video;
+  // 只清理服务端生成并关联到该记录的录像，不接受客户端文件路径。
+  if (video && basename(video.filePath) === video.fileName && /^replay-[\d]+-[\da-f-]+\.mp4$/.test(video.fileName)) {
+    rmSync(video.filePath, { force: true });
+  }
   runSql(`PRAGMA secure_delete=ON; DELETE FROM appium_run_history WHERE script_id=${sqlString(scriptId)} AND id=${sqlString(id)};`);
 }

package/server/appium-recorder/scrcpy-recording-source.ts

@@ -0,0 +1,80 @@
+import { execFile } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { AdbServerClient, type Adb } from '@yume-chan/adb';
+import { AdbServerNodeTcpConnector } from '@yume-chan/adb-server-node-tcp';
+import { AdbScrcpyClient, AdbScrcpyOptions3_3_3 } from '@yume-chan/adb-scrcpy';
+import { ScrcpyVideoCodecId } from '@yume-chan/scrcpy';
+import { getAdbCommand } from '../android-sdk';
+
+export function waitForVideoTask<T>(task: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener('abort', abort, { once: true });
+    task.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    if (signal.aborted) abort();
+  });
+}
+
+function adbCommand(args: string[], signal?: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    execFile(getAdbCommand(), args, { timeout: 10000, signal, windowsHide: true }, error => error ? reject(error) : resolve());
+  });
+}
+
+export async function openRecordingSource(deviceId: string, signal: AbortSignal) {
+  const require = createRequire(import.meta.url);
+  const bin = join(dirname(require.resolve('@midscene/android-playground/package.json')), 'bin');
+  const version = (await readFile(join(bin, 'scrcpy-server.version'), 'utf8')).trim();
+  if (version !== 'v3.3.3') throw new Error(`内置 scrcpy 服务端版本不兼容：${version}`);
+  const remotePath = `/data/local/tmp/midscene-recording-${randomUUID()}.jar`;
+  let adb: Adb | undefined;
+  let client: Awaited<ReturnType<typeof AdbScrcpyClient.start>> | undefined;
+  let closing = false;
+  let logs = '';
+  let closeTask: Promise<void> | undefined;
+  const close = () => closeTask ??= (async () => {
+    closing = true;
+    await waitForVideoTask(Promise.allSettled([client?.close(), adb?.close()]), AbortSignal.timeout(3000)).catch(() => undefined);
+    await adbCommand(['-s', deviceId, 'shell', 'rm', '-f', remotePath]).catch(() => undefined);
+  })();
+  try {
+    await adbCommand(['start-server'], signal);
+    await adbCommand(['-s', deviceId, 'push', join(bin, 'scrcpy-server'), remotePath], signal);
+    const server = new AdbServerClient(new AdbServerNodeTcpConnector({ host: '127.0.0.1', port: 5037 }));
+    adb = await waitForVideoTask(server.createAdb({ serial: deviceId }).then(connection => {
+      if (closing || signal.aborted) { void connection.close(); throw signal.reason || new Error('录屏已取消'); }
+      return connection;
+    }), signal);
+    // 独立 socket ID 和上传路径，停止录制不会关闭正在使用的设备预览。
+    const options = new AdbScrcpyOptions3_3_3({
+      scid: Math.floor(Math.random() * 0x7fffffff).toString(16).padStart(8, '0'),
+      audio: false, control: false, videoCodec: 'h264', sendFrameMeta: true,
+      maxSize: 1280, maxFps: 15, videoBitRate: 2000000,
+      captureOrientation: '@', videoCodecOptions: 'profile=1,max-bframes=0,i-frame-interval=2',
+    });
+    client = await waitForVideoTask(AdbScrcpyClient.start(adb, remotePath, options).then(value => {
+      if (closing || signal.aborted) { void value.close(); throw signal.reason || new Error('录屏已取消'); }
+      return value;
+    }), signal);
+    // 持续消费服务端输出，避免输出管道阻塞编码进程。
+    const outputReader = client.output.getReader();
+    void (async () => {
+      try {
+        while (true) {
+          const { done, value } = await outputReader.read();
+          if (done) break;
+          logs = `${logs}\n${value}`.slice(-4000);
+        }
+      } finally { outputReader.releaseLock(); }
+    })().catch(() => undefined);
+    const video = await waitForVideoTask(client.videoStream!, signal);
+    if (video.metadata.codec !== ScrcpyVideoCodecId.H264) throw new Error('录屏需要 H.264 视频流');
+    return { stream: video.stream, close, diagnostics: () => logs };
+  } catch (error) {
+    await close();
+    throw error;
+  }
+}

package/server/appium-recorder/video-response.ts

@@ -0,0 +1,36 @@
+import { open } from 'node:fs/promises';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+// 浏览器按字节加载 MP4；支持 Range 才能直接跳转到录像中间。
+export async function sendReplayVideo(req: IncomingMessage, res: ServerResponse, path: string) {
+  const file = await open(path, 'r').catch(() => null);
+  if (!file) { res.statusCode = 404; res.end('视频文件不存在'); return; }
+  let streaming = false;
+  try {
+    const { size } = await file.stat();
+    let start = 0, end = size - 1;
+    const range = req.headers.range;
+    if (range) {
+      const match = /^bytes=(\d*)-(\d*)$/.exec(range);
+      if (match && (match[1] || match[2])) {
+        start = match[1] ? Number(match[1]) : Math.max(0, size - Number(match[2]));
+        end = match[1] && match[2] ? Math.min(Number(match[2]), size - 1) : size - 1;
+      } else start = size;
+      if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start > end || start >= size) {
+        res.writeHead(416, { 'Content-Range': `bytes */${size}` }); res.end(); return;
+      }
+      res.statusCode = 206;
+      res.setHeader('Content-Range', `bytes ${start}-${end}/${size}`);
+    }
+    res.setHeader('Content-Type', 'video/mp4');
+    res.setHeader('Accept-Ranges', 'bytes');
+    res.setHeader('Cache-Control', 'private, no-store');
+    res.setHeader('Content-Length', String(Math.max(0, end - start + 1)));
+    if (req.method === 'HEAD' || !size) { res.end(); return; }
+    const stream = file.createReadStream({ start, end });
+    streaming = true;
+    res.once('close', () => stream.destroy());
+    stream.once('error', () => res.destroy());
+    stream.pipe(res);
+  } finally { if (!streaming) await file.close(); }
+}