vcorp-chrome 1.7.0 → 2.0.0

package/extension/desktop-policy.js

@@ -0,0 +1,400 @@
+// 桌面能力的规矩 —— 纯函数，不碰任何 chrome / node API。
+//
+// 本机 MCP（src/lib/desktop.js）和云端通道（cloud.js → 原生宿主）用同一份。
+// agent-desktop 自己只管系统权限，不管「哪个应用能碰」，所以闸门全在这里，
+// 和页面侧一样：安全判断不放在模型里。
+//
+// 2026-11-02 在 Windows 上实测（agent-desktop 1.0.2）定下的几条：
+// - Chrome 主窗口在 UIA 里整个是敞开的：地址栏、MetaMask / OKX 钱包按钮、密码管理、
+//   扩展按钮，连 vcorp-chrome 侧栏里的「暂停」「断开并忘记这个服务器」「移除」网站、
+//   「高保真模式」开关都有 ref。桌面一侧能点到它们，扩展里的每一道闸就都白设了。
+//   所以浏览器的主窗口一律不碰，只放行浏览器弹出的系统文件对话框。
+// - 系统文件对话框的控件有固定的自动化 id：文件名 1148、打开/保存 1、取消 2。
+//   判断「这是文件对话框」认这组 id，不认标题（标题随语言变，也可能被页面影响）。
+// - 每次调用要起一个进程，list-windows 最少约 730ms，Chrome 快照约 2.4s。
+
+const err = (code, message) => Object.assign(new Error(message), { code });
+
+// ---------- 应用身份 ----------
+
+// 进程名 / 应用名的规范形式：小写、去掉 .exe / .app。「Weixin.exe」和「weixin」是同一个。
+export function appKey(raw) {
+  return String(raw ?? '').trim().toLowerCase().replace(/\.(exe|app)$/, '').slice(0, 80);
+}
+
+const BROWSERS = new Set([
+  'chrome', 'google chrome', 'msedge', 'microsoft edge', 'brave', 'brave browser', 'chromium',
+  'firefox', 'mozilla firefox', 'opera', 'vivaldi', 'arc', 'safari', 'yandex', '360se', '360chrome',
+  'qqbrowser', 'sogouexplorer', 'doubao',
+]);
+
+export function isBrowserApp(app) {
+  return BROWSERS.has(appKey(app));
+}
+
+// 浏览器主窗口的标题以浏览器名收尾（「VCorp Super Agent - Google Chrome」）
+const BROWSER_TITLE = /\s[-–—]\s(Google Chrome|Chromium|Microsoft​? Edge|Brave|Mozilla Firefox|Opera|Vivaldi|Arc)$/i;
+
+export function isBrowserMainTitle(title) {
+  return BROWSER_TITLE.test(String(title ?? ''));
+}
+
+// 快照树里有没有系统文件对话框的那组控件
+export function isFileDialogTree(tree) {
+  let name = false;
+  let ok = false;
+  const walk = (n, depth) => {
+    if (!n || typeof n !== 'object' || depth > 40 || (name && ok)) return;
+    const id = n.native_id?.value;
+    if (id === '1148') name = true;
+    if (id === '1' && n.role === 'button') ok = true;
+    for (const c of Array.isArray(n.children) ? n.children : []) walk(c, depth + 1);
+  };
+  walk(tree, 0);
+  return name && ok;
+}
+
+// 两条通道都不碰的：密码管理器（凭据不进上下文）
+const SECRET_APPS = new Set([
+  '1password', 'bitwarden', 'keepass', 'keepassxc', 'lastpass', 'dashlane', 'enpass', 'keychain access',
+  'keeper', 'nordpass', 'roboform', 'proton pass',
+]);
+
+// 云端还不碰的：能拿到整台机器的东西。本机 agent 本来就有 shell，拦它们没有意义
+const CLOUD_DENIED_APPS = new Set([
+  'powershell', 'pwsh', 'cmd', 'windowsterminal', 'terminal', 'iterm2', 'conhost', 'wt', 'openconsole',
+  'regedit', 'mmc', 'taskmgr', 'sechealthui', 'systemsettings', 'control', 'system preferences',
+  'system settings', 'mstsc', 'gnome-terminal', 'konsole', 'xterm', 'alacritty', 'wezterm', 'kitty',
+  'cursor', 'code', 'goose', 'claude', 'codex',
+]);
+
+export function deniedApp(app, channel) {
+  const k = appKey(app);
+  if (!k) return null;
+  if (SECRET_APPS.has(k)) return `${app} 是密码管理器，桌面能力不碰它`;
+  if (channel === 'cloud' && CLOUD_DENIED_APPS.has(k)) return `云端任务不能操作 ${app}`;
+  return null;
+}
+
+// ---------- 敏感动作 ----------
+
+export const PAY_NAME = /支付|付款|下单|结算|购买|充值|提现|转账|打赏|续费|红包|pay\s?now|checkout|place\s?order|buy\s?now|purchase|transfer/i;
+export const SENSITIVE_NAME = /发送|发布|提交|删除|移除|清空|卸载|格式化|退出登录|注销|send|submit|publish|delete|remove|erase|uninstall|format|sign\s?out|log\s?out/i;
+
+// 'pay'：要花钱，必须人点头，没有跳过的办法；'sensitive'：对外或不可逆，不自动重试、不进批处理
+export function sensitivity(name) {
+  const s = String(name ?? '');
+  if (PAY_NAME.test(s)) return 'pay';
+  if (SENSITIVE_NAME.test(s)) return 'sensitive';
+  return null;
+}
+
+// ---------- 命令表 ----------
+
+// kind：read 只看不动，write 会改应用状态。ref：要不要一个快照里的 ref。
+// cloud / local：这条通道能不能用。
+const C = (kind, o = {}) => ({ kind, cloud: true, local: true, ref: false, ...o });
+export const DESKTOP_CMDS = {
+  'list-apps': C('read'),
+  'list-windows': C('read'),
+  snapshot: C('read'),
+  find: C('read'),
+  get: C('read', { ref: true }),
+  screenshot: C('read', { cloud: false }),   // 原生消息单条回包 1MB 上限，PNG 常常超
+  wait: C('read'),
+  click: C('write', { ref: true }),
+  'double-click': C('write', { ref: true }),
+  'right-click': C('write', { ref: true }),
+  type: C('write', { ref: true }),
+  'set-value': C('write', { ref: true }),
+  clear: C('write', { ref: true }),
+  focus: C('write', { ref: true }),
+  select: C('write', { ref: true }),
+  toggle: C('write', { ref: true }),
+  check: C('write', { ref: true }),
+  uncheck: C('write', { ref: true }),
+  expand: C('write', { ref: true }),
+  collapse: C('write', { ref: true }),
+  scroll: C('write', { ref: true }),
+  'scroll-to': C('write', { ref: true }),
+  press: C('write'),
+  launch: C('write'),
+  'focus-window': C('write', { cloud: false }),   // 抢用户的焦点
+  'clipboard-set': C('write'),
+  'clipboard-get': C('read', { cloud: false }),   // 剪贴板里常常是刚复制的密码
+  'list-notifications': C('read', { cloud: false }),   // 私信、验证码
+  'notification-action': C('write', { cloud: false }),
+};
+
+export const REF_RE = /^@s[a-z0-9]{4,40}:e\d{1,6}$/;
+const SESSION_RE = /^[\w-]{1,64}$/;
+const WINDOW_RE = /^w-\d{1,20}$/;
+const COMBO_RE = /^[a-z0-9][a-z0-9+_-]{0,39}$/i;
+const ROLE_RE = /^[a-z_-]{1,30}$/;
+
+const str = (v, max) => String(v ?? '').replace(/\0/g, '').slice(0, max);
+const int = (v, lo, hi, dflt) => {
+  const n = Math.floor(Number(v));
+  return Number.isFinite(n) ? Math.min(hi, Math.max(lo, n)) : dflt;
+};
+
+export function snapshotIdOf(ref) {
+  const m = /^@(s[a-z0-9]+):e\d+$/.exec(String(ref ?? ''));
+  return m ? m[1] : '';
+}
+
+// 一份快照的户口：这些 ref 属于哪个应用、哪个窗口，是不是文件对话框，每个 ref 叫什么。
+// 执行器在快照（和 find）回来之后记下它，之后每条 ref 命令都对着它判。
+export function recordOf(data) {
+  if (!data || typeof data !== 'object' || !data.snapshot_id) return null;
+  const refs = {};
+  let n = 0;
+  const walk = (node, depth) => {
+    if (!node || typeof node !== 'object' || depth > 60 || n > 4000) return;
+    if (node.ref_id) {
+      const e = /:(e\d+)$/.exec(node.ref_id)?.[1];
+      if (e) { refs[e] = { role: str(node.role, 30), name: str(node.name, 80) }; n += 1; }
+    }
+    for (const c of Array.isArray(node.children) ? node.children : []) walk(c, depth + 1);
+  };
+  walk(data.tree, 0);
+  if (data.match) walk(data.match, 0);
+  for (const m of Array.isArray(data.matches) ? data.matches : []) walk(m, 0);
+  return {
+    id: String(data.snapshot_id),
+    app: str(data.app, 80),
+    window: data.window && typeof data.window === 'object'
+      ? { id: str(data.window.id, 40), title: str(data.window.title, 200) } : null,
+    fileDialog: data.tree ? isFileDialogTree(data.tree) : false,
+    refs,
+  };
+}
+
+// 浏览器的窗口只认文件对话框。preflight：对一个非主窗口先拍一张快照，
+// 拍回来由 checkObserved 认它是不是文件对话框——在那之前它的 ref 不进户口。
+function browserGate(app, title, fileDialog, { preflight = false } = {}) {
+  if (!isBrowserApp(app) || fileDialog) return null;
+  if (preflight && title && !isBrowserMainTitle(title)) return null;
+  return `不能操作浏览器窗口（${app}${title ? `「${title.slice(0, 40)}」` : ''}）：网页用浏览器工具；`
+    + '浏览器弹出的打开/另存为对话框，先 list-windows 拿到它的 window 再 snapshot。';
+}
+
+// 审一条桌面命令，返回 agent-desktop 的参数数组（不含可执行文件本身）。
+// ctx.channel：'local' | 'cloud'；ctx.session：快照命名空间；
+// ctx.lookup(snapshotId)：取 recordOf 记下的户口；ctx.apps：云端本任务批准的应用（appKey 列表）；
+// ctx.windows(windowId)：取 list-windows 里那个窗口的 {app, title}（执行器预取）。
+// 返回 { cmd, argv, kind, app, target, sensitive }，不合规直接抛。
+export function checkDesktop(params, ctx = {}) {
+  const p = params && typeof params === 'object' ? params : {};
+  const channel = ctx.channel === 'cloud' ? 'cloud' : 'local';
+  const cmd = String(p.cmd || '');
+  const spec = DESKTOP_CMDS[cmd];
+  if (!spec) throw err('DESKTOP_DENIED', `desktop 不支持 ${cmd || '（没写 cmd）'}`);
+  if (!spec[channel]) throw err('DESKTOP_DENIED', `${channel === 'cloud' ? '云端任务' : '本机'}不能用 desktop ${cmd}`);
+  if (p.headed && channel === 'cloud') throw err('DESKTOP_DENIED', '云端任务不能用真实鼠标键盘（headed）');
+
+  const argv = [cmd];
+  let app = p.app !== undefined ? str(p.app, 80).trim() : '';
+  const win = p.window !== undefined ? str(p.window, 40) : '';
+  if (win && !WINDOW_RE.test(win)) throw err('DESKTOP_DENIED', 'window 要用 list-windows 给的 id，如 w-460112');
+  let title = '';
+  if (win) {
+    const w = ctx.windows?.(win);
+    if (!w) throw err('DESKTOP_DENIED', `不认识窗口 ${win}：先 list-windows`);
+    app = app || w.app;
+    title = w.title || '';
+    if (appKey(w.app) !== appKey(app)) throw err('DESKTOP_DENIED', `窗口 ${win} 属于 ${w.app}，不是 ${app}`);
+  }
+
+  let rec = null;
+  let target = null;
+  if (spec.ref || p.root !== undefined) {
+    const ref = str(spec.ref ? p.ref : p.root, 60);
+    if (!REF_RE.test(ref)) throw err('DESKTOP_DENIED', 'ref 要用快照里完整的形式，如 @s8f3k2p9:e8');
+    rec = ctx.lookup?.(snapshotIdOf(ref)) || null;
+    if (!rec) throw err('DESKTOP_DENIED', `不认识 ${ref} 所属的快照：先在这个会话里 snapshot 一次`);
+    app = rec.app;
+    title = rec.window?.title || '';
+    target = rec.refs[/:(e\d+)$/.exec(ref)[1]] || null;
+    if (spec.ref) argv.push(ref);
+    else argv.push('--root', ref);
+  }
+
+  const appless = ['list-apps', 'clipboard-set', 'clipboard-get', 'list-notifications', 'notification-action'];
+  if (!app && !appless.includes(cmd) && !(cmd === 'wait' && p.ms !== undefined && p.text === undefined)) {
+    if (channel === 'cloud' || cmd !== 'list-windows') throw err('DESKTOP_DENIED', `desktop ${cmd} 要给 app 或 window`);
+  }
+  if (app) {
+    const why = deniedApp(app, channel);
+    if (why) throw err('DESKTOP_DENIED', why);
+    if (channel === 'cloud' && !(ctx.apps || []).includes(appKey(app))) {
+      throw err('APP_NOT_APPROVED', `本任务还不能操作 ${app}。先用 apps 申请，用户点头之后再来。`);
+    }
+    const gate = cmd === 'list-windows' ? null
+      : browserGate(app, title, rec?.fileDialog, { preflight: cmd === 'snapshot' && !!win && !rec });
+    if (gate) throw err('DESKTOP_DENIED', gate);
+  }
+
+  // 用户给的文字一律不能被当成开关：选项值写成 --opt=值，自由文本放到 -- 之后。
+  // 实测 `type @ref --headed` 会被 agent-desktop 当成开关解析——云端的一段文字就能换成真实输入。
+  const opt = (name, v) => argv.push(`${name}=${v}`);
+  const tail = [];
+  const where = () => (win ? opt('--window-id', win) : opt('--app', app));
+  switch (cmd) {
+    case 'list-windows':
+      if (app) opt('--app', app);
+      break;
+    case 'snapshot':
+      if (!rec) where();
+      if (!p.all) argv.push('-i');
+      argv.push('--compact');
+      if (p.skeleton) argv.push('--skeleton');
+      if (p.timeout !== undefined) opt('--timeout-ms', int(p.timeout, 500, 20000, 3000));
+      break;
+    case 'find': {
+      if (!rec) where();
+      if (p.role === undefined && p.name === undefined && p.text === undefined) throw err('DESKTOP_DENIED', 'find 要给 role / name / text 里至少一个');
+      if (p.role !== undefined) {
+        const role = str(p.role, 30);
+        if (!ROLE_RE.test(role)) throw err('DESKTOP_DENIED', 'role 不合法');
+        opt('--role', role);
+      }
+      if (p.name !== undefined) opt('--name', str(p.name, 200));
+      if (p.text !== undefined) opt('--text', str(p.text, 200));
+      if (p.nth !== undefined) opt('--nth', int(p.nth, 0, 500, 0));
+      else opt('--limit', 20);
+      break;
+    }
+    case 'get':
+      if (p.property !== undefined) {
+        const prop = str(p.property, 10);
+        if (!['text', 'value', 'title', 'bounds', 'role', 'states'].includes(prop)) throw err('DESKTOP_DENIED', 'property 不合法');
+        opt('--property', prop);
+      }
+      break;
+    case 'screenshot':
+      where();
+      break;
+    case 'wait':
+      if (p.text !== undefined) { opt('--text', str(p.text, 200)); opt('--app', app); opt('--timeout', int(p.timeout, 100, 60000, 10000)); }
+      else if (p.windowTitle !== undefined) { opt('--window', str(p.windowTitle, 200)); opt('--timeout', int(p.timeout, 100, 60000, 10000)); }
+      else argv.push(String(int(p.ms, 0, 30000, 1000)));
+      break;
+    case 'type':
+      if (p.text === undefined) throw err('DESKTOP_DENIED', 'type 要给 text');
+      tail.push(str(p.text, 5000));
+      break;
+    case 'set-value':
+    case 'select':
+      if (p.value === undefined) throw err('DESKTOP_DENIED', `${cmd} 要给 value`);
+      tail.push(str(p.value, 5000));
+      break;
+    case 'scroll':
+      opt('--direction', ['up', 'down', 'left', 'right'].includes(p.direction) ? p.direction : 'down');
+      opt('--amount', int(p.amount, 1, 50, 3));
+      break;
+    case 'press': {
+      const combo = str(p.keys, 40);
+      if (!COMBO_RE.test(combo)) throw err('DESKTOP_DENIED', 'keys 要写成 return / escape / ctrl+s 这样');
+      argv.push(combo);
+      where();
+      break;
+    }
+    case 'launch':
+      tail.push(app);
+      break;
+    case 'focus-window':
+      where();
+      break;
+    case 'clipboard-set':
+      if (p.text === undefined) throw err('DESKTOP_DENIED', 'clipboard-set 要给 text');
+      tail.push(str(p.text, 20000));
+      break;
+    case 'list-notifications':
+      if (p.app !== undefined) opt('--app', str(p.app, 80));
+      opt('--limit', 20);
+      break;
+    case 'notification-action': {
+      const by = str(p.app, 80);
+      if (!by) throw err('DESKTOP_DENIED', 'notification-action 要给 app：通知来自哪个应用');
+      if (isBrowserApp(by) || /vcorp/i.test(by)) throw err('DESKTOP_DENIED', '不能替用户点浏览器发出的通知——那里面有任务批准和付款确认');
+      opt('--expected-app', by);
+      argv.push(String(int(p.index, 1, 100, 1)));
+      tail.push(str(p.action, 60));
+      break;
+    }
+    default:
+      break;
+  }
+
+  if (p.headed) argv.push('--headed');
+  const session = str(ctx.session, 64);
+  if (session) {
+    if (!SESSION_RE.test(session)) throw err('DESKTOP_DENIED', 'session 不合法');
+    if (cmd !== 'list-apps' && cmd !== 'clipboard-set' && cmd !== 'clipboard-get') opt('--session', session);
+  }
+  if (tail.length) argv.push('--', ...tail);
+
+  const sensitive = spec.kind === 'write' ? sensitivity(target?.name) : null;
+  return { cmd, argv, kind: spec.kind, app, target, sensitive };
+}
+
+// 快照（或 find）回来之后的复核：浏览器的窗口只认文件对话框。
+// snapshot 允许先拍一张浏览器的非主窗口，拍回来不是文件对话框就整份作废，树不出门。
+export function checkObserved(rec) {
+  if (!rec) return;
+  const gate = browserGate(rec.app, rec.window?.title || '', rec.fileDialog);
+  if (gate) throw err('DESKTOP_DENIED', gate);
+}
+
+// list-windows 的结果出门前过一道：浏览器主窗口的标题是用户正在看的网页，云端不给。
+// 本机给，但标上「不可操作」，免得 agent 拿它去 snapshot。
+export function filterWindows(list, channel) {
+  const arr = Array.isArray(list) ? list : [];
+  return arr.flatMap((w) => {
+    const main = isBrowserApp(w.app_name) && isBrowserMainTitle(w.title);
+    if (main && channel === 'cloud') return [];
+    if (main) return [{ ...w, blocked: '浏览器主窗口：用浏览器工具操作' }];
+    if (deniedApp(w.app_name, channel)) return channel === 'cloud' ? [] : [{ ...w, blocked: deniedApp(w.app_name, channel) }];
+    return [w];
+  });
+}
+
+// 批处理：一步一步过同一套检查。敏感动作不代做，和页面侧的 act 一个规矩。
+export const STEPS_MAX = 20;
+export function checkSteps(steps) {
+  if (!Array.isArray(steps) || !steps.length) throw err('DESKTOP_DENIED', 'steps 要是非空数组');
+  if (steps.length > STEPS_MAX) throw err('DESKTOP_DENIED', `steps 最多 ${STEPS_MAX} 步`);
+  for (const st of steps) {
+    if (!st || typeof st !== 'object' || Array.isArray(st)) throw err('DESKTOP_DENIED', 'steps 的每一步都要是对象');
+    if (st.steps !== undefined) throw err('DESKTOP_DENIED', 'steps 不能嵌套');
+    if (!DESKTOP_CMDS[st.cmd]) throw err('DESKTOP_DENIED', `steps 里不支持 ${st.cmd}`);
+  }
+  return steps;
+}
+
+// ---------- 云端：应用申请 ----------
+
+export const APPS_MAX = 10;
+
+export function cleanApps(list) {
+  const apps = [];
+  const bad = [];
+  for (const raw of [].concat(list ?? [])) {
+    const k = appKey(raw);
+    if (!k || !/^[\p{L}\p{N} ._()-]{1,80}$/u.test(k)) { bad.push(String(raw).slice(0, 40)); continue; }
+    if (isBrowserApp(k) || deniedApp(k, 'cloud')) { bad.push(String(raw).slice(0, 40)); continue; }
+    if (!apps.includes(k)) apps.push(k);
+  }
+  return { apps: apps.slice(0, APPS_MAX), bad, overflow: apps.slice(APPS_MAX) };
+}
+
+export function appsToAsk(add, { covered = [], apps = [], refused = [] } = {}) {
+  const ask = [];
+  const already = [];
+  for (const a of add) {
+    if (covered.includes(a) || apps.includes(a)) already.push(a);
+    else if (!refused.includes(a)) ask.push(a);
+  }
+  return { ask, covered: already };
+}

