android-midscene-automation 0.1.30 → 0.1.31

package/CHANGELOG.md

@@ -1,11 +1,16 @@
 # 更新记录
 
-## v0.1.30
+## v0.1.31
+- 组件详情展示 Resource ID、Accessibility ID、XPath 和 UiAutomator 四种定位内容，支持分别复制，方便配置循环退出条件；缺少对应属性时显示未提供。
+- “流程控制”新增有界循环及退出循环：支持固定次数、元素出现或消失时退出，必须设置最大执行次数；循环体支持嵌套判断、合流和连接脚本。退出节点可选择当前或外层循环，退出外层时同时结束内部循环并直接执行目标循环结束路径，日志及 HTML 报告标注轮次和退出目标。
+- 新增流程节点搜索，支持按名称、操作类型、定位内容和日志关键字筛选，展示所属分支并在多个结果间切换；普通画布与流程总览支持定位高亮，不改变节点布局及批量选中状态。
+- Midscene 相关模块统一从 1.12.0 升级至 1.12.2，包含 Android、Android Playground、Core、Playground、Shared 和 Web。
+- 录制工作区支持拖拽调整设备预览、组件树栏宽，自动保存布局并支持恢复默认。 
 
+## v0.1.30
 - 新增节点批量删除功能，支持多选节点，选中节点及所属子节点以柔和红色背景和浅色文字标记，确认后统一删除；支持普通与放大视图同步操作。
 
 ## v0.1.29
-
 - 判断节点新增“合并分支”，支持选择一侧公共流程起点，将两侧后续汇入同一段居中流程；另一侧可保留独有操作或确认删除重复后缀，支持嵌套判断及各类分支，公共节点只执行一次且不随单侧节点删除。
 - 将 Checkbox、RadioButton 判断入口合并为“判断勾选”，新增 Switch 支持；添加和回放时自动校验组件类型及可勾选属性，读取实时 checked 状态进入 true / false 分支，不改变控件状态，兼容已有独立判断节点。
 - “流程控制”新增终止流程节点，执行到该节点时主动结束本次回放，不再执行后续节点或连接脚本；子脚本触发时也结束整个流程，保留执行日志和报告，不作为执行失败。
@@ -13,7 +18,6 @@
 - Appium 配置新增流程背景色设置，默认沿用浅绿色，支持预选颜色、颜色选择器、#RGB / #RRGGBB 输入校验和恢复默认；保存后持久化，普通画布、放大视图和连接脚本预览统一应用。
 
 ## v0.1.28
-
 - Appium 配置中的流程背景色独立成区，与节点模型配置分开展示，保留预选颜色、自定义颜色及保存入口。
 - “组件操作”新增文字点击分支节点，无需预选元素，支持精准匹配和模糊匹配原生组件文字；匹配并点击后进入“匹配到文字”，等待超时未找到则进入“未匹配到文字”。支持编辑文字和超时，多元素匹配及点击异常明确报错，日志和报告保留分支结果。
 - “流程控制”新增输出日志节点，支持设置日志内容和自定义关键字，默认按 `stageLog:内容` 输出；支持添加后编辑，回放实时输出、日志文件及报告均保留日志内容，多行内容逐行添加关键字。
@@ -22,7 +26,6 @@
 - 新增原生 Checkbox 和 RadioButton 状态判断节点，添加时校验选中元素类型，回放时读取 `checked` 属性，按 `true / false` 进入对应分支，不改变勾选状态；组件详情显示原生勾选属性，回放日志和报告记录判断结果。
 
 ## v0.1.27
-
 - npx android-midscene-automation 启动时默认使用固定的系统用户数据目录保存脚本、配置、报告和运行态文件，并在启动时尝试迁移旧版启动目录下的数据，降低升级后脚本或配置“不见了”的风险。
 - 新增脚本列表复制和重命名能力，可直接生成“原文件名 Copy”副本并修改脚本名称，便于复用已有录制流程。
 - 新增检测画面变化能力，支持框选设备预览区域或使用当前选中元素作为检测区域，通过“检测画面变化N-开始节点 / 结束节点”对同一分支内的前后截图进行差异对比。
@@ -32,34 +35,28 @@
 - 回放报告截图和截图节点改为使用 ADB 截图，避免 Appium /screenshot 超时后堵塞 UiAutomator2 命令队列；Appium 请求超时时也会显示更准确的超时提示。
 
 ## v0.1.26
-
 - 修复流程节点复制与粘贴问题，避免 `structuredClone` 失败、粘贴后原节点消失、分支插入位置错误和复制后相对位置偏移。
 - 修复判断分支已有节点时入口添加按钮缺失的问题，分支入口现在会保留可插入节点，并正确连接到首个分支节点。
 - 滑动操作支持在添加弹窗和节点配置中修改起点、终点坐标及滑动时长。
 - 长按操作支持设置长按时间，并在节点卡片中显示长按坐标和时长。
 
 ## v0.1.25
