@glittering0717/ai-browser 1.2.1 → 1.3.0

package/src/shared/screenshot_opts.cjs

@@ -0,0 +1,130 @@
+// src/shared/screenshot_opts.cjs — ui.screenshot / browse_screenshot 参数规范化
+//
+// 为什么值得单独一个模块：截图是"把页面原样交给调用方"的动作，参数错了
+// （quality 传了字符串、clip 越界、fullPage 与 clip 同传）要么静默出坏图，
+// 要么让 CDP 报一句看不懂的错。这里在入口一次性把参数收敛成合法形状，
+// 坏参数当场给出可读错误，而不是拖到 CDP 那一层。
+
+'use strict';
+
+const FORMATS = ['png', 'jpeg', 'webp'];
+const DEFAULT_FORMAT = 'png';
+// 512KB base64 ≈ 684KB 原始字节。单次回执再大，WS 帧和模型上下文都吃不消。
+const MAX_DATA_URL_CHARS = 512 * 1024;
+
+/**
+ * 规范化截图参数。
+ * @param {object} opts 调用方传入（可能缺项/错型）
+ * @returns {{ok: true, opts: object} | {ok: false, error: string}}
+ */
+function normalizeScreenshotOpts(opts) {
+  const src = opts && typeof opts === 'object' ? opts : {};
+  const out = {};
+
+  // --- format ---
+  let format = DEFAULT_FORMAT;
+  if (src.format !== undefined && src.format !== null) {
+    if (typeof src.format !== 'string' || !FORMATS.includes(src.format)) {
+      return { ok: false, error: `format must be one of ${FORMATS.join('/')} (got ${JSON.stringify(src.format)})` };
+    }
+    format = src.format;
+  }
+  out.format = format;
+
+  // --- quality（仅 jpeg/webp 有意义；png 无损，传了忽略而不是报错）---
+  if (src.quality !== undefined && src.quality !== null) {
+    const q = Number(src.quality);
+    if (!Number.isFinite(q) || q < 0 || q > 100) {
+      return { ok: false, error: 'quality must be a number in 0..100' };
+    }
+    out.quality = Math.round(q);
+  } else if (format === 'jpeg') {
+    out.quality = 85; // 文字页面 85 肉眼无损，体积约为 png 的 1/5
+  }
+
+  // --- fullPage（captureBeyondViewport）---
+  // null 与 undefined 同样视为"未提供"：JSON 里显式传 null 表示"用默认值"，
+  // 不该和传错类型（'yes'/1）一样报错。
+  if (src.fullPage != null && typeof src.fullPage !== 'boolean') {
+    return { ok: false, error: 'fullPage must be a boolean' };
+  }
+  out.fullPage = src.fullPage === true;
+
+  // --- path（可选：把图直接落盘，省得调用方自己解 base64）---
+  // 此前传 path 会被**静默忽略**：调用方拿到 ok:true 以为文件写好了。
+  // 这是本项目反复踩的同一类坑（参数被吞 → 结论错），所以在规范层直接支持。
+  if (src.path !== undefined && src.path !== null && src.path !== '') {
+    if (typeof src.path !== 'string' || !src.path.trim()) {
+      return { ok: false, error: 'path must be a non-empty absolute file path' };
+    }
+    out.path = src.path;
+  }
+
+  // --- clip（设备像素坐标；不传则整视口）---
+  if (src.clip !== undefined && src.clip !== null) {
+    const c = src.clip;
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : NaN);
+    const clip = {
+      x: num(c.x),
+      y: num(c.y),
+      width: num(c.width),
+      height: num(c.height),
+      scale: c.scale === undefined ? 1 : num(c.scale),
+    };
+    if (['x', 'y', 'width', 'height'].some((k) => Number.isNaN(clip[k]))) {
+      return { ok: false, error: 'clip.x/y/width/height must all be numbers' };
+    }
+    if (!Number.isFinite(clip.scale) || clip.scale <= 0 || clip.scale > 4) {
+      return { ok: false, error: 'clip.scale must be a number in (0, 4]' };
+    }
+    if (clip.width <= 0 || clip.height <= 0) {
+      return { ok: false, error: 'clip.width/height must be positive' };
+    }
+    if (clip.x < 0 || clip.y < 0) {
+      return { ok: false, error: 'clip.x/y must be >= 0' };
+    }
+    // clip 与 captureBeyondViewport 同时传时，Chromium 的语义是"从 clip 顶部
+    // 开始一路拍到页面底部"——调用方九成不是这个意思，且极易拍出几十 MB 的图。
+    // 当场拦下，让调用方明确二选一。
+    if (out.fullPage) {
+      return { ok: false, error: 'fullPage and clip are mutually exclusive (captureBeyondViewport+clip means "clip top through page bottom" — pick one)' };
+    }
+    out.clip = clip;
+  }
+
+  return { ok: true, opts: out };
+}
+
+/**
+ * 回执摘要：调用方拿到图之后最想知道的几件事，省得它再发一轮查询。
+ * 敏感字段（密码框在场）单独标，因为 captureScreenshot 不会模糊它。
+ */
+function describeShot(meta) {
+  const m = meta && typeof meta === 'object' ? meta : {};
+  const out = {
+    format: m.format || 'png',
+    mime: m.mime || 'image/png',
+    bytes: typeof m.bytes === 'number' ? m.bytes : null,
+    width: typeof m.width === 'number' ? m.width : null,
+    height: typeof m.height === 'number' ? m.height : null,
+    truncated: false,
+  };
+  if (typeof m.url === 'string') out.url = m.url;
+  if (typeof m.title === 'string') out.title = m.title;
+  // CDP 的 clip/视口坐标是 CSS 像素，输出图是设备像素。带上 DPR，调用方才能
+  // 把图上的像素坐标换算回页面坐标（Retina 上差 2 倍）。
+  if (typeof m.devicePixelRatio === 'number' && m.devicePixelRatio > 0) {
+    out.device_pixel_ratio = m.devicePixelRatio;
+  }
+  if (m.hasVisiblePasswordInput === true) {
+    out.warning = 'page has a visible password input — the screenshot may contain typed secrets';
+  }
+  return out;
+}
+
+module.exports = {
+  FORMATS,
+  MAX_DATA_URL_CHARS,
+  normalizeScreenshotOpts,
+  describeShot,
+};

