vcorp-chrome 1.7.0 → 2.0.0

package/src/lib/native-install.js

@@ -0,0 +1,139 @@
+// 原生消息宿主的安装 / 卸载 / 体检（npx vcorp-chrome desktop install|uninstall|status）。
+//
+// Chrome 找宿主靠一份清单：Windows 在注册表 HKCU 下登记清单路径，macOS / Linux 把清单放进
+// 浏览器约定的目录。清单的 path 指向一个启动脚本，脚本用装它时的那个 node 跑 native-host/host.js。
+// allowed_origins 只写本扩展：扩展 id 由 manifest.json 里的 key 算出来，不手抄。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn, execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { HOME, ensureHome } from './paths.js';
+
+export const HOST_NAME = 'ai.vcorp.desktop';
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const HOST_JS = path.join(ROOT, 'native-host', 'host.js');
+const DIR = path.join(HOME, 'desktop-host');
+const MANIFEST = path.join(DIR, `${HOST_NAME}.json`);
+
+// Chrome 的扩展 id：公钥 DER 的 sha256 前 16 字节，每个十六进制位 0-f 映射成 a-p
+export function extensionId(manifestKey) {
+  const hex = crypto.createHash('sha256').update(Buffer.from(manifestKey, 'base64')).digest('hex').slice(0, 32);
+  return [...hex].map((c) => String.fromCharCode(97 + parseInt(c, 16))).join('');
+}
+
+function ourExtensionId() {
+  const mf = JSON.parse(fs.readFileSync(path.join(ROOT, 'extension', 'manifest.json'), 'utf8'));
+  return extensionId(mf.key);
+}
+
+const REG_KEYS = [
+  `HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts\\${HOST_NAME}`,
+  `HKCU\\Software\\Microsoft\\Edge\\NativeMessagingHosts\\${HOST_NAME}`,
+];
+
+function manifestDirs() {
+  const h = os.homedir();
+  if (process.platform === 'darwin') {
+    const base = path.join(h, 'Library', 'Application Support');
+    return ['Google/Chrome', 'Chromium', 'Microsoft Edge', 'BraveSoftware/Brave-Browser'].map((b) => path.join(base, b, 'NativeMessagingHosts'));
+  }
+  return ['google-chrome', 'chromium', 'microsoft-edge', 'BraveSoftware/Brave-Browser'].map((b) => path.join(h, '.config', b, 'NativeMessagingHosts'));
+}
+
+export function install() {
+  ensureHome();
+  fs.mkdirSync(DIR, { recursive: true });
+  const win = process.platform === 'win32';
+  const launcher = path.join(DIR, win ? 'vcorp-desktop-host.cmd' : 'vcorp-desktop-host');
+  fs.writeFileSync(launcher, win
+    ? `@echo off\r\n"${process.execPath}" "${HOST_JS}" %*\r\n`
+    : `#!/bin/sh\nexec "${process.execPath}" "${HOST_JS}" "$@"\n`);
+  if (!win) fs.chmodSync(launcher, 0o755);
+  const id = ourExtensionId();
+  fs.writeFileSync(MANIFEST, JSON.stringify({
+    name: HOST_NAME,
+    description: 'vcorp-chrome desktop host',
+    path: launcher,
+    type: 'stdio',
+    allowed_origins: [`chrome-extension://${id}/`],
+  }, null, 2));
+  const placed = [];
+  if (win) {
+    for (const key of REG_KEYS) {
+      execFileSync('reg', ['add', key, '/ve', '/t', 'REG_SZ', '/d', MANIFEST, '/f'], { stdio: 'ignore', windowsHide: true });
+      placed.push(key);
+    }
+  } else {
+    for (const dir of manifestDirs()) {
+      if (!fs.existsSync(path.dirname(dir))) continue;   // 没装这个浏览器
+      fs.mkdirSync(dir, { recursive: true });
+      fs.copyFileSync(MANIFEST, path.join(dir, `${HOST_NAME}.json`));
+      placed.push(dir);
+    }
+  }
+  return { id, launcher, manifest: MANIFEST, placed };
+}
+
+export function uninstall() {
+  const removed = [];
+  if (process.platform === 'win32') {
+    for (const key of REG_KEYS) {
+      try { execFileSync('reg', ['delete', key, '/f'], { stdio: 'ignore', windowsHide: true }); removed.push(key); } catch { /* 本来就没登记 */ }
+    }
+  } else {
+    for (const dir of manifestDirs()) {
+      const f = path.join(dir, `${HOST_NAME}.json`);
+      if (fs.existsSync(f)) { fs.rmSync(f); removed.push(f); }
+    }
+  }
+  fs.rmSync(DIR, { recursive: true, force: true });
+  return { removed };
+}
+
+// 按 Chrome 的方式跟宿主说一句话：起启动脚本、写一条带长度前缀的消息、读一条回包
+export function talk(msg, { launcher, timeoutMs = 20000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const win = process.platform === 'win32';
+    const child = win
+      ? spawn('cmd.exe', ['/d', '/c', launcher, `chrome-extension://${ourExtensionId()}/`], { windowsHide: true })
+      : spawn(launcher, [`chrome-extension://${ourExtensionId()}/`]);
+    const chunks = [];
+    const timer = setTimeout(() => { child.kill(); reject(new Error(`宿主 ${timeoutMs / 1000}s 没有回包`)); }, timeoutMs);
+    child.stdout.on('data', (b) => chunks.push(b));
+    child.on('error', (e) => { clearTimeout(timer); reject(e); });
+    child.on('close', () => {
+      clearTimeout(timer);
+      const buf = Buffer.concat(chunks);
+      if (buf.length < 4) return reject(new Error('宿主没有回包'));
+      resolve(JSON.parse(buf.subarray(4, 4 + buf.readUInt32LE(0)).toString('utf8')));
+    });
+    const body = Buffer.from(JSON.stringify(msg), 'utf8');
+    const len = Buffer.alloc(4);
+    len.writeUInt32LE(body.length, 0);
+    child.stdin.end(Buffer.concat([len, body]));
+  });
+}
+
+export async function status() {
+  const lines = [];
+  let launcher = '';
+  if (!fs.existsSync(MANIFEST)) return { installed: false, lines: ['没有安装：运行 npx vcorp-chrome desktop install'] };
+  const mf = JSON.parse(fs.readFileSync(MANIFEST, 'utf8'));
+  launcher = mf.path;
+  lines.push(`清单 ${MANIFEST}`);
+  if (process.platform === 'win32') {
+    for (const key of REG_KEYS) {
+      let ok = false;
+      try { ok = execFileSync('reg', ['query', key, '/ve'], { encoding: 'utf8', windowsHide: true }).includes(MANIFEST); } catch { /* 没登记 */ }
+      lines.push(`${ok ? '✅' : '❌'} ${key}`);
+    }
+  }
+  if (!fs.existsSync(HOST_JS)) lines.push(`❌ 启动脚本指向的 ${HOST_JS} 不在了（npx 缓存被清过？）：重新运行 desktop install`);
+  const hello = await talk({ op: 'hello' }, { launcher });
+  lines.push(hello.ready
+    ? `✅ 宿主应答 · 设备 ${hello.device.id} · agent-desktop 可用`
+    : `❌ 宿主应答了，但 agent-desktop 用不了：[${hello.error?.code}] ${hello.error?.message}`);
+  return { installed: true, ready: !!hello.ready, device: hello.device, lines };
+}