package/extension/desktop-render.js

@@ -0,0 +1,81 @@
+// agent-desktop 信封 → 给模型看的短文本。纯函数：本机执行器（src/lib/desktop.js）和
+// 云端通道（cloud.js，经原生宿主）用同一份，两边的 agent 读到的是同一种回执。
+import { DESKTOP_CMDS } from './desktop-policy.js';
+
+const LINES_MAX = 400;
+
+export function renderTree(tree) {
+  const lines = [];
+  let cut = 0;
+  const walk = (n, depth) => {
+    if (!n || typeof n !== 'object') return;
+    const named = n.name || n.value;
+    const show = n.ref_id || (named && depth < 30);
+    if (show) {
+      if (lines.length >= LINES_MAX) { cut += 1; } else {
+        const bits = [];
+        if (n.value !== undefined && n.value !== null && n.value !== n.name) bits.push(`value: ${JSON.stringify(String(n.value).slice(0, 120))}`);
+        for (const s of n.states || []) if (s !== 'readonly') bits.push(s);
+        if (n.subtree_truncated) bits.push('subtree_truncated');
+        if (n.children_count !== undefined && !n.children) bits.push(`${n.children_count} children`);
+        const ref = n.ref_id ? `[${n.ref_id}] ` : '';
+        lines.push(`${'  '.repeat(Math.min(depth, 12))}${ref}${n.role || '?'}${n.name ? ` ${JSON.stringify(String(n.name).slice(0, 80))}` : ''}${bits.length ? ` (${bits.join(', ')})` : ''}`);
+      }
+    }
+    for (const c of Array.isArray(n.children) ? n.children : []) walk(c, show ? depth + 1 : depth);
+  };
+  walk(tree, 0);
+  if (cut) lines.push(`…还有 ${cut} 个节点没列出：用 root:<ref> 往某一块里钻，或 skeleton:true 先看轮廓`);
+  return lines.join('\n');
+}
+
+// disposition → 效果行。agent-desktop 的语义：delivered_verified 读回过，
+// delivered_unverified 只是发出去了，retry: unsafe 就是「可能已经生效」。
+export function effectLine(env) {
+  const d = env?.data?.disposition || env?.error?.disposition;
+  if (env?.ok) {
+    if (!d) return '';
+    if (d.delivery === 'delivered_verified') return `效果：已读回验证${env.data.details?.verification_scope ? `（${env.data.details.verification_scope}）` : ''}`;
+    if (d.delivery === 'delivered_unverified') return '效果：已送达，但没有读回证据——重新 snapshot 核对它变成了你要的样子没有';
+    if (d.delivery === 'not_delivered') return '效果：本来就是这个状态，什么都没做';
+    return '';
+  }
+  if (!d) return '';
+  if (d.retry === 'safe') return '没有送达，可以按建议重试';
+  return '⚠️ 这一下可能已经生效了。不要直接重试，先 snapshot 看现状';
+}
+
+function renderData(cmd, data) {
+  if (cmd === 'snapshot') {
+    const head = `# ${data.app || ''}${data.window?.title ? ` — ${data.window.title}` : ''}${data.window?.id ? ` [${data.window.id}]` : ''} [snapshot ${data.snapshot_id}] ${data.ref_count ?? 0} refs${data.complete === false ? '（不完整：观察时间用完了，可以 timeout 调大或用 root 往下钻）' : ''}`;
+    return `${head}\n\n${renderTree(data.tree)}`;
+  }
+  if (cmd === 'find') {
+    const list = data.match ? [data.match] : Array.isArray(data.matches) ? data.matches : [];
+    if (data.count !== undefined && !list.length) return `命中 ${data.count} 个`;
+    return list.map((m) => `[${m.ref_id}] ${m.role} ${JSON.stringify(m.name || '')}${m.value ? ` value: ${JSON.stringify(String(m.value).slice(0, 80))}` : ''}  ← ${(m.path || []).slice(-3).join(' › ')}`).join('\n') || '没有匹配';
+  }
+  if (cmd === 'list-windows') {
+    return (data || []).map((w) => `${w.id}  ${w.app_name}  ${JSON.stringify(w.title || '')}${w.minimized ? ' (minimized)' : ''}${w.is_focused ? ' (focused)' : ''}${w.blocked ? `  ⛔ ${w.blocked}` : ''}`).join('\n') || '没有窗口';
+  }
+  if (cmd === 'list-apps') return (data?.apps || []).map((a) => a.name).join('\n');
+  if (cmd === 'list-notifications') return JSON.stringify(data, null, 1).slice(0, 6000);
+  const keep = { ...data };
+  delete keep.disposition;
+  delete keep.steps;
+  if (keep.details) { delete keep.details.auto_wait; if (!Object.keys(keep.details).length) delete keep.details; }
+  const s = JSON.stringify(keep);
+  return s === '{}' ? '' : s.slice(0, 4000);
+}
+
+export function renderEnvelope(cmd, env, { target } = {}) {
+  const what = `${cmd}${target ? ` ${target.role} ${JSON.stringify(target.name || '')}` : ''}`;
+  if (!env?.ok) {
+    const e = env?.error || {};
+    return [`❌ ${what}：${e.code || 'INTERNAL'} ${e.message || ''}`, e.suggestion ? `建议：${e.suggestion}` : '', effectLine(env)].filter(Boolean).join('\n');
+  }
+  const body = renderData(cmd, env.data);
+  const eff = effectLine(env);
+  const head = DESKTOP_CMDS[cmd]?.kind === 'write' ? `✅ ${what}` : '';
+  return [head, eff, body].filter(Boolean).join('\n');
+}

