@mobileaidev/ai-app-bridge 0.2.15 → 0.3.0-rc.2

package/skills/ai-app-bridge-use/SKILL.md

@@ -1,385 +1,48 @@
 ---
 name: ai-app-bridge-use
-description: 使用 AI App Bridge MCP 观察、操作、验证和调试 Android native、Android WebView/H5/CDP、Flutter、iOS native + WDA/XCUITest、WKWebView 和桌面 Web Bridge。能力域包括 core/status/tree/screenshot/logs/network/state/events，app/install/clear-data/launch/freeze/thaw/permissions/appops，action/tap/input/swipe/keyevent/wait/keyboard，flutter/widget/action，webview/H5/CDP，ios/devices/setup/runtime/WDA/H5/flutter，web/session/DOM/logs/network/events/command，diagnostics/logcat/smoke，advanced/batch/port-forward。
+description: 通过 AI App Bridge 实际观察、操作和验证 App 时使用。用 Intent 进行观察与决策，用 Script 进行重复回归，用共享命令进行单次操作和诊断，并通过当前 MCP capabilities 核对参数与平台范围。开发 Bridge 本身时，以当前源码和命令合同为准。
 ---
 
 # AI App Bridge Use
 
-## 能力总览
+## 选择执行方式
 
-AI App Bridge 支持 Android native apps、Android WebView/H5/CDP、Flutter apps、iOS native apps via `AiAppBridgeIOS` + WebDriverAgent/XCUITest、WKWebView，以及桌面 Web Bridge sessions。
+Intent 和 Script 是一等执行入口。日常页面操作、未知流程和系统窗口交互使用 Intent 的观察与决策合同；固定流程使用 JavaScript/Python Script。单次观察、动作、安装、权限夹具和诊断命令同样有独立价值。
 
-默认 MCP surface 只有 `capabilities` 和 `run`；先用 `capabilities` 查 domain、command 和 options，再用 `run` 执行。
+1. 从任务、构建产物和设备状态确定目标。Android 动作明确传 `serial`，App 操作传 `packageName`；iOS 使用 `deviceId`/`bundleId`，Native Intent 还需绑定 `wdaRunnerBundleId`/`wdaSessionId`；Web 使用当前文档的 `sessionId`/`runtimeEpoch`/`targetId`。
+2. 调用 `capabilities` 查询本次实际运行版本的命令。指定 `command` 时返回完整 `inputSchema`、`role`、`entrypoints` 和 Script 能力声明。先核对平台与参数，再派发。
+3. MCP 只有 `capabilities` 和 `run`。所有命令参数放在 `run.arguments`，命令名使用 capabilities 原样返回的名称。JSON 数字、布尔值不写成字符串。Intent/Script/evidence 必须明确 operation；嵌套控制参数也以当前 inputSchema 为准，错误中的 field 指向需修正的字段。
+4. 从当前观察取得 selector 或坐标。`tap-text` 的 `provider:auto` 按 Native、Flutter、UIAutomator 顺序观察并选择一次动作；`provider:native|flutter|uia` 可固定回归来源。结果中的 observations/provider 说明选择依据。动作前会重新定位，多重匹配、语义身份或前台变化应重新观察。UIA 同名控件可用当前 `uia-tree` 的完整 `targetRef`，或当前 Intent revision 的 `selector.nodeRef`；引用失效后重新观察。Native 前台弹窗会阻挡后台 Flutter 文字动作。
+5. 按任务的真实结果验证。执行完成、机械动作成功、UI 变化、业务状态和证据覆盖分别判断；操作后使用本轮新证据。没有足够证据的断言保留为 inconclusive。
 