package/src/shared/tree_diff.cjs

@@ -0,0 +1,105 @@
+// 悬停前后两棵语义树的差异（ui.peek 的核心）。
+//
+// 数据源从 AX 换成 DOM 语义树，是实测逼出来的两个理由：
+//
+// 1. 自绘菜单在 AX 里是「无名的 generic」。实测（tools/_oneoff/peek 对照页）：
+//    一个 hover 后展开的纯 div 菜单，AX 报 7 个新节点，但两个菜单项都长这样 ——
+//      generic ""            ← 名字是空的，文字跑到子节点 StaticText 去了
+//      StaticText "普通选项一"
+//    而 AX 侧的"可交互"判据是 role 名单 / editable / focusable，generic 一条都不占
+//    → 被过滤掉 → peek 对这类菜单一律报空。DOM 读层有 isHumanClickable +
+//    floatingLayerOf + elementName，正好能认出它们（同一次实测：DOM 侧报出 2 项，
+//    都带 actions=["click"] 和坐标）。
+//
+// 2. 更致命：AX 的 id 形如 ax-{backendNodeId}，动作层解析不了（实测
+//    "Target not found for ref: ax-291"）。就算 AX 探到了，报出去的 id 也点不了。
+//    DOM 的 e:div-N 是 ui.act 直接可用的。
+//
+// 代价：DOM 抽取会写 data-ai-id 属性（get_tree 本来就在做，peek 此前也调
+// ensureHandles 打过标记），不再是"纯读"。换取的是报出来的东西真能点。
+
+// 拍平。保留根节点（它是 body 的映射，diff 时两边一致，会被自然抵消）。
+function flattenTree(root) {
+  var out = [];
+  (function walk(n) {
+    if (!n) return;
+    out.push(n);
+    var kids = n.children || [];
+    for (var i = 0; i < kids.length; i++) walk(kids[i]);
+  })(root);
+  return out;
+}
+
+// 输出给调用方的精简节点。带 actions 与 bounds，是为了让"探到了"直接等于"能点"。
+function toLite(n) {
+  var o = { id: n.id, role: n.role || 'generic', label: n.label == null ? '' : n.label };
+  if (n.actions && n.actions.length) o.actions = n.actions.slice();
+  if (n.bounds) o.bounds = n.bounds;
+  return o;
+}
+
+// 位置对得上就算同一个（菜单重开时会有 1~2px 的抖动）。
+function sameBounds(a, b) {
+  if (!a || !b) return false;
+  return Math.abs(a.x - b.x) <= 4 && Math.abs(a.y - b.y) <= 4
+    && Math.abs(a.width - b.width) <= 4 && Math.abs(a.height - b.height) <= 4;
+}
+
+// 菜单收起再展开时，DOM 节点是新造的，id 跟着变 —— 上一张快照报出去的 id 就点不动了
+// （实测 B站 头部「收藏」：revertMs=0 把鼠标移回目标后，原先报出的三个 id
+// e:div-208 / e:div-209 / e:a-229 全部消失）。想让"探到就能点"成立，必须把 id
+// 重新绑到新节点上。
+//
+// 认亲用 (role, label, bounds) 三元组：同一个菜单项重开后文本和位置不会变，
+// 而 id 会。三者全中才认，宁可对不上也不乱指 —— 对不上时保留原 id，调用方会拿到
+// target_not_found，这比悄悄点到别的东西上安全得多。
+function remapIds(liteNodes, nowNodes) {
+  var now = nowNodes || [];
+  return (liteNodes || []).map(function (n) {
+    var i;
+    for (i = 0; i < now.length; i++) if (now[i].id === n.id) return n; // 还在就别动
+    for (i = 0; i < now.length; i++) {
+      var c = now[i];
+      if (c.role === n.role && (c.label || '') === (n.label || '') && sameBounds(c.bounds, n.bounds)) {
+        // 只换 id，其余（actions / bounds）沿用原来那份 —— 重绑是为了让 id 活过来，
+        // 不是为了重算一次，顺手把已经报给调用方的信息弄丢反而更糟。
+        var o = {};
+        for (var k in n) if (Object.prototype.hasOwnProperty.call(n, k)) o[k] = n[k];
+        o.id = c.id;
+        return o;
+      }
+    }
+    return n;
+  });
+}
+
+// 可点的排前面：悬停探出来的东西里，菜单项永远比包裹它的容器有用。
+function actionableFirst(a, b) {
+  var ac = (a.actions && a.actions.length) ? 1 : 0;
+  var bc = (b.actions && b.actions.length) ? 1 : 0;
+  if (ac !== bc) return bc - ac;
+  return 0;
+}
+
+function diffTree(beforeNodes, afterNodes) {
+  var before = beforeNodes || [];
+  var after = afterNodes || [];
+  var bi = {}, ai = {}, i;
+  for (i = 0; i < before.length; i++) if (before[i] && before[i].id != null) bi[before[i].id] = before[i];
+  for (i = 0; i < after.length; i++) if (after[i] && after[i].id != null) ai[after[i].id] = after[i];
+  var revealed = [], hidden = [];
+  for (i = 0; i < after.length; i++) {
+    var n = after[i];
+    if (!n || n.id == null) continue;
+    if (!Object.prototype.hasOwnProperty.call(bi, n.id)) revealed.push(toLite(n));
+  }
+  for (i = 0; i < before.length; i++) {
+    var m = before[i];
+    if (!m || m.id == null) continue;
+    if (!Object.prototype.hasOwnProperty.call(ai, m.id)) hidden.push(toLite(m));
+  }
+  revealed.sort(actionableFirst);
+  return { revealed: revealed, hidden: hidden };
+}
+
+module.exports = { flattenTree, diffTree, toLite, remapIds, sameBounds };

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 = '1.2.1';
+export const VERSION = '1.3.0';

