@glittering0717/ai-browser 1.3.0 → 2.0.0

package/src/shared/doc_coverage.js

@@ -0,0 +1,264 @@
+// src/shared/doc_coverage.js — 「这棵树读到了多少页面文字」的度量
+//
+// ============ 为什么要有它 ============
+// 2026-10-19 的泛雅事故里，默认语义树 27 个节点、13 个可操作，而整门课的章节
+// 列表一个字都不在树里。当时没有任何一个数字能表达这件事：调用方看到的是
+// "merged / frames_read:1"，以及 capabilities 的一句"the UI is largely
+// canvas-rendered"。**"读到了"从来不是一个可测量的结论。**
+//
+// 同一个仓库里已经有这个纪律，只是只覆盖了一半：tools/coverage_probe.cjs 数
+// "人看着能点的东西有多少进了树"。但它数的是**可点目标**，而且原先只数默认
+// 文档。文字呢？没人数。
+//
+// 这个模块补的就是那个数字：**树里的文字 / 页面上看得见的文字**。
+// 分母 = 主文档 innerText 长度 + 每个跨进程帧里可见文字长度（帧那边由
+// frame_read_source.stats.text_chars 给，已经算过，不重复付钱）。
+//
+// ============ 为什么用 innerText ============
+// 它是**浏览器自己算出来的"看得见的文字"**：display:none、折叠的、被
+// visibility:hidden 藏掉的都不算，换行/空白也按渲染结果归一。用它当分母，
+// 比"数 DOM 里的 textContent"更接近人眼看到的东西 —— 也就更接近
+// "agent 应该能读到多少"。
+//
+// 它是纯函数模块（不碰 DOM、不碰 Electron），所以能单测；
+// 取 innerText 的那一侧在 preload/extractor.cjs 的 stats.text_chars。
+
+/**
+ * 这些角色的 label 是**元数据**，不是页面上渲染出来的文字。
+ *
+ * 为什么必须排除：分母用 `innerText` 量（浏览器自己算的"看得见的字"），
+ * 分子就得用同一把尺子。实测泛雅页面上：
+ *   - `<img alt="Logo">` 的 alt 不在 innerText 里；
+ *   - `<iframe name="frame_content-zj">` 的 name 更不在 —— 而树的合并逻辑
+ *     会给同一个 iframe 建三个描述节点（iframe_body / iframe / Iframe 闸门），
+ *     `frame_content-zj` 这 16 个字被数了三遍，凭空多出 32 字。
+ * 不排除它们，比例就会溢出到 100% 以上，这个数字就废了（实测 547/185）。
+ *
+ * 用 role 名单而不是"看有没有 children"：children 数量是树形状的偶然结果，
+ * role 才是语义。
+ */
+const META_ROLES = new Set(['image', 'img', 'iframe', 'iframe_body', 'canvas', 'separator']);
+
+/**
+ * 这些 label **不是页面上渲染出来的文字**，而是可访问名：aria-label / alt /
+ * title / placeholder / input 的 value。抽取器给它们标了 label_kind。
+ *
+ * 为什么必须排除：分母是 innerText，里面根本没有这些字。实测 /basic.html ——
+ * `<input placeholder="随便填">` 让分子 46 大于分母 43，页面明明只有 43 字却报 100%。
+ * 真实站点上每个图标按钮都挂 aria-label，虚高是系统性的，不是零点几个百分点。
+ * （节点本身照旧带 label —— agent 需要它来认识"这个按钮是干什么的"，只是不算进覆盖率。）
+ */
+const isNonRenderedLabel = (n) => !!(n.label_kind && n.label_kind !== 'text');
+
+/**
+ * 只数**非空白字符**。
+ *
+ * 为什么：分母来自 `innerText`，它会把结构分隔符也吐出来 —— 一个 32 格表格的
+ * innerText 里夹着 30 多个 `\t` / `\n`，而分子（label）没有这些。
+ * 实测一张 8×4 的表格：page 80 字、tree 54 字 → 覆盖率 68%，看起来"少读了三分之一"，
+ * 实际每个单元格的文字都在，少的是**空格**。
+ * 中文页面几乎不吃这个亏，英文页面按词空格能虚低 15%，表格页面能虚低 40%。
+ * 同一把尺子量两边，这类结构性误差才会消失。
+ */
+const countChars = (s) => {
+  if (!s) return 0;
+  const m = String(s).match(/[^\s\u00a0]/g);
+  return m ? m.length : 0;
+};
+
+/** 树里所有**正文** label 的字符数。图标的空 label、可编辑框的占位符不算。 */
+export function sumLabelChars(tree) {
+  let labels = 0;
+  let nodes = 0;
+  let chars = 0;
+
+  // 累加规则：**先算后代，后代有字就以后代为准**。
+  //
+  // 为什么不是"把所有 label 加起来"：DOM 抽取器会给容器节点也写 label，而且
+  // 那 label 就是它里面的全部文字（`<div>课程门户 链接</div>`）。全加一遍等于
+  // 同一句话数了三次 —— 实测泛雅页 tree_chars 547 vs 页面 185，覆盖率直接
+  // 溢出到 100%，这个数字就废了。
+  //
+  // 为什么不是"只数叶子"：图标链接 `<a>课程门户<i/></a>` 有子节点（空的 i），
+  // 按叶子算会把它的文字丢掉 —— 那正是"少算"，同样会让数字失真。
+  //
+  // 所以：有字的后代优先；后代一个字都没有时，才认这个节点自己的 label。
+  function measure(n) {
+    if (!n) return 0;
+    nodes += 1;
+    let kidsChars = 0;
+    for (const c of n.children || []) kidsChars += measure(c);
+    // 可编辑节点的 label 是 placeholder / value，不是页面正文：
+    // innerText 里没有它们，算进分子会让覆盖率虚高（一个带 placeholder 的
+    // 搜索框就能把 0% 抬到 20%）。
+    const role = typeof n.role === 'string' ? n.role.toLowerCase() : '';
+    const own = (n.editor_type || isNonRenderedLabel(n) || META_ROLES.has(role)) ? 0 : countChars(n.label);
+    if (kidsChars > 0) return kidsChars;   // 后代有字：以它们为准，容器不再加一遍
+    if (own) labels += 1;                  // 这个节点是这段文字的唯一来源
+    return own;
+  }
+
+  chars = measure(tree);
+  return { chars, labels, nodes };
+}
+
+const clamp01 = (x) => (x < 0 ? 0 : x > 1 ? 1 : x);
+
+/**
+ * 分子超过分母这么多，就不是"读得好"，是**分母漏了一块**。
+ *
+ * 为什么要留这个判据：这个指标的第一版就在这里撒过谎。泛雅页分子 547、分母 185，
+ * 我当时的处理是钳到 1、当没事发生。可"分子大于分母"本身就是一个**测量结论**：
+ * 树里数出来的字比页面上能看见的还多，只可能是分母少统计了一个承载文字的
+ * 表面（同源子帧 / shadow DOM / canvas），或者是分子在重复计数。
+ * 钳掉之后，100% 这个数字看起来最健康，恰好把问题藏得最深。
+ */
+export const OVER_MEASURED = 1.2;
+
+/**
+ * 页面级文字覆盖率。
+ *
+ * @param {{treeChars:number, mainChars:number, sameOriginChars?:number,
+ *          frameChars:number, canvases?:number, ax?:boolean}} input
+ *        ax:true 表示这是 AX 树（label 是可访问名，不是渲染文字），
+ *        超过 100% 不算异常，见下面 over 分支。
+ * @returns {{tree_chars:number, page_chars:number, main_chars:number, frame_chars:number,
+ *            same_origin_chars:number, ratio:number|null, percent:number|null,
+ *            hint:string|null, unmeasurable?:string, over_measured?:boolean,
+ *            names_exceed_text?:boolean}}
+ */
+export function pageCoverage(input) {
+  const o = input && typeof input === 'object' ? input : {};
+  const tree = Math.max(0, Number(o.treeChars) || 0);
+  const main = Math.max(0, Number(o.mainChars) || 0);
+  const sameOrigin = Math.max(0, Number(o.sameOriginChars) || 0);
+  const shadow = Math.max(0, Number(o.shadowChars) || 0);
+  const frame = Math.max(0, Number(o.frameChars) || 0);
+  const canvases = Math.max(0, Number(o.canvases) || 0);
+  // 分母 = 分子会走到的每一个表面：主文档 + 同源子帧 + open shadow root + 跨进程帧。
+  // 少算任何一块，比例就虚高 —— 而同源子帧和 shadow DOM 是最容易漏的两块：
+  // `body.innerText` 既不下钻 iframe，也不穿过 shadow 边界，抽取器却两头都会走。
+  // 实测 shadow 页：树里 35 字、分母只有 8 字 → over_measured。
+  const page = main + sameOrigin + shadow + frame;
+  const base = {
+    tree_chars: tree,
+    page_chars: page,
+    main_chars: main,
+    frame_chars: frame,
+    same_origin_chars: sameOrigin,
+    shadow_chars: shadow,
+    ratio: null,
+    percent: null,
+    hint: null,
+  };
+  // 页面一个字都没有（空标签页、还没渲染）→ 不报覆盖率。
+  // 报 0 会被读成"我们没读到"，而事实是"没有可读的文字"。两种情况必须分开。
+  if (page <= 0) {
+    if (canvases > 0) {
+      return { ...base, unmeasurable: 'canvas', hint: CANVAS_HINT };
+    }
+    return base;
+  }
+  // canvas 画的字永远不在 innerText 里，所以这类页面的"文字覆盖率"没有分母。
+  // 与其拿页面上那 4 个字的 HUD 文案算出一个 100%，不如直接说量不了。
+  if (canvases > 0 && page < 200) {
+    return { ...base, unmeasurable: 'canvas', hint: CANVAS_HINT };
+  }
+
+  const raw = tree / page;
+  const over = raw > OVER_MEASURED;
+  const ratio = clamp01(raw);
+  base.ratio = Math.round(ratio * 1000) / 1000;
+  base.percent = Math.round(ratio * 100);
+  if (over) {
+    // AX 树的 label 是**可访问名**，天生包含 aria-label / alt / title 这些
+    // 不属于 innerText 的字。所以 AX 读数超过 100% 是设计使然，不是"分母漏了表面"。
+    // 实测 知乎首页：DOM 346/443、AX 542/443 —— 那 99 个字是 18 个图标按钮的
+    // aria-label，一个字都没漏。这种情况不能报 over_measured（那是给 DOM 树用的
+    // 报警器，报了就是每张真实页面都报警，警报就废了），但也不许装作没发生：
+    // 记一个 names_exceed_text 让调用方知道"这个 100% 是钳出来的"。
+    if (o.ax) {
+      base.names_exceed_text = true;
+      return base;
+    }
+    base.over_measured = true;
+    base.hint = `the tree carries ${tree} chars but this page only has ${page} measurable visible chars `
+      + `(${main} main + ${sameOrigin} same-origin iframe + ${shadow} shadow DOM + ${frame} cross-process frame) — `
+      + 'the numerator is larger than the denominator, so the denominator is missing a surface '
+      + '(text inside shadow DOM, or a frame we could not measure). Treat this page\'s coverage as unknown, '
+      + 'not as 100%: read with get_tree {ax:true} and judge by the content';
+    return base;
+  }
+  base.hint = coverageHint(base);
+  return base;
+}
+
+const CANVAS_HINT = 'this page draws on a <canvas>, so its text is invisible to innerText and text coverage '
+  + 'cannot be measured — a percentage here would be meaningless. Use ui.screenshot to see it, '
+  + 'ui.canvas_read to get the pixels, or context.route in ui.capabilities to pick a read layer';
+
+/**
+ * 低于这个比例才给提示。
+ *
+ * 0.5 是错的，实测被抓了三次（e2e/readcov_ws.cjs 第一次跑就三条一起红）：
+ *   · /long.html     70% —— 60 段正文全在树里，但每段 label 被裁到 60 字
+ *   · /xorigin-frame 59% —— 帧合并了，帧里的段落同样被裁
+ *   · /sr-only       27% —— 移出视口的 span 没有独立节点
+ * 这三张页面**都在静默地少读**（27% 是最刺眼的那种：页面 22 字，agent 只看到 6 字），
+ * 而闸门 0.5 让前两张一声不响。也就是说这个闸门对"读了一半"这种最常见、
+ * 也最容易误导人的状态恰好是聋的。
+ *
+ * 判据只能是**不变量本身**：读不到 90% 就该说一句。提示是一句话，多给一次的
+ * 成本远低于"agent 以为读完了"的成本。
+ */
+export const LOW_COVERAGE = 0.9;
+
+/**
+ * 绝对缺口的下限（字）。只负责"别为一两个字打扰调用方"，不负责判断严重程度 ——
+ * 严重程度由比例闸门说。
+ *
+ * 这个数字的历史：最初是 `page_chars < 200 → 不提示`（把泛雅 185 字自己排除了），
+ * 后来是 20（把 /sr-only.html 的 73% 缺口静音了），现在 5。详见 missingEnough。
+ */
+export const MIN_MISSING_CHARS = 5;
+
+/**
+ * 这个页面"漏够了没有"。
+ *
+ * 这里换过三版判据，每一版都是被实测推翻的：
+ *   1. `page_chars < 200 → 静音`：把泛雅（185 字）自己排除了。
+ *   2. `缺 ≥ 20 字`：把 /sr-only.html（22 字页面漏 16 字，漏 73%）静音了。
+ *   3. 现在：比例闸门已经抬到 0.9，缺口天然是成比例的；绝对值只留一个
+ *      "别为一两个字打扰调用方"的下限。
+ *
+ * 0.9 这条闸门意味着"漏 10% 以上就要说话"，所以 20 这个绝对门槛是重复保险，
+ * 而它在小页面上反而成了静音器。留着 5：一个词以下的缺口，说什么都没用。
+ */
+function missingEnough(missing) {
+  return missing >= MIN_MISSING_CHARS;
+}
+
+function coverageHint(c) {
+  if (c.ratio === null || c.ratio >= LOW_COVERAGE) return null;
+  const missing = Math.max(0, c.page_chars - c.tree_chars);
+  if (!missingEnough(missing)) return null;
+  // 归因要挂在数字上，不能靠猜。帧里有多少字是**实测**的（frame_read_source），
+  // 所以这里能分辨"文字在跨进程帧里"和"文字在主文档里但没进树"。
+  //
+  // 帧这一支**不许**推荐 ax:true：AX 树对子帧的内容同样走 frame_read_source
+  // 的合并通路（实测 /same-frame AX 也只能到 55%），指过去等于把人指进死胡同。
+  // 帧里文字的可靠读法是 frame_ref / 帧地址。
+  if (c.frame_chars > 0 && c.frame_chars >= missing * 0.6) {
+    return `the tree carries ${c.percent}% of this page's visible text (${c.tree_chars}/${c.page_chars} chars); `
+      + `${c.frame_chars} of the missing ${missing} chars are inside cross-process frame(s). `
+      + 'Frame bodies are merged as a preview (each block clipped), so read them directly: '
+      + 'ui.evaluate {frame_ref:"frame-1", expr:"document.body.innerText"} — the frame refs and absolute '
+      + 'src are in context.frame_hints.frames';
+  }
+  if (c.main_chars > 0 && c.main_chars >= missing * 0.6) {
+    return `the tree carries ${c.percent}% of this page's visible text (${c.tree_chars}/${c.page_chars} chars) and most of the gap is in the main document — the DOM tree keeps structure and clips each block's text, the AX tree keeps the full text. Try get_tree {ax:true} before concluding the content is invisible; if AX is also low, the page may still be rendering, or the content sits in shadow DOM / a virtualized list`;
+  }
+  return `the tree carries ${c.percent}% of this page's visible text (${c.tree_chars}/${c.page_chars} chars) — the gap is split between the main document and cross-process frames; check context.frame_hints first, and use frame_ref for the frames`;
+}
+
+export default { sumLabelChars, pageCoverage, LOW_COVERAGE, MIN_MISSING_CHARS, OVER_MEASURED };