-目标标识：Android 用 `packageName` 或显式 `port`；iOS 用 `bundleId`，多设备加 `deviceId`，full-control 加 `wdaUrl`；Web 用 `sessionId`，多 target 加 `targetId`。
-
-命令域：
-- `core`: `status`/`tree`/`uia-tree`/`screenshot`/`logs`/`network`/`state`/`events`
-- `app`: `install-apk`/`clear-app-data`/`launch-*`/`freeze-app`/`thaw-app`/`permission-*`/`appops-set`
-- `action`: `tap`/`tap-text`/`tap-uia-text`/`input-text`/`swipe`/`keyevent`/`wait-text`/`keyboard-*`
-- `flutter`: `flutter-tree`/`flutter-nodes`/`flutter-action`/`tap-flutter-text`/`input-flutter-text`/`scroll-flutter`
-- `webview`: `h5-*`/`flutter-h5-*`/`webview-pages`/`webview-network`/`webview-console`
-- `ios`: `ios-devices`/`ios-doctor`/`ios-setup`/`ios-status`/`ios-tree`/`ios-uia-tree`/`ios-tap`/`ios-input`/`ios-swipe`/`ios-h5-*`/`ios-flutter-*`
-- `web`: `web-session-start`/`web-sessions`/`web-status`/`web-dom`/`web-logs`/`web-network`/`web-state`/`web-events`/`web-command`/`web-click`/`web-input`/`web-wait`/`web-scroll`
-- `diagnostics`/`advanced`: `logcat`/`smoke`/`batch`/`forward`/`remove-forward`
-
-## Agent 快速流程
-
-1. 确认目标：Android 使用 `packageName`，iOS 使用 `bundleId`，真机多设备场景传 `deviceId`/UDID；Web 使用 `sessionId`，多 target 时加 `targetId`。没有目标 id 时先从上下文、构建配置或前台 app/session 线索推断。面向具体 app/session 的命令必须传目标 id，只有无法发现 bridge 端口时才传 `port`、`runtimeUrl` 或先启动 Web session。
-2. 发现能力：默认 MCP surface 只有 `capabilities` 和 `run`。不确定命令或参数时先调用 `capabilities`，再用 `run` 执行。
-3. 选择命令路径：按任务类型选 `core`、`app`、`action`、`flutter`、`webview`、`ios`、`web`、`diagnostics` 或 `advanced` 域；不要先退回原始 `adb`、浏览器脚本或坐标猜测。
-4. 用 `batch` 串联相关步骤：观察、操作、等待、截图、tree 验证尽量放进一次 MCP 调用。
-5. 验证可见结果：界面变化必须用 `screenshot` 加 `tree`/`uia-tree` 交叉确认。
-6. 生成截图等默认产物时，让 AI Bridge 自动选择会被当前项目 git 忽略的目录；只有确实需要固定路径时才传 `outFile`/`artifactDir`，且路径必须在 `build`、`.build`、`.dart_tool`、`node_modules/.cache`、`target` 或其他已忽略目录内。
-7. 只在需要稳定动态画面时使用 `freeze-app`/`thaw-app`；如果本轮冻结过 app，最终回复前必须解冻。
-
-## 能力发现和调用
-
-`capabilities` 用来列出命令域和参数：
-
-```json
-{ "domain": "webview", "includeOptions": true }
-```
-
-```json
-{ "command": "input-text", "includeOptions": true }
-```
-
-`run` 用 CLI 形式的命令名执行能力，例如：
-
-```json
-{
-  "command": "screenshot",
-  "packageName": "com.example.app"
-}
-```
-
-如果 MCP 暴露的是 full/legacy surface，直接工具名通常用下划线形式；语义与 `run` 里的连字符命令一致，例如 `tap_text` 对应 `tap-text`。
-
-## 任务路由
-
-| 任务 | 首选命令 |
-| --- | --- |
-| 当前 app 状态和桥接信息 | `status` |
-| 真实可见画面 | `screenshot` |
-| App 内 View 节点 | `tree`，常配 `compact`、`visibleOnly` |
-| 系统窗口、权限弹窗、Compose/跨 app UI | `uia-tree`、`tap-uia-text` |
-| 点击、输入、等待、滑动、按键 | `tap-text`、`tap`、`input-text`、`wait-text`、`swipe`、`keyevent` |
-| 键盘处理 | `keyboard-state`、`hide-keyboard` |
-| 安装、启动、清数据 | `install-apk`、`launch-app`、`launch-activity`、`clear-app-data` |
-| 权限和 appops | `permission-state`、`permission-grant`、`permission-revoke`、`permission-dialog`、`appops-set` |
-| Flutter UI 和动作 | `flutter-tree`、`flutter-nodes`、`tap-flutter-text`、`input-flutter-text`、`scroll-flutter`、`flutter-action` |
-| 原生 WebView DOM | `h5-dom`、`h5-click`、`h5-input`、`h5-wait`、`h5-scroll` |
-| Flutter H5 adapter | `flutter-h5-dom`、`flutter-h5-click`、`flutter-h5-input`、`flutter-h5-wait`、`flutter-h5-scroll` |
-| WebView CDP 网络/控制台 | `webview-pages`、`webview-network`、`webview-console` |
-| App 内记录 | `logs`、`network`、`state`、`events` |
-| Android 日志 | `logcat`，按 `pid`、`appPid`、`tag`、`level`、`grep` 过滤 |
-| iOS 设备/环境检查 | `ios-devices`、`ios-doctor`、`ios-setup` |
-| iOS App 内证据 | `ios-status`、`ios-tree`、`ios-logs`、`ios-network`、`ios-state`、`ios-events`、`ios-h5-dom`、`ios-h5-eval` |
-| iOS 系统级 UI 与动作 | `ios-uia-tree`、`ios-tap`、`ios-input`、`ios-swipe`、`ios-screenshot` |
-| Web Bridge session | `web-provider-status`、`web-session-start`、`web-connect-info`、`web-sessions` |
-| Web DOM 和证据 | `web-status`、`web-dom`、`web-logs`、`web-network`、`web-state`、`web-events` |
-| Web 页面动作 | `web-click`、`web-input`、`web-wait`、`web-scroll`、`web-command` |
-| 自检 | `smoke` |
-| 多步骤串行执行 | `batch` |
-| 动态画面稳定 | `freeze-app`、`thaw-app`，只按需使用 |
-
-## 常用模式
-
-观察当前界面：
-
-```json
-{
-  "command": "batch",
-  "arguments": {
-    "defaults": { "packageName": "com.example.app" },
-    "steps": [
-      { "id": "status", "command": "status" },
-      { "id": "shot", "command": "screenshot" },
-      { "id": "tree", "command": "tree", "arguments": { "compact": true, "visibleOnly": true } }
-    ],
-    "stopOnError": true,
-    "includeRaw": true
-  }
-}
-```
-
-点击并验证结果：
-
-```json
-{
-  "command": "batch",
-  "arguments": {
-    "defaults": { "packageName": "com.example.app" },
-    "steps": [
-      { "id": "tap", "command": "tap-text", "arguments": { "targetText": "继续" } },
-      { "id": "wait", "command": "wait-text", "arguments": { "targetText": "完成", "timeoutSec": 8 } },
-      { "id": "shot-after", "command": "screenshot" },
-      { "id": "tree-after", "command": "tree", "arguments": { "compact": true, "visibleOnly": true } }
-    ],
-    "stopOnError": true,
-    "includeRaw": true
-  }
-}
-```
-
-输入文本：
-
-```json
-{
-  "command": "input-text",
-  "packageName": "com.example.app",
-  "arguments": {
-    "text": "中文输入",
-    "hideKeyboard": true
-  }
-}
-```
-
-捕获 WebView 网络：
-
-```json
-{
-  "command": "webview-network",
-  "packageName": "com.example.app",
-  "arguments": {
-    "durationMs": 3000,
-    "urlFilter": "/api/"
-  }
-}
-```
-
-iOS 观察和操作：
-
-```json
-{
-  "command": "batch",
-  "arguments": {
-    "defaults": {
-      "deviceId": "00008150-...",
-      "bundleId": "com.example.ios"
-    },
-    "steps": [
-      { "id": "status", "command": "ios-status" },
-      { "id": "tree", "command": "ios-tree" },
-      { "id": "uia", "command": "ios-uia-tree", "arguments": { "wdaUrl": "http://[fd00::1]:8100" } },
-      { "id": "tap", "command": "ios-tap", "arguments": { "wdaUrl": "http://[fd00::1]:8100", "tapX": 160, "tapY": 320 } },
-      { "id": "events", "command": "ios-events" }
-    ],
-    "stopOnError": true,
-    "includeRaw": true
-  }
-}
-```
-
-Web session 启动和连接：
-
-```json
-{
-  "command": "web-session-start",
-  "arguments": {
-    "webPort": 18180,
-    "token": "session-token"
-  }
-}
-```
-
-页面调试入口使用 Web SDK 连接：
-
-```js
-import { createAiAppBridge } from "@mobileaidev/ai-app-bridge-web";
-
-const bridge = createAiAppBridge({
-  endpoint: "ws://127.0.0.1:18180/ai-app-bridge-web",
-  token: "session-token",
-  appName: "demo-web-app",
-  capture: { console: true, errors: true, fetch: true, xhr: true, dom: true }
-});
-
-bridge.start();
-```
-
-Web 观察、操作和验证：
+## 最小调用
 
 ```json
-{
-  "command": "batch",
-  "arguments": {
-    "defaults": { "sessionId": "web-session-abc123" },
-    "steps": [
-      { "id": "status", "command": "web-status" },
-      { "id": "dom", "command": "web-dom", "arguments": { "refresh": true } },
-      { "id": "click", "command": "web-click", "arguments": { "selector": "button[type=submit]" } },
-      { "id": "wait", "command": "web-wait", "arguments": { "targetText": "Saved", "timeoutMs": 5000 } },
-      { "id": "events", "command": "web-events" }
-    ],
-    "stopOnError": true,
-    "includeRaw": true
-  }
-}
+{"command":"tap-text","arguments":{"serial":"DEVICE","packageName":"com.example.app","targetText":"设置","provider":"auto"}}
 ```
 
