android-midscene-automation 0.1.43 → 0.2.2

package/{AI_RECOGNITION_GUIDE.md → AI/350/257/206/345/210/253/346/223/215/344/275/234/350/257/264/346/230/216.md}

@@ -1,9 +1,27 @@
-# AI 识别详细使用说明
+# Appium AI 识别与参数设置使用说明
 
-本文针对本项目 **Appium 流程中的“AI 识别”节点**，说明模型配置、预设场景、单帧识别、持续观察、提前结束、分支、截图去重和超时处理。它与“Midscene 配置”中的模型配置相互独立。
+本文说明本项目的 **Appium 参数设置**和流程中的“AI 识别”节点，包括模型服务、预设场景、单帧识别、持续观察、截图去重、回放截图、报告总结和流程外观。Appium 的 AI 识别模型与“Midscene 配置”中的模型相互独立。
+
+本文档对应页面“帮助与版本 → 操作说明 → AI 识别”。其他 Appium 节点请查看 [流程节点操作说明](./流程节点操作说明.md)。
 
 文中的场景参数是调试起点，请用实际设备、页面和模型验证后调整。
 
+## Appium 参数配置总览
+
+入口：**参数配置 → Appium 配置**。页面按用途分为以下模块：
+
+| 模块 | 配置项 | 保存方式 |
+| --- | --- | --- |
+| 模型服务 | AI 识别模型 | 点击“测试并保存”，测试通过后保存 |
+| 模型服务 | 提示词优化模型 | 点击“测试并保存”，测试通过后保存 |
+| AI 识别设置 | 持续观察截图去重 | 修改后自动保存 |
+| AI 识别设置 | AI 识别预设提示词 | 新增、编辑或删除后自动保存 |
+| 回放与报告 | 回放截图 | 开关修改后自动保存 |
+| 回放与报告 | 回放报告总结 | 开关、测试场景和提示词修改后自动保存 |
+| 流程编辑器 | 流程背景色、连接线条颜色 | 修改后自动保存 |
+
+页面顶部会显示 Appium 配置的自动保存状态。模型连接参数只有测试成功后才会覆盖已保存配置，其他开关、颜色和提示词配置按修改自动保存。
+
 ## 1. 先根据目标选择配置
 
 | 你的目标 | 识别方式 | 观察模式 | 启用分支 | 建议起始配置 |
@@ -22,7 +40,7 @@
 
 ## 2. 配置 AI 识别模型
 
-入口：**参数配置 → Appium 配置 → AI 识别配置 → 模型连接**。
+入口：**参数配置 → Appium 配置 → 模型服务 → AI 识别模型**。
 
 1. 填写模型服务的 `Base URL`。
 2. 填写 `API Key`。
@@ -39,7 +57,7 @@ AI 识别读取设备实际截图，不依赖组件树来理解内容。设备
 
 ## 3. 管理预设测试场景
 
-入口：**参数配置 → Appium 配置 → AI 识别配置 → 预设提示词**。
+入口：**参数配置 → Appium 配置 → AI 识别设置 → AI 识别预设提示词**。
 
 每条预设包含两个部分：
 
@@ -48,7 +66,7 @@ AI 识别读取设备实际截图，不依赖组件树来理解内容。设备
 | 测试场景 | 下拉选择时显示的名称 | 开屏广告检测 |
 | 提示词内容 | 实际发给模型的识别要求 | 当前画面是否出现广告？升级弹窗和通知弹窗不属于广告。 |
 
-填写后点击“添加提示词”。右侧列表显示场景名称和内容，可删除不再需要的预设。列表修改后自动保存。
+填写后点击“添加提示词”。下方列表固定显示三行高度，可以滚动查看全部内容。默认预设和自定义预设都可以编辑测试场景名称及提示词内容，也可以删除；新增、编辑和删除后都会自动保存。
 
 内置场景包括出图检测、广告及跳过关闭按钮检测、广告内容提取、异常提示检测。旧版纯文本预设会保留内容并补上场景名称；删除全部预设后不会在刷新时重新恢复。
 
@@ -187,6 +205,14 @@ AI 识别读取设备实际截图，不依赖组件树来理解内容。设备
 
 **问题验证不提供设备截图，只检查这段文字是否适合判断。** 验证通过不代表广告已经出现；检查当前设备必须执行“测试 AI 识别”或回放。
 
+启用分支后可以勾选“启用兜底”，再选择无有效识别结果时进入左侧 true 分支还是右侧 false 分支。兜底适用范围收在选项旁的问号说明中：
+
+- 不启用兜底：模型没有返回可用结果时节点失败，保持旧脚本行为。
+- 进入 true 分支：模型返回空内容、无效 JSON、`result: null` 或没有返回布尔值时进入 true。
+- 进入 false 分支：出现上述无有效结果时进入 false。
+
+模型正常返回 `true` 或 `false` 时始终按实际结果执行，不使用兜底。模型请求失败、设备截图失败和网络异常也不会被兜底吞掉；模型请求超时继续使用节点原有的“超时后处理”。回放日志会明确记录“AI 未返回有效 true/false”及实际进入的兜底分支。
+
 ## 8. 按场景配置
 
 ### 场景 A：开屏广告加载时间不固定
