android-midscene-automation 0.1.21 → 0.1.23

package/README.md

@@ -32,7 +32,7 @@ appium driver install uiautomator2
 ## 启动
 
 ```sh
-npx android-midscene-automation
+npx --yes android-midscene-automation@latest
 ```
 
 启动后访问：
@@ -52,6 +52,7 @@ npx android-midscene-automation --port 5174
 ## 功能文档
 
 - [Appium 录制器使用说明](#appium-录制器使用说明)
+- [常见问题](./FAQ.md)
 - [项目更新记录](#项目更新记录)
 
 ## 源码开发
@@ -164,7 +165,7 @@ midscene_run/                  # Midscene 执行报告和运行产物
 
 本文档说明 Appium 组件树录制器的完整使用方式，包括每个操作按钮的用途、录制方法和示例。
 
-本文档随 npm 包发布，也可以从 README 的“功能文档”直接打开。
+本文档随 npm 包发布，也可以从 README 的“功能文档”直接打开。常见问题请查看 [FAQ.md](./FAQ.md)。
 
 ## 使用前准备
 
@@ -621,14 +622,14 @@ Home 键
 4. 点击判断节点，按需填写“指定文本”。
 5. 选择“模糊匹配（包含）”或“精准匹配（完全一致）”。
 6. 在“是”或“否”分支下点击“插入操作”，分别添加分支步骤。
-7. 需要回到判断后的主流程时，点击分支旁的“连接到下一节点”；连接成功后按钮变为“取消连接”。
+7. 如果两个分支后续要执行相同操作，可以复制公共节点到对应分支，或把公共流程拆成“连接脚本”复用。
 
 示例：
 
 ```text
 判断存在 确认按钮
   是 -> 点击 确认按钮
-  否 -> 继续主流程
+  否 -> 不添加操作
 ```
 
 分支说明：
@@ -638,7 +639,6 @@ Home 键
 - 模糊匹配会忽略换行和连续空白差异，只要规范化后的文本包含目标内容即可。
 - 精准匹配要求 Appium 返回的完整文本与指定文本完全一致。
 - 分支可以包含多个连续步骤，也可以在分支末尾连接其他脚本。
-- “连接到下一节点”只在判断后仍有主流程节点时显示。
 
 适用场景：
 
@@ -658,7 +658,7 @@ Home 键
 3. 选择“判断存在”。
 4. 展开节点，在“指定文本”中输入该弹窗特有的文案。
 5. 根据需要选择模糊匹配或精准匹配。
-6. 在“是”分支添加该弹窗对应的确认、取消或关闭步骤；“否”分支继续下一个判断或主流程。
+6. 在“是”分支添加该弹窗对应的确认、取消或关闭步骤；“否”分支继续下一个判断或不添加操作。
 
 示例：
 
@@ -667,7 +667,7 @@ Home 键
   是 -> 点击 确定
   否 -> 判断存在：指定文本“是否退出登录”
         是 -> 点击 确定
-        否 -> 继续主流程
+        否 -> 不添加操作
 ```
 
 适用场景：
@@ -1029,12 +1029,8 @@ output/2026-08-21_17-13-42-831-登录流程.html
 输入 账号
 输入 密码
 判断存在 用户协议弹窗
-  是 -> 点击 同意
-  否 -> 连接到下一节点
-点击 登录
-判断登录是否成功
-  是 -> 连接脚本 首页脚本
-  否 -> 断言文本 登录错误提示
+  是 -> 点击 同意 -> 点击 登录 -> 判断登录是否成功 -> 连接脚本 首页脚本
+  否 -> 点击 登录 -> 判断登录是否成功 -> 连接脚本 首页脚本
 ```
 
 首页脚本：
@@ -1068,16 +1064,15 @@ output/2026-08-21_17-13-42-831-登录流程.html
 2. 选择用于区分登录结果的稳定元素，添加“判断存在”。
 3. 在“是”分支插入首页校验或“连接脚本”。
 4. 在“否”分支插入错误提示断言。
-5. 需要继续执行判断后的公共步骤时，点击对应分支的“连接到下一节点”。
+5. 如果两个分支后续有相同公共步骤，使用批量复制把公共节点复制到对应分支。
 
 ### 示例 3：一次性弹窗
 
 ```text
 启动 App
 判断存在 确认按钮
-  是 -> 点击 确认按钮
-  否 -> 连接到下一节点
-断言存在 首页
+  是 -> 点击 确认按钮 -> 断言存在 首页
+  否 -> 断言存在 首页
 ```
 
 适合场景：
@@ -1113,89 +1108,7 @@ output/2026-08-21_17-13-42-831-登录流程.html
 
 ## 常见问题
 
-### 同一个 id 定位到错误输入框怎么办
-
-如果账号框和密码框都是 `id/tg_edit`，只按 id 回放可能输入到第一个输入框。
-
-建议：
-
-- 直接分别选择账号框和密码框录制输入。
-- 在节点详情里确认 selector 是否显示“重复 N”，以及“推荐定位”是否显示父级 + 子级。
-- 如果推荐定位不准确，展开录制步骤，手动修改父级上下文 selector。
-- 坐标点击只作为最后兜底。
-
-### 点击后没有检测到页面跳转怎么办
-
-可能原因：
-
-- 按钮当前禁用。
-- 账号密码不正确。
-- App 使用单 Activity，Activity 不变化。
-- 页面跳转依赖网络。
-
-推荐：
-
-- 使用“断言存在”判断下个页面核心元素。
-- 多 Activity 页面可以拆成两个脚本，在判断分支中用“连接脚本”串起来；回放会等待目标 Activity 出现。
-- 单 Activity App 不要依赖 Activity 变化，应使用页面核心元素判断是否已进入目标状态。
-
-### 为什么连接脚本提示入口 Activity 不匹配
-
-- 主流程连接要求目标脚本入口 Activity 与当前插入点一致，适合复用同一页面上的公共流程。
-- 登录后进入首页等跨 Activity 场景，应先添加“判断存在”，再在“是”或“否”分支中添加“连接脚本”。
-- 分支连接允许选择同一 App 的其他 Activity，但不会主动跳转页面；前面的点击或输入必须真正触发跳转。
-- 如果页面未跳转，回放会在等待目标 Activity 超时后失败，这是为了防止在错误页面执行目标脚本。
-
-### 弹窗只出现一次怎么办
-
-使用“判断存在”。
-
-```text
-判断存在 确认按钮
-  是 -> 点击 确认按钮
-  否 -> 继续主流程
-```
-
-不要直接把弹窗确认按钮作为普通必选点击，否则弹窗不出现时脚本会失败。
-
-### 什么时候用等待 Activity
-
-适合多 Activity App。
-
-如果 App 是单 Activity 架构，优先用：
-
-```text
-断言存在 页面核心元素
-```
-
-### 什么时候用可选步骤
-
-可选步骤适合非主流程阻塞项：
-
-- 权限弹窗
-- 协议弹窗
-- 活动弹窗
-- 首次引导
-
-不建议把登录按钮、提交按钮、核心断言设置为可选。
-
-### 回放时出现 UiAutomation not connected 怎么办
-
-组件树刷新和 Appium 回放不能同时占用 UiAutomation。当前版本会在回放期间暂停组件树自动刷新，并在断开时清理残留抓取进程后重试一次。
-
-如果仍然失败：
-
-1. 确认手机保持解锁，USB 调试授权没有失效。
-2. 确认 Appium 和 UiAutomator2 Driver 已正常启动。
-3. 停止其他正在抓取同一设备组件树的工具。
-4. 重新连接设备后再次回放。
-
-### 设备预览或组件树没有更新怎么办
-
-1. 先确认设备仍显示在设备下拉框中。
-2. 点击设备预览刷新按钮重新获取画面。
-3. 点击“刷新组件树”重新抓取页面结构。
-4. 回放期间组件树自动刷新会暂停，回放完成后会自动恢复。
+常见问题已独立整理到 [FAQ.md](./FAQ.md)。
 
 ## 推荐录制规范
 
@@ -1205,188 +1118,117 @@ output/2026-08-21_17-13-42-831-登录流程.html
 - 弹窗或其他可选组件使用“判断存在”，不要直接写死必点。
 - 坐标点击只作为兜底。
 - 给关键节点填写“登录按钮”“账号输入框”等备注，方便查看流程和报告。
-- 判断分支需要回到主流程时，明确点击“连接到下一节点”。
 - 回放失败后优先查看“回放输出”中的失败节点、Activity 和 selector，再打开 `output` 中的 Markdown 报告查看完整配置。
 
 # 项目更新记录
 
+## v0.1.23
+
+- 常见问题拆分为独立 `FAQ.md` 文档，并在 README 的“功能文档”中增加跳转入口。
+
+## v0.1.22
+
+- 升级 Midscene 相关依赖到 `v1.12.0`
+
 ## v0.1.21
 
-- 补充 GitHub 仓库、问题反馈和项目主页信息，npm 包页面可直接跳转至源码仓库和 Issues。
+- 录制步骤流程图升级为独立画布与节点卡片视图，优化节点内容排版、操作图标、选中态、批量复制和还原位置体验。
+- 统一普通流程线、操作按钮连线和判断分支线条样式，按节点实际高度计算连接位置，修复线条颜色不一致、断裂、多余线条、节点重叠和分支错位问题。
+- 优化判断分支布局，统一“是 / 否”分支的 T 形连接样式，避免分支节点堆叠、左右分支连接错乱及多出第三分支。
+- 连接脚本支持只读预览，使用眼睛图标打开预览弹窗，预览内容居中展示，修改仍需加载脚本后进行。
+- 连接脚本回放时会跳过子脚本开始后的重复“启动 App”和“清除 App”操作，减少跨脚本连接时的重复初始化。
+- 移除“连接到下一节点”“取消连接”“继续主流程”等冗余连接操作，保留复制节点作为主要复用方式。
+- 修复放大面板后点击操作按钮或节点配置会重置缩放的问题，保持当前画布大小和位置。
+- Android Playground 改为后台启动 5800 服务，不再自动打开 `http://localhost:5800/` 浏览器窗口。
+- CLI 启动时输出 GitHub 和 Issues 地址，方便用户反馈问题和提交建议。
+- 常见问题新增桌面点击 App 录制说明：部分厂商系统无法获取桌面图标稳定 id，建议使用开始节点后的“启动 App”操作替代。
+- 补充 GitHub 仓库、问题反馈和项目主页信息。
 
 ## v0.1.20
 
-- 修复包含判断分支的历史脚本在加载时因流程轴线循环计算导致渲染失败、无法切换到“当前录制”的问题。
-- Appium 工作区加载脚本后会同步切换并保存“当前录制”标签页状态。
-
-- Appium 判断分支按“是 / 否”两侧各自的子树宽度布局，并以当前判断节点为锚点就近排列；内容较少的一侧不再被推向画布远端，连接线同步跟随真实节点中心。
-- 加深 Appium 流程复制模式的节点选中颜色，并确保“是 / 否”分支节点不会覆盖蓝色选中边框。
-- Appium 复制判断节点后，父级分支会按嵌套子树宽度自动扩展；连接线端点与分支中心保持对齐，移除穿透子流程的父级竖线，并避免不同层级重复显示“插入操作”。
-- Appium 流程总览弹窗补齐批量复制、节点执行/编辑/删除、开始与节点后插入、分支插入及连接操作；移除“撤销粘贴”功能。
-- Appium 流程节点在主画布与放大弹窗中统一固定尺寸，补充分支节点间距，移除节点序号，并在放大弹窗补充主节点和递归分支节点的复制操作。
-- Appium 批量复制支持选择“分支末尾 → 已连接的后续主流程”节点，不再误报为不同分支。
-- Appium 流程复制支持递归展示粘贴后的判断子节点，保留“是 / 否”分支及其子节点的复制、编辑和插入操作。
-
-- Appium session 创建与“启动 APP”流程节点解耦：session 只绑定设备，应用统一由启动节点按预设包名通过 ADB 启动。
-- Appium 脚本保存和导入时会忽略不属于目标 App 的桌面、设置等系统 Activity，并从首个业务节点快照恢复入口 Activity。
-- Appium 录制流程新增单节点和同分支连续节点批量复制；可在现有插入位置粘贴，自动重建节点 ID、判断子流程和流程连接。
-- Appium 工作区扩大“录制与脚本”区域并保持设备预览完整高度；回放输出改为右下角悬浮入口，通过可拖动、可缩放弹窗查看。
-- 修复 Appium 批量复制判断节点和子节点时的跨分支误判；统一主流程与分支节点宽度，并扩大分支间距，避免粘贴节点尺寸不一致和内容挤压。
-- Appium 回放日志弹窗的输出区域改为暗色终端样式，并优化滚动条对比度。
-- 修复历史脚本因当前 Activity 不匹配时“粘贴节点”静默无效的问题；粘贴现在与普通插入操作使用相同锁定规则，并在页面操作忙碌时给出提示。
+- Appium 流程支持单节点、连续节点及完整判断子流程的复制与粘贴。
+- 优化判断分支布局和流程总览，支持在总览中编辑完整流程。
+- Appium session 与“启动 APP”节点解耦，并避免将桌面、设置等系统 Activity 误识别为脚本入口。
+- 修复复杂判断脚本加载失败及加载后无法进入“当前录制”的问题。
 
 ## v0.1.19
 
-- Appium 回放输出新增托管 Appium 服务端完整日志，并将页面回放输出和 Appium 原始日志保存为同名 `.log` 文件。
-- Appium 回放新增“终止”操作；手动终止后会关闭当前 session，并继续生成 Markdown 报告、日志和截图回放。
-- Appium 回放新增单文件 HTML 截图回放报告，内嵌实际执行节点前后、判断、失败与终止时的设备截图，无需额外图片目录。
-- HTML 回放报告新增左侧执行步骤、默认收起的完整日志、顶部真实时间轴、截图缩略图、播放控制和可拖动进度条。
-- HTML 回放按照节点截图的真实采集时间连续推进，并支持点击步骤、缩略图或时间轴定位画面。
-- HTML 回放头部统一状态、设备、App、耗时和执行时间的对齐方式，日期改为紧凑的 24 小时格式。
+- 回放输出支持保留完整 Appium 服务日志，并可在执行过程中手动终止。
+- 新增单文件 HTML 截图回放报告，提供时间轴、步骤导航和连续播放效果。
 
 ## v0.1.18
 
-- 修复 jsDelivr 将 HTML 文档显示为源码的问题；使用说明和更新记录改为自动嵌入 README，由 npm 页面直接渲染。
+- 使用说明和更新记录自动嵌入 README，可直接在 npm 页面渲染查看。
 
 ## v0.1.17
 
-- README 中的使用说明与更新记录链接改为 HTML 文档查看器，点击后直接显示渲染后的 Markdown 内容。
+- 新增在线文档查看入口，支持渲染使用说明和更新记录。
 
 ## v0.1.16
 
-- 参数配置页调整卡片顺序，将“预设 App 参数”移动到“运行配置”下方。
+- 优化参数配置页面布局，将预设 App 参数归入运行配置区域。
 
 ## v0.1.15
 
-- README 新增 Midscene 与 Appium 两种测试方式对比，明确 Midscene 必须配置模型，Appium 不依赖模型。
-- README 环境要求补充 Appium 3.x、UiAutomator2 Driver 的安装与启动说明。
-- README 明确 Android 测试不需要 Playwright Chromium，仅源码中的 Web E2E 示例需要单独安装。
+- README 新增 Midscene 与 Appium 两种测试方式及环境要求说明。
+- 明确 Midscene 需要配置模型，Appium 无需模型即可运行。
 
 ## v0.1.14
 
-- 参数配置新增 Android SDK 路径和 Appium 回放报告目录；留空时分别读取系统默认 SDK 和启动目录下的 `output`。
-- Appium 回放前新增 Android SDK 检测，并让设备列表、预览、组件树、设备操作和回放统一使用配置的 SDK 中的 ADB。
-- Appium 回放结束后自动在 `output` 目录生成 Markdown 报告，记录每个节点的配置、执行状态与完整回放日志，并将报告路径保存到数据库。
-- Appium 脚本列表新增 JSON 脚本导入和下载功能；导入重名脚本时自动生成新名称。
-- Appium 回放修复分支内末尾连接脚本被误当成全局连接执行的问题；连接脚本前会等待目标 Activity，减少页面切换尚未完成造成的误报。
-- Appium 判断节点的模糊文本匹配会统一换行和连续空白，避免录制文本与 Appium 返回文本仅因排版差异而误判为不存在。
-- Appium 设备预览恢复复用 Midscene Playground 的 scrcpy 实时流；仅在实时流不可用时启用 ADB 截图轮询，避免停帧和两种预览源相互覆盖。
-- Playground 代理补充 action-space 和 execute 路径，修复嵌入式设备预览初始化时的 404 错误。
-- Appium 组件树在当前 Activity 或页面结构变化后自动刷新，保留仍存在的已选节点，并避免与录制、回放和手动刷新并发。
-- Appium 回放与组件树的 `uiautomator dump` 按设备互斥：回放前等待正在进行的抓取结束，回放期间暂停新抓取，并在 `UiAutomation not connected` 时清理残留进程后自动重试一次。
-- Appium 判断分支中的连接脚本允许选择同一 App 的其他 Activity 脚本；回放到连接节点时等待目标入口 Activity，未真正跳转则超时失败。
-- Appium 回放输出改为 NDJSON 流式传输，节点开始、结果、完成、失败和报告路径会在执行过程中实时追加到回放日志。
-- Appium 线性脚本和流程图脚本的回放日志统一使用“[节点 N]”编号，不再混用“步骤”和“节点”。
-- Appium 判断分支后的主流程节点按实际前驱分支定位：单分支连接时沿该分支中轴继续排列，双分支汇合时回到中轴，后续线性节点继承前一节点位置。
-- Appium 流程节点新增备注字段，可在节点配置中编辑，并显示在操作描述下方。
-- 浏览器刷新后保持当前功能页面和 Appium 工作区 Tab；Appium 录制存在未保存修改时，刷新或关闭页面前显示保存提醒。
-- Appium 模块：“启动 APP”流程节点新增立即执行操作，可从系统桌面直接启动当前预设应用，并在刷新 Activity 后自动解除匹配页面的编辑锁定。
-- Appium 模块：Activity 不匹配时仍可使用开始节点和步骤节点的插入菜单；“启动 APP”仅保留在开始节点，普通节点提供其余操作。
-- Appium 模块：回放前检测目标 App 是否已在前台；已启动时关闭 Appium 自动拉起并跳过“启动 APP”节点，保留当前页面状态。
-- Appium 模块：判断节点移除后续节点下拉配置，是/否分支改为通过“连接下一节点”按钮自动连接判断后的主流程节点。
-- Appium 模块：“判断存在”支持按指定文本判断，可选择模糊匹配或精准匹配。
-- Appium 模块：判断节点的配置面板移动到当前节点正下方，不再显示在分支子节点末尾。
-- Appium 模块：分支子节点支持点击展开配置，节点尺寸与主流程节点保持一致。
-- Appium 模块：流程总览弹窗支持点击主流程和分支节点并直接修改配置。
-- Appium 模块：节点配置面板移除重复的“插入延时”按钮，延时统一从流程“插入操作”菜单添加。
-- Appium 模块：三列工作区比例调整为 3:3:4，缩小组件树区域并扩大录制与脚本区域。
-- Appium 模块：判断分支连接后使用流程线连接后续主节点，连接按钮切换为“取消连接”并支持解除连线。
+- 参数配置支持指定 Android SDK 和回放报告目录，并在回放前检查 Android SDK。
+- 回放完成后生成包含节点配置、执行结果和日志的 Markdown 报告。
+- 脚本列表支持 JSON 脚本导入和下载。
+- 设备预览接入 scrcpy 实时画面，组件树可随页面和 Activity 变化自动刷新。
+- 回放输出改为实时流式日志，并增强 UIAutomator 并发和异常恢复能力。
+- 判断分支支持文本匹配、连接不同 Activity 的脚本及连接后的主流程回放。
+- 新增节点备注、未保存提醒和页面状态持久化。
 
 ## v0.1.13
 
-- Appium 模块：修复加载历史脚本并新增节点后被误判为新脚本、无法覆盖保存的问题。
-- Appium 模块：脚本末尾的连接节点改为当前脚本完成后的串联阶段，避免判断分支未命中时漏掉后一个脚本。
+- 修复历史脚本新增节点后无法覆盖保存的问题。
+- 修复连接脚本未按顺序继续执行的问题。
 
 ## v0.1.12
 
-- 修复部分浏览器打开更新记录时中文乱码的问题，将 README 链接切换到明确返回 UTF-8 编码的 jsDelivr。
-- Appium 模块：删除结束节点、前置操作和后置操作；“启动 APP”改为从开始节点直接插入为流程第一步，并对齐开始节点与插入按钮。
-- Appium 模块：每个录制脚本只允许一个“启动 APP”节点；添加后操作菜单自动禁用该选项，删除节点后恢复。
-- Appium 模块：连接脚本回放时自动跳过子脚本的“启动 APP”节点，子脚本独立回放时仍正常启动 App。
+- “启动 APP”统一为流程开始节点操作，每个脚本最多添加一次。
+- 连接脚本回放时自动跳过子脚本的重复启动操作。
 
 ## v0.1.11
 
-- 修复 npm 页面中的项目更新记录链接，改为使用可直接访问包文件的 unpkg 地址。
+- 修复 npm 页面中的更新记录访问链接。
 
 ## v0.1.10
 
-- npm 包新增根目录 `CHANGELOG.md`，README 可直接查看项目更新记录。
-- README 删除未随 npm 包发布的内部文档链接。
+- npm 包新增项目更新记录，并清理未随包发布的内部文档链接。
 
 ## v0.1.9
 
-- Appium 模块：录制流程新增前置操作和后置操作区域，分别固定在“开始”之前和“结束”之后，目前仅支持“启动 APP”和“添加延时”。
-- Appium 模块：“启动 APP”回放时通过 ADB 启动当前预设 App 参数对应的应用包。
-- Appium 模块：节点详情的 selector 展示新增当前 Activity。
-- 文档：新增同组件不同内容弹窗的判断操作说明。
-- Appium 模块：“判断弹窗”改名为“判断存在”，支持用于弹窗以外的任意组件判断。
-- Appium 模块：判断节点的“是 / 否”分支支持直接插入操作，并自动连接到新步骤。
-- Appium 模块：判断节点分支内插入的步骤会按“是 / 否”归类展示，不再混入主线单列。
-- Appium 模块：判断节点后的步骤改为沿“是 / 否”分支线向下延伸，不再嵌套在分支容器中。
-- Appium 模块：统一分支步骤节点宽度与居中对齐，并补充删除节点操作。
-- Appium 模块：检测到 Activity 跳转时强制保存当前脚本，每份录制脚本限制在单个 Activity 内。
-- Appium 模块：录制步骤画布支持按住 Ctrl 使用鼠标滚轮缩放，缩放范围为 50%–200%。
-- Appium 模块：修复可拖动画布吞掉分支节点删除点击的问题，并在删除后自动修正流程目标引用。
-- Appium 模块：操作入口移动到录制流程的“开始”节点下方；分支仅关联从“是/否”入口插入的操作，并统一分支节点卡片与间距。
-- Appium 模块：加载已保存脚本时校验绑定 Activity；当前页面不一致时锁定流程编辑，避免跨 Activity 继续追加录制步骤。
-- Appium 模块：步骤操作新增“系统返回”（Android keyCode 4）；Activity 不匹配时仅允许将该操作插入脚本，其他流程编辑继续锁定。
-- Appium 模块：连接脚本按插入点 Activity 过滤并校验目标脚本入口 Activity；回放时再次校验手机当前 Activity，阻止尚未跳转就执行其他页面脚本。
-- Appium 模块：普通流程步骤与展开编辑面板改为紧凑宽度，减少可拖动画布中的横向空白。
-- Appium 模块：修复可拖动画布捕获步骤卡片点击的问题，步骤详情现在可通过再次点击卡片正常收起。
-- Appium 模块：判断节点分支支持连续追加多个操作。
-- Appium 模块：录制步骤区域改为可拖拽流程画布，默认显示第一个节点视角。
-- Appium 模块：录制步骤区域新增“放大”按钮，可弹出流程总览查看全部节点。
-- Appium 模块：判断分支线条改为连续曲线样式，减少断线和空白间隔。
-- Appium 模块：判断节点展示改为左右分叉流程样式。
-- Appium 模块：支持在任意录制步骤后插入其他操作。
-- Appium 模块：录制步骤改为流程图节点样式。
-- Appium 模块：支持点击步骤节点展开编辑面板。
-- Appium 模块：支持修改节点名称、节点类型、超时时间、输入内容和可选状态。
-- Appium 模块：支持编辑 selector 和父级上下文 selector。
-- Appium 模块：支持判断节点配置“是 / 否”分支目标。
-- Appium 模块：检测到页面变化时支持留在当前页面、保存为新用例或添加返回键继续录制。
-- Appium 模块：支持连接已保存脚本，用于登录脚本接首页脚本等组合场景。
-- Appium 模块：新增脚本列表 Tab，支持加载和删除已录制脚本。
-- Appium 模块：回放输出支持展开查看和清除日志。
-- Appium 模块：脚本存储移除旧版 `steps_json`，只保留 `flow_json`。
+- 录制步骤升级为可拖动、缩放和编辑的流程图，支持“是 / 否”判断分支。
+- 支持在流程任意位置插入操作，并编辑节点、定位器、超时和输入内容。
+- 支持 Activity 跳转检测和单 Activity 脚本录制保护。
+- 支持连接已保存脚本，组合登录、首页等跨页面测试流程。
+- 新增脚本管理列表，可加载、删除和回放已录制脚本。
 
 ## v0.1.8
 
-- Appium 模块：组件树新增 selector 唯一性检测。
-- Appium 模块：组件树节点展示“唯一”或“重复 N”状态。
-- Appium 模块：重复 selector 自动记录父级上下文定位信息。
-- Appium 模块：回放时支持“父级上下文 + 子级 selector”定位。
-- Appium 模块：回放查找顺序调整为父级上下文、备用 selector、当前 selector、坐标兜底。
-- Appium 模块：每个录制步骤新增页面检查点，保存录制前后 Activity 和页面摘要。
-- Appium 模块：回放失败日志新增当前 Activity、selector、上下文 selector、备用 selector 和录制前后 Activity。
+- 新增 selector 唯一性检测和父级上下文定位，解决多个组件共用同一 ID 的问题。
+- 回放支持多级定位和坐标兜底，并记录页面检查点与完整失败诊断信息。
 
 ## v0.1.7
 
-- Appium 模块：新增“存在则点击”操作。
-- Appium 模块：新增“存在则输入”操作。
-- Appium 模块：新增“存在则清空”操作。
-- Appium 模块：新增“存在则返回”操作。
-- Appium 模块：新增“等待出现”操作。
-- Appium 模块：新增“判断存在”操作。
-- Appium 模块：新增“等待元素消失”操作。
-- Appium 模块：“存在则...”类操作找不到目标时不再中断回放，并在日志中显示“未出现，已跳过”。
+- 新增存在则点击、输入、清空、返回等可选操作。
+- 新增等待出现、判断存在和等待消失等等待与判断能力。
 
 ## v0.1.6
 
-- Appium 模块：新增设备预览复用组件。
-- Appium 模块：设备预览支持点击画面选择组件树节点。
-- Appium 模块：设备预览支持刷新当前画面。
-- Appium 模块：App 组件树区域支持滚动浏览。
-- Appium 模块：App 组件树下方展示当前 Activity。
-- Appium 模块：操作按钮统一为“添加操作”下拉列表。
-- Appium 模块：删除截图操作入口。
+- 新增可复用设备预览，支持点击画面选择组件树节点和刷新实时画面。
+- 组件树支持滚动浏览并展示当前 Activity。
+- 录制操作统一通过“添加操作”菜单选择。
 
 ## v0.1.5
 
-- Appium 模块：新增组件树录制页面。
-- Appium 模块：支持从组件树选择节点并录制点击、输入、断言、延时。
-- Appium 模块：支持保存 Appium 录制脚本。
-- Appium 模块：支持通过 Appium 回放录制脚本。
-- Appium 模块：App 包名只能从“预设 App 参数”中选择。
+- 首次提供 Appium 无模型录制与回放能力。
+- 支持从组件树录制点击、输入、断言和延时，并保存为可回放脚本。
+- App 包名与参数配置中的预设 App 统一管理。
 
 <!-- generated-docs:end -->

package/USAGE.md

@@ -2,7 +2,7 @@
 
 本文档说明 Appium 组件树录制器的完整使用方式，包括每个操作按钮的用途、录制方法和示例。
 
-本文档随 npm 包发布，也可以从 README 的“功能文档”直接打开。
+本文档随 npm 包发布，也可以从 README 的“功能文档”直接打开。常见问题请查看 [FAQ.md](./FAQ.md)。
 
 ## 使用前准备
 
@@ -459,14 +459,14 @@ Home 键
 4. 点击判断节点，按需填写“指定文本”。
 5. 选择“模糊匹配（包含）”或“精准匹配（完全一致）”。
 6. 在“是”或“否”分支下点击“插入操作”，分别添加分支步骤。
-7. 需要回到判断后的主流程时，点击分支旁的“连接到下一节点”；连接成功后按钮变为“取消连接”。
+7. 如果两个分支后续要执行相同操作，可以复制公共节点到对应分支，或把公共流程拆成“连接脚本”复用。
 
 示例：
 
 ```text
 判断存在 确认按钮
   是 -> 点击 确认按钮
-  否 -> 继续主流程
+  否 -> 不添加操作
 ```
 
 分支说明：
@@ -476,7 +476,6 @@ Home 键
 - 模糊匹配会忽略换行和连续空白差异，只要规范化后的文本包含目标内容即可。
 - 精准匹配要求 Appium 返回的完整文本与指定文本完全一致。
 - 分支可以包含多个连续步骤，也可以在分支末尾连接其他脚本。
-- “连接到下一节点”只在判断后仍有主流程节点时显示。
 
 适用场景：
 
@@ -496,7 +495,7 @@ Home 键
 3. 选择“判断存在”。
 4. 展开节点，在“指定文本”中输入该弹窗特有的文案。
 5. 根据需要选择模糊匹配或精准匹配。
-6. 在“是”分支添加该弹窗对应的确认、取消或关闭步骤；“否”分支继续下一个判断或主流程。
+6. 在“是”分支添加该弹窗对应的确认、取消或关闭步骤；“否”分支继续下一个判断或不添加操作。
 
 示例：
 
@@ -505,7 +504,7 @@ Home 键
   是 -> 点击 确定
   否 -> 判断存在：指定文本“是否退出登录”
         是 -> 点击 确定
-        否 -> 继续主流程
+        否 -> 不添加操作
 ```
 
 适用场景：
@@ -867,12 +866,8 @@ output/2026-08-21_17-13-42-831-登录流程.html
 输入 账号
 输入 密码
 判断存在 用户协议弹窗
-  是 -> 点击 同意
-  否 -> 连接到下一节点
-点击 登录
-判断登录是否成功
-  是 -> 连接脚本 首页脚本
-  否 -> 断言文本 登录错误提示
+  是 -> 点击 同意 -> 点击 登录 -> 判断登录是否成功 -> 连接脚本 首页脚本
+  否 -> 点击 登录 -> 判断登录是否成功 -> 连接脚本 首页脚本
 ```
 
 首页脚本：
@@ -906,16 +901,15 @@ output/2026-08-21_17-13-42-831-登录流程.html
 2. 选择用于区分登录结果的稳定元素，添加“判断存在”。
 3. 在“是”分支插入首页校验或“连接脚本”。
 4. 在“否”分支插入错误提示断言。
-5. 需要继续执行判断后的公共步骤时，点击对应分支的“连接到下一节点”。
+5. 如果两个分支后续有相同公共步骤，使用批量复制把公共节点复制到对应分支。
 
 ### 示例 3：一次性弹窗
 
 ```text
 启动 App
 判断存在 确认按钮
-  是 -> 点击 确认按钮
-  否 -> 连接到下一节点
-断言存在 首页
+  是 -> 点击 确认按钮 -> 断言存在 首页
+  否 -> 断言存在 首页
 ```
 
 适合场景：
@@ -951,89 +945,7 @@ output/2026-08-21_17-13-42-831-登录流程.html
 
 ## 常见问题
 
-### 同一个 id 定位到错误输入框怎么办
-
-如果账号框和密码框都是 `id/tg_edit`，只按 id 回放可能输入到第一个输入框。
-
-建议：
-
-- 直接分别选择账号框和密码框录制输入。
-- 在节点详情里确认 selector 是否显示“重复 N”，以及“推荐定位”是否显示父级 + 子级。
-- 如果推荐定位不准确，展开录制步骤，手动修改父级上下文 selector。
-- 坐标点击只作为最后兜底。
-
-### 点击后没有检测到页面跳转怎么办
-
-可能原因：
-
-- 按钮当前禁用。
-- 账号密码不正确。
-- App 使用单 Activity，Activity 不变化。
-- 页面跳转依赖网络。
-
-推荐：
-
-- 使用“断言存在”判断下个页面核心元素。
-- 多 Activity 页面可以拆成两个脚本，在判断分支中用“连接脚本”串起来；回放会等待目标 Activity 出现。
-- 单 Activity App 不要依赖 Activity 变化，应使用页面核心元素判断是否已进入目标状态。
-
-### 为什么连接脚本提示入口 Activity 不匹配
-
-- 主流程连接要求目标脚本入口 Activity 与当前插入点一致，适合复用同一页面上的公共流程。
-- 登录后进入首页等跨 Activity 场景，应先添加“判断存在”，再在“是”或“否”分支中添加“连接脚本”。
-- 分支连接允许选择同一 App 的其他 Activity，但不会主动跳转页面；前面的点击或输入必须真正触发跳转。
-- 如果页面未跳转，回放会在等待目标 Activity 超时后失败，这是为了防止在错误页面执行目标脚本。
-
-### 弹窗只出现一次怎么办
-
-使用“判断存在”。
-
-```text
-判断存在 确认按钮
-  是 -> 点击 确认按钮
-  否 -> 继续主流程
-```
-
-不要直接把弹窗确认按钮作为普通必选点击，否则弹窗不出现时脚本会失败。
-
-### 什么时候用等待 Activity
-
-适合多 Activity App。
-
-如果 App 是单 Activity 架构，优先用：
-
-```text
-断言存在 页面核心元素
-```
-
-### 什么时候用可选步骤
-
-可选步骤适合非主流程阻塞项：
-
-- 权限弹窗
-- 协议弹窗
-- 活动弹窗
-- 首次引导
-
-不建议把登录按钮、提交按钮、核心断言设置为可选。
-
-### 回放时出现 UiAutomation not connected 怎么办
-
-组件树刷新和 Appium 回放不能同时占用 UiAutomation。当前版本会在回放期间暂停组件树自动刷新，并在断开时清理残留抓取进程后重试一次。
-
-如果仍然失败：
-
-1. 确认手机保持解锁，USB 调试授权没有失效。
-2. 确认 Appium 和 UiAutomator2 Driver 已正常启动。
-3. 停止其他正在抓取同一设备组件树的工具。
-4. 重新连接设备后再次回放。
-
-### 设备预览或组件树没有更新怎么办
-
-1. 先确认设备仍显示在设备下拉框中。
-2. 点击设备预览刷新按钮重新获取画面。
-3. 点击“刷新组件树”重新抓取页面结构。
-4. 回放期间组件树自动刷新会暂停，回放完成后会自动恢复。
+常见问题已独立整理到 [FAQ.md](./FAQ.md)。
 
 ## 推荐录制规范
 
@@ -1043,5 +955,4 @@ output/2026-08-21_17-13-42-831-登录流程.html
 - 弹窗或其他可选组件使用“判断存在”，不要直接写死必点。
 - 坐标点击只作为兜底。
 - 给关键节点填写“登录按钮”“账号输入框”等备注，方便查看流程和报告。
-- 判断分支需要回到主流程时，明确点击“连接到下一节点”。
 - 回放失败后优先查看“回放输出”中的失败节点、Activity 和 selector，再打开 `output` 中的 Markdown 报告查看完整配置。

package/bin/android-midscene-automation.js

@@ -10,12 +10,16 @@ const viteRoot = path.dirname(require.resolve('vite/package.json'));
 const viteBin = path.join(viteRoot, 'bin', 'vite.js');
 const args = process.argv.slice(2);
 const userRoot = process.cwd();
+const githubUrl = 'https://github.com/oooooooko/android-midscene-automation';
 
 if (!args.includes('--host')) {
   args.unshift('127.0.0.1');
   args.unshift('--host');
 }
 
+console.log(`\nGitHub 源码 / 二次修改：${githubUrl}`);
+console.log(`问题反馈 / 功能建议：${githubUrl}/issues\n`);
+
 const child = spawn(process.execPath, [viteBin, ...args], {
   cwd: packageRoot,
   env: {