-
 - Android 设备预览恢复使用 scrcpy 实时流，优化实时流参数，减少 H.264 丢帧导致的花屏；刷新画面时会重启底层 Playground 预览流并等待会话就绪。
 - 测试脚本生成新增提示词模板，可在通用提示词、广告测试、表单填写、聊天对话、播放器测试、搜索列表、订单支付、权限弹窗、个人设置和 H5/WebView 等场景间切换，并支持编辑或上传当前原始 Prompt。
 - 优化 AI 生成流程，支持后台处理和终止生成；生成中锁定原始 Prompt，再次点击“AI 生成”可恢复进度弹窗，终止后不再弹出额外提示。
 - 优化脚本生成提示词策略，区分广告、播放器、弹窗等被测目标与无关遮挡内容，登录流程增加登录后遮挡弹窗处理和无遮挡首页成功判定。
 
 ## v0.1.24
-
 - 参数配置的运行配置新增保存校验，Android SDK 路径必须包含 `platform-tools/adb`，回放报告目录必须填写已存在且可写入的绝对路径。
 - Midscene 自定义提供方的 `Model Name` 和 `Model Family` 改为输入框，`Base URL` 匹配已知提供方时自动填充模型名称和模型系列，并在字段旁新增官方配置说明入口。
 
 ## v0.1.23
-
 - 常见问题拆分为独立 `FAQ.md` 文档，并在 README 的“功能文档”中增加跳转入口。
 
 ## v0.1.22
-
 - 升级 Midscene 相关依赖到 `v1.12.0`
 
 ## v0.1.21
-
 - 录制步骤流程图升级为独立画布与节点卡片视图，优化节点内容排版、操作图标、选中态、批量复制和还原位置体验。
 - 统一普通流程线、操作按钮连线和判断分支线条样式，按节点实际高度计算连接位置，修复线条颜色不一致、断裂、多余线条、节点重叠和分支错位问题。
 - 优化判断分支布局，统一“是 / 否”分支的 T 形连接样式，避免分支节点堆叠、左右分支连接错乱及多出第三分支。
@@ -69,36 +66,29 @@
 - 修复放大面板后点击操作按钮或节点配置会重置缩放的问题，保持当前画布大小和位置。
 
 ## v0.1.20
-
 - Appium 流程支持单节点、连续节点及完整判断子流程的复制与粘贴。
 - 优化判断分支布局和流程总览，支持在总览中编辑完整流程。
 - Appium session 与“启动 APP”节点解耦，并避免将桌面、设置等系统 Activity 误识别为脚本入口。
 - 修复复杂判断脚本加载失败及加载后无法进入“当前录制”的问题。
 
 ## v0.1.19
-
 - 回放输出支持保留完整 Appium 服务日志，并可在执行过程中手动终止。
 - 新增单文件 HTML 截图回放报告，提供时间轴、步骤导航和连续播放效果。
 
 ## v0.1.18
-
 - 使用说明和更新记录自动嵌入 README，可直接在 npm 页面渲染查看。
 
 ## v0.1.17
-
 - 新增在线文档查看入口，支持渲染使用说明和更新记录。
 
 ## v0.1.16
-
 - 优化参数配置页面布局，将预设 App 参数归入运行配置区域。
 
 ## v0.1.15
-
 - README 新增 Midscene 与 Appium 两种测试方式及环境要求说明。
 - 明确 Midscene 需要配置模型，Appium 无需模型即可运行。
 
 ## v0.1.14
-
 - 参数配置支持指定 Android SDK 和回放报告目录，并在回放前检查 Android SDK。
 - 回放完成后生成包含节点配置、执行结果和日志的 Markdown 报告。
 - 脚本列表支持 JSON 脚本导入和下载。
@@ -108,25 +98,20 @@
 - 新增节点备注、未保存提醒和页面状态持久化。
 
 ## v0.1.13
-
 - 修复历史脚本新增节点后无法覆盖保存的问题。
 - 修复连接脚本未按顺序继续执行的问题。
 
 ## v0.1.12
-
 - “启动 APP”统一为流程开始节点操作，每个脚本最多添加一次。
 - 连接脚本回放时自动跳过子脚本的重复启动操作。
 
 ## v0.1.11
-
 - 修复 npm 页面中的更新记录访问链接。
 
 ## v0.1.10
-
 - npm 包新增项目更新记录，并清理未随包发布的内部文档链接。
 
 ## v0.1.9
-
 - 录制步骤升级为可拖动、缩放和编辑的流程图，支持“是 / 否”判断分支。
 - 支持在流程任意位置插入操作，并编辑节点、定位器、超时和输入内容。
 - 支持 Activity 跳转检测和单 Activity 脚本录制保护。
