android-midscene-automation 0.1.32 → 0.1.33

package/CHANGELOG.md

@@ -1,4 +1,8 @@
 # 更新记录
+## v0.1.33
+- 操作菜单移除“断言存在”和“断言文本”，统一保留“判断存在”及其文本匹配配置；旧脚本中的断言节点仍兼容原有执行行为。
+- “点击坐标”节点支持编辑 X、Y 坐标，保存后回放使用新坐标；默认节点名称同步更新，自定义名称保持不变。
+- 新增“预设变量”区域，支持全局变量和脚本私有变量，输入、判断、定位和日志支持 `{{变量名}}` 引用。
 
 ## v0.1.32
 - 添加画面变化结束节点时，多组可配对检测支持按名称及开始节点编号选择，允许交叉结束；只有一组时直接添加，保留分支及重复结束校验。

package/README.md

@@ -1229,6 +1229,11 @@ Linux: ~/.local/share/android-midscene-automation
 
 # 项目更新记录
 
+## v0.1.33
+- 操作菜单移除“断言存在”和“断言文本”，统一保留“判断存在”及其文本匹配配置；旧脚本中的断言节点仍兼容原有执行行为。
+- “点击坐标”节点支持编辑 X、Y 坐标，保存后回放使用新坐标；默认节点名称同步更新，自定义名称保持不变。
+- 新增“预设变量”区域，支持全局变量和脚本私有变量，输入、判断、定位和日志支持 `{{变量名}}` 引用。
+
 ## v0.1.32
 - 添加画面变化结束节点时，多组可配对检测支持按名称及开始节点编号选择，允许交叉结束；只有一组时直接添加，保留分支及重复结束校验。
 - 画面变化结束节点校验覆盖祖先及子分支：同一执行路径已存在对应结束节点时，后续分支不能重复添加；互斥分支仍可分别结束。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "android-midscene-automation",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oooooooko/android-midscene-automation.git"

package/remote-agent/index.ts

@@ -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,7 @@
 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';
@@ -10,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';
@@ -59,6 +62,7 @@ const replayContext = new AsyncLocalStorage<{
   appiumLog: (line: string) => void;
   serverUrl: string;
   deviceId: string;
+  scripts: Map<string, AppiumRecordedScriptRecord>;
   frames: AppiumReplayFrame[];
   historyEvents: AppiumReplayFrame[];
   visualChecks: AppiumReplayVisualCheck[];
@@ -349,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,
@@ -519,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`);
@@ -701,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;
@@ -931,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!);
@@ -1048,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) {
@@ -1076,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}`);
 }
 
@@ -1342,25 +1362,48 @@ 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[],
@@ -1368,7 +1411,8 @@ export async function replayAppiumScript(
     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}`,
@@ -1386,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()}`);
@@ -1452,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;
@@ -1481,7 +1528,7 @@ export async function replayAppiumScript(
     return {
       success,
       stopped,
-      output: lines.join('\n'),
+      output: scope.redact(lines.join('\n')),
       reportPath,
       reportId,
       logPath,
@@ -1492,9 +1539,9 @@ export async function replayAppiumScript(
         appVersion, deviceId: targetDeviceId, startedAt: startedAt.toISOString(),
         durationMs: completedAt.getTime() - startedAt.getTime(),
         status: stopped ? 'stopped' as const : success ? 'passed' as const : 'failed' as const,
-        output: lines.join('\n'),
-        ...captureHistoryFrames(context.frames, context.visualChecks, context.historyEvents),
+        output: scope.redact(lines.join('\n')),
+        ...scope.scrub(captureHistoryFrames(safeFrames, safeChecks, context.historyEvents)),
       },
     };
-  });
+  }));
 }

package/server/appium-recorder/repository.ts

@@ -8,6 +8,8 @@ import {
 } from '../storage/sqlite';
 import { normalizeLegacyNestedConditionBranches } from '../../src/appium-recorder/flow-normalize';
 import { validateLoopSteps } from '../../src/appium-recorder/bounded-loop';
