vcorp-chrome 1.8.1 → 2.0.0

package/native-host/host.js

@@ -0,0 +1,122 @@
+// 原生消息宿主 ai.vcorp.desktop —— 云端通道够到桌面的唯一一段。
+//
+// Chrome 每次 sendNativeMessage 起一个本进程：stdin 进一条消息（4 字节小端长度 + JSON），
+// stdout 回一条，Chrome 随即关管道。本进程只做两件事：
+//   hello：报出这台电脑的桌面设备身份（和本机 MCP 用同一个 machineId，所以两条通道里是同一台设备）
+//   run：把扩展审过的参数再审一遍，交给 agent-desktop，回它的信封
+// 扩展那一侧已经过了 desktop-policy.js；这里再审是因为扩展本身也可能出错，
+// 而真实输入（--headed）、截图、剪贴板读取这些不该因为一处疏漏就对云端打开。
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runAgentDesktop, findBinary } from '../src/lib/desktop.js';
+import { machineId, desktopDeviceId } from '../src/lib/paths.js';
+import {
+  DESKTOP_CMDS, REF_RE, filterWindows, checkObserved, recordOf, isBrowserMainTitle,
+} from '../extension/desktop-policy.js';
+import { VERSION } from '../src/lib/version.js';
+
+// Chrome 收宿主回包的上限是 1MB，留出 JSON 外壳的余量
+const REPLY_MAX = 1000 * 1000;
+const IN_MAX = 1024 * 1024;
+
+const OPTS = new Set([
+  '--app', '--window-id', '--timeout-ms', '--role', '--name', '--text', '--nth', '--limit', '--property',
+  '--timeout', '--window', '--direction', '--amount', '--session', '--root', '--expected-app',
+]);
+const FLAGS = new Set(['-i', '--compact', '--skeleton']);
+const COMBO_RE = /^[a-z0-9][a-z0-9+_-]{0,39}$/i;
+const SESSION_RE = /^--session=cloud-[\w-]{1,64}$/;
+
+function denied(message) {
+  return { ok: false, error: { code: 'DESKTOP_DENIED', message, disposition: { delivery: 'not_delivered', retry: 'safe' } } };
+}
+
+// 返回 null 表示合规，否则是拒绝原因
+export function recheck(argv) {
+  if (!Array.isArray(argv) || !argv.length || argv.length > 40) return 'argv 不合法';
+  if (!argv.every((a) => typeof a === 'string' && a.length <= 20000 && !a.includes('\0'))) return 'argv 不合法';
+  const spec = DESKTOP_CMDS[argv[0]];
+  if (!spec || !spec.cloud) return `云端不能用 ${argv[0]}`;
+  const cut = argv.indexOf('--');
+  const head = cut < 0 ? argv.slice(1) : argv.slice(1, cut);
+  let session = false;
+  for (const a of head) {
+    if (FLAGS.has(a) || REF_RE.test(a) || /^\d{1,6}$/.test(a)) continue;
+    if (argv[0] === 'press' && COMBO_RE.test(a)) continue;
+    const eq = a.indexOf('=');
+    if (a.startsWith('--') && eq > 2 && OPTS.has(a.slice(0, eq))) {
+      if (a.startsWith('--session=')) { if (!SESSION_RE.test(a)) return 'session 不合法'; session = true; }
+      continue;
+    }
+    return `参数不在白名单里：${a.slice(0, 40)}`;
+  }
+  if (!session && !['list-apps', 'clipboard-set'].includes(argv[0])) return '缺少任务的 session';
+  return null;
+}
+
+function readMessage() {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    process.stdin.on('data', (b) => {
+      chunks.push(b);
+      size += b.length;
+      if (size > IN_MAX + 4) reject(new Error('消息太大'));
+      const buf = Buffer.concat(chunks);
+      if (buf.length >= 4 && buf.length >= 4 + buf.readUInt32LE(0)) resolve(JSON.parse(buf.subarray(4, 4 + buf.readUInt32LE(0)).toString('utf8')));
+    });
+    process.stdin.on('end', () => reject(new Error('没有收到消息')));
+  });
+}
+
+function reply(obj) {
+  let body = Buffer.from(JSON.stringify(obj), 'utf8');
+  if (body.length > REPLY_MAX) {
+    body = Buffer.from(JSON.stringify({
+      ok: false,
+      error: {
+        code: 'TOO_LARGE',
+        message: `结果有 ${Math.round(body.length / 1024)}KB，超过原生消息 1MB 的上限`,
+        suggestion: 'snapshot 加 skeleton:true 先看轮廓，再用 root 往某一块里钻',
+        disposition: { delivery: 'unknown', retry: 'unsafe' },
+      },
+    }), 'utf8');
+  }
+  const len = Buffer.alloc(4);
+  len.writeUInt32LE(body.length, 0);
+  return new Promise((resolve) => process.stdout.write(Buffer.concat([len, body]), resolve));
+}
+
+async function main() {
+  const msg = await readMessage();
+  if (msg?.op === 'hello') {
+    const machine = machineId();
+    const probe = await runAgentDesktop(['list-apps'], { timeoutMs: 15000 });
+    return reply({
+      ok: true,
+      device: { id: desktopDeviceId(machine), kind: 'desktop', machine, caps: { platform: process.platform, version: VERSION } },
+      ready: !!probe.ok,
+      ...(probe.ok ? {} : { error: probe.error }),
+      binary: findBinary(),
+    });
+  }
+  if (msg?.op === 'run') {
+    const why = recheck(msg.argv);
+    if (why) return reply(denied(why));
+    const timeoutMs = Math.min(Math.max(Number(msg.timeoutMs) || 30000, 1000), 90000);
+    const env = await runAgentDesktop(msg.argv, { timeoutMs });
+    // 浏览器主窗口的标题和树不出这台电脑：扩展那侧也会滤，这里是第二道
+    if (env.ok && msg.argv[0] === 'list-windows') env.data = filterWindows(env.data, 'cloud');
+    if (env.ok && msg.argv[0] === 'snapshot') {
+      const rec = recordOf(env.data);
+      if (isBrowserMainTitle(rec?.window?.title)) return reply(denied('浏览器主窗口不出这台电脑'));
+      try { checkObserved(rec); } catch (e) { return reply(denied(e.message)); }
+    }
+    return reply(env);
+  }
+  return reply(denied(`未知操作 ${String(msg?.op).slice(0, 20)}`));
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().then(() => process.exit(0), async (e) => { await reply(denied(`宿主出错：${e.message}`)); process.exit(0); });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vcorp-chrome",
-  "version": "1.8.1",
+  "version": "2.0.0",
   "description": "让任何 AI agent 操控你自己的 Chrome——带着全部登录态。MCP + Chrome 扩展，Claude Code / Codex / Cursor / Gemini CLI 通用。",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "src",
     "extension",
+    "native-host",
     "docs",
     "README.md"
   ],
