android-midscene-automation 0.1.26 → 0.1.28

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

@@ -1,12 +1,28 @@
-import type { FlowKind } from './flow-graph';
+import type { FlowBranch, FlowKind } from './flow-graph';
 import type { AppiumRecordedStep } from './types';
+import { visualChangeMeta } from './visual-change';
+import { longPressMode } from './long-press';
+import { isNativeStateCondition } from './native-control-state';
+import { DEFAULT_LOG_PREFIX } from './stage-log';
+
+export function isBooleanCondition(step: Pick<AppiumRecordedStep, 'type'>) {
+  return isNativeStateCondition(step) || step.type === 'aiRecognition' || step.type === 'textClick';
+}
 
 export function defaultFlowKind(step: AppiumRecordedStep): FlowKind {
+  if (step.type === 'log') return 'action';
+  if (isBooleanCondition(step)) return 'condition';
   if (step.flow?.nodeKind) return step.flow.nodeKind;
-  if (step.type === 'assertExists' || step.type === 'assertText') return 'assertion';
+  if (step.type === 'assertExists' || step.type === 'assertText' || step.type === 'visualChange') return 'assertion';
   return 'action';
 }
 
+export function flowBranchLabel(step: Pick<AppiumRecordedStep, 'type'>, branch: FlowBranch) {
+  if (step.type === 'textClick') return branch === 'yes' ? '匹配到文字' : '未匹配到文字';
+  if (isBooleanCondition(step)) return branch === 'yes' ? 'true' : 'false';
+  return branch === 'yes' ? '是' : '否';
+}
+
 export function flowKindLabel(kind: FlowKind) {
   return { action: '操作', condition: '判断', assertion: '校验' }[kind];
 }
