android-midscene-automation 0.1.24 → 0.1.25

package/CHANGELOG.md

@@ -1,9 +1,16 @@
 # 更新记录
 
+## v0.1.25
+
+- Android 设备预览恢复使用 scrcpy 实时流，优化实时流参数，减少 H.264 丢帧导致的花屏；刷新画面时会重启底层 Playground 预览流并等待会话就绪。
+- 测试脚本生成新增提示词模板，可在通用提示词、广告测试、表单填写、聊天对话、播放器测试、搜索列表、订单支付、权限弹窗、个人设置和 H5/WebView 等场景间切换，并支持编辑或上传当前原始 Prompt。
+- 优化 AI 生成流程，支持后台处理和终止生成；生成中锁定原始 Prompt，再次点击“AI 生成”可恢复进度弹窗，终止后不再弹出额外提示。
+- 优化脚本生成提示词策略，区分广告、播放器、弹窗等被测目标与无关遮挡内容，登录流程增加登录后遮挡弹窗处理和无遮挡首页成功判定。
+
 ## v0.1.24
 
 - 参数配置的运行配置新增保存校验，Android SDK 路径必须包含 `platform-tools/adb`，回放报告目录必须填写已存在且可写入的绝对路径。
-- Midscene 自定义提供方的 `Model Name` 和 `Model Family` 改为输入框，方便填写官方支持列表之外的模型名称和模型系列。
+- Midscene 自定义提供方的 `Model Name` 和 `Model Family` 改为输入框，`Base URL` 匹配已知提供方时自动填充模型名称和模型系列，并在字段旁新增官方配置说明入口。
 
 ## v0.1.23
 
@@ -22,10 +29,6 @@
 - 连接脚本回放时会跳过子脚本开始后的重复“启动 App”和“清除 App”操作，减少跨脚本连接时的重复初始化。
 - 移除“连接到下一节点”“取消连接”“继续主流程”等冗余连接操作，保留复制节点作为主要复用方式。
 - 修复放大面板后点击操作按钮或节点配置会重置缩放的问题，保持当前画布大小和位置。
-- Android Playground 改为后台启动 5800 服务，不再自动打开 `http://localhost:5800/` 浏览器窗口。
-- CLI 启动时输出 GitHub 和 Issues 地址，方便用户反馈问题和提交建议。
-- 常见问题新增桌面点击 App 录制说明：部分厂商系统无法获取桌面图标稳定 id，建议使用开始节点后的“启动 App”操作替代。
-- 补充 GitHub 仓库、问题反馈和项目主页信息。
 
 ## v0.1.20
 

package/README.md

@@ -1211,10 +1211,17 @@ output/2026-08-21_17-13-42-831-登录流程.html
 
 # 项目更新记录
 
+## v0.1.25
+
+- Android 设备预览恢复使用 scrcpy 实时流，优化实时流参数，减少 H.264 丢帧导致的花屏；刷新画面时会重启底层 Playground 预览流并等待会话就绪。
+- 测试脚本生成新增提示词模板，可在通用提示词、广告测试、表单填写、聊天对话、播放器测试、搜索列表、订单支付、权限弹窗、个人设置和 H5/WebView 等场景间切换，并支持编辑或上传当前原始 Prompt。
+- 优化 AI 生成流程，支持后台处理和终止生成；生成中锁定原始 Prompt，再次点击“AI 生成”可恢复进度弹窗，终止后不再弹出额外提示。
+- 优化脚本生成提示词策略，区分广告、播放器、弹窗等被测目标与无关遮挡内容，登录流程增加登录后遮挡弹窗处理和无遮挡首页成功判定。
+
 ## v0.1.24
 
 - 参数配置的运行配置新增保存校验，Android SDK 路径必须包含 `platform-tools/adb`，回放报告目录必须填写已存在且可写入的绝对路径。
-- Midscene 自定义提供方的 `Model Name` 和 `Model Family` 改为输入框，方便填写官方支持列表之外的模型名称和模型系列。
+- Midscene 自定义提供方的 `Model Name` 和 `Model Family` 改为输入框，`Base URL` 匹配已知提供方时自动填充模型名称和模型系列，并在字段旁新增官方配置说明入口。
 
 ## v0.1.23
 