@@ -279,7 +305,7 @@ AI 节点只判断，不会因为提示词写了“关闭广告”就自动点
 
 ## 9. 截图去重怎么调
 
-入口：**参数配置 → Appium 配置 → AI 识别配置 → 持续观察截图去重**。
+入口：**参数配置 → Appium 配置 → AI 识别设置 → 持续观察截图去重**。
 
 去重是全局配置，用于后续持续观察回放和识别测试，不影响单帧识别。两种算法都在本地比较图片，不调用模型；第一帧始终保留，之后与上一张保留的截图比较。
 
@@ -336,6 +362,8 @@ AI 节点需要主动勾选“启用超时”，设置值才会生效。新建
 | 采集很多帧，只提交少量 | 通常是去重生效；对照实际提交画面检查是否误删关键变化 |
 | 观察 15 秒，执行超过 15 秒 | 检查模型耗时、剩余关键帧和逐次请求等待 |
 | 命中后仍没有走 true | 检查是否启用分支、true 路径是否连接，以及是否编辑后尚未验证保存 |
+| 模型未返回 true/false，流程直接失败 | 在启用分支后按业务风险配置“无有效识别结果时”；未设置兜底会保持失败行为 |
+| 已设置兜底，但网络报错时没有进入分支 | 兜底只处理无效模型内容；网络、模型接口、截图和超时错误仍按失败或超时设置处理 |
 | 没有命中却执行了下一节点 | 未启用分支时这是正常行为；需要区分结果请开启分支 |
 | 每次都拍到启动页 | AI 节点位置、观察窗口和采样时机可能不合适 |
 | 小按钮出现但没检测到 | 降低 pixelmatch 允许变化面积，或提高 SSIM 阈值；用不去重对照 |
@@ -368,3 +396,47 @@ App 品牌启动页、升级弹窗、系统通知弹窗和权限申请弹窗不
 如果下一步必须立刻点击“跳过”，将命中条件改为“广告与可见的跳过 / 关闭按钮同时存在”，并重点验证小按钮变化不会被去重。
 
 如果目标是提取广告内容，应改用统一分析、关闭分支，或另设内容提取节点；第二个节点会重新截图，不能保证仍看到第一个节点捕获的短暂广告。
+
+## 13. 配置提示词优化模型
+
+入口：**参数配置 → Appium 配置 → 模型服务 → 提示词优化模型**。
+
+提示词优化模型只需支持文本输入，统一用于：
+
+- 根据简短要求补充和优化 AI 识别提示词。
+- 优化回放报告提示词。
+- 开启回放报告总结后，根据日志和节点配置生成测试报告总结。
+
+填写 `Base URL`、`API Key` 和 `Model Name` 后点击“测试并保存”。测试成功会弹窗提示并保存配置；测试失败时保留之前可用的配置。AI 识别模型和提示词优化模型用途不同，可以配置为不同模型。
+
+## 14. 配置回放截图与 HTML 报告
+
+入口：**参数配置 → Appium 配置 → 回放与报告 → 回放截图**。
+
+该开关默认关闭。开启后，回放会在实际执行节点前后采集设备截图，并生成可播放的单文件 HTML 报告；判断结果、失败节点和手动终止也会保留相应画面。关闭后仅保留 Markdown 报告、日志和运行历史，图像判断及手动截图等确实需要图片的节点仍会按需截图。
+
+截图采集会增加回放耗时，节点之间的实际操作间隔可能超过流程中设置的固定延时。报告需要完整过程画面时开启；只关心执行日志或希望减少耗时时可以关闭。
+
+## 15. 配置回放报告总结
+
+入口：**参数配置 → Appium 配置 → 回放与报告 → 回放报告总结**。
+
+开启后，工具使用“提示词优化模型”读取脱敏后的回放日志和节点配置，生成 Markdown 测试报告总结。可以选择测试场景、修改报告提示词、增加自定义测试场景，或输入简要要求后使用“优化提示词”补充内容。
+
+回放按钮的设置中可以为本次回放选择报告模板；不选择时使用默认测试报告。需要分析出图速度时可以选择出图时间分析模板，报告应结合日志中的节点开始、截图采集、识别命中和结束时间说明出图耗时。
+
+开启总结后，页面会验证提示词优化模型：
+
+- 模型可用时，回放结束后生成 AI 总结。
+- 模型不可用时，开关旁显示“模型不可用，使用默认模板”，回放仍会继续。
+- 总结请求失败、超时或返回空内容时，保留默认格式的基础报告和原始日志，不改变测试结果。
+
+总结耗时不计入设备测试总时长。发送给模型的内容不包含截图和图片模板；脚本配置及日志过长时会保留头尾并标明中段省略。
+
+## 16. 配置流程编辑器外观
+
+入口：**参数配置 → Appium 配置 → 流程编辑器 → 流程外观**。
+
+可以分别设置流程背景色和连接线条颜色。每项都支持预选颜色、颜色选择器、十六进制颜色输入和恢复默认。颜色值支持 `#RGB` 或 `#RRGGBB`，输入无效时页面会显示校验提示。
+
+外观修改后自动保存，并同时应用到普通流程画布、放大视图和连接脚本预览。该配置只影响流程编辑界面显示，不改变脚本节点和回放行为。

package/CHANGELOG.md

