android-midscene-automation 0.1.30 → 0.1.32

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

@@ -1,4 +1,7 @@
 import { execFile } from 'node:child_process';
+import { captureHistoryFrames, readAppVersion } from './history-capture';
+import { BoundedLoopTraversal } from './bounded-loop';
+import { validateLoopSteps } from '../../src/appium-recorder/bounded-loop';
 import { adbScreenshotBase64 } from './screenshot';
 import { recognizeDeviceScreen } from './ai-recognition';
 import { formatStageLog } from '../../src/appium-recorder/stage-log';
@@ -47,6 +50,8 @@ type PendingVisualChangeCheck = {
   step: AppiumRecordedStepRecord;
   nodeNumber: number;
   scriptName: string;
+  frameStart: number;
+  endFrameStart: number;
 };
 
 const replayContext = new AsyncLocalStorage<{
@@ -55,8 +60,10 @@ const replayContext = new AsyncLocalStorage<{
   serverUrl: string;
   deviceId: string;
   frames: AppiumReplayFrame[];
+  historyEvents: AppiumReplayFrame[];
   visualChecks: AppiumReplayVisualCheck[];
   pendingVisualChecks: PendingVisualChangeCheck[];
+  visualStartOffsets: Map<string, number>;
   softFailureCount: number;
   flowEnded?: boolean;
 }>();
@@ -330,6 +337,10 @@ async function captureReplayFrame(
 ) {
   const context = replayContext.getStore();
   if (!context || !context.deviceId) return;
+  // 执行记录独立于截图，设备截图失败不能让失败节点从统计中消失。
+  context.historyEvents.push({ sequence: context.historyEvents.length + 1, scriptName, nodeId: step.id,
+    nodeNumber, nodeLabel: step.label, nodeType: step.type, note: step.note || '',
+    selector: replayFrameSelector(step), phase, status, capturedAt: new Date().toISOString(), imageBase64: '' });
   const appendFrame = (imageBase64: string) => {
     context.frames.push({
       sequence: context.frames.length + 1,
@@ -517,6 +528,7 @@ async function saveScreenshot(deviceId: string) {
 type RunStepMeta = {
   nodeNumber: number;
   scriptName: string;
+  frameStart?: number;
 };
 
 type RunStepResult = string | {
@@ -558,10 +570,9 @@ function findVisualFrame(
 ) {
   const matches = frames.filter((frame) => frame.nodeId === nodeId && frame.scriptName === scriptName);
   if (!matches.length) return undefined;
-  const preferred = preferredPhase === 'before'
-    ? matches.find((frame) => frame.phase === preferredPhase)
-    : [...matches].reverse().find((frame) => frame.phase === preferredPhase);
-  return preferred || (preferredPhase === 'before' ? matches[0] : matches[matches.length - 1]);
+  const frame = preferredPhase === 'before' ? matches[0] : matches[matches.length - 1];
+  // A failed capture must not fall back to an older round or a before/error image.
+  return frame?.phase === preferredPhase ? frame : undefined;
 }
 
 const EMPTY_PNG_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=';
@@ -572,12 +583,14 @@ function registerVisualChangeStep(
 ): RunStepResult {
   const config = step.visualChange;
   if (!config) throw new Error(`${step.label} 缺少画面变化检测配置`);
+  const context = replayContext.getStore();
   if (config.role === 'start') {
+    // Invalidate the previous capture even when this start's after screenshot fails.
+    context?.visualStartOffsets.set(JSON.stringify([meta.frameStart || 0, step.id]), context.frames.length);
     return {
       message: `已记录画面变化基准点：${config.pairLabel || step.label}`,
     };
   }
-  const context = replayContext.getStore();
   const endStep = {
     ...step,
     visualChange: {
@@ -585,7 +598,9 @@ function registerVisualChangeStep(
       endStepId: config.endStepId || step.id,
     },
   };
-  context?.pendingVisualChecks.push({ step: endStep, nodeNumber: meta.nodeNumber, scriptName: meta.scriptName });
+  context?.pendingVisualChecks.push({ step: endStep, nodeNumber: meta.nodeNumber, scriptName: meta.scriptName,
+    frameStart: context.visualStartOffsets.get(JSON.stringify([meta.frameStart || 0, config.startStepId])) ?? meta.frameStart ?? 0,
+    endFrameStart: context.frames.length });
   return {
     message: `已记录画面变化对比点：${config.pairLabel || step.label}`,
   };
@@ -622,16 +637,16 @@ function processPendingVisualChecks(lines: string[]) {
   const context = replayContext.getStore();
   if (!context || !context.pendingVisualChecks.length) return;
 
-  // Visual checks compare captured replay frames after the path finishes, so
-  // they never block or mutate the device state for downstream nodes.
+  // Resolve each pair immediately after its end capture, before later rounds
+  // or linked-script calls can replace the images associated with these IDs.
   context.pendingVisualChecks.forEach((check) => {
     const config = check.step.visualChange;
     if (!config?.startStepId || !config.endStepId) {
       appendVisualCheckFailure(lines, check, `${check.step.label} 缺少开始节点或结束节点`);
       return;
     }
-    const baselineFrame = findVisualFrame(context.frames, config.startStepId, check.scriptName, 'after');
-    const comparisonFrame = findVisualFrame(context.frames, config.endStepId, check.scriptName, 'after');
+    const baselineFrame = findVisualFrame(context.frames.slice(check.frameStart, check.endFrameStart), config.startStepId, check.scriptName, 'after');
+    const comparisonFrame = findVisualFrame(context.frames.slice(check.endFrameStart), config.endStepId, check.scriptName, 'after');
     if (!baselineFrame || !comparisonFrame) {
       const missing = [
         baselineFrame ? '' : '开始节点截图',
@@ -916,6 +931,15 @@ async function readNativeControlState(sessionId: string, step: AppiumRecordedSte
 }
 
 async function evaluateCondition(sessionId: string, deviceId: string, step: AppiumRecordedStepRecord) {
+  if (step.type === 'loop') {
+    if (step.loop?.exitWhen === 'never') return false;
+    const selector = toAppiumUsing(step.selector!);
+    const payload = await appiumRequest<AppiumValueResponse<Record<string, string>[]>>(`/session/${sessionId}/elements`, {
+      method: 'POST', body: JSON.stringify(selector),
+    });
+    if (!Array.isArray(payload.value)) throw new Error('循环退出条件查询返回了无效结果');
+    return step.loop?.exitWhen === 'exists' ? payload.value.length > 0 : payload.value.length === 0;
+  }
   if (step.type === 'textClick') {
     const selector = textClickSelector(step);
     const deadline = Date.now() + Math.max(0, step.timeoutMs ?? 10000);
@@ -994,12 +1018,17 @@ async function appendStepDiagnostics(lines: string[], deviceId: string, step: Ap
 }
 
 type ReplayStepOptions = {
+  frameStart?: number;
   skipAppInitialization?: boolean;
   scriptName?: string;
 };
 
-function shouldSkipLinkedScriptInitStep(options: ReplayStepOptions, step: AppiumRecordedStepRecord) {
-  return Boolean(options.skipAppInitialization && (step.type === 'launchApp' || step.type === 'clearAppData'));
+function shouldSkipLinkedScriptInitStep(options: ReplayStepOptions, step: AppiumRecordedStepRecord, steps: AppiumRecordedStepRecord[]) {
+  if (!options.skipAppInitialization) return false;
+  // Only the leading initialization sequence is redundant in a linked script.
+  // Launches inside branches or after other operations are intentional actions.
+  return steps.slice(0, steps.indexOf(step) + 1).every(item =>
+    !item.flow?.parentConditionId && (item.type === 'launchApp' || item.type === 'clearAppData'));
 }
 
 function linkedScriptInitSkipReason(step: AppiumRecordedStepRecord) {
@@ -1079,7 +1108,7 @@ async function replayLinearSteps(
   for (const [index, step] of steps.entries()) {
     if (replayContext.getStore()?.flowEnded) return;
     throwIfReplayStopped();
-    if (shouldSkipLinkedScriptInitStep(options, step)) {
+    if (shouldSkipLinkedScriptInitStep(options, step, steps)) {
       lines.push(`[节点 ${index + 1}] 跳过：${step.label}（${linkedScriptInitSkipReason(step)}）`);
       continue;
     }
@@ -1093,11 +1122,13 @@ async function replayLinearSteps(
         const result = await runStep(sessionId, deviceId, step, {
           nodeNumber: index + 1,
           scriptName: options.scriptName || '',
+          frameStart: options.frameStart,
         });
         softFailed = appendRunStepResult(lines, index + 1, result);
       }
       lines.push(`[节点 ${index + 1}] 完成：${step.label}${softFailed ? '（存在软失败，已继续）' : ''}`);
       await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'after', completedStepStatus(step, softFailed));
+      processPendingVisualChecks(lines);
     } catch (error) {
       if (isReplayStopped(error)) {
         lines.push(`[节点 ${index + 1}] 已终止：${step.label}`);
@@ -1121,47 +1152,47 @@ async function replayFlowSteps(
   options: ReplayStepOptions = {},
 ) {
   const idToIndex = new Map(steps.map((step, index) => [step.id, index]));
-  const conditionContinuationIndex = (conditionId: string) => {
-    const conditionIndex = idToIndex.get(conditionId);
-    if (conditionIndex === undefined) return undefined;
-    const explicitTargetId = steps[conditionIndex]?.flow?.successTargetId;
-    return explicitTargetId ? idToIndex.get(explicitTargetId) : undefined;
-  };
-  const nextIndexAfterStep = (currentIndex: number, step: AppiumRecordedStepRecord) => {
-    const explicitTargetId = step.flow?.successTargetId;
-    if (explicitTargetId) return idToIndex.get(explicitTargetId);
-    if (!step.flow?.parentConditionId || !step.flow.parentBranch) return currentIndex + 1;
-    const nextStep = steps[currentIndex + 1];
-    const staysInBranch = nextStep?.flow?.parentConditionId === step.flow.parentConditionId
-      && nextStep.flow.parentBranch === step.flow.parentBranch;
-    return staysInBranch
-      ? currentIndex + 1
-      : conditionContinuationIndex(step.flow.parentConditionId);
-  };
+  const traversal = new BoundedLoopTraversal(steps);
+  const nextIndexAfterStep = (index: number, step: AppiumRecordedStepRecord) => traversal.next(step, index);
   const visitedPath: string[] = [];
   let index: number | undefined = 0;
-  let guard = 0;
-  const maxVisits = Math.max(steps.length * 4, 20);
 
   while (typeof index === 'number' && index >= 0 && index < steps.length) {
     if (replayContext.getStore()?.flowEnded) return;
     throwIfReplayStopped();
-    guard += 1;
-    if (guard > maxVisits) throw new Error('流程图可能存在循环，已终止回放');
-
     const step = steps[index];
-    if (shouldSkipLinkedScriptInitStep(options, step)) {
+    traversal.visit(step);
+    const loopContext = traversal.context(step);
+    const frameStep = loopContext ? { ...step, label: `${step.label}（${loopContext}）` } : step;
+    if (shouldSkipLinkedScriptInitStep(options, step, steps)) {
       lines.push(`[节点 ${index + 1}] 跳过：${step.label}（${linkedScriptInitSkipReason(step)}）`);
       index = nextIndexAfterStep(index, step);
       continue;
     }
     visitedPath.push(step.label);
     const nodeKind = defaultFlowKind(step);
-    lines.push(`[节点 ${index + 1}] 开始：${step.label}`);
-    await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'before', '执行前');
+    lines.push(`[节点 ${index + 1}] 开始：${frameStep.label}`);
+    await captureReplayFrame(sessionId, frameStep, index + 1, options.scriptName || '', 'before', '执行前');
 
     if (nodeKind === 'condition') {
       try {
+        if (step.type === 'loop') {
+          const iterations = traversal.iteration(step);
+          const atLimit = iterations >= step.loop!.maxIterations;
+          const exitMatched = !atLimit && await evaluateCondition(sessionId, deviceId, step);
+          if (atLimit || exitMatched) {
+            const reason = atLimit ? '达到最大次数' : '满足退出条件';
+            lines.push(`[循环 ${step.label}] 结束：${reason}，已执行 ${iterations} 轮`);
+            await captureReplayFrame(sessionId, frameStep, index + 1, options.scriptName || '', 'after', `${reason}，已执行 ${iterations} 轮`);
+            index = traversal.exit(step);
+          } else {
+            const entered = traversal.enter(step);
+            lines.push(`[循环 ${step.label}] 第 ${entered.iteration}/${step.loop!.maxIterations} 轮开始`);
+            await captureReplayFrame(sessionId, frameStep, index + 1, options.scriptName || '', 'after', `第 ${entered.iteration}/${step.loop!.maxIterations} 轮`);
+            index = entered.next;
+          }
+          continue;
+        }
         // AI 节点使用本次执行前截图，并将同一张图片和识别依据写入结果帧。
         const beforeFrame = replayContext.getStore()?.frames.at(-1);
         const recognition = step.type === 'aiRecognition' ? await recognizeDeviceScreen({
@@ -1172,19 +1203,20 @@ async function replayFlowSteps(
         const matched = recognition ? recognition.result : await evaluateCondition(sessionId, deviceId, step);
         if (recognition) lines.push(`[节点 ${index + 1}] AI 识别：${recognition.result}，耗时 ${recognition.durationMs}ms${recognition.reason ? `，依据：${recognition.reason}` : ''}`);
         const branchTargetId = matched ? step.flow?.yesTargetId : step.flow?.noTargetId;
-        const targetId = branchTargetId || step.flow?.successTargetId || '';
+        const next = traversal.branch(step, matched);
+        const targetId = branchTargetId || (next === undefined ? '' : steps[next]?.id) || '';
         const branchLabel = flowBranchLabel(step, matched ? 'yes' : 'no');
         lines.push(`[节点 ${index + 1}] 判断：${branchLabel}${isNativeStateCondition(step) ? `（checked=${matched}）` : ''}${targetId ? `，进入 ${targetId}` : '，流程结束'}`);
         await captureReplayFrame(
           sessionId,
-          step,
+          frameStep,
           index + 1,
           options.scriptName || '',
           'after',
           `判断：${branchLabel}${recognition?.reason ? `；${recognition.reason}` : ''}`,
           recognition?.imageBase64,
         );
-        index = targetId ? idToIndex.get(targetId) : undefined;
+        index = next;
       } catch (error) {
         if (isReplayStopped(error)) {
           lines.push(`[节点 ${index + 1}] 已终止：${step.label}`);
@@ -1201,17 +1233,25 @@ async function replayFlowSteps(
 
     try {
       let softFailed = false;
-      if (step.type === 'runScript') {
+      if (step.type === 'breakLoop') {
+        const exited = traversal.break(step);
+        lines.push(`[循环 ${exited.loop.label}] 第 ${exited.iteration} 轮主动退出`);
+        await captureReplayFrame(sessionId, frameStep, index + 1, options.scriptName || '', 'after', `已退出循环：${exited.loop.label}`);
+        index = exited.next;
+        continue;
+      } else if (step.type === 'runScript') {
         await replayLinkedScript(sessionId, deviceId, step, lines, stack);
       } else {
         const result = await runStep(sessionId, deviceId, step, {
           nodeNumber: index + 1,
           scriptName: options.scriptName || '',
+          frameStart: options.frameStart,
         });
         softFailed = appendRunStepResult(lines, index + 1, result);
       }
       lines.push(`[节点 ${index + 1}] 完成：${step.label}${softFailed ? '（存在软失败，已继续）' : ''}`);
-      await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'after', completedStepStatus(step, softFailed));
+      await captureReplayFrame(sessionId, frameStep, index + 1, options.scriptName || '', 'after', completedStepStatus(step, softFailed));
+      processPendingVisualChecks(lines);
       index = nextIndexAfterStep(index, step);
     } catch (error) {
       if (isReplayStopped(error)) {
@@ -1259,6 +1299,8 @@ async function replayScriptSteps(
   stack: string[],
   options: ReplayStepOptions = {},
 ) {
+  validateLoopSteps(steps);
+  options = { ...options, frameStart: replayContext.getStore()?.frames.length || 0 };
   let trailingLinkIndex = steps.length;
   while (
     trailingLinkIndex > 0
@@ -1306,6 +1348,7 @@ export async function replayAppiumScript(
   if (!script.steps.length) throw new Error('脚本没有可回放步骤');
 
   const startedAt = new Date();
+  const appVersion = await readAppVersion(targetDeviceId, script.appPackage).catch(() => '');
   const lines: string[] = [];
   const pushLine = lines.push.bind(lines);
   lines.push = (...items: string[]) => {
@@ -1319,7 +1362,9 @@ export async function replayAppiumScript(
     serverUrl: configuredAppiumServerUrl(),
     deviceId: targetDeviceId,
     frames: [] as AppiumReplayFrame[],
+    historyEvents: [] as AppiumReplayFrame[],
     visualChecks: [] as AppiumReplayVisualCheck[],
+    visualStartOffsets: new Map<string, number>(),
     pendingVisualChecks: [] as PendingVisualChangeCheck[],
     softFailureCount: 0,
   };
@@ -1334,6 +1379,7 @@ export async function replayAppiumScript(
     let stopped = false;
     let managedAppium: Awaited<ReturnType<typeof startManagedAppiumServer>> | null = null;
     try {
+      validateLoopSteps(script.steps);
       lines.push('正在检测 Android SDK...');
       const androidSdk = ensureAndroidSdkAvailable();
       lines.push(`Android SDK 已就绪：${androidSdk.root}`);
@@ -1441,6 +1487,14 @@ export async function replayAppiumScript(
       logPath,
       htmlReportPath,
       softFailureCount: context.softFailureCount,
+      history: {
+        scriptId: script.id, scriptName: script.name, appPackage: script.appPackage,
+        appVersion, deviceId: targetDeviceId, startedAt: startedAt.toISOString(),
+        durationMs: completedAt.getTime() - startedAt.getTime(),
+        status: stopped ? 'stopped' as const : success ? 'passed' as const : 'failed' as const,
+        output: lines.join('\n'),
+        ...captureHistoryFrames(context.frames, context.visualChecks, context.historyEvents),
+      },
     };
   });
 }

package/server/appium-recorder/bounded-loop.ts

@@ -0,0 +1,118 @@
+import type { AppiumRecordedStep } from '../../src/appium-recorder/types';
+import { enclosingLoop, enclosingLoops, breakLoopTarget, validateLoopSteps } from '../../src/appium-recorder/bounded-loop';
+import { defaultFlowKind } from '../../src/appium-recorder/flow-labels';
+
+/** Virtual returns keep the saved flow graph acyclic and preserve branch layout. */
+export class BoundedLoopTraversal {
+  private readonly byId: Map<string, number>;
+  private readonly active = new Map<string, { iteration: number; visited: Set<string> }>();
+  private readonly rootVisited = new Set<string>();
+  private readonly owners = new Map<string, AppiumRecordedStep | undefined>();
+
+  constructor(private readonly steps: AppiumRecordedStep[]) {
+    validateLoopSteps(steps);
+    this.byId = new Map(steps.map((step, index) => [step.id, index]));
+  }
+
+  private target(id?: string) { return id ? this.byId.get(id) : undefined; }
+  private owner(step: AppiumRecordedStep) {
+    if (!this.owners.has(step.id)) this.owners.set(step.id, enclosingLoop(this.steps, step));
+    return this.owners.get(step.id);
+  }
+
+  visit(step: AppiumRecordedStep) {
+    if (step.type === 'loop' && this.active.has(step.id)) return;
+    const owner = this.owner(step);
+    const frame = owner ? this.active.get(owner.id) : undefined;
+    if (owner && !frame) throw new Error('不能从循环外直接进入循环体');
+    const visited = frame?.visited || this.rootVisited;
+    if (visited.has(step.id)) throw new Error('流程存在非有界循环回边，已终止回放');
+    visited.add(step.id);
+  }
+
+  private continuation(step: AppiumRecordedStep, seen = new Set<string>()): number | undefined {
+    if (seen.has(step.id)) throw new Error('流程分支归属存在循环');
+    seen.add(step.id);
+    if (step.flow?.successTargetId) return this.target(step.flow.successTargetId);
+    if (defaultFlowKind(step) === 'condition') {
+      const start = this.byId.get(step.id)!;
+      const sibling = this.steps.findIndex((item, index) => index > start && item.flow?.parentConditionId === step.flow?.parentConditionId && item.flow?.parentBranch === step.flow?.parentBranch);
+      if (sibling >= 0) return sibling;
+    }
+    const parentIndex = this.target(step.flow?.parentConditionId);
+    if (parentIndex === undefined) return;
+    const parent = this.steps[parentIndex]!;
+    if (parent.type === 'loop' && step.flow?.parentBranch === 'yes') return parentIndex;
+    return this.continuation(parent, seen);
+  }
+
+  private returnAtBoundary(step: AppiumRecordedStep, next: number | undefined) {
+    const owner = this.owner(step);
+    if (!owner || !this.active.has(owner.id)) return next;
+    // The end of any nested branch returns to the loop, not to the other branch.
+    if (next === undefined || (this.steps[next]?.id !== owner.id && !this.isInBody(this.steps[next]!, owner.id))) {
+      return this.target(owner.id);
+    }
+    return next;
+  }
+
+  private isInBody(step: AppiumRecordedStep, loopId: string) {
+    let owner = this.owner(step);
+    const seen = new Set<string>();
+    while (owner && !seen.has(owner.id)) {
+      if (owner.id === loopId) return true;
+      seen.add(owner.id); owner = this.owner(owner);
+    }
+    return false;
+  }
+
+  next(step: AppiumRecordedStep, index: number) {
+    let next = this.target(step.flow?.successTargetId);
+    if (!step.flow?.successTargetId) {
+      const sibling = this.steps[index + 1];
+      next = sibling && sibling.flow?.parentConditionId === step.flow?.parentConditionId && sibling.flow?.parentBranch === step.flow?.parentBranch
+        ? index + 1 : this.continuation(step);
+    }
+    return this.returnAtBoundary(step, next);
+  }
+
+  branch(step: AppiumRecordedStep, matched: boolean) {
+    const id = matched ? step.flow?.yesTargetId : step.flow?.noTargetId;
+    return this.returnAtBoundary(step, id ? this.target(id) : this.continuation(step));
+  }
+
+  iteration(step: AppiumRecordedStep) { return this.active.get(step.id)?.iteration || 0; }
+
+  enter(step: AppiumRecordedStep) {
+    const iteration = this.iteration(step) + 1;
+    if (iteration > step.loop!.maxIterations) throw new Error('循环次数超过上限');
+    this.active.set(step.id, { iteration, visited: new Set() });
+    return { iteration, next: this.target(step.flow?.yesTargetId) ?? this.target(step.id) };
+  }
+
+  exit(step: AppiumRecordedStep) {
+    this.active.delete(step.id);
+    return this.returnAtBoundary(step, this.target(step.flow?.noTargetId) ?? this.continuation(step));
+  }
+
+  break(step: AppiumRecordedStep) {
+    const owner = breakLoopTarget(this.steps, step);
+    if (!this.active.has(owner.id)) throw new Error('目标循环当前未执行');
+    // Unwind inner frames without running their completion branches.
+    for (const inner of enclosingLoops(this.steps, step)) {
+      if (inner.id === owner.id) break;
+      this.active.delete(inner.id);
+    }
+    return { loop: owner, iteration: this.iteration(owner), next: this.exit(owner) };
+  }
+
+  context(step: AppiumRecordedStep) {
+    const parts: string[] = [];
+    let owner = this.owner(step);
+    while (owner) {
+      parts.unshift(`${owner.label} 第 ${this.iteration(owner)}/${owner.loop!.maxIterations} 轮`);
+      owner = this.owner(owner);
+    }
+    return parts.join(' / ');
+  }
+}

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

@@ -0,0 +1,34 @@
+import { execFile } from 'node:child_process';
+import { getAdbCommand } from '../android-sdk';
+import { htmlImageUrl, type AppiumReplayFrame, type AppiumReplayVisualCheck } from './report';
+import type { HistoryNode } from '../../src/appium-recorder/run-history';
+
+export function readAppVersion(deviceId: string, appPackage: string): Promise<string> {
+  if (!appPackage) return Promise.resolve('');
+  return new Promise(resolve => {
+    execFile(getAdbCommand(), ['-s', deviceId, 'shell', 'dumpsys', 'package', appPackage], { timeout: 5000, maxBuffer: 4 * 1024 * 1024 }, (error, stdout) => {
+      if (error) return resolve('');
+      const name = stdout.match(/\bversionName=([^\r\n]+)/)?.[1]?.trim();
+      const code = stdout.match(/\bversionCode=(\d+)/)?.[1];
+      resolve(name ? `${name}${code ? ` (${code})` : ''}` : '');
+    });
+  });
+}
+
+export function captureHistoryFrames(frames: AppiumReplayFrame[], checks: AppiumReplayVisualCheck[], events = frames) {
+  const cache = new Map<string, string>();
+  const nodes: HistoryNode[] = [];
+  const pending = new Map<string, AppiumReplayFrame>();
+  for (const frame of events) {
+    const key = frame.nodeId;
+    if (frame.phase === 'before') { pending.set(key, frame); continue; }
+    const start = pending.get(key);
+    pending.delete(key);
+    if (frame.phase !== 'stopped') nodes.push({ key, label: `${frame.scriptName} / ${frame.nodeLabel}`, failed: frame.phase === 'error', durationMs: start ? Math.max(0, Date.parse(frame.capturedAt) - Date.parse(start.capturedAt)) : null });
+  }
+  for (const check of checks.filter(check => check.status === 'failed')) {
+    const node = nodes.find(node => node.key === check.nodeId);
+    if (node) node.failed = true;
+  }
+  return { nodes, frames: frames.map(frame => ({ key: frame.nodeId, label: frame.nodeLabel, phase: frame.phase, capturedAt: frame.capturedAt, imageUrl: htmlImageUrl(frame.imageBase64, cache) })) };
+}

package/server/appium-recorder/report.ts

@@ -126,7 +126,7 @@ function compressHtmlPngBase64(base64: string) {
   }
 }
 
-function htmlImageUrl(base64: string, cache: Map<string, string>) {
+export function htmlImageUrl(base64: string, cache: Map<string, string>) {
   const cached = cache.get(base64);
   if (cached) return cached;
 

package/server/appium-recorder/repository.ts

@@ -7,6 +7,7 @@ import {
   sqlString,
 } from '../storage/sqlite';
 import { normalizeLegacyNestedConditionBranches } from '../../src/appium-recorder/flow-normalize';
+import { validateLoopSteps } from '../../src/appium-recorder/bounded-loop';
 
 export type AppiumRecordedStepRecord = {
   id: string;
@@ -34,6 +35,8 @@ export type AppiumRecordedStepRecord = {
     | 'launchApp'
     | 'openGallery'
     | 'endFlow'
+    | 'loop'
+    | 'breakLoop'
     | 'clearAppData'
     | 'waitDisappear'
     | 'assertText'
@@ -86,6 +89,11 @@ export type AppiumRecordedStepRecord = {
   keyCode?: number;
   timeoutMs?: number;
   longPressMode?: 'element' | 'coordinates';
+  breakLoopTargetId?: string;
+  loop?: {
+    maxIterations: number;
+    exitWhen: 'never' | 'exists' | 'notExists';
+  };
   flow?: {
     nodeKind?: 'action' | 'condition' | 'assertion';
     yesTargetId?: string;
@@ -338,6 +346,7 @@ export function saveAppiumRecordedScript(input: {
   const name = input.name.trim();
   const appPackage = input.appPackage.trim();
   const steps = normalizeLegacyNestedConditionBranches(input.steps || []);
+  validateLoopSteps(steps);
   const appActivity = normalizeScriptActivity(appPackage, input.appActivity, steps);
 
   if (!name) throw new Error('脚本名称不能为空');

package/server/appium-recorder/routes.ts

@@ -1,4 +1,5 @@
 import { execFile } from 'node:child_process';
+import { deleteRunHistory, getRunHistory, listRunHistory, saveRunHistory } from './run-history';
 import { recognizeDeviceScreen } from './ai-recognition';
 import { readFreshWindowHierarchy } from './tree-dump';
 import type { IncomingMessage, ServerResponse } from 'node:http';
@@ -307,6 +308,21 @@ export async function handleAppiumRecorderRequest(
       return true;
     }
 
+    const historyMatch = pathname.match(/^\/api\/appium-recorder\/scripts\/([^/]+)\/history(?:\/([^/]+))?$/);
+    if (historyMatch) {
+      const scriptId = decodeURIComponent(historyMatch[1]);
+      const id = historyMatch[2] ? decodeURIComponent(historyMatch[2]) : '';
+      if (req.method === 'GET') {
+        const data = id ? getRunHistory(scriptId, id) : listRunHistory(scriptId);
+        sendJson(res, data, data ? 200 : 404);
+        return true;
+      }
+      if (req.method === 'DELETE' && id) {
+        deleteRunHistory(scriptId, id);
+        sendJson(res, { success: true });
+        return true;
+      }
+    }
     const replayMatch = pathname.match(/^\/api\/appium-recorder\/scripts\/([^/]+)\/replay$/);
     if (replayMatch && req.method === 'POST') {
       const parsed = await readBody<{ deviceId?: string }>(req);
@@ -323,13 +339,18 @@ export async function handleAppiumRecorderRequest(
         res.flushHeaders();
       }
       if (isRemoteDeviceId(deviceId)) {
-        const result = await sendRemoteCommand(deviceId, 'replay', { script }) as { success?: boolean; output?: string };
+        const result = await sendRemoteCommand(deviceId, 'replay', { 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 }));
-          sendStreamEvent(res, { type: 'result', ...result });
+          sendStreamEvent(res, { type: 'result', ...response });
           res.end();
         } else {
-          sendJson(res, result, result.success ? 200 : 500);
+          sendJson(res, response, result.success ? 200 : 500);
         }
         return true;
       }
@@ -346,11 +367,14 @@ export async function handleAppiumRecorderRequest(
           streamOutput ? (line) => sendStreamEvent(res, { type: 'log', line }) : undefined,
           replayAbortController.signal,
         );
+        try { saveRunHistory(result.history); }
+        catch { result.output += '\n历史记录保存失败'; }
+        const { history: _history, ...response } = result;
         if (streamOutput) {
-          sendStreamEvent(res, { type: 'result', ...result });
+          sendStreamEvent(res, { type: 'result', ...response });
           res.end();
         } else {
-          sendJson(res, result, result.success ? 200 : 500);
+          sendJson(res, response, result.success ? 200 : 500);
         }
       } finally {
         replayingDevices.delete(deviceId);

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

@@ -0,0 +1,34 @@
+import { createId, querySql, runSql, sqlJson, sqlString } from '../storage/sqlite';
+import type { RunDetail, RunSummary } from '../../src/appium-recorder/run-history';
+
+function ensureTable() {
+  runSql(`CREATE TABLE IF NOT EXISTS appium_run_history (
+    id TEXT PRIMARY KEY, script_id TEXT NOT NULL, started_at TEXT NOT NULL,
+    summary TEXT NOT NULL, detail TEXT NOT NULL
+  ); CREATE INDEX IF NOT EXISTS appium_run_history_script ON appium_run_history(script_id, started_at);`);
+}
+
+export function saveRunHistory(input: Omit<RunDetail, 'id'>) {
+  ensureTable();
+  const record = { ...input, id: createId('run') };
+  const { frames, output, ...summary } = record;
+  runSql(`INSERT INTO appium_run_history VALUES (${sqlString(record.id)}, ${sqlString(record.scriptId)}, ${sqlString(record.startedAt)}, ${sqlJson(summary)}, ${sqlJson({ frames, output })});`);
+  return record.id;
+}
+
+export function listRunHistory(scriptId: string): RunSummary[] {
+  ensureTable();
+  return (querySql<{ summary: string }>(`SELECT summary FROM appium_run_history WHERE script_id=${sqlString(scriptId)} ORDER BY started_at DESC;`) || []).map(row => JSON.parse(row.summary));
+}
+
+export function getRunHistory(scriptId: string, id: string): RunDetail | null {
+  ensureTable();
+  const row = querySql<{ summary: string; detail: string }>(`SELECT summary, detail FROM appium_run_history WHERE script_id=${sqlString(scriptId)} AND id=${sqlString(id)};`)?.[0];
+  return row ? { ...JSON.parse(row.summary), ...JSON.parse(row.detail) } : null;
+}
+
+export function deleteRunHistory(scriptId: string, id: string) {
+  ensureTable();
+  // 不接受文件路径，也不删除原始报告；只删除这条历史的自包含快照。
+  runSql(`PRAGMA secure_delete=ON; DELETE FROM appium_run_history WHERE script_id=${sqlString(scriptId)} AND id=${sqlString(id)};`);
+}