@glittering0717/ai-browser 2.0.0 → 2.1.1

package/bin/ai-browser.cjs

@@ -25,6 +25,8 @@ Usage:
                               Install the bundled agent skills into your client
   ai-browser call <method> [json|-]
                               Call one JSON-RPC method and print the result
+                              (starts the browser first if it is not running)
+  ai-browser ensure           Start the browser if needed, then exit (idempotent)
   ai-browser status           Is the browser running? pid / port / tabs
   ai-browser --version        Print version
   ai-browser --help           Show this help
@@ -83,6 +85,13 @@ async function main() {
       process.exit(await runStatus(argv.slice(1)));
       break;
     }
+    case 'ensure': {
+      // 只把浏览器弄到"能连"的状态，然后退出。存在的理由：让 `call` 之外还有一条
+      // **显式**的启动动作，脚本/CI 里想先起再调时用它（幂等，已在跑就是 no-op）。
+      const { runEnsure } = require('../scripts/cli_call.cjs');
+      process.exit(await runEnsure(argv.slice(1)));
+      break;
+    }
     case '--version':
     case '-v':
     case 'version':

package/llms-install.md

@@ -11,8 +11,9 @@ semantic tree (roles / labels / values / actions, stable `data-ai-id` per elemen
 not screenshots. Input is trusted CDP keyboard/mouse events. A human can use the
 window's mouse and keyboard at any time (login, QR scan, CAPTCHA, payment).
 
-Two equivalent interfaces: **MCP stdio** (20 `browse_*` tools) and a raw WebSocket
-JSON-RPC API at `ws://localhost:9223` (`ui.*` methods).
+Two equivalent interfaces: **MCP stdio** (17 `browse_*` tools) and a raw WebSocket
+JSON-RPC API at `ws://localhost:9223` (`ui.*` methods). A CLI (`ai-browser call ui.xxx`) speaks
+the same JSON-RPC and needs **no registration at all** — see "Fastest path" below.
 
 ## Requirements
 
@@ -65,6 +66,28 @@ ls node_modules/electron/dist   # must contain Electron.app (macOS)
 Optional end-to-end check: `npx -y @glittering0717/ai-browser start` (or `npm start` from source) opens
 a 1280×800 window and logs `AI Browser WS server listening on ws://localhost:9223`.
 
+## Fastest path — works with zero registration
+
+If you just need to drive the browser now, skip the MCP section entirely. The CLI reaches the
+same engine, and **starts the browser itself if it is not running** (idempotent; no separate
+`start` step):
+
+```bash
+npm i -g @glittering0717/ai-browser     # or: npm link  (from a source checkout)
+ai-browser call ui.navigate '{"url":"https://example.com"}'
+ai-browser call ui.get_tree '{"subset":"interactive"}'
+ai-browser call ui.act '{"action":"click","target":"e:a-3"}'
+```
+
+No global install? Prefix every command with `npx -y @glittering0717/ai-browser`.
+
+Why this matters more than it looks: registering an MCP server passes through **three gates the
+agent does not control** — the config file, a one-time trust/approval for executing a local
+program, and the client's tool snapshot taken at session start. If any one of them has not
+completed, `browse_*` simply does not exist in the tool list, and the symptom is identical to
+"the capability is not installed". A weaker model then spends a long time concluding it is
+misconfigured. The CLI has none of those gates: it only needs the command to run.
+
 ## Register as an MCP server
 
 Add this to the client config (Claude Desktop config, `~/.cursor/mcp.json`, project `.mcp.json`,
@@ -105,7 +128,7 @@ call can take longer if the engine download hasn't happened yet — the progress
 A long-lived shared window is also fine — run the `start` command manually; a second launch only
 focuses the existing window (single instance lock).
 
-## The 20 tools
+## The 17 tools
 
 - `browse_navigate` — load a URL in the active or given tab.
 - `browse_get_tree` — semantic tree + context (modals, toasts, required-field
@@ -142,10 +165,24 @@ focuses the existing window (single instance lock).
   `switch` sets the default target for later calls, so you rarely pass `tab`.
 - `browse_quit` — shut the whole browser down and release the process.
 
-Prefer MCP when an agent client drives the browser. For shell / CI / debugging there is a CLI
-that speaks the same JSON-RPC: `ai-browser status`, `ai-browser call ui.list_tabs`,
-`ai-browser call ui.navigate '{"url":"..."}'`. One implementation, three doors — no separate
-script needed to call a method.
+**Which door should you use?** Prefer the **CLI** unless the tool list already contains
+`browse_*`. MCP is a nicer interface (schemas are self-describing) but it is not under your
+control; the CLI is. Both hit one implementation (`page_manager`) — there is no capability that
+only exists over MCP.
+
+```bash
+ai-browser status                                   # is it running? pid / port / tabs
+ai-browser ensure                                   # start it if needed, then exit
+ai-browser call ui.list_tabs
+ai-browser call ui.navigate '{"url":"..."}'
+```
+
+CLI method names are the tool names with `browse_` → `ui.` (`get_tree`, `act`, `navigate`,
+`evaluate`, `scroll`, `wait`, `screenshot`, `errors`, `capabilities`, `downloads`, `quit`,
+`auth_state`, `repaint`). The four that do not map one-to-one: `tabs` → `ui.list_tabs` /
+`ui.new_tab` / `ui.close_tab` / `ui.set_active_tab`; `network` → `ui.network_list` /
+`ui.network_get`; `canvas` → `ui.canvas_list` / `ui.canvas_read` / `ui.canvas_capture` /
+`ui.canvas_configure`; `diff` → `ui.snapshot` / `ui.diff`.
 
 There is no `browse_subscribe` and no `browse_network_body`: real-time events are
 raw-WebSocket only (`ui.subscribe`), because MCP stdio drops server→client

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittering0717/ai-browser",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "AI-native browser — renders pixels for humans, structured semantic-tree API for agents. No screenshots, no OCR, no coordinate guessing.",
   "main": "src/main/index.js",
   "bin": {
@@ -15,7 +15,9 @@
     "examples/AGENT_INSTRUCTIONS.md",
     "examples/mcp-config.json",
     "llms-install.md",
-    "LICENSE"
+    "LICENSE",
+    "build/icon.png",
+    "build/icon.icns"
   ],
   "type": "module",
   "license": "MIT",
@@ -72,6 +74,7 @@
     "audit": "node e2e/audit_ws.cjs",
     "e2e:all": "node e2e/run_all.cjs",
     "readcov": "node e2e/readcov_ws.cjs",
+    "winopen": "node e2e/window_open_ws.cjs",
     "coverage": "node tools/coverage_probe.cjs"
   },
   "dependencies": {

package/scripts/cli_call.cjs

@@ -22,25 +22,33 @@
 // 选项：
 //   --port <n>       默认 9223（也读 AI_BROWSER_WS_PORT）
 //   --timeout <ms>   默认 30000
+//   --no-start       连不上**不要**自动拉起浏览器（脚本里想快速失败时用）
 //   --compact        单行输出（默认就是紧凑 JSON，加这个只是显式）
 //   --pretty         缩进输出（给人看时用）
+//
+// 关于自动拉起（2026-10-20 改）：`call` 连不上时默认会先把浏览器拉起来再重试一次。
+// 理由：agent 装完包应该一条命令就能干活，而不是先学"要 start 再 call"两步。
+// `status` 不这么做 —— 它问的是"在跑吗"，回答了"不在"才算答对。
 'use strict';
 
 const WS_PORT_DEFAULT = 9223;
 const TIMEOUT_DEFAULT = 30000;
 
 function parseArgs(argv) {
-  const out = { port: null, timeout: TIMEOUT_DEFAULT, pretty: false, rest: [] };
+  const out = { port: null, timeout: TIMEOUT_DEFAULT, pretty: false, start: true, rest: [] };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--port') { out.port = Number(argv[++i]); continue; }
     if (a === '--timeout') { out.timeout = Number(argv[++i]); continue; }
     if (a === '--pretty') { out.pretty = true; continue; }
     if (a === '--compact') { out.pretty = false; continue; }
+    if (a === '--no-start') { out.start = false; continue; }
     out.rest.push(a);
   }
   if (!out.port || !Number.isFinite(out.port)) {
-    const envPort = Number(process.env.AI_BROWSER_WS_PORT);
+    // AI_BROWSER_PORT 是 Electron 侧（src/shared/config.js）用的名字，读它才和
+    // "AI_BROWSER_PORT=9701 ai-browser ensure" 这种用法对得上；WS_PORT 是历史别名。
+    const envPort = Number(process.env.AI_BROWSER_PORT ?? process.env.AI_BROWSER_WS_PORT);
     out.port = Number.isFinite(envPort) && envPort > 0 ? envPort : WS_PORT_DEFAULT;
   }
   if (!Number.isFinite(out.timeout) || out.timeout <= 0) out.timeout = TIMEOUT_DEFAULT;
@@ -103,7 +111,7 @@ function rpcCall({ port, timeout, method, params }) {
     ws.on('error', (e) => {
       clearTimeout(timer);
       const hint = /ECONNREFUSED/i.test(e.message)
-        ? `浏览器没在 127.0.0.1:${port} 上跑。先 \`ai-browser start\`（MCP 客户端会自己拉起），或用 --port 指定别的端口。`
+        ? `浏览器没在 127.0.0.1:${port} 上跑。\`ai-browser ensure\` 会拉起它，\`ai-browser start\` 是前台启动。`
         : e.message;
       done(reject, Object.assign(new Error(hint), { code: 'connect_failed' }));
     });
@@ -138,7 +146,43 @@ async function runCall(argv) {
     printResult(result, opt.pretty);
     return 0;
   } catch (e) {
-    process.stderr.write(`[ai-browser] ${e.message}\n`);
+    // 连不上 → 默认把浏览器拉起来再试一次（见文件头"关于自动拉起"）。
+    // 只在 connect_failed 时做：方法不存在、参数错这类不该去启动进程。
+    if (e.code !== 'connect_failed' || !opt.start) {
+      process.stderr.write(`[ai-browser] ${e.message}\n`);
+      return 1;
+    }
+    const { ensureRunning } = require('./ensure_running.cjs');
+    try {
+      const info = await ensureRunning({
+        port: opt.port,
+        log: (m) => process.stderr.write(m + '\n'),
+      });
+      if (info.started) process.stderr.write(`[ai-browser] browser started (via ${info.via})\n`);
+      const result = await rpcCall({ port: opt.port, timeout: opt.timeout, method, params });
+      printResult(result, opt.pretty);
+      return 0;
+    } catch (e2) {
+      // ensure 的报错已经带原因和下一步；原始连接错误作为补充，别只丢一句 ECONNREFUSED。
+      process.stderr.write(`[ai-browser] ${e2.message}\n`);
+      return 1;
+    }
+  }
+}
+
+/** `ai-browser ensure` — 只负责把浏览器弄到"能连"的状态，不调任何业务方法。 */
+async function runEnsure(argv) {
+  const opt = parseArgs(argv);
+  const { ensureRunning } = require('./ensure_running.cjs');
+  try {
+    const info = await ensureRunning({
+      port: opt.port,
+      log: (m) => process.stderr.write(m + '\n'),
+    });
+    printResult({ ...info, port: info.port ?? opt.port }, opt.pretty);
+    return 0;
+  } catch (e) {
+    printResult({ running: false, port: opt.port, error: e.message }, opt.pretty);
     return 1;
   }
 }
@@ -175,4 +219,4 @@ function readStdin() {
   }
 }
 
-module.exports = { runCall, runStatus, parsePayload, parseArgs, rpcCall, WS_PORT_DEFAULT };
+module.exports = { runCall, runStatus, runEnsure, parsePayload, parseArgs, rpcCall, WS_PORT_DEFAULT };

package/scripts/ensure_running.cjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// scripts/ensure_running.cjs — 幂等地把浏览器弄起来，CLI 与 MCP **共用这一份**。
+//
+// # 为什么抽出来（2026-10-20）
+//
+// 原来这段只活在 mcp_server.js 里（ensureElectronRunning）。后果是：
+//   • 走 MCP 的 agent：浏览器没开也能用（服务端自动拉起）；
+//   • 走 CLI 的 agent：连不上只会看到 "先 ai-browser start" —— 得学两步。
+// 而「装完就能用」要求的是**一条命令**。所以把拉起逻辑挪到共享模块，
+// 两个壳调用同一份实现（与项目一贯的"一套实现、多个薄壳"对齐）。
+//
+// # 三个坑（都是实测踩出来的，别删）
+//
+// ① `ELECTRON_RUN_AS_NODE` 必须删掉。本机 shell 就带着它，此时 electron 二进制
+//    会当普通 Node 跑，拿 Node 加载 ESM 入口直接崩，端口永不监听，而报错是一串
+//    Node 的 ESM 栈 —— 完全不提 Electron。
+// ② 必须 `detached` + `unref()`。否则调用方（CLI 进程）一退出，浏览器被一起带走。
+// ③ 失败必须**带原因**。之前 return false 被上层 catch 吞掉，agent 先重试 120 秒，
+//    最后只拿到 "connection refused"，没有任何线索说明浏览器根本没起来。
+//
+// # macOS 的沙箱兜底（第四个坑）
+//
+// 在受限运行环境里（agent 的沙箱 shell）直接 spawn Chromium，会以
+// "sandbox initialization failed: Operation not permitted" 挂掉 —— 沙箱能力
+// 随父进程继承，`--no-sandbox` 也救不了。此时改走 LaunchServices：
+//   open -n -a <Electron.app> --args <appRoot>
+// 新进程由 launchd 拉起，不继承父进程的沙箱限制。这条兜底不是 hack，是 macOS
+// 上启动 GUI 应用的**正规方式**（Finder 双击走的就是它）。
+'use strict';
+
+const { spawn } = require('node:child_process');
+const net = require('node:net');
+const path = require('node:path');
+
+const ROOT = path.resolve(__dirname, '..');
+const DEFAULT_PORT = 9223;
+const DEFAULT_TIMEOUT = 30000;
+
+/** 端口上有没有人在听。超时 500ms —— 只探本地回环，不该慢。 */
+function checkPort(port, host = '127.0.0.1') {
+  return new Promise((resolve) => {
+    const sock = net.connect({ port, host });
+    let done = false;
+    const finish = (ok) => { if (!done) { done = true; sock.destroy(); resolve(ok); } };
+    sock.once('connect', () => finish(true));
+    sock.once('error', () => finish(false));
+    sock.once('timeout', () => finish(false));
+    sock.setTimeout(500);
+  });
+}
+
+/** 轮询等到端口起来，或超时。`abort()` 说"别等了"时立刻放弃（子进程已经没了）。 */
+async function waitForPort(port, timeoutMs, stepMs = 400, abort = null) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await checkPort(port)) return true;
+    if (abort && abort()) return false;   // 子进程已经报错退出，再等只是浪费
+    await new Promise((r) => setTimeout(r, stepMs));
+  }
+  return false;
+}
+
+/**
+ * 从 electron 二进制路径反推 macOS 的 .app 包路径。
+ * `/x/Electron.app/Contents/MacOS/Electron` → `/x/Electron.app`
+ * 非 mac / 路径不含 .app 时返回 null。
+ */
+function appBundleFromBinary(bin) {
+  if (!bin) return null;
+  const i = bin.indexOf('.app' + path.sep);
+  if (i < 0) return null;
+  return bin.slice(0, i + 4);
+}
+
+/** 用 LaunchServices 启动（macOS）。返回是否成功把进程扔出去（不代表端口会开）。 */
+function launchViaOpen(bundle, root, log) {
+  try {
+    const child = spawn('open', ['-n', '-a', bundle, '--args', root], {
+      stdio: 'ignore',
+      detached: true,
+    });
+    child.unref();
+    return true;
+  } catch (e) {
+    log(`[ensure] open -a ${bundle} failed: ${e.message}`);
+    return false;
+  }
+}
+
+/**
+ * 确保浏览器在跑。幂等：已经在跑就立刻返回。
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.port=9223]
+ * @param {number} [opts.timeoutMs=30000]  首轮等待上限
+ * @param {(msg: string) => void} [opts.log]  进度输出（走 stderr，别污染 stdout 的 result）
+ * @param {boolean} [opts.allowLaunchServices=true]  macOS 沙箱失败时是否兜底走 open
+ * @returns {Promise<{running:boolean, started:boolean, via:string|null, port:number}>}
+ * @throws 端口始终没起来时抛错，message 里带**可执行的下一步**
+ */
+async function ensureRunning(opts = {}) {
+  const port = Number(opts.port) || DEFAULT_PORT;
+  const timeoutMs = Number(opts.timeoutMs) || DEFAULT_TIMEOUT;
+  const log = opts.log || ((m) => console.error(m));
+  const allowLS = opts.allowLaunchServices !== false;
+
+  if (await checkPort(port)) return { running: true, started: false, via: 'already', port };
+
+  // AI_BROWSER_ELECTRON_BIN：显式指定二进制（打包版、自定义构建、e2e 用假路径）。
+  // 没设就交给共享解析器（它会在二进制缺失时自己跑一遍 electron 的安装脚本）。
+  let bin;
+  const override = process.env.AI_BROWSER_ELECTRON_BIN;
+  if (override) {
+    bin = override;
+  } else {
+    const { resolveElectronBinary } = require('./electron_resolve.cjs');
+    try {
+      bin = resolveElectronBinary({ log });
+    } catch (e) {
+      throw new Error(
+        `could not locate the Electron binary: ${e.message}\n`
+        + '  fix: run `npm install` once inside the ai-browser package (this also downloads Chromium).'
+      );
+    }
+  }
+
+  log(`[ensure] port ${port} not listening — starting ai-browser`);
+
+  // —— 第一轮：直接 spawn（Linux/Windows 的正常路径，macOS 也先试这个）——
+  const env = { ...process.env, AI_BROWSER_LAUNCHED_BY_AGENT: '1' };
+  delete env.ELECTRON_RUN_AS_NODE;   // 坑 ①
+  let earlyExit = null;
+  let child = null;
+  try {
+    child = spawn(bin, [ROOT], { cwd: ROOT, detached: true, stdio: 'ignore', env });  // 坑 ②
+    child.unref();
+    child.on('exit', (code, signal) => { earlyExit = { code, signal }; });
+    child.on('error', (e) => { earlyExit = { error: e.message }; });
+  } catch (e) {
+    log(`[ensure] spawn failed: ${e.message}`);
+    earlyExit = { error: e.message };
+  }
+
+  // 子进程自报错（ENOENT 之类）就别等满超时了 —— 那只会把真实原因埋掉。
+  let ok = await waitForPort(port, timeoutMs, 400, () => !!(earlyExit && earlyExit.error));
+  if (ok) return { running: true, started: true, via: 'spawn', port };
+
+  // —— 第二轮：macOS 沙箱兜底，走 LaunchServices ——
+  let lsTried = false;
+  if (allowLS && process.platform === 'darwin') {
+    const bundle = appBundleFromBinary(bin);
+    if (bundle) {
+      lsTried = true;
+      log(`[ensure] direct spawn did not come up (${describeExit(earlyExit)}) — retrying via LaunchServices`);
+      if (launchViaOpen(bundle, ROOT, log)) {
+        ok = await waitForPort(port, 20000);
+        if (ok) return { running: true, started: true, via: 'launchservices', port };
+      }
+    }
+  }
+
+  throw new Error(buildFailureMessage({ port, earlyExit, lsTried }));
+}
+
+/** 把子进程退出状态说人话。 */
+function describeExit(earlyExit) {
+  if (!earlyExit) return 'no exit event, port still closed';
+  if (earlyExit.error) return `spawn error: ${earlyExit.error}`;
+  return `exited early (code=${earlyExit.code}, signal=${earlyExit.signal})`;
+}
+
+/** 失败原因 + 用户/agent 照着能做的下一步。 */
+function buildFailureMessage({ port, earlyExit, lsTried }) {
+  const lines = [`could not start the browser: nothing is listening on 127.0.0.1:${port}`];
+  lines.push(`  cause: ${describeExit(earlyExit)}`);
+  if (lsTried) lines.push('  a LaunchServices launch (open -n -a Electron.app) was also tried and did not come up');
+  lines.push(
+    '  common causes:',
+    '    • ELECTRON_RUN_AS_NODE is set in the environment (unset it)',
+    '    • Chromium sandbox is blocked inside a container/sandbox — launch once from a normal terminal: `ai-browser start`',
+    '    • Chromium binary missing or partially extracted — `npm install` in the ai-browser package',
+    '    • a stale lock: another instance owns this userData dir (quit it, or use --port for a separate profile)'
+  );
+  return lines.join('\n');
+}
+
+module.exports = {
+  ensureRunning,
+  checkPort,
+  waitForPort,
+  appBundleFromBinary,
+  DEFAULT_PORT,
+  DEFAULT_TIMEOUT,
+  APP_ROOT: ROOT,
+};