@@ -1,4 +1,17 @@
 # 更新记录
+## v0.2.2
+- 更新 Vben 风格的浅色后台界面：蓝色主色、白色卡片、浅灰背景、可折叠侧边栏与顶部页签。
+- 新增“概览 → 分析页”，根据已保存脚本和真实执行记录分别汇总 Midscene、Appium 测试数据。
+- 修复配置加载失败后出现空白可保存表单的问题，增加独立错误提示和重试；后端断线后自动尝试重连并支持手动重连，保留页面编辑内容。
+- Appium 配置自动保存失败后保留最新待保存内容并提供“重试保存”；修复切换或关闭 Appium 页签后，离开页面时未保存草稿保护失效的问题。
+- Appium 顶部工具栏改为随页面布局排列，窄屏自动换行，避免遮挡面包屑；统一全站样式与中文组件文案，合并重复主题声明。
+- 完善隔离数据环境下的浏览器回归测试，以及请求校验、配置保护、自动保存重试和统计口径测试。
+
+## v0.2.1
+- 侧边栏底部新增“帮助与版本”入口。
+- AI 识别预设提示词支持编辑测试场景名称和提示词内容，默认预设与自定义预设均可修改并自动保存。
+- AI 识别启用分支后可勾选“启用兜底”，再选择进入左侧 true 或右侧 false 分支；正常识别结果不受影响。
+
 ## v0.1.43
 - 新增独立的“提示词优化模型”，统一用于优化 AI 识别提示词、报告提示词和生成回放测试报告总结；AI 识别与回放报告均可输入简要要求后由模型补充提示词，模型测试成功改为弹窗提示。
 - 回放设置新增报告模板选择，不选择时使用默认测试报告；开启报告总结后会在回放前检测提示词优化模型，模型不可用时弹窗提示并继续生成默认格式的基础报告。总结请求失败、超时或返回空内容时同样保留基础报告，不改变测试结果。

package/FAQ.md

@@ -36,16 +36,16 @@ Linux: ~/.local/share/android-midscene-automation
 
 推荐：
 
-- 使用“断言存在”判断下个页面核心元素。
-- 多 Activity 页面可以拆成两个脚本，在判断分支中用“连接脚本”串起来；回放会等待目标 Activity 出现。
+- 使用“等待出现”判断下个页面核心元素，或添加“等待 Activity”明确目标页面。
+- 检测到 Activity 变化时可以选择继续在当前脚本录制；也可以拆成两个脚本，再用“连接脚本”串联。
 - 单 Activity App 不要依赖 Activity 变化，应使用页面核心元素判断是否已进入目标状态。
 
-## 为什么连接脚本提示入口 Activity 不匹配
+## 连接脚本后为什么没有进入目标页面
 
-- 主流程连接要求目标脚本入口 Activity 与当前插入点一致，适合复用同一页面上的公共流程。
-- 登录后进入首页等跨 Activity 场景，应先添加“判断存在”，再在“是”或“否”分支中添加“连接脚本”。
-- 分支连接允许选择同一 App 的其他 Activity，但不会主动跳转页面；前面的点击或输入必须真正触发跳转。
-- 如果页面未跳转，回放会在等待目标 Activity 超时后失败，这是为了防止在错误页面执行目标脚本。
+- 连接脚本列表会显示同一 App 的其他已保存脚本，不受入口 Activity 限制。
+- 连接操作本身不会点击页面或主动跳转，前面的点击、输入或启动 App 必须先让设备进入目标脚本需要的页面。
+- 目标脚本绑定了入口 Activity 时，回放会等待该 Activity；未绑定时会直接从当前画面执行。
+- 跨页面连接前建议添加“等待 Activity”或“等待出现”，便于确认页面已经切换完成。
 
 ## 为什么在桌面点击 App 后回放无效
 
@@ -72,7 +72,7 @@ Linux: ~/.local/share/android-midscene-automation
 如果 App 是单 Activity 架构，优先用：
 
 ```text
-断言存在 页面核心元素
+等待出现 页面核心元素
 ```
 
 ## 什么时候用可选步骤

package/README.md

