android-midscene-automation 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # 更新记录
 
+## v0.1.15
+
+- README 新增 Midscene 与 Appium 两种测试方式对比，明确 Midscene 必须配置模型，Appium 不依赖模型。
+- README 环境要求补充 Appium 3.x、UiAutomator2 Driver 的安装与启动说明。
+
+## v0.1.14
+
+- 参数配置新增 Android SDK 路径和 Appium 回放报告目录；留空时分别读取系统默认 SDK 和启动目录下的 `output`。
+- Appium 回放前新增 Android SDK 检测，并让设备列表、预览、组件树、设备操作和回放统一使用配置的 SDK 中的 ADB。
+- Appium 回放结束后自动在 `output` 目录生成 Markdown 报告，记录每个节点的配置、执行状态与完整回放日志，并将报告路径保存到数据库。
+- Appium 脚本列表新增 JSON 脚本导入和下载功能；导入重名脚本时自动生成新名称。
+- Appium 回放修复分支内末尾连接脚本被误当成全局连接执行的问题；连接脚本前会等待目标 Activity，减少页面切换尚未完成造成的误报。
+- Appium 判断节点的模糊文本匹配会统一换行和连续空白，避免录制文本与 Appium 返回文本仅因排版差异而误判为不存在。
+- Appium 设备预览恢复复用 Midscene Playground 的 scrcpy 实时流；仅在实时流不可用时启用 ADB 截图轮询，避免停帧和两种预览源相互覆盖。
+- Playground 代理补充 action-space 和 execute 路径，修复嵌入式设备预览初始化时的 404 错误。
+- Appium 组件树在当前 Activity 或页面结构变化后自动刷新，保留仍存在的已选节点，并避免与录制、回放和手动刷新并发。
+- Appium 回放与组件树的 `uiautomator dump` 按设备互斥：回放前等待正在进行的抓取结束，回放期间暂停新抓取，并在 `UiAutomation not connected` 时清理残留进程后自动重试一次。
+- Appium 判断分支中的连接脚本允许选择同一 App 的其他 Activity 脚本；回放到连接节点时等待目标入口 Activity，未真正跳转则超时失败。
+- Appium 回放输出改为 NDJSON 流式传输，节点开始、结果、完成、失败和报告路径会在执行过程中实时追加到回放日志。
+- Appium 线性脚本和流程图脚本的回放日志统一使用“[节点 N]”编号，不再混用“步骤”和“节点”。
+- Appium 判断分支后的主流程节点按实际前驱分支定位：单分支连接时沿该分支中轴继续排列，双分支汇合时回到中轴，后续线性节点继承前一节点位置。
+- Appium 流程节点新增备注字段，可在节点配置中编辑，并显示在操作描述下方。
+- 浏览器刷新后保持当前功能页面和 Appium 工作区 Tab；Appium 录制存在未保存修改时，刷新或关闭页面前显示保存提醒。
+- Appium 模块：“启动 APP”流程节点新增立即执行操作，可从系统桌面直接启动当前预设应用，并在刷新 Activity 后自动解除匹配页面的编辑锁定。
+- Appium 模块：Activity 不匹配时仍可使用开始节点和步骤节点的插入菜单；“启动 APP”仅保留在开始节点，普通节点提供其余操作。
+- Appium 模块：回放前检测目标 App 是否已在前台；已启动时关闭 Appium 自动拉起并跳过“启动 APP”节点，保留当前页面状态。
+- Appium 模块：判断节点移除后续节点下拉配置，是/否分支改为通过“连接下一节点”按钮自动连接判断后的主流程节点。
+- Appium 模块：“判断存在”支持按指定文本判断，可选择模糊匹配或精准匹配。
+- Appium 模块：判断节点的配置面板移动到当前节点正下方，不再显示在分支子节点末尾。
+- Appium 模块：分支子节点支持点击展开配置，节点尺寸与主流程节点保持一致。
+- Appium 模块：流程总览弹窗支持点击主流程和分支节点并直接修改配置。
+- Appium 模块：节点配置面板移除重复的“插入延时”按钮，延时统一从流程“插入操作”菜单添加。
+- Appium 模块：三列工作区比例调整为 3:3:4，缩小组件树区域并扩大录制与脚本区域。
+- Appium 模块：判断分支连接后使用流程线连接后续主节点，连接按钮切换为“取消连接”并支持解除连线。
+
 ## v0.1.13
 
 - Appium 模块：修复加载历史脚本并新增节点后被误判为新脚本、无法覆盖保存的问题。

