offscreen-android 0.0.0-stage → 0.1.0

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/src/ocr.js ADDED
@@ -0,0 +1,209 @@
1
+ /**
2
+ * ocr.js — 屏幕文字识别(RapidOCR / PP-OCRv4,纯 CPU,不依赖 PyTorch)。
3
+ *
4
+ * 为什么必须做这一层:实测盲测证明,把截图缩到九格(每格 262 宽)后,原图 26px 的
5
+ * 中文只剩 5-9px,**大模型完全读不出数字,而且会编造**。所以数字和文字不能靠模型看图,
6
+ * 必须 OCR 成文本交给它 —— 这样既准又省 vision token(文本几乎不计图 token)。
7
+ *
8
+ * 实测对比(720×1592 真实截图):
9
+ * Tesseract chi_sim : 4.29s,46 行,大量乱码
10
+ * RapidOCR : 1.60s,96 个文本框,置信度 0.74-1.00,带坐标
11
+ * → 选 RapidOCR,且 det_limit_side_len 从 736 降到 320 后提速 2.5 倍,质量几乎不变
12
+ *
13
+ * **实现方式**:RapidOCR 是 Python 包,而本插件跑在 Node 里,所以这里起一个 Python
14
+ * 常驻子进程(src/ocr_helper.py),用 stdin/stdout 上的 JSON 行通信。常驻是关键 ——
15
+ * 模型加载要 3-5 秒,每次重载就没法用了。
16
+ *
17
+ * 依赖:pip install rapidocr-onnxruntime(模型 15MB)
18
+ * 没装的话本模块返回 ok:false 而不是崩掉 —— OCR 是增强能力,不该让整个插件挂。
19
+ */
20
+
21
+ import { spawn } from 'node:child_process';
22
+ import { fileURLToPath } from 'node:url';
23
+ import { dirname, join } from 'node:path';
24
+
25
+ const __dirname = dirname(fileURLToPath(import.meta.url));
26
+ const HELPER = join(__dirname, 'ocr_helper.py');
27
+
28
+ const state = {
29
+ child: null,
30
+ ready: false,
31
+ error: null,
32
+ buf: '',
33
+ nextId: 1,
34
+ pending: new Map(), // id -> {resolve, timer}
35
+ lastHash: null,
36
+ lastResult: null,
37
+ startedAt: 0,
38
+ };
39
+
40
+ function finishPending(err) {
41
+ for (const [, p] of state.pending) {
42
+ clearTimeout(p.timer);
43
+ p.resolve({ ok: false, hint: err });
44
+ }
45
+ state.pending.clear();
46
+ }
47
+
48
+ /** 起(或重启)Python 常驻进程。 */
49
+ function spawnHelper() {
50
+ if (state.child) return state.child;
51
+ state.error = null;
52
+ state.ready = false;
53
+ state.buf = '';
54
+
55
+ let child;
56
+ try {
57
+ child = spawn('python3', [HELPER], { stdio: ['pipe', 'pipe', 'pipe'] });
58
+ } catch (e) {
59
+ state.error = String(e?.message || e);
60
+ return null;
61
+ }
62
+ state.child = child;
63
+ state.startedAt = Date.now();
64
+
65
+ child.stdout.on('data', (d) => {
66
+ state.buf += d.toString();
67
+ let idx;
68
+ while ((idx = state.buf.indexOf('\n')) >= 0) {
69
+ const line = state.buf.slice(0, idx).trim();
70
+ state.buf = state.buf.slice(idx + 1);
71
+ if (!line) continue;
72
+ let msg;
73
+ try { msg = JSON.parse(line); } catch { continue; }
74
+
75
+ if (msg.ready === true) { state.ready = true; continue; }
76
+ if (msg.ready === false) { state.error = msg.error || '模型加载失败'; continue; }
77
+
78
+ const p = state.pending.get(msg.id);
79
+ if (p) {
80
+ clearTimeout(p.timer);
81
+ state.pending.delete(msg.id);
82
+ p.resolve(msg);
83
+ }
84
+ }
85
+ });
86
+
87
+ child.stderr.on('data', (d) => {
88
+ const s = d.toString().trim();
89
+ if (s && !state.error) state.error = s.slice(0, 200);
90
+ });
91
+
92
+ child.on('exit', (code) => {
93
+ state.child = null;
94
+ state.ready = false;
95
+ finishPending(`OCR 进程退出(code ${code})`);
96
+ });
97
+
98
+ child.on('error', (e) => {
99
+ state.child = null;
100
+ state.ready = false;
101
+ state.error = String(e?.message || e);
102
+ finishPending(state.error);
103
+ });
104
+
105
+ return child;
106
+ }
107
+
108
+ /** 等进程报 ready(最多等 timeoutMs) */
109
+ function waitReady(timeoutMs = 20000) {
110
+ return new Promise((resolve) => {
111
+ const t0 = Date.now();
112
+ const tick = () => {
113
+ if (state.ready) return resolve(true);
114
+ if (state.error) return resolve(false);
115
+ if (!state.child) return resolve(false);
116
+ if (Date.now() - t0 > timeoutMs) return resolve(false);
117
+ setTimeout(tick, 150);
118
+ };
119
+ tick();
120
+ });
121
+ }
122
+
123
+ /** 引擎状态(不触发加载) */
124
+ export function available() {
125
+ return { ready: state.ready, running: !!state.child, error: state.error };
126
+ }
127
+
128
+ /** 预热:提前把模型加载好,让第一次 vdisplay_text 不用等 3-5 秒 */
129
+ export async function warm() {
130
+ spawnHelper();
131
+ const ok = await waitReady();
132
+ return { ok, error: state.error };
133
+ }
134
+
135
+ /**
136
+ * 识别一张图。
137
+ *
138
+ * @param {string} imagePath 本地 PNG 路径
139
+ * @param {object} [o]
140
+ * @param {number} [o.minConf=0.45] 置信度下限
141
+ * @param {number} [o.maxLines=80] 最多返回几行
142
+ * @param {string} [o.hash] 截图哈希;一样就复用上次结果,省 1.6 秒
143
+ */
144
+ export async function recognize(imagePath, o = {}) {
145
+ const minConf = Number(o.minConf) || 0.45;
146
+ const maxLines = Math.max(1, Math.min(200, Number(o.maxLines) || 80));
147
+ const hash = o.hash || null;
148
+
149
+ // 缓存键必须带上 minConf/maxLines:同一个 hash 用不同阈值请求,
150
+ // 返回的应该是不同结果,只按 hash 命中会把上次的低置信度过滤结果当成这次的。
151
+ const cacheKey = hash ? `${hash}|${minConf}|${maxLines}` : null;
152
+ if (cacheKey && state.lastKey === cacheKey && state.lastResult) {
153
+ return { ...state.lastResult, cached: true, elapsedMs: 0 };
154
+ }
155
+
156
+ if (!spawnHelper()) {
157
+ return { ok: false, hint: `起 OCR 进程失败:${state.error}` };
158
+ }
159
+ const ready = await waitReady();
160
+ if (!ready) {
161
+ return {
162
+ ok: false,
163
+ hint: state.error
164
+ ? `OCR 不可用:${state.error}`
165
+ : 'OCR 进程启动超时。装一下依赖:pip install rapidocr-onnxruntime',
166
+ };
167
+ }
168
+
169
+ const id = state.nextId++;
170
+ const t0 = Date.now();
171
+ const resp = await new Promise((resolve) => {
172
+ const timer = setTimeout(() => {
173
+ state.pending.delete(id);
174
+ resolve({ ok: false, hint: 'OCR 超时(20 秒)' });
175
+ }, 20000);
176
+ state.pending.set(id, { resolve, timer });
177
+ try {
178
+ state.child.stdin.write(JSON.stringify({ id, image: imagePath, minConf, maxLines }) + '\n');
179
+ } catch (e) {
180
+ clearTimeout(timer);
181
+ state.pending.delete(id);
182
+ resolve({ ok: false, hint: `写不进 OCR 进程:${String(e?.message || e)}` });
183
+ }
184
+ });
185
+
186
+ if (!resp.ok) return resp;
187
+
188
+ const result = {
189
+ ok: true,
190
+ lines: resp.lines || [],
191
+ count: resp.count || 0,
192
+ total: resp.total || resp.count || 0,
193
+ elapsedMs: resp.elapsedMs || (Date.now() - t0),
194
+ cached: false,
195
+ };
196
+ if (cacheKey) { state.lastKey = cacheKey; state.lastResult = result; }
197
+ return result;
198
+ }
199
+
200
+ /** 收工:关掉 Python 进程。插件卸载或引擎退出时调用。 */
201
+ export function shutdown() {
202
+ if (state.child) {
203
+ try { state.child.stdin.end(); } catch {}
204
+ try { state.child.kill('SIGTERM'); } catch {}
205
+ state.child = null;
206
+ }
207
+ state.ready = false;
208
+ finishPending('已关闭');
209
+ }
@@ -0,0 +1,125 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ ocr_helper.py — 常驻 OCR 服务,给 Node 侧调用。
4
+
5
+ 为什么是常驻而不是每次起一个:RapidOCR 加载模型要 3-5 秒,每次调用都重新加载
6
+ 就没法用了(一次识别才 1.6 秒)。所以这里保持进程活着,模型只加载一次。
7
+
8
+ 协议:stdin 一行一个 JSON 请求,stdout 一行一个 JSON 响应。
9
+ {"id":1,"image":"/tmp/a.png","minConf":0.45,"maxLines":80}
10
+ → {"id":1,"ok":true,"lines":[{"text":..,"conf":..,"x":..,"y":..,"w":..,"h":..}],"elapsedMs":..}
11
+ → {"id":1,"ok":false,"hint":"..."}
12
+
13
+ 启动后先输出 {"ready":true} 表示模型加载好了。
14
+ """
15
+
16
+ import sys
17
+ import json
18
+ import time
19
+
20
+
21
+ def main():
22
+ try:
23
+ from rapidocr_onnxruntime import RapidOCR
24
+ except Exception as e:
25
+ print(json.dumps({"ready": False, "error": f"rapidocr 未安装: {e}"}), flush=True)
26
+ return
27
+
28
+ try:
29
+ # det_limit_side_len=320:实测比默认 736 快 2.5 倍(4.5s → 1.6s),
30
+ # 文本框从 101 降到 96,关键文案 6/6 全保留。
31
+ engine = RapidOCR(
32
+ det_limit_side_len=320,
33
+ det_limit_type="min",
34
+ intra_op_num_threads=6,
35
+ )
36
+ # 预热:先跑一张 1x1 的假图,把第一个 conv 的分配做完
37
+ from PIL import Image
38
+ import tempfile
39
+ import os
40
+
41
+ tmp = os.path.join(tempfile.gettempdir(), "_ocr_warm.png")
42
+ Image.new("RGB", (64, 64), (255, 255, 255)).save(tmp)
43
+ try:
44
+ engine(tmp)
45
+ except Exception:
46
+ pass
47
+ try:
48
+ os.remove(tmp)
49
+ except Exception:
50
+ pass
51
+ except Exception as e:
52
+ print(json.dumps({"ready": False, "error": f"模型加载失败: {e}"}), flush=True)
53
+ return
54
+
55
+ print(json.dumps({"ready": True}), flush=True)
56
+
57
+ for line in sys.stdin:
58
+ line = line.strip()
59
+ if not line:
60
+ continue
61
+ try:
62
+ req = json.loads(line)
63
+ except Exception:
64
+ continue
65
+ rid = req.get("id")
66
+ path = req.get("image")
67
+ min_conf = float(req.get("minConf") or 0.45)
68
+ max_lines = int(req.get("maxLines") or 80)
69
+
70
+ if not path:
71
+ print(json.dumps({"id": rid, "ok": False, "hint": "缺 image 路径"}), flush=True)
72
+ continue
73
+
74
+ t0 = time.time()
75
+ try:
76
+ out = engine(path)
77
+ raw = out[0] if isinstance(out, tuple) else out
78
+ except Exception as e:
79
+ print(json.dumps({"id": rid, "ok": False, "hint": f"识别失败: {e}"}), flush=True)
80
+ continue
81
+
82
+ if not raw:
83
+ print(json.dumps({"id": rid, "ok": True, "lines": [], "count": 0,
84
+ "elapsedMs": int((time.time() - t0) * 1000)}), flush=True)
85
+ continue
86
+
87
+ lines = []
88
+ for item in raw:
89
+ try:
90
+ box = item[0]
91
+ text = str(item[1]).strip()
92
+ conf = float(item[2])
93
+ except Exception:
94
+ continue
95
+ if not text or conf < min_conf:
96
+ continue
97
+ xs = [float(p[0]) for p in box]
98
+ ys = [float(p[1]) for p in box]
99
+ x, y = min(xs), min(ys)
100
+ lines.append({
101
+ "text": text,
102
+ "conf": round(conf, 2),
103
+ "x": int(round(x)),
104
+ "y": int(round(y)),
105
+ "w": int(round(max(xs) - x)),
106
+ "h": int(round(max(ys) - y)),
107
+ })
108
+
109
+ # 按行分带排序:同一行的字按 x 排,不同行按 y
110
+ lines.sort(key=lambda l: (l["y"] // 14, l["x"]))
111
+ total = len(lines)
112
+ lines = lines[:max_lines]
113
+
114
+ print(json.dumps({
115
+ "id": rid,
116
+ "ok": True,
117
+ "lines": lines,
118
+ "count": len(lines),
119
+ "total": total,
120
+ "elapsedMs": int((time.time() - t0) * 1000),
121
+ }), flush=True)
122
+
123
+
124
+ if __name__ == "__main__":
125
+ main()
package/src/pool.js ADDED
@@ -0,0 +1,195 @@
1
+ /**
2
+ * pool.js — 多块后台屏的池化管理。
3
+ *
4
+ * ## 为什么需要
5
+ *
6
+ * `vd.js` 原来是模块级单例,一次只能一块屏。要让「每个会话/子代理一块屏」,
7
+ * 就得有多块屏并存。实测两块 scrcpy 虚拟屏能同时存在(见
8
+ * `tests/risk-sim/MULTI-SCREEN-FINDINGS.md` U8)。
9
+ *
10
+ * ## 屏身份怎么认
11
+ *
12
+ * 最大的障碍:所有 scrcpy 屏的名字都是 `"scrcpy"`(scrcpy 5.0.1 没有改名参数,
13
+ * 见同一个文件的 U6)。所以没法按名字分。
14
+ *
15
+ * **解法是 dpi 金丝雀**:第 i 块屏用 `dpi = 320 + i`,之后从
16
+ * `dumpsys display` 的 `density` 反查是哪一块。差 1 dpi 肉眼无感,
17
+ * 但数值上是唯一的。U4 实测 density 可读,U8 实测 320/321 能区分。
18
+ *
19
+ * ## 设计取舍
20
+ *
21
+ * 不做完整的 broker(租约、抢占、优先级队列)—— 那是 2.5-4 天的活,设计在
22
+ * `BROKER-DESIGN.md`。这里做的是**能真正用起来的最小版**:
23
+ *
24
+ * · 建/销毁/列举屏
25
+ * · 每块屏有稳定的 screenId(`sd-1`、`sd-2`…),一次开机内不复用
26
+ * · 按 screenId 切换活动上下文,之后所有 vd.* 调用都作用在那块屏上
27
+ * · 屏没了能检测、能重建
28
+ *
29
+ * 抢占和租约留给下一层 —— 因为没有它们,多屏本身也是有用的(不同会话用不同屏,
30
+ * 撞了就报错让人决定,比默默抢走好)。
31
+ */
32
+
33
+ import * as vd from './vd.js';
34
+
35
+ /** screenId → 上下文。一次开机内 screenId 不复用。 */
36
+ const screens = new Map();
37
+ let nextId = 1;
38
+ /** dpi 金丝雀的下一个偏移。320 是基础值,每块屏 +1。 */
39
+ let nextDpiOffset = 0;
40
+
41
+ const BASE_DPI = 320;
42
+
43
+ /**
44
+ * 建一块新屏。
45
+ *
46
+ * @param {object} [o]
47
+ * @param {number} [o.width] 省略则按物理屏比例
48
+ * @param {number} [o.height]
49
+ * @param {string} [o.orientation] 'portrait' | 'landscape'
50
+ * @param {boolean} [o.hwc]
51
+ * @returns {Promise<{ok:boolean, screenId?:string, displayId?:number, dpi?:number, hint?:string}>}
52
+ */
53
+ export async function create(o = {}) {
54
+ // 切换到一个全新的空上下文来建屏,建完再把它存进池
55
+ const ctx = vd.newContext();
56
+ vd.setActive(ctx);
57
+
58
+ const dpi = BASE_DPI + nextDpiOffset;
59
+ const r = await vd.start({
60
+ width: Number(o.width) || 0,
61
+ height: Number(o.height) || 0,
62
+ dpi,
63
+ systemDecorations: false,
64
+ orientation: o.orientation,
65
+ hwc: o.hwc || 'auto',
66
+ });
67
+
68
+ if (!r.ok) {
69
+ return { ok: false, hint: r.hint || '建屏失败' };
70
+ }
71
+
72
+ // 建屏过程中 dpi 可能被系统重算,以实际生效的为准
73
+ const screenId = `sd-${nextId}`;
74
+ nextId += 1;
75
+ nextDpiOffset += 1;
76
+
77
+ screens.set(screenId, {
78
+ screenId,
79
+ ctx,
80
+ dpi,
81
+ displayId: r.displayId,
82
+ sfId: r.sfId,
83
+ createdAt: Date.now(),
84
+ });
85
+
86
+ return { ok: true, screenId, displayId: r.displayId, dpi, requestedDpi: dpi };
87
+ }
88
+
89
+ /**
90
+ * 切换当前活动屏。之后所有 vd.* 调用都作用在它上面。
91
+ * @returns {{ok:boolean, hint?:string, displayId?:number}}
92
+ */
93
+ export function use(screenId) {
94
+ const s = screens.get(screenId);
95
+ if (!s) {
96
+ return {
97
+ ok: false,
98
+ hint: `没有这块屏「${screenId}」。现有的:${[...screens.keys()].join(', ') || '(空,先建一块)'}`,
99
+ };
100
+ }
101
+ vd.setActive(s.ctx);
102
+ return { ok: true, displayId: s.displayId };
103
+ }
104
+
105
+ /**
106
+ * 销毁一块屏。
107
+ *
108
+ * 注意:**必须先把活动上下文切到它**,因为 vd.stop() 操作的是当前 state。
109
+ */
110
+ export async function destroy(screenId, o = {}) {
111
+ const s = screens.get(screenId);
112
+ if (!s) return { ok: false, hint: `没有这块屏「${screenId}」` };
113
+
114
+ vd.setActive(s.ctx);
115
+ try {
116
+ await vd.stop({ forceStopApps: o.forceStopApps === true });
117
+ } catch { /* 尽力而为 */ }
118
+ screens.delete(screenId);
119
+
120
+ // 活动上下文被销毁了,切到剩下的任意一块(或重置)
121
+ const rest = [...screens.values()];
122
+ vd.setActive(rest.length ? rest[0].ctx : vd.newContext());
123
+
124
+ return { ok: true, screenId, remaining: screens.size };
125
+ }
126
+
127
+ /**
128
+ * 列出池里所有屏,并**对账**:系统里还在不在。
129
+ *
130
+ * 为什么要对账:DisplayHost 是 uid 2000 普通进程,oom_adj 不占优,
131
+ * 可能被 LMK 杀掉,屏跟着消失,而我们的账本还以为它在。
132
+ */
133
+ export async function list() {
134
+ const out = [];
135
+ for (const [id, s] of screens) {
136
+ let alive = false;
137
+ let actualDpi = null;
138
+ try {
139
+ // 切到它再查,vd.status() 看的是当前 state
140
+ vd.setActive(s.ctx);
141
+ const st = await vd.status();
142
+ alive = st.running === true;
143
+ actualDpi = st.dpi ?? null;
144
+ } catch { /* 查不到就当死了 */ }
145
+ out.push({
146
+ screenId: id,
147
+ displayId: s.displayId,
148
+ dpi: actualDpi ?? s.dpi,
149
+ dpiCanary: s.dpi,
150
+ alive,
151
+ ageSec: Math.round((Date.now() - s.createdAt) / 1000),
152
+ });
153
+ }
154
+ return { ok: true, count: out.length, screens: out };
155
+ }
156
+
157
+ /**
158
+ * 按 dpi 找回 screenId。
159
+ *
160
+ * 这是金丝雀方案的核心:拿到一块屏的 dpi,就能知道它是池里的哪一个。
161
+ * 用于「重启 daemon 后认领已有的屏」这种场景。
162
+ */
163
+ export function findByDpi(dpi) {
164
+ for (const [id, s] of screens) {
165
+ if (s.dpi === dpi) return id;
166
+ }
167
+ return null;
168
+ }
169
+
170
+ /** 池的概况(给 screen_pool 工具用) */
171
+ export function info() {
172
+ const active = vd.getActive();
173
+ let activeId = null;
174
+ for (const [id, s] of screens) {
175
+ if (s.ctx === active) { activeId = id; break; }
176
+ }
177
+ return {
178
+ count: screens.size,
179
+ active: activeId,
180
+ screens: [...screens.entries()].map(([id, s]) => ({
181
+ screenId: id,
182
+ displayId: s.displayId,
183
+ dpi: s.dpi,
184
+ })),
185
+ };
186
+ }
187
+
188
+ /** 销毁全部(daemon 退出时用) */
189
+ export async function destroyAll() {
190
+ const ids = [...screens.keys()];
191
+ for (const id of ids) {
192
+ try { await destroy(id); } catch { /* 尽力而为 */ }
193
+ }
194
+ return { ok: true, destroyed: ids.length };
195
+ }
@@ -0,0 +1,163 @@
1
+ /**
2
+ * sampling.js — 按「画面变化量」决定留哪一帧,不是按固定间隔。
3
+ *
4
+ * 为什么需要这一层(对抗竞品分析指出了我们的真实短板):
5
+ *
6
+ * 老做法是每 300ms 抓一帧,跟内容速度完全无关。后果可以量化:
7
+ * · 静止画面 → 抓 9 张一模一样的图,白花 2.2 秒抓帧 + 全部 token
8
+ * · 快动作 → 300ms 一格,中间十几帧的变化全丢
9
+ * dsh-video-storyboard 从 0.6.0 起就是"真切点分段 + 按累积变化量补采样点",
10
+ * 我们这一项本来落后,这个模块就是补这块。
11
+ *
12
+ * 做法:以 minGapMs 快抓,每帧先缩到 32×32 灰度跟「上一个留下的帧」比,
13
+ * 累积变化够了才留下当一格。比的是 32×32(3KB)而不是 720×1592(几 MB),
14
+ * 一次比较约 40ms,比"白抓一张图再拼进网格"便宜得多。
15
+ *
16
+ * 两个必须处理的边界:
17
+ * ① 画面一直不动 → 不能等到超时只留 1 帧就交差,要补"相同帧"把网格填满,
18
+ * 否则模型看到 1 格会以为"只有一瞬间",实际是"这段时间都一样"。
19
+ * ② 画面一直在动 → 不能无限抓,有 budgetMs 上限,超了就用手上的帧。
20
+ */
21
+
22
+ import { execFile } from 'node:child_process';
23
+ import { join } from 'node:path';
24
+ import { readFile, rm } from 'node:fs/promises';
25
+
26
+ const THUMB = 32; // 缩略图边长,比较用
27
+
28
+ /*
29
+ * 阈值是**量出来的**,不是拍的:
30
+ * 同一帧对比 → 0.00000
31
+ * 动画页相邻帧 → 0.0132 / 0.0142(几个黄点在暗背景上移动)
32
+ * 所以静止和运动的分界落在 0 到 0.013 之间。
33
+ *
34
+ * 第一版把 DIFF_KEEP 定成 0.055,比运动信号高 4 倍,结果**动画页被判成静止**
35
+ * (只留 1 帧就收工)—— 这是典型"阈值凭感觉定"的翻车。
36
+ * 取 0.005:留 2.6 倍余量给压缩噪声,同时能抓住 0.013 级的真实运动。
37
+ *
38
+ * 注意:这个尺度下"整屏换页"会是 0.1~0.3,远高于阈值;而"单个小图标闪烁"
39
+ * 可能只有 0.001~0.002,会被当成静止 —— 这是有意的取舍,那种变化不值得占一格。
40
+ */
41
+ const DIFF_KEEP = 0.005;
42
+ const DIFF_MAX = 0.08; // 超过这个值说明画面整体换了,必须留下
43
+
44
+ function spawnCollect(cmd, args, timeoutMs = 15000) {
45
+ return new Promise((resolve) => {
46
+ execFile(cmd, args, { timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024, encoding: 'buffer' },
47
+ (err, stdout) => resolve(err ? null : stdout));
48
+ });
49
+ }
50
+
51
+ /** 把一张图缩成 32×32 灰度,返回 Buffer(1024 字节)或 null */
52
+ async function thumb(path) {
53
+ const buf = await spawnCollect('ffmpeg', [
54
+ '-v', 'error', '-i', path,
55
+ '-vf', `scale=${THUMB}:${THUMB}:force_original_aspect_ratio=disable,format=gray`,
56
+ '-frames:v', '1', '-f', 'rawvideo', '-',
57
+ ]);
58
+ return buf && buf.length >= THUMB * THUMB ? buf.subarray(0, THUMB * THUMB) : null;
59
+ }
60
+
61
+ /** 两张缩略图的平均绝对差(0..1) */
62
+ function diffRatio(a, b) {
63
+ if (!a || !b || a.length !== b.length) return 1;
64
+ let sum = 0;
65
+ for (let i = 0; i < a.length; i += 1) sum += Math.abs(a[i] - b[i]);
66
+ return sum / (a.length * 255);
67
+ }
68
+
69
+ /**
70
+ * 自适应抓帧。
71
+ *
72
+ * @param {object} o
73
+ * @param {(dest:string)=>Promise<boolean>} o.grab 抓一帧到 dest,返回是否成功
74
+ * @param {string} o.dir 工作目录
75
+ * @param {number} o.need 需要几帧(会被填满,用重复帧补)
76
+ * @param {number} [o.minGapMs=100] 两次抓帧之间最短间隔
77
+ * @param {number} [o.maxGapMs=300] 画面一直不变时,最多等这么久就再试一次
78
+ * @param {number} [o.budgetMs=6000] 总时间上限
79
+ * @returns {Promise<{frames:string[], changes:number[], skipped:number, stopReason:string}>}
80
+ */
81
+ export async function captureFramesAdaptive({
82
+ grab, dir, need, minGapMs = 100, maxGapMs = 300, budgetMs = 6000,
83
+ }) {
84
+ const t0 = Date.now();
85
+ const frames = []; // 留下的帧路径
86
+ const changes = []; // 每帧相对上一帧的变化量(0..1)
87
+ const thumbs = []; // 对应缩略图
88
+ let skipped = 0; // 因为"没怎么变"被丢掉的帧数
89
+ let stopReason = 'filled';
90
+ let seq = 0;
91
+
92
+ while (frames.length < need) {
93
+ if (Date.now() - t0 > budgetMs) { stopReason = 'budget'; break; }
94
+
95
+ const dest = join(dir, `s${String(seq + 1).padStart(3, '0')}.png`);
96
+ seq += 1;
97
+ const ok = await grab(dest);
98
+ if (!ok) {
99
+ stopReason = 'grab-failed';
100
+ break;
101
+ }
102
+ const th = await thumb(dest);
103
+
104
+ if (frames.length === 0) {
105
+ // 第一帧无条件留下 —— 没有参照物
106
+ frames.push(dest);
107
+ thumbs.push(th);
108
+ changes.push(0);
109
+ await new Promise((r) => setTimeout(r, minGapMs));
110
+ continue;
111
+ }
112
+
113
+ const d = diffRatio(thumbs[thumbs.length - 1], th);
114
+ if (d >= DIFF_KEEP || d >= DIFF_MAX) {
115
+ frames.push(dest);
116
+ thumbs.push(th);
117
+ changes.push(Math.round(d * 1000) / 1000);
118
+ await new Promise((r) => setTimeout(r, minGapMs));
119
+ } else {
120
+ // 没怎么变 → 丢掉这张,不占格子
121
+ skipped += 1;
122
+ try { await rm(dest, { force: true }); } catch { /* 删不掉不影响 */ }
123
+ // 但也不能一直干等:太久没变化就再抓一次(万一刚好在变化的间歇)
124
+ await new Promise((r) => setTimeout(r, Math.max(minGapMs, Math.min(maxGapMs, 220))));
125
+ // 连续很多次都没变化,说明真的静止 —— 不用再耗预算,直接补满
126
+ // **按时间判定静止,不按跳过次数。**
127
+ // 按次数的话:每轮 抓帧250 + 缩略40 + 等待220 ≈ 510ms,18 次要 9 秒,
128
+ // 比老的固定间隔(2.2 秒)还慢 —— 实测就是这么翻车的(6.2s 才判定 static)。
129
+ // 静止画面只要 1.2 秒还没出现第二帧,就足以确定它不动了,直接补满收工。
130
+ const elapsed = Date.now() - t0;
131
+ if (frames.length < 2 && elapsed > 1200) {
132
+ stopReason = 'static';
133
+ break;
134
+ }
135
+ // 已经有多帧但连续很多次没变化,也收工(画面进入了静止段)
136
+ if (frames.length >= 2 && skipped >= Math.max(4, need)) {
137
+ stopReason = 'static-tail';
138
+ break;
139
+ }
140
+ }
141
+ }
142
+
143
+ // 帧不够就补重复(静止画面正常如此),让网格填满而不是留空格
144
+ if (frames.length === 0) return { frames, changes, skipped, stopReason: 'none' };
145
+ const filled = frames.slice();
146
+ const filledChanges = changes.slice();
147
+ while (filled.length < need) {
148
+ filled.push(frames[frames.length - 1]);
149
+ filledChanges.push(0);
150
+ }
151
+ if (stopReason === 'filled' && skipped > 0) stopReason = 'adaptive';
152
+
153
+ return {
154
+ frames: filled,
155
+ changes: filledChanges,
156
+ skipped,
157
+ stopReason,
158
+ elapsedMs: Date.now() - t0,
159
+ distinct: frames.length,
160
+ };
161
+ }
162
+
163
+ export const _internal = { thumb, diffRatio, THUMB, DIFF_KEEP };