@mobileaidev/ai-app-bridge 0.2.11 → 0.2.13

package/README.md

@@ -1,5 +1,23 @@
 # AI App Bridge CLI
 
+AI App Bridge CLI/MCP supports Android native apps, Android WebView/H5/CDP,
+Flutter apps on Android and iOS, iOS native apps via `AiAppBridgeIOS` plus
+WebDriverAgent/XCUITest, WKWebView, and desktop Web Bridge sessions.
+
+Command domains:
+
+- `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-state`, `hide-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-*` runtime evidence, WDA tree/tap/input/swipe, WKWebView, and Flutter iOS
+- `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`
+
+For MCP clients, the default surface is compact: call `capabilities` to discover
+domains, commands, and options, then call `run` with the selected command.
+
 ```bash
 npm install -g @mobileaidev/ai-app-bridge
 
@@ -19,9 +37,10 @@ ai-app-bridge ios-setup --device-id <device-or-udid> --bundle-id <ios.bundle.id>
 ai-app-bridge ios-status --device-id <device-or-udid> --bundle-id <ios.bundle.id>
 ai-app-bridge ios-tap --bundle-id <ios.bundle.id> --tap-x 120 --tap-y 360 --wda-url <wda-url-from-setup>
 ai-app-bridge ios-input --bundle-id <ios.bundle.id> --accessibility-id sample_text_field --clear-first --text "hello" --wda-url <wda-url-from-setup>
+ai-app-bridge-mcp # then run web-session-start / web-* commands through MCP
 ai-app-bridge thaw-app --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge freeze-app --package-name io.github.mobileaidev.aiappbridge.sample
-ai-app-bridge-mcp
+ai-app-bridge-mcp --help
 ```
 
 AI agents, model clients, automation frameworks, and IDE MCP clients reading
@@ -37,12 +56,13 @@ refresh the session.
 MCP defaults to a compact tool surface to avoid loading every command schema
 into the model context:
 
-- `capabilities` lists the bridge domains and command names.
+- `capabilities` lists supported targets, command domains, command names, and optional argument names.
 - `run` executes a selected command with command-specific arguments.
 
-This keeps install, data reset, launch, UI, Flutter, WebView, logcat, network,
-permission, iOS, and web capabilities discoverable without exposing dozens of full schemas
-at session start. Set `AI_APP_BRIDGE_MCP_SURFACE=full` before launching
+This keeps install, data reset, launch, UI action, Flutter, WebView/H5/CDP,
+iOS, Web Bridge, logcat, network, permission, smoke, batch, and port-forward
+capabilities discoverable without exposing dozens of full schemas at session start.
+Set `AI_APP_BRIDGE_MCP_SURFACE=full` before launching
 `ai-app-bridge-mcp` only when a client needs the legacy one-tool-per-command
 surface.
 

package/bin/ai-app-bridge.js