package/skills/ai-browser/SKILL.md

@@ -7,48 +7,49 @@ description: >-
 
 # ai-browser
 
-## 先看这一行
+## 两条路，选一条就能干活
 
-`browse_*` 工具在不在？**不在 = MCP 没挂上，别去翻配置文件**，直接用 CLI（同一个 JSON-RPC，
-stdout 只有 result）：`ai-browser status`、`ai-browser call ui.navigate '{"url":"…"}'`。
-
-## 三步（照抄即可）
+工具在就 `browse_navigate {"url":"https://example.com"}`；**不在也不用配任何东西**，走 CLI（同一引擎，装完即用）：
 
 ```
-browse_navigate  {"url":"https://example.com"}
-browse_get_tree  {"subset":"interactive"}
-browse_act       {"action":"click","target":"e:a-3"}
+ai-browser call ui.get_tree '{"subset":"interactive"}'        # 读页面，拿 e:xxx
+ai-browser call ui.act '{"action":"click","target":"e:a-3"}'  # 点它
+ai-browser call ui.navigate '{"url":"https://example.com"}'
 ```
 
-`browse_get_tree` 返回的每个节点都有 `id`（形如 `e:a-3`）；`browse_act` 的 `target` **只接受这个 id**，
-不接受页面上看到的文字（传文字会报 `target_not_found`）。
+没这个命令就加前缀 `npx -y @glittering0717/ai-browser`。浏览器没开时会自动拉起。
+
+CLI 方法 = 工具名去掉 `browse_` 换 `ui.`（`get_tree` `act` `navigate` … 一一对应）。
+不一一对应的 4 个（tabs/network/canvas/diff）见 `references/cli.md`。
+
+## 点东西只认 id
+
+`get_tree` 每个节点有 `id`（形如 `e:a-3`）。`act` 的 `target` **只接受这个 id**，
+传页面上的文字会报 `target_not_found`。
 
