UI 场景使用文档
一、页面布局
- 左侧：场景目录树（与 API 场景相互独立），支持搜索、右键新建、拖拽排序
- 右侧：步骤编排区，支持两种视图切换：
- 列表模式：步骤树（条件/循环步骤可展开子步骤）
- 工作流画布：图形化节点视图，支持拖拽排序、自动布局
- 顶部：调试控制（开始/暂停/继续/停止/重试）、场景配置、保存
二、场景配置
点「场景配置」弹窗：
| 配置 | 选项 | 说明 |
|---|---|---|
| 浏览器 | Chrome / Firefox / Edge / IE / Safari | Edge 用本机 Edge 内核；IE/Safari 走 WebKit |
| 运行方式 | 无头 / 有头 | 调试建议有头（看得见浏览器）；计划任务用无头 |
| 窗口模式 | 最大化 / 自定义尺寸 | 自定义默认 2560x1440 |
| 设备类型 | PC / 移动端 | 移动端注入手机 UA、360x640 视口、触屏模拟 |
| 执行设置 | 错误策略 / 超时 / 截图 | 默认：失败即停、单步超时 15s、每步截图 |
三、步骤编排
3.1 步骤类型一览
| 分类 | 步骤 |
|---|---|
| 页面 | 打开页面、后退、前进、刷新、关闭页面、切换页签 |
| 元素操作 | 点击（单击/双击/右键/长按/下拉选择）、悬停、拖拽、键盘输入 |
| 结构 | iframe 切换、对话框（接受/关闭/抓取文案）、文件上传、DOM 操作（改属性/样式/class/派发事件） |
| 数据 | 关联提取（页面/元素值存变量）、断言 |
| 控制流 | 条件 IF、循环 FOR（次数/文件驱动）、条件循环 WHILE（带上限保护）、等待 |
| 接口 | API 请求（在 UI 流程中混排调接口，如前置造数/后置校验） |
3.2 编排操作
- 步骤行「+」添加相邻/子步骤（IF/FOR/WHILE 可含子步骤，支持多层嵌套）
- 步骤行支持：编辑、禁用、复制、删除、拖拽排序、批量操作
- 元素类步骤的目标元素支持「库选元素 / 自定义元素」两种来源（见《元素库使用文档》）。两种来源是单选切换，两边填过的数据都会保留，以当前选中的一侧为准，切换不会清空另一侧
- 每个步骤可在「设置」tab 覆盖场景级配置（执行前后等待、超时、失败策略、截图）
- 每个步骤可单独配置「断言」和「提取」（执行该步骤后自动校验/取值）
3.3 变量
- 提取步骤把页面/元素值存入变量，后续步骤用
双大括号语法引用
系统内置了一些常用函数供大家使用
- 直接点击，就可以复制使用。
四、调试执行
4.1 基本操作
| 操作 | 说明 |
|---|---|
| 开始调试 | 启动浏览器从头执行 |
| 暂停 | 当前步骤执行完后暂停（点暂停后按钮转 loading，显示「将在当前步骤执行完成后暂停」） |
| 继续 | 从暂停点继续 |
| 停止 | 终止并关闭浏览器 |
| 重试 | 失败挂起时修复问题后从失败处重跑 |
| 执行到此步骤 | 步骤右键菜单：自动执行到该步骤完成后暂停 |
暂停最多保留 5 分钟，超时自动结束并关闭浏览器。
4.2 调试期间的编辑限制
- 运行中全锁：调试运行期间，当前场景的步骤不能改/删/禁用/复制/拖拽，编辑抽屉为只读（标题显示「调试中只读」）
- 暂停后可改：暂停（含失败挂起）时可以修改未执行的步骤（已执行步骤仍锁定）；失败挂起时失败步骤本身也可改。点「继续」后：
- 没改动 → 从原位置继续
- 有改动 → 从「待执行步骤的最外层父步骤」整体重跑，旧执行结果自动清空
4.3 失败处理
步骤失败且策略为「停止」时进入失败挂起：浏览器保持打开 5 分钟，你可以：
- 查看失败步骤的报错和截图
- 修改失败步骤（或后续步骤）的配置
- 点「重试」从失败处重跑
4.4 结果查看
每个步骤执行后显示状态徽标，点开结果抽屉查看：执行状态、耗时、报错详情（Playwright 超时已翻译为友好文案）、截图、提取到的变量。循环步骤按轮次展示每轮结果。
五、AI 定位自愈
页面改了、元素定位失效导致步骤失败时，AI 会抓取当前页面快照，推断新定位器并在真实页面上验证（唯一且可见）后自动重试该步骤——定位失效不再等于用例作废。
5.1 使用前提
- 平台已配置并启用 AI 模型（超管在「AI 配置」中维护，有生效中的档案即可），未配置时该能力自动关闭，不影响原有失败流程
- 建议选用非推理型模型（如 deepseek-v4-pro）；推理型模型可能因输出被截断导致自愈失效
5.2 触发条件
仅对定位类失败触发：等元素超时、一个定位匹配到多个元素。断言失败、脚本错误等不触发。
5.3 自愈命中后
步骤用新定位器重试成功，调试栏出现「AI 修复建议」角标，点开可逐条或批量处理：
| 操作 | 效果 |
|---|---|
| 采纳（库选元素） | 二次确认后写回元素库，以后都走新定位 |
| 采纳（自定义定位） | 更新当前步骤的定位配置；调试运行中被写保护时，结束后重试即可 |
| 忽略 | 仅本次生效，不改任何配置 |
5.4 修不了时
AI 确认页面上找不到该元素时，步骤结果里直接给出「AI 诊断」，例如：
- 页面上不存在匹配「登录按钮」的元素，可能是产品 BUG 或前置流程缺失
- 目标元素疑似位于 iframe(id=xxx) 中，请检查 Iframe 步骤的 frame 配置
5.5 计划任务执行
计划任务跑场景时同样会自愈，但不推修复建议、不写回元素库，只保证本次跑通。
六、录制导入
支持导入浏览器录制插件生成的操作脚本（仓库根目录 recorder-extension.zip 为配套扩展），自动转换为场景步骤；录制产生的元素定位默认存为「自定义定位」，可一键「添加到元素管理」沉淀进元素库。
注意：录制插件录制的操作，不能保证百分百可执行。导入场景之后，还需要手动调试！！！
七、导入导出
导出
- 场景可导出 JSON 并导入其他项目
- 导出弹窗支持搜索（命中高亮、自动展开）、全选/清空，可一次勾选多个场景/整个目录
导入
如果是同项目的场景，可以通过底部的【导入步骤】进行操作 
八、常见问题
- 元素找不到超时：优先把定位沉淀到元素库并选用更稳的定位方式（TEST_ID > ROLE > CSS > XPATH）；给该步骤调大超时；检查是否需要先切换 iframe。已配置 AI 时可直接看步骤结果里的「AI 诊断」
- AI 自愈没生效：先确认「AI 配置」里有生效中的模型档案；推理型模型（如 deepseek-v4-flash）可能输出截断导致自愈失败，建议换非推理模型（如 deepseek-v4-pro）
- 点了暂停没立即停：暂停只在步骤边界生效，当前步骤（含等待步骤）执行完才会停
- 弹窗（alert）导致卡住：在触发弹窗的点击步骤之前插入「对话框」步骤（一次性监听）