@glittering0717/ai-browser 1.3.0 → 2.0.0

package/src/shared/frame_read_source.js

@@ -0,0 +1,260 @@
+// src/shared/frame_read_source.js — 跨进程子帧（OOPIF）内容读取器
+//
+// 这段代码**在子帧自己的 JS 上下文里执行**（frame.executeJavaScript），所以它
+// 不能引用模块作用域的任何东西；也因此本文件用「真实函数 + toString」的形式
+// 产出源码，而不是拼字符串 —— 拼字符串时正则里的 \s 会被模板串吃掉一层，
+// 这类错误只有在页面里跑起来才暴露。
+//
+// ================== 为什么要有这个文件 ==================
+// 原来 _readOopifFrames 里内联的选择器是：
+//   [contenteditable],[role=textbox],[role=combobox],textarea,
+//   input[type=text],input[type=title],input[type=search],button,
+//   [role=button],a[href]
+// 它是一份**表单控件读取器**，为「B站图文编辑器住在 OOPIF 里」那一次事故写的。
+// 于是：
+//   1. `a[href]` 漏掉一切 JS 驱动的链接。超星泛雅的章节条目就是
+//      `<a onclick=...>` 且 href 为 null —— 实测该帧里 a 有 8 个、a[href] 只有 2 个，
+//      章节列表整整 6 条一个都进不了树。
+//   2. 纯文本/列表/表格结构完全没有采集通路。就算把锚点补齐，一个「没有可点
+//      元素」的 frame（正文、成绩表）依然是空树 —— 而 frame_hints 还会说
+//      "merged"，因为合并确实发生了（合并进去一个搜索框）。
+//
+// 现在改成一次合并查询、按文档序产出两类节点：
+//   - 可交互（链接/按钮/输入/富文本/ARIA 控件）→ 带 actions，可被 ui.act
+//   - 内容块（标题/列表项/段落/表格单元）→ 只读，用来让 agent **读懂**内容
+// 并额外回报覆盖率（帧里可见文本多少字、其中多少字进了树），让"读到了"
+// 变成可测量的结论而不是一句自我声明。
+
+/**
+ * 子帧内容读取器（页面内执行）。
+ * @param {string} prefix 本帧的 ref 前缀，形如 "axf-2-"
+ * @returns {{url:string,title:string,nodes:Array,stats:object}|null}
+ */
+function frameRead(prefix) {
+  if (typeof document === 'undefined' || !document || !document.body) return null;
+
+  // 上限是**给调用方省 token**，不是给采集省事：一帧正文能匹配上千个元素，
+  // 全塞进树里既贵又没用。覆盖率字段会如实告诉调用方"剩下的没进来"。
+  var MAX_SCAN = 1200;   // 参与判定的候选元素上限（文档序）
+  var MAX_NODES = 200;   // 最终产出节点上限
+  var LABEL_CAP = 120;   // 单个 label 字符上限
+
+  var SEL = [
+    // 可编辑 / 表单
+    '[contenteditable]', 'textarea', 'select', 'input:not([type=hidden])',
+    '[role=textbox]', '[role=combobox]', '[role=listbox]',
+    // 可点
+    'button', 'a', '[role=button]', '[role=link]', '[role=tab]',
+    '[role=menuitem]', '[role=option]', '[role=treeitem]',
+    '[role=checkbox]', '[role=switch]',
+    // 内容块
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6', '[role=heading]',
+    'li', '[role=listitem]', 'p', 'dt', 'dd', 'blockquote', 'pre',
+    'td', 'th', '[role=cell]', '[role=article]'
+  ].join(',');
+
+  function norm(s) {
+    return String(s == null ? '' : s).replace(/[\s\u00a0]+/g, ' ').trim();
+  }
+  function clip(s) {
+    return s.length > LABEL_CAP ? s.slice(0, LABEL_CAP - 1) + '\u2026' : s;
+  }
+  // 字数只数**非空白字符**。分母（innerText）和分子（label 累计）必须用同一把
+  // 尺子，否则中文页面的覆盖率会因为空格/换行/缩进横向失真：
+  // 一个 40 行、每行 3 个字的表格，按字符数算分母会虚高 2~3 倍。
+  // 主文档侧的 doc_coverage.js 用的是同一条规则，改一处必须改另一处。
+  function countChars(s) {
+    if (!s) return 0;
+    var m = String(s).match(/[^\s\u00a0]/g);
+    return m ? m.length : 0;
+  }
+
+  var els;
+  try { els = Array.prototype.slice.call(document.querySelectorAll(SEL)); }
+  catch (e) { return null; }
+  if (els.length > MAX_SCAN) els = els.slice(0, MAX_SCAN);
+
+  // 这一帧**看得见的文字**总量（覆盖率的分母）。提前算，因为"一个候选都没有
+  // 但正文有字"这种帧要单独对待：它往往意味着内容在更深一层的 iframe 里。
+  var bodyText = norm(document.body.innerText || '');
+  // 完全空白的帧返回 null（上层据此跳过，不往树里塞空壳）。
+  if (!els.length && !bodyText) return null;
+
+  // 第一趟：分类 + 过滤不可见。
+  var picked = [];
+  for (var k = 0; k < els.length; k++) {
+    var e = els[k];
+    var tag = String(e.tagName || '').toUpperCase();
+    var aria = (e.getAttribute && e.getAttribute('role')) || '';
+    var r;
+    try { r = e.getBoundingClientRect(); } catch (e2) { continue; }
+    // 不可见（display:none / 折叠 / 零尺寸）不进树 —— 这是唯一一条"存在但不算"的规则。
+    if (!r || r.width < 4 || r.height < 4) continue;
+
+    var editable = e.isContentEditable === true || tag === 'TEXTAREA' || tag === 'INPUT'
+      || tag === 'SELECT' || aria === 'textbox' || aria === 'combobox' || aria === 'listbox';
+    var clickable = tag === 'BUTTON' || tag === 'A'
+      || aria === 'button' || aria === 'link' || aria === 'tab' || aria === 'menuitem'
+      || aria === 'option' || aria === 'treeitem' || aria === 'checkbox' || aria === 'switch';
+
+    if (editable || clickable) {
+      var label = norm(e.getAttribute && (
+        e.getAttribute('aria-label') || e.getAttribute('placeholder') ||
+        e.getAttribute('title') || e.getAttribute('data-placeholder')));
+      if (!label && (tag === 'BUTTON' || tag === 'A' || clickable)) {
+        label = norm(e.innerText || e.textContent || '');
+      }
+      if (!label && tag === 'INPUT') label = norm(e.value || '');
+      var role;
+      if (tag === 'A' || aria === 'link') role = 'link';
+      else if (tag === 'BUTTON' || aria === 'button') role = 'button';
+      else if (tag === 'SELECT' || aria === 'combobox' || aria === 'listbox') role = 'select';
+      else if (aria === 'checkbox' || aria === 'switch') role = 'checkbox';
+      else if (aria === 'tab' || aria === 'menuitem' || aria === 'option' || aria === 'treeitem') role = 'button';
+      else role = 'textbox';
+      var editor_type = null;
+      if (e.isContentEditable) editor_type = 'richtext';
+      else if (tag === 'TEXTAREA') editor_type = 'textarea';
+      else if (tag === 'INPUT') editor_type = 'textbox';
+      var url = '';
+      // `href="javascript:void(0)"` 不是地址，是"点我"的另一种写法。照搬进树里
+      // 会让调用方以为可以拿它去 navigate（然后失败），也会让它以为这个链接有
+      // 真实目标。丢掉它，节点仍然是 link + click。
+      if (tag === 'A' && e.href && !/^\s*javascript:/i.test(String(e.href))) url = String(e.href);
+      picked.push({
+        el: e, interactive: true, role: role, label: clip(label), editor_type: editor_type, url: url,
+        bounds: { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height) }
+      });
+      continue;
+    }
+
+    // 内容块：用 innerText（含后代文字）。**不能用"只取直接文本"**：超星的
+    // "已完成任务点: <span>0</span>/4" 是 <h3> 里套 span，只取直接文本会得到
+    // "已完成任务点: /4" —— 数字丢了，而这正是这一行唯一有用的信息。
+    // 祖先重复的问题不靠这里解决，靠下面第二趟"祖先让位给后代"。
+    var t = norm(e.innerText || e.textContent || '');
+    if (!t) continue;
+    var crole = 'text';
+    if (tag === 'H1' || tag === 'H2' || tag === 'H3' || tag === 'H4' || tag === 'H5' || tag === 'H6' || aria === 'heading') crole = 'heading';
+    else if (tag === 'LI' || aria === 'listitem') crole = 'listitem';
+    else if (tag === 'TD' || tag === 'TH' || aria === 'cell') crole = 'cell';
+    picked.push({
+      el: e, interactive: false, role: crole, label: clip(t),
+      bounds: { x: Math.round(r.x), y: Math.round(r.y), width: Math.round(r.width), height: Math.round(r.height) }
+    });
+  }
+
+  // 第二趟：祖先让位给后代 —— 谁更具体谁留下。
+  //
+  // 实测（超星泛雅章节行）：一行是
+  //   <div role="link" tabindex="0" class="catalog_title">1.1 标题 <b>1</b></div>
+  //     └─ <a class="clicktitle">1.1 标题</a>
+  // 两个都能点、文字几乎一样。全留下 = 6 个章节变成 12 个节点，全是噪声。
+  //
+  // 规则按"谁更可能是真正的动作目标"来分：
+  //   可交互 ← 可交互：留**里面那个**（里面的是 a/button，是最精确的目标；
+  //                  外面那层通常是整行包装，点里面那层照样冒泡上去）
+  //   内容块 ← 任何后代：留后代（后代的文字更具体，祖先只是把它们拼在一起）
+  //   可交互 ← 内容块：留可交互，内容块让位（否则"链接"和它里面的"标题"各来一次）
+  var kept = [];
+  for (var i = 0; i < picked.length; i++) {
+    var it = picked[i];
+    var shadowed = false;
+    for (var j = 0; j < picked.length; j++) {
+      if (j === i) continue;
+      var o = picked[j];
+      if (o.el === it.el) continue;
+      try {
+        if (!it.el.contains(o.el)) continue; // o 不是 it 的后代
+      } catch (e3) { continue; /* 跨文档不会发生 */ }
+      if (o.interactive || !it.interactive) { shadowed = true; break; }
+    }
+    if (!shadowed) kept.push(it);
+  }
+
+  // 第二趟半：内容块如果被某个**活着的**可交互祖先包着，也让位。
+  var final = [];
+  for (var f = 0; f < kept.length; f++) {
+    var node0 = kept[f];
+    if (!node0.interactive) {
+      var underInteractive = false;
+      for (var g = 0; g < kept.length; g++) {
+        var o2 = kept[g];
+        if (g === f || !o2.interactive) continue;
+        try { if (o2.el.contains(node0.el)) { underInteractive = true; break; } } catch (e5) { /* ignore */ }
+      }
+      if (underInteractive) continue;
+    }
+    final.push(node0);
+  }
+  kept = final;
+
+  // 第三趟：产出节点。**两类都写 data-ai-id**：树里出现的 ref 必须能用
+  // ui.act / ui.evaluate 路由回这个帧（见 page_manager._owningFrame）。
+  // 出现"树里有、点了说找不到"的 ref，比不出现更伤人。
+  var out = [];
+  for (var m = 0; m < kept.length && out.length < MAX_NODES; m++) {
+    var node = kept[m];
+    var idx = out.length;
+    var id = prefix + idx;
+    try { node.el.setAttribute('data-ai-id', id); } catch (e4) { continue; }
+    var rec = {
+      id: id,
+      role: node.role,
+      label: node.label || '',
+      bounds: node.bounds
+    };
+    if (node.url) rec.url = node.url;
+    if (node.editor_type) {
+      rec.editor_type = node.editor_type;
+      rec.states = ['editable=' + node.editor_type, 'focusable'];
+    } else if (node.interactive) {
+      rec.states = ['focusable'];
+    } else {
+      // 只读内容：显式标出来，调用方不会去点一个标题再奇怪为什么没反应。
+      rec.states = ['readonly'];
+    }
+    out.push(rec);
+  }
+
+  var keptChars = 0;
+  var texts = 0;
+  for (var n = 0; n < out.length; n++) {
+    // 可编辑节点的 label 是占位符（"请输入标题"），不是页面正文 —— 不计入
+    // 覆盖率分子，否则一个带 placeholder 的搜索框就能把覆盖率虚抬上去。
+    if (out[n].editor_type) continue;
+    keptChars += countChars(out[n].label);
+    if ((out[n].states || [])[0] === 'readonly') texts += 1;
+  }
+  var bodyChars = countChars(bodyText);
+
+  return {
+    url: (typeof location !== 'undefined' && location.href) || '',
+    title: (typeof document.title === 'string') ? document.title : '',
+    nodes: out,
+    stats: {
+      candidates: els.length,
+      interactive: out.length - texts,
+      text_blocks: texts,
+      text_chars: bodyChars,
+      kept_chars: keptChars,
+      // 覆盖率：这一帧**看得见的文字**里，有多少进了树。1 = 全进；
+      // 0.01 = 树里只有一个搜索框，正文一个字都没读到（泛雅事故现场）。
+      coverage: bodyChars
+        ? Math.round(Math.min(1, keptChars / bodyChars) * 100) / 100
+        : (out.length ? 1 : 0),
+    }
+  };
+}
+
+/**
+ * 产出可直接喂给 `frame.executeJavaScript()` 的源码。
+ * 用 toString() 而不是拼字符串：正则、模板、引号全部保持原样，不会在拼装层
+ * 被转义吃掉一层（拼字符串的版本踩过 `\s` 变成 `s`）。
+ */
+export function buildFrameReadSource(prefix) {
+  return '(' + frameRead.toString() + ')(' + JSON.stringify(String(prefix || '')) + ')';
+}
+
+export { frameRead };
+export default { buildFrameReadSource, frameRead };