@@ -134,23 +119,19 @@
 - 新增脚本管理列表，可加载、删除和回放已录制脚本。
 
 ## v0.1.8
-
 - 新增 selector 唯一性检测和父级上下文定位，解决多个组件共用同一 ID 的问题。
 - 回放支持多级定位和坐标兜底，并记录页面检查点与完整失败诊断信息。
 
 ## v0.1.7
-
 - 新增存在则点击、输入、清空、返回等可选操作。
 - 新增等待出现、判断存在和等待消失等等待与判断能力。
 
 ## v0.1.6
-
 - 新增可复用设备预览，支持点击画面选择组件树节点和刷新实时画面。
 - 组件树支持滚动浏览并展示当前 Activity。
 - 录制操作统一通过“添加操作”菜单选择。
 
 ## v0.1.5
-
 - 首次提供 Appium 无模型录制与回放能力。
 - 支持从组件树录制点击、输入、断言和延时，并保存为可回放脚本。
 - App 包名与参数配置中的预设 App 统一管理。

package/README.md

@@ -1229,12 +1229,17 @@ Linux: ~/.local/share/android-midscene-automation
 
 # 项目更新记录
 
-## v0.1.30
+## v0.1.31
+- 组件详情展示 Resource ID、Accessibility ID、XPath 和 UiAutomator 四种定位内容，支持分别复制，方便配置循环退出条件；缺少对应属性时显示未提供。
+- “流程控制”新增有界循环及退出循环：支持固定次数、元素出现或消失时退出，必须设置最大执行次数；循环体支持嵌套判断、合流和连接脚本。退出节点可选择当前或外层循环，退出外层时同时结束内部循环并直接执行目标循环结束路径，日志及 HTML 报告标注轮次和退出目标。
+- 新增流程节点搜索，支持按名称、操作类型、定位内容和日志关键字筛选，展示所属分支并在多个结果间切换；普通画布与流程总览支持定位高亮，不改变节点布局及批量选中状态。
+- Midscene 相关模块统一从 1.12.0 升级至 1.12.2，包含 Android、Android Playground、Core、Playground、Shared 和 Web。
+- 录制工作区支持拖拽调整设备预览、组件树栏宽，自动保存布局并支持恢复默认。 
 
+## v0.1.30
 - 新增节点批量删除功能，支持多选节点，选中节点及所属子节点以柔和红色背景和浅色文字标记，确认后统一删除；支持普通与放大视图同步操作。
 
 ## v0.1.29
-
 - 判断节点新增“合并分支”，支持选择一侧公共流程起点，将两侧后续汇入同一段居中流程；另一侧可保留独有操作或确认删除重复后缀，支持嵌套判断及各类分支，公共节点只执行一次且不随单侧节点删除。
 - 将 Checkbox、RadioButton 判断入口合并为“判断勾选”，新增 Switch 支持；添加和回放时自动校验组件类型及可勾选属性，读取实时 checked 状态进入 true / false 分支，不改变控件状态，兼容已有独立判断节点。
 - “流程控制”新增终止流程节点，执行到该节点时主动结束本次回放，不再执行后续节点或连接脚本；子脚本触发时也结束整个流程，保留执行日志和报告，不作为执行失败。
@@ -1242,7 +1247,6 @@ Linux: ~/.local/share/android-midscene-automation
 - Appium 配置新增流程背景色设置，默认沿用浅绿色，支持预选颜色、颜色选择器、#RGB / #RRGGBB 输入校验和恢复默认；保存后持久化，普通画布、放大视图和连接脚本预览统一应用。
 
 ## v0.1.28
-
 - Appium 配置中的流程背景色独立成区，与节点模型配置分开展示，保留预选颜色、自定义颜色及保存入口。
 - “组件操作”新增文字点击分支节点，无需预选元素，支持精准匹配和模糊匹配原生组件文字；匹配并点击后进入“匹配到文字”，等待超时未找到则进入“未匹配到文字”。支持编辑文字和超时，多元素匹配及点击异常明确报错，日志和报告保留分支结果。
 - “流程控制”新增输出日志节点，支持设置日志内容和自定义关键字，默认按 `stageLog:内容` 输出；支持添加后编辑，回放实时输出、日志文件及报告均保留日志内容，多行内容逐行添加关键字。
@@ -1251,7 +1255,6 @@ Linux: ~/.local/share/android-midscene-automation
 - 新增原生 Checkbox 和 RadioButton 状态判断节点，添加时校验选中元素类型，回放时读取 `checked` 属性，按 `true / false` 进入对应分支，不改变勾选状态；组件详情显示原生勾选属性，回放日志和报告记录判断结果。
 
 ## v0.1.27
