android-midscene-automation 0.1.16 → 0.1.18

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 更新记录
 
+## v0.1.18
+
+- 修复 jsDelivr 将 HTML 文档显示为源码的问题；使用说明和更新记录改为自动嵌入 README，由 npm 页面直接渲染。
+
+## v0.1.17
+
+- README 中的使用说明与更新记录链接改为 HTML 文档查看器，点击后直接显示渲染后的 Markdown 内容。
+
 ## v0.1.16
 
 - 参数配置页调整卡片顺序，将“预设 App 参数”移动到“运行配置”下方。

package/README.md

@@ -51,8 +51,8 @@ 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)
+- [Appium 录制器使用说明](#appium-录制器使用说明)
+- [项目更新记录](#项目更新记录)
 
 ## 源码开发
 
@@ -157,3 +157,1173 @@ scripts-output/                # 保存的脚本输出
 output/                        # Appium 回放 Markdown 报告（可在运行配置中修改）
 midscene_run/                  # Midscene 执行报告和运行产物
 ```
+
+<!-- generated-docs:start -->
+
+# Appium 录制器使用说明
+
+本文档说明 Appium 组件树录制器的完整使用方式，包括每个操作按钮的用途、录制方法和示例。
+
+本文档随 npm 包发布，也可以从 README 的“功能文档”直接打开。
+
+## 使用前准备
+
+### 1. 连接 Android 设备
+
+```sh
+adb devices -l
+```
+
+确认设备已连接，并且手机已允许 USB 调试。
+
+### 2. 启动 Appium
+
+```sh
+appium
+```
+
+如果没有安装 UiAutomator2 Driver：
+
+```sh
+appium driver install uiautomator2
+```
+
+### 3. 启动项目
+
+```sh
+npx --yes android-midscene-automation@latest
+```
+
+或源码开发：
+
+```sh
+npm install
+npm run dev
+```
+
+打开页面后进入 `Appium` 菜单。
+
+### 4. 配置运行路径（可选）
+
+进入“参数配置 > 运行配置”可以设置：
+
+- `Android SDK 路径`：填写包含 `platform-tools/adb` 的 SDK 根目录。留空时依次读取 `ANDROID_SDK_ROOT`、`ANDROID_HOME`、系统常见 SDK 目录和 PATH 中的 ADB。
+- `回放报告目录`：填写 Markdown 回放报告的保存目录。支持绝对路径；相对路径以启动命令所在目录为基准。留空时使用启动目录下的 `output`。
+
+回放开始前会检测 Android SDK。检测失败时不会创建 Appium session，回放输出会直接显示需要修正的 SDK 路径。
+
+## 基本录制流程
+
+1. 选择设备。
+2. 在“参数配置”中添加预设 App 参数。
+3. 回到 `Appium` 页面，在“节点与脚本”区域选择预设 App。
+4. 等待设备预览和 App 组件树自动加载；必要时点击“刷新组件树”。
+5. 在设备预览或 App 组件树中选择目标组件。
+6. 在“开始”节点或任意步骤后的“插入操作”中选择要录制的操作。
+7. 在“录制步骤”中检查流程、编辑节点备注并配置判断分支。
+8. 输入脚本名称并保存。
+9. 选择已保存脚本后点击“回放”。
+
+App 包名是必填项，只能从“参数配置”中已经添加的“预设 App 参数”选择，不能手动输入。未选择 App 时不能录制操作。
+
+## 设备预览与组件树
+
+### 设备预览
+
+- 设备预览优先使用 Midscene Playground 的 scrcpy 实时画面，可以直接点击和滑动手机画面。
+- 点击预览中的组件后，组件树会定位并选中对应节点，默认同时显示组件边框。
+- 实时流不可用时会自动使用 ADB 截图轮询，避免两种画面来源相互覆盖。
+- 画面停止更新时，可点击设备预览工具栏中的刷新按钮重新获取画面。
+
+### App 组件树
+
+- 首次进入页面、切换设备、Activity 变化或页面结构变化后，组件树会自动刷新。
+- 自动刷新会尽量保留仍然存在的已选节点。
+- 录制操作、回放和手动刷新期间会暂停自动刷新，结束后自动恢复。
+- 组件树支持横向和纵向滚动；下方“当前 Activity”最多显示三行。
+- 手动点击“刷新组件树”可立即重新抓取当前页面结构。
+
+注意：Appium 回放和组件树抓取都会占用 Android UiAutomation。系统会按设备串行执行，并在连接被抢占时清理残留进程后自动重试一次。
+
+## 流程图节点
+
+录制步骤以流程图节点展示。
+
+节点类型：
+
+- 操作：执行点击、输入、滑动、返回等动作。
+- 判断：根据页面状态走“是 / 否”分支。
+- 校验：验证页面是否满足预期。
+
+点击节点可以展开编辑面板，支持修改：
+
+- 节点名称
+- 备注，例如“登录按钮”“账号输入框”
+- 节点类型
+- 超时时间
+- 输入文本
+- 是否可选
+- selector 和父级上下文 selector
+- 判断节点的指定文本与匹配方式
+
+流程画布支持以下操作：
+
+- 按住空白区域或节点拖动画布。
+- 按住 `Ctrl` 并滚动鼠标滚轮，在 `50%` 到 `200%` 之间缩放。
+- 点击“放大”打开流程总览；总览中同样可以点击节点编辑。
+- 点击节点后的“插入操作”可在任意步骤中间新增操作。
+- 点击节点右上角删除按钮可移除节点，流程引用会自动修正。
+- 浏览器刷新后会保持当前功能页面和 Appium 工作区 Tab；存在未保存修改时，刷新或关闭页面前会提示保存。
+
+### 单 Activity 录制规则
+
+每个脚本只允许录制一个 Activity。录制点击后如果检测到 Activity 发生变化，会强制弹出保存提示；保存完成后清空当前流程，并从新 Activity 开始录制新脚本。
+
+加载历史脚本时，如果手机当前 Activity 与脚本入口 Activity 不一致，流程编辑会锁定。此时可执行脚本中的“启动 APP”节点，或插入“系统返回”使页面回到脚本绑定的 Activity；Activity 匹配后自动解除锁定。
+
+## 操作说明
+
+### 录制点击
+
+用途：点击某个组件。
+
+操作方法：
+
+1. 在设备预览或组件树中选择按钮、图标、列表项等组件。
+2. 点击“添加操作”。
+3. 选择“录制点击”。
+
+示例：
+
+```text
+点击 登录按钮
+点击 添加设备入口
+点击 我的 Tab
+```
+
+适用场景：
+
+- 点击按钮。
+- 点击列表项。
+- 点击页面入口。
+
+注意：
+
+- 优先使用组件 selector。
+- 如果 Appium 找不到组件，会使用 bounds 坐标兜底。
+
+### 录制输入
+
+用途：向输入框输入文本。
+
+操作方法：
+
+1. 选择输入框组件。
+2. 点击“添加操作”。
+3. 选择“录制输入”。
+4. 在弹窗中输入文本。
+
+示例：
+
+```text
+输入 账号输入框：test@example.com
+输入 密码输入框：123456
+```
+
+适用场景：
+
+- 账号输入。
+- 密码输入。
+- 搜索框输入。
+- 表单字段输入。
+
+注意：
+
+- 如果账号框和密码框底层 id 一样，录制器会自动保存父级上下文 selector；回放时会先找父级，再找子输入框。
+- 录制后可以展开节点修改输入内容。
+
+### 清空输入
+
+用途：清空输入框已有内容。
+
+操作方法：
+
+1. 选择输入框组件。
+2. 点击“添加操作”。
+3. 选择“清空输入”。
+
+示例：
+
+```text
+清空 搜索框
+输入 搜索框：摄像机
+```
+
+适用场景：
+
+- 搜索框重复测试。
+- 输入框默认已有内容。
+- 修改表单字段前先清空。
+
+### 点击坐标
+
+用途：按当前组件中心坐标点击，不依赖 selector。
+
+操作方法：
+
+1. 选择目标区域。
+2. 点击“添加操作”。
+3. 选择“点击坐标”。
+
+示例：
+
+```text
+点击坐标 540,1680
+```
+
+适用场景：
+
+- 组件树识别不到的自绘区域。
+- selector 不稳定，但坐标稳定的按钮。
+
+注意：
+
+- 对分辨率、横竖屏、布局变化敏感。
+- 能用组件点击时，不建议优先用坐标点击。
+
+### 长按
+
+用途：长按某个组件或坐标。
+
+操作方法：
+
+1. 选择目标组件。
+2. 点击“添加操作”。
+3. 选择“长按”。
+
+示例：
+
+```text
+长按 设备卡片
+```
+
+适用场景：
+
+- 长按打开菜单。
+- 长按删除列表项。
+- 长按进入编辑模式。
+
+默认长按时间为 `800ms`，可展开节点修改超时时间。
+
+### 返回键
+
+用途：执行 Android 返回键。
+
+操作方法：
+
+1. 点击“添加操作”。
+2. 选择“返回键”。
+
+示例：
+
+```text
+点击设备详情
+返回键
+断言存在 设备列表
+```
+
+适用场景：
+
+- 从详情页返回列表页。
+- 关闭页面。
+- 关闭系统弹窗或软键盘。
+
+### Home 键
+
+用途：执行 Android Home 键。
+
+操作方法：
+
+1. 点击“添加操作”。
+2. 选择“Home 键”。
+
+示例：
+
+```text
+Home 键
+启动 App
+```
+
+适用场景：
+
+- 验证 App 从后台恢复。
+- 回到桌面后重新启动 App。
+
+### 最近任务
+
+用途：打开 Android 最近任务页面。
+
+操作方法：
+
+1. 点击“添加操作”。
+2. 选择“最近任务”。
+
+示例：
+
+```text
+最近任务
+Home 键
+```
+
+适用场景：
+
+- 验证多任务切换。
+- 验证 App 后台状态。
+
+### 电源键
+
+用途：发送 Android 电源键。
+
+操作方法：
+
+1. 点击“添加操作”。
+2. 选择“电源键”。
+
+示例：
+
+```text
+电源键
+添加延时 1000ms
+电源键
+```
+
+适用场景：
+
+- 锁屏 / 亮屏相关测试。
+
+注意：
+
+- 不同设备锁屏行为可能不同。
+- 自动化回放时请确认设备不会因锁屏无法继续操作。
+
+### 滑动
+
+用途：执行上、下、左、右滑动。
+
+操作方法：
+
+1. 点击“添加操作”。
+2. 选择“滑动”。
+3. 输入方向：`上`、`下`、`左`、`右`。
+
+示例：
+
+```text
+下滑
+断言存在 下一页内容
+```
+
+适用场景：
+
+- 列表滚动。
+- 页面翻页。
+- 轮播切换。
+
+### 双指缩放
+
+用途：执行双指放大或缩小。
+
+操作方法：
+
+1. 点击“添加操作”。
+2. 选择“双指缩放”。
+3. 输入方向：`放大` 或 `缩小`。
+
+示例：
+
+```text
+双指放大
+双指缩小
+```
+
+适用场景：
+
+- 地图缩放。
+- 图片预览缩放。
+- 视频画面缩放。
+
+### 启动 App
+
+用途：启动当前选择的预设 App。
+
+操作方法：
+
+1. 先选择预设 App 参数。
+2. 在录制步骤的“开始”节点下点击“插入操作”。
+3. 选择“启动 App”，该操作会作为流程第一步插入。
+
+示例：
+
+```text
+启动 App
+等待 Activity com.example.MainActivity
+```
+
+适用场景：
+
+- 脚本第一步启动目标 App。
+- 从桌面或其他 App 回到目标 App。
+
+“启动 APP”只能从开始节点添加，并且每个脚本只能有一个启动节点。添加后菜单中的“启动 App”会自动置灰，删除该节点后恢复可用。启动时会通过 ADB 使用当前预设 App 参数中保存的包名打开应用。
+
+录制时可以点击启动节点上的执行按钮立即启动 App，并刷新当前 Activity。回放前会先检查目标 App 是否已在前台：已经启动时跳过“启动 APP”节点并保留当前页面；通过“连接脚本”进入子脚本时，也会跳过子脚本中的启动节点。
+
+### 添加延时
+
+用途：等待固定时间。
+
+操作方法：
+
+1. 点击“添加操作”。
+2. 选择“添加延时”。
+3. 输入毫秒数。
+
+也可以在流程节点后点击“插入延时”。
+
+示例：
+
+```text
+点击 登录按钮
+添加延时 1000ms
+断言存在 首页元素
+```
+
+适用场景：
+
+- 等动画结束。
+- 等网络请求短暂完成。
+- 等系统弹窗出现。
+
+注意：
+
+- 优先使用“等待 Activity”“断言存在”等状态等待。
+- 固定延时越多，脚本越慢。
+
+### 判断存在
+
+用途：判断某个组件或指定文本是否出现，并根据结果走不同分支。它可以用于弹窗，也可以用于按钮、列表项、提示文案等普通页面组件。
+
+操作方法：
+
+1. 选择目标组件上的稳定元素，例如标题、按钮、列表项或提示文案。
+2. 点击“添加操作”。
+3. 选择“判断存在”。
+4. 点击判断节点，按需填写“指定文本”。
+5. 选择“模糊匹配（包含）”或“精准匹配（完全一致）”。
+6. 在“是”或“否”分支下点击“插入操作”，分别添加分支步骤。
+7. 需要回到判断后的主流程时，点击分支旁的“连接到下一节点”；连接成功后按钮变为“取消连接”。
+
+示例：
+
+```text
+判断存在 确认按钮
+  是 -> 点击 确认按钮
+  否 -> 继续主流程
+```
+
+分支说明：
+
+- 未配置指定文本时，只判断目标组件是否存在。
+- 配置指定文本后，会同时检查组件及其子节点文本。
+- 模糊匹配会忽略换行和连续空白差异，只要规范化后的文本包含目标内容即可。
+- 精准匹配要求 Appium 返回的完整文本与指定文本完全一致。
+- 分支可以包含多个连续步骤，也可以在分支末尾连接其他脚本。
+- “连接到下一节点”只在判断后仍有主流程节点时显示。
+
+适用场景：
+
+- 首次启动确认弹窗。
+- 权限说明弹窗。
+- 活动弹窗。
+- 只出现一次的引导弹窗。
+
+### 判断同组件不同内容弹窗
+
+用途：同一个页面有两个弹窗复用同一个组件，只是标题或正文不同，需要按文案区分弹窗类型。
+
+操作方法：
+
+1. 选择能覆盖弹窗正文的节点；如果文本位于子节点中，也可以选择其稳定父容器。
+2. 点击“添加操作”。
+3. 选择“判断存在”。
+4. 展开节点，在“指定文本”中输入该弹窗特有的文案。
+5. 根据需要选择模糊匹配或精准匹配。
+6. 在“是”分支添加该弹窗对应的确认、取消或关闭步骤；“否”分支继续下一个判断或主流程。
+
+示例：
+
+```text
+判断存在：指定文本“是否删除设备”
+  是 -> 点击 确定
+  否 -> 判断存在：指定文本“是否退出登录”
+        是 -> 点击 确定
+        否 -> 继续主流程
+```
+
+适用场景：
+
+- 两个弹窗 `resource-id`、按钮 id、class 都一样。
+- 同一个弹窗组件展示不同业务文案。
+- 需要根据弹窗内容执行不同分支。
+
+注意：
+
+- 弹窗不是必出现时，先用“判断存在”形成分支，不要直接使用“断言文本”，否则弹窗未出现会让回放失败。
+- 不要只判断“确定”按钮是否存在，这会把两个弹窗都识别成同一种弹窗。
+- 优先用弹窗标题、正文、关键提示文案作为判断目标。
+- 节点详情里的 selector 会显示当前 Activity，方便确认该定位属于哪个页面。
+
+### 存在则点击
+
+用途：元素出现时点击，不出现时跳过。
+
+操作方法：
+
+1. 选择可能出现的按钮，例如权限确认、协议同意、活动关闭。
+2. 点击“添加操作”。
+3. 选择“存在则点击”。
+
+示例：
+
+```text
+存在则点击 同意按钮
+存在则点击 关闭活动弹窗
+```
+
+适用场景：
+
+- 一次性弹窗。
+- 偶尔出现的活动弹窗。
+- 首次启动协议确认。
+
+### 存在则输入
+
+用途：输入框出现时输入文本，不出现时跳过。
+
+操作方法：
+
+1. 选择可能出现的输入框。
+2. 点击“添加操作”。
+3. 选择“存在则输入”。
+4. 在居中弹窗中输入文本。
+
+示例：
+
+```text
+存在则输入 搜索框：摄像机
+```
+
+录制后可展开节点修改输入内容。
+
+### 存在则清空
+
+用途：输入框出现时清空，不出现时跳过。
+
+示例：
+
+```text
+存在则清空 搜索框
+存在则输入 搜索框：摄像机
+```
+
+### 存在则返回
+
+用途：某个遮挡元素或页面出现时执行返回键，不出现时跳过。
+
+示例：
+
+```text
+存在则返回 权限说明页
+存在则返回 引导页
+```
+
+适用场景：
+
+- 临时引导页。
+- 偶尔出现的中间页。
+- 可通过系统返回关闭的遮挡页面。
+
+### 等待出现
+
+用途：等待页面加载到某个目标状态。
+
+操作方法：
+
+1. 选择目标页面的稳定元素。
+2. 点击“添加操作”。
+3. 选择“等待出现”。
+
+示例：
+
+```text
+点击 登录按钮
+等待出现 首页设备列表
+```
+
+适用场景：
+
+- 页面跳转后等待目标元素出现。
+- 单 Activity App 无法通过 Activity 判断页面时。
+
+### 断言存在
+
+用途：校验页面上必须存在某个组件。
+
+操作方法：
+
+1. 选择目标组件。
+2. 点击“添加操作”。
+3. 选择“断言存在”。
+
+示例：
+
+```text
+断言存在 首页设备列表
+断言存在 登录失败提示
+```
+
+适用场景：
+
+- 校验登录成功。
+- 校验页面跳转成功。
+- 校验按钮或列表存在。
+
+注意：
+
+- 断言失败表示测试失败。
+- 不建议用于可有可无的弹窗。
+
+### 断言文本
+
+用途：校验组件文本是否包含指定内容。
+
+操作方法：
+
+1. 选择带文本的组件。
+2. 点击“添加操作”。
+3. 选择“断言文本”。
+4. 输入要校验的文本。
+
+示例：
+
+```text
+断言文本 登录失败提示：密码错误
+断言文本 页面标题：设备
+```
+
+适用场景：
+
+- 校验错误提示。
+- 校验标题。
+- 校验列表文案。
+
+### 等待元素消失
+
+用途：等待某个组件从页面上消失。
+
+操作方法：
+
+1. 选择 loading、弹窗或遮罩组件。
+2. 点击“添加操作”。
+3. 选择“等待元素消失”。
+
+示例：
+
+```text
+点击 登录按钮
+等待元素消失 loading
+断言存在 首页设备列表
+```
+
+适用场景：
+
+- 等 loading 结束。
+- 等弹窗关闭。
+- 等遮罩消失。
+
+### 等待 Activity
+
+用途：等待 Android 当前 Activity 切换到指定值。
+
+操作方法：
+
+1. 点击“添加操作”。
+2. 选择“等待 Activity”。
+3. 输入目标 Activity。
+
+示例：
+
+```text
+点击 登录按钮
+等待 Activity com.example.MainActivity
+```
+
+适用场景：
+
+- 点击按钮后进入新页面。
+- 启动 App 后等待首页 Activity。
+
+注意：
+
+- 有些 App 使用单 Activity 架构，Activity 不会变化，这时应改用“断言存在”判断页面元素。
+
+### 连接脚本
+
+用途：把一个已保存脚本连接到当前脚本后继续执行。
+
+操作方法：
+
+1. 先保存被连接的脚本，例如“首页脚本”。
+2. 打开当前脚本，例如“登录脚本”。
+3. 在主流程节点或判断分支下点击“插入操作”。
+4. 选择“连接脚本”，再选择目标脚本。
+5. 保存当前脚本。
+
+校验规则：
+
+- 主流程中连接脚本：插入点 Activity 优先使用前一步录制的 `pageAfter.activity`，只允许选择入口 Activity 与插入点一致的脚本。
+- 判断分支中连接脚本：允许选择同一 App 的其他 Activity 脚本，适合登录成功后进入首页等跳转路径。
+- 分支连接在回放时会等待手机进入目标脚本的入口 Activity；页面没有真正跳转时会超时失败，不会提前执行其他页面的步骤。
+- 目标脚本必须属于当前 App，且不能连接当前脚本自身。
+- 脚本互相连接形成循环时，回放会终止并提示循环连接。
+
+示例：
+
+```text
+登录脚本：
+  输入账号
+  输入密码
+  点击登录
+  连接脚本：首页脚本
+
+首页脚本：
+  启动 App
+  断言存在 首页元素
+  点击设备列表
+  断言存在 设备详情
+```
+
+适用场景：
+
+- 测试人员不知道点击后页面是什么。
+- 登录流程和首页流程由不同人录制。
+- 复用公共前置流程。
+
+回放行为：
+
+- 不重新创建 Appium session。
+- 子脚本中的“启动 App”节点会自动跳过，不会重新启动 App。
+- 在当前页面状态继续执行目标脚本。
+- 子脚本单独回放时仍会正常执行自己的“启动 App”节点。
+- 如果脚本互相连接形成循环，会终止并提示循环连接。
+
+## 脚本保存与管理
+
+### 保存和更新
+
+- 新脚本需要填写名称并选择预设 App 后保存。
+- 从顶部脚本下拉框或“脚本列表”加载历史脚本后，再次点击“保存”会更新原脚本，不会因为名称相同而报错。
+- 脚本数据只保存流程图 `flow_json`，其中包含主流程、判断分支、连接关系、节点备注和页面检查点。
+- 已保存脚本加载后会校验当前 Activity；页面不匹配时按“单 Activity 录制规则”锁定编辑。
+
+### 脚本列表
+
+在“录制与脚本”区域切换到“脚本列表”Tab，可以：
+
+- 加载脚本：回到“当前录制”继续查看、编辑或回放。
+- 下载脚本：导出包含完整流程的 JSON 文件。
+- 导入脚本：选择此前导出的 JSON 文件；名称重复时自动生成新名称，不覆盖已有脚本。
+- 删除脚本：删除数据库中的已录制脚本。
+
+导入脚本后仍需在本机配置对应的预设 App，并连接可用的 Android 设备。
+
+## 回放输出与报告
+
+### 实时日志
+
+点击“回放”后，日志会随着执行过程实时追加，不需要等待整个脚本结束。所有流程统一使用 `[节点 N]` 编号，常见内容包括：
+
+```text
+[节点 1] 开始：启动 APP com.example.app
+[节点 1] 结果：APP 已在前台，跳过启动 com.example.app
+[节点 1] 完成：启动 APP com.example.app
+[节点 2] 判断：是
+```
+
+“回放输出”默认只保留最近 `80` 行的可视高度，避免无限撑长页面。可以使用：
+
+- 复制：复制当前完整日志。
+- 展开查看：在弹窗中查看完整日志。
+- 清除：清空页面上的回放输出。
+
+### Markdown 回放报告
+
+每次回放结束后，无论成功或失败，都会生成 Markdown 报告。文件名格式为：
+
+```text
+当前日期时间-脚本名称.md
+```
+
+报告保存到“参数配置 > 运行配置”指定的目录；没有指定时，默认保存在启动命令所在目录的 `output` 文件夹中，例如：
+
+```text
+output/2026-08-21_17-13-42-831-登录流程.md
+```
+
+报告包含：
+
+- 脚本、App、Activity、设备、执行时间和结果。
+- 每个节点的类型、selector、上下文 selector、输入值、超时、备注和分支配置。
+- 每个节点的实际执行状态与执行信息。
+- 完整回放日志。
+
+生成成功后，报告绝对路径会追加到实时回放日志中，并保存到数据库，便于后续追溯。
+
+## 组合示例
+
+### 示例 1：登录成功后连接首页脚本
+
+登录脚本：
+
+```text
+启动 App
+输入 账号
+输入 密码
+判断存在 用户协议弹窗
+  是 -> 点击 同意
+  否 -> 连接到下一节点
+点击 登录
+判断登录是否成功
+  是 -> 连接脚本 首页脚本
+  否 -> 断言文本 登录错误提示
+```
+
+首页脚本：
+
+```text
+启动 App
+断言存在 首页设备列表
+点击 添加设备
+断言存在 添加设备页面标题
+```
+
+适合场景：
+
+- 录制登录时不知道登录成功后跳到哪个页面。
+- 首页流程希望独立维护。
+
+### 示例 2：登录成功 / 失败分支
+
+```text
+输入 账号
+输入 密码
+点击 登录
+判断 首页设备列表是否存在
+  是 -> 断言存在 首页设备列表
+  否 -> 断言文本 登录错误提示
+```
+
+操作方法：
+
+1. 先录制输入和点击登录。
+2. 选择用于区分登录结果的稳定元素，添加“判断存在”。
+3. 在“是”分支插入首页校验或“连接脚本”。
+4. 在“否”分支插入错误提示断言。
+5. 需要继续执行判断后的公共步骤时，点击对应分支的“连接到下一节点”。
+
+### 示例 3：一次性弹窗
+
+```text
+启动 App
+判断存在 确认按钮
+  是 -> 点击 确认按钮
+  否 -> 连接到下一节点
+断言存在 首页
+```
+
+适合场景：
+
+- 只第一次安装后出现的确认弹窗。
+- 老用户不再出现的弹窗。
+
+### 示例 4：列表滚动查找元素
+
+```text
+启动 App
+断言存在 列表页标题
+上滑
+添加延时 500ms
+断言存在 目标列表项
+```
+
+如果列表加载慢，可以把固定延时换成目标元素断言。
+
+### 示例 5：从详情页返回列表页
+
+```text
+点击 设备卡片
+断言存在 设备详情标题
+返回键
+断言存在 设备列表
+```
+
+适合场景：
+
+- 校验页面返回路径。
+- 校验返回后列表仍可见。
+
+## 常见问题
+
+### 同一个 id 定位到错误输入框怎么办
+
+如果账号框和密码框都是 `id/tg_edit`，只按 id 回放可能输入到第一个输入框。
+
+建议：
+
+- 直接分别选择账号框和密码框录制输入。
+- 在节点详情里确认 selector 是否显示“重复 N”，以及“推荐定位”是否显示父级 + 子级。
+- 如果推荐定位不准确，展开录制步骤，手动修改父级上下文 selector。
+- 坐标点击只作为最后兜底。
+
+### 点击后没有检测到页面跳转怎么办
+
+可能原因：
+
+- 按钮当前禁用。
+- 账号密码不正确。
+- App 使用单 Activity，Activity 不变化。
+- 页面跳转依赖网络。
+
+推荐：
+
+- 使用“断言存在”判断下个页面核心元素。
+- 多 Activity 页面可以拆成两个脚本，在判断分支中用“连接脚本”串起来；回放会等待目标 Activity 出现。
+- 单 Activity App 不要依赖 Activity 变化，应使用页面核心元素判断是否已进入目标状态。
+
+### 为什么连接脚本提示入口 Activity 不匹配
+
+- 主流程连接要求目标脚本入口 Activity 与当前插入点一致，适合复用同一页面上的公共流程。
+- 登录后进入首页等跨 Activity 场景，应先添加“判断存在”，再在“是”或“否”分支中添加“连接脚本”。
+- 分支连接允许选择同一 App 的其他 Activity，但不会主动跳转页面；前面的点击或输入必须真正触发跳转。
+- 如果页面未跳转，回放会在等待目标 Activity 超时后失败，这是为了防止在错误页面执行目标脚本。
+
+### 弹窗只出现一次怎么办
+
+使用“判断存在”。
+
+```text
+判断存在 确认按钮
+  是 -> 点击 确认按钮
+  否 -> 继续主流程
+```
+
+不要直接把弹窗确认按钮作为普通必选点击，否则弹窗不出现时脚本会失败。
+
+### 什么时候用等待 Activity
+
+适合多 Activity App。
+
+如果 App 是单 Activity 架构，优先用：
+
+```text
+断言存在 页面核心元素
+```
+
+### 什么时候用可选步骤
+
+可选步骤适合非主流程阻塞项：
+
+- 权限弹窗
+- 协议弹窗
+- 活动弹窗
+- 首次引导
+
+不建议把登录按钮、提交按钮、核心断言设置为可选。
+
+### 回放时出现 UiAutomation not connected 怎么办
+
+组件树刷新和 Appium 回放不能同时占用 UiAutomation。当前版本会在回放期间暂停组件树自动刷新，并在断开时清理残留抓取进程后重试一次。
+
+如果仍然失败：
+
+1. 确认手机保持解锁，USB 调试授权没有失效。
+2. 确认 Appium 和 UiAutomator2 Driver 已正常启动。
+3. 停止其他正在抓取同一设备组件树的工具。
+4. 重新连接设备后再次回放。
+
+### 设备预览或组件树没有更新怎么办
+
+1. 先确认设备仍显示在设备下拉框中。
+2. 点击设备预览刷新按钮重新获取画面。
+3. 点击“刷新组件树”重新抓取页面结构。
+4. 回放期间组件树自动刷新会暂停，回放完成后会自动恢复。
+
+## 推荐录制规范
+
+- 每个脚本只负责一个清晰场景。
+- 登录、首页、详情页可以拆成多个脚本，用“连接脚本”组合。
+- 每次页面跳转后，添加一个“断言存在”或“等待 Activity”。
+- 弹窗或其他可选组件使用“判断存在”，不要直接写死必点。
+- 坐标点击只作为兜底。
+- 给关键节点填写“登录按钮”“账号输入框”等备注，方便查看流程和报告。
+- 判断分支需要回到主流程时，明确点击“连接到下一节点”。
+- 回放失败后优先查看“回放输出”中的失败节点、Activity 和 selector，再打开 `output` 中的 Markdown 报告查看完整配置。
+
+# 项目更新记录
+
+## v0.1.18
+
+- 修复 jsDelivr 将 HTML 文档显示为源码的问题；使用说明和更新记录改为自动嵌入 README，由 npm 页面直接渲染。
+
+## v0.1.17
+
+- README 中的使用说明与更新记录链接改为 HTML 文档查看器，点击后直接显示渲染后的 Markdown 内容。
+
+## v0.1.16
+
+- 参数配置页调整卡片顺序，将“预设 App 参数”移动到“运行配置”下方。
+
+## v0.1.15
+
+- README 新增 Midscene 与 Appium 两种测试方式对比，明确 Midscene 必须配置模型，Appium 不依赖模型。
+- README 环境要求补充 Appium 3.x、UiAutomator2 Driver 的安装与启动说明。
+- README 明确 Android 测试不需要 Playwright Chromium，仅源码中的 Web E2E 示例需要单独安装。
+
+## 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 模块：修复加载历史脚本并新增节点后被误判为新脚本、无法覆盖保存的问题。
+- Appium 模块：脚本末尾的连接节点改为当前脚本完成后的串联阶段，避免判断分支未命中时漏掉后一个脚本。
+
+## v0.1.12
+
+- 修复部分浏览器打开更新记录时中文乱码的问题，将 README 链接切换到明确返回 UTF-8 编码的 jsDelivr。
+- Appium 模块：删除结束节点、前置操作和后置操作；“启动 APP”改为从开始节点直接插入为流程第一步，并对齐开始节点与插入按钮。
+- Appium 模块：每个录制脚本只允许一个“启动 APP”节点；添加后操作菜单自动禁用该选项，删除节点后恢复。
+- Appium 模块：连接脚本回放时自动跳过子脚本的“启动 APP”节点，子脚本独立回放时仍正常启动 App。
+
+## v0.1.11
+
+- 修复 npm 页面中的项目更新记录链接，改为使用可直接访问包文件的 unpkg 地址。
+
+## v0.1.10
+
+- npm 包新增根目录 `CHANGELOG.md`，README 可直接查看项目更新记录。
+- README 删除未随 npm 包发布的内部文档链接。
+
+## v0.1.9
+
+- Appium 模块：录制流程新增前置操作和后置操作区域，分别固定在“开始”之前和“结束”之后，目前仅支持“启动 APP”和“添加延时”。
+- Appium 模块：“启动 APP”回放时通过 ADB 启动当前预设 App 参数对应的应用包。
+- Appium 模块：节点详情的 selector 展示新增当前 Activity。
+- 文档：新增同组件不同内容弹窗的判断操作说明。
+- Appium 模块：“判断弹窗”改名为“判断存在”，支持用于弹窗以外的任意组件判断。
+- Appium 模块：判断节点的“是 / 否”分支支持直接插入操作，并自动连接到新步骤。
+- Appium 模块：判断节点分支内插入的步骤会按“是 / 否”归类展示，不再混入主线单列。
+- Appium 模块：判断节点后的步骤改为沿“是 / 否”分支线向下延伸，不再嵌套在分支容器中。
+- Appium 模块：统一分支步骤节点宽度与居中对齐，并补充删除节点操作。
+- Appium 模块：检测到 Activity 跳转时强制保存当前脚本，每份录制脚本限制在单个 Activity 内。
+- Appium 模块：录制步骤画布支持按住 Ctrl 使用鼠标滚轮缩放，缩放范围为 50%–200%。
+- Appium 模块：修复可拖动画布吞掉分支节点删除点击的问题，并在删除后自动修正流程目标引用。
+- Appium 模块：操作入口移动到录制流程的“开始”节点下方；分支仅关联从“是/否”入口插入的操作，并统一分支节点卡片与间距。
+- Appium 模块：加载已保存脚本时校验绑定 Activity；当前页面不一致时锁定流程编辑，避免跨 Activity 继续追加录制步骤。
+- Appium 模块：步骤操作新增“系统返回”（Android keyCode 4）；Activity 不匹配时仅允许将该操作插入脚本，其他流程编辑继续锁定。
+- Appium 模块：连接脚本按插入点 Activity 过滤并校验目标脚本入口 Activity；回放时再次校验手机当前 Activity，阻止尚未跳转就执行其他页面脚本。
+- Appium 模块：普通流程步骤与展开编辑面板改为紧凑宽度，减少可拖动画布中的横向空白。
+- Appium 模块：修复可拖动画布捕获步骤卡片点击的问题，步骤详情现在可通过再次点击卡片正常收起。
+- Appium 模块：判断节点分支支持连续追加多个操作。
+- Appium 模块：录制步骤区域改为可拖拽流程画布，默认显示第一个节点视角。
+- Appium 模块：录制步骤区域新增“放大”按钮，可弹出流程总览查看全部节点。
+- Appium 模块：判断分支线条改为连续曲线样式，减少断线和空白间隔。
+- Appium 模块：判断节点展示改为左右分叉流程样式。
+- Appium 模块：支持在任意录制步骤后插入其他操作。
+- Appium 模块：录制步骤改为流程图节点样式。
+- Appium 模块：支持点击步骤节点展开编辑面板。
+- Appium 模块：支持修改节点名称、节点类型、超时时间、输入内容和可选状态。
+- Appium 模块：支持编辑 selector 和父级上下文 selector。
+- Appium 模块：支持判断节点配置“是 / 否”分支目标。
+- Appium 模块：检测到页面变化时支持留在当前页面、保存为新用例或添加返回键继续录制。
+- Appium 模块：支持连接已保存脚本，用于登录脚本接首页脚本等组合场景。
+- Appium 模块：新增脚本列表 Tab，支持加载和删除已录制脚本。
+- Appium 模块：回放输出支持展开查看和清除日志。
+- Appium 模块：脚本存储移除旧版 `steps_json`，只保留 `flow_json`。
+
+## v0.1.8
+
+- Appium 模块：组件树新增 selector 唯一性检测。
+- Appium 模块：组件树节点展示“唯一”或“重复 N”状态。
+- Appium 模块：重复 selector 自动记录父级上下文定位信息。
+- Appium 模块：回放时支持“父级上下文 + 子级 selector”定位。
+- Appium 模块：回放查找顺序调整为父级上下文、备用 selector、当前 selector、坐标兜底。
+- Appium 模块：每个录制步骤新增页面检查点，保存录制前后 Activity 和页面摘要。
+- Appium 模块：回放失败日志新增当前 Activity、selector、上下文 selector、备用 selector 和录制前后 Activity。
+
+## v0.1.7
+
+- Appium 模块：新增“存在则点击”操作。
+- Appium 模块：新增“存在则输入”操作。
+- Appium 模块：新增“存在则清空”操作。
+- Appium 模块：新增“存在则返回”操作。
+- Appium 模块：新增“等待出现”操作。
+- Appium 模块：新增“判断存在”操作。
+- Appium 模块：新增“等待元素消失”操作。
+- Appium 模块：“存在则...”类操作找不到目标时不再中断回放，并在日志中显示“未出现，已跳过”。
+
+## v0.1.6
+
+- Appium 模块：新增设备预览复用组件。
+- Appium 模块：设备预览支持点击画面选择组件树节点。
+- Appium 模块：设备预览支持刷新当前画面。
+- Appium 模块：App 组件树区域支持滚动浏览。
+- Appium 模块：App 组件树下方展示当前 Activity。
+- Appium 模块：操作按钮统一为“添加操作”下拉列表。
+- Appium 模块：删除截图操作入口。
+
+## v0.1.5
+
+- Appium 模块：新增组件树录制页面。
+- Appium 模块：支持从组件树选择节点并录制点击、输入、断言、延时。
+- Appium 模块：支持保存 Appium 录制脚本。
+- Appium 模块：支持通过 Appium 回放录制脚本。
+- Appium 模块：App 包名只能从“预设 App 参数”中选择。
+
+<!-- generated-docs:end -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "android-midscene-automation",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "type": "module",
   "bin": {
     "android-midscene-automation": "./bin/android-midscene-automation.js"
@@ -19,6 +19,7 @@
   ],
   "scripts": {
     "dev": "vite --host 127.0.0.1",
+    "prepack": "node scripts/sync-readme-docs.mjs",
     "remote-agent": "tsx remote-agent/index.ts",
     "build": "vue-tsc -b && vite build",
     "preview": "vite preview --host 127.0.0.1",