# AI App Bridge Use

> AI App Bridge Use is an Agent Skill for apps & automation published in the mobileAiDev/ai-app-bridge repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

使用 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。

- Skill name: `ai-app-bridge-use`
- Category: [Apps & Automation](https://www.openparable.com/skill/apps-automation/1)
- Source: https://github.com/mobileAiDev/ai-app-bridge/blob/HEAD/desktop/ai-app-bridge-cli/skills/ai-app-bridge-use/SKILL.md
- Repository: mobileAiDev/ai-app-bridge (256 GitHub stars when collected)

## SKILL.md

# 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。

默认 MCP surface 只有 `capabilities` 和 `run`；先用 `capabilities` 查 domain、command 和 options，再用 `run` 执行。

目标标识：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
  }
}
```

## 验证规则

把 `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 命令。

Web：

- 独立 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 再重试。

Flutter：

- 先尝试泛用 `tap-text`/`input-text`；失败、节点不可见或语义特殊时切到 `flutter-*`。
- 用 `flutter-nodes` 找可操作节点，用 `scroll-flutter` 处理需要滚动后才出现的文本。

WebView/H5：

- DOM 操作优先用 `h5-*` 或 `flutter-h5-*`，避免靠坐标猜元素。
- CDP 网络/控制台用 `webview-network`/`webview-console`；目标 app 需要 debuggable，且 WebView debugging 可用。
- `webview-pages` 可先确认可 attach 的 page、socket、URL。

输入：

- 中文和 Unicode 输入优先用 `input-text` 或 `input-flutter-text`，不要用原始 `adb shell input text`。
- 下半屏点击前注意键盘遮挡；必要时先 `keyboard-state` 再 `hide-keyboard`。

权限和系统 UI：

- 运行时权限优先用 `permission-state`/`permission-grant`/`permission-revoke`。
- 必须处理系统弹窗时，用 `permission-dialog` 或 `uia-tree`/`tap-uia-text`。

## 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` 确认连接。

---

Source: https://www.openparable.com/skill/apps-automation/ai-app-bridge-use (OpenParable). Cite the canonical URL above.