-## 验证规则
-
-把 `screenshot` 当作当前可见画面的最高优先级证据，把 `tree`/`uia-tree` 当作可操作节点和结构证据。
-
-对打开/关闭面板、关闭弹窗、切换页面、点击 tab、进入详情页、展开抽屉、按钮触发内容变化等可见状态变化，必须同时采集截图和 tree。只有二者指向同一状态时，才报告成功。
-
-如果截图和 tree 冲突：
-
-- 以截图判断用户实际看到什么。
-- 认为 tree 可能包含缓存、不可见节点、过期层或非前台窗口。
-- 重新等待、采集或换用 `uia-tree`、坐标点击、Flutter/WebView 专用命令。
-- 不要把冲突证据包装成确定结论。
-
-异步 UI 用 `wait-text` 或 H5/Flutter wait 命令等待；不要用固定 sleep 代替状态判断。
-
-## 平台专项
-
-iOS：
-
-- 完整能力必须同时使用两层：App 内 `AiAppBridgeIOS` runtime 负责结构化证据，WebDriverAgent/XCUITest 负责系统级 tap/input/swipe、权限弹窗、外部 UI tree 和跨 app UI。
-- 首次真机使用先跑 `ios-devices` 和 `ios-doctor`。如果 Developer Mode、DDI、信任、解锁、Xcode Apple team 或 WDA signing 不满足，停下来报告 blocker，不要跳过 WDA 降级成只读模式。
-- WDA 可由 `ios-setup --start-wda --team-id <APPLE_TEAM_ID>` 启动；真机上返回的 WDA URL 可能是 CoreDevice tunnel，例如 `http://[fdxx::1]:8100`，后续 `ios-uia-tree`、`ios-tap`、`ios-input`、`ios-swipe` 都优先复用这个 URL。
-- 文本输入优先用元素目标，例如 `ios-input` 搭配 `accessibilityId` 或 `elementId` 和 `clearFirst`；坐标输入仅用于没有稳定 accessibility id 的控件。
-- Flutter iOS 仍按 Flutter 路径读 widget/action 证据；设备级动作、权限弹窗和外部 UI 仍走 iOS WDA 命令。
+`wait-text` 使用 `timeoutMs`（默认 10000），文字精确匹配；`requireText`/`absentText` 是字符串数组，不接受 CSV。所有条件必须由同一次前台 provider 观察证明。纯消失等待必须明确 `provider`，读取失败不能证明消失。`requireActivity` 是完整类名。Native Intent 输入必须有 SDK `editable:true`。
 
