android-midscene-automation 0.1.31 → 0.1.33

package/CHANGELOG.md

@@ -1,10 +1,23 @@
 # 更新记录
+## v0.1.33
+- 操作菜单移除“断言存在”和“断言文本”，统一保留“判断存在”及其文本匹配配置；旧脚本中的断言节点仍兼容原有执行行为。
+- “点击坐标”节点支持编辑 X、Y 坐标，保存后回放使用新坐标；默认节点名称同步更新，自定义名称保持不变。
+- 新增“预设变量”区域，支持全局变量和脚本私有变量，输入、判断、定位和日志支持 `{{变量名}}` 引用。
+
+## v0.1.32
+- 添加画面变化结束节点时，多组可配对检测支持按名称及开始节点编号选择，允许交叉结束；只有一组时直接添加，保留分支及重复结束校验。
+- 画面变化结束节点校验覆盖祖先及子分支：同一执行路径已存在对应结束节点时，后续分支不能重复添加；互斥分支仍可分别结束。
+- 脚本列表新增“历史结果对比”：保存运行结果、应用版本、设备、截图和日志，支持筛选查看通过率、耗时趋势与失败节点分布，对比两次运行并删除选中历史；手动终止不计入通过率，旧报告不自动补录。
+- 画面变化检测在每个结束节点执行后立即对比本次截图，避免循环及重复调用脚本时多组检测复用最后一轮图片；截图缺失时明确报告异常，不使用旧图替代。
+- “启动 APP”支持在流程中途、判断分支及循环体内多次添加，按所选位置执行；连接脚本仅跳过开头的应用初始化，中途启动操作正常保留。
+- Midscene 相关模块统一从 1.12.2 升级至 1.12.5。
+
 
 ## v0.1.31
 - 组件详情展示 Resource ID、Accessibility ID、XPath 和 UiAutomator 四种定位内容，支持分别复制，方便配置循环退出条件；缺少对应属性时显示未提供。
 - “流程控制”新增有界循环及退出循环：支持固定次数、元素出现或消失时退出，必须设置最大执行次数；循环体支持嵌套判断、合流和连接脚本。退出节点可选择当前或外层循环，退出外层时同时结束内部循环并直接执行目标循环结束路径，日志及 HTML 报告标注轮次和退出目标。
 - 新增流程节点搜索，支持按名称、操作类型、定位内容和日志关键字筛选，展示所属分支并在多个结果间切换；普通画布与流程总览支持定位高亮，不改变节点布局及批量选中状态。
-- Midscene 相关模块统一从 1.12.0 升级至 1.12.2，包含 Android、Android Playground、Core、Playground、Shared 和 Web。
+- Midscene 相关模块统一从 1.12.0 升级至 1.12.2。
 - 录制工作区支持拖拽调整设备预览、组件树栏宽，自动保存布局并支持恢复默认。 
 
 ## v0.1.30

package/README.md

@@ -1229,11 +1229,25 @@ Linux: ~/.local/share/android-midscene-automation
 
 # 项目更新记录
 