-## 每次操作后先看 `effect_state`
+## 操作后先看 effect_state
 
-| 值 | 意思 | 该做什么 |
-|---|---|---|
-| `committed` | 已生效 | 别重试，继续下一步 |
-| `none` | 页面没被动过 | 修掉原因（换 target / 重读树）再试 |
-| `unknown` | 说不准（超时等） | **先 `browse_get_tree` 看现状**，盲目重试会提交两次 |
+`committed` 已生效 → 继续｜`none` 页面没动 → 换 target 或重读树｜
+`unknown` 说不准 → **先重读树再决定**，盲目重试会提交两次。
 
 ## 卡住时
 
 | 现象 | 先做什么 |
 |---|---|
-| 树里没有要点的东西 | `browse_wait {"condition":"text_contains","text":"关键词"}` 再重读树 |
-| `target_not_found` 且 `stale_ref:true` | 页面变过 → 重读树拿新 id |
-| `target_not_found` 且 `ref_diagnosis:"never_seen"` | id 本身错了 → 别重读，改传参 |
-| 点了没反应 | `browse_screenshot` 看画面；`browse_network {"operation":"list"}` 看请求 |
-| 怀疑掉登录 | `browse_auth_state` |
-| 以上都不对 | `browse_errors` |
+| 树里没有要点的东西 | 等 `{"condition":"text_contains","text":"关键词"}` 再重读 |
+| `target_not_found` + `stale_ref` | 页面变了 → 重读树拿新 id |
+| `target_not_found` + `never_seen` | id 本身错 → 别重读，改参数 |
+| 点了没反应 | `screenshot` 看画面；`network_list` 看请求 |
+| 怀疑掉登录 | `auth_state` |
+| 以上都不对 | `errors` |
 
 ## 需要人帮忙
 