package/src/lib/paths.js

@@ -11,8 +11,28 @@ export const AUDIT_FILE = path.join(HOME, 'audit.jsonl');
 export const ALLOWLIST_FILE = path.join(HOME, 'allowlist.json');
 export const LOG_FILE = path.join(HOME, 'bridge.log');
 
+export const MACHINE_FILE = path.join(HOME, 'machine.json');
+
 export const DEFAULT_PORT = 8899;
 
+// 这台电脑（这个系统用户）的身份。本机 MCP 和原生宿主（native-host/）读同一个文件，
+// 所以同一台电脑上的桌面设备在两条通道里是同一个设备号。第一次用时生成，之后不变。
+export function machineId() {
+  try {
+    const id = JSON.parse(fs.readFileSync(MACHINE_FILE, 'utf8')).machineId;
+    if (/^m_[0-9a-f]{16}$/.test(id)) return id;
+  } catch { /* 还没有，下面生成 */ }
+  ensureHome();
+  const id = `m_${crypto.randomBytes(8).toString('hex')}`;
+  const tmp = `${MACHINE_FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ machineId: id, createdAt: new Date().toISOString() }, null, 2), { mode: 0o600 });
+  try { fs.linkSync(tmp, MACHINE_FILE); } catch { /* 别的进程抢先写好了，用它的 */ }
+  fs.rmSync(tmp, { force: true });
+  return JSON.parse(fs.readFileSync(MACHINE_FILE, 'utf8')).machineId;
+}
+
+export const desktopDeviceId = (machine) => `desktop-${machine}`;
+
 export function ensureHome() {
   fs.mkdirSync(HOME, { recursive: true, mode: 0o700 });
   return HOME;

package/src/lib/rpc.js

@@ -100,6 +100,7 @@ export class BridgeClient {
           this.extensionVersion = msg.extensionVersion;
           this.versionMismatch = !!msg.versionMismatch;
           this.extensionProtocol = msg.extensionProtocol;
+          this.bridgeDevices = !!msg.devices;
           ws.onmessage = (e2) => this.#dispatch(JSON.parse(e2.data));
           ws.onclose = () => { this.ws = null; this.#failAll('桥连接已断开'); };
           ws.onerror = () => {};
@@ -144,7 +145,11 @@ export class BridgeClient {
   }
 
   // 桥侧已有 30s 超时兜底；这里的 35s 只防「桥自己也没了」的情况
-  async call(cmd, params = {}, { tabId, timeoutMs = 35000 } = {}) {
+  // device：指定投给哪一个浏览器设备（devices 列出的 id）。不给就由桥挑有窗口、最近活跃的那个。
+  async call(cmd, params = {}, { tabId, timeoutMs = 35000, device } = {}) {
+    if ((device || cmd === 'devices') && this.ws && !this.bridgeDevices) {
+      throw Object.assign(new Error('在跑的桥是旧版本，不认识设备：指定 device 的命令会被它投给默认的 Chrome。所有会话都退出、桥自动重启之后再用。'), { code: 'BRIDGE_OLD' });
+    }
     if (!this.ws) await this.connect();
     const id = 'c' + ++this.seq;
     return new Promise((resolve, reject) => {
@@ -154,7 +159,7 @@ export class BridgeClient {
       }, timeoutMs);
       this.waiting.set(id, { resolve, reject, timer });
       // 桥侧也要知道这条命令能等多久，否则它按默认 30s 就把慢命令判死了
-      this.ws.send(JSON.stringify({ type: 'cmd', id, cmd, params, tabId, timeout: timeoutMs - 3000 }));
+      this.ws.send(JSON.stringify({ type: 'cmd', id, cmd, params, tabId, timeout: timeoutMs - 3000, ...(device ? { to: { device } } : {}) }));
     });
   }
 }

package/src/mcp-server.js

@@ -10,9 +10,14 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import { BridgeClient } from './lib/rpc.js';
 import { resolveHost } from './lib/host.js';
 import { flatCount } from '../extension/script.js';
+import { LOADS } from '../extension/loads/index.js';
 import { getLearnings, saveLearnings, saveDraft, adoptDraft } from './lib/learnings.js';
-import { audit } from './lib/paths.js';
+import { audit, machineId, desktopDeviceId } from './lib/paths.js';
+import { DesktopSession, findBinary } from './lib/desktop.js';
+import { redact } from './bridge.js';
+import { describeDevices } from '../extension/device.js';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { VERSION } from './lib/version.js';
 import { compat, compatNote } from '../extension/compat.js';
@@ -207,6 +212,7 @@ const TOOLS = [
         tabId: TAB,
         label: { type: 'string', description: 'With new/select: what this tab is for ("CRM import — batch 2"). Shown in list, page panel, and to the user.' },
         focus: { type: 'boolean', description: 'Also bring the tab to the foreground. Interrupts the user — off by default.' },
+        device: { type: 'string', description: 'With 2+ Chromes: id from devices. That tabId then sticks to it.' },
       },
       required: ['action'],
     },
@@ -457,6 +463,31 @@ const TOOLS = [
       required: ['expr'],
     },
   },
+  {
+    name: 'load',
+    description:
+      'Install a capability pack bundled with the extension into the tab (e.g. "eda" on pro.lceda.cn / pro.easyeda.com). ' +
+      'Returns its read/write action list. Use `call` afterwards instead of eval.',
+    inputSchema: {
+      type: 'object',
+      properties: { name: { type: 'string' }, reload: { type: 'boolean' }, tabId: TAB },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'call',
+    description:
+      'Call one action of a loaded pack with a JSON payload; result is JSON. Re-loads by itself after a page refresh. ' +
+      'timeout ms defaults to the pack limit (eda: 120000, max 600000).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' }, action: { type: 'string' }, payload: { type: 'object' },
+        timeout: { type: 'number' }, tabId: TAB,
+      },
+      required: ['name', 'action'],
+    },
+  },
   {
     name: 'learnings',
     description:
@@ -474,6 +505,39 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'desktop',
+    description:
+      'Native apps and OS dialogs (the file picker a page opens) via the accessibility tree. '
+      + 'list-windows → snapshot {app|window} → act on the FULL ref "@s…:eN" → read the effect line. '
+      + 'Browser windows are refused (use browser tools). headed:true = real mouse/keys. '
+      + 'steps:[{cmd,…}] (≤20) stops on failure or send/delete.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cmd: {
+          type: 'string',
+          enum: ['list-apps', 'list-windows', 'snapshot', 'find', 'get', 'screenshot', 'wait', 'click', 'double-click',
+            'right-click', 'type', 'set-value', 'clear', 'focus', 'select', 'toggle', 'check', 'uncheck', 'expand',
+            'collapse', 'scroll', 'scroll-to', 'press', 'launch', 'focus-window', 'clipboard-set', 'clipboard-get',
+            'list-notifications', 'notification-action'],
+        },
+        app: { type: 'string' }, window: { type: 'string' }, ref: { type: 'string' },
+        root: { type: 'string' }, skeleton: { type: 'boolean' }, all: { type: 'boolean' },
+        text: { type: 'string' }, value: { type: 'string' }, keys: { type: 'string', description: 'press: "ctrl+s"' },
+        role: { type: 'string' }, name: { type: 'string' }, nth: { type: 'number' }, property: { type: 'string' },
+        direction: { type: 'string' }, amount: { type: 'number' },
+        ms: { type: 'number' }, windowTitle: { type: 'string' }, timeout: { type: 'number' },
+        index: { type: 'number' }, action: { type: 'string' }, headed: { type: 'boolean' },
+        steps: { type: 'array', items: { type: 'object' } },
+      },
+    },
+  },
+  {
+    name: 'devices',
+    description: 'Devices this session can drive: each connected Chrome and this computer\'s desktop.',
+    inputSchema: { type: 'object', properties: {} },
+  },
   {
     name: 'reload',
     description:
@@ -526,7 +590,7 @@ warning change target or approach, never repeat the same call.
 
 A STEP NEEDS A HUMAN (captcha, QR login, OTP, payment)? Call \`ask\` — never retry or work
 around. Never let a download put a dialog on their screen: see the \`download\` tool for the
-required order. OS file dialogs are beyond any extension.`;
+required order. Native apps and OS file dialogs: \`desktop\`.`;
 
 // 页面来的文本全部走这里。边界标记 + 降权说明，both 是给模型看的。
 function wrapUntrusted(body, meta = '') {
@@ -547,6 +611,9 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 
+  let desk = null;
+  const tabDevice = new Map();
+
   // 宿主身份：--client 只是兜底，真名以 initialize 里宿主自报的 clientInfo 为准
   // （见 src/lib/host.js）。握手一定先于第一条工具调用，所以在那时认一次就够。
   let host = null;
@@ -559,7 +626,7 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
     return host;
   };
 
-  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  server.setRequestHandler(CallToolRequestSchema, busy(async (req) => {
     const { name, arguments: args = {} } = req.params;
     identify();
     try {
@@ -572,12 +639,51 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
         return { content: [{ type: 'text', text }] };
       }
 
+      // desktop 也不经过桥：本机直接起 agent-desktop 子进程。审计照记，设备号写本机桌面
+      if (name === 'desktop') {
+        desk ??= new DesktopSession({ session: `vc-${bridge.sessionId}` });
+        const t0 = Date.now();
+        const id = `desktop:${t0}`;
+        const cmd = `desktop.${args.steps !== undefined ? 'steps' : args.cmd}`;
+        audit({ ev: 'cmd', id, cmd, client: bridge.client, sid: bridge.sessionId, device: desktopDeviceId(machineId()), params: redact(args) });
+        let r;
+        try {
+          r = await desk.run(args, { timeoutMs: args.steps ? 120000 : Math.min(Math.max((Number(args.timeout) || 0) + 10000, 30000), 600000) });
+        } catch (e) {
+          audit({ ev: 'res', id, cmd, ok: false, ms: Date.now() - t0, error: e.code || 'INTERNAL' });
+          throw e;
+        }
+        const ok = r.env ? !!r.env.ok : !r.stopped;
+        audit({ ev: 'res', id, cmd, ok, ms: Date.now() - t0, error: ok ? undefined : r.env?.error?.code, effect: r.env?.data?.disposition?.delivery });
+        if (r.image) return { content: [{ type: 'image', data: r.image, mimeType: 'image/png' }] };
+        return { content: [{ type: 'text', text: wrapUntrusted(r.text, 'source="desktop"') }], isError: !ok || undefined };
+      }
+
+      if (name === 'devices') {
+        const machine = machineId();
+        const list = [{ id: desktopDeviceId(machine), kind: 'desktop', name: `${os.hostname()} 桌面`, machine, online: true,
+          caps: { platform: process.platform } }];
+        let browserNote = '';
+        try {
+          if (!bridge.ws) await bridge.connect();
+          const d = await bridge.call('devices', {}, { timeoutMs: 8000 });
+          list.unshift(...d.devices.map((x) => (x.primary ? { ...x, name: `${x.name}（默认）` } : x)));
+        } catch (e) {
+          browserNote = `\n浏览器设备查不到：[${e.code || 'INTERNAL'}] ${e.message}`;
+        }
+        return { content: [{ type: 'text', text: describeDevices(list) + browserNote }] };
+      }
+
       if (!bridge.ws) await bridge.connect();
 
+      // 指定设备：tabs 带 device 时记住新开/选中的 tabId 属于哪台，之后同一 tabId 自动跟过去
+      const device = args.device || (args.tabId != null ? tabDevice.get(args.tabId) : undefined);
+      if (args.device !== undefined) delete args.device;
+
       // 翻页在这一侧循环：审计里 fetch→fetch 相邻 386 次，agent 在一页一个回合地
       // 手动翻。扩展只管发单次请求，翻页的循环、落盘、停机判定都不该经过模型。
       if (name === 'fetch' && args.pages && !args.binary) {
-        return { content: [{ type: 'text', text: await fetchPages(bridge, args) }] };
+        return { content: [{ type: 'text', text: await fetchPages(bridge, args, device) }] };
       }
 
       // upload：先把**路径**交给扩展，让它用 CDP 的 DOM.setFileInputFiles 让浏览器
@@ -591,7 +697,7 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
         const base = { path: args.path, name: path.basename(args.path), type: mime, bytes: st.size, selector: args.selector, dropSelector: args.dropSelector };
         // 上传本身可能很慢（本机→浏览器只是投喂，但页面自己的上传要时间），给足预算
         const timeoutMs = Math.max(60000, Math.round(st.size / (1024 * 1024)) * 1000);
-        let out = args.dropSelector ? null : await bridge.call('upload', base, { tabId: args.tabId, timeoutMs });
+        let out = args.dropSelector ? null : await bridge.call('upload', base, { tabId: args.tabId, timeoutMs, device });
         if (!out || out.needBytes) {
           // 走拖放：这条必须有文件字节。超过 DROP_MAX 就明确报错，不要拿桥去撞——
           // 桥一断，当前 agent 会话就再也连不回来了，比报错难查得多。
@@ -603,7 +709,7 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
               `先压小，或改用页面上真实存在的 file input（给 selector）。`);
           }
           out = await bridge.call('upload', { ...base, base64: fs.readFileSync(args.path).toString('base64') },
-            { tabId: args.tabId, timeoutMs });
+            { tabId: args.tabId, timeoutMs, device });
         }
         return { content: [{ type: 'text', text: out.text }] };
       }