package/src/shared/opened_tab.js

@@ -0,0 +1,71 @@
+// shared/opened_tab.js — 判断"这条新标签记录是不是本次动作造成的"
+//
+// 背景（2026-10-19 实测）：_openedTabs 记录"某个 tab 打开了新标签"，供
+// executeAction 回报 opened_tab 并自动切换过去。但记录的产生方不止 act：
+//   • window.open 垫片 / setWindowOpenHandler 也会写这条记录
+//   • 如果那次 window.open 是 ui.evaluate 里 el.click() 触发的，就**没有人消费它**
+// 于是陈旧记录会挂在 map 里，被下一次点击或悬停误认为"我刚开了个标签"。
+// 实测症状：在课程列表页点过「进入学习」之后，随后的 hover 回执里
+// opened_tab 指向那个 about:blank —— 一个与本次操作毫无关系的标签。
+//
+// 规则：只有**在本次动作开始之后**记录的条目才算数。时间戳由 act 入口打，
+// 这里只做纯判定，便于单测。
+
+/**
+ * @param {{id:number,url:string,at?:number}|null|undefined} entry 已取出的记录
+ * @param {number|undefined} startedAt 本次动作的开始时刻（ms）
+ * @returns {object|null} 属于本次动作的记录，否则 null
+ */
+export function pickOpenedTab(entry, startedAt) {
+  if (!entry) return null;
+  // startedAt 缺省时保持旧行为（调用方没提供时间基准，不做时间过滤）
+  if (startedAt === undefined) return entry;
+  // 没有时间戳的旧记录一律视为陈旧：宁可漏报一次，也不要把别的动作的标签
+  // 算到这次头上 —— 后者会让 agent 去操作一个它没打开过的页面。
+  if (typeof entry.at !== 'number') return null;
+  return entry.at >= startedAt ? entry : null;
+}
+
+// ── 「等一下再收」的宽限窗口 ──────────────────────────────────────────────
+//
+// 2026-10-19 实测（西电专技课程页点「进入学习」，站点代码是
+// `var w = window.open("","_blank"); w.location = res.url;`）：
+//
+//   act 返回      10~15 ms
+//   新标签出现   105 / 214 / 236 ms   ← 三轮，**不稳定**
+//
+// 第一轮测到的 105~119ms（三轮）是热缓存下的假稳定，加了等待之后复测就散到
+// 200ms 以上了 —— 站点是先 fetch 拿到地址再 window.open，所以延迟跟着网络走。
+// 这条推翻了我最初"固定 100ms 就够"的判断，记在这里免得下次又按那个数设计。
+//
+// 结论：**单靠一个窗口不可能既覆盖又不拖慢**，所以配两个提前退出条件：
+//   1. 已经有记录 → 立刻返回（零等待）；
+//   2. 本 tab 开始原地导航（isLoading）→ 立刻返回。站内跳转不会同时开新标签，
+//      而这一类点击恰恰是最高频的，于是最常见的情况根本不会付这笔时间。
+// 剩下的（点了按钮、页面既没导航也没开标签）才等满窗口。
+//
+// 为什么是固定窗口而不是"等到页面安静"：没有可靠的"安静"信号 —— 页面自己的
+// 定时器、动画、轮询会让它永远不安静（教训见 hover 的收菜单那段注释）。
+//
+// 代价要说明白：窗口大小直接乘以"无副作用的点击次数"。所以它必须可关：
+//   · `opened_tab_wait_ms: 0`  单次调用关掉
+//   · `AI_BROWSER_OPENED_TAB_WAIT_MS=0`  全局关掉（跑基准测试时用）
+export const DEFAULT_OPENED_TAB_GRACE_MS = 250;
+const MAX_GRACE_MS = 2000;
+
+/**
+ * 本次点击应该为"新标签记录"等多久。
+ *
+ * @param {object} [params] act 的参数体
+ * @param {NodeJS.ProcessEnv|object} [env] 便于测试注入
+ * @returns {number} 毫秒，0 表示不等
+ */
+export function openedTabGraceMs(params, env) {
+  const explicit = params && Number(params.opened_tab_wait_ms);
+  if (Number.isFinite(explicit) && explicit >= 0) return Math.min(explicit, MAX_GRACE_MS);
+  const e = env || (typeof process !== 'undefined' ? process.env : null);
+  const fromEnv = e && Number(e.AI_BROWSER_OPENED_TAB_WAIT_MS);
+  if (Number.isFinite(fromEnv) && fromEnv >= 0) return Math.min(fromEnv, MAX_GRACE_MS);
+  return DEFAULT_OPENED_TAB_GRACE_MS;
+}
+

