@glittering0717/ai-browser 1.3.1 → 2.1.0

package/scripts/cli_call.cjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+// scripts/cli_call.cjs — 命令行直接调浏览器，**不用写任何客户端脚本**。
+//
+// 为什么要有这个（真实抱怨，2026-10-19）：
+//   「我看操作这个项目，经常需要写 cjs 代码，这是必须的吗？」
+//   不是必须的，但以前确实没有别的办法：对外只有两个入口 —— MCP stdio（给 agent
+//   客户端用）和裸 WebSocket JSON-RPC（ws://127.0.0.1:9223）。想从 shell 里问一句
+//   "现在有哪些标签页"，就得先 npm i ws、再写一个连上发 JSON 的小脚本、再等回包。
+//   一个本来只是一行命令的事情，被迫变成"写代码"。
+//
+// 所以这里补的是**通道**，不是新能力：它做的就是把一条 JSON-RPC 发出去、把 result
+// 打出来。所有能力仍然只有一套实现（page_manager），MCP 和 CLI 都是它的薄壳。
+//
+// 用法：
+//   ai-browser call ui.list_tabs
+//   ai-browser call ui.get_tree '{"subset":"interactive"}'
+//   ai-browser call ui.navigate '{"url":"https://example.com"}'
+//   echo '{"url":"https://example.com"}' | ai-browser call ui.navigate -
+//   ai-browser call ui.act '{"action":"click","target":"e:a-1"}'
+//   ai-browser status
+//
+// 选项：
+//   --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, 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)) {
+    // 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;
+  return out;
+}
+
+/** 把命令行里的 JSON 载荷解析成对象；空/缺省 → {}。 */
+function parsePayload(text) {
+  if (text === undefined) return {};
+  const t = String(text).trim();
+  if (!t) return {};
+  let val;
+  try {
+    val = JSON.parse(t);
+  } catch (e) {
+    const err = new Error(`payload is not valid JSON: ${e.message}\n  got: ${t.slice(0, 120)}`);
+    err.code = 'bad_json';
+    throw err;
+  }
+  if (val === null || typeof val !== 'object' || Array.isArray(val)) {
+    const err = new Error('payload must be a JSON object, e.g. {"url":"https://example.com"}');
+    err.code = 'bad_json';
+    throw err;
+  }
+  return val;
+}
+
+/**
+ * 发一条 JSON-RPC 并等回包。**不在这里做重试/重连** —— CLI 是同步语义：
+ * 一条命令一个结果，失败就把原因原样报出来，别替调用方猜。
+ */
+function rpcCall({ port, timeout, method, params }) {
+  // require 放在函数里：只有真的要连的时候才需要 ws（--help 之类不该加载它）。
+  const WebSocket = require('ws');
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const done = (fn, arg) => { if (!settled) { settled = true; try { ws.close(); } catch (_) {} fn(arg); } };
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    const timer = setTimeout(() => {
+      done(reject, Object.assign(new Error(`no reply from ${method} within ${timeout}ms`), { code: 'timeout' }));
+    }, timeout);
+
+    ws.on('open', () => {
+      ws.send(JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }));
+    });
+    ws.on('message', (data) => {
+      let msg;
+      try { msg = JSON.parse(String(data)); } catch (_) { return; }  // 事件广播不是回包，忽略
+      if (msg.id !== 1) return;
+      clearTimeout(timer);
+      if (msg.error) {
+        // 带上方法名：服务端只会说 "Method not found"，不带名字的话调用方还得自己
+        // 回想刚才打的是哪个（一条命令里可能有变量拼出来的方法名）。
+        const why = msg.error.message || 'rpc error';
+        done(reject, Object.assign(new Error(`${why} (${method})`), { code: 'rpc_error', rpc: msg.error }));
+      } else {
+        done(resolve, msg.result);
+      }
+    });
+    ws.on('error', (e) => {
+      clearTimeout(timer);
+      const hint = /ECONNREFUSED/i.test(e.message)
+        ? `浏览器没在 127.0.0.1:${port} 上跑。\`ai-browser ensure\` 会拉起它，\`ai-browser start\` 是前台启动。`
+        : e.message;
+      done(reject, Object.assign(new Error(hint), { code: 'connect_failed' }));
+    });
+  });
+}
+
+function printResult(result, pretty) {
+  if (result === undefined) { process.stdout.write('null\n'); return; }
+  const text = pretty ? JSON.stringify(result, null, 2) : JSON.stringify(result);
+  process.stdout.write(text + '\n');
+}
+
+async function runCall(argv) {
+  const opt = parseArgs(argv);
+  const method = opt.rest[0];
+  if (!method) {
+    process.stderr.write('usage: ai-browser call <method> [json|-] [--port n] [--timeout ms] [--pretty]\n'
+      + '  e.g. ai-browser call ui.list_tabs\n'
+      + '       ai-browser call ui.get_tree \'{"subset":"interactive"}\'\n');
+    return 2;
+  }
+  let params;
+  try {
+    const raw = opt.rest[1] === '-' ? readStdin() : opt.rest[1];
+    params = parsePayload(raw);
+  } catch (e) {
+    process.stderr.write(`[ai-browser] ${e.message}\n`);
+    return 2;
+  }
+  try {
+    const result = await rpcCall({ port: opt.port, timeout: opt.timeout, method, params });
+    printResult(result, opt.pretty);
+    return 0;
+  } catch (e) {
+    // 连不上 → 默认把浏览器拉起来再试一次（见文件头"关于自动拉起"）。
+    // 只在 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;
+  }
+}
+
+async function runStatus(argv) {
+  const opt = parseArgs(argv);
+  try {
+    const info = await rpcCall({ port: opt.port, timeout: Math.min(opt.timeout, 5000), method: 'ui.server_info', params: {} });
+    let tabs = null;
+    try { tabs = await rpcCall({ port: opt.port, timeout: Math.min(opt.timeout, 5000), method: 'ui.list_tabs', params: {} }); } catch (_) {}
+    const out = {
+      running: true,
+      port: opt.port,
+      pid: info && info.pid,
+      started_at: info && info.started_at,
+      platform: info && info.platform,
+      tabs: tabs && tabs.tabs ? tabs.tabs.map((t) => ({ id: t.id, active: t.active, title: t.title, url: t.url })) : null,
+    };
+    printResult(out, opt.pretty);
+    return 0;
+  } catch (e) {
+    // 没跑**不是错误状态**：这是用户最常问的第一个问题，答案要清楚、可执行。
+    printResult({ running: false, port: opt.port, reason: e.message }, opt.pretty);
+    return 1;
+  }
+}
+
+// stdin 读成字符串（供 `... | ai-browser call ui.navigate -` 用）
+function readStdin() {
+  try {
+    return require('node:fs').readFileSync(0, 'utf8');
+  } catch (_) {
+    return '';
+  }
+}
+
+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/scripts/skill.cjs

