前言¶
在 Android 上用 DeepSeek Harness（DSH）驱动真机——点按、启动 App、滑动界面——时，被操作的 App 会占据前台，DSH 退到后台。每跑完一个控制回合，往往要手动切回 DSH 才能看结果、继续对话。社区插件 dsh-return-front（维护者 zxyan99，分类：客户端）针对的就是这一环节：只在「本回合确实动过真机前台」且开关打开时，在回合结束时通过 Shizuku 特权通道把 DSH 宿主 App 拉回前台；只读任务（截图、UI dump 等）和虚拟屏任务不会触发。
下面介绍它的定位、安装方式、设置项，以及触发边界。
这是什么¶
dsh-return-front 是 DSH 的客户端侧插件，版本 0.1.0（MIT 许可）。一句话：真机控制任务结束后，自动把 DSH 切回前台。
适用环境在 README 中写得很明确：Android 上的 DSH（Termux 系运行时 + Shizuku 特权通道）。在其他平台装上插件会正常加载，但不会执行任何前台拉回动作。
| 场景 | 行为 |
|---|---|
| Agent 在真机上点开某 App 并完成控制回合 | 回合结束，DSH 自动回到前台（开关开启时） |
| 纯只读任务（截图 / dump 等） | 不触发 |
| 虚拟屏任务 | 不触发 |
触发条件被刻意收窄：只有本回合真的动过真机前台，且你在设置里开着开关，才会动作。
前提条件¶
使用前需同时满足 README 中的几条前提：
- DSH 跑在 Android 上（Termux 系运行时，便于自动探测宿主 App 包名）。
- Shizuku 特权通道就绪（插件通过它执行拉起命令）。
- 屏幕范围含真机：
scope为all或real-only。出厂默认virtual-only时 Agent 动不了真机前台，插件会静默跳过（设计如此，不是 bug）。 - 能执行特权 shell 的运行档位（例如
danger-full-access）。
安装与启用¶
官方安装命令如下（装完后需重启 DSH，并刷新页面）：
dsh plugin --profile web add github:zxyan99/dsh-return-front
若从本地源码手工装配，等价步骤为：把仓库放到任意目录；在 $DSH_HOME/profiles/<profile>/node_modules/ 下建立指向该目录的软链；在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 末尾追加插件条目；再重启 DSH。装配顺序需晚于 @dsh-android/dsh-android-bridge，放在 patch 末尾通常即可满足。
插件以当前 DSH 进程权限运行；安装前建议在 GitHub 查看源码与 MIT 许可证，确认符合你的环境策略。
典型用法¶
安装并重启后，打开 设置 → 通用，会出现一行：
任务收尾
☑ 真机控制任务结束后回到 DSH
勾选或取消会即时生效并持久化，状态保存在 $DSH_HOME/dsh-return-front.json，默认开启。
日常无需额外命令：Agent 在真机上完成会改变前台的工具调用后，回合结束即可能自动切回 DSH；若本回合只有只读或虚拟屏操作，界面行为与未装插件时一致。
工作原理与配置（可选）¶
插件订阅 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
宿主包名默认从 Termux 环境变量 TERMUX_APP__DATA_DIR 的目录名自动探测，不绑定某一固定壳应用构建。开关通过带鉴权的回环路由 /api/dsh-return-front 读写。
若需在 profile 的 patch 里设初始状态或覆盖包名，可使用（一般不必手动指定包名）：
- insert:
- id: dsh-return-front
name: dsh-return-front
config:
enabled: true
appPackage: com.example.shell
launchCommand: "monkey -p com.example.shell -c android.intent.category.LAUNCHER 1"
环境变量 DSH_RETURN_FRONT_APP_PACKAGE 也可覆盖宿主包名。
适用场景与注意¶
适合谁： 经常在 Android 真机上用 DSH 做 UI 自动化、点按与输入，且希望每回合结束后少一步手动切回 DSH 的开发者。
边界（README 中的诚实清单）：
- 非 Android 宿主上插件加载但不动作。
scope=virtual-only时不工作，且为设计意图；会写 debug 日志，不报错。- Shizuku 未运行或档位不足时失败被吞掉，仅 debug 日志。
- 只做「切回前台」：不改前台内容、不清理、不重启引擎、不碰用户数据。
- 若本回合动过真机但用户已主动切到别处，回合结束时仍可能被拉回 DSH；不需要该行为时关闭设置即可。
DSH 生态强调「一切皆插件」；社区目录 SkillHub 插件页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-return-front 把「真机控制回合结束 → 手动切回 DSH」收成一条可开关的自动化：触发面收窄到真机前台变更，避免只读和虚拟屏误触。需要时可从目录页或仓库查看更新与 Issue。
- 目录页：https://www.skillhub.cn/plugins/zxyan99/dsh-return-front
- GitHub：https://github.com/zxyan99/dsh-return-front