package/src/shared/ref_epoch.js

@@ -0,0 +1,99 @@
+// shared/ref_epoch.js — 给「目标找不到」补上一个关键区分：**ref 过期了，还是从来没对过**。
+//
+// 问题（真实排查记录）：agent 从 get_tree 拿到 `e:button-12`，点下去回
+// `target_not_found`。它面对两种完全不同的处境，却收到同一句话：
+//   a) 页面在这两次调用之间变了（SPA 重渲染、弹窗重开、列表翻页）→ 老 ref 作废，
+//      正确做法是**重新 get_tree 拿新 ref**；
+//   b) ref 从头就没对过（传了可见文字、抄错、来自另一个标签页）→ 重新 get_tree
+//      也没用，要改的是传参方式。
+// 分不清这两者时，agent 的典型反应是"重试同一个 ref"（因为错误信息里没说要换），
+// 把一次本来 1 步的恢复拖成 3~5 步。
+//
+// 做法：每次 get_tree 成功就推进一个 per-tab 的 epoch，并记下这一版树里出现过的所有
+// ref 属于哪一版。之后 ref 找不到时：
+//   · ref 在某版树里出现过，且那版 < 当前版 → **stale**（过期），让它重读树；
+//   · ref 一次都没出现过 → **never_seen**（形状/来源错），让它改传参；
+//   · ref 就在当前版里，DOM 却查不到 → **present_in_tree**（树里有、点不到），
+//     通常是在 iframe / shadow root 里，或节点已脱离文档 —— 换读法，不是换 ref。
+//
+// 边界诚实说明：这个追踪只知道**本进程内 get_tree 见过什么**。如果 agent 从别处
+// 拿到 ref（自己拼的、上一次会话的），这里只会判成 never_seen —— 那也正是我们想让
+// 它知道的事实。
+
+/** 一个 tracker 管一个标签页。 */
+export function newTracker() {
+  return { epoch: 0, seen: new Map() }; // ref -> 见过它的最后一次 epoch
+}
+
+/**
+ * 从语义树里收集所有 ref。节点的 id 就是 data-ai-id。
+ * 只收字符串型 id；缺 id 的容器节点跳过。
+ */
+export function collectRefs(tree) {
+  const refs = [];
+  (function walk(n) {
+    if (!n || typeof n !== 'object') return;
+    if (typeof n.id === 'string' && n.id) refs.push(n.id);
+    const kids = n.children;
+    if (Array.isArray(kids)) for (const k of kids) walk(k);
+  })(tree);
+  return refs;
+}
+
+/**
+ * 推进 epoch 并登记这一版树里出现过的 ref。
+ * @returns {number} 新的 epoch（从 1 开始，0 表示"还没有任何一版树"）
+ */
+export function bumpEpoch(tracker, refs) {
+  tracker.epoch += 1;
+  for (const r of refs) if (typeof r === 'string' && r) tracker.seen.set(r, tracker.epoch);
+  return tracker.epoch;
+}
+
+/** 便捷入口：直接吃一棵树。 */
+export function noteTree(tracker, tree) {
+  return bumpEpoch(tracker, collectRefs(tree));
+}
+
+export const REF_STALE = 'stale';
+export const REF_NEVER_SEEN = 'never_seen';
+export const REF_PRESENT_IN_TREE = 'present_in_tree';
+
+const HINTS = {
+  [REF_STALE]: (o) =>
+    `stale_ref: this ref was in semantic-tree v${o.ref_epoch}, the page has since been re-read (now v${o.tree_epoch}). ` +
+    'Re-run get_tree and use a fresh ref — retrying the same one will keep failing.',
+  [REF_NEVER_SEEN]: (o) =>
+    `ref_never_seen: this ref is not in any of the ${o.tree_epoch} semantic tree(s) read so far. ` +
+    'Most likely you passed visible text instead of a data-ai-id, mistyped it, or took it from another tab. ' +
+    'Reading the tree again will not help by itself — fix the ref.',
+  [REF_PRESENT_IN_TREE]: (o) =>
+    `ref_present_in_tree: the ref is in the current tree (v${o.tree_epoch}) but the DOM query found nothing. ` +
+    'It is probably inside an iframe / shadow root, or has been detached. Try the frame-aware read, or pick a nearby stable element.',
+};
+
+/**
+ * 诊断一个找不到的 ref。
+ *
+ * @param {string} ref
+ * @param {{epoch:number, seen:Map<string,number>}} tracker
+ * @returns {{stale_ref:boolean, ref_epoch:number|null, tree_epoch:number, reason:string, hint:string}}
+ */
+export function diagnoseMissingRef(ref, tracker) {
+  const treeEpoch = (tracker && tracker.epoch) || 0;
+  const seenEpoch = tracker && tracker.seen ? tracker.seen.get(String(ref)) : undefined;
+
+  let reason;
+  if (seenEpoch === undefined || treeEpoch === 0) reason = REF_NEVER_SEEN;
+  else if (seenEpoch < treeEpoch) reason = REF_STALE;
+  else reason = REF_PRESENT_IN_TREE;
+
+  const info = { ref_epoch: seenEpoch === undefined ? null : seenEpoch, tree_epoch: treeEpoch };
+  return {
+    stale_ref: reason === REF_STALE,
+    ref_epoch: info.ref_epoch,
+    tree_epoch: info.tree_epoch,
+    reason,
+    hint: HINTS[reason](info),
+  };
+}