@@ -1233,10 +1240,6 @@ output/2026-08-21_17-13-42-831-登录流程.html
 - 连接脚本回放时会跳过子脚本开始后的重复“启动 App”和“清除 App”操作，减少跨脚本连接时的重复初始化。
 - 移除“连接到下一节点”“取消连接”“继续主流程”等冗余连接操作，保留复制节点作为主要复用方式。
 - 修复放大面板后点击操作按钮或节点配置会重置缩放的问题，保持当前画布大小和位置。
-- Android Playground 改为后台启动 5800 服务，不再自动打开 `http://localhost:5800/` 浏览器窗口。
-- CLI 启动时输出 GitHub 和 Issues 地址，方便用户反馈问题和提交建议。
-- 常见问题新增桌面点击 App 录制说明：部分厂商系统无法获取桌面图标稳定 id，建议使用开始节点后的“启动 App”操作替代。
-- 补充 GitHub 仓库、问题反馈和项目主页信息。
 
 ## v0.1.20
 

package/package.json

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

package/server/http-api.ts

@@ -12,9 +12,7 @@ import { appPath } from './paths';
 import { ConfigValidationError, loadConfig, saveConfig, type AppConfig } from './config';
 import { listAppPresetRecords, removeAppPresetRecord, saveAppPresetRecord } from './config-store';
 import { generatePlan } from './script-agent';
-import { importMidsceneModelUsage } from './model-call-usage-importer';
 import { testModelConnection } from './model-tester';
-import { listModelUsageRecords, saveModelUsageRecord } from './model-usage-repository';
 import { DeviceLockConflictError } from './device-locks/types';
 import { acquireDeviceLock, listActiveDeviceLocks, releaseDeviceLock } from './device-locks/service';
 import { ensureDeviceSession, listDeviceSessions } from './device-sessions/service';
@@ -95,12 +93,38 @@ function writeNdjson(res: ServerResponse, event: RunGeneratedScriptEvent | { typ
   res.write(`${JSON.stringify(event)}\n`);
 }
 
+function delay(ms: number) {
+  return new Promise<void>((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+// Work around @midscene/android-playground v1.12.x ESM __dirname usage on Node 24.
 const START_ANDROID_PLAYGROUND_WITHOUT_BROWSER = [
-  "import { androidPlaygroundPlatform, ScrcpyServer } from '@midscene/android-playground';",
-  "import { launchPreparedPlaygroundPlatform } from '@midscene/playground';",
-  'const scrcpyServer = new ScrcpyServer();',
-  'const prepared = await androidPlaygroundPlatform.prepare({ scrcpyServer });',
-  'await launchPreparedPlaygroundPlatform(prepared);',
+  "import { createRequire } from 'node:module';",
+  'const require = createRequire(import.meta.url);',
+  "const { androidPlaygroundPlatform, ScrcpyServer } = require('@midscene/android-playground');",
+  "const { launchPreparedPlaygroundPlatform } = require('@midscene/playground');",
+  'const STABLE_PREVIEW_OPTIONS = {',
+  '  maxFps: 15,',
+  '  maxSize: 1024,',
+  '  videoBitRate: 3000000,',
+  "  videoCodecOptions: 'i-frame-interval=0',",
+  '};',
+  'async function main() {',
+  '  const scrcpyServer = new ScrcpyServer();',
+  '  const startScrcpy = scrcpyServer.startScrcpy.bind(scrcpyServer);',
+  '  scrcpyServer.startScrcpy = (adb, options = {}, onProgress) => startScrcpy(adb, {',
+  '    ...options,',
+  '    ...STABLE_PREVIEW_OPTIONS,',
+  '  }, onProgress);',
+  '  const prepared = await androidPlaygroundPlatform.prepare({ scrcpyServer });',
+  '  await launchPreparedPlaygroundPlatform(prepared);',
+  '}',
+  "main().catch((error) => {",
+  "  console.error(error);",
+  "  process.exit(1);",
+  "});",
 ].join('\n');
 
 type AndroidDevice = {
@@ -458,6 +482,24 @@ async function proxyPlaygroundRequest(req: IncomingMessage, res: ServerResponse,
     return;
   }
 
+  if (targetPath === '/mjpeg' && response.body) {
+    const reader = response.body.getReader();
+    req.once('close', () => {
+      reader.cancel().catch(() => undefined);
+    });
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value) res.write(Buffer.from(value));
+      }
+      res.end();
+    } catch {
+      if (!res.writableEnded) res.end();
+    }
+    return;
+  }
+
   const buffer = Buffer.from(await response.arrayBuffer());
   res.end(buffer);
 }
@@ -557,6 +599,39 @@ export function createApiMiddleware() {
       });
   };
 