-Web：
+`tap` 是物理坐标；`tap-flutter` 是 Flutter 逻辑坐标。显式 App 目标必须匹配前台。系统 UI 使用已观察的系统目标与 device scope。已派发但结果未知时，先重新观察，不通过另一个 provider 重试同一动作。
 
-- 独立 Web app 不用 Android `packageName`；先 `web-session-start` 启动桌面 WebSocket provider，再用 `web-connect-info` 读取 endpoint/token，让页面里的 `@mobileaidev/ai-app-bridge-web` SDK 连接。
-- SDK 只放在 debug/test/client 代码里；SSR 框架必须只在浏览器端初始化，生产环境默认不要启用。
-- 页面连接后先用 `web-sessions` 找 `sessionId`，再用 `web-status`、`web-dom`、`web-logs`、`web-network`、`web-state`、`web-events` 采集证据。
-- 操作页面优先用 `web-command` 调注册过的白名单 action；需要 DOM 操作时用 `web-click`、`web-input`、`web-wait`、`web-scroll`，并传稳定 `selector` 或 `targetText`。
-- 多页面、iframe 或自定义 surface 时传 `targetId`；如果返回 target ambiguous，先读取候选 target 再重试。
+CLI 和 MCP 共用独立执行 Runtime、命令 schema 和 operationId。客户端退出后任务继续运行；用任务 cancel 停止一个任务，或 `runtime operation:stop` 等待全部已拥有工作收尾。更换版本或 Runtime 环境先显式 stop，再启动。详细生命周期见 CLI 包内 `docs/COMMAND_CONTRACT.md`（仓库路径 `desktop/ai-app-bridge-cli/docs/COMMAND_CONTRACT.md`）。
 
