agent_admin/docs/agent/actions/open.md

OPEN [提案]

返回动作目录 · 任务协议 · Condition

OPEN 用于启动 App、把 App 带到前台或打开 URI。当前代码尚未实现。

1. 打开 App

{
  "id": "open-target",
  "action": "OPEN",
  "target": {
    "type": "APP",
    "packageName": "com.example.target"
  },
  "expectedPackageName": "com.example.target",
  "after": {
    "state": "PAGE_STABLE",
    "stableForMs": 300
  },
  "timeoutMs": 10000
}

APP 已经在前台时不重复启动，直接执行 after。否则通过 PackageManager 获取启动 Intent，并从 Service 上下文使用 FLAG_ACTIVITY_NEW_TASK。

2. 打开 URI

{
  "id": "open-link",
  "action": "OPEN",
  "target": {
    "type": "URI",
    "uri": "exampleapp://items/123",
    "handler": "PACKAGE",
    "packageName": "com.example.target"
  },
  "expectedPackageName": "com.example.target",
  "timeoutMs": 10000
}

handler 首批支持：

• PACKAGE：由指定包处理，推荐用于已知深链。
• DEFAULT：使用系统默认处理程序。

如果需要限制 URI 的 scheme、host 或来源页面，可以作为部署配置或任务字段增加，不作为首版通用动作的固定门禁。

3. 执行规则

1. 解析目标并确认 App 已安装或 URI 有处理程序。
2. 目标已经在前台时跳过 Intent 分发。
3. 最多分发一次 Intent。
4. 等待 expectedPackageName 成为前台。
5. 提供 after 时继续验证页面条件。

timeoutMs 覆盖解析、启动、等待前台和 after。Intent 返回成功不等于目标页面已经准备完成。

OPEN 不写入任何具体 App 的页面文案、深链或恢复流程；这些内容由任务或目标 App 适配层提供。

4. 结果码

• OPEN_ALREADY_FOREGROUND
• OPEN_SENT：目标包已进入前台，未声明 after。
• OK：目标包和 after 都满足。
• TARGET_NOT_INSTALLED
• NO_HANDLER
• ACTION_FAILED
• PACKAGE_MISMATCH
• VERIFICATION_FAILED

5. 测试

单元测试覆盖已在前台、冷启动、无处理程序、单次分发、目标包不符和 after 超时。任务栈恢复、后台启动限制和厂商系统差异需要真机验证。