android-midscene-automation 0.1.34 → 0.1.35

package/src/appium-recorder/action-descriptions.ts

@@ -0,0 +1,46 @@
+import type { InsertAction } from './flow-graph';
+
+// 普通画布、嵌套分支及流程总览共用说明，新增操作时必须补齐。
+export const actionDescriptions: Record<InsertAction, string> = {
+  imageCheck: '使用 OpenCV 在本地判断指定区域，不调用 AI。适合固定图标、图片勾选状态、黑屏、颜色及多帧变化；不适合业务语义或任意文字识别，不能仅凭外观证明按钮可用或视频卡死。原生属性可读取时优先使用属性判断，证据不足报告无法判定。',
+  tap: '记录点击当前选中的组件，回放时重新定位后点击。',
+  input: '向当前选中的输入组件写入指定文字，支持 {{变量名}} 引用。',
+  extractVariable: '读取组件文字或属性，保存到当前脚本变量供后续节点引用。',
+  clearInput: '清空当前选中输入组件的内容。',
+  coordinateTap: '点击设备屏幕上的指定 X、Y 坐标。节点中可修改坐标，页面位置变化后需重新确认。',
+  longPress: '长按指定元素或屏幕坐标，可设置按住时长，默认按元素定位。',
+  keyBack: '执行 Android 系统返回操作。',
+  keyHome: '按 Home 键返回设备桌面，不等同于关闭应用。',
+  keyRecent: '打开 Android 最近任务列表。',
+  keyPower: '发送电源键操作，实际锁屏或唤醒行为由设备当前状态决定。',
+  swipe: '按指定起点、终点和时长滑动屏幕。',
+  pinch: '执行双指放大或缩小手势，需要当前页面支持缩放。',
+  launchApp: '启动指定应用，可放在流程中途或分支中执行。',
+  openGallery: '打开设备相册应用，不自动选择照片或视频。',
+  endFlow: '立即结束当前回放流程，后续节点不再执行。',
+  loop: '重复执行循环体，支持固定次数或条件退出，必须设置最大次数。',
+  breakLoop: '退出指定的当前或外层循环，继续执行该循环的结束路径。',
+  clearAppData: '清除目标应用数据并重置应用状态，可能删除登录信息和本地设置，仅允许在流程开始处添加。',
+  popupCondition: '判断目标组件是否存在，可进一步配置指定文本及精确或模糊匹配，按结果进入是或否分支。',
+  checkboxState: '读取原生 Checkbox 的 checked 状态，按 true/false 分支执行。',
+  radioButtonState: '读取原生 RadioButton 的 checked 状态，按 true/false 分支执行。',
+  checkedState: '读取 Checkbox、RadioButton 或 Switch 的真实勾选状态，按 true/false 分支执行。不支持仅用图片表示状态的普通 ImageView。',
+  aiRecognition: '用配置的模型判断当前画面，返回 true/false。适合语义、提示含义和复杂画面判断；可直接读取的组件属性优先使用原生判断。需要配置 AI 节点模型。',
+  textClick: '在组件树中按指定文字精确或模糊匹配并点击，进入匹配到文字或未匹配到文字分支。不识别图片或自绘画面中的文字。',
+  tapIfExists: '找到目标组件时点击，未找到则跳过并继续后续流程。',
+  inputIfExists: '找到目标输入组件时写入文字，未找到则跳过。支持 {{变量名}} 引用。',
+  clearIfExists: '找到目标输入组件时清空内容，未找到则跳过。',
+  backIfExists: '目标组件出现时执行系统返回，未出现则跳过。',
+  waitFor: '等待目标组件出现，超过配置的等待时间仍未出现则失败。',
+  assertExists: '校验目标组件是否存在，不满足时记录执行失败。旧脚本兼容操作。',
+  assertText: '校验组件文字是否满足预期，不满足时记录执行失败。旧脚本兼容操作。',
+  waitDisappear: '等待目标组件消失，超时仍存在则失败。',
+  waitActivity: '等待设备切换到指定的 Activity，适合确认页面跳转是否完成。',
+  delay: '暂停指定的毫秒数后继续执行，不判断页面是否已经准备完成。',
+  runScript: '执行连接的子脚本，支持显式传入参数并将返回变量映射到当前脚本。',
+  noop: '不执行设备操作，作为流程占位节点。',
+  log: '输出自定义内容和日志关键字，默认前缀为 stageLog，支持 {{变量名}} 引用。',
+  visualChangeStart: '截取指定组件或区域作为基准，与对应结束节点的截图比较。未添加对应结束节点时不比较。',
+  visualChangeEnd: '与同一可达路径上对应的开始截图比较，报告变化结果；多组检测可选择对应的开始节点。',
+  visualChange: '比较指定区域的截图变化，不直接判断业务状态或图片单选框是否勾选。',
+};

package/src/appium-recorder/api.ts