@@ -20,7 +21,7 @@
     "bridge": "node src/cli.js bridge --foreground",
     "doctor": "node src/cli.js doctor",
     "build:loads": "node scripts/build-loads.mjs",
-    "test": "node --test test/protocol.test.js test/mcp.test.js test/fetch-pages.test.js test/liveness.test.js test/redact.test.js test/audit-redact.test.js test/learnings.test.js test/risk.test.js test/identity.test.js test/host.test.js test/presence.test.js test/act-script.test.js test/multi-instance.test.js test/compat.test.js test/cloud-policy.test.js test/loads.test.js",
+    "test": "node --test test/protocol.test.js test/mcp.test.js test/fetch-pages.test.js test/liveness.test.js test/redact.test.js test/audit-redact.test.js test/learnings.test.js test/risk.test.js test/identity.test.js test/host.test.js test/presence.test.js test/act-script.test.js test/multi-instance.test.js test/compat.test.js test/cloud-policy.test.js test/loads.test.js test/desktop-policy.test.js",
     "test:live": "node --test test/scenarios.test.js"
   },
   "dependencies": {
@@ -45,5 +46,8 @@
   "devDependencies": {
     "esbuild": "^0.24.2",
     "jszip": "^3.10.1"
+  },
+  "optionalDependencies": {
+    "agent-desktop": "1.0.2"
   }
 }

