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/tools.js ADDED
@@ -0,0 +1,2034 @@
1
+ /** 工具的执行体。全部返回 { text },失败给原因和下一步,不抛异常。 */
2
+ import * as vd from './vd.js';
3
+ import * as stream from './stream.js';
4
+ import * as timeline from './timeline.js';
5
+ import { adbTarget } from './target.js';
6
+
7
+ export async function modes() {
8
+ return {
9
+ text: [
10
+ '可用操作方式(都保证不动主屏):',
11
+ '',
12
+ '| 方式 | 用什么 | 适用 | 代价 |',
13
+ '| shell | adb_shell 那套 | 装包、看日志、查状态、改设置 | 零打扰,最快 |',
14
+ '| browser | web_* 那套(CDP) | 网页交互、填表、读页面 | 需要浏览器在跑 |',
15
+ '| vdisplay | vdisplay_* | 需要"看界面再点"的 App | 多占约 0.28 核 |',
16
+ '| watch | vdisplay_shot | 用户想看你操作时的证据 | 一次截图 |',
17
+ '',
18
+ '选择顺序:能用 shell 就别开屏;能读文本就别截图;必须操作 App 界面时才用 vdisplay。',
19
+ ].join('\n'),
20
+ };
21
+ }
22
+
23
+ export async function start(args) {
24
+ // **AI 可以按任务预估设定空闲超时**:比如「这个任务大概要挂 30 分钟」就传 keepMin:30。
25
+ // 不传就沿用当前设定(默认 5 分钟)。
26
+ if (args?.keepMin != null) {
27
+ const r = setIdleTimeout(args.keepMin);
28
+ if (r.ok) {
29
+ try { console.error('[dsh-screen] 后台屏空闲超时设为 ' + r.minutes + ' 分钟'); } catch { /* ignore */ }
30
+ }
31
+ }
32
+ const r = await vd.start({
33
+ width: Number(args?.width) || 0, // 0 = 自动按物理屏比例
34
+ height: Number(args?.height) || 0,
35
+ dpi: Number(args?.dpi) || 320,
36
+ systemDecorations: args?.systemDecorations === true, // 默认 false:屏上不带二级桌面/导航栏
37
+ orientation: args?.orientation, // portrait / landscape
38
+ hwc: args?.hwc || 'auto', // 3D 游戏需要 HWC 参与合成
39
+ // 帧率上限。以前没传过 = 无限,实测 MC 跑起来 145fps 白烧 CPU/带宽。
40
+ // 默认 60;传 0 表示不限。
41
+ maxFps: args?.maxFps === 0 ? 0 : (Number(args?.maxFps) || 60),
42
+ });
43
+ if (!r.ok) return { text: `建屏失败:${r.hint}` };
44
+ // HWC 状态以真实属性为准(复用分支以前不返回 hwc,开着 HWC 的屏会被报成「会黑屏」)。
45
+ // 配置和请求不一致必须说出来:复用一块活着的屏时不会按新配置重建,
46
+ // 以前悄悄返回「已就绪」,调用方以为拿到了横屏/带装饰的屏,实际还是旧的。
47
+ const parts = [
48
+ `虚拟屏已就绪:displayId=${r.displayId},SurfaceFlinger id=${r.sfId || '(未取到)'}`,
49
+ `能托管 App:${r.canHost ? '是 ✅' : '否(缺 OWN_CONTENT_ONLY 或 OWN_FOCUS)'}`,
50
+ `硬件合成(HWC):${r.hwc ? '已开启 ✅ 3D 游戏可正常渲染' : '未开启(3D 游戏会黑屏,轻量 App 正常)'}`,
51
+ `标志位:${r.flags || '(无)'}`,
52
+ ];
53
+ if (r.configMismatch) {
54
+ parts.push(`⚠️ 复用了已有的屏,配置和这次请求不一致:${r.configMismatch}。`
55
+ + '要按新配置建屏,请先 vdisplay_stop 再 vdisplay_start。');
56
+ }
57
+ parts.push('这块屏用户看不见,不占主屏焦点。');
58
+
59
+ // **屏建好就自动开推流** —— 用户的要求:「如果后台屏存在就自动拉起推流屏幕」。
60
+ // 这样用户不用手动调 vdisplay_stream,建屏就能看到画面。
61
+ try {
62
+ const auto = await streamStart({ fps: 10, width: 480 });
63
+ const t = String(auto?.text || '');
64
+ if (/悬浮窗已浮起/.test(t)) parts.push('✅ 推流已自动开启,悬浮窗浮起(能看到这块屏的画面)');
65
+ else if (/ImageReader/.test(t)) parts.push('✅ 推流已自动开启(' + t.split('\n')[0] + ')');
66
+ else parts.push('⚠️ 推流没起来:' + t.split('\n').slice(0,2).join(' '));
67
+ } catch (e) {
68
+ parts.push('⚠️ 自动推流失败:' + String(e?.message || e).slice(0, 60));
69
+ }
70
+ return { text: parts.join('\n') };
71
+ }
72
+
73
+ export async function launch(args) {
74
+ try { stream.setState('acting'); } catch { /* ignore */ }
75
+ const pkg = String(args?.pkg || '').trim();
76
+ if (!/^[a-z][\w.]*$/i.test(pkg)) return { text: 'pkg 看起来不是合法包名。' };
77
+ const act = args?.activity ? String(args.activity).trim() : '';
78
+ const r = await vd.launch(pkg, act);
79
+ if (!r.displayId) return { text: `投屏失败:${r.hint}` };
80
+ const lines = [
81
+ `投到虚拟屏 display=${r.displayId}`,
82
+ `落在虚拟屏上:${r.landedOnVd ? '是 ✅' : '否 ❌'}`,
83
+ `主屏前后:${r.mainFocusBefore || '(未测到)'} → ${r.mainFocusAfter || '(未测到)'}`,
84
+ ];
85
+ // 不再自动还原(见 vd.js 里的说明),所以这里**必须明确告诉调用方**:
86
+ // 主屏被抢了,而且我们没管。以前这行只在 restoredMain 为真时打,而它永远是 false。
87
+ if (r.mainChanged) {
88
+ lines.push('⚠️ 主屏前台变了(这是投屏造成的)。**本插件不会自动还原主屏**,'
89
+ + '要还原请自己 am start 原来那个。');
90
+ }
91
+ if (!r.ok) lines.push(`原始输出:${r.out}`);
92
+ return { text: lines.join('\n') };
93
+ }
94
+
95
+ export async function input(args) {
96
+ // **告诉推流「在操作」**:胶囊显示「AI 点按」,用户才知道 AI 在干活
97
+ try { stream.setState('acting'); stream.touch(); } catch { /* 推流没开就算了 */ }
98
+ // **记下坐标**:推流帧上会画出十字,用户能直接看到 AI 点在哪
99
+ try {
100
+ const a0 = args || {};
101
+ // **像素坐标要按屏幕尺寸归一化,不是除以 100000。**
102
+ // 原来 x/100000 是拍脑袋的:720 宽的屏上 x=360 会算成 0.0036,
103
+ // 十字画在左上角,跟实际点的地方完全不对。
104
+ let mx = NaN, my = NaN;
105
+ if (Number.isFinite(Number(a0.nx)) && Number.isFinite(Number(a0.ny))) {
106
+ mx = Number(a0.nx); my = Number(a0.ny);
107
+ } else if (Number.isFinite(Number(a0.x)) && Number.isFinite(Number(a0.y))) {
108
+ const vst = await vd.status().catch(() => null);
109
+ const sw = (vst && vst.width) || 720;
110
+ const sh = (vst && vst.height) || 1592;
111
+ mx = Number(a0.x) / sw;
112
+ my = Number(a0.y) / sh;
113
+ }
114
+ if (Number.isFinite(mx) && Number.isFinite(my)) {
115
+ // **两个后端各自独立 try。**
116
+ // 原来整段共用一个 try/catch:stream.markTap 一抛错,后面的
117
+ // framesrv.markTap 就被跳过,用户看不到点击位置(实机踩到)。
118
+ try { stream.markTap(mx, my, String(a0.kind || 'tap')); } catch { /* 慢路径失败不影响快路径 */ }
119
+ try {
120
+ const fsrv = await import('./framesrv.js');
121
+ await fsrv.markTap(mx, my); // 快路径(ImageReader)画
122
+ } catch { /* 快路径失败不影响慢路径 */ }
123
+ }
124
+ } catch { /* 没坐标就算了(滑动这类) */ }
125
+ const kind = String(args?.kind || '').trim();
126
+ // **hold 必须在这个白名单里。**
127
+ // vd.js:1568 早就实现了 kind==='hold'(60Hz 连续 MOVE,驱动游戏摇杆),
128
+ // 但这里漏了它 → 模型传 hold 直接被拒,README 宣传的「60Hz 摇杆走路」
129
+ // 只有命令行能用,模型完全够不着(对抗审查发现的)。
130
+ // **multitouch 已通过实测**(2026-11-19 晚)。关键是「不要自己编码 index」——
131
+ // 反编译 scrcpy 的 classes.dex 发现它自己算 index 并 OR 上 5/6,
132
+ // 我们只要发基础 action(0/1/2)。修正后 Inconsistent=0、Dropping=0。
133
+ if (!['tap', 'swipe', 'hold', 'multitouch', 'text', 'key', 'paste'].includes(kind)) {
134
+ return { text: 'kind 只能是 tap / swipe / hold / text / key / paste。hold 是按住不动(游戏摇杆/长按/挖方块)。' };
135
+ }
136
+ const r = await vd.input(kind, args || {});
137
+
138
+ // shotAfter:动作后顺手截一张,省掉「再调一次 vdisplay_shot」的整轮模型往返。
139
+ // 实测一轮往返 6–9 秒,占"点一下看结果"总耗时的绝大部分。
140
+ let shotInfo = '';
141
+ if (r.ok !== false && args?.shotAfter === true) {
142
+ const shot = await vd.shot('/tmp', { width: Number(args?.width) || 540 });
143
+ if (shot.ok) {
144
+ shotInfo = shot.unchanged
145
+ ? `\n画面和上次完全一样(${shot.path}),可以直接复用那张图。`
146
+ : `\n动作后的画面:${shot.path}(${shot.width}x${shot.height})——用 read_image 打开它。`;
147
+ }
148
+ }
149
+
150
+ // changed 必须透传:false 表示"动作发出去了但画面没变",这是有效信息,
151
+ // 不是"注入失败"。早期把它包成"注入失败"会让调用方以为工具坏了。
152
+ if (r.changed === false && r.hint) return { text: `${r.hint}\n(display=${r.displayId},${kind} 已发出)${shotInfo}` };
153
+ if (!r.ok && r.hint) return { text: `注入失败:${r.hint}` };
154
+ const tail = r.out ? `(${r.out})` : '';
155
+ return { text: `已在 display=${r.displayId} 注入 ${kind}${tail}${shotInfo}` };
156
+ }
157
+
158
+ export async function shot(args) {
159
+ try { stream.setState('looking'); } catch { /* ignore */ }
160
+ const frames = Number(args?.frames) || 1;
161
+
162
+ // frames=1 → 单张截图(读字用)
163
+ if (frames <= 1) {
164
+ const region = (args?.region && typeof args.region === 'object') ? args.region : null;
165
+ // **不做自动裁剪浏览器壳了**(原来的 crop:'content' 已移除)。
166
+ //
167
+ // 原因是经过对抗审查和实测,这个功能有三个拿不到的假设:
168
+ // ① 壳在底部 —— 实测这台 Edge 顶部还会有翻译条,clientHeight 从 1372 变 1276,
169
+ // 只从底部切会把顶部壳留下、同时切掉 96px 真实内容;
170
+ // ② 单位不变 —— layoutViewport 是 deprecated 字段(可能是 DP 也可能是 CSS px),
171
+ // 那个 flag 一翻,裁剪量从 220 变 906,直接切掉一半画面;
172
+ // ③ 前台真是浏览器 —— 不校验时虚拟屏上开着设置页也会被切掉底部。
173
+ // 而它只省 13%,region 已经能更好地解决"想看清"这个需求(2 倍细节、更便宜、不用猜)。
174
+ // 所以宁可多花 13% 的 token,也不留三个静默出错的口子。
175
+ //
176
+ // 需要跳过浏览器壳时,用 region 显式选内容区,坐标自己给 —— 明确比自动猜可靠。
177
+ const cropPx = 0;
178
+ let cropNote = args?.crop === 'content'
179
+ ? '\nℹ️ crop 已废弃:浏览器壳的上下分布拿不到可靠信号,自动裁会切错内容。想看细节请用 region。'
180
+ : '';
181
+
182
+ // region 时默认宽度不能超过 region 本身,否则是上采样(信息不增加,只花 token)。
183
+ // 比如 region 只有 200 宽却交付到 540,放大 2.7 倍,图更贵但更清楚不了一分。
184
+ const reqW = Number(args?.width) || 0;
185
+ const defaultW = region ? Math.min(540, Math.max(240, Math.round(Number(region.w) || 540))) : 540;
186
+ const outW = reqW || defaultW;
187
+ const r = await vd.shot(String(args?.dir || '/tmp'), {
188
+ width: outW,
189
+ format: args?.format === 'png' ? 'png' : 'jpeg',
190
+ cropPx,
191
+ region,
192
+ });
193
+ if (!r.ok) return { text: `截图失败:${r.hint}` };
194
+ const lines = [`虚拟屏截图:${r.path}(displayId=${r.displayId},屏 ${r.width}x${r.height})`];
195
+ if (r.unchanged) lines.push('画面和上次完全一样,可以直接复用这张,不用再看一次。');
196
+ else lines.push('用 read_image 打开它就能看到界面。');
197
+ lines.push('点坐标时可以用 nx/ny(0..1 归一化)代替 x/y,不用自己算像素。');
198
+ // **裁剪后 nx/ny 的基准变了**:ny 按整屏算会落到壳里,偏一个裁剪量。
199
+ // 对抗审查指出的第 4 条 —— 这里必须说清楚,否则模型照着推荐用 nx/ny 就会点歪。
200
+ if (cropPx > 0) {
201
+ lines.push(`⚠️ 已裁掉底部 ${cropPx}px 浏览器壳。这张图的 ny=0..1 对应的是「内容区」,不是整屏;`
202
+ + `若要用整屏归一化坐标,请改用 x/y(按图片像素给)。`);
203
+ }
204
+ if (region) lines.push('这是一张局部放大图,坐标请按这张图自己的像素给 x/y。');
205
+ if (cropNote) lines.push(cropNote);
206
+ lines.push('');
207
+ lines.push('想看"在动吗、往哪动"就传 frames=9 再调一次。');
208
+ return { text: lines.join('\n') };
209
+ }
210
+
211
+ // frames>1 → 连拍拼网格(看运动用)
212
+ const st = await vd.status();
213
+ if (!st.running) return { text: '虚拟屏没在运行。先 vdisplay_start 建屏、vdisplay_launch 投 App。' };
214
+ if (!st.sfId) return { text: '没拿到 SurfaceFlinger id,先 vdisplay_status 确认屏状态。' };
215
+
216
+ const r = await timeline.capture({
217
+ sfId: st.sfId,
218
+ frames,
219
+ intervalMs: args?.intervalMs === undefined ? 300 : Math.max(0, Number(args.intervalMs) || 0),
220
+ cellWidth: Number(args?.width) || 262,
221
+ dir: String(args?.dir || '/tmp'),
222
+ // 网格也不自动裁壳了,理由同上(壳的上下分布不可靠)。
223
+ crop: 'none',
224
+ });
225
+ if (!r.ok) return { text: `抓时间线失败:${r.hint}` };
226
+
227
+ // **报真实采样情况,不要拿公式糊弄。**
228
+ // 上一版写 `(cells-1)*intervalMs`,固定说"2.4 秒、间隔 300ms"——
229
+ // 但采样已经改成自适应了,静止画面实际只采了 1.2 秒、只拿到 1 个不同帧,
230
+ // 模型看到 9 个一样的格子 + "2.4 秒"会以为这段时间画面一直在变。
231
+ const shape = r.canvasW > r.canvasH ? '横屏' : '竖屏';
232
+ const distinct = r.distinct ?? r.captured;
233
+ const sampled = (r.sampledElapsedMs || 0) / 1000;
234
+ const lines = [
235
+ `时间线拼图:${r.path}`,
236
+ `${r.cols}×${r.rows} = ${r.cells} 格,每格 ${r.cellW}×${r.cellH},画布 ${r.canvasW}×${r.canvasH}(${shape})`,
237
+ ];
238
+ if (distinct <= 1) {
239
+ lines.push('**画面基本没动**:只采到 1 个不同帧,其余是重复帧填满网格。'
240
+ + `实际采样约 ${sampled.toFixed(1)} 秒 —— 不代表这段时间有变化。`);
241
+ } else if (distinct < r.cells) {
242
+ lines.push(`**采到 ${distinct} 个不同帧**(其余 ${r.cells - distinct} 格是重复填充),`
243
+ + `实际采样约 ${sampled.toFixed(1)} 秒。画面变化不多。`);
244
+ } else {
245
+ lines.push(`**${distinct} 个帧各不相同**,按画面变化自适应采样,实际采样约 ${sampled.toFixed(1)} 秒。`);
246
+ }
247
+ lines.push(
248
+ '用 read_image 打开它,从左到右、从上到下就是时间顺序。',
249
+ '',
250
+ '这个尺寸只能看「结构、位置、有没有动」,读不出屏幕上的小字和数字。要读数字请用 frames=1 单帧,或用 vdisplay_text。',
251
+ );
252
+ return { text: lines.join('\n') };
253
+ }
254
+
255
+ export async function mainShot(args) {
256
+ const focus = await vd.mainFocus();
257
+ const r = await vd.mainShot(String(args?.dir || '/tmp'), {
258
+ width: Number(args?.width) || 540,
259
+ format: args?.format === 'png' ? 'png' : 'jpeg',
260
+ });
261
+ if (!r.ok) return { text: `主屏截图失败:${r.hint}` };
262
+ return { text: `主屏截图:${r.path}\n主屏当前焦点:${focus || '(未测到)'}` };
263
+ }
264
+
265
+ export async function status() {
266
+ const st = await vd.status();
267
+ const focus = await vd.mainFocus();
268
+ return {
269
+ text: st.running
270
+ ? `虚拟屏运行中:displayId=${st.displayId},SF id=${st.sfId},已运行 ${st.uptimeSec} 秒\n上面的 App:${st.focusedApp || '(未知)'}\n主屏焦点:${focus || '(未测到)'}\n所有屏:${Array.isArray(st.allDisplays) && st.allDisplays.length ? st.allDisplays.join(', ') : '(查询失败)'}`
271
+ : `虚拟屏没有在运行。\n主屏焦点:${focus || '(未测到)'}\n所有屏:${Array.isArray(st.allDisplays) && st.allDisplays.length ? st.allDisplays.join(', ') : '(查询失败)'}`,
272
+ };
273
+ }
274
+
275
+ export async function stop(args) {
276
+ // **只关这一块屏的窗口,不要全关。**
277
+ // 原来这里是不带参数的 overlayStop() = 全关 —— 用户有 2 块屏时销毁其中一块,
278
+ // 两块的悬浮窗都会被关掉(对抗审查 S「Node 侧必须同步改」)。
279
+ const stopDisp = vd.getActive()?.displayId;
280
+ const stopPort = stopDisp != null ? (screenPorts.get(Number(stopDisp)) || 0) : 0;
281
+ await overlayStop(stopPort || undefined).catch(() => {});
282
+ // **屏关了就停 framesrv** —— 用户的要求:「关闭就跟着自动关闭推流屏」
283
+ try {
284
+ const fsrv = await import('./framesrv.js');
285
+ await fsrv.stop();
286
+ } catch { /* 没起来就算了 */ }
287
+ await stream.stop().catch(() => {});
288
+ const r = await vd.stop({ forceStopApps: args?.forceStopApps === true });
289
+ const lines = ['虚拟屏已销毁。'];
290
+ if (r.killed?.length) lines.push(`已清理后台 App:${r.killed.join('、')}`);
291
+ if (r.hint) lines.push(r.hint);
292
+ // **停屏时也把常驻助手关掉。**
293
+ // 原来是「用一次 find_image / vdisplay_text 之后,OpenCV(80-150MB) 和
294
+ // OCR(15MB 模型) 会一直挂到插件卸载」—— 实测确实如此(独立复核指出)。
295
+ // closeAll 里虽然写了 shutdown,但 closeAll 全库没有调用点(死代码)。
296
+ // 这里直接关,让「停屏」真正释放全部资源。
297
+ try { const vis = await import('./vision.js'); vis.shutdown(); } catch { /* ignore */ }
298
+ try { const oc = await import('./ocr.js'); oc.shutdown(); } catch { /* ignore */ }
299
+
300
+ return { text: lines.join('\n') };
301
+ }
302
+
303
+ /** 悬浮窗 APK 的包名。装了就能把画面浮在任何 App 上。 */
304
+ const OVERLAY_PKG = 'com.dsh.overlay';
305
+
306
+ /**
307
+ * 拉起 / 关掉悬浮窗 APK。
308
+ *
309
+ * **为什么要自动做**:手动敲三条 adb 命令太麻烦,而且容易忘。
310
+ * 起推流时自动把端口传给它,停推流时自动关掉 —— 用户只要调 vdisplay_stream 就够。
311
+ *
312
+ * APK 不在就静默跳过:胶囊仍然能用,只是没有跨 App 的悬浮窗。
313
+ */
314
+ /**
315
+ * 确保悬浮窗 APK 装好 —— **用户不需要手动装**。
316
+ *
317
+ * ## 为什么必须装 APK(实测过,不是偷懒)
318
+ *
319
+ * `app_process` 画不了悬浮窗:`WindowManagerService.openSession` 建的 `Session`
320
+ * 要求调用进程在 ActivityManager 的进程表里,而 app_process 从 adb shell 起、
321
+ * 不是 zygote fork 的应用进程 → `Unknown pid` 直接拒绝。
322
+ * 探针代码在 `probe/src/com/dsh/probe/OverlayProbe.java`,结论在
323
+ * `tests/NO-APK-OVERLAY-PROBE.md`。
324
+ *
325
+ * ## 怎么做到用户无感
326
+ *
327
+ * APK 就在插件包里(`assets/overlay/ai-overlay.apk`)。
328
+ * 第一次用悬浮窗时自动 push + install + 授权,用户什么都不用做。
329
+ */
330
+ async function ensureOverlayInstalled(run, target) {
331
+ // 已装就直接返回
332
+ try {
333
+ const { stdout } = await run('adb', ['-s', target, 'shell',
334
+ `pm list packages ${OVERLAY_PKG}`], { timeout: 8000 });
335
+ if (String(stdout || '').includes(OVERLAY_PKG)) return { ok: true, already: true };
336
+ } catch { /* 查不到就当没装,继续试装 */ }
337
+
338
+ // 找内置 APK
339
+ const { existsSync } = await import('node:fs');
340
+ const { fileURLToPath } = await import('node:url');
341
+ const { dirname, join } = await import('node:path');
342
+ let apk = null;
343
+ try {
344
+ const here = dirname(fileURLToPath(import.meta.url));
345
+ for (const rel of ['../assets/overlay/ai-overlay.apk', './assets/overlay/ai-overlay.apk']) {
346
+ const p = join(here, rel);
347
+ if (existsSync(p)) { apk = p; break; }
348
+ }
349
+ } catch { /* ignore */ }
350
+ if (!apk) return { ok: false, why: '找不到内置 APK(assets/overlay/ai-overlay.apk)' };
351
+
352
+ // **直接用本地路径装,不要 push 后再装。**
353
+ // 实测:`adb install <设备路径>` 会走 Incremental Install,报
354
+ // "failed to stat ... No such file or directory",装不上;
355
+ // 给本地路径则是 Streamed Install,正常。
356
+ try {
357
+ const r = await run('adb', ['-s', target, 'install', '-r', apk], { timeout: 90000 });
358
+ const out = String(r.stdout || '') + String(r.stderr || '');
359
+ if (!/Success/i.test(out)) return { ok: false, why: 'install 失败: ' + out.slice(0, 120) };
360
+ // 给悬浮窗权限(不用用户手点)
361
+ await run('adb', ['-s', target, 'shell',
362
+ `appops set ${OVERLAY_PKG} SYSTEM_ALERT_WINDOW allow`], { timeout: 8000 }).catch(() => {});
363
+ return { ok: true, already: false };
364
+ } catch (e) {
365
+ return { ok: false, why: String(e?.message || e).slice(0, 80) };
366
+ }
367
+ }
368
+
369
+ async function overlayStart(port) {
370
+ try {
371
+ const { execFile } = await import('node:child_process');
372
+ const { promisify } = await import('node:util');
373
+ const run = promisify(execFile);
374
+ const target = await adbTarget();
375
+ // **装不上就自动装**(用户无感)
376
+ const inst = await ensureOverlayInstalled(run, target);
377
+ if (!inst.ok) return { ok: false, why: inst.why };
378
+ // 给权限(幂等,已给过也不报错)
379
+ await run('adb', ['-s', target, 'shell',
380
+ `appops set ${OVERLAY_PKG} SYSTEM_ALERT_WINDOW allow`], { timeout: 8000 }).catch(() => {});
381
+ // 拉起并把端口传进去
382
+ await run('adb', ['-s', target, 'shell',
383
+ `am start -n ${OVERLAY_PKG}/.MainActivity --ei port ${port}`], { timeout: 8000 });
384
+
385
+ /* **必须验证窗口真的出现了。**
386
+ *
387
+ * 2026-11-21 对抗审查抓到:原来这里 `am start` 退出码 0 就直接返回 ok,
388
+ * streamStart 随即打印「悬浮窗已浮起」—— 而 am start 成功**不等于**窗口存在。
389
+ * 隔壁「热成像助手」对话就是被这句假成功骗了:它以为浮窗起来了,
390
+ * 实际没有,用户看不到,它又没有任何工具能自检,最后写下「悬浮窗不可用」。
391
+ *
392
+ * 现在最多等 3 秒,用 dumpsys 确认窗口真的挂上了;确认不到就返回失败,
393
+ * 让调用方(和 AI)看到真话。
394
+ */
395
+ for (let i = 0; i < 6; i++) {
396
+ const r = await run('adb', ['-s', target, 'shell',
397
+ `dumpsys window windows 2>/dev/null | grep -c 'u0 ${OVERLAY_PKG}'`],
398
+ { timeout: 6000 }).catch(() => ({ stdout: '0' }));
399
+ if (Number(String(r.stdout).trim()) > 0) {
400
+ return { ok: true, autoInstalled: inst.already === false };
401
+ }
402
+ await new Promise((res) => setTimeout(res, 500));
403
+ }
404
+ return { ok: false, why: 'am start 成功但窗口没出现(可能缺悬浮窗权限,或服务被系统拦了)' };
405
+ } catch (e) {
406
+ return { ok: false, why: String(e?.message || e).slice(0, 60) };
407
+ }
408
+ }
409
+
410
+ /**
411
+ * 关悬浮窗。
412
+ *
413
+ * @param {number} [port] 只关这个端口的窗口;省略 = 全关。
414
+ *
415
+ * **多窗口后必须支持单关**:一块屏停止推流时,不该把别的屏的窗口也关了。
416
+ */
417
+ async function overlayStop(port) {
418
+ /* **服务没在跑就别发停止指令。**
419
+ *
420
+ * 2026-11-21 用户报:浮窗早关了,过一会又弹一个「已关闭」。
421
+ * 根因不只在那个 Toast —— 5 分钟空闲看门狗会调 streamStop(),
422
+ * 而 overlayStop() 用 `am start` 发 stop,**即使服务已经停了,
423
+ * 这条 Intent 也会把那个透明 Activity 拉起来**:旧 APK 弹 Toast,
424
+ * 新 APK 也会短暂抢一次焦点/键盘。删 Toast 只是去掉症状。
425
+ *
426
+ * 所以先查服务在不在,不在就直接返回,连 Intent 都不发。
427
+ */
428
+ try {
429
+ const { execFile } = await import('node:child_process');
430
+ const { promisify } = await import('node:util');
431
+ const run0 = promisify(execFile);
432
+ const t0 = await adbTarget();
433
+ const { stdout: svc } = await run0('adb', ['-s', t0, 'shell',
434
+ `dumpsys activity services ${OVERLAY_PKG} 2>/dev/null | grep -c "${OVERLAY_PKG}"`],
435
+ { timeout: 6000 });
436
+ if (Number(String(svc).trim()) === 0) return { ok: true, skipped: 'service-not-running' };
437
+ } catch { /* 查不到就当它在跑,继续原来的路 */ }
438
+
439
+ try {
440
+ const { execFile } = await import('node:child_process');
441
+ const { promisify } = await import('node:util');
442
+ const run = promisify(execFile);
443
+ const target = await adbTarget();
444
+ const arg = (typeof port === 'number' && port > 0)
445
+ ? `--ei closePort ${port}`
446
+ : '--ez stop true';
447
+ await run('adb', ['-s', target, 'shell',
448
+ `am start -n ${OVERLAY_PKG}/.MainActivity ${arg}`], { timeout: 8000 });
449
+ return { ok: true };
450
+ } catch { return { ok: false }; }
451
+ }
452
+
453
+ /** 开始把虚拟屏画面推给原生胶囊插件(装了悬浮窗 APK 的话一起拉起来)。 */
454
+ /** displayId → framesrv 端口。多屏时用于按屏关推流/画标记。 */
455
+ const screenPorts = new Map();
456
+
457
+ export async function streamStart(args) {
458
+ // **支持为指定的屏开推流(屏幕池用)。**
459
+ // 屏幕池里的屏不是 vd 的活动屏,不能走 vd.start()(那会去建/复用另一块)。
460
+ // 传了 displayId 就直接用它,跳过 vd.start()。
461
+ let s;
462
+ if (args?.displayId) {
463
+ s = { ok: true, displayId: Number(args.displayId), sfId: args?.sfId || null,
464
+ width: args?.width, height: args?.height };
465
+ } else {
466
+ s = await vd.start();
467
+ if (!s.ok) return { text: `建屏失败:${s.hint}` };
468
+ }
469
+ const fps = Math.min(Math.max(Number(args?.fps) || 2, 1), 15); // 上限 15(原来 4 是桥接遗留)
470
+ const width = Math.min(Math.max(Number(args?.width) || 360, 240), 720);
471
+ // 传真实的 focusedApp:以前这里写死空串,导致胶囊永远只显示"操作中 12s"。
472
+ const focus = await vd.focusedApp();
473
+ try { stream.setState('looking'); } catch { /* ignore */ }
474
+
475
+ // **优先走 framesrv(ImageReader,76fps)**。
476
+ // screencap 每帧 141ms 的 Surface 回读是它的工作方式决定的,改不了;
477
+ // ImageReader 从合成器直接拿 buffer,实测快 30 倍。
478
+ let fast = { ok: false };
479
+ try {
480
+ const fsrv = await import('./framesrv.js');
481
+ fast = await fsrv.start({
482
+ displayId: s.displayId, width: s.width || 720, height: s.height || 1592,
483
+ });
484
+ } catch (e) { fast = { ok: false, why: String(e?.message || e).slice(0, 60) }; }
485
+
486
+ // **只有快路径失败时才起 screencap 推流。**
487
+ // 审计发现:原来无条件起,两条路同时跑,多烧 0.31 核,而且胶囊读的是慢的那条
488
+ // (screencap 143ms/帧),用户看到的反而是差的那一路。
489
+ let r = { ok: false, port: 0, hint: '跳过了(快路径已在跑)' };
490
+ if (!fast.ok) {
491
+ r = await stream.start({ sfId: s.sfId, displayId: s.displayId, fps, width, focusedApp: focus });
492
+ if (!r.ok) return { text: `推流启动失败:${r.hint}` };
493
+ try { screenPorts.set(Number(s.displayId), r.port); } catch { /* ignore */ }
494
+ } else {
495
+ // **登记外部后端**,让 stream.js 的 writeState 也报 framesrv 的端口
496
+ try { stream.setExternalBackend(fast.port, 'imagereader'); } catch { /* ignore */ }
497
+ // **必须记下 displayId → port 的映射。**
498
+ // 对抗审查发现:这个 Map 只有 get/delete、从没 set,
499
+ // 于是 stop() 取到 0 → overlayStop(undefined) → `--ez stop true` → **关掉所有窗口**。
500
+ try { screenPorts.set(Number(s.displayId), fast.port); } catch { /* ignore */ }
501
+ // **快路径在跑 → 把 stream.json 指向 framesrv**,让胶囊读快的这一路。
502
+ // 胶囊读 stream.json 的 port 去取 /frame.jpg 和 /status,
503
+ // framesrv 的这两个端点返回的字段是兼容的(running/frames/fps/aspect)。
504
+ try {
505
+ const { writeFile, readFile, mkdir } = await import('node:fs/promises');
506
+ const { homedir } = await import('node:os');
507
+ const { join } = await import('node:path');
508
+ const dir = join(homedir(), '.dsh', 'plugin-screen');
509
+ await mkdir(dir, { recursive: true });
510
+ // **多屏:扁平字段保留「活动那块」(胶囊兼容),另加 screens 列表。**
511
+ let prevScreens = [];
512
+ try {
513
+ const oldRaw = await readFile(join(dir, 'stream.json'), 'utf8');
514
+ const oldJ = JSON.parse(oldRaw);
515
+ if (Array.isArray(oldJ.screens)) prevScreens = oldJ.screens;
516
+ } catch { /* 第一次写 */ }
517
+ // **尺寸优先用 framesrv 查到的真实值**,不是调用方传的(可能没传 → 0x0)。
518
+ let meSize = (s.width && s.height) ? (s.width + 'x' + s.height) : '';
519
+ try {
520
+ const fsrv = await import('./framesrv.js');
521
+ const fi = await fsrv.info(Number(s.displayId));
522
+ if (fi && fi.size) meSize = fi.size;
523
+ } catch { /* 查不到就用估算 */ }
524
+ const me = {
525
+ displayId: Number(s.displayId), port: fast.port,
526
+ aspect: s.width && s.height ? (s.width / s.height) : 0,
527
+ size: meSize || '?',
528
+ };
529
+ const screens = prevScreens.filter((x) => Number(x.displayId) !== me.displayId);
530
+ screens.push(me);
531
+ await writeFile(join(dir, 'stream.json'), JSON.stringify({
532
+ port: fast.port, running: true, startedAt: Date.now(),
533
+ fps, width, displayId: String(s.displayId),
534
+ focusedApp: focus || '',
535
+ state: 'looking',
536
+ aspect: me.aspect,
537
+ backend: 'imagereader',
538
+ screens,
539
+ }));
540
+ } catch { /* 写不进去不影响推流 */ }
541
+ }
542
+
543
+ // 悬浮窗连哪个端口:优先 framesrv(快)
544
+ const viewPort = fast.ok ? fast.port : (r.port || 0);
545
+ const ov = await overlayStart(viewPort);
546
+
547
+ const lines = [];
548
+ if (fast.ok) {
549
+ lines.push(`取帧走 ImageReader(快路径):127.0.0.1:${fast.port}`);
550
+ lines.push('实测 76 fps,静止时不抓帧几乎不耗 CPU。');
551
+ } else {
552
+ lines.push(`取帧走 screencap(慢路径,${fps} fps):127.0.0.1:${r.port}`);
553
+ lines.push(`ImageReader 没起来:${fast.why || '未知'} —— 先跑 framesrv/build.sh 编译`);
554
+ }
555
+ lines.push(ov.ok ? '悬浮窗已浮起(可拖动,单击收起,浮在任何 App 上)' : `悬浮窗没起来(${ov.why})`);
556
+ lines.push('打开 DSH Go 输入框上方的「AI 画面」胶囊也能看。');
557
+ return { text: lines.join('\n') };
558
+ }
559
+
560
+ /**
561
+ * 停推流。
562
+ * @param {{displayId?:number}} [args] 只停这一块屏;省略 = 全停。
563
+ */
564
+ export async function streamStop(args) {
565
+ const oneId = args?.displayId != null ? Number(args.displayId) : null;
566
+ if (oneId != null) {
567
+ // **只停这一块**:关它的悬浮窗 + 停它的 framesrv,别的不动
568
+ const p = screenPorts.get(oneId) || 0;
569
+ if (p) await overlayStop(p);
570
+ try { const fsrv = await import('./framesrv.js'); await fsrv.stop(oneId); } catch { /* ignore */ }
571
+ screenPorts.delete(oneId);
572
+ // **从 stream.json 的 screens 里摘掉它**,否则胶囊/诊断会看到已经不存在的屏
573
+ try {
574
+ const { readFile, writeFile } = await import('node:fs/promises');
575
+ const { homedir } = await import('node:os');
576
+ const { join } = await import('node:path');
577
+ const f = join(homedir(), '.dsh', 'plugin-screen', 'stream.json');
578
+ const j = JSON.parse(await readFile(f, 'utf8'));
579
+ if (Array.isArray(j.screens)) {
580
+ j.screens = j.screens.filter((x) => Number(x.displayId) !== oneId);
581
+ // 全没了就标 not running
582
+ if (!j.screens.length) { j.running = false; j.port = 0; j.displayId = null; }
583
+ await writeFile(f, JSON.stringify(j));
584
+ }
585
+ } catch { /* 写不进去不影响停推流 */ }
586
+ return { text: `已停掉 displayId=${oneId} 的推流` + (p ? `(端口 ${p})` : '') };
587
+ }
588
+ await overlayStop(); // 先关悬浮窗,否则它会自己发现推流没了才关(多留一会儿)
589
+ // **真的把 framesrv 停掉。**
590
+ // 审计发现:原来全库没有任何 framesrv.stop() 调用点 ——
591
+ // app_process 起来了就一直在,一直编码,直到手机重启或 OOM。
592
+ let stoppedFast = false;
593
+ try {
594
+ const fsrv = await import('./framesrv.js');
595
+ await fsrv.stop();
596
+ stoppedFast = true;
597
+ } catch { /* 没起来就算了 */ }
598
+ try { stream.clearExternalBackend(); } catch { /* ignore */ }
599
+ await stream.stop();
600
+ return { text: stoppedFast
601
+ ? '推流已停止(framesrv 已退出,胶囊和悬浮窗都不再显示画面)。'
602
+ : '推流已停止(胶囊和悬浮窗都不再显示画面)。' };
603
+ }
604
+
605
+ export async function closeAll() {
606
+ // **视觉助手也要关。** 和 OCR 当初同款泄漏:OpenCV 常驻进程占 80-150MB,
607
+ // 不关就成孤儿进程(对抗审查发现的 P0)。
608
+ try { const v = await import('./vision.js'); v.shutdown(); } catch { /* ignore */ }
609
+ await stream.shutdown();
610
+ // **OCR 的 Python 常驻进程必须在这里关掉。**
611
+ // 不关的话:用过一次 vdisplay_text 之后,插件卸载/引擎重启/daemon 闲置自杀
612
+ // 都会留下一个带着 15MB 模型的 python3 孤儿进程,重载一次多一个。
613
+ try { const ocr = await import('./ocr.js'); ocr.shutdown(); } catch { /* 没装 OCR 就算了 */ }
614
+ await vd.stop();
615
+ return { text: '虚拟屏与推流都已关闭。' };
616
+ }
617
+
618
+ export async function text(args) {
619
+ try { stream.setState('looking'); } catch { /* ignore */ }
620
+ const st = await vd.status();
621
+ if (!st.running) return { text: '虚拟屏没在运行。先 vdisplay_start 建屏、vdisplay_launch 投 App。' };
622
+
623
+ const ocr = await import('./ocr.js');
624
+ const fresh = args?.fresh === true;
625
+
626
+ // 拿一张原生分辨率的截图(OCR 要在原生尺度上跑,缩小会丢小字)
627
+ const shot = await vd.shot(String(args?.dir || '/tmp'), {
628
+ width: Math.min(1080, Math.max(360, st.width || 720)),
629
+ format: 'png',
630
+ });
631
+ if (!shot.ok) return { text: `截图失败:${shot.hint}` };
632
+
633
+ const r = await ocr.recognize(shot.path, {
634
+ minConf: args?.minConf === undefined ? 0.45 : Number(args.minConf),
635
+ maxLines: Number(args?.maxLines) || 80,
636
+ hash: fresh ? null : shot.hash,
637
+ });
638
+
639
+ if (!r.ok) return { text: r.hint };
640
+
641
+ const W = shot.width || 720;
642
+ const H = shot.height || 1280;
643
+ const lines = [
644
+ `识别到 ${r.count} 行文字${r.total > r.count ? `(共 ${r.total},已截断)` : ''}`
645
+ + `,耗时 ${r.cached ? '0(画面没变,复用上次)' : `${(r.elapsedMs / 1000).toFixed(1)} 秒`}`,
646
+ `屏 ${W}x${H},下面每行的 nx/ny 是归一化坐标,可直接传给 vdisplay_input。`,
647
+ '',
648
+ ];
649
+ for (const l of r.lines) {
650
+ const nx = ((l.x + l.w / 2) / W).toFixed(3);
651
+ const ny = ((l.y + l.h / 2) / H).toFixed(3);
652
+ lines.push(` [${l.conf.toFixed(2)}] (${String(l.x).padStart(4)},${String(l.y).padStart(4)}) ${l.w}x${l.h} nx=${nx} ny=${ny} ${l.text}`);
653
+ }
654
+ lines.push('');
655
+ lines.push('要读的位置画面对不上?用 vdisplay_shot(frames=1) 看实际画面。');
656
+ lines.push('要看清某个按钮长什么样?用 vdisplay_shot 配合坐标自己判断。');
657
+ return { text: lines.join('\n') };
658
+ }
659
+
660
+
661
+ /**
662
+ * 查「用户现在在用手机吗」,以及目标 App 的风险等级。
663
+ *
664
+ * ## 为什么必须有这个工具
665
+ *
666
+ * `tools/user-busy.sh` 的判据是对的(topResumedActivity + mInputShown),
667
+ * 但它只是个脚本,不在工具链路里 —— 所以模型根本不知道要调它。
668
+ * 2026-11-17 抢键盘事故就是这么发生的:我用 mcp__phone__open 打开 Edge,
669
+ * 用户正在 DSH Go 里打字的 InputConnection 被 detach,半截草稿丢了。
670
+ *
671
+ * 同理 `docs/risk.json` 记了 44 个 App 的风控等级(带 forbid:["batch","pay"]),
672
+ * 但全库零引用 —— PLAYBOOK 里「L3 只读」只是散文,模型可以直接在微信/支付宝上
673
+ * 点发送转账,没有任何自动拦截。
674
+ *
675
+ * 这个工具把两件事变成机器可查的。
676
+ */
677
+
678
+ /**
679
+ * 按文字找位置 / 按文字点击。
680
+ *
681
+ * ## 为什么必须有
682
+ *
683
+ * 现在模型是「看 OCR 返回的一堆 nx/ny,自己挑一个坐标去点」——
684
+ * 实测存在一定点空率,主要原因是模型算坐标时会算错/挑错行。
685
+ *
686
+ * 这两个工具把「找文字 → 算坐标 → 点」变成一次调用,坐标由代码算,模型不用碰。
687
+ *
688
+ * ## 匹配规则
689
+ *
690
+ * 默认「包含」匹配(要找「蓝牙」,OCR 行的「蓝牙」或「蓝牙 已开启」都算命中)。
691
+ * 可以先精确匹配(exact),也可以正则(regex)。
692
+ * 多个命中时:默认取最靠上的(第一个),可以指定 nth。
693
+ */
694
+ export async function findText(args) {
695
+ const need = String(args?.text || '').trim();
696
+ if (!need) return { text: '要给要找的文字,比如「蓝牙」' };
697
+
698
+ // **不要先调 text()**:那会 OCR 一次,然后下面又 OCR 一次,
699
+ // 实测浪费 2 秒(4.2s vs 2.1s)。直接走下面的单次识别。
700
+ const st = await vd.status();
701
+ if (!st.running) return { text: '虚拟屏没在运行。先 vdisplay_start。' };
702
+ const ocr = await import('./ocr.js');
703
+ const shot = await vd.shot(String(args?.dir || '/tmp'), {
704
+ width: Math.min(1080, Math.max(360, st.width || 720)), format: 'png',
705
+ });
706
+ if (!shot.ok) return { text: `截图失败:${shot.hint}` };
707
+ // **必须传 hash**,否则 cacheKey 为 null、缓存对 find/tap_text 完全不生效 ——
708
+ // 而这两个正是循环里最常用的工具(对抗审查 + OCR 专项审查都指出)。
709
+ const rr = await ocr.recognize(shot.path, {
710
+ minConf: args?.minConf ?? 0.4,
711
+ maxLines: 200,
712
+ hash: args?.fresh ? null : shot.hash,
713
+ });
714
+ if (!rr.ok) return { text: rr.hint };
715
+
716
+ const mode = String(args?.mode || 'contains');
717
+ const rx = mode === 'regex' ? new RegExp(need) : null;
718
+ const hits = [];
719
+ for (const l of rr.lines) {
720
+ const t = String(l.text || '');
721
+ let hit = false;
722
+ if (mode === 'exact') hit = t.trim() === need;
723
+ else if (mode === 'regex') hit = rx.test(t);
724
+ else hit = t.includes(need) || need.includes(t.trim()) && t.trim().length > 0;
725
+ if (hit) hits.push(l);
726
+ }
727
+ if (!hits.length) {
728
+ const near = rr.lines
729
+ .map((l) => ({ l, d: levenshtein(need, String(l.text || '')) }))
730
+ .sort((a, b) => a.d - b.d)
731
+ .slice(0, 3)
732
+ .filter((x) => x.d <= Math.max(2, need.length));
733
+ const hint = near.length
734
+ ? '相近的有:' + near.map((x) => `「${x.l.text}」`).join('、')
735
+ : '屏幕上没找到相近文字';
736
+ return { text: `没找到「${need}」。${hint}`, found: 0 };
737
+ }
738
+
739
+ const W = shot.width || 720, H = shot.height || 1280;
740
+ const nth = Math.min(Math.max(0, Number(args?.nth) || 0), hits.length - 1);
741
+ const target = hits[nth];
742
+ const cx = (target.x + target.w / 2) / W;
743
+ const cy = (target.y + target.h / 2) / H;
744
+
745
+ const lines = [
746
+ `找到 ${hits.length} 处「${need}」,用第 ${nth + 1} 处:`,
747
+ ];
748
+ hits.slice(0, 5).forEach((l, i) => {
749
+ const x = ((l.x + l.w / 2) / W).toFixed(3);
750
+ const y = ((l.y + l.h / 2) / H).toFixed(3);
751
+ lines.push(` ${i === nth ? '→' : ' '} 「${l.text}」 nx=${x} ny=${y}`);
752
+ });
753
+ if (hits.length > 5) lines.push(` …还有 ${hits.length - 5} 处`);
754
+ lines.push('', `目标坐标:nx=${cx.toFixed(3)} ny=${cy.toFixed(3)}`);
755
+ lines.push('要直接点,用 vdisplay_tap_text(它会自己找坐标,不用你传)。');
756
+
757
+ return {
758
+ text: lines.join('\n'), found: hits.length, nx: cx, ny: cy,
759
+ label: String(target.text || ''),
760
+ // **把这张截图传出去给 tapText 复用。**
761
+ // tapText 原来自己又截一张(376ms),纯浪费 —— findText 刚刚才截过同一屏。
762
+ shotPath: shot.path, shotHash: shot.hash,
763
+ };
764
+ }
765
+
766
+ /**
767
+ * 找到文字并点它 —— 一次调用完成「找 → 算坐标 → 点 → 确认」。
768
+ *
769
+ * ## 为什么校验要自己重做,不能用 input() 返回的 changed
770
+ *
771
+ * 实测踩到:点「蓝牙」明明跳进了蓝牙设置页,但 `input()` 的画面哈希校验
772
+ * 报「画面在 2 秒内一直没有变化」—— **假失败**。
773
+ *
774
+ * 原因:`frameHash()` 用两次 screencap 比 SHA1,而页面跳转的转场时间
775
+ * 可能超过检查窗口,或者两次截图都截在转场前。
776
+ *
777
+ * 假失败比不校验更糟:调用方会重试 → 重复操作(点两次「购买」)。
778
+ *
779
+ * 所以这里改成**用 OCR 判断页面身份变了没有**:
780
+ * 点之前记一个屏指纹,点之后等一会儿再取一次,不同就算成功。
781
+ * 这个判据慢一点(多一次 OCR),但它判断的是「页面确实变了」,不是「像素闪了一下」。
782
+ */
783
+ export async function tapText(args) {
784
+ const r = await findText(args);
785
+ if (!r.found) return r;
786
+
787
+ // **点击前记画面指纹 —— 复用 findText 已经截过的那张图,不再单独截。**
788
+ // 原来这里额外调一次 vd.shot(160 宽),250-400ms;加上后面的固定 1.2 秒,
789
+ // tap_text 真实墙钟 4.2-6.2 秒(OCR 专项审查指出)。
790
+ const V = await import('./vision.js');
791
+ // **必须用同一种哈希。**
792
+ // findText 返回的 shotHash 是 shot() 算的 SHA1(40 位,整张 PNG 字节),
793
+ // 而下面 after 用的是 vision 的 dHash(16 位,9×8 灰度)—— 两种字符串永远不等,
794
+ // 于是 pageChanged 恒 true,**校验退化成返回常量 true**。
795
+ // 这是「防假成功的代码自己在造假成功」(独立复核发现,最讽刺也最危险的一条)。
796
+ // 正确做法:用同一张图的路径重新算 dHash 当基线。
797
+ let before = null;
798
+ if (r.shotPath) {
799
+ const fp0 = await V.dhash(r.shotPath);
800
+ before = fp0.ok ? fp0.hash : null;
801
+ }
802
+
803
+ const t = await input({
804
+ kind: 'tap', nx: r.nx, ny: r.ny,
805
+ verify: false, // 不用它的哈希校验(会假失败),下面自己做
806
+ shotAfter: false,
807
+ });
808
+
809
+ // **等一次就够,不要循环截图。**
810
+ // 我第一版写成「每 150ms 截一张比对」—— 每张截图 376ms,
811
+ // 循环三次就是 1.1 秒,反而比固定 1.2 秒还慢(实测 tapText 5.9 秒)。
812
+ // 改成:等 500ms(覆盖多数转场)→ 截一张 → 比一次。最多再补一次。
813
+ // 只后验一次:多数转场 500ms 内完成,截两次的第二次基本是白等。
814
+ let after = null;
815
+ await new Promise((res) => setTimeout(res, 500));
816
+ const g2 = await grabFullPng();
817
+ if (g2.ok) after = (await V.dhash(g2.path)).hash;
818
+ const pageChanged = !!(before && after && before !== after);
819
+ const tapOk = !/失败|不允许|不可用/.test(String(t.text || ''));
820
+
821
+ const verdict = !tapOk
822
+ ? '⚠️ 注入失败'
823
+ : pageChanged
824
+ ? '✅ 点了,页面已变化'
825
+ : '✅ 点了(页面没变化 —— 可能是开关类控件,或这个页面本来就该保持)';
826
+
827
+ return {
828
+ text: `${verdict}\n点击目标:「${r.label}」 nx=${r.nx.toFixed(3)} ny=${r.ny.toFixed(3)}\n`
829
+ + `画面:${pageChanged ? '变了' : '没变'}`,
830
+ clicked: tapOk,
831
+ pageChanged,
832
+ label: r.label,
833
+ nx: r.nx, ny: r.ny,
834
+ };
835
+ }
836
+
837
+ /** 编辑距离(用于「没找到」时给相近建议)。 */
838
+ function levenshtein(a, b) {
839
+ a = String(a); b = String(b);
840
+ if (!a.length) return b.length;
841
+ if (!b.length) return a.length;
842
+ let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
843
+ for (let i = 1; i <= a.length; i += 1) {
844
+ const cur = [i];
845
+ for (let j = 1; j <= b.length; j += 1) {
846
+ cur[j] = Math.min(
847
+ prev[j] + 1,
848
+ cur[j - 1] + 1,
849
+ prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
850
+ );
851
+ }
852
+ prev = cur;
853
+ }
854
+ return prev[b.length];
855
+ }
856
+
857
+
858
+ /* ═══════════════════════════════════════════════════════════════════════════
859
+ * **空闲看门狗:AI 不干活就把资源全放掉。**
860
+ *
861
+ * ## 为什么必须有
862
+ *
863
+ * 实机实测(2026-11-19):对话结束后虚拟屏+悬浮窗+framesrv 一直在跑,
864
+ * framesrv 持续 **10.3% CPU**,因为悬浮窗连着 MJPEG 长连接,
865
+ * framesrv 就认为「有人在看」,一直编码。
866
+ *
867
+ * 用户的原话:「dsh 引擎停了 ai 也会停,那还要后台屏一直开着干嘛?」
868
+ *
869
+ * 对。屏和推流唯一的用途是「给 AI 操作 + 给用户看」。AI 不调工具了,
870
+ * 就是没人需要它。留着纯烧电。
871
+ *
872
+ * ## 判据
873
+ *
874
+ * 每次工具调用都刷新 `lastToolCallAt`。看门狗每分钟检查一次:
875
+ * - 超过 IDLE_STOP_MS 没有任何工具调用 → 停推流(关悬浮窗 + framesrv)
876
+ * - 再超过 IDLE_DISPLAY_MS → 连虚拟屏一起销毁
877
+ *
878
+ * 为什么分两步:停推流是零风险的(屏还在,随时能再开);
879
+ * 销毁屏会丢掉屏上的 App 状态,所以多等一会儿。
880
+ *
881
+ * ## 不受影响的场景
882
+ *
883
+ * 用户主动调 vdisplay_stream / vdisplay_start 时也会刷新时间戳,
884
+ * 所以「用户想一直看」不会被打断 —— 只要有人调工具就活着。
885
+ */
886
+ // **超时时间由 AI 按任务预估设定**(1~360 分钟)。
887
+ // 用户的原话:「让 ai 自己判断这个任务需要使用多久后台屏,在 ai 不操作的情况下才开始计时,
888
+ // 一旦操作立刻重置计时」。
889
+ //
890
+ // 默认 5 分钟:绝大多数交互式任务每几分钟就会有工具调用,不会误关;
891
+ // 长任务(挂机/等待/轮询)由 AI 自己调大。
892
+ const IDLE_MIN_DEFAULT = 5;
893
+ const IDLE_MIN_FLOOR = 1; // 最少 1 分钟
894
+ const IDLE_MIN_CEIL = 360; // 最多 6 小时
895
+ let idleTimeoutMin = IDLE_MIN_DEFAULT;
896
+ let lastToolCallAt = Date.now();
897
+ let idleTimer = null;
898
+ let idleStoppedStream = false;
899
+ let idleStoppedDisplay = false;
900
+
901
+ /** 每次工具调用时调一下,重置空闲计时。 */
902
+ export function touchActivity() {
903
+ lastToolCallAt = Date.now();
904
+ idleStoppedStream = false;
905
+ idleStoppedDisplay = false;
906
+ }
907
+
908
+ /** 启动看门狗(插件加载时调一次)。 */
909
+ export function startIdleWatchdog() {
910
+ if (idleTimer) return;
911
+ idleTimer = setInterval(async () => {
912
+ const idle = Date.now() - lastToolCallAt;
913
+ const limitMs = idleTimeoutMin * 60 * 1000;
914
+ if (idle <= limitMs) return;
915
+ try {
916
+ // **到点:推流和屏一起关。**
917
+ // 先关推流(关悬浮窗 + framesrv,立刻省掉编码的 CPU),
918
+ // 再销毁屏(释放 ImageReader/镜像屏/端口)。
919
+ if (!idleStoppedStream) {
920
+ idleStoppedStream = true;
921
+ await import('./tools.js').then((m) => m.streamStop()).catch(() => {});
922
+ }
923
+ if (!idleStoppedDisplay) {
924
+ idleStoppedDisplay = true;
925
+ const vdMod = await import('./vd.js');
926
+ const st2 = await vdMod.status();
927
+ if (st2 && st2.running) {
928
+ await vdMod.stop({ forceStopApps: false }).catch(() => {});
929
+ }
930
+ }
931
+ try {
932
+ console.error('[dsh-screen] 空闲 ' + Math.round(idle / 60000) + ' 分钟(上限 ' + idleTimeoutMin + '),已自动关闭后台屏');
933
+ } catch { /* ignore */ }
934
+ } catch { /* 看门狗自己不能崩 */ }
935
+ }, 60 * 1000); // 每分钟检查一次
936
+ // 不阻止进程退出
937
+ if (idleTimer.unref) idleTimer.unref();
938
+ }
939
+
940
+ /**
941
+ * 设定「AI 停止操作多久后自动关掉后台屏」。
942
+ *
943
+ * @param {number} minutes 1~360 分钟
944
+ * @returns {{ok:boolean, minutes:number, hint?:string}}
945
+ */
946
+ export function setIdleTimeout(minutes) {
947
+ const n = Number(minutes);
948
+ if (!Number.isFinite(n)) return { ok: false, minutes: idleTimeoutMin, hint: '要给分钟数,比如 30' };
949
+ const clamped = Math.min(IDLE_MIN_CEIL, Math.max(IDLE_MIN_FLOOR, Math.round(n)));
950
+ idleTimeoutMin = clamped;
951
+ // 设置完立刻刷新计时,避免「刚设完就被判定空闲」
952
+ lastToolCallAt = Date.now();
953
+ idleStoppedStream = false;
954
+ idleStoppedDisplay = false;
955
+ return { ok: true, minutes: clamped };
956
+ }
957
+
958
+ /** 当前设定(给诊断用)。 */
959
+ export function getIdleTimeout() { return idleTimeoutMin; }
960
+
961
+ /** 停看门狗(插件卸载时用)。 */
962
+ export function stopIdleWatchdog() {
963
+ if (idleTimer) { clearInterval(idleTimer); idleTimer = null; }
964
+ }
965
+
966
+
967
+ /**
968
+ * 调整「AI 停止操作多久后自动关掉后台屏」。
969
+ *
970
+ * 长任务(挂机、等转盘、轮询消息)需要屏活久一点;
971
+ * 短任务(点几下就完)可以设短,省电更彻底。
972
+ *
973
+ * 任何工具调用都会重置计时,所以只要 AI 一直在操作,屏就不会被关。
974
+ */
975
+ export function keepAlive(args) {
976
+ const min = args?.minutes;
977
+ const r = setIdleTimeout(min);
978
+ if (!r.ok) {
979
+ return { text: `设置失败:${r.hint}。当前是 ${getIdleTimeout()} 分钟。` };
980
+ }
981
+ const lines = [
982
+ `✅ 后台屏空闲超时设为 **${r.minutes} 分钟**`,
983
+ '',
984
+ '含义:AI 连续 ' + r.minutes + ' 分钟没有调用任何工具 → 自动关闭推流 + 销毁虚拟屏。',
985
+ '任何工具调用都会重置计时,所以只要还在操作就不会被关。',
986
+ '',
987
+ `范围:1~360 分钟。当前设定:${getIdleTimeout()} 分钟。`,
988
+ ];
989
+ if (r.minutes === 360) lines.push('', '⚠️ 已设为上限 6 小时 —— 期间会持续占 CPU,确认真的需要这么久。');
990
+ return { text: lines.join('\n'), minutes: r.minutes };
991
+ }
992
+
993
+
994
+ /* ═══════════════ 视觉方法(OpenCV,常驻助手)═══════════════
995
+ *
996
+ * 这些工具之前完全没有 —— 只有 OCR(文字)和截图(给模型看)。
997
+ * 加了之后,「找没有文字的东西」终于有路了:
998
+ * 图标、开关、技能格、血条、准星、红心、返回箭头 …
999
+ *
1000
+ * 实测耗时(tests/CV-BENCHMARK-ARM.md,1592×720):
1001
+ * 模板匹配 5.7ms(温)/ 16-30ms(Node 往返)
1002
+ * 指纹 7ms、差分 2.3ms、颜色 6.8ms、边缘 0.7ms
1003
+ *
1004
+ * 对比 OCR 的 1600ms —— 快 100-280 倍。
1005
+ */
1006
+
1007
+ /**
1008
+ * 截一张原分辨率 PNG 给 CV 用(不缩放,缩放会丢模板精度)。
1009
+ *
1010
+ * **不要先调 vd.status()** —— 它内部又走一遍 alive()(2 次 dumpsys)+ 一次
1011
+ * dumpsys window displays,实测多花 ~250ms。vd.shot() 自己会做必要的检查。
1012
+ */
1013
+ async function grabFullPng() {
1014
+ // **零开销守卫:屏没建就直接返回,不能让 vd.shot() 静默建一块。**
1015
+ // vd.shot 第一行是 start(),displayId 为空时会完整建屏(1.8 秒)——
1016
+ // 一个只读探测工具(fingerprint/probe/diff)顺手建了一块屏还留着,
1017
+ // 再截到全黑空屏,用户完全不知道发生了什么(对抗审查 S16)。
1018
+ // 用 getActive() 而不是 status():后者要 3 次 dumpsys(约 250ms)。
1019
+ const st = vd.getActive();
1020
+ if (!st || !st.displayId) {
1021
+ return { ok: false, hint: '虚拟屏没在运行。先 vdisplay_start 建屏,再调这个工具。' };
1022
+ }
1023
+ const shot = await vd.shot('/tmp', { width: 1080, format: 'png' });
1024
+ if (!shot.ok) return { ok: false, hint: `截图失败:${shot.hint}` };
1025
+ return { ok: true, path: shot.path, width: shot.width, height: shot.height };
1026
+ }
1027
+
1028
+ /**
1029
+ * 模板匹配找图。**这是找「没有文字的东西」的唯一快路。**
1030
+ *
1031
+ * 用法:先 `vdisplay_shot` 看一眼,把目标图标的位置告诉 AI,
1032
+ * 或者 AI 自己截一小块存成模板文件,之后就能反复找。
1033
+ */
1034
+ export async function findImage(args) {
1035
+ const tpl = String(args?.template || '').trim();
1036
+ if (!tpl) return { text: '要给模板图路径(PNG/JPG)。先用 vdisplay_shot 截图,再裁出目标存成文件。' };
1037
+ const { existsSync } = await import('node:fs');
1038
+ if (!existsSync(tpl)) return { text: `模板文件不存在:${tpl}` };
1039
+
1040
+ const g = await grabFullPng();
1041
+ if (!g.ok) return { text: g.hint };
1042
+
1043
+ const V = await import('./vision.js');
1044
+ // **默认多尺度。**
1045
+ // 文档教的「vdisplay_shot 截图 → 裁出目标存 PNG」拿到的模板是 540 宽,
1046
+ // 而 find_image 走 PNG 原生 720 —— 模板小 25%,单尺度匹配分数从 0.8 掉到 0.45
1047
+ // 直接报「没找到」(实测:单尺度 0.454 找不到,多尺度 scale=1.3 得 0.796 找到)。
1048
+ // 这不是优化,是让文档教的做法真能用。
1049
+ const scales = Array.isArray(args?.scales) && args.scales.length
1050
+ ? args.scales.map(Number).filter((x) => x > 0)
1051
+ : [0.55, 0.65, 0.75, 0.85, 1.0, 1.15, 1.33, 1.5];
1052
+ const thr = Number.isFinite(Number(args?.threshold)) ? Number(args.threshold) : 0.75;
1053
+ const r = await V.match(g.path, tpl, {
1054
+ region: args?.region || null,
1055
+ threshold: thr,
1056
+ scales,
1057
+ });
1058
+ if (!r.ok) return { text: `模板匹配失败:${r.hint}` };
1059
+
1060
+ const lines = [
1061
+ r.found
1062
+ ? `✅ 找到目标(score ${r.score} ≥ 阈值 ${r.threshold})`
1063
+ : `❌ 没找到(最高分 ${r.score} < 阈值 ${r.threshold})`,
1064
+ `模板:${tpl}(内部标准差 ${r.tplStd},用 ${r.method})`,
1065
+ `位置:屏幕 (${r.x}, ${r.y}) 大小 ${r.w}×${r.h} → 中心 nx=${r.cx} ny=${r.cy}`,
1066
+ `耗时 ${r.elapsedMs}ms`,
1067
+ ];
1068
+ if (!r.found) {
1069
+ lines.push('', '可以试:① 调低 threshold(0.6-0.7)② 模板换成更清晰的一块 ③ 换用 OCR 找文字');
1070
+ } else {
1071
+ lines.push('', '要直接点它,用 vdisplay_tap_image(它会自己找再点)。');
1072
+ }
1073
+ return { text: lines.join('\n'), found: r.found, nx: r.cx, ny: r.cy, score: r.score };
1074
+ }
1075
+
1076
+ /**
1077
+ * 找到图并点它。
1078
+ *
1079
+ * **不能无条件报成功。** 原来传 verify:false 然后检查文本里有没有"失败",
1080
+ * 但 verify:false 时 input() 的文本恒为「已在 display=N 注入 tap」,
1081
+ * 永远不含"失败" → ok 恒 true。屏死、坐标出屏、控件不可点全报「✅ 已点击」,
1082
+ * AI 会以为点了购买/发送其实什么都没发生(对抗审查发现的 P0)。
1083
+ *
1084
+ * 现在照 tapText 的做法:点前后各取一次画面指纹,如实说变没变。
1085
+ */
1086
+ export async function tapImage(args) {
1087
+ const r = await findImage(args);
1088
+ if (!r.found) return r;
1089
+ const V = await import('./vision.js');
1090
+ const g1 = await grabFullPng();
1091
+ const before = g1.ok ? (await V.dhash(g1.path)).hash : null;
1092
+
1093
+ const t = await input({ kind: 'tap', nx: r.nx, ny: r.ny, verify: false });
1094
+ // **tools.input() 从不返回 ok 字段** —— 它所有返回路径都只有 {text}。
1095
+ // 所以 `t.ok !== false` 恒为 true(undefined !== false),注入失败也报 ✅。
1096
+ // 改成和 tapText 一致的文本判据。
1097
+ const injected = !/失败|不允许|不可用/.test(String(t.text || ''));
1098
+ await new Promise((res) => setTimeout(res, 900));
1099
+
1100
+ const g2 = await grabFullPng();
1101
+ const after = g2.ok ? (await V.dhash(g2.path)).hash : null;
1102
+ const pageChanged = !!(before && after && before !== after);
1103
+
1104
+ const verdict = !injected
1105
+ ? '⚠️ 注入失败'
1106
+ : pageChanged
1107
+ ? '✅ 点击已生效(画面变了)'
1108
+ : '✅ 已点击,但画面没变(可能是开关类控件,或这一下没打到可点的地方)';
1109
+ return {
1110
+ text: `${verdict}\n模板目标 nx=${r.nx} ny=${r.ny}(score ${r.score})\n画面:${pageChanged ? '变了' : '没变'}`,
1111
+ clicked: injected, pageChanged, nx: r.nx, ny: r.ny,
1112
+ };
1113
+ }
1114
+
1115
+ /**
1116
+ * 界面指纹(64 位 dHash)。
1117
+ *
1118
+ * 用途:判断「现在是不是那个界面」——比截图比对便宜得多(7ms vs 143ms),
1119
+ * 也比 OCR 可靠(不依赖文字)。
1120
+ */
1121
+ export async function fingerprint(args) {
1122
+ const g = await grabFullPng();
1123
+ if (!g.ok) return { text: g.hint };
1124
+ const V = await import('./vision.js');
1125
+ const r = await V.dhash(g.path);
1126
+ if (!r.ok) return { text: `指纹失败:${r.hint}` };
1127
+
1128
+ // 和上次的比,判断界面变了没
1129
+ const { readFile, writeFile } = await import('node:fs/promises');
1130
+ // **必须清洗 key**:原来直接用,传 "../../etc/passwd" 会写到 /etc/passwd.json
1131
+ // (root 下可写),读侧同样能读任意 .json 并回显内容。
1132
+ const key = String(args?.key || 'default').replace(/[^A-Za-z0-9_-]/g, '').slice(0, 32) || 'default';
1133
+ const store = '/tmp/dsh-fp-' + key + '.json';
1134
+ let prev = null;
1135
+ try { prev = JSON.parse(await readFile(store, 'utf8')); } catch { /* 没有上次 */ }
1136
+
1137
+ let dist = null;
1138
+ if (prev && prev.hash && /^[0-9a-f]{16}$/i.test(String(prev.hash))) {
1139
+ // 汉明距离(先校验格式,缓存文件被写坏时 BigInt 会抛 SyntaxError 冒到工具层)
1140
+ let d = 0;
1141
+ const a = BigInt('0x' + prev.hash), b = BigInt('0x' + r.hash);
1142
+ let x = a ^ b;
1143
+ while (x) { d += Number(x & 1n); x >>= 1n; }
1144
+ dist = d;
1145
+ }
1146
+ try { await writeFile(store, JSON.stringify({ hash: r.hash, at: Date.now() })); } catch { /* ignore */ }
1147
+
1148
+ const lines = [
1149
+ `界面指纹:${r.hash}(${r.w}×${r.h},${r.elapsedMs}ms)`,
1150
+ prev ? `上次:${prev.hash} → 汉明距离 ${dist} ${dist === 0 ? '(完全相同的界面)' : dist <= 10 ? '(同一界面,变了点细节)' : '(不同界面)'}` : '(第一次记录)',
1151
+ ];
1152
+ return { text: lines.join('\n'), hash: r.hash, distance: dist, changed: dist === null ? null : dist > 10 };
1153
+ }
1154
+
1155
+ /**
1156
+ * 两张截图的差异(MAD + maxCell)。
1157
+ *
1158
+ * **maxCell 是关键**:全局 MAD 会被大面积静态背景稀释,
1159
+ * 小区域变化(比如一个数字变了)MAD 可能只有 0.0012 但 maxCell 有 0.31。
1160
+ */
1161
+ export async function screenDiff(args) {
1162
+ const a = String(args?.before || '').trim();
1163
+ const g = await grabFullPng();
1164
+ if (!g.ok) return { text: g.hint };
1165
+ if (!a) {
1166
+ // 没有 before 就和上一张比
1167
+ const { readFile, writeFile } = await import('node:fs/promises');
1168
+ const store = '/tmp/dsh-lastshot.json';
1169
+ let prev = null;
1170
+ try { prev = JSON.parse(await readFile(store, 'utf8')); } catch { /* ignore */ }
1171
+ try { await writeFile(store, JSON.stringify({ path: g.path, at: Date.now() })); } catch { /* ignore */ }
1172
+ if (!prev || !prev.path) {
1173
+ return { text: `已记录当前画面(${g.path})。再调一次就能看差异。`, first: true };
1174
+ }
1175
+ args = { ...args, before: prev.path };
1176
+ }
1177
+
1178
+ const V = await import('./vision.js');
1179
+ const r = await V.diff(args.before, g.path);
1180
+ if (!r.ok) return { text: `差异计算失败:${r.hint}` };
1181
+ return {
1182
+ text: [
1183
+ `差异:MAD ${r.mad},最大格 ${r.maxCell}(在 ${r.maxCellAt.gx},${r.maxCellAt.gy} 格)`,
1184
+ `判定:${r.changed ? '画面有实质变化' : '画面基本没变'}`,
1185
+ `(MAD 会被大片静态背景稀释,小区域变化要看 maxCell)`,
1186
+ `耗时 ${r.elapsedMs}ms`,
1187
+ ].join('\n'),
1188
+ mad: r.mad, maxCell: r.maxCell, changed: r.changed,
1189
+ };
1190
+ }
1191
+
1192
+ /**
1193
+ * 探测当前界面适合用什么识别方法。
1194
+ *
1195
+ * 这是「按 App 自动选方法」的第一步:先量,再选。
1196
+ * 返回边缘密度、颜色可分性、亮度对比,据此判断:
1197
+ * 边缘密度 5-18% 且对比够 → 模板匹配可用
1198
+ * 颜色 top5 占比高且色数少 → 颜色/连通域可用
1199
+ * 看起来空白 → 可能 FLAG_SECURE 或没加载完
1200
+ */
1201
+ export async function probeScreen(args) {
1202
+ const g = await grabFullPng();
1203
+ if (!g.ok) return { text: g.hint };
1204
+ const V = await import('./vision.js');
1205
+ const r = await V.probe(g.path);
1206
+ if (!r.ok) return { text: `探测失败:${r.hint}` };
1207
+
1208
+ const recs = [];
1209
+ if (r.looksBlank) recs.push('⚠️ 画面接近空白 —— 可能是 FLAG_SECURE 或界面没加载完');
1210
+ if (r.canTemplate) recs.push('✅ 模板匹配可用(边缘 5-30%、对比够)');
1211
+ else recs.push('⚠️ 模板匹配可能不稳(边缘太密或太少)');
1212
+ if (r.canColor) recs.push('✅ 颜色/连通域可用(色块集中)');
1213
+ else recs.push('⚠️ 颜色方法可能不稳(颜色太杂)');
1214
+ recs.push('ℹ️ OCR 永远可用(文字是另一条路)');
1215
+
1216
+ return {
1217
+ text: [
1218
+ `界面 ${r.w}×${r.h},耗时 ${r.elapsedMs}ms`,
1219
+ `边缘密度 ${r.edgeDensity}(5-18% 适合形状检测)`,
1220
+ `颜色:top5 占比 ${r.colorTop5},色数 ${r.colorCount}(色数少才好用)`,
1221
+ `亮度 ${r.brightness},对比 ${r.contrast}`,
1222
+ '',
1223
+ ...recs,
1224
+ ].join('\n'),
1225
+ data: r,
1226
+ };
1227
+ }
1228
+
1229
+
1230
+ /**
1231
+ * 按颜色找色块(颜色阈值 + 连通域)。
1232
+ *
1233
+ * ## 能干什么
1234
+ *
1235
+ * 找**固定颜色**的东西:血条(红/绿)、按钮底色、选中状态的边框、
1236
+ * 小地图上的敌我点、进度条、生命值/魔法值条。
1237
+ *
1238
+ * **和模板匹配的分工**:
1239
+ * 模板匹配 → 形状固定但颜色会变的(图标)
1240
+ * 颜色检测 → 颜色固定但位置会变的(血条长度、小地图点位)
1241
+ *
1242
+ * ## 为什么必须用 Lab
1243
+ *
1244
+ * 实测踩过:用绝对 RGB 阈值,HDR 内容/不同色温下全部失效。
1245
+ * Lab 的 a/b 通道描述的是「色相」,和亮度解耦,色偏时仍然稳。
1246
+ *
1247
+ * 耗时:6.8ms(实测,tests/CV-BENCHMARK-ARM.md)。
1248
+ */
1249
+ export async function findColor(args) {
1250
+ const tgt = args?.color;
1251
+ if (!tgt) {
1252
+ return {
1253
+ text: '要给目标颜色。两种写法:\n'
1254
+ + ' {r:200,g:50,b:50} RGB(会自动转 Lab)\n'
1255
+ + ' {l:128,a:180,b:150} 直接给 Lab\n'
1256
+ + '先用 vdisplay_shot 看一眼,从图上取色。',
1257
+ };
1258
+ }
1259
+
1260
+ const g = await grabFullPng();
1261
+ if (!g.ok) return { text: g.hint };
1262
+
1263
+ const V = await import('./vision.js');
1264
+ const r = await V.color(g.path, tgt, {
1265
+ tolerance: args?.tolerance === undefined ? 20 : Number(args.tolerance),
1266
+ minArea: args?.minArea === undefined ? 200 : Number(args.minArea),
1267
+ max: args?.max === undefined ? 10 : Number(args.max),
1268
+ region: args?.region || null,
1269
+ });
1270
+ if (!r.ok) return { text: `颜色检测失败:${r.hint}` };
1271
+
1272
+ if (!r.count) {
1273
+ return {
1274
+ text: `没找到该颜色的色块(容差 ${args?.tolerance ?? 20})。\n`
1275
+ + '可以试:① 调大 tolerance(30-50)② 调小 minArea(50-100)③ 确认颜色值取对了',
1276
+ count: 0,
1277
+ };
1278
+ }
1279
+
1280
+ const lines = [`找到 ${r.count} 个色块(耗时 ${r.elapsedMs}ms):`];
1281
+ r.boxes.slice(0, 8).forEach((b, i) => {
1282
+ lines.push(` ${i + 1}. 位置 (${b.x},${b.y}) 大小 ${b.w}×${b.h} 面积 ${b.area}`
1283
+ + ` → 中心 nx=${b.cx} ny=${b.cy}`);
1284
+ });
1285
+ if (r.count > 8) lines.push(` …还有 ${r.count - 8} 个`);
1286
+ lines.push('', '最大的那个通常是目标(比如血条)。要点它用坐标或 vdisplay_input。');
1287
+ return { text: lines.join('\n'), count: r.count, boxes: r.boxes, biggest: r.boxes[0] };
1288
+ }
1289
+
1290
+ /** 找颜色并点最大的那个色块。校验同 tapImage —— 不能无条件报成功。 */
1291
+ export async function tapColor(args) {
1292
+ const r = await findColor(args);
1293
+ if (!r.count) return r;
1294
+ const b = r.biggest;
1295
+ const V = await import('./vision.js');
1296
+ const g1 = await grabFullPng();
1297
+ const before = g1.ok ? (await V.dhash(g1.path)).hash : null;
1298
+
1299
+ const t = await input({ kind: 'tap', nx: b.cx, ny: b.cy, verify: false });
1300
+ const injected = !/失败|不允许|不可用/.test(String(t.text || ''));
1301
+ await new Promise((res) => setTimeout(res, 900));
1302
+
1303
+ const g2 = await grabFullPng();
1304
+ const after = g2.ok ? (await V.dhash(g2.path)).hash : null;
1305
+ const pageChanged = !!(before && after && before !== after);
1306
+
1307
+ const verdict = !injected
1308
+ ? '⚠️ 注入失败'
1309
+ : pageChanged
1310
+ ? '✅ 点击已生效(画面变了)'
1311
+ : '✅ 已点击,但画面没变(可能不是可点区域)';
1312
+ return {
1313
+ text: `${verdict}\n色块 ${b.w}×${b.h} 中心 nx=${b.cx} ny=${b.cy}\n画面:${pageChanged ? '变了' : '没变'}`,
1314
+ clicked: injected, pageChanged, nx: b.cx, ny: b.cy,
1315
+ };
1316
+ }
1317
+
1318
+ /**
1319
+ * 自动判断当前界面该用什么识别方法,并给出建议顺序。
1320
+ *
1321
+ * ## 为什么需要
1322
+ *
1323
+ * 现在工具多了(OCR / 模板 / 颜色 / 指纹 / 差分),模型不知道该用哪个。
1324
+ * 这个工具**先量再选**,把「用哪个」变成数据驱动的决定,不是猜。
1325
+ *
1326
+ * ## 判据(都来自实测数据)
1327
+ *
1328
+ * | 界面特征 | 推荐方法 | 依据 |
1329
+ * |---|---|---|
1330
+ * | 边缘密度 5-18% + 对比够 | **模板匹配** | 5.7ms,形状清晰 |
1331
+ * | 颜色 top5 占比 >35% + 色数 <260 | **颜色检测** | 6.8ms,色块集中 |
1332
+ * | 文字多(跑一次 OCR 探)| **OCR / find_text** | 唯一能读文字的 |
1333
+ * | 画面接近空白 | **先怀疑 FLAG_SECURE 或没加载完** | std < 3 |
1334
+ *
1335
+ * ## 结果会缓存
1336
+ *
1337
+ * 同一个界面(用 dHash 判断)第二次问直接返回缓存,省掉探测的 100ms。
1338
+ */
1339
+ export async function chooseMethod(args) {
1340
+ const { readFile, writeFile, mkdir } = await import('node:fs/promises');
1341
+ const { homedir } = await import('node:os');
1342
+ const { join } = await import('node:path');
1343
+ const cacheDir = join(homedir(), '.dsh', 'plugin-screen');
1344
+ const cacheFile = join(cacheDir, 'method-cache.json');
1345
+
1346
+ const g = await grabFullPng();
1347
+ if (!g.ok) return { text: g.hint };
1348
+
1349
+ const V = await import('./vision.js');
1350
+ const fp = await V.dhash(g.path);
1351
+ const pr = await V.probe(g.path);
1352
+ if (!pr.ok) return { text: `探测失败:${pr.hint}` };
1353
+
1354
+ // 读缓存
1355
+ let cache = {};
1356
+ try { cache = JSON.parse(await readFile(cacheFile, 'utf8')); } catch { /* 没有缓存 */ }
1357
+
1358
+ const key = String(args?.key || 'default') + '|' + fp.hash;
1359
+ const cached = cache[key];
1360
+ if (cached && !args?.fresh) {
1361
+ return {
1362
+ text: [
1363
+ `✅ 这个界面见过(指纹 ${fp.hash}),直接用上次的结论:`,
1364
+ '',
1365
+ ...cached.methods.map((m, i) => ` ${i + 1}. ${m.tool} —— ${m.why}`),
1366
+ '',
1367
+ `(要重新探测传 fresh:true)`,
1368
+ ].join('\n'),
1369
+ methods: cached.methods, cached: true,
1370
+ };
1371
+ }
1372
+
1373
+ // 打分
1374
+ const methods = [];
1375
+ if (pr.looksBlank) {
1376
+ methods.push({ tool: 'vdisplay_probe_secure', why: '画面近空白,先确认是不是 FLAG_SECURE', score: 100 });
1377
+ }
1378
+ if (pr.canTemplate) {
1379
+ methods.push({ tool: 'vdisplay_find_image', why: `边缘密度 ${(pr.edgeDensity * 100).toFixed(1)}%、对比 ${pr.contrast},模板匹配 5.7ms 最划算`, score: 90 });
1380
+ }
1381
+ if (pr.canColor) {
1382
+ methods.push({ tool: 'vdisplay_find_color', why: `颜色 top5 占比 ${(pr.colorTop5 * 100).toFixed(0)}%、色数 ${pr.colorCount},色块集中适合颜色检测`, score: 85 });
1383
+ }
1384
+ methods.push({ tool: 'vdisplay_text', why: 'OCR 永远可用 —— 文字是唯一能「读懂内容」的路(1.9-3.3s)', score: 60 });
1385
+ methods.push({ tool: 'vdisplay_fingerprint', why: '判断「还是不是同一屏」用指纹,7ms,不依赖内容', score: 50 });
1386
+ methods.sort((a, b) => b.score - a.score);
1387
+
1388
+ // 写缓存
1389
+ try {
1390
+ await mkdir(cacheDir, { recursive: true });
1391
+ cache[key] = { methods, at: Date.now(), stats: { edge: pr.edgeDensity, top5: pr.colorTop5, colors: pr.colorCount, contrast: pr.contrast } };
1392
+ // 只留最近 100 条
1393
+ const keys = Object.keys(cache);
1394
+ if (keys.length > 100) for (const k of keys.slice(0, keys.length - 100)) delete cache[k];
1395
+ await writeFile(cacheFile, JSON.stringify(cache));
1396
+ } catch { /* 写不进去不影响 */ }
1397
+
1398
+ return {
1399
+ text: [
1400
+ `界面 ${pr.w}×${pr.h},指纹 ${fp.hash}(新界面,已缓存)`,
1401
+ `边缘密度 ${(pr.edgeDensity * 100).toFixed(1)}% 颜色 top5 ${(pr.colorTop5 * 100).toFixed(0)}% 色数 ${pr.colorCount} 对比 ${pr.contrast}`,
1402
+ '',
1403
+ '推荐的识别方法(按性价比):',
1404
+ ...methods.map((m, i) => ` ${i + 1}. ${m.tool}\n ${m.why}`),
1405
+ '',
1406
+ '要点按优先用 vdisplay_tap_text(有文字)或 vdisplay_tap_image(有图标)。',
1407
+ ].join('\n'),
1408
+ methods, cached: false, fingerprint: fp.hash,
1409
+ };
1410
+ }
1411
+
1412
+
1413
+ /**
1414
+ * 条件等待 —— 替代所有「固定等 2 秒再截图」。
1415
+ *
1416
+ * ## 为什么这是最高价值的一个
1417
+ *
1418
+ * 现在每个操作之后都是固定 sleep,然后截图。实测:
1419
+ * - 固定等 2 秒 + OCR 2-3 秒 = 每步 4-5 秒
1420
+ * - 门控等待(7ms 指纹先看变没变,变了才 OCR)= 多数 150-400ms
1421
+ *
1422
+ * `cheapFirst` 是核心:先用 7ms 的 dHash 判断画面变没变,
1423
+ * **只有真变了才跑 OCR**。等待类操作的绝大多数时间都省在这里。
1424
+ *
1425
+ * ## 支持的判据
1426
+ *
1427
+ * text_appears —— 出现某段文字(OCR,慢但准)
1428
+ * text_gone —— 某段文字消失
1429
+ * fingerprint_is —— 指纹等于某值(7ms,最快)
1430
+ * fingerprint_changes —— 指纹和开始时不同(7ms)
1431
+ * diff_gt —— 画面变化超过阈值(2.3ms)
1432
+ * color_present —— 出现某个颜色(6.8ms)
1433
+ * stable —— 连续 N 次画面不变(转场结束)
1434
+ */
1435
+ export async function waitFor(args) {
1436
+ const until = String(args?.until || '').trim();
1437
+ const timeoutMs = Math.min(30000, Math.max(200, Number(args?.timeoutMs) || 8000));
1438
+ const pollMs = Math.min(2000, Math.max(50, Number(args?.pollMs) || 150));
1439
+ const cheapFirst = args?.cheapFirst !== false;
1440
+ const text = String(args?.text || '');
1441
+ const t0 = Date.now();
1442
+
1443
+ const st = vd.getActive();
1444
+ if (!st || !st.displayId) return { text: '虚拟屏没在运行。先 vdisplay_start。' };
1445
+
1446
+ const V = await import('./vision.js');
1447
+ const grab = async () => {
1448
+ const g = await grabFullPng();
1449
+ if (!g.ok) return null;
1450
+ return g.path;
1451
+ };
1452
+
1453
+ // 基线指纹
1454
+ let baseHash = null;
1455
+ const p0 = await grab();
1456
+ if (p0) baseHash = (await V.dhash(p0)).hash;
1457
+
1458
+ const targetHash = String(args?.hash || '') || null;
1459
+ let stableCount = 0;
1460
+ let lastHash = null;
1461
+ let polls = 0;
1462
+ let ocrRuns = 0;
1463
+
1464
+ while (Date.now() - t0 < timeoutMs) {
1465
+ polls += 1;
1466
+ const path = await grab();
1467
+ if (!path) { await new Promise((r) => setTimeout(r, pollMs)); continue; }
1468
+ const h = (await V.dhash(path)).hash;
1469
+
1470
+ // ── 便宜判据,先用 ──
1471
+ if (until === 'fingerprint_is' && targetHash) {
1472
+ if (h === targetHash) return ok('指纹已匹配');
1473
+ } else if (until === 'fingerprint_changes') {
1474
+ if (baseHash && h !== baseHash) return ok('画面已变化(指纹变了)');
1475
+ } else if (until === 'stable') {
1476
+ if (h === lastHash) { stableCount += 1; } else { stableCount = 0; lastHash = h; }
1477
+ if (stableCount >= (Number(args?.stableTimes) || 2)) return ok('画面已稳定');
1478
+ } else if (until === 'diff_gt') {
1479
+ const d = await V.diff(path, path); // 占位,下面用 baseHash 判
1480
+ if (baseHash && h !== baseHash) {
1481
+ const d2 = await V.diff(p0, path);
1482
+ if (d2.ok && (d2.maxCell >= (Number(args?.threshold) || 0.15))) return ok(`变化 ${d2.maxCell} 超过阈值`);
1483
+ }
1484
+ } else if (until === 'color_present') {
1485
+ const c = await V.color(path, args?.color || { r: 255, g: 0, b: 0 }, {
1486
+ tolerance: Number(args?.tolerance) || 30,
1487
+ minArea: Number(args?.minArea) || 300,
1488
+ region: args?.region || null,
1489
+ });
1490
+ if (c.ok && c.count > 0) return ok(`找到 ${c.count} 个该颜色色块`);
1491
+ } else if (until === 'text_appears' || until === 'text_gone') {
1492
+ // **cheapFirst:画面没变就不跑 OCR**
1493
+ // 这是省时间的关键 —— 等待期间画面多数时候是静止的。
1494
+ const changed = baseHash && h !== baseHash;
1495
+ if (cheapFirst && !changed && polls > 2) {
1496
+ await new Promise((r) => setTimeout(r, pollMs));
1497
+ continue;
1498
+ }
1499
+ const ocr = await import('./ocr.js');
1500
+ const rr = await ocr.recognize(path, { minConf: 0.4, maxLines: 200, hash: h });
1501
+ if (!rr.ok) { await new Promise((r) => setTimeout(r, pollMs)); continue; }
1502
+ ocrRuns += 1;
1503
+ const hit = rr.lines.some((l) => String(l.text || '').includes(text));
1504
+ if (until === 'text_appears' && hit) return ok(`「${text}」已出现`);
1505
+ if (until === 'text_gone' && !hit && text) return ok(`「${text}」已消失`);
1506
+ if (hit) baseHash = h; // 已出现但等它消失时,把基线滑过去
1507
+ } else {
1508
+ return { text: `不认识的 until「${until}」。可用:text_appears / text_gone / fingerprint_is / fingerprint_changes / diff_gt / color_present / stable` };
1509
+ }
1510
+
1511
+ await new Promise((r) => setTimeout(r, pollMs));
1512
+ }
1513
+
1514
+ return {
1515
+ text: `⏱ ${Math.round((Date.now() - t0) / 1000)} 秒内没等到「${until}」`
1516
+ + (text ? `(${text})` : '')
1517
+ + `\n轮询 ${polls} 次,跑了 ${ocrRuns} 次 OCR`
1518
+ + (cheapFirst ? '(cheapFirst 生效:画面没变就跳过 OCR)' : '')
1519
+ + '\n可以:① 加长 timeoutMs ② 换判据 ③ 直接截图看看现在是什么',
1520
+ ok: false, elapsedMs: Date.now() - t0, polls, ocrRuns,
1521
+ };
1522
+
1523
+ function ok(why) {
1524
+ return {
1525
+ text: `✅ ${why}(等了 ${Date.now() - t0}ms,轮询 ${polls} 次`
1526
+ + (ocrRuns ? `,OCR ${ocrRuns} 次` : ',没跑 OCR') + ')',
1527
+ ok: true, elapsedMs: Date.now() - t0, polls, ocrRuns,
1528
+ };
1529
+ }
1530
+ }
1531
+
1532
+
1533
+ /* ═══════════════════════════════════════════════════════════════
1534
+ * 用户事件(悬浮窗 → AI)
1535
+ *
1536
+ * 用户在悬浮窗上「拖到滑轨右端删除」某块后台屏时,overlay 会调
1537
+ * framesrv 的 /event?type=user_deleted,写一行到
1538
+ * /data/local/tmp/dshframe/events.log
1539
+ *
1540
+ * 这里把它读出来,附在工具返回里 —— 这样 AI 就知道
1541
+ * 「用户手动关了我的后台屏,可能是我影响了他操作」。
1542
+ * ═══════════════════════════════════════════════════════════════ */
1543
+
1544
+ const EVENTS_REMOTE = '/data/local/tmp/dshframe/events.log';
1545
+ const EVENTS_SEEN_FILE = 'user-events-seen.txt';
1546
+ let userEventsWarned = [];
1547
+
1548
+ /** 读新出现的用户事件(只看上次之后的新条目)。 */
1549
+ export async function pollUserEvents() {
1550
+ try {
1551
+ const { execFile } = await import('node:child_process');
1552
+ const { promisify } = await import('node:util');
1553
+ const { readFile, writeFile, mkdir } = await import('node:fs/promises');
1554
+ const { homedir } = await import('node:os');
1555
+ const { join } = await import('node:path');
1556
+ const run = promisify(execFile);
1557
+ const target = await adbTarget();
1558
+
1559
+ const r = await run('adb', ['-s', target, 'shell', `cat ${EVENTS_REMOTE} 2>/dev/null`],
1560
+ { timeout: 6000, maxBuffer: 1 << 20 }).catch(() => ({ stdout: '' }));
1561
+ const raw = String(r.stdout || '').trim();
1562
+ if (!raw) return [];
1563
+
1564
+ const dir = join(homedir(), '.dsh', 'plugin-screen');
1565
+ const seenPath = join(dir, EVENTS_SEEN_FILE);
1566
+ let lastSeen = 0;
1567
+ try { lastSeen = Number(await readFile(seenPath, 'utf8')) || 0; } catch { /* 第一次 */ }
1568
+
1569
+ const fresh = [];
1570
+ let maxTs = lastSeen;
1571
+ for (const lineText of raw.split('\n')) {
1572
+ const parts = lineText.split('|');
1573
+ if (parts.length < 3) continue;
1574
+ const ts = Number(parts[0]) || 0;
1575
+ if (ts <= lastSeen) continue;
1576
+ if (ts > maxTs) maxTs = ts;
1577
+ /* **必须把 stopScreen 也带出来。**
1578
+ * 2026-11-21 对抗审查抓到:浮窗写 `ts|type|displayId|stopScreen=N`,
1579
+ * 这里只取前 3 段 → stopScreen 被丢掉 → AI 分不清用户是
1580
+ * 「只关浮窗」(嫌挡路,活可能还要继续)还是「连屏一起停」(明确要求停手)。
1581
+ */
1582
+ let stopScreen = false;
1583
+ for (let k = 3; k < parts.length; k++) {
1584
+ if (parts[k].startsWith('stopScreen=')) stopScreen = parts[k].endsWith('=1');
1585
+ }
1586
+ fresh.push({ ts, type: parts[1], displayId: parts[2], stopScreen });
1587
+ }
1588
+ if (!fresh.length) return [];
1589
+
1590
+ try { await mkdir(dir, { recursive: true }); await writeFile(seenPath, String(maxTs)); } catch { /* ignore */ }
1591
+ return fresh;
1592
+ } catch {
1593
+ return [];
1594
+ }
1595
+ }
1596
+
1597
+ /** 把用户事件格式化成给 AI 看的提示。 */
1598
+ export function formatUserEvents(events) {
1599
+ if (!events || !events.length) return '';
1600
+ const lines = [];
1601
+ for (const e of events) {
1602
+ if (e.type === 'user_deleted') {
1603
+ lines.push(
1604
+ `⚠️ **用户手动关闭了 displayId=${e.displayId} 的后台屏。**`,
1605
+ '这通常意味着你的操作影响到了用户 —— 请先确认:',
1606
+ ' · 是不是抢了他的前台/键盘?(用 screen_user_state 查)',
1607
+ ' · 是不是那块屏上的 App 他被顶掉了?',
1608
+ ' · 是不是悬浮窗挡住了他要点的地方?',
1609
+ '**不要自动重建那块屏**,先问用户要不要继续。',
1610
+ );
1611
+ } else {
1612
+ lines.push(`⚠️ 用户事件:${e.type}(displayId=${e.displayId})`);
1613
+ }
1614
+ }
1615
+ return lines.join('\n');
1616
+ }
1617
+
1618
+ export async function userState() {
1619
+ const target = await adbTarget();
1620
+ const run = (cmd) => new Promise((resolve) => {
1621
+ import('node:child_process').then(({ execFile }) => {
1622
+ execFile('adb', ['-s', target, 'shell', cmd], { timeout: 8000 }, (e, out) => {
1623
+ resolve(String(out || ''));
1624
+ });
1625
+ });
1626
+ });
1627
+
1628
+ const [front, ime] = await Promise.all([
1629
+ run("dumpsys activity activities 2>/dev/null | grep -m1 topResumedActivity"),
1630
+ run("dumpsys input_method 2>/dev/null | grep -m1 mInputShown"),
1631
+ ]);
1632
+
1633
+ // 前台包名
1634
+ let frontPkg = '';
1635
+ const m = front.match(/([a-zA-Z][\w.]*)\/[\w.]*/);
1636
+ if (m) frontPkg = m[1];
1637
+
1638
+ const imeShown = /mInputShown=true/.test(ime);
1639
+ const dshFg = /dsh_app|ccch1mneyyy/.test(front);
1640
+
1641
+ // 判据:DSH Go 在前台 或 输入法挂着 → 用户在用
1642
+ const busey = dshFg || imeShown;
1643
+ const reasons = [];
1644
+ if (dshFg) reasons.push('DSH Go 在前台(用户正在跟 AI 对话)');
1645
+ if (imeShown) reasons.push('输入法正在显示(用户可能在打字)');
1646
+
1647
+ // **先查有没有「用户手动关了后台屏」这类事件**
1648
+ let evText = '';
1649
+ try {
1650
+ const evs = await pollUserEvents();
1651
+ evText = formatUserEvents(evs);
1652
+ } catch { /* ignore */ }
1653
+
1654
+ const lines = [
1655
+ busey ? '🔴 用户正在用手机 —— 不要抢前台/抢键盘' : '🟢 用户没在用手机,可以操作',
1656
+ '',
1657
+ `前台 App:${frontPkg || '(查不到)'}`,
1658
+ `输入法:${imeShown ? '显示中' : '收起'}`,
1659
+ ];
1660
+ if (reasons.length) {
1661
+ lines.push('', '判据命中:', ...reasons.map((r) => ` · ${r}`));
1662
+ lines.push('', '如果要操作主屏(am start / mcp__phone__type / input text),建议改走:',
1663
+ ' · 虚拟屏(vdisplay_*)—— 不碰用户前台',
1664
+ ' · 浏览器 CDP(web_*)—— 不抢焦点',
1665
+ ' · 或等用户停下来');
1666
+ }
1667
+ return {
1668
+ text: (evText ? evText + '\n\n' : '') + lines.join('\n'),
1669
+ busy: busey, frontPkg, imeShown,
1670
+ userEvents: userEventsWarned,
1671
+ };
1672
+ }
1673
+
1674
+ /** 查某个包的风控等级(读 docs/risk.json)。 */
1675
+ export async function riskCheck(pkg) {
1676
+ const name = String(pkg || '').trim();
1677
+ if (!name) return { text: '要给包名,比如 com.tencent.mm' };
1678
+ let data = null;
1679
+ try {
1680
+ const { readFile } = await import('node:fs/promises');
1681
+ const { fileURLToPath } = await import('node:url');
1682
+ const { dirname, join } = await import('node:path');
1683
+ const here = dirname(fileURLToPath(import.meta.url));
1684
+ for (const rel of ['../docs/risk.json', '../../docs/risk.json']) {
1685
+ try {
1686
+ const raw = await readFile(join(here, rel), 'utf8');
1687
+ data = JSON.parse(raw);
1688
+ break;
1689
+ } catch { /* 试下一个 */ }
1690
+ }
1691
+ } catch { /* ignore */ }
1692
+ if (!data) return { text: '读不到 docs/risk.json(插件没带这个文件?)' };
1693
+
1694
+ const apps = data.apps || data;
1695
+ const info = apps[name];
1696
+ if (!info) {
1697
+ return {
1698
+ text: `未知 App(${name})→ 按默认 L${data.unknown_level ?? 3} 处理:先只读观察,写操作前问用户。`,
1699
+ level: data.unknown_level ?? 3,
1700
+ name: '',
1701
+ };
1702
+ }
1703
+ const LEVELS = {
1704
+ 0: 'L0 无风控 —— 随便操作',
1705
+ 1: 'L1 轻微 —— 控制频率即可',
1706
+ 2: 'L2 中等 —— 操作要拟人化',
1707
+ 3: 'L3 严格 —— 只读,写操作必须问用户',
1708
+ 4: 'L4 禁止 —— 银行/支付,只能交给人',
1709
+ 5: 'L5 硬边界 —— 技术上也做不到',
1710
+ };
1711
+ const lines = [
1712
+ `${info.name || name}:${LEVELS[info.level] || ('L' + info.level)}`,
1713
+ `包名:${name}`,
1714
+ ];
1715
+ if (info.readOnly) lines.push('⚠️ 标记为只读:不要点任何会改变状态的东西');
1716
+ if (Array.isArray(info.forbid) && info.forbid.length) {
1717
+ lines.push(`⚠️ 禁止动作:${info.forbid.join('、')}`);
1718
+ }
1719
+ return { text: lines.join('\n'), level: info.level, name: info.name || name, forbid: info.forbid || [] };
1720
+ }
1721
+
1722
+ export async function apps() {
1723
+ const r = await vd.adb(['shell', 'pm list packages -3 2>/dev/null']);
1724
+ if (!r.ok) return { text: `列应用失败:${r.err || 'adb 不可用'}` };
1725
+ const pkgs = String(r.out || '')
1726
+ .split('\n')
1727
+ .map((l) => l.trim().replace(/^package:/, ''))
1728
+ .filter(Boolean)
1729
+ .sort();
1730
+ if (!pkgs.length) return { text: '没读到第三方 App。确认 adb 连着、且设备不是空的。' };
1731
+ return {
1732
+ text: `第三方 App 共 ${pkgs.length} 个(用包名调 vdisplay_launch):\n`
1733
+ + pkgs.map((p) => ` ${p}`).join('\n'),
1734
+ };
1735
+ }
1736
+
1737
+ /* ===== 多屏池 ===== */
1738
+
1739
+ export async function poolInfo() {
1740
+ const pool = await import('./pool.js');
1741
+ const info = pool.info();
1742
+ if (!info.count) {
1743
+ return { text: '池里还没有屏。用 screen_new 建一块。' };
1744
+ }
1745
+ const lines = [`共 ${info.count} 块屏,活动屏:${info.active || '(无)'}`, ''];
1746
+ for (const s of info.screens) {
1747
+ const mark = s.screenId === info.active ? ' ← 活动' : '';
1748
+ lines.push(` ${s.screenId} displayId=${s.displayId} dpi=${s.dpi}${mark}`);
1749
+ }
1750
+ lines.push('');
1751
+ lines.push('所有 vdisplay_* 操作都作用在活动屏上。切换用 screen_use。');
1752
+ return { text: lines.join('\n') };
1753
+ }
1754
+
1755
+ export async function newScreen(args) {
1756
+ const pool = await import('./pool.js');
1757
+ const r = await pool.create({
1758
+ orientation: args?.orientation,
1759
+ hwc: args?.hwc,
1760
+ });
1761
+ if (!r.ok) return { text: `建屏失败:${r.hint}` };
1762
+
1763
+ const lines = [
1764
+ `新屏已建好:${r.screenId}(displayId=${r.displayId},dpi=${r.dpi})`,
1765
+ `它现在是活动屏,接下来 vdisplay_launch 会投到它上面。`,
1766
+ ];
1767
+
1768
+ // **屏幕池的屏也要有自己的推流和悬浮窗。**
1769
+ // 用户的要求:「开多少个就带多少个悬浮窗起来」。
1770
+ // 原来 newScreen 完全不启动推流 → 池里的屏用户看不见(只有 vdisplay_start 才有窗口)。
1771
+ // overlay:false 可以显式关掉(用户说「喊 ai 不启动悬浮窗」)。
1772
+ if (args?.overlay !== false) {
1773
+ try {
1774
+ const r2 = await streamStart({ displayId: r.displayId, sfId: r.sfId, overlay: true });
1775
+ const t = String(r2?.text || '');
1776
+ if (/悬浮窗已浮起/.test(t)) lines.push('✅ 这块屏的悬浮窗已浮起(多屏会按级联位置错开)');
1777
+ else lines.push('⚠️ 推流:' + t.split('\n').slice(0, 2).join(' '));
1778
+ } catch (e) {
1779
+ lines.push('⚠️ 自动推流失败:' + String(e?.message || e).slice(0, 60));
1780
+ }
1781
+ } else {
1782
+ lines.push('(按你的要求没有起悬浮窗;要看画面用 vdisplay_stream)');
1783
+ }
1784
+ lines.push(`想切回别的屏用 screen_use。`);
1785
+ return { text: lines.join('\n') };
1786
+ }
1787
+
1788
+ export async function useScreen(args) {
1789
+ const pool = await import('./pool.js');
1790
+ const r = pool.use(String(args?.screenId || ''));
1791
+ if (!r.ok) return { text: r.hint };
1792
+ return { text: `已切到 ${args.screenId}(displayId=${r.displayId})。之后的操作都作用在这块屏上。` };
1793
+ }
1794
+
1795
+ export async function closeScreen(args) {
1796
+ const pool = await import('./pool.js');
1797
+ const id = String(args?.screenId || '');
1798
+ const r = await pool.destroy(id, { forceStopApps: args?.forceStopApps === true });
1799
+ if (!r.ok) return { text: r.hint };
1800
+ return { text: `已销毁 ${id}。池里还剩 ${r.remaining} 块。` };
1801
+ }
1802
+
1803
+ export async function checkApp(args) {
1804
+ const pkg = String(args?.pkg || '').trim();
1805
+ if (!/^[a-z][\w.]*$/i.test(pkg)) return { text: 'pkg 看起来不是合法包名。用 vdisplay_apps 查。' };
1806
+ const occ = await import('./occupancy.js');
1807
+ const pool = await import('./pool.js');
1808
+ // 把池里的屏 id 传给检测器,它才能区分「我们的屏」和「外来屏」
1809
+ const info = pool.info();
1810
+ const ourScreens = new Map(info.screens.map((s) => [Number(s.displayId), s.screenId]));
1811
+ const r = await occ.checkApp(pkg, { ourScreens });
1812
+ return { text: occ.describe(r) };
1813
+ }
1814
+
1815
+ /* ===== 租约 ===== */
1816
+
1817
+ export async function claimApp(args) {
1818
+ const lease = await import('./lease.js');
1819
+ const pkg = String(args?.pkg || '').trim();
1820
+ if (!/^[a-z][\w.]*$/i.test(pkg)) return { text: 'pkg 看起来不是合法包名。用 vdisplay_apps 查。' };
1821
+ const pool = await import('./pool.js');
1822
+ const info = pool.info();
1823
+ if (!info.active) return { text: '还没有活动屏。先 screen_new 建一块。' };
1824
+
1825
+ const r = await lease.claim({
1826
+ pkg,
1827
+ screenId: info.active,
1828
+ owner: String(args?.owner || 'this-session'),
1829
+ mode: args?.mode,
1830
+ priority: args?.priority,
1831
+ preemptible: args?.preemptible,
1832
+ nonPreemptibleReason: args?.nonPreemptibleReason,
1833
+ onConflict: args?.onConflict || 'fail',
1834
+ ttlMs: args?.ttlSec ? Number(args.ttlSec) * 1000 : undefined,
1835
+ });
1836
+
1837
+ if (r.ok) {
1838
+ const l = r.lease;
1839
+ const lines = [`已占用「${l.pkg}」→ ${l.screenId}(${l.leaseId},还剩 ${l.remainingSec} 秒)`];
1840
+ if (!l.preemptible) lines.push(` 标记为不可抢${l.nonPreemptibleReason ? `:${l.nonPreemptibleReason}` : ''}`);
1841
+ if (r.preempted) lines.push(` 接管自 ${r.preempted.owner}`);
1842
+ if (r.note) lines.push(` ${r.note}`);
1843
+ return { text: lines.join('\n') };
1844
+ }
1845
+ return {
1846
+ text: `${r.hint}\n${r.holder ? `原持有者:${r.holder.owner}(${r.holder.screenId},还剩 ${r.holder.remainingSec} 秒)` : ''}`
1847
+ + (r.next?.action ? `\n建议:${r.next.action}` : ''),
1848
+ };
1849
+ }
1850
+
1851
+ export async function releaseApp(args) {
1852
+ const lease = await import('./lease.js');
1853
+ const id = args?.leaseId ? String(args.leaseId) : '';
1854
+ if (id) {
1855
+ const r = lease.release(id);
1856
+ return { text: r.ok ? `已释放 ${id}` : (r.hint || '释放失败') };
1857
+ }
1858
+ const r = lease.releaseAll(String(args?.owner || 'this-session'));
1859
+ return { text: r.released.length ? `已释放 ${r.released.length} 个租约:${r.released.join(', ')}` : '当前会话没有持有租约。' };
1860
+ }
1861
+
1862
+ export async function leases() {
1863
+ const lease = await import('./lease.js');
1864
+ return { text: lease.describeList() };
1865
+ }
1866
+
1867
+ /* ============================================================
1868
+ * 感知层工具(2026-11-16 新增)
1869
+ *
1870
+ * 这些能力在 vd.js / video.js 里已经做好并真机验证过,但一直只是模块导出,
1871
+ * 工具层没暴露 —— 等于 AI 用不到。这里补齐。
1872
+ * ============================================================ */
1873
+
1874
+ /**
1875
+ * 起/停视频流的常驻解码器,或只看状态。
1876
+ *
1877
+ * 为什么要单独一个工具:常驻解码器不启动的话,`vdisplay_live_shot` 只能走
1878
+ * 按需解码(244ms);启动之后读帧是内存拷贝(<1ms)。
1879
+ */
1880
+ export async function live(args) {
1881
+ const action = String(args?.action || 'status');
1882
+ if (action === 'start') {
1883
+ const r = await vd.startLive({ quality: Number(args?.quality) || 5 });
1884
+ const s = await vd.videoStats();
1885
+ return {
1886
+ // **必须给 text**:out() 的 schema 里 text 是 required 且 additionalProperties:false,
1887
+ // 少这个字段模型拿到的是空结果(审计发现的 P0)。
1888
+ text: r.ok
1889
+ ? `解码器 ${s.decoder ? '已启动' : '未启动'};流 ${s.width}x${s.height},${s.frames} 帧,实测 ${s.fps || 0} fps。`
1890
+ : `解码器操作失败:${r.hint || '未知'}`,
1891
+ ok: Boolean(r.ok),
1892
+ hint: r.hint,
1893
+ decoder: s.decoder,
1894
+ stream: { width: s.width, height: s.height, frames: s.frames, fps: s.fps },
1895
+ note: r.ok
1896
+ ? '常驻解码器已启动。画面静止时 scrcpy 不发帧,读不到画面是正常的。'
1897
+ : undefined,
1898
+ };
1899
+ }
1900
+ if (action === 'stop') {
1901
+ const r = await vd.stopLive();
1902
+ // **必须给 text**:out() 的 schema 里 text 是 required,
1903
+ // 少了模型拿到空结果(同文件其他分支都写了,这两处漏了 —— 审查 S13)。
1904
+ return { text: `常驻解码器已停止${r?.hint ? ':' + r.hint : '。'}`, ok: true, ...r };
1905
+ }
1906
+ const s = await vd.videoStats();
1907
+ const ready = Boolean(s.headerDone && !s.headerError);
1908
+ return {
1909
+ text: ready
1910
+ ? `解码器 ${s.decoder ? '在跑' : '未启动'};流 ${s.width}x${s.height},${s.frames} 帧,${s.fps || 0} fps;`
1911
+ + `${s.hasKeyframe ? '已收到关键帧' : '还没关键帧(画面静止时不发帧,正常)'}。`
1912
+ : '视频流还没接上(先 vdisplay_start 建屏)。',
1913
+ ok: ready,
1914
+ width: s.width,
1915
+ height: s.height,
1916
+ frames: s.frames,
1917
+ fps: s.fps,
1918
+ hasKeyframe: s.hasKeyframe,
1919
+ badSizes: s.badSizes,
1920
+ decoder: s.decoder,
1921
+ hint: s.headerDone ? undefined : '视频流还没接上(先 vdisplay_start 建屏)',
1922
+ };
1923
+ }
1924
+
1925
+ /**
1926
+ * 从视频流里取一张**最新帧**(比 vdisplay_shot 快得多)。
1927
+ *
1928
+ * 前提:必须先 `vdisplay_live action=start`,而且**画面要动** ——
1929
+ * scrcpy 只在内容变化时发帧,静止的屏一个包都不发。
1930
+ */
1931
+ export async function liveShot(args) {
1932
+ const r = await vd.liveShot({
1933
+ dir: String(args?.dir || '/tmp'),
1934
+ width: Number(args?.width) || 0,
1935
+ });
1936
+ if (!r.ok) {
1937
+ return {
1938
+ // **text 必填**,失败分支也要给
1939
+ text: `取帧失败:${r.hint || '未知'}。改用 vdisplay_shot(走 screencap,静止屏也能截)。`,
1940
+ ok: false,
1941
+ hint: r.hint,
1942
+ fallback: '用 vdisplay_shot(走 screencap,静止屏也能截)',
1943
+ };
1944
+ }
1945
+ return {
1946
+ // **text 必填**(out() 的 schema 要求),少了模型拿到空结果
1947
+ text: `从流里取到一帧:${r.path || '(无路径)'}(${r.bytes || 0} 字节)`,
1948
+ ok: true,
1949
+ path: r.path,
1950
+ width: r.width,
1951
+ height: r.height,
1952
+ source: r.source,
1953
+ frameAgeMs: r.frameAgeMs,
1954
+ fps: r.fps,
1955
+ displayId: r.displayId,
1956
+ };
1957
+ }
1958
+
1959
+ /**
1960
+ * 等画面稳定下来再返回(替代固定 sleep)。
1961
+ *
1962
+ * 实测:滑动后 121-182ms 就稳了,比固定 `sleep(500)` 快 300ms 左右,
1963
+ * 而且截图不会撞上转场中间态。
1964
+ */
1965
+ export async function waitStable(args) {
1966
+ const r = await vd.waitStable({
1967
+ stableMs: Number(args?.stableMs) || 120,
1968
+ maxWaitMs: Number(args?.maxWaitMs) || 2500,
1969
+ threshold: Number(args?.threshold) || 0.5,
1970
+ });
1971
+ return {
1972
+ // **text 必填**
1973
+ text: `画面${r.stable !== false ? '已稳定' : '未稳定'},等了 ${r.waitedMs || 0} ms(尾部 MAD ${r.tailMad ?? '?'})。`,
1974
+ ok: r.stable !== false,
1975
+ waitedMs: r.waitedMs,
1976
+ stable: r.stable,
1977
+ tailMad: r.tailMad,
1978
+ hint: r.hint,
1979
+ };
1980
+ }
1981
+
1982
+ /**
1983
+ * 自动挑一块值得看的区域(局部放大)。
1984
+ *
1985
+ * 同样的 token 预算下,裁剪 1:1 比全屏缩放清晰 2 倍左右。
1986
+ * 返回的 `region` 可以直接传给 `vdisplay_shot`。
1987
+ */
1988
+ export async function roi(args) {
1989
+ const r = await vd.pickRoi({
1990
+ // 544 而不是 420:地板价 169 覆盖到 544²,同价多 68% 面积
1991
+ outputWidth: Number(args?.outputWidth) || 544,
1992
+ minArea: Number(args?.minArea) || 0.04,
1993
+ });
1994
+ if (!r) {
1995
+ return {
1996
+ // **text 必填**,失败分支也要给
1997
+ text: '挑不出合适的区域(画面可能完全没有变化,也没有最近的点击位置)。直接 vdisplay_shot 全屏。',
1998
+ ok: false,
1999
+ hint: '挑不出合适的区域(画面可能完全没有变化,也没有最近的点击位置)。直接 vdisplay_shot 全屏。',
2000
+ };
2001
+ }
2002
+ return {
2003
+ // **text 必填**
2004
+ text: `推荐区域 region{ x:${r.x}, y:${r.y}, w:${r.w}, h:${r.h} },来源 ${r.src || '?'},占屏 ${((r.area || 0) * 100).toFixed(1)}%。`,
2005
+ ok: true,
2006
+ region: { x: r.x, y: r.y, w: r.w, h: r.h },
2007
+ src: r.src,
2008
+ area: r.area,
2009
+ hint: `把 region 传给 vdisplay_shot,同 token 下清晰约 2 倍`,
2010
+ };
2011
+ }
2012
+
2013
+ /**
2014
+ * 黑屏探针:判断这块屏上的内容是不是抓不到(FLAG_SECURE)。
2015
+ *
2016
+ * A 正常 / B? 疑似受保护 / C 整屏黑 / A? 误报纠正
2017
+ */
2018
+ export async function probeSecure(args) {
2019
+ const r = await vd.probeSecure({ dir: String(args?.dir || '/tmp') });
2020
+ if (!r.ok) return { text: `黑屏探针失败:${r.hint || '未知'}`, ok: false, hint: r.hint };
2021
+ return {
2022
+ // **text 必填**(out() 的 schema 要求),少了模型拿到空结果
2023
+ text: `黑屏探针结论:${r.verdict || '正常出画'}(置信度 ${r.confidence ?? '?'})。${r.hint || ''}`,
2024
+ ok: true,
2025
+ verdict: r.verdict,
2026
+ confidence: r.confidence,
2027
+ why: r.why,
2028
+ upperMax: r.upMax,
2029
+ lowerMax: r.downMax,
2030
+ secureWindows: r.secureWins,
2031
+ path: r.path,
2032
+ hint: r.hint,
2033
+ };
2034
+ }