mocode-ai 1.4.6 → 1.5.0

package/dist/runtime/screen-capture-service.js

@@ -0,0 +1,251 @@
+/**
+ * 常驻抓屏进程(Windows)。
+ *
+ * 为什么要有这个:实测一次全屏抓屏 710-737ms,其中绝大部分是 PowerShell 冷启动 +
+ * `Add-Type` 加载 System.Windows.Forms / System.Drawing(GDI+ 初始化)。这一步每个动作都要
+ * 付一次,而它跟「抓哪块屏」毫无关系 —— 典型的可以摊薄的固定成本。
+ *
+ * 协议与 `input-injector.ts` 完全同构(stdin 收 NDJSON 动作 / stdout 回 NDJSON 结果),
+ * 就是为了复用同一套心智模型:Add-Type 只做一次,之后每次抓屏只是一次管道往返。
+ *
+ * 生命周期(见 `idle-guard.ts`):惰性启动 → 每次调用续期 → 空闲 3 分钟回收 → /cu off 与
+ * REPL 退出强制回收。**不因为 /cu on 就启动** —— /cu 是写进 config 的持久开关,若 on 即起进程,
+ * 那么每次开 mocode 都会白起一个 PowerShell。
+ *
+ * 降级:常驻路径任何一步失败都 kill 掉进程并回落一次性 spawn;连续 2 次失败则本会话内
+ * 彻底禁用常驻路径(失败模式通常是环境级的,重试没有意义,反而每次多付一次启动成本)。
+ */
+import { spawn } from 'node:child_process';
+import { filterEnv } from '../sandbox/index.js';
+import { IdleGuard, envInt } from './idle-guard.js';
+const OP_TIMEOUT_MS = 15000;
+const DEFAULT_IDLE_MS = 3 * 60 * 1000;
+const BROKEN_AFTER = 2;
+const PS_CAPTURE_SCRIPT = [
+    '$ErrorActionPreference = "Stop"',
+    '[Console]::InputEncoding = [System.Text.Encoding]::UTF8',
+    '[Console]::OutputEncoding = [System.Text.Encoding]::UTF8',
+    // ── 以下三行只在进程启动时执行一次,这是常驻化的全部收益来源 ──
+    'Add-Type -TypeDefinition @"',
+    'using System;',
+    'using System.Runtime.InteropServices;',
+    'public class MoCap {',
+    '  [DllImport("user32.dll")] public static extern bool SetProcessDpiAwarenessContext(IntPtr ctx);',
+    '  [DllImport("user32.dll")] public static extern bool SetProcessDPIAware();',
+    '  [DllImport("user32.dll", CharSet = CharSet.Auto)] public static extern bool EnumDisplaySettings(string dev, int mode, ref DEVMODE dm);',
+    '  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Auto)]',
+    '  public struct DEVMODE {',
+    '    [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)] public string dmDeviceName;',
+    '    public short dmSpecVersion; public short dmDriverVersion; public short dmSize; public short dmDriverExtra;',
+    '    public int dmFields; public int dmPositionX; public int dmPositionY; public int dmDisplayOrientation;',
+    '    public int dmDisplayFixedOutput; public short dmColor; public short dmDuplex; public short dmYResolution;',
+    '    public short dmTTOption; public short dmCollate;',
+    '    [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)] public string dmFormName;',
+    '    public short dmLogPixels; public int dmBitsPerPel; public int dmPelsWidth; public int dmPelsHeight;',
+    '    public int dmDisplayFlags; public int dmDisplayFrequency; public int dmICMMethod; public int dmICMIntent;',
+    '    public int dmMediaType; public int dmDitherType; public int dmReserved1; public int dmReserved2;',
+    '    public int dmPanningWidth; public int dmPanningHeight;',
+    '  }',
+    '}',
+    // here-string 结束符必须在行首,不能有任何前导空格(PowerShell 解析要求)。
+    '"@ | Out-Null',
+    'try { if (-not [MoCap]::SetProcessDpiAwarenessContext([IntPtr](-4))) { [void][MoCap]::SetProcessDPIAware() } } catch { }',
+    'Add-Type -AssemblyName System.Windows.Forms',
+    'Add-Type -AssemblyName System.Drawing',
+    'while ($null -ne ($line = [Console]::In.ReadLine())) {',
+    '  $resp = @{ id = 0; ok = $false; detail = "" }',
+    '  try {',
+    '    $req = $line | ConvertFrom-Json',
+    '    $resp.id = $req.id',
+    '    $bounds = if ($req.target -eq "all") { [System.Windows.Forms.SystemInformation]::VirtualScreen } else { [System.Windows.Forms.Screen]::PrimaryScreen.Bounds }',
+    '    $bitmap = [System.Drawing.Bitmap]::new($bounds.Width, $bounds.Height)',
+    '    $graphics = [System.Drawing.Graphics]::FromImage($bitmap)',
+    '    try {',
+    '      $graphics.CopyFromScreen($bounds.X, $bounds.Y, 0, 0, $bounds.Size)',
+    '      $bitmap.Save($req.path, [System.Drawing.Imaging.ImageFormat]::Png)',
+    '    } finally {',
+    '      $graphics.Dispose()',
+    '      $bitmap.Dispose()',
+    '    }',
+    '    $physW = $bounds.Width',
+    '    $physH = $bounds.Height',
+    '    try {',
+    '      $dm = New-Object MoCap+DEVMODE',
+    '      $dm.dmSize = [System.Runtime.InteropServices.Marshal]::SizeOf($dm)',
+    '      if ([MoCap]::EnumDisplaySettings([System.Windows.Forms.Screen]::PrimaryScreen.DeviceName, -1, [ref]$dm)) {',
+    '        if ($dm.dmPelsWidth -gt 0) { $physW = $dm.dmPelsWidth }',
+    '        if ($dm.dmPelsHeight -gt 0) { $physH = $dm.dmPelsHeight }',
+    '      }',
+    '    } catch { }',
+    '    $resp.ok = $true',
+    '    $resp.shotW = $bounds.Width',
+    '    $resp.shotH = $bounds.Height',
+    '    $resp.physW = $physW',
+    '    $resp.physH = $physH',
+    '    $resp.originX = $bounds.X',
+    '    $resp.originY = $bounds.Y',
+    '  } catch {',
+    '    $resp.ok = $false',
+    '    $resp.detail = $_.Exception.Message',
+    '  }',
+    '  [Console]::Out.WriteLine(($resp | ConvertTo-Json -Compress))',
+    '  [Console]::Out.Flush()',
+    '}',
+].join('\n');
+class ResidentCaptureService {
+    child = null;
+    nextId = 1;
+    pending = new Map();
+    stdoutBuf = '';
+    lastError = '';
+    failures = 0;
+    idle;
+    constructor(idleMs) {
+        this.idle = new IdleGuard(idleMs, () => {
+            void this.dispose();
+        });
+    }
+    /** 常驻路径是否可用(进程未崩、未被熔断)。 */
+    get available() {
+        return this.failures < BROKEN_AFTER;
+    }
+    ensureProcess() {
+        if (this.child && this.child.exitCode === null && !this.child.killed)
+            return this.child;
+        this.child = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', PS_CAPTURE_SCRIPT], { env: filterEnv(process.env), windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
+        this.stdoutBuf = '';
+        this.lastError = '';
+        this.child.stdout?.on('data', (chunk) => this.onStdout(chunk.toString('utf8')));
+        this.child.stderr?.on('data', (chunk) => {
+            this.lastError = (this.lastError + chunk.toString('utf8')).slice(-2000);
+        });
+        this.child.on('exit', () => this.failAll(new Error(`capture service exited${this.lastError ? `: ${this.lastError.trim()}` : ''}`)));
+        this.child.on('error', (err) => this.failAll(err));
+        return this.child;
+    }
+    onStdout(text) {
+        this.stdoutBuf += text;
+        let idx;
+        while ((idx = this.stdoutBuf.indexOf('\n')) >= 0) {
+            const line = this.stdoutBuf.slice(0, idx).trim();
+            this.stdoutBuf = this.stdoutBuf.slice(idx + 1);
+            if (!line)
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue; // 非协议行(Add-Type 警告等)
+            }
+            const id = typeof msg.id === 'number' ? msg.id : -1;
+            const op = this.pending.get(id);
+            if (!op)
+                continue;
+            this.pending.delete(id);
+            clearTimeout(op.timer);
+            op.resolve(msg);
+        }
+    }
+    failAll(error) {
+        for (const [, op] of this.pending) {
+            clearTimeout(op.timer);
+            op.reject(error);
+        }
+        this.pending.clear();
+        if (this.child) {
+            try {
+                this.child.kill();
+            }
+            catch {
+                /* 已退出 */
+            }
+            this.child = null;
+        }
+    }
+    num(msg, key) {
+        const v = msg[key];
+        return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+    }
+    async capture(outputPath, target, signal) {
+        if (!this.available)
+            throw new Error('resident capture service disabled after repeated failures');
+        const child = this.ensureProcess();
+        const id = this.nextId++;
+        try {
+            const resp = await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    this.pending.delete(id);
+                    this.failAll(new Error(`capture timed out after ${OP_TIMEOUT_MS}ms`));
+                    reject(new Error(`capture timed out after ${OP_TIMEOUT_MS}ms`));
+                }, OP_TIMEOUT_MS);
+                this.pending.set(id, { resolve, reject, timer });
+                const onAbort = () => {
+                    this.pending.delete(id);
+                    clearTimeout(timer);
+                    // abort 通常是用户 Ctrl+C,进程状态未知 —— 直接回收,下次重建。
+                    this.failAll(new Error('aborted'));
+                    reject(new Error('Screenshot capture was aborted.'));
+                };
+                if (signal) {
+                    if (signal.aborted)
+                        return onAbort();
+                    signal.addEventListener('abort', onAbort, { once: true });
+                }
+                try {
+                    child.stdin?.write(`${JSON.stringify({ id, op: 'capture', path: outputPath, target })}\n`, 'utf8');
+                }
+                catch (err) {
+                    this.pending.delete(id);
+                    clearTimeout(timer);
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                }
+            });
+            if (resp.ok !== true) {
+                throw new Error(String(resp.detail ?? 'unknown capture error'));
+            }
+            const shotW = this.num(resp, 'shotW');
+            const shotH = this.num(resp, 'shotH');
+            const physW = this.num(resp, 'physW');
+            const physH = this.num(resp, 'physH');
+            const geometry = shotW && shotH && physW && physH
+                ? {
+                    shotW,
+                    shotH,
+                    physW,
+                    physH,
+                    originX: this.num(resp, 'originX') ?? 0,
+                    originY: this.num(resp, 'originY') ?? 0,
+                }
+                : undefined;
+            this.failures = 0;
+            this.idle.touch();
+            return geometry ? { status: 'passed', detail: 'ok', geometry } : { status: 'passed', detail: 'ok' };
+        }
+        catch (error) {
+            // 任何失败都回收进程:不能把一个状态未知的常驻进程留到下一次调用。
+            this.failures += 1;
+            this.failAll(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    async dispose() {
+        this.idle.stop();
+        this.failAll(new Error('capture service disposed'));
+    }
+}
+let singleton = null;
+/** 取常驻抓屏服务(惰性构造,此时还不 spawn;第一次 capture 才真正起进程)。 */
+export function getCaptureService() {
+    if (process.platform !== 'win32')
+        return null;
+    singleton ??= new ResidentCaptureService(envInt('MOCODE_CU_CAPTURE_IDLE_MS', DEFAULT_IDLE_MS));
+    return singleton;
+}
+/** 回收常驻抓屏进程(/cu off / REPL 退出 / 空闲超时)。幂等。 */
+export async function disposeCaptureService() {
+    if (singleton) {
+        await singleton.dispose();
+        singleton = null;
+    }
+}

package/dist/runtime/screen-capture.js

@@ -2,17 +2,57 @@
  * 跨平台桌面截图捕获:从 tools/builtins/screenshot.ts 抽出的可复用底层。
  * screenshot 工具与 computer 工具的闭环重截屏共用同一份平台逻辑,零重复。
  * 只做「抓屏 → 写 PNG 文件」,不做缩放/坐标/回灌(那是 screen-pipeline 的职责)。
+ *
+ * DPI 正确性(computer use 的点击精度命门):
+ * PowerShell 默认以 DPI UNAWARE 启动,此时 `Screen.PrimaryScreen.Bounds` 与 `CopyFromScreen`
+ * 返回的都是**逻辑像素**(150% 缩放下 2560×1440 的屏只有 1707×960),而 `SetCursorPos` 始终
+ * 按**物理像素**解释坐标 —— 两者差一个缩放比,表现为「所有点击都落在从左上角算起的 2/3 处,
+ * 越往右下偏得越多」。因此这里做两件事:
+ *  1. 抓屏前显式声明 PER_MONITOR_AWARE_V2(失败回落 SYSTEM_AWARE),让 Bounds 与抓到的图都是物理像素;
+ *  2. 额外用 EnumDisplaySettings 读取**不受 DPI 虚拟化影响**的物理分辨率并回传(geometry),
+ *     调用方据此校准坐标。即使 1 在老系统上失败,2 仍能兜底。
  */
 import { spawn } from 'node:child_process';
 import { filterEnv } from '../sandbox/index.js';
-function runCaptureProcess(program, args, env, signal) {
+function parseGeometry(stdout) {
+    const line = stdout
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .pop();
+    if (!line || !line.startsWith('{'))
+        return undefined;
+    try {
+        const o = JSON.parse(line);
+        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+        const shotW = num(o.shotW);
+        const shotH = num(o.shotH);
+        const physW = num(o.physW);
+        const physH = num(o.physH);
+        if (shotW === undefined || shotH === undefined || physW === undefined || physH === undefined)
+            return undefined;
+        return {
+            shotW,
+            shotH,
+            physW,
+            physH,
+            originX: num(o.originX) ?? 0,
+            originY: num(o.originY) ?? 0,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function runCaptureProcess(program, args, env, signal, collectStdout = false) {
     return new Promise((resolve) => {
         const child = spawn(program, args, {
             env,
             windowsHide: true,
-            stdio: ['ignore', 'ignore', 'pipe'],
+            stdio: ['ignore', collectStdout ? 'pipe' : 'ignore', 'pipe'],
         });
         let stderr = '';
+        let stdout = '';
         let finished = false;
         const finish = (result) => {
             if (finished)
@@ -25,14 +65,21 @@ function runCaptureProcess(program, args, env, signal) {
             child.kill();
             finish({ status: 'aborted', detail: 'Screenshot capture was aborted.' });
         };
-        child.stderr.on('data', (chunk) => {
+        child.stderr?.on('data', (chunk) => {
             stderr = (stderr + chunk.toString('utf8')).slice(-4000);
         });
+        if (collectStdout) {
+            child.stdout?.on('data', (chunk) => {
+                stdout = (stdout + chunk.toString('utf8')).slice(-4000);
+            });
+        }
         child.on('error', (error) => finish({ status: 'spawn_error', detail: error.message }));
-        child.on('close', (code) => finish({
-            status: code === 0 ? 'passed' : 'failed',
-            detail: stderr.trim() || `Capture process exited with code ${code ?? 'null'}.`,
-        }));
+        child.on('close', (code) => {
+            const status = code === 0 ? 'passed' : 'failed';
+            const detail = stderr.trim() || `Capture process exited with code ${code ?? 'null'}.`;
+            const geometry = collectStdout ? parseGeometry(stdout) : undefined;
+            finish(geometry ? { status, detail, geometry } : { status, detail });
+        });
         if (signal) {
             if (signal.aborted)
                 onAbort();
@@ -42,6 +89,34 @@ function runCaptureProcess(program, args, env, signal) {
     });
 }
 const WINDOWS_CAPTURE_SCRIPT = [
+    '$ErrorActionPreference = "Stop"',
+    // ── DPI 感知:必须在读取任何屏幕信息之前声明 ──
+    'try {',
+    '  Add-Type -TypeDefinition @"',
+    '  using System;',
+    '  using System.Runtime.InteropServices;',
+    '  public class MoCap {',
+    '    [DllImport("user32.dll")] public static extern bool SetProcessDpiAwarenessContext(IntPtr ctx);',
+    '    [DllImport("user32.dll")] public static extern bool SetProcessDPIAware();',
+    '    [DllImport("user32.dll", CharSet = CharSet.Auto)] public static extern bool EnumDisplaySettings(string dev, int mode, ref DEVMODE dm);',
+    '    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Auto)]',
+    '    public struct DEVMODE {',
+    '      [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)] public string dmDeviceName;',
+    '      public short dmSpecVersion; public short dmDriverVersion; public short dmSize; public short dmDriverExtra;',
+    '      public int dmFields; public int dmPositionX; public int dmPositionY; public int dmDisplayOrientation;',
+    '      public int dmDisplayFixedOutput; public short dmColor; public short dmDuplex; public short dmYResolution;',
+    '      public short dmTTOption; public short dmCollate;',
+    '      [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)] public string dmFormName;',
+    '      public short dmLogPixels; public int dmBitsPerPel; public int dmPelsWidth; public int dmPelsHeight;',
+    '      public int dmDisplayFlags; public int dmDisplayFrequency; public int dmICMMethod; public int dmICMIntent;',
+    '      public int dmMediaType; public int dmDitherType; public int dmReserved1; public int dmReserved2;',
+    '      public int dmPanningWidth; public int dmPanningHeight;',
+    '    }',
+    '  }',
+    // 注意:here-string 的结束符 "@ 必须在行首,不能有任何前导空格,否则 PowerShell 解析失败。
+    '"@ | Out-Null',
+    '  if (-not [MoCap]::SetProcessDpiAwarenessContext([IntPtr](-4))) { [void][MoCap]::SetProcessDPIAware() }',
+    '} catch { }',
     'Add-Type -AssemblyName System.Windows.Forms',
     'Add-Type -AssemblyName System.Drawing',
     "$bounds = if ($env:MOCODE_SCREENSHOT_TARGET -eq 'all') { [System.Windows.Forms.SystemInformation]::VirtualScreen } else { [System.Windows.Forms.Screen]::PrimaryScreen.Bounds }",
@@ -54,6 +129,20 @@ const WINDOWS_CAPTURE_SCRIPT = [
     '  $graphics.Dispose()',
     '  $bitmap.Dispose()',
     '}',
+    // ── 物理分辨率兜底:EnumDisplaySettings 不受 DPI 虚拟化影响 ──
+    '$physW = $bounds.Width',
+    '$physH = $bounds.Height',
+    'try {',
+    '  $dm = New-Object MoCap+DEVMODE',
+    '  $dm.dmSize = [System.Runtime.InteropServices.Marshal]::SizeOf($dm)',
+    '  if ([MoCap]::EnumDisplaySettings([System.Windows.Forms.Screen]::PrimaryScreen.DeviceName, -1, [ref]$dm)) {',
+    '    if ($dm.dmPelsWidth -gt 0) { $physW = $dm.dmPelsWidth }',
+    '    if ($dm.dmPelsHeight -gt 0) { $physH = $dm.dmPelsHeight }',
+    '  }',
+    '} catch { }',
+    'try {',
+    '  [Console]::Out.WriteLine((@{ shotW = $bounds.Width; shotH = $bounds.Height; physW = $physW; physH = $physH; originX = $bounds.X; originY = $bounds.Y } | ConvertTo-Json -Compress))',
+    '} catch { }',
 ].join('\n');
 /** 抓屏并写入 outputPath。target=primary 主屏,all 整个虚拟桌面。 */
 export async function captureDesktop(outputPath, target, signal) {
@@ -63,7 +152,18 @@ export async function captureDesktop(outputPath, target, signal) {
         MOCODE_SCREENSHOT_TARGET: target,
     };
     if (process.platform === 'win32') {
-        return runCaptureProcess('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', WINDOWS_CAPTURE_SCRIPT], env, signal);
+        // 优先走常驻进程(Add-Type / GDI+ 初始化只付一次,实测能省掉 710ms 里的大头)。
+        // 常驻路径任何异常都回落到一次性 spawn —— 这是原有行为,保证不会有功能倒退。
+        try {
+            const { getCaptureService } = await import('./screen-capture-service.js');
+            const svc = getCaptureService();
+            if (svc?.available)
+                return await svc.capture(outputPath, target, signal);
+        }
+        catch {
+            // 常驻路径失败 → 回落到一次性 spawn(下面继续)。
+        }
+        return runCaptureProcess('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', WINDOWS_CAPTURE_SCRIPT], env, signal, true);
     }
     if (process.platform === 'darwin') {
         const args = ['-x', ...(target === 'primary' ? ['-m'] : []), outputPath];

package/dist/runtime/screen-pipeline.js

@@ -10,6 +10,22 @@
  */
 import { inflateSync, deflateSync } from 'node:zlib';
 const PNG_SIG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/**
+ * 只读 IHDR 拿宽高,不做 inflate / 反滤镜。
+ * 抓屏图 4K 时全量 decodePng 要吃满 14MB 像素缓冲 + 逐字节反滤镜循环,而宽高在文件头 24 字节里就有。
+ * 非 Windows 平台(macOS screencapture / Linux)拿不到 CaptureGeometry,靠这条路径避免整图解开销。
+ */
+export function readPngSize(buf) {
+    if (buf.length < 24 || !buf.subarray(0, 8).equals(PNG_SIG))
+        return null;
+    if (buf.toString('ascii', 12, 16) !== 'IHDR')
+        return null;
+    const width = buf.readUInt32BE(16);
+    const height = buf.readUInt32BE(20);
+    if (!width || !height)
+        return null;
+    return { width, height };
+}
 function paeth(a, b, c) {
     const p = a + b - c;
     const pa = Math.abs(p - a);
@@ -83,7 +99,8 @@ export function decodePng(buf) {
                 case 4:
                     v = cur + paeth(a, b, c);
                     break;
-                default: throw new Error(`bad PNG filter ${f}`);
+                default:
+                    throw new Error(`bad PNG filter ${f}`);
             }
             out[rowOut + x] = v & 0xff;
         }
@@ -119,8 +136,14 @@ function chunk(type, data) {
     crc.writeUInt32BE(crc32(body), 0);
     return Buffer.concat([len, body, crc]);
 }
-/** 编码 RGBA → PNG(colorType 6,filter 0)。 */
-export function encodePng(img) {
+/**
+ * 编码 RGBA → PNG(colorType 6,filter 0)。
+ *
+ * `level` 默认 1(而非 zlib 默认的 6):截图是高频噪声图,压缩率对等级极不敏感
+ * (实测体积差 <10%),但 level 6 在 4K 图上要多花数倍 CPU。图片 token 按**像素**计费、
+ * 与字节数无关,所以「压得小」在 LLM 侧没有任何收益 —— 这里只买速度。
+ */
+export function encodePng(img, opts) {
     const { width, height, data } = img;
     const stride = width * 4;
     const raw = Buffer.alloc((stride + 1) * height);
@@ -139,7 +162,7 @@ export function encodePng(img) {
     return Buffer.concat([
         PNG_SIG,
         chunk('IHDR', ihdr),
-        chunk('IDAT', deflateSync(raw)),
+        chunk('IDAT', deflateSync(raw, { level: opts?.level ?? 1 })),
         chunk('IEND', Buffer.alloc(0)),
     ]);
 }
@@ -194,6 +217,52 @@ export function crop(img, x, y, w, h) {
     }
     return { width: cw, height: ch, data: out };
 }
+// ── 帧间差分 ───────────────────────────────────────────────────────────
+/**
+ * 把任意尺寸图降采样成 grid×grid 的灰度块均值(box average,非最近邻 —— 4K → 64 时
+ * 最近邻会严重走样,块均值才对「有没有变」这个问题敏感)。
+ */
+function grayGrid(img, grid) {
+    const out = new Float64Array(grid * grid);
+    const { width, height, data } = img;
+    for (let gy = 0; gy < grid; gy++) {
+        const y0 = Math.floor((gy * height) / grid);
+        const y1 = Math.max(y0 + 1, Math.floor(((gy + 1) * height) / grid));
+        for (let gx = 0; gx < grid; gx++) {
+            const x0 = Math.floor((gx * width) / grid);
+            const x1 = Math.max(x0 + 1, Math.floor(((gx + 1) * width) / grid));
+            let sum = 0;
+            let n = 0;
+            for (let y = y0; y < y1; y++) {
+                const row = y * width;
+                for (let x = x0; x < x1; x++) {
+                    const i = (row + x) * 4;
+                    // Rec.601 亮度;alpha 视为不透明(截图不透明)。
+                    sum += 0.299 * data[i] + 0.587 * data[i + 1] + 0.114 * data[i + 2];
+                    n++;
+                }
+            }
+            out[gy * grid + gx] = n ? sum / n : 0;
+        }
+    }
+    return out;
+}
+/**
+ * 两帧的差异比例(0..1):各网格块灰度差的平均值 / 255。
+ * 典型值:完全静止 ≈ 0;光标移动或抗锯齿抖动 < 0.005;局部区域重绘 0.01-0.1;整屏切换 > 0.2。
+ * 输入必须同尺寸(调用方负责保证),否则抛错 —— 尺寸不同意味着显示器配置变了,不该静默比。
+ */
+export function diffRatio(a, b, grid = 64) {
+    if (a.width !== b.width || a.height !== b.height) {
+        throw new Error(`diffRatio size mismatch: ${a.width}×${a.height} vs ${b.width}×${b.height}`);
+    }
+    const ga = grayGrid(a, grid);
+    const gb = grayGrid(b, grid);
+    let sum = 0;
+    for (let i = 0; i < ga.length; i++)
+        sum += Math.abs(ga[i] - gb[i]);
+    return sum / ga.length / 255;
+}
 // ── norm1000 坐标换算 ──────────────────────────────────────────────────
 /** 归一化坐标(0-1000)→ 物理像素。scale = 喂模型的图相对物理的缩放比。 */
 export function normToPhysical(nx, ny, physW, physH) {

package/dist/runtime/shutdown.js

@@ -11,6 +11,19 @@ export async function shutdownRuntime() {
         return;
     asyncDone = true;
     stopAllDevServersSync();
+    try {
+        // 动态 import:未用过 computer 工具时不该把这两个常驻进程拉进来。
+        // 常驻 PowerShell 进程不随主进程自动退出,必须显式回收(否则每次会话留一组孤儿)。
+        const [{ disposeInputInjector }, { disposeCaptureService }] = await Promise.all([
+            import('./input-injector.js'),
+            import('./screen-capture-service.js'),
+        ]);
+        await disposeInputInjector();
+        await disposeCaptureService();
+    }
+    catch {
+        // 从未启动过:忽略。
+    }
     try {
         // 动态 import:未用过 browser 工具时不该把 playwright 拉进进程。
         const { closeAllBrowsers } = await import('./browser-manager.js');