android-midscene-automation 0.1.42 → 0.2.1

package//346/265/201/347/250/213/350/212/202/347/202/271/346/223/215/344/275/234/350/257/264/346/230/216.md

@@ -0,0 +1,408 @@
+# 流程节点操作说明
+
+本文档对应页面“帮助与版本 → 操作说明 → Appium”，说明当前流程菜单中的节点用途、配置方法和执行结果。AI 识别的模型配置、持续观察、截图去重和场景示例请查看 [AI识别操作说明](./AI识别操作说明.md)。
+
+## 一、通用操作
+
+1. 选择目标设备和预设 App，加载已有脚本或新建脚本。
+2. 对需要定位组件的操作，先在设备预览或 App 组件树中选中目标组件。
+3. 点击流程中的“+”，选择操作分类及具体操作。分支内的“+”会把节点添加到该分支。
+4. 按弹窗要求填写参数。添加后点击节点卡片展开配置；部分操作通过节点上的编辑图标打开专用弹窗。
+5. 检查流程连接并保存脚本，再执行回放。节点名称和备注可用于说明业务目的，名称不会替代实际定位条件。
+
+### 定位与坐标
+
+支持 Resource ID、Accessibility ID、XPath、UiAutomator 定位，部分组件使用父级上下文或定位链限定范围。优先使用稳定且唯一的原生定位，避免把动态文本或列表位置当作永久标识。
+
+坐标以设备截图坐标系为准，不是浏览器窗口坐标。更换分辨率、屏幕方向或页面布局后，应重新确认坐标和检测区域。
+
+### 变量引用
+
+在“预设变量”中设置全局变量或脚本私有变量。在支持文本配置的输入、定位、判断、日志等字段使用 `{{变量名}}`，例如 `{{account}}`。未定义变量会报错。
+
+敏感变量在日志、报告中脱敏，导出时清空敏感值；敏感运行对截图和录屏另有限制。详细说明见[测试变量与子脚本参数](测试变量与子脚本参数.md)。
+
+### 超时、分支与失败
+
+- 常规等待与判断的默认超时时间为 3000ms；已有节点以实际保存值为准。1000ms 等于 1 秒。
+- 分支节点的“超时后处理”可选择终止流程或进入指定侧分支，默认终止。正常判断结果与超时不是同一件事。
+- AI 识别仅在勾选“启用超时”后使用配置时间，默认等待模型完成，仍可手动终止。网络错误或模型服务报错不会被无限等待掩盖。
+- 延时、长按、滑动的时长表示操作持续时间；图像判断还有独立的观察时长，不能把这些参数都理解为查找元素超时。
+- “存在则……”未找到组件可以跳过，但设备断连、请求错误或找到后操作失败，不等同于“未找到”。
+
+### 日志与报告
+
+回放文本日志记录时间、节点编号、执行结果及错误。参数配置 → Appium配置中的“截图与 HTML 报告”默认关闭，开启后才采集报告截图并生成 HTML，截图会增加耗时。AI、图像判断、画面变化等操作需要的截图不依赖此开关。
+
+## 二、组件操作
+
+### 1. 录制点击
+
+**功能：** 回放时重新定位目标组件并点击。
+
+**操作：** 选中组件，在“组件操作”中选择“录制点击”；检查节点的 Selector 和父级定位范围。
+
+**结果与注意：** 点击成功后继续。组件不存在或无法点击时失败。适合按钮、列表项等原生组件，不应与“点击坐标”混用。
+
+### 2. 录制输入
+
+**功能：** 向目标输入组件写入指定内容。
+
+**操作：** 选中输入框，选择“录制输入”，填写文字或 `{{变量名}}`；可在节点中修改文本。
+
+**结果与注意：** 输入成功后继续。需要覆盖旧内容时，建议先添加“清空输入”，不要假设所有输入框都会自动清空。
+
+### 3. 提取变量
+
+**功能：** 读取组件文字或属性，保存到当前运行的脚本变量中。
+
+**操作：** 选中组件，填写变量名，选择 `text`、`content-desc`、`checked`、`selected`、`enabled`、`resource-id`、`class` 等属性；需要时标记为敏感变量。后续通过 `{{变量名}}` 引用。
+
+**结果与注意：** 找不到组件或属性不存在会失败。提取结果按文本保存，只影响运行时变量，不写回预设变量文件。
+
+### 4. 清空输入
+
+**功能：** 清空指定输入组件的内容。
+
+**操作：** 选中输入框，添加“清空输入”，确认定位正确。
+
+**结果与注意：** 成功后继续；组件不存在或不支持清空时失败。与“存在则清空”不同，本操作不自动跳过缺失组件。
+
+### 5. 点击坐标
+
+**功能：** 点击设备屏幕的指定 X、Y 位置，不依赖原生组件定位。
+
+**操作：** 添加节点后检查或修改“坐标 X”“坐标 Y”，确认点位落在目标控件内。
+
+**结果与注意：** 命令成功只代表执行了点击，不代表业务操作一定生效。适合位置固定但难以定位的控件，分辨率或布局变化后需重新校准。
+
+### 6. 长按
+
+**功能：** 按住元素或坐标一段时间后松开，默认按元素定位。
+
+**操作：** 选中目标后添加“长按”，设置长按方式和“长按时间 ms”；使用坐标方式时设置 X、Y。
+
+**结果与注意：** 完成后继续。时长不足可能触发普通点击，时长过长可能触发其他行为，应以目标应用实际交互为准。
+
+### 7. 判断勾选
+
+**功能：** 读取原生 Checkbox、RadioButton、Switch 等可勾选组件的真实 `checked` 状态。
+
+**操作：** 选中目标组件后添加节点。系统检查组件是否支持勾选判断，在 true 和 false 两侧分别添加后续操作。
+
+**结果与注意：** true 表示已勾选，false 表示未勾选；缺失组件、状态不可读取或超时另行处理。普通 ImageView 用图片模拟的选中状态不适用，可使用“图像判断”的图片状态模式。
+
+### 8. 文字点击
+
+**功能：** 在当前页面的原生组件树中匹配指定文字并点击。
+
+**操作：** 输入目标文字，例如“音频设置”；选择精准匹配（完全一致）或模糊匹配（包含），配置等待时间及超时处理。
+
+**结果与注意：** 提供“匹配到文字”和“未匹配到文字”分支。找到文字后点击失败仍会报错。不能识别图片、视频或自绘画面中的文字；重复文字应尽量通过更明确的条件避免误点。
+
+## 三、设备操作
+
+### 9. 系统返回
+
+**功能：** 发送 Android 返回键。
+
+**操作：** 在目标位置添加“系统返回”。
+
+**结果与注意：** 返回上一页、关闭弹窗或收起键盘等具体效果由当前界面决定，不保证每次都退回同一页面。
+
+### 10. Home 键
+
+**功能：** 返回设备桌面。
+
+**操作：** 添加“Home 键”，需要回到应用时在后面添加“启动 App”。
+
+**结果与注意：** 应用通常仍在后台，Home 不等于杀死应用或清除数据。
+
+### 11. 最近任务
+
+**功能：** 打开 Android 最近任务界面。
+
+**操作：** 添加“最近任务”；如需进一步操作任务卡片，另加点击或滑动节点。
+
+**结果与注意：** 不会自动切换或关闭指定应用，任务界面布局因系统而异。
+
+### 12. 电源键
+
+**功能：** 发送设备电源键操作。
+
+**操作：** 添加“电源键”，根据设备当前状态组织后续流程。
+
+**结果与注意：** 可能熄屏或唤醒，不保证自动解锁；锁屏后可能无法继续操作应用。
+
+### 13. 滑动
+
+**功能：** 从指定起点滑动到终点。
+
+**操作：** 配置起点 X、Y，终点 X、Y 和“时长 ms”。
+
+**结果与注意：** 手势结束后继续。起点需位于实际可滑动区域，距离和时长会影响滚动或翻页效果。
+
+### 14. 双指缩放
+
+**功能：** 执行双指放大或缩小手势。
+
+**操作：** 配置缩放方向、中心 X、Y 和缩放比例，中心点应位于支持缩放的内容区域。
+
+**结果与注意：** 应用必须支持该手势；命令成功不代表画面一定发生缩放。
+
+### 15. 清理 App 缓存
+
+**功能：** 实际执行的是清除应用数据与缓存，重置目标应用状态。
+
+**操作：** 仅允许在流程开始处添加，检查目标 App 包名后再运行。
+
+**结果与注意：** **不是仅删除缓存。可能清除登录信息、应用设置和本地数据。** 只应对允许重置的测试应用使用。后续通常需要重新启动应用、处理权限和登录。
+
+### 16. 启动 App
+
+**功能：** 启动指定包名的应用，支持在流程中途和分支中使用。
+
+**操作：** 添加节点并确认“目标 APP 包名”；可在节点中修改目标。
+
+**结果与注意：** 应用必须安装并具有可启动入口。启动不保证重置进程或回到首页，需要重启时可先添加“杀死 APP”。
+
+### 17. 杀死 APP
+
+**功能：** 停止指定包名的应用进程。
+
+**操作：** 添加节点，检查默认填入的包名或修改“目标 APP 包名”。
+
+**结果与注意：** 不卸载应用、不清除数据。需要再次使用时，在后续添加“启动 App”。
+
+### 18. 启动相册
+
+**功能：** 尝试打开设备可用的相册应用；启动前先停止目标相册进程。
+
+**操作：** 添加“启动相册”。进入后如需选择媒体，另加相应操作。
+
+**结果与注意：** 只负责打开，不自动选择照片或视频。不同系统的应用入口和权限可能不同，不能保证所有设备都有可用相册。
+
+## 四、等待断言
+
+### 19. 添加延时
+
+**功能：** 暂停指定时长后继续。
+
+**操作：** 输入毫秒数，例如 `5000` 表示等待 5 秒；添加后可修改。
+
+**结果与注意：** 延时不检查页面是否加载完成。日志中相邻操作的总间隔还可能包含截图、设备命令等耗时，需要等待明确组件时优先使用“等待出现”。
+
+### 20. 判断存在
+
+**功能：** 判断目标组件是否存在，可同时检查文本匹配条件。
+
+**操作：** 选中组件后添加，检查定位；需要时填写“指定文本（可选）”，选择精准或模糊匹配，在“是”“否”两侧添加操作。
+
+**结果与注意：** 按判断结果走分支，等待超时按“超时后处理”执行。它不等于判断按钮可点击，也不等于读取勾选状态。
+
+### 21. 图像判断
+
+**功能：** 使用本地 OpenCV 比较指定区域，不调用大模型。一个节点即可完成判断并提供 true/false 分支，无需成对添加。
+
+**操作：** 选择检测模式，再选择当前元素或在设备预览中框选区域；按模式采集或上传 PNG 模板、设置参数，保存节点。
+
+| 检测模式 | 配置及用途 |
+| --- | --- |
+| 模板匹配 | 采集目标模板，设置匹配严格度及“匹配到模板/未匹配到模板”预期，判断固定图标是否符合预期。 |
+| 图片状态判断 | 分别采集选中、未选中模板，配置匹配严格度和最小得分差，用于图片模拟的单选状态。true 表示选中，false 表示未选中；证据不足则无法判定。 |
+| 黑屏检测 | 设置暗色像素容差和占比，判断区域是否达到黑屏条件。 |
+| 区域颜色判断 | 填写 `#RRGGBB` 目标颜色，配置颜色容差和像素占比。 |
+| 多帧变化检测 | 设置观察时长、采样间隔、像素容差、变化比例及变化预期，比较观察期间的图像。 |
+
+**参数说明：** 匹配严格度越高，模板匹配要求越严；100% 可能因极细微像素差异不匹配。观察时长、采样间隔及连续满足帧数需相互合理，具体可设置字段随模式变化。
+
+**结果与注意：** true 表示符合配置预期，不总是表示“找到了图片”。例如预期“未匹配到模板”时，没找到才是 true。观察超时按超时处理，不一定直接进入 false 分支。模板比检测区域大、尺寸变化或双模板得分无法区分等情况会提示无法判定。
+
+模板不会自动缩放。检测区域可调整，但不能缩小到容不下模板；应扩大区域或重新采集。适合固定图标、颜色和像素变化，不适合业务语义判断或任意文字识别，也不能仅凭静态外观证明按钮可用或视频卡死。
+
+### 22. AI 识别
+
+**功能：** 将设备截图和问题发送给已配置的视觉模型，支持顺序回答和分支判断。
+
+**操作：**
+
+1. 在“参数配置 → Appium配置 → AI 识别模型”填写并保存 Base URL、API Key、Model Name，使用支持图片输入的模型。
+2. 添加“AI 识别”，填写问题。新节点默认不启用分支，例如可以填写“当前画面有什么内容”。回答写入日志后继续下一节点。
+3. 需要判断时，在节点配置中勾选“启用分支”。系统立即使用模型验证问题文本，验证时不上传设备截图。
+4. 验证通过后生成 true/false 分支；非判断问题会提示“无法进入分支”并取消勾选。推荐问题：“当前是否显示设备列表？”
+5. 分支模式下修改问题，点击“验证并保存问题”；验证失败不保存本次修改。已有子分支时，需先移除子分支才能关闭分支模式。
+6. 启用分支后，可按需要勾选“启用兜底”，再选择进入左侧 true 分支或右侧 false 分支。问号中说明兜底的适用范围。模型未返回有效内容或没有返回预期的 true/false 时才使用该选择；正常识别到布尔结果时仍按实际结果执行。
+7. 可选勾选“启用超时”，再配置时间和超时处理。默认不勾选，等待模型完成，仍支持手动终止。
+8. 使用节点上的“测试 AI 识别”按钮检查当前画面的回答或判断依据，不必执行整个脚本。
+
+**结果与注意：** 顺序模式记录回答后继续；分支模式必须得到明确布尔值。未配置兜底时，无有效结果会使节点失败；配置后才进入指定分支。兜底只处理模型空内容、无效 JSON、`result: null` 或缺少布尔值，不处理模型请求失败、网络异常、设备截图失败和节点超时。模型正文、判断依据、兜底方向和错误都会写入日志。旧版 AI 节点保留原有分支。
+
+AI 可能误判；问题验证通过也不代表运行时一定能判断。设备截图会发给配置的模型服务，可能产生费用，请确认服务可信并注意画面中的隐私。远程设备暂不支持单节点 AI 测试。
+
+### 23. 存在则点击
+
+**功能：** 找到组件时点击，未找到时跳过。
+
+**操作：** 选中可能出现的组件，添加节点，配置定位和等待时间。
+
+**结果与注意：** 不生成左右分支，点击或跳过后顺序继续；适合偶发弹窗。找到组件但点击失败仍会报错。
+
+### 24. 存在则输入
+
+**功能：** 找到输入框时输入文字，否则跳过。
+
+**操作：** 选中输入框，填写输入内容或变量引用，配置等待时间。
+
+**结果与注意：** 输入或跳过后继续，不生成分支。需要覆盖旧值时可配合“存在则清空”。
+
+### 25. 存在则清空
+
+**功能：** 找到输入框时清空内容，否则跳过。
+
+**操作：** 选中输入组件并添加，检查定位和等待时间。
+
+**结果与注意：** 清空或跳过后继续，实际清空失败仍会报错。
+
+### 26. 存在则返回
+
+**功能：** 指定组件出现时执行系统返回，否则跳过。
+
+**操作：** 选择能够代表某个弹窗或页面的组件，再添加节点。
+
+**结果与注意：** 执行的是系统返回，不是点击所选组件；适合关闭可选弹窗或页面。
+
+### 27. 等待出现
+
+**功能：** 等待目标组件出现。
+
+**操作：** 选中目标、检查定位，设置超时时间。
+
+**结果与注意：** 出现后继续，超时未出现则失败。不会自动点击该组件。
+
+### 28. 等待元素消失
+
+**功能：** 等待目标组件不再存在。
+
+**操作：** 选择加载提示、遮罩等目标组件，配置等待时间。
+
+**结果与注意：** 消失后继续；开始时已不存在可直接通过，超时仍存在则失败。不能把设备通信错误当成消失。
+
+### 29. 等待 Activity
+
+**功能：** 等待设备切换到指定 Android Activity。
+
+**操作：** 参考组件树下方显示的 Activity，填写“目标 Activity”和超时时间。
+
+**结果与注意：** 匹配后继续，超时失败。一个 Activity 可能承载多个页面，必要时再检查页面中的组件。
+
+### 30. 检测画面变化开始节点
+
+**功能：** 记录指定组件或区域的基准截图，供对应结束节点比较。
+
+**操作：** 在待观察操作之前添加开始节点，选择当前元素或手动框选区域，设置变化阈值、像素容差及检测标记。
+
+**结果与注意：** 开始节点不阻塞等待画面变化；只有执行到匹配的结束节点时才比较。未添加结束节点或运行路径没有经过结束节点，则不做比较。
+
+### 31. 检测画面变化结束节点
+
+**功能：** 截取结束时的目标区域，与指定开始节点记录的基准比较。
+
+**操作：** 在实际操作之后添加结束节点，选择同一可达路径上尚可匹配的开始节点。多组检测可显式选择对应关系，不要求按最后开始的顺序结束。
+
+**结果与注意：** 开始于判断之前的检测，可在其不同分支结束；只在 yes 分支开始的检测，不能在兄弟 no 分支结束。同一路径不能重复结束同一组检测。变化未达预期记录结果并继续，不作为左右分支节点。
+
+例如：开始节点 → 点击按钮 → 等待出现或延时 → 结束节点。该功能比较两次截图，不是持续轮询，也不判断变化后的业务内容是否正确。
+
+## 五、流程控制
+
+### 32. 空节点
+
+**功能：** 不执行设备操作，仅作为占位节点。
+
+**操作：** 在“流程控制”中添加，可修改名称以说明流程位置。
+
+**结果与注意：** 立即继续；空节点不是延时，不应依靠它等待画面刷新。
+
+### 33. 终止流程
+
+**功能：** 正常结束整个当前回放，后续节点不再执行。
+
+**操作：** 添加到满足结束条件的路径中。
+
+**结果与注意：** 与执行失败不同；在连接脚本中执行也会结束整个回放，不是只返回调用方。只想结束循环时使用“退出循环”。
+
+### 34. 有界循环
+
+**功能：** 重复执行循环体，达到次数上限或满足退出条件后进入“循环结束”路径。
+
+**操作：** 选择固定次数、元素出现时退出或元素消失时退出；设置执行次数或最大执行次数。条件模式还需选择定位方式并填写定位内容。把重复操作放入“循环体”，后续操作放入“循环结束”。
+
+**结果与注意：** 次数范围为 1–10000，当前实现必须设置最大次数，不提供最大时长模式。条件在每轮开始前检查，首次即满足可不执行循环体；达到次数上限是正常退出。日志标注轮次。
+
+### 35. 退出循环
+
+**功能：** 提前退出指定的当前循环或外层循环。
+
+**操作：** 在循环体内添加，并从“退出目标循环”选择目标，默认最内层；常配合判断分支使用。
+
+**结果与注意：** A 包含 B 时，退出 B 后继续 B 的结束路径；退出 A 时同时结束 B 和 A，直接执行 A 的结束路径。不能退出不包含当前位置的循环，也不能从子脚本退出调用方循环。
+
+### 36. 继续下一次循环
+
+**功能：** 结束本轮执行，跳过循环体内当前节点之后的操作，直接进入指定循环的下一轮。
+
+**操作：** 在循环体内选择“循环 → 继续下一次循环”，再选择当前循环或包含当前位置的外层循环。常放在判断分支中，例如本轮未出图时返回列表页后进入下一轮。
+
+**结果与注意：** 选择当前循环时，只跳过当前循环本轮剩余节点；选择外层循环时，会同时结束内层循环的当前执行并进入外层下一轮。目标循环达到最大次数后，不会再开始新一轮，而是执行该循环的“循环结束”路径。不能选择不包含当前位置的循环，也不能从子脚本控制调用方循环。
+
+### 37. 输出日志
+
+**功能：** 输出指定关键字和内容，方便搜索执行阶段与变量值。
+
+**操作：** 填写日志内容，按需修改默认关键字 `stageLog`。例如关键字 `login`、内容 `当前账号：{{account}}`。
+
+**结果与注意：** 文本日志显示类似 `login:当前账号：...` 的内容，并带执行时间和节点信息；启用 HTML 报告时也展示日志内容。敏感变量会脱敏。该节点不执行设备操作。
+
+### 38. 连接脚本
+
+**功能：** 执行已有子脚本，正常完成后返回当前脚本继续。
+
+**操作：** 选择目标脚本，按需设置传入参数和返回值映射。传入值可引用当前变量；返回映射填写“子脚本变量名 → 当前脚本变量名”。
+
+**结果与注意：** 子脚本具有独立变量作用域，不自动继承父脚本私有变量；需显式传参。指定返回值不存在会失败，子脚本主动终止整个流程时不执行返回映射。连接脚本可能跳过其入口的应用初始化节点，避免重复初始化，具体以运行日志中的“跳过”说明为准。
+
+导出包含连接关系的脚本时，会递归收集连接脚本到 ZIP；无连接时导出单个 JSON。启用回放录屏时，连接脚本可关联独立视频片段。
+
+## 六、旧脚本兼容节点
+
+以下类型仍可能出现在旧脚本中，但不是当前主操作菜单中的独立新增入口。
+
+| 节点 | 功能和使用方式 |
+| --- | --- |
+| 断言存在 | 校验组件存在，不满足则失败。新流程使用“判断存在”组织结果路径。 |
+| 断言文本 | 校验组件文字是否满足预期，不满足则失败。新流程可使用“判断存在”的文本条件。 |
+| Checkbox 状态、RadioButton 状态 | 读取对应原生组件的勾选状态，提供 true/false 分支。新流程统一使用“判断勾选”。 |
+| 截图 | 执行时保存设备截图，独立于报告截图开关；敏感运行不保存截图文件。截图存于应用数据根目录下的 `.midscene-app/screenshots`。 |
+| 旧版画面变化节点 | 保留历史配置兼容。新流程建议使用命名配对的开始/结束节点，不应直接照搬旧版单节点配置。 |
+
+## 七、不是执行节点的流程工具
+
+- **开始：** 表示流程入口，通过下方“+”添加首个操作，不是“启动 App”的替代品。
+- **合并分支：** 将分支后续公共操作接到共同路径，支持双向选择；合并按钮可切换为取消合并。它改变连接关系，不执行设备操作。
+- **复制、粘贴、批量复制、批量删除：** 编辑流程结构，不执行节点。删除判断节点会连同所属子分支删除，操作前检查范围。
+- **搜索与定位：** 按名称、操作类型、定位内容或日志关键字查找节点，定位并高亮，不改变布局。
+- **还原位置、流程总览：** 调整画布显示，不改变执行顺序。
+
+## 八、常见组合
+
+| 目标 | 示例流程 |
+| --- | --- |
+| 登录 | 启动 App → 等待出现 → 清空输入 → 录制输入账号 → 录制输入密码 → 录制点击 → 判断存在。 |
+| 处理偶发弹窗 | 启动 App → 存在则点击关闭按钮 → 后续流程。 |
+| 查看 AI 描述 | AI 识别“当前画面有什么内容”，不启用分支 → 下一节点；在日志中查看回答。 |
+| AI 判断页面 | AI 识别“是否显示设备列表”，启用分支并验证 → true 继续，false 输出日志或终止流程；需要容错时再配置无有效结果兜底。 |
+| 校验点击后的变化 | 检测画面变化开始 → 点击 → 等待出现 → 对应结束节点。 |
+| 图片单选状态 | 图像判断选择“图片状态判断”，配置两张模板 → true 已选中，false 未选中时点击。 |
+| 多轮稳定性测试 | 有界循环 → 循环体内切换页面并检查 → 本轮失败时返回初始页并“继续下一次循环” → 达到次数或成功时“退出循环” → 循环结束后的汇总日志。 |
+
+以上示例只表示节点组合方式，实际定位、超时、分支及预期结果必须结合目标应用配置。