@@ -627,6 +733,12 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
         // 扩展侧的执行预算同源（extension/script.js），否则预算会判死一个
         // 还在老实跑的剧本，「已经在做」被报成「没做，去重试」。
         if (n === 'act') return cap(Math.min(flatCount(a.steps) || 1, 60) * 8000 + 20000);
+        // 能力包：load 要等编辑器加载（最多 30 秒）再等 ready()；call 的上限由参数和包的 limits 决定
+        if (n === 'load') return 80000;
+        if (n === 'call') {
+          const lim = LOADS[a.name]?.limits;
+          return cap(Math.min(Number(a.timeout) || lim?.timeoutMs || 120000, lim?.timeoutMaxMs || 600000) + 15000);
+        }
         return undefined;   // 其余维持默认，它们的真实耗时离墙还很远
       };
 
@@ -638,7 +750,11 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
         // 无人值守（cron、服务器）没有人可问。开关放在 MCP 这一侧读环境变量，
         // 扩展只管照做——扩展不该知道自己跑在什么场景里。
         name === 'ask' ? { ...args, disabled: process.env.HUASHU_CHROME_ASK === 'off' } : args,
-        { tabId: args.tabId, timeoutMs: budgetOf(name, args, askMs) });
+        { tabId: args.tabId, timeoutMs: budgetOf(name, args, askMs), device });
+      if (device && name === 'tabs') {
+        const tid = data?.tabId ?? (args.action === 'select' ? args.tabId : undefined);
+        if (tid != null) tabDevice.set(tid, device);
+      }
 
       // 浏览器只能下到 Downloads 里；下完再挪到 agent 要的位置，对它保持透明
       if (name === 'download' && args.savePath && data.path) {
@@ -689,7 +805,7 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
     } catch (e) {
       return { content: [{ type: 'text', text: hint(e) + mismatchNote(true) }], isError: true };
     }