package/src/shared/tab_hooks.js

@@ -0,0 +1,33 @@
+// shared/tab_hooks.js — 给 pageManager.setActive 挂副作用钩子，且**不吞返回值**。
+//
+// 为什么要单独抽出来（2026-10-19 实测事故）：
+//   index.js 为了「地址栏状态跟随激活 tab」在启动时给 setActive 套了一层包装：
+//       const orig = pageManager.setActive.bind(pageManager);
+//       pageManager.setActive = function (tabId) { orig(tabId); wireNavState(tabId); };
+//   包装里忘了 return。setActive 原本 return true/false，是**协议的一部分**：
+//   ws_server.js 里 `const ok = pageManager.setActive(params.tab)` 再回
+//   `{ ok }` 给客户端。丢掉返回值 → ok 变 undefined → JSON.stringify 直接把这个
+//   键删掉 → agent 收到 `{}`，拿不到"切成功了没"的任何确认。
+//
+//   这个 bug 极难在端到端里看出来：tab 实际上**切成功了**（list_tabs 显示 active
+//   已变），只有回执是空的。所以修法不只是补一个 return，而是把"套钩子"这件事
+//   变成一个被测过的函数，以后再有人往上挂副作用，返回值天然被保住。
+//
+// 契约（tests/test_tab_hooks.js 钉住）：
+//   1. 返回值原样透传（true / false / 任何值）；
+//   2. 钩子在**原方法之后**执行 —— 它要读 activeTab 这类被原方法改过的状态；
+//   3. 原方法抛异常时钩子不执行，异常照常向上抛（不能掩盖真错误）；
+//   4. this 绑定到原 pageManager（原方法可能是 class 方法，用到 this）。
+export function wrapSetActive(pageManager, onAfter) {
+  if (!pageManager || typeof pageManager.setActive !== 'function') {
+    throw new TypeError('wrapSetActive: pageManager.setActive is not a function');
+  }
+  const orig = pageManager.setActive.bind(pageManager);
+  const wrapped = function (tabId) {
+    const result = orig(tabId);
+    if (typeof onAfter === 'function') onAfter(tabId, result);
+    return result;
+  };
+  pageManager.setActive = wrapped;
+  return wrapped;
+}

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.3.0';
+export const VERSION = '2.0.0';

