android-midscene-automation 0.1.33 → 0.1.35

package/src/appium-recorder/AppiumPage.vue

@@ -10,6 +10,7 @@ import LoopSettings from './components/LoopSettings.vue';
 import BreakLoopSettings from './components/BreakLoopSettings.vue';
 import VisualChangeEndPicker from './components/VisualChangeEndPicker.vue';
 import PresetVariables from './components/PresetVariables.vue';
+import { insertBeforeSharedStep } from './flow-insert';
 import VariableExtractionSettings from './components/VariableExtractionSettings.vue';
 import ScriptParameterSettings from './components/ScriptParameterSettings.vue';
 import { validateVariables, validateExtraction, validateReturns, type TestVariable } from './variables';
@@ -39,6 +40,8 @@ import { DEFAULT_LOG_PREFIX, validateStageLog } from './stage-log';
 import RecordedSteps from './components/RecordedSteps.vue';
 import NewScriptDialog from './components/NewScriptDialog.vue';
 import VisualChangeDialog from './components/VisualChangeDialog.vue';
+import ImageCheckDialog from './components/ImageCheckDialog.vue';
+import { createImageCheckConfig, validateImageCheck, type ImageCheckConfig } from './image-check';
 import AiRecognitionTestDialog from './components/AiRecognitionTestDialog.vue';
 import { validateAiRecognitionPrompt } from './ai-recognition';
 import {
@@ -77,6 +80,7 @@ type LegacyFlow = NonNullable<AppiumRecordedStep['flow']> & { scope?: string };
 type SwipeGesture = NonNullable<AppiumRecordedStep['swipe']>;
 type SwipeForm = SwipeGesture & { direction: string };
 type BranchTarget = {
+  beforeStepId?: string;
   stepId: string;
   branch: BranchName;
   updateTarget?: boolean;
@@ -105,6 +109,7 @@ const insertableRecorderActions: RecorderAction[] = [
   'checkedState',
   'radioButtonState',
   'aiRecognition',
+  'imageCheck',
   'textClick',
   'runScript',
   'keyBack',
@@ -186,6 +191,11 @@ const linkedScriptPreviewVisible = shallowRef(false);
 const linkedScriptPreviewScriptId = shallowRef('');
 const linkedScriptPreviewResetToken = shallowRef(0);
 const visualChangeDialogVisible = shallowRef(false);
+const imageCheckDraft = shallowRef<AppiumRecordedStep | null>(null);
+let imageCheckIndex: number | undefined;
+let imageCheckBranch: BranchTarget | undefined;
+let imageCheckEditing = false;
+const imageCheckPicking = shallowRef(false);
 const visualChangePicking = shallowRef(false);
 const visualChangeInsertIndex = shallowRef<number | undefined>();
 const visualChangeBranchTarget = shallowRef<BranchTarget | null>(null);
@@ -291,11 +301,12 @@ const selectedBounds = computed(() => {
   return bounds && selectedNode.value ? { id: selectedNode.value.id, ...bounds } : undefined;
 });
 const visualChangeSelectedRegion = computed(() => {
+  if (imageCheckDraft.value?.imageCheck?.target === 'region') return visualRegionToBounds('image-check-region', imageCheckDraft.value.imageCheck.region);
   if (!visualChangeDialogVisible.value || visualChangeConfig.value.mode !== 'region') return undefined;
   return visualRegionToBounds('visual-change-region', visualChangeConfig.value.region);
 });
 const visualChangeRegionSelectionEnabled = computed(() => (
-  visualChangeDialogVisible.value && visualChangeConfig.value.mode === 'region'
+  (visualChangeDialogVisible.value && visualChangeConfig.value.mode === 'region') || imageCheckDraft.value?.imageCheck?.target === 'region'
 ));
 
 function stepWithBranchTarget(step: AppiumRecordedStep, branchTarget: BranchTarget) {
@@ -311,6 +322,10 @@ function stepWithBranchTarget(step: AppiumRecordedStep, branchTarget: BranchTarg
 }
 
 function insertStep(step: AppiumRecordedStep, index?: number, branchTarget?: BranchTarget) {
+  if (branchTarget?.beforeStepId) {
+    steps.value = insertBeforeSharedStep(steps.value, branchTarget.beforeStepId, [step], [step.id]);
+    return steps.value.find(item => item.id === step.id)!;
+  }
   let nextSteps = [...steps.value];
   let insertedStep = branchTarget ? stepWithBranchTarget(step, branchTarget) : step;
   if (index === -1) {
@@ -369,7 +384,7 @@ function copyFlowNodes(indexes: number[]) {
   }
 }
 
-function pasteFlowNodes(index: number, branch?: BranchName) {
+function pasteFlowNodes(index: number, branch?: BranchName, beforeStepId?: string) {
   if (!flowClipboard.value) {
     ElMessage.warning('请先复制节点');
     return;
@@ -382,6 +397,7 @@ function pasteFlowNodes(index: number, branch?: BranchName) {
     const nextSteps = pasteFlowClipboard(steps.value, flowClipboard.value, {
       afterIndex: index,
       branch,
+      beforeStepId,
     });
     validateLoopSteps(nextSteps);
     steps.value = nextSteps;
@@ -631,6 +647,35 @@ function defaultVisualChangeRegion(): AppiumVisualChangeRegion {
   };
 }
 
+function updateImageCheck(config: ImageCheckConfig) {
+  if (imageCheckDraft.value) imageCheckDraft.value = { ...imageCheckDraft.value, imageCheck: config };
+}
+
+function useImageCheckElement() {
+  const node = selectedNode.value;
+  if (!node?.bounds || !imageCheckDraft.value?.imageCheck) return;
+  const located = createNodeActionStep('imageCheck', '图像判断', node);
+  imageCheckDraft.value = { ...imageCheckDraft.value, selector: located.selector, contextSelector: located.contextSelector,
+    selectorChain: located.selectorChain, fallback: undefined,
+    imageCheck: { ...imageCheckDraft.value.imageCheck, target: 'element', region: boundsToVisualRegion(node.bounds) } };
+}
+
+function confirmImageCheck() {
+  const draft = imageCheckDraft.value;
+  if (!draft || recordingLocked.value) return;
+  try {
+    validateImageCheck(draft.imageCheck);
+    if (draft.imageCheck?.target === 'element' && (!draft.selector || draft.selector.strategy === 'bounds')) throw new Error('请选择具有有效定位信息的组件');
+    if (imageCheckEditing) {
+      const index = steps.value.findIndex(step => step.id === draft.id);
+      if (index < 0) throw new Error('原节点已删除');
+      updateStep(index, draft);
+    } else insertStep(draft, imageCheckIndex, imageCheckBranch);
+    imageCheckDraft.value = null;
+    imageCheckPicking.value = false;
+  } catch (error) { ElMessage.warning((error as Error).message); }
+}
+
 function currentVisualChangeConfig() {
   const bounds = selectedNode.value?.bounds;
   return normalizeVisualChangeConfig({
@@ -1245,6 +1290,11 @@ function pickVisualChangeRegion() {
 }
 
 function applyVisualChangeRegion(region: AppiumVisualChangeRegion) {
+  if (imageCheckDraft.value?.imageCheck) {
+    updateImageCheck({ ...imageCheckDraft.value.imageCheck, region, screenWidth: props.deviceWidth || 0, screenHeight: props.deviceHeight || 0 });
+    imageCheckPicking.value = false;
+    return;
+  }
   visualChangeConfig.value = normalizeVisualChangeConfig({
     ...visualChangeConfig.value,
     mode: 'region',
@@ -1282,6 +1332,13 @@ function isReadonlyFlowCopySelected(_index: number) {
   return false;
 }
 
+function addSharedAction(action: RecorderAction, index: number, beforeStepId?: string) {
+  if (!beforeStepId) return addAction(action, index);
+  const target = steps.value.find(step => step.id === beforeStepId);
+  if (!target) return;
+  return addAction(action, index, { beforeStepId, stepId: target.flow?.parentConditionId || '', branch: target.flow?.parentBranch || 'yes' });
+}
+
 async function addAction(
   action: RecorderAction,
   index?: number,
@@ -1350,6 +1407,16 @@ async function addAction(
     if (result) return insertStep({ ...step, breakLoopTargetId: scoped.breakLoopTargetId }, index, branchTarget);
     return;
   }
+  if (action === 'imageCheck') {
+    imageCheckIndex = index;
+    imageCheckBranch = branchTarget;
+    imageCheckEditing = false;
+    imageCheckPicking.value = false;
+    imageCheckDraft.value = { id: createStepId(), type: 'imageCheck', label: '图像判断', flow: { nodeKind: 'condition' },
+      imageCheck: { ...createImageCheckConfig(), region: defaultVisualChangeRegion(), screenWidth: props.deviceWidth || 0, screenHeight: props.deviceHeight || 0 } };
+    if (selectedNode.value?.bounds) useImageCheckElement();
+    return;
+  }
   if (action === 'aiRecognition') {
     const input = await ElMessageBox.prompt('识别内容', '添加 AI 识别', {
       inputType: 'textarea',
@@ -1729,6 +1796,13 @@ function updateStep(index: number, step: AppiumRecordedStep) {
 
 async function editInputStep(index: number) {
   const step = steps.value[index];
+  if (step?.type === 'imageCheck' && !recordingBusy.value) {
+    imageCheckIndex = index;
+    imageCheckEditing = true;
+    imageCheckPicking.value = false;
+    imageCheckDraft.value = JSON.parse(JSON.stringify(step));
+    return;
+  }
   if (!step || (step.type !== 'input' && step.type !== 'inputIfExists') || recordingBusy.value) return;
   const input = await ElMessageBox.prompt('', '修改输入内容', {
     inputValue: step.value || '',
@@ -2142,7 +2216,7 @@ watch(
         :selected-bounds="selectedBounds"
         :selected-region="visualChangeSelectedRegion"
         :region-selection="visualChangeRegionSelectionEnabled"
-        :region-draw-mode="visualChangePicking"
+        :region-draw-mode="visualChangePicking || imageCheckPicking"
         :device-width="deviceWidth"
         :device-height="deviceHeight"
         @switch-device="switchDevice"
@@ -2216,7 +2290,7 @@ watch(
                   @copy="copyFlowNodes"
                   @paste="pasteFlowNodes"
                   @add-delay="addDelayStep"
-                  @insert-action="(index, action) => addAction(action, index)"
+                  @insert-action="(index, action, beforeStepId) => addSharedAction(action, index, beforeStepId)"
                   @insert-branch-action="addBranchAction"
                   @edit-input="editInputStep"
                   @preview-linked-script="previewLinkedScriptStep"
@@ -2331,6 +2405,14 @@ watch(
       @close="aiRecognitionTestStep = null"
     />
 
+    <ImageCheckDialog
+      v-if="imageCheckDraft?.imageCheck"
+      :config="imageCheckDraft.imageCheck" :device-id="selectedDeviceId"
+      :has-element="Boolean(selectedNode?.bounds)" :editing="imageCheckEditing" :picking="imageCheckPicking"
+      @update="updateImageCheck" @close="imageCheckDraft = null; imageCheckPicking = false"
+      @confirm="confirmImageCheck" @use-element="useImageCheckElement"
+      @pick="imageCheckPicking = true; workspaceRef?.showPreview()"
+    />
     <VisualChangeDialog
       :model-value="visualChangeDialogVisible"
       :config="visualChangeConfig"

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>