一个面向 Android App 的自动化测试工具，集成 Appium 组件树录制回放、Artemis 自然语言任务执行和 Midscene AI 测试。
| 测试方式 | 页面入口 | 工作方式 | 模型要求 | 适用场景 |
|---|---|---|---|---|
| Appium | Appium |
读取 Android 组件树，按 selector、组件 ID 和流程图录制、回放 | 不需要配置任何模型 | 需要稳定、可重复、无模型消耗的传统自动化测试 |
| Artemis | Artemis |
使用自然语言描述目标，AI 自主规划并操作设备，记录步骤、结果和任务笔记 | 必须配置模型，独立配置 | 探索性测试、多步骤业务任务、画面检查与数据收集 |
| Midscene | Midscene > 测试脚本生成 / 自动化测试 |
使用自然语言生成和执行测试脚本，通过多模态模型理解设备画面 | 必须配置模型 | 页面元素难以稳定定位、希望使用自然语言快速编写测试 |
使用 Midscene 前，请先进入“参数配置”完成 Midscene 模型 配置；需要 AI 生成脚本时，还要配置 脚本优化模型。模型配置不可用时，Midscene 脚本无法正常生成或执行。
Appium 方案完全不依赖大模型，不需要填写 Base URL、API Key、Model Name 等模型参数。使用前只需连接 Android 设备、准备 Android SDK / ADB，并启动 Appium 服务。
- Node.js：运行主项目需要符合 Vite 7 的要求（20.19+ 或 22.12+）；同时使用 Artemis 前端时按其 Angular 依赖要求准备 Node.js，当前集成使用 22.22.3+（22 LTS）。
- npm。
- Android SDK / ADB，移动端自动化测试需要。
- Appium 3.x 和 UiAutomator2 Driver，仅 Appium 录制回放方式需要。
- uv 和 Python 3.12+，仅 Artemis 需要。
安装 Appium 相关依赖：
npm install -g appium@3.5.0
appium driver install uiautomator2使用 Appium 方式前需要运行 appium 启动服务；只使用 Artemis 或 Midscene 时不需要安装或启动 Appium。
菜单中的 Artemis 在主内容区嵌入独立的 Artemis 控制台，支持切换菜单后保留页面状态。首次连接和“重新连接”都会检查服务；未启动或未允许嵌入时显示操作提示。
- Artemis 源码独立放在项目根目录的
artemis-main/，或通过ARTEMIS_PROJECT_DIR指定源码绝对路径。artemis-main/源码随主项目的 Git / npm 包分发。本地config/artemis.jsonc、.env、依赖环境和运行数据不提交、不打包；首次启动会从公开的config/artemis.example.jsonc生成本地配置，已有配置不会被覆盖。 - 安装
uv，准备 Python 3.12+、Node.js 22.22.3+（22 LTS）、ADB 和设备；Artemis 前端首次启动时会自动安装依赖并构建。 - 在项目根目录运行
npm run dev，或使用npx android-midscene-automation，会同时启动主项目与 Artemis；首次会同步 Python 依赖并按需构建 Artemis 前端。启动完成后点击 Artemis。API Key、模型和设备在 Artemis 自身的配置中设置，不会自动复用 Midscene 的模型配置。
检测到 Artemis 已运行时会复用该服务；按 Ctrl+C 会停止本次启动的服务，不会停止之前已运行的 Artemis。缺少源码或 Artemis 启动失败时会输出提示，主项目仍可使用。仍可通过 npm run artemis 单独启动 Artemis。主项目端口被占用时会明确报错，可通过 npm run dev -- --port 5174 指定其他端口，并自动为新启动的 Artemis 配置对应的嵌入来源。
在 Artemis 的“系统设置 → 自定义配置”中点击“编辑 JSONC”，可直接修改并保存当前使用的 artemis.jsonc；支持注释和原有排版，保存前校验 JSONC、模型与智能体配置。文件已被其他操作修改时会阻止覆盖，保存失败时保留草稿。“取消编辑”放弃本次修改并重新加载文件。模型配置用于新任务，运行中的任务保持当前设置；API Key 和接口地址仍在 Artemis 的 .env 中配置。
修改配置文件或 .env 后，点击自定义配置中的“刷新配置”，会重新校验 JSONC 并加载模型密钥和 Base URL，更新“已配置 / 未设置”状态，无需重启服务。刷新只检查本地配置，不调用模型 API 验证密钥；正在编辑草稿时按钮禁用，校验失败时保留当前已加载设置。
专用启动入口仅绑定 127.0.0.1:8000，通过 CSP 允许 localhost / 127.0.0.1 的 5173、4173 端口嵌入，并保留 Artemis 原有的 Host / Origin 校验。原来的 artemis ui 默认禁止 iframe；若已启动，需要先停止原服务再执行 npm run artemis。终端按 Ctrl+C 停止服务。
可选环境变量：
| 变量 | 用途 |
|---|---|
ARTEMIS_PROJECT_DIR |
Artemis 源码目录，传给 npm run dev 或 npm run artemis |
ARTEMIS_PORT |
Artemis 服务端口，默认 8000 |
ARTEMIS_EMBED_ORIGINS |
允许嵌入的完整来源地址，逗号分隔；主项目使用其他端口时需设置，不接受通配符 |
ARTEMIS_URL |
主项目后端连接的 Artemis 地址，默认 http://127.0.0.1:8000，传给 npm run dev 或 npm run preview |
ARTEMIS_AUTO_START |
设置为 0 时，npm run dev 仅启动主项目；默认自动启动 Artemis |
当前集成面向本机使用。Artemis 与 Midscene/Appium 的任务队列、设备锁和结果各自独立，请不要同时控制同一台设备。
-
连接并解锁 Android 设备，开启 USB 调试，在终端运行
adb devices -l，确认设备状态为device，并在手机上允许调试授权。 -
首次启动后，按下方说明配置
artemis-main/.env和artemis-main/config/artemis.jsonc，然后在“系统设置 → 自定义配置”点击“刷新配置”。 -
点击主项目菜单中的 Artemis，在 Artemis 控制台的设备选择入口选择实际连接的设备，再选择 Flash 或 Pro 执行模式。模式名称与模型名称不同，例如 Pro 模式也可以使用自定义的 MiniMax 模型。
-
输入自然语言任务并提交。任务应明确目标 App、操作范围和可观察的完成条件，例如：
打开 Android 设置，查看设备型号和 Android 版本，返回查到的信息后结束任务。
-
在执行视图查看步骤、模型调用、错误与结果；需要中止时使用停止按钮。选择历史任务可以查看对应记录。右上角中英文切换按钮用于切换控制台界面语言，任务描述可以使用中文。
Artemis 不读取主项目“参数配置”中的 Midscene 模型。其模型名称、节点和备用模型写在 JSONC 中，API Key 与接口地址写在 .env 中：
| 你获得的参数 | Artemis 配置位置 | 示例字段 |
|---|---|---|
| API Key | artemis-main/.env |
OPENAI_API_KEY |
| Base URL | artemis-main/.env |
OPENAI_BASE_URL |
| Model Name | artemis-main/config/artemis.jsonc |
default.model 与 default.fallback.model |
| 接口类型 | artemis-main/config/artemis.jsonc |
OpenAI 兼容接口使用 provider: "openai" |
首次准备 .env 时，从项目根目录执行以下命令；如果文件已存在，直接编辑已有文件：
cp -n artemis-main/.env.example artemis-main/.env编辑 .env，使用模型服务商给出的 OpenAI 兼容接口地址和密钥。地址通常包含 /v1，应填写接口基地址，不要填写完整的 /chat/completions 请求路径：
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://your-provider.example/v1通过“编辑 JSONC”修改本地配置，例如：
将占位名称替换为服务商提供的实际模型名称。没有其他备用模型时，fallback 可以使用同一模型，但不会提供跨模型容错。nodes 用于覆盖指定节点的模型；没有覆盖的节点继承 default。切换提供方时也要检查原有节点及其 fallback，避免仍引用其他提供方的模型。
GLM、DeepSeek、MiniMax 等提供 OpenAI 兼容接口的服务可按此结构配置，但用于屏幕理解的模型还需要支持图片输入与所需的工具调用；接口兼容不代表每个模型型号都能完成设备任务。配置 Gemini 时使用 provider: "google"，并在 .env 中填写 GOOGLE_API_KEY 或 GEMINI_API_KEY。
保存 JSONC 后点击“刷新配置”检查本地设置。出现“已配置”表示字段已读取，不代表 API Key、模型权限或多模态能力已通过在线验证。修改 Python 源码后需重启 Artemis；“刷新配置”不会重新加载源码。
| 模式 | 执行方式 | 适用任务 | 笔记与计划 |
|---|---|---|---|
| Flash | 根据当前画面直接决策、操作，流程较简洁 | 打开页面、短流程操作、简单查询 | 当前未提供笔记读写工具，页签可能为空 |
| Pro | 先规划，再执行与校验，任务结束前进行最终检查 | 多步骤任务、需要过程证据或整理结果的测试 | 可生成计划和任务笔记 |
Pro 任务完成设备操作后，仍可能继续回看截图、检查结果、等待步骤摘要和生成录像。计划全部勾选不代表服务已完成收尾，以最终任务状态为准。
“笔记与计划”用于查看当前或历史任务中 AI 保存的记录，页面目前不提供直接编辑操作：
task_plan.md：任务步骤和执行进度，显示待执行、执行中及完成状态。- 其他笔记：保存采集数据、观察结果或任务总结；有多个文件时点击名称切换查看。
在 Pro 模式的任务描述中明确要求记录，例如：
打开设置，查看设备型号和 Android 版本。执行前制定任务计划，将查到的信息保存到 device_info 笔记中，完成后更新计划并返回结果。
笔记按任务保存，用于同一任务内的持续记忆，不会自动成为所有后续任务共享的知识库。
默认执行数据保存在 artemis-main/traces/，临时数据保存在 artemis-main/scratch/；自定义 TRACES_PATH 或运行参数时，以实际配置的输出位置为准。
| 路径 | 内容 | Git / npm 分发 |
|---|---|---|
artemis-main/config/artemis.example.jsonc |
不含密钥的公开默认配置 | 随源码分发 |
artemis-main/config/artemis.jsonc |
本机实际使用的模型与智能体配置 | 已忽略，不提交、不打包 |
artemis-main/.env |
本机模型密钥、Base URL 等设置 | 已忽略，不提交、不打包 |
artemis-main/traces/ |
执行数据库、步骤截图、录像、回放数据、任务笔记和计划 | 已忽略，不提交、不打包 |
artemis-main/scratch/ |
执行过程临时文件 | 已忽略，不提交、不打包 |
执行记录写入本地不会自动执行 Git 提交或推送，正常 git add . 不会包含上述已忽略的文件。这里说明的是 Git/npm 分发范围；执行 AI 任务时，模型调用仍会向所配置的服务商发送任务所需的文本和图片。
- 控制台无法连接：检查启动终端的日志，确认
uv、Python、Node.js 和前端构建依赖可用，再运行npm run artemis。若使用其他端口，检查ARTEMIS_URL、ARTEMIS_PORT和嵌入来源是否一致。 - 模型仍显示“未设置”：确认修改的是当前
ARTEMIS_PROJECT_DIR下的.env与config/artemis.jsonc，再点击“刷新配置”；主项目的 Midscene 配置不会同步到 Artemis。 - 没有实际设备：运行
adb devices -l，检查 USB 调试授权、设备连接，以及 Artemis 的ADB_HOST、ADB_PORT。任务使用 Artemis 中选择的设备。 - 视频工具链提示缺少 scrcpy / ffmpeg：在“系统设置”的视频工具链检查中查看缺失项目，安装后确认启动 Artemis 的终端能找到工具；终端 PATH 改变后重新启动服务。
- 任务看起来没有结束：查看最近步骤和日志，区分正在操作、等待模型、错误暂停与 Pro 最终检查。记录任务 ID 可用于定位日志；需要结束当前任务时使用停止按钮。
- 自定义模型输出解析失败：本项目已为非 Google 模型的 Pydantic 结构化输出接入思考标签清理、JSON 提取和校验，格式错误时要求模型纠正一次；持续错误仍会报告失败。纯文本步骤摘要也会清理思考内容，避免将其计入摘要长度。
上述模型适配修复属于本项目集成源码的修改，并不代表 Artemis 上游已包含相同修复。
npx --yes android-midscene-automation@latest启动后访问：
http://127.0.0.1:5173/
每个测试人员在自己的电脑运行这条命令，后端执行的就是当前电脑上的 adb devices，页面会识别当前电脑连接的手机。
如果 5173 端口被占用，可以指定端口：
npx android-midscene-automation --port 5174npm install
npm run devMidscene Android 测试和 Appium 测试都不需要 Playwright Chromium。只有运行源码中的 Web E2E 示例时才需要单独安装：
npx playwright install chromiumPlaywright 浏览器下载不走 npm registry。下载较慢时，可临时指定镜像：
PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/ npx playwright install chromiumnpm run dev启动后访问 Vite 输出的本机地址。项目默认只监听 127.0.0.1：
http://127.0.0.1:5173/
npm run dev 会同时启动前端页面、本地后端 API 和独立的 Artemis 服务。主项目后端不是独立进程，而是在 vite.config.ts 中通过 server/http-api.ts 挂载到 Vite dev server 的 Connect middleware。
本节的“参数配置”仅用于 Midscene 和 AI 脚本生成，Appium 录制与回放不读取这些模型配置。Artemis 使用自己的 JSONC 与 .env，详见 Artemis 使用说明。首次使用 Midscene 时进入页面的“参数配置”：
运行配置：可选指定 Android SDK 根目录和 Appium 回放报告目录；留空时使用系统 SDK 与默认output目录。Midscene模型：执行测试脚本时使用，支持“自定义提供方”和“使用 Codex”。AI生成脚本模型：根据测试需求生成脚本时使用。
使用 npx android-midscene-automation 启动时，配置会保存到固定的系统用户数据目录：
Windows: %LOCALAPPDATA%\android-midscene-automation\.midscene-app\script-cache.sqlite
macOS: ~/Library/Application Support/android-midscene-automation/.midscene-app/script-cache.sqlite
Linux: ~/.local/share/android-midscene-automation/.midscene-app/script-cache.sqlite
也可以通过 ANDROID_MIDSCENE_DATA_ROOT 指定自定义数据目录。使用 npm run dev 本地开发时，默认仍写入项目根目录。
旧版 config.yaml 或 config.json 会在读取后迁移到数据库。当前运行时会优先读取数据库中的模型配置。
执行移动端脚本前确认设备已连接：
adb devices -l页面会通过 /api/android-devices 获取设备列表。Midscene 执行时由 @midscene/android 连接设备并运行生成脚本；Appium 执行时使用组件树和已录制的流程，不调用大模型。
如果要走不依赖大模型的 Appium 组件树录制方案，可查看项目的 Appium 录制器使用说明。
如果测试人员需要识别自己电脑上的手机，推荐每个人在自己的电脑本地运行：
npx android-midscene-automation然后访问自己本机的：
http://localhost:5173/
这样后端执行的是当前电脑上的 adb devices，页面会识别当前电脑连接的手机。
如果要回放 Appium 脚本，本机还需要启动 Appium：
appium本项目的本地后端位于 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
使用 npx android-midscene-automation 启动时，后端运行态文件默认都在系统用户数据目录下；使用 npm run dev 本地开发时，默认在项目根目录下。可以通过 ANDROID_MIDSCENE_DATA_ROOT 覆盖数据目录：
.midscene-app/ # SQLite 数据库
.midscene-generated/ # 执行前生成的临时脚本
scripts-output/ # 保存的脚本输出
output/ # Appium 回放 Markdown 报告（可在运行配置中修改）
midscene_run/ # Midscene 执行报告和运行产物
本文档说明 Appium 组件树录制器的完整使用方式，包括每个操作按钮的用途、录制方法和示例。
本文档随 npm 包发布，也可以从 README 的“功能文档”直接打开。常见问题请查看 常见问题。
Appium 各流程节点的用途和配置方式，请查看 流程节点操作说明。AI 识别的场景选择、预设提示词、持续观察、分支、截图去重及超时配置，请查看 AI 识别操作说明。
点击侧边栏最下方的问号图标，可以在“帮助与版本”窗口中查看：
- 当前工具版本和对应的 Midscene 版本。
- Vue、Element Plus、Appium、Midscene、Vue Flow、OpenCV.js、Vite 和 TypeScript 等主要技术及版本。
- 本操作说明。
- 常见问题和各版本更新记录。
Midscene 操作说明读取 USAGE.md，Appium 操作说明读取 流程节点操作说明.md，AI 识别操作说明读取 AI识别操作说明.md，常见问题和更新记录分别读取 FAQ.md 与 CHANGELOG.md；文档更新后页面内容会同步更新。
进入“参数配置”，在 Midscene 模型区域选择模型提供方并填写所需参数。Midscene 执行依赖支持图片输入的多模态模型，填写后应先点击测试，确认模型可以正常响应。
进入“Midscene > 测试脚本生成”，填写脚本名称、场景标题、目标 App 和测试需求，也可以上传用例文件。点击“AI 生成”后检查生成步骤，确保测试数据、操作目标和成功条件准确。
在测试脚本生成页面切换到“自定义步骤编排”，可以逐条添加操作、等待、查询和判断步骤。每条指令只描述一个明确目标，页面跳转后使用可观察的页面元素作为等待条件。
生成脚本后可以查看、编辑或复制代码。确认内容后点击“保存脚本”，保存的脚本会出现在“自动化测试”页面中。
进入“Midscene > 自动化测试”，选择脚本和 Android 设备后点击“开始执行”。执行期间保持设备亮屏和解锁，Midscene 会根据当前画面理解目标并执行操作。
脚本运行期间点击顶部“停止执行”可以中止后续步骤。停止后查看执行输出，确认最后完成的步骤和停止位置。
自动化测试页面会实时显示步骤状态、耗时和错误信息。执行失败时先检查模型配置、ADB 连接、设备画面以及指令中的目标描述是否清晰。
一条指令只完成一个目标；输入、点击和等待尽量拆分；等待条件应描述页面中可观察到的稳定元素；不要在同一步骤中同时处理大量弹窗和业务操作。组件 ID 稳定并需要大量重复回放时，可以改用 Appium 流程。
adb devices -l确认设备已连接，并且手机已允许 USB 调试。
appium如果没有安装 UiAutomator2 Driver：
appium driver install uiautomator2npx --yes android-midscene-automation@latest或源码开发：
npm install
npm run dev打开页面后进入 Appium 菜单。
进入“参数配置 > 运行配置”可以设置：
Android SDK 路径：填写包含platform-tools/adb的 SDK 根目录。留空时依次读取ANDROID_SDK_ROOT、ANDROID_HOME、系统常见 SDK 目录和 PATH 中的 ADB。回放报告目录：填写 Markdown 回放报告的保存目录。支持绝对路径；相对路径以启动命令所在目录为基准。留空时使用启动目录下的output。
回放开始前会检测 Android SDK。检测失败时不会创建 Appium session，回放输出会直接显示需要修正的 SDK 路径。
- 选择设备。
- 在“参数配置”中添加预设 App 参数。
- 回到
Appium页面，在“节点与脚本”区域选择预设 App。 - 等待设备预览和 App 组件树自动加载；必要时点击“刷新组件树”。
- 在设备预览或 App 组件树中选择目标组件。
- 在“开始”节点或任意步骤后的“插入操作”中选择要录制的操作。
- 在“录制步骤”中检查流程、编辑节点备注并配置判断分支。
- 输入脚本名称并保存。
- 选择已保存脚本后点击“回放”。
App 包名是必填项，只能从“参数配置”中已经添加的“预设 App 参数”选择，不能手动输入。未选择 App 时不能录制操作。
- 设备预览优先使用 Midscene Playground 的 scrcpy 实时画面，可以直接点击和滑动手机画面。
- 点击预览中的组件后，组件树会定位并选中对应节点，默认同时显示组件边框。
- 实时流不可用时会自动使用 ADB 截图轮询，避免两种画面来源相互覆盖。
- 画面停止更新时，可点击设备预览工具栏中的刷新按钮重新获取画面。
- 首次进入页面、切换设备、Activity 变化或页面结构变化后，组件树会自动刷新。
- 自动刷新会尽量保留仍然存在的已选节点。
- 录制操作、回放和手动刷新期间会暂停自动刷新，结束后自动恢复。
- 组件树支持横向和纵向滚动；下方“当前 Activity”最多显示三行。
- 手动点击“刷新组件树”可立即重新抓取当前页面结构。
注意：Appium 回放和组件树抓取都会占用 Android UiAutomation。系统会按设备串行执行，并在连接被抢占时清理残留进程后自动重试一次。
录制步骤以流程图节点展示。
节点类型：
- 操作：执行点击、输入、滑动、返回等动作。
- 判断：根据页面状态走“是 / 否”分支。
- 校验：验证页面是否满足预期。
点击节点可以展开编辑面板，支持修改：
- 节点名称
- 备注，例如“登录按钮”“账号输入框”
- 节点类型
- 超时时间
- 输入文本
- 是否可选
- selector 和父级上下文 selector
- 判断节点的指定文本与匹配方式
流程画布支持以下操作：
- 按住空白区域或节点拖动画布。
- 按住
Ctrl并滚动鼠标滚轮，在50%到200%之间缩放。 - 点击“放大”打开流程总览；总览中同样可以点击节点编辑。
- 点击节点后的“插入操作”可在任意步骤中间新增操作。
- 点击节点右上角删除按钮可移除节点，流程引用会自动修正。
- 浏览器刷新后会保持当前功能页面和 Appium 工作区 Tab；存在未保存修改时，刷新或关闭页面前会提示保存。
录制点击后如果检测到 Activity 发生变化，系统会提示选择继续录制或结束并保存。需要把多个页面保存在同一脚本时选择继续，等待新页面组件树刷新后即可录制后续操作；希望按页面拆分时，结束当前脚本并在新 Activity 中创建脚本，再通过“连接脚本”组合流程。
跨页面流程建议在跳转操作后添加“等待 Activity”，明确目标页面并提高回放稳定性。加载历史脚本时，即使手机当前 Activity 与脚本入口 Activity 不同，也可以查看和编辑流程；回放前应确认启动节点、等待 Activity 或前置操作能把设备带到正确页面。
- 组件操作：录制点击、录制输入、提取变量、清空输入、长按、存在则点击、存在则输入、存在则清空。
- 设备操作：点击坐标、系统返回、Home 键、最近任务、电源键、滑动、双指缩放、启动 APP、停止 APP、启动相册、清除 APP 数据。
- 判断与等待：判断存在、判断勾选、文字点击、AI 识别、图像判断、等待出现、等待消失、等待 Activity。
- 检测画面变化：在三级菜单中分别添加“开始”和“结束”，对比指定区域前后的画面。
- 循环：添加有界循环、进入下一次循环和退出循环。进入下一次循环会跳过本轮剩余节点；退出循环会执行目标循环结束后的流程。
- 流程控制：连接脚本、终止流程、输出日志和添加延时。
旧脚本中的“断言存在”和“断言文本”仍可回放，但新流程统一使用当前菜单中的判断与等待操作。
读取选中组件的文字或属性并保存为脚本变量，后续输入、判断、定位和日志节点可以使用 {{变量名}} 引用。
停止指定包名的 App 进程，不卸载应用，也不清除登录信息和本地数据。节点中可以修改目标包名。
打开设备可用的系统相册或常见相册应用，只负责进入相册，不自动选择照片或视频。
清除目标应用数据并恢复初始状态，会删除登录信息和本地设置。该操作只允许放在流程开始位置，使用前应确认测试数据可以重置。
读取原生 Checkbox、RadioButton 或 Switch 的真实 checked 状态，并按勾选或未勾选进入对应分支。普通图片控件应改用图像判断。
按指定文字精确或模糊查找原生组件，匹配后点击并进入成功分支，未匹配时进入另一分支。它不识别图片或自绘画面中的文字。
将设备截图发送给视觉模型，可以执行单帧识别、持续观察或检测命中后提前结束。默认按顺序继续执行；启用分支后根据识别结果进入不同路径。
使用本地 OpenCV 判断模板、图片勾选状态、黑屏、区域颜色或多帧变化，不调用模型。固定图标和稳定视觉特征适合使用该操作。
从三级菜单分别添加“开始”和“结束”。开始节点保存指定区域的基准截图，结束节点与对应基准比较并在日志和报告中记录变化结果。
在最大执行次数范围内重复执行循环体，可以固定次数运行，也可以根据元素出现或消失提前退出。最大次数用于防止脚本无限循环。
跳过当前轮剩余节点并进入指定的当前或外层循环下一轮。达到最大次数后执行循环结束路径。
立即结束指定的当前或外层循环，随后执行该循环结束后的流程。
主动结束整次回放，后续节点和连接脚本不再执行。系统仍会保存本次日志和报告。
输出自定义内容和日志关键字，支持 {{变量名}}。适合标记测试阶段、记录读取值或为报告提供检索标识。
用途：点击某个组件。
操作方法：
- 在设备预览或组件树中选择按钮、图标、列表项等组件。
- 点击“添加操作”。
- 选择“录制点击”。
示例：
点击 登录按钮
点击 添加设备入口
点击 我的 Tab
适用场景：
- 点击按钮。
- 点击列表项。
- 点击页面入口。
注意：
- 优先使用组件 selector。
- 如果 Appium 找不到组件，会使用 bounds 坐标兜底。
用途：向输入框输入文本。
操作方法：
- 选择输入框组件。
- 点击“添加操作”。
- 选择“录制输入”。
- 在弹窗中输入文本。
示例：
输入 账号输入框：test@example.com
输入 密码输入框：123456
适用场景：
- 账号输入。
- 密码输入。
- 搜索框输入。
- 表单字段输入。
注意：
- 如果账号框和密码框底层 id 一样，录制器会自动保存父级上下文 selector；回放时会先找父级，再找子输入框。
- 录制后可以展开节点修改输入内容。
用途：清空输入框已有内容。
操作方法：
- 选择输入框组件。
- 点击“添加操作”。
- 选择“清空输入”。
示例：
清空 搜索框
输入 搜索框：摄像机
适用场景：
- 搜索框重复测试。
- 输入框默认已有内容。
- 修改表单字段前先清空。
用途：按当前组件中心坐标点击，不依赖 selector。
操作方法：
- 选择目标区域。
- 点击“添加操作”。
- 选择“点击坐标”。
示例：
点击坐标 540,1680
适用场景：
- 组件树识别不到的自绘区域。
- selector 不稳定，但坐标稳定的按钮。
注意：
- 对分辨率、横竖屏、布局变化敏感。
- 能用组件点击时，不建议优先用坐标点击。
用途：长按某个组件或坐标。
操作方法：
- 选择目标组件。
- 点击“添加操作”。
- 选择“长按”。
示例：
长按 设备卡片
适用场景：
- 长按打开菜单。
- 长按删除列表项。
- 长按进入编辑模式。
默认长按时间为 800ms，可展开节点修改超时时间。
用途：执行 Android 返回键。
操作方法：
- 点击“添加操作”。
- 选择“返回键”。
示例：
点击设备详情
返回键
断言存在 设备列表
适用场景：
- 从详情页返回列表页。
- 关闭页面。
- 关闭系统弹窗或软键盘。
用途：执行 Android Home 键。
操作方法：
- 点击“添加操作”。
- 选择“Home 键”。
示例：
Home 键
启动 App
适用场景：
- 验证 App 从后台恢复。
- 回到桌面后重新启动 App。
用途：打开 Android 最近任务页面。
操作方法：
- 点击“添加操作”。
- 选择“最近任务”。
示例：
最近任务
Home 键
适用场景：
- 验证多任务切换。
- 验证 App 后台状态。
用途：发送 Android 电源键。
操作方法：
- 点击“添加操作”。
- 选择“电源键”。
示例：
电源键
添加延时 1000ms
电源键
适用场景：
- 锁屏 / 亮屏相关测试。
注意：
- 不同设备锁屏行为可能不同。
- 自动化回放时请确认设备不会因锁屏无法继续操作。
用途：执行上、下、左、右滑动。
操作方法：
- 点击“添加操作”。
- 选择“滑动”。
- 输入方向：
上、下、左、右。
示例：
下滑
断言存在 下一页内容
适用场景：
- 列表滚动。
- 页面翻页。
- 轮播切换。
用途：执行双指放大或缩小。
操作方法：
- 点击“添加操作”。
- 选择“双指缩放”。
- 输入方向：
放大或缩小。
示例：
双指放大
双指缩小
适用场景：
- 地图缩放。
- 图片预览缩放。
- 视频画面缩放。
用途：启动当前选择的预设 App。
操作方法：
- 先选择预设 App 参数。
- 在录制步骤的“开始”节点下点击“插入操作”。
- 选择“启动 App”，该操作会作为流程第一步插入。
示例：
启动 App
等待 Activity com.example.MainActivity
适用场景：
- 脚本第一步启动目标 App。
- 从桌面或其他 App 回到目标 App。
“启动 APP”只能从开始节点添加，并且每个脚本只能有一个启动节点。添加后菜单中的“启动 App”会自动置灰，删除该节点后恢复可用。启动时会通过 ADB 使用当前预设 App 参数中保存的包名打开应用。
录制时可以点击启动节点上的执行按钮立即启动 App，并刷新当前 Activity。回放前会先检查目标 App 是否已在前台：已经启动时跳过“启动 APP”节点并保留当前页面；通过“连接脚本”进入子脚本时，也会跳过子脚本中的启动节点。
用途：等待固定时间。
操作方法：
- 点击“添加操作”。
- 选择“添加延时”。
- 输入毫秒数。
也可以在流程节点后点击“插入延时”。
示例：
点击 登录按钮
添加延时 1000ms
断言存在 首页元素
适用场景：
- 等动画结束。
- 等网络请求短暂完成。
- 等系统弹窗出现。
注意：
- 优先使用“等待 Activity”“断言存在”等状态等待。
- 固定延时越多，脚本越慢。
用途：判断某个组件或指定文本是否出现，并根据结果走不同分支。它可以用于弹窗，也可以用于按钮、列表项、提示文案等普通页面组件。
操作方法：
- 选择目标组件上的稳定元素，例如标题、按钮、列表项或提示文案。
- 点击“添加操作”。
- 选择“判断存在”。
- 点击判断节点，按需填写“指定文本”。
- 选择“模糊匹配（包含）”或“精准匹配（完全一致）”。
- 在“是”或“否”分支下点击“插入操作”，分别添加分支步骤。
- 如果两个分支后续要执行相同操作，可以复制公共节点到对应分支，或把公共流程拆成“连接脚本”复用。
示例：
判断存在 确认按钮
是 -> 点击 确认按钮
否 -> 不添加操作
分支说明：
- 未配置指定文本时，只判断目标组件是否存在。
- 配置指定文本后，会同时检查组件及其子节点文本。
- 模糊匹配会忽略换行和连续空白差异，只要规范化后的文本包含目标内容即可。
- 精准匹配要求 Appium 返回的完整文本与指定文本完全一致。
- 分支可以包含多个连续步骤，也可以在分支末尾连接其他脚本。
适用场景：
- 首次启动确认弹窗。
- 权限说明弹窗。
- 活动弹窗。
- 只出现一次的引导弹窗。
用途：同一个页面有两个弹窗复用同一个组件，只是标题或正文不同，需要按文案区分弹窗类型。
操作方法：
- 选择能覆盖弹窗正文的节点；如果文本位于子节点中，也可以选择其稳定父容器。
- 点击“添加操作”。
- 选择“判断存在”。
- 展开节点，在“指定文本”中输入该弹窗特有的文案。
- 根据需要选择模糊匹配或精准匹配。
- 在“是”分支添加该弹窗对应的确认、取消或关闭步骤；“否”分支继续下一个判断或不添加操作。
示例：
判断存在：指定文本“是否删除设备”
是 -> 点击 确定
否 -> 判断存在：指定文本“是否退出登录”
是 -> 点击 确定
否 -> 不添加操作
适用场景：
- 两个弹窗
resource-id、按钮 id、class 都一样。 - 同一个弹窗组件展示不同业务文案。
- 需要根据弹窗内容执行不同分支。
注意：
- 弹窗不是必出现时，先用“判断存在”形成分支，不要直接使用“断言文本”，否则弹窗未出现会让回放失败。
- 不要只判断“确定”按钮是否存在，这会把两个弹窗都识别成同一种弹窗。
- 优先用弹窗标题、正文、关键提示文案作为判断目标。
- 节点详情里的 selector 会显示当前 Activity，方便确认该定位属于哪个页面。
用途：元素出现时点击，不出现时跳过。
操作方法：
- 选择可能出现的按钮，例如权限确认、协议同意、活动关闭。
- 点击“添加操作”。
- 选择“存在则点击”。
示例：
存在则点击 同意按钮
存在则点击 关闭活动弹窗
适用场景：
- 一次性弹窗。
- 偶尔出现的活动弹窗。
- 首次启动协议确认。
用途：输入框出现时输入文本，不出现时跳过。
操作方法：
- 选择可能出现的输入框。
- 点击“添加操作”。
- 选择“存在则输入”。
- 在居中弹窗中输入文本。
示例：
存在则输入 搜索框：摄像机
录制后可展开节点修改输入内容。
用途：输入框出现时清空，不出现时跳过。
示例：
存在则清空 搜索框
存在则输入 搜索框：摄像机
用途：某个遮挡元素或页面出现时执行返回键，不出现时跳过。
示例：
存在则返回 权限说明页
存在则返回 引导页
适用场景：
- 临时引导页。
- 偶尔出现的中间页。
- 可通过系统返回关闭的遮挡页面。
用途：等待页面加载到某个目标状态。
操作方法：
- 选择目标页面的稳定元素。
- 点击“添加操作”。
- 选择“等待出现”。
示例：
点击 登录按钮
等待出现 首页设备列表
适用场景：
- 页面跳转后等待目标元素出现。
- 单 Activity App 无法通过 Activity 判断页面时。
用途：校验页面上必须存在某个组件。
操作方法：
- 选择目标组件。
- 点击“添加操作”。
- 选择“断言存在”。
示例：
断言存在 首页设备列表
断言存在 登录失败提示
适用场景：
- 校验登录成功。
- 校验页面跳转成功。
- 校验按钮或列表存在。
注意：
- 断言失败表示测试失败。
- 不建议用于可有可无的弹窗。
用途：校验组件文本是否包含指定内容。
操作方法：
- 选择带文本的组件。
- 点击“添加操作”。
- 选择“断言文本”。
- 输入要校验的文本。
示例：
断言文本 登录失败提示：密码错误
断言文本 页面标题：设备
适用场景：
- 校验错误提示。
- 校验标题。
- 校验列表文案。
用途：等待某个组件从页面上消失。
操作方法：
- 选择 loading、弹窗或遮罩组件。
- 点击“添加操作”。
- 选择“等待元素消失”。
示例：
点击 登录按钮
等待元素消失 loading
断言存在 首页设备列表
适用场景：
- 等 loading 结束。
- 等弹窗关闭。
- 等遮罩消失。
用途：等待 Android 当前 Activity 切换到指定值。
操作方法：
- 点击“添加操作”。
- 选择“等待 Activity”。
- 输入目标 Activity。
示例：
点击 登录按钮
等待 Activity com.example.MainActivity
适用场景：
- 点击按钮后进入新页面。
- 启动 App 后等待首页 Activity。
注意：
- 有些 App 使用单 Activity 架构，Activity 不会变化，这时应改用“断言存在”判断页面元素。
用途：把一个已保存脚本连接到当前脚本后继续执行。
操作方法：
- 先保存被连接的脚本，例如“首页脚本”。
- 打开当前脚本，例如“登录脚本”。
- 在主流程节点或判断分支下点击“插入操作”。
- 选择“连接脚本”，再选择目标脚本。
- 保存当前脚本。
校验规则：
- 主流程和判断分支均可选择同一 App 的其他已保存脚本，不要求入口 Activity 与插入点一致。
- 目标脚本已绑定入口 Activity 时，回放会等待手机进入该 Activity；页面没有真正跳转时会超时失败。
- 目标脚本未绑定入口 Activity 时，直接从当前画面执行。连接脚本不会自动切换手机页面，需在前序步骤中完成点击、返回等操作。
- 目标脚本必须属于当前 App，且不能连接当前脚本自身。
- 脚本互相连接形成循环时，回放会终止并提示循环连接。
示例：
登录脚本：
输入账号
输入密码
点击登录
连接脚本：首页脚本
首页脚本：
启动 App
断言存在 首页元素
点击设备列表
断言存在 设备详情
适用场景：
- 测试人员不知道点击后页面是什么。
- 登录流程和首页流程由不同人录制。
- 复用公共前置流程。
回放行为：
- 不重新创建 Appium session。
- 子脚本中的“启动 App”节点会自动跳过，不会重新启动 App。
- 在当前页面状态继续执行目标脚本。
- 子脚本单独回放时仍会正常执行自己的“启动 App”节点。
- 如果脚本互相连接形成循环，会终止并提示循环连接。
在“参数配置 → Appium配置 → 回放报告总结”中配置，默认关闭，与截图报告独立。
- 在上方“提示词优化模型”填写 Base URL、API Key、Model Name，并点击“测试并保存”。该文本模型同时用于优化提示词和生成回放报告总结。
- 开启“回放报告总结”。开关和报告提示词修改后自动保存。
- 在回放按钮的设置中选择报告模板；不选择时使用默认测试报告。默认格式包括测试概览（脚本名称、起止时间、结果、总时长）、执行配置及节点参数、用例描述表格、失败详情和汇总，也可以选择出图时间分析或自定义模板。
- 回放结束后将脱敏日志、主脚本与连接脚本配置发送给总结模型，生成的 Markdown 使用原回放报告路径，保存在配置的报告输出目录（默认
output）；完成日志会显示报告路径。
开启报告总结后，工具会在回放前验证提示词优化模型。模型不可用时，开关旁会提示“模型不可用，使用默认模板”，回放仍会继续并生成基础报告。总结在设备操作结束后生成，页面会显示生成进度，总结耗时不计入测试总时长。关闭时继续生成原基础报告且不调用总结模型；请求失败、超时或返回空内容时保留基础报告和原始日志，并输出失败原因，不改变测试结果。模型请求最多等待 60 秒。
报告不会向模型发送截图和图片模板。为控制输入大小，脚本配置最多保留约 50000 字符，日志最多保留约 100000 字符；超限时保留头尾并标注中段省略，生成报告也会注明信息不完整。模型的原因分析属于辅助判断，应结合原始日志核实。
- 新脚本需要填写名称并选择预设 App 后保存。
- 从顶部脚本下拉框或“脚本列表”加载历史脚本后，再次点击“保存”会更新原脚本，不会因为名称相同而报错。
- 脚本数据只保存流程图
flow_json，其中包含主流程、判断分支、连接关系、节点备注和页面检查点。 - 已保存脚本加载后仍可直接查看和编辑；当前 Activity 不影响脚本编辑。
在“录制与脚本”区域切换到“脚本列表”Tab，可以：
- 加载脚本：回到“当前录制”继续查看、编辑或回放。
- 下载脚本：导出包含完整流程的 JSON 文件。
- 导入脚本：选择此前导出的 JSON 文件；名称重复时自动生成新名称，不覆盖已有脚本。
- 删除脚本：删除数据库中的已录制脚本。
导入脚本后仍需在本机配置对应的预设 App，并连接可用的 Android 设备。
点击“回放”后，日志会随着执行过程实时追加，不需要等待整个脚本结束。所有流程统一使用 [节点 N] 编号，常见内容包括：
[节点 1] 开始：启动 APP com.example.app
[节点 1] 结果：APP 已在前台，跳过启动 com.example.app
[节点 1] 完成：启动 APP com.example.app
[节点 2] 判断：是
默认情况下，每次回放会启动一个独立端口的 Appium 服务。回放输出会完整保留该服务的 stdout/stderr，包括 Appium、AndroidUiautomator2Driver、ADB、请求参数、响应内容和驱动诊断信息，同时保留工具自身记录的请求方法、接口路径、HTTP 状态和耗时。例如：
2026-08-22 13:57:35:756 - [Appium] Welcome to Appium v3.5.0
[AndroidUiautomator2Driver@ec68] Got response with status 200: {...}
[ADB] Running '.../adb -s device-id shell ...'
[Appium] 请求：POST /session
[Appium] 响应：HTTP 200 POST /session（328ms）
完整 Appium 日志可能包含输入值、设备信息和 WebDriver 请求参数。共享 .log 文件前请先检查并清理敏感内容。
如果通过环境变量 APPIUM_SERVER_URL 显式连接外部 Appium 服务，工具无法读取外部进程所在终端的 stdout/stderr，只会保存 WebDriver 请求、响应状态、耗时和错误响应。需要完整服务端日志时，请不要设置该环境变量，让工具为回放自动启动 Appium。
“回放输出”默认只保留最近 80 行的可视高度，避免无限撑长页面。可以使用：
- 复制：复制当前完整日志。
- 展开查看：在弹窗中查看完整日志。
- 清除：清空页面上的回放输出。
回放期间顶部会显示“终止”按钮。点击后会停止后续节点、关闭当前 Appium session，并继续生成本次回放的报告和日志；执行结果标记为“已终止”。
每次回放结束后，无论成功、失败或手动终止，都会生成 Markdown 报告、纯文本日志和单文件 HTML 截图回放。三个文件使用相同的日期时间和脚本名称：
当前日期时间-脚本名称.md
当前日期时间-脚本名称.log
当前日期时间-脚本名称.html
报告保存到“参数配置 > 运行配置”指定的目录；没有指定时，默认保存在启动命令所在目录的 output 文件夹中，例如：
output/2026-08-21_17-13-42-831-登录流程.md
output/2026-08-21_17-13-42-831-登录流程.log
output/2026-08-21_17-13-42-831-登录流程.html
报告包含：
- 脚本、App、Activity、设备、执行时间和结果。
- 每个节点的类型、selector、上下文 selector、输入值、超时、备注和分支配置。
- 每个节点的实际执行状态与执行信息。
- 完整回放日志。
.log 文件保存页面中显示的完整回放过程，以及本次托管 Appium 进程未经截断的 stdout/stderr。生成成功后，报告与日志的绝对路径会追加到实时回放输出中；报告位置同时保存到数据库，便于后续追溯。
.html 文件在每个实际执行节点前后采集设备截图，并将截图以 Base64 形式直接嵌入文件。打开后可以：
- 在左侧查看执行步骤和当前截图对应的脚本、节点、阶段、结果、备注与 selector。
- 在顶部时间轴查看截图所在的真实执行时间，并点击缩略图或时间轴跳转。
- 使用“上一帧”“播放”“下一帧”及进度条控制回放；播放进度按实际回放耗时连续推进，不再按固定间隔逐张切换。
- 在左侧步骤下方展开完整回放日志；日志默认收起。
判断分支、失败和手动终止会保留对应的最后画面。连接脚本中的实际执行节点也会进入同一条截图时间线。HTML 不依赖外部图片目录，可以单独复制和打开。
登录脚本：
启动 App
输入 账号
输入 密码
判断存在 用户协议弹窗
是 -> 点击 同意 -> 点击 登录 -> 判断登录是否成功 -> 连接脚本 首页脚本
否 -> 点击 登录 -> 判断登录是否成功 -> 连接脚本 首页脚本
首页脚本：
启动 App
断言存在 首页设备列表
点击 添加设备
断言存在 添加设备页面标题
适合场景：
- 录制登录时不知道登录成功后跳到哪个页面。
- 首页流程希望独立维护。
输入 账号
输入 密码
点击 登录
判断 首页设备列表是否存在
是 -> 断言存在 首页设备列表
否 -> 断言文本 登录错误提示
操作方法：
- 先录制输入和点击登录。
- 选择用于区分登录结果的稳定元素，添加“判断存在”。
- 在“是”分支插入首页校验或“连接脚本”。
- 在“否”分支插入错误提示断言。
- 如果两个分支后续有相同公共步骤，使用批量复制把公共节点复制到对应分支。
启动 App
判断存在 确认按钮
是 -> 点击 确认按钮 -> 断言存在 首页
否 -> 断言存在 首页
适合场景：
- 只第一次安装后出现的确认弹窗。
- 老用户不再出现的弹窗。
启动 App
断言存在 列表页标题
上滑
添加延时 500ms
断言存在 目标列表项
如果列表加载慢，可以把固定延时换成目标元素断言。
点击 设备卡片
断言存在 设备详情标题
返回键
断言存在 设备列表
适合场景：
- 校验页面返回路径。
- 校验返回后列表仍可见。
- 每个脚本只负责一个清晰场景。
- 登录、首页、详情页可以拆成多个脚本，用“连接脚本”组合。
- 每次页面跳转后，添加一个“断言存在”或“等待 Activity”。
- 弹窗或其他可选组件使用“判断存在”，不要直接写死必点。
- 坐标点击只作为兜底。
- 给关键节点填写“登录按钮”“账号输入框”等备注，方便查看流程和报告。
- 回放失败后优先查看“回放输出”中的失败节点、Activity 和 selector，再打开
output中的 Markdown 报告查看完整配置。
通常不是数据被删除，而是旧版本把数据保存到了启动命令所在目录。新版 npx android-midscene-automation 会默认使用固定的系统用户数据目录，并在启动时尝试从当前目录自动迁移旧数据。
默认数据目录：
Windows: %LOCALAPPDATA%\android-midscene-automation
macOS: ~/Library/Application Support/android-midscene-automation
Linux: ~/.local/share/android-midscene-automation
如果迁移后仍看不到旧数据，请在之前启动过的目录里查找 .midscene-app/script-cache.sqlite，再把 .midscene-app 复制到上面的固定数据目录。也可以设置 ANDROID_MIDSCENE_DATA_ROOT 指向原来的数据目录继续使用。
如果账号框和密码框都是 id/tg_edit，只按 id 回放可能输入到第一个输入框。
建议：
- 直接分别选择账号框和密码框录制输入。
- 在节点详情里确认 selector 是否显示“重复 N”，以及“推荐定位”是否显示父级 + 子级。
- 如果推荐定位不准确，展开录制步骤，手动修改父级上下文 selector。
- 坐标点击只作为最后兜底。
可能原因：
- 按钮当前禁用。
- 账号密码不正确。
- App 使用单 Activity，Activity 不变化。
- 页面跳转依赖网络。
推荐：
- 使用“等待出现”判断下个页面核心元素，或添加“等待 Activity”明确目标页面。
- 检测到 Activity 变化时可以选择继续在当前脚本录制；也可以拆成两个脚本，再用“连接脚本”串联。
- 单 Activity App 不要依赖 Activity 变化，应使用页面核心元素判断是否已进入目标状态。
- 连接脚本列表会显示同一 App 的其他已保存脚本，不受入口 Activity 限制。
- 连接操作本身不会点击页面或主动跳转，前面的点击、输入或启动 App 必须先让设备进入目标脚本需要的页面。
- 目标脚本绑定了入口 Activity 时，回放会等待该 Activity；未绑定时会直接从当前画面执行。
- 跨页面连接前建议添加“等待 Activity”或“等待出现”，便于确认页面已经切换完成。
部分厂商系统会限制桌面或启动器页面的控件信息，Appium 可能无法获取桌面图标的稳定 id。此时在桌面录制“点击 App 图标”可能无法回放。
建议在开始节点后添加“启动 App”操作，由系统按包名打开目标 App，替代桌面点击图标。需要重置登录态或缓存时，可以先添加“清理 App 缓存”，再添加“启动 App”。
使用“判断存在”。
判断存在 确认按钮
是 -> 点击 确认按钮
否 -> 不添加操作
不要直接把弹窗确认按钮作为普通必选点击，否则弹窗不出现时脚本会失败。
适合多 Activity App。
如果 App 是单 Activity 架构，优先用：
等待出现 页面核心元素
可选步骤适合非主流程阻塞项：
- 权限弹窗
- 协议弹窗
- 活动弹窗
- 首次引导
不建议把登录按钮、提交按钮、核心断言设置为可选。
组件树刷新和 Appium 回放不能同时占用 UiAutomation。当前版本会在回放期间暂停组件树自动刷新，并在断开时清理残留抓取进程后重试一次。
如果仍然失败：
- 确认手机保持解锁，USB 调试授权没有失效。
- 确认 Appium 和 UiAutomator2 Driver 已正常启动。
- 停止其他正在抓取同一设备组件树的工具。
- 重新连接设备后再次回放。
- 先确认设备仍显示在设备下拉框中。
- 点击设备预览刷新按钮重新获取画面。
- 点击“刷新组件树”重新抓取页面结构。
- 回放期间组件树自动刷新会暂停，回放完成后会自动恢复。
- [Appium]修复登录等点击操作已经触发 Activity 跳转后，UiAutomator2 仍等待点击确认、最终误报超时并占用命令队列的问题；元素点击先读取实时区域，再通过 ADB 点击中心坐标，并限制界面空闲等待时间。
- [Appium]修复登录等点击操作已经触发 Activity 跳转后，持续动画或频繁界面事件仍让 UiAutomator2 长时间等待、最终误报点击超时的问题；限制界面空闲等待时间，避免命令队列被长期占用。
- [文档]更新 README.md。
- [Artemis]修复自定义模型返回
<think>思考标签导致 Hopper 等节点 JSON 解析失败的问题：非 Google 模型的 Pydantic 结构化输出接入统一清理、提取和校验流程，显式提供 JSON Schema，格式错误时限次要求模型纠正。 - [Artemis]修复 Flash 步骤摘要和历史压缩仍直接创建 Gemini 客户端的问题：非 Google 模型统一使用配置中的 summarizer 节点及其备用模型；模型初始化错误不再静默切换到 Gemini。
- [Artemis]修复 Artemis 使用 MiniMax、GLM 等非 Google 默认模型时，辅助检查节点仍强制调用 Gemini 并因缺少密钥导致任务启动失败的问题；支持这些节点继承默认模型或使用显式配置。
- [Artemis]集成 Google Artemis。
- [Midscene]Midscene 集成已停止日常维护，现有功能仍保留。
- Midscene Android、Android Playground、Core、Playground、Shared 和 Web 模块统一升级至 1.14.0。
- 修复 Midscene 测试脚本生成过程中切换“AI 生成 / 自定义步骤编排”会清空生成状态和结果的问题；生成任务继续在后台执行，模式切换后保留已生成步骤与代码。
- 修复长时间执行 ADB 操作、延时或 AI 识别后，Appium 因默认 60 秒命令空闲超时销毁会话，导致后续 Home 键、点击等节点报“invalid session id”的问题；托管服务关闭会话空闲计时，外部服务通过心跳保活并保留 60 秒空闲回收，避免创建请求取消或清理失败后遗留永久会话。
- 为启动 App、清理数据、坐标点击与滑动补齐 ADB 超时和取消控制；终止前台检查后不再继续启动 App，异常结束仍清理会话。
- 修复远程回放固定 10 分钟超时后丢失结果的问题：任务随代理心跳续期，离线任务支持恢复连接后终止与补交历史记录，结果上报失败自动重试且不会重复执行脚本。
- 修复远程设备无法手动终止回放的问题，通过独立心跳传递取消信号，兼容任务派发前取消，并阻止同一设备重复提交回放。
- 新增“概览 → 分析页”，根据已保存脚本和真实执行记录分别汇总 Midscene、Appium 测试数据。
- 修复配置加载失败后出现空白可保存表单的问题，增加独立错误提示和重试；后端断线后自动尝试重连并支持手动重连，保留页面编辑内容。
- Appium 配置自动保存失败后保留最新待保存内容并提供“重试保存”；修复切换或关闭 Appium 页签后，离开页面时未保存草稿保护失效的问题。
- Appium 顶部工具栏改为随页面布局排列，窄屏自动换行，避免遮挡面包屑；统一全站样式与中文组件文案，合并重复主题声明。
- 完善隔离数据环境下的浏览器回归测试，以及请求校验、配置保护、自动保存重试和统计口径测试。
- 侧边栏底部新增“帮助与版本”入口。
- AI 识别预设提示词支持编辑测试场景名称和提示词内容，默认预设与自定义预设均可修改并自动保存。
- AI 识别启用分支后可勾选“启用兜底”，再选择进入左侧 true 或右侧 false 分支；正常识别结果不受影响。
- 新增独立的“提示词优化模型”，统一用于优化 AI 识别提示词、报告提示词和生成回放测试报告总结；AI 识别与回放报告均可输入简要要求后由模型补充提示词，模型测试成功改为弹窗提示。
- 回放设置新增报告模板选择，不选择时使用默认测试报告；开启报告总结后会在回放前检测提示词优化模型，模型不可用时弹窗提示并继续生成默认格式的基础报告。总结请求失败、超时或返回空内容时同样保留基础报告，不改变测试结果。
- 回放输出弹窗支持同时拖拽调整宽度和高度，并保留最小尺寸与窗口边界限制。
- 连接脚本列表显示同一 App 的其他已保存脚本，不再因入口 Activity 不同或未绑定而隐藏；选择时说明等待入口页面或直接从当前画面执行的行为。
- 点击坐标操作新增“获取点击坐标”，直接在左侧设备预览点击画面即可填入实际 X、Y 坐标，无需弹窗，支持取消，取点不会执行设备操作。
- 修复回放终止或会话创建失败后设备端 UiAutomator2 残留，导致组件树刷新失败的问题。
- AI 持续观察新增“检测命中后提前结束”模式，边采样去重边识别，命中后停止观察并继续流程或进入“是”分支；到达最长观察时间后完成剩余关键帧判断，未命中走原顺序或“否”分支，支持命中条件校验、取消和逐次模型请求超时。
- Appium 参数的AI 识别配置，新增持续观察选项，支持 pixelmatch（默认）、OpenCV（SSIM）和不去重选项。
- AI 识别新增“持续观察”，可设置观察时长与采样间隔，按时间顺序采集多帧后统一判断目标是否出现过或读取内容；观察与模型超时分开计时，支持取消、采样日志与测试画面预览，原单帧识别保持兼容。
- Midscene 配置新增官方文档中的模型提供方预设。
- 新增 AI 识别默认顺序执行模式，模型回答写入日志后继续下一节点；勾选“启用分支”及修改分支问题时通过模型验证判断语义，不符合时提示且不保存分支修改。
- Appium 配置新增默认关闭的“截图与 HTML 报告”开关；开启后才采集节点前后截图并生成 HTML。
- 修复部分华为设备录屏启动时报编码器错误的问题：使用设备默认编码参数，视频流启动失败时降低分辨率和码率重试，并输出各次尝试的诊断日志。
- 开启录屏时，在 Appium 服务端日志结束后汇总所有录像片段的脚本名称和保存位置；未生成视频时明确提示。
- 录屏启动失败、录像不完整或保存失败时，日志明确提示对流程执行的影响并提供排查建议，保留原始错误信息。
- 回放录屏支持按连接脚本分段保存 MP4，返回父脚本继续执行时另存片段；历史结果可选择片段播放，HTML 报告按节点时间自动切换视频，删除历史结果时一并清理全部片段。
- Midscene 相关模块统一升级至 1.12.7，
- scrcpy 视频帧完整性修复：可靠传输视频包、修正关键帧标记，并在缓冲溢出后等待完整关键帧恢复，降低设备预览花屏风险。
- 回放按钮右侧下拉设置新增默认关闭的“录制回放视频”，远程设备暂不支持。
- 图像模板判断改为“预期匹配结果”，匹配严格度以百分比配置，100% 时提示细微像素差异风险；节点显示预期结果，日志和 HTML 报告分别展示实际匹配、预期匹配、得分与条件结论，保留原检测算法及已有阈值。
- 移除 AI 识别操作、测试入口及 Appium 参数中的 AI 模型配置，保留流程背景色设置；旧脚本中的 AI 节点提示替换，回放前阻止执行，不自动删除或改变分支。
- 移除节点类型切换；新节点及未配置的判断等待超时统一为 3000ms，已有自定义时间和延时、长按等操作时长保持不变。
- 取消 Activity 不匹配时的脚本编辑锁定，不在脚本绑定页面也可编辑节点；页面差异仅作提示，保留录制操作及回放期间的编辑保护。
- 所有分支节点新增“超时后处理”，可预设终止流程、进入左侧或右侧分支，默认终止；覆盖元素等待、文字匹配、勾选控件等待、AI 识别及图像观察超时，日志和 HTML 报告标明超时分支。正常 false、循环次数上限与超时区分处理，设备断开及 Appium 无响应仍终止。
- 修复元素查找超时未覆盖 Appium 请求的问题，驱动无响应时及时中止并明确报错，不再误判为找不到元素；唯一原生定位优先使用 ID 或 Accessibility ID。
- 设备预览新增设备信息，展示设备名称、品牌、型号、处理器、Android 版本、物理分辨率及当前分辨率，支持远程设备；问号位于标题右侧，样式与全局变量帮助图标一致。
- 新增独立“杀死 APP”操作节点，默认使用当前选中应用包名，支持编辑目标包名；停止当前设备用户下的应用进程，不清除应用数据。
- Midscene 相关模块由 1.12.5 统一升级至 1.12.6。
- 新合并支持取消：原合并按钮切换为取消合并，还原分支和被删除的重复节点，保留配置编辑；公共流程新增的普通操作可选择保留左侧、右侧或两侧，结构冲突时阻止还原。本地保存还原记录，导出及节点复制不携带历史记录。
- 启动相册前先停止当前设备用户下的目标相册进程，再重新打开；保留相册自动适配，不清除照片及应用数据，停止失败时明确报错。
- 修复修改元素或父级定位后仍使用旧备用定位、画面变化像素容差无法设为 0 的问题。
- 新增“图像判断”分支节点，支持本地 OpenCV 模板匹配、图片勾选双模板、黑屏、区域颜色和多帧变化检测；支持组件定位、框选区域、模板采集与上传、连续采样及 true/false 分支，证据不足时明确报告无法判定。HTML 报告展示指标和可放大的检测图片，并沿用敏感运行截图保护。
- 合流后的公共节点上方新增插入入口，支持新增和粘贴操作，所有汇入分支先执行新操作再进入原公共节点。
- 修复嵌套判断显式合流到外层公共节点时连接被过滤、公共节点提前排列的问题，支持跨层分支合流。
- 修复同一分支内显式跳转被画布误画为顺序连接的问题，失效跳转目标不再错误连接到相邻节点。
- 修复判断分支默认返回公共后续节点时画布漏连线、节点重叠的问题，嵌套分支显示与回放路径保持一致。
- 操作菜单移除“断言存在”和“断言文本”，统一保留“判断存在”及其文本匹配配置；旧脚本中的断言节点仍兼容原有执行行为。
- “点击坐标”节点支持编辑 X、Y 坐标，保存后回放使用新坐标；默认节点名称同步更新，自定义名称保持不变。
- 新增“预设变量”区域，支持全局变量和脚本私有变量，输入、判断、定位和日志支持
{{变量名}}引用。
- 添加画面变化结束节点时，多组可配对检测支持按名称及开始节点编号选择，允许交叉结束；只有一组时直接添加，保留分支及重复结束校验。
- 画面变化结束节点校验覆盖祖先及子分支：同一执行路径已存在对应结束节点时，后续分支不能重复添加；互斥分支仍可分别结束。
- 脚本列表新增“历史结果对比”：保存运行结果、应用版本、设备、截图和日志，支持筛选查看通过率、耗时趋势与失败节点分布，对比两次运行并删除选中历史；手动终止不计入通过率，旧报告不自动补录。
- 画面变化检测在每个结束节点执行后立即对比本次截图，避免循环及重复调用脚本时多组检测复用最后一轮图片；截图缺失时明确报告异常，不使用旧图替代。
- “启动 APP”支持在流程中途、判断分支及循环体内多次添加，按所选位置执行；连接脚本仅跳过开头的应用初始化，中途启动操作正常保留。
- Midscene 相关模块统一从 1.12.2 升级至 1.12.5。
- 组件详情展示 Resource ID、Accessibility ID、XPath 和 UiAutomator 四种定位内容，支持分别复制，方便配置循环退出条件；缺少对应属性时显示未提供。
- “流程控制”新增有界循环及退出循环：支持固定次数、元素出现或消失时退出，必须设置最大执行次数；循环体支持嵌套判断、合流和连接脚本。退出节点可选择当前或外层循环，退出外层时同时结束内部循环并直接执行目标循环结束路径，日志及 HTML 报告标注轮次和退出目标。
- 新增流程节点搜索，支持按名称、操作类型、定位内容和日志关键字筛选，展示所属分支并在多个结果间切换；普通画布与流程总览支持定位高亮，不改变节点布局及批量选中状态。
- Midscene 相关模块统一从 1.12.0 升级至 1.12.2。
- 录制工作区支持拖拽调整设备预览、组件树栏宽，自动保存布局并支持恢复默认。
- 新增节点批量删除功能，支持多选节点，选中节点及所属子节点以柔和红色背景和浅色文字标记，确认后统一删除；支持普通与放大视图同步操作。
- 判断节点新增“合并分支”，支持选择一侧公共流程起点，将两侧后续汇入同一段居中流程；另一侧可保留独有操作或确认删除重复后缀，支持嵌套判断及各类分支，公共节点只执行一次且不随单侧节点删除。
- 将 Checkbox、RadioButton 判断入口合并为“判断勾选”，新增 Switch 支持；添加和回放时自动校验组件类型及可勾选属性，读取实时 checked 状态进入 true / false 分支，不改变控件状态，兼容已有独立判断节点。
- “流程控制”新增终止流程节点，执行到该节点时主动结束本次回放，不再执行后续节点或连接脚本；子脚本触发时也结束整个流程，保留执行日志和报告，不作为执行失败。
- “设备操作”新增启动相册顺序节点，优先解析系统相册入口，必要时查找已安装的常见相册应用；仅打开相册，不选择照片，日志记录实际启动应用，找不到或启动失败时明确报错。
- Appium 配置新增流程背景色设置，默认沿用浅绿色，支持预选颜色、颜色选择器、#RGB / #RRGGBB 输入校验和恢复默认；保存后持久化，普通画布、放大视图和连接脚本预览统一应用。
- Appium 配置中的流程背景色独立成区，与节点模型配置分开展示，保留预选颜色、自定义颜色及保存入口。
- “组件操作”新增文字点击分支节点，无需预选元素，支持精准匹配和模糊匹配原生组件文字；匹配并点击后进入“匹配到文字”，等待超时未找到则进入“未匹配到文字”。支持编辑文字和超时，多元素匹配及点击异常明确报错，日志和报告保留分支结果。
- “流程控制”新增输出日志节点，支持设置日志内容和自定义关键字，默认按
stageLog:内容输出；支持添加后编辑，回放实时输出、日志文件及报告均保留日志内容，多行内容逐行添加关键字。 - 新增 AI 识别判断节点，可输入按钮可用、画面黑屏等识别要求，通过当前设备截图返回
true / false并进入对应分支；Appium配置支持独立设置 Base URL、API Key、Model Name 和测试模型，模型需支持图片输入。 - 长按操作新增元素模式，新建节点默认按元素定位执行长按；添加弹窗和节点配置支持切换元素 / 坐标模式及修改长按时间，旧脚本保留坐标长按行为。
- 新增原生 Checkbox 和 RadioButton 状态判断节点，添加时校验选中元素类型，回放时读取
checked属性，按true / false进入对应分支，不改变勾选状态；组件详情显示原生勾选属性，回放日志和报告记录判断结果。
- npx android-midscene-automation 启动时默认使用固定的系统用户数据目录保存脚本、配置、报告和运行态文件，并在启动时尝试迁移旧版启动目录下的数据，降低升级后脚本或配置“不见了”的风险。
- 新增脚本列表复制和重命名能力，可直接生成“原文件名 Copy”副本并修改脚本名称，便于复用已有录制流程。
- 新增检测画面变化能力，支持框选设备预览区域或使用当前选中元素作为检测区域，通过“检测画面变化N-开始节点 / 结束节点”对同一分支内的前后截图进行差异对比。
- 检测画面变化结果写入 Markdown 和 HTML 回放报告，展示检测区域、阈值、最大变化比例、基准帧、对比帧和差异图，HTML 图片支持点击放大查看。
- 新增空节点，用于在顺序流程中作为无操作占位节点，配合画面变化检测或流程编排使用。
- 优化流程图节点插入、删除、复制、缩放和判断分支布局，修复节点新增后连线延迟、缩放后节点不可见、删除检测节点后分支错乱、重复添加同一结束节点等问题。
- 回放报告截图和截图节点改为使用 ADB 截图，避免 Appium /screenshot 超时后堵塞 UiAutomator2 命令队列；Appium 请求超时时也会显示更准确的超时提示。
- 修复流程节点复制与粘贴问题，避免
structuredClone失败、粘贴后原节点消失、分支插入位置错误和复制后相对位置偏移。 - 修复判断分支已有节点时入口添加按钮缺失的问题，分支入口现在会保留可插入节点，并正确连接到首个分支节点。
- 滑动操作支持在添加弹窗和节点配置中修改起点、终点坐标及滑动时长。
- 长按操作支持设置长按时间，并在节点卡片中显示长按坐标和时长。
- Android 设备预览恢复使用 scrcpy 实时流，优化实时流参数，减少 H.264 丢帧导致的花屏；刷新画面时会重启底层 Playground 预览流并等待会话就绪。
- 测试脚本生成新增提示词模板，可在通用提示词、广告测试、表单填写、聊天对话、播放器测试、搜索列表、订单支付、权限弹窗、个人设置和 H5/WebView 等场景间切换，并支持编辑或上传当前原始 Prompt。
- 优化 AI 生成流程，支持后台处理和终止生成；生成中锁定原始 Prompt，再次点击“AI 生成”可恢复进度弹窗，终止后不再弹出额外提示。
- 优化脚本生成提示词策略，区分广告、播放器、弹窗等被测目标与无关遮挡内容，登录流程增加登录后遮挡弹窗处理和无遮挡首页成功判定。
- 参数配置的运行配置新增保存校验，Android SDK 路径必须包含
platform-tools/adb，回放报告目录必须填写已存在且可写入的绝对路径。 - Midscene 自定义提供方的
Model Name和Model Family改为输入框，Base URL匹配已知提供方时自动填充模型名称和模型系列，并在字段旁新增官方配置说明入口。
- 常见问题拆分为独立
FAQ.md文档，并在 README 的“功能文档”中增加跳转入口。
- 升级 Midscene 相关依赖到
v1.12.0
- 录制步骤流程图升级为独立画布与节点卡片视图，优化节点内容排版、操作图标、选中态、批量复制和还原位置体验。
- 统一普通流程线、操作按钮连线和判断分支线条样式，按节点实际高度计算连接位置，修复线条颜色不一致、断裂、多余线条、节点重叠和分支错位问题。
- 优化判断分支布局，统一“是 / 否”分支的 T 形连接样式，避免分支节点堆叠、左右分支连接错乱及多出第三分支。
- 连接脚本支持只读预览，使用眼睛图标打开预览弹窗，预览内容居中展示，修改仍需加载脚本后进行。
- 连接脚本回放时会跳过子脚本开始后的重复“启动 App”和“清除 App”操作，减少跨脚本连接时的重复初始化。
- 移除“连接到下一节点”“取消连接”“继续主流程”等冗余连接操作，保留复制节点作为主要复用方式。
- 修复放大面板后点击操作按钮或节点配置会重置缩放的问题，保持当前画布大小和位置。
- Appium 流程支持单节点、连续节点及完整判断子流程的复制与粘贴。
- 优化判断分支布局和流程总览，支持在总览中编辑完整流程。
- Appium session 与“启动 APP”节点解耦，并避免将桌面、设置等系统 Activity 误识别为脚本入口。
- 修复复杂判断脚本加载失败及加载后无法进入“当前录制”的问题。
- 回放输出支持保留完整 Appium 服务日志，并可在执行过程中手动终止。
- 新增单文件 HTML 截图回放报告，提供时间轴、步骤导航和连续播放效果。
- 使用说明和更新记录自动嵌入 README，可直接在 npm 页面渲染查看。
- 新增在线文档查看入口，支持渲染使用说明和更新记录。
- 优化参数配置页面布局，将预设 App 参数归入运行配置区域。
- README 新增 Midscene 与 Appium 两种测试方式及环境要求说明。
- 明确 Midscene 需要配置模型，Appium 无需模型即可运行。
- 参数配置支持指定 Android SDK 和回放报告目录，并在回放前检查 Android SDK。
- 回放完成后生成包含节点配置、执行结果和日志的 Markdown 报告。
- 脚本列表支持 JSON 脚本导入和下载。
- 设备预览接入 scrcpy 实时画面，组件树可随页面和 Activity 变化自动刷新。
- 回放输出改为实时流式日志，并增强 UIAutomator 并发和异常恢复能力。
- 判断分支支持文本匹配、连接不同 Activity 的脚本及连接后的主流程回放。
- 新增节点备注、未保存提醒和页面状态持久化。
- 修复历史脚本新增节点后无法覆盖保存的问题。
- 修复连接脚本未按顺序继续执行的问题。
- “启动 APP”统一为流程开始节点操作，每个脚本最多添加一次。
- 连接脚本回放时自动跳过子脚本的重复启动操作。
- 修复 npm 页面中的更新记录访问链接。
- npm 包新增项目更新记录，并清理未随包发布的内部文档链接。
- 录制步骤升级为可拖动、缩放和编辑的流程图，支持“是 / 否”判断分支。
- 支持在流程任意位置插入操作，并编辑节点、定位器、超时和输入内容。
- 支持 Activity 跳转检测和单 Activity 脚本录制保护。
- 支持连接已保存脚本，组合登录、首页等跨页面测试流程。
- 新增脚本管理列表，可加载、删除和回放已录制脚本。
- 新增 selector 唯一性检测和父级上下文定位，解决多个组件共用同一 ID 的问题。
- 回放支持多级定位和坐标兜底，并记录页面检查点与完整失败诊断信息。
- 新增存在则点击、输入、清空、返回等可选操作。
- 新增等待出现、判断存在和等待消失等等待与判断能力。
- 新增可复用设备预览，支持点击画面选择组件树节点和刷新实时画面。
- 组件树支持滚动浏览并展示当前 Activity。
- 录制操作统一通过“添加操作”菜单选择。
- 首次提供 Appium 无模型录制与回放能力。
- 支持从组件树录制点击、输入、断言和延时，并保存为可回放脚本。
- App 包名与参数配置中的预设 App 统一管理。
{ "default": { "provider": "openai", "model": "your-model-name", "fallback": { "provider": "openai", "model": "your-fallback-model-name" } }, "nodes": {} }