@@ -23,6 +39,10 @@ export function flowTypeLabel(step: AppiumRecordedStep) {
     waitFor: '等待出现',
     waitDisappear: '等待消失',
     assertExists: '断言存在',
+    checkboxState: 'Checkbox 状态',
+    radioButtonState: 'RadioButton 状态',
+    aiRecognition: 'AI 识别',
+    textClick: '文字点击',
     assertText: '断言文本',
     key: '按键',
     waitActivity: '等待 Activity',
@@ -35,11 +55,22 @@ export function flowTypeLabel(step: AppiumRecordedStep) {
     longPress: '长按',
     pinch: '双指缩放',
     runScript: '连接脚本',
+    noop: '空节点',
+    log: '输出日志',
+    visualChange: '检测画面变化',
   };
   return labelMap[step.type] || step.type;
 }
 
 export function flowStepMeta(step: AppiumRecordedStep) {
+  if (step.type === 'log') return `${step.logPrefix ?? DEFAULT_LOG_PREFIX}:${step.value || ''}`;
+  if (step.type === 'aiRecognition') return step.value || '未填写识别内容';
+  if (step.type === 'longPress') {
+    const target = longPressMode(step) === 'element'
+      ? `元素 ${step.selector?.strategy || ''} ${step.selector?.value || ''}`
+      : `坐标 ${step.fallback?.centerX ?? ''},${step.fallback?.centerY ?? ''}`;
+    return `${target} · ${step.timeoutMs ?? 800}ms`;
+  }
   if (step.type === 'delay') return `${step.timeoutMs || 1000}ms`;
   if (step.type === 'input' || step.type === 'inputIfExists') return `输入内容：${step.value || '空'}`;
   if (defaultFlowKind(step) === 'condition' && step.value) {
@@ -53,15 +84,14 @@ export function flowStepMeta(step: AppiumRecordedStep) {
   if (step.type === 'launchApp') return step.value || '';
   if (step.type === 'clearAppData') return `${step.value || ''}（清除数据与缓存）`;
   if (step.type === 'runScript') return step.value ? `脚本 ${step.value}` : '';
+  if (step.type === 'noop') return '';
   if (step.type === 'screenshot') return '保存当前截图';
+  if (step.type === 'visualChange') return visualChangeMeta(step);
   if (step.type === 'swipe') {
     const swipe = step.swipe;
     return swipe ? `[${swipe.startX},${swipe.startY}] -> [${swipe.endX},${swipe.endY}]` : '';
   }
   if (step.type === 'pinch') return step.pinch?.direction === 'out' ? '放大' : '缩小';
-  if (step.type === 'longPress') {
-    return `${step.fallback?.centerX || ''},${step.fallback?.centerY || ''} · ${step.timeoutMs || 800}ms`;
-  }
   if (step.type === 'coordinateTap') {
     return `${step.fallback?.centerX || ''},${step.fallback?.centerY || ''}`;
   }
@@ -73,7 +103,6 @@ export function labelFlowStep(step: AppiumRecordedStep) {
   const meta = [
     flowKindLabel(defaultFlowKind(step)),
     flowTypeLabel(step),
-    step.optional ? '可选' : '',
     flowStepMeta(step),
   ].filter(Boolean).join(' · ');
   return {

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

@@ -0,0 +1,76 @@
+import type { AppiumRecordedStep } from './types';
+import { isBooleanCondition } from './flow-labels';
+
+type BranchName = 'yes' | 'no';
+
+function isCondition(step: AppiumRecordedStep) {
+  return step.flow?.nodeKind === 'condition';
+}
+
+function isEmptyNestedCondition(step: AppiumRecordedStep) {
+  return isCondition(step)
+    // 新类型不存在旧版分支数据，不应把后续同级节点迁入 true 分支。
+    && !isBooleanCondition(step)
+    && Boolean(step.flow?.parentConditionId)
+    && Boolean(step.flow?.parentBranch)
+    && !step.flow?.yesTargetId
+    && !step.flow?.noTargetId
+    && !step.flow?.successTargetId;
+}
+
+function sameParentBranch(step: AppiumRecordedStep, parentConditionId: string, parentBranch: BranchName) {
+  return step.flow?.parentConditionId === parentConditionId
+    && step.flow?.parentBranch === parentBranch;
+}
+
+export function normalizeLegacyNestedConditionBranches<T extends AppiumRecordedStep>(steps: T[]) {
+  // 清理旧脚本已移除的可选步骤设置，避免继续导出或保存失效字段。
+  const nextSteps = steps.map((step) => {
+    if (!('optional' in step)) return step;
+    const next = { ...step };
+    Reflect.deleteProperty(next, 'optional');
+    return next;
+  });
+  let changed = nextSteps.some((step, index) => step !== steps[index]);
+
+  for (let index = 0; index < nextSteps.length; index += 1) {
+    const condition = nextSteps[index];
+    if (!condition || !isEmptyNestedCondition(condition)) continue;
+
+    const parentConditionId = condition.flow?.parentConditionId || '';
+    const parentBranch = condition.flow?.parentBranch;
+    if (!parentConditionId || !parentBranch) continue;
+
+    const childIndexes: number[] = [];
+    for (let childIndex = index + 1; childIndex < nextSteps.length; childIndex += 1) {
+      if (!sameParentBranch(nextSteps[childIndex], parentConditionId, parentBranch)) break;
+      childIndexes.push(childIndex);
+    }
+    if (!childIndexes.length) continue;
+
+    const firstChild = nextSteps[childIndexes[0]];
+    nextSteps[index] = {
+      ...condition,
+      flow: {
+        ...(condition.flow || {}),
+        nodeKind: 'condition',
+        yesTargetId: firstChild.id,
+      },
+    };
+
+    childIndexes.forEach((childIndex) => {
+      const child = nextSteps[childIndex];
+      nextSteps[childIndex] = {
+        ...child,
+        flow: {
+          ...(child.flow || {}),
+          parentConditionId: condition.id,
+          parentBranch: 'yes',
+        },
+      };
+    });
+    changed = true;
+  }
+
+  return changed ? nextSteps : steps;
+}

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

@@ -0,0 +1,69 @@
+import type { AppiumRecordedStep } from './types';
+
+type FlowTargetKey = 'yesTargetId' | 'noTargetId' | 'successTargetId' | 'failureTargetId';
+
+const FLOW_TARGET_KEYS: FlowTargetKey[] = ['yesTargetId', 'noTargetId', 'successTargetId', 'failureTargetId'];
+
+function sameBranch(step: AppiumRecordedStep, removed: AppiumRecordedStep) {
+  return Boolean(
+    removed.flow?.parentConditionId
+    && removed.flow?.parentBranch
+    && step.flow?.parentConditionId === removed.flow.parentConditionId
+    && step.flow?.parentBranch === removed.flow.parentBranch,
+  );
+}
+
+function nextSequentialStep(steps: AppiumRecordedStep[], removed: AppiumRecordedStep, index: number, removedIds: Set<string>) {
+  const followingSteps = steps.slice(index + 1).filter((step) => !removedIds.has(step.id));
+  if (removed.flow?.parentConditionId && removed.flow.parentBranch) {
+    return followingSteps.find((step) => sameBranch(step, removed));
+  }
+  return followingSteps.find((step) => !step.flow?.parentConditionId);
+}
+
+function cleanFlow(flow: NonNullable<AppiumRecordedStep['flow']>) {
+  return Object.keys(flow).length ? flow : undefined;
+}
+
+export function removeFlowStep(steps: AppiumRecordedStep[], index: number) {
+  const removed = steps[index];
+  if (!removed) return steps;
+
+  // 分支归属决定删除范围，不能沿跳转连线删除共享的后续节点。
+  const removedIds = new Set([removed.id]);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const step of steps) {
+      if (step.flow?.parentConditionId && removedIds.has(step.flow.parentConditionId) && !removedIds.has(step.id)) {
+        removedIds.add(step.id);
+        changed = true;
+      }
+    }
+  }
+  const sequentialStep = nextSequentialStep(steps, removed, index, removedIds);
+  const continuation = steps.find((step) => step.id === removed.flow?.successTargetId && !removedIds.has(step.id));
+  const replacementId = continuation?.id || sequentialStep?.id || '';
+
+  return steps
+    .filter((step) => !removedIds.has(step.id))
+    .map((step) => {
+      if (!step.flow) return step;
+
+      const flow = { ...step.flow };
+      let changed = false;
+
+      FLOW_TARGET_KEYS.forEach((key) => {
+        if (!flow[key] || !removedIds.has(flow[key])) return;
+        // 只有指向被点击节点的入口可以接到后续节点，其他子节点引用直接清除。
+        if (flow[key] === removed.id && replacementId && replacementId !== step.id) {
+          flow[key] = replacementId;
+        } else {
+          delete flow[key];
+        }
+        changed = true;
+      });
+
+      return changed ? { ...step, flow: cleanFlow(flow) } : step;
+    });
+}

package/src/appium-recorder/long-press.ts

@@ -0,0 +1,27 @@
+import type { AppiumRecordedStep } from './types';
+
+export function longPressMode(step: Pick<AppiumRecordedStep, 'longPressMode'>) {
+  // 旧脚本没有模式字段，继续使用录制坐标；新增节点显式设置为 element。
+  return step.longPressMode ?? 'coordinates';
+}
+
+export function validateLongPress(step: AppiumRecordedStep) {
+  const duration = step.timeoutMs ?? 800;
+  if (!Number.isInteger(duration) || duration < 80) return '长按时间必须是至少 80 毫秒的整数';
+  const mode = longPressMode(step);
+  if (mode === 'element') {
+    if (!step.selector || step.selector.strategy === 'bounds' || !step.selector.value?.trim()) {
+      return '请设置有效的长按元素定位器';
+    }
+  } else if (mode === 'coordinates') {
+    const point = step.fallback;
+    if (point?.strategy !== 'bounds'
+      || !Number.isFinite(point.centerX) || Number(point.centerX) < 0
+      || !Number.isFinite(point.centerY) || Number(point.centerY) < 0) {
+      return '请填写有效的长按坐标';
+    }
+  } else {
+    return '长按方式无效';
+  }
+  return '';
+}

package/src/appium-recorder/native-control-state.ts

@@ -0,0 +1,26 @@
+import type { AppiumRecordedStep } from './types';
+
+export type NativeStateType = 'checkboxState' | 'radioButtonState';
+
+export function isNativeStateCondition(step: Pick<AppiumRecordedStep, 'type'>): step is { type: NativeStateType } {
+  return step.type === 'checkboxState' || step.type === 'radioButtonState';
+}
+
+export function nativeControlName(type: NativeStateType) {
+  return type === 'checkboxState' ? 'Checkbox' : 'RadioButton';
+}
+
+export function nativeControlType(className: unknown): NativeStateType | undefined {
+  if (typeof className !== 'string') return undefined;
+  // 识别原生、AppCompat 和 Material 控件；仅有 checkable 的 View 不能证明控件类型。
+  if (/(?:^|\.)(?:AppCompat|Material)?CheckBox$/.test(className)) return 'checkboxState';
+  if (/(?:^|\.)(?:AppCompat|Material)?RadioButton$/.test(className)) return 'radioButtonState';
+  return undefined;
+}
+
+// UIAutomator XML 使用字符串，Appium 属性响应也可能返回布尔值；缺失值不能视为 false。
+export function parseNativeBoolean(value: unknown): boolean | undefined {
+  if (value === true || value === 'true') return true;
+  if (value === false || value === 'false') return false;
+  return undefined;
+}

package/src/appium-recorder/stage-log.ts

@@ -0,0 +1,21 @@
+import type { AppiumRecordedStep } from './types';
+
+export const DEFAULT_LOG_PREFIX = 'stageLog';
+type LogStep = Pick<AppiumRecordedStep, 'logPrefix' | 'value'>;
+
+export function validateStageLog(step: LogStep) {
+  const prefix = step.logPrefix ?? DEFAULT_LOG_PREFIX;
+  if (typeof prefix !== 'string' || !prefix.trim() || /[\r\n:：]/.test(prefix) || prefix.length > 100) {
+    return '关键字不能为空，不能包含冒号或换行，最多 100 字';
+  }
+  if (typeof step.value !== 'string' || !step.value.trim()) return '请输入日志内容';
+  if (step.value.length > 4000) return '日志内容不能超过 4000 字';
+  return '';
+}
+
+export function formatStageLog(step: LogStep) {
+  const error = validateStageLog(step);
+  if (error) throw new Error(error);
+  // 多行内容逐行添加关键字，便于搜索；内容仅作为文本，不执行插值或代码。
+  return step.value!.split(/\r?\n/).map((line) => `${(step.logPrefix ?? DEFAULT_LOG_PREFIX).trim()}:${line}`).join('\n');
+}

package/src/appium-recorder/text-click.ts

@@ -0,0 +1,9 @@
+import type { AppiumRecordedStep } from './types';
+
+export function textClickSelector(step: Pick<AppiumRecordedStep, 'value' | 'flow'>) {
+  if (!step.value?.trim()) throw new Error('请输入要点击的文字');
+  if (step.value.length > 1000) throw new Error('点击文字不能超过 1000 字');
+  // JSON 字符串转义防止引号、反斜杠等内容改变 UiSelector 表达式。
+  const method = step.flow?.textMatch === 'exact' ? 'text' : 'textContains';
+  return { using: '-android uiautomator', value: `new UiSelector().${method}(${JSON.stringify(step.value)})` };
+}

package/src/appium-recorder/tree.ts

@@ -1,4 +1,5 @@
 import type { AppiumBounds, AppiumNode, AppiumSelector } from './types';
+import { parseNativeBoolean } from './native-control-state';
 
 type SelectorCounts = {
   contentDesc: Map<string, number>;
@@ -112,6 +113,8 @@ function transformNode(
     contentDesc: attr(element, 'content-desc'),
     className,
     packageName: attr(element, 'package'),
+    checkable: parseNativeBoolean(attr(element, 'checkable')),
+    checked: parseNativeBoolean(attr(element, 'checked')),
     clickable: attr(element, 'clickable') === 'true',
     enabled: attr(element, 'enabled') !== 'false',
     xpath,

package/src/appium-recorder/types.ts

@@ -24,6 +24,27 @@ export type AppiumPageSnapshot = {
   selectedNodePath?: string;
 };
 
+export type AppiumVisualChangeRegion = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+export type AppiumVisualChangeConfig = {
+  mode: 'selectedElement' | 'region';
+  region: AppiumVisualChangeRegion;
+  role?: 'start' | 'end';
+  pairId?: string;
+  pairLabel?: string;
+  startStepId?: string;
+  endStepId?: string;
+  durationMs: number;
+  intervalMs: number;
+  changeRatioThreshold: number;
+  pixelmatchThreshold: number;
+};
+
 export type AppiumNode = {
   id: string;
   label: string;
@@ -34,6 +55,8 @@ export type AppiumNode = {
   packageName: string;
   clickable: boolean;
   enabled: boolean;
+  checkable?: boolean;
+  checked?: boolean;
   xpath: string;
   bounds?: AppiumBounds;
   selector: AppiumSelector;
@@ -52,6 +75,10 @@ export type AppiumRecordedStep = {
     | 'backIfExists'
     | 'waitFor'
     | 'assertExists'
+    | 'checkboxState'
+    | 'radioButtonState'
+    | 'aiRecognition'
+    | 'textClick'
     | 'key'
     | 'waitActivity'
     | 'delay'
@@ -65,7 +92,10 @@ export type AppiumRecordedStep = {
     | 'assertText'
     | 'longPress'
     | 'pinch'
-    | 'runScript';
+    | 'runScript'
+    | 'noop'
+    | 'log'
+    | 'visualChange';
   label: string;
   note?: string;
   selector?: AppiumSelector;
@@ -73,9 +103,10 @@ export type AppiumRecordedStep = {
   selectorChain?: AppiumSelector[];
   fallback?: AppiumSelector;
   value?: string;
-  optional?: boolean;
+  logPrefix?: string;
   keyCode?: number;
   timeoutMs?: number;
+  longPressMode?: 'element' | 'coordinates';
   flow?: {
     nodeKind?: 'action' | 'condition' | 'assertion';
     yesTargetId?: string;
@@ -102,6 +133,7 @@ export type AppiumRecordedStep = {
     centerY: number;
     percent: number;
   };
+  visualChange?: AppiumVisualChangeConfig;
   snapshot?: {
     text: string;
     resourceId: string;

package/src/appium-recorder/visual-change-pairs.ts

@@ -0,0 +1,147 @@
+import type { AppiumRecordedStep } from './types';
+
+export type VisualChangeBranchTarget = {
+  stepId: string;
+  branch: 'yes' | 'no';
+};
+
+const FLOW_TARGET_KEYS = ['successTargetId', 'failureTargetId'] as const;
+
+export function visualChangePairNumber(label?: string) {
+  const match = /^检测画面变化(\d+)$/.exec(label || '');
+  return match ? Number(match[1]) : 0;
+}
+
+export function nextVisualChangePairLabel(steps: AppiumRecordedStep[]) {
+  const maxNumber = steps.reduce((max, step) => Math.max(
+    max,
+    visualChangePairNumber(step.visualChange?.pairLabel),
+  ), 0);
+  return `检测画面变化${maxNumber + 1}`;
+}
+
+function rawBranchPathForStep(steps: AppiumRecordedStep[], step?: AppiumRecordedStep) {
+  const path: string[] = [];
+  let current = step;
+  let guard = 0;
+  while (current?.flow?.parentConditionId && current.flow.parentBranch && guard < steps.length) {
+    path.unshift(`${current.flow.parentConditionId}:${current.flow.parentBranch}`);
+    current = steps.find((item) => item.id === current?.flow?.parentConditionId);
+    guard += 1;
+  }
+  return path;
+}
+
+function uniqueBranchPaths(paths: string[][]) {
+  const seen = new Set<string>();
+  return paths.filter((path) => {
+    const key = path.join('|');
+    if (!path.length || seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function branchTargetPath(
+  steps: AppiumRecordedStep[],
+  condition: AppiumRecordedStep,
+  branch: 'yes' | 'no',
+  seen: Set<string>,
+) {
+  return [...branchPathForStep(steps, condition, new Set(seen)), `${condition.id}:${branch}`];
+}
+
+export function branchPathForStep(
+  steps: AppiumRecordedStep[],
+  step?: AppiumRecordedStep,
+  seen = new Set<string>(),
+) {
+  const rawPath = rawBranchPathForStep(steps, step);
+  if (rawPath.length || !step || seen.has(step.id)) return rawPath;
+  seen.add(step.id);
+
+  const incomingPaths = uniqueBranchPaths(steps.flatMap((source) => {
+    if (!source.flow || source.id === step.id) return [];
+    const paths: string[][] = [];
+    if (source.flow.nodeKind === 'condition') {
+      if (source.flow.yesTargetId === step.id) paths.push(branchTargetPath(steps, source, 'yes', seen));
+      if (source.flow.noTargetId === step.id) paths.push(branchTargetPath(steps, source, 'no', seen));
+    }
+    FLOW_TARGET_KEYS.forEach((key) => {
+      if (source.flow?.[key] === step.id) paths.push(branchPathForStep(steps, source, new Set(seen)));
+    });
+    return paths;
+  }));
+
+  return incomingPaths.length === 1 ? incomingPaths[0] : [];
+}
+
+// Branch paths are stored as an ancestry chain like
+// ["outer:yes", "inner:no"]. A root node before a condition has an empty
+// path, so it can be closed by an end marker in either downstream branch.
+export function branchPathForInsert(
+  steps: AppiumRecordedStep[],
+  index?: number,
+  branchTarget?: VisualChangeBranchTarget,
+) {
+  if (branchTarget) {
+    const condition = steps.find((step) => step.id === branchTarget.stepId);
+    return [...branchPathForStep(steps, condition), `${branchTarget.stepId}:${branchTarget.branch}`];
+  }
+  return typeof index === 'number' && index >= 0
+    ? branchPathForStep(steps, steps[index])
+    : [];
+}
+
+function sameBranchPath(left: string[], right: string[]) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function branchPathContains(parent: string[], child: string[]) {
+  return parent.length <= child.length && parent.every((value, index) => value === child[index]);
+}
+
+function visualChangeRole(step: AppiumRecordedStep) {
+  return step.visualChange?.role;
+}
+
+function isEndForStart(endStep: AppiumRecordedStep, startStep: AppiumRecordedStep) {
+  const start = startStep.visualChange;
+  const end = endStep.visualChange;
+  if (!start || end?.role !== 'end') return false;
+  if (start.pairId && end.pairId === start.pairId) return true;
+  if (end.startStepId && end.startStepId === startStep.id) return true;
+  return Boolean(
+    start.pairLabel
+      && end.pairLabel === start.pairLabel
+      && (!start.pairId || !end.pairId || !end.startStepId),
+  );
+}
+
+export function findOpenVisualChangeStart(
+  steps: AppiumRecordedStep[],
+  index?: number,
+  branchTarget?: VisualChangeBranchTarget,
+) {
+  const insertPath = branchPathForInsert(steps, index, branchTarget);
+  const insertIndex = typeof index === 'number' ? index : steps.length - 1;
+  // A start marker may be closed once per concrete branch path. This allows a
+  // root start before a condition to have independent yes/no end markers, while
+  // preventing a yes-branch start from pairing with a no-branch end.
+  const hasEndInInsertBranch = (startStep: AppiumRecordedStep) => steps.some((step) => (
+    isEndForStart(step, startStep)
+    && sameBranchPath(branchPathForStep(steps, step), insertPath)
+  ));
+
+  return steps
+    .map((step, stepIndex) => ({ step, stepIndex, path: branchPathForStep(steps, step) }))
+    .filter(({ step, stepIndex, path }) => (
+      visualChangeRole(step) === 'start'
+      && stepIndex <= insertIndex
+      && branchPathContains(path, insertPath)
+      && !hasEndInInsertBranch(step)
+    ))
+    .sort((left, right) => (
+      right.path.length - left.path.length || right.stepIndex - left.stepIndex
+    ))[0]?.step;
+}

package/src/appium-recorder/visual-change.ts

@@ -0,0 +1,75 @@
+import type { AppiumBounds, AppiumRecordedStep } from './types';
+
+export const VISUAL_CHANGE_DEFAULTS = {
+  durationMs: 5000,
+  intervalMs: 1000,
+  changeRatioThreshold: 2,
+  pixelmatchThreshold: 0.1,
+} as const;
+
+export function createStepId() {
+  return `step_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export function boundsToVisualRegion(bounds: AppiumBounds) {
+  return {
+    x: bounds.left,
+    y: bounds.top,
+    width: Math.max(0, bounds.right - bounds.left),
+    height: Math.max(0, bounds.bottom - bounds.top),
+  };
+}
+
+export function normalizeVisualRegion(
+  region: NonNullable<AppiumRecordedStep['visualChange']>['region'],
+) {
+  return {
+    x: Math.max(0, Math.round(Number(region?.x) || 0)),
+    y: Math.max(0, Math.round(Number(region?.y) || 0)),
+    width: Math.max(1, Math.round(Number(region?.width) || 1)),
+    height: Math.max(1, Math.round(Number(region?.height) || 1)),
+  };
+}
+
+export function normalizeVisualChangeConfig(
+  config?: AppiumRecordedStep['visualChange'],
+): NonNullable<AppiumRecordedStep['visualChange']> {
+  return {
+    mode: config?.mode === 'selectedElement' ? 'selectedElement' : 'region',
+    region: normalizeVisualRegion(config?.region || { x: 0, y: 0, width: 1, height: 1 }),
+    role: config?.role === 'start' ? 'start' : config?.role === 'end' ? 'end' : undefined,
+    pairId: config?.pairId || '',
+    pairLabel: config?.pairLabel || '',
+    startStepId: config?.startStepId || '',
+    endStepId: config?.endStepId || '',
+    durationMs: Math.max(1000, Math.round(Number(config?.durationMs) || VISUAL_CHANGE_DEFAULTS.durationMs)),
+    intervalMs: Math.max(200, Math.round(Number(config?.intervalMs) || VISUAL_CHANGE_DEFAULTS.intervalMs)),
+    changeRatioThreshold: Math.max(0.01, Number(config?.changeRatioThreshold) || VISUAL_CHANGE_DEFAULTS.changeRatioThreshold),
+    pixelmatchThreshold: Math.min(
+      1,
+      Math.max(0, Number(config?.pixelmatchThreshold) || VISUAL_CHANGE_DEFAULTS.pixelmatchThreshold),
+    ),
+  };
+}
+
+export function visualRegionToBounds(
+  id: string,
+  region: NonNullable<AppiumRecordedStep['visualChange']>['region'],
+) {
+  const normalized = normalizeVisualRegion(region);
+  return {
+    id,
+    left: normalized.x,
+    top: normalized.y,
+    right: normalized.x + normalized.width,
+    bottom: normalized.y + normalized.height,
+  };
+}
+
+export function visualChangeMeta(step: AppiumRecordedStep) {
+  const config = normalizeVisualChangeConfig(step.visualChange);
+  if (config.role === 'start') return `${config.pairLabel || '检测画面变化'} · 开始 · 阈值 ${config.changeRatioThreshold}%`;
+  if (config.role === 'end') return `${config.pairLabel || '检测画面变化'} · 结束`;
+  const range = config.startStepId && config.endStepId ? '起止节点截图对比' : '请选择起止节点';
+  return `${range} · 阈值 ${config.changeRatioThreshold}%`;
+}