dsh-quiet-windows 0.2.2 → 0.2.3

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/index.js CHANGED
@@ -1,571 +1,571 @@
1
- /**
2
- * dsh-quiet-windows —— 让 agent 在屏幕外「安静地」操作 GUI。
3
- *
4
- * 全部动作走 helper/quietwin.py(Python + pywin32 + uiautomation):
5
- * 窗口先隐藏启动、摆到所有显示器之外、再用 SW_SHOWNOACTIVATE 显示,
6
- * 之后用 UI Automation 读写控件、用 PrintWindow 截图(不吃遮挡、不怕离屏)。
7
- *
8
- * 为什么不用坐标点击:离屏窗口的坐标落在虚拟屏幕之外,光标会被夹回来;
9
- * 而且 175% 缩放下坐标换算一旦不感知 DPI 就整体偏 1.75 倍。控件模式绕开这两件事。
10
- *
11
- * @module dsh-quiet-windows
12
- */
13
- import { fileURLToPath } from 'node:url';
14
- import { mkdirSync } from 'node:fs';
15
- import { join, resolve as resolvePath } from 'node:path';
16
-
17
- export const name = 'quiet-windows';
18
- export const inject = ['subprocess', 'tools'];
19
-
20
- const HELPER = fileURLToPath(new URL('./helper/quietwin.py', import.meta.url));
21
- const STDOUT_LIMIT = 4 * 1024 * 1024;
22
-
23
- const DEFAULTS = {
24
- pythonPath: 'python',
25
- graceMs: 3000,
26
- timeoutMs: 120000,
27
- launchTimeoutMs: 180000,
28
- };
29
-
30
- /** 会话工作目录:截图等产物写在这里,便于后续读取。 */
31
- function sessionCwd(exec) {
32
- try {
33
- const cwd = exec?.agent?.session?.header?.cwd;
34
- if (typeof cwd === 'string' && cwd !== '') return cwd;
35
- } catch {
36
- /* ignore */
37
- }
38
- return process.cwd();
39
- }
40
-
41
- function asRecord(value) {
42
- return value !== null && typeof value === 'object' ? value : {};
43
- }
44
-
45
- function optionalString(args, key) {
46
- const value = args[key];
47
- return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
48
- }
49
-
50
- function requiredNumber(args, key, label) {
51
- const value = args[key];
52
- if (typeof value === 'number' && Number.isFinite(value)) return Math.trunc(value);
53
- if (typeof value === 'string' && /^\d+$/.test(value.trim())) return Number(value.trim());
54
- throw new Error(label + '(参数 ' + key + ')必须是窗口句柄数字。先用 quiet_windows 或 quiet_launch 拿到 hwnd。');
55
- }
56
-
57
- function optionalNumber(args, key) {
58
- const value = args[key];
59
- if (typeof value === 'number' && Number.isFinite(value)) return Math.trunc(value);
60
- return undefined;
61
- }
62
-
63
- const OBJECT_SCHEMA = { type: 'object', additionalProperties: true };
64
-
65
- function text(lines) {
66
- return [{ type: 'text', text: lines.join('\n') }];
67
- }
68
-
69
- // ---------------------------------------------------------------- python 解析
70
- // 插件跑的 Python 必须同时具备 pywin32 / uiautomation / comtypes / Pillow。
71
- // DSH 自带的运行时 Python 只有 Pillow,没有 pywin32 —— 所以不能盲信一个 "python"。
72
- const PY_PROBE = 'import sys, win32gui, uiautomation, comtypes, PIL; print("OK", sys.version.split()[0])';
73
-
74
- /** 按优先级列出候选解释器;prefix 是放在脚本前面的固定参数(py 需要 -3)。重复项去掉。 */
75
- function pythonCandidates(cfg) {
76
- const raw = [];
77
- const configured = typeof cfg.pythonPath === 'string' ? cfg.pythonPath.trim() : '';
78
- if (configured !== '') raw.push({ cmd: configured, prefix: [] });
79
- raw.push({ cmd: 'python', prefix: [] });
80
- raw.push({ cmd: 'py', prefix: ['-3'] });
81
- const local = process.env.LOCALAPPDATA;
82
- if (local) {
83
- for (const v of ['Python313', 'Python312', 'Python311', 'Python310']) {
84
- raw.push({ cmd: join(local, 'Programs', 'Python', v, 'python.exe'), prefix: [] });
85
- }
86
- }
87
- for (const v of ['Python313', 'Python312', 'Python311', 'Python310']) {
88
- raw.push({ cmd: 'C:\\' + v + '\\python.exe', prefix: [] });
89
- }
90
- const seen = new Set();
91
- return raw.filter((cand) => {
92
- const key = cand.cmd + '\u0000' + cand.prefix.join(',');
93
- if (seen.has(key)) return false;
94
- seen.add(key);
95
- return true;
96
- });
97
- }
98
-
99
- /**
100
- * 收一个短命令的全部输出。用于探测解释器,不解析 JSON。
101
- * 失败(ENOENT、超时)一律返回 ok:false,交给调用方换下一个候选。
102
- *
103
- * 注意 cwd 必须是字符串:宿主的 subprocess.spawn 会拿它做校验,传 undefined 会在
104
- * spawn 内部直接抛 "Cannot read properties of undefined (reading 'includes')"。
105
- */
106
- async function collect(ctx, cfg, argv, timeoutMs, cwd) {
107
- const workdir = typeof cwd === 'string' && cwd !== '' ? cwd : process.cwd();
108
- const controller = new AbortController();
109
- const timer = setTimeout(() => controller.abort(new Error('timeout')), timeoutMs);
110
- try {
111
- const handle = ctx.subprocess.spawn({
112
- argv,
113
- cwd: workdir,
114
- stdio: {
115
- stdin: 'ignore',
116
- stdout: { maxBytes: 64 * 1024 },
117
- stderr: { maxBytes: 64 * 1024 },
118
- },
119
- graceMs: 1500,
120
- signal: controller.signal,
121
- });
122
- const outcome = await handle.done;
123
- return {
124
- code: outcome.exitCode,
125
- stdout: handle.collected.stdout?.readFrom(0)?.text ?? '',
126
- stderr: handle.collected.stderr?.readFrom(0)?.text ?? '',
127
- };
128
- } catch (error) {
129
- return { code: null, stdout: '', stderr: String(error?.message ?? error) };
130
- } finally {
131
- clearTimeout(timer);
132
- }
133
- }
134
-
135
- let pythonCache = null;
136
-
137
- /**
138
- * 找一个能跑本 helper 的 Python,并缓存。
139
- * 全部候选都失败时抛一条能直接照做的错误,而不是让工具在第一次调用时才莫名其妙失败。
140
- */
141
- async function resolvePython(ctx, cfg, cwd) {
142
- if (pythonCache !== null) return pythonCache;
143
- const tried = [];
144
- for (const cand of pythonCandidates(cfg)) {
145
- const probe = await collect(ctx, cfg, [cand.cmd, ...cand.prefix, '-X', 'utf8', '-c', PY_PROBE], 20000, cwd);
146
- const line = probe.stdout.trim().split(/\r?\n/).filter((l) => l.startsWith('OK')).pop();
147
- if (line !== undefined) {
148
- pythonCache = { ...cand, version: line.slice(3).trim() };
149
- return pythonCache;
150
- }
151
- const reason = (probe.stderr.trim().split(/\r?\n/).pop() || '').slice(0, 160)
152
- || (probe.code === null ? '启动失败或超时' : '退出码 ' + String(probe.code));
153
- tried.push(' - ' + cand.cmd + (cand.prefix.length > 0 ? ' ' + cand.prefix.join(' ') : '') + ' → ' + reason);
154
- }
155
- throw new Error([
156
- '找不到可用的 Python:需要一个同时装有 pywin32、uiautomation、comtypes、Pillow 的解释器。',
157
- '已尝试:',
158
- ...tried,
159
- '修复方式(任选其一):',
160
- ' 1. 用 pip 装依赖:<那个 python> -m pip install pywin32 uiautomation comtypes pillow',
161
- ' 2. 在 profile 的 cordis.patch.yml 里给 quiet-windows 配 pythonPath 指向一个装好依赖的解释器(注意:DSH 自带的运行时 Python 没有 pywin32,不能用)。',
162
- ].join('\n'));
163
- }
164
-
165
- /** hwnd → 我们启动时记录的进程信息,用来防句柄复用和误杀。 */
166
- const knownWindows = new Map();
167
-
168
- /**
169
- * 跑一次 helper,返回解析后的 JSON。
170
- * 输出统一走 stdout 的 JSON;退出码非零时把 stdout 里的 error 也带出来,不吞信息。
171
- */
172
- async function runHelper(ctx, cfg, argv, options) {
173
- const py = await resolvePython(ctx, cfg, options.cwd);
174
- const timeoutMs = options.timeoutMs ?? cfg.timeoutMs;
175
- const controller = new AbortController();
176
- const timer = setTimeout(() => controller.abort(new Error('quietwin 超时(' + timeoutMs + 'ms)')), timeoutMs);
177
- const signal = options.signal === undefined
178
- ? controller.signal
179
- : AbortSignal.any([options.signal, controller.signal]);
180
- let handle;
181
- try {
182
- handle = ctx.subprocess.spawn({
183
- argv: [py.cmd, ...py.prefix, '-X', 'utf8', HELPER, ...argv, '--json'],
184
- cwd: typeof options.cwd === 'string' && options.cwd !== '' ? options.cwd : process.cwd(),
185
- stdio: {
186
- stdin: 'ignore',
187
- stdout: { maxBytes: STDOUT_LIMIT },
188
- stderr: { maxBytes: STDOUT_LIMIT },
189
- },
190
- graceMs: cfg.graceMs,
191
- signal,
192
- });
193
- const outcome = await handle.done;
194
- if (signal.aborted === true) throw signal.reason;
195
- const out = handle.collected.stdout?.readFrom(0)?.text ?? '';
196
- const err = handle.collected.stderr?.readFrom(0)?.text ?? '';
197
- const trimmed = out.trim();
198
- if (trimmed === '') {
199
- throw new Error('quietwin 没有输出(退出码 ' + String(outcome.exitCode ?? 'null') + '):' + (err.trim().split(/\r?\n/).slice(-4).join(' | ') || '无 stderr'));
200
- }
201
- let parsed;
202
- try {
203
- parsed = JSON.parse(trimmed.slice(trimmed.indexOf('{')));
204
- } catch {
205
- throw new Error('quietwin 输出不是 JSON:' + trimmed.slice(0, 300));
206
- }
207
- parsed._python = py.cmd + ' ' + py.version;
208
- return parsed;
209
- } finally {
210
- clearTimeout(timer);
211
- }
212
- }
213
-
214
- /** 给操作类命令补上 expect-pid:句柄被复用时 helper 会直接拒绝,而不是操作到别的窗口。 */
215
- function withExpectedPid(argv, hwnd) {
216
- const known = knownWindows.get(hwnd);
217
- if (known === undefined || !Number.isInteger(known.pid)) return argv;
218
- return [...argv, '--expect-pid', String(known.pid)];
219
- }
220
-
221
- function failText(value, fallback) {
222
- const rec = asRecord(value);
223
- const message = typeof rec.error === 'string' && rec.error !== '' ? rec.error : fallback;
224
- return '失败:' + message;
225
- }
226
-
227
- /** 一个窗口一行。 */
228
- function windowLine(w) {
229
- const rec = asRecord(w);
230
- const rect = Array.isArray(rec.rect) ? rec.rect : [];
231
- const size = rect.length === 4 ? (rect[2] - rect[0]) + 'x' + (rect[3] - rect[1]) : '?';
232
- const tags = [];
233
- if (rec.offscreen === true) tags.push('屏幕外');
234
- if (rec.minimized === true) tags.push('已最小化');
235
- if (rec.visible === false) tags.push('不可见');
236
- const flag = tags.length > 0 ? ' [' + tags.join(',') + ']' : '';
237
- return '- hwnd ' + rec.hwnd + ' · pid ' + rec.pid + ' · ' + size + flag + '\n ' + (rec.title || '(无标题)');
238
- }
239
-
240
- /** 把 UIA 控件树渲染成缩进文本,省略超量节点。 */
241
- function renderTree(items, limit = 200) {
242
- const list = Array.isArray(items) ? items : [];
243
- const lines = [];
244
- for (const raw of list.slice(0, limit)) {
245
- const item = asRecord(raw);
246
- const depth = typeof item.path === 'string' ? item.path.split('.').length - 1 : 0;
247
- const pats = Array.isArray(item.patterns) && item.patterns.length > 0
248
- ? ' {' + item.patterns.join(',') + '}'
249
- : '';
250
- const ident = item.auto_id ? ' id=' + item.auto_id : '';
251
- const klass = item.class ? ' class=' + item.class : '';
252
- lines.push(
253
- ' '.repeat(Math.min(depth, 8))
254
- + (item.path ?? '') + ' ' + (item.type ?? '?')
255
- + ' "' + (item.name ?? '') + '"' + klass + ident + pats,
256
- );
257
- }
258
- if (list.length > limit) lines.push('… 还有 ' + (list.length - limit) + ' 个节点未显示,缩小查询范围或降低 depth');
259
- return lines;
260
- }
261
-
262
- function buildTools(ctx, cfg) {
263
- const tools = [];
264
-
265
- tools.push({
266
- name: 'quiet_launch',
267
- isConcurrencySafe: () => false,
268
- description: '在屏幕外启动一个 GUI 程序:窗口从创建起就停在你所有显示器之外,全程不上屏,并尽量避免抢键盘焦点(被发现抢走会还回去),返回它的 hwnd。之后就配合 quiet_shot / quiet_tree / quiet_act 操作它。浏览器默认使用独立 profile,避免寄生到你已开的浏览器进程。',
269
- parameters: {
270
- type: 'object',
271
- properties: {
272
- exe: { type: 'string', description: '可执行文件的绝对路径,或 PATH 里的名字(如 charmap.exe、msedge.exe)。' },
273
- args: {
274
- type: 'array',
275
- items: { type: 'string' },
276
- description: '传给程序的命令行参数,逐项给出。网址、文件路径这类参数放这里。',
277
- },
278
- width: { type: 'number', description: '窗口宽度(像素,默认 1280)。' },
279
- height: { type: 'number', description: '窗口高度(像素,默认 860)。' },
280
- title: { type: 'string', description: '只接受窗口标题匹配这个正则的窗口(可选,用于程序会先弹出别的窗口时)。' },
281
- isolateProfile: {
282
- type: 'boolean',
283
- description: '浏览器是否使用独立 profile,默认 true。关掉后如果浏览器已在运行,新窗口会寄生到旧进程里,此时不会对该进程执行强制结束。',
284
- },
285
- keepOnFailure: {
286
- type: 'boolean',
287
- description: '启动失败时保留已拉起的进程(默认 false:失败即结束它并清理临时 profile,避免留下看不见的窗口)。',
288
- },
289
- },
290
- required: ['exe'],
291
- },
292
- output: { schema: OBJECT_SCHEMA, render: (_args, value) => {
293
- const rec = asRecord(value);
294
- if (rec.ok !== true) {
295
- const lines = [failText(rec, '启动失败')];
296
- if (rec.cleaned === true) lines.push('已结束本次拉起的进程,没有留下隐藏窗口。');
297
- if (rec.launched !== undefined) lines.push('命令行:' + JSON.stringify(rec.launched));
298
- return text(lines);
299
- }
300
- const lines = [
301
- '已在屏幕外启动:hwnd ' + rec.hwnd + ' · 窗口进程 pid ' + rec.pid,
302
- '标题:' + (rec.title || '(无标题)'),
303
- '矩形:' + JSON.stringify(rec.rect) + (rec.offscreen === true ? '(完全在所有显示器之外)' : '(警告:不在屏幕外)'),
304
- '上屏过:' + (rec.flashed === true ? '是(已被立刻挪走)' : '否'),
305
- '焦点:' + (rec.focus_stolen === true ? '曾被抢走,已尽量还回去' : '没有被动过'),
306
- ];
307
- if (rec.isolated_profile !== null && rec.isolated_profile !== undefined) {
308
- lines.push('独立 profile:' + rec.isolated_profile);
309
- }
310
- if (rec.shared_process === true) {
311
- lines.push('警告:窗口属于一个已有进程(不是本次启动的进程),不会对它执行强制结束。');
312
- }
313
- lines.push('下一步:quiet_shot 看画面,或 quiet_tree 读控件树。');
314
- return text(lines);
315
- } },
316
- timeoutMs: cfg.launchTimeoutMs,
317
- async execute(rawArgs, exec) {
318
- const args = asRecord(rawArgs);
319
- const exe = optionalString(args, 'exe');
320
- if (exe === undefined) throw new Error('exe 为必填:给出可执行文件路径或名字。');
321
- const argv = ['launch', '--exe', exe];
322
- const extra = Array.isArray(args.args) ? args.args.filter((a) => typeof a === 'string' && a !== '') : [];
323
- // 逐个 --arg 会被 argparse 当成选项(Chromium 的开关都以 '-' 开头),走 JSON 数组。
324
- if (extra.length > 0) argv.push('--argv-json', JSON.stringify(extra));
325
- const width = optionalNumber(args, 'width');
326
- const height = optionalNumber(args, 'height');
327
- if (width !== undefined) argv.push('--width', String(width));
328
- if (height !== undefined) argv.push('--height', String(height));
329
- const title = optionalString(args, 'title');
330
- if (title !== undefined) argv.push('--title', title);
331
- // 留给 helper 的等待上限必须比工具自身超时短,否则会先被掐断、拿不到干净的 JSON 错误。
332
- argv.push('--timeout', String(Math.max(5, Math.floor(cfg.launchTimeoutMs / 1000) - 8)));
333
- if (args.isolateProfile === false) argv.push('--no-isolate');
334
- if (args.keepOnFailure === true) argv.push('--keep-on-failure');
335
- const value = await runHelper(ctx, cfg, argv, {
336
- cwd: sessionCwd(exec), signal: exec?.signal, timeoutMs: cfg.launchTimeoutMs,
337
- });
338
- if (value.ok === true && Number.isInteger(value.hwnd)) {
339
- knownWindows.set(value.hwnd, {
340
- pid: value.pid,
341
- shared: value.shared_process === true,
342
- });
343
- }
344
- return value;
345
- },
346
- });
347
-
348
- tools.push({
349
- name: 'quiet_windows',
350
- isConcurrencySafe: () => true,
351
- description: '列出当前所有屏幕外窗口(就是安静启动的那些),以及显示器布局、DPI 和前台窗口。用来找回之前启动的 hwnd,或确认没有窗口漏在你屏幕上。',
352
- parameters: { type: 'object', properties: {} },
353
- output: { schema: OBJECT_SCHEMA, render: (_args, value) => {
354
- const rec = asRecord(value);
355
- if (rec.ok !== true) return text([failText(rec, '读取失败')]);
356
- const offscreen = Array.isArray(rec.offscreen) ? rec.offscreen : [];
357
- const lines = ['显示器:' + JSON.stringify(rec.monitors) + ',系统 DPI:' + rec.dpi];
358
- lines.push('屏幕外窗口:' + offscreen.length + ' 个');
359
- for (const w of offscreen) lines.push(windowLine(w));
360
- if (offscreen.length === 0) lines.push('- 没有。用 quiet_launch 启动一个。');
361
- return text(lines);
362
- } },
363
- timeoutMs: 30000,
364
- async execute(rawArgs, exec) {
365
- const value = await runHelper(ctx, cfg, ['list'], { cwd: sessionCwd(exec), signal: exec?.signal });
366
- for (const w of Array.isArray(value.offscreen) ? value.offscreen : []) {
367
- if (Number.isInteger(w?.hwnd) && !knownWindows.has(w.hwnd) && Number.isInteger(w.pid)) {
368
- knownWindows.set(w.hwnd, { pid: w.pid, shared: false });
369
- }
370
- }
371
- return value;
372
- },
373
- });
374
-
375
- tools.push({
376
- name: 'quiet_shot',
377
- isConcurrencySafe: () => true,
378
- description: '截取指定窗口当前的画面并存成 PNG,返回路径。截图来自窗口自己的渲染表面,因此即使窗口在屏幕外、被别的窗口完全盖住也能拿到;窗口被最小化时可能变黑(looks_blank 会标出来)。',
379
- parameters: {
380
- type: 'object',
381
- properties: { hwnd: { type: 'number', description: '窗口句柄,来自 quiet_launch 或 quiet_windows。' } },
382
- required: ['hwnd'],
383
- },
384
- output: { schema: OBJECT_SCHEMA, render: (_args, value) => {
385
- const rec = asRecord(value);
386
- if (rec.ok !== true) return text([failText(rec, '截图失败')]);
387
- const lines = [
388
- '截图:' + rec.path,
389
- '尺寸:' + rec.width + 'x' + rec.height + ',灰阶种类:' + rec.unique_gray,
390
- ];
391
- if (rec.looks_blank === true) {
392
- lines.push('警告:画面接近纯色,这个应用可能在屏幕外停止绘制。可改用虚拟显示器,或短暂把窗口搬到屏幕内。');
393
- } else {
394
- lines.push('下一步:用 read_image 读取这个路径查看画面。');
395
- }
396
- return text(lines);
397
- } },
398
- timeoutMs: 60000,
399
- async execute(rawArgs, exec) {
400
- const args = asRecord(rawArgs);
401
- const hwnd = requiredNumber(args, 'hwnd', '窗口句柄');
402
- const cwd = sessionCwd(exec);
403
- const dir = join(cwd, '.dsh-quiet');
404
- try {
405
- mkdirSync(dir, { recursive: true });
406
- } catch {
407
- /* 目录已存在 */
408
- }
409
- const out = join(dir, 'win-' + hwnd + '-' + Date.now() + '.png');
410
- return runHelper(ctx, cfg, withExpectedPid(['shot', '--hwnd', String(hwnd), '--out', out], hwnd), {
411
- cwd, signal: exec?.signal,
412
- });
413
- },
414
- });
415
-
416
- tools.push({
417
- name: 'quiet_tree',
418
- isConcurrencySafe: () => true,
419
- description: '读取窗口的 UI Automation 控件树:每个控件的类型、文字、class、AutomationId、可用模式(invoke / value / selectionitem / toggle / expandcollapse)。先看树,再用 quiet_act 按控件操作,不要猜坐标。',
420
- parameters: {
421
- type: 'object',
422
- properties: {
423
- hwnd: { type: 'number', description: '窗口句柄。' },
424
- depth: { type: 'number', description: '向下遍历的层数,默认 3;树太大时降低它。' },
425
- },
426
- required: ['hwnd'],
427
- },
428
- output: { schema: OBJECT_SCHEMA, render: (_args, value) => {
429
- const rec = asRecord(value);
430
- if (rec.ok !== true) return text([failText(rec, '读取控件树失败')]);
431
- const root = asRecord(rec.root);
432
- const lines = [
433
- '根:' + (root.type ?? '?') + ' "' + (root.name ?? '') + '" class=' + (root.class ?? ''),
434
- '节点数:' + rec.count + '(显示上限 200)',
435
- ];
436
- lines.push(...renderTree(rec.items));
437
- return text(lines);
438
- } },
439
- timeoutMs: 60000,
440
- async execute(rawArgs, exec) {
441
- const args = asRecord(rawArgs);
442
- const hwnd = requiredNumber(args, 'hwnd', '窗口句柄');
443
- const depth = optionalNumber(args, 'depth');
444
- const argv = ['tree', '--hwnd', String(hwnd)];
445
- if (depth !== undefined) argv.push('--depth', String(depth));
446
- return runHelper(ctx, cfg, withExpectedPid(argv, hwnd), { cwd: sessionCwd(exec), signal: exec?.signal });
447
- },
448
- });
449
-
450
- tools.push({
451
- name: 'quiet_act',
452
- isConcurrencySafe: () => false,
453
- description: '对控件执行一次操作,走控件自身的 UI Automation 模式(invoke / set / select / toggle / expand / collapse),不需要窗口在前台、不用坐标点击,通常不会把窗口搬到屏幕内。按 name / auto_id / class / type 定位控件,至少给一个;动作期间若键盘焦点被抢会试图还回去——是“尽量不打扰”,不是零干扰保证。',
454
- parameters: {
455
- type: 'object',
456
- properties: {
457
- hwnd: { type: 'number', description: '窗口句柄。' },
458
- op: {
459
- type: 'string',
460
- enum: ['invoke', 'set', 'select', 'toggle', 'expand', 'collapse', 'focus'],
461
- description: 'invoke=按按钮/链接;set=写输入框(配 value);select=选中列表项或标签页;toggle=勾选;expand/collapse=展开折叠。',
462
- },
463
- value: { type: 'string', description: 'op 为 set 时写入的文本。' },
464
- name: { type: 'string', description: '控件名包含这段文字(模糊匹配)。' },
465
- exact_name: { type: 'string', description: '控件名完全等于这段文字。' },
466
- auto_id: { type: 'string', description: '控件的 AutomationId。' },
467
- class: { type: 'string', description: '控件的窗口类名片段。' },
468
- type: { type: 'string', description: '控件类型,如 ButtonControl、EditControl、TabItemControl。' },
469
- },
470
- required: ['hwnd', 'op'],
471
- },
472
- output: { schema: OBJECT_SCHEMA, render: (_args, value) => {
473
- const rec = asRecord(value);
474
- if (rec.ok !== true) {
475
- const lines = [failText(rec, '操作失败')];
476
- if (rec.selector !== undefined) lines.push('选择器:' + JSON.stringify(rec.selector));
477
- lines.push('下一步:先 quiet_tree 确认控件名与可用模式,再重试。');
478
- return text(lines);
479
- }
480
- const before = rec.foreground_before;
481
- const after = rec.foreground_after;
482
- const focusLine = before === after
483
- ? '焦点:没有变化'
484
- : (rec.foreground_restored === true ? '焦点:曾移走,已还原' : '焦点:被移走且未能还原');
485
- return text([
486
- '已执行 ' + rec.op + ' → ' + (rec.type ?? '') + ' "' + (rec.target ?? '') + '"',
487
- focusLine,
488
- ]);
489
- } },
490
- timeoutMs: 60000,
491
- async execute(rawArgs, exec) {
492
- const args = asRecord(rawArgs);
493
- const hwnd = requiredNumber(args, 'hwnd', '窗口句柄');
494
- const op = optionalString(args, 'op');
495
- if (op === undefined) throw new Error('op 为必填:invoke / set / select / toggle / expand / collapse / focus。');
496
- const argv = ['act', '--hwnd', String(hwnd), '--op', op];
497
- const value = optionalString(args, 'value');
498
- if (value !== undefined) argv.push('--value', value);
499
- const map = [['name', '--name'], ['exact_name', '--exact-name'], ['class', '--class'], ['auto_id', '--auto-id'], ['type', '--type']];
500
- for (const [key, flag] of map) {
501
- const v = optionalString(args, key);
502
- if (v !== undefined) argv.push(flag, v);
503
- }
504
- if (!map.some(([key]) => optionalString(args, key) !== undefined)) {
505
- throw new Error('至少给出一个定位条件:name / exact_name / class / auto_id / type。');
506
- }
507
- return runHelper(ctx, cfg, withExpectedPid(argv, hwnd), { cwd: sessionCwd(exec), signal: exec?.signal });
508
- },
509
- });
510
-
511
- tools.push({
512
- name: 'quiet_close',
513
- isConcurrencySafe: () => false,
514
- description: '关闭一个屏幕外窗口(先正常关闭,进程不退就强制结束)。收尾用,避免留下看不见的进程。',
515
- parameters: {
516
- type: 'object',
517
- properties: {
518
- hwnd: { type: 'number', description: '窗口句柄。' },
519
- kill: { type: 'boolean', description: '关闭失败时强制结束进程(默认 false)。' },
520
- },
521
- required: ['hwnd'],
522
- },
523
- output: { schema: OBJECT_SCHEMA, render: (_args, value) => {
524
- const rec = asRecord(value);
525
- if (rec.ok !== true) return text([failText(rec, '关闭失败')]);
526
- const lines = [rec.closed === true ? '窗口已关闭。' : '已发出关闭请求,窗口仍在。可加 kill=true 强制结束。'];
527
- if (rec.killed === true) lines.push('进程已强制结束。');
528
- if (typeof rec.kill_skipped === 'string') lines.push(rec.kill_skipped);
529
- return text(lines);
530
- } },
531
- timeoutMs: 30000,
532
- async execute(rawArgs, exec) {
533
- const args = asRecord(rawArgs);
534
- const hwnd = requiredNumber(args, 'hwnd', '窗口句柄');
535
- const known = knownWindows.get(hwnd);
536
- const argv = ['close', '--hwnd', String(hwnd)];
537
- // 共享进程(寄生到用户已开的浏览器里)绝不强制结束,只关这个窗口。
538
- const wantKill = args.kill === true && known?.shared !== true;
539
- if (wantKill) argv.push('--kill');
540
- if (Number.isInteger(known?.pid)) argv.push('--expect-pid', String(known.pid));
541
- const value = await runHelper(ctx, cfg, argv, { cwd: sessionCwd(exec), signal: exec?.signal });
542
- if (value.ok === true && value.closed === true) knownWindows.delete(hwnd);
543
- if (args.kill === true && !wantKill) {
544
- value.kill_skipped = '这个窗口属于一个已有进程(共享),已跳过强制结束,只关闭了窗口本身。';
545
- }
546
- return value;
547
- },
548
- });
549
-
550
- return tools;
551
- }
552
-
553
- export function apply(ctx, config) {
554
- const cfg = { ...DEFAULTS, ...(config === null || config === undefined ? {} : asRecord(config)) };
555
- const disposers = [];
556
- try {
557
- for (const definition of buildTools(ctx, cfg)) {
558
- disposers.push(ctx.tools.register(definition));
559
- }
560
- } catch (error) {
561
- for (const dispose of disposers) dispose();
562
- throw error;
563
- }
564
- const teardown = () => {
565
- for (const dispose of disposers) dispose();
566
- };
567
- if (typeof ctx.effect === 'function') ctx.effect(() => teardown, 'quiet-windows.tools()');
568
- else if (typeof ctx.on === 'function') ctx.on('dispose', teardown);
569
- }
570
-
571
- export { HELPER as helperPath, resolvePath };
1
+ /**
2
+ * dsh-quiet-windows —— 让 agent 在屏幕外「安静地」操作 GUI。
3
+ *
4
+ * 全部动作走 helper/quietwin.py(Python + pywin32 + uiautomation):
5
+ * 窗口先隐藏启动、摆到所有显示器之外、再用 SW_SHOWNOACTIVATE 显示,
6
+ * 之后用 UI Automation 读写控件、用 PrintWindow 截图(不吃遮挡、不怕离屏)。
7
+ *
8
+ * 为什么不用坐标点击:离屏窗口的坐标落在虚拟屏幕之外,光标会被夹回来;
9
+ * 而且 175% 缩放下坐标换算一旦不感知 DPI 就整体偏 1.75 倍。控件模式绕开这两件事。
10
+ *
11
+ * @module dsh-quiet-windows
12
+ */
13
+ import { fileURLToPath } from 'node:url';
14
+ import { mkdirSync } from 'node:fs';
15
+ import { join, resolve as resolvePath } from 'node:path';
16
+
17
+ export const name = 'quiet-windows';
18
+ export const inject = ['subprocess', 'tools'];
19
+
20
+ const HELPER = fileURLToPath(new URL('./helper/quietwin.py', import.meta.url));
21
+ const STDOUT_LIMIT = 4 * 1024 * 1024;
22
+
23
+ const DEFAULTS = {
24
+ pythonPath: 'python',
25
+ graceMs: 3000,
26
+ timeoutMs: 120000,
27
+ launchTimeoutMs: 180000,
28
+ };
29
+
30
+ /** 会话工作目录:截图等产物写在这里,便于后续读取。 */
31
+ function sessionCwd(exec) {
32
+ try {
33
+ const cwd = exec?.agent?.session?.header?.cwd;
34
+ if (typeof cwd === 'string' && cwd !== '') return cwd;
35
+ } catch {
36
+ /* ignore */
37
+ }
38
+ return process.cwd();
39
+ }
40
+
41
+ function asRecord(value) {
42
+ return value !== null && typeof value === 'object' ? value : {};
43
+ }
44
+
45
+ function optionalString(args, key) {
46
+ const value = args[key];
47
+ return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
48
+ }
49
+
50
+ function requiredNumber(args, key, label) {
51
+ const value = args[key];
52
+ if (typeof value === 'number' && Number.isFinite(value)) return Math.trunc(value);
53
+ if (typeof value === 'string' && /^\d+$/.test(value.trim())) return Number(value.trim());
54
+ throw new Error(label + '(参数 ' + key + ')必须是窗口句柄数字。先用 quiet_windows 或 quiet_launch 拿到 hwnd。');
55
+ }
56
+
57
+ function optionalNumber(args, key) {
58
+ const value = args[key];
59
+ if (typeof value === 'number' && Number.isFinite(value)) return Math.trunc(value);
60
+ return undefined;
61
+ }
62
+
63
+ const OBJECT_SCHEMA = { type: 'object', additionalProperties: true };
64
+
65
+ function text(lines) {
66
+ return [{ type: 'text', text: lines.join('\n') }];
67
+ }
68
+
69
+ // ---------------------------------------------------------------- python 解析
70
+ // 插件跑的 Python 必须同时具备 pywin32 / uiautomation / comtypes / Pillow。
71
+ // DSH 自带的运行时 Python 只有 Pillow,没有 pywin32 —— 所以不能盲信一个 "python"。
72
+ const PY_PROBE = 'import sys, win32gui, uiautomation, comtypes, PIL; print("OK", sys.version.split()[0])';
73
+
74
+ /** 按优先级列出候选解释器;prefix 是放在脚本前面的固定参数(py 需要 -3)。重复项去掉。 */
75
+ function pythonCandidates(cfg) {
76
+ const raw = [];
77
+ const configured = typeof cfg.pythonPath === 'string' ? cfg.pythonPath.trim() : '';
78
+ if (configured !== '') raw.push({ cmd: configured, prefix: [] });
79
+ raw.push({ cmd: 'python', prefix: [] });
80
+ raw.push({ cmd: 'py', prefix: ['-3'] });
81
+ const local = process.env.LOCALAPPDATA;
82
+ if (local) {
83
+ for (const v of ['Python313', 'Python312', 'Python311', 'Python310']) {
84
+ raw.push({ cmd: join(local, 'Programs', 'Python', v, 'python.exe'), prefix: [] });
85
+ }
86
+ }
87
+ for (const v of ['Python313', 'Python312', 'Python311', 'Python310']) {
88
+ raw.push({ cmd: 'C:\\' + v + '\\python.exe', prefix: [] });
89
+ }
90
+ const seen = new Set();
91
+ return raw.filter((cand) => {
92
+ const key = cand.cmd + '\u0000' + cand.prefix.join(',');
93
+ if (seen.has(key)) return false;
94
+ seen.add(key);
95
+ return true;
96
+ });
97
+ }
98
+
99
+ /**
100
+ * 收一个短命令的全部输出。用于探测解释器,不解析 JSON。
101
+ * 失败(ENOENT、超时)一律返回 ok:false,交给调用方换下一个候选。
102
+ *
103
+ * 注意 cwd 必须是字符串:宿主的 subprocess.spawn 会拿它做校验,传 undefined 会在
104
+ * spawn 内部直接抛 "Cannot read properties of undefined (reading 'includes')"。
105
+ */
106
+ async function collect(ctx, cfg, argv, timeoutMs, cwd) {
107
+ const workdir = typeof cwd === 'string' && cwd !== '' ? cwd : process.cwd();
108
+ const controller = new AbortController();
109
+ const timer = setTimeout(() => controller.abort(new Error('timeout')), timeoutMs);
110
+ try {
111
+ const handle = ctx.subprocess.spawn({
112
+ argv,
113
+ cwd: workdir,
114
+ stdio: {
115
+ stdin: 'ignore',
116
+ stdout: { maxBytes: 64 * 1024 },
117
+ stderr: { maxBytes: 64 * 1024 },
118
+ },
119
+ graceMs: 1500,
120
+ signal: controller.signal,
121
+ });
122
+ const outcome = await handle.done;
123
+ return {
124
+ code: outcome.exitCode,
125
+ stdout: handle.collected.stdout?.readFrom(0)?.text ?? '',
126
+ stderr: handle.collected.stderr?.readFrom(0)?.text ?? '',
127
+ };
128
+ } catch (error) {
129
+ return { code: null, stdout: '', stderr: String(error?.message ?? error) };
130
+ } finally {
131
+ clearTimeout(timer);
132
+ }
133
+ }
134
+
135
+ let pythonCache = null;
136
+
137
+ /**
138
+ * 找一个能跑本 helper 的 Python,并缓存。
139
+ * 全部候选都失败时抛一条能直接照做的错误,而不是让工具在第一次调用时才莫名其妙失败。
140
+ */
141
+ async function resolvePython(ctx, cfg, cwd) {
142
+ if (pythonCache !== null) return pythonCache;
143
+ const tried = [];
144
+ for (const cand of pythonCandidates(cfg)) {
145
+ const probe = await collect(ctx, cfg, [cand.cmd, ...cand.prefix, '-X', 'utf8', '-c', PY_PROBE], 20000, cwd);
146
+ const line = probe.stdout.trim().split(/\r?\n/).filter((l) => l.startsWith('OK')).pop();
147
+ if (line !== undefined) {
148
+ pythonCache = { ...cand, version: line.slice(3).trim() };
149
+ return pythonCache;
150
+ }
151
+ const reason = (probe.stderr.trim().split(/\r?\n/).pop() || '').slice(0, 160)
152
+ || (probe.code === null ? '启动失败或超时' : '退出码 ' + String(probe.code));
153
+ tried.push(' - ' + cand.cmd + (cand.prefix.length > 0 ? ' ' + cand.prefix.join(' ') : '') + ' → ' + reason);
154
+ }
155
+ throw new Error([
156
+ '找不到可用的 Python:需要一个同时装有 pywin32、uiautomation、comtypes、Pillow 的解释器。',
157
+ '已尝试:',
158
+ ...tried,
159
+ '修复方式(任选其一):',
160
+ ' 1. 用 pip 装依赖:<那个 python> -m pip install pywin32 uiautomation comtypes pillow',
161
+ ' 2. 在 profile 的 cordis.patch.yml 里给 quiet-windows 配 pythonPath 指向一个装好依赖的解释器(注意:DSH 自带的运行时 Python 没有 pywin32,不能用)。',
162
+ ].join('\n'));
163
+ }
164
+
165
+ /** hwnd → 我们启动时记录的进程信息,用来防句柄复用和误杀。 */
166
+ const knownWindows = new Map();
167
+
168
+ /**
169
+ * 跑一次 helper,返回解析后的 JSON。
170
+ * 输出统一走 stdout 的 JSON;退出码非零时把 stdout 里的 error 也带出来,不吞信息。
171
+ */
172
+ async function runHelper(ctx, cfg, argv, options) {
173
+ const py = await resolvePython(ctx, cfg, options.cwd);
174
+ const timeoutMs = options.timeoutMs ?? cfg.timeoutMs;
175
+ const controller = new AbortController();
176
+ const timer = setTimeout(() => controller.abort(new Error('quietwin 超时(' + timeoutMs + 'ms)')), timeoutMs);
177
+ const signal = options.signal === undefined
178
+ ? controller.signal
179
+ : AbortSignal.any([options.signal, controller.signal]);
180
+ let handle;
181
+ try {
182
+ handle = ctx.subprocess.spawn({
183
+ argv: [py.cmd, ...py.prefix, '-X', 'utf8', HELPER, ...argv, '--json'],
184
+ cwd: typeof options.cwd === 'string' && options.cwd !== '' ? options.cwd : process.cwd(),
185
+ stdio: {
186
+ stdin: 'ignore',
187
+ stdout: { maxBytes: STDOUT_LIMIT },
188
+ stderr: { maxBytes: STDOUT_LIMIT },
189
+ },
190
+ graceMs: cfg.graceMs,
191
+ signal,
192
+ });
193
+ const outcome = await handle.done;
194
+ if (signal.aborted === true) throw signal.reason;
195
+ const out = handle.collected.stdout?.readFrom(0)?.text ?? '';
196
+ const err = handle.collected.stderr?.readFrom(0)?.text ?? '';
197
+ const trimmed = out.trim();
198
+ if (trimmed === '') {
199
+ throw new Error('quietwin 没有输出(退出码 ' + String(outcome.exitCode ?? 'null') + '):' + (err.trim().split(/\r?\n/).slice(-4).join(' | ') || '无 stderr'));
200
+ }
201
+ let parsed;
202
+ try {
203
+ parsed = JSON.parse(trimmed.slice(trimmed.indexOf('{')));
204
+ } catch {
205
+ throw new Error('quietwin 输出不是 JSON:' + trimmed.slice(0, 300));
206
+ }
207
+ parsed._python = py.cmd + ' ' + py.version;
208
+ return parsed;
209
+ } finally {
210
+ clearTimeout(timer);
211
+ }
212
+ }
213
+
214
+ /** 给操作类命令补上 expect-pid:句柄被复用时 helper 会直接拒绝,而不是操作到别的窗口。 */
215
+ function withExpectedPid(argv, hwnd) {
216
+ const known = knownWindows.get(hwnd);
217
+ if (known === undefined || !Number.isInteger(known.pid)) return argv;
218
+ return [...argv, '--expect-pid', String(known.pid)];
219
+ }
220
+
221
+ function failText(value, fallback) {
222
+ const rec = asRecord(value);
223
+ const message = typeof rec.error === 'string' && rec.error !== '' ? rec.error : fallback;
224
+ return '失败:' + message;
225
+ }
226
+
227
+ /** 一个窗口一行。 */
228
+ function windowLine(w) {
229
+ const rec = asRecord(w);
230
+ const rect = Array.isArray(rec.rect) ? rec.rect : [];
231
+ const size = rect.length === 4 ? (rect[2] - rect[0]) + 'x' + (rect[3] - rect[1]) : '?';
232
+ const tags = [];
233
+ if (rec.offscreen === true) tags.push('屏幕外');
234
+ if (rec.minimized === true) tags.push('已最小化');
235
+ if (rec.visible === false) tags.push('不可见');
236
+ const flag = tags.length > 0 ? ' [' + tags.join(',') + ']' : '';
237
+ return '- hwnd ' + rec.hwnd + ' · pid ' + rec.pid + ' · ' + size + flag + '\n ' + (rec.title || '(无标题)');
238
+ }
239
+
240
+ /** 把 UIA 控件树渲染成缩进文本,省略超量节点。 */
241
+ function renderTree(items, limit = 200) {
242
+ const list = Array.isArray(items) ? items : [];
243
+ const lines = [];
244
+ for (const raw of list.slice(0, limit)) {
245
+ const item = asRecord(raw);
246
+ const depth = typeof item.path === 'string' ? item.path.split('.').length - 1 : 0;
247
+ const pats = Array.isArray(item.patterns) && item.patterns.length > 0
248
+ ? ' {' + item.patterns.join(',') + '}'
249
+ : '';
250
+ const ident = item.auto_id ? ' id=' + item.auto_id : '';
251
+ const klass = item.class ? ' class=' + item.class : '';
252
+ lines.push(
253
+ ' '.repeat(Math.min(depth, 8))
254
+ + (item.path ?? '') + ' ' + (item.type ?? '?')
255
+ + ' "' + (item.name ?? '') + '"' + klass + ident + pats,
256
+ );
257
+ }
258
+ if (list.length > limit) lines.push('… 还有 ' + (list.length - limit) + ' 个节点未显示,缩小查询范围或降低 depth');
259
+ return lines;
260
+ }
261
+
262
+ function buildTools(ctx, cfg) {
263
+ const tools = [];
264
+
265
+ tools.push({
266
+ name: 'quiet_launch',
267
+ isConcurrencySafe: () => false,
268
+ description: '在屏幕外启动一个 GUI 程序:窗口从创建起就停在你所有显示器之外,全程不上屏,并尽量避免抢键盘焦点(被发现抢走会还回去),返回它的 hwnd。之后就配合 quiet_shot / quiet_tree / quiet_act 操作它。浏览器默认使用独立 profile,避免寄生到你已开的浏览器进程。要打开任何界面程序都用这个,不要用 Start-Process、cmd、手写 CreateProcess 或 ShowWindow。',
269
+ parameters: {
270
+ type: 'object',
271
+ properties: {
272
+ exe: { type: 'string', description: '可执行文件的绝对路径,或 PATH 里的名字(如 charmap.exe、msedge.exe)。' },
273
+ args: {
274
+ type: 'array',
275
+ items: { type: 'string' },
276
+ description: '传给程序的命令行参数,逐项给出。网址、文件路径这类参数放这里。',
277
+ },
278
+ width: { type: 'number', description: '窗口宽度(像素,默认 1280)。' },
279
+ height: { type: 'number', description: '窗口高度(像素,默认 860)。' },
280
+ title: { type: 'string', description: '只接受窗口标题匹配这个正则的窗口(可选,用于程序会先弹出别的窗口时)。' },
281
+ isolateProfile: {
282
+ type: 'boolean',
283
+ description: '浏览器是否使用独立 profile,默认 true。关掉后如果浏览器已在运行,新窗口会寄生到旧进程里,此时不会对该进程执行强制结束。',
284
+ },
285
+ keepOnFailure: {
286
+ type: 'boolean',
287
+ description: '启动失败时保留已拉起的进程(默认 false:失败即结束它并清理临时 profile,避免留下看不见的窗口)。',
288
+ },
289
+ },
290
+ required: ['exe'],
291
+ },
292
+ output: { schema: OBJECT_SCHEMA, render: (_args, value) => {
293
+ const rec = asRecord(value);
294
+ if (rec.ok !== true) {
295
+ const lines = [failText(rec, '启动失败')];
296
+ if (rec.cleaned === true) lines.push('已结束本次拉起的进程,没有留下隐藏窗口。');
297
+ if (rec.launched !== undefined) lines.push('命令行:' + JSON.stringify(rec.launched));
298
+ return text(lines);
299
+ }
300
+ const lines = [
301
+ '已在屏幕外启动:hwnd ' + rec.hwnd + ' · 窗口进程 pid ' + rec.pid,
302
+ '标题:' + (rec.title || '(无标题)'),
303
+ '矩形:' + JSON.stringify(rec.rect) + (rec.offscreen === true ? '(完全在所有显示器之外)' : '(警告:不在屏幕外)'),
304
+ '上屏过:' + (rec.flashed === true ? '是(已被立刻挪走)' : '否'),
305
+ '焦点:' + (rec.focus_stolen === true ? '曾被抢走,已尽量还回去' : '没有被动过'),
306
+ ];
307
+ if (rec.isolated_profile !== null && rec.isolated_profile !== undefined) {
308
+ lines.push('独立 profile:' + rec.isolated_profile);
309
+ }
310
+ if (rec.shared_process === true) {
311
+ lines.push('警告:窗口属于一个已有进程(不是本次启动的进程),不会对它执行强制结束。');
312
+ }
313
+ lines.push('下一步:quiet_shot 看画面,或 quiet_tree 读控件树。');
314
+ return text(lines);
315
+ } },
316
+ timeoutMs: cfg.launchTimeoutMs,
317
+ async execute(rawArgs, exec) {
318
+ const args = asRecord(rawArgs);
319
+ const exe = optionalString(args, 'exe');
320
+ if (exe === undefined) throw new Error('exe 为必填:给出可执行文件路径或名字。');
321
+ const argv = ['launch', '--exe', exe];
322
+ const extra = Array.isArray(args.args) ? args.args.filter((a) => typeof a === 'string' && a !== '') : [];
323
+ // 逐个 --arg 会被 argparse 当成选项(Chromium 的开关都以 '-' 开头),走 JSON 数组。
324
+ if (extra.length > 0) argv.push('--argv-json', JSON.stringify(extra));
325
+ const width = optionalNumber(args, 'width');
326
+ const height = optionalNumber(args, 'height');
327
+ if (width !== undefined) argv.push('--width', String(width));
328
+ if (height !== undefined) argv.push('--height', String(height));
329
+ const title = optionalString(args, 'title');
330
+ if (title !== undefined) argv.push('--title', title);
331
+ // 留给 helper 的等待上限必须比工具自身超时短,否则会先被掐断、拿不到干净的 JSON 错误。
332
+ argv.push('--timeout', String(Math.max(5, Math.floor(cfg.launchTimeoutMs / 1000) - 8)));
333
+ if (args.isolateProfile === false) argv.push('--no-isolate');
334
+ if (args.keepOnFailure === true) argv.push('--keep-on-failure');
335
+ const value = await runHelper(ctx, cfg, argv, {
336
+ cwd: sessionCwd(exec), signal: exec?.signal, timeoutMs: cfg.launchTimeoutMs,
337
+ });
338
+ if (value.ok === true && Number.isInteger(value.hwnd)) {
339
+ knownWindows.set(value.hwnd, {
340
+ pid: value.pid,
341
+ shared: value.shared_process === true,
342
+ });
343
+ }
344
+ return value;
345
+ },
346
+ });
347
+
348
+ tools.push({
349
+ name: 'quiet_windows',
350
+ isConcurrencySafe: () => true,
351
+ description: '列出当前所有屏幕外窗口(就是安静启动的那些),以及显示器布局、DPI 和前台窗口。用来找回之前启动的 hwnd,或确认没有窗口漏在你屏幕上。',
352
+ parameters: { type: 'object', properties: {} },
353
+ output: { schema: OBJECT_SCHEMA, render: (_args, value) => {
354
+ const rec = asRecord(value);
355
+ if (rec.ok !== true) return text([failText(rec, '读取失败')]);
356
+ const offscreen = Array.isArray(rec.offscreen) ? rec.offscreen : [];
357
+ const lines = ['显示器:' + JSON.stringify(rec.monitors) + ',系统 DPI:' + rec.dpi];
358
+ lines.push('屏幕外窗口:' + offscreen.length + ' 个');
359
+ for (const w of offscreen) lines.push(windowLine(w));
360
+ if (offscreen.length === 0) lines.push('- 没有。用 quiet_launch 启动一个。');
361
+ return text(lines);
362
+ } },
363
+ timeoutMs: 30000,
364
+ async execute(rawArgs, exec) {
365
+ const value = await runHelper(ctx, cfg, ['list'], { cwd: sessionCwd(exec), signal: exec?.signal });
366
+ for (const w of Array.isArray(value.offscreen) ? value.offscreen : []) {
367
+ if (Number.isInteger(w?.hwnd) && !knownWindows.has(w.hwnd) && Number.isInteger(w.pid)) {
368
+ knownWindows.set(w.hwnd, { pid: w.pid, shared: false });
369
+ }
370
+ }
371
+ return value;
372
+ },
373
+ });
374
+
375
+ tools.push({
376
+ name: 'quiet_shot',
377
+ isConcurrencySafe: () => true,
378
+ description: '截取指定窗口当前的画面并存成 PNG,返回路径。截图来自窗口自己的渲染表面,因此即使窗口在屏幕外、被别的窗口完全盖住也能拿到;窗口被最小化时可能变黑(looks_blank 会标出来)。要截任何窗口都用这个,不要用 CopyFromScreen、ImageGrab、BitBlt 或 PrintWindow 手写脚本——它们要么要求窗口在屏上、要么会带上遮挡、要么 DPI 不对。',
379
+ parameters: {
380
+ type: 'object',
381
+ properties: { hwnd: { type: 'number', description: '窗口句柄,来自 quiet_launch 或 quiet_windows。' } },
382
+ required: ['hwnd'],
383
+ },
384
+ output: { schema: OBJECT_SCHEMA, render: (_args, value) => {
385
+ const rec = asRecord(value);
386
+ if (rec.ok !== true) return text([failText(rec, '截图失败')]);
387
+ const lines = [
388
+ '截图:' + rec.path,
389
+ '尺寸:' + rec.width + 'x' + rec.height + ',灰阶种类:' + rec.unique_gray,
390
+ ];
391
+ if (rec.looks_blank === true) {
392
+ lines.push('警告:画面接近纯色,这个应用可能在屏幕外停止绘制。可改用虚拟显示器,或短暂把窗口搬到屏幕内。');
393
+ } else {
394
+ lines.push('下一步:用 read_image 读取这个路径查看画面。');
395
+ }
396
+ return text(lines);
397
+ } },
398
+ timeoutMs: 60000,
399
+ async execute(rawArgs, exec) {
400
+ const args = asRecord(rawArgs);
401
+ const hwnd = requiredNumber(args, 'hwnd', '窗口句柄');
402
+ const cwd = sessionCwd(exec);
403
+ const dir = join(cwd, '.dsh-quiet');
404
+ try {
405
+ mkdirSync(dir, { recursive: true });
406
+ } catch {
407
+ /* 目录已存在 */
408
+ }
409
+ const out = join(dir, 'win-' + hwnd + '-' + Date.now() + '.png');
410
+ return runHelper(ctx, cfg, withExpectedPid(['shot', '--hwnd', String(hwnd), '--out', out], hwnd), {
411
+ cwd, signal: exec?.signal,
412
+ });
413
+ },
414
+ });
415
+
416
+ tools.push({
417
+ name: 'quiet_tree',
418
+ isConcurrencySafe: () => true,
419
+ description: '读取窗口的 UI Automation 控件树:每个控件的类型、文字、class、AutomationId、可用模式(invoke / value / selectionitem / toggle / expandcollapse)。先看树,再用 quiet_act 按控件操作,不要猜坐标。读控件树本身也用它,不要自己 pip install uiautomation 再写脚本。',
420
+ parameters: {
421
+ type: 'object',
422
+ properties: {
423
+ hwnd: { type: 'number', description: '窗口句柄。' },
424
+ depth: { type: 'number', description: '向下遍历的层数,默认 3;树太大时降低它。' },
425
+ },
426
+ required: ['hwnd'],
427
+ },
428
+ output: { schema: OBJECT_SCHEMA, render: (_args, value) => {
429
+ const rec = asRecord(value);
430
+ if (rec.ok !== true) return text([failText(rec, '读取控件树失败')]);
431
+ const root = asRecord(rec.root);
432
+ const lines = [
433
+ '根:' + (root.type ?? '?') + ' "' + (root.name ?? '') + '" class=' + (root.class ?? ''),
434
+ '节点数:' + rec.count + '(显示上限 200)',
435
+ ];
436
+ lines.push(...renderTree(rec.items));
437
+ return text(lines);
438
+ } },
439
+ timeoutMs: 60000,
440
+ async execute(rawArgs, exec) {
441
+ const args = asRecord(rawArgs);
442
+ const hwnd = requiredNumber(args, 'hwnd', '窗口句柄');
443
+ const depth = optionalNumber(args, 'depth');
444
+ const argv = ['tree', '--hwnd', String(hwnd)];
445
+ if (depth !== undefined) argv.push('--depth', String(depth));
446
+ return runHelper(ctx, cfg, withExpectedPid(argv, hwnd), { cwd: sessionCwd(exec), signal: exec?.signal });
447
+ },
448
+ });
449
+
450
+ tools.push({
451
+ name: 'quiet_act',
452
+ isConcurrencySafe: () => false,
453
+ description: '对控件执行一次操作,走控件自身的 UI Automation 模式(invoke / set / select / toggle / expand / collapse),不需要窗口在前台、不用坐标点击,通常不会把窗口搬到屏幕内。按 name / auto_id / class / type 定位控件,至少给一个;动作期间若键盘焦点被抢会试图还回去——是“尽量不打扰”,不是零干扰保证。点按钮、填输入框都用这个,不要用 SetCursorPos + mouse_event 点坐标,也不要 SendKeys。',
454
+ parameters: {
455
+ type: 'object',
456
+ properties: {
457
+ hwnd: { type: 'number', description: '窗口句柄。' },
458
+ op: {
459
+ type: 'string',
460
+ enum: ['invoke', 'set', 'select', 'toggle', 'expand', 'collapse', 'focus'],
461
+ description: 'invoke=按按钮/链接;set=写输入框(配 value);select=选中列表项或标签页;toggle=勾选;expand/collapse=展开折叠。',
462
+ },
463
+ value: { type: 'string', description: 'op 为 set 时写入的文本。' },
464
+ name: { type: 'string', description: '控件名包含这段文字(模糊匹配)。' },
465
+ exact_name: { type: 'string', description: '控件名完全等于这段文字。' },
466
+ auto_id: { type: 'string', description: '控件的 AutomationId。' },
467
+ class: { type: 'string', description: '控件的窗口类名片段。' },
468
+ type: { type: 'string', description: '控件类型,如 ButtonControl、EditControl、TabItemControl。' },
469
+ },
470
+ required: ['hwnd', 'op'],
471
+ },
472
+ output: { schema: OBJECT_SCHEMA, render: (_args, value) => {
473
+ const rec = asRecord(value);
474
+ if (rec.ok !== true) {
475
+ const lines = [failText(rec, '操作失败')];
476
+ if (rec.selector !== undefined) lines.push('选择器:' + JSON.stringify(rec.selector));
477
+ lines.push('下一步:先 quiet_tree 确认控件名与可用模式,再重试。');
478
+ return text(lines);
479
+ }
480
+ const before = rec.foreground_before;
481
+ const after = rec.foreground_after;
482
+ const focusLine = before === after
483
+ ? '焦点:没有变化'
484
+ : (rec.foreground_restored === true ? '焦点:曾移走,已还原' : '焦点:被移走且未能还原');
485
+ return text([
486
+ '已执行 ' + rec.op + ' → ' + (rec.type ?? '') + ' "' + (rec.target ?? '') + '"',
487
+ focusLine,
488
+ ]);
489
+ } },
490
+ timeoutMs: 60000,
491
+ async execute(rawArgs, exec) {
492
+ const args = asRecord(rawArgs);
493
+ const hwnd = requiredNumber(args, 'hwnd', '窗口句柄');
494
+ const op = optionalString(args, 'op');
495
+ if (op === undefined) throw new Error('op 为必填:invoke / set / select / toggle / expand / collapse / focus。');
496
+ const argv = ['act', '--hwnd', String(hwnd), '--op', op];
497
+ const value = optionalString(args, 'value');
498
+ if (value !== undefined) argv.push('--value', value);
499
+ const map = [['name', '--name'], ['exact_name', '--exact-name'], ['class', '--class'], ['auto_id', '--auto-id'], ['type', '--type']];
500
+ for (const [key, flag] of map) {
501
+ const v = optionalString(args, key);
502
+ if (v !== undefined) argv.push(flag, v);
503
+ }
504
+ if (!map.some(([key]) => optionalString(args, key) !== undefined)) {
505
+ throw new Error('至少给出一个定位条件:name / exact_name / class / auto_id / type。');
506
+ }
507
+ return runHelper(ctx, cfg, withExpectedPid(argv, hwnd), { cwd: sessionCwd(exec), signal: exec?.signal });
508
+ },
509
+ });
510
+
511
+ tools.push({
512
+ name: 'quiet_close',
513
+ isConcurrencySafe: () => false,
514
+ description: '关闭一个屏幕外窗口(先正常关闭,进程不退就强制结束)。收尾用,避免留下看不见的进程。',
515
+ parameters: {
516
+ type: 'object',
517
+ properties: {
518
+ hwnd: { type: 'number', description: '窗口句柄。' },
519
+ kill: { type: 'boolean', description: '关闭失败时强制结束进程(默认 false)。' },
520
+ },
521
+ required: ['hwnd'],
522
+ },
523
+ output: { schema: OBJECT_SCHEMA, render: (_args, value) => {
524
+ const rec = asRecord(value);
525
+ if (rec.ok !== true) return text([failText(rec, '关闭失败')]);
526
+ const lines = [rec.closed === true ? '窗口已关闭。' : '已发出关闭请求,窗口仍在。可加 kill=true 强制结束。'];
527
+ if (rec.killed === true) lines.push('进程已强制结束。');
528
+ if (typeof rec.kill_skipped === 'string') lines.push(rec.kill_skipped);
529
+ return text(lines);
530
+ } },
531
+ timeoutMs: 30000,
532
+ async execute(rawArgs, exec) {
533
+ const args = asRecord(rawArgs);
534
+ const hwnd = requiredNumber(args, 'hwnd', '窗口句柄');
535
+ const known = knownWindows.get(hwnd);
536
+ const argv = ['close', '--hwnd', String(hwnd)];
537
+ // 共享进程(寄生到用户已开的浏览器里)绝不强制结束,只关这个窗口。
538
+ const wantKill = args.kill === true && known?.shared !== true;
539
+ if (wantKill) argv.push('--kill');
540
+ if (Number.isInteger(known?.pid)) argv.push('--expect-pid', String(known.pid));
541
+ const value = await runHelper(ctx, cfg, argv, { cwd: sessionCwd(exec), signal: exec?.signal });
542
+ if (value.ok === true && value.closed === true) knownWindows.delete(hwnd);
543
+ if (args.kill === true && !wantKill) {
544
+ value.kill_skipped = '这个窗口属于一个已有进程(共享),已跳过强制结束,只关闭了窗口本身。';
545
+ }
546
+ return value;
547
+ },
548
+ });
549
+
550
+ return tools;
551
+ }
552
+
553
+ export function apply(ctx, config) {
554
+ const cfg = { ...DEFAULTS, ...(config === null || config === undefined ? {} : asRecord(config)) };
555
+ const disposers = [];
556
+ try {
557
+ for (const definition of buildTools(ctx, cfg)) {
558
+ disposers.push(ctx.tools.register(definition));
559
+ }
560
+ } catch (error) {
561
+ for (const dispose of disposers) dispose();
562
+ throw error;
563
+ }
564
+ const teardown = () => {
565
+ for (const dispose of disposers) dispose();
566
+ };
567
+ if (typeof ctx.effect === 'function') ctx.effect(() => teardown, 'quiet-windows.tools()');
568
+ else if (typeof ctx.on === 'function') ctx.on('dispose', teardown);
569
+ }
570
+
571
+ export { HELPER as helperPath, resolvePath };