package/src/bridge.js

@@ -8,7 +8,7 @@
 // 网页的 Origin 是自己的域名，扩展的是 chrome-extension://<id>。只放后者进来。
 import { WebSocketServer } from 'ws';
 import fs from 'node:fs';
-import { DEFAULT_PORT, writeBridgeInfo, newToken, tokenEquals, audit, ensureHome, ALLOWLIST_FILE } from './lib/paths.js';
+import { DEFAULT_PORT, writeBridgeInfo, newToken, tokenEquals, audit, ensureHome, ALLOWLIST_FILE, machineId } from './lib/paths.js';
 import { VERSION } from './lib/version.js';
 // 纯字符串判定、不碰 chrome API，所以桥这边直接复用，不再抄一份
 import { scrubProse } from '../extension/redact.js';
@@ -112,6 +112,8 @@ export function startBridge({ port = DEFAULT_PORT, token = newToken(), writeInfo
     return pool.reduce((a, b) => (a.lastRx >= b.lastRx ? a : b));
   }
   const extLabel = (ws) => `Chrome ${ws.chromeVersion || '?'}${ws.headless ? ' · headless' : ''} · 扩展 ${ws.extVersion}`;
+  let machineCache = null;
+  const machine = () => (machineCache ??= machineId());
 
   const wss = new WebSocketServer({
     host: '127.0.0.1',
@@ -216,6 +218,8 @@ export function startBridge({ port = DEFAULT_PORT, token = newToken(), writeInfo
       // 老扩展不报 instanceId。退回按扩展 id 认——行为和单槽那版一样
       // （同一份代码的两个实例仍会互相替换），但至少不会跟新扩展混着算。
       ws.instanceId = msg.instanceId || `ext:${msg.extId || '?'}`;
+      // 设备号由实例号派生：同一个 Chrome profile 重启、重载扩展都不变（见 extension/device.js）
+      ws.deviceId = `browser-${String(ws.instanceId).replace(/[^\w.-]/g, '').slice(0, 64) || 'unknown'}`;
 
       // 同一个实例又连了一条：那是断线重连或重载扩展，旧的那条已经是死的，
       // 顶掉它。**只顶同实例的**——顶错了就退回单槽，每秒互踢的老毛病就回来了。
@@ -241,6 +245,10 @@ export function startBridge({ port = DEFAULT_PORT, token = newToken(), writeInfo
           + `命令路由到：${extLabel(primary())}`);
       }
       send(ws, { type: 'welcome', bridge: VERSION, v: PROTOCOL });
+      // 连上就给一份名单，哪怕是空的。扩展手里那份可能是上一个桥留下的：桥换过之后
+      // 旧连接不会再发 close，不推的话死会话要等下一条命令才被冲掉——面板就一直
+      // 显示着已经不在的 agent。
+      send(ws, { type: 'event', event: 'sessions', live: liveSessions() });
       broadcast({ type: 'event', event: 'extension_online' });
       flushWaiting();
       return;
@@ -265,6 +273,8 @@ export function startBridge({ port = DEFAULT_PORT, token = newToken(), writeInfo
       const ext = primary();
       send(ws, {
         type: 'welcome', bridge: VERSION, v: PROTOCOL,
+        // 设备目录与按 to.device 投递。老桥没有这一项：它会把指名的命令照样投给默认的那个 Chrome
+        devices: true,
         extensionOnline: !!ext,
         extensionVersion: ext?.extVersion,
         // 老 MCP 只认 versionMismatch：只在真需要人处理时置位，补丁号差异不再惊动它
@@ -286,6 +296,25 @@ export function startBridge({ port = DEFAULT_PORT, token = newToken(), writeInfo
     // agent → extension
     if (msg.type === 'cmd') {
       if (!agents.has(ws)) return;
+      // 本机设备目录：桥是唯一知道「有几个 Chrome 连着」的一方，这条由它自己答
+      if (msg.cmd === 'devices') {
+        const main = primary();
+        return send(ws, { type: 'res', id: msg.id, ok: true, data: { devices: liveExtensions().map((e) => ({
+          id: e.deviceId, kind: 'browser', name: extLabel(e), machine: machine(), online: true,
+          caps: { platform: 'chrome', version: e.extVersion, cmds: [] }, primary: e === main,
+        })) } });
+      }
+      // 指名道姓的命令只投给那一个实例。它不在就直说，不改投别的 Chrome——
+      // agent 指定设备正是因为它在意落在哪一台上
+      const want = msg.to?.device;
+      if (want) {
+        const hit = liveExtensions().find((e) => e.deviceId === want);
+        if (!hit) {
+          return send(ws, { type: 'res', id: msg.id, ok: false, error: { code: 'DEVICE_OFFLINE',
+            message: `浏览器设备 ${String(want).slice(0, 80)} 没有连着。用 devices 看看现在有哪些。` } });
+        }
+        return dispatch(ws, msg, hit);
+      }
       const target = primary();
       if (!target) return enqueue(ws, msg);
       return dispatch(ws, msg, target);
@@ -349,7 +378,7 @@ export function startBridge({ port = DEFAULT_PORT, token = newToken(), writeInfo
     // 只有 281 个不同的 id，最多的一个出现了 1088 次。
     // 路由用的一直是 connId:id，审计却记裸 id——「出事能查」这条承诺
     // 在数据结构层面就不成立。
-    audit({ ev: 'cmd', id: key, cmd: msg.cmd, client: ws.client, sid: ws.sid, params: redact(msg.params) });
+    audit({ ev: 'cmd', id: key, cmd: msg.cmd, client: ws.client, sid: ws.sid, device: target.deviceId, params: redact(msg.params) });
     // sid 盖章：扩展据此维护每个会话自己的受控 tab 槽（多 agent 并发隔离）。
     // live 是此刻还连着的会话，扩展拿它判断某个标签页「还有没有主」。
     // client / label 是给人看的：页面上的控制标记要写出「Codex CLI」而不是一串 sid。

package/src/cli.js

@@ -102,6 +102,28 @@ switch (cmd) {
     await doctor();
     break;
 
+  // 云端任务够到桌面要经原生消息宿主；本机 MCP 的 desktop 工具不需要这一步
+  case 'desktop': {
+    const nat = await import('./lib/native-install.js');
+    const sub = process.argv[3];
+    if (sub === 'install') {
+      const r = nat.install();
+      console.log(`已登记原生消息宿主 ${nat.HOST_NAME}（只允许扩展 ${r.id} 调用）`);
+      for (const p of r.placed) console.log(`  ✅ ${p}`);
+      if (!r.placed.length) console.log('  ⚠️ 没找到已安装的 Chrome / Edge / Chromium 配置目录');
+      console.log('\n回到扩展侧栏点「启用桌面能力」。');
+      for (const l of (await nat.status()).lines) console.log(`  ${l}`);
+    } else if (sub === 'uninstall') {
+      const r = nat.uninstall();
+      console.log(r.removed.length ? `已移除：\n  ${r.removed.join('\n  ')}` : '本来就没有登记。');
+    } else if (sub === 'status') {
+      for (const l of (await nat.status()).lines) console.log(`  ${l}`);
+    } else {
+      console.log('用法：vcorp-chrome desktop install | uninstall | status');
+    }
+    break;
+  }
+
   case 'extension':
     printExtension();
     // --reveal：在访达 / 资源管理器里选中扩展文件夹，用户拖进 chrome://extensions 就装好了。
@@ -133,6 +155,7 @@ switch (cmd) {
   vcorp-chrome audit --stats [--days 7]   真实 agent 的用法统计：回合数、哪类调用最多、在哪儿浪费
   vcorp-chrome bridge --foreground   前台跑桥（调试用）
   vcorp-chrome install --dry-run     只看会改哪些配置，不写
+  vcorp-chrome desktop install|uninstall|status   让云端任务也能操作桌面应用（登记原生消息宿主）
 
 配置目录 ${HOME}`);
 }
@@ -204,7 +227,6 @@ async function doctor() {
   fs.existsSync(mf)
     ? ok(`${path.join(ROOT, 'extension')}${alive ? '' : ''}（这只说明文件在；Chrome 是否从这里加载了，看上面「扩展在线」那行）`)
     : bad('扩展目录缺失', '重装 vcorp-chrome');
-
   // bridge.log 里最近一次断连：用户体感的「插件消失」到底是什么时候、断了多久
   try {
     const lines = fs.readFileSync(LOG_FILE, 'utf8').trim().split('\n').slice(-400);
@@ -216,6 +238,18 @@ async function doctor() {
     if (lastDown) console.log(`  ·  最近一次断开 ${lastDown}${lastUp ? `，最近一次连上 ${lastUp}` : '，之后没再连上'}（bridge.log，只有时分秒）`);
   } catch { /* 没日志就没日志 */ }
 
+  console.log('\n桌面');
+  {
+    const { findBinary, runAgentDesktop } = await import('./lib/desktop.js');
+    const bin = findBinary();
+    const t0 = Date.now();
+    const env = await runAgentDesktop(['list-apps'], { bin, timeoutMs: 15000 });
+    if (env.ok) ok(`agent-desktop 可用 · ${(env.data?.apps || []).length} 个应用 · ${Date.now() - t0}ms（${bin}）`);
+    else if (env.error?.code === 'PERM_DENIED') bad(`agent-desktop 没有辅助功能权限：${env.error.message}`, env.error.suggestion);
+    else bad(`desktop 工具用不了：[${env.error?.code}] ${env.error?.message}`,
+      '在 vcorp-chrome 的安装目录里补装 agent-desktop（npm i agent-desktop@1.0.2），或设 AGENT_DESKTOP_BIN 指到它的可执行文件');
+  }
+
   // 经验库里 agent 记下的「vcorp-chrome 的 X 不生效」——产品 bug 住在经验库里，
   // 没有这一栏就永远回不到开发者手上（screenshot 的 savePath 就是这么躺了一周的）
   try {

package/src/lib/desktop.js

@@ -0,0 +1,171 @@
+// 本机桌面执行器 —— 把 desktop 工具的一次调用变成一次 agent-desktop 子进程调用。
+//
+// agent-desktop 是无状态 CLI：每条命令一个进程、输出一个 JSON 信封（见它的 docs/json-output.md）。
+// 这一层做四件事：找到二进制；每条命令先过 extension/desktop-policy.js；
+// 记住每份快照属于哪个应用、哪个窗口（之后的 ref 命令对着它判）；把信封渲染成给模型看的短文本。
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import {
+  checkDesktop, checkObserved, recordOf, filterWindows, checkSteps, snapshotIdOf,
+} from '../../extension/desktop-policy.js';
+import { renderEnvelope } from '../../extension/desktop-render.js';
+
+const require = createRequire(import.meta.url);
+
+// npm 包 agent-desktop 自带各平台的二进制（bin/agent-desktop-<平台>-<架构>[.exe]）。
+// 直接调平台二进制，不经它的 JS 启动器：少起一个 node 进程，每条命令省一两百毫秒。
+export function findBinary() {
+  if (process.env.AGENT_DESKTOP_BIN) return process.env.AGENT_DESKTOP_BIN;
+  const name = `agent-desktop-${process.platform === 'win32' ? 'win32' : process.platform}-${process.arch}${process.platform === 'win32' ? '.exe' : ''}`;
+  try {
+    const dir = path.dirname(require.resolve('agent-desktop/package.json'));
+    const p = path.join(dir, 'bin', name);
+    if (fs.existsSync(p)) return p;
+  } catch { /* 没装这个依赖，退到 PATH */ }
+  return process.platform === 'win32' ? 'agent-desktop.exe' : 'agent-desktop';
+}
+
+const OUT_MAX = 8 * 1024 * 1024;
+
+// 跑一次，返回信封。不经 shell：参数数组原样交给进程，没有拼接、没有转义问题。
+export function runAgentDesktop(argv, { bin = findBinary(), timeoutMs = 30000 } = {}) {
+  return new Promise((resolve) => {
+    let out = '';
+    let errText = '';
+    let done = false;
+    const finish = (env) => { if (!done) { done = true; clearTimeout(timer); resolve(env); } };
+    let child;
+    try {
+      child = spawn(bin, argv, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+      finish(fail('DESKTOP_UNAVAILABLE', `起不来 agent-desktop（${bin}）：${e.message}`));
+      return;
+    }
+    const timer = setTimeout(() => {
+      child.kill();
+      finish(fail('TIMEOUT', `agent-desktop ${Math.round(timeoutMs / 1000)}s 没有回音，结果不明。先 snapshot 看现状，别直接重做。`, 'unknown'));
+    }, timeoutMs);
+    child.stdout.on('data', (b) => { if (out.length < OUT_MAX) out += b; });
+    child.stderr.on('data', (b) => { if (errText.length < 4000) errText += b; });
+    child.on('error', (e) => finish(fail('DESKTOP_UNAVAILABLE',
+      e.code === 'ENOENT' ? '这台电脑上没有 agent-desktop。运行 npx vcorp-chrome doctor 看怎么装。' : e.message)));
+    child.on('close', () => {
+      const line = out.trim().split('\n').filter(Boolean).at(-1) || '';
+      try { finish(JSON.parse(line)); } catch {
+        finish(fail('INTERNAL', `agent-desktop 的输出不是 JSON：${(line || errText).slice(0, 300)}`, 'unknown'));
+      }
+    });
+  });
+}
+
+function fail(code, message, delivery = 'not_delivered') {
+  return { ok: false, error: { code, message, disposition: { delivery, retry: delivery === 'not_delivered' ? 'safe' : 'unknown' } } };
+}
+
+// ---------- 会话 ----------
+
+const SNAPS_MAX = 64;
+
+// 一个 vcorp 会话（一个 MCP server 进程）一个实例。快照户口只活在内存里：
+// 进程没了户口也没了，那时 ref 命令会被要求重新 snapshot——宁可多拍一次，也不认来路不明的 ref。
+export class DesktopSession {
+  constructor({ session, channel = 'local', bin = findBinary(), run = runAgentDesktop } = {}) {
+    this.session = String(session || 'vcorp').replace(/[^\w-]/g, '-').slice(0, 64);
+    this.channel = channel;
+    this.bin = bin;
+    this.runner = run;
+    this.snaps = new Map();
+    this.windows = new Map();
+  }
+
+  remember(rec) {
+    this.snaps.delete(rec.id);
+    this.snaps.set(rec.id, rec);
+    while (this.snaps.size > SNAPS_MAX) this.snaps.delete(this.snaps.keys().next().value);
+  }
+
+  async refreshWindows() {
+    const env = await this.runner(['list-windows'], { bin: this.bin, timeoutMs: 15000 });
+    if (env?.ok && Array.isArray(env.data)) {
+      for (const w of env.data) this.windows.set(w.id, { app: w.app_name, title: w.title || '' });
+    }
+    return env;
+  }
+
+  ctx() {
+    return {
+      channel: this.channel,
+      session: this.session,
+      lookup: (id) => this.snaps.get(id) || null,
+      windows: (id) => this.windows.get(id) || null,
+    };
+  }
+
+  // 一条命令。返回 { text, image?, env, sensitive }。策略不过直接抛（code 在 e.code 上）。
+  async run(params, { timeoutMs = 30000, allowSensitive = true } = {}) {
+    if (params?.steps !== undefined) return this.steps(params.steps, { timeoutMs });
+    if (params?.window && !this.windows.has(String(params.window))) await this.refreshWindows();
+    const chk = checkDesktop(params, this.ctx());
+    if (chk.sensitive === 'pay') {
+      throw Object.assign(new Error(`「${chk.target?.name}」像是要花钱的按钮。桌面能力不代做付款，请用户亲手点。`), { code: 'PAY_REFUSED' });
+    }
+    if (chk.sensitive && !allowSensitive) {
+      throw Object.assign(new Error(`「${chk.target?.name}」是发送/删除一类的动作，批处理不代做。单独调用一次 desktop ${chk.cmd}。`), { code: 'NEEDS_SINGLE_CALL' });
+    }
+    let shot = null;
+    if (chk.cmd === 'screenshot') {
+      shot = path.join(os.tmpdir(), `vcorp-desktop-${process.pid}-${Date.now()}.png`);
+      chk.argv.push(shot);
+    }
+    const env = await this.runner(chk.argv, { bin: this.bin, timeoutMs });
+
+    if (env?.ok && (chk.cmd === 'snapshot' || chk.cmd === 'find')) {
+      const rec = recordOf(env.data);
+      if (rec && !rec.app) rec.app = chk.app;
+      if (rec && !rec.window && env.data.window) rec.window = env.data.window;
+      if (chk.cmd === 'snapshot') checkObserved(rec);
+      if (rec) {
+        const prev = chk.cmd === 'find' ? this.snaps.get(rec.id) : null;
+        this.remember(prev ? { ...prev, refs: { ...prev.refs, ...rec.refs } } : rec);
+      }
+    }
+    if (env?.ok && chk.cmd === 'list-windows') {
+      for (const w of env.data || []) this.windows.set(w.id, { app: w.app_name, title: w.title || '' });
+      env.data = filterWindows(env.data, this.channel);
+    }
+    let image = null;
+    if (shot) {
+      try { image = fs.readFileSync(shot).toString('base64'); } catch { /* 截图失败时信封里有原因 */ }
+      fs.rmSync(shot, { force: true });
+    }
+    return { text: renderEnvelope(chk.cmd, env, { target: chk.target }), image, env, cmd: chk.cmd, app: chk.app, sensitive: chk.sensitive };
+  }
+
+  // 一串步骤：每步过同一套检查，任何一步失败或碰到敏感动作就停，讲清做到哪、为什么停
+  async steps(list, { timeoutMs = 30000 } = {}) {
+    checkSteps(list);
+    const out = [];
+    for (let i = 0; i < list.length; i++) {
+      const st = list[i];
+      let r;
+      try {
+        r = await this.run(st, { timeoutMs, allowSensitive: false });
+      } catch (e) {
+        out.push(`⏸ 第 ${i + 1}/${list.length} 步 ${st.cmd}：${e.message}`);
+        out.push(`剩下 ${list.length - i - 1} 步没做。`);
+        return { text: out.join('\n'), stopped: true };
+      }
+      out.push(`— ${i + 1}/${list.length} ${st.cmd}\n${r.text}`);
+      if (!r.env?.ok) {
+        out.push(`⏸ 停在第 ${i + 1} 步，剩下 ${list.length - i - 1} 步没做。`);
+        return { text: out.join('\n'), stopped: true };
+      }
+    }
+    return { text: out.join('\n\n') };
+  }
+}
+
+export { snapshotIdOf };

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;