-Flutter：
+`script` 的 start/status/wait/result/pause/resume/decide/cancel/runtime-status 操作用于连续执行和控制。start 使用 script 及其内部 target，语言明确为 javascript 或 python；调用失败和断言结果由源码处理。status/wait 和完成事件保留小型 resultRef；最终返回值通过 `script operation:result` 加原 operationId 从持久存储读取，核对 representation 和 hash。编写脚本前查询 `capabilities {"command":"script"}`；按需读取 CLI 包内 `docs/SCRIPT_AUTHORING.md`（仓库路径 `desktop/ai-app-bridge-cli/docs/SCRIPT_AUTHORING.md`）。`app.lifecycle` 和 `app.permissions` 是可信调用者为回归夹具显式选择的额外能力。JS/Python 是 trusted-local-code，权限声明不是 OS 沙箱。
 
-- 先尝试泛用 `tap-text`/`input-text`；失败、节点不可见或语义特殊时切到 `flutter-*`。
-- 用 `flutter-nodes` 找可操作节点，用 `scroll-flutter` 处理需要滚动后才出现的文本。
+普通 Android 命令的 timeoutMs 是包括排队和 Provider 调用的同一 Host 预算，默认 30000 ms；不能用内部重试延长。Script 的 policy.timeoutMs 限制整个运行，单个调用只能缩短预算。取消期间状态为 cancelling，已拥有的调用、回执和检查点收尾后才写 cancelled；已提交但未确认的动作仍是 ambiguous，不能宣称撤销成功。安装/权限 Intent、iOS/Web 及等待条件的范围按包内 COMMAND_CONTRACT.md 判断。
 