-  });
+  }));
 
   // 扩展和本地端版本对不上时在回执里说一次——回执是唯一一定有人读的通道。
   // 分级见 extension/compat.js：补丁号差异静默；本地端旧了提一次怎么升级；
@@ -706,16 +822,51 @@ export async function startMcpServer({ client = 'unknown' } = {}) {
   }
 
   await server.connect(new StdioServerTransport());
+  watchIdle();
   return server;
 }
 
+// 闲置自退。
+//
+// 本该是宿主的事：会话结束就关掉 stdin，我们读到 EOF 自然就退了（实测成立）。
+// 可 Goose 桌面版每开一个会话起一个 mcp、会话结束却从不关管道——11-2 查到
+// 一个 goose serve 下面挂着 34 个，最老的一周前，合计约 2 GB。宿主不收，只能自己收。
+//
+// 判据是「stdin 上多久没来过任何东西」，且手上没有在跑的工具调用。默认 4 小时：
+// 一个真在用的会话很少静默这么久；万一真是，宿主下一次调用会看到连接已断，
+// 代价是重开一次会话，远小于无限期地攒进程。HUASHU_CHROME_MCP_IDLE_MIN=0 关掉。
+let inflight = 0;
+let lastActive = Date.now();
+const busy = (fn) => async (...a) => {
+  inflight++;
+  try { return await fn(...a); } finally { inflight--; lastActive = Date.now(); }
+};
+
+export function idleLimitMs(env = process.env) {
+  const raw = env.HUASHU_CHROME_MCP_IDLE_MIN;
+  const min = raw == null || raw === '' ? 240 : Number(raw);
+  return Number.isFinite(min) && min > 0 ? min * 60000 : 0;
+}
+
+function watchIdle() {
+  const limit = idleLimitMs();
+  if (!limit) return;
+  process.stdin.on('data', () => { lastActive = Date.now(); });
+  const tick = setInterval(() => {
+    if (inflight || Date.now() - lastActive < limit) return;
+    console.error(`[vcorp-chrome] ${Math.round(limit / 60000)} 分钟没有任何请求，宿主大概已经不用这个进程了，自行退出`);
+    process.exit(0);
+  }, Math.min(60000, Math.max(limit / 4, 50)));
+  tick.unref();   // 吊着进程的该是 stdin，不是这个检查
+}
+
 // 自动翻页。页码型：改一个 query 参数递增；游标型：从上一页响应里按路径取下一个游标。
 // 停机判据都是确定性的：非 2xx、空体、和上一页一模一样、游标为空或没变、跑满 max。
 // 落盘是每页一行 JSON（url/status/body），body 能解析成 JSON 就存解析后的。
 const pathGet = (obj, p) => String(p || '').split('.').filter(Boolean).reduce((o, k) => (o == null ? undefined : o[k]), obj);
 const EMPTY_BODY = /^\s*(\[\s*\]|\{\s*\}|null)?\s*$/;
 