package/tools/coverage_probe.cjs

@@ -81,12 +81,38 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 //   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]';
+  // a[href] 换成 a：无 href 的锚点（onclick 驱动）也是可点目标。超星泛雅的章节
+  // 条目就是 <a onclick>，href 为 null —— 只认 a[href] 会把它们从**分母**里删掉，
+  // 于是覆盖率虚高。帧读取器（shared/frame_read_source.js）早先踩过同一个坑。
+  var INTER = 'a,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 (!hits || hits.length === 0) return false;
+    // 只算**可见的、最内层的**可交互元素：
+    //  - 不可见的（隐藏 input、0×0 的埋点控件）不是人能看到的目标；
+    //  - 最内层的（不再包含别的可交互元素）才是真正的动作目标，外面那层是包装。
+    // 不这么筛，"这一行里到底有几个可点的东西"永远数不清 —— 实测超星章节行
+    // 里同时有 2 个隐藏 input + 行容器 div[role=link] + 标题 a，共 4 个命中，
+    // 于是"唯一可交互后代"这个前提永远不成立，6 个章节被永久误报成真缺口。
+    var live = [];
+    for (var i = 0; i < hits.length; i++) {
+      var h = hits[i];
+      var hr = h.getBoundingClientRect();
+      if (!(hr.width > 0) || !(hr.height > 0)) continue;
+      live.push(h);
+    }
+    var leaves = [];
+    for (var k = 0; k < live.length; k++) {
+      var nest = false;
+      for (var m = 0; m < live.length; m++) {
+        if (m === k || live[m] === live[k]) continue;
+        if (live[k].contains(live[m])) { nest = true; break; }
+      }
+      if (!nest) leaves.push(live[k]);
+    }
+    if (leaves.length !== 1) return false;
+    var inner = leaves[0];
     if (!inner.hasAttribute('data-ai-id')) return false;
     var b = inner.getBoundingClientRect();
     if (!(b.width > 0) || !(b.height > 0)) return false;