-
 - npx android-midscene-automation 启动时默认使用固定的系统用户数据目录保存脚本、配置、报告和运行态文件，并在启动时尝试迁移旧版启动目录下的数据，降低升级后脚本或配置“不见了”的风险。
 - 新增脚本列表复制和重命名能力，可直接生成“原文件名 Copy”副本并修改脚本名称，便于复用已有录制流程。
 - 新增检测画面变化能力，支持框选设备预览区域或使用当前选中元素作为检测区域，通过“检测画面变化N-开始节点 / 结束节点”对同一分支内的前后截图进行差异对比。
@@ -1261,34 +1264,28 @@ Linux: ~/.local/share/android-midscene-automation
 - 回放报告截图和截图节点改为使用 ADB 截图，避免 Appium /screenshot 超时后堵塞 UiAutomator2 命令队列；Appium 请求超时时也会显示更准确的超时提示。
 
 ## v0.1.26
-
 - 修复流程节点复制与粘贴问题，避免 `structuredClone` 失败、粘贴后原节点消失、分支插入位置错误和复制后相对位置偏移。
 - 修复判断分支已有节点时入口添加按钮缺失的问题，分支入口现在会保留可插入节点，并正确连接到首个分支节点。
 - 滑动操作支持在添加弹窗和节点配置中修改起点、终点坐标及滑动时长。
 - 长按操作支持设置长按时间，并在节点卡片中显示长按坐标和时长。
 
 ## v0.1.25
-
 - Android 设备预览恢复使用 scrcpy 实时流，优化实时流参数，减少 H.264 丢帧导致的花屏；刷新画面时会重启底层 Playground 预览流并等待会话就绪。
 - 测试脚本生成新增提示词模板，可在通用提示词、广告测试、表单填写、聊天对话、播放器测试、搜索列表、订单支付、权限弹窗、个人设置和 H5/WebView 等场景间切换，并支持编辑或上传当前原始 Prompt。
 - 优化 AI 生成流程，支持后台处理和终止生成；生成中锁定原始 Prompt，再次点击“AI 生成”可恢复进度弹窗，终止后不再弹出额外提示。
 - 优化脚本生成提示词策略，区分广告、播放器、弹窗等被测目标与无关遮挡内容，登录流程增加登录后遮挡弹窗处理和无遮挡首页成功判定。
 
 ## v0.1.24
-
 - 参数配置的运行配置新增保存校验，Android SDK 路径必须包含 `platform-tools/adb`，回放报告目录必须填写已存在且可写入的绝对路径。
 - Midscene 自定义提供方的 `Model Name` 和 `Model Family` 改为输入框，`Base URL` 匹配已知提供方时自动填充模型名称和模型系列，并在字段旁新增官方配置说明入口。
 
 ## v0.1.23
-
 - 常见问题拆分为独立 `FAQ.md` 文档，并在 README 的“功能文档”中增加跳转入口。
 
 ## v0.1.22
-
 - 升级 Midscene 相关依赖到 `v1.12.0`
 
 ## v0.1.21
-
 - 录制步骤流程图升级为独立画布与节点卡片视图，优化节点内容排版、操作图标、选中态、批量复制和还原位置体验。
 - 统一普通流程线、操作按钮连线和判断分支线条样式，按节点实际高度计算连接位置，修复线条颜色不一致、断裂、多余线条、节点重叠和分支错位问题。
 - 优化判断分支布局，统一“是 / 否”分支的 T 形连接样式，避免分支节点堆叠、左右分支连接错乱及多出第三分支。
@@ -1298,36 +1295,29 @@ Linux: ~/.local/share/android-midscene-automation
 - 修复放大面板后点击操作按钮或节点配置会重置缩放的问题，保持当前画布大小和位置。
 
 ## v0.1.20
-
 - Appium 流程支持单节点、连续节点及完整判断子流程的复制与粘贴。
 - 优化判断分支布局和流程总览，支持在总览中编辑完整流程。
 - Appium session 与“启动 APP”节点解耦，并避免将桌面、设置等系统 Activity 误识别为脚本入口。
 - 修复复杂判断脚本加载失败及加载后无法进入“当前录制”的问题。
 
 ## v0.1.19
-
 - 回放输出支持保留完整 Appium 服务日志，并可在执行过程中手动终止。
 - 新增单文件 HTML 截图回放报告，提供时间轴、步骤导航和连续播放效果。
 
 ## v0.1.18
-
 - 使用说明和更新记录自动嵌入 README，可直接在 npm 页面渲染查看。
 
 ## v0.1.17
-
 - 新增在线文档查看入口，支持渲染使用说明和更新记录。
 
 ## v0.1.16
-
 - 优化参数配置页面布局，将预设 App 参数归入运行配置区域。
 
 ## v0.1.15
-
 - README 新增 Midscene 与 Appium 两种测试方式及环境要求说明。
 - 明确 Midscene 需要配置模型，Appium 无需模型即可运行。
 
 ## v0.1.14