@@ -52,7 +52,8 @@ npx android-midscene-automation --port 5174
 ## 功能文档
 
 - [Appium 录制器使用说明](#appium-录制器使用说明)
-- [AI 识别详细使用说明](./AI_RECOGNITION_GUIDE.md)
+- [流程节点操作说明](./流程节点操作说明.md)
+- [AI 识别操作说明](./AI识别操作说明.md)
 - [常见问题](#常见问题)
 - [项目更新记录](#项目更新记录)
 
@@ -172,9 +173,54 @@ midscene_run/                  # Midscene 执行报告和运行产物
 
 本文档随 npm 包发布，也可以从 README 的“功能文档”直接打开。常见问题请查看 [常见问题](#常见问题)。
 
-AI 识别的场景选择、预设提示词、持续观察、分支、截图去重及超时配置，请查看 [AI 识别详细使用说明](./AI_RECOGNITION_GUIDE.md)。
+Appium 各流程节点的用途和配置方式，请查看 [流程节点操作说明](./流程节点操作说明.md)。AI 识别的场景选择、预设提示词、持续观察、分支、截图去重及超时配置，请查看 [AI 识别操作说明](./AI识别操作说明.md)。
 
-## 使用前准备
+## 页面内帮助
+
+点击侧边栏最下方的问号图标，可以在“帮助与版本”窗口中查看：
+
+- 当前工具版本和对应的 Midscene 版本。
+- Vue、Element Plus、Appium、Midscene、Vue Flow、OpenCV.js、Vite 和 TypeScript 等主要技术及版本。
+- 本操作说明。
+- 常见问题和各版本更新记录。
+
+Midscene 操作说明读取 `USAGE.md`，Appium 操作说明读取 `流程节点操作说明.md`，AI 识别操作说明读取 `AI识别操作说明.md`，常见问题和更新记录分别读取 `FAQ.md` 与 `CHANGELOG.md`；文档更新后页面内容会同步更新。
+
+## Midscene 操作说明
+
+### 配置 Midscene 模型
+
+进入“参数配置”，在 Midscene 模型区域选择模型提供方并填写所需参数。Midscene 执行依赖支持图片输入的多模态模型，填写后应先点击测试，确认模型可以正常响应。
+
+### 生成测试脚本
+
+进入“Midscene > 测试脚本生成”，填写脚本名称、场景标题、目标 App 和测试需求，也可以上传用例文件。点击“AI 生成”后检查生成步骤，确保测试数据、操作目标和成功条件准确。
+
+### 自定义步骤编排
+
+在测试脚本生成页面切换到“自定义步骤编排”，可以逐条添加操作、等待、查询和判断步骤。每条指令只描述一个明确目标，页面跳转后使用可观察的页面元素作为等待条件。
+
+### 编辑并保存脚本
+
+生成脚本后可以查看、编辑或复制代码。确认内容后点击“保存脚本”，保存的脚本会出现在“自动化测试”页面中。
+
+### 执行 Midscene 脚本
+
+进入“Midscene > 自动化测试”，选择脚本和 Android 设备后点击“开始执行”。执行期间保持设备亮屏和解锁，Midscene 会根据当前画面理解目标并执行操作。
+
+### 停止执行
+
+脚本运行期间点击顶部“停止执行”可以中止后续步骤。停止后查看执行输出，确认最后完成的步骤和停止位置。
+
+### 查看执行输出
+
+自动化测试页面会实时显示步骤状态、耗时和错误信息。执行失败时先检查模型配置、ADB 连接、设备画面以及指令中的目标描述是否清晰。
+
+### Midscene 编写建议
+
+一条指令只完成一个目标；输入、点击和等待尽量拆分；等待条件应描述页面中可观察到的稳定元素；不要在同一步骤中同时处理大量弹窗和业务操作。组件 ID 稳定并需要大量重复回放时，可以改用 Appium 流程。
+
+## Appium 使用前准备
 
 ### 1. 连接 Android 设备
 
@@ -283,14 +329,81 @@ App 包名是必填项，只能从“参数配置”中已经添加的“预设
 - 点击节点右上角删除按钮可移除节点，流程引用会自动修正。
 - 浏览器刷新后会保持当前功能页面和 Appium 工作区 Tab；存在未保存修改时，刷新或关闭页面前会提示保存。
 
-### 单 Activity 录制规则
+### 跨 Activity 录制
 
-每个脚本只允许录制一个 Activity。录制点击后如果检测到 Activity 发生变化，会强制弹出保存提示；保存完成后清空当前流程，并从新 Activity 开始录制新脚本。
+录制点击后如果检测到 Activity 发生变化，系统会提示选择继续录制或结束并保存。需要把多个页面保存在同一脚本时选择继续，等待新页面组件树刷新后即可录制后续操作；希望按页面拆分时，结束当前脚本并在新 Activity 中创建脚本，再通过“连接脚本”组合流程。
 
-加载历史脚本时，如果手机当前 Activity 与脚本入口 Activity 不一致，流程编辑会锁定。此时可执行脚本中的“启动 APP”节点，或插入“系统返回”使页面回到脚本绑定的 Activity；Activity 匹配后自动解除锁定。
+跨页面流程建议在跳转操作后添加“等待 Activity”，明确目标页面并提高回放稳定性。加载历史脚本时，即使手机当前 Activity 与脚本入口 Activity 不同，也可以查看和编辑流程；回放前应确认启动节点、等待 Activity 或前置操作能把设备带到正确页面。
 
 ## 操作说明
 
+### 当前操作分类
+
+- 组件操作：录制点击、录制输入、提取变量、清空输入、长按、存在则点击、存在则输入、存在则清空。
+- 设备操作：点击坐标、系统返回、Home 键、最近任务、电源键、滑动、双指缩放、启动 APP、停止 APP、启动相册、清除 APP 数据。
+- 判断与等待：判断存在、判断勾选、文字点击、AI 识别、图像判断、等待出现、等待消失、等待 Activity。
+- 检测画面变化：在三级菜单中分别添加“开始”和“结束”，对比指定区域前后的画面。
+- 循环：添加有界循环、进入下一次循环和退出循环。进入下一次循环会跳过本轮剩余节点；退出循环会执行目标循环结束后的流程。
+- 流程控制：连接脚本、终止流程、输出日志和添加延时。
+
+旧脚本中的“断言存在”和“断言文本”仍可回放，但新流程统一使用当前菜单中的判断与等待操作。
+
+### 提取变量
+
+读取选中组件的文字或属性并保存为脚本变量，后续输入、判断、定位和日志节点可以使用 `{{变量名}}` 引用。
+
+### 停止 APP
+
+停止指定包名的 App 进程，不卸载应用，也不清除登录信息和本地数据。节点中可以修改目标包名。
+
+### 启动相册
+
+打开设备可用的系统相册或常见相册应用，只负责进入相册，不自动选择照片或视频。
+
+### 清除 APP 数据
+
+清除目标应用数据并恢复初始状态，会删除登录信息和本地设置。该操作只允许放在流程开始位置，使用前应确认测试数据可以重置。
+
+### 判断勾选
+
+读取原生 Checkbox、RadioButton 或 Switch 的真实 checked 状态，并按勾选或未勾选进入对应分支。普通图片控件应改用图像判断。
+
+### 文字点击
+
+按指定文字精确或模糊查找原生组件，匹配后点击并进入成功分支，未匹配时进入另一分支。它不识别图片或自绘画面中的文字。
+
+### AI 识别
+
+将设备截图发送给视觉模型，可以执行单帧识别、持续观察或检测命中后提前结束。默认按顺序继续执行；启用分支后根据识别结果进入不同路径。
+
+### 图像判断
+
+使用本地 OpenCV 判断模板、图片勾选状态、黑屏、区域颜色或多帧变化，不调用模型。固定图标和稳定视觉特征适合使用该操作。
+
+### 检测画面变化
+
+从三级菜单分别添加“开始”和“结束”。开始节点保存指定区域的基准截图，结束节点与对应基准比较并在日志和报告中记录变化结果。
+
+### 循环
+
+在最大执行次数范围内重复执行循环体，可以固定次数运行，也可以根据元素出现或消失提前退出。最大次数用于防止脚本无限循环。
+
+### 进入下一次循环
+
+跳过当前轮剩余节点并进入指定的当前或外层循环下一轮。达到最大次数后执行循环结束路径。
+
+### 退出循环
+
+立即结束指定的当前或外层循环，随后执行该循环结束后的流程。
+
+### 终止流程
+
+主动结束整次回放，后续节点和连接脚本不再执行。系统仍会保存本次日志和报告。
+
+### 输出日志
+
+输出自定义内容和日志关键字，支持 `{{变量名}}`。适合标记测试阶段、记录读取值或为报告提供检索标识。
+
 ### 录制点击
 
 用途：点击某个组件。
@@ -940,10 +1053,10 @@ Home 键
 
 1. 在上方“提示词优化模型”填写 Base URL、API Key、Model Name，并点击“测试并保存”。该文本模型同时用于优化提示词和生成回放报告总结。
 2. 开启“回放报告总结”。开关和报告提示词修改后自动保存。
-3. 默认格式包括测试概览（脚本名称、起止时间、结果、总时长）、执行配置及节点参数、用例描述表格、失败详情和汇总。可选择默认测试报告或出图时间分析，也可修改提示词调整内容。
+3. 在回放按钮的设置中选择报告模板；不选择时使用默认测试报告。默认格式包括测试概览（脚本名称、起止时间、结果、总时长）、执行配置及节点参数、用例描述表格、失败详情和汇总，也可以选择出图时间分析或自定义模板。
 4. 回放结束后将脱敏日志、主脚本与连接脚本配置发送给总结模型，生成的 Markdown 使用原回放报告路径，保存在配置的报告输出目录（默认 `output`）；完成日志会显示报告路径。
 
-总结在设备操作结束后生成，页面会显示生成进度，总结耗时不计入测试总时长。关闭时继续生成原基础报告且不调用总结模型；请求失败、超时或返回空内容时保留基础报告和原始日志，并输出失败原因，不改变测试结果。模型请求最多等待 60 秒。
+开启报告总结后，工具会在回放前验证提示词优化模型。模型不可用时，开关旁会提示“模型不可用，使用默认模板”，回放仍会继续并生成基础报告。总结在设备操作结束后生成，页面会显示生成进度，总结耗时不计入测试总时长。关闭时继续生成原基础报告且不调用总结模型；请求失败、超时或返回空内容时保留基础报告和原始日志，并输出失败原因，不改变测试结果。模型请求最多等待 60 秒。
 
 报告不会向模型发送截图和图片模板。为控制输入大小，脚本配置最多保留约 50000 字符，日志最多保留约 100000 字符；超限时保留头尾并标注中段省略，生成报告也会注明信息不完整。模型的原因分析属于辅助判断，应结合原始日志核实。
 
@@ -954,7 +1067,7 @@ Home 键
 - 新脚本需要填写名称并选择预设 App 后保存。
 - 从顶部脚本下拉框或“脚本列表”加载历史脚本后，再次点击“保存”会更新原脚本，不会因为名称相同而报错。
 - 脚本数据只保存流程图 `flow_json`，其中包含主流程、判断分支、连接关系、节点备注和页面检查点。
-- 已保存脚本加载后会校验当前 Activity；页面不匹配时按“单 Activity 录制规则”锁定编辑。
+- 已保存脚本加载后仍可直接查看和编辑；当前 Activity 不影响脚本编辑。
 
 ### 脚本列表
 
@@ -1175,16 +1288,16 @@ Linux: ~/.local/share/android-midscene-automation
 
 推荐：
 
-- 使用“断言存在”判断下个页面核心元素。
-- 多 Activity 页面可以拆成两个脚本，在判断分支中用“连接脚本”串起来；回放会等待目标 Activity 出现。
+- 使用“等待出现”判断下个页面核心元素，或添加“等待 Activity”明确目标页面。
+- 检测到 Activity 变化时可以选择继续在当前脚本录制；也可以拆成两个脚本，再用“连接脚本”串联。
 - 单 Activity App 不要依赖 Activity 变化，应使用页面核心元素判断是否已进入目标状态。
 
-## 为什么连接脚本提示入口 Activity 不匹配
+## 连接脚本后为什么没有进入目标页面
 
-- 主流程连接要求目标脚本入口 Activity 与当前插入点一致，适合复用同一页面上的公共流程。
-- 登录后进入首页等跨 Activity 场景，应先添加“判断存在”，再在“是”或“否”分支中添加“连接脚本”。
-- 分支连接允许选择同一 App 的其他 Activity，但不会主动跳转页面；前面的点击或输入必须真正触发跳转。
-- 如果页面未跳转，回放会在等待目标 Activity 超时后失败，这是为了防止在错误页面执行目标脚本。
+- 连接脚本列表会显示同一 App 的其他已保存脚本，不受入口 Activity 限制。
+- 连接操作本身不会点击页面或主动跳转，前面的点击、输入或启动 App 必须先让设备进入目标脚本需要的页面。
+- 目标脚本绑定了入口 Activity 时，回放会等待该 Activity；未绑定时会直接从当前画面执行。
+- 跨页面连接前建议添加“等待 Activity”或“等待出现”，便于确认页面已经切换完成。
 
 ## 为什么在桌面点击 App 后回放无效
 
@@ -1211,7 +1324,7 @@ Linux: ~/.local/share/android-midscene-automation
 如果 App 是单 Activity 架构，优先用：
 
 ```text
-断言存在 页面核心元素
+等待出现 页面核心元素
 ```
 
 ## 什么时候用可选步骤
@@ -1245,6 +1358,19 @@ Linux: ~/.local/share/android-midscene-automation
 
 # 项目更新记录
 
+## v0.2.2
+- 更新 Vben 风格的浅色后台界面：蓝色主色、白色卡片、浅灰背景、可折叠侧边栏与顶部页签。
+- 新增“概览 → 分析页”，根据已保存脚本和真实执行记录分别汇总 Midscene、Appium 测试数据。
+- 修复配置加载失败后出现空白可保存表单的问题，增加独立错误提示和重试；后端断线后自动尝试重连并支持手动重连，保留页面编辑内容。
+- Appium 配置自动保存失败后保留最新待保存内容并提供“重试保存”；修复切换或关闭 Appium 页签后，离开页面时未保存草稿保护失效的问题。
+- Appium 顶部工具栏改为随页面布局排列，窄屏自动换行，避免遮挡面包屑；统一全站样式与中文组件文案，合并重复主题声明。
+- 完善隔离数据环境下的浏览器回归测试，以及请求校验、配置保护、自动保存重试和统计口径测试。
+
+## v0.2.1
+- 侧边栏底部新增“帮助与版本”入口。
+- AI 识别预设提示词支持编辑测试场景名称和提示词内容，默认预设与自定义预设均可修改并自动保存。
+- AI 识别启用分支后可勾选“启用兜底”，再选择进入左侧 true 或右侧 false 分支；正常识别结果不受影响。
+
 ## v0.1.43
 - 新增独立的“提示词优化模型”，统一用于优化 AI 识别提示词、报告提示词和生成回放测试报告总结；AI 识别与回放报告均可输入简要要求后由模型补充提示词，模型测试成功改为弹窗提示。
 - 回放设置新增报告模板选择，不选择时使用默认测试报告；开启报告总结后会在回放前检测提示词优化模型，模型不可用时弹窗提示并继续生成默认格式的基础报告。总结请求失败、超时或返回空内容时同样保留基础报告，不改变测试结果。

package/USAGE.md

@@ -4,9 +4,54 @@
 
 本文档随 npm 包发布，也可以从 README 的“功能文档”直接打开。常见问题请查看 [FAQ.md](./FAQ.md)。
 
-AI 识别的场景选择、预设提示词、持续观察、分支、截图去重及超时配置，请查看 [AI 识别详细使用说明](./AI_RECOGNITION_GUIDE.md)。
+Appium 各流程节点的用途和配置方式，请查看 [流程节点操作说明](./流程节点操作说明.md)。AI 识别的场景选择、预设提示词、持续观察、分支、截图去重及超时配置，请查看 [AI 识别操作说明](./AI识别操作说明.md)。
 
-## 使用前准备
+## 页面内帮助
+
+点击侧边栏最下方的问号图标，可以在“帮助与版本”窗口中查看：
+
+- 当前工具版本和对应的 Midscene 版本。
+- Vue、Element Plus、Appium、Midscene、Vue Flow、OpenCV.js、Vite 和 TypeScript 等主要技术及版本。
+- 本操作说明。
+- 常见问题和各版本更新记录。
+
+Midscene 操作说明读取 `USAGE.md`，Appium 操作说明读取 `流程节点操作说明.md`，AI 识别操作说明读取 `AI识别操作说明.md`，常见问题和更新记录分别读取 `FAQ.md` 与 `CHANGELOG.md`；文档更新后页面内容会同步更新。
+
+## Midscene 操作说明
+
+### 配置 Midscene 模型
+
+进入“参数配置”，在 Midscene 模型区域选择模型提供方并填写所需参数。Midscene 执行依赖支持图片输入的多模态模型，填写后应先点击测试，确认模型可以正常响应。
+
+### 生成测试脚本
+
+进入“Midscene > 测试脚本生成”，填写脚本名称、场景标题、目标 App 和测试需求，也可以上传用例文件。点击“AI 生成”后检查生成步骤，确保测试数据、操作目标和成功条件准确。
+
+### 自定义步骤编排
+
+在测试脚本生成页面切换到“自定义步骤编排”，可以逐条添加操作、等待、查询和判断步骤。每条指令只描述一个明确目标，页面跳转后使用可观察的页面元素作为等待条件。
+
+### 编辑并保存脚本
+
+生成脚本后可以查看、编辑或复制代码。确认内容后点击“保存脚本”，保存的脚本会出现在“自动化测试”页面中。
+
+### 执行 Midscene 脚本
+
+进入“Midscene > 自动化测试”，选择脚本和 Android 设备后点击“开始执行”。执行期间保持设备亮屏和解锁，Midscene 会根据当前画面理解目标并执行操作。
+
+### 停止执行
+
+脚本运行期间点击顶部“停止执行”可以中止后续步骤。停止后查看执行输出，确认最后完成的步骤和停止位置。
+
+### 查看执行输出
+
+自动化测试页面会实时显示步骤状态、耗时和错误信息。执行失败时先检查模型配置、ADB 连接、设备画面以及指令中的目标描述是否清晰。
+
+### Midscene 编写建议
+
+一条指令只完成一个目标；输入、点击和等待尽量拆分；等待条件应描述页面中可观察到的稳定元素；不要在同一步骤中同时处理大量弹窗和业务操作。组件 ID 稳定并需要大量重复回放时，可以改用 Appium 流程。
+
+## Appium 使用前准备
 
 ### 1. 连接 Android 设备
 
@@ -115,14 +160,81 @@ App 包名是必填项，只能从“参数配置”中已经添加的“预设
 - 点击节点右上角删除按钮可移除节点，流程引用会自动修正。
 - 浏览器刷新后会保持当前功能页面和 Appium 工作区 Tab；存在未保存修改时，刷新或关闭页面前会提示保存。
 
-### 单 Activity 录制规则
+### 跨 Activity 录制
 
-每个脚本只允许录制一个 Activity。录制点击后如果检测到 Activity 发生变化，会强制弹出保存提示；保存完成后清空当前流程，并从新 Activity 开始录制新脚本。
+录制点击后如果检测到 Activity 发生变化，系统会提示选择继续录制或结束并保存。需要把多个页面保存在同一脚本时选择继续，等待新页面组件树刷新后即可录制后续操作；希望按页面拆分时，结束当前脚本并在新 Activity 中创建脚本，再通过“连接脚本”组合流程。
 
-加载历史脚本时，如果手机当前 Activity 与脚本入口 Activity 不一致，流程编辑会锁定。此时可执行脚本中的“启动 APP”节点，或插入“系统返回”使页面回到脚本绑定的 Activity；Activity 匹配后自动解除锁定。
+跨页面流程建议在跳转操作后添加“等待 Activity”，明确目标页面并提高回放稳定性。加载历史脚本时，即使手机当前 Activity 与脚本入口 Activity 不同，也可以查看和编辑流程；回放前应确认启动节点、等待 Activity 或前置操作能把设备带到正确页面。
 
 ## 操作说明
 
+### 当前操作分类
+
+- 组件操作：录制点击、录制输入、提取变量、清空输入、长按、存在则点击、存在则输入、存在则清空。
+- 设备操作：点击坐标、系统返回、Home 键、最近任务、电源键、滑动、双指缩放、启动 APP、停止 APP、启动相册、清除 APP 数据。
+- 判断与等待：判断存在、判断勾选、文字点击、AI 识别、图像判断、等待出现、等待消失、等待 Activity。
+- 检测画面变化：在三级菜单中分别添加“开始”和“结束”，对比指定区域前后的画面。
+- 循环：添加有界循环、进入下一次循环和退出循环。进入下一次循环会跳过本轮剩余节点；退出循环会执行目标循环结束后的流程。
+- 流程控制：连接脚本、终止流程、输出日志和添加延时。
+
+旧脚本中的“断言存在”和“断言文本”仍可回放，但新流程统一使用当前菜单中的判断与等待操作。
+
+### 提取变量
+
+读取选中组件的文字或属性并保存为脚本变量，后续输入、判断、定位和日志节点可以使用 `{{变量名}}` 引用。
+
+### 停止 APP
+
+停止指定包名的 App 进程，不卸载应用，也不清除登录信息和本地数据。节点中可以修改目标包名。
+
+### 启动相册
+
+打开设备可用的系统相册或常见相册应用，只负责进入相册，不自动选择照片或视频。
+
+### 清除 APP 数据
+
+清除目标应用数据并恢复初始状态，会删除登录信息和本地设置。该操作只允许放在流程开始位置，使用前应确认测试数据可以重置。
+
+### 判断勾选
+
+读取原生 Checkbox、RadioButton 或 Switch 的真实 checked 状态，并按勾选或未勾选进入对应分支。普通图片控件应改用图像判断。
+
+### 文字点击
+
+按指定文字精确或模糊查找原生组件，匹配后点击并进入成功分支，未匹配时进入另一分支。它不识别图片或自绘画面中的文字。
+
+### AI 识别
+
+将设备截图发送给视觉模型，可以执行单帧识别、持续观察或检测命中后提前结束。默认按顺序继续执行；启用分支后根据识别结果进入不同路径。
+
+### 图像判断
+
+使用本地 OpenCV 判断模板、图片勾选状态、黑屏、区域颜色或多帧变化，不调用模型。固定图标和稳定视觉特征适合使用该操作。
+
+### 检测画面变化
+
+从三级菜单分别添加“开始”和“结束”。开始节点保存指定区域的基准截图，结束节点与对应基准比较并在日志和报告中记录变化结果。
+
+### 循环
+
+在最大执行次数范围内重复执行循环体，可以固定次数运行，也可以根据元素出现或消失提前退出。最大次数用于防止脚本无限循环。
+
+### 进入下一次循环
+
+跳过当前轮剩余节点并进入指定的当前或外层循环下一轮。达到最大次数后执行循环结束路径。
+
+### 退出循环
+
+立即结束指定的当前或外层循环，随后执行该循环结束后的流程。
+
+### 终止流程
+
+主动结束整次回放，后续节点和连接脚本不再执行。系统仍会保存本次日志和报告。
+
+### 输出日志
+
+输出自定义内容和日志关键字，支持 `{{变量名}}`。适合标记测试阶段、记录读取值或为报告提供检索标识。
+
 ### 录制点击
 
 用途：点击某个组件。
@@ -772,10 +884,10 @@ Home 键
 
 1. 在上方“提示词优化模型”填写 Base URL、API Key、Model Name，并点击“测试并保存”。该文本模型同时用于优化提示词和生成回放报告总结。
 2. 开启“回放报告总结”。开关和报告提示词修改后自动保存。
-3. 默认格式包括测试概览（脚本名称、起止时间、结果、总时长）、执行配置及节点参数、用例描述表格、失败详情和汇总。可选择默认测试报告或出图时间分析，也可修改提示词调整内容。
+3. 在回放按钮的设置中选择报告模板；不选择时使用默认测试报告。默认格式包括测试概览（脚本名称、起止时间、结果、总时长）、执行配置及节点参数、用例描述表格、失败详情和汇总，也可以选择出图时间分析或自定义模板。
 4. 回放结束后将脱敏日志、主脚本与连接脚本配置发送给总结模型，生成的 Markdown 使用原回放报告路径，保存在配置的报告输出目录（默认 `output`）；完成日志会显示报告路径。
 
-总结在设备操作结束后生成，页面会显示生成进度，总结耗时不计入测试总时长。关闭时继续生成原基础报告且不调用总结模型；请求失败、超时或返回空内容时保留基础报告和原始日志，并输出失败原因，不改变测试结果。模型请求最多等待 60 秒。
+开启报告总结后，工具会在回放前验证提示词优化模型。模型不可用时，开关旁会提示“模型不可用，使用默认模板”，回放仍会继续并生成基础报告。总结在设备操作结束后生成，页面会显示生成进度，总结耗时不计入测试总时长。关闭时继续生成原基础报告且不调用总结模型；请求失败、超时或返回空内容时保留基础报告和原始日志，并输出失败原因，不改变测试结果。模型请求最多等待 60 秒。
 
 报告不会向模型发送截图和图片模板。为控制输入大小，脚本配置最多保留约 50000 字符，日志最多保留约 100000 字符；超限时保留头尾并标注中段省略，生成报告也会注明信息不完整。模型的原因分析属于辅助判断，应结合原始日志核实。
 
@@ -786,7 +898,7 @@ Home 键
 - 新脚本需要填写名称并选择预设 App 后保存。
 - 从顶部脚本下拉框或“脚本列表”加载历史脚本后，再次点击“保存”会更新原脚本，不会因为名称相同而报错。
 - 脚本数据只保存流程图 `flow_json`，其中包含主流程、判断分支、连接关系、节点备注和页面检查点。
-- 已保存脚本加载后会校验当前 Activity；页面不匹配时按“单 Activity 录制规则”锁定编辑。
+- 已保存脚本加载后仍可直接查看和编辑；当前 Activity 不影响脚本编辑。
 
 ### 脚本列表
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "android-midscene-automation",
-  "version": "0.1.43",
+  "version": "0.2.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oooooooko/android-midscene-automation.git"
@@ -23,7 +23,8 @@
     "vite.config.ts",
     "README.md",
     "USAGE.md",
-    "AI_RECOGNITION_GUIDE.md",
+    "流程节点操作说明.md",
+    "AI识别操作说明.md",
     "FAQ.md",
     "CHANGELOG.md"
   ],