@@ -94,10 +120,26 @@ const COUNT_JS = `(function(){
     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;
+    // 判据一（几何）：内层要「盖满」外层，两个方向都 >= 90%。与
+    // src/preload/extractor.cjs 的 wrapsSingleInteractive 同一口径。
+    // 只看交集/内层面积会把"大卡片里放个小链接"误判成壳子（点卡片 ≠ 点那个链接）。
+    if (inter / (b.width * b.height) >= 0.9 && inter / (r.width * r.height) >= 0.9) return true;
+    // 判据二（文本）：外层的文字**就是**这一个链接的文字（可能多个角标）。
+    // 2026-10-19 实测（超星泛雅章节行）：外层是整行
+    //   <div class="chapter_item" role="link">1.1 标题 <b>1</b></div>
+    // 内层是 <a>1.1 标题</a>，宽 996 / 行宽 1100 —— 几何上差 5% 不过线，于是
+    // 6 个章节被报成"真缺口"。但点内层 a 会冒泡到整行，实测
+    // act{axf-1-4} → clicked_via:"oopif-click", effect_state:"committed"。
+    // 这里比抽取层**故意松一点**，因为两边错的方向不同：抽取层判错会**丢掉**
+    // 一个目标（不可逆），这里判松只是让百分比略微乐观（可复查）。
+    // 松的条件是有界的：唯一可交互后代 + 外层文字以内层文字开头 + 长度接近。
+    // "大卡片里放个小链接"过不了这三条（文字开头就不是它）。
+    try {
+      var ot = (el.innerText || '').replace(/\s+/g, ' ').trim();
+      var it = (inner.innerText || '').replace(/\s+/g, ' ').trim();
+      if (ot && it && ot.indexOf(it) === 0 && it.length >= ot.length * 0.5) return true;
+    } catch (e2) { /* 拿不到文字就按几何判据走 */ }
+    return false;
   }
   function scan(onlyBoundary){
     var s = {pointer: 0, inTree: 0, byDesc: 0, ancOnly: 0, ambiguous: 0, noIdChain: 0, missing: []};
@@ -179,8 +221,51 @@ const COUNT_JS = `(function(){
 
   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;            // 元素视角：和此前数据可比，但分母被继承放大了
+
+  // ---- 跨进程帧：分母必须包含它们，否则这个数字会骗人 ----
+  // 2026-10-19 实测（超星泛雅学习页）：本工具报「可点目标 4，可用率 100%、
+  // 真缺口 0」，而**整门课程的章节列表一个都没进树** —— 因为那 6 个条目住在
+  // 跨进程 iframe 里，而 COUNT_JS 只在顶层 document 里数。
+  // 100% 覆盖了 4 个按钮，同时 100% 看不见正文。
+  // 现在的口径：每个 `frame-N` 门节点都单独数一遍再合并，数不到的明确报出来，
+  // 不许静默排除 —— 分母把"我没测的地方"藏起来，比测错更危险。
+  const gates = [];
+  (function walkGates(n) {
+    if (!n) return;
+    if (n.role === 'Iframe' && /^frame-\d+$/.test(String(n.id || ''))) gates.push(n.id);
+    (n.children || []).forEach(walkGates);
+  })(root);
+  const perFrame = [];
+  for (const g of gates) {
+    try {
+      const fr = await c.call('ui.evaluate', { tab: TAB, js: COUNT_JS, frame_ref: g }, 60000);
+      const pj = JSON.parse(String(fr.value));
+      perFrame.push({ ref: g, boundary: pj.boundary });
+    } catch (err) {
+      perFrame.push({ ref: g, error: String((err && err.message) || err) });
+    }
+  }
+  const emptyScan = () => ({ pointer: 0, inTree: 0, byDesc: 0, ancOnly: 0, ambiguous: 0, noIdChain: 0, missing: [] });
+  const num = (o, k) => (o && Number.isFinite(Number(o[k])) ? Number(o[k]) : 0);
+  function addInto(acc, one, where) {
+    for (const k of ['pointer', 'inTree', 'byDesc', 'ancOnly', 'ambiguous', 'noIdChain']) acc[k] += num(one, k);
+    for (const m of (one && one.missing) || []) acc.missing.push(where ? { ...m, frame: where } : m);
+  }
+  // 顶层 + 每个可读帧 = 完整分母（人的视角 / 元素视角各算一份）
+  const d = emptyScan();
+  const e = emptyScan();
+  addInto(d, raw2.boundary, null);
+  addInto(e, raw2.el, null);
+  for (const pf of perFrame) {
+    if (pf.error || !pf.boundary) continue;
+    addInto(d, pf.boundary, pf.ref);
+    // 帧内没有单独的"元素口径"（继承放大在帧内影响很小），与主口径同源
+    addInto(e, pf.boundary, pf.ref);
+  }
+  const framesRead = perFrame.filter((x) => !x.error).length;
+  const framesFailed = perFrame.filter((x) => x.error);
+  const opaque = Number((raw.context && raw.context.cross_process_frames && raw.context.cross_process_frames.visible_count) || 0);
+  const unmeasured = Math.max(0, opaque - gates.length);
   const pct = (n, tot) => (tot ? Math.round((n / tot) * 100) : null);
 
   const report = {
@@ -197,6 +282,14 @@ const COUNT_JS = `(function(){
     coverage_pct: pct(d.inTree, d.pointer),
     usable_pct: pct(d.inTree + d.byDesc + d.ancOnly, d.pointer),
     blind: d.ambiguous + d.noIdChain,
+    // 跨进程帧的计量状态：读了几个、失败几个、还有几个根本没被读到。
+    // unmeasured > 0 时，上面的百分比只覆盖了顶层文档 + 已读的帧。
+    frames: {
+      measured: framesRead,
+      failed: framesFailed,
+      unmeasured,
+      details: perFrame.map((x) => (x.error ? { ref: x.ref, error: x.error } : { ref: x.ref, pointer: num(x.boundary, 'pointer') })),
+    },
     // 次要口径：所有 cursor:pointer 元素（含继承），仅供与历史数据对比
     legacy: {
       pointer_elements: e.pointer,
@@ -218,6 +311,15 @@ const COUNT_JS = `(function(){
     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('跨进程帧（已计入分母）:', framesRead, '个'
+      + (framesFailed.length ? '，读取失败 ' + framesFailed.length + ' 个' : '')
+      + (unmeasured ? '，**未测量 ' + unmeasured + ' 个**' : ''));
+    if (framesFailed.length) {
+      for (const f of framesFailed) console.log('  ! ' + f.ref + ' 读不到: ' + f.error);
+    }
+    if (unmeasured) {
+      console.log('  ! 上面这批百分比不含未测量的帧 —— 分母把没测的地方藏起来，比测错更危险');
+    }
     console.log('（历史口径 cursor:pointer 元素数 ' + e.pointer + '，覆盖 ' + (report.legacy.coverage_pct ?? 'n/a') + '%）');
     if (d.missing.length) {
       console.log('\n没进树的可点目标（ancOnly 已排除，前 40 个）:');