-WebView/H5：
+普通 Intent 的 timeoutMs 默认 300000，覆盖初次观察、等待决策、暂停和后续动作。cancel 会中止并等待已拥有的操作收尾，终态必须先写入检查点；写入失败是 blocked_evidence_store。重启后的 intent status 从持久证据恢复终态，live:false、recovered:true，不自动重放；缺少终态时报告 interrupted/runtime_restarted。最后一个动作的 dispatched/ambiguous 仍需独立检查。complete/fail/inconclusive 决策同样必须提供当前 basedOnRevision。
 
-- DOM 操作优先用 `h5-*` 或 `flutter-h5-*`，避免靠坐标猜元素。
-- CDP 网络/控制台用 `webview-network`/`webview-console`；目标 app 需要 debuggable，且 WebView debugging 可用。
-- `webview-pages` 可先确认可 attach 的 page、socket、URL。
+`install-apk` 通过 CLI 或 MCP 返回一个 supervised Intent 操作。调用者用该 operationId 观察系统页面并提交基于 revision 的唯一 selector 决策；没有 Agent 决策不会点击按钮。安装完成由 ADB 回执和独立 APK 身份核验共同确定。安装作为 Script 前置准备，后续客户端可继续观察和决策；同步 ctx.call 不提供安装入口，详见命令合同。
 
-输入：
+`permission-dialog` 同样返回 Intent 操作：先由 App 触发权限请求，再明确 packageName、permission 和 outcome（allow / allow-once / deny / dismiss）。依据实际弹窗决定 selector，以 PackageManager 状态及原 Activity 关闭核验结果；pending:activity_closure 时用 intent observe 继续核验。intent cancel 只停止任务；dismiss 才表示操作界面关闭弹窗。权限状态与 grant/revoke 夹具继续可直接调用；详情见包内 docs/COMMAND_CONTRACT.md。
 
-- 中文和 Unicode 输入优先用 `input-text` 或 `input-flutter-text`，不要用原始 `adb shell input text`。
-- 下半屏点击前注意键盘遮挡；必要时先 `keyboard-state` 再 `hide-keyboard`。
+## 证据与平台
 
-权限和系统 UI：
+Android 和 iOS 四流在持久后端接入后读取手机 FactStore；Host 记录执行与观察，Web 采集在接收时写入 Host FactStore。核对实际 refs、epoch、目标、窗口、coverage 和分页，保留失败或不完整覆盖。Script 和 Intent 支持 Android、iOS 和 Web，具体 provider 与动作范围以当前 schema 为准；支持平台不等于该 App 业务已经验证。
 
-- 运行时权限优先用 `permission-state`/`permission-grant`/`permission-revoke`。
-- 必须处理系统弹窗时，用 `permission-dialog` 或 `uia-tree`/`tap-uia-text`。
+用 `evidence` 导出并离线核验保留的执行记录与文件；归档完整不等于业务通过。错误返回保留 `error`、`message`、`dispatched`、`ambiguous` 和操作状态。在冻结 App 的诊断中，完成后恢复运行。
 