-
 - 参数配置支持指定 Android SDK 和回放报告目录，并在回放前检查 Android SDK。
 - 回放完成后生成包含节点配置、执行结果和日志的 Markdown 报告。
 - 脚本列表支持 JSON 脚本导入和下载。
@@ -1337,25 +1327,20 @@ Linux: ~/.local/share/android-midscene-automation
 - 新增节点备注、未保存提醒和页面状态持久化。
 
 ## v0.1.13
-
 - 修复历史脚本新增节点后无法覆盖保存的问题。
 - 修复连接脚本未按顺序继续执行的问题。
 
 ## v0.1.12
-
 - “启动 APP”统一为流程开始节点操作，每个脚本最多添加一次。
 - 连接脚本回放时自动跳过子脚本的重复启动操作。
 
 ## v0.1.11
-
 - 修复 npm 页面中的更新记录访问链接。
 
 ## v0.1.10
-
 - npm 包新增项目更新记录，并清理未随包发布的内部文档链接。
 
 ## v0.1.9
-
 - 录制步骤升级为可拖动、缩放和编辑的流程图，支持“是 / 否”判断分支。
 - 支持在流程任意位置插入操作，并编辑节点、定位器、超时和输入内容。
 - 支持 Activity 跳转检测和单 Activity 脚本录制保护。
@@ -1363,23 +1348,19 @@ Linux: ~/.local/share/android-midscene-automation
 - 新增脚本管理列表，可加载、删除和回放已录制脚本。
 
 ## v0.1.8
-
 - 新增 selector 唯一性检测和父级上下文定位，解决多个组件共用同一 ID 的问题。
 - 回放支持多级定位和坐标兜底，并记录页面检查点与完整失败诊断信息。
 
 ## v0.1.7
-
 - 新增存在则点击、输入、清空、返回等可选操作。
 - 新增等待出现、判断存在和等待消失等等待与判断能力。
 
 ## v0.1.6
-
 - 新增可复用设备预览，支持点击画面选择组件树节点和刷新实时画面。
 - 组件树支持滚动浏览并展示当前 Activity。
 - 录制操作统一通过“添加操作”菜单选择。
 
 ## v0.1.5
-
 - 首次提供 Appium 无模型录制与回放能力。
 - 支持从组件树录制点击、输入、断言和延时，并保存为可回放脚本。
 - App 包名与参数配置中的预设 App 统一管理。

package/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Midscene 脚本后台</title>
+    <title>移动自动化控制台</title>
   </head>
   <body>
     <div id="app"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "android-midscene-automation",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oooooooko/android-midscene-automation.git"