package/tools/coverage_probe.cjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+// tools/coverage_probe.cjs — 「页面上一半能点的东西，语义树里看不见」的量化探针。
+//
+// 为什么需要它（2026-10-17 实测）：
+//   在真实站点上量「用户看着能点」的元素有多少真的进了语义树，结果是
+//   百度 43%、B站 33%、CSDN 60%。也就是说**一半左右的可点目标 agent 拿不到 ref**，
+//   于是每次任务都退化成一个站点专用脚本去 querySelector 狙击 —— 26 个临时脚本里
+//   142 个是站点特化、731 处硬编码选择器，就是这么来的。
+//
+//   这个数字此前没人量过。没有它，"通用能力够不够"只能靠感觉争论；有了它，
+//   改进就能被验证：改完抽取层再跑一遍，覆盖率应该上去，而不是"感觉好点了"。
+//
+// 判据为什么用 cursor:pointer：
+//   它是**浏览器自己算出来的可点性** —— 人手看到手型光标就知道这儿能点，浏览器
+//   也是这么画的。用它当分母，比"猜哪些 div 挂了监听器"更接近"人看到的东西"。
+//
+// 用法：
+//   node tools/coverage_probe.cjs https://www.bilibili.com/
+//   node tools/coverage_probe.cjs https://www.csdn.net/ 12000 --json
+//
+// 需要 ai-browser 正在运行（默认 9223，AI_BROWSER_PORT 可改）。
+
+'use strict';
+
+const { WebSocket } = require('ws');
+
+const URL_ARG = process.argv[2];
+const WAIT = Number(process.argv[3]) || 9000;
+const AS_JSON = process.argv.indexOf('--json') >= 0;
+const PORT = Number(process.env.AI_BROWSER_PORT) || 9223;
+
+if (!URL_ARG) {
+  console.error('usage: node tools/coverage_probe.cjs <url> [waitMs] [--json]');
+  process.exit(2);
+}
+
+function makeClient(port) {
+  const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+  let id = 1;
+  const pending = new Map();
+  ws.on('message', (raw) => {
+    const m = JSON.parse(raw.toString());
+    if (m.id && pending.has(m.id)) {
+      const p = pending.get(m.id);
+      pending.delete(m.id);
+      m.error ? p.reject(new Error(m.error.message)) : p.resolve(m.result);
+    }
+  });
+  const call = (method, params = {}, timeout = 120000) => new Promise((resolve, reject) => {
+    const i = id++;
+    pending.set(i, { resolve, reject });
+    ws.send(JSON.stringify({ jsonrpc: '2.0', id: i, method, params }));
+    setTimeout(() => {
+      if (pending.has(i)) { pending.delete(i); reject(new Error('timeout ' + method)); }
+    }, timeout);
+  });
+  const ready = new Promise((res, rej) => { ws.on('open', res); ws.on('error', rej); });
+  return { ws, call, ready, close: () => { try { ws.close(); } catch {} } };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// 在页面里数：手型元素总数 / 其中带 data-ai-id 的（= 真的进了树）
+//
+// ⚠️ 分母必须先修正，否则整件事都是错的。
+//   cursor 是**可继承**的 CSS 属性：给一张卡片设了 cursor:pointer，卡片里所有
+//   div/span/svg/path 计算出来全是 pointer。按"元素"数分母，CSDN 的
+//   .layout-menu-item / _info / _icon / _name 会被算成 4 个目标，而人看着只有 1 个
+//   可点区块（点哪个位置效果都一样）。B站 nav 的 svg+path 同理。
+//   所以"能点的东西"的计量单位是**手型边界** = 自己的 cursor 是 pointer、
+//   而父元素的 cursor **不是** pointer 的那个最外层元素。
+//
+// 两个口径都输出：element 口径（和此前数据可比）+ boundary 口径（人的视角）。
+//
+// 分类（两个口径各自算一遍）：
+//   inTree      自己带 id  → 直接可操作（真覆盖）
+//   byDesc      自己被单个交互后代盖满，而那个后代在树里
+//               （<div class=x><a>首页</a></div> 这种壳子，点里面的 a 就是点它）
+//   ancOnly     最近带 id 的祖先下只有它这一个手型后代 → 点祖先等价于点它
+//   ambiguous   同一祖先下有多个手型后代 → 点祖先指不到唯一目标
+//   noIdChain   自己和整条祖先链都没有 id → **真缺口**
+// 真缺口 = ambiguous + noIdChain。
+const COUNT_JS = `(function(){
+  var INTER = 'a[href],button,input,select,textarea,summary,details,[role=button],[role=link],[role=checkbox],[role=radio],[role=tab],[role=menuitem],[contenteditable=true]';
+  function coveredByDesc(el, r){
+    var hits;
+    try { hits = el.querySelectorAll(INTER); } catch(e) { return false; }
+    if (!hits || hits.length !== 1) return false;
+    var inner = hits[0];
+    if (!inner.hasAttribute('data-ai-id')) return false;
+    var b = inner.getBoundingClientRect();
+    if (!(b.width > 0) || !(b.height > 0)) return false;
+    var w = Math.min(r.right, b.right) - Math.max(r.left, b.left);
+    var h = Math.min(r.bottom, b.bottom) - Math.max(r.top, b.top);
+    if (!(w > 0) || !(h > 0)) return false;
+    var inter = w * h;
+    // 与 src/preload/extractor.cjs 的 wrapsSingleInteractive 同一判据：
+    // 内层要「盖满」外层，两个方向都 >= 90%。只看交集/内层面积会把
+    // "大卡片里放个小链接"误判成壳子（点卡片 ≠ 点那个链接）。
+    return inter / (b.width * b.height) >= 0.9 && inter / (r.width * r.height) >= 0.9;
+  }
+  function scan(onlyBoundary){
+    var s = {pointer: 0, inTree: 0, byDesc: 0, ancOnly: 0, ambiguous: 0, noIdChain: 0, missing: []};
+    var all = document.querySelectorAll('*');
+    var list = [];
+    for (var i = 0; i < all.length; i++) {
+      var el = all[i];
+      var r = el.getBoundingClientRect();
+      if (r.width < 4 || r.height < 4) continue;          // 不可见/装饰性小块
+      var cs = getComputedStyle(el);
+      if (cs.visibility === 'hidden' || cs.display === 'none' || cs.opacity === '0') continue;
+      if (cs.cursor !== 'pointer') continue;
+      if (onlyBoundary) {
+        var p = el.parentElement;
+        // 父元素也是 pointer → 它是继承来的，不是独立的可点目标
+        if (p && getComputedStyle(p).cursor === 'pointer') continue;
+      }
+      s.pointer++;
+      if (el.hasAttribute('data-ai-id')) { s.inTree++; continue; }
+      if (coveredByDesc(el, r)) { s.byDesc++; continue; }
+      var anc = el.parentElement, anchor = null;
+      while (anc && anc !== document.body) {
+        if (anc.hasAttribute('data-ai-id')) { anchor = anc; break; }
+        anc = anc.parentElement;
+      }
+      list.push({ el: el, anchor: anchor });
+    }
+    var perAnchor = new Map();
+    for (var j = 0; j < list.length; j++) {
+      if (!list[j].anchor) continue;
+      perAnchor.set(list[j].anchor, (perAnchor.get(list[j].anchor) || 0) + 1);
+    }
+    for (var k = 0; k < list.length; k++) {
+      var it = list[k], el = it.el, kind;
+      if (!it.anchor) { s.noIdChain++; kind = 'noIdChain'; }
+      else if (perAnchor.get(it.anchor) === 1) { s.ancOnly++; kind = 'ancOnly'; }
+      else { s.ambiguous++; kind = 'ambiguous'; }
+      if (s.missing.length < 40 && kind !== 'ancOnly') {
+        s.missing.push({
+          tag: el.tagName.toLowerCase(),
+          cls: String(el.className || '').slice(0, 44),
+          text: (el.innerText || '').replace(/\\s+/g, ' ').trim().slice(0, 28),
+          // onclick 属性 vs addEventListener：后者是 Vue/React 的默认写法，
+          // 而抽取层只看得到前者
+          reg: el.onclick === null ? 'listener' : 'attr',
+          kind: kind,
+        });
+      }
+    }
+    return s;
+  }
+  var byEl = scan(false);
+  var byBound = scan(true);
+  return JSON.stringify({ el: byEl, boundary: byBound });
+})()`;
+
+(async () => {
+  const c = makeClient(PORT);
+  await c.ready;
+
+  const nt = await c.call('ui.new_tab', { url: URL_ARG });
+  const TAB = nt && nt.tab;
+  await sleep(WAIT);
+
+  const info = await c.call('ui.evaluate', {
+    tab: TAB,
+    js: 'JSON.stringify({url:location.href,title:document.title})',
+  }).then((r) => JSON.parse(String(r.value))).catch(() => ({ url: URL_ARG, title: '' }));
+
+  // 先读树：抽取过程才会给命中的元素打上 data-ai-id
+  const raw = await c.call('ui.get_tree', { tab: TAB });
+  const root = raw.tree || raw.root || raw;
+  let nodes = 0;
+  (function walk(n) {
+    if (!n) return;
+    nodes++;
+    (n.children || []).forEach(walk);
+  })(root);
+
+  const r = await c.call('ui.evaluate', { tab: TAB, js: COUNT_JS }, 60000);
+  const raw2 = JSON.parse(String(r.value));
+  const d = raw2.boundary;      // 人的视角：手型边界
+  const e = raw2.el;            // 元素视角：和此前数据可比，但分母被继承放大了
+  const pct = (n, tot) => (tot ? Math.round((n / tot) * 100) : null);
+
+  const report = {
+    url: info.url,
+    title: info.title,
+    tree_nodes: nodes,
+    // 主要口径：手型边界
+    click_targets: d.pointer,
+    in_tree: d.inTree,
+    covered_by_descendant: d.byDesc,
+    covered_by_ancestor_only: d.ancOnly,
+    ambiguous_ancestor: d.ambiguous,
+    no_id_chain: d.noIdChain,
+    coverage_pct: pct(d.inTree, d.pointer),
+    usable_pct: pct(d.inTree + d.byDesc + d.ancOnly, d.pointer),
+    blind: d.ambiguous + d.noIdChain,
+    // 次要口径：所有 cursor:pointer 元素（含继承），仅供与历史数据对比
+    legacy: {
+      pointer_elements: e.pointer,
+      in_tree: e.inTree,
+      coverage_pct: pct(e.inTree, e.pointer),
+    },
+    missing: d.missing,
+  };
+
+  if (AS_JSON) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log('页面:', report.url);
+    console.log('树节点数:', nodes);
+    console.log('可点目标（手型边界）:', d.pointer);
+    console.log('  ├ 自己带 data-ai-id（直接可操作）:', d.inTree, '→ ' + (report.coverage_pct ?? 'n/a') + '%');
+    console.log('  ├ 被单个交互后代盖满且它在树里（壳子，点内层等价）:', d.byDesc);
+    console.log('  ├ 仅祖先可定位（点祖先等价于它，且祖先下只有它一个）:', d.ancOnly);
+    console.log('  ├ 祖先歧义（同一祖先下多个手型后代，点祖先指不准）:', d.ambiguous);
+    console.log('  └ 整条祖先链无 id（真看不见）:', d.noIdChain);
+    console.log('可用率（in_tree + by_desc + anc_only）:', report.usable_pct ?? 'n/a', '%', '| 真缺口:', report.blind);
+    console.log('（历史口径 cursor:pointer 元素数 ' + e.pointer + '，覆盖 ' + (report.legacy.coverage_pct ?? 'n/a') + '%）');
+    if (d.missing.length) {
+      console.log('\n没进树的可点目标（ancOnly 已排除，前 40 个）:');
+      console.log('  ' + 'tag'.padEnd(7) + 'class'.padEnd(46) + 'text'.padEnd(30) + 'kind');
+      for (const m of d.missing) {
+        console.log('  ' + m.tag.padEnd(7)
+          + ('[' + m.cls + ']').padEnd(46)
+          + JSON.stringify(m.text).padEnd(30)
+          + m.kind + (m.reg === 'attr' ? ' attr' : ''));
+      }
+    }
+  }
+
+  c.close();
+  process.exit(report.usable_pct !== null && report.usable_pct < 80 ? 1 : 0);
+})().catch((e) => {
+  console.error('coverage_probe error:', e && e.message);
+  process.exit(2);
+});