Skip to content

feat: 任务级虚拟屏幕执行(后台 VirtualDisplay,复用 Shizuku) - #593

Closed
wavezhang wants to merge 4 commits into
SuperMonster003:masterfrom
wavezhang:pr/virtual-screen
Closed

wavezhang wants to merge 4 commits into
SuperMonster003:masterfrom
wavezhang:pr/virtual-screen

Conversation

@wavezhang

@wavezhang wavezhang commented Nov 10, 2026 •

Copy link
Copy Markdown

概要

让一次自动化任务整体运行在一个后台虚拟显示屏上。这是任务级启动选项,不是新的脚本 API:已有 JS 脚本一行都不用改,只需要在运行入口选择「在虚拟屏运行」,截图、点击/滑动、按键、控件查找、应用启动与 applink 跳转都会自动指向该 display。

目的是让自动化不再占用物理屏、不再抢主屏焦点,也不会和用户操作互相干扰;虚拟屏随任务结束自动释放。实现机制参考 Mika(Apache-2.0):VirtualDisplay 由 Shizuku 的 shell-uid 常驻用户服务持有,而不是由 app 进程或一次性 execCommand 创建。

主要改动

层 内容
底座 core/virtualscreen/*:VirtualDisplayFlags(按 SDK 组合 @hide flags)、ShellVirtualDisplay / ShellCommandRunner、VirtualScreenManager / Session(ImageReader 截图与生命周期)、DisplayCoordinateMapper、VirtualScreenFramePump
Shizuku IUserService.aidl 新增事务 51–62(建屏/释放/列举/启动/点击/滑动/按键/文本/强停/applink/音频静音),UserService 的 shell 侧实现,WrappedShizuku 接口版本 +6 → +9
任务级路由 ExecutionConfig 新增 virtualScreenMode 等字段(含 Parcel 读写),ScriptIntents extra,Scripts.runOnVirtualScreen(),ScriptRuntime.initPrologue() 里 DisplayRoute.apply()
API 路由 SimpleActionAutomator、Images、App(含 openUrl 的 applink)、Shell 全部从 DisplayRoute 取当前 display,不再假定默认屏
控件查找 AccessibilityService.getWindowsOnAllDisplays() 展开 SparseArray,新增 DisplayWindowScope 按 displayId 限定并与 auto.setWindowFilter 取交集,AccessibilityBridge 全链路作用域化
UI 设置页全局开关、脚本菜单「在虚拟屏运行」、定时任务设置页三态(跟随/强制开/强制关,持久化到 DB v6)、侧边栏「工具」里的虚拟屏幕查看器(实时预览 + 手势/按键/文本/启动/保存 PNG/建屏/释放,exported=false)、主界面右下角悬浮实时小窗(无标题栏,画面顶部浮三枚透明图标按钮:静音/展开/最小化;无虚拟屏时自动隐藏)
其他 中英字符串、示例脚本、KSP/API surface baseline、静态引用白名单、10 类 JVM 单测(70 用例)、docs/virtual-screen/README.md

一个可选的显式模块 virtualscreen 也一并保留(手动建屏、指定尺寸等高级用法),但主推路径仍是任务级配置。

首页悬浮小窗(第 2 个提交)

主界面右下角有一个应用内悬浮预览,实时显示当前存活虚拟屏的画面;第 4 个提交后去掉了标题栏,改为三枚透明图标按钮浮在画面顶部,拖动画面可移动、可最小化成小浮标、点击打开完整查看器。它是加到 android.R.id.content 的普通 View,不需要 SYSTEM_ALERT_WINDOW 权限,只在 AutoJs6 界面内可见,设置页可关闭(默认开启)。

关键点是把帧源改成多订阅者:PreviewObserverRegistry 让完整查看器与小窗共用同一个 VirtualScreenFramePump(唯一的 ImageReader 消费者),第一个订阅者起泵、最后一个离开才停泵,因此打开/关闭任一界面都不会让另一个黑屏;脚本截图仍从帧泵的复用 Bitmap 复制。小窗自动跟随脚本/定时任务/查看器创建的屏,Activity 进入后台即停止订阅。

静音切换与无屏自动隐藏(第 3 个提交)

小窗顶部新增静音切换按钮(第 4 个提交起改为矢量图标),默认静音,设置页也可配置;按钮状态持久化,Activity 回到前台时把偏好同步给可能已重启的 shell 服务。

VirtualDisplay 不隔离音频,虚拟屏上的应用与物理屏共用 STREAM_MUSIC。因此 AudioMuteController(shell 侧) + AudioMuteState(纯 JVM、可单测)实现:第一块屏创建时记录当前媒体音量并置 0,用户取消静音或最后一块屏释放/服务销毁时写回原值;多块屏只记录一次;读不到当前音量时一律不改设备音量以免无法还原。AudioManager.setStreamVolume 需要 MODIFY_AUDIO_SETTINGS,部分 ROM 不授予 shell,故回退到 cmd media_session volume / media volume(在 system_server 内执行)。新增 AIDL 事务 62,接口版本递增到 +9。

另外把小窗可见性改为「开关开启 且 存在存活虚拟屏」:无屏时整个浮层连同三枚图标按钮与浮标一起隐藏,不再留空闲卡片;建屏后自动出现。卡片宽度 148dp → 176dp 以容纳三个按钮。

悬浮窗界面精简(第 4 个提交)

按界面反馈去掉标题栏:虚拟屏画面铺满整个卡片,静音 / 展开 / 最小化 三枚透明背景的矢量图标按钮直接叠在画面顶部右上角;其后仅有一层极淡渐变遮罩保证白色图标在亮色画面上可读(无文字、无实心条、不占布局高度)。

  • 拖动把手从标题移到画面本身:拖动画面移动小窗,轻点仍打开完整查看器(同一个 OnTouchListener 在 ACTION_UP 且未移动时调用 performClick())。
  • 原来的 displayId · 宽×高 · fps 状态文字改为画面的 contentDescription,界面上不再有可见标题;tv_title / title_bar 与四个文字符号字符串一并删除。
  • 静音状态改用「喇叭+叉」/「喇叭+声波」两个矢量图标区分(取消静音时染绿),不再依赖 静/响、M/♪ 文字符号。
  • 显隐逻辑收敛为直接切换根 View,applyCollapsed() 负责浮标,不再逐个 toggle 按钮。

启用方式

优先级从高到低:脚本菜单的单次运行选项 → 定时任务的三态配置 → project.json 的 useFeatures: ["virtualScreen"] → 设置页全局开关。外部启动可用 Intent extra virtual_screen_mode / virtual_screen_width / virtual_screen_height / virtual_screen_density / virtual_screen_display_id。

依赖与风险

  • 需要 Shizuku 已启动并授权、Android 12(API 31)及以上;可信屏标志位从 API 33 起、独立焦点从 API 34 起可用。
  • 使用了 DisplayManager.createVirtualDisplay 的 @hide flags、InputEvent.setDisplayId 和 WindowManagerGlobal 反射;不同 ROM / 未来 Android 版本可能行为不一致。shell 缺少 ADD_TRUSTED_DISPLAY 时会退化为非可信屏,与主屏共享焦点。
  • IntentTask(意图触发路径)尚未接入任务级配置;少数强制主屏的 Activity 可能无法落到虚拟屏;同一脚本一次只绑定一块屏。
  • 条件不满足时任务会明确报错,不会静默在物理屏上跑。
  • 静音作用于全局媒体音量(VirtualDisplay 不隔离音频):虚拟屏存活期间主屏上的音乐/视频也会被静音,最后一块屏释放后自动还原。若 ROM 同时拒绝 setStreamVolume 与 shell 回退命令,按钮会提示失败且不改动音量。

验证状态

  • :app:compileAppDebugKotlin、:app:assembleAppDebug 通过;与本次改动相关的 10 个测试类(虚拟屏标志位、坐标映射、窗口作用域、悬浮窗几何与可见性、多预览观察者、音频静音策略、模块顺序、API surface 门禁、静态引用白名单、Rhino 别名兼容)共 70 个用例全部通过。KSP/API surface baseline 与静态引用白名单均已同步更新(static_audit.py --guard --check 新增 0 行)。
  • 全量 :app:testAppDebugUnitTest 在本机另有 20 个与本次改动无关的既有基线失败:macOS 把 /var 规范化为 /private/var 导致的路径断言,以及中文 locale 下 Rhino 错误消息与英文断言不一致(ScriptRequireDifferentialTest / PromiseDifferentialTest 等),不涉及虚拟屏代码;Linux + 英文 locale 的 CI 上不会出现。
  • 任务级主链路(建屏、应用落到虚拟屏、截图、输入、释放、与主屏隔离)在一台 Android 17 / API 37 设备上验证通过。
  • 尚未在真机复验:查看器预览与手势、定时任务建屏、applink 落到虚拟屏、截图与预览并发、控件查找修复后的完整链路,以及悬浮小窗画面、拖动画面移动、三枚透明图标按钮的点击与最小化/展开、静音切换与音量还原、无屏自动隐藏与双订阅共存。合并前建议按 docs/virtual-screen/README.md 的清单补测。

备注

  • 基于 master 的 b95b98b,是纯功能改动,没有改动 applicationId、自定义权限、provider authority、快捷方式或任何发布/签名配置。
  • 兼容性上特意把虚拟屏字段放在 ExecutionConfig 的类体而非 data class 主构造,避免改变生成的 copy() 签名、破坏 com.stardust Rhino 别名对存量脚本的承诺(StardustClassAliasesTest 会守护这一点);新增的 VirtualScreenManager.sessions 也已登记静态引用白名单。
  • PR 体积较大(约 5250 行,含 UI 与文档)。如需拆分,建议顺序:① core/virtualscreen + AIDL/Shizuku 底座 → ② DisplayRoute 与运行时 API 路由 → ③ 控件查找作用域 → ④ 设置/定时任务/菜单 → ⑤ 查看器与示例。也可以先只合底座,后续再逐步接 UI。

设计细节、接口版本约定和已知限制都写在 docs/virtual-screen/README.md 里,欢迎按项目的架构习惯调整。

任务级启动选项,现有 JS 脚本零改动即可在虚拟屏运行:ScriptRuntime 通过
DisplayRoute 统一路由截图、点击/滑动/按键、控件查找、应用启动与 applink。

- 底座:VirtualDisplay 由 Shizuku shell-uid 常驻用户服务持有(参考 Mika),
  IUserService.aidl 新增事务 51-61,VirtualDisplayFlags 按 SDK 组合隐藏标志位
- 启用入口:设置页全局开关、脚本菜单单次运行、定时任务三态配置、project.json
  的 useFeatures: ["virtualScreen"],以及对应的 Intent extras
- 控件查找:getWindowsOnAllDisplays() + DisplayWindowScope 按 displayId 限定,
  与 auto.setWindowFilter 取交集
- 查看器:侧边栏「工具」入口,实时预览、手势/按键/文本/启动应用/保存 PNG、
  新建与释放屏幕,Activity 不导出
- 兼容性:虚拟屏字段不进入 ExecutionConfig 主构造,保持 com.stardust Rhino
  别名承诺的 copy() 签名;同步 KSP/API surface baseline 与静态引用白名单
- 文档与示例:docs/virtual-screen/README.md、两份 JS 示例、46 个定向单测用例
Add an in-app bottom-right floating window that shows the current virtual
display in real time (display id, size, FPS). It follows screens created by
scripts, timed tasks or the viewer, can be dragged, collapsed into a bubble,
and opens the full viewer on tap. No SYSTEM_ALERT_WINDOW permission is needed;
the Settings switch virtual_screen_floating_window is enabled by default.

Make the session frame pump multi-subscriber via PreviewObserverRegistry: the
viewer and the floating window share the single ImageReader consumer, so
opening or closing either surface no longer blacks out the other. Script
screenshots still copy the pump's reusable bitmap.

Also add FloatingWindowGeometry (JVM-tested aspect-ratio clamping),
observer-registry unit tests, the preference/strings resources, and README
updates.
…no display

Add a mute toggle to the floating preview toolbar (muted by default) and a
Settings switch; the choice is persisted and re-pushed to a restarted shell
service when the host Activity resumes.

A VirtualDisplay does not isolate audio: apps on it share STREAM_MUSIC with the
physical display. The shell side now captures the media volume on the first
display, zeros it, and restores the exact index when the user unmutes or the
last display is released / the service is destroyed. AudioMuteState is pure JVM
state with 14 unit tests; AudioManager.setStreamVolume falls back to
`cmd media_session volume` / `media volume` when the ROM denies the permission.
Reading the current volume failing means the device is left untouched, since
there would be nothing to restore.

AIDL transaction 62 (setMediaMuted), UserService implementation and
WrappedShizuku interface version +8 -> +9.

With no live virtual display the whole floating overlay AND its mute / open /
collapse buttons and bubble are hidden, instead of leaving an idle card; they
reappear automatically as soon as a screen is created. Card width 148dp ->
176dp to fit the third button.

Verified: :app:compileAppDebugKotlin, 10 targeted test classes / 70 cases
(0 failures), :app:assembleAppDebug, static_audit.py --guard --check (0 new
rows). Device-side audio behaviour is still pending a real-device check.
…icon controls

The home-screen mini preview no longer has a title bar. The virtual display
picture now fills the whole card and three transparent vector icon buttons
(mute / expand / minimize) float over its top edge, backed only by a very
light gradient scrim for readability on bright frames (no text, no solid bar,
no layout height).

* layout: remove title_bar + tv_title; add ic_vs_float_{mute,unmute,expand,minimize}
  and bg_vs_float_toolbar_scrim; the controls layer over the picture.
* drag handle moves from the title to the picture itself: the existing
  OnTouchListener still calls performClick() on ACTION_UP, so a tap opens the
  full viewer while a drag repositions the card.
* status text (displayId / size / FPS) moves to the picture's
  contentDescription instead of taking visible space.
* mute state switches between two vector icons (speaker+cross / speaker+waves)
  with a subtle tint, replacing the text symbols; delete the four now-unused
  symbol strings.
* visibility simplified to toggling the root view; applyCollapsed() owns the
  bubble, no per-button GONE/VISIBLE toggling.
* refresh en/zh setting summaries, button content descriptions and geometry
  comments; update docs/virtual-screen/README.md.

Verified: compileAppDebugKotlin, assembleAppDebug, 10 targeted test classes
(70 cases, 0 failures), static_audit.py --guard --check (0 new rows).
@SuperMonster003

Copy link
Copy Markdown
Owner

感谢你的投入, 可以看到在兼容性方面 (copy() 签名, AIDL 版本号, augment 基线与白名单) 等地方, 都处理得很细, README 也如实写明了风险与未验证的路径.

经过评估, 决定不把任务级虚拟屏执行整合到 AutoJs6 当中, 此 PR 会关闭. 原因并非代码质量问题 (反而代码质量非常可观):

  • AutoJs6 希望自动化对设备主人是可见的. 而这个功能让任务在用户看不到的屏幕上运行, 锁屏和熄屏后仍可继续, 没有常驻通知, 屏数没有上限. 它可以经全局开关, project.json, Intent extra 或脚本启用, 都不需要逐次确认, 打包应用里同样可用.
  • 这些特性合在一起, 适合项目一直刻意不支持的大规模无人值守用途, 与此前对 HID 注入, 打包加密等提议的取舍一致.
  • 它还依赖 shell 持有 ADD_TRUSTED_DISPLAY / ADD_ALWAYS_UNLOCKED_DISPLAY 以及多处隐藏接口, 长期维护的风险较高.

再次感谢, 欢迎以后在其他方向继续提 PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants