AI App Bridge Use

AI App Bridge Use

选择入口

• Intent：日常操作和未知流程，观察与 Agent 决策绑定；适合页面探索、系统窗口交互。
• Script：固定流程和重复运行，自由编写 JavaScript/Python（trusted-local-code），用 ctx.call 调用设备能力；权限声明不是 OS 沙箱。
• 单次命令：观察、单步动作、安装、权限夹具和诊断可独立调用，无须包装成完整流程。

共享调用合同

MCP 入口是 capabilities 和 run；capabilities 是独立工具，不是 run 的命令。命令参数全部放在 run.arguments，包括目标和 operation，使用当前命令名与 JSON 类型。默认 capabilities 或 domain 查询只取目录；domain 取值为 execution、evidence、core、app、action、flutter、webview、ios、web、diagnostics、advanced；android 是平台不是 domain，平台筛选只用于 Intent decide 的 platform。用 command 查合同，Intent/Script/evidence 加 operation 只取当前操作。Intent decide 可再加实际 platform、provider、action，例如 {"command":"intent","operation":"decide","platform":"android","provider":"native","action":"tap"}。CLI --help COMMAND 接受相同筛选；发现正文上限 96 KiB，宽查询超限时按提示用 command/operation 收窄，不反复读取整个 schema。

每次 run 顶层必填 extract：只需整个小结果时显式 null；树、网络、日志等大结果优先用 regex 或 JS/Python 提取需要的字段。业务参数仍在 arguments；extract/output 不传入设备命令。CLI 使用 --extract null 或 JSON 对象。

CLI 与 MCP 共用独立执行 Runtime、命令合同和 operationId。CLI 响应是一行紧凑 JSON，业务值在 value；MCP 工具正文同样是紧凑 JSON。Script 的调用返回值另见下文。客户端退出不会取消任务，用原 operationId 显式 cancel。取消不撤销已派发效果；版本错误会列出两侧身份，只在确定 Runtime 是待更新一侧时安排显式 stop。

旧 MCP 实例可能与已安装 CLI 不同。缺少 Intent/Script 或参数不匹配时，核对实际入口版本，选用支持当前合同的入口；不要套用旧 batch、工具别名或外层参数。

卡死 / 换 agent： Android 遇到 target_busy、device_ownership_unresolved 或旧动作一直没有终态时，按返回的 recoveryHint 调 device-ownership {operation:"force-stop",serial:"原设备"}；CLI 为 ai-app-bridge device-ownership --operation force-stop --serial 原设备 --extract null。这是独立重置入口：无需旧回执，强制结束旧 Host 及共享 Runtime 的任务，重置手机执行器并解除占用。共享这些 Host 的其他任务也会结束；已派发效果记为未知。读取 ownershipReleased/remoteResetPending；手机已重置后重新观察并开始新操作，手机断开时重连后再执行一次。

响应与提取

先看 execution 的原执行事实及 failureStage，再消费 value；Script 内部 ctx.call 仍按 ok/result 处理，不加 extract。control 保留续跑字段和采集覆盖；当前 Script 问题从 control.pendingQuestion 读取，即使 events 被游标过滤也可回答。

默认最终正文预算 96 KiB，可用 output.maxBytes 设为 16–256 KiB。提取失败或超预算不等于动作失败；存在 control.source.persisted:true 时，用 response 的 operation:read、原 ref 和新的 extract 重读，不重发原动作。未保存或留存已过期时没有可恢复的大结果，不捏造 ref。提取会减少交付内容，不承诺减少采集耗时。

提取脚本只使用 ctx.inputs = {kind, response, execution, control}，返回严格 JSON；没有 ctx.call。保留实际断言需要的来源身份、时间和状态，不能将选出的几条成功记录当作完整覆盖。完整示例见 docs/RESPONSE_EXTRACTION.md。

目标与动作

• Android：明确 serial 和 packageName。iOS：deviceId/bundleId；Native Intent 还需原 WDA Runner/session 绑定。Web：从当前连接取得 sessionId/runtimeEpoch/targetId。
• Intent/Script 的目标带 platform。执行目标保持明确指定的 App/provider；Android 前台匹配、不匹配、未知是独立观测事实，不代表动作成功或失败。更多绑定按平台合同补齐。
• selector、nodeRef、pageRef 和坐标来自当前观察。多重匹配、过期引用或 reobserve_required 需要重新观察。Android 前台 warning 由 agent 决定继续、观察或调整目标；无需 force。Intent 切 provider 通过 observe，切 Android App 显式传 observationTarget.packageName。
• 已派发但结果未知（ambiguous）时先观察，避免换 provider 或端点重放动作。保留原 error、message、dispatched 和操作状态。
• 若使用 freeze，后续操作和结束交付前先 thaw。

Intent

start 提供 goal、显式 target 和所需 provider；默认 supervised。 保留返回的 operationId，读取当前观察后以 decide 提交决策。 decision 包含唯一 decisionId、当前 basedOnRevision 和 agentDecision；act 的 action 遵循该观察的 provider 合同，控件动作使用唯一 selector。 需要刷新或切换 provider 时用 observe，随后使用新 revision。 complete/fail/inconclusive 也需要当前 revision，且不带 action；完成决策不能代替实际结果证据。 supervised 不会仅凭 goal 自动执行：没有决策时停在 waiting_for_decision 直到 timeoutMs。 status 显式给 limit（限制条数，不限制字节）；续读历史用上一页的 history.lastSequence 作为 afterSequence，不能用 Script 的 eventSequence。完整 start → decide → status → complete 范例见 COMMAND_CONTRACT.md Execution operation contracts。 安装与权限弹窗命令会返回受监督 Intent，须继续观察和决策；具体收尾条件见对应合同章节。