@mobileaidev/ai-app-bridge 0.2.9 → 0.2.11

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

@@ -1,13 +1,13 @@
 ---
 name: ai-app-bridge-use
-description: 使用 AI App Bridge MCP 观察、操作、验证和调试 Android 或 Flutter 应用。Codex 需要检查移动端 UI、截图、Android View/UIAutomator tree、点击/输入/等待/滑动、安装/启动/清数据、Flutter widget 与 action、WebView/H5 DOM 或 CDP 网络/控制台、日志/网络/状态/事件、权限/appops、smoke 测试，或按需使用 freeze/thaw 稳定动态画面时触发。
+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 稳定动态画面时触发。
 ---
 
 # AI App Bridge Use
 
 ## Agent 快速流程
 
-1. 确认目标 app：优先使用用户给出的 `packageName`；没有包名时先从上下文、构建配置或前台 app 线索推断。面向具体 app 的命令必须传 `packageName`，只有包名无法发现 bridge 端口时才传 `port`。
+1. 确认目标 app：Android 使用 `packageName`，iOS 使用 `bundleId`，真机多设备场景传 `deviceId`/UDID；没有目标 id 时先从上下文、构建配置或前台 app 线索推断。面向具体 app 的命令必须传目标 id，只有无法发现 bridge 端口时才传 `port` 或 `runtimeUrl`。
 2. 发现能力：默认 MCP surface 只有 `capabilities` 和 `run`。不确定命令或参数时先调用 `capabilities`，再用 `run` 执行。
 3. 选择命令路径：按任务类型选 `core`、`app`、`action`、`flutter`、`webview`、`diagnostics` 或 `advanced` 域；不要先退回原始 `adb`。
 4. 用 `batch` 串联相关步骤：观察、操作、等待、截图、tree 验证尽量放进一次 MCP 调用。
@@ -55,6 +55,9 @@ description: 使用 AI App Bridge MCP 观察、操作、验证和调试 Android
 | 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` |
 | 自检 | `smoke` |
 | 多步骤串行执行 | `batch` |
 | 动态画面稳定 | `freeze-app`、`thaw-app`，只按需使用 |
@@ -124,6 +127,29 @@ description: 使用 AI App Bridge MCP 观察、操作、验证和调试 Android
 }
 ```
 
+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
+  }
+}
+```
+
 ## 验证规则
 
 把 `screenshot` 当作当前可见画面的最高优先级证据，把 `tree`/`uia-tree` 当作可操作节点和结构证据。
@@ -141,6 +167,14 @@ description: 使用 AI App Bridge MCP 观察、操作、验证和调试 Android
 
 ## 平台专项
 
+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 命令。
+
 Flutter：
 
 - 先尝试泛用 `tap-text`/`input-text`；失败、节点不可见或语义特殊时切到 `flutter-*`。
@@ -217,6 +251,8 @@ WebView/H5：
 ## 失败处理
 
 - `packageName`/`port` 缺失：先补目标，不要让 MCP 回落到默认 sample。
+- iOS `bundleId`/`deviceId`/`wdaUrl` 缺失：先用 `ios-devices`/`ios-setup` 补齐；需要 full-control 时不要在没有 WDA 的情况下宣称完成。
+- iOS 设备锁屏、未信任、Developer Mode/DDI 不可用、WDA signing 失败、首次启动弹出授权/密码框：停下告诉用户需要操作，用户处理后再重试。
 - `screenshot` 报前台 package 不匹配：先 `launch-app` 或确认当前前台，再继续判断。
 - `tree` 为空但截图正常：尝试 `uia-tree`、等待一轮或使用 Flutter/WebView 专用命令。
 - WebView CDP 不可用：确认 app debuggable、WebView debugging、目标 page；不能用 CDP 时退回 `h5-*` 或可见 UI 验证。

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "AI App Bridge Use"
-  short_description: "观察、操作并验证 Android/Flutter app。"
-  default_prompt: "使用 $ai-app-bridge-use 观察、操作和验证目标 Android/Flutter app；先发现能力并传 packageName，只有动态画面需要稳定证据时才使用 freeze/thaw。"
+  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。"