+import { validateVariables, validateExtraction, validateReturns, type TestVariable, type VariableExtraction, type ScriptReturn } from '../../src/appium-recorder/variables';
+import { getPresetVariables, savePresetVariables, deleteScriptVariables } from './variable-store';
 
 export type AppiumRecordedStepRecord = {
   id: string;
@@ -44,6 +46,7 @@ export type AppiumRecordedStepRecord = {
     | 'pinch'
     | 'runScript'
     | 'noop'
+    | 'extractVariable'
     | 'log'
     | 'visualChange';
   label: string;
@@ -86,6 +89,9 @@ export type AppiumRecordedStepRecord = {
   };
   value?: string;
   logPrefix?: string;
+  extractVariable?: VariableExtraction;
+  parameters?: TestVariable[];
+  returns?: ScriptReturn[];
   keyCode?: number;
   timeoutMs?: number;
   longPressMode?: 'element' | 'coordinates';
@@ -162,6 +168,7 @@ export type AppiumRecordedScriptRecord = {
   appPackage: string;
   appActivity: string;
   deviceId: string;
+  variables?: TestVariable[];
   steps: AppiumRecordedStepRecord[];
   createdAt: string;
   updatedAt: string;
@@ -290,6 +297,7 @@ function rowToRecord(row: AppiumRecordedScriptRow): AppiumRecordedScriptRecord {
     appPackage: row.app_package,
     appActivity: normalizeScriptActivity(row.app_package, row.app_activity, steps),
     deviceId: row.device_id || '',
+    variables: getPresetVariables(row.id),
     steps,
     createdAt: row.created_at,
     updatedAt: row.updated_at,
@@ -332,7 +340,20 @@ export function getAppiumRecordedScript(id: string) {
   return row ? rowToRecord(row) : null;
 }
 
+export function linkedScriptSnapshot(root: AppiumRecordedScriptRecord) {
+  const found = new Map<string, AppiumRecordedScriptRecord>([[root.id, root]]);
+  for (const script of found.values()) {
+    for (const step of script.steps) {
+      if (step.type !== 'runScript' || !step.value || found.has(step.value)) continue;
+      const linked = getAppiumRecordedScript(step.value);
+      if (linked) found.set(linked.id, linked);
+    }
+  }
+  return [...found.values()];
+}
+
 export function saveAppiumRecordedScript(input: {
+  variables?: TestVariable[];
   id?: string;
   name: string;
   appPackage: string;
@@ -346,6 +367,11 @@ export function saveAppiumRecordedScript(input: {
   const name = input.name.trim();
   const appPackage = input.appPackage.trim();
   const steps = normalizeLegacyNestedConditionBranches(input.steps || []);
+  if (input.variables !== undefined) validateVariables(input.variables);
+  for (const step of steps) {
+    if (step.type === 'extractVariable') validateExtraction(step.extractVariable);
+    if (step.type === 'runScript') { validateVariables(step.parameters); validateReturns(step.returns); }
+  }
   validateLoopSteps(steps);
   const appActivity = normalizeScriptActivity(appPackage, input.appActivity, steps);
 
@@ -382,6 +408,7 @@ export function saveAppiumRecordedScript(input: {
         flow_json = excluded.flow_json,
         updated_at = excluded.updated_at;
     `);
+    if (input.variables !== undefined) savePresetVariables(input.variables, input.id);
     return getAppiumRecordedScript(input.id);
   }
 
@@ -414,11 +441,14 @@ export function saveAppiumRecordedScript(input: {
       updated_at = excluded.updated_at;
   `);
 
-  return listAppiumRecordedScripts().find((script) => script.name === name) || getAppiumRecordedScript(id);
+  const record = listAppiumRecordedScripts().find((script) => script.name === name) || getAppiumRecordedScript(id);
+  if (record && input.variables !== undefined) record.variables = savePresetVariables(input.variables, record.id);
+  return record;
 }
 
 export function deleteAppiumRecordedScript(id: string) {
   initDb();
+  deleteScriptVariables(id);
   runSql(`
     DELETE FROM appium_recorded_scripts
     WHERE id = ${sqlString(id)};
@@ -426,6 +456,7 @@ export function deleteAppiumRecordedScript(id: string) {
 }
 
 export function importAppiumRecordedScript(input: {
+  variables?: TestVariable[];
   name: string;
   appPackage: string;
   appActivity?: string;

package/server/appium-recorder/routes.ts

@@ -1,10 +1,13 @@
 import { execFile } from 'node:child_process';
+import { getPresetVariables, savePresetVariables } from './variable-store';
+import type { TestVariable } from '../../src/appium-recorder/variables';
 import { deleteRunHistory, getRunHistory, listRunHistory, saveRunHistory } from './run-history';
 import { recognizeDeviceScreen } from './ai-recognition';
 import { readFreshWindowHierarchy } from './tree-dump';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import {
   deleteAppiumRecordedScript,
+  linkedScriptSnapshot,
   getAppiumRecordedScript,
   importAppiumRecordedScript,
   listAppiumRecordedScripts,
@@ -221,6 +224,17 @@ export async function handleAppiumRecorderRequest(
       return true;
     }
 
+    if (pathname === '/api/appium-recorder/variables') {
+      const scriptId = requestUrl.searchParams.get('scriptId') || undefined;
+      if (scriptId && !getAppiumRecordedScript(scriptId)) throw new Error('脚本不存在');
+      const scope = scriptId || (requestUrl.searchParams.get('draft') === '1' ? '__variable_draft__' : undefined);
+      if (req.method === 'GET') { sendJson(res, { variables: getPresetVariables(scope) }); return true; }
+      if (req.method === 'PUT') {
+        const body = await readBody<{ variables: TestVariable[] }>(req);
+        if (!Array.isArray(body.variables)) throw new Error('变量必须为数组');
+        sendJson(res, { variables: savePresetVariables(body.variables, scope) }); return true;
+      }
+    }
     if (pathname === '/api/appium-recorder/scripts' && req.method === 'GET') {
       sendJson(res, { scripts: listAppiumRecordedScripts() });
       return true;
@@ -234,6 +248,7 @@ export async function handleAppiumRecorderRequest(
         appActivity?: string;
         deviceId?: string;
         steps?: AppiumRecordedStepRecord[];
+        variables?: TestVariable[];
       }>(req);
       const script = saveAppiumRecordedScript({
         id: parsed.id,
@@ -242,6 +257,7 @@ export async function handleAppiumRecorderRequest(
         appActivity: parsed.appActivity || '',
         deviceId: parsed.deviceId || selectedDeviceId,
         steps: parsed.steps || [],
+        variables: parsed.variables,
       });
       sendJson(res, { script });
       return true;
@@ -256,6 +272,7 @@ export async function handleAppiumRecorderRequest(
           appActivity?: string;
           deviceId?: string;
           steps?: AppiumRecordedStepRecord[];
+          variables?: TestVariable[];
         };
       }>(req);
       const imported = parsed.script;
@@ -271,6 +288,7 @@ export async function handleAppiumRecorderRequest(
         appActivity: imported.appActivity || '',
         deviceId: imported.deviceId || '',
         steps: imported.steps,
+        variables: imported.variables,
       });
       sendJson(res, { script });
       return true;
@@ -325,7 +343,7 @@ export async function handleAppiumRecorderRequest(
     }
     const replayMatch = pathname.match(/^\/api\/appium-recorder\/scripts\/([^/]+)\/replay$/);
     if (replayMatch && req.method === 'POST') {
-      const parsed = await readBody<{ deviceId?: string }>(req);
+      const parsed = await readBody<{ deviceId?: string; parameters?: TestVariable[] }>(req);
       const script = getAppiumRecordedScript(decodeURIComponent(replayMatch[1]));
       if (!script) throw new Error('Appium 录制脚本不存在');
       const deviceId = parsed.deviceId || selectedDeviceId;
@@ -339,7 +357,7 @@ export async function handleAppiumRecorderRequest(
         res.flushHeaders();
       }
       if (isRemoteDeviceId(deviceId)) {
-        const result = await sendRemoteCommand(deviceId, 'replay', { script }) as Awaited<ReturnType<typeof replayAppiumScript>>;
+        const result = await sendRemoteCommand(deviceId, 'replay', { script, parameters: parsed.parameters, globalVariables: getPresetVariables(), linkedScripts: linkedScriptSnapshot(script) }) as Awaited<ReturnType<typeof replayAppiumScript>>;
         if (result.history) {
           try { saveRunHistory({ ...result.history, scriptId: script.id, deviceId }); }
           catch { result.output += '\n历史记录保存失败'; }
@@ -366,6 +384,7 @@ export async function handleAppiumRecorderRequest(
           deviceId,
           streamOutput ? (line) => sendStreamEvent(res, { type: 'log', line }) : undefined,
           replayAbortController.signal,
+          { parameters: parsed.parameters, globalVariables: getPresetVariables() },
         );
         try { saveRunHistory(result.history); }
         catch { result.output += '\n历史记录保存失败'; }

package/server/appium-recorder/script-export.ts

@@ -1,6 +1,8 @@
 import { buffer } from 'node:stream/consumers';
 import archiver from 'archiver';
 import type { AppiumRecordedScriptRecord } from './repository';
+import { VariableScope } from './variables';
+import { sensitiveVariableName } from '../../src/appium-recorder/variables';
 
 function safeExportName(name: string) {
   const base = Array.from(name.trim().replace(/[<>:"/\\|?*\u0000-\u001f]/g, '_'))
@@ -29,7 +31,11 @@ export async function createAppiumScriptExport(
   }
 
   const exportedAt = new Date().toISOString();
-  const serialize = (script: AppiumRecordedScriptRecord) => JSON.stringify({
+  const serialize = (script: AppiumRecordedScriptRecord) => {
+    const scope = new VariableScope([], script.variables || []);
+    script.steps.forEach(step => step.parameters?.forEach(item => scope.track(item)));
+    const clearSecrets = (items: typeof script.variables = []) => items.map(item => item.sensitive || sensitiveVariableName(item.name) ? { ...item, value: '', sensitive: true } : item);
+    return JSON.stringify(scope.scrub({
     schemaVersion: 1,
     exportedAt,
     script: {
@@ -38,9 +44,11 @@ export async function createAppiumScriptExport(
       appPackage: script.appPackage,
       appActivity: script.appActivity,
       deviceId: script.deviceId,
-      steps: script.steps,
+      variables: clearSecrets(script.variables),
+      steps: script.steps.map(step => ({ ...step, ...(step.parameters ? { parameters: clearSecrets(step.parameters) } : {}) })),
     },
-  }, null, 2);
+  }), null, 2);
+  };
   const baseName = safeExportName(root.name);
   if (!root.steps.some((step) => step.type === 'runScript')) {
     return {

package/server/appium-recorder/variable-store.ts

@@ -0,0 +1,22 @@
+import { querySql, runSql, sqlJson, sqlString } from '../storage/sqlite';
+import { validateVariables, type TestVariable } from '../../src/appium-recorder/variables';
+
+function init() {
+  runSql('CREATE TABLE IF NOT EXISTS appium_variables (scope TEXT PRIMARY KEY, value TEXT NOT NULL);');
+}
+// 预设只在编辑时持久化；回放使用独立快照，不将提取值写回全局。
+export function getPresetVariables(scriptId?: string): TestVariable[] {
+  init();
+  const row = querySql<{ value: string }>(`SELECT value FROM appium_variables WHERE scope=${sqlString(scriptId ? `script:${scriptId}` : 'global')};`)?.[0];
+  return validateVariables(row ? JSON.parse(row.value) : []);
+}
+export function savePresetVariables(variables: TestVariable[], scriptId?: string) {
+  const values = validateVariables(variables);
+  init();
+  runSql(`INSERT INTO appium_variables VALUES (${sqlString(scriptId ? `script:${scriptId}` : 'global')}, ${sqlJson(values)}) ON CONFLICT(scope) DO UPDATE SET value=excluded.value;`);
+  return values;
+}
+export function deleteScriptVariables(scriptId: string) {
+  init();
+  runSql(`DELETE FROM appium_variables WHERE scope=${sqlString(`script:${scriptId}`)};`);
+}

package/server/appium-recorder/variables.ts

@@ -0,0 +1,89 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { sensitiveVariableName, validateVariables, validateReturns, type TestVariable, type ScriptReturn } from '../../src/appium-recorder/variables';
+import type { AppiumRecordedStepRecord } from './repository';
+
+export class VariableScope {
+  readonly locals = new Map<string, TestVariable & { literal?: boolean }>();
+  readonly globals: Map<string, TestVariable>;
+  readonly secrets: Set<string>;
+  readonly privacy: { enabled: boolean };
+  constructor(globals: TestVariable[], locals: TestVariable[], parent?: VariableScope) {
+    this.globals = parent?.globals || new Map(validateVariables(globals).map(item => [item.name, item]));
+    this.secrets = parent?.secrets || new Set();
+    this.privacy = parent?.privacy || { enabled: false };
+    for (const item of this.globals.values()) this.track(item);
+    for (const item of validateVariables(locals)) this.set(item);
+  }
+  track(item: TestVariable) {
+    if (item.sensitive || sensitiveVariableName(item.name)) {
+      this.privacy.enabled = true;
+      if (item.value) this.secrets.add(item.value);
+    }
+  }
+  set(item: TestVariable, literal = false) {
+    const value = validateVariables([item])[0];
+    value.sensitive ||= this.locals.get(value.name)?.sensitive || this.globals.get(value.name)?.sensitive;
+    this.track(value);
+    this.locals.set(value.name, { ...value, literal });
+  }
+  resolve(value: string, chain: string[] = []): { value: string; sensitive: boolean } {
+    let sensitive = false;
+    const resolved = value.replace(/\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g, (_match, name: string) => {
+      if (chain.includes(name)) throw new Error(`变量循环引用：${[...chain, name].join(' -> ')}`);
+      const item: (TestVariable & { literal?: boolean }) | undefined = this.locals.get(name) || this.globals.get(name);
+      if (!item) throw new Error(`变量未定义：${name}`);
+      const next = item.literal ? { value: item.value, sensitive: Boolean(item.sensitive) } : this.resolve(item.value, [...chain, name]);
+      sensitive ||= Boolean(item.sensitive) || sensitiveVariableName(name) || next.sensitive;
+      if (sensitive && next.value) this.secrets.add(next.value);
+      return next.value;
+    });
+    if (sensitive) { this.privacy.enabled = true; if (resolved) this.secrets.add(resolved); }
+    return { value: resolved, sensitive };
+  }
+  child(defaults: TestVariable[], params: TestVariable[] = []) {
+    const child = new VariableScope([], defaults, this);
+    for (const item of validateVariables(params)) {
+      const resolved = this.resolve(item.value);
+      child.set({ ...item, value: resolved.value, sensitive: item.sensitive || resolved.sensitive }, true);
+    }
+    return child;
+  }
+  acceptReturns(child: VariableScope, mappings: ScriptReturn[] = []) {
+    // 先校验全部返回值，缺失时不能只写回一半。
+    const values = validateReturns(mappings).map(mapping => {
+      const item = child.locals.get(mapping.name);
+      if (!item) throw new Error(`子脚本未产生返回变量：${mapping.name}`);
+      const resolved = child.resolve(`{{${mapping.name}}}`);
+      return { name: mapping.target, value: resolved.value, sensitive: item.sensitive || resolved.sensitive };
+    });
+    values.forEach(item => this.set(item, true));
+  }
+  redact(text: string) {
+    let result = text;
+    for (const secret of [...this.secrets].sort((a, b) => b.length - a.length)) {
+      for (const variant of new Set([secret, JSON.stringify(secret).slice(1, -1), encodeURIComponent(secret), JSON.stringify([...secret])])) {
+        if (variant) result = result.split(variant).join('[已脱敏]');
+      }
+    }
+    return result;
+  }
+  scrub<T>(value: T): T {
+    if (typeof value === 'string') return this.redact(value) as T;
+    if (Array.isArray(value)) return value.map(item => this.scrub(item)) as T;
+    if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, this.scrub(item)])) as T;
+    return value;
+  }
+}
+
+export const variableContext = new AsyncLocalStorage<VariableScope>();
+export function resolveVariableStep(step: AppiumRecordedStepRecord) {
+  const scope = variableContext.getStore();
+  if (!scope) return step;
+  const resolve = (value: string | undefined) => value === undefined ? value : scope.resolve(value).value;
+  const selector = (item: typeof step.selector) => item ? { ...item, value: resolve(item.value) } : item;
+  return { ...step, label: resolve(step.label)!, note: resolve(step.note),
+    value: step.type === 'runScript' ? step.value : resolve(step.value), logPrefix: resolve(step.logPrefix),
+    selector: selector(step.selector), fallback: selector(step.fallback), contextSelector: selector(step.contextSelector),
+    selectorChain: step.selectorChain?.map(item => selector(item)!),
+  };
+}