+  const stopAndroidPlayground = async () => {
+    const processToStop = playgroundProcess;
+    if (!processToStop || processToStop.killed) return;
+
+    await new Promise<void>((resolve) => {
+      const timeout = setTimeout(resolve, 1500);
+      processToStop.once('exit', () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+      processToStop.kill('SIGTERM');
+    });
+    if (playgroundProcess === processToStop) {
+      playgroundProcess = null;
+    }
+  };
+
+  const waitForUsablePlaygroundTarget = async (selectedDeviceId: string, timeoutMs = 30000) => {
+    const deadline = Date.now() + timeoutMs;
+    let resolved: PlaygroundTarget = null;
+    while (Date.now() < deadline) {
+      resolved = await resolvePlaygroundUrl(selectedDeviceId);
+      if (resolved && selectedDeviceId && !isUsablePlaygroundTarget(resolved, selectedDeviceId) && !resolved.sessionConnected) {
+        resolved = await createPlaygroundSession(resolved, selectedDeviceId) || resolved;
+      }
+      if (isUsablePlaygroundTarget(resolved, selectedDeviceId)) {
+        return resolved;
+      }
+      await delay(500);
+    }
+    return resolved;
+  };
+
   const handler: NextHandleFunction = async (req, res, next) => {
     const requestUrl = new URL(req.url || '/', 'http://localhost');
     const pathname = requestUrl.pathname;
@@ -947,16 +1022,53 @@ export function createApiMiddleware() {
       return;
     }
 
+    if (req.url === '/api/playground-restart' && req.method === 'POST') {
+      try {
+        const payload = await readBody<{ deviceId?: string }>(req);
+        const deviceId = payload.deviceId || selectedDeviceId;
+        if (!deviceId) {
+          throw new Error('请先选择 Android 设备');
+        }
+        if (isRemoteDeviceId(deviceId)) {
+          throw new Error('远程设备不支持重启本地实时预览');
+        }
+
+        setSelectedDeviceId(req, res, deviceId);
+        selectedDeviceId = deviceId;
+        playgroundEnsurePromise = null;
+        lastPlaygroundEnsureAt = 0;
+        lastPlaygroundEnsureDeviceId = '';
+        await stopAndroidPlayground();
+        const result = await ensureAndroidPlayground(deviceId);
+        const target = result.target || await waitForUsablePlaygroundTarget(deviceId);
+
+        ensureDeviceSession({
+          deviceId,
+          patch: {
+            playgroundUrl: target?.url || '',
+            previewKind: target?.previewKind || '',
+            sessionConnected: target?.sessionConnected || false,
+            setupState: target?.setupState || result.skippedReason || '',
+            previewError: target?.previewError || '',
+          },
+        });
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.end(JSON.stringify({
+          success: true,
+          started: result.started,
+          available: isUsablePlaygroundTarget(target, deviceId),
+          url: target?.url || '',
+          skippedReason: result.skippedReason,
+        }));
+      } catch (error) {
+        res.statusCode = 500;
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.end(JSON.stringify({ message: error instanceof Error ? error.message : '重启 Android Playground 失败' }));
+      }
+      return;
+    }
+
     if (req.url === '/api/test-model' && req.method === 'POST') {
-      const startedAt = Date.now();
-      let modelKey: 'midscene' | 'scriptOptimizer' = 'midscene';
-      let model: {
-        provider?: 'custom' | 'codex';
-        baseUrl?: string;
-        apiKey?: string;
-        name?: string;
-        family?: string;
-      } = {};
       try {
         const parsed = await readBody<{
           modelKey?: 'midscene' | 'scriptOptimizer';
@@ -968,8 +1080,7 @@ export function createApiMiddleware() {
             family?: string;
           };
         }>(req);
-        model = parsed.model || {};
-        modelKey = parsed.modelKey === 'scriptOptimizer' ? 'scriptOptimizer' : 'midscene';
+        const model = parsed.model || {};
 
         const result = await testModelConnection({
           provider: model.provider,
@@ -978,42 +1089,8 @@ export function createApiMiddleware() {
           name: model.name || '',
           family: model.family || '',
         });
-        saveModelUsageRecord({
-          modelKey,
-          provider: modelKey === 'midscene' ? model.provider || 'custom' : 'custom',
-          modelName: model.name || '',
-          family: model.family || '',
-          success: true,
-          durationMs: result.durationMs ?? Date.now() - startedAt,
-          promptTokens: result.usage?.promptTokens,
-          completionTokens: result.usage?.completionTokens,
-          totalTokens: result.usage?.totalTokens,
-        });
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify(result));
-      } catch (error) {
-        saveModelUsageRecord({
-          modelKey,
-          provider: modelKey === 'midscene' ? model.provider || 'custom' : 'custom',
-          modelName: model.name || '',
-          family: model.family || '',
-          success: false,
-          durationMs: Date.now() - startedAt,
-          errorMessage: error instanceof Error ? error.message : 'Unknown error',
-        });
-        res.statusCode = 500;
-        res.setHeader('Content-Type', 'application/json; charset=utf-8');
-        res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
-      }
-      return;
-    }
-
-    if (req.url?.startsWith('/api/model-usage-records') && req.method === 'GET') {
-      try {
-        const requestUrl = new URL(req.url, 'http://localhost');
-        const limit = Number(requestUrl.searchParams.get('limit') || 50);
-        res.setHeader('Content-Type', 'application/json; charset=utf-8');
-        res.end(JSON.stringify({ records: listModelUsageRecords(limit) }));
       } catch (error) {
         res.statusCode = 500;
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
@@ -1175,43 +1252,23 @@ export function createApiMiddleware() {
 
     try {
       if (req.url === '/api/generate' && req.method === 'POST') {
-        const startedAt = Date.now();
-        const config = loadConfig();
         const parsed = await readBody<{
           prompt?: string;
         }>(req);
+        const generateAbortController = new AbortController();
+        res.on('close', () => {
+          if (!res.writableEnded) {
+            generateAbortController.abort();
+          }
+        });
 
-        try {
-          const result = await generatePlan({
-            prompt: parsed.prompt || '',
-          });
-
-          saveModelUsageRecord({
-            modelKey: 'scriptOptimizer',
-            provider: 'custom',
-            modelName: config.scriptOptimizer.model.name || '',
-            family: '',
-            success: true,
-            durationMs: result.durationMs || Date.now() - startedAt,
-            promptTokens: result.usage?.promptTokens,
-            completionTokens: result.usage?.completionTokens,
-            totalTokens: result.usage?.totalTokens,
-          });
+        const result = await generatePlan({
+          prompt: parsed.prompt || '',
+          signal: generateAbortController.signal,
+        });
 
-          res.setHeader('Content-Type', 'application/json; charset=utf-8');
-          res.end(JSON.stringify(result));
-        } catch (error) {
-          saveModelUsageRecord({
-            modelKey: 'scriptOptimizer',
-            provider: 'custom',
-            modelName: config.scriptOptimizer.model.name || '',
-            family: '',
-            success: false,
-            durationMs: Date.now() - startedAt,
-            errorMessage: error instanceof Error ? error.message : 'AI 生成失败',
-          });
-          throw error;
-        }
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.end(JSON.stringify(result));
         return;
       }
 
@@ -1281,7 +1338,6 @@ export function createApiMiddleware() {
         res.setHeader('X-Accel-Buffering', 'no');
         writeNdjson(res, { type: 'operation', operation });
 
-        const usageImportSinceMs = Date.now();
         try {
           const result = await runGeneratedScript({
             code: parsed.code || '',
@@ -1316,26 +1372,6 @@ export function createApiMiddleware() {
               writeNdjson(res, event);
             },
           });
-          try {
-            const usageImportResult = importMidsceneModelUsage({
-              sinceMs: usageImportSinceMs,
-              model: loadConfig().midscene.model,
-              success: result.success,
-            });
-            if (usageImportResult.imported > 0) {
-              recordOperationEvent({
-                operationId: operation.id,
-                eventType: 'model_usage_imported',
-                data: usageImportResult,
-              });
-            }
-          } catch (error) {
-            recordOperationEvent({
-              operationId: operation.id,
-              eventType: 'model_usage_import_failed',
-              message: error instanceof Error ? error.message : '模型消耗导入失败',
-            });
-          }
           finishScriptRunOperation({
             operationId: operation.id,
             status: result.success ? 'succeeded' : runAbortController.signal.aborted ? 'cancelled' : 'failed',

package/server/script-agent.ts

@@ -45,32 +45,34 @@ const systemPrompt = `你是一个 Midscene 自动化脚本规划器。
 7. 通用测试场景默认按“进入/确认目标 App -> 处理启动阶段遮挡 -> 等待起始页面稳定 -> 执行核心业务动作 -> 等待结果页面或读取结果”的结构拆分。不要只生成一条巨型 act，也不要为同一状态生成重复验证。
 8. 如果需求涉及某个 App，第一条可执行步骤只做轻量进入/确认目标 App：若当前已在目标 App 内则保持当前状态；若不在目标 App 内，使用包名打开目标 App 并等待首屏，不要描述“查找桌面图标/从最近任务选择”等视觉搜索过程。启动后不要再生成额外 boolean 确认。
 9. 如果原始需求里有“遇到弹窗则关闭/允许/跳过”这类策略，生成 1 条启动阶段总括 act 步骤即可，默认 repeat: 1；只有用户明确要求“反复处理/直到没有/所有弹窗”时才设置 repeat: 2。prompt 要写清楚只检查权限、启动协议、广告、更新、活动、通知引导等启动阶段弹窗；如果没有弹窗，不要点击业务内容、表单字段、复选框或提交按钮。
-10. 所有场景都要把输入、点击、等待结果拆成独立步骤。输入使用 input，明确点击使用 tap，条件式处理使用 act，页面稳定使用 waitFor，读取数据使用 query/string/number，真假判断使用 boolean。
-11. 所有定位 prompt 都要具体到页面、区域、附近文本或业务含义，例如“搜索页顶部搜索框”“设备列表中的第一个在线设备”“详情页右上角设置按钮”。不要写“输入框”“按钮”“列表项”等泛化描述。
-12. 所有 input 的 value 必须完全来自原始需求；不得改写、脱敏、复用历史值或编造示例值。aiInput 步骤中 prompt 只表示输入框定位描述，value 表示要输入的内容。
-13. 结果验证默认用 1 条 waitFor 写正向、可观察的成功信号，例如目标页面标题、列表项、详情页核心元素、提交成功页、设备状态变化。不要默认追加长串失败排除条件；只有用户明确要求校验失败原因时，才额外生成错误提示读取或失败断言。
-14. 每个 boolean 步骤只能问一个真假问题；默认不要为了确认当前页面状态而生成 boolean，优先使用 waitFor 作为稳定状态验证。不要生成“waitFor + boolean”重复判断同一结果。
-15. 条件式 no-op 动作会增加模型调用，只有确实存在分支时才生成。如果一个动作步骤的 prompt 包含“如果存在/若出现/如果当前不是/如果未勾选/如果已经/否则跳过/保持当前状态”，不能使用 tap；应使用单次 act，或者先用 boolean 判断后再生成确定目标的 tap，但不要两者都生成。
-16. “处理弹窗/关闭弹窗/允许权限/同意协议”必须使用 act 或 tap，因为 boolean/query 只会判断或读取，不会点击按钮。
-17. 生成步骤时必须参考后续提供的 Midscene 文档内容，尤其是 JavaScript 优化建议、aiAct/aiTap/aiInput/aiWaitFor/aiQuery/aiBoolean/aiString/aiNumber 的职责边界和用法。
-18. 不要生成 Midscene 文档中不存在的 API 名称。当前只输出结构化 JSON steps，由代码生成器映射为对应的 Midscene API。
-19. 优先套用后续 Midscene 脚本生成参考中的拆分策略、步骤标题规范、通用场景模板、登录场景模板、弹窗处理模板和失败验证规则。
-20. Midscene 1.10.4 支持 startObserving/UIObserver。只有原始需求明确需要验证动作过程中一闪而过的 Toast、短暂错误提示、Banner、加载状态或自动消失控件时，才给触发该现象的 act/tap/input 步骤填写 observePrompt；如果不需要验证瞬时现象，必须省略该字段。
-21. observePrompt 必须描述一个肯定、可观察的历史事件，例如“点击保存后，执行过程中出现过保存成功提示”。不要用它判断最终页面是否稳定、当前是否仍有弹窗、是否进入结果页等持续状态，这些情况默认只用 aiWaitFor。
-22. observePrompt 应挂在直接触发现象的动作步骤上，不要挂在启动 App、循环处理弹窗或等待步骤上。即使观察到了成功 Toast，只要用户把“进入结果页/列表更新/状态变化”作为成功标准，仍必须生成最终页面的 waitFor；不要再默认补结果 boolean。
-23. 登录场景默认控制在 7 到 9 个可执行步骤：进入/确认 App、处理启动弹窗、等待登录页、必要时进入账号密码登录、输入账号、输入密码、必要时勾选协议、提交登录、等待首页。最终默认用 waitFor 作为成功判定；只有用户明确要求读取布尔结果、错误原因或断言日志时，才额外生成 boolean/string/query。
-24. 登录场景必须先从原始需求中抽取账号、密码、验证码等输入值；所有后续步骤必须复用完全相同的字面量，禁止把邮箱改成手机号、把手机号改成邮箱、使用历史账号、示例账号或自行编造账号。
-25. 登录表单必须拆分：账号输入是独立 input，密码输入是独立 input，登录按钮是独立 tap。登录协议勾选框只有在页面/需求明确需要时才生成独立处理步骤。不要用一条 act 同时输入账号、输入密码、勾选协议和点击登录。
-26. 登录按钮步骤必须使用 tap，prompt 只描述点击当前页面的登录按钮，例如“点击登录页中的登录按钮，提交当前已填写的表单；不要修改账号、密码或其他输入框”。不要在登录按钮 prompt 中重新写账号或密码，也不要追加“如果软键盘遮挡”等条件式子句。
-27. 简单且目标确定可见的点击优先使用 tap。登录按钮适合 tap；只有明确当前不在账号密码登录页时，账号密码登录入口才适合 tap；只有明确协议未勾选时，登录协议勾选框才适合 tap。
-28. 如果步骤语义是“如果当前不是账号密码登录页则点击入口，否则保持当前状态”，必须使用单次 act，不要用 tap。
-29. 如果步骤语义是“如果协议未勾选则勾选，已勾选或没有复选框则保持当前状态”，必须使用单次 act，避免 tap 反选已勾选的协议。
-30. 登录协议勾选框、登录按钮和登录后协议确认弹窗不能设置 repeat；每个步骤最多点击一次，后续用 waitFor 判断是否成功，避免再补重复 boolean。
-31. 如果等待登录页后还可能停留在欢迎页、手机号登录页、微信登录页或其他非账号密码登录页，必须在输入账号前生成单次 act：如果当前不是账号密码登录页，点击账号密码登录入口或切换到账号密码登录方式；如果当前已经显示账号和密码输入框，则保持当前状态。
-32. 登录账号输入框 prompt 必须根据已选择的登录方式精确定位：账号密码登录页中写“账号密码登录页中的账号或邮箱输入框”；手机号登录页中写“手机号登录页中的手机号输入框”。不要写“手机号、账号或邮箱输入框”这种会匹配多个字段的泛化描述。
-33. 登录协议勾选 prompt 必须说明只点击复选框本身，不点击用户协议、隐私政策等文本链接。
-34. 登录成功后的 waitFor 默认只写正向成功信号：等待首页或主界面稳定显示，出现设备列表、添加设备入口、底部导航、用户头像或我的页面入口等首页核心元素之一。不要默认追加长串失败排除条件；只有用户明确要求校验失败原因时，才额外生成错误提示读取或失败断言。
-35. 协议确认弹窗和“再次提交登录”不是登录脚本的默认步骤。只有原始需求明确提到点击登录后会出现服务协议/隐私政策/声明与条款确认弹窗，或上下文明确该 App 存在这个二次确认，才生成这两个条件式 act 步骤。`;
+10. 处理任何弹窗、广告、活动、播放器浮层、权限、升级提示前，必须先根据原始需求判断它是“被测目标”还是“干扰遮挡”。如果原始需求正在测试广告、播放器、弹窗、活动页、升级提示、引导页等内容，不要把这些元素当作干扰关闭；应生成 waitFor/query/boolean/tap/act 来等待、读取、断言或操作它们。只有与当前测试目标无关且遮挡后续操作的内容，才生成单独 act 关闭、跳过或允许。
+11. 所有场景都要把输入、点击、等待结果拆成独立步骤。输入使用 input，明确点击使用 tap，条件式处理使用 act，页面稳定使用 waitFor，读取数据使用 query/string/number，真假判断使用 boolean。
+12. 所有定位 prompt 都要具体到页面、区域、附近文本或业务含义，例如“搜索页顶部搜索框”“设备列表中的第一个在线设备”“详情页右上角设置按钮”。不要写“输入框”“按钮”“列表项”等泛化描述。
+13. 所有 input 的 value 必须完全来自原始需求；不得改写、脱敏、复用历史值或编造示例值。aiInput 步骤中 prompt 只表示输入框定位描述，value 表示要输入的内容。
+14. 结果验证默认用 1 条 waitFor 写正向、可观察的成功信号，例如目标页面标题、列表项、详情页核心元素、提交成功页、设备状态变化。不要默认追加长串失败排除条件；只有用户明确要求校验失败原因时，才额外生成错误提示读取或失败断言。
+15. 每个 boolean 步骤只能问一个真假问题；默认不要为了确认当前页面状态而生成 boolean，优先使用 waitFor 作为稳定状态验证。不要生成“waitFor + boolean”重复判断同一结果。
+16. 条件式 no-op 动作会增加模型调用，只有确实存在分支时才生成。如果一个动作步骤的 prompt 包含“如果存在/若出现/如果当前不是/如果未勾选/如果已经/否则跳过/保持当前状态”，不能使用 tap；应使用单次 act，或者先用 boolean 判断后再生成确定目标的 tap，但不要两者都生成。
+17. “处理弹窗/关闭弹窗/允许权限/同意协议”必须使用 act 或 tap，因为 boolean/query 只会判断或读取，不会点击按钮。
+18. 生成步骤时必须参考后续提供的 Midscene 文档内容，尤其是 JavaScript 优化建议、aiAct/aiTap/aiInput/aiWaitFor/aiQuery/aiBoolean/aiString/aiNumber 的职责边界和用法。
+19. 不要生成 Midscene 文档中不存在的 API 名称。当前只输出结构化 JSON steps，由代码生成器映射为对应的 Midscene API。
+20. 优先套用后续 Midscene 脚本生成参考中的拆分策略、步骤标题规范、通用场景模板、登录场景模板、弹窗处理模板和失败验证规则。
+21. Midscene 1.10.4 支持 startObserving/UIObserver。只有原始需求明确需要验证动作过程中一闪而过的 Toast、短暂错误提示、Banner、加载状态或自动消失控件时，才给触发该现象的 act/tap/input 步骤填写 observePrompt；如果不需要验证瞬时现象，必须省略该字段。
+22. observePrompt 必须描述一个肯定、可观察的历史事件，例如“点击保存后，执行过程中出现过保存成功提示”。不要用它判断最终页面是否稳定、当前是否仍有弹窗、是否进入结果页等持续状态，这些情况默认只用 aiWaitFor。
+23. observePrompt 应挂在直接触发现象的动作步骤上，不要挂在启动 App、循环处理弹窗或等待步骤上。即使观察到了成功 Toast，只要用户把“进入结果页/列表更新/状态变化”作为成功标准，仍必须生成最终页面的 waitFor；不要再默认补结果 boolean。
+24. 登录场景默认控制在 8 到 10 个可执行步骤：进入/确认 App、处理启动弹窗、等待登录页、必要时进入账号密码登录、输入账号、输入密码、必要时勾选协议、提交登录、处理登录后遮挡弹窗、等待首页。最终默认用 waitFor 作为成功判定；只有用户明确要求读取布尔结果、错误原因或断言日志时，才额外生成 boolean/string/query。
+25. 登录场景必须先从原始需求中抽取账号、密码、验证码等输入值；所有后续步骤必须复用完全相同的字面量，禁止把邮箱改成手机号、把手机号改成邮箱、使用历史账号、示例账号或自行编造账号。
+26. 登录表单必须拆分：账号输入是独立 input，密码输入是独立 input，登录按钮是独立 tap。登录协议勾选框只有在页面/需求明确需要时才生成独立处理步骤。不要用一条 act 同时输入账号、输入密码、勾选协议和点击登录。
+27. 登录按钮步骤必须使用 tap，prompt 只描述点击当前页面的登录按钮，例如“点击登录页中的登录按钮，提交当前已填写的表单；不要修改账号、密码或其他输入框”。不要在登录按钮 prompt 中重新写账号或密码，也不要追加“如果软键盘遮挡”等条件式子句。
+28. 简单且目标确定可见的点击优先使用 tap。登录按钮适合 tap；只有明确当前不在账号密码登录页时，账号密码登录入口才适合 tap；只有明确协议未勾选时，登录协议勾选框才适合 tap。
+29. 如果步骤语义是“如果当前不是账号密码登录页则点击入口，否则保持当前状态”，必须使用单次 act，不要用 tap。
+30. 如果步骤语义是“如果协议未勾选则勾选，已勾选或没有复选框则保持当前状态”，必须使用单次 act，避免 tap 反选已勾选的协议。
+31. 登录协议勾选框、登录按钮和登录后协议确认弹窗不能设置 repeat；每个步骤最多点击一次，后续用 waitFor 判断是否成功，避免再补重复 boolean。
+32. 如果等待登录页后还可能停留在欢迎页、手机号登录页、微信登录页或其他非账号密码登录页，必须在输入账号前生成单次 act：如果当前不是账号密码登录页，点击账号密码登录入口或切换到账号密码登录方式；如果当前已经显示账号和密码输入框，则保持当前状态。
+33. 登录账号输入框 prompt 必须根据已选择的登录方式精确定位：账号密码登录页中写“账号密码登录页中的账号或邮箱输入框”；手机号登录页中写“手机号登录页中的手机号输入框”。不要写“手机号、账号或邮箱输入框”这种会匹配多个字段的泛化描述。
+34. 登录协议勾选 prompt 必须说明只点击复选框本身，不点击用户协议、隐私政策等文本链接。
+35. 登录按钮提交后必须生成 1 条单次 act 处理登录后遮挡弹窗：若出现版本升级、广告、活动、评分、通知引导、登录后协议或权限弹窗，点击关闭、跳过、稍后再说、取消、同意或允许；如果没有弹窗则保持当前状态。不要点击首页业务内容、添加设备、底部导航或退出登录。若是强制升级且没有关闭/取消/稍后按钮，不要点击立即更新，保持弹窗让最终 waitFor 失败。
+36. 登录成功后的 waitFor 默认只写正向成功信号并带无遮挡要求：等待首页或主界面稳定显示，出现设备列表、添加设备入口、底部导航、用户头像或我的页面入口等首页核心元素之一，并且没有版本升级、广告、活动、评分或通知引导弹窗遮挡首页。不要默认追加长串失败排除条件；只有用户明确要求校验失败原因时，才额外生成错误提示读取或失败断言。
+37. 协议确认弹窗和“再次提交登录”不是登录脚本的默认步骤。只有原始需求明确提到点击登录后会出现服务协议/隐私政策/声明与条款确认弹窗，或上下文明确该 App 存在这个二次确认，才生成这两个条件式 act 步骤。`;
 
 const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const midsceneDocsDir = path.join(projectRoot, 'docs', 'midscene');
@@ -228,7 +230,7 @@ function normalizeSteps(steps: Array<Record<string, unknown>>) {
   });
 }
 
-export async function generatePlan(input: { prompt: string }) {
+export async function generatePlan(input: { prompt: string; signal?: AbortSignal }) {
   const startedAt = Date.now();
   const config = loadConfig();
 
@@ -241,24 +243,27 @@ export async function generatePlan(input: { prompt: string }) {
     baseURL: config.scriptOptimizer.model.baseUrl,
   });
 
-  const completion = await client.chat.completions.create({
-    model: config.scriptOptimizer.model.name,
-    temperature: 0.2,
-    messages: [
-      { role: 'system', content: systemPrompt },
-      { role: 'system', content: buildMidsceneDocsContext() },
-      {
-        role: 'user',
-        content: JSON.stringify(
-          {
-            prompt: input.prompt,
-          },
-          null,
-          2,
-        ),
-      },
-    ],
-  });
+  const completion = await client.chat.completions.create(
+    {
+      model: config.scriptOptimizer.model.name,
+      temperature: 0.2,
+      messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'system', content: buildMidsceneDocsContext() },
+        {
+          role: 'user',
+          content: JSON.stringify(
+            {
+              prompt: input.prompt,
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    },
+    { signal: input.signal },
+  );
 
   const content = completion.choices[0]?.message?.content;
   if (!content) {