+## v0.1.33
+- 操作菜单移除“断言存在”和“断言文本”，统一保留“判断存在”及其文本匹配配置；旧脚本中的断言节点仍兼容原有执行行为。
+- “点击坐标”节点支持编辑 X、Y 坐标，保存后回放使用新坐标；默认节点名称同步更新，自定义名称保持不变。
+- 新增“预设变量”区域，支持全局变量和脚本私有变量，输入、判断、定位和日志支持 `{{变量名}}` 引用。
+
+## v0.1.32
+- 添加画面变化结束节点时，多组可配对检测支持按名称及开始节点编号选择，允许交叉结束；只有一组时直接添加，保留分支及重复结束校验。
+- 画面变化结束节点校验覆盖祖先及子分支：同一执行路径已存在对应结束节点时，后续分支不能重复添加；互斥分支仍可分别结束。
+- 脚本列表新增“历史结果对比”：保存运行结果、应用版本、设备、截图和日志，支持筛选查看通过率、耗时趋势与失败节点分布，对比两次运行并删除选中历史；手动终止不计入通过率，旧报告不自动补录。
+- 画面变化检测在每个结束节点执行后立即对比本次截图，避免循环及重复调用脚本时多组检测复用最后一轮图片；截图缺失时明确报告异常，不使用旧图替代。
+- “启动 APP”支持在流程中途、判断分支及循环体内多次添加，按所选位置执行；连接脚本仅跳过开头的应用初始化，中途启动操作正常保留。
+- Midscene 相关模块统一从 1.12.2 升级至 1.12.5。
+
+
 ## v0.1.31
 - 组件详情展示 Resource ID、Accessibility ID、XPath 和 UiAutomator 四种定位内容，支持分别复制，方便配置循环退出条件；缺少对应属性时显示未提供。
 - “流程控制”新增有界循环及退出循环：支持固定次数、元素出现或消失时退出，必须设置最大执行次数；循环体支持嵌套判断、合流和连接脚本。退出节点可选择当前或外层循环，退出外层时同时结束内部循环并直接执行目标循环结束路径，日志及 HTML 报告标注轮次和退出目标。
 - 新增流程节点搜索，支持按名称、操作类型、定位内容和日志关键字筛选，展示所属分支并在多个结果间切换；普通画布与流程总览支持定位高亮，不改变节点布局及批量选中状态。
-- Midscene 相关模块统一从 1.12.0 升级至 1.12.2，包含 Android、Android Playground、Core、Playground、Shared 和 Web。
+- Midscene 相关模块统一从 1.12.0 升级至 1.12.2。
 - 录制工作区支持拖拽调整设备预览、组件树栏宽，自动保存布局并支持恢复默认。 
 
 ## v0.1.30

package/bin/sync-readme-docs.mjs

