dsh-return-front

Readme

# dsh-return-front

**真机控制任务结束后，自动把 DSH 切回前台。**

> 适用：**Android 上的 DSH**（Termux 系运行时 + Shizuku 特权通道）。
> 其他平台装上无害——插件会正常加载，但不会做任何事。

---

## 它解决什么问题

在 Android 上用 DSH 驱动真机（点按、开 App、滑动）时，**被操作的那个 App 会占据前台**，DSH 退到后台。于是每跑完一个任务，你都要手动切回 DSH 才能看结果、发下一句。

装上这个插件后：

| | 之前 | 之后 |
|---|---|---|
| 让 agent 在真机上点开某 App | 任务结束，**你手动切回 DSH** | 任务结束，**DSH 自己回到前台** |
| 纯只读任务（截图 / dump） | 前台没变 | **不触发**（本来就没变） |
| 虚拟屏任务 | 不影响真机前台 | **不触发** |

触发条件被刻意收窄，只在"本回合**真的动过真机前台**"且"你开着开关"时才动作。

## 前提条件

1. **DSH 跑在 Android 上**（Termux 系运行时，这决定了宿主 App 的包名可被自动探测）
2. **Shizuku 特权通道就绪**（插件通过它执行拉起命令）
3. **屏幕范围含真机**：`scope` 为 `all` 或 `real-only`
   - 出厂默认是 `virtual-only`。该模式下 agent 本来就动不了真机前台，**所以插件什么都不做**（这是对的，不是 bug）
4. 能执行特权 shell 的运行档位（如 `danger-full-access`）

## 安装

```sh
dsh plugin --profile web add github:zxyan99/dsh-return-front
```

装完**重启 DSH**，然后刷新页面。

手工安装（等价，适合本地源码）：

1. 把本仓库放到任意目录
2. 在 `$DSH_HOME/profiles/<profile>/node_modules/` 下建一个指向它的软链：
   ```sh
   ln -s /path/to/dsh-return-front "$DSH_HOME/profiles/web/node_modules/dsh-return-front"
   ```
3. 在 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 末尾追加：
   ```yaml
   - insert:
       - id: dsh-return-front
         name: dsh-return-front
   ```
4. 重启 DSH

> 装配顺序需**晚于** `@dsh-android/dsh-android-bridge`（因为要用它提供的特权服务）。放在 patch 末尾通常就满足。

## 使用

**设置 → 通用**，会看到一行：

> **任务收尾**
> ☑ 真机控制任务结束后回到 DSH

勾选/取消即时生效并持久化（存在 `$DSH_HOME/dsh-return-front.json`）。默认开启。

## 工作原理（简述）

- 订阅 `session/event`，在 `turn/start` 清空状态、在 `tool/call` 记录"本回合是否动过真机前台"、在 `turn/end` 决定是否动作
- **计入**的工具：`android_app_launch`、`android_ui_click`、`android_act_input`、`android_ui_scroll`、`android_ui_input`、`android_ui_global`
- **排除**：全部 `android_vdisplay_*`；全部只读类（`device_info`/`screen_list`/`ui_dump`/`ui_detail`/`ui_tree`/`screenshot`/`web_dump`）
- `screenId` 缺省或 `real` 才算真机；`virtual-N` 不计
- 动作就是一条拉起命令：`monkey -p <宿主包名> -c android.intent.category.LAUNCHER 1`
- 开关通过一条带鉴权的回环路由读写（`/api/dsh-return-front`）

**宿主包名是自动探测的**，取自 Termux 标准环境变量 `TERMUX_APP__DATA_DIR` 的目录名，因此不绑定某个特定的壳应用构建。

## 配置（可选）

在 profile 的 patch 里：

```yaml
- insert:
    - id: dsh-return-front
      name: dsh-return-front
      config:
        enabled: true           # 初始开关状态（之后以设置页/状态文件为准）
        appPackage: com.example.shell   # 手动指定宿主 App 包名（一般不需要）
        launchCommand: "monkey -p com.example.shell -c android.intent.category.LAUNCHER 1"
```

环境变量覆盖：`DSH_RETURN_FRONT_APP_PACKAGE`。

## 已知边界（诚实清单）

- **只在 Android 上有意义。** 非 Android 宿主上插件会加载但永不动作。
- **`scope=virtual-only` 时不工作**，且这是设计意图：该模式下 agent 动不了真机前台，切回没有意义。插件会静默跳过并写一行 debug 日志，不报错、不刷屏。
- **Shizuku 未运行 / 档位不足**时不报错，只吞掉失败（一行 debug 日志）。
- **只做"切回前台"这一件事**：不改前台内容、不清理、不重启引擎、不碰用户数据。
- 若本回合**动过真机但用户已主动切到别处**，回合结束时仍会被拉回 DSH——这是开关语义的一部分；不想要就关掉。

## 开发

无需构建链，纯手写 bundle（客户端用 `React.createElement` 避开 JSX）。

```sh
node tests/smoke.mjs
```

密闭测试（不接触设备）：覆盖宿主包名自动探测、路由鉴权、持久化、以及触发矩阵（只读不触发 / 真机触发 / 虚拟屏不触发 / 关开关不触发 / 重复 `turn/end` 只触发一次 / 特权通道抛错被吞）。

## 许可

MIT © zxyan99