offscreen-android 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +195 -2
- package/assets/injector/Injector.smali +1179 -0
- package/assets/injector/README.md +101 -0
- package/assets/injector/inject.dex +0 -0
- package/assets/overlay/ai-overlay.apk +0 -0
- package/assets/scrcpy-server.jar +0 -0
- package/bin/aim.mjs +220 -0
- package/bin/asr.mjs +81 -0
- package/bin/audcap.mjs +128 -0
- package/bin/mcp-server.mjs +410 -0
- package/bin/vdisplay.mjs +305 -0
- package/bin/vdisplayd.mjs +398 -0
- package/bin/vidcap.mjs +82 -0
- package/bin/vidgrab.mjs +172 -0
- package/package.json +55 -4
- package/src/framesrv.js +348 -0
- package/src/human.js +302 -0
- package/src/index.js +161 -0
- package/src/inject.js +415 -0
- package/src/lease.js +314 -0
- package/src/occupancy.js +214 -0
- package/src/ocr.js +209 -0
- package/src/ocr_helper.py +125 -0
- package/src/pool.js +195 -0
- package/src/sampling.js +163 -0
- package/src/stream.js +571 -0
- package/src/target.js +29 -0
- package/src/timeline.js +324 -0
- package/src/tool-spec.js +873 -0
- package/src/tools.js +2034 -0
- package/src/vd.js +2354 -0
- package/src/video.js +751 -0
- package/src/vision.js +193 -0
- package/src/vision_helper.py +334 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 JMINNO
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,196 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dsh-go-plugin-screen
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
在手机上开一块**用户看不见的虚拟屏**,把 App 跑上去,Agent 可以截图、点击、输入,全程不打断用户。
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
dsh plugin --profile web add dsh-go-plugin-screen
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## 为什么不是镜像一块屏
|
|
10
|
+
|
|
11
|
+
Android 上「造虚拟屏」有两条路,差别是生死攸关的:
|
|
12
|
+
|
|
13
|
+
| 做法 | 用户主屏上会怎样 |
|
|
14
|
+
|---|---|
|
|
15
|
+
| `settings put global overlay_display_devices` | 画一块半透明浮窗压在屏幕上、**吃触摸**、**抢输入法**、SurfaceFlinger 43.7%→68~80%、约 5.5W |
|
|
16
|
+
| `scrcpy-server` 的 `new_display`(本插件用的) | **完全不显示**。标志位 `FLAG_OWN_CONTENT_ONLY`(内容不跟主屏同步)+ `FLAG_OWN_FOCUS`(不抢主屏焦点)+ 没有 `FLAG_PUBLIC` |
|
|
17
|
+
|
|
18
|
+
实测:虚拟屏上跑着计算器,主屏仍在放视频,输入法焦点留在主屏(`mDisplayIdToShowIme=0`),主屏截图里没有任何浮窗。
|
|
19
|
+
|
|
20
|
+
代价:多占约 0.28 个核(基线 0.52 → 0.80 秒/秒),比 overlay 那条路便宜一个数量级。
|
|
21
|
+
|
|
22
|
+
## 前提
|
|
23
|
+
|
|
24
|
+
需要 `com.android.shell` 拥有 `ADD_TRUSTED_DISPLAY` 权限。一部分机型有(这台 nubia 有),Pixel 和部分 Android 15 没有(见 scrcpy issue #5523)。插件启动时会先检查,没有就明确报错,不会硬撑。
|
|
25
|
+
|
|
26
|
+
## 命令行版本(给任何 agent 用,不限于 DSH)
|
|
27
|
+
|
|
28
|
+
同一个包也带 CLI,**不需要装 DSH**。Claude Code、opencode、Codex、Cursor 只要能跑 bash 就能用。
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
vdisplay start # 建一块看不见的屏
|
|
32
|
+
vdisplay launch com.tencent.mm # 把微信投上去
|
|
33
|
+
vdisplay shot --out /tmp/wx.jpg # 截图
|
|
34
|
+
vdisplay input tap --nx 0.5 --ny 0.9 # 归一化坐标点击
|
|
35
|
+
vdisplay status
|
|
36
|
+
vdisplay stop
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
完整命令:
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
vdisplay start [--width 720] [--height 1280] [--dpi 320]
|
|
43
|
+
[--orientation landscape|portrait] [--hwc auto|on|off]
|
|
44
|
+
vdisplay stop [--forceStopApps]
|
|
45
|
+
vdisplay status
|
|
46
|
+
vdisplay launch <包名> [Activity]
|
|
47
|
+
vdisplay shot [--out 路径] [--width 540] [--format jpeg|png]
|
|
48
|
+
vdisplay main-shot [--out 路径]
|
|
49
|
+
vdisplay input tap --x 100 --y 200 或 --nx 0.5 --ny 0.5
|
|
50
|
+
vdisplay input swipe --x1 100 --y1 200 --x2 300 --y2 400 [--ms 400]
|
|
51
|
+
vdisplay input text --text "要输入的字"
|
|
52
|
+
vdisplay input key --key KEYCODE_BACK
|
|
53
|
+
vdisplay input paste [--text "要粘的内容"]
|
|
54
|
+
vdisplay daemon stop
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
加 `--json` 输出机器可读的完整结果。
|
|
58
|
+
|
|
59
|
+
### 为什么需要一个守护进程
|
|
60
|
+
|
|
61
|
+
虚拟屏跟"建它的那个进程"同生共死。CLI 每次调用都是新进程,退出就把屏带走了 —— 所以 `vdisplay shot` 这种一次性命令没法直接工作。
|
|
62
|
+
|
|
63
|
+
做法是常驻一个 `vdisplayd`,把屏握在手里,CLI 通过回环 HTTP 把命令发进去:
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
vdisplay(CLI)──HTTP──> vdisplayd(常驻,持有虚拟屏)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
**CLI 会自动拉起守护进程**,你不用管。它闲置 10 分钟且没有虚拟屏时会自己退出,不留垃圾进程。
|
|
70
|
+
|
|
71
|
+
状态文件在 `$DSH_HOME/plugin-screen/cli-daemon.json`,里面是 `{pid, port}`。
|
|
72
|
+
|
|
73
|
+
查看守护进程:`vdisplay daemon`;让它退出:`vdisplay daemon stop`。
|
|
74
|
+
|
|
75
|
+
## 八个工具
|
|
76
|
+
|
|
77
|
+
| 工具 | 作用 |
|
|
78
|
+
|---|---|
|
|
79
|
+
| `screen_modes` | 列出四种操作方式(shell / browser / vdisplay / watch)和各自代价 |
|
|
80
|
+
| `vdisplay_start` | 建私有虚拟屏,返回 displayId 与能力标志。支持 `orientation: 'landscape'/'portrait'` 自动调整宽高 |
|
|
81
|
+
| `vdisplay_launch` | 把 App 投到虚拟屏(先 force-stop,避免把主屏的旧任务拉前台) |
|
|
82
|
+
| `vdisplay_input` | 往虚拟屏定向注入 tap / swipe / text / key / **paste** |
|
|
83
|
+
| `vdisplay_shot` | 截虚拟屏,返回本地路径,可直接当图片读 |
|
|
84
|
+
| `screen_shot_main` | 截主屏(只读),用来核对有没有影响用户 |
|
|
85
|
+
| `vdisplay_status` | 屏状态、上面跑着什么、主屏焦点是什么 |
|
|
86
|
+
| `vdisplay_stop` | 销毁 |
|
|
87
|
+
|
|
88
|
+
## 按任务选方式
|
|
89
|
+
|
|
90
|
+
1. 能用 `adb shell` 办的(装包、看日志、改设置)→ 不开屏,零打扰
|
|
91
|
+
2. 网页交互 → `dsh-go-plugin-web` 的 CDP,不点屏幕
|
|
92
|
+
3. 必须"看界面再点"的 App → `vdisplay_*`
|
|
93
|
+
4. 用户想看你干了什么 → `vdisplay_shot` 截图发上来
|
|
94
|
+
|
|
95
|
+
## 横屏/竖屏支持
|
|
96
|
+
|
|
97
|
+
`vdisplay_start` 支持 `orientation` 参数:
|
|
98
|
+
|
|
99
|
+
```javascript
|
|
100
|
+
// 横屏(确保宽 > 高)
|
|
101
|
+
await vdisplay_start({ orientation: 'landscape' }); // → 1280x720
|
|
102
|
+
|
|
103
|
+
// 竖屏(确保高 > 宽)
|
|
104
|
+
await vdisplay_start({ orientation: 'portrait' }); // → 720x1280
|
|
105
|
+
|
|
106
|
+
// 自定义尺寸
|
|
107
|
+
await vdisplay_start({ width: 1920, height: 1080 }); // 直接指定
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**实测**:Minecraft PE 在横屏虚拟屏(1280x720)上正常渲染;虚拟屏带有 `FLAG_ROTATES_WITH_CONTENT` 标志,App 强制某个方向时虚拟屏会自动旋转匹配。
|
|
111
|
+
|
|
112
|
+
## 五个实测坑(都写进代码里了)
|
|
113
|
+
|
|
114
|
+
1. **socket 名有下划线**:`scrcpy_<scid>`。写成 `scrcpy<scid>` 会连不上,server 卡在 accept 不建屏。
|
|
115
|
+
2. **scid 必须在有符号 32 位内**:scrcpy 用 `Integer.parseInt(radix 16)` 解析,随机取 `0xffffffff` 会得到 `cd7bccd6` 这种超范围值,server 直接 `NumberFormatException` 退出。
|
|
116
|
+
3. **jar 会自杀**:scrcpy-server 启动后 `unlinkSelf` 删自己的 jar,所以要放在 `chmod 555` 的目录里,日志也要写到别处。
|
|
117
|
+
4. **客户端一断屏就消失**:必须常驻两个哑客户端(video + control)。
|
|
118
|
+
5. **`screencap -d` 要 SurfaceFlinger 的 64 位 id**,不是逻辑 displayId;传错会报 `Display Id 'NN' is not valid`,不带 `-d` 就截到主屏,看起来像"这块屏在镜像主屏"。
|
|
119
|
+
|
|
120
|
+
## 判据:这块屏到底能不能托管 App
|
|
121
|
+
|
|
122
|
+
看 `dumpsys display` 里 **`DisplayDeviceInfo`** 那一行:
|
|
123
|
+
|
|
124
|
+
```
|
|
125
|
+
FLAG_OWN_CONTENT_ONLY + FLAG_OWN_FOCUS → 能托管,内容独立
|
|
126
|
+
缺 OWN_CONTENT_ONLY → 内容跟主屏(镜像)
|
|
127
|
+
缺 OWN_FOCUS → 窗口拿不到焦点
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
`mBaseDisplayInfo` / `mOverrideDisplayInfo` 那两段**永远**不带这两个标志,别拿它判断(我踩过,误判成"不能托管")。
|
|
131
|
+
|
|
132
|
+
`canHostTasks` 也不能当判据——实测能正常投 App 的屏,它在 `mBaseDisplayInfo` 里是 `false`。
|
|
133
|
+
|
|
134
|
+
## 主屏保护
|
|
135
|
+
|
|
136
|
+
`vdisplay_launch` 做三件事:
|
|
137
|
+
|
|
138
|
+
1. 投屏前 `am force-stop` 目标 App(否则它如果在主屏后台跑着,`am start --display` 只会把旧任务拉到前台,直接顶掉用户正在看的东西)
|
|
139
|
+
2. 投完校验主屏焦点没变
|
|
140
|
+
3. **只报告,不自动还原** —— 会告诉主屏焦点变没变,但不会主动去改你的主屏。
|
|
141
|
+
自动还原试过,在「用户自己切了 App」时会误判,反而去动用户的主屏,所以去掉了。
|
|
142
|
+
|
|
143
|
+
第 2 步的判据只能读 **display 0 的 `mCurrentFocus`**:`dumpsys activity activities | grep topResumedActivity` 是全局的,虚拟屏上的 Activity 也会算进来,会误判。
|
|
144
|
+
|
|
145
|
+
## 已知限制
|
|
146
|
+
|
|
147
|
+
### 3D 游戏:开了 HWC 就能跑,不开会黑屏
|
|
148
|
+
|
|
149
|
+
**能跑,前提是让硬件合成器(HWC)参与虚拟屏合成。**
|
|
150
|
+
|
|
151
|
+
实测 REDMAGIC NX809J(Adreno 8 Gen 3 / Android 16):
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
厂商声明 vendor.display.vds_allow_hwc = 1 ← 硬件支持
|
|
155
|
+
系统默认 debug.sf.enable_hwc_vds = 0 ← 但出厂是关的
|
|
156
|
+
置 1 之后 王者荣耀在虚拟屏正常渲染(启动页非黑屏,3D 场景初始化成功)
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
所以插件现在会自动处理(`vdisplay_start` 的 `hwc` 参数,默认 `"auto"`):
|
|
160
|
+
检测到 `vds_allow_hwc=1` 就打开 `debug.sf.enable_hwc_vds`,`vdisplay_stop` 时恢复原值。
|
|
161
|
+
|
|
162
|
+
**没有 HWC 支持的设备仍然会黑屏。** 未开启时的实测记录(Minecraft,`com.mojang.minecraftpe`):
|
|
163
|
+
|
|
164
|
+
```
|
|
165
|
+
vdisplay_start → vdisplay_launch:都报成功,landedOnVd=true
|
|
166
|
+
进程存活,logcat 显示 LICENSED、app-foreground 正常
|
|
167
|
+
但 vdisplay_shot 截出来是全黑,48 秒内画面只变化 1 次
|
|
168
|
+
多次测试:8–15 秒间进程退出,不稳定
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
同一个游戏在真屏上:41 FPS、正常渲染 3D 画面。
|
|
172
|
+
|
|
173
|
+
> 早期版本把这条写成"虚拟屏跑不了 3D 游戏",那是**只测了默认配置**得出的结论,已修正。
|
|
174
|
+
|
|
175
|
+
**HWC 的作用**:虚拟屏默认走 GPU 软件合成,SurfaceView 拿不到硬件叠加层,画面写不进去。
|
|
176
|
+
HWC 参与后,硬件直接合成到虚拟屏的 buffer,3D 内容就能出图。
|
|
177
|
+
|
|
178
|
+
**怎么判断自己的机器行不行**:
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
adb shell getprop vendor.display.vds_allow_hwc
|
|
182
|
+
# 1 = 硬件支持,插件会自动开启
|
|
183
|
+
# 0 或空 = 不支持,3D 游戏仍然黑屏
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
**轻量 App 从来不受影响**(微信、小红书、设置、浏览器、文档类都实测正常)。
|
|
187
|
+
|
|
188
|
+
**风险提示**:`debug.sf.enable_hwc_vds` 是**全局** SurfaceFlinger 属性,会影响整台设备的合成策略。
|
|
189
|
+
插件只在 `vds_allow_hwc=1` 时才动它,并在 `vdisplay_stop` 时恢复原值;
|
|
190
|
+
它是 `debug.*` 属性,重启设备也会自动复原,不会留下永久改动。
|
|
191
|
+
|
|
192
|
+
### 其他
|
|
193
|
+
|
|
194
|
+
- 没有 root。虚拟屏上的 App 仍然受 SELinux 约束,读不了别人的 `/data/data`。
|
|
195
|
+
- 虚拟屏与插件进程同生共死:引擎重启,屏自动消失,任务里的 App 也会结束。
|
|
196
|
+
- 每次 `start` 会多占约 0.28 核,用完记得 `vdisplay_stop`。
|