@mobileaidev/ai-app-bridge 0.2.11 → 0.2.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/package.json +1 -1
  2. package/skills/ai-app-bridge-use/SKILL.md +73 -3
  3. package/skills/ai-app-bridge-use/agents/openai.yaml +2 -2
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mobileaidev/ai-app-bridge",
3
- "version": "0.2.11",
3
+ "version": "0.2.12",
4
4
  "description": "Desktop CLI and MCP server for AI App Bridge.",
5
5
  "repository": {
6
6
  "type": "git",
package/skills/ai-app-bridge-use/SKILL.md CHANGED
@@ -1,15 +1,15 @@
1
1
  ---
2
2
  name: ai-app-bridge-use
3
- 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 稳定动态画面时触发。
3
+ description: 使用 AI App Bridge MCP 观察、操作、验证和调试 Android、iOS、Flutter 或 Web 应用。Codex 需要检查移动端 UI、Web DOM、截图、Android View/UIAutomator tree、iOS UIKit/WDA tree、点击/输入/等待/滑动、安装/启动/清数据、Flutter widget 与 action、WebView/WKWebView/H5 DOM 或 CDP 网络/控制台、Web Bridge session/DOM/command、日志/网络/状态/事件、权限/appops、smoke 测试，或按需使用 freeze/thaw 稳定动态画面时触发。
4
4
  ---
5
5
 
6
6
  # AI App Bridge Use
7
7
 
8
8
  ## Agent 快速流程
9
9
 
10
- 1. 确认目标 app：Android 使用 `packageName`，iOS 使用 `bundleId`，真机多设备场景传 `deviceId`/UDID；没有目标 id 时先从上下文、构建配置或前台 app 线索推断。面向具体 app 的命令必须传目标 id，只有无法发现 bridge 端口时才传 `port` 或 `runtimeUrl`。
10
+ 1. 确认目标：Android 使用 `packageName`，iOS 使用 `bundleId`，真机多设备场景传 `deviceId`/UDID；Web 使用 `sessionId`，多 target 时加 `targetId`。没有目标 id 时先从上下文、构建配置或前台 app/session 线索推断。面向具体 app/session 的命令必须传目标 id，只有无法发现 bridge 端口时才传 `port`、`runtimeUrl` 或先启动 Web session。
11
11
  2. 发现能力：默认 MCP surface 只有 `capabilities` 和 `run`。不确定命令或参数时先调用 `capabilities`，再用 `run` 执行。
12
- 3. 选择命令路径：按任务类型选 `core`、`app`、`action`、`flutter`、`webview`、`diagnostics` 或 `advanced` 域；不要先退回原始 `adb`。
12
+ 3. 选择命令路径：按任务类型选 `core`、`app`、`action`、`flutter`、`webview`、`ios`、`web`、`diagnostics` 或 `advanced` 域；不要先退回原始 `adb`、浏览器脚本或坐标猜测。
13
13
  4. 用 `batch` 串联相关步骤：观察、操作、等待、截图、tree 验证尽量放进一次 MCP 调用。
14
14
  5. 验证可见结果：界面变化必须用 `screenshot` 加 `tree`/`uia-tree` 交叉确认。
15
15
  6. 只在需要稳定动态画面时使用 `freeze-app`/`thaw-app`；如果本轮冻结过 app，最终回复前必须解冻。
@@ -58,6 +58,9 @@ description: 使用 AI App Bridge MCP 观察、操作、验证和调试 Android
58
58
  | iOS 设备/环境检查 | `ios-devices`、`ios-doctor`、`ios-setup` |
59
59
  | iOS App 内证据 | `ios-status`、`ios-tree`、`ios-logs`、`ios-network`、`ios-state`、`ios-events`、`ios-h5-dom`、`ios-h5-eval` |
60
60
  | iOS 系统级 UI 与动作 | `ios-uia-tree`、`ios-tap`、`ios-input`、`ios-swipe`、`ios-screenshot` |
61
+ | Web Bridge session | `web-provider-status`、`web-session-start`、`web-connect-info`、`web-sessions` |
62
+ | Web DOM 和证据 | `web-status`、`web-dom`、`web-logs`、`web-network`、`web-state`、`web-events` |
63
+ | Web 页面动作 | `web-click`、`web-input`、`web-wait`、`web-scroll`、`web-command` |
61
64
  | 自检 | `smoke` |
62
65
  | 多步骤串行执行 | `batch` |
63
66
  | 动态画面稳定 | `freeze-app`、`thaw-app`，只按需使用 |
@@ -150,6 +153,53 @@ iOS 观察和操作：
150
153
  }
