android-midscene-automation 0.1.23 → 0.1.24

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 更新记录
 
+## v0.1.24
+
+- 参数配置的运行配置新增保存校验，Android SDK 路径必须包含 `platform-tools/adb`，回放报告目录必须填写已存在且可写入的绝对路径。
+- Midscene 自定义提供方的 `Model Name` 和 `Model Family` 改为输入框，方便填写官方支持列表之外的模型名称和模型系列。
+
 ## v0.1.23
 
 - 常见问题拆分为独立 `FAQ.md` 文档，并在 README 的“功能文档”中增加跳转入口。

package/README.md

@@ -52,7 +52,7 @@ npx android-midscene-automation --port 5174
 ## 功能文档
 
 - [Appium 录制器使用说明](#appium-录制器使用说明)
-- [常见问题](./FAQ.md)
+- [常见问题](#常见问题)
 - [项目更新记录](#项目更新记录)
 
 ## 源码开发
@@ -165,7 +165,7 @@ midscene_run/                  # Midscene 执行报告和运行产物
 
 本文档说明 Appium 组件树录制器的完整使用方式，包括每个操作按钮的用途、录制方法和示例。
 
-本文档随 npm 包发布，也可以从 README 的“功能文档”直接打开。常见问题请查看 [FAQ.md](./FAQ.md)。
+本文档随 npm 包发布，也可以从 README 的“功能文档”直接打开。常见问题请查看 [常见问题](#常见问题)。
 
 ## 使用前准备
 
@@ -1106,9 +1106,6 @@ output/2026-08-21_17-13-42-831-登录流程.html
 - 校验页面返回路径。
 - 校验返回后列表仍可见。
 
-## 常见问题
-
-常见问题已独立整理到 [FAQ.md](./FAQ.md)。
 
 ## 推荐录制规范
 
@@ -1120,8 +1117,105 @@ output/2026-08-21_17-13-42-831-登录流程.html
 - 给关键节点填写“登录按钮”“账号输入框”等备注，方便查看流程和报告。
 - 回放失败后优先查看“回放输出”中的失败节点、Activity 和 selector，再打开 `output` 中的 Markdown 报告查看完整配置。
 
+# 常见问题
+
+## 同一个 id 定位到错误输入框怎么办
+
+如果账号框和密码框都是 `id/tg_edit`，只按 id 回放可能输入到第一个输入框。
+
+建议：
+
+- 直接分别选择账号框和密码框录制输入。
+- 在节点详情里确认 selector 是否显示“重复 N”，以及“推荐定位”是否显示父级 + 子级。
+- 如果推荐定位不准确，展开录制步骤，手动修改父级上下文 selector。
+- 坐标点击只作为最后兜底。
+
+## 点击后没有检测到页面跳转怎么办
+
+可能原因：
+
+- 按钮当前禁用。
+- 账号密码不正确。
+- App 使用单 Activity，Activity 不变化。
+- 页面跳转依赖网络。
+
+推荐：
+
+- 使用“断言存在”判断下个页面核心元素。
+- 多 Activity 页面可以拆成两个脚本，在判断分支中用“连接脚本”串起来；回放会等待目标 Activity 出现。
+- 单 Activity App 不要依赖 Activity 变化，应使用页面核心元素判断是否已进入目标状态。
+
+## 为什么连接脚本提示入口 Activity 不匹配
+
+- 主流程连接要求目标脚本入口 Activity 与当前插入点一致，适合复用同一页面上的公共流程。
+- 登录后进入首页等跨 Activity 场景，应先添加“判断存在”，再在“是”或“否”分支中添加“连接脚本”。
+- 分支连接允许选择同一 App 的其他 Activity，但不会主动跳转页面；前面的点击或输入必须真正触发跳转。
+- 如果页面未跳转，回放会在等待目标 Activity 超时后失败，这是为了防止在错误页面执行目标脚本。
+
+## 为什么在桌面点击 App 后回放无效
+
+部分厂商系统会限制桌面或启动器页面的控件信息，Appium 可能无法获取桌面图标的稳定 id。此时在桌面录制“点击 App 图标”可能无法回放。
+
+建议在开始节点后添加“启动 App”操作，由系统按包名打开目标 App，替代桌面点击图标。需要重置登录态或缓存时，可以先添加“清理 App 缓存”，再添加“启动 App”。
+
+## 弹窗只出现一次怎么办
+
+使用“判断存在”。
+
+```text
+判断存在 确认按钮
+  是 -> 点击 确认按钮
+  否 -> 不添加操作
+```
+
+不要直接把弹窗确认按钮作为普通必选点击，否则弹窗不出现时脚本会失败。
+
+## 什么时候用等待 Activity
+
+适合多 Activity App。
+
+如果 App 是单 Activity 架构，优先用：
+
+```text
+断言存在 页面核心元素
+```
+
+## 什么时候用可选步骤
+
+可选步骤适合非主流程阻塞项：
+
+- 权限弹窗
+- 协议弹窗
+- 活动弹窗
+- 首次引导
+
+不建议把登录按钮、提交按钮、核心断言设置为可选。
+
+## 回放时出现 UiAutomation not connected 怎么办
+
+组件树刷新和 Appium 回放不能同时占用 UiAutomation。当前版本会在回放期间暂停组件树自动刷新，并在断开时清理残留抓取进程后重试一次。
+
+如果仍然失败：
+
+1. 确认手机保持解锁，USB 调试授权没有失效。
+2. 确认 Appium 和 UiAutomator2 Driver 已正常启动。
+3. 停止其他正在抓取同一设备组件树的工具。
+4. 重新连接设备后再次回放。
+
+## 设备预览或组件树没有更新怎么办
+
+1. 先确认设备仍显示在设备下拉框中。
+2. 点击设备预览刷新按钮重新获取画面。
+3. 点击“刷新组件树”重新抓取页面结构。
+4. 回放期间组件树自动刷新会暂停，回放完成后会自动恢复。
+
 # 项目更新记录
 
+## v0.1.24
+
+- 参数配置的运行配置新增保存校验，Android SDK 路径必须包含 `platform-tools/adb`，回放报告目录必须填写已存在且可写入的绝对路径。
+- Midscene 自定义提供方的 `Model Name` 和 `Model Family` 改为输入框，方便填写官方支持列表之外的模型名称和模型系列。
+
 ## v0.1.23
 
 - 常见问题拆分为独立 `FAQ.md` 文档，并在 README 的“功能文档”中增加跳转入口。

package/package.json

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

package/server/config.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import YAML from 'yaml';
 import { appDataPath } from './paths';
@@ -31,6 +32,14 @@ export type AppConfig = {
 let cachedConfig: AppConfig | null = null;
 const configPath = appDataPath('config.json');
 const legacyConfigPath = appDataPath('config.yaml');
+const adbFileName = process.platform === 'win32' ? 'adb.exe' : 'adb';
+
+export class ConfigValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConfigValidationError';
+  }
+}
 
 function defaultConfig(): AppConfig {
   return {
@@ -95,6 +104,65 @@ function normalizeConfig(config: Partial<AppConfig> | null | undefined): AppConf
   };
 }
 
+function expandRuntimePath(value: string) {
+  const trimmed = value.trim().replace(/^(["'])(.*)\1$/, '$2');
+  if (trimmed === '~') return os.homedir();
+  if (trimmed.startsWith(`~${path.sep}`) || trimmed.startsWith('~/')) {
+    return path.join(os.homedir(), trimmed.slice(2));
+  }
+  return path.isAbsolute(trimmed) ? path.normalize(trimmed) : appDataPath(trimmed);
+}
+
+function isAbsoluteRuntimePath(value: string) {
+  const trimmed = value.trim().replace(/^(["'])(.*)\1$/, '$2');
+  return trimmed === '~'
+    || trimmed.startsWith(`~${path.sep}`)
+    || trimmed.startsWith('~/')
+    || path.isAbsolute(trimmed);
+}
+
+function validateAndroidSdkPath(value: string) {
+  if (!value) return;
+  const candidate = expandRuntimePath(value);
+  const lowerBaseName = path.basename(candidate).toLowerCase();
+  const root = lowerBaseName === adbFileName.toLowerCase()
+    ? path.dirname(path.dirname(candidate))
+    : lowerBaseName === 'platform-tools'
+      ? path.dirname(candidate)
+      : candidate;
+  const adbPath = path.join(root, 'platform-tools', adbFileName);
+  if (!fs.existsSync(adbPath)) {
+    throw new ConfigValidationError(
+      `Android SDK 路径无效：${value}。请选择包含 platform-tools/${adbFileName} 的 SDK 目录。`,
+    );
+  }
+}
+
+function validateReportOutputPath(value: string) {
+  if (!value) return;
+  if (!isAbsoluteRuntimePath(value)) {
+    throw new ConfigValidationError(`回放报告目录无效：${value}。请填写绝对路径，或留空使用默认 output 目录。`);
+  }
+  const outputDir = expandRuntimePath(value);
+  try {
+    if (!fs.existsSync(outputDir)) {
+      throw new Error('目录不存在');
+    }
+    if (!fs.statSync(outputDir).isDirectory()) {
+      throw new Error('不是目录');
+    }
+    fs.accessSync(outputDir, fs.constants.W_OK);
+  } catch (error) {
+    const detail = error instanceof Error && error.message ? `（${error.message}）` : '';
+    throw new ConfigValidationError(`回放报告目录无效：${value}。请选择已经存在并可写入的目录${detail}。`);
+  }
+}
+
+function validateRuntimeConfig(config: AppConfig) {
+  validateAndroidSdkPath(config.runtime.androidSdkPath);
+  validateReportOutputPath(config.runtime.reportOutputPath);
+}
+
 export function loadConfig(): AppConfig {
   if (cachedConfig) {
     return cachedConfig;
@@ -126,7 +194,9 @@ export function loadConfig(): AppConfig {
 }
 
 export function saveConfig(config: AppConfig) {
-  cachedConfig = normalizeConfig(config);
+  const normalized = normalizeConfig(config);
+  validateRuntimeConfig(normalized);
+  cachedConfig = normalized;
   saveModelConfigToDb(cachedConfig);
 }
 

package/server/http-api.ts

@@ -9,7 +9,7 @@ type NextHandleFunction = (req: IncomingMessage, res: ServerResponse, next: Next
 
 import { execFile, spawn } from 'node:child_process';
 import { appPath } from './paths';
-import { loadConfig, saveConfig, type AppConfig } from './config';
+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';
@@ -648,7 +648,7 @@ export function createApiMiddleware() {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ success: true }));
       } catch (error) {
-        res.statusCode = 500;
+        res.statusCode = error instanceof ConfigValidationError ? 400 : 500;
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.end(JSON.stringify({ message: error instanceof Error ? error.message : 'Unknown error' }));
       }

package/src/pages/ConfigPage.vue

@@ -1,11 +1,9 @@
 <script setup lang="ts">
 import { computed } from 'vue';
-import { Delete, Edit } from '@element-plus/icons-vue';
+import { Delete, Edit, QuestionFilled } from '@element-plus/icons-vue';
 import ModelUsageChart from '../components/config/ModelUsageChart.vue';
 import {
   codexMidsceneModelOptions,
-  midsceneModelFamilyOptions,
-  midsceneModelOptions,
   midsceneModelPresets,
   type MidsceneModelProvider,
   type MidsceneModelPresetKey,
@@ -45,6 +43,7 @@ const emit = defineEmits<{
 const activeMidsceneProvider = computed<MidsceneModelProvider>(() =>
   props.configForm.midscene.model.provider === 'codex' ? 'codex' : 'custom',
 );
+const modelConfigGuideUrl = 'https://midscenejs.com/zh/model-common-config.html';
 
 const activeMidscenePresetKey = computed(() => {
   const model = props.configForm.midscene.model;
@@ -56,13 +55,9 @@ const activeMidscenePresetKey = computed(() => {
   )?.key || '';
 });
 
-const activeMidsceneModelOptions = computed(() =>
-  activeMidsceneProvider.value === 'codex' ? codexMidsceneModelOptions : midsceneModelOptions,
-);
-
 const updateMidsceneModelName = (value: string) => {
   props.configForm.midscene.model.name = value;
-  const option = activeMidsceneModelOptions.value.find((item) => item.value === value);
+  const option = codexMidsceneModelOptions.find((item) => item.value === value);
   if (option) {
     props.configForm.midscene.model.family = option.family;
   }
@@ -79,6 +74,10 @@ const updateMidsceneProvider = (value: string) => {
     emit('updateMidsceneModelProvider', value);
   }
 };
+
+const openModelConfigGuide = () => {
+  window.open(modelConfigGuideUrl, '_blank', 'noopener,noreferrer');
+};
 </script>
 
 <template>
@@ -204,29 +203,41 @@ const updateMidsceneProvider = (value: string) => {
                 <el-form-item label="API Key">
                   <el-input v-model="configForm.midscene.model.apiKey" show-password />
                 </el-form-item>
-                <el-form-item label="Model Name">
-                  <el-select
-                    :model-value="configForm.midscene.model.name"
-                    filterable
-                    @change="updateMidsceneModelName"
-                  >
-                    <el-option
-                      v-for="option in activeMidsceneModelOptions"
-                      :key="option.value"
-                      :label="option.label"
-                      :value="option.value"
-                    />
-                  </el-select>
+                <el-form-item>
+                  <template #label>
+                    <span class="config-field-label">
+                      <span>Model Name</span>
+                      <el-tooltip content="查看模型填写参考" placement="top">
+                        <el-button
+                          class="config-field-help"
+                          text
+                          size="small"
+                          :icon="QuestionFilled"
+                          aria-label="查看 Model Name 填写参考"
+                          @click.stop="openModelConfigGuide"
+                        />
+                      </el-tooltip>
+                    </span>
+                  </template>
+                  <el-input v-model="configForm.midscene.model.name" placeholder="例如：gpt-5.5" />
                 </el-form-item>
-                <el-form-item label="Model Family">
-                  <el-select v-model="configForm.midscene.model.family" filterable>
-                    <el-option
-                      v-for="option in midsceneModelFamilyOptions"
-                      :key="option.value"
-                      :label="option.label"
-                      :value="option.value"
-                    />
-                  </el-select>
+                <el-form-item>
+                  <template #label>
+                    <span class="config-field-label">
+                      <span>Model Family</span>
+                      <el-tooltip content="查看模型填写参考" placement="top">
+                        <el-button
+                          class="config-field-help"
+                          text
+                          size="small"
+                          :icon="QuestionFilled"
+                          aria-label="查看 Model Family 填写参考"
+                          @click.stop="openModelConfigGuide"
+                        />
+                      </el-tooltip>
+                    </span>
+                  </template>
+                  <el-input v-model="configForm.midscene.model.family" placeholder="例如：gpt-5" />
                 </el-form-item>
               </template>
 
@@ -246,7 +257,7 @@ const updateMidsceneProvider = (value: string) => {
                     @change="updateMidsceneModelName"
                   >
                     <el-option
-                      v-for="option in activeMidsceneModelOptions"
+                      v-for="option in codexMidsceneModelOptions"
                       :key="option.value"
                       :label="option.label"
                       :value="option.value"

package/src/style.css

@@ -1587,6 +1587,18 @@ select {
   gap: 8px;
 }
 
+.config-field-label {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.config-field-help.el-button {
+  height: 18px;
+  padding: 0;
+  color: var(--el-text-color-secondary);
+}
+
 .config-module-card {
   min-width: 0;
 }