@mobileaidev/ai-app-bridge 0.2.7 → 0.2.9

package/README.md

@@ -66,13 +66,15 @@ steps as skipped without mixing results from different commands:
 }
 ```
 
-For dynamic screens, MCP agents should follow the `ai-app-bridge-use` cadence:
-thaw immediately before reading app content or performing an app action, freeze
-immediately after evidence or action results are captured, keep the app frozen
-while reasoning/planning, and thaw once more before finishing the overall task.
-For visible state changes such as panels, dialogs, page transitions, tabs, or
-button-triggered content, verify with both `screenshot` and `tree`/`uia-tree`;
-do not conclude success from UI tree alone.
+For dynamic or transient screens, MCP agents can use `freeze-app`/`thaw-app` as
+an optional stabilization control: thaw before reads, actions, waits, or
+captures; freeze after evidence capture only when a changing UI would make
+reasoning unreliable; and thaw before the next app operation or before
+finishing so the app is not left frozen. Static screens and ordinary form
+flows usually do not need freezing.
+For visible state changes such as panels, dialogs, page transitions, tabs, or
+button-triggered content, verify with both `screenshot` and `tree`/`uia-tree`;
+do not conclude success from UI tree alone.
 
 WebView network and console capture use Android WebView DevTools/CDP when the
 target app is debuggable and WebView debugging is enabled.

package/bin/mcp-server.js

@@ -14,8 +14,8 @@ const serverInstructions = [
   'AI App Bridge observes and controls Android apps for agent workflows. Prefer these tools over raw adb when inspecting UI, text, WebView, logs, network, app install, data reset, launch, and permissions.',
   'Default surface is compact: call capabilities to discover domains, then call run with a command and arguments.',
   'Always pass packageName for app-specific commands, or pass an explicit port. Do not rely on a sample/default package in MCP sessions.',
-  'When freezing is available, keep the target app frozen while the model thinks or plans. Thaw only immediately before reading app content or performing an app action, freeze again as soon as that evidence/action result is captured, and thaw once more before finishing the overall task so the app is not left frozen.',
-].join(' ');
+  '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(' ');
 
 let buffer = Buffer.alloc(0);
 let responseFormat = null;
@@ -257,10 +257,10 @@ function fullToolDefinitions() {
       deltaY: { type: 'number', description: 'Window scroll delta Y when no selector/text is supplied.' },
     }),
     bridgeTool('logs', 'Read generic in-app log records.'),
-    bridgeTool('freeze_app', 'Stop the target app processes with SIGSTOP after app content is captured, preventing playback or animation from changing the observed evidence.', {
+    bridgeTool('freeze_app', 'Optionally stop target app processes with SIGSTOP when a dynamic or transient screen needs stable evidence for review.', {
       pid: { type: 'string', description: 'Optional explicit process id. Defaults to all processes named packageName or packageName:*.' },
     }, ['packageName']),
-    bridgeTool('thaw_app', 'Resume the target app processes with SIGCONT before reading app content or dispatching actions, so bridge endpoints can answer.', {
+    bridgeTool('thaw_app', 'Resume target app processes with SIGCONT before reads, waits, captures, or actions, and before finishing any task that used freeze-app.', {
       pid: { type: 'string', description: 'Optional explicit process id. Defaults to all processes named packageName or packageName:*.' },
     }, ['packageName']),
     bridgeTool('logcat', 'Read Android logcat through ADB with optional pid/tag/level/grep filters.', {
@@ -458,8 +458,8 @@ const commandDefinitions = [
   { command: 'logcat', domain: 'diagnostics', summary: 'Read Android logcat with optional app pid, tag, level, and grep filters.', options: ['serial', 'packageName', 'pid', 'appPid', 'tag', 'level', 'grep', 'lines', 'since', 'follow', 'durationSec', 'clear'] },
   { command: 'install-apk', domain: 'app', summary: 'Install an APK and assist device-side installer confirmation screens.', options: ['serial', 'packageName', 'apkPath', 'allowDowngrade', 'streaming', 'installTimeoutMs', 'installerTimeoutMs', 'intervalMs'] },
   { command: 'clear-app-data', domain: 'app', summary: 'Clear target app local data through the bridge runtime.', targetApp: true, options: ['serial', 'packageName'] },
-  { command: 'freeze-app', domain: 'app', summary: 'Stop target app processes with SIGSTOP after content capture to keep observed evidence stable.', targetApp: true, options: ['serial', 'packageName', 'pid'] },
-  { command: 'thaw-app', domain: 'app', summary: 'Resume target app processes with SIGCONT before content capture or actions so bridge data can be read.', targetApp: true, options: ['serial', 'packageName', 'pid'] },
+  { command: 'freeze-app', domain: 'app', summary: 'Optionally stop target app processes with SIGSTOP when dynamic UI needs stable evidence.', targetApp: true, options: ['serial', 'packageName', 'pid'] },
+  { command: 'thaw-app', domain: 'app', summary: 'Resume target app processes with SIGCONT before reads, waits, captures, actions, or final handoff.', targetApp: true, options: ['serial', 'packageName', 'pid'] },
   { command: 'launch-app', domain: 'app', summary: 'Launch the target package LAUNCHER Activity and report launcher candidates.', targetApp: true, options: ['serial', 'packageName', 'activity', 'component', 'action', 'category', 'data', 'extra'] },
   { command: 'launch-activity', domain: 'app', summary: 'Launch an explicit Android Activity component with optional string extras.', targetApp: true, options: ['serial', 'packageName', 'activity', 'component', 'action', 'category', 'data', 'extra'] },
   { command: 'launch-native-test', domain: 'app', summary: 'Launch the debug native bridge test Activity.', targetApp: true, options: ['serial', 'packageName'] },

package/package.json

@@ -1,35 +1,35 @@
-{
-  "name": "@mobileaidev/ai-app-bridge",
-  "version": "0.2.7",
-  "description": "Desktop CLI and MCP server for AI App Bridge.",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mobileAiDev/ai-app-bridge.git",
-    "directory": "desktop/ai-app-bridge-cli"
-  },
-  "homepage": "https://github.com/mobileAiDev/ai-app-bridge#readme",
-  "bugs": {
-    "url": "https://github.com/mobileAiDev/ai-app-bridge/issues"
-  },
-  "bin": {
-    "ai-app-bridge": "bin/ai-app-bridge.js",
-    "ai-app-bridge-mcp": "bin/mcp-server.js"
-  },
+{
+  "name": "@mobileaidev/ai-app-bridge",
+  "version": "0.2.9",
+  "description": "Desktop CLI and MCP server for AI App Bridge.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mobileAiDev/ai-app-bridge.git",
+    "directory": "desktop/ai-app-bridge-cli"
+  },
+  "homepage": "https://github.com/mobileAiDev/ai-app-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/mobileAiDev/ai-app-bridge/issues"
+  },
+  "bin": {
+    "ai-app-bridge": "bin/ai-app-bridge.js",
+    "ai-app-bridge-mcp": "bin/mcp-server.js"
+  },
   "files": [
     "bin/ai-app-bridge.js",
     "bin/mcp-server.js",
     "skills/ai-app-bridge-use",
     "README.md"
   ],
-  "scripts": {
-    "check": "node -c bin/ai-app-bridge.js && node -c bin/mcp-server.js && node --test",
-    "test": "node --test"
-  },
-  "license": "Apache-2.0",
-  "dependencies": {
-    "ws": "^8.18.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+  "scripts": {
+    "check": "node -c bin/ai-app-bridge.js && node -c bin/mcp-server.js && node --test",
+    "test": "node --test"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -1,183 +1,260 @@
----
-name: ai-app-bridge-use
-description: 使用 AI App Bridge MCP 观察、操作、验证 Android 或 Flutter 应用。Codex 需要读取 app UI 内容、截图、View tree、Flutter widget、WebView DOM、日志、网络请求、状态，或通过 ai-app-bridge-mcp 执行 Android app 操作时触发；必须在模型思考和规划下一步期间冻结 app，只在读取内容或执行操作前短暂解冻，并在全部任务结束前解冻 app。
----
-
-# AI App Bridge Use
-
-## MCP 安装
-
-使用前先确认 AI App Bridge MCP server 已安装并配置。如果当前会话里已经有 `ai-app-bridge` MCP 工具，直接进入“冻结节奏”。
-
-安装桌面 MCP 包：
-
-```bash
-npm install -g @mobileaidev/ai-app-bridge
-```
-
-把 MCP server 加到用户的 agent 配置里。
-
-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"]
-    }
-  }
-}
-```
-
-配置后重启或刷新 agent 的 MCP session。第一次使用时先调用 `capabilities`，确认 compact surface 里有 `run`、`freeze-app` 和 `thaw-app`。
-
-## 冻结节奏
-
-核心规则：**模型思考、分析证据、规划下一步期间，app 必须保持冻结；全部任务结束前，app 必须恢复解冻。**
-
-每一轮都按这个循环执行：
-
-1. 准备读取 app 内容或执行 app 操作前，调用 `thaw-app`。
-2. 立即执行需要 app 运行的 MCP 命令，例如读取 `tree`、截图、等待文本、点击、输入、滚动、抓取 WebView 网络等。
-3. 一旦拿到本轮需要的证据或动作结果，立即调用 `freeze-app`。
-4. 在 app 已冻结的状态下，再分析证据、判断是否成功、规划下一步。
-5. 下一轮真正要读内容或操作 app 时，再次 `thaw-app`。
-6. 当确认整个用户任务已经完成、准备给用户最终回复前，最后调用一次 `thaw-app`，不要把 app 留在冻结状态。
-
-换句话说，app 只在“采集证据/执行动作”的短窗口内运行；模型停下来思考时，app 应该已经被冻结；任务结束交还给用户前，app 应该已经解冻。
-
-## 状态变化校验
-
-对任何会改变可见界面的操作，例如打开/关闭面板、关闭弹窗、切换页面、点击 tab、进入详情页、展开抽屉、点击按钮后读取内容，不能只依赖 `uia-tree` 或 `tree` 判断成功。
-
-操作后必须同时采集：
-
-1. `screenshot`
-2. `uia-tree` 或 `tree`
-
-只有当截图中的可见画面与 UI tree 的关键节点一致时，才能认为操作成功。
-
-如果两者冲突：
-
-- 以截图作为当前真实可见界面的优先证据。
-- 将 UI tree 视为可能存在缓存、残留节点、不可见层或过期节点。
-- 重新点击、调整坐标、等待后再采集。
-- 不得基于冲突证据向用户报告结论。
-
-禁止仅凭 UI tree 中存在目标文本，就断言目标面板、弹窗、页面或 tab 已经打开；必须确认该文本在截图中对应的可见区域也存在，或截图中存在等价的可见状态标志。
-
-例如打开评论面板后，必须确认：
-
-- 截图中实际出现评论面板、评论标题或评论列表。
-- UI tree 中也出现 `评论` 标题、评论列表节点或评论输入栏。
-- 两者内容对应同一个界面。
-
-## 推荐批处理
-
-优先用 `batch` 把“解冻 -> 采集/操作 -> 冻结”放进同一个 MCP 调用，避免中间留下 app 继续播放或动画变化。
-
-读取当前屏幕：
-
-```json
-{
-  "command": "batch",
-  "arguments": {
-    "defaults": {
-      "packageName": "com.example.app"
-    },
-    "steps": [
-      { "id": "thaw", "command": "thaw-app" },
-      { "id": "tree", "command": "tree", "arguments": { "compact": true, "visibleOnly": true } },
-      { "id": "freeze", "command": "freeze-app" }
-    ],
-    "stopOnError": true,
-    "includeRaw": true
-  }
-}
-```
-
-执行点击并读取结果：
-
-```json
-{
-  "command": "batch",
-  "arguments": {
-    "defaults": {
-      "packageName": "com.example.app"
-    },
-    "steps": [
-      { "id": "thaw", "command": "thaw-app" },
-      { "id": "tap", "command": "tap-text", "arguments": { "targetText": "继续" } },
-      { "id": "screenshot-after", "command": "screenshot" },
-      { "id": "tree-after", "command": "tree", "arguments": { "compact": true, "visibleOnly": true } },
-      { "id": "freeze", "command": "freeze-app" }
-    ],
-    "stopOnError": true,
-    "includeRaw": true
-  }
-}
-```
-
-任务结束前恢复 app：
-
-```json
-{
-  "command": "thaw-app",
-  "packageName": "com.example.app"
-}
-```
-
-## 单步命令模式
-
-如果不能用 `batch`，也必须手动保持同样顺序：
-
-```json
-{ "command": "thaw-app", "packageName": "com.example.app" }
-```
-
-```json
-{ "command": "tree", "packageName": "com.example.app", "arguments": { "compact": true, "visibleOnly": true } }
-```
-
-```json
-{ "command": "freeze-app", "packageName": "com.example.app" }
-```
-
-之后再开始思考和规划下一步。全部任务完成后，再执行一次：
-
-```json
-{ "command": "thaw-app", "packageName": "com.example.app" }
-```
-
-## 什么时候不要提前冻结
-
-不要在一个需要 app 持续运行的 MCP 命令还没完成前冻结，例如：
-
-- `wait-text`
-- 点击、输入、滚动、启动 Activity
-- 带 `durationMs` 的 `webview-network` / `webview-console`
-- `logcat --follow`
-- 安装、授权、权限弹窗处理
-
-这些命令执行前先解冻，命令返回并拿到结果后立刻冻结，然后再思考。等全部任务完成并准备结束时，再解冻 app。
-
-## 失败处理
-
-如果 `freeze-app` 失败，继续用 MCP 完成观察和操作，但在结果里说明限制。常见原因包括：app 不是 debuggable、目标进程不存在、`run-as` 不可用、系统已经杀掉进程。
-
-如果 app 已经被冻结，而 MCP 读取内容超时或无法返回数据，先调用 `thaw-app`，再重试读取；不要在冻结状态下反复读取 bridge 数据。
-
-如果最终 `thaw-app` 失败，也要在给用户的最终回复里说明 app 可能仍处于冻结状态，以及失败原因。
+---
+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 稳定动态画面时触发。
+---
+
+# AI App Bridge Use
+
+## Agent 快速流程
+
+1. 确认目标 app：优先使用用户给出的 `packageName`；没有包名时先从上下文、构建配置或前台 app 线索推断。面向具体 app 的命令必须传 `packageName`，只有包名无法发现 bridge 端口时才传 `port`。
+2. 发现能力：默认 MCP surface 只有 `capabilities` 和 `run`。不确定命令或参数时先调用 `capabilities`，再用 `run` 执行。
+3. 选择命令路径：按任务类型选 `core`、`app`、`action`、`flutter`、`webview`、`diagnostics` 或 `advanced` 域；不要先退回原始 `adb`。
+4. 用 `batch` 串联相关步骤：观察、操作、等待、截图、tree 验证尽量放进一次 MCP 调用。
+5. 验证可见结果：界面变化必须用 `screenshot` 加 `tree`/`uia-tree` 交叉确认。
+6. 只在需要稳定动态画面时使用 `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` 过滤 |
+| 自检 | `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/"
+  }
+}
+```
+
+## 验证规则
+
+把 `screenshot` 当作当前可见画面的最高优先级证据，把 `tree`/`uia-tree` 当作可操作节点和结构证据。
+
+对打开/关闭面板、关闭弹窗、切换页面、点击 tab、进入详情页、展开抽屉、按钮触发内容变化等可见状态变化，必须同时采集截图和 tree。只有二者指向同一状态时，才报告成功。
+
+如果截图和 tree 冲突：
+
+- 以截图判断用户实际看到什么。
+- 认为 tree 可能包含缓存、不可见节点、过期层或非前台窗口。
+- 重新等待、采集或换用 `uia-tree`、坐标点击、Flutter/WebView 专用命令。
+- 不要把冲突证据包装成确定结论。
+
+异步 UI 用 `wait-text` 或 H5/Flutter wait 命令等待；不要用固定 sleep 代替状态判断。
+
+## 平台专项
+
+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` 是稳定动态画面的能力之一，不是默认动作节奏。只有冻结能让证据更可靠时才用。
+
+适合冻结：
+
+- 视频、动画、倒计时、实时刷新列表、游戏、播放页等会在思考期间变化的画面。
+- 点击后出现短暂状态，需要先固定再分析截图和节点。
+- 用户要求精确截图、坐标、像素或瞬时状态验证。
+
+不要冻结或不要提前冻结：
+
+- 静态页面的一次性观察、简单点击、普通表单输入。
+- `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。
+- `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
+```
+
+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` 确认连接。

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

@@ -1,4 +1,4 @@
-interface:
-  display_name: "AI App Bridge Use"
-  short_description: "使用 AI App Bridge MCP，在思考期间冻结 app，结束前解冻。"
-  default_prompt: "使用 AI App Bridge MCP 观察和操作 Android app。每轮读取内容或操作前先解冻，拿到证据后立刻冻结，再思考和规划下一步；全部任务结束前最后解冻 app。"
+interface:
+  display_name: "AI App Bridge Use"
+  short_description: "观察、操作并验证 Android/Flutter app。"
+  default_prompt: "使用 $ai-app-bridge-use 观察、操作和验证目标 Android/Flutter app；先发现能力并传 packageName，只有动态画面需要稳定证据时才使用 freeze/thaw。"