# OPEN **[提案]**

> [返回动作目录](README.md) · [任务协议](../protocol.md) · [Condition](../flow-control.md#2-condition-提案)

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

## 1. 打开 App

~~~json
{
  "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

~~~json
{
  "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. 结果码

见[结果码总表](README.md#结果码总表)。OPEN 使用 `OK`、`PACKAGE_MISMATCH`、`ACTION_FAILED`（未安装、无处理程序或 Intent 分发失败）和 `VERIFICATION_FAILED`。

“已在前台”“已进入前台但未验证”属于成功的细节，放在 `detail` 而不是 `code`。未安装与无处理程序是否需要独立码，等实现时按排查需要决定。

## 5. 测试

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