151
154
  ```
152
155
 
156
+ Web session 启动和连接：
157
+
158
+ ```json
159
+ {
160
+ "command": "web-session-start",
161
+ "arguments": {
162
+ "webPort": 18180,
163
+ "token": "session-token"
164
+ }
165
+ }
166
+ ```
167
+
168
+ 页面调试入口使用 Web SDK 连接：
169
+
170
+ ```js
171
+ import { createAiAppBridge } from "@mobileaidev/ai-app-bridge-web";
172
+
173
+ const bridge = createAiAppBridge({
174
+ endpoint: "ws://127.0.0.1:18180/ai-app-bridge-web",
175
+ token: "session-token",
176
+ appName: "demo-web-app",
177
+ capture: { console: true, errors: true, fetch: true, xhr: true, dom: true }
178
+ });
179
+
180
+ bridge.start();
181
+ ```
182
+
183
+ Web 观察、操作和验证：
184
+
185
+ ```json
186
+ {
187
+ "command": "batch",
188
+ "arguments": {
189
+ "defaults": { "sessionId": "web-session-abc123" },
190
+ "steps": [
191
+ { "id": "status", "command": "web-status" },
192
+ { "id": "dom", "command": "web-dom", "arguments": { "refresh": true } },
193
+ { "id": "click", "command": "web-click", "arguments": { "selector": "button[type=submit]" } },
194
+ { "id": "wait", "command": "web-wait", "arguments": { "targetText": "Saved", "timeoutMs": 5000 } },
195
+ { "id": "events", "command": "web-events" }
196
+ ],
197
+ "stopOnError": true,
198
+ "includeRaw": true
199
+ }
200
+ }
201
+ ```
202
+
153
203
  ## 验证规则
154
204
 
155
205
  把 `screenshot` 当作当前可见画面的最高优先级证据，把 `tree`/`uia-tree` 当作可操作节点和结构证据。
@@ -175,6 +225,14 @@ iOS：
175
225
  - 文本输入优先用元素目标，例如 `ios-input` 搭配 `accessibilityId` 或 `elementId` 和 `clearFirst`；坐标输入仅用于没有稳定 accessibility id 的控件。
176
226
  - Flutter iOS 仍按 Flutter 路径读 widget/action 证据；设备级动作、权限弹窗和外部 UI 仍走 iOS WDA 命令。
177
227
 
228
+ Web：
229
+
230
+ - 独立 Web app 不用 Android `packageName`；先 `web-session-start` 启动桌面 WebSocket provider，再用 `web-connect-info` 读取 endpoint/token，让页面里的 `@mobileaidev/ai-app-bridge-web` SDK 连接。
231
+ - SDK 只放在 debug/test/client 代码里；SSR 框架必须只在浏览器端初始化，生产环境默认不要启用。
232
+ - 页面连接后先用 `web-sessions` 找 `sessionId`，再用 `web-status`、`web-dom`、`web-logs`、`web-network`、`web-state`、`web-events` 采集证据。
233
+ - 操作页面优先用 `web-command` 调注册过的白名单 action；需要 DOM 操作时用 `web-click`、`web-input`、`web-wait`、`web-scroll`，并传稳定 `selector` 或 `targetText`。
234
+ - 多页面、iframe 或自定义 surface 时传 `targetId`；如果返回 target ambiguous，先读取候选 target 再重试。
235
+
178
236
  Flutter：
179
237
 
180
238
  - 先尝试泛用 `tap-text`/`input-text`；失败、节点不可见或语义特殊时切到 `flutter-*`。
@@ -200,6 +258,8 @@ WebView/H5：
200
258
 
201
259
  `freeze-app`/`thaw-app` 是稳定动态画面的能力之一，不是默认动作节奏。只有冻结能让证据更可靠时才用。
202
260
 
261
+ `freeze-app`/`thaw-app` 只适用于移动 app runtime；Web Bridge 目标不要使用这两个命令。
262
+
203
263
  适合冻结：
204
264
 
205
265
  - 视频、动画、倒计时、实时刷新列表、游戏、播放页等会在思考期间变化的画面。
@@ -253,6 +313,10 @@ WebView/H5：
253
313
  - `packageName`/`port` 缺失：先补目标，不要让 MCP 回落到默认 sample。
254
314
  - iOS `bundleId`/`deviceId`/`wdaUrl` 缺失：先用 `ios-devices`/`ios-setup` 补齐；需要 full-control 时不要在没有 WDA 的情况下宣称完成。
255
315
  - iOS 设备锁屏、未信任、Developer Mode/DDI 不可用、WDA signing 失败、首次启动弹出授权/密码框：停下告诉用户需要操作，用户处理后再重试。
316
+ - Web `sessionId` 缺失：先跑 `web-session-start`、让页面 SDK 连接，再用 `web-sessions` 获取 session；不要把 Web 命令改成 Android `packageName`。
317
+ - Web provider 未运行或 endpoint/token 不匹配：用 `web-provider-status` 和 `web-connect-info` 重新确认连接信息，让页面刷新后重连。
318
+ - Web target ambiguous：读取 `web-sessions` 或 `web-dom` 返回的 target 候选，明确传 `targetId`。
319
+ - Web command 被拒绝：确认页面 SDK 是否注册了对应 action，或改用允许的 `web-click`/`web-input`/`web-scroll`；不要临时打开任意 `eval`。
256
320
  - `screenshot` 报前台 package 不匹配：先 `launch-app` 或确认当前前台，再继续判断。
257
321
  - `tree` 为空但截图正常：尝试 `uia-tree`、等待一轮或使用 Flutter/WebView 专用命令。
258
322
  - WebView CDP 不可用：确认 app debuggable、WebView debugging、目标 page；不能用 CDP 时退回 `h5-*` 或可见 UI 验证。
@@ -268,6 +332,12 @@ WebView/H5：
268
332
  npm install -g @mobileaidev/ai-app-bridge
269
333
  ```
270
334
 
335
+ Web 页面需要额外在目标项目中安装调试 SDK：
336
+
337
+ ```bash
338
+ npm install --save-dev @mobileaidev/ai-app-bridge-web
339
+ ```
340
+
271
341
  macOS / Linux:
272
342
 
273
343
  ```json
package/skills/ai-app-bridge-use/agents/openai.yaml CHANGED
@@ -1,4 +1,4 @@
1
1
  interface:
2
2
  display_name: "AI App Bridge Use"
3
- short_description: "观察、操作并验证 Android/iOS/Flutter app。"
4
- default_prompt: "使用 $ai-app-bridge-use 观察、操作和验证目标 Android/iOS/Flutter app；先发现能力，Android 传 packageName，iOS 传 bundleId/deviceId 并在 full-control 时使用 WDA，只有动态画面需要稳定证据时才使用 freeze/thaw。"
3
+ short_description: "观察、操作并验证 Android/iOS/Flutter/Web app。"
4
+ default_prompt: "使用 $ai-app-bridge-use 观察、操作和验证目标 Android/iOS/Flutter/Web app；先发现能力，Android 传 packageName，iOS 传 bundleId/deviceId 并在 full-control 时使用 WDA，Web 先建立 sessionId，只有移动端动态画面需要稳定证据时才使用 freeze/thaw。"