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/package.json CHANGED
@@ -1,6 +1,57 @@
1
1
  {
2
2
  "name": "offscreen-android",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Give an AI agent its own invisible Android screen. VirtualDisplay + scrcpy over adb, no root. MCP server and CLI included.",
5
+ "keywords": [
6
+ "android",
7
+ "virtual-display",
8
+ "ai-agent",
9
+ "mcp",
10
+ "scrcpy",
11
+ "adb",
12
+ "computer-use",
13
+ "no-root",
14
+ "automation",
15
+ "headless"
16
+ ],
17
+ "license": "MIT",
18
+ "author": "JMINNO",
19
+ "type": "module",
20
+ "main": "./src/index.js",
21
+ "exports": {
22
+ ".": "./src/index.js"
23
+ },
24
+ "files": [
25
+ "src/",
26
+ "bin/",
27
+ "assets/",
28
+ "README.md",
29
+ "LICENSE"
30
+ ],
31
+ "engines": {
32
+ "node": "^22.19.0 || >=24.0.0"
33
+ },
34
+ "dsh": {
35
+ "bundle": {
36
+ "patch": "./cordis.patch.yml"
37
+ }
38
+ },
39
+ "peerDependencies": {
40
+ "@deepseek-ai/dsh-tools": ">=0.1.0-rc.7"
41
+ },
42
+ "peerDependenciesMeta": {
43
+ "@deepseek-ai/dsh-tools": {
44
+ "optional": true
45
+ }
46
+ },
47
+ "bin": {
48
+ "offscreen-android": "./bin/vdisplay.mjs",
49
+ "offscreen-androidd": "./bin/vdisplayd.mjs",
50
+ "offscreen-android-mcp": "./bin/mcp-server.mjs"
51
+ },
52
+ "homepage": "https://github.com/JMINN0/offscreen-android#readme",
53
+ "repository": {
54
+ "type": "git",
55
+ "url": "git+https://github.com/JMINN0/offscreen-android.git"
56
+ }
57
+ }
@@ -0,0 +1,348 @@
1
+ /**
2
+ * 常驻取帧服务(ImageReader)的 Node 侧管理 —— **多实例版**。
3
+ *
4
+ * ## 为什么需要
5
+ *
6
+ * `screencap` 每帧要 141ms 的 Surface 回读,加起来 227-243ms/帧 = 2.5fps,
7
+ * 这是 screencap 的工作方式决定的,改不了。`ImageReader` 从合成器直接拿 buffer,
8
+ * 实测 76fps,快 30 倍。
9
+ *
10
+ * ## 为什么是多实例
11
+ *
12
+ * 上一版是**单例**:模块级 `state` 只有一个,`start()` 第一件事是 `await stop()` ——
13
+ * 于是「开第二块屏」会把「第一块屏的推流」停掉,第一个悬浮窗因 `/status` 说
14
+ * running:false 而自己关掉。**多窗口因此永远只剩一个。**
15
+ *
16
+ * 现在按 displayId 分组:
17
+ *
18
+ * servers: Map<displayId, {port, size, proc, startedAt}>
19
+ *
20
+ * Java 侧本来就接受 `--display=N --port=P` 参数,**一个 displayId 一个 app_process 进程**,
21
+ * 天然可以并存。端口从 38820 往上分配,跳过已占用的。
22
+ *
23
+ * ## 兼容
24
+ *
25
+ * `stop()` / `info()` 不传 displayId 时作用于「全部」/「活动的那一个」,
26
+ * 老调用方不用改。
27
+ */
28
+ import { spawn, execFile } from 'node:child_process';
29
+ import { promisify } from 'node:util';
30
+ import { existsSync } from 'node:fs';
31
+ import { fileURLToPath } from 'node:url';
32
+ import { dirname, join } from 'node:path';
33
+ import { adbTarget } from './target.js';
34
+
35
+ const run = promisify(execFile);
36
+
37
+ const REMOTE_DIR = '/data/local/tmp/dshframe';
38
+ const REMOTE_DEX = REMOTE_DIR + '/frame.dex';
39
+ const BASE_PORT = 38820;
40
+ const MAX_PORT = 38840; // 最多 20 块屏,够了
41
+
42
+ /**
43
+ * displayId → 实例。
44
+ *
45
+ * 用 Map 而不是对象:displayId 是数字,Map 的键类型稳定,
46
+ * 而且能保证 `for (const [id, v] of servers)` 的插入顺序(级联顺序靠它)。
47
+ */
48
+ const servers = new Map();
49
+
50
+ /** 当前「活动」的 displayId(最后一次 start 的那个),给不带参数的调用用。 */
51
+ let activeDisplayId = null;
52
+
53
+ function pkgRoot() {
54
+ try { return join(dirname(fileURLToPath(import.meta.url)), '..'); }
55
+ catch { return process.cwd(); }
56
+ }
57
+
58
+ /** 找编译好的 dex。没有就返回 null(调用方降级)。 */
59
+ function findDex() {
60
+ const root = pkgRoot();
61
+ for (const rel of ['../framesrv/build/classes.dex', '../framesrv/classes.dex']) {
62
+ const p = join(root, rel);
63
+ if (existsSync(p)) return p;
64
+ }
65
+ return null;
66
+ }
67
+
68
+ /** 推 dex 到设备(内容一样就跳过)。多个实例共用同一个 dex 文件。 */
69
+ async function pushDex(target) {
70
+ const local = findDex();
71
+ if (!local) return { ok: false, why: '没找到 framesrv/build/classes.dex(先编译 framesrv)' };
72
+ try {
73
+ await run('adb', ['-s', target, 'shell', `mkdir -p ${REMOTE_DIR}`], { timeout: 8000 });
74
+ const r = await run('adb', ['-s', target, 'push', local, REMOTE_DEX], { timeout: 20000 });
75
+ const out = String(r.stdout || '') + String(r.stderr || '');
76
+ if (/error|failed/i.test(out) && !/1 file pushed/.test(out)) {
77
+ return { ok: false, why: 'push 失败: ' + out.slice(0, 80) };
78
+ }
79
+ await run('adb', ['-s', target, 'shell', `chmod 644 ${REMOTE_DEX}`], { timeout: 8000 });
80
+ return { ok: true };
81
+ } catch (e) {
82
+ return { ok: false, why: 'push 异常: ' + String(e?.message || e).slice(0, 80) };
83
+ }
84
+ }
85
+
86
+ /** 探活:/status 能通就算活着。 */
87
+ async function probe(port) {
88
+ try {
89
+ const { request } = await import('node:http');
90
+ return await new Promise((resolve) => {
91
+ const req = request({
92
+ host: '127.0.0.1', port, path: '/status', method: 'GET', timeout: 700,
93
+ }, (res) => {
94
+ let body = '';
95
+ res.on('data', (d) => { body += d; });
96
+ res.on('end', () => {
97
+ try { resolve({ ok: true, info: JSON.parse(body) }); }
98
+ catch { resolve({ ok: false }); }
99
+ });
100
+ });
101
+ req.on('error', () => resolve({ ok: false }));
102
+ req.on('timeout', () => { req.destroy(); resolve({ ok: false }); });
103
+ req.end();
104
+ });
105
+ } catch { return { ok: false }; }
106
+ }
107
+
108
+ /** 分配一个没被占用的端口。 */
109
+ function allocPort() {
110
+ const used = new Set();
111
+ for (const s of servers.values()) used.add(s.port);
112
+ for (let p = BASE_PORT; p < MAX_PORT; p++) {
113
+ if (!used.has(p)) return p;
114
+ }
115
+ return 0;
116
+ }
117
+
118
+ /**
119
+ * 查这块屏**当前**的尺寸。
120
+ *
121
+ * **必须用 `app W x H`,不能用 `real W x H`。**
122
+ * `dumpsys display` 里 `real` 是自然尺寸(= DisplayDeviceInfo),旋转后**不变**;
123
+ * `app` 才是应用实际在用的尺寸,跟随旋转。
124
+ *
125
+ * 用 real 的后果:屏已经是横向时启动取帧服务,会把 720×1592 传进去,
126
+ * 第一帧方向就是错的(有尺寸看门狗会自愈,但开头那段是歪的)。
127
+ *
128
+ * 优先 app,取不到退 real,都没有才用调用方给的兜底值。
129
+ */
130
+ async function realSize(target, displayId, fallbackW, fallbackH) {
131
+ try {
132
+ const r = await run('adb', ['-s', target, 'shell',
133
+ `dumpsys display 2>/dev/null | grep -A8 "Display ${displayId}:" | grep -oE "(app|real) [0-9]+ x [0-9]+" | head -2`],
134
+ { timeout: 8000 });
135
+ const out = String(r.stdout || '');
136
+ let m = out.match(/app (\d+) x (\d+)/); // 跟随旋转,首选
137
+ if (!m) m = out.match(/real (\d+) x (\d+)/); // 物理兜底
138
+ if (m) return { w: Number(m[1]), h: Number(m[2]) };
139
+ } catch { /* 查不到就用传入值 */ }
140
+ return { w: fallbackW, h: fallbackH };
141
+ }
142
+
143
+ /**
144
+ * 为一块屏启动取帧服务。
145
+ *
146
+ * @param {{displayId:number, width?:number, height?:number, port?:number, mirror?:string}} opt
147
+ * @returns {Promise<{ok:boolean, port?:number, reused?:boolean, why?:string, fps?:number}>}
148
+ */
149
+ export async function start({ displayId, width, height, port, mirror } = {}) {
150
+ if (!displayId) return { ok: false, why: '缺 displayId' };
151
+
152
+ // 已经在跑这块屏 → 复用(探活确认)
153
+ const cur = servers.get(displayId);
154
+ if (cur) {
155
+ const p = await probe(cur.port);
156
+ if (p.ok) {
157
+ activeDisplayId = displayId;
158
+ return { ok: true, port: cur.port, reused: true, fps: p.info?.fps || 0 };
159
+ }
160
+ // 死了 → 清掉重来
161
+ servers.delete(displayId);
162
+ }
163
+
164
+ const target = await adbTarget();
165
+ const pushed = await pushDex(target);
166
+ if (!pushed.ok) return pushed;
167
+
168
+ const real = await realSize(target, displayId, width || 720, height || 1592);
169
+ const size = `${real.w}x${real.h}`;
170
+
171
+ const usePort = port || allocPort();
172
+ if (!usePort) return { ok: false, why: `端口用完了(${BASE_PORT}-${MAX_PORT})` };
173
+
174
+ // mirror 参数:把这块屏镜像到 dsh-frames 虚拟屏(悬浮窗读它)
175
+ // 不传就让 Java 侧自己建默认的镜像屏
176
+ const mirrorArg = mirror ? ` --mirror=${mirror}` : '';
177
+ const cmd = `CLASSPATH=${REMOTE_DEX} app_process / com.dsh.framesrv.Main`
178
+ + ` --display=${displayId} --port=${usePort} --width=400 --size=${size}${mirrorArg}`;
179
+
180
+ try {
181
+ const child = spawn('adb', ['-s', target, 'shell', cmd], {
182
+ detached: true,
183
+ stdio: 'ignore',
184
+ });
185
+ child.unref();
186
+ servers.set(displayId, {
187
+ port: usePort, displayId, size, proc: child, startedAt: Date.now(),
188
+ });
189
+ } catch (e) {
190
+ return { ok: false, why: '启动失败: ' + String(e?.message || e).slice(0, 80) };
191
+ }
192
+
193
+ // 等端口起来(最多 8 秒)
194
+ for (let i = 0; i < 16; i++) {
195
+ await new Promise((r) => setTimeout(r, 500));
196
+ const p = await probe(usePort);
197
+ if (p.ok) {
198
+ activeDisplayId = displayId;
199
+ return { ok: true, port: usePort, fps: p.info?.fps || 0, reused: false };
200
+ }
201
+ }
202
+ // 起不来就清掉,别留死记录
203
+ servers.delete(displayId);
204
+ return { ok: false, why: '启动后 8 秒内端口没起来(看 logcat: app_process 可能崩了)' };
205
+ }
206
+
207
+ /** 请一个实例自己退出。 */
208
+ async function quit(port) {
209
+ try {
210
+ const { request } = await import('node:http');
211
+ await new Promise((resolve) => {
212
+ const req = request({ host: '127.0.0.1', port, path: '/quit', timeout: 500 }, (res) => {
213
+ res.resume(); res.on('end', resolve);
214
+ });
215
+ req.on('error', () => resolve());
216
+ req.on('timeout', () => { req.destroy(); resolve(); });
217
+ req.end();
218
+ });
219
+ } catch { /* ignore */ }
220
+ }
221
+
222
+ /**
223
+ * 停取帧服务。
224
+ * @param {number} [displayId] 只停这一块;省略 = 全停。
225
+ */
226
+ export async function stop(displayId) {
227
+ if (displayId != null) {
228
+ const s = servers.get(displayId);
229
+ if (s) {
230
+ await quit(s.port);
231
+ servers.delete(displayId);
232
+ try { s.proc?.kill?.(); } catch { /* ignore */ }
233
+ }
234
+ if (activeDisplayId === displayId) activeDisplayId = firstKey();
235
+ return { ok: true, stopped: displayId ? 1 : 0 };
236
+ }
237
+ // 全停
238
+ const ports = [...servers.values()].map((s) => s.port);
239
+ for (const p of ports) await quit(p);
240
+ for (const s of servers.values()) { try { s.proc?.kill?.(); } catch { /* ignore */ } }
241
+ servers.clear();
242
+ activeDisplayId = null;
243
+ return { ok: true, stopped: ports.length };
244
+ }
245
+
246
+ function firstKey() {
247
+ for (const k of servers.keys()) return k;
248
+ return null;
249
+ }
250
+
251
+ /**
252
+ * 状态。
253
+ * @param {number} [displayId] 查这一块;省略 = 返回活动那块 + 全部列表。
254
+ */
255
+ export async function info(displayId) {
256
+ if (displayId != null) {
257
+ const s = servers.get(displayId);
258
+ if (!s) return { running: false, displayId };
259
+ const p = await probe(s.port);
260
+ if (!p.ok) {
261
+ servers.delete(displayId);
262
+ return { running: false, displayId };
263
+ }
264
+ return { running: true, port: s.port, displayId, size: s.size, ...(p.info || {}) };
265
+ }
266
+ // 无参:活动那块(兼容老调用)+ 全部
267
+ const all = [];
268
+ for (const [id, s] of servers) {
269
+ const p = await probe(s.port);
270
+ all.push({ displayId: id, port: s.port, size: s.size, running: p.ok, ...(p.ok ? (p.info || {}) : {}) });
271
+ }
272
+ const act = activeDisplayId != null ? all.find((x) => x.displayId === activeDisplayId) : all[0];
273
+ return {
274
+ running: !!(act && act.running),
275
+ port: act?.port || 0,
276
+ displayId: act?.displayId ?? null,
277
+ size: act?.size || '',
278
+ count: all.length,
279
+ servers: all,
280
+ };
281
+ }
282
+
283
+ /** 把点击位置发给 framesrv,下一帧会画十字。 */
284
+ export async function markTap(nx, ny, displayId) {
285
+ // **端口优先用进程内状态,没有就回退到 stream.json。**
286
+ // 实机踩到:模块状态是进程内的,换一个 Node 进程调 input 时 port 是 0
287
+ // → 标记发不出去 → 用户看不到点击位置。
288
+ let port = 0;
289
+ const want = displayId != null ? displayId : activeDisplayId;
290
+ const s = want != null ? servers.get(want) : null;
291
+ if (s) port = s.port;
292
+ if (!port && servers.size === 1) port = [...servers.values()][0].port;
293
+ if (!port) {
294
+ try {
295
+ const { readFile } = await import('node:fs/promises');
296
+ const { homedir } = await import('node:os');
297
+ const { join } = await import('node:path');
298
+ const raw = await readFile(join(homedir(), '.dsh', 'plugin-screen', 'stream.json'), 'utf8');
299
+ const j = JSON.parse(raw);
300
+ if (j && j.port && (j.backend === 'imagereader')) port = Number(j.port);
301
+ } catch { /* 读不到就算了 */ }
302
+ }
303
+ if (!port) return;
304
+ try {
305
+ const { request } = await import('node:http');
306
+ const x = Math.max(0, Math.min(1, Number(nx)));
307
+ const y = Math.max(0, Math.min(1, Number(ny)));
308
+ if (!Number.isFinite(x) || !Number.isFinite(y)) return;
309
+ await new Promise((resolve) => {
310
+ const req = request({
311
+ host: '127.0.0.1', port,
312
+ path: `/mark?nx=${x.toFixed(4)}&ny=${y.toFixed(4)}`,
313
+ method: 'GET', timeout: 600,
314
+ }, (res) => { res.resume(); res.on('end', resolve); });
315
+ req.on('error', () => resolve());
316
+ req.on('timeout', () => { req.destroy(); resolve(); });
317
+ req.end();
318
+ });
319
+ } catch { /* 画不上就算了 */ }
320
+ }
321
+
322
+ /** 活动实例的端口(兼容老调用)。 */
323
+ export function currentPort() {
324
+ const s = activeDisplayId != null ? servers.get(activeDisplayId) : null;
325
+ if (s) return s.port;
326
+ if (servers.size === 1) return [...servers.values()][0].port;
327
+ return 0;
328
+ }
329
+
330
+ /** 是否有实例在跑(兼容老调用)。 */
331
+ export function isRunning() { return servers.size > 0; }
332
+
333
+ /** 所有实例(诊断用)。 */
334
+ export function listServers() {
335
+ return [...servers.entries()].map(([id, s]) => ({ displayId: id, port: s.port, size: s.size }));
336
+ }
337
+
338
+ /** 指定/活动实例的端口。 */
339
+ export function portOf(displayId) {
340
+ const s = displayId != null ? servers.get(displayId) : (activeDisplayId != null ? servers.get(activeDisplayId) : null);
341
+ return s ? s.port : 0;
342
+ }
343
+
344
+ /** 设活动屏(screen_use 切屏时调)。 */
345
+ export function setActive(displayId) {
346
+ if (servers.has(displayId)) { activeDisplayId = displayId; return true; }
347
+ return false;
348
+ }