-export async function fetchPages(bridge, args) {
+export async function fetchPages(bridge, args, device) {
   const pg = args.pages || {};
   if (!pg.param && !pg.cursorParam) throw Object.assign(new Error('pages 需要 param（页码参数名）或 cursorParam（游标参数名）'), { code: 'INTERNAL' });
   const max = Math.min(Math.max(Number(pg.max) || 10, 1), 50);
@@ -730,7 +881,7 @@ export async function fetchPages(bridge, args) {
     const url = new URL(base);
     if (pg.param) url.searchParams.set(pg.param, String(n));
     if (pg.cursorParam && cursor) url.searchParams.set(pg.cursorParam, cursor);
-    const data = await bridge.call('fetch', { url: url.toString(), init: args.init, maxBody: args.maxBody || 2000000, via: args.via }, { tabId: args.tabId });
+    const data = await bridge.call('fetch', { url: url.toString(), init: args.init, maxBody: args.maxBody || 2000000, via: args.via }, { tabId: args.tabId, device });
     const m = /^(\d+)\n\n([\s\S]*)$/.exec(data?.text || '');
     const status = Number(m?.[1] || 0), body = m?.[2] ?? '';
     if (!(status >= 200 && status < 300)) { stop = `第 ${i + 1} 页返回 ${status}，停下`; break; }
@@ -790,6 +941,12 @@ function hint(e) {
       + '在「高保真模式」那一栏点「开启」——只需一次。',
     L2_BUSY: '真实输入事件用不了（多半是用户自己开着 DevTools，一个标签页只允许一个调试器）。'
       + '已经用普通事件完成了；如果结果不对，让用户关掉 DevTools 再试。',
+    DEVICE_OFFLINE: '指定的设备不在线。devices 看现在有哪些，换一台或请用户把它打开。',
+    AMBIGUOUS_DEVICE: '有不止一台设备能做这件事。从候选里挑一个，用 device 指定。',
+    DESKTOP_DENIED: '这条桌面命令被安全规则拦下（原因见上）。浏览器窗口用浏览器工具；别换个写法绕。',
+    DESKTOP_UNAVAILABLE: '这台电脑上的桌面能力没装好。运行 npx vcorp-chrome doctor 看缺什么。',
+    PAY_REFUSED: '付款类按钮只能由用户亲手点。用 ask 把要付的东西说清楚，请用户自己完成。',
+    NEEDS_SINGLE_CALL: '发送/删除一类的动作不在批处理里做。先确认目标没错，再单独调用一次。',
   };
   return `[${e.code || 'INTERNAL'}] ${e.message}` + (map[e.code] ? `\n→ ${map[e.code]}` : '');
 }