package/src/shared/effect_state.js

@@ -0,0 +1,160 @@
+// shared/effect_state.js — 每个动作回执都自带"页面到底被改动了没有"的三态判断。
+//
+// 为什么必须有这个字段（来自真实故障，不是设计洁癖）：
+//   agent 点击后拿到 `{success:false, error:'...'}`，它无法回答一个关键问题 ——
+//   **刚才那一下，页面里到底发生没发生？**
+//   · 如果是"根本没点到"（target_not_found），重试是安全的；
+//   · 如果是"点到了但回执超时"，重试就是第二次提交 —— 表单重复提交、消息发两遍、
+//     订单下两次。这类事故在 agent 上比人更容易发生，因为 agent 没有"我记得我刚
+//     点过"这层直觉。
+//   以前这个判断藏在 error 字符串里，要靠模型读懂措辞（"may have partially applied"
+//   写在一个 30 个词的英文长句末尾，实测经常被忽略）。现在把它变成一个**机器可判
+//   的枚举**，并配一条明确的重试策略。
+//
+// 三态定义（宁可保守，不可乐观）：
+//   none      —— 有证据表明页面**没被动过**（目标不存在、参数不合法、CDP 没连上、
+//                形状体检没过）。重试安全。
+//   committed —— 输入已经派发且页面 ack 了。不要重试。
+//   unknown   —— **无法证明**没被动过（超时、事件派发了但页面没消费、粘贴落地存疑、
+//                按了一半的键）。必须先读页面状态再决定，绝不能盲目重试。
+//
+// 最后一条是这套东西的全部价值所在：默认值是 unknown，不是 none。分类不出来时
+// 承认不知道，比猜"应该没点到"安全得多。
+
+export const EFFECT_NONE = 'none';
+export const EFFECT_COMMITTED = 'committed';
+export const EFFECT_UNKNOWN = 'unknown';
+
+// 重试策略枚举（跟着 effect_state 一起回，省得调用方自己去查表）
+export const RETRY_SAFE = 'safe';
+export const RETRY_NO = 'no';
+export const RETRY_VERIFY_FIRST = 'verify_first';
+
+// 「页面一定没被动过」的征兆。全部取自 page_manager.js 里真实存在过的 error 文案
+// （见 tests/test_effect_state.js 的 E-* 用例，那里逐条钉住了真实字符串）。
+const NO_EFFECT_PATTERNS = [
+  /target[_ ]not[_ ]found/i,
+  // 上面的正则同时覆盖两种真实写法：page_manager 的 `target_not_found:` 与
+  // src/preload/actions.cjs:34 的 `Target not found for ref:`。它们**不是同一
+  // 个词**，2026-10-19 真机回归时按前者写死就漏判了后者，差点把"没点到"误判成
+  // "不知道"（那会让 agent 对一次干净的失败也不敢重试）。
+  /^no target/i,
+  /^no url provided/i,
+  /^no link matches url/i,
+  /no-such-tab|tab not found/i,
+  /target_has_no_value/i,
+  /sensitive_value_not_readable/i,
+  /unsupported action/i,
+  /missing[-_ ](snapshot|target|param)/i,
+  /unknown-snapshot|tab-mismatch/i,
+  /cdp-unavailable/i,
+  /requires CDP/i,
+  /^wheel: need /i,
+  /^drag: (start element not found|to_target not found|need one of)/i,
+  /upload target not found/i,
+  /cannot read file/i,
+  /^type called with empty text/i,
+  /^paste called with neither/i,
+  /snapshot_failed/i,
+  /ref_not_an_id|looks like visible text|not a data-ai-id/i,
+  /element_not_found|element is not visible|has zero size/i,
+];
+
+// 「已经派发，但结果不确定」的征兆。顺序很重要：先判 partial，再判 no-effect，
+// 因为 paste 的失败判断里同时出现 "not found" 与 "not consumed"，前者是入口检查后者
+// 是事后存疑，而**事后**才是真相。
+const PARTIAL_PATTERNS = [
+  /may have partially applied/i,
+  /not consumed by the page/i,
+  /consumed but nothing landed/i,
+  /interrupted|disconnected|target closed|debugger detached/i,
+  /deadline exceeded|timed? ?out/i,
+];
+
+function matches(patterns, text) {
+  for (const re of patterns) if (re.test(text)) return true;
+  return false;
+}
+
+/**
+ * 这条错误是不是"目标找不到"？ref 过期诊断只在这种失败上做，别的一律无关。
+ * 单独导出是因为 page_manager 那边要用**同一套判定**，不能两处各写一份正则
+ * （两份词表迟早分叉，实际已经分叉过一次：page_manager 用 `target_not_found:`，
+ * preload 用 `Target not found for ref:`）。
+ */
+export function isTargetMiss(error) {
+  return typeof error === 'string' && /target[_ ]not[_ ]found/i.test(error);
+}
+
+/**
+ * 判定一个动作回执的 effect_state。
+ *
+ * @param {object} result   page_manager 里各种动作返回的对象
+ * @returns {'none'|'committed'|'unknown'}
+ */
+export function classifyEffect(result) {
+  if (!result || typeof result !== 'object') return EFFECT_UNKNOWN;
+
+  // 1. 超时是最高优先级：它可能已经生效，且**一定**不该被当成"没点到"。
+  if (result.timed_out === true) return EFFECT_UNKNOWN;
+
+  // 2. 明确成功 —— 动作实现里所有成功路径都在 CDP 派发之后才返回 success:true。
+  if (result.success === true) return EFFECT_COMMITTED;
+
+  // 2b. hover/peek 这条路径用 revealed 数组表达成功，没有 success 字段。
+  if (Array.isArray(result.revealed) && !result.error) return EFFECT_COMMITTED;
+
+  // 3. 按键按到一半失败：已经发出去的键**已经生效了**，后面那半没有。
+  if (Array.isArray(result.pressed) && result.pressed.length > 0) return EFFECT_UNKNOWN;
+
+  const errText = [result.error, result.hint, result.message]
+    .filter((x) => typeof x === 'string')
+    .join(' | ');
+
+  // 4. 事后存疑优先于入口检查。
+  if (matches(PARTIAL_PATTERNS, errText)) return EFFECT_UNKNOWN;
+
+  // 5. 有证据表明没被动过。
+  if (matches(NO_EFFECT_PATTERNS, errText)) return EFFECT_NONE;
+
+  // 6. 失败但没有证据 —— 承认不知道。
+  return EFFECT_UNKNOWN;
+}
+
+// 三态 → 重试策略。
+//
+// ⚠️ `retry` 回答的不是"有没有副作用"，而是**"原样再来一次有没有意义"**。
+// 这两件事会分叉，实测踩过：目标 ref 过期时 effect_state=none（确实什么都没发生，
+// 重试没有副作用），但原样重试**必然再失败一次** —— 那时给 `safe` 就是在骗调用方。
+// 所以 ref 类失败由调用方在 extras 里把 retry 覆盖成 verify_first。
+export function retryAdvice(state) {
+  if (state === EFFECT_NONE) return RETRY_SAFE;
+  if (state === EFFECT_COMMITTED) return RETRY_NO;
+  return RETRY_VERIFY_FIRST;
+}
+
+// unknown 时随回执给一句**可执行**的话。它必须自解释 —— 模型第一次看到这个字段
+// 也要能立刻知道该干什么，不然就得回去读文档，那正是我们要消灭的成本。
+const HINTS = {
+  [EFFECT_NONE]: null,
+  [EFFECT_COMMITTED]: null,
+  [EFFECT_UNKNOWN]:
+    'effect unknown: the page may have partially applied this action. Read the page (get_tree / get_value) to see its current state before trying again — a blind retry can submit twice.',
+};
+
+/**
+ * 把三态写进回执。纯函数，返回新对象（不原地改调用方的 result）。
+ *
+ * @param {object} result
+ * @param {object} [extras] 额外要合并进去的字段（如 stale_ref 诊断）
+ */
+export function withEffectState(result, extras) {
+  if (!result || typeof result !== 'object') return result;
+  const state = classifyEffect(result);
+  const out = { ...result, effect_state: state, retry: retryAdvice(state), ...(extras || {}) };
+  const hint = HINTS[state];
+  // 已经有更具体的错误说明时不覆盖，只在 unknown 且没有说明时补一句 ——
+  // 保证 agent 一定能看到"先验证再重试"这条要求。
+  if (hint && !result.effect_hint) out.effect_hint = hint;
+  return out;
+}