-## Freeze/Thaw 策略
-
-`freeze-app`/`thaw-app` 是稳定动态画面的能力之一，不是默认动作节奏。只有冻结能让证据更可靠时才用。
-
-`freeze-app`/`thaw-app` 只适用于移动 app runtime；Web Bridge 目标不要使用这两个命令。
-
-适合冻结：
-
-- 视频、动画、倒计时、实时刷新列表、游戏、播放页等会在思考期间变化的画面。
-- 点击后出现短暂状态，需要先固定再分析截图和节点。
-- 用户要求精确截图、坐标、像素或瞬时状态验证。
-
-不要冻结或不要提前冻结：
-
-- 静态页面的一次性观察、简单点击、普通表单输入。
-- `install-apk`、`launch-*`、`clear-app-data`、权限弹窗处理。
-- `wait-text`、点击、输入、滚动、WebView CDP 捕获、`logcat --follow` 等命令尚未完成时。
-
-如果使用冻结：
-
-1. 读取、操作、等待、捕获前先确保 app 解冻。
-2. 拿到本轮证据后，确实需要稳定画面时再 `freeze-app`。
-3. 冻结期间只做分析和规划，不执行依赖 app 运行的命令。
-4. 下一次读取/操作/等待/捕获前先 `thaw-app`。
-5. 最终回复前调用 `thaw-app`，不要把 app 留给用户时仍处于冻结状态。
-
-动态画面采集并冻结：
-
-```json
-{
-  "command": "batch",
-  "arguments": {
-    "defaults": { "packageName": "com.example.app" },
-    "steps": [
-      { "id": "thaw", "command": "thaw-app" },
-      { "id": "shot", "command": "screenshot" },
-      { "id": "tree", "command": "tree", "arguments": { "compact": true, "visibleOnly": true } },
-      { "id": "freeze", "command": "freeze-app" }
-    ],
-    "stopOnError": true,
-    "includeRaw": true
-  }
-}
-```
-
-最终恢复：
-
-```json
-{
-  "command": "thaw-app",
-  "packageName": "com.example.app"
-}
-```
-
-## 失败处理
-
-- `packageName`/`port` 缺失：先补目标，不要让 MCP 回落到默认 sample。
-- iOS `bundleId`/`deviceId`/`wdaUrl` 缺失：先用 `ios-devices`/`ios-setup` 补齐；需要 full-control 时不要在没有 WDA 的情况下宣称完成。
-- iOS 设备锁屏、未信任、Developer Mode/DDI 不可用、WDA signing 失败、首次启动弹出授权/密码框：停下告诉用户需要操作，用户处理后再重试。
-- Web `sessionId` 缺失：先跑 `web-session-start`、让页面 SDK 连接，再用 `web-sessions` 获取 session；不要把 Web 命令改成 Android `packageName`。
-- Web provider 未运行或 endpoint/token 不匹配：用 `web-provider-status` 和 `web-connect-info` 重新确认连接信息，让页面刷新后重连。
-- Web target ambiguous：读取 `web-sessions` 或 `web-dom` 返回的 target 候选，明确传 `targetId`。
-- Web command 被拒绝：确认页面 SDK 是否注册了对应 action，或改用允许的 `web-click`/`web-input`/`web-scroll`；不要临时打开任意 `eval`。
-- `screenshot` 报前台 package 不匹配：先 `launch-app` 或确认当前前台，再继续判断。
-- `tree` 为空但截图正常：尝试 `uia-tree`、等待一轮或使用 Flutter/WebView 专用命令。
-- WebView CDP 不可用：确认 app debuggable、WebView debugging、目标 page；不能用 CDP 时退回 `h5-*` 或可见 UI 验证。
-- `freeze-app` 失败：继续任务；只有影响动态证据稳定性时才说明限制。
-- 冻结状态下读取超时：先 `thaw-app` 再重试。
-- 最终 `thaw-app` 失败：在回复中明确说明 app 可能仍被冻结。
-
-## 安装配置
-
-如果当前会话没有 AI App Bridge MCP，安装桌面包：
-
-```bash
-npm install -g @mobileaidev/ai-app-bridge
-```
-
-Web 页面需要额外在目标项目中安装调试 SDK：
-
-```bash
-npm install --save-dev @mobileaidev/ai-app-bridge-web
-```
-
-macOS / Linux:
-
-```json
-{
-  "mcpServers": {
-    "ai-app-bridge": {
-      "command": "ai-app-bridge-mcp"
-    }
-  }
-}
-```
-
-Windows:
-
-```json
-{
-  "mcpServers": {
-    "ai-app-bridge": {
-      "command": "cmd",
-      "args": ["/c", "ai-app-bridge-mcp"]
-    }
-  }
-}
-```
+## 版本差异
 
-配置后重启或刷新 MCP session，再调用 `capabilities` 确认连接。
+当前候选版移除了 batch、样例专用启动/smoke 命令、旧 MCP 工具别名和外层重复参数。连续步骤写成 Script，Flutter 普通启动用 launch-app。运行版本不支持新合同时，明确报告版本差异；以实际发现的能力继续任务，不能把旧证据描述为本轮验证。