android-midscene-automation 0.1.42 → 0.2.1

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

@@ -0,0 +1,442 @@
+# Appium AI 识别与参数设置使用说明
+
+本文说明本项目的 **Appium 参数设置**和流程中的“AI 识别”节点，包括模型服务、预设场景、单帧识别、持续观察、截图去重、回放截图、报告总结和流程外观。Appium 的 AI 识别模型与“Midscene 配置”中的模型相互独立。
+
+本文档对应页面“帮助与版本 → 操作说明 → AI 识别”。其他 Appium 节点请查看 [流程节点操作说明](./流程节点操作说明.md)。
+
+文中的场景参数是调试起点，请用实际设备、页面和模型验证后调整。
+
+## Appium 参数配置总览
+
+入口：**参数配置 → Appium 配置**。页面按用途分为以下模块：
+
+| 模块 | 配置项 | 保存方式 |
+| --- | --- | --- |
+| 模型服务 | AI 识别模型 | 点击“测试并保存”，测试通过后保存 |
+| 模型服务 | 提示词优化模型 | 点击“测试并保存”，测试通过后保存 |
+| AI 识别设置 | 持续观察截图去重 | 修改后自动保存 |
+| AI 识别设置 | AI 识别预设提示词 | 新增、编辑或删除后自动保存 |
+| 回放与报告 | 回放截图 | 开关修改后自动保存 |
+| 回放与报告 | 回放报告总结 | 开关、测试场景和提示词修改后自动保存 |
+| 流程编辑器 | 流程背景色、连接线条颜色 | 修改后自动保存 |
+
+页面顶部会显示 Appium 配置的自动保存状态。模型连接参数只有测试成功后才会覆盖已保存配置，其他开关、颜色和提示词配置按修改自动保存。
+
+## 1. 先根据目标选择配置
+
+| 你的目标 | 识别方式 | 观察模式 | 启用分支 | 建议起始配置 |
+| --- | --- | --- | --- | --- |
+| 判断当前稳定画面有没有广告 | 单帧识别 | 不适用 | 开启 | 一张截图判断，true / false 走不同流程 |
+| 开屏广告出现时间不固定，出现后尽快执行下一步 | 持续观察 | 检测命中后提前结束 | 需要区分有无广告时开启 | 最长 15000ms，间隔 1000ms |
+| 统计观察期间有没有出现过广告，优先减少请求次数 | 持续观察 | 观察结束后统一分析 | 开启 | 15000ms，间隔 1000ms |
+| 提取广告标题、产品名称、按钮文字 | 单帧识别，或持续观察 | 持续观察时选统一分析 | 关闭 | 稳定画面用单帧；短暂广告用 10000ms / 1000ms |
+| 等待视频、图片或预览区域出图 | 持续观察 | 检测命中后提前结束 | 建议开启 | 最长 20000ms，间隔 1000ms |
+| 等待“跳过”或“关闭”按钮出现 | 持续观察 | 检测命中后提前结束 | 建议开启 | 最长 10000ms，间隔 500ms |
+| 检查当前画面是否有网络异常、加载失败提示 | 单帧识别 | 不适用 | 开启 | 页面仍在变化时再改成持续观察 |
+| 记录页面描述，只需要模型回答 | 单帧识别 | 不适用 | 关闭 | 使用开放式提示词，回答写入回放日志 |
+| 判断纯黑屏、固定模板、颜色占比等明确图像特征 | 优先考虑“图像判断”节点 | 按对应判断功能设置 | 按需求 | 这类需求通常无需语言模型理解 |
+
+选择的关键是：**只看现在用单帧；需要等待或捕捉短暂事件用持续观察；需要命中后尽快继续才选提前结束。**
+
+## 2. 配置 AI 识别模型
+
+入口：**参数配置 → Appium 配置 → 模型服务 → AI 识别模型**。
+
+1. 填写模型服务的 `Base URL`。
+2. 填写 `API Key`。
+3. 填写实际可调用的 `Model Name`。
+4. 点击 **测试并保存**。
+
+测试通过才保存当前模型，失败时保留之前的模型配置。只修改输入框不会自动保存模型。截图去重和预设提示词等其他 Appium 配置仍按修改自动保存。
+
+模型需要支持图片输入；持续观察还需要支持同一请求中的多张图片。当前实现使用兼容 OpenAI Chat Completions 的请求格式。
+
+**“测试并保存”目前验证的是文本连接请求，不能代替图片识别测试。** 配置成功后，应在 AI 节点上执行一次“测试 AI 识别”，检查真实设备截图能否被模型正确识别。持续观察还应单独测试多图请求。
+
+AI 识别读取设备实际截图，不依赖组件树来理解内容。设备预览只是观察界面，不能以预览显示正常代替实际截图和模型调用测试。
+
+## 3. 管理预设测试场景
+
+入口：**参数配置 → Appium 配置 → AI 识别设置 → AI 识别预设提示词**。
+
+每条预设包含两个部分：
+
+| 字段 | 用途 | 示例 |
+| --- | --- | --- |
+| 测试场景 | 下拉选择时显示的名称 | 开屏广告检测 |
+| 提示词内容 | 实际发给模型的识别要求 | 当前画面是否出现广告？升级弹窗和通知弹窗不属于广告。 |
+
+填写后点击“添加提示词”。下方列表固定显示三行高度，可以滚动查看全部内容。默认预设和自定义预设都可以编辑测试场景名称及提示词内容，也可以删除；新增、编辑和删除后都会自动保存。
+
+内置场景包括出图检测、广告及跳过关闭按钮检测、广告内容提取、异常提示检测。旧版纯文本预设会保留内容并补上场景名称；删除全部预设后不会在刷新时重新恢复。
+
+在新建 AI 节点或编辑“识别内容 / 命中条件”时：
+
+1. 打开“选择测试场景”下拉框。
+2. 按场景名称搜索或选择。
+3. 鼠标悬停在场景上查看完整提示词。
+4. 选中后，提示词填入下方输入框，可继续修改。
+
+**选择场景只填入提示词，不会自动改变识别方式、观察模式、超时或分支配置。**
+
+节点保存的是独立的提示词文本。删除预设不会清空已有节点，调整预设也不会自动改写已有脚本。场景名称最长 80 字，提示词最长 4000 字；重复场景名称或重复内容不能再次添加。
+
+## 4. 新建和保存 AI 节点
+
+1. 在 Appium 流程中选择插入位置。
+2. 选择 **视觉识别 → AI 识别**。
+3. 选择测试场景，或手动填写识别内容。
+4. 添加节点后，配置识别方式、观察模式和分支。
+5. 对需要判断条件的节点，完成“验证并保存问题”。
+6. 保存脚本，再进行回放。
+
+新建 AI 节点默认使用单帧识别、不启用分支。需要 true / false 路径时主动勾选“启用分支”，并连接两个方向的后续节点。
+
+## 5. 识别方式：单帧与持续观察
+
+### 单帧识别
+
+节点执行时取得一张设备截图，再交给模型分析。
+
+适合已经稳定的页面，例如检查当前页面是否有弹窗、读取当前广告文字、描述当前画面。
+
+它不能看到截图前已经消失的内容，也不会等待截图后才出现的内容。因此，“启动 App → 固定延时 5 秒 → 单帧识别”仍可能错过第 7 秒才加载的广告。
+
+### 持续观察
+
+从当前 AI 节点开始，按采样间隔连续截图，再根据观察模式提交模型。它观察的是一组离散截图，并不是连续视频。
+
+| 参数 | 含义 | 当前范围 / 默认值 |
+| --- | --- | --- |
+| 观察时长 / 最长观察时间 | 本节点的采样窗口 | 1000～60000ms；默认 15000ms |
+| 采样间隔 | 两次采样的计划间隔 | 500～10000ms；默认 1000ms |
+| 采样数量 | 一次观察允许的截图数量 | 最多 30 帧 |
+
+节点开始会立即采样，因此 **15000ms、间隔 1000ms，通常约采集 16 张，而不是固定 15 张**。实际数量受截图速度、处理耗时和提前结束影响；提交模型的图片数量还会受去重影响。
+
+配置校验按以下公式估算帧数：
+
+```text
+预计帧数 = 向上取整（观察时长 ÷ 采样间隔）+ 1
+```
+
+例如：
+
+| 观察时长 | 采样间隔 | 预计帧数 | 是否可用 |
+| --- | --- | --- | --- |
+| 15000ms | 1000ms | 16 | 可用 |
+| 10000ms | 500ms | 21 | 可用 |
+| 30000ms | 1000ms | 31 | 超过上限 |
+| 30000ms | 2000ms | 16 | 可用 |
+| 60000ms | 3000ms | 21 | 可用 |
+
+采样间隔越短，越容易捕捉短暂画面，但截图和图片分析的消耗也可能增加。持续时间短于采样间隔的广告仍可能漏采。
+
+观察从 AI 节点开始，不会追溯上一节点的画面。应紧接启动 App 或触发广告的操作放置节点；如果广告在上一节点执行期间已经出现并消失，后续观察仍无法补拍。
+
+## 6. 观察模式怎么选
+
+### 观察结束后统一分析
+
+执行过程：**采样 → 本地去重 → 观察结束 → 将保留截图统一提交模型 → 得到结果**。
+
+适合以下需求：
+
+- 想知道观察期间是否出现过广告，不需要立即操作。
+- 需要提取短暂广告的内容。
+- 希望减少模型请求次数。
+- 需要比较多张截图中的页面变化。
+
+这个模式在采样完成后发起一次多图分析请求。一次请求仍可能包含多张图片，所以“请求次数少”不等于“图片输入成本一定很低”。
+
+存在性判断按“观察期间任意一帧明确出现目标”理解。例如问题写“当前画面有没有广告”，持续观察下判断的是本次观察期间是否看到过广告，而不是只看最后一张图。
+
+### 检测命中后提前结束
+
+执行过程：**持续采样并保留关键帧 → 逐次提交新关键帧识别 → 模型确认命中 → 停止观察**。
+
+同一时间只进行一个模型识别请求。模型处理中采到的新关键帧会排队，在下一次请求中一起分析，因此不是固定“一秒调用一次模型”。
+
+| 执行结果 | 已启用分支 | 未启用分支 |
+| --- | --- | --- |
+| 模型确认命中 | 停止观察，进入 true（是）分支 | 停止观察，执行下一节点 |
+| 采样结束且所有待分析关键帧均未命中 | 进入 false（否）分支 | 执行下一节点 |
+| 模型报错、无法判断、返回格式错误 | 按识别失败处理 | 按识别失败处理 |
+
+最长观察时间结束后停止的是采样，还需要等待正在进行和剩余关键帧的识别。因此：
+
+- 设置最长观察 15 秒，节点总耗时可能超过 15 秒。
+- 提前结束发生在模型返回命中结果时，不是广告出现在屏幕上的瞬间。
+- 即使未启用分支，也必须填写能判断“是 / 否”的命中条件。
+- 未启用分支时，有没有命中都会继续下一节点；要让“没检测到广告”走异常流程，应启用分支。
+
+不要用这个模式要求模型完整描述全过程，也不要用它精确测量广告出现或消失时间。
+
+## 7. 分支条件和问题验证
+
+“启用分支”适合明确的判断问题；不启用分支的单帧或统一分析模式适合描述和内容提取。
+
+| 提示词 | 适合分支 / 提前结束 | 原因 |
+| --- | --- | --- |
+| 当前画面是否出现广告？ | 是 | 判断一个明确对象是否存在 |
+| 当前广告页面是否存在可见的“跳过”按钮？ | 是 | 判断指定按钮是否存在 |
+| 视频区域是否已显示正常图像，而不是黑屏或加载占位？ | 是 | 判断指定区域的状态 |
+| 描述当前画面 | 否 | 开放式描述 |
+| 提取广告标题、产品名称和全部按钮文字 | 否 | 内容提取任务 |
+| 有没有广告，如果有请列出全部广告内容 | 不建议 | 将判断与开放式提取混在一起，可能无法通过验证 |
+
+内置的“广告及跳过关闭按钮检测”包含多项检查要求。用于信息分析时可直接选择；用于分支时，建议改成单一明确条件，例如：
+
+```text
+当前画面是否出现商业推广广告？
+升级弹窗、系统通知弹窗、权限申请弹窗不属于广告。
+```
+
+如果你只希望在“广告出现并且能跳过”时继续，应明确写成：
+
+```text
+当前画面是否同时满足以下条件：
+1. 已出现商业推广广告；
+2. 广告上存在可见的“跳过”或“关闭”按钮。
+升级弹窗、通知弹窗和权限申请弹窗不属于广告。
+```
+
+开启分支、切换到提前结束模式，或者修改判断问题时，系统会调用模型验证问题类型。点击“验证并保存问题”后，验证期间按钮禁用，下方显示“正在验证…”。失败时不会保存本次问题修改。
+
+**问题验证不提供设备截图，只检查这段文字是否适合判断。** 验证通过不代表广告已经出现；检查当前设备必须执行“测试 AI 识别”或回放。
+
+启用分支后可以勾选“启用兜底”，再选择无有效识别结果时进入左侧 true 分支还是右侧 false 分支。兜底适用范围收在选项旁的问号说明中：
+
+- 不启用兜底：模型没有返回可用结果时节点失败，保持旧脚本行为。
+- 进入 true 分支：模型返回空内容、无效 JSON、`result: null` 或没有返回布尔值时进入 true。
+- 进入 false 分支：出现上述无有效结果时进入 false。
+
+模型正常返回 `true` 或 `false` 时始终按实际结果执行，不使用兜底。模型请求失败、设备截图失败和网络异常也不会被兜底吞掉；模型请求超时继续使用节点原有的“超时后处理”。回放日志会明确记录“AI 未返回有效 true/false”及实际进入的兜底分支。
+
+## 8. 按场景配置
+
+### 场景 A：开屏广告加载时间不固定
+
+例如有时 3 秒出现，有时 7 秒出现，固定延时容易拍到闪屏页。
+
+| 项目 | 建议 |
+| --- | --- |
+| 节点位置 | 启动 App 后立即进入 AI 识别 |
+| 识别方式 | 持续观察 |
+| 观察模式 | 检测命中后提前结束 |
+| 最长观察时间 | 15000ms；实测存在更长加载时再调整 |
+| 采样间隔 | 1000ms |
+| 分支 | 开启 |
+| 去重 | 先用 pixelmatch 默认参数 |
+| true 分支 | 进入后续广告检查或独立点击节点 |
+| false 分支 | 记录“观察期间未发现广告”，按测试要求结束或执行其他流程 |
+
+提示词：
+
+```text
+当前画面是否出现商业推广广告？
+App 品牌启动页、升级弹窗、系统通知弹窗和权限申请弹窗不属于广告。
+```
+
+不要把“尚未出现广告”与“永远不会出现广告”等同。false 只能说明这次采样并分析的画面没有命中。
+
+### 场景 B：广告出现后等待跳过按钮
+
+如果广告出现时按钮尚未展示，不要只判断“广告出现”。改用上文“广告与按钮同时存在”的条件，或拆成“广告检测 → 按钮检测”两个节点。
+
+建议持续观察、提前结束、10000ms / 500ms、启用分支。为了保留小按钮变化，可先将 pixelmatch 的允许变化面积从默认 0.50% 降到 0.10%，再用截图验证。
+
+AI 节点只判断，不会因为提示词写了“关闭广告”就自动点击。下一步应使用独立的点击节点。模型返回时按钮也可能已经消失，后续操作仍应考虑实际页面状态。
+
+### 场景 C：广告内容提取，包含升级弹窗等干扰
+
+| 项目 | 建议 |
+| --- | --- |
+| 识别方式 | 广告稳定时用单帧；短暂展示时用持续观察 |
+| 观察模式 | 观察结束后统一分析 |
+| 观察时长 / 间隔 | 10000ms / 1000ms |
+| 分支 | 关闭 |
+| 去重 | pixelmatch 默认；重要小字被漏掉时降低去重强度 |
+
+提示词：
+
+```text
+请检查截图中的商业推广广告，并回答：
+1. 是否发现广告；
+2. 广告标题和产品名称；
+3. 是否有“跳过”或“关闭”按钮；
+4. 其他清晰可见的广告文字。
+升级弹窗、系统通知弹窗和权限申请弹窗不属于广告。
+没有看到的内容写“未发现”或“无法辨认”，不要推测。
+```
+
+回答写入识别结果和回放日志。当前 AI 识别节点不会自动把广告标题等结果写入可供后续节点引用的变量。
+
+### 场景 D：等待视频、摄像头预览或图片出图
+
+建议持续观察、提前结束、20000ms / 1000ms、启用分支。
+
+提示词应指出目标区域，避免把导航栏或背景图片误当成“出图”：
+
+```text
+当前画面中部的视频预览区域是否已显示实际场景图像？
+纯黑、纯白、加载动画、默认封面和离线占位图均视为未出图。
+```
+
+如果目标只是检查黑屏比例，可优先使用“图像判断”；如果需要区分封面、占位图与真实场景，再使用 AI 识别。
+
+### 场景 E：只想确认观察期间是否出现过广告，控制模型消耗
+
+建议持续观察、统一分析、15000ms / 1000ms、启用分支、pixelmatch 默认参数。
+
+这个模式即使较早采到广告，也会完成观察后再分析。它适合结果统计，不适合立即点击即将消失的广告。
+
+### 场景 F：按钮、角标或小文字发生变化
+
+先使用 pixelmatch，降低允许变化面积，例如 0.10%；必要时再降低像素颜色容差，例如 0.05。若仍漏掉关键细节，临时切换“不去重”作对照测试。
+
+这些数值是调试起点。不要为了减少图片数量直接增大允许变化面积：一个重要按钮可能只占屏幕很小的一部分。
+
+### 场景 G：视频或动画持续变化，提交图片太多
+
+先缩短观察窗口或增大采样间隔；若无需立即操作，使用统一分析。对不重要的细微变化，可尝试 OpenCV（SSIM），从默认 0.990 开始调整。
+
+视频帧内容本来就可能差异很大，两种去重都不能保证大幅减少图片。也不要把阈值调得过宽，把真正需要识别的广告或按钮一起过滤掉。
+
+## 9. 截图去重怎么调
+
+入口：**参数配置 → Appium 配置 → AI 识别设置 → 持续观察截图去重**。
+
+去重是全局配置，用于后续持续观察回放和识别测试，不影响单帧识别。两种算法都在本地比较图片，不调用模型；第一帧始终保留，之后与上一张保留的截图比较。
+
+| 方式 | 适合 | 注意事项 |
+| --- | --- | --- |
+| 不去重 | 排查漏帧、确认每次采样内容、细节非常重要 | 图片输入消耗较高；仍无法补回采样间隔内没拍到的内容 |
+| pixelmatch（默认） | 同一设备的页面、弹窗、按钮变化 | 比较像素颜色与变化面积，参数过宽会过滤小变化 |
+| OpenCV（SSIM） | 更关注整体画面相似度，希望忽略部分细微噪声 | 不理解广告等语义，不自动对齐位移；缩图可能损失小文字差异 |
+
+参数含义：
+
+| 参数 | 默认值 | 增大后的影响 |
+| --- | --- | --- |
+| pixelmatch：像素颜色容差 | 0.10 | 更容易忽略细微颜色差异，通常保留更少 |
+| pixelmatch：允许变化面积 | 0.50% | 更大面积的变化也可能被视为重复，保留更少 |
+| OpenCV：SSIM 相似度阈值 | 0.990 | 越接近 1，判重复越严格，通常保留更多 |
+| OpenCV：比较图像最长边 | 512px | 比较时保留更多细节，也增加本地计算量 |
+
+注意，pixelmatch 的“允许变化面积”与 SSIM 的阈值调整方向不同。要更保守地保留画面，前者调低，后者调高。
+
+OpenCV 的最长边参数只影响本地比较图片。持续观察提交模型的图片另有统一压缩：最长边不超过 1600px、JPEG 质量 85；观察图片数据还受约 24MB 上限约束。小文字识别也会受设备分辨率、图片压缩和模型能力影响。
+
+## 10. 超时应该怎么设置
+
+AI 节点需要主动勾选“启用超时”，设置值才会生效。新建节点默认不启用；启用时请检查数值，通用默认值 3000ms 对部分多图请求可能过短。
+
+| 时间设置 | 控制什么 | 不控制什么 |
+| --- | --- | --- |
+| 观察时长 / 最长观察时间 | 持续采样的窗口 | 不是整个节点的总耗时上限 |
+| 模型请求超时 | 持续观察中每次模型请求的等待时间 | 不会把 15 秒观察窗口截成 3 秒 |
+| 单帧超时时间 | 单帧识别的请求流程，包含需要进行的截图等待 | 不等于广告等待窗口 |
+
+可先启用 30000ms 作为模型请求超时的调试起点，再根据实际耗时调整。后端将正数超时限制在 1000～300000ms；不要把填入 0 理解为禁用，禁用应取消勾选“启用超时”。
+
+统一分析总耗时大致由“观察采样 + 模型分析”组成；提前结束模式的采样与识别有重叠，但仍可能等待多个请求。
+
+未启用节点超时也不意味着任何外部连接都能无限等待；网络、模型服务和设备截图本身仍可能报错。需要停止等待时可手动终止回放。
+
+启用分支并启用超时时，可以配置“超时后处理”：默认超时终止，也可以指定进入 true 或 false 分支。**因超时进入某分支不代表模型判断为真或假**，回放日志会记录超时原因。模型 HTTP 错误、格式错误或无法判断，不会自动被当成“未命中”。
+
+## 11. 测试与排查
+
+在节点上点击“测试 AI 识别”，查看判断 / 回答、耗时及实际使用的截图。持续观察还会显示采集帧数、提交帧数、去重方式；提前结束模式会显示是否命中和模型请求次数。
+
+测试会立即开始识别，使用的是此时设备的画面，不会自动执行前面的“启动 App”等节点。验证完整开屏流程，应回放包含启动操作的脚本。
+
+按下面的顺序排查：
+
+| 现象 | 优先检查 |
+| --- | --- |
+| 配置测试通过，但 AI 识别报错 | 模型是否支持图片、多图；检查 HTTP 错误和节点测试结果 |
+| 问题验证失败 | 是否混入开放式提取要求；先改成单一“是否”条件 |
+| 明明有广告，却走 false | 提交的截图有没有拍到广告；再看是否被去重、提示词是否排除了目标 |
+| 采集很多帧，只提交少量 | 通常是去重生效；对照实际提交画面检查是否误删关键变化 |
+| 观察 15 秒，执行超过 15 秒 | 检查模型耗时、剩余关键帧和逐次请求等待 |
+| 命中后仍没有走 true | 检查是否启用分支、true 路径是否连接，以及是否编辑后尚未验证保存 |
+| 模型未返回 true/false，流程直接失败 | 在启用分支后按业务风险配置“无有效识别结果时”；未设置兜底会保持失败行为 |
+| 已设置兜底，但网络报错时没有进入分支 | 兜底只处理无效模型内容；网络、模型接口、截图和超时错误仍按失败或超时设置处理 |
+| 没有命中却执行了下一节点 | 未启用分支时这是正常行为；需要区分结果请开启分支 |
+| 每次都拍到启动页 | AI 节点位置、观察窗口和采样时机可能不合适 |
+| 小按钮出现但没检测到 | 降低 pixelmatch 允许变化面积，或提高 SSIM 阈值；用不去重对照 |
+| 提前命中后点击失败 | 模型识别的是已采集画面，返回时目标可能已消失；检查后续点击节点 |
+
+调试时先确认“拍到了什么”，再调整“模型怎么理解”，最后才优化图片数量和模型消耗。保留正常页面、真实广告、升级弹窗和通知弹窗等样本，有助于发现提示词的误判边界。
+
+## 12. 可直接采用的开屏广告流程
+
+```text
+启动目标 App
+  ↓
+AI 识别：持续观察 / 检测命中后提前结束
+最长观察 15000ms，采样间隔 1000ms
+启用分支，pixelmatch 先用默认参数
+模型超时先试 30000ms，超时默认终止
+  ├─ true：进入广告相关的独立检查或操作节点
+  └─ false：记录“观察期间未发现广告”，按用例要求处理
+```
+
+测试场景名称：**开屏广告检测**。
+
+命中条件：
+
+```text
+当前画面是否出现商业推广广告？
+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,7 +1,17 @@
 # 更新记录
+## v0.2.1
+- 侧边栏底部新增“帮助与版本”入口。
+- AI 识别预设提示词支持编辑测试场景名称和提示词内容，默认预设与自定义预设均可修改并自动保存。
+- AI 识别启用分支后可勾选“启用兜底”，再选择进入左侧 true 或右侧 false 分支；适用范围改为问号提示，正常识别结果不受影响。
+
+## v0.1.43
+- 新增独立的“提示词优化模型”，统一用于优化 AI 识别提示词、报告提示词和生成回放测试报告总结；AI 识别与回放报告均可输入简要要求后由模型补充提示词，模型测试成功改为弹窗提示。
+- 回放设置新增报告模板选择，不选择时使用默认测试报告；开启报告总结后会在回放前检测提示词优化模型，模型不可用时弹窗提示并继续生成默认格式的基础报告。总结请求失败、超时或返回空内容时同样保留基础报告，不改变测试结果。
+- 回放输出弹窗支持同时拖拽调整宽度和高度，并保留最小尺寸与窗口边界限制。
+- 连接脚本列表显示同一 App 的其他已保存脚本，不再因入口 Activity 不同或未绑定而隐藏；选择时说明等待入口页面或直接从当前画面执行的行为。
+- 点击坐标操作新增“获取点击坐标”，直接在左侧设备预览点击画面即可填入实际 X、Y 坐标，无需弹窗，支持取消，取点不会执行设备操作。
+
 ## v0.1.42
-- 新增 AI 识别详细使用说明，涵盖预设场景、单帧与持续观察、提前结束、分支、去重、超时及开屏广告等配置示例。
-- 预设提示词新增测试场景名称，管理列表同时展示场景和内容；AI 识别按场景名称选择。
 - 修复回放终止或会话创建失败后设备端 UiAutomator2 残留，导致组件树刷新失败的问题。
 - AI 持续观察新增“检测命中后提前结束”模式，边采样去重边识别，命中后停止观察并继续流程或进入“是”分支；到达最长观察时间后完成剩余关键帧判断，未命中走原顺序或“否”分支，支持命中条件校验、取消和逐次模型请求超时。
 - Appium 参数的AI 识别配置，新增持续观察选项，支持 pixelmatch（默认）、OpenCV（SSIM）和不去重选项。

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
-断言存在 页面核心元素
+等待出现 页面核心元素
 ```
 
 ## 什么时候用可选步骤