@@ -0,0 +1,49 @@
+import { readFile, writeFile } from 'node:fs/promises';
+
+const generatedStart = '<!-- generated-docs:start -->';
+const generatedEnd = '<!-- generated-docs:end -->';
+const readmeUrl = new URL('../README.md', import.meta.url);
+
+const stripFirstHeading = (markdown) =>
+  markdown.replace(/^#\s+[^\r\n]+\r?\n+/, '').trim();
+
+const stripUsageFaqPointer = (markdown) =>
+  markdown.replace(
+    /\n## 常见问题\r?\n\r?\n常见问题已独立整理到 \[FAQ\.md\]\(\.\/FAQ\.md\)。\r?\n/g,
+    '\n',
+  );
+
+const linkReadmeAnchors = (markdown) =>
+  markdown.replace(/\[FAQ\.md\]\(\.\/FAQ\.md\)/g, '[常见问题](#常见问题)');
+
+const [readme, usage, faq, changelog] = await Promise.all([
+  readFile(readmeUrl, 'utf8'),
+  readFile(new URL('../USAGE.md', import.meta.url), 'utf8'),
+  readFile(new URL('../FAQ.md', import.meta.url), 'utf8'),
+  readFile(new URL('../CHANGELOG.md', import.meta.url), 'utf8'),
+]);
+
+const generatedIndex = readme.indexOf(generatedStart);
+const readmeBody = (
+  generatedIndex >= 0 ? readme.slice(0, generatedIndex) : readme
+).trimEnd();
+
+const generatedDocs = [
+  generatedStart,
+  '',
+  '# Appium 录制器使用说明',
+  '',
+  linkReadmeAnchors(stripUsageFaqPointer(stripFirstHeading(usage))),
+  '',
+  '# 常见问题',
+  '',
+  stripFirstHeading(faq),
+  '',
+  '# 项目更新记录',
+  '',
+  stripFirstHeading(changelog),
+  '',
+  generatedEnd,
+].join('\n');
+
+await writeFile(readmeUrl, `${readmeBody}\n\n${generatedDocs}\n`, 'utf8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "android-midscene-automation",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oooooooko/android-midscene-automation.git"
@@ -28,7 +28,7 @@
   ],
   "scripts": {
     "dev": "vite --host 127.0.0.1",
-    "prepack": "node scripts/sync-readme-docs.mjs",
+    "prepack": "node bin/sync-readme-docs.mjs",
     "remote-agent": "tsx remote-agent/index.ts",
     "build": "vue-tsc -b && vite build",
     "preview": "vite preview --host 127.0.0.1",
@@ -38,12 +38,12 @@
   "dependencies": {
     "@dagrejs/dagre": "1.1.5",
     "@element-plus/icons-vue": "2.3.2",
-    "@midscene/android": "https://registry.npmjs.org/@midscene/android/-/android-1.12.2.tgz",
-    "@midscene/android-playground": "https://registry.npmjs.org/@midscene/android-playground/-/android-playground-1.12.2.tgz",
-    "@midscene/core": "https://registry.npmjs.org/@midscene/core/-/core-1.12.2.tgz",
-    "@midscene/playground": "https://registry.npmjs.org/@midscene/playground/-/playground-1.12.2.tgz",
-    "@midscene/shared": "https://registry.npmjs.org/@midscene/shared/-/shared-1.12.2.tgz",
-    "@midscene/web": "https://registry.npmjs.org/@midscene/web/-/web-1.12.2.tgz",
+    "@midscene/android": "https://registry.npmjs.org/@midscene/android/-/android-1.12.5.tgz",
+    "@midscene/android-playground": "https://registry.npmjs.org/@midscene/android-playground/-/android-playground-1.12.5.tgz",
+    "@midscene/core": "https://registry.npmjs.org/@midscene/core/-/core-1.12.5.tgz",
+    "@midscene/playground": "https://registry.npmjs.org/@midscene/playground/-/playground-1.12.5.tgz",
+    "@midscene/shared": "https://registry.npmjs.org/@midscene/shared/-/shared-1.12.5.tgz",
+    "@midscene/web": "https://registry.npmjs.org/@midscene/web/-/web-1.12.5.tgz",
     "@vitejs/plugin-vue": "6.0.7",
     "@vue-flow/core": "1.48.2",
     "archiver": "7.0.1",

package/remote-agent/index.ts

@@ -18,7 +18,7 @@ const agentName = argValue('agent-name', agentId);
 const token = argValue('token', process.env.REMOTE_AGENT_TOKEN || '');
 
 if (!server) {
-  console.error('缺少 --server，例如：npm run remote-agent -- --server http://172.16.20.116:5173');
+  console.error('缺少 --server，例如：npm run remote-agent -- --server http://<控制台主机地址>:5173');
   process.exit(1);
 }
 
@@ -133,7 +133,11 @@ async function handleCommand(command: RemoteCommand) {
   if (command.type === 'replay') {
     const script = payload.script as AppiumRecordedScriptRecord | undefined;
     if (!script) throw new Error('远程回放缺少脚本内容');
-    return await replayAppiumScript(script, command.deviceId);
+    return await replayAppiumScript(script, command.deviceId, undefined, undefined, {
+      parameters: payload.parameters as import('../src/appium-recorder/variables').TestVariable[] | undefined,
+      globalVariables: payload.globalVariables as import('../src/appium-recorder/variables').TestVariable[] | undefined,
+      linkedScripts: payload.linkedScripts as AppiumRecordedScriptRecord[] | undefined,
+    });
   }
   throw new Error(`不支持的命令：${command.type}`);
 }

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

@@ -1,4 +1,8 @@
 import { execFile } from 'node:child_process';
+import { VariableScope, variableContext, resolveVariableStep } from './variables';
+import { getPresetVariables } from './variable-store';
+import { validateExtraction, validateVariables, type TestVariable } from '../../src/appium-recorder/variables';
+import { captureHistoryFrames, readAppVersion } from './history-capture';
 import { BoundedLoopTraversal } from './bounded-loop';
 import { validateLoopSteps } from '../../src/appium-recorder/bounded-loop';
 import { adbScreenshotBase64 } from './screenshot';
@@ -9,7 +13,7 @@ import { textClickSelector } from '../../src/appium-recorder/text-click';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { getAppiumRecordedScript, type AppiumRecordedScriptRecord, type AppiumRecordedStepRecord } from './repository';
+import { linkedScriptSnapshot, type AppiumRecordedScriptRecord, type AppiumRecordedStepRecord } from './repository';
 import { appDataPath } from '../paths';
 import { ensureAndroidSdkAvailable, getAdbCommand } from '../android-sdk';
 import { createAppiumReplayReport, type AppiumReplayFrame, type AppiumReplayVisualCheck } from './report';
@@ -49,6 +53,8 @@ type PendingVisualChangeCheck = {
   step: AppiumRecordedStepRecord;
   nodeNumber: number;
   scriptName: string;
+  frameStart: number;
+  endFrameStart: number;
 };
 
 const replayContext = new AsyncLocalStorage<{
@@ -56,9 +62,12 @@ const replayContext = new AsyncLocalStorage<{
   appiumLog: (line: string) => void;
   serverUrl: string;
   deviceId: string;
+  scripts: Map<string, AppiumRecordedScriptRecord>;
   frames: AppiumReplayFrame[];
+  historyEvents: AppiumReplayFrame[];
   visualChecks: AppiumReplayVisualCheck[];
   pendingVisualChecks: PendingVisualChangeCheck[];
+  visualStartOffsets: Map<string, number>;
   softFailureCount: number;
   flowEnded?: boolean;
 }>();
@@ -332,6 +341,10 @@ async function captureReplayFrame(
 ) {
   const context = replayContext.getStore();
   if (!context || !context.deviceId) return;
+  // 执行记录独立于截图，设备截图失败不能让失败节点从统计中消失。
+  context.historyEvents.push({ sequence: context.historyEvents.length + 1, scriptName, nodeId: step.id,
+    nodeNumber, nodeLabel: step.label, nodeType: step.type, note: step.note || '',
+    selector: replayFrameSelector(step), phase, status, capturedAt: new Date().toISOString(), imageBase64: '' });
   const appendFrame = (imageBase64: string) => {
     context.frames.push({
       sequence: context.frames.length + 1,
@@ -340,7 +353,7 @@ async function captureReplayFrame(
       nodeNumber,
       nodeLabel: step.label,
       nodeType: step.type,
-      logContent: step.type === 'log' && phase === 'after' ? formatStageLog(step) : undefined,
+      logContent: step.type === 'log' && phase === 'after' ? formatStageLog(resolveVariableStep(step)) : undefined,
       note: step.note || '',
       selector: replayFrameSelector(step),
       phase,
@@ -510,6 +523,7 @@ async function waitForElementGone(sessionId: string, step: AppiumRecordedStepRec
 }
 
 async function saveScreenshot(deviceId: string) {
+  if (variableContext.getStore()?.privacy.enabled) return;
   const dir = appDataPath('.midscene-app', 'screenshots');
   await mkdir(dir, { recursive: true });
   const file = join(dir, `appium-${Date.now()}.png`);
@@ -519,6 +533,7 @@ async function saveScreenshot(deviceId: string) {
 type RunStepMeta = {
   nodeNumber: number;
   scriptName: string;
+  frameStart?: number;
 };
 
 type RunStepResult = string | {
@@ -560,10 +575,9 @@ function findVisualFrame(
 ) {
   const matches = frames.filter((frame) => frame.nodeId === nodeId && frame.scriptName === scriptName);
   if (!matches.length) return undefined;
-  const preferred = preferredPhase === 'before'
-    ? matches.find((frame) => frame.phase === preferredPhase)
-    : [...matches].reverse().find((frame) => frame.phase === preferredPhase);
-  return preferred || (preferredPhase === 'before' ? matches[0] : matches[matches.length - 1]);
+  const frame = preferredPhase === 'before' ? matches[0] : matches[matches.length - 1];
+  // A failed capture must not fall back to an older round or a before/error image.
+  return frame?.phase === preferredPhase ? frame : undefined;
 }
 
 const EMPTY_PNG_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=';
@@ -574,12 +588,14 @@ function registerVisualChangeStep(
 ): RunStepResult {
   const config = step.visualChange;
   if (!config) throw new Error(`${step.label} 缺少画面变化检测配置`);
+  const context = replayContext.getStore();
   if (config.role === 'start') {
+    // Invalidate the previous capture even when this start's after screenshot fails.
+    context?.visualStartOffsets.set(JSON.stringify([meta.frameStart || 0, step.id]), context.frames.length);
     return {
       message: `已记录画面变化基准点：${config.pairLabel || step.label}`,
     };
   }
-  const context = replayContext.getStore();
   const endStep = {
     ...step,
     visualChange: {
@@ -587,7 +603,9 @@ function registerVisualChangeStep(
       endStepId: config.endStepId || step.id,
     },
   };
-  context?.pendingVisualChecks.push({ step: endStep, nodeNumber: meta.nodeNumber, scriptName: meta.scriptName });
+  context?.pendingVisualChecks.push({ step: endStep, nodeNumber: meta.nodeNumber, scriptName: meta.scriptName,
+    frameStart: context.visualStartOffsets.get(JSON.stringify([meta.frameStart || 0, config.startStepId])) ?? meta.frameStart ?? 0,
+    endFrameStart: context.frames.length });
   return {
     message: `已记录画面变化对比点：${config.pairLabel || step.label}`,
   };
@@ -624,16 +642,16 @@ function processPendingVisualChecks(lines: string[]) {
   const context = replayContext.getStore();
   if (!context || !context.pendingVisualChecks.length) return;
 
-  // Visual checks compare captured replay frames after the path finishes, so
-  // they never block or mutate the device state for downstream nodes.
+  // Resolve each pair immediately after its end capture, before later rounds
+  // or linked-script calls can replace the images associated with these IDs.
   context.pendingVisualChecks.forEach((check) => {
     const config = check.step.visualChange;
     if (!config?.startStepId || !config.endStepId) {
       appendVisualCheckFailure(lines, check, `${check.step.label} 缺少开始节点或结束节点`);
       return;
     }
-    const baselineFrame = findVisualFrame(context.frames, config.startStepId, check.scriptName, 'after');
-    const comparisonFrame = findVisualFrame(context.frames, config.endStepId, check.scriptName, 'after');
+    const baselineFrame = findVisualFrame(context.frames.slice(check.frameStart, check.endFrameStart), config.startStepId, check.scriptName, 'after');
+    const comparisonFrame = findVisualFrame(context.frames.slice(check.endFrameStart), config.endStepId, check.scriptName, 'after');
     if (!baselineFrame || !comparisonFrame) {
       const missing = [
         baselineFrame ? '' : '开始节点截图',
@@ -688,6 +706,18 @@ async function runStep(
   meta: RunStepMeta,
 ): Promise<RunStepResult | void> {
   throwIfReplayStopped();
+  step = resolveVariableStep(step);
+  if (step.type === 'extractVariable') {
+    const config = validateExtraction(step.extractVariable);
+    const scope = variableContext.getStore();
+    if (!scope) throw new Error('变量作用域未初始化');
+    const elementId = await findElement(sessionId, step);
+    const endpoint = config.attribute === 'text' ? 'text' : `attribute/${encodeURIComponent(config.attribute)}`;
+    const payload = await appiumRequest<AppiumValueResponse<unknown>>(`/session/${sessionId}/element/${elementId}/${endpoint}`);
+    if (payload.value === null || payload.value === undefined) throw new Error(`组件不存在属性：${config.attribute}`);
+    scope.set({ name: config.name, value: String(payload.value), sensitive: config.sensitive }, true);
+    return `已提取变量：${config.name}`;
+  }
   if (step.type === 'delay') {
     await wait(Math.max(0, step.timeoutMs || 1000));
     return;
@@ -918,6 +948,7 @@ async function readNativeControlState(sessionId: string, step: AppiumRecordedSte
 }
 
 async function evaluateCondition(sessionId: string, deviceId: string, step: AppiumRecordedStepRecord) {
+  step = resolveVariableStep(step);
   if (step.type === 'loop') {
     if (step.loop?.exitWhen === 'never') return false;
     const selector = toAppiumUsing(step.selector!);
@@ -1005,12 +1036,17 @@ async function appendStepDiagnostics(lines: string[], deviceId: string, step: Ap
 }
 
 type ReplayStepOptions = {
+  frameStart?: number;
   skipAppInitialization?: boolean;
   scriptName?: string;
 };
 
-function shouldSkipLinkedScriptInitStep(options: ReplayStepOptions, step: AppiumRecordedStepRecord) {
-  return Boolean(options.skipAppInitialization && (step.type === 'launchApp' || step.type === 'clearAppData'));
+function shouldSkipLinkedScriptInitStep(options: ReplayStepOptions, step: AppiumRecordedStepRecord, steps: AppiumRecordedStepRecord[]) {
+  if (!options.skipAppInitialization) return false;
+  // Only the leading initialization sequence is redundant in a linked script.
+  // Launches inside branches or after other operations are intentional actions.
+  return steps.slice(0, steps.indexOf(step) + 1).every(item =>
+    !item.flow?.parentConditionId && (item.type === 'launchApp' || item.type === 'clearAppData'));
 }
 
 function linkedScriptInitSkipReason(step: AppiumRecordedStepRecord) {
@@ -1030,7 +1066,7 @@ async function replayLinkedScript(
   const scriptId = step.value || '';
   if (!scriptId) throw new Error(`${step.label} 缺少连接脚本 ID`);
   if (stack.includes(scriptId)) throw new Error(`${step.label} 检测到循环连接脚本`);
-  const linkedScript = getAppiumRecordedScript(scriptId);
+  const linkedScript = replayContext.getStore()?.scripts.get(scriptId);
   if (!linkedScript) throw new Error(`${step.label} 指向的脚本不存在`);
 
   if (linkedScript.appActivity) {
@@ -1058,10 +1094,12 @@ async function replayLinkedScript(
 
   lines.push(`连接脚本开始：${linkedScript.name}`);
   const nextStack = [...stack, linkedScript.id];
-  await replayScriptSteps(sessionId, deviceId, linkedScript.steps, lines, nextStack, {
-    skipAppInitialization: true,
-    scriptName: linkedScript.name,
-  });
+  const parent = variableContext.getStore()!;
+  const child = parent.child(linkedScript.variables || [], step.parameters);
+  await variableContext.run(child, () => replayScriptSteps(sessionId, deviceId, linkedScript.steps, lines, nextStack, {
+    skipAppInitialization: true, scriptName: linkedScript.name,
+  }));
+  if (!replayContext.getStore()?.flowEnded) parent.acceptReturns(child, step.returns);
   lines.push(`连接脚本完成：${linkedScript.name}`);
 }
 
@@ -1090,7 +1128,7 @@ async function replayLinearSteps(
   for (const [index, step] of steps.entries()) {
     if (replayContext.getStore()?.flowEnded) return;
     throwIfReplayStopped();
-    if (shouldSkipLinkedScriptInitStep(options, step)) {
+    if (shouldSkipLinkedScriptInitStep(options, step, steps)) {
       lines.push(`[节点 ${index + 1}] 跳过：${step.label}（${linkedScriptInitSkipReason(step)}）`);
       continue;
     }
@@ -1104,11 +1142,13 @@ async function replayLinearSteps(
         const result = await runStep(sessionId, deviceId, step, {
           nodeNumber: index + 1,
           scriptName: options.scriptName || '',
+          frameStart: options.frameStart,
         });
         softFailed = appendRunStepResult(lines, index + 1, result);
       }
       lines.push(`[节点 ${index + 1}] 完成：${step.label}${softFailed ? '（存在软失败，已继续）' : ''}`);
       await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'after', completedStepStatus(step, softFailed));
+      processPendingVisualChecks(lines);
     } catch (error) {
       if (isReplayStopped(error)) {
         lines.push(`[节点 ${index + 1}] 已终止：${step.label}`);
@@ -1144,7 +1184,7 @@ async function replayFlowSteps(
     traversal.visit(step);
     const loopContext = traversal.context(step);
     const frameStep = loopContext ? { ...step, label: `${step.label}（${loopContext}）` } : step;
-    if (shouldSkipLinkedScriptInitStep(options, step)) {
+    if (shouldSkipLinkedScriptInitStep(options, step, steps)) {
       lines.push(`[节点 ${index + 1}] 跳过：${step.label}（${linkedScriptInitSkipReason(step)}）`);
       index = nextIndexAfterStep(index, step);
       continue;
@@ -1225,11 +1265,13 @@ async function replayFlowSteps(
         const result = await runStep(sessionId, deviceId, step, {
           nodeNumber: index + 1,
           scriptName: options.scriptName || '',
+          frameStart: options.frameStart,
         });
         softFailed = appendRunStepResult(lines, index + 1, result);
       }
       lines.push(`[节点 ${index + 1}] 完成：${step.label}${softFailed ? '（存在软失败，已继续）' : ''}`);
       await captureReplayFrame(sessionId, frameStep, index + 1, options.scriptName || '', 'after', completedStepStatus(step, softFailed));
+      processPendingVisualChecks(lines);
       index = nextIndexAfterStep(index, step);
     } catch (error) {
       if (isReplayStopped(error)) {
@@ -1278,6 +1320,7 @@ async function replayScriptSteps(
   options: ReplayStepOptions = {},
 ) {
   validateLoopSteps(steps);
+  options = { ...options, frameStart: replayContext.getStore()?.frames.length || 0 };
   let trailingLinkIndex = steps.length;
   while (
     trailingLinkIndex > 0
@@ -1319,30 +1362,57 @@ export async function replayAppiumScript(
   deviceId: string,
   onOutput?: (line: string) => void,
   signal?: AbortSignal,
+  runOptions: { parameters?: TestVariable[]; globalVariables?: TestVariable[]; linkedScripts?: AppiumRecordedScriptRecord[] } = {},
 ) {
   const targetDeviceId = deviceId || script.deviceId;
   if (!targetDeviceId) throw new Error('未检测到可用设备');
   if (!script.steps.length) throw new Error('脚本没有可回放步骤');
 
+  const scope = new VariableScope(runOptions.globalVariables ?? getPresetVariables(), script.variables || []);
+  const scripts = new Map((runOptions.linkedScripts ?? linkedScriptSnapshot(script)).map(item => [item.id, item]));
+  for (const item of validateVariables(runOptions.parameters)) scope.set(item);
+  // 提前登记子脚本敏感预设，避免进入子脚本前的原始日志或截图泄露。
+  const visited = new Set<string>();
+  const registerSecrets = (current: AppiumRecordedScriptRecord) => {
+    if (visited.has(current.id)) return;
+    visited.add(current.id);
+    (current.variables || []).forEach(item => scope.track(item));
+    for (const step of current.steps) {
+      (step.parameters || []).forEach(item => scope.track(item));
+      if (step.extractVariable) scope.track({ ...step.extractVariable, value: '' });
+      if (step.type === 'runScript' && step.value) {
+        const child = scripts.get(step.value);
+        if (child) registerSecrets(child);
+      }
+    }
+  };
+  registerSecrets(script);
+
   const startedAt = new Date();
+  const appVersion = await readAppVersion(targetDeviceId, script.appPackage).catch(() => '');
   const lines: string[] = [];
   const pushLine = lines.push.bind(lines);
   lines.push = (...items: string[]) => {
+    items = items.map(item => scope.redact(item));
     const length = pushLine(...items);
     items.forEach((line) => onOutput?.(line));
     return length;
   };
   const context = {
     signal,
-    appiumLog: (line) => lines.push(line),
+    appiumLog: (line) => { if (!scope.privacy.enabled) lines.push(line); },
     serverUrl: configuredAppiumServerUrl(),
     deviceId: targetDeviceId,
+    scripts,
     frames: [] as AppiumReplayFrame[],
+    historyEvents: [] as AppiumReplayFrame[],
     visualChecks: [] as AppiumReplayVisualCheck[],
+    visualStartOffsets: new Map<string, number>(),
     pendingVisualChecks: [] as PendingVisualChangeCheck[],
     softFailureCount: 0,
   };
-  return replayContext.run(context, async () => {
+  return variableContext.run(scope, () => replayContext.run(context, async () => {
+    if (scope.privacy.enabled) lines.push('敏感变量保护已启用：不保存报告截图、截图节点文件或 Appium 原始日志');
     lines.push(
       `目标设备：${targetDeviceId}`,
       `App 包名：${script.appPackage}`,
@@ -1360,7 +1430,7 @@ export async function replayAppiumScript(
       if (usesManagedAppiumServer()) {
         lines.push('正在启动本次回放的 Appium 服务...');
         lines.push('----- Appium 服务端原始日志开始 -----');
-        managedAppium = await startManagedAppiumServer((line) => lines.push(line), signal);
+        managedAppium = await startManagedAppiumServer((line) => { if (!scope.privacy.enabled) lines.push(line); }, signal);
         context.serverUrl = managedAppium.serverUrl;
       }
       lines.push(`Appium 服务：${appiumServerUrl()}`);
@@ -1426,21 +1496,24 @@ export async function replayAppiumScript(
     }
 
     const completedAt = new Date();
+    const safeFrames = scope.privacy.enabled ? [] : scope.scrub(context.frames);
+    const safeChecks = scope.scrub(context.visualChecks.map(check => scope.privacy.enabled
+      ? { ...check, baselineBase64: '', comparisonBase64: '', diffBase64: '' } : check));
     let reportPath = '';
     let reportId = '';
     let logPath = '';
     let htmlReportPath = '';
     try {
       const report = await createAppiumReplayReport({
-        script,
+        script: scope.scrub(script),
         deviceId: targetDeviceId,
         success,
         stopped,
-        output: lines.join('\n'),
+        output: scope.redact(lines.join('\n')),
         startedAt,
         completedAt,
-        frames: context.frames,
-        visualChecks: context.visualChecks,
+        frames: safeFrames,
+        visualChecks: safeChecks,
       });
       reportPath = report.filePath;
       reportId = report.id;
@@ -1455,12 +1528,20 @@ export async function replayAppiumScript(
     return {
       success,
       stopped,
-      output: lines.join('\n'),
+      output: scope.redact(lines.join('\n')),
       reportPath,
       reportId,
       logPath,
       htmlReportPath,
       softFailureCount: context.softFailureCount,
+      history: {
+        scriptId: script.id, scriptName: script.name, appPackage: script.appPackage,
+        appVersion, deviceId: targetDeviceId, startedAt: startedAt.toISOString(),
+        durationMs: completedAt.getTime() - startedAt.getTime(),
+        status: stopped ? 'stopped' as const : success ? 'passed' as const : 'failed' as const,
+        output: scope.redact(lines.join('\n')),
+        ...scope.scrub(captureHistoryFrames(safeFrames, safeChecks, context.historyEvents)),
+      },
     };
-  });
+  }));
 }

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

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

package/server/appium-recorder/report.ts

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