-登录、扫码、滑块、支付：**在对话里请用户在自己的窗口里操作**，他说"好了"再 `browse_get_tree` 确认。
-不要编造账号密码，不要反复重试注定失败的点击。
+登录/扫码/滑块/支付：**请用户在自己的窗口里操作**，他说"好了"再重读树确认。不要编造密码。
 
-## 按需深挖（不要一上来就读）
+## 按需深挖
 
+- `references/cli.md` — CLI 全部方法与参数对照
 - `references/troubleshooting.md` — 失败排查顺序
 - `references/hard-pages.md` — canvas / 富文本 / iframe / 上传
 - `references/network.md` — 抓请求、取结构化数据

package/skills/ai-browser/references/cli.md

@@ -0,0 +1,81 @@
+# CLI — 不用 MCP 也能干活的那条路
+
+## 什么时候得用它
+
+`browse_*` 工具是 MCP 层的东西。MCP 要挂上，得经过客户端的三道闸门：配置文件、一次性授权、
+会话启动时的工具快照。任何一环没走完（最常见：**改完配置没开新会话**），工具就不出现。
+
+这时候别顺着"配置 → 授权 → 重启"往下修 —— 那条路在客户端手里，你改不动。
+CLI 是同一个 JSON-RPC 的另一个门，只依赖一件事：命令能在 PATH 里跑起来。
+
+```bash
+ai-browser call ui.get_tree '{"subset":"interactive"}'
+# 没装全局命令时：
+npx -y @glittering0717/ai-browser call ui.get_tree '{"subset":"interactive"}'
+```
+
+stdout 只有 result（紧凑 JSON，可直接 `| jq`），进度和错误走 stderr。
+
+## 先确认它是不是活着
+
+```bash
+ai-browser status          # {"running":true,"pid":…,"port":9223,"tabs":[…]}
+ai-browser ensure          # 幂等：没开就拉起，开了就直接返回
+ai-browser call ui.get_tree   # 连不上会自动 ensure 再重试一次
+```
+
+`status` **不会**拉起浏览器 —— 它问的是"在跑吗"，答"不在"才算答对。
+`call` 会。想快速失败（脚本里）加 `--no-start`。
+
+## 方法对照表
+
+MCP 工具名去掉 `browse_`，换成 `ui.`，就是 CLI 方法名。
+
+| 一一对应 | get_tree · act · navigate · evaluate · scroll · wait · screenshot · errors · capabilities · downloads · quit · auth_state · repaint |
+|---|---|
+| `browse_tabs` | `ui.list_tabs` / `ui.new_tab` / `ui.close_tab` / `ui.set_active_tab` |
+| `browse_network` | `ui.network_list` / `ui.network_get`（两个，不是一个） |
+| `browse_canvas` | `ui.canvas_list` / `ui.canvas_read` / `ui.canvas_capture` / `ui.canvas_configure` |
+| `browse_diff` | `ui.snapshot` / `ui.diff` |
+
+## 常用参数（底层契约，CLI 直传）
+
+```bash
+ai-browser call ui.navigate '{"url":"https://example.com","tab":1,"wait_until":"load"}'
+ai-browser call ui.get_tree '{"tab":1,"subset":"interactive"}'    # 交互树
+ai-browser call ui.get_tree '{"tab":1,"ax":true}'                # 阅读树（长正文用它）
+ai-browser call ui.act '{"action":"click","target":"e:a-3"}'
+ai-browser call ui.act '{"action":"type","target":"e:input-1","text":"关键词"}'
+ai-browser call ui.evaluate '{"js":"document.title"}'
+ai-browser call ui.evaluate '{"frame_ref":"frame-1","js":"document.body.innerText"}'
+ai-browser call ui.wait '{"condition":"text_contains","text":"加载完成"}'
+ai-browser call ui.network_list '{"tab":1}'
+ai-browser call ui.screenshot '{"tab":1}'
+```
+
+`ui.act` 的 `target` 只认树里的 `id`（形如 `e:a-3`），不认页面上的文字。
+
+长 JSON 别跟 shell 引号搏斗，用 `-` 从 stdin 读：
+
+```bash
+echo '{"action":"type","target":"e:input-1","text":"很长很长的内容"}' | ai-browser call ui.act -
+```
+
+## 没连上时它在说什么
+
+| stderr 里出现 | 意思 | 下一步 |
+|---|---|---|
+| `没在 127.0.0.1:9223 上跑` | 浏览器没起（`--no-start` 时最常见） | 去掉 `--no-start`，或 `ai-browser ensure` |
+| `could not start the browser: …cause: exited early` | 拉起了但立刻崩 | 看 cause：`ELECTRON_RUN_AS_NODE` 没清 / Chromium 沙箱被拦 / 二进制没装全 |
+| `Method not found (ui.xxx)` | 方法名错（拼错，或用了 MCP 的名字） | 对照上面的表 |
+| `no reply from … within …ms` | 方法执行太慢 | 加大 `--timeout` |
+
+## 端口与多实例
+
+```bash
+ai-browser status --port 9701
+AI_BROWSER_PORT=9701 AI_BROWSER_USER_DATA=/tmp/ab-test ai-browser ensure
+```
+
+同一 `AI_BROWSER_USER_DATA` 有单实例锁 —— 换 profile 才能开第二个。
+搞 e2e / 并行任务时必须换，否则会撞锁，端口永远不开。