@@ -38,12 +38,12 @@
   "dependencies": {
     "@dagrejs/dagre": "1.1.5",
     "@element-plus/icons-vue": "2.3.2",
-    "@midscene/android": "https://registry.npmjs.org/@midscene/android/-/android-1.12.0.tgz",
-    "@midscene/android-playground": "1.12.0",
-    "@midscene/core": "https://registry.npmjs.org/@midscene/core/-/core-1.12.0.tgz",
-    "@midscene/playground": "https://registry.npmjs.org/@midscene/playground/-/playground-1.12.0.tgz",
-    "@midscene/shared": "https://registry.npmjs.org/@midscene/shared/-/shared-1.12.0.tgz",
-    "@midscene/web": "1.12.0",
+    "@midscene/android": "https://registry.npmjs.org/@midscene/android/-/android-1.12.2.tgz",
+    "@midscene/android-playground": "https://registry.npmjs.org/@midscene/android-playground/-/android-playground-1.12.2.tgz",
+    "@midscene/core": "https://registry.npmjs.org/@midscene/core/-/core-1.12.2.tgz",
+    "@midscene/playground": "https://registry.npmjs.org/@midscene/playground/-/playground-1.12.2.tgz",
+    "@midscene/shared": "https://registry.npmjs.org/@midscene/shared/-/shared-1.12.2.tgz",
+    "@midscene/web": "https://registry.npmjs.org/@midscene/web/-/web-1.12.2.tgz",
     "@vitejs/plugin-vue": "6.0.7",
     "@vue-flow/core": "1.48.2",
     "archiver": "7.0.1",

package/server/appium-recorder/appium-runner.ts

@@ -1,4 +1,6 @@
 import { execFile } from 'node:child_process';
+import { BoundedLoopTraversal } from './bounded-loop';
+import { validateLoopSteps } from '../../src/appium-recorder/bounded-loop';
 import { adbScreenshotBase64 } from './screenshot';
 import { recognizeDeviceScreen } from './ai-recognition';
 import { formatStageLog } from '../../src/appium-recorder/stage-log';
@@ -916,6 +918,15 @@ async function readNativeControlState(sessionId: string, step: AppiumRecordedSte
 }
 
 async function evaluateCondition(sessionId: string, deviceId: string, step: AppiumRecordedStepRecord) {
+  if (step.type === 'loop') {
+    if (step.loop?.exitWhen === 'never') return false;
+    const selector = toAppiumUsing(step.selector!);
+    const payload = await appiumRequest<AppiumValueResponse<Record<string, string>[]>>(`/session/${sessionId}/elements`, {
+      method: 'POST', body: JSON.stringify(selector),
+    });
+    if (!Array.isArray(payload.value)) throw new Error('循环退出条件查询返回了无效结果');
+    return step.loop?.exitWhen === 'exists' ? payload.value.length > 0 : payload.value.length === 0;
+  }
   if (step.type === 'textClick') {
     const selector = textClickSelector(step);
     const deadline = Date.now() + Math.max(0, step.timeoutMs ?? 10000);
@@ -1121,35 +1132,18 @@ async function replayFlowSteps(
   options: ReplayStepOptions = {},
 ) {
   const idToIndex = new Map(steps.map((step, index) => [step.id, index]));
-  const conditionContinuationIndex = (conditionId: string) => {
-    const conditionIndex = idToIndex.get(conditionId);
-    if (conditionIndex === undefined) return undefined;
-    const explicitTargetId = steps[conditionIndex]?.flow?.successTargetId;
-    return explicitTargetId ? idToIndex.get(explicitTargetId) : undefined;
-  };
-  const nextIndexAfterStep = (currentIndex: number, step: AppiumRecordedStepRecord) => {
-    const explicitTargetId = step.flow?.successTargetId;
-    if (explicitTargetId) return idToIndex.get(explicitTargetId);
-    if (!step.flow?.parentConditionId || !step.flow.parentBranch) return currentIndex + 1;
-    const nextStep = steps[currentIndex + 1];
-    const staysInBranch = nextStep?.flow?.parentConditionId === step.flow.parentConditionId
-      && nextStep.flow.parentBranch === step.flow.parentBranch;
-    return staysInBranch
-      ? currentIndex + 1
-      : conditionContinuationIndex(step.flow.parentConditionId);
-  };
+  const traversal = new BoundedLoopTraversal(steps);
+  const nextIndexAfterStep = (index: number, step: AppiumRecordedStepRecord) => traversal.next(step, index);
   const visitedPath: string[] = [];
   let index: number | undefined = 0;
-  let guard = 0;
-  const maxVisits = Math.max(steps.length * 4, 20);
 
   while (typeof index === 'number' && index >= 0 && index < steps.length) {
     if (replayContext.getStore()?.flowEnded) return;
     throwIfReplayStopped();
-    guard += 1;
-    if (guard > maxVisits) throw new Error('流程图可能存在循环，已终止回放');
-
     const step = steps[index];
+    traversal.visit(step);
+    const loopContext = traversal.context(step);
+    const frameStep = loopContext ? { ...step, label: `${step.label}（${loopContext}）` } : step;
     if (shouldSkipLinkedScriptInitStep(options, step)) {
       lines.push(`[节点 ${index + 1}] 跳过：${step.label}（${linkedScriptInitSkipReason(step)}）`);
       index = nextIndexAfterStep(index, step);
@@ -1157,11 +1151,28 @@ async function replayFlowSteps(
     }
     visitedPath.push(step.label);
     const nodeKind = defaultFlowKind(step);
-    lines.push(`[节点 ${index + 1}] 开始：${step.label}`);
-    await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'before', '执行前');
+    lines.push(`[节点 ${index + 1}] 开始：${frameStep.label}`);
+    await captureReplayFrame(sessionId, frameStep, index + 1, options.scriptName || '', 'before', '执行前');
 
     if (nodeKind === 'condition') {
       try {
+        if (step.type === 'loop') {
+          const iterations = traversal.iteration(step);
+          const atLimit = iterations >= step.loop!.maxIterations;
+          const exitMatched = !atLimit && await evaluateCondition(sessionId, deviceId, step);
+          if (atLimit || exitMatched) {
+            const reason = atLimit ? '达到最大次数' : '满足退出条件';
+            lines.push(`[循环 ${step.label}] 结束：${reason}，已执行 ${iterations} 轮`);
+            await captureReplayFrame(sessionId, frameStep, index + 1, options.scriptName || '', 'after', `${reason}，已执行 ${iterations} 轮`);
+            index = traversal.exit(step);
+          } else {
+            const entered = traversal.enter(step);
+            lines.push(`[循环 ${step.label}] 第 ${entered.iteration}/${step.loop!.maxIterations} 轮开始`);
+            await captureReplayFrame(sessionId, frameStep, index + 1, options.scriptName || '', 'after', `第 ${entered.iteration}/${step.loop!.maxIterations} 轮`);
+            index = entered.next;
+          }
+          continue;
+        }
         // AI 节点使用本次执行前截图，并将同一张图片和识别依据写入结果帧。
         const beforeFrame = replayContext.getStore()?.frames.at(-1);
         const recognition = step.type === 'aiRecognition' ? await recognizeDeviceScreen({
@@ -1172,19 +1183,20 @@ async function replayFlowSteps(
         const matched = recognition ? recognition.result : await evaluateCondition(sessionId, deviceId, step);
         if (recognition) lines.push(`[节点 ${index + 1}] AI 识别：${recognition.result}，耗时 ${recognition.durationMs}ms${recognition.reason ? `，依据：${recognition.reason}` : ''}`);
         const branchTargetId = matched ? step.flow?.yesTargetId : step.flow?.noTargetId;
-        const targetId = branchTargetId || step.flow?.successTargetId || '';
+        const next = traversal.branch(step, matched);
+        const targetId = branchTargetId || (next === undefined ? '' : steps[next]?.id) || '';
         const branchLabel = flowBranchLabel(step, matched ? 'yes' : 'no');
         lines.push(`[节点 ${index + 1}] 判断：${branchLabel}${isNativeStateCondition(step) ? `（checked=${matched}）` : ''}${targetId ? `，进入 ${targetId}` : '，流程结束'}`);
         await captureReplayFrame(
           sessionId,
-          step,
+          frameStep,
           index + 1,
           options.scriptName || '',
           'after',
           `判断：${branchLabel}${recognition?.reason ? `；${recognition.reason}` : ''}`,
           recognition?.imageBase64,
         );
-        index = targetId ? idToIndex.get(targetId) : undefined;
+        index = next;
       } catch (error) {
         if (isReplayStopped(error)) {
           lines.push(`[节点 ${index + 1}] 已终止：${step.label}`);
@@ -1201,7 +1213,13 @@ async function replayFlowSteps(
 
     try {
       let softFailed = false;
-      if (step.type === 'runScript') {
+      if (step.type === 'breakLoop') {
+        const exited = traversal.break(step);
+        lines.push(`[循环 ${exited.loop.label}] 第 ${exited.iteration} 轮主动退出`);
+        await captureReplayFrame(sessionId, frameStep, index + 1, options.scriptName || '', 'after', `已退出循环：${exited.loop.label}`);
+        index = exited.next;
+        continue;
+      } else if (step.type === 'runScript') {
         await replayLinkedScript(sessionId, deviceId, step, lines, stack);
       } else {
         const result = await runStep(sessionId, deviceId, step, {
@@ -1211,7 +1229,7 @@ async function replayFlowSteps(
         softFailed = appendRunStepResult(lines, index + 1, result);
       }
       lines.push(`[节点 ${index + 1}] 完成：${step.label}${softFailed ? '（存在软失败，已继续）' : ''}`);
-      await captureReplayFrame(sessionId, step, index + 1, options.scriptName || '', 'after', completedStepStatus(step, softFailed));
+      await captureReplayFrame(sessionId, frameStep, index + 1, options.scriptName || '', 'after', completedStepStatus(step, softFailed));
       index = nextIndexAfterStep(index, step);
     } catch (error) {
       if (isReplayStopped(error)) {
@@ -1259,6 +1277,7 @@ async function replayScriptSteps(
   stack: string[],
   options: ReplayStepOptions = {},
 ) {
+  validateLoopSteps(steps);
   let trailingLinkIndex = steps.length;
   while (
     trailingLinkIndex > 0
@@ -1334,6 +1353,7 @@ export async function replayAppiumScript(
     let stopped = false;
     let managedAppium: Awaited<ReturnType<typeof startManagedAppiumServer>> | null = null;
     try {
+      validateLoopSteps(script.steps);
       lines.push('正在检测 Android SDK...');
       const androidSdk = ensureAndroidSdkAvailable();
       lines.push(`Android SDK 已就绪：${androidSdk.root}`);

package/server/appium-recorder/bounded-loop.ts

@@ -0,0 +1,118 @@
+import type { AppiumRecordedStep } from '../../src/appium-recorder/types';
+import { enclosingLoop, enclosingLoops, breakLoopTarget, validateLoopSteps } from '../../src/appium-recorder/bounded-loop';
+import { defaultFlowKind } from '../../src/appium-recorder/flow-labels';
+
+/** Virtual returns keep the saved flow graph acyclic and preserve branch layout. */
+export class BoundedLoopTraversal {
+  private readonly byId: Map<string, number>;
+  private readonly active = new Map<string, { iteration: number; visited: Set<string> }>();
+  private readonly rootVisited = new Set<string>();
+  private readonly owners = new Map<string, AppiumRecordedStep | undefined>();
+
+  constructor(private readonly steps: AppiumRecordedStep[]) {
+    validateLoopSteps(steps);
+    this.byId = new Map(steps.map((step, index) => [step.id, index]));
+  }
+
+  private target(id?: string) { return id ? this.byId.get(id) : undefined; }
+  private owner(step: AppiumRecordedStep) {
+    if (!this.owners.has(step.id)) this.owners.set(step.id, enclosingLoop(this.steps, step));
+    return this.owners.get(step.id);
+  }
+
+  visit(step: AppiumRecordedStep) {
+    if (step.type === 'loop' && this.active.has(step.id)) return;
+    const owner = this.owner(step);
+    const frame = owner ? this.active.get(owner.id) : undefined;
+    if (owner && !frame) throw new Error('不能从循环外直接进入循环体');
+    const visited = frame?.visited || this.rootVisited;
+    if (visited.has(step.id)) throw new Error('流程存在非有界循环回边，已终止回放');
+    visited.add(step.id);
+  }
+
+  private continuation(step: AppiumRecordedStep, seen = new Set<string>()): number | undefined {
+    if (seen.has(step.id)) throw new Error('流程分支归属存在循环');
+    seen.add(step.id);
+    if (step.flow?.successTargetId) return this.target(step.flow.successTargetId);
+    if (defaultFlowKind(step) === 'condition') {
+      const start = this.byId.get(step.id)!;
+      const sibling = this.steps.findIndex((item, index) => index > start && item.flow?.parentConditionId === step.flow?.parentConditionId && item.flow?.parentBranch === step.flow?.parentBranch);
+      if (sibling >= 0) return sibling;
+    }
+    const parentIndex = this.target(step.flow?.parentConditionId);
+    if (parentIndex === undefined) return;
+    const parent = this.steps[parentIndex]!;
+    if (parent.type === 'loop' && step.flow?.parentBranch === 'yes') return parentIndex;
+    return this.continuation(parent, seen);
+  }
+
+  private returnAtBoundary(step: AppiumRecordedStep, next: number | undefined) {
+    const owner = this.owner(step);
+    if (!owner || !this.active.has(owner.id)) return next;
+    // The end of any nested branch returns to the loop, not to the other branch.
+    if (next === undefined || (this.steps[next]?.id !== owner.id && !this.isInBody(this.steps[next]!, owner.id))) {
+      return this.target(owner.id);
+    }
+    return next;
+  }
+
+  private isInBody(step: AppiumRecordedStep, loopId: string) {
+    let owner = this.owner(step);
+    const seen = new Set<string>();
+    while (owner && !seen.has(owner.id)) {
+      if (owner.id === loopId) return true;
+      seen.add(owner.id); owner = this.owner(owner);
+    }
+    return false;
+  }
+
+  next(step: AppiumRecordedStep, index: number) {
+    let next = this.target(step.flow?.successTargetId);
+    if (!step.flow?.successTargetId) {
+      const sibling = this.steps[index + 1];
+      next = sibling && sibling.flow?.parentConditionId === step.flow?.parentConditionId && sibling.flow?.parentBranch === step.flow?.parentBranch
+        ? index + 1 : this.continuation(step);
+    }
+    return this.returnAtBoundary(step, next);
+  }
+
+  branch(step: AppiumRecordedStep, matched: boolean) {
+    const id = matched ? step.flow?.yesTargetId : step.flow?.noTargetId;
+    return this.returnAtBoundary(step, id ? this.target(id) : this.continuation(step));
+  }
+
+  iteration(step: AppiumRecordedStep) { return this.active.get(step.id)?.iteration || 0; }
+
+  enter(step: AppiumRecordedStep) {
+    const iteration = this.iteration(step) + 1;
+    if (iteration > step.loop!.maxIterations) throw new Error('循环次数超过上限');
+    this.active.set(step.id, { iteration, visited: new Set() });
+    return { iteration, next: this.target(step.flow?.yesTargetId) ?? this.target(step.id) };
+  }
+
+  exit(step: AppiumRecordedStep) {
+    this.active.delete(step.id);
+    return this.returnAtBoundary(step, this.target(step.flow?.noTargetId) ?? this.continuation(step));
+  }
+
+  break(step: AppiumRecordedStep) {
+    const owner = breakLoopTarget(this.steps, step);
+    if (!this.active.has(owner.id)) throw new Error('目标循环当前未执行');
+    // Unwind inner frames without running their completion branches.
+    for (const inner of enclosingLoops(this.steps, step)) {
+      if (inner.id === owner.id) break;
+      this.active.delete(inner.id);
+    }
+    return { loop: owner, iteration: this.iteration(owner), next: this.exit(owner) };
+  }
+
+  context(step: AppiumRecordedStep) {
+    const parts: string[] = [];
+    let owner = this.owner(step);
+    while (owner) {
+      parts.unshift(`${owner.label} 第 ${this.iteration(owner)}/${owner.loop!.maxIterations} 轮`);
+      owner = this.owner(owner);
+    }
+    return parts.join(' / ');
+  }
+}