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/LICENSE +21 -0
- package/README.md +195 -2
- package/assets/injector/Injector.smali +1179 -0
- package/assets/injector/README.md +101 -0
- package/assets/injector/inject.dex +0 -0
- package/assets/overlay/ai-overlay.apk +0 -0
- package/assets/scrcpy-server.jar +0 -0
- package/bin/aim.mjs +220 -0
- package/bin/asr.mjs +81 -0
- package/bin/audcap.mjs +128 -0
- package/bin/mcp-server.mjs +410 -0
- package/bin/vdisplay.mjs +305 -0
- package/bin/vdisplayd.mjs +398 -0
- package/bin/vidcap.mjs +82 -0
- package/bin/vidgrab.mjs +172 -0
- package/package.json +55 -4
- package/src/framesrv.js +348 -0
- package/src/human.js +302 -0
- package/src/index.js +161 -0
- package/src/inject.js +415 -0
- package/src/lease.js +314 -0
- package/src/occupancy.js +214 -0
- package/src/ocr.js +209 -0
- package/src/ocr_helper.py +125 -0
- package/src/pool.js +195 -0
- package/src/sampling.js +163 -0
- package/src/stream.js +571 -0
- package/src/target.js +29 -0
- package/src/timeline.js +324 -0
- package/src/tool-spec.js +873 -0
- package/src/tools.js +2034 -0
- package/src/vd.js +2354 -0
- package/src/video.js +751 -0
- package/src/vision.js +193 -0
- package/src/vision_helper.py +334 -0
package/src/tool-spec.js
ADDED
|
@@ -0,0 +1,873 @@
|
|
|
1
|
+
/** 六个工具的契约。 */
|
|
2
|
+
const out = (d) => ({
|
|
3
|
+
schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true, description: d } } },
|
|
4
|
+
render(_a, v) { return [{ type: 'text', text: v.text }]; },
|
|
5
|
+
});
|
|
6
|
+
|
|
7
|
+
const MODES = [
|
|
8
|
+
'四种操作方式,按任务选(都不许影响主屏):',
|
|
9
|
+
'1) shell —— adb 直接执行,最快最稳,零打扰。装包、看日志、查状态、改设置都用它。',
|
|
10
|
+
'2) browser —— 走 CDP 操作浏览器,不点屏幕。只在需要网页交互时用。',
|
|
11
|
+
'3) vdisplay —— 私有虚拟屏,App 跑在用户看不见的屏上,可以截图+定向点击。需要"看界面再点"的 App 操作用它。',
|
|
12
|
+
'4) watch —— 用户想看你操作时,把虚拟屏截图发上来。',
|
|
13
|
+
].join('\n');
|
|
14
|
+
|
|
15
|
+
export function modesSpec() {
|
|
16
|
+
return {
|
|
17
|
+
name: 'screen_modes',
|
|
18
|
+
description: ['列出目前可用的操作方式以及各自的代价与适用场景,供你选择。', '', MODES].join('\n'),
|
|
19
|
+
parameters: {},
|
|
20
|
+
output: out('四种方式的对比表与选择建议。'),
|
|
21
|
+
};
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export function startSpec() {
|
|
25
|
+
return {
|
|
26
|
+
name: 'vdisplay_start',
|
|
27
|
+
description: [
|
|
28
|
+
'创建一块用户看不见的私有虚拟屏(headless virtual display),App 可以跑在上面。',
|
|
29
|
+
'',
|
|
30
|
+
'关键性质(都实测过):不画在物理屏幕上、不抢主屏焦点、不弹输入法。',
|
|
31
|
+
'需要这台机器的 com.android.shell 拥有 ADD_TRUSTED_DISPLAY 权限(一部分机型有,Pixel 默认没有)。',
|
|
32
|
+
'',
|
|
33
|
+
'屏与插件进程同生共死:客户端断开或引擎重启,屏自动消失,不会留垃圾。',
|
|
34
|
+
].join('\n'),
|
|
35
|
+
parameters: {
|
|
36
|
+
keepMin: { type: 'integer', description: '**按任务预估后台屏要活多久**(分钟,1~360)。不传沿用当前设定(默认 5)。长任务(挂机/轮询/等转盘)先设大,比如 60;点几下就完的设 3。AI 连续这么多分钟没调工具就自动关闭。' },
|
|
37
|
+
maxFps: {
|
|
38
|
+
type: 'integer',
|
|
39
|
+
description: '视频流帧率上限,默认 60。传 0 表示不限。'
|
|
40
|
+
+ '以前没这个参数等于无限帧率,实测 3D 游戏会跑到 145fps,白烧 CPU 和带宽。',
|
|
41
|
+
},
|
|
42
|
+
width: { type: 'integer', description: '宽度,默认 720。' },
|
|
43
|
+
height: { type: 'integer', description: '高度,默认 1280。' },
|
|
44
|
+
dpi: { type: 'integer', description: '密度,默认 320。' },
|
|
45
|
+
orientation: { type: 'string', description: '方向,默认 "auto"(按物理屏比例,最接近真机,推荐)。"auto" 不要改;"landscape"/"portrait" 只交换宽高;"square" 正方形(慎用:16:9 的游戏会按高度算出更宽的画布,右边被裁)' },
|
|
46
|
+
systemDecorations: { type: 'boolean', description: '默认 false。false 时虚拟屏上不含二级桌面、导航栏和权限弹窗,AI 截图更干净(scrcpy ≥3.1)。改这个值会重建屏。' },
|
|
47
|
+
hwc: { type: 'string', description: '是否让硬件合成器(HWC)参与虚拟屏合成。"auto"(默认):仅当本机 vendor.display.vds_allow_hwc=1 时自动开启;"on":强制尝试;"off":不碰。开启后 3D 游戏(SurfaceView 渲染)能正常出画面,否则全黑。这是全局 SurfaceFlinger 属性,stop 时会恢复原值。' },
|
|
48
|
+
},
|
|
49
|
+
output: out('displayId、SurfaceFlinger id、是否具备托管 App 的能力标志。'),
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export function launchSpec() {
|
|
54
|
+
return {
|
|
55
|
+
name: 'vdisplay_launch',
|
|
56
|
+
description: [
|
|
57
|
+
'把一个 App 投到虚拟屏上,而不是主屏。',
|
|
58
|
+
'',
|
|
59
|
+
'内部会先 force-stop 该 App:如果它已经在主屏后台跑着,直接投屏只会把旧任务拉到前台,',
|
|
60
|
+
'就会顶掉用户正在看的东西(实测踩过)。投完会**校验并报告**主屏焦点变没变,',
|
|
61
|
+
'但**不会自动还原** —— 自动还原会误判(用户自己切了 App 时插件反而去改主屏),',
|
|
62
|
+
'所以只观察、只报告,由你决定要不要处理。',
|
|
63
|
+
].join('\n'),
|
|
64
|
+
parameters: {
|
|
65
|
+
pkg: { type: 'string', required: true, description: '包名,例如 com.tencent.mm。' },
|
|
66
|
+
activity: { type: 'string', description: 'Activity 名,例如 .ui.LauncherUI。省略则只给包名。' },
|
|
67
|
+
},
|
|
68
|
+
output: out('是否成功落在虚拟屏上、主屏前后焦点对比。'),
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
export function inputSpec() {
|
|
73
|
+
return {
|
|
74
|
+
name: 'vdisplay_input',
|
|
75
|
+
description: [
|
|
76
|
+
'往虚拟屏定向注入输入:点击、滑动、输入文字、按键。',
|
|
77
|
+
'',
|
|
78
|
+
'这些事件只发给虚拟屏,不会落到主屏上。虚拟屏上不弹软键盘(为了不抢你的键盘),所以:',
|
|
79
|
+
'',
|
|
80
|
+
'- kind:"text":往标准输入框注入文字。系统设置、原生控件一般有效;',
|
|
81
|
+
' 自绘输入框(京东、部分 App 的搜索框)可能注不进去。',
|
|
82
|
+
'- kind:"paste":发 KEYCODE_PASTE,把**剪贴板**内容粘进当前输入框。',
|
|
83
|
+
' 这条路不经过输入法,对自绘输入框也有效,是 text 失败时的首选替代。',
|
|
84
|
+
' 带 text 时插件会先写剪贴板再粘,支持中文;不带 text 则粘用户剪贴板里现有的内容。',
|
|
85
|
+
'- kind:"key":发按键,如 KEYCODE_BACK / KEYCODE_ENTER。',
|
|
86
|
+
].join('\n'),
|
|
87
|
+
parameters: {
|
|
88
|
+
kind: { type: 'string', required: true, description: 'tap | swipe | hold | text | key | paste。hold = 按住不动(游戏摇杆/长按/挖方块),60Hz 连续 MOVE,实测可用。multitouch = 双指(一根按住 + 另一根滑动),实测可用 —— 游戏边走路边转视角、双指缩放。参数用 p1/p2/p2To。' },
|
|
89
|
+
ms: { type: 'integer', description: '时长毫秒。swipe 默认 300;hold 默认 1000(按住的时长);multitouch 默认 600。' },
|
|
90
|
+
p1: { type: 'object', additionalProperties: false, properties: { nx: { type: 'number', description: '第一指 x 0-1' }, ny: { type: 'number', description: '第一指 y 0-1' } }, description: 'multitouch:第一指位置(通常是摇杆,按住不动)' },
|
|
91
|
+
p2: { type: 'object', additionalProperties: false, properties: { nx: { type: 'number' }, ny: { type: 'number' } }, description: 'multitouch:第二指起点(通常是视角滑动起点)' },
|
|
92
|
+
p2To: { type: 'object', additionalProperties: false, properties: { nx: { type: 'number' }, ny: { type: 'number' } }, description: 'multitouch:第二指终点。省略则第二指不动' },
|
|
93
|
+
jitter: { type: 'integer', description: 'hold:手指位置抖动幅度(逻辑像素),默认 2。真按不会绝对静止,设 0 会变成机器特征。' },
|
|
94
|
+
driftX: { type: 'integer', description: 'hold:按住期间缓慢横向漂移(逻辑像素),默认 0。摇杆往右推就设正数(比如 40)。' },
|
|
95
|
+
driftY: { type: 'integer', description: 'hold:按住期间缓慢纵向漂移,默认 0。摇杆往前推设负数(屏幕坐标 y 向下)。' },
|
|
96
|
+
verify: { type: 'boolean', description: '默认 true:动作前后各取一次画面哈希,没变就返回"可能没生效"。传 false 跳过校验,实测省约 2 秒(两次 screencap 各约 1 秒),适合连续点同一界面。' },
|
|
97
|
+
settleMs: { type: 'integer', description: '动作后等画面稳定的毫秒数,默认 500。' },
|
|
98
|
+
shotAfter: { type: 'boolean', description: '动作后顺手截一张并返回路径(省掉单独调 vdisplay_shot 的一轮往返)。默认 false。' },
|
|
99
|
+
width: { type: 'integer', description: 'shotAfter 时的截图宽度,默认 540。' },
|
|
100
|
+
text: { type: 'string', description: 'kind:"text" 要注入的 ASCII 文字;或 kind:"paste" 要粘贴的文字(**支持中文**,插件会先写剪贴板再粘)。paste 不带 text 时粘现有剪贴板内容。注意剪贴板是系统全局的,写它会覆盖用户自己的剪贴板。' },
|
|
101
|
+
x: { type: 'integer', description: 'tap 的 x 像素坐标(和 nx 二选一)。' },
|
|
102
|
+
y: { type: 'integer', description: 'tap 的 y 像素坐标(和 ny 二选一)。' },
|
|
103
|
+
nx: { type: 'number', description: '归一化横坐标 0..1,按屏宽换算。比算像素省心,推荐用它。' },
|
|
104
|
+
ny: { type: 'number', description: '归一化纵坐标 0..1,按屏高换算。' },
|
|
105
|
+
x1: { type: 'integer', description: 'swipe 起点 x。' },
|
|
106
|
+
y1: { type: 'integer', description: 'swipe 起点 y。' },
|
|
107
|
+
x2: { type: 'integer', description: 'swipe 终点 x。' },
|
|
108
|
+
y2: { type: 'integer', description: 'swipe 终点 y。' },
|
|
109
|
+
key: { type: 'string', description: 'kind=key 时的按键名,例如 KEYCODE_BACK。' },
|
|
110
|
+
},
|
|
111
|
+
output: out('注入结果。'),
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
export function shotSpec() {
|
|
116
|
+
return {
|
|
117
|
+
name: 'vdisplay_shot',
|
|
118
|
+
description: [
|
|
119
|
+
'看虚拟屏。frames=1 给一张静态截图;frames>1 连拍几张拼成网格,用来看「在动吗、往哪动、变成什么样」。',
|
|
120
|
+
'',
|
|
121
|
+
'frames=1(默认):一张截图,能读屏幕上的字和数字。720x1592 竖屏缩到 420 宽约 230 token、540 宽约 377。',
|
|
122
|
+
'',
|
|
123
|
+
'frames>1:抓 N 帧拼成网格,从左到右、从上到下是时间顺序。',
|
|
124
|
+
'九格缩到每格 262 宽后,原图 26px 的字只剩 9px —— 只能看结构、位置、有没有动,读不出小字。',
|
|
125
|
+
'形状会按屏幕真实比例自动算:竖屏画布是竖的,横屏(游戏)画布是横的。',
|
|
126
|
+
'',
|
|
127
|
+
'成本(720x1592 竖屏、9 帧 3x3 实测):每格 160 → 312 token;180 → 377;200 → 480;262 → 798;300 → 1056。',
|
|
128
|
+
'只想判断动没动用 160-180(312-377 token);想顺便看清大字用 262(798 token)。',
|
|
129
|
+
'',
|
|
130
|
+
'看不清某个按钮或数字时,用 region 只截那一块 —— 比调大 width 更划算:'
|
|
131
|
+
+ '同样 420 宽,局部 1.167x(放大),全屏 0.583x(缩小),而且局部只要 180 token、全屏要 684。',
|
|
132
|
+
].join('\n'),
|
|
133
|
+
parameters: {
|
|
134
|
+
frames: {
|
|
135
|
+
type: 'integer',
|
|
136
|
+
description: '抓几帧。1(默认)= 单张截图;2/4/6/9/12/16 = 拼成网格。会被规整成能拼成矩形的数。',
|
|
137
|
+
},
|
|
138
|
+
width: {
|
|
139
|
+
type: 'integer',
|
|
140
|
+
description: '每帧宽度。frames=1 时默认 540(读字用);frames>1 时默认 262(看运动用)。范围 240-720。',
|
|
141
|
+
},
|
|
142
|
+
intervalMs: {
|
|
143
|
+
type: 'integer',
|
|
144
|
+
description: 'frames>1 时的帧间隔毫秒,默认 300。抓快动作调小(最小 0),抓慢变化调大。',
|
|
145
|
+
},
|
|
146
|
+
format: { type: 'string', description: 'frames=1 时有效:"jpeg"(默认,省 token)或 "png"。' },
|
|
147
|
+
region: {
|
|
148
|
+
type: 'object',
|
|
149
|
+
// **必须显式声明 additionalProperties**,否则宿主拒绝整个工具的注册:
|
|
150
|
+
// register failed: unsupported JSON schema:
|
|
151
|
+
// parameters.region.additionalProperties must be explicitly true or false
|
|
152
|
+
// 诊断日志 dsh-app/diagnostics.md:62 和 :122 两次报过这个。
|
|
153
|
+
// 后果:vdisplay_shot 这个核心工具一直没注册上,工具列表里少一个。
|
|
154
|
+
additionalProperties: false,
|
|
155
|
+
properties: {
|
|
156
|
+
x: { type: 'integer', description: '左上角 x(显示逻辑像素)' },
|
|
157
|
+
y: { type: 'integer', description: '左上角 y' },
|
|
158
|
+
w: { type: 'integer', description: '宽' },
|
|
159
|
+
h: { type: 'integer', description: '高' },
|
|
160
|
+
},
|
|
161
|
+
description: '只看屏幕的一块:{x,y,w,h},坐标用显示逻辑像素(跟 x/y 点按同一套坐标)。把这块按 width 交付,等于放大。'
|
|
162
|
+
+ '实测:取 360×796 的局部交付到 420 宽,只要 180 token(全屏要 684),而线性分辨率是全屏的 2 倍。'
|
|
163
|
+
+ '看不清某个按钮/数字时用这个,比调大 width 划算。',
|
|
164
|
+
},
|
|
165
|
+
crop: {
|
|
166
|
+
type: 'string',
|
|
167
|
+
description: '已废弃,传了也不裁。原因:浏览器壳在顶部还是底部拿不到可靠信号(实测顶部还会有翻译条),'
|
|
168
|
+
+ '自动裁会把真实内容切掉。想看细节请用 region。',
|
|
169
|
+
},
|
|
170
|
+
dir: { type: 'string', description: '输出目录,默认 /tmp。' },
|
|
171
|
+
},
|
|
172
|
+
output: out('图片路径、格数、每格大小、是否和上次一样。'),
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
export function mainShotSpec() {
|
|
177
|
+
return {
|
|
178
|
+
name: 'screen_shot_main',
|
|
179
|
+
description: [
|
|
180
|
+
'截主屏(用户正在看的屏幕)。只读操作,不会改变任何东西。',
|
|
181
|
+
'',
|
|
182
|
+
'用途:确认用户现在在看什么,或核对"我刚才的操作有没有影响主屏"。',
|
|
183
|
+
].join('\n'),
|
|
184
|
+
parameters: {
|
|
185
|
+
dir: { type: 'string', description: '本地保存目录,默认 /tmp。' },
|
|
186
|
+
width: { type: 'integer', description: '输出宽度,默认 540(实测文字仍清晰,token 省约 44%)。范围 240–1080。' },
|
|
187
|
+
format: { type: 'string', description: '"jpeg"(默认,省 token)或 "png"(需要无损时)。' },
|
|
188
|
+
},
|
|
189
|
+
output: out('截图路径,以及当前主屏焦点是哪个 App。'),
|
|
190
|
+
};
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
export function statusSpec() {
|
|
194
|
+
return {
|
|
195
|
+
name: 'vdisplay_status',
|
|
196
|
+
description: ['查看虚拟屏状态:是否在跑、displayId、上面跑着哪个 App、主屏现在是什么。'].join('\n'),
|
|
197
|
+
parameters: {},
|
|
198
|
+
output: out('状态摘要。'),
|
|
199
|
+
};
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
export function stopSpec() {
|
|
203
|
+
return {
|
|
204
|
+
name: 'vdisplay_stop',
|
|
205
|
+
description: ['销毁虚拟屏,释放资源。收工时应调用——虽然是自动生命周期的,但显式停更干净。'].join('\n'),
|
|
206
|
+
parameters: {
|
|
207
|
+
forceStopApps: { type: 'boolean', description: '默认 false。传 true 会 force-stop 投上去过的 App,清掉后台占用;DSH 和 Shizuku 会被自动跳过(杀了会影响用户)。' },
|
|
208
|
+
},
|
|
209
|
+
output: out('销毁结果。'),
|
|
210
|
+
};
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
export function streamStartSpec() {
|
|
214
|
+
return {
|
|
215
|
+
name: 'vdisplay_stream',
|
|
216
|
+
description: [
|
|
217
|
+
'把虚拟屏的画面推给悬浮窗 / DSH Go 的「AI 画面」胶囊。',
|
|
218
|
+
'',
|
|
219
|
+
'**这一步可以当第一步用**:没有屏它会自己建一块,然后连带起推流和悬浮窗,',
|
|
220
|
+
'一次调用完成「建屏 + 投画面 + 弹窗」。所以新环境里想给用户看画面,直接调这个就行。',
|
|
221
|
+
'',
|
|
222
|
+
'**反过来也一样**:vdisplay_start / screen_new 建屏时会自动调这个工具',
|
|
223
|
+
'(除非显式传 overlay:false),所以你不需要「先建屏再单独开推流」。',
|
|
224
|
+
'',
|
|
225
|
+
'**没开推流的屏是无头的**:屏建出来了,但没有任何输出通道,',
|
|
226
|
+
'用户看不到、悬浮窗不会出现、你也只能靠 vdisplay_shot 读帧。',
|
|
227
|
+
'',
|
|
228
|
+
'用户点它就能实时看到 AI 在操作什么。',
|
|
229
|
+
'',
|
|
230
|
+
'实测成本:360x640 @2fps 约 0.30 核、29 KB/s,全程不写任何文件。帧率上限 15fps。',
|
|
231
|
+
'不看的时候胶囊不显示画面;调 vdisplay_stream_stop 或 vdisplay_stop 就会完全停掉。',
|
|
232
|
+
].join('\n'),
|
|
233
|
+
parameters: {
|
|
234
|
+
fps: { type: 'integer', description: '帧率,1–4,默认 2。' },
|
|
235
|
+
width: { type: 'integer', description: 'JPEG 宽度,240–720,默认 360。' },
|
|
236
|
+
},
|
|
237
|
+
output: out('端口、帧率与打开方式。'),
|
|
238
|
+
};
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
export function streamStopSpec() {
|
|
242
|
+
return {
|
|
243
|
+
name: 'vdisplay_stream_stop',
|
|
244
|
+
description: '停止推流。',
|
|
245
|
+
parameters: {},
|
|
246
|
+
output: out('结果。'),
|
|
247
|
+
};
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
export function textSpec() {
|
|
251
|
+
return {
|
|
252
|
+
name: 'vdisplay_text',
|
|
253
|
+
description: [
|
|
254
|
+
'把虚拟屏上的文字识别成文本,带坐标返回。**这是读数字和文字最可靠的方式,而且不花图片 token。**',
|
|
255
|
+
'',
|
|
256
|
+
'什么时候该用:要读屏幕上的数字、金额、时间、列表文字、按钮文字、输入框内容时。',
|
|
257
|
+
'实测:把截图缩成九格后,原图 26px 的字只剩 5px,模型读不出还会编造 —— 所以数字一律走这个工具。',
|
|
258
|
+
'',
|
|
259
|
+
'返回每行文字 + 像素坐标 + 归一化坐标(nx/ny,可直接给 vdisplay_input 点按)+ 置信度。',
|
|
260
|
+
'图像没变化时会直接复用上次结果,不重新识别。',
|
|
261
|
+
'',
|
|
262
|
+
'成本:约 1.6 秒(首次要 3-5 秒加载模型),**0 图片 token**。',
|
|
263
|
+
].join('\n'),
|
|
264
|
+
parameters: {
|
|
265
|
+
minConf: {
|
|
266
|
+
type: 'number',
|
|
267
|
+
description: '置信度下限,默认 0.45。调高(如 0.8)只留很确定的,调低会带噪声进来。',
|
|
268
|
+
},
|
|
269
|
+
maxLines: {
|
|
270
|
+
type: 'integer',
|
|
271
|
+
description: '最多返回几行,默认 80。屏幕文字多时截断(按从上到下、从左到右)。',
|
|
272
|
+
},
|
|
273
|
+
fresh: {
|
|
274
|
+
type: 'boolean',
|
|
275
|
+
description: '强制重新识别,默认 false(画面没变就复用缓存)。',
|
|
276
|
+
},
|
|
277
|
+
},
|
|
278
|
+
output: out('识别到的文字行(含坐标和置信度)。'),
|
|
279
|
+
};
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
export function appsSpec() {
|
|
283
|
+
return {
|
|
284
|
+
name: 'vdisplay_apps',
|
|
285
|
+
description: [
|
|
286
|
+
'列出手机上的第三方 App(名称 + 包名),投屏前拿来查包名。',
|
|
287
|
+
'',
|
|
288
|
+
'为什么要这个工具:vdisplay_launch 要包名,但之前没有任何工具能告诉你包名是什么,',
|
|
289
|
+
'模型只能靠猜。这个工具补上这一环 —— 列的是 `pm list packages -3`(第三方),',
|
|
290
|
+
'系统应用不列,因为投系统应用基本没意义。',
|
|
291
|
+
].join('\n'),
|
|
292
|
+
parameters: {},
|
|
293
|
+
output: out('已安装第三方 App 的包名列表。'),
|
|
294
|
+
};
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
export function poolSpec() {
|
|
298
|
+
return {
|
|
299
|
+
name: 'screen_pool',
|
|
300
|
+
description: [
|
|
301
|
+
'看当前有几块后台屏、哪块是活动屏。',
|
|
302
|
+
'',
|
|
303
|
+
'后台屏是这么回事:每个会话可以有自己的屏,屏上跑自己的 App,互不干扰。',
|
|
304
|
+
'实测两块屏可以同时跑不同 App(一块设置、一块文件管理器),切换不打扰对方。',
|
|
305
|
+
'',
|
|
306
|
+
'注意:**所有 vdisplay_* 操作作用在「活动屏」上**,切换用 screen_use。',
|
|
307
|
+
].join('\n'),
|
|
308
|
+
parameters: {},
|
|
309
|
+
output: out('屏列表、活动屏、每块的 displayId 和 dpi。'),
|
|
310
|
+
};
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
export function newScreenSpec() {
|
|
314
|
+
return {
|
|
315
|
+
name: 'screen_new',
|
|
316
|
+
description: [
|
|
317
|
+
'新建一块后台屏,返回它的 screenId。',
|
|
318
|
+
'',
|
|
319
|
+
'什么时候用:需要一块干净的屏、或需要同时让两个 App 各自独立跑。',
|
|
320
|
+
'注意屏幕数量受手机资源限制 —— 每块屏约 75-185MB 内存,实测两块很轻松,',
|
|
321
|
+
'4-6 块要看你手机上跑的 App 有多重。',
|
|
322
|
+
].join('\n'),
|
|
323
|
+
parameters: {
|
|
324
|
+
orientation: { type: 'string', description: '"portrait" / "landscape" / "square"。省略(默认 auto)按物理屏比例,最接近真机,推荐不要指定。**square 不推荐**:16:9 的游戏会按高度算出更宽的画布,右边被裁。' },
|
|
325
|
+
hwc: { type: 'string', description: '"auto"(默认)/"on"/"off"。3D 游戏要开。' },
|
|
326
|
+
},
|
|
327
|
+
output: out('新建屏的 screenId、displayId、dpi。'),
|
|
328
|
+
};
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
export function useScreenSpec() {
|
|
332
|
+
return {
|
|
333
|
+
name: 'screen_use',
|
|
334
|
+
description: [
|
|
335
|
+
'切换活动屏。之后所有 vdisplay_* 操作都作用在这块屏上。',
|
|
336
|
+
'',
|
|
337
|
+
'典型用法:screen_new 建一块 → screen_use 切过去 → vdisplay_launch 投 App。',
|
|
338
|
+
'切回来不会打扰另一块屏上的 App —— 实测各自状态都保留。',
|
|
339
|
+
].join('\n'),
|
|
340
|
+
parameters: {
|
|
341
|
+
screenId: { type: 'string', required: true, description: 'screenId,比如 "sd-1"。来自 screen_new 或 screen_pool。' },
|
|
342
|
+
},
|
|
343
|
+
output: out('切换结果。'),
|
|
344
|
+
};
|
|
345
|
+
}
|
|
346
|
+
|
|
347
|
+
export function closeScreenSpec() {
|
|
348
|
+
return {
|
|
349
|
+
name: 'screen_close',
|
|
350
|
+
description: [
|
|
351
|
+
'销毁一块后台屏,释放它的内存和上面的 App。',
|
|
352
|
+
'',
|
|
353
|
+
'注意:**屏一销毁,上面的 App 就没了**,下次要用得重新投。',
|
|
354
|
+
'如果只是想切走,用 screen_use,不用关屏。',
|
|
355
|
+
].join('\n'),
|
|
356
|
+
parameters: {
|
|
357
|
+
screenId: { type: 'string', required: true, description: '要销毁的 screenId。' },
|
|
358
|
+
forceStopApps: { type: 'boolean', description: '默认 false。true 时同时 force-stop 屏上的 App。' },
|
|
359
|
+
},
|
|
360
|
+
output: out('销毁结果。'),
|
|
361
|
+
};
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
export function checkAppSpec() {
|
|
365
|
+
return {
|
|
366
|
+
name: 'screen_check_app',
|
|
367
|
+
description: [
|
|
368
|
+
'查某个 App 现在被谁占着 —— 主屏用户在用它?还是别的屏上的 AI 在用?还是没人用?',
|
|
369
|
+
'',
|
|
370
|
+
'投屏前先查这个,避免把人正在用的 App 抢走(实测:`am start --display` 对',
|
|
371
|
+
'singleTask 的 App 会把主屏任务直接搬走,用户那一下就没了)。',
|
|
372
|
+
'',
|
|
373
|
+
'返回等级:FREE 没人用 / USER_BG 用户主屏后台有 / USER_ACTIVE 用户正在看着',
|
|
374
|
+
'(**绝对不能碰**)/ AI_HELD 在我们自己屏上 / FOREIGN 外来屏(不碰)。',
|
|
375
|
+
].join('\n'),
|
|
376
|
+
parameters: {
|
|
377
|
+
pkg: { type: 'string', required: true, description: '包名,比如 "com.android.settings"。用 vdisplay_apps 查。' },
|
|
378
|
+
},
|
|
379
|
+
output: out('占用等级和详细情况。'),
|
|
380
|
+
};
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
export function claimAppSpec() {
|
|
384
|
+
return {
|
|
385
|
+
name: 'screen_claim_app',
|
|
386
|
+
description: [
|
|
387
|
+
'申请占用一个 App。拿到了才能安全地在它上面操作,别人再申请会失败。',
|
|
388
|
+
'',
|
|
389
|
+
'**默认不抢占**(onConflict 默认 fail)。这是故意的:默认抢占会让多 AI 互相抢,',
|
|
390
|
+
'默认失败才逼出「先查再决定」。',
|
|
391
|
+
'',
|
|
392
|
+
'三种冲突处理:',
|
|
393
|
+
" fail 直接失败,告诉你谁占着(默认)",
|
|
394
|
+
" wait 返回还要等多久",
|
|
395
|
+
" preempt 强制接管 —— 原持有者下次调用会收到撤销通知",
|
|
396
|
+
'',
|
|
397
|
+
'**重要**:宽限期只有 5 秒,而一轮 AI 往返 6-9 秒,所以「让原持有者体面收尾」',
|
|
398
|
+
'在物理上做不到。preempt 能保证的只有「它不会继续误操作」。',
|
|
399
|
+
'',
|
|
400
|
+
'登录、支付、发送这类操作请传 preemptible:false,别人就抢不走了。',
|
|
401
|
+
].join('\n'),
|
|
402
|
+
parameters: {
|
|
403
|
+
pkg: { type: 'string', required: true, description: '包名。用 vdisplay_apps 查。' },
|
|
404
|
+
onConflict: { type: 'string', description: "'fail'(默认)/ 'wait' / 'preempt'" },
|
|
405
|
+
preemptible: { type: 'boolean', description: '默认 true。设 false 表示谁都抢不走(登录取证、支付中)。' },
|
|
406
|
+
nonPreemptibleReason: { type: 'string', description: 'preemptible:false 时说明原因,比如"正在登录"。' },
|
|
407
|
+
priority: { type: 'string', description: "'user' / 'agent'(默认)/ 'subagent'。高优先级能抢低的。" },
|
|
408
|
+
ttlSec: { type: 'integer', description: '租约时长秒数,默认 600(10 分钟)。' },
|
|
409
|
+
mode: { type: 'string', description: "'exclusive'(默认)/ 'readonly'" },
|
|
410
|
+
},
|
|
411
|
+
output: out('租约信息,或者冲突详情。'),
|
|
412
|
+
};
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
export function releaseAppSpec() {
|
|
416
|
+
return {
|
|
417
|
+
name: 'screen_release_app',
|
|
418
|
+
description: [
|
|
419
|
+
'释放 App 占用。干完了主动放,别人就能用了。',
|
|
420
|
+
'',
|
|
421
|
+
'不传 leaseId 时释放自己持有的全部租约。',
|
|
422
|
+
].join('\n'),
|
|
423
|
+
parameters: {
|
|
424
|
+
leaseId: { type: 'string', description: '要释放的租约 id。省略则释放当前会话全部的。' },
|
|
425
|
+
},
|
|
426
|
+
output: out('释放结果。'),
|
|
427
|
+
};
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
export function leasesSpec() {
|
|
431
|
+
return {
|
|
432
|
+
name: 'screen_leases',
|
|
433
|
+
description: '看当前所有 App 占用凭证(谁占着什么、还剩多久、能不能抢)。',
|
|
434
|
+
parameters: {},
|
|
435
|
+
output: out('租约列表。'),
|
|
436
|
+
};
|
|
437
|
+
}
|
|
438
|
+
|
|
439
|
+
/* ============================================================
|
|
440
|
+
* 感知层工具定义(2026-11-16)
|
|
441
|
+
*
|
|
442
|
+
* 对应的实现在 tools.js:live / liveShot / waitStable / roi / probeSecure。
|
|
443
|
+
* 这些能力在 vd.js 里已经真机验证过,之前只是没暴露给工具层。
|
|
444
|
+
* ============================================================ */
|
|
445
|
+
|
|
446
|
+
export function liveSpec() {
|
|
447
|
+
return {
|
|
448
|
+
name: 'vdisplay_live',
|
|
449
|
+
description: [
|
|
450
|
+
'视频流的常驻解码器:启动 / 停止 / 看状态。',
|
|
451
|
+
'',
|
|
452
|
+
'为什么值得开:常驻之后读一帧是内存拷贝(<1ms);不开的话每次都要按需解码(约 244ms)。',
|
|
453
|
+
'',
|
|
454
|
+
'**重要限制**:scrcpy 只在画面变化时发帧。画面静止时一个包都不发,读不到画面是正常的。',
|
|
455
|
+
'要一张确定的静止帧,用 vdisplay_shot(走 screencap)。',
|
|
456
|
+
'',
|
|
457
|
+
'实测:GIF/动画能跑 60fps;但**视频(MediaCodec 输出)在虚拟屏上不刷新**,别指望它看视频。',
|
|
458
|
+
].join('\n'),
|
|
459
|
+
parameters: {
|
|
460
|
+
action: { type: 'string', description: '"start" | "stop" | "status"(默认 status)' },
|
|
461
|
+
quality: { type: 'integer', description: 'start 时的 MJPEG 质量 2-31,默认 5(越小越好)。' },
|
|
462
|
+
},
|
|
463
|
+
output: out('解码器状态、流宽高、帧数、实测 fps。'),
|
|
464
|
+
};
|
|
465
|
+
}
|
|
466
|
+
|
|
467
|
+
export function liveShotSpec() {
|
|
468
|
+
return {
|
|
469
|
+
name: 'vdisplay_live_shot',
|
|
470
|
+
description: [
|
|
471
|
+
'从视频流里取一张最新帧(比 vdisplay_shot 快得多)。',
|
|
472
|
+
'',
|
|
473
|
+
'前提两条:① 先 vdisplay_live action=start;② 画面要动(静止屏收不到帧)。',
|
|
474
|
+
'满足不了就回退到 vdisplay_shot。',
|
|
475
|
+
'',
|
|
476
|
+
'实测:常驻解码后读一帧 <1ms,按需解码约 244ms,screencap 约 143ms。',
|
|
477
|
+
].join('\n'),
|
|
478
|
+
parameters: {
|
|
479
|
+
width: { type: 'integer', description: '缩放宽度,0=原生 720。默认 0。' },
|
|
480
|
+
dir: { type: 'string', description: '输出目录,默认 /tmp。' },
|
|
481
|
+
},
|
|
482
|
+
output: out('图片路径、宽高、来源(persistent-decoder / on-demand)、帧龄、实测 fps。'),
|
|
483
|
+
};
|
|
484
|
+
}
|
|
485
|
+
|
|
486
|
+
export function waitStableSpec() {
|
|
487
|
+
return {
|
|
488
|
+
name: 'vdisplay_wait_stable',
|
|
489
|
+
description: [
|
|
490
|
+
'等画面稳定下来再继续(替代固定 sleep)。',
|
|
491
|
+
'',
|
|
492
|
+
'用 32×32 灰度信号判断:连续 stableMs 内变化量低于阈值才算稳。',
|
|
493
|
+
'实测滑动后 121-182ms 就稳了,比固定 sleep(500) 快约 300ms,而且截图不会撞上转场中间态。',
|
|
494
|
+
'',
|
|
495
|
+
'典型用法:vdisplay_input 之后调它,再 vdisplay_shot。',
|
|
496
|
+
].join('\n'),
|
|
497
|
+
parameters: {
|
|
498
|
+
stableMs: { type: 'integer', description: '要连续稳多久才算稳,默认 120ms。' },
|
|
499
|
+
maxWaitMs: { type: 'integer', description: '最多等多久,超了就用当前帧,默认 2500。' },
|
|
500
|
+
threshold: { type: 'number', description: 'tailMad 低于它算稳,默认 0.5(滑动时 8-9,静止 0)。' },
|
|
501
|
+
},
|
|
502
|
+
output: out('等了多久、是否稳定、当前变化量。'),
|
|
503
|
+
};
|
|
504
|
+
}
|
|
505
|
+
|
|
506
|
+
export function roiSpec() {
|
|
507
|
+
return {
|
|
508
|
+
name: 'vdisplay_roi',
|
|
509
|
+
description: [
|
|
510
|
+
'自动挑一块值得看的区域,拿去做局部放大。',
|
|
511
|
+
'',
|
|
512
|
+
'为什么有用:token 按 ⌈宽/42⌉×⌈高/42⌉ 计费,小于 544² 按地板价收。',
|
|
513
|
+
'所以同样一笔 169 token,裁 420 见方是 1:1 像素,全屏缩到 420 宽只有 0.58x —— 清晰度差近 2 倍。',
|
|
514
|
+
'',
|
|
515
|
+
'区域怎么选:灰度变化包围盒 → 太大就用变化热力图挑最密集的 544² 子区 → 实在没有就用最近点击位置兜底。',
|
|
516
|
+
'',
|
|
517
|
+
'返回的 region 直接传给 vdisplay_shot 的 region 参数。',
|
|
518
|
+
].join('\n'),
|
|
519
|
+
parameters: {
|
|
520
|
+
outputWidth: { type: 'integer', description: '打算输出的宽度,默认 544。注意 544 以下都是地板价 169,所以 544 比 420 同价多看 68% 面积。' },
|
|
521
|
+
minArea: { type: 'number', description: '区域至少占整屏多少,默认 0.04。太小没信息量。' },
|
|
522
|
+
},
|
|
523
|
+
output: out('region(x/y/w/h)、来源(sensor-bbox / sensor-bbox+hotspot / last-input)、占屏面积。'),
|
|
524
|
+
};
|
|
525
|
+
}
|
|
526
|
+
|
|
527
|
+
export function probeSecureSpec() {
|
|
528
|
+
return {
|
|
529
|
+
name: 'vdisplay_probe_secure',
|
|
530
|
+
description: [
|
|
531
|
+
'黑屏探针:判断这块屏上的内容是不是抓不到(FLAG_SECURE)。',
|
|
532
|
+
'',
|
|
533
|
+
'FLAG_SECURE 是 Android 对受保护内容的保护:任何截屏 API 拿到的都是纯黑,',
|
|
534
|
+
'screencap / 视频流 / MediaProjection 全一样。**这是无 root 的硬边界,绕不过去。**',
|
|
535
|
+
'',
|
|
536
|
+
'判定:',
|
|
537
|
+
' A 正常出画',
|
|
538
|
+
' B? 疑似受保护(上半黑、下半可读)—— 会再用 dumpsys 的 FLAG_SECURE 窗口数复核',
|
|
539
|
+
' C 整屏黑 —— App 拒绝在虚拟屏渲染,或者没起来',
|
|
540
|
+
' A? 原本疑似但复核为不是受保护(通常是底部弹窗造成的误报)',
|
|
541
|
+
'',
|
|
542
|
+
'投屏之后建议先跑一次,能提前知道这条线能不能做。',
|
|
543
|
+
].join('\n'),
|
|
544
|
+
parameters: {
|
|
545
|
+
dir: { type: 'string', description: '截图输出目录,默认 /tmp。' },
|
|
546
|
+
},
|
|
547
|
+
output: out('verdict、置信度、判定理由、上下半亮度、dumpsys 里的 FLAG_SECURE 窗口数。'),
|
|
548
|
+
};
|
|
549
|
+
}
|
|
550
|
+
|
|
551
|
+
/**
|
|
552
|
+
* 查用户是否正在用手机。
|
|
553
|
+
*
|
|
554
|
+
* 这是把 `tools/user-busy.sh` 的判据变成工具 —— 那个脚本是对的,但不在工具链路里,
|
|
555
|
+
* 所以模型不知道要调它。2026-11-17 抢键盘事故就是没查这个。
|
|
556
|
+
*/
|
|
557
|
+
export function userStateSpec() {
|
|
558
|
+
return {
|
|
559
|
+
name: 'screen_user_state',
|
|
560
|
+
description: [
|
|
561
|
+
'查「用户现在在用手机吗」。**动主屏之前必须先调它。**',
|
|
562
|
+
'',
|
|
563
|
+
'判据:前台是 DSH Go(用户正在跟 AI 对话)或输入法正在显示(用户可能在打字)→ BUSY。',
|
|
564
|
+
'',
|
|
565
|
+
'为什么要有:`am start` / `mcp__phone__open` 会让新窗口成为焦点,',
|
|
566
|
+
'输入法的 InputConnection 从用户的输入框 detach —— 键盘被抢走、半截草稿丢失。',
|
|
567
|
+
'更危险的是 `input text` 会把文字拼进用户草稿,`input keyevent 66` 可能把草稿发出去。',
|
|
568
|
+
'',
|
|
569
|
+
'返回 BUSY 时改走:虚拟屏(vdisplay_*)、浏览器 CDP(web_*),或等用户停下来。',
|
|
570
|
+
].join('\n'),
|
|
571
|
+
parameters: {},
|
|
572
|
+
output: out('BUSY/IDLE 判定、前台包名、输入法状态。'),
|
|
573
|
+
};
|
|
574
|
+
}
|
|
575
|
+
|
|
576
|
+
/** 查某个 App 的风控等级(读 docs/risk.json,44 个 App 已标注)。 */
|
|
577
|
+
export function riskCheckSpec() {
|
|
578
|
+
return {
|
|
579
|
+
name: 'screen_risk',
|
|
580
|
+
description: [
|
|
581
|
+
'查某个 App 的风控等级,决定能用什么操作方式。',
|
|
582
|
+
'',
|
|
583
|
+
'L0 无风控 → 随便操作;L1 控制频率;L2 拟人化;',
|
|
584
|
+
'L3 严格 → 只读,写操作必须问用户;L4 银行/支付 → 只能交给人;L5 技术做不到。',
|
|
585
|
+
'',
|
|
586
|
+
'**操作微信/支付宝/银行/游戏之前先查这个。** 未知 App 按 L3 处理。',
|
|
587
|
+
].join('\n'),
|
|
588
|
+
parameters: {
|
|
589
|
+
pkg: { type: 'string', required: true, description: '包名,比如 com.tencent.mm。不知道包名先用 vdisplay_apps 查。' },
|
|
590
|
+
},
|
|
591
|
+
output: out('风控等级、中文名、禁止动作列表。'),
|
|
592
|
+
};
|
|
593
|
+
}
|
|
594
|
+
|
|
595
|
+
/**
|
|
596
|
+
* 按文字找位置。
|
|
597
|
+
*
|
|
598
|
+
* 现在模型是「看 OCR 返回的一堆 nx/ny,自己挑坐标去点」—— 这个环节容易点空。
|
|
599
|
+
* (曾经写过「17.6%」,但那个数字的推导有误,已作废;现在不引用具体比例。)
|
|
600
|
+
* 这两个工具把「找文字 → 算坐标」交给代码,模型不碰坐标。
|
|
601
|
+
*/
|
|
602
|
+
export function findTextSpec() {
|
|
603
|
+
return {
|
|
604
|
+
name: 'vdisplay_find',
|
|
605
|
+
description: [
|
|
606
|
+
'在虚拟屏上找文字,返回坐标(不点击)。',
|
|
607
|
+
'',
|
|
608
|
+
'**比让模型自己看 OCR 坐标再算要准得多** —— 模型自己算坐标是主要的点空来源(这个比例没有可靠测量,别引用具体数字)。',
|
|
609
|
+
'',
|
|
610
|
+
'匹配规则:默认「包含」(找「蓝牙」→ 「蓝牙 已开启」也算命中);',
|
|
611
|
+
'mode=exact 精确匹配;mode=regex 正则。多个命中时默认取最靠上的,用 nth 指定第几个。',
|
|
612
|
+
'',
|
|
613
|
+
'没找到会给「相近的文字」建议,方便你换词重试。',
|
|
614
|
+
'',
|
|
615
|
+
'要直接点,用 vdisplay_tap_text —— 它一步完成找+点。',
|
|
616
|
+
].join('\n'),
|
|
617
|
+
parameters: {
|
|
618
|
+
text: { type: 'string', required: true, description: '要找的文字,比如「蓝牙」「立即购买」' },
|
|
619
|
+
mode: { type: 'string', description: 'contains(默认)| exact | regex' },
|
|
620
|
+
nth: { type: 'integer', description: '多个命中时取第几个,从 0 开始,默认 0(最靠上的)' },
|
|
621
|
+
minConf: { type: 'number', description: 'OCR 置信度下限,默认 0.4' },
|
|
622
|
+
},
|
|
623
|
+
output: out('找到几处、目标坐标 nx/ny、命中文字。'),
|
|
624
|
+
};
|
|
625
|
+
}
|
|
626
|
+
|
|
627
|
+
/** 找到文字并点击 —— 一步完成,模型不碰坐标。 */
|
|
628
|
+
export function tapTextSpec() {
|
|
629
|
+
return {
|
|
630
|
+
name: 'vdisplay_tap_text',
|
|
631
|
+
description: [
|
|
632
|
+
'找到文字并点击它。**这是最可靠的点击方式,优先用它代替自己算坐标。**',
|
|
633
|
+
'',
|
|
634
|
+
'一步完成:OCR 找文字 → 算中心坐标 → 注入点击 → 校验。',
|
|
635
|
+
'模型只需要说要找什么,不需要看坐标。',
|
|
636
|
+
'',
|
|
637
|
+
'实测价值:模型自己看 OCR 坐标去点容易偏,这个工具把「自己算坐标」那个环节消掉。',
|
|
638
|
+
].join('\n'),
|
|
639
|
+
parameters: {
|
|
640
|
+
text: { type: 'string', required: true, description: '要点的文字,比如「立即购买」「确定」' },
|
|
641
|
+
mode: { type: 'string', description: 'contains(默认)| exact | regex' },
|
|
642
|
+
nth: { type: 'integer', description: '多个命中时点第几个,从 0 开始' },
|
|
643
|
+
verify: { type: 'boolean', description: '点击后校验画面有没有变化,默认 true' },
|
|
644
|
+
},
|
|
645
|
+
output: out('点到了什么、坐标、校验结果。'),
|
|
646
|
+
};
|
|
647
|
+
}
|
|
648
|
+
|
|
649
|
+
/** 调整后台屏的空闲超时 —— 让 AI 按任务预估生命周期。 */
|
|
650
|
+
export function keepAliveSpec() {
|
|
651
|
+
return {
|
|
652
|
+
name: 'screen_keepalive',
|
|
653
|
+
description: [
|
|
654
|
+
'设定「AI 停止操作多久后自动关掉后台屏」,让 AI 按任务预估生命周期。',
|
|
655
|
+
'',
|
|
656
|
+
'**开始长任务前先调它**:挂机、等转盘、轮询消息、玩需要时间累积的游戏 → 设大(30-360 分钟);',
|
|
657
|
+
'点几下就完的短任务 → 设小(2-5 分钟),省电更彻底。',
|
|
658
|
+
'',
|
|
659
|
+
'判据是「AI 连续 N 分钟没有调用任何工具」。**任何工具调用都会重置计时**,',
|
|
660
|
+
'所以只要还在操作就不会被关;真闲着时才关。',
|
|
661
|
+
'',
|
|
662
|
+
'默认 5 分钟。范围 1~360 分钟。',
|
|
663
|
+
'',
|
|
664
|
+
'为什么需要它:实测后台屏不关时 framesrv 持续 10.3% CPU。',
|
|
665
|
+
'设太短会在思考时被关掉,设太长会白白耗电 —— 按任务估是唯一正确的做法。',
|
|
666
|
+
].join('\n'),
|
|
667
|
+
parameters: {
|
|
668
|
+
minutes: { type: 'integer', required: true, description: '空闲多少分钟后自动关闭,1~360。短任务 2-5,长任务 30-360。' },
|
|
669
|
+
},
|
|
670
|
+
output: out('新的超时设定和含义。'),
|
|
671
|
+
};
|
|
672
|
+
}
|
|
673
|
+
|
|
674
|
+
/** 模板匹配找图 —— 找「没有文字的东西」的唯一快路。 */
|
|
675
|
+
export function findImageSpec() {
|
|
676
|
+
return {
|
|
677
|
+
name: 'vdisplay_find_image',
|
|
678
|
+
description: [
|
|
679
|
+
'用模板匹配找图上的图案(不点击)。**这是找「没有文字的东西」的唯一快速方法。**',
|
|
680
|
+
'',
|
|
681
|
+
'适合:图标、开关、返回箭头、技能格、红心、血条、准星、任何纯图形元素。',
|
|
682
|
+
'OCR 读不到这些(它们没有文字),而模板匹配实测只要 **5-30ms**(OCR 是 1600ms)。',
|
|
683
|
+
'',
|
|
684
|
+
'怎么用:**用 vdisplay_shot({format:\'png\'}) 截原分辨率**,把要反复找的那块裁出来存成 PNG。',
|
|
685
|
+
'(默认的 540 宽 JPEG 会得到小 25% 的模板 —— 虽然工具默认多尺度能兜住,但原分辨率更稳。)',
|
|
686
|
+
'模板要选「有特征」的一块:纯色块能匹配(自动切 SQDIFF),有一点纹理更稳,纯黑不行。',
|
|
687
|
+
'',
|
|
688
|
+
'找不到时可以:调低 threshold(0.6-0.7)、换一块更清晰的模板、或改用 vdisplay_find(找文字)。',
|
|
689
|
+
].join('\n'),
|
|
690
|
+
parameters: {
|
|
691
|
+
template: { type: 'string', required: true, description: '模板图片路径(PNG/JPG,在设备可读的文件系统上)' },
|
|
692
|
+
threshold: { type: 'number', description: '匹配阈值 0-1,默认 0.75。低了误报多,高了漏检' },
|
|
693
|
+
scales: { type: 'array', items: { type: 'number' }, description: '多尺度搜(默认 0.55~1.5 共 8 档)。模板大小和屏幕不一致时靠这个兜住。只在已知精确比例时手动传' },
|
|
694
|
+
region: { type: 'object', additionalProperties: false, properties: { x: { type: 'integer' }, y: { type: 'integer' }, w: { type: 'integer' }, h: { type: 'integer' } }, description: '只在屏幕这一块里找(省时间,也能避免找错地方)' },
|
|
695
|
+
},
|
|
696
|
+
output: out('找到没、score、屏幕坐标、中心 nx/ny。'),
|
|
697
|
+
};
|
|
698
|
+
}
|
|
699
|
+
|
|
700
|
+
/** 找到图并点它。 */
|
|
701
|
+
export function tapImageSpec() {
|
|
702
|
+
return {
|
|
703
|
+
name: 'vdisplay_tap_image',
|
|
704
|
+
description: [
|
|
705
|
+
'用模板匹配找到图案并点击它。一步完成找+点,适合点图标类的东西。',
|
|
706
|
+
'',
|
|
707
|
+
'有文字的东西用 vdisplay_tap_text(更准),没文字的东西用这个。',
|
|
708
|
+
].join('\n'),
|
|
709
|
+
parameters: {
|
|
710
|
+
template: { type: 'string', required: true, description: '模板图片路径' },
|
|
711
|
+
threshold: { type: 'number', description: '匹配阈值,默认 0.75' },
|
|
712
|
+
region: { type: 'object', additionalProperties: false, properties: { x: { type: 'integer' }, y: { type: 'integer' }, w: { type: 'integer' }, h: { type: 'integer' } }, description: '只在这块里找' },
|
|
713
|
+
},
|
|
714
|
+
output: out('点到了没、坐标、匹配分数。'),
|
|
715
|
+
};
|
|
716
|
+
}
|
|
717
|
+
|
|
718
|
+
/** 界面指纹。 */
|
|
719
|
+
export function fingerprintSpec() {
|
|
720
|
+
return {
|
|
721
|
+
name: 'vdisplay_fingerprint',
|
|
722
|
+
description: [
|
|
723
|
+
'算当前界面的 64 位指纹,用来判断「还是不是同一个界面」。',
|
|
724
|
+
'',
|
|
725
|
+
'比截图比对便宜(7ms vs 143ms),比 OCR 可靠(不依赖文字 —— 游戏/图片界面也能用)。',
|
|
726
|
+
'两次调用会给出汉明距离:0 = 完全相同,≤10 = 同一界面,>10 = 不同界面。',
|
|
727
|
+
'',
|
|
728
|
+
'用途:判断操作有没有生效、判断页面跳转了没、给方法缓存做键。',
|
|
729
|
+
].join('\n'),
|
|
730
|
+
parameters: {
|
|
731
|
+
key: { type: 'string', description: '独立记录的槽位名,默认 default。不同任务用不同 key,互不干扰' },
|
|
732
|
+
},
|
|
733
|
+
output: out('指纹、和上次的汉明距离、是否变了界面。'),
|
|
734
|
+
};
|
|
735
|
+
}
|
|
736
|
+
|
|
737
|
+
/** 屏幕差异。 */
|
|
738
|
+
export function screenDiffSpec() {
|
|
739
|
+
return {
|
|
740
|
+
name: 'vdisplay_diff',
|
|
741
|
+
description: [
|
|
742
|
+
'算当前画面和上一次的差异(MAD + 最大格差)。',
|
|
743
|
+
'',
|
|
744
|
+
'**maxCell 是关键**:全局 MAD 会被大片静态背景稀释 —— 一个数字变了,MAD 可能只有 0.0012',
|
|
745
|
+
'但 maxCell 有 0.31。只看 MAD 会漏掉小区域变化。',
|
|
746
|
+
'',
|
|
747
|
+
'第一次调用只记录,第二次起才给差异。用来判断「我这一下操作到底有没有生效」。',
|
|
748
|
+
].join('\n'),
|
|
749
|
+
parameters: {
|
|
750
|
+
before: { type: 'string', description: '指定「之前的图」路径。省略则自动和上一张比' },
|
|
751
|
+
},
|
|
752
|
+
output: out('MAD、maxCell、变没变。'),
|
|
753
|
+
};
|
|
754
|
+
}
|
|
755
|
+
|
|
756
|
+
/** 界面方法探测。 */
|
|
757
|
+
export function probeScreenSpec() {
|
|
758
|
+
return {
|
|
759
|
+
name: 'vdisplay_probe',
|
|
760
|
+
description: [
|
|
761
|
+
'探测当前界面适合用什么识别方法,并给出建议。',
|
|
762
|
+
'',
|
|
763
|
+
'量三个东西:边缘密度(5-18% 适合形状/模板)、颜色集中度(色数少才好用)、亮度和对比。',
|
|
764
|
+
'',
|
|
765
|
+
'**什么时候调**:第一次操作某个 App 时先探一次,之后按建议选方法 ——',
|
|
766
|
+
'文字多的界面用 OCR,图形界面用模板匹配,纯色状态用颜色检测。',
|
|
767
|
+
'',
|
|
768
|
+
'也用来识别「画面是不是空白」(FLAG_SECURE 或者还没加载完)。',
|
|
769
|
+
].join('\n'),
|
|
770
|
+
parameters: {},
|
|
771
|
+
output: out('边缘/颜色/亮度统计 + 方法建议。'),
|
|
772
|
+
};
|
|
773
|
+
}
|
|
774
|
+
|
|
775
|
+
/** 按颜色找色块。 */
|
|
776
|
+
export function findColorSpec() {
|
|
777
|
+
return {
|
|
778
|
+
name: 'vdisplay_find_color',
|
|
779
|
+
description: [
|
|
780
|
+
'按颜色找色块(颜色阈值 + 连通域)。找**固定颜色**的东西。',
|
|
781
|
+
'',
|
|
782
|
+
'适合:血条(红/绿)、按钮底色、选中边框、小地图上的敌我点、进度条、生命值/魔法值。',
|
|
783
|
+
'',
|
|
784
|
+
'**和模板匹配的分工**:模板找「形状固定但颜色会变」的(图标);',
|
|
785
|
+
'颜色找「颜色固定但位置/长度会变」的(血条、点位)。',
|
|
786
|
+
'',
|
|
787
|
+
'内部用 Lab 的 a/b 通道而不是绝对 RGB —— 实测 HDR/色温偏移下 RGB 阈值会全失效。',
|
|
788
|
+
'耗时 6.8ms(实测)。',
|
|
789
|
+
].join('\n'),
|
|
790
|
+
parameters: {
|
|
791
|
+
color: { type: 'object', additionalProperties: false, properties: { r: { type: 'integer', description: '红 0-255(给了 r/g/b 就不用 l/a/b)' }, g: { type: 'integer' }, b: { type: 'integer' }, l: { type: 'integer', description: 'Lab 亮度 0-255' }, a: { type: 'integer', description: 'Lab a 通道(绿-红)' }, b2: { type: 'integer' } }, required: true, description: '目标颜色。{r,g,b} 或 {l,a,b}' },
|
|
792
|
+
tolerance: { type: 'integer', description: 'Lab 空间容差,默认 20。找不到就调大(30-50)' },
|
|
793
|
+
minArea: { type: 'integer', description: '最小色块面积(像素),默认 200。小目标调小(50)' },
|
|
794
|
+
region: { type: 'object', additionalProperties: false, properties: { x: { type: 'integer' }, y: { type: 'integer' }, w: { type: 'integer' }, h: { type: 'integer' } }, description: '只在这块里找' },
|
|
795
|
+
},
|
|
796
|
+
output: out('找到几个色块、每个的位置和面积、最大的那个。'),
|
|
797
|
+
};
|
|
798
|
+
}
|
|
799
|
+
|
|
800
|
+
/** 找颜色并点最大色块。 */
|
|
801
|
+
export function tapColorSpec() {
|
|
802
|
+
return {
|
|
803
|
+
name: 'vdisplay_tap_color',
|
|
804
|
+
description: '按颜色找到最大色块并点击它。适合点「纯色按钮」「纯色图标」。',
|
|
805
|
+
parameters: {
|
|
806
|
+
color: { type: 'object', additionalProperties: false, properties: { r: { type: 'integer' }, g: { type: 'integer' }, b: { type: 'integer' }, l: { type: 'integer' }, a: { type: 'integer' }, b2: { type: 'integer' } }, required: true, description: '目标颜色 {r,g,b} 或 {l,a,b}' },
|
|
807
|
+
tolerance: { type: 'integer', description: 'Lab 容差,默认 20' },
|
|
808
|
+
minArea: { type: 'integer', description: '最小面积,默认 200' },
|
|
809
|
+
region: { type: 'object', additionalProperties: false, properties: { x: { type: 'integer' }, y: { type: 'integer' }, w: { type: 'integer' }, h: { type: 'integer' } }, description: '只在这块里找' },
|
|
810
|
+
},
|
|
811
|
+
output: out('点到没、坐标、色块大小。'),
|
|
812
|
+
};
|
|
813
|
+
}
|
|
814
|
+
|
|
815
|
+
/** 自动判断该用什么识别方法。 */
|
|
816
|
+
export function chooseMethodSpec() {
|
|
817
|
+
return {
|
|
818
|
+
name: 'vdisplay_choose_method',
|
|
819
|
+
description: [
|
|
820
|
+
'**第一次操作某个界面时先调这个** —— 它会量一下这个界面,告诉你该用什么识别方法。',
|
|
821
|
+
'',
|
|
822
|
+
'工具多了(OCR / 模板 / 颜色 / 指纹 / 差分),不知道该用哪个时用它。',
|
|
823
|
+
'它测三个东西并给出排序建议:',
|
|
824
|
+
' · 边缘密度 5-18% + 对比够 → 模板匹配(5.7ms)',
|
|
825
|
+
' · 颜色 top5 占比高 + 色数少 → 颜色检测(6.8ms)',
|
|
826
|
+
' · 文字界面 → OCR(1.9-3.3s,唯一能读懂内容的)',
|
|
827
|
+
'',
|
|
828
|
+
'**结果会按界面指纹缓存** —— 同一个界面第二次问直接返回,省 100ms。',
|
|
829
|
+
'换界面(指纹变了)会重新探测。',
|
|
830
|
+
].join('\n'),
|
|
831
|
+
parameters: {
|
|
832
|
+
key: { type: 'string', description: '缓存槽位名,默认 default。不同 App 用不同 key 互不干扰' },
|
|
833
|
+
fresh: { type: 'boolean', description: '强制重新探测,忽略缓存' },
|
|
834
|
+
},
|
|
835
|
+
output: out('界面统计 + 推荐的方法排序(含理由)。'),
|
|
836
|
+
};
|
|
837
|
+
}
|
|
838
|
+
|
|
839
|
+
/** 条件等待 —— 替代固定 sleep。 */
|
|
840
|
+
export function waitForSpec() {
|
|
841
|
+
return {
|
|
842
|
+
name: 'vdisplay_wait_for',
|
|
843
|
+
description: [
|
|
844
|
+
'等某个条件成立,替代「固定等 2 秒再截图」。**这是省时间最多的一个工具。**',
|
|
845
|
+
'',
|
|
846
|
+
'实测对比:固定等 2 秒 + OCR 2-3 秒 = 每步 4-5 秒;',
|
|
847
|
+
'用 wait_for 的门控(先 7ms 指纹看画面变没变,变了才跑 OCR)= 多数 150-400ms。',
|
|
848
|
+
'',
|
|
849
|
+
'判据(从便宜到贵):',
|
|
850
|
+
' · stable — 连续几次画面不变(转场结束,最便宜)',
|
|
851
|
+
' · fingerprint_changes — 画面变了没(7ms)',
|
|
852
|
+
' · diff_gt — 变化超过阈值(2.3ms + 截图)',
|
|
853
|
+
' · color_present — 出现某个颜色(6.8ms)',
|
|
854
|
+
' · text_appears/gone — 文字出现/消失(OCR,慢但有 cheapFirst 门控)',
|
|
855
|
+
'',
|
|
856
|
+
'**所有「点完等页面加载」的地方都该用它**,不要写固定 sleep。',
|
|
857
|
+
'',
|
|
858
|
+
'失败时会告诉你了多久、轮询几次、跑了几次 OCR —— 便于判断是超时还是判据写错。',
|
|
859
|
+
].join('\n'),
|
|
860
|
+
parameters: {
|
|
861
|
+
until: { type: 'string', required: true, description: 'text_appears | text_gone | fingerprint_changes | fingerprint_is | diff_gt | color_present | stable' },
|
|
862
|
+
text: { type: 'string', description: 'until=text_appears/text_gone 时要等的文字' },
|
|
863
|
+
hash: { type: 'string', description: 'until=fingerprint_is 时要比对的 16 位指纹(先用 vdisplay_fingerprint 拿)' },
|
|
864
|
+
color: { type: 'object', additionalProperties: false, properties: { r: { type: 'integer' }, g: { type: 'integer' }, b: { type: 'integer' } }, description: 'until=color_present 时等什么颜色 {r,g,b}' },
|
|
865
|
+
threshold: { type: 'number', description: 'until=diff_gt 的阈值(0-1),默认 0.15' },
|
|
866
|
+
timeoutMs: { type: 'integer', description: '最多等多少毫秒,默认 8000,上限 30000' },
|
|
867
|
+
pollMs: { type: 'integer', description: '轮询间隔,默认 150' },
|
|
868
|
+
cheapFirst: { type: 'boolean', description: '先用 7ms 指纹门控,画面没变就跳过 OCR。默认 true,别关' },
|
|
869
|
+
region: { type: 'object', additionalProperties: false, properties: { x: { type: 'integer' }, y: { type: 'integer' }, w: { type: 'integer' }, h: { type: 'integer' } }, description: '只在这块里找(主要给 color_present 用)' },
|
|
870
|
+
},
|
|
871
|
+
output: out('等到了没、等了多久、轮询几次、跑了几次 OCR。'),
|
|
872
|
+
};
|
|
873
|
+
}
|