package/src/main/index.js

@@ -2,6 +2,7 @@
 // One process, one WS server, multiple tabs with real tab bar.
 import { app, BrowserWindow, BrowserView, ipcMain, net, session, dialog } from 'electron';
 import path from 'node:path';
+import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { startWSServer } from './ws_server.js';
 import { PageManager } from './page_manager.js';
@@ -326,10 +327,40 @@ if (gotLock) {
   app.quit();
 }
 
+// === 应用图标（2026-10-20）===
+//
+// macOS 上从源码启动时 Dock 图标是 Electron 的默认火箭 —— 因为进程本体就是
+// node_modules/electron/dist/Electron.app，**Dock 跟的是可执行文件，不是我们的
+// 代码**。打包版没有这个问题（Info.plist 里已经是自定义 icns），但 `npm start`
+// / `npx` 启动占日常使用的大头；图标错了，用户的判断就是"这不是 AI Browser"。
+// （2026-10-20 原话："我看现在系统里运行的 ai-browser 都是默认图标了"。）
+//
+// app.dock.setIcon 是 Electron 提供的运行时入口，不影响签名与打包。
+// Windows/Linux 走 BrowserWindow 的 icon 选项（见 createWindow）。
+function appIconPath() {
+  const p = path.join(__dirname, '..', '..', 'build', 'icon.png');
+  try { return fs.existsSync(p) ? p : null; } catch (_) { return null; }
+}
+
+function applyAppIcon() {
+  if (process.platform !== 'darwin') return false;   // 其他平台由窗口 icon 选项负责
+  const icon = appIconPath();
+  if (!icon) return false;   // 装的是精简包（没带 build/）→ 静默跳过，不值得启动失败
+  try {
+    if (app.dock && typeof app.dock.setIcon === 'function') { app.dock.setIcon(icon); return true; }
+  } catch (e) {
+    console.error('[icon] dock.setIcon failed:', e && e.message);
+  }
+  return false;
+}
+
 function createWindow() {
   mainWindow = new BrowserWindow({
     width: 1280,
     height: 800,
+    // Windows/Linux 的任务栏图标来自这里（macOS 走 app.dock.setIcon，
+    // 见 applyAppIcon：Dock 跟的是进程可执行文件，不是窗口选项）。
+    icon: appIconPath() || undefined,
     // 先不显示：如何显示由 showInitialWindow() 按焦点策略决定 —— 窗口必须真实可见
     // （产品承诺人可随时介入），但被 agent 拉起时不该把用户正在做的事打断。
     show: false,
@@ -764,6 +795,7 @@ function normalizeUrlInput(input) {
 }
 
 app.whenReady().then(() => {
+  applyAppIcon();
   createWindow();
 
   // === 自检钩子：AI_BROWSER_SELFTEST=crash ===

package/src/main/mcp_server.js

@@ -9,14 +9,11 @@ import {
   ListResourcesRequestSchema,
   ListResourceTemplatesRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
-import net from 'node:net';
-import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-// Shared Electron-binary resolver. npm >= 11 blocks dependency install scripts
-// by default (so plain `npx` leaves electron without its engine); the resolver
-// self-heals by running electron's bundled installer on first launch.
-import electronResolve from '../../scripts/electron_resolve.cjs';
+// 启动逻辑与 CLI 共用一份（scripts/ensure_running.cjs）。曾经这里有一份私有实现，
+// 结果 MCP 能自动拉起浏览器、CLI 不能 —— 同一件事两个行为。
+import ensureMod from '../../scripts/ensure_running.cjs';
 import { MCP_TOOLS } from './mcp_tools.js';
 import { actParams, networkParams } from './mcp_args.js';
 import { evaluateGuardError } from '../shared/guards.js';
@@ -33,96 +30,29 @@ const ELECTRON_PORT = config.wsPort;
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-// App/package root — identical layout in a git checkout and inside
-// node_modules/@glittering0717/ai-browser: src/main/ → up two levels.
-const APP_ROOT = path.resolve(__dirname, '..', '..');
-const { resolveElectronBinary } = electronResolve;
+const { ensureRunning, checkPort } = ensureMod;
 
 // Persistent WS client — one reused connection with incrementing ids.
 // Lazy launch: no Electron is started at boot. The first browse_* call that
-// fails to connect triggers `ensureRunning`, which spawns Electron on demand
-// (ensureElectronRunning is idempotent). `ensureElectronRunning` is a hoisted
-// function declaration, so referencing it here is safe.
+// fails to connect triggers `ensureRunning`, which starts Electron on demand.
+//
+// 2026-10-20: the launch logic moved to scripts/ensure_running.cjs so the CLI
+// (`ai-browser call` / `ai-browser ensure`) shares ONE implementation with this
+// server. Duplicating it here is what made "install and use" a two-step dance
+// for CLI callers: MCP auto-started the browser, the CLI did not.
 const wsClient = createWsClient({
   url: WS_URL,
   timeout: WS_TIMEOUT,
-  ensureRunning: ensureElectronRunning,
+  ensureRunning: () => ensureBrowser(),
 });
 
-// Probe whether the Electron WS server is already listening on the port.
-function checkPort(port) {
-  return new Promise((resolve) => {
-    const sock = net.connect({ port, host: '127.0.0.1' });
-    let done = false;
-    const finish = (ok) => { if (!done) { done = true; sock.destroy(); resolve(ok); } };
-    sock.once('connect', () => finish(true));
-    sock.once('error', () => finish(false));
-    setTimeout(() => finish(false), 500);
-  });
-}
-
-function waitForPort(port, timeoutMs) {
-  const start = Date.now();
-  return new Promise(async (resolve) => {
-    while (Date.now() - start < timeoutMs) {
-      if (await checkPort(port)) return resolve(true);
-      await new Promise(r => setTimeout(r, 500));
-    }
-    resolve(false);
+/** 拉起浏览器（幂等）。失败时抛带原因的 Error，由 mcp_ws 并进最终错误信息。 */
+async function ensureBrowser() {
+  const info = await ensureRunning({
+    port: ELECTRON_PORT,
+    log: (m) => console.error('[mcp] ' + m),
   });
-}
-
-// Spawn Electron detached so it survives this MCP subprocess.
-//
-// 两个坑都是实测踩出来的（2026-10-12）：
-//
-// ① `ELECTRON_RUN_AS_NODE` 必须删掉。本机 shell 就带着它，此时 `electron .` 会
-//    被当作普通 Node 运行，拿 Node 加载 ESM 入口直接崩，端口永不监听，而报错是
-//    一串 Node 的 ESM 栈 —— 完全不提 Electron。e2e 脚本都删了它，只有这里漏了。
-//    详见 scripts/start.cjs 顶部。
-//
-// ② 启动失败必须**说出来**。此前这里 return false，而 mcp_ws.js 又把它 catch 掉
-//    吞了，于是 agent 先重试 120 秒，最后只拿到 "WS reconnect timeout:
-//    connection refused" —— 没有任何线索表明浏览器根本没起来，更别说为什么。
-//    现在抛一个带原因的 Error，由 mcp_ws 并进最终错误信息。
-async function ensureElectronRunning() {
-  if (await checkPort(ELECTRON_PORT)) return true;
-  console.error('[mcp] port 9223 not listening — spawning the ai-browser Electron app');
-  // Spawn the electron binary directly (resolved from this package's
-  // dependencies), pointed at the app root. Do NOT shell out to `npm start`:
-  // npm is not guaranteed on PATH for MCP clients, and on Windows the
-  // executable is npm.cmd — direct spawn avoids both classes of failure.
-  // AI_BROWSER_LAUNCHED_BY_AGENT：告诉 Electron 它是被 agent 拉起来的，因此
-  // 窗口出现时**不要**抢焦点（showInactive）—— 否则 agent 第一次连上来就会把
-  // 用户正在做的事打断。人手动 `ai-browser` / `npm start` 时没有这个变量。
-  const childEnv = { ...process.env, AI_BROWSER_LAUNCHED_BY_AGENT: '1' };
-  delete childEnv.ELECTRON_RUN_AS_NODE;
-  let child;
-  try {
-    child = spawn(resolveElectronBinary(), [APP_ROOT], {
-      cwd: APP_ROOT,
-      detached: true,
-      stdio: 'ignore',
-      env: childEnv,
-    });
-  } catch (e) {
-    throw new Error(`could not start the browser: ${e.message}`);
-  }
-  child.unref();
-  // 子进程自己提前退出（例如上面那个 Node ESM 崩溃）时，等满 30 秒是纯浪费 ——
-  // 而且会掩盖真实原因。这里挂一个 exit 监听，把退出码留给下面的诊断。
-  let earlyExit = null;
-  child.on('exit', (code, signal) => { earlyExit = { code, signal }; });
-  // Give Electron up to 30s to start the WS server.
-  const ok = await waitForPort(ELECTRON_PORT, 30000);
-  if (!ok) {
-    const why = earlyExit
-      ? `Electron exited early (code=${earlyExit.code}, signal=${earlyExit.signal}) — a common cause is ELECTRON_RUN_AS_NODE being set in the environment, or the electron binary being missing (check node_modules/electron/dist)`
-      : 'Electron did not come up within 30s (slow first-run binary download? try ELECTRON_MIRROR for users behind a slow network)';
-    console.error('[mcp] ' + why);
-    throw new Error(`could not start the browser: ${why}`);
-  }
-  return true;
+  return info.running;
 }
 
 const server = new Server(

package/src/main/page_manager.js

@@ -81,6 +81,11 @@ const CANVAS_BRIDGE_KEY = '__aiCanvasBridge';
 // 请求头都拿不到）。关闭开关：AI_BROWSER_NETWORK_CAPTURE=0。
 const NETWORK_CAPTURE_DEFAULT = !(process.env.AI_BROWSER_NETWORK_CAPTURE === '0' || process.env.AI_BROWSER_NETWORK_CAPTURE === 'false');
 
+// window.open("") 派生 tab 的"等垫片再导航"上限。超过就照常导航（退化成
+// 该 tab 没有垫片），页面绝不能因为垫片安装慢而永久空白。
+// 实测正常路径约 120–300ms（about:blank 的 did-finish-load + 两次 CDP 命令）。
+const WINDOW_OPEN_NAV_WAIT_MS = 2000;
+
 // 具名按键 → CDP Input.dispatchKeyEvent 参数。agent 用自然名字（'Delete'、
 // 'Escape'、'ArrowRight'、'a'）而不是让人去查 Windows 虚拟键码。
 // vk 用 Windows 虚拟键码（Chromium 在 macOS 上也按它解释）。
@@ -174,6 +179,12 @@ class PageManager {
     this._openedTabs = new Map();   // sourceTabId -> { id, url } (new tab opened by window.open)
     this._windowOpenTokens = new Map(); // token -> { tabId, sourceTabId } (window.open shim, preload bridge.cjs)
     this._windowOpenShimTabs = new Set(); // 已注入 window.open 垫片的 tabId
+    // tabId -> Promise<void>：该 tab 的垫片**注册完成**的信号（不是"注入成功"，
+    // 失败也 resolve —— 调用方要的是"可以往下走了"，不是"一切顺利"）。
+    // 存在的唯一理由：window.open("") 派生的 tab 里，ai:window_open_nav 必须等
+    // 垫片登记完再导航，否则真实文档先到、垫片只对"下一次文档"生效，那个 tab
+    // 就成了没有垫片的窗中窗（见 newTab 末尾长注释）。
+    this._windowOpenShimReady = new Map();
     this._axDiffCache = new Map();  // tabId -> lite interactive snapshot (get_tree {mode:'diff'})
     this._repaintTimers = new Map();// tabId -> 正在排队/已调度的重绘（合并同一批导航事件）
     this._snapshots = new Map();    // snapshotId -> { tabId, js, value, at }（ui.snapshot 存基线）
@@ -328,16 +339,41 @@ class PageManager {
       const entry = this._windowOpenTokens.get(p.token);
       const url = typeof p.url === 'string' ? p.url : '';
       if (!entry || !url) return;
-      const view = this._getView(entry.tabId);
-      if (view) {
-        // 占位 tab（about:blank）→ 真实学习页。loadURL 的 rejection 由
-        // 页面自身处理（站点可能会立刻再导航一次），这里只防 unhandled。
+      const nav = () => {
+        const view = this._getView(entry.tabId);
+        if (!view) {
+          // tab 已被用户/Agent 关掉：赋值静默丢弃（真实浏览器里关掉的
+          // 窗口被赋 location 也是无人接收）。
+          console.warn('[window_open] nav target tab gone:', entry.tabId, url);
+          return;
+        }
+        // loadURL 的 rejection 由页面自身处理（站点可能会立刻再导航一次），
+        // 这里只防 unhandled。
         view.webContents.loadURL(url).catch(() => {});
-      } else {
-        // tab 已被用户/Agent 关掉：赋值静默丢弃（真实浏览器里关掉的
-        // 窗口被赋 location 也是无人接收）。
-        console.warn('[window_open] nav target tab gone:', entry.tabId, url);
-      }
+      };
+      // ⚠️ **必须等垫片登记完再导航**（2026-10-20 修，超星"进入学习"第二层）。
+      //
+      // 原来这里直接 loadURL。看上去时序够用（站点 ajax 往返几十毫秒，
+      // 而 about:blank 的 did-finish-load 通常更早），但那是**赌**：
+      // 只要 nav 抢在 did-finish-load 之前到达，真实文档就先把 renderer 占住，
+      // 随后 addScriptToEvaluateOnNewDocument 只对"下一次文档"生效 ——
+      // 新 tab 里 window.open 是原生实现，站点再走一次
+      // `window.open("") + w.location = url` 就得到 null，静默不跳转。
+      // 实测（2026-10-20）：列表页的"进入学习"能开，新 tab 的 shim 是 false。
+      const ready = this._windowOpenShimReady.get(entry.tabId);
+      if (!ready) { nav(); return; }   // 老路径/测试桩：没有信号就直接走
+      let timer = null;
+      const cap = new Promise((resolve) => {
+        timer = setTimeout(resolve, WINDOW_OPEN_NAV_WAIT_MS);
+        if (timer.unref) timer.unref();
+      });
+      Promise.race([ready, cap]).then(() => {
+        if (timer) clearTimeout(timer);
+        nav();
+      }, () => {
+        if (timer) clearTimeout(timer);
+        nav();
+      });
     });
 
     ipcMain.on('ai:window_open_close', (_event, payload) => {
@@ -3093,11 +3129,18 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
     const wc0 = view.webContents;
     const targetUrl = url || null;
     if (wc0 && !wc0.isDestroyed()) {
+      // 垫片就绪信号：先挂上去，再去加载 about:blank。顺序不能反 ——
+      // ai:window_open_nav 可能在这一行之后立刻到达（IPC 保序，但它不等我们）。
+      let signalReady = () => {};
+      const ready = new Promise((resolve) => { signalReady = resolve; });
+      this._windowOpenShimReady.set(tabId, ready);
       let proceeded = false;
       const proceed = () => {
         if (proceeded) return;
         proceeded = true;
         Promise.resolve(this._ensureWindowOpenShim(tabId, view)).finally(() => {
+          // 失败也放行：宁可这个 tab 没有垫片，也不能把它卡在 about:blank。
+          signalReady();
           if (targetUrl && wc0 && !wc0.isDestroyed()) {
             wc0.loadURL(targetUrl).catch(() => {});
           }
@@ -3338,6 +3381,7 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
       if (entry.tabId === tabId) this._windowOpenTokens.delete(token);
     }
     this._windowOpenShimTabs.delete(tabId);
+    this._windowOpenShimReady.delete(tabId);
     // Release per-tab network resources so a closed tab can never leak its
     // debugger attachment or cached request entries / stale monitors.
     this._cleanupTabResources(tabId);
@@ -3815,6 +3859,10 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
         );
         return true;
       } catch (e) {
+        // 失败时撤掉记账：留着就等于给这个 tab 判了"永久无垫片"。
+        // 撤掉后下一次 window.open 还有机会补上（CDP 偶发挂住是环境问题，
+        // 不是这个 tab 的固有属性）。
+        this._windowOpenShimTabs.delete(tabId);
         console.error('[window_open] shim inject failed:', tabId, e && e.message);
         return false;
       }

package/src/main/window_open_shim_source.js

@@ -49,7 +49,10 @@ export const WINDOW_OPEN_SHIM_SOURCE = `(function () {
   window.open = function (url, name, _features) {
     var target = (url === undefined || url === null) ? '' : String(url);
     var token = 'wo' + (++seq) + '_' + Date.now();
-    var ok = send('open', token, target, name || '');
+    // ⚠️ 相对地址必须在这里就解析成绝对。主进程拿到的 '/foo.html' 没有 base，
+    // loadURL 会直接报 ERR_INVALID_URL（表现为一个 file:// 错误页）。
+    // 实测 2026-10-20：window.open('/l2.html','_blank') 开出的是错误页。
+    var ok = send('open', token, target ? abs(target) : '', name || '');
     if (!ok) {
       // 没有桥：退回原生语义（deny → null），至少不像成功那样骗站点。
       return null;

package/src/main/ws_server.js

@@ -206,7 +206,19 @@ export function startWSServer(pageManager, port = config.wsPort, onQuit = null)
             break;
           }
           case 'ui.evaluate': {
-            const js = String(params.js ?? '');
+            // 参数名是 js；expr 是 MCP 层的叫法，作为别名保留 —— 文档里写错一次
+            // （2026-10-20 技能里写成 expr）就会得到 `{value: undefined}`，
+            // 看上去像"页面没东西"，实际是表达式根本没执行。别名 + 空表达式报错，
+            // 把"静默返回 undefined"这条路彻底堵掉。
+            const rawJs = params.js !== undefined ? params.js : params.expr;
+            const js = String(rawJs === undefined || rawJs === null ? '' : rawJs);
+            if (!js.trim()) {
+              send({
+                jsonrpc: '2.0', id,
+                error: { code: -32602, message: 'empty expression: pass {"js":"<expression>"} (alias: "expr")' },
+              });
+              break;
+            }
             // Guard rails (shared single source) — enforce length + reject
             // obvious Node-exfil patterns. The MCP layer applies the same guard;
             // a direct ws client bypasses MCP, so enforce the same contract here.

package/src/shared/version.js

@@ -2,4 +2,4 @@
 // Kept in JS (not imported from package.json) to avoid Node import-attribute
 // (JSON module) compatibility issues inside Electron. package.json "version"
 // is manually synced to this value; tests assert they match.
-export const VERSION = '2.0.0';
+export const VERSION = '2.1.1';