@@ -2,6 +2,11 @@ import { APP_BASE } from '../api';
 import type { AppiumRecordedScript, AppiumRecordedStep } from './types';
 import type { AiRecognitionResult } from './ai-recognition';
 import type { TestVariable } from './variables';
+import type { AppiumVisualChangeRegion } from './types';
+
+export function captureImageCheckRegion(deviceId: string, region: AppiumVisualChangeRegion, screenWidth: number, screenHeight: number) {
+  return postJson<{ base64: string; screenWidth: number; screenHeight: number }>(`${APP_BASE}/api/appium-recorder/image-check/capture`, { deviceId, region, screenWidth, screenHeight });
+}
 
 // 队列跨组件挂载保留，切换脚本或清空草稿时仍按编辑顺序写入。
 const variableWrites = new Map<string, Promise<unknown>>();

package/src/appium-recorder/components/ComponentInspector.vue

@@ -12,7 +12,13 @@ defineEmits<{ refresh: []; select: [node: AppiumNode] }>();
     <template #header><div class="panel-header"><span>App 组件树</span><el-tooltip content="刷新组件树" placement="top" :show-after="200"><el-button class="recorder-panel-tool" :icon="Refresh" size="small" aria-label="刷新组件树" :loading="loading" :disabled="disabled" @click="$emit('refresh')" /></el-tooltip></div></template>
     <ComponentTree :tree="tree" :selected-id="node?.id || ''" @select="$emit('select', $event)" />
     <NodeDetail :node="node" :current-activity="activity" :loading="recording" />
-    <div class="component-inspector__activity"><span>Activity</span><code :title="activity">{{ activity || '-' }}</code></div>
+    <div class="component-inspector__activity">
+      <span>Activity</span>
+      <el-tooltip :content="activity" :disabled="!activity" placement="top" effect="dark" :show-after="200"
+        :popper-style="{ maxWidth: 'min(480px, calc(100vw - 24px))', overflowWrap: 'anywhere', fontSize: '12px' }">
+        <code :tabindex="activity ? 0 : undefined">{{ activity || '-' }}</code>
+      </el-tooltip>
+    </div>
   </el-card>
 </template>
 