@@ -0,0 +1,133 @@
+// scripts/skill.cjs — 把随包分发的 skills/ 装进 agent 客户端的技能目录
+//
+// 为什么需要它：技能只有被客户端**发现并自动加载**才有价值。放在 npm 包里
+// 不等于装上了——用户的 ~/.claude/skills 或 ~/.workbuddy/skills 里没有文件，
+// agent 每次开新会话就只能靠人贴说明书（这就是"每次都要重新学"的真相）。
+//
+// 设计取舍：
+//  - 只写自己管理的目录，靠 .ai-browser-skill 标记文件区分"我装的"和"用户自己写的"。
+//    没有标记就跳过并提示，绝不覆盖用户手改的技能。
+//  - 不猜路径：每个客户端一个明确常量，装不装得上让用户看见。
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const pkg = require('../package.json');
+
+const SKILLS_ROOT = path.join(__dirname, '..', 'skills');
+const MARKER = '.ai-browser-skill';
+
+// 已知客户端的技能目录。宁可只列确定正确的几个，也不猜。
+const TARGETS = [
+  { id: 'workbuddy', label: 'WorkBuddy', dir: path.join(os.homedir(), '.workbuddy', 'skills') },
+  { id: 'claude', label: 'Claude Code', dir: path.join(os.homedir(), '.claude', 'skills') },
+  { id: 'codex', label: 'Codex', dir: path.join(os.homedir(), '.codex', 'skills') },
+];
+
+function listSkills() {
+  if (!fs.existsSync(SKILLS_ROOT)) return [];
+  return fs
+    .readdirSync(SKILLS_ROOT, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && fs.existsSync(path.join(SKILLS_ROOT, d.name, 'SKILL.md')))
+    .map((d) => d.name);
+}
+
+function detectTargets() {
+  return TARGETS.map((t) => ({
+    ...t,
+    exists: fs.existsSync(t.dir),
+    installed: listSkills().filter((s) => fs.existsSync(path.join(t.dir, s, MARKER))),
+  }));
+}
+
+function installOne(skill, targetDir) {
+  const src = path.join(SKILLS_ROOT, skill);
+  const dest = path.join(targetDir, skill);
+  const marker = path.join(dest, MARKER);
+
+  if (fs.existsSync(dest) && !fs.existsSync(marker)) {
+    return { skill, status: 'skipped-user-owned' };
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+  fs.cpSync(src, dest, { recursive: true });
+  fs.writeFileSync(marker, `ai-browser ${pkg.version}\n`, 'utf8');
+  return { skill, status: 'installed' };
+}
+
+function install({ dir, all }) {
+  const skills = listSkills();
+  if (!skills.length) {
+    console.error('[skill] 包里没有 skills/ 目录，这个构建是坏的');
+    return 1;
+  }
+
+  let dirs;
+  if (dir) {
+    dirs = [{ id: 'custom', label: dir, dir: path.resolve(dir), exists: true }];
+  } else {
+    dirs = detectTargets().filter((t) => all || t.exists);
+    if (!dirs.length) {
+      console.error('[skill] 没找到任何已知客户端的技能目录。用 --dir <path> 指定，或加 --all 强行创建。');
+      console.error('        已知位置：' + TARGETS.map((t) => `${t.label} → ${t.dir}`).join('；'));
+      return 1;
+    }
+  }
+
+  let failed = 0;
+  for (const t of dirs) {
+    console.log(`\n→ ${t.label} (${t.dir})`);
+    for (const s of skills) {
+      const r = installOne(s, t.dir);
+      const note =
+        r.status === 'installed'
+          ? `✓ ${s}`
+          : `! ${s} —— 这个目录已有同名技能且不是本工具装的，跳过（要覆盖请先手动删掉）`;
+      console.log('  ' + note);
+    }
+  }
+  console.log(`\n装了 ${skills.length} 个技能。新开会话时客户端会自动发现它们，不需要再贴说明书。`);
+  return failed;
+}
+
+function printEntry() {
+  const entry = path.join(SKILLS_ROOT, 'ai-browser', 'SKILL.md');
+  if (!fs.existsSync(entry)) {
+    console.error('[skill] 找不到 skills/ai-browser/SKILL.md');
+    return 1;
+  }
+  process.stdout.write(fs.readFileSync(entry, 'utf8'));
+  return 0;
+}
+
+function run(argv) {
+  const sub = argv[0] || 'list';
+
+  if (sub === 'list') {
+    const skills = listSkills();
+    console.log(`ai-browser ${pkg.version} 附带 ${skills.length} 个技能：${skills.join(', ')}\n`);
+    const rows = detectTargets();
+    for (const t of rows) {
+      const state = !t.exists ? '目录不存在' : t.installed.length ? `已装 ${t.installed.length} 个` : '未装';
+      console.log(`  ${t.label.padEnd(12)} ${state.padEnd(12)} ${t.dir}`);
+    }
+    console.log('\n装上：ai-browser skill install        只装到已存在的客户端目录');
+    console.log('      ai-browser skill install --all  三个位置都装');
+    console.log('      ai-browser skill print          打印入口 SKILL.md（手动粘贴用）');
+    return 0;
+  }
+
+  if (sub === 'install') {
+    const dirIdx = argv.indexOf('--dir');
+    return install({ dir: dirIdx >= 0 ? argv[dirIdx + 1] : null, all: argv.includes('--all') });
+  }
+
+  if (sub === 'print') return printEntry();
+
+  console.error(`[skill] 未知子命令: ${sub}\n用法: ai-browser skill [list|install|print] [--dir <path>] [--all]`);
+  return 2;
+}
+
+module.exports = { run, listSkills, detectTargets, SKILLS_ROOT };

package/skills/ai-browser/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: ai-browser
+description: >-
+  Control a real, visible browser to do things on websites: open a page, click, type, fill a form, log in, read page content, download/upload, inspect network requests. Use whenever the user asks to operate a website (打开网页/点一下/填表/登录/发布/提交/抓取/截图/看接口) or to read a page that needs JS to render.
+  触发词：打开、点击、填表、输入、登录、扫码、发布、提交、下载、上传、抓取、爬取、截图、看接口、网页操作、browse。
+---
+
+# ai-browser
+
+## 两条路，选一条就能干活
+
+工具在就 `browse_navigate {"url":"https://example.com"}`；**不在也不用配任何东西**，走 CLI（同一引擎，装完即用）：
+
+```
+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"}'
+```
+
+没这个命令就加前缀 `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
+
+`committed` 已生效 → 继续｜`none` 页面没动 → 换 target 或重读树｜
+`unknown` 说不准 → **先重读树再决定**，盲目重试会提交两次。
+
+## 卡住时
+
+| 现象 | 先做什么 |
+|---|---|
+| 树里没有要点的东西 | 等 `{"condition":"text_contains","text":"关键词"}` 再重读 |
+| `target_not_found` + `stale_ref` | 页面变了 → 重读树拿新 id |
+| `target_not_found` + `never_seen` | id 本身错 → 别重读，改参数 |
+| 点了没反应 | `screenshot` 看画面；`network_list` 看请求 |
+| 怀疑掉登录 | `auth_state` |
+| 以上都不对 | `errors` |
+
+## 需要人帮忙
+
+登录/扫码/滑块/支付：**请用户在自己的窗口里操作**，他说"好了"再重读树确认。不要编造密码。
+
+## 按需深挖
+
+- `references/cli.md` — CLI 全部方法与参数对照
+- `references/troubleshooting.md` — 失败排查顺序
+- `references/hard-pages.md` — canvas / 富文本 / iframe / 上传
+- `references/network.md` — 抓请求、取结构化数据
+- `references/tasks.md` — 发布文章 / 读正文 的配方