package/src/shared/frame_probe.cjs

@@ -40,15 +40,75 @@ function shouldAutoAx(summary) {
   return !!(summary && typeof summary.visible_count === 'number' && summary.visible_count > 0);
 }
 
+/**
+ * 把"读了几个帧、并进去多少东西、帧里还有多少字没进树"算成可核对的数字。
+ *
+ * 存在的理由（泛雅事故）：describeAutoAx 的 `merged` 判据是
+ * `frames.length > 0` —— 也就是"我确实拼进去了一些节点"。实测那个页面上拼进
+ * 去的只有一个搜索框，正文（章节列表）一个字都没有，回执却是
+ * `{auto_ax:'merged', frames_read:1}`。调用方看到 merged 会认为"内容读到了"，
+ * 于是一路往下操作，拿到的全是 target_not_found。
+ *
+ * "我试过了"和"成功了"必须能分开。这里产出三个测量值：
+ *   nodes_added   —— 真的并进树里的节点数（可以说 1）
+ *   text_coverage —— 帧里看得见的文字有多少进了树（0.01 一眼就知道不对）
+ *   frames[].src  —— 帧的绝对地址，树里读不到时唯一的可靠退路
+ *
+ * @param {Array<{key:string,label?:string,src?:string,tree?:object,stats?:object}>} frames
+ */
+function summarizeFrameRead(frames) {
+  const list = (Array.isArray(frames) ? frames : []).filter((f) => f && f.key);
+  if (!list.length) {
+    return { frames_read: 0, nodes_added: 0, text_coverage: null, frames: [] };
+  }
+  let nodesAdded = 0;
+  let chars = 0;
+  let keptChars = 0;
+  const per = [];
+  for (const f of list) {
+    const st = f.stats && typeof f.stats === 'object' ? f.stats : {};
+    const nodes = f.tree && Array.isArray(f.tree.children) ? f.tree.children.length : 0;
+    nodesAdded += nodes;
+    const c = Number(st.text_chars) || 0;
+    const k = Number(st.kept_chars) || 0;
+    chars += c;
+    keptChars += k;
+    per.push({
+      ref: f.key,
+      src: f.src || null,
+      nodes,
+      // 帧里可见文本的字符数：0 表示这一帧本身是空的/纯 widgets，不是我们漏了。
+      chars: c,
+    });
+  }
+  // 帧里一个字都没有时不报覆盖率 —— 报 0 会被读成"我们没读到"，而事实是
+  // "这帧没有可读的文字"。两种情况必须分开。
+  const coverage = chars > 0 ? Math.round(Math.min(1, keptChars / chars) * 100) / 100 : null;
+  return { frames_read: list.length, nodes_added: nodesAdded, text_coverage: coverage, frames: per };
+}
+
 /**
  * 自动 AX 读取的结果如何写进 context.frame_hints。
  * 三种结局分开说：合并成功 / 合并没有新内容 / AX 本身失败。调用方需要能
  * 区分"已经尽力了"和"还有一条没走过的路"。
+ *
+ * 另外附带 summarizeFrameRead 的测量值（能算多少算多少）：`merged` 只说
+ * "拼进去了"，`nodes_added` 与 `text_coverage` 才说"拼进去的是什么"。
  */
 function describeAutoAx(outcome) {
   const o = outcome && typeof outcome === 'object' ? outcome : {};
   if (o.merged) {
-    return { auto_ax: 'merged', frames_read: Number(o.framesRead) || 0 };
+    const h = { auto_ax: 'merged', frames_read: Number(o.framesRead) || 0 };
+    const s = o.summary && typeof o.summary === 'object' ? o.summary : null;
+    if (s) {
+      if (typeof s.nodes_added === 'number') h.nodes_added = s.nodes_added;
+      if (s.text_coverage != null) h.text_coverage = s.text_coverage;
+      if (Array.isArray(s.frames) && s.frames.length) {
+        // 只留 ref/src —— 调用方要的是"去哪读剩下那部分"，不是统计表。
+        h.frames = s.frames.map((f) => ({ ref: f.ref, src: f.src }));
+      }
+    }
+    return h;
   }
   if (o.error) {
     return { auto_ax: 'failed', reason: String(o.error) };
@@ -104,9 +164,39 @@ function mergeFrameContext(ctx, frames) {
   return out;
 }
 
+/**
+ * `frame-N` → 子帧序号 N。不是门节点 ref 时返回 null。
+ *
+ * 为什么需要：axExtractor.mergeFrameTrees 把每个跨进程帧挂成一个 gate 节点，
+ * id 就是 `frame-N`。它在页面里**没有对应元素**，所以"按 data-ai-id 找元素"
+ * 这条路对它永远失败 —— 实测 `ui.evaluate {frame_ref:"frame-1"}` 报
+ * frame_not_found，而语义树里明明写着 frame-1。树里出现的 ref 必须能用。
+ */
+function gateFrameIndex(aiId) {
+  const m = /^frame-(\d+)$/.exec(String(aiId == null ? '' : aiId));
+  if (!m) return null;
+  const n = Number(m[1]);
+  return Number.isInteger(n) && n >= 1 ? n : null;
+}
+
+/**
+ * 按 `frame-N` 从**子帧列表**（已排除主帧、保持 framesInSubtree 顺序）里取帧。
+ * 序号口径必须与 _readOopifFrames 完全一致：第 N 个非主帧，且读不到的帧也占号
+ * —— 两边不同步的话，`frame-2` 会指向另一个帧，比"找不到"更危险。
+ */
+function pickSubframe(subs, aiId) {
+  const idx = gateFrameIndex(aiId);
+  if (idx == null) return null;
+  const list = Array.isArray(subs) ? subs : [];
+  return list[idx - 1] || null;
+}
+
 module.exports = {
   summarizeOpaqueFrames,
   shouldAutoAx,
   describeAutoAx,
+  summarizeFrameRead,
   mergeFrameContext,
+  gateFrameIndex,
+  pickSubframe,
 };