@@ -22,5 +28,6 @@ defineEmits<{ refresh: []; select: [node: AppiumNode] }>();
 .component-inspector :deep(.appium-node-summary) { flex: none; }
 .panel-header { font-size: 14px; gap: 4px; }
 .component-inspector__activity { flex: none; display: flex; min-width: 0; gap: 6px; padding-top: 8px; border-top: 1px solid #e4e7ed; font-size: 12px; color: #606266; }
-.component-inspector__activity code { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.component-inspector__activity > span { flex-shrink: 0; }
+.component-inspector__activity code { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 </style>

package/src/appium-recorder/components/FlowActionMenu.vue

@@ -2,6 +2,7 @@
 import { nextTick, shallowRef } from 'vue';
 import type { MenuInstance, PopoverInstance } from 'element-plus';
 import { PASTE_COMMAND, type FlowActionGroup, type InsertAction } from '../flow-graph';
+import { actionDescriptions } from '../action-descriptions';
 
 const props = defineProps<{
   groups: FlowActionGroup[];
@@ -118,14 +119,25 @@ function selectAction(value: string) {
             @click="openGroupOnClick($event, group.title)"
           >
             <template #title>{{ group.title }}</template>
-            <el-menu-item
+            <el-tooltip
               v-for="action in group.actions"
               :key="action.type"
-              :index="action.type"
-              :disabled="isActionDisabled(action.type)"
+              :content="actionDescriptions[action.type]"
+              placement="right"
+              effect="dark"
+              :show-after="350"
+              :hide-after="0"
+              :enterable="false"
+              :popper-options="{ modifiers: [{ name: 'preventOverflow', options: { altAxis: true, padding: 8 } }] }"
+              popper-class="appium-action-description"
             >
-              {{ action.label }}
-            </el-menu-item>
+              <el-menu-item
+                :index="action.type"
+                :disabled="isActionDisabled(action.type)"
+              >
+                {{ action.label }}
+              </el-menu-item>
+            </el-tooltip>
           </el-sub-menu>
           <el-menu-item v-if="clipboardCount" :index="PASTE_COMMAND" class="appium-action-paste">
             粘贴 {{ clipboardCount }} 个节点
@@ -137,6 +149,15 @@ function selectAction(value: string) {
 </template>
 
 <style>
+.appium-action-description.el-popper {
+  max-width: min(300px, calc(100vw - 32px));
+  padding: 8px 10px;
+  font-size: 12px;
+  line-height: 1.6;
+  overflow-wrap: anywhere;
+  pointer-events: none;
+}
+
 .appium-action-menu-trigger {
   display: inline-flex;
 }

package/src/appium-recorder/components/FlowCanvas.vue

@@ -47,9 +47,9 @@ const emit = defineEmits<{
   nodeClick: [index: number];
   merge: [index: number];
   copy: [indexes: number[]];
-  paste: [index: number, branch?: FlowBranch];
+  paste: [index: number, branch?: FlowBranch, beforeStepId?: string];
   remove: [index: number];
-  insertAction: [index: number, action: InsertAction];
+  insertAction: [index: number, action: InsertAction, beforeStepId?: string];
   insertBranchAction: [index: number, branch: FlowBranch, action: InsertAction];
   editInput: [index: number];
   previewLinkedScript: [index: number];
@@ -180,16 +180,17 @@ function handleInsert(payload: {
   action: InsertAction | typeof PASTE_COMMAND;
   branch?: FlowBranch;
   conditionIndex?: number;
+  beforeStepId?: string;
 }) {
   if (payload.action === PASTE_COMMAND) {
-    emit('paste', payload.afterIndex, payload.branch);
+    emit('paste', payload.afterIndex, payload.branch, payload.beforeStepId);
     return;
   }
   if (payload.branch && payload.conditionIndex !== undefined) {
     emit('insertBranchAction', payload.afterIndex, payload.branch, payload.action);
     return;
   }
-  emit('insertAction', payload.afterIndex, payload.action);
+  emit('insertAction', payload.afterIndex, payload.action, payload.beforeStepId);
 }
 </script>
 

package/src/appium-recorder/components/FlowNodeCard.vue

@@ -29,7 +29,7 @@ const emit = defineEmits<{
   editInput: [index: number];
   previewLinkedScript: [index: number];
   execute: [index: number];
-  insert: [payload: { afterIndex: number; action: InsertAction | typeof PASTE_COMMAND; branch?: FlowBranch; conditionIndex?: number }];
+  insert: [payload: { afterIndex: number; action: InsertAction | typeof PASTE_COMMAND; branch?: FlowBranch; conditionIndex?: number; beforeStepId?: string }];
   updateStep: [payload: { index: number; step: AppiumRecordedStep }];
   resize: [payload: { id: string; height: number }];
 }>();
@@ -39,6 +39,7 @@ let resizeObserver: ResizeObserver | null = null;
 
 const insertTitle = computed(() => {
   if (props.data.kind !== 'insert') return '';
+  if (props.data.beforeStepId) return '在合流后插入操作';
   if (props.data.branch) return `在“${props.data.branchLabel || (props.data.branch === 'yes' ? '是' : '否')}”分支插入操作`;
   return props.data.afterIndex < 0 ? '在开始后插入操作' : '插入操作';
 });
@@ -47,6 +48,7 @@ function emitInsert(command: string | number | object) {
   if (props.readonly || props.data.kind !== 'insert') return;
   emit('insert', {
     afterIndex: props.data.afterIndex,
+    beforeStepId: props.data.beforeStepId,
     action: command === PASTE_COMMAND ? PASTE_COMMAND : command as InsertAction,
     branch: props.data.branch,
     conditionIndex: props.data.conditionIndex,
@@ -213,14 +215,14 @@ watch(() => props.data, () => {
           @click="emit('execute', data.index)"
         />
         </span></el-tooltip>
-        <el-tooltip v-if="data.canEditInput" content="修改输入内容：编辑此节点要输入的文字" placement="top" :show-after="200">
+        <el-tooltip v-if="data.canEditInput" :content="data.step.type === 'imageCheck' ? '修改图像判断配置' : '修改输入内容：编辑此节点要输入的文字'" placement="top" :show-after="200">
         <span class="appium-node-action-tooltip">
         <el-button
           text
           size="small"
           :icon="Edit"
           :disabled="data.disabled"
-          title="修改输入内容"
+          :title="data.step.type === 'imageCheck' ? '修改图像判断配置' : '修改输入内容'"
           @click="emit('editInput', data.index)"
         />
         </span></el-tooltip>

package/src/appium-recorder/components/ImageCheckDialog.vue

@@ -0,0 +1,143 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { ElMessage } from 'element-plus';
+import { Aim, Camera, Upload, QuestionFilled } from '@element-plus/icons-vue';
+import { IMAGE_CHECK_MODES, validateImageCheck, imageTemplateSize, imageTemplateRegionIssue, expandedImageTemplateRegion, type ImageCheckConfig } from '../image-check';
+import { captureImageCheckRegion } from '../api';
+
+const props = defineProps<{ config: ImageCheckConfig; deviceId: string; hasElement: boolean; editing: boolean; picking: boolean }>();
+const emit = defineEmits<{ update: [config: ImageCheckConfig]; close: []; confirm: []; pick: []; useElement: [] }>();
+const busy = ref(false);
+const regionIssue = computed(() => imageTemplateRegionIssue(props.config));
+const expandedRegion = computed(() => expandedImageTemplateRegion(props.config));
+const fileInput = ref<HTMLInputElement>();
+const uploadSlot = ref<'template' | 'negativeTemplate'>('template');
+const slots = computed(() => props.config.mode === 'state'
+  ? [{ key: 'template' as const, label: '选中模板' }, { key: 'negativeTemplate' as const, label: '未选中模板' }]
+  : props.config.mode === 'template' ? [{ key: 'template' as const, label: '模板' }] : []);
+const numericFields = computed(() => [
+  ...(['template', 'state'].includes(props.config.mode) ? [{ key: 'threshold' as const, label: '匹配得分阈值', min: 0.01, max: 1, step: 0.01 }] : []),
+  ...(props.config.mode === 'state' ? [{ key: 'minScoreGap' as const, label: '两种状态最小得分差', min: 0.001, max: 1, step: 0.01 }] : []),
+  ...(['black', 'color', 'change'].includes(props.config.mode) ? [
+    { key: 'tolerance' as const, label: props.config.mode === 'black' ? '暗色亮度阈值 (0–255)' : 'RGB 通道容差 (0–255)', min: 0, max: 255, step: 1 },
+    { key: 'ratio' as const, label: props.config.mode === 'change' ? '变化像素比例 %' : '目标像素占比 %', min: 0.01, max: 100, step: 1 },
+  ] : []),
+  ...(props.config.mode !== 'state' ? [
+    { key: 'durationMs' as const, label: '最长观察时长 ms', min: 0, max: 60000, step: 1000 },
+    { key: 'intervalMs' as const, label: '采样间隔 ms', min: 200, max: 10000, step: 200 },
+    ...(props.config.mode !== 'change' ? [{ key: 'consecutive' as const, label: '连续满足帧数', min: 1, max: 100, step: 1 }] : []),
+  ] : []),
+]);
+function patch(value: Partial<ImageCheckConfig>) { emit('update', { ...props.config, ...value }); }
+function confirm() {
+  try { validateImageCheck(props.config); emit('confirm'); }
+  catch (error) { ElMessage.warning((error as Error).message); }
+}
+async function capture(key: 'template' | 'negativeTemplate') {
+  busy.value = true;
+  const regionKey = JSON.stringify(props.config.region);
+  const deviceId = props.deviceId;
+  try {
+    const result = await captureImageCheckRegion(props.deviceId, props.config.region, props.config.screenWidth, props.config.screenHeight);
+    if (deviceId !== props.deviceId || regionKey !== JSON.stringify(props.config.region)) throw new Error('采集期间目标区域已变化，请重新采集');
+    patch({ [key]: result.base64, screenWidth: result.screenWidth, screenHeight: result.screenHeight });
+  } catch (error) { ElMessage.error((error as Error).message); }
+  finally { busy.value = false; }
+}
+function chooseFile(key: 'template' | 'negativeTemplate') { uploadSlot.value = key; fileInput.value?.click(); }
+async function upload(event: Event) {
+  const input = event.target as HTMLInputElement;
+  const file = input.files?.[0];
+  input.value = '';
+  if (!file) return;
+  try {
+    if (file.size > 3 * 1024 * 1024 || file.type !== 'image/png') throw new Error('请选择小于 3MB 的 PNG 模板');
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    if (Array.from(bytes.slice(0, 8)).join(',') !== '137,80,78,71,13,10,26,10') throw new Error('模板不是有效 PNG');
+    const reader = new FileReader();
+    reader.onload = () => patch({ [uploadSlot.value]: String(reader.result).split(',')[1] });
+    reader.readAsDataURL(file);
+  } catch (error) { ElMessage.error((error as Error).message); }
+}
+</script>
+
+<template>
+  <el-dialog :model-value="true" :title="editing ? '修改图像判断' : '添加图像判断'" width="520px" top="5vh"
+    class="image-check-dialog" append-to-body draggable :modal="false" modal-penetrable
+    :close-on-click-modal="false" :close-on-press-escape="false" :show-close="!busy" @close="emit('close')">
+    <el-form label-position="top" size="small" :disabled="busy">
+      <el-form-item label="检测模式">
+        <el-select :model-value="config.mode" @update:model-value="patch({ mode: $event, consecutive: $event === 'black' ? 3 : 1, ratio: $event === 'change' ? 2 : 95 })">
+          <el-option v-for="(label, key) in IMAGE_CHECK_MODES" :key="key" :label="label" :value="key" />
+        </el-select>
+        <el-tooltip content="适合固定图标、图片勾选、黑屏、颜色和画面变化。不识别任意文字或业务语义，不能仅凭外观证明按钮可用或视频卡死。证据不足时报告无法判定。" :show-after="200">
+          <el-icon class="image-check-help"><QuestionFilled /></el-icon>
+        </el-tooltip>
+      </el-form-item>
+      <el-form-item label="检测目标">
+        <el-radio-group :model-value="config.target" @update:model-value="$event === 'element' ? emit('useElement') : patch({ target: 'region' })">
+          <el-radio-button value="element" :disabled="!hasElement && config.target !== 'element'">当前选中元素</el-radio-button>
+          <el-radio-button value="region">框选区域</el-radio-button>
+        </el-radio-group>
+        <el-tooltip content="组件按实时定位结果截图，同名组件必须限定父级；框选区域只在采集时相同屏幕尺寸下执行，尺寸变化需重新框选。模板按原始尺寸匹配，不自动缩放。">
+          <el-icon class="image-check-help"><QuestionFilled /></el-icon>
+        </el-tooltip>
+      </el-form-item>
+      <el-form-item v-if="config.target === 'region'" label="设备预览区域">
+        <el-button :icon="Aim" @click="emit('pick')">{{ picking ? '正在框选' : '框选 / 拖动区域' }}</el-button>
+      </el-form-item>
+      <div class="image-check-grid">
+        <el-form-item v-for="(label, key) in { x: 'X', y: 'Y', width: '宽度', height: '高度' }" :key="key" :label="label">
+          <el-input-number :model-value="config.region[key]" :disabled="config.target === 'element'" :min="key === 'x' || key === 'y' ? 0 : 1" :max="16000" :precision="0" controls-position="right"
+            @update:model-value="$event !== undefined && patch({ region: { ...config.region, [key]: $event } })" />
+        </el-form-item>
+      </div>
+      <div v-if="slots.length" class="image-check-grid">
+        <div v-for="slot in slots" :key="slot.key" class="image-check-template">
+          <span>{{ slot.label }}</span>
+          <small v-if="imageTemplateSize(config[slot.key])" class="image-check-size">{{ imageTemplateSize(config[slot.key])!.width }} × {{ imageTemplateSize(config[slot.key])!.height }} px</small>
+          <el-image v-if="config[slot.key]" :src="'data:image/png;base64,' + config[slot.key]" :preview-src-list="['data:image/png;base64,' + config[slot.key]]" fit="contain" preview-teleported />
+          <div v-else class="image-check-empty">未采集</div>
+          <div>
+            <el-tooltip content="截取当前检测区域作为模板，可再次采集替换"><el-button :icon="Camera" :disabled="!deviceId" :loading="busy" aria-label="采集模板" @click="capture(slot.key)" /></el-tooltip>
+            <el-tooltip content="上传 PNG 替换模板"><el-button :icon="Upload" aria-label="上传模板" @click="chooseFile(slot.key)" /></el-tooltip>
+          </div>
+        </div>
+      </div>
+      <input ref="fileInput" type="file" accept="image/png" hidden @change="upload" />
+      <el-alert v-if="regionIssue" :title="regionIssue" type="warning" show-icon :closable="false" class="image-check-region-warning">
+        <el-button v-if="expandedRegion" size="small" @click="patch({ region: expandedRegion })">扩大检测区域</el-button>
+      </el-alert>
+      <el-form-item v-if="config.mode === 'template' || config.mode === 'change'" label="判断条件">
+        <el-radio-group :model-value="config.expectation" @update:model-value="patch({ expectation: $event as 'present' | 'absent' })">
+          <el-radio-button value="present">{{ config.mode === 'template' ? '图片存在' : '画面有变化' }}</el-radio-button>
+          <el-radio-button value="absent">{{ config.mode === 'template' ? '图片不存在' : '持续无明显变化' }}</el-radio-button>
+        </el-radio-group>
+      </el-form-item>
+      <el-form-item v-if="config.mode === 'color'" label="目标颜色 #RRGGBB">
+        <el-color-picker :model-value="config.color" @update:model-value="$event && patch({ color: $event })" />
+        <el-input :model-value="config.color" maxlength="7" @update:model-value="patch({ color: $event })" />
+      </el-form-item>
+      <div class="image-check-grid">
+        <el-form-item v-for="field in numericFields" :key="field.key" :label="field.label">
+          <el-input-number :model-value="config[field.key]" :min="field.min" :max="field.max" :step="field.step" controls-position="right" @update:model-value="$event !== undefined && patch({ [field.key]: $event })" />
+        </el-form-item>
+      </div>
+    </el-form>
+    <template #footer><el-button :disabled="busy" @click="emit('close')">取消</el-button><el-button type="primary" :disabled="busy" @click="confirm">{{ editing ? '保存' : '添加' }}</el-button></template>
+  </el-dialog>
+</template>
+
+<style>
+.image-check-dialog { max-width: calc(100vw - 24px); }
+.image-check-dialog .el-dialog__body { max-height: 70vh; overflow-y: auto; }
+.image-check-dialog .el-select { flex: 1; }
+.image-check-dialog .el-input-number { width: 100%; }
+.image-check-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 12px; }
+.image-check-help { margin-left: 8px; color: #606266; }
+.image-check-template { display: grid; gap: 6px; margin-bottom: 16px; min-width: 0; }
+.image-check-size { color: #606266; font-size: 12px; }
+.image-check-region-warning { margin-bottom: 16px; }
+.image-check-template .el-image, .image-check-empty { height: 96px; width: 100%; background: #eff5f3; border: 1px solid #d5dfdb; border-radius: 4px; }
+.image-check-empty { display: grid; place-items: center; color: #606266; }
+</style>

package/src/appium-recorder/components/NestedConditionBranches.vue

@@ -33,6 +33,7 @@ type InsertAction =
   | 'checkedState'
   | 'radioButtonState'
   | 'aiRecognition'
+  | 'imageCheck'
   | 'textClick'
   | 'tapIfExists'
   | 'inputIfExists'
@@ -117,6 +118,7 @@ const actionGroups: Array<{ title: string; actions: Array<{ type: InsertAction;
       { type: 'delay', label: '添加延时' },
       { type: 'popupCondition', label: '判断存在' },
       { type: 'aiRecognition', label: 'AI 识别' },
+      { type: 'imageCheck', label: '图像判断' },
       { type: 'tapIfExists', label: '存在则点击' },
       { type: 'inputIfExists', label: '存在则输入' },
       { type: 'clearIfExists', label: '存在则清空' },
@@ -162,6 +164,7 @@ function typeLabel(step: AppiumRecordedStep) {
     checkedState: '判断勾选',
     radioButtonState: 'RadioButton 状态',
     aiRecognition: 'AI 识别',
+    imageCheck: '图像判断',
     openGallery: '启动相册',
     textClick: '文字点击',
   };
@@ -169,6 +172,7 @@ function typeLabel(step: AppiumRecordedStep) {
 }
 
 function stepMeta(step: AppiumRecordedStep) {
+  if (step.type === 'imageCheck') return flowStepMeta(step);
   if (step.type === 'delay') return `${step.timeoutMs || 1000}ms`;
   if (step.type === 'input' || step.type === 'inputIfExists') return `输入内容：${step.value || '空'}`;
   if (step.type === 'longPress') return flowStepMeta(step);
@@ -336,14 +340,14 @@ function branchSplitPath() {
                   @click="$emit('copy', [item.index])"
                 />
                 </span></el-tooltip>
-                <el-tooltip v-if="item.step.type === 'input' || item.step.type === 'inputIfExists'" content="修改输入内容：编辑此节点要输入的文字" placement="top" :show-after="200">
+                <el-tooltip v-if="item.step.type === 'input' || item.step.type === 'inputIfExists' || item.step.type === 'imageCheck'" :content="item.step.type === 'imageCheck' ? '修改图像判断配置' : '修改输入内容：编辑此节点要输入的文字'" placement="top" :show-after="200">
                 <span style="display: inline-flex">
                 <el-button
                   text
                   size="small"
                   :icon="Edit"
                   :disabled="disabled"
-                  title="修改输入内容"
+                  :title="item.step.type === 'imageCheck' ? '修改图像判断配置' : '修改输入内容'"
                   @click="$emit('editInput', item.index)"
                 />
                 </span></el-tooltip>

package/src/appium-recorder/components/RecordedSteps.vue

@@ -26,9 +26,9 @@ const props = defineProps<{
 const emit = defineEmits<{
   remove: [index: number];
   copy: [indexes: number[]];
-  paste: [index: number, branch?: FlowBranch];
+  paste: [index: number, branch?: FlowBranch, beforeStepId?: string];
   addDelay: [index?: number];
-  insertAction: [index: number, action: InsertAction];
+  insertAction: [index: number, action: InsertAction, beforeStepId?: string];
   insertBranchAction: [index: number, branch: FlowBranch, action: InsertAction];
   editInput: [index: number];
   previewLinkedScript: [index: number];
@@ -89,6 +89,7 @@ const insertActionGroups: FlowActionGroup[] = [
       { type: 'delay', label: '添加延时' },
       { type: 'popupCondition', label: '判断存在' },
       { type: 'aiRecognition', label: 'AI 识别' },
+      { type: 'imageCheck', label: '图像判断' },
       { type: 'tapIfExists', label: '存在则点击' },
       { type: 'inputIfExists', label: '存在则输入' },
       { type: 'clearIfExists', label: '存在则清空' },
@@ -330,9 +331,9 @@ function updateStep(index: number, step: AppiumRecordedStep) {
       :is-copy-selected="isCopySelected"
       @node-click="handleNodeClick"
       @copy="(indexes) => emit('copy', indexes)"
-      @paste="(index, branch) => emit('paste', index, branch)"
+      @paste="(index, branch, beforeStepId) => emit('paste', index, branch, beforeStepId)"
       @remove="(index) => emit('remove', index)"
-      @insert-action="(index, action) => emit('insertAction', index, action)"
+      @insert-action="(index, action, beforeStepId) => emit('insertAction', index, action, beforeStepId)"
       @insert-branch-action="(index, branch, action) => emit('insertBranchAction', index, branch, action)"
       @edit-input="(index) => emit('editInput', index)"
       @preview-linked-script="(index) => emit('previewLinkedScript', index)"
@@ -406,9 +407,9 @@ function updateStep(index: number, step: AppiumRecordedStep) {
         :is-copy-selected="isCopySelected"
         @node-click="handleNodeClick"
         @copy="(indexes) => emit('copy', indexes)"
-        @paste="(index, branch) => emit('paste', index, branch)"
+        @paste="(index, branch, beforeStepId) => emit('paste', index, branch, beforeStepId)"
         @remove="(index) => emit('remove', index)"
-        @insert-action="(index, action) => emit('insertAction', index, action)"
+        @insert-action="(index, action, beforeStepId) => emit('insertAction', index, action, beforeStepId)"
         @insert-branch-action="(index, branch, action) => emit('insertBranchAction', index, branch, action)"
         @edit-input="(index) => emit('editInput', index)"
         @preview-linked-script="(index) => emit('previewLinkedScript', index)"

package/src/appium-recorder/flow-copy.ts

@@ -1,4 +1,5 @@
 import type { AppiumRecordedStep } from './types';
+import { insertBeforeSharedStep } from './flow-insert';
 
 export type FlowBranch = 'yes' | 'no';
 
@@ -10,6 +11,7 @@ export type FlowClipboard = {
 type PasteTarget = {
   afterIndex: number;
   branch?: FlowBranch;
+  beforeStepId?: string;
 };
 
 const targetKeys = [
@@ -226,6 +228,8 @@ export function pasteFlowClipboard(
   const lastRoot = copiedRoots[copiedRoots.length - 1];
   if (!firstRoot || !lastRoot) throw new Error('复制节点数据无效');
 
+  if (target.beforeStepId) return insertBeforeSharedStep(steps, target.beforeStepId, copies, copiedRoots.map(step => step.id));
+
   const nextSteps = [...steps];
   let insertAfterIndex = target.afterIndex;
   let continuationId = '';

package/src/appium-recorder/flow-graph.ts

@@ -34,6 +34,7 @@ export type InsertAction =
   | 'checkedState'
   | 'radioButtonState'
   | 'aiRecognition'
+  | 'imageCheck'
   | 'textClick'
   | 'tapIfExists'
   | 'inputIfExists'
@@ -107,6 +108,7 @@ export type FlowGraphNodeData =
       kind: 'insert';
       actionGroups: FlowActionGroup[];
       afterIndex: number;
+      beforeStepId?: string;
       branch?: FlowBranch;
       branchLabel?: string;
       conditionIndex?: number;
@@ -260,7 +262,8 @@ function branchConnectionTargetId(items: StepItem[], condition: AppiumRecordedSt
   const targetId = branch === 'yes' ? condition.flow?.yesTargetId : condition.flow?.noTargetId;
   if (!targetId) return condition.type === 'loop' && branch === 'yes' ? '' : continuationTargetId(items, condition);
   const target = items.find(({ step }) => step.id === targetId)?.step;
-  return target && target.flow?.parentConditionId === condition.flow?.parentConditionId ? target.id : '';
+  // 合流目标可以属于祖先作用域，不能用同父节点限制过滤合法的显式连接。
+  return target?.id || '';
 }
 
 function estimateTextLines(text: string | undefined, charsPerLine: number) {
@@ -378,8 +381,9 @@ export function buildFlowGraph(
     afterIndex: number,
     branch?: FlowBranch,
     condition?: StepItem,
+    beforeStepId?: string,
   ) => {
-    const id = insertNodeId(afterIndex, branch, condition?.step.id);
+    const id = beforeStepId ? `insert:before:${beforeStepId}` : insertNodeId(afterIndex, branch, condition?.step.id);
     const isStartInsert = afterIndex < 0 && !branch;
     addNode({
       id,
@@ -398,6 +402,7 @@ export function buildFlowGraph(
           ? options.startActionGroups
           : withLaunchAppAction(options.mainActionGroups),
         afterIndex,
+        beforeStepId,
         branch,
         branchLabel: branch && condition ? flowBranchLabel(condition.step, branch) : undefined,
         conditionIndex: condition?.index,
@@ -453,7 +458,7 @@ export function buildFlowGraph(
         canCopy: item.step.type !== 'launchApp'
           && item.step.type !== 'clearAppData'
           && item.step.visualChange?.role !== 'end',
-        canEditInput: item.step.type === 'input' || item.step.type === 'inputIfExists',
+        canEditInput: item.step.type === 'input' || item.step.type === 'inputIfExists' || item.step.type === 'imageCheck',
         canExecute: item.step.type === 'launchApp' || item.step.type === 'clearAppData' || item.step.type === 'aiRecognition',
         missingAiModel: item.step.type === 'aiRecognition' && !options.aiRecognitionModelConfigured,
       },
@@ -585,6 +590,20 @@ export function buildFlowGraph(
     }
   });
 
+  // 汇入线先接公共插入点，再接原节点；分支内插入点仍保持独立。
+  const joins = new Map<string, string>();
+  items.forEach(({ step }) => {
+    const target = defaultKind(step) === 'condition' && stepById.get(continuationTargetId(items, step));
+    if (!target) return;
+    const targetId = nodeIdForStep(target.step);
+    const insertId = `insert:before:${target.step.id}`;
+    if (joins.has(insertId) || !links.some(link => link.target === targetId)) return;
+    addInsertNode(target.index - 1, undefined, undefined, target.step.id);
+    links.forEach(link => { if (link.target === targetId) link.target = insertId; });
+    addVisibleLink(insertId, targetId);
+    joins.set(insertId, nodeIdForStep(step));
+  });
+
   const selectedDescendantIds = collectDescendantIds(
     steps,
     options.selectedCopyIndexes.map((index) => steps[index]?.id).filter((id): id is string => Boolean(id)),
@@ -752,13 +771,6 @@ export function buildFlowGraph(
     (nodeOrder.get(a.source) || 0) - (nodeOrder.get(b.source) || 0)
   ));
   // 公共起点从两侧汇入，不能被最后一条分支连线拉到左列或右列。
-  const joins = new Map<string, string>();
-  items.forEach(({ step }) => {
-    const target = defaultKind(step) === 'condition' && stepById.get(continuationTargetId(items, step));
-    if (defaultKind(step) === 'condition' && target && !joins.has(nodeIdForStep(target.step))) {
-      joins.set(nodeIdForStep(target.step), nodeIdForStep(step));
-    }
-  });
   const alignVisibleChainGeometry = () => {
     orderedLinks.forEach((link) => {
       const source = nodeById.get(link.source);

package/src/appium-recorder/flow-insert.ts

@@ -0,0 +1,27 @@
+import type { AppiumRecordedStep } from './types';
+
+/** 在公共节点前插入，不改变原有分支归属，并重接所有显式汇入连接。 */
+export function insertBeforeSharedStep(steps: AppiumRecordedStep[], targetId: string, additions: AppiumRecordedStep[], rootIds: string[]) {
+  const index = steps.findIndex(step => step.id === targetId);
+  if (index < 0) throw new Error('合流节点已不存在，请重新选择插入位置');
+  const target = steps[index];
+  const roots = new Set(rootIds);
+  const first = rootIds[0];
+  const last = rootIds[rootIds.length - 1];
+  if (!first || !last) throw new Error('没有可插入的节点');
+  const inserted = additions.map(step => roots.has(step.id) ? {
+    ...step, flow: { ...step.flow, parentConditionId: target.flow?.parentConditionId, parentBranch: target.flow?.parentBranch,
+      ...(step.id === last ? { successTargetId: targetId } : {}) },
+  } : step);
+  const result = steps.map(step => {
+    if (!step.flow) return step;
+    const flow = { ...step.flow };
+    for (const key of ['yesTargetId', 'noTargetId', 'successTargetId'] as const) {
+      if (flow[key] === targetId) flow[key] = first;
+    }
+    return { ...step, flow };
+  });
+  // 无显式目标的默认返回会按同作用域顺序落到新节点。
+  result.splice(index, 0, ...inserted);
+  return result;
+}

package/src/appium-recorder/flow-labels.ts

@@ -4,9 +4,10 @@ import { visualChangeMeta } from './visual-change';
 import { longPressMode } from './long-press';
 import { isNativeStateCondition } from './native-control-state';
 import { DEFAULT_LOG_PREFIX } from './stage-log';
+import { imageCheckSummary } from './image-check';
 
 export function isBooleanCondition(step: Pick<AppiumRecordedStep, 'type'>) {
-  return isNativeStateCondition(step) || step.type === 'aiRecognition' || step.type === 'textClick';
+  return isNativeStateCondition(step) || step.type === 'aiRecognition' || step.type === 'textClick' || step.type === 'imageCheck';
 }
 
 export function defaultFlowKind(step: AppiumRecordedStep): FlowKind {
@@ -47,6 +48,7 @@ export function flowTypeLabel(step: AppiumRecordedStep) {
     checkedState: '判断勾选',
     radioButtonState: 'RadioButton 状态',
     aiRecognition: 'AI 识别',
+    imageCheck: '图像判断',
     textClick: '文字点击',
     assertText: '断言文本',
     key: '按键',
@@ -73,6 +75,7 @@ export function flowTypeLabel(step: AppiumRecordedStep) {
 }
 
 export function flowStepMeta(step: AppiumRecordedStep) {
+  if (step.type === 'imageCheck') return imageCheckSummary(step.imageCheck);
   if (step.type === 'extractVariable') return `${step.extractVariable?.attribute || 'text'} → ${step.extractVariable?.name || '未设置变量名'}`;
   if (step.type === 'loop') return `最多 ${step.loop?.maxIterations ?? '?'} 次 · ${step.loop?.exitWhen === 'exists' ? '元素出现时退出' : step.loop?.exitWhen === 'notExists' ? '元素消失时退出' : '固定次数'}${step.loop?.exitWhen !== 'never' ? ` ${step.selector?.value || ''}` : ''}`;
   if (step.type === 'breakLoop') return step.breakLoopTargetId ? '退出指定循环，继续循环结束后的流程' : '退出当前循环，继续循环结束后的流程';