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）

安装

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

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

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

1. 把本仓库放到任意目录
2. 在 $DSH_HOME/profiles/<profile>/node_modules/ 下建一个指向它的软链：

   ln -s /path/to/dsh-return-front "$DSH_HOME/profiles/web/node_modules/dsh-return-front"
   

3. 在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 末尾追加：

   - 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 里：

- 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）。

node tests/smoke.mjs

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

许可

MIT © zxyan99