package/extension/device.js

@@ -0,0 +1,144 @@
+// 设备模型 —— 一个用户、多台设备。纯函数，不碰任何 chrome / node API。
+//
+// 桥（本机）、扩展（云端中继）、服务器（opus-video-maker/extlink.js 抄一份）按同一套规则
+// 回答两个问题：命令要下到哪台设备，结果是从哪台设备来的。协议见 docs/协议.md 第十二节。
+//
+// 四个概念：
+// - 设备 device：能执行命令的独立终端。有自己的 id、类型 kind、能力清单 caps、所在机器 machine。
+// - 链路 link：设备怎么连上来。浏览器自己连；云端的桌面经同机浏览器中继。身份不随链路变。
+// - 机器 machine：同一台电脑上的设备共用一个 machineId。交接只在同机设备之间成立。
+// - 任务绑定：任务开始时把需要的设备钉住，整个任务不换设备。
+
+export const PROTOCOL_V = 2;
+
+export const KINDS = ['browser', 'desktop', 'mobile'];
+
+// 命令属于哪种能力。没写 cap 的老消息一律是浏览器命令——老扩展、老服务器照常工作。
+export const CAPS = ['browser', 'desktop'];
+
+export const DEVICE_ERRORS = {
+  NO_DEVICE: 'NO_DEVICE',
+  DEVICE_OFFLINE: 'DEVICE_OFFLINE',
+  DEVICE_NOT_IN_JOB: 'DEVICE_NOT_IN_JOB',
+  AMBIGUOUS_DEVICE: 'AMBIGUOUS_DEVICE',
+  DEVICE_NOT_HERE: 'DEVICE_NOT_HERE',
+};
+
+const ID_RE = /^[\w.:-]{1,80}$/;
+
+const err = (code, message, details) => Object.assign(new Error(message), { code, ...(details ? { details } : {}) });
+
+export function cleanDeviceId(raw) {
+  const s = String(raw ?? '').trim();
+  return ID_RE.test(s) ? s : '';
+}
+
+export function cleanKind(raw) {
+  return KINDS.includes(raw) ? raw : '';
+}
+
+export function capOf(msg) {
+  const c = msg?.cap;
+  return CAPS.includes(c) ? c : 'browser';
+}
+
+// 能力 → 能执行它的设备类型。手机以后会认领一部分 browser 命令（内置浏览器）和自己的 mobile 能力，
+// 那时在这里加映射，而不是在每个调用方各写一份。
+export function kindsFor(cap) {
+  return cap === 'desktop' ? ['desktop'] : ['browser'];
+}
+
+// 设备记录的规范形状。所有一侧上报的、服务器存的、给 agent 看的，都过这一道。
+export function cleanDevice(d) {
+  if (!d || typeof d !== 'object') return null;
+  const id = cleanDeviceId(d.id);
+  const kind = cleanKind(d.kind);
+  if (!id || !kind) return null;
+  const caps = d.caps && typeof d.caps === 'object' ? d.caps : {};
+  return {
+    id,
+    kind,
+    name: String(d.name || '').replace(/\s+/g, ' ').trim().slice(0, 60) || kind,
+    machine: cleanDeviceId(d.machine) || null,
+    parent: cleanDeviceId(d.parent) || null,
+    online: d.online !== false,
+    caps: {
+      platform: String(caps.platform || '').slice(0, 20),
+      version: String(caps.version || '').slice(0, 40),
+      cmds: Array.isArray(caps.cmds) ? caps.cmds.filter((c) => typeof c === 'string' && c.length <= 40).slice(0, 80) : [],
+    },
+  };
+}
+
+// 命令落到哪台设备。
+// devices：调用方能看到的设备（服务器：本任务绑定的；桥：本机目录）。
+// want：agent 显式指定的 device（可缺省）。cap：命令属于哪种能力。
+// 规则：指定了就必须在名单里、类型对、在线；没指定就找同类，唯一才落，两台以上不猜。
+export function resolveTarget(devices, { cap = 'browser', want = '' } = {}) {
+  const list = (Array.isArray(devices) ? devices : []).map(cleanDevice).filter(Boolean);
+  const kinds = kindsFor(cap);
+  const id = cleanDeviceId(want);
+  if (want && !id) throw err(DEVICE_ERRORS.NO_DEVICE, `设备号不合法：${String(want).slice(0, 40)}`);
+  if (id) {
+    const d = list.find((x) => x.id === id);
+    if (!d) throw err(DEVICE_ERRORS.DEVICE_NOT_IN_JOB, `设备 ${id} 不在可用设备里。先用 devices 看看有哪些。`);
+    if (!kinds.includes(d.kind)) throw err(DEVICE_ERRORS.NO_DEVICE, `设备 ${id} 是 ${d.kind}，不能执行 ${cap} 命令`);
+    if (!d.online) throw err(DEVICE_ERRORS.DEVICE_OFFLINE, `设备 ${d.name}（${id}）离线`);
+    return d;
+  }
+  const same = list.filter((x) => kinds.includes(x.kind));
+  if (!same.length) throw err(DEVICE_ERRORS.NO_DEVICE, `没有可执行 ${cap} 命令的设备`);
+  const live = same.filter((x) => x.online);
+  if (!live.length) throw err(DEVICE_ERRORS.DEVICE_OFFLINE, `${same.map((x) => x.name).join('、')} 离线`);
+  if (live.length > 1) {
+    throw err(DEVICE_ERRORS.AMBIGUOUS_DEVICE,
+      `有 ${live.length} 台设备都能执行 ${cap} 命令，用 device 指定一台：${live.map((x) => `${x.id}（${x.name}）`).join('、')}`,
+      { candidates: live.map((x) => x.id) });
+  }
+  return live[0];
+}
+
+// 中继：这条链路（self）收到一条命令，判断该自己执行、交给名下子设备，还是拒绝。
+// 不带 to 的老消息归自己。to 指向别人（包括同一用户的其它设备）一律拒绝——
+// 中继只替自己名下的设备转发，服务器想借道去别的设备，这里不答应。
+export function routeHere(msg, { self, children = [] }) {
+  const to = cleanDeviceId(msg?.to?.device);
+  const cap = capOf(msg);
+  if (!to) {
+    if (cap !== 'browser') {
+      const kid = children.find((c) => kindsFor(cap).includes(c.kind));
+      if (kid) return { device: kid, relay: true };
+      throw err(DEVICE_ERRORS.NO_DEVICE, `这台设备上没有 ${cap} 能力`);
+    }
+    return { device: self, relay: false };
+  }
+  if (to === self.id) {
+    if (!kindsFor(cap).includes(self.kind)) throw err(DEVICE_ERRORS.NO_DEVICE, `${self.kind} 设备不能执行 ${cap} 命令`);
+    return { device: self, relay: false };
+  }
+  const kid = children.find((c) => c.id === to);
+  if (!kid) throw err(DEVICE_ERRORS.DEVICE_NOT_HERE, `设备 ${to} 不在这条链路上`);
+  if (!kindsFor(cap).includes(kid.kind)) throw err(DEVICE_ERRORS.NO_DEVICE, `${kid.kind} 设备不能执行 ${cap} 命令`);
+  return { device: kid, relay: true };
+}
+
+// 结果和事件出门前盖上来源。from 只由执行它的一侧盖，信封里原有的 from 一律覆盖——
+// 不能让 payload 里自带一个伪造的来源。
+export function stampFrom(msg, device) {
+  const d = cleanDevice(device);
+  if (!d) return msg;
+  return { ...msg, from: { device: d.id, kind: d.kind, ...(d.machine ? { machine: d.machine } : {}) } };
+}
+
+// 给 agent 看的一行行设备清单
+export function describeDevices(devices) {
+  const list = (Array.isArray(devices) ? devices : []).map(cleanDevice).filter(Boolean);
+  if (!list.length) return '（没有可用设备）';
+  return list.map((d) => {
+    const bits = [d.kind, d.online ? '在线' : '离线'];
+    if (d.machine) bits.push(`机器 ${d.machine}`);
+    if (d.parent) bits.push(`经 ${d.parent} 中继`);
+    if (d.caps.platform) bits.push(d.caps.platform);
+    return `${d.id}  ${d.name}  (${bits.join(' · ')})`;
+  }).join('\n');
+}