@@ -22,6 +22,15 @@ const defaults = {
 
 const helpText = `Usage: ai-app-bridge <command> [options]
 
+Supports:
+  Android native apps; Android WebView/H5/CDP; Flutter apps on Android and iOS;
+  iOS native apps via AiAppBridgeIOS + WebDriverAgent/XCUITest; WKWebView;
+  desktop Web Bridge sessions through ai-app-bridge-mcp.
+
+MCP discovery:
+  ai-app-bridge-mcp exposes a compact capability index by default.
+  Call capabilities, then run a command from core/app/action/flutter/webview/ios/web/diagnostics/advanced.
+
 Commands:
   status                 Read bridge status and app/device metadata.
   tree                   Read the Android View tree from the in-app bridge.
@@ -84,6 +93,23 @@ Flutter commands:
   flutter-h5-wait        Wait for Flutter H5 text or selector.
   flutter-h5-scroll      Scroll Flutter H5 content.
 
+Web Bridge MCP commands:
+  web-provider-status    Read desktop Web Bridge provider status.
+  web-session-start      Start the Web Bridge WebSocket session server.
+  web-connect-info       Read endpoint/token for browser SDK clients.
+  web-sessions           List connected Web Bridge SDK sessions.
+  web-status             Read Web Bridge session status.
+  web-dom                Read or refresh Web Bridge DOM snapshots.
+  web-logs               Read Web Bridge log records.
+  web-network            Read Web Bridge network records.
+  web-state              Read Web Bridge state records.
+  web-events             Read Web Bridge event records.
+  web-command            Run a whitelisted browser SDK command.
+  web-click              Click a DOM element through the browser SDK.
+  web-input              Set text in a DOM input through the browser SDK.
+  web-wait               Wait for text or selector through the browser SDK.
+  web-scroll             Scroll a Web Bridge DOM target.
+
 Device/action commands:
   tap                    Tap device coordinates through ADB.
   tap-text               Tap a visible node by exact text or content description.
@@ -4555,4 +4581,3 @@ module.exports = {
   waitTextConditionsMet,
   withFileLock,
 };
-

package/bin/mcp-server.js

@@ -12,12 +12,62 @@ const nodeBinary = process.env.AI_APP_BRIDGE_NODE || process.execPath;
 const supportedProtocolVersions = ['2025-06-18', '2024-11-05'];
 const defaultProtocolVersion = supportedProtocolVersions[0];
 const mcpSurface = (process.env.AI_APP_BRIDGE_MCP_SURFACE || 'compact').toLowerCase();
+const supportedTargets = [
+  'Android native apps',
+  'Android WebView/H5/CDP',
+  'Flutter apps on Android and iOS',
+  'iOS native apps via AiAppBridgeIOS + WebDriverAgent/XCUITest',
+  'WKWebView',
+  'desktop Web Bridge sessions',
+];
+const commandDomains = {
+  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-state, hide-keyboard',
+  flutter: 'flutter-tree, flutter-nodes, flutter-action, tap/input/scroll Flutter controls',
+  webview: 'h5-*, flutter-h5-*, webview-pages, webview-network, webview-console',
+  ios: 'ios-devices, ios-doctor, ios-setup, ios runtime evidence, ios-uia-tree/tap/input/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: 'logcat, smoke',
+  advanced: 'batch, forward, remove-forward',
+};
+const supportedTargetsText = `AI App Bridge supports ${supportedTargets.join('; ')}.`;
+const commandDomainsText = `Command domains: ${Object.entries(commandDomains).map(([domain, summary]) => `${domain}(${summary})`).join('; ')}.`;
+const discoveryText = 'Default MCP surface is compact: call capabilities to discover domains, commands, and options, then call run with the selected command and arguments.';
 const serverInstructions = [
-  'AI App Bridge observes and controls Android, iOS, Flutter, and Web targets for agent workflows. Prefer these tools over raw adb, devicectl, or browser-specific scripts when inspecting UI, text, WebView/WKWebView, logs, network, app install, launch, and permissions.',
-  'Default surface is compact: call capabilities to discover domains, then call run with a command and arguments.',
+  supportedTargetsText,
+  commandDomainsText,
+  discoveryText,
+  'Prefer AI App Bridge over raw adb, devicectl, or browser-specific scripts when inspecting UI, text, WebView/WKWebView, logs, network, app install, launch, permissions, or app-level Web evidence.',
   'Always pass packageName for Android app-specific commands, or pass an explicit port. For iOS, pass bundleId plus deviceId when more than one iPhone is connected.',
+  'For Web Bridge sessions, start the provider, connect the browser SDK, then pass sessionId and targetId when needed.',
   'Use freeze-app/thaw-app only as an optional stabilization control for dynamic or transient screens: thaw before reads/actions/captures, freeze after evidence capture only when it helps reasoning, and thaw before the next operation or before finishing so the app is not left frozen.',
 ].join(' ');
+const mcpHelpText = `Usage: ai-app-bridge-mcp [--help]
+
+${supportedTargetsText}
+
+${commandDomainsText}
+
+MCP surface:
+  compact (default)  exposes only capabilities and run.
+  full/legacy        exposes one tool per command; set AI_APP_BRIDGE_MCP_SURFACE=full.
+
+Discovery:
+  1. Call capabilities with optional domain or command filters.
+  2. Call run with a command name from capabilities.
+  3. Put command-specific options in arguments.
+
+Target ids:
+  Android app commands require packageName or explicit port.
+  iOS app commands use bundleId; add deviceId when multiple devices exist and wdaUrl for WDA actions.
+  Web Bridge commands use sessionId; add targetId for multi-target pages.
+
+Examples:
+  capabilities { "domain": "webview", "includeOptions": true }
+  run { "command": "screenshot", "packageName": "com.example.app" }
+  run { "command": "web-session-start", "arguments": { "webPort": 18180 } }
+`;
 const iosProvider = new IOSBridgeProvider();
 const webProvider = new WebBridgeProvider();
 
@@ -185,18 +235,20 @@ function toolDefinitions() {
 
 function compactToolDefinitions() {
   return [
-    bridgeTool('capabilities', 'List AI App Bridge capability domains and commands. Call this first when planning app automation; then use run to execute the selected command.', {
-      domain: { type: 'string', description: 'Optional domain filter such as core, app, action, flutter, webview, ios, web, or diagnostics.' },
-      command: { type: 'string', description: 'Optional command name for detailed arguments, such as install-apk, launch-app, tree, input-text, webview-network, ios-setup, or ios-tap.' },
+    bridgeTool('capabilities', `List AI App Bridge capability domains and commands across Android, iOS, Flutter, WebView/H5/CDP, and Web Bridge targets. ${commandDomainsText}`, {
+      domain: { type: 'string', description: 'Optional domain filter: core, app, action, flutter, webview, ios, web, diagnostics, or advanced.' },
+      command: { type: 'string', description: 'Optional command name for detailed arguments, such as install-apk, launch-app, tree, input-text, webview-network, ios-setup, ios-tap, web-session-start, or web-command.' },
       includeOptions: { type: 'boolean', description: 'Include per-command argument names. Defaults to false to keep output compact.' },
     }),
-    bridgeTool('run', 'Run an AI App Bridge command. Use capabilities first to choose the command. Pass packageName for Android app commands and bundleId for iOS app commands.', {
-      command: { type: 'string', description: 'Command name from capabilities, using CLI form such as status, install-apk, launch-app, input-text, webview-network, ios-doctor, ios-setup, ios-status, ios-tap, or web-status.' },
+    bridgeTool('run', 'Run an AI App Bridge command from capabilities. Pass packageName/port for Android app commands, bundleId/deviceId for iOS app commands, and sessionId/targetId for Web Bridge commands.', {
+      command: { type: 'string', description: 'Command name from capabilities, using CLI form such as status, install-apk, launch-app, input-text, webview-network, ios-doctor, ios-setup, ios-status, ios-tap, web-session-start, web-status, or web-command.' },
       packageName: { type: 'string', description: 'Target Android package for app-specific commands. Strongly recommended.' },
       serial: { type: 'string', description: 'ADB serial when multiple devices are connected.' },
       port: { type: 'number', description: 'Explicit bridge port when packageName discovery is not available.' },
       bundleId: { type: 'string', description: 'Target iOS app bundle identifier for ios-* commands.' },
       deviceId: { type: 'string', description: 'iOS devicectl identifier, UDID, serial number, or device name.' },
+      sessionId: { type: 'string', description: 'Target Web Bridge SDK session id for web-* commands.' },
+      targetId: { type: 'string', description: 'Optional Web Bridge target id for multi-target pages.' },
       iosHost: { type: 'string', description: 'iOS runtime host or CoreDevice tunnel IP.' },
       iosPort: { type: 'number', description: 'iOS runtime port when auto-discovery is unavailable.' },
       runtimeUrl: { type: 'string', description: 'Explicit iOS runtime base URL.' },
@@ -635,7 +687,9 @@ function capabilityPayload(args = {}) {
   return {
     ok: true,
     surface: mcpSurface === 'full' || mcpSurface === 'legacy' ? 'full' : 'compact',
-    usage: 'Use run with one of these command names. Prefer packageName for app-specific commands; install-apk, clear-app-data, launch-app, freeze/thaw, UI, WebView, logcat, network, and permission workflows are supported.',
+    supportedTargets,
+    commandDomains,
+    usage: `${supportedTargetsText} ${discoveryText} Use run with one of these command names. Prefer packageName for Android app commands, bundleId/deviceId for iOS, and sessionId/targetId for Web Bridge sessions.`,
     domains,
   };
 }
@@ -1225,12 +1279,19 @@ function writeLog(text) {
 }
 
 if (require.main === module) {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    process.stdout.write(`${mcpHelpText}\n`);
+    process.exit(0);
+  }
   startServer();
 }
 
 module.exports = {
   buildBridgeCliArgs,
+  commandDomains,
+  mcpHelpText,
   readNextMessage,
   runBatch,
   startServer,
+  supportedTargets,
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mobileaidev/ai-app-bridge",
-  "version": "0.2.11",
-  "description": "Desktop CLI and MCP server for AI App Bridge.",
+  "version": "0.2.13",
+  "description": "Desktop CLI and MCP server for AI App Bridge across Android, iOS, Flutter, WebView, and Web targets.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mobileAiDev/ai-app-bridge.git",

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

@@ -1,15 +1,33 @@
 ---
 name: ai-app-bridge-use
-description: 使用 AI App Bridge MCP 观察、操作、验证和调试 Android、iOS 或 Flutter 应用。Codex 需要检查移动端 UI、截图、Android View/UIAutomator tree、iOS UIKit/WDA tree、点击/输入/等待/滑动、安装/启动/清数据、Flutter widget 与 action、WebView/WKWebView/H5 DOM 或 CDP 网络/控制台、日志/网络/状态/事件、权限/appops、smoke 测试，或按需使用 freeze/thaw 稳定动态画面时触发。
+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。
 ---
 
 # 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. 确认目标 app：Android 使用 `packageName`，iOS 使用 `bundleId`，真机多设备场景传 `deviceId`/UDID；没有目标 id 时先从上下文、构建配置或前台 app 线索推断。面向具体 app 的命令必须传目标 id，只有无法发现 bridge 端口时才传 `port` 或 `runtimeUrl`。
+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`、`diagnostics` 或 `advanced` 域；不要先退回原始 `adb`。
+3. 选择命令路径：按任务类型选 `core`、`app`、`action`、`flutter`、`webview`、`ios`、`web`、`diagnostics` 或 `advanced` 域；不要先退回原始 `adb`、浏览器脚本或坐标猜测。
 4. 用 `batch` 串联相关步骤：观察、操作、等待、截图、tree 验证尽量放进一次 MCP 调用。
 5. 验证可见结果：界面变化必须用 `screenshot` 加 `tree`/`uia-tree` 交叉确认。
 6. 只在需要稳定动态画面时使用 `freeze-app`/`thaw-app`；如果本轮冻结过 app，最终回复前必须解冻。
@@ -58,6 +76,9 @@ description: 使用 AI App Bridge MCP 观察、操作、验证和调试 Android
 | 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`，只按需使用 |
@@ -150,6 +171,53 @@ iOS 观察和操作：
 }
 ```
 
+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` 当作可操作节点和结构证据。
@@ -175,6 +243,14 @@ iOS：
 - 文本输入优先用元素目标，例如 `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-*`。
@@ -200,6 +276,8 @@ WebView/H5：
 
 `freeze-app`/`thaw-app` 是稳定动态画面的能力之一，不是默认动作节奏。只有冻结能让证据更可靠时才用。
 
+`freeze-app`/`thaw-app` 只适用于移动 app runtime；Web Bridge 目标不要使用这两个命令。
+
 适合冻结：
 
 - 视频、动画、倒计时、实时刷新列表、游戏、播放页等会在思考期间变化的画面。
@@ -253,6 +331,10 @@ WebView/H5：
 - `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 验证。
@@ -268,6 +350,12 @@ WebView/H5：
 npm install -g @mobileaidev/ai-app-bridge
 ```
 
+Web 页面需要额外在目标项目中安装调试 SDK：
+
+```bash
+npm install --save-dev @mobileaidev/ai-app-bridge-web
+```
+
 macOS / Linux:
 
 ```json

package/skills/ai-app-bridge-use/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "AI App Bridge Use"
-  short_description: "观察、操作并验证 Android/iOS/Flutter app。"
-  default_prompt: "使用 $ai-app-bridge-use 观察、操作和验证目标 Android/iOS/Flutter app；先发现能力，Android 传 packageName，iOS 传 bundleId/deviceId 并在 full-control 时使用 WDA，只有动态画面需要稳定证据时才使用 freeze/thaw。"
+  short_description: "Android/iOS/Flutter/Web 全域观察、操作、验证能力索引。"
+  default_prompt: "使用 $ai-app-bridge-use 观察、操作和验证 Android native、Android WebView/H5/CDP、Flutter、iOS native/WKWebView/WDA/XCUITest 或桌面 Web Bridge；先用 capabilities 查 core/app/action/flutter/webview/ios/web/diagnostics/advanced，再用 run 执行。Android 传 packageName，iOS 传 bundleId/deviceId 并在 full-control 时使用 WDA，Web 先建立 sessionId，只有移动端动态画面需要稳定证据时才使用 freeze/thaw。"