android-midscene-automation 0.1.26 → 0.1.28

package/server/appium-recorder/report.ts

@@ -1,8 +1,10 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { PNG } from 'pngjs';
 import { appDataPath } from '../paths';
 import { loadConfig } from '../config';
 import { saveAppiumReplayReport, type AppiumRecordedScriptRecord, type AppiumRecordedStepRecord } from './repository';
+import { flowBranchLabel } from '../../src/appium-recorder/flow-labels';
 
 export type AppiumReplayFrame = {
   sequence: number;
@@ -11,6 +13,7 @@ export type AppiumReplayFrame = {
   nodeNumber: number;
   nodeLabel: string;
   nodeType: string;
+  logContent?: string;
   note: string;
   selector: string;
   phase: 'before' | 'after' | 'error' | 'stopped';
@@ -19,6 +22,35 @@ export type AppiumReplayFrame = {
   imageBase64: string;
 };
 
+export type AppiumReplayVisualCheck = {
+  nodeId: string;
+  nodeNumber: number;
+  nodeLabel: string;
+  startNodeId?: string;
+  startNodeLabel?: string;
+  endNodeId?: string;
+  endNodeLabel?: string;
+  status: 'passed' | 'failed';
+  message: string;
+  region: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  durationMs: number;
+  intervalMs: number;
+  sampleCount: number;
+  changeRatioThreshold: number;
+  maxChangeRatio: number;
+  baselineBase64: string;
+  comparisonBase64: string;
+  diffBase64: string;
+};
+
+const HTML_REPORT_IMAGE_MAX_WIDTH = 540;
+const HTML_REPORT_IMAGE_MAX_HEIGHT = 1200;
+
 function pad(value: number, length = 2) {
   return String(value).padStart(length, '0');
 }
@@ -55,6 +87,54 @@ function jsonForHtml(value: unknown) {
     .replace(/&/g, '\\u0026');
 }
 
+function compressHtmlPngBase64(base64: string) {
+  if (!base64) return base64;
+
+  try {
+    const source = PNG.sync.read(Buffer.from(base64, 'base64'));
+    const scale = Math.min(
+      1,
+      HTML_REPORT_IMAGE_MAX_WIDTH / source.width,
+      HTML_REPORT_IMAGE_MAX_HEIGHT / source.height,
+    );
+
+    if (scale >= 1) return base64;
+
+    const width = Math.max(1, Math.round(source.width * scale));
+    const height = Math.max(1, Math.round(source.height * scale));
+    const target = new PNG({ width, height });
+    const scaleX = source.width / width;
+    const scaleY = source.height / height;
+
+    // HTML 回放只用于预览，降采样能明显降低报告体积，不影响实际检测结果。
+    for (let y = 0; y < height; y += 1) {
+      const sourceY = Math.min(source.height - 1, Math.floor(y * scaleY));
+      for (let x = 0; x < width; x += 1) {
+        const sourceX = Math.min(source.width - 1, Math.floor(x * scaleX));
+        const sourceIndex = (sourceY * source.width + sourceX) << 2;
+        const targetIndex = (y * width + x) << 2;
+        target.data[targetIndex] = source.data[sourceIndex];
+        target.data[targetIndex + 1] = source.data[sourceIndex + 1];
+        target.data[targetIndex + 2] = source.data[sourceIndex + 2];
+        target.data[targetIndex + 3] = source.data[sourceIndex + 3];
+      }
+    }
+
+    return PNG.sync.write(target).toString('base64');
+  } catch {
+    return base64;
+  }
+}
+
+function htmlImageUrl(base64: string, cache: Map<string, string>) {
+  const cached = cache.get(base64);
+  if (cached) return cached;
+
+  const imageUrl = `data:image/png;base64,${compressHtmlPngBase64(base64)}`;
+  cache.set(base64, imageUrl);
+  return imageUrl;
+}
+
 function markdownValue(value: unknown) {
   if (value === undefined || value === null || value === '') return '-';
   return String(value).replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>');
@@ -73,14 +153,51 @@ function stepExecutionLines(outputLines: string[], index: number) {
 
 function executionStatus(lines: string[]) {
   if (!lines.length) return '未执行';
-  if (lines.some((line) => line.includes('失败：') || line.includes('失败分支：'))) return '失败';
-  if (lines.some((line) => line.includes('跳过：'))) return '跳过';
-  if (lines.some((line) => line.includes('判断：'))) return '判断完成';
-  if (lines.some((line) => line.includes('完成：'))) return '成功';
+  // 只识别执行器的状态前缀，用户日志中的“失败”等文字不是执行结果。
+  const messages = lines.map((line) => line.replace(/^\[(?:节点|步骤) \d+\] /, ''));
+  if (messages.some((line) => line.startsWith('失败：') || line.startsWith('失败分支：'))) return '失败';
+  if (messages.some((line) => line.startsWith('跳过：'))) return '跳过';
+  if (messages.some((line) => line.startsWith('判断：'))) return '判断完成';
+  if (messages.some((line) => line.startsWith('完成：'))) return '成功';
   return '中断';
 }
 
-function stepSection(step: AppiumRecordedStepRecord, index: number, outputLines: string[]) {
+function visualCheckStatusLabel(status: AppiumReplayVisualCheck['status']) {
+  return status === 'passed' ? '有变化' : '无明显变化';
+}
+
+function visualCheckSection(check?: AppiumReplayVisualCheck) {
+  if (!check) return '';
+  const statusLabel = visualCheckStatusLabel(check.status);
+  const region = `${check.region.x}, ${check.region.y}, ${check.region.width} x ${check.region.height}`;
+  return [
+    '#### 画面变化检测',
+    '',
+    '| 项目 | 内容 |',
+    '| --- | --- |',
+    `| 检测结果 | **${statusLabel}** |`,
+    `| 开始节点 | ${markdownValue(check.startNodeLabel || check.startNodeId)} |`,
+    `| 结束节点 | ${markdownValue(check.endNodeLabel || check.endNodeId)} |`,
+    `| 检测区域 | ${markdownValue(region)} |`,
+    `| 对比方式 | ${check.durationMs ? markdownValue(`${check.durationMs}ms / 每 ${check.intervalMs}ms`) : '起止节点截图对比'} |`,
+    `| 采样次数 | ${check.sampleCount} |`,
+    `| 变化阈值 | ${check.changeRatioThreshold}% |`,
+    `| 最大变化比例 | ${check.maxChangeRatio.toFixed(2)}% |`,
+    `| 说明 | ${markdownValue(check.message)} |`,
+    '',
+    '| 基准帧 | 对比帧 | 差异图 |',
+    '| --- | --- | --- |',
+    `| ![基准帧](data:image/png;base64,${check.baselineBase64}) | ![对比帧](data:image/png;base64,${check.comparisonBase64}) | ![差异图](data:image/png;base64,${check.diffBase64}) |`,
+    '',
+  ].join('\n');
+}
+
+function stepSection(
+  step: AppiumRecordedStepRecord,
+  index: number,
+  outputLines: string[],
+  visualCheck?: AppiumReplayVisualCheck,
+) {
   const executionLines = stepExecutionLines(outputLines, index);
   const config = JSON.stringify(step, null, 2);
   return [
@@ -96,9 +213,8 @@ function stepSection(step: AppiumRecordedStepRecord, index: number, outputLines:
     `| 上下文 Selector | ${markdownValue(selectorText(step.contextSelector))} |`,
     `| 输入/目标值 | ${markdownValue(step.value)} |`,
     `| 超时时间 | ${markdownValue(step.timeoutMs === undefined ? '-' : `${step.timeoutMs}ms`)} |`,
-    `| 可选步骤 | ${step.optional ? '是' : '否'} |`,
-    `| 是分支 | ${markdownValue(step.flow?.yesTargetId)} |`,
-    `| 否分支 | ${markdownValue(step.flow?.noTargetId)} |`,
+    `| ${flowBranchLabel(step, 'yes')} 分支 | ${markdownValue(step.flow?.yesTargetId)} |`,
+    `| ${flowBranchLabel(step, 'no')} 分支 | ${markdownValue(step.flow?.noTargetId)} |`,
     `| 成功后续节点 | ${markdownValue(step.flow?.successTargetId)} |`,
     `| 执行状态 | **${executionStatus(executionLines)}** |`,
     '',
@@ -108,6 +224,7 @@ function stepSection(step: AppiumRecordedStepRecord, index: number, outputLines:
     executionLines.length ? executionLines.join('\n') : '该节点未进入执行路径，或在前序失败后未执行。',
     executionLines.length ? '```' : '',
     '',
+    visualCheckSection(visualCheck),
     '<details>',
     '<summary>完整节点配置</summary>',
     '',
@@ -127,16 +244,27 @@ function createReplayHtml(input: {
   startedAt: Date;
   completedAt: Date;
   frames: AppiumReplayFrame[];
+  visualChecks: AppiumReplayVisualCheck[];
   output: string;
 }) {
+  const imageCache = new Map<string, string>();
   const payload = jsonForHtml({
     startedAt: input.startedAt.toISOString(),
     durationMs: input.durationMs,
     frames: input.frames.map((frame) => ({
       ...frame,
-      imageUrl: `data:image/png;base64,${frame.imageBase64}`,
+      imageUrl: htmlImageUrl(frame.imageBase64, imageCache),
       imageBase64: undefined,
     })),
+    visualChecks: input.visualChecks.map((check) => ({
+      ...check,
+      baselineImageUrl: htmlImageUrl(check.baselineBase64, imageCache),
+      comparisonImageUrl: htmlImageUrl(check.comparisonBase64, imageCache),
+      diffImageUrl: htmlImageUrl(check.diffBase64, imageCache),
+      baselineBase64: undefined,
+      comparisonBase64: undefined,
+      diffBase64: undefined,
+    })),
     output: input.output,
   });
   const resultClass = input.resultText === '成功' ? 'success' : input.resultText === '已终止' ? 'stopped' : 'failed';
@@ -174,6 +302,8 @@ function createReplayHtml(input: {
     .frame-title, .frame-subtitle { display: block; overflow-wrap: anywhere; }
     .frame-title { font-size: 13px; font-weight: 600; }
     .frame-subtitle, .frame-time { margin-top: 3px; color: #7a818b; font-size: 11px; }
+    .frame-log, #node-log { white-space: pre-wrap; overflow-wrap: anywhere; font-family: ui-monospace, SFMono-Regular, Consolas, monospace; }
+    .frame-log { display: block; margin-top: 6px; color: #4b515a; font-size: 12px; line-height: 1.5; }
     .workspace { display: grid; grid-template-rows: 178px minmax(0, 1fr); min-width: 0; min-height: 0; }
     .timeline-panel { min-width: 0; overflow-x: auto; overflow-y: hidden; border-bottom: 1px solid #dfe3e8; background: #fff; }
     .timeline-track { position: relative; height: 178px; min-width: 100%; cursor: pointer; user-select: none; }
@@ -199,6 +329,25 @@ function createReplayHtml(input: {
     details { margin: 4px 10px 16px; border: 1px solid #dfe3e8; border-radius: 6px; background: #fff; }
     summary { padding: 12px 14px; cursor: pointer; font-weight: 600; }
     pre { max-height: 360px; margin: 0; overflow: auto; padding: 14px; border-top: 1px solid #e5e8ec; white-space: pre; font: 11px/1.6 ui-monospace, SFMono-Regular, Consolas, monospace; }
+    .visual-check-list { display: grid; gap: 12px; padding: 0 12px 12px; border-top: 1px solid #e5e8ec; }
+    .visual-check { padding: 12px 0 0; border-top: 1px solid #eef1f5; }
+    .visual-check:first-child { border-top: 0; }
+    .visual-check h3 { margin: 0 0 8px; font-size: 13px; overflow-wrap: anywhere; }
+    .visual-check dl { display: grid; grid-template-columns: 72px minmax(0, 1fr); gap: 5px 8px; margin: 0 0 10px; font-size: 12px; }
+    .visual-check dt { color: #8a9099; }
+    .visual-check dd { margin: 0; overflow-wrap: anywhere; }
+    .visual-check .passed { color: #237804; font-weight: 700; }
+    .visual-check .failed { color: #cf1322; font-weight: 700; }
+    .visual-images { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 6px; }
+    .visual-image span { display: block; margin-bottom: 4px; color: #646a73; font-size: 11px; text-align: center; }
+    .visual-image img { display: block; width: 100%; max-height: 120px; object-fit: contain; border: 1px solid #dfe3e8; border-radius: 3px; background: #101827; cursor: zoom-in; }
+    .visual-image img:hover { border-color: #1677ff; }
+    .image-preview { position: fixed; inset: 0; z-index: 20; display: grid; grid-template-rows: auto minmax(0, 1fr); gap: 12px; padding: 20px; background: rgba(16, 24, 39, .88); }
+    .image-preview[hidden] { display: none; }
+    .image-preview__bar { display: flex; align-items: center; justify-content: space-between; gap: 16px; color: #fff; }
+    .image-preview__title { min-width: 0; overflow: hidden; font-size: 14px; font-weight: 600; text-overflow: ellipsis; white-space: nowrap; }
+    .image-preview__close { flex: 0 0 auto; border-color: rgba(255, 255, 255, .28); color: #fff; background: rgba(255, 255, 255, .1); }
+    .image-preview__image { place-self: center; max-width: 100%; max-height: calc(100vh - 88px); object-fit: contain; border-radius: 4px; background: #101827; box-shadow: 0 20px 60px rgba(0, 0, 0, .35); }
     @media (max-width: 860px) {
       body { overflow: auto; }
       main { grid-template-columns: 1fr; height: auto; }
@@ -231,12 +380,14 @@ function createReplayHtml(input: {
           <dt>节点</dt><dd id="node">-</dd>
           <dt>阶段</dt><dd id="phase">-</dd>
           <dt>结果</dt><dd id="frame-status">-</dd>
+          <dt id="node-log-label" hidden>日志内容</dt><dd id="node-log" hidden></dd>
           <dt>备注</dt><dd id="note">-</dd>
           <dt>定位</dt><dd id="selector">-</dd>
           <dt>时间</dt><dd id="time">-</dd>
         </dl>
       </section>
       <nav id="step-list" class="step-list" aria-label="执行步骤"></nav>
+      <details><summary>视觉变化检测</summary><div id="visual-checks" class="visual-check-list"></div></details>
       <details><summary>完整回放日志</summary><pre id="log"></pre></details>
     </aside>
     <section class="workspace">
@@ -259,21 +410,61 @@ function createReplayHtml(input: {
       </section>
     </section>
   </main>
+  <div id="image-preview" class="image-preview" hidden>
+    <div class="image-preview__bar">
+      <span id="image-preview-title" class="image-preview__title"></span>
+      <button id="image-preview-close" class="image-preview__close" type="button">关闭</button>
+    </div>
+    <img id="image-preview-image" class="image-preview__image" alt="" />
+  </div>
   <script id="replay-data" type="application/json">${payload}</script>
   <script>
     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 frames = (Array.isArray(data.frames) ? data.frames : []).map((frame) => ({
       ...frame,
       offsetMs: Math.max(0, (Date.parse(frame.capturedAt) || reportStartedAt) - reportStartedAt),
     }));
     const durationMs = Math.max(1000, Number(data.durationMs) || 0, frames.at(-1)?.offsetMs || 0);
-    const elements = Object.fromEntries(['screen','empty','previous','play','next','seek','clock','caption','title','script','node','phase','frame-status','note','selector','time','step-list','timeline-track','ruler','playhead','log'].map((id) => [id, document.querySelector('#' + id)]));
+    // 按一次执行配对，而不是按节点 ID 全局去重；连接脚本和重复执行仍保留独立步骤。
+    const steps = [];
+    const frameSteps = [];
+    const pendingSteps = new Map();
+    frames.forEach((frame, index) => {
+      const key = JSON.stringify([frame.scriptName, frame.nodeId, frame.nodeNumber]);
+      const pending = pendingSteps.get(key) || [];
+      let stepIndex = frame.phase === 'before' ? undefined : pending.pop();
+      if (stepIndex === undefined) {
+        stepIndex = steps.length;
+        steps.push({ firstIndex: index, lastIndex: index });
+      } else {
+        steps[stepIndex].lastIndex = index;
+      }
+      if (frame.phase === 'before') pending.push(stepIndex);
+      pendingSteps.set(key, pending);
+      frameSteps[index] = stepIndex;
+    });
+    const elements = Object.fromEntries(['screen','empty','previous','play','next','seek','clock','caption','title','script','node','phase','frame-status','note','selector','time','step-list','timeline-track','ruler','playhead','visual-checks','log'].map((id) => [id, document.querySelector('#' + id)]));
+    const imagePreview = document.querySelector('#image-preview');
+    const imagePreviewImage = document.querySelector('#image-preview-image');
+    const imagePreviewTitle = document.querySelector('#image-preview-title');
+    const closeImagePreview = () => {
+      imagePreview.hidden = true;
+      imagePreviewImage.removeAttribute('src');
+    };
+    const openImagePreview = (url, title) => {
+      imagePreviewImage.src = url;
+      imagePreviewImage.alt = title;
+      imagePreviewTitle.textContent = title;
+      imagePreview.hidden = false;
+    };
     let currentFrame = frames.length ? 0 : -1;
     let currentMs = 0;
     let animationFrame = 0;
     let playbackStartedAt = 0;
     const phaseLabels = { before: '执行前', after: '执行后', error: '失败', stopped: '已终止' };
+    const visualCheckStatusLabel = (status) => status === 'passed' ? '有变化' : '无明显变化';
     const formatTime = (milliseconds) => {
       const seconds = Math.max(0, Math.floor(milliseconds / 1000));
       return String(Math.floor(seconds / 60)).padStart(2, '0') + ':' + String(seconds % 60).padStart(2, '0');
@@ -297,6 +488,10 @@ function createReplayHtml(input: {
         elements.node.textContent = String(frame.nodeNumber || '-');
         elements.phase.textContent = phaseLabels[frame.phase] || frame.phase || '-';
         elements['frame-status'].textContent = frame.status || '-';
+        const logContent = frames[steps[frameSteps[currentFrame]].lastIndex].logContent;
+        document.querySelector('#node-log-label').hidden = !logContent;
+        document.querySelector('#node-log').hidden = !logContent;
+        document.querySelector('#node-log').textContent = logContent || '';
         elements.note.textContent = frame.note || '-';
         elements.selector.textContent = frame.selector || '-';
         elements.time.textContent = new Date(frame.capturedAt).toLocaleString();
@@ -308,7 +503,8 @@ function createReplayHtml(input: {
       elements.seek.value = String(Math.round(currentMs / durationMs * 1000));
       elements.clock.textContent = formatTime(currentMs) + ' / ' + formatTime(durationMs);
       elements.playhead.style.left = (currentMs / durationMs * 100) + '%';
-      document.querySelectorAll('.frame-item, .thumbnail').forEach((item) => item.classList.toggle('active', Number(item.dataset.index) === currentFrame));
+      document.querySelectorAll('.frame-item').forEach((item) => item.classList.toggle('active', Number(item.dataset.step) === frameSteps[currentFrame]));
+      document.querySelectorAll('.thumbnail').forEach((item) => item.classList.toggle('active', Number(item.dataset.index) === currentFrame));
       if (scrollStep) document.querySelector('.frame-item.active')?.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
     };
     const pause = () => {
@@ -340,11 +536,13 @@ function createReplayHtml(input: {
       tick.append(label);
       elements.ruler.append(tick);
     }
-    frames.forEach((frame, index) => {
+    steps.forEach((step, index) => {
+      const frame = frames[step.firstIndex];
+      const result = frames[step.lastIndex];
       const button = document.createElement('button');
       button.type = 'button';
       button.className = 'frame-item';
-      button.dataset.index = String(index);
+      button.dataset.step = String(index);
       const badge = document.createElement('span');
       badge.className = 'frame-index';
       badge.textContent = String(index + 1);
@@ -354,15 +552,28 @@ function createReplayHtml(input: {
       title.textContent = frame.nodeNumber + '. ' + frame.nodeLabel;
       const subtitle = document.createElement('span');
       subtitle.className = 'frame-subtitle';
-      subtitle.textContent = (phaseLabels[frame.phase] || frame.phase) + ' · ' + frame.status;
+      subtitle.textContent = result.phase === 'before' ? '未完成' : result.status;
       content.append(title, subtitle);
+      if (frame.nodeType === 'textClick') {
+        const text = document.createElement('span');
+        text.className = 'frame-log frame-click-text';
+        text.textContent = frame.selector || '未设置点击文字';
+        content.append(text);
+      }
+      if (result.logContent) {
+        const log = document.createElement('span');
+        log.className = 'frame-log';
+        log.textContent = result.logContent;
+        content.append(log);
+      }
       const time = document.createElement('span');
       time.className = 'frame-time';
       time.textContent = formatTime(frame.offsetMs);
       button.append(badge, content, time);
       button.addEventListener('click', () => { pause(); seekTo(frame.offsetMs); });
       elements['step-list'].append(button);
-
+    });
+    frames.forEach((frame, index) => {
       const thumbnail = document.createElement('button');
       thumbnail.type = 'button';
       thumbnail.className = 'thumbnail';
@@ -376,6 +587,62 @@ function createReplayHtml(input: {
       thumbnail.addEventListener('click', (event) => { event.stopPropagation(); pause(); seekTo(frame.offsetMs); });
       elements['timeline-track'].append(thumbnail);
     });
+    if (!visualChecks.length) {
+      elements['visual-checks'].textContent = '本次没有视觉变化检测节点';
+    }
+    visualChecks.forEach((check) => {
+      const article = document.createElement('article');
+      article.className = 'visual-check';
+      const title = document.createElement('h3');
+      title.textContent = check.nodeNumber + '. ' + check.nodeLabel;
+      const detail = document.createElement('dl');
+      [
+        ['结果', visualCheckStatusLabel(check.status), check.status],
+        ['开始节点', check.startNodeLabel || check.startNodeId || '-'],
+        ['结束节点', check.endNodeLabel || check.endNodeId || '-'],
+        ['区域', check.region.x + ', ' + check.region.y + ', ' + check.region.width + ' x ' + check.region.height],
+        ['对比', check.durationMs ? check.sampleCount + ' 次 / 每 ' + check.intervalMs + 'ms' : '起止节点截图对比'],
+        ['阈值', check.changeRatioThreshold + '%'],
+        ['最大变化', Number(check.maxChangeRatio || 0).toFixed(2) + '%'],
+        ['说明', check.message || '-'],
+      ].forEach(([label, value, className]) => {
+        const dt = document.createElement('dt');
+        const dd = document.createElement('dd');
+        dt.textContent = label;
+        dd.textContent = value;
+        if (className) dd.className = className;
+        detail.append(dt, dd);
+      });
+      const images = document.createElement('div');
+      images.className = 'visual-images';
+      [
+        ['基准帧', check.baselineImageUrl],
+        ['对比帧', check.comparisonImageUrl],
+        ['差异图', check.diffImageUrl],
+      ].forEach(([label, url]) => {
+        const figure = document.createElement('div');
+        figure.className = 'visual-image';
+        const caption = document.createElement('span');
+        caption.textContent = label;
+        const img = document.createElement('img');
+        img.src = url;
+        img.alt = label;
+        img.title = '点击放大 ' + label;
+        img.tabIndex = 0;
+        img.addEventListener('click', () => openImagePreview(url, check.nodeNumber + '. ' + check.nodeLabel + ' · ' + label));
+        img.addEventListener('keydown', (event) => {
+          if (event.key === 'Enter' || event.key === ' ') {
+            event.preventDefault();
+            event.stopPropagation();
+            openImagePreview(url, check.nodeNumber + '. ' + check.nodeLabel + ' · ' + label);
+          }
+        });
+        figure.append(caption, img);
+        images.append(figure);
+      });
+      article.append(title, detail, images);
+      elements['visual-checks'].append(article);
+    });
     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', () => {
@@ -393,10 +660,18 @@ function createReplayHtml(input: {
       seekTo((event.clientX - bounds.left) / bounds.width * durationMs);
     });
     document.addEventListener('keydown', (event) => {
+      if (!imagePreview.hidden) {
+        if (event.key === 'Escape') closeImagePreview();
+        return;
+      }
       if (event.key === 'ArrowLeft') elements.previous.click();
       if (event.key === 'ArrowRight') elements.next.click();
       if (event.key === ' ') { event.preventDefault(); elements.play.click(); }
     });
+    imagePreview.addEventListener('click', (event) => {
+      if (event.target === imagePreview) closeImagePreview();
+    });
+    document.querySelector('#image-preview-close').addEventListener('click', closeImagePreview);
     elements.log.textContent = data.output || '';
     seekTo(frames[0]?.offsetMs || 0, false);
   </script>
@@ -413,6 +688,7 @@ export async function createAppiumReplayReport(input: {
   startedAt: Date;
   completedAt: Date;
   frames?: AppiumReplayFrame[];
+  visualChecks?: AppiumReplayVisualCheck[];
 }) {
   const configuredOutputPath = loadConfig().runtime.reportOutputPath.trim();
   const outputDir = appDataPath(configuredOutputPath || 'output');
@@ -433,6 +709,9 @@ export async function createAppiumReplayReport(input: {
   const outputLines = persistedOutput.split(/\r?\n/);
   const durationMs = input.completedAt.getTime() - input.startedAt.getTime();
   const resultText = input.stopped ? '已终止' : input.success ? '成功' : '失败';
+  const visualChecks = input.visualChecks || [];
+  const visualCheckByStepId = new Map(visualChecks.map((check) => [check.nodeId, check]));
+  const visualFailureCount = visualChecks.filter((check) => check.status === 'failed').length;
   const html = createReplayHtml({
     script: input.script,
     deviceId: input.deviceId,
@@ -441,6 +720,7 @@ export async function createAppiumReplayReport(input: {
     startedAt: input.startedAt,
     completedAt: input.completedAt,
     frames: input.frames || [],
+    visualChecks,
     output: persistedOutput,
   });
   const markdown = [
@@ -459,11 +739,12 @@ export async function createAppiumReplayReport(input: {
     `| 执行结果 | **${resultText}** |`,
     `| 节点数量 | ${input.script.steps.length} |`,
     `| 截图帧数 | ${(input.frames || []).length} |`,
+    `| 视觉检测未达预期 | ${visualFailureCount} |`,
     `| 截图回放 | ${markdownValue(htmlReportPath)} |`,
     '',
     '## 节点明细',
     '',
-    ...input.script.steps.map((step, index) => stepSection(step, index, outputLines)),
+    ...input.script.steps.map((step, index) => stepSection(step, index, outputLines, visualCheckByStepId.get(step.id))),
     '## 完整回放日志',
     '',
     '```text',

package/server/appium-recorder/repository.ts

@@ -6,6 +6,7 @@ import {
   sqlNullableString,
   sqlString,
 } from '../storage/sqlite';
+import { normalizeLegacyNestedConditionBranches } from '../../src/appium-recorder/flow-normalize';
 
 export type AppiumRecordedStepRecord = {
   id: string;
@@ -18,6 +19,10 @@ export type AppiumRecordedStepRecord = {
     | 'backIfExists'
     | 'waitFor'
     | 'assertExists'
+    | 'checkboxState'
+    | 'radioButtonState'
+    | 'aiRecognition'
+    | 'textClick'
     | 'key'
     | 'waitActivity'
     | 'delay'
@@ -31,7 +36,10 @@ export type AppiumRecordedStepRecord = {
     | 'assertText'
     | 'longPress'
     | 'pinch'
-    | 'runScript';
+    | 'runScript'
+    | 'noop'
+    | 'log'
+    | 'visualChange';
   label: string;
   note?: string;
   selector?: {
@@ -71,9 +79,10 @@ export type AppiumRecordedStepRecord = {
     source?: 'node' | 'ancestor' | 'fallback';
   };
   value?: string;
-  optional?: boolean;
+  logPrefix?: string;
   keyCode?: number;
   timeoutMs?: number;
+  longPressMode?: 'element' | 'coordinates';
   flow?: {
     nodeKind?: 'action' | 'condition' | 'assertion';
     yesTargetId?: string;
@@ -110,6 +119,24 @@ export type AppiumRecordedStepRecord = {
     centerY: number;
     percent: number;
   };
+  visualChange?: {
+    mode: 'selectedElement' | 'region';
+    region: {
+      x: number;
+      y: number;
+      width: number;
+      height: number;
+    };
+    role?: 'start' | 'end';
+    pairId?: string;
+    pairLabel?: string;
+    startStepId?: string;
+    endStepId?: string;
+    durationMs: number;
+    intervalMs: number;
+    changeRatioThreshold: number;
+    pixelmatchThreshold: number;
+  };
   snapshot?: {
     text: string;
     resourceId: string;
@@ -245,7 +272,7 @@ function normalizeScriptActivity(
 }
 
 function rowToRecord(row: AppiumRecordedScriptRow): AppiumRecordedScriptRecord {
-  const steps = parseStepList(row.flow_json);
+  const steps = normalizeLegacyNestedConditionBranches(parseStepList(row.flow_json));
   return {
     id: row.id,
     name: row.name,
@@ -307,7 +334,7 @@ export function saveAppiumRecordedScript(input: {
   const id = input.id || createId('appium_script');
   const name = input.name.trim();
   const appPackage = input.appPackage.trim();
-  const steps = input.steps || [];
+  const steps = normalizeLegacyNestedConditionBranches(input.steps || []);
   const appActivity = normalizeScriptActivity(appPackage, input.appActivity, steps);
 
   if (!name) throw new Error('脚本名称不能为空');