package/README.md

@@ -1,15 +1,36 @@
 # Android Midscene Automation
 
-一个最小可用的 Midscene + Playwright 项目，同时提供一个基于 Vue 3 和 Element Plus 的后台，用来把自然语言 prompt 生成结构化自动化脚本。
+一个面向 Android App 的自动化测试工具，同时支持 Midscene AI 测试和 Appium 组件树录制回放。
+
+## 支持的测试方式
+
+| 测试方式 | 页面入口 | 工作方式 | 模型要求 | 适用场景 |
+| --- | --- | --- | --- | --- |
+| Midscene | `Midscene > 测试脚本生成 / 自动化测试` | 使用自然语言生成和执行测试脚本，通过多模态模型理解设备画面 | **必须配置模型** | 页面元素难以稳定定位、希望使用自然语言快速编写测试 |
+| Appium | `Appium` | 读取 Android 组件树，按 selector、组件 ID 和流程图录制、回放 | **不需要配置任何模型** | 需要稳定、可重复、无模型消耗的传统自动化测试 |
+
+使用 Midscene 前，请先进入“参数配置”完成 `Midscene 模型` 配置；需要 AI 生成脚本时，还要配置 `脚本优化模型`。模型配置不可用时，Midscene 脚本无法正常生成或执行。
+
+Appium 方案完全不依赖大模型，不需要填写 Base URL、API Key、Model Name 等模型参数。使用前只需连接 Android 设备、准备 Android SDK / ADB，并启动 Appium 服务。
 
 ## 环境要求
 
 - Node.js 18+
 - npm
 - Android SDK / ADB，移动端自动化测试需要
+- Appium 3.x 和 UiAutomator2 Driver，仅 Appium 录制回放方式需要
 - Playwright Chromium，Web 示例脚本需要
 
-## 一行启动
+安装 Appium 相关依赖：
+
+```sh
+npm install -g appium@3.5.0
+appium driver install uiautomator2
+```
+
+使用 Appium 方式前需要运行 `appium` 启动服务；只使用 Midscene 时不需要安装或启动 Appium。
+
+## 启动
 
 ```sh
 npx android-midscene-automation
@@ -21,12 +42,6 @@ npx android-midscene-automation
 http://127.0.0.1:5173/
 ```
 
-如果还没有发布到 npm，也可以用 GitHub 地址运行：
-
-```sh
-npx github:你的组织/你的仓库
-```
-
 每个测试人员在自己的电脑运行这条命令，后端执行的就是当前电脑上的 `adb devices`，页面会识别当前电脑连接的手机。
 
 如果 `5173` 端口被占用，可以指定端口：
@@ -35,6 +50,11 @@ npx github:你的组织/你的仓库
 npx android-midscene-automation --port 5174
 ```
 
+## 功能文档
+
+- [Appium 录制器使用说明](https://cdn.jsdelivr.net/npm/android-midscene-automation@latest/USAGE.md)
+- [项目更新记录](https://cdn.jsdelivr.net/npm/android-midscene-automation@latest/CHANGELOG.md)
+
 ## 源码开发
 
 ```sh
@@ -64,8 +84,9 @@ http://127.0.0.1:5173/
 
 ## 模型配置
 
-首次启动后进入页面的“参数配置”：
+模型配置仅用于 Midscene 和 AI 脚本生成，Appium 录制与回放不读取模型配置。首次使用 Midscene 时进入页面的“参数配置”：
 
+- `运行配置`：可选指定 Android SDK 根目录和 Appium 回放报告目录；留空时使用系统 SDK 与默认 `output` 目录。
 - `Midscene模型`：执行测试脚本时使用，支持“自定义提供方”和“使用 Codex”。
 - `AI生成脚本模型`：根据测试需求生成脚本时使用。
 
@@ -77,28 +98,6 @@ http://127.0.0.1:5173/
 
 旧版 `config.yaml` 或 `config.json` 会在读取后迁移到数据库。当前运行时会优先读取数据库中的模型配置。
 
-## 后端说明
-
-本项目的本地后端位于 `server/http-api.ts`，通过 `/api/*` 暴露能力，主要包括：
-
-- 脚本生成：`POST /api/generate`
-- 脚本保存和列表：`POST /api/save-script`、`GET /api/scripts`
-- 脚本执行和停止：`POST /api/run-script`、`POST /api/stop-script`
-- 模型配置：`GET /api/config`、`POST /api/config`
-- 模型测试和消耗统计：`POST /api/test-model`、`GET /api/model-usage-records`
-- Android 设备：`GET /api/android-devices`、`POST /api/android-device`
-- Android 预览和操作：`GET /api/android-preview`、`POST /api/android-tap`、`POST /api/android-swipe`、`POST /api/android-keyevent`
-- App 预设：`GET /api/app-presets`、`POST /api/save-app-preset`、`POST /api/delete-app-preset`
-
-后端运行态文件默认都在项目根目录下：
-
-```text
-.midscene-app/                 # SQLite 数据库
-.midscene-generated/           # 执行前生成的临时脚本
-scripts-output/                # 保存的脚本输出
-midscene_run/                  # Midscene 执行报告和运行产物
-```
-
 ## Android 自动化
 
 执行移动端脚本前确认设备已连接：
@@ -107,9 +106,9 @@ midscene_run/                  # Midscene 执行报告和运行产物
 adb devices -l
 ```
 
-页面会通过 `/api/android-devices` 获取设备列表。执行脚本时会把当前选择的设备 ID 传给后端，由 `@midscene/android` 连接设备并运行生成脚本。
+页面会通过 `/api/android-devices` 获取设备列表。Midscene 执行时由 `@midscene/android` 连接设备并运行生成脚本；Appium 执行时使用组件树和已录制的流程，不调用大模型。
 
-如果要走不依赖大模型的 Appium 组件树录制方案，源码仓库里的 `demo` 目录保留了方案文档；npm 包不会发布 `demo` 目录。
+如果要走不依赖大模型的 Appium 组件树录制方案，可查看项目的 Appium 录制器使用说明。
 
 如果测试人员需要识别自己电脑上的手机，推荐每个人在自己的电脑本地运行：
 
@@ -131,26 +130,25 @@ http://localhost:5173/
 appium
 ```
 
-## 功能文档
-
-- [项目更新记录](https://cdn.jsdelivr.net/npm/android-midscene-automation@latest/CHANGELOG.md)
-
-## 运行 E2E 测试
-
-```sh
-npm run test:e2e
-```
+## 后端说明
 
-## 构建
+本项目的本地后端位于 `server/http-api.ts`，通过 `/api/*` 暴露能力，主要包括：
 
-```sh
-npm run build
-```
+- 脚本生成：`POST /api/generate`
+- 脚本保存和列表：`POST /api/save-script`、`GET /api/scripts`
+- 脚本执行和停止：`POST /api/run-script`、`POST /api/stop-script`
+- 模型配置：`GET /api/config`、`POST /api/config`
+- 模型测试和消耗统计：`POST /api/test-model`、`GET /api/model-usage-records`
+- Android 设备：`GET /api/android-devices`、`POST /api/android-device`
+- Android 预览和操作：`GET /api/android-preview`、`POST /api/android-tap`、`POST /api/android-swipe`、`POST /api/android-keyevent`
+- App 预设：`GET /api/app-presets`、`POST /api/save-app-preset`、`POST /api/delete-app-preset`
 
-## 本地预览构建结果
+后端运行态文件默认都在项目根目录下：
 
-```sh
-npm run preview
+```text
+.midscene-app/                 # SQLite 数据库
+.midscene-generated/           # 执行前生成的临时脚本
+scripts-output/                # 保存的脚本输出
+output/                        # Appium 回放 Markdown 报告（可在运行配置中修改）
+midscene_run/                  # Midscene 执行报告和运行产物
 ```
-
-`npm run preview` 同样会挂载 `/api/*` 后端 middleware。