android-midscene-automation 0.1.22 → 0.1.23

package/CHANGELOG.md

@@ -1,9 +1,12 @@
 # 更新记录
 
+## v0.1.23
+
+- 常见问题拆分为独立 `FAQ.md` 文档，并在 README 的“功能文档”中增加跳转入口。
+
 ## v0.1.22
 
-- 升级 Midscene 相关依赖到 `v1.12.0`，跟进官方发布说明：https://github.com/web-infra-dev/midscene/releases/tag/v1.12.0
-- 跟进 Midscene `v1.12.0` 的 Test Runner Beta、报告 wall/model call time 汇总、`deepseek-v4-flash-vision-exp` 支持，以及 Android ASAR 外部二进制路径修复。
+- 升级 Midscene 相关依赖到 `v1.12.0`
 
 ## v0.1.21
 

package/FAQ.md

@@ -0,0 +1,91 @@
+# 常见问题
+
+## 同一个 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. 回放期间组件树自动刷新会暂停，回放完成后会自动恢复。

package/README.md

@@ -32,7 +32,7 @@ appium driver install uiautomator2
 ## 启动
 
 ```sh
-npx android-midscene-automation
+npx --yes android-midscene-automation@latest
 ```
 
 启动后访问：
@@ -52,6 +52,7 @@ npx android-midscene-automation --port 5174
 ## 功能文档
 
 - [Appium 录制器使用说明](#appium-录制器使用说明)
+- [常见问题](./FAQ.md)
 - [项目更新记录](#项目更新记录)
 
 ## 源码开发
@@ -164,7 +165,7 @@ midscene_run/                  # Midscene 执行报告和运行产物
 
 本文档说明 Appium 组件树录制器的完整使用方式，包括每个操作按钮的用途、录制方法和示例。
 
-本文档随 npm 包发布，也可以从 README 的“功能文档”直接打开。
+本文档随 npm 包发布，也可以从 README 的“功能文档”直接打开。常见问题请查看 [FAQ.md](./FAQ.md)。
 
 ## 使用前准备
 
@@ -1107,95 +1108,7 @@ output/2026-08-21_17-13-42-831-登录流程.html
 
 ## 常见问题
 
-### 同一个 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. 回放期间组件树自动刷新会暂停，回放完成后会自动恢复。
+常见问题已独立整理到 [FAQ.md](./FAQ.md)。
 
 ## 推荐录制规范
 
@@ -1209,10 +1122,13 @@ output/2026-08-21_17-13-42-831-登录流程.html
 
 # 项目更新记录
 
+## v0.1.23
+
+- 常见问题拆分为独立 `FAQ.md` 文档，并在 README 的“功能文档”中增加跳转入口。
+
 ## v0.1.22
 
-- 升级 Midscene 相关依赖到 `v1.12.0`，跟进官方发布说明：https://github.com/web-infra-dev/midscene/releases/tag/v1.12.0
-- 跟进 Midscene `v1.12.0` 的 Test Runner Beta、报告 wall/model call time 汇总、`deepseek-v4-flash-vision-exp` 支持，以及 Android ASAR 外部二进制路径修复。
+- 升级 Midscene 相关依赖到 `v1.12.0`
 
 ## v0.1.21
 

package/USAGE.md

@@ -2,7 +2,7 @@
 
 本文档说明 Appium 组件树录制器的完整使用方式，包括每个操作按钮的用途、录制方法和示例。
 
-本文档随 npm 包发布，也可以从 README 的“功能文档”直接打开。
+本文档随 npm 包发布，也可以从 README 的“功能文档”直接打开。常见问题请查看 [FAQ.md](./FAQ.md)。
 
 ## 使用前准备
 
@@ -945,95 +945,7 @@ output/2026-08-21_17-13-42-831-登录流程.html
 
 ## 常见问题
 
-### 同一个 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. 回放期间组件树自动刷新会暂停，回放完成后会自动恢复。
+常见问题已独立整理到 [FAQ.md](./FAQ.md)。
 
 ## 推荐录制规范
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "android-midscene-automation",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oooooooko/android-midscene-automation.git"
@@ -23,6 +23,7 @@
     "vite.config.ts",
     "README.md",
     "USAGE.md",
+    "FAQ.md",
     "CHANGELOG.md"
   ],
   "scripts": {