@glittering0717/ai-browser 1.3.1 → 2.0.0

package/src/main/page_manager.js

@@ -10,6 +10,12 @@ import axExtractor from './axExtractor.js';
 import { NetworkMonitor, MAX_POST_DATA_SIZE } from './network_monitor.js';
 import { CanvasMonitor, isCanvasHookEnabled } from './canvas_monitor.js';
 import { buildCanvasHookSource } from './canvas_hook_source.js';
+// window.open("") + location 赋值模式的兼容垫片（主 world 源码，见文件头注释）
+import { WINDOW_OPEN_SHIM_SOURCE } from './window_open_shim_source.js';
+import { pickOpenedTab, openedTabGraceMs } from '../shared/opened_tab.js';
+// 动作回执自带的"页面到底动没动"三态，以及 ref 过期诊断（两个纯函数模块）。
+import { withEffectState, isTargetMiss as isTargetMissError } from '../shared/effect_state.js';
+import { newTracker, noteTree, diagnoseMissingRef } from '../shared/ref_epoch.js';
 import { diffValues, previewOf, safeByteLength, DEFAULT_SNAPSHOT_JS, DIFF_MAX_ENTRIES, evictOldest } from './snapshot_diff.js';
 import { withDeadline, actionDeadlineMs } from '../shared/deadline.js';
 import { DownloadMonitor } from './download_monitor.js';
@@ -23,6 +29,12 @@ import screenshotOpts from '../shared/screenshot_opts.cjs';
 // 跨进程子帧（OOPIF）判定与自动路由回执（纯函数）：默认读法检测到不可读
 // 子帧时自己补一次 AX 读取，调用方无需知道 ax:true 的存在。
 import frameProbe from '../shared/frame_probe.cjs';
+// 子帧内容读取器（在帧内执行）。选择器/上限/覆盖率口径全在那个文件里，
+// 这里只负责把它喂进去 —— 采集规则不该散落在 page_manager 的字符串里。
+import { buildFrameReadSource } from '../shared/frame_read_source.js';
+// 文字覆盖率（纯函数）：树里的正文字数 / 页面上看得见的字数。"读到了"必须
+// 是能算出来的结论，见 shared/doc_coverage.js 顶部的事故说明。
+import docCoverage from '../shared/doc_coverage.js';
 // ui.act target 形状体检（纯函数）：传了可见文字而不是 data-ai-id 时，
 // 入口就给可操作的错误，而不是等到选择器查空才说 "Target not found"。
 import refGuard from '../shared/ref_guard.cjs';
@@ -160,6 +172,8 @@ class PageManager {
     this._requestId = 0;
     this._wsClients = new Map();
     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
     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 存基线）
@@ -286,6 +300,64 @@ class PageManager {
       // Tag events with active tab
       this._broadcast(payload.event, payload.data || {});
     });
+
+    // === window.open 垫片的主进程侧（见 preload/bridge.cjs 的注释）===
+    // 站点模式：window.open("", "_blank") 先开空窗口，再把 location 赋成
+    // 真实地址。setWindowOpenHandler 那条路给不了页面可用的 window 引用
+    // （deny 后 window.open 返回 null），所以页面侧改为走这两条 IPC：
+    // ai:window_open 建真实 tab（空 url → about:blank 占位），
+    // ai:window_open_nav 把 location 赋值翻译成对该 tab 的导航。
+    // 同 sender 的 IPC 保序，nav 到达时 tab 必已建好。
+    ipcMain.on('ai:window_open', (_event, payload) => {
+      const p = payload || {};
+      const token = p.token;
+      if (!token) return;
+      const sourceTabId = this._tabIdForContents(_event.sender);
+      const url = typeof p.url === 'string' ? p.url : '';
+      const childId = this.newTab(url && url !== 'about:blank' ? url : null);
+      this._windowOpenTokens.set(token, { tabId: childId, sourceTabId });
+      // 与 setWindowOpenHandler 路径共用 _openedTabs：executeAction 的
+      // auto-follow（点击后 Agent 视角跟到新 tab）对两种打开方式一致。
+      if (sourceTabId !== null) {
+        this._openedTabs.set(sourceTabId, { id: childId, at: Date.now(), url: url || 'about:blank' });
+      }
+    });
+
+    ipcMain.on('ai:window_open_nav', (_event, payload) => {
+      const p = payload || {};
+      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。
+        view.webContents.loadURL(url).catch(() => {});
+      } else {
+        // tab 已被用户/Agent 关掉：赋值静默丢弃（真实浏览器里关掉的
+        // 窗口被赋 location 也是无人接收）。
+        console.warn('[window_open] nav target tab gone:', entry.tabId, url);
+      }
+    });
+
+    ipcMain.on('ai:window_open_close', (_event, payload) => {
+      const token = (payload || {}).token;
+      const entry = this._windowOpenTokens.get(token);
+      if (!entry) return;
+      this._windowOpenTokens.delete(token);
+      if (this._getView(entry.tabId)) this.closeTab(entry.tabId);
+    });
+  }
+
+  // webContents -> tabId 反查。window.open 垫片需要知道是哪个 tab 发起的
+  // （记 _openedTabs 供 auto-follow 用）；ipc-message 的 sender 就是发起
+  // tab 的 webContents。
+  _tabIdForContents(wc) {
+    if (!wc) return null;
+    for (const [tid, view] of this.tabs) {
+      if (view && view.webContents === wc) return tid;
+    }
+    return null;
   }
 
   _broadcast(eventType, data) {
@@ -636,10 +708,31 @@ class PageManager {
     // 此前这条通路只在 ax:true 下存在，而**没有任何地方告诉调用方 ax:true
     // 的存在** —— B站图文编辑器（正文在 OOPIF 里）因此隐形了两小时，agent
     // 得出"编辑器没加载"的错误结论。现在默认读法自己补上这一步。
-    if (!focusedOnly) await this._autoMergeOpaqueFrames(res, tid);
+    const frames = focusedOnly ? [] : await this._autoMergeOpaqueFrames(res, tid);
+    // 「这棵树读到了多少页面文字」—— 与 frame_hints 的 text_coverage（只看帧）
+    // 互补：那个回答"帧读够了吗"，这个回答"整页读够了吗"。
+    // 事故里 27 个节点、正文 0 字的页面，两个数字都会报警，而此前一个都没有。
+    this._annotateCoverage(res, frames);
+    // 记下"这一版树里有哪些 ref"。之后 act 报 target_not_found 时，靠它区分
+    // 「ref 过期了」（页面变过，重读树即可）和「ref 从来没对过」（改传参）。
+    // 见 shared/ref_epoch.js 顶部注释。
+    this._noteTreeRefs(tid, res && res.tree);
     return res;
   }
 
+  /** per-tab 的 ref 版本追踪器（懒建，避免动构造函数）。 */
+  _refTracker(tid) {
+    if (!this._refTrackers) this._refTrackers = new Map();
+    let t = this._refTrackers.get(tid);
+    if (!t) { t = newTracker(); this._refTrackers.set(tid, t); }
+    return t;
+  }
+
+  _noteTreeRefs(tid, tree) {
+    if (!tree) return;
+    try { noteTree(this._refTracker(tid), tree); } catch (_) { /* 追踪失败绝不影响读树 */ }
+  }
+
   // 把跨进程子帧的内容读出来、合并进默认（DOM）树。轻量：只读子帧，
   // 不重建主树，所以默认树的形状/id 全部保持原样。
   // 三种结局都写进 context.frame_hints（见 shared/frame_probe.describeAutoAx）：
@@ -647,12 +740,12 @@ class PageManager {
   // "还有一条没走过的路"。
   async _autoMergeOpaqueFrames(res, tid) {
     try {
-      if (!res || !res.tree || !res.context) return;
-      if (res.tree.__oopif_merged) return; // 幂等：合并过的树不重复做
+      if (!res || !res.tree || !res.context) return [];
+      if (res.tree.__oopif_merged) return []; // 幂等：合并过的树不重复做
       const summary = res.context.cross_process_frames;
-      if (!frameProbe.shouldAutoAx(summary)) return;
+      if (!frameProbe.shouldAutoAx(summary)) return [];
       const view = this._getView(tid);
-      if (!view) return;
+      if (!view) return [];
       const frames = await withDeadline(this._readOopifFrames(view, tid), 15000, 'get_tree(auto-oopif)');
       if (frames && frames.length) {
         res.tree = axExtractor.mergeFrameTrees(res.tree, frames);
@@ -665,7 +758,11 @@ class PageManager {
       res.context.frame_hints = frameProbe.describeAutoAx({
         merged: !!(frames && frames.length),
         framesRead: (frames || []).length,
+        // 测量值：光说 merged 等于只说"我试过了"。见 frame_probe.summarizeFrameRead。
+        summary: frameProbe.summarizeFrameRead(frames),
       });
+      // 返回帧记录：文字覆盖率要用它们的 text_chars 当分母的一部分。
+      return frames || [];
     } catch (e) {
       // 自动合并失败绝不拖垮主读法：默认树照常返回，只在 hints 里说明原因。
       // 调用方看到 failed 可以手动切 ax:true 重试。
@@ -674,9 +771,44 @@ class PageManager {
           error: (e && e.__deadline ? e.message + ' — the page main thread is likely blocked' : e && e.message) || String(e),
         });
       }
+      return [];
     }
   }
 
+  /**
+   * 「这棵树读到了多少页面文字」写进 context.page_coverage。
+   *
+   * 分子 = 树里所有正文 label 的字符数；分母 = 主文档 innerText 长度 +
+   * 每个跨进程帧里可见文字的字符数（帧那边在 frame_read_source 里已经算过）。
+   *
+   * 为什么必须分成"主文档 + 帧"两半：innerText 不跨 iframe，把两者混在一个
+   * 数里，任何一侧读漏都会被另一侧的平均值盖住 —— 泛雅那次就是这样，
+   * 主文档读得很好（外壳 100%），正文一个字没有，而没有任何数字表达这件事。
+   */
+  _annotateCoverage(res, frames, opts) {
+    if (!res || !res.tree || !res.context) return;
+    // 读失败时不算覆盖率：这一版树是 bridge 的兜底占位（只有一个装着异常文本的
+    // 节点），拿它当分子只会得出一个看似正常的小数字，把"没读成"包装成
+    // "页面内容少"。宁可让 page_coverage 缺席，让 read_ok/read_error 说话。
+    if (res.context.read_ok === false) return;
+    try {
+      const stats = res.context.stats || {};
+      const frameChars = (frames || []).reduce(
+        (s, f) => s + Number((f && f.stats && f.stats.text_chars) || 0), 0);
+      const summed = docCoverage.sumLabelChars(res.tree);
+      res.context.page_coverage = docCoverage.pageCoverage({
+        treeChars: summed.chars,
+        mainChars: Number(stats.text_chars) || 0,
+        sameOriginChars: Number(stats.same_origin_chars) || 0,
+        shadowChars: Number(stats.shadow_chars) || 0,
+        frameChars,
+        canvases: Number(stats.canvases) || 0,
+        // AX 树算的是**可访问名**，天生比 innerText 多（aria-label / alt / title）。
+        ax: !!(opts && opts.ax),
+      });
+    } catch (_) { /* 度量失败绝不影响读树 */ }
+  }
+
   // 登录态 / 登录墙自查。长任务里每个关键步骤前都可以问一次，成本只是走一次
   // extractPageContext（不建树）。
   //
@@ -881,9 +1013,15 @@ class PageManager {
             if (out.context[k] == null && ctx[k] != null) out.context[k] = ctx[k];
           }
           if (!out.context.session || !Object.keys(out.context.session).length) out.context.session = ctx.session || {};
-          if (out.context.stats && ctx.stats) Object.assign(out.context.stats, { inputs: ctx.stats.inputs, buttons: ctx.stats.buttons, links: ctx.stats.links, iframes: ctx.stats.iframes });
+          if (out.context.stats && ctx.stats) Object.assign(out.context.stats, { inputs: ctx.stats.inputs, buttons: ctx.stats.buttons, links: ctx.stats.links, links_without_href: ctx.stats.links_without_href, iframes: ctx.stats.iframes, text_chars: ctx.stats.text_chars });
         } catch (e) { /* context 补全失败不影响树 */ }
       }
+      // 分母（text_chars）补完了，这时候才算覆盖率。frames 由 _finishAxTree 带过来。
+      if (out) {
+        const framesForCoverage = out.__frames || [];
+        delete out.__frames;
+        this._annotateCoverage(out, framesForCoverage, { ax: true });
+      }
       return out;
     } catch (e) {
       if (e && e.__deadline) {
@@ -905,8 +1043,20 @@ class PageManager {
       if (main.context) {
         const mergedCtx = frameProbe.mergeFrameContext(main.context, frames);
         if (mergedCtx) Object.assign(main.context, mergedCtx);
+        // 与默认读法同一份回执：走 AX 这条路的调用方也要能看到"并进去几个节点、
+        // 帧里还有多少字没进树"。两条读法给不同口径的提示，等于让调用方猜。
+        main.context.frame_hints = frameProbe.describeAutoAx({
+          merged: true,
+          framesRead: frames.length,
+          summary: frameProbe.summarizeFrameRead(frames),
+        });
       }
     }
+    // 覆盖率在两条读法上是同一个口径（同一个函数），否则"ax:true 覆盖率 60%、
+    // 默认读法 40%"只会让调用方怀疑读数本身。
+    // 这里只把 frames 挂给调用方，**不能在这里算**：AX 的 context.stats 还要等
+    // getTreeViaAx 补完 DOM 侧字段（含 text_chars）才有分母。
+    if (main) main.__frames = frames || [];
     // #4: incremental diff — return only newly appeared / hidden interactive
     // nodes since the last ax read on this tab (feeds: small payload per scroll).
     if (opts.mode === 'diff') {
@@ -969,12 +1119,20 @@ class PageManager {
     })()`;
   }
 
-  // Read editable/interactive fields out of each out-of-process sub-frame via
+  // Read the **content** of each out-of-process sub-frame via
   // Frame.executeJavaScript (runs in that frame's own context). Returns
-  // [{ key, label, tree }] — pure mergeFrameTrees input. Stamps idempotent
-  // data-ai-id = `axf-{frameSeq}-{idx}` inside each frame so the act layer can
-  // (a) find the owning frame by testing which frame has `[data-ai-id=...]`, and
-  // (b) run its JS in that frame's own context (top querySelector can't reach OOPIF).
+  // [{ key, label, src, tree, context, stats }] — pure mergeFrameTrees input.
+  // Stamps idempotent data-ai-id = `axf-{frameSeq}-{idx}` inside each frame so
+  // the act layer can (a) find the owning frame by testing which frame has
+  // `[data-ai-id=...]`, and (b) run its JS in that frame's own context (top
+  // querySelector can't reach OOPIF).
+  //
+  // 采集规则在 shared/frame_read_source.js —— 这里原本内联了一份只认表单控件
+  // 的选择器，于是「没有可点元素」的 frame（正文、目录、成绩表）读出来是空的，
+  // 而回执还说 merged。事故与口径见那个文件顶部。
+  //
+  // frameSeq 在 try 之前自增：某个帧读不到时序号不能回填，否则树里的
+  // `frame-N` 会指向另一个帧（agents 会照着 ref 去操作，指错比没有更坏）。
   async _readOopifFrames(view, tabId) {
     try {
       const root = view.webContents.mainFrame;
@@ -987,45 +1145,15 @@ class PageManager {
         const key = 'frame-' + frameSeq;
         const prefix = 'axf-' + frameSeq + '-';
         try {
-          const dto = await frame.executeJavaScript(`(function(prefix){
-            if(!document||!document.body) return null;
-            var sel='[contenteditable],[role="textbox"],[role="combobox"],textarea,input[type="text"],input[type="title"],input[type="search"],button,[role="button"],a[href]';
-            var els=Array.prototype.slice.call(document.querySelectorAll(sel));
-            var out=[]; var idx=0;
-            for(var k=0;k<els.length;k++){
-              var e=els[k];
-              if(e.isContentEditable){ // skip editable boxes nested inside a contenteditable root
-                var inside=false;for(var p=e.parentElement;p;p=p.parentElement){if(p.isContentEditable&&p!==e){inside=true;break;}}
-              }
-              var r=e.getBoundingClientRect();
-              if(r.width<4||r.height<4)continue; // hidden
-              if(e.tagName==='BUTTON'||(e.getAttribute&&e.getAttribute('role')==='button')){} // buttons not relevant for read-editor; keep anyway
-              var ai=prefix+idx;
-              e.setAttribute('data-ai-id',ai);
-              var isEditable=e.isContentEditable||e.tagName==='TEXTAREA'||((e.tagName==='INPUT'));
-              var role;
-              if(e.isContentEditable)role='textbox';
-              else if(e.tagName==='TEXTAREA')role='textbox';
-              else if(e.tagName==='INPUT')role='textbox';
-              else if(e.tagName==='BUTTON'||e.getAttribute&&e.getAttribute('role')==='button')role='button';
-              else if(e.tagName==='SELECT'||e.getAttribute&&e.getAttribute('role')==='combobox')role='select';
-              else if(e.tagName==='A')role='link';
-              else role='textbox';
-              var label=e.getAttribute('aria-label')||e.getAttribute('placeholder')||e.getAttribute('title')||'';
-              if(!label&&e.getAttribute&&e.getAttribute('data-placeholder'))label=e.getAttribute('data-placeholder');
-              if(!label&&(e.tagName==='BUTTON'||(e.getAttribute&&e.getAttribute('role')==='button'))){label=(e.innerText||e.textContent||'').trim();}
-              if(!label&&e.tagName==='A'){label=(e.innerText||e.textContent||'').trim();}
-              var url=(e.tagName==='A'&&e.href)||(e.closest&&e.closest('a[href]')?e.closest('a[href]').href:'');
-              var editor_type=null;
-              if(e.isContentEditable)editor_type='richtext';
-              else if(e.tagName==='TEXTAREA')editor_type='textarea';
-              else if(e.tagName==='INPUT')editor_type='textbox';
-              out.push({id:ai,role:role,label: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)}});
-              idx++;
-            }
-            return out.length?out:null;
-          })(${JSON.stringify(prefix)})`);
-          if (!dto || !dto.length) continue;
+          const dto = await frame.executeJavaScript(buildFrameReadSource(prefix));
+          if (!dto) continue;
+          const nodes = Array.isArray(dto.nodes) ? dto.nodes : [];
+          const chars = (dto.stats && Number(dto.stats.text_chars)) || 0;
+          // 一个节点都没有、也没有可见文字 = 这个帧确实是空的，跳过。
+          // 有文字却一个节点都没读出来 = 内容在更深一层 iframe 里，或者结构完全
+          // 超出采集规则 —— 必须留下门节点 + 绝对 src，让调用方知道"这里有一块
+          // 内容没读到"；让它从树里彻底消失，就回到了这轮修的起点。
+          if (!nodes.length && chars < 20) continue;
           // 子帧里的"该填什么 / 错在哪"。顶层 extractPageContext 只能看顶层文档，
           // 而 B站图文的标题框、掘金编辑器都住在 OOPIF 里 —— 上下文扫描不跟着
           // 走一遍子帧，required_hints / validation_errors 就会在**真正需要它们
@@ -1042,19 +1170,39 @@ class PageManager {
             label: frame.name || ('frame-' + frameSeq),
             states: [],
             actions: [],
+            // 门节点带上**绝对** src：树里出现的东西，调用方就应该能直接用。
+            // 相对地址（/mooc2-ans/...）没法喂给 ui.new_tab / ui.navigate，
+            // 等于把"我知道内容在哪"变成一句废话。
+            ...(dto.url ? { src: dto.url } : {}),
             bounds: { x: 0, y: 0, width: 0, height: 0 },
-            children: dto.map((n) => ({
+            children: nodes.map((n) => ({
               id: n.id,
               role: n.role,
               label: n.label || '',
               ...(n.url ? { url: n.url } : {}),
-              states: n.editor_type ? ['editable=' + n.editor_type, 'focusable'] : ['focusable'],
+              states: n.states || (n.editor_type ? ['editable=' + n.editor_type, 'focusable'] : ['focusable']),
               ...(n.editor_type ? { editor_type: n.editor_type } : {}), // first-class, mirrors main AX path
-              actions: n.role === 'button' ? ['click', 'focus'] : ['click', 'focus', 'type', 'setContent', 'clear'],
+              // 只读内容块没有动作。此前一律给 ['click','focus','type','setContent','clear']，
+              // 于是每个段落都被报成"可以往里打字" —— agent 照着做，然后拿到一串
+              // 莫名其妙的失败。
+              actions: (n.states || []).indexOf('readonly') >= 0
+                ? []
+                : (n.role === 'button'
+                  ? ['click', 'focus']
+                  : ['click', 'focus', 'type', 'setContent', 'clear']),
               bounds: n.bounds,
             })),
           };
-          out.push({ key, label: frame.name || ('frame-' + frameSeq), tree, context: frameCtx });
+          out.push({
+            key,
+            label: frame.name || ('frame-' + frameSeq),
+            // frame.url 是 WebFrameMain 的绝对地址；dto.url 是页内 location.href。
+            // 两个都试，拿到的第一个能用的就写进 hints（走新标签打开时要用绝对地址）。
+            src: dto.url || frame.url || null,
+            tree,
+            context: frameCtx,
+            stats: dto.stats || null,
+          });
         } catch (e) { /* skip unreachable frame */ }
       }
       return out;
@@ -1187,33 +1335,75 @@ class PageManager {
    */
   async executeAction(action, target, params = {}, tabId) {
     const ms = actionDeadlineMs(action, params);
+    const tid = tabId !== undefined ? tabId : this.activeTab;
     try {
-      return await withDeadline(
+      const res = await withDeadline(
         this._executeActionInner(action, target, params, tabId),
         ms,
         `action:${action}`
       );
+      return this._annotateActResult(res, action, target, tid);
     } catch (e) {
       if (e && e.__deadline) {
         // 明确告诉 agent 两件事：① 它该重试/换策略；② 这个动作**可能已经部分生效**
         // （超时时指针可能已经按下、字符可能已经输入了一半）—— 后者必须说，否则
         // agent 会以为页面没被动过而直接重试，造成双倍输入。
-        return {
+        return this._annotateActResult({
           success: false,
           error: `${e.message} — the page's main thread is likely blocked; the action may have partially applied`,
           timed_out: true,
           deadline_ms: ms,
           action,
-        };
+        }, action, target, tid);
       }
       throw e;
     }
   }
 
+  /**
+   * 动作回执的最终加工：补 effect_state / retry，以及 ref 过期诊断。
+   *
+   * 为什么集中在这一层而不是各分支里：_executeActionInner 有三十多处 return，
+   * 逐个补等于逐个漏（这条教训在 ui.act 的超时兜底上已经吃过一次 —— 那里也是
+   * 因为挂住的位置不止一个才上移到唯一出口）。唯一出口是唯一可靠的覆盖方式。
+   */
+  _annotateActResult(res, action, target, tid) {
+    if (!res || typeof res !== 'object') return res;
+    const extras = {};
+    // 只有"目标找不到"这一种失败需要额外诊断 —— 其它错误跟 ref 无关。
+    // 判定用 effect_state.js 导出的同一个函数，避免这里和分类器各写一套正则。
+    const isTargetMiss = isTargetMissError(res.error);
+    if (isTargetMiss && target) {
+      try {
+        const d = diagnoseMissingRef(target, this._refTracker(tid));
+        extras.stale_ref = d.stale_ref;
+        extras.ref_epoch = d.ref_epoch;
+        extras.tree_epoch = d.tree_epoch;
+        extras.ref_diagnosis = d.reason;
+        // 具体的、可执行的下一步，直接给出来。诊断 hint 比通用错误文案更有用，
+        // 所以这里覆盖 effect_hint 的位置由 withEffectState 之后合并。
+        extras.ref_hint = d.hint;
+        // 关键：ref 类失败一律不能算"照原样重试是安全的"。三种处境（过期 / 从没
+        // 见过 / 树里有 DOM 里没有）都意味着**同一个调用再发一次一定还失败**，
+        // 只是失败原因不同。effect_state 仍然是 none（确实没副作用），
+        // 但 retry 必须改成 verify_first，否则等于告诉 agent"可以再来一遍"。
+        extras.retry = 'verify_first';
+      } catch (_) { /* 诊断失败不影响主回执 */ }
+    }
+    return withEffectState(res, extras);
+  }
+
   async _executeActionInner(action, target, params = {}, tabId) {
     const tid = tabId !== undefined ? tabId : this.activeTab;
     const view = this._getView(tid);
     if (!view) return { success: false, error: 'Tab not found' };
+    // 本次动作的开始时刻。用来判断"这个新标签是不是**这次**动作打开的" ——
+    // _openedTabs 里的条目可能来自更早的一次 window.open（例如 ui.evaluate 里
+    // 调 el.click() 触发的那种：它没有经过 act，所以没人消费那条记录）。
+    // 之前没有这个时间戳，陈旧条目会被下一次点击/悬停当成"我刚开了个标签"，
+    // 导致 opened_tab 报一个与本次操作无关的 tab（实测：hover 报出上一次
+    // 「进入学习」打开的 about:blank）。
+    const actionStartedAt = Date.now();
     // press 是唯一不要求目标的动作：快捷键通常挂在 document/window 上（删除节点、
     // 撤销重做、取消选中），发给"当前焦点"就是正确语义。
     // drag 给了显式起点坐标（params.from）时同样不要求目标 —— "从空白处起拖"正是
@@ -1251,7 +1441,7 @@ class PageManager {
           const res = await this._resolveClickByUrl(view, target, params.url, tid);
           if (!res || !res.success) return { ...(res || {}), success: false, opened_tab: null };
           // #3: 若此点击触发了 window.open → 新 tab，记录并默认接管焦点。
-          res.opened_tab = this._consumeOpenedTab(tid, params.keep_tab === true);
+          res.opened_tab = await this._awaitOpenedTab(tid, params.keep_tab === true, actionStartedAt, params, target);
           return res;
         } catch (e) {
           return { success: false, error: String((e && e.message) || e).slice(0, 200), opened_tab: null };
@@ -1260,7 +1450,10 @@ class PageManager {
       try {
         await this._ensureAxHandles(view, tid);
         const via = await this._cdpPointerTarget(view, action, target, tid);
-        if (via) return { success: true, clicked_via: via, target, opened_tab: this._consumeOpenedTab(tid, params.keep_tab === true) };
+        if (via) {
+          const opened = await this._awaitOpenedTab(tid, params.keep_tab === true, actionStartedAt, params, target);
+          return { success: true, clicked_via: via, target, opened_tab: opened };
+        }
       } catch (e) { /* fall through to preload */ }
     } else if (action === 'type' || action === 'setContent' || action === 'clear') {
       try {
@@ -1336,9 +1529,17 @@ class PageManager {
     }
 
     const preloadRes = await this._executeViaPreload(action, target, params, tid);
+    // preload 只在**顶层文档**里查 data-ai-id。目标住在跨进程帧里时，它必然
+    // 报 Target not found —— 而树里明明有那个 ref（focus 就是这样：click/type
+    // 各自有 OOPIF 分支，focus 没有）。这里补一次帧内原生动作，只在"找不到"
+    // 时触发，不去抢其它失败原因的处理权。
+    if (preloadRes && preloadRes.success === false && isTargetMissError(preloadRes.error)) {
+      const inFrame = await this._actInOwningFrame(view, action, target, tid);
+      if (inFrame) return inFrame;
+    }
     // preload 合成点击也可能触发 window.open → 新 tab，同样回报 opened_tab。
     if (action === 'click' && preloadRes && preloadRes.success) {
-      preloadRes.opened_tab = this._consumeOpenedTab(tid, params.keep_tab === true);
+      preloadRes.opened_tab = await this._awaitOpenedTab(tid, params.keep_tab === true, actionStartedAt, params, target);
       // 路径可区分：CDP 受信点击报 clicked_via='cdp-click'，回退路径报
       // 'preload-click'。两种都只报 success 的话，agent（和人）无从判断这一下
       // 到底是真实输入还是合成事件 —— 双发 bug 正是靠这个字段才暴露出来的。
@@ -1347,6 +1548,41 @@ class PageManager {
     return preloadRes;
   }
 
+  // === 帧内原生动作（跨进程子帧里那些"preload 够不到"的动作）===
+  // 只处理少数几个有明确原生等价物的动作，并且**只在顶层报 target miss 后**
+  // 调用。返回 null 表示"不是我该管的"，让原错误照常上报。
+  // 为什么不在这里补 type/paste/upload：它们各自有 OOPIF 分支（受信输入、
+  // 合成 ClipboardEvent、DOM.setFileInputFiles），抢过来只会绕开那些更可靠的实现。
+  async _actInOwningFrame(view, action, target, tabId) {
+    if (action !== 'focus' && action !== 'click') return null;
+    let frame = null;
+    try { frame = await this._owningFrameFor(view, target, tabId); } catch (_) { frame = null; }
+    if (!frame) return null;
+    const js = `(function(){
+      var el=${findRefExpr(JSON.stringify(String(target)))};
+      if(!el) return {__miss:true};
+      if(${JSON.stringify(action)}==='focus'){
+        try{ el.scrollIntoView({block:'nearest',behavior:'instant'}); }catch(e){}
+        try{ el.focus(); }catch(e){}
+        return {success:true, focused: document.activeElement===el};
+      }
+      try{ el.scrollIntoView({block:'center',behavior:'instant'}); }catch(e){}
+      try{ el.click(); }catch(e){ return {success:false, error:String(e&&e.message||e).slice(0,200)}; }
+      return {success:true};
+    })()`;
+    try {
+      const r = await frame.executeJavaScript(js);
+      if (!r || r.__miss) return null;
+      if (r.success === false) return { success: false, error: r.error || 'frame action failed', method: 'frame-js' };
+      const out = { success: true, target, method: 'frame-js' };
+      if (action === 'click') out.clicked_via = 'frame-native';
+      else out.focused = r.focused !== false;
+      return out;
+    } catch (e) {
+      return null;
+    }
+  }
+
   // === 只读取全量 node.value（ui.act {action:'get_value'}）===
   // 语义树里 node.value 只给前 200 Unicode code point；超长的节点带
   // value_fetch 提示，调用方用它取全量（支持 offset/limit 分页）。
@@ -1402,12 +1638,98 @@ class PageManager {
 
   // #3 helper: read & clear the "new tab opened by this source tab" entry.
   // Returns { id, url } or null. Unless keep===true, auto-activates the new tab.
-  _consumeOpenedTab(tid, keep) {
+  //
+  // startedAt（可选）：本次动作的开始时刻。只有**在这之后**记录的条目才算
+  // "这次动作开的"。没有它时，任何没被 act 消费的记录（例如 ui.evaluate 里
+  // el.click() 触发的 window.open）会一直挂在 map 里，被下一次点击/悬停
+  // 误当成"刚开的标签"。陈旧条目在读取时顺带清掉，避免长期堆积。
+  _consumeOpenedTab(tid, keep, startedAt) {
     const entry = this._openedTabs.get(tid);
     this._openedTabs.delete(tid);
-    if (!entry) return null;
-    if (keep !== true) this.setActive(entry.id);
-    return { id: entry.id, url: entry.url };
+    const mine = pickOpenedTab(entry, startedAt);
+    if (!mine) return null;
+    if (keep !== true) this.setActive(mine.id);
+    // 记录里的 url 是**建标签那一刻**的值。window.open("") 这条路上它永远是
+    // 'about:blank' —— 真实地址由随后的 ai:window_open_nav 才载入。直接回
+    // 'about:blank' 会让 agent 以为"打开了个空白页"，这恰恰是当初那个 bug 的样子。
+    // 所以这里读一次实时 URL：已经导航了就用真地址，还没导航就明说 pending。
+    let url = mine.url;
+    let pending = false;
+    try {
+      const view = this._getView(mine.id);
+      const live = view && view.webContents.getURL();
+      if (live && live !== 'about:blank') url = live;
+      // 仍然没有真实地址（占位页还没被导航）→ 明说 pending，而不是回一个
+      // 看起来像"空白页"的 about:blank。
+      if (!url || url === 'about:blank') pending = true;
+    } catch (_) { /* 读不到就维持记录里的值 */ }
+    const out = { id: mine.id, url };
+    if (pending) out.url_pending = true;
+    return out;
+  }
+
+  /**
+   * 点完**等一下**再收新标签记录（只给 click 用）。
+   *
+   * 为什么需要：实测（见 shared/opened_tab.js 顶部）点击派发后 105~119ms 才出现
+   * 新标签，而 act 在 10~15ms 就返回了 —— 回执里的 `opened_tab: null` 是**错的**，
+   * agent 会据此认为"点了没反应"，然后重试。
+   *
+   * 代价：不开标签的点击会等满宽限窗口（默认 150ms，可关）。所以这里是
+   * 「先看一眼，有就立刻返回」，只有确实没有记录时才进入轮询。
+   */
+  async _awaitOpenedTab(tid, keep, startedAt, params, target) {
+    const graceMs = openedTabGraceMs(params);
+    // 快路径 1：已经有属于本次动作的记录，零等待。
+    if (pickOpenedTab(this._openedTabs.get(tid), startedAt) || graceMs <= 0) {
+      return this._consumeOpenedTab(tid, keep, startedAt);
+    }
+    const view = this._getView(tid);
+    // 快路径 2：本 tab 已经开始原地导航 —— 站内跳转不会同时开新标签，别等。
+    // 这一类（点链接跳走）是最高频的点击，跳过它等于让绝大多数点击零额外成本。
+    if (view && view.webContents.isLoading()) {
+      return this._consumeOpenedTab(tid, keep, startedAt);
+    }
+    // 快路径 3：目标不是链接 → 不等。
+    // 实测代价：等待是加在**每一个**点击上的，点段落这种不导航的点击从 7ms 变成
+    // 261ms。而"点开新标签"在实际站点上几乎都发生在 <a> 上（window.open 的按钮
+    // 弹层也存在，但少），所以用 tagName 做闸门：探一次开销约几毫秒，换来把
+    // 250ms 的税从绝大多数点击上摘掉。
+    // 非链接的弹层场景由调用方显式传 opened_tab_wait_ms 打开等待。
+    const explicitWait = params && params.opened_tab_wait_ms !== undefined && params.opened_tab_wait_ms !== null;
+    if (!explicitWait && !(await this._targetIsLink(view, target, tid))) {
+      return this._consumeOpenedTab(tid, keep, startedAt);
+    }
+    const deadline = Date.now() + graceMs;
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 25));
+      if (pickOpenedTab(this._openedTabs.get(tid), startedAt)) break;
+      // 等待期间页面开始导航了，同样立刻收工。
+      if (view && view.webContents.isLoading()) break;
+    }
+    return this._consumeOpenedTab(tid, keep, startedAt);
+  }
+
+  /**
+   * 目标是不是 <a>。只用于决定"要不要为开新标签等一会儿"。
+   *
+   * 探不到（元素已被 SPA 重渲染掉、帧不可达）一律按"不是链接"处理：
+   * 宁可少等一次（回到原来的漏报），也不要为一个不确定的目标付 250ms。
+   */
+  async _targetIsLink(view, target, tid) {
+    if (!view || !target) return false;
+    try {
+      const owning = await this._owningFrameFor(view, target, tid);
+      const expr = `(function(){var el=${findRefExpr(JSON.stringify(String(target)))};` +
+        `return el?String(el.tagName||'').toUpperCase():null;})()`;
+      // 用 this.evaluate（与 _owningFrameFor 同一口径：直接给值），不要用
+      // _evaluateViaCdp —— 那里回的是 {result:{value}} 包裹，比一次就永远判成
+      // "不是链接"，闸门形同虚设（第一版就踩了这个）。
+      const tag = owning ? await owning.executeJavaScript(expr) : await this.evaluate(expr, tid);
+      return tag === 'A';
+    } catch (_) {
+      return false;
+    }
   }
 
   // #2: 按目标 URL 定位并点击链接 —— 通用替代"猜卡片里的 <a>"。顶层在
@@ -1612,7 +1934,8 @@ class PageManager {
   // 所以这里先看顶层，找不到再逐个帧找。返回 null 表示就在主帧里。
   async _owningFrameFor(view, aiId, tabId) {
     if (!aiId) return null;
-    if (/^axf-/.test(aiId)) return await this._owningFrame(view, aiId);
+    // `frame-N` 是合并门节点，页面里没有对应元素，别浪费一次顶层查询。
+    if (/^axf-/.test(aiId) || /^frame-\d+$/.test(aiId)) return await this._owningFrame(view, aiId);
     try {
       const inTop = await this.evaluate(
         `!!${findRefExpr(JSON.stringify(aiId))}`,
@@ -1629,6 +1952,13 @@ class PageManager {
   async _owningFrame(view, aiId) {
     const root = view.webContents.mainFrame;
     const frames = root && root.framesInSubtree ? root.framesInSubtree : [];
+    // 树里暴露的 `frame-N` 是合并出来的门节点（axExtractor.mergeFrameTrees 的
+    // gate），它在页面里**没有对应元素**。此前这里只会按 [data-ai-id] 找，于是
+    // `{frame_ref:"frame-1"}` 必然报 frame_not_found —— 树里写着 frame-1，用起来
+    // 说不存在。序号口径与 _readOopifFrames 一致（见 shared/frame_probe.pickSubframe）。
+    const subs = frames.filter((f) => f !== root);
+    const gateFrame = frameProbe.pickSubframe(subs, aiId);
+    if (gateFrame || frameProbe.gateFrameIndex(aiId) != null) return gateFrame;
     for (const frame of frames) {
       if (frame === root) continue;
       try {
@@ -2720,6 +3050,8 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
     // 导航阶段发出的 POST 全部丢失 —— agent 永远拿不到它们的请求体。
     // 关闭开关：AI_BROWSER_NETWORK_CAPTURE=0 或 ui.network_configure{enabled:false}。
     this._ensureNetworkCapture(tabId, view);
+    // window.open 垫片不在这里调：它返回的 Promise 要被下面的首次导航等
+    // （见文件末尾 navWhenShimReady），在这里提前调会消耗掉首次注入。
 
     // Mask automation fingerprint: remove Electron from UA
     view.webContents.setUserAgent(config.userAgent);
@@ -2729,7 +3061,7 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
       const childId = self.newTab(urlToOpen);
       // Track which source tab opened a new tab so `executeAction` can report the
       // resulting tab and auto-follow it. Generic (any target=_blank / window.open).
-      self._openedTabs.set(tabId, { id: childId, url: urlToOpen });
+      self._openedTabs.set(tabId, { id: childId, at: Date.now(), url: urlToOpen });
       return { action: 'deny' };
     });
 
@@ -2749,11 +3081,35 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
       // （configure({reload:true}) 可以补齐）。
       const install = () => { this._ensureCanvasHook(tabId, view).catch(() => false); };
       view.webContents.once('did-finish-load', install);
-      if (url) {
-        view.webContents.loadURL(url);
-      }
-    } else if (url) {
-      view.webContents.loadURL(url);
+    }
+    // window.open 垫片注入：CDP 命令在**未导航的空 webContents** 上会挂住
+    // （实测 Page.enable 都 1.5s 不 resolve —— renderer 没就绪，命令无人
+    // 处理）。所以先 load about:blank 把 renderer 垫起来，did-finish-load
+    // 后再发注入命令，最后才 loadURL 真实 URL —— 这样首屏 document 一定
+    // 带着垫片（addScriptToEvaluateOnNewDocument 注册后跨导航持久）。
+    // 占位 tab（window.open 的空窗口，url=null）就停在 about:blank 等
+    // location 赋值来导航；赋值到达时注入通常早已完成（源页面 ajax 往返
+    // 至少几十毫秒），基本不存在竞态。
+    const wc0 = view.webContents;
+    const targetUrl = url || null;
+    if (wc0 && !wc0.isDestroyed()) {
+      let proceeded = false;
+      const proceed = () => {
+        if (proceeded) return;
+        proceeded = true;
+        Promise.resolve(this._ensureWindowOpenShim(tabId, view)).finally(() => {
+          if (targetUrl && wc0 && !wc0.isDestroyed()) {
+            wc0.loadURL(targetUrl).catch(() => {});
+          }
+        });
+      };
+      // 兜底：about:blank 的 did-finish-load 万一来不了（renderer 异常、
+      // 视图尚未 attach 等），也不能把真实导航永久挂住——1.2s 后照常放行，
+      // 最坏退化成"首屏没有垫片"（与修复前一致），而不是打不开页面。
+      const guard = setTimeout(proceed, 1200);
+      if (guard.unref) guard.unref();
+      wc0.loadURL('about:blank').catch(() => {});
+      wc0.once('did-finish-load', () => { clearTimeout(guard); proceed(); });
     }
 
     // Force repaint after load — BrowserView content can be loaded but not
@@ -2976,6 +3332,12 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
       view.webContents.close();
     }
     this.tabs.delete(tabId);
+    // window.open 垫片记账：这个 tab 若是某次 window.open 的目标，token 已
+    // 失去意义（nav 到达也只会在上面打一行 warn），清掉防止 Map 无限增长。
+    for (const [token, entry] of this._windowOpenTokens) {
+      if (entry.tabId === tabId) this._windowOpenTokens.delete(token);
+    }
+    this._windowOpenShimTabs.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);
@@ -3411,6 +3773,54 @@ return {ok:true,name:file.name,size:file.size,via:via,host_sel:hostSel,clicked:c
     } catch (e) { /* mid-navigation / already-attached elsewhere; skip this tab */ }
   }
 
+  // window.open 垫片注入（见 window_open_shim_source.js 顶部注释）。
+  // contextIsolation 下 preload 改不了页面可见的 window.open，只能经
+  // Page.addScriptToEvaluateOnNewDocument 注入主 world。
+  //
+  // ⚠️ 必须在 renderer 就绪后调用：未导航的空 webContents 上 CDP 命令无人
+  // 处理会挂住（实测 Page.enable 1.5s 不 resolve）。newTab 的做法是先
+  // load about:blank，did-finish-load 后再调这里。
+  // 幂等：每个 tab 只注册一次（_windowOpenShimTabs 记账）；跨导航自动保留
+  // 正是 addScriptToEvaluateOnNewDocument 的语义，不需要重复注册。
+  _ensureWindowOpenShim(tabId, view) {
+    if (this._windowOpenShimTabs.has(tabId)) return Promise.resolve(true);
+    this._windowOpenShimTabs.add(tabId);
+    // async IIFE：注入要 await（Page.enable → addScript 有序），但函数本身
+    // 仍返回 Promise（调用方 .finally 等它）。
+    return (async () => {
+      try {
+        const wc = view.webContents;
+        if (!wc || typeof wc.debugger?.attach !== 'function') return false;
+        if (!this._cdpTabs.has(tabId)) {
+          wc.debugger.attach('1.3');
+          const entry = { wc, domains: new Set() };
+          this._cdpTabs.set(tabId, entry);
+          wc.debugger.on('message', (_event, method, params) => this._onCdpMessage(tabId, method, params));
+        }
+        // ⚠️ 必须先 Page.enable：Page 域 agent 未启用时，
+        // addScriptToEvaluateOnNewDocument 发出去会**挂住不回**（实测 1.5s
+        // 超时也不 resolve，首屏页面因此永远拿不到垫片）。enable 后再注入。
+        await withDeadline(
+          wc.debugger.sendCommand('Page.enable'),
+          1500,
+          'window_open_page_enable'
+        );
+        await withDeadline(
+          wc.debugger.sendCommand('Page.addScriptToEvaluateOnNewDocument', {
+            source: WINDOW_OPEN_SHIM_SOURCE,
+            runForSubFrames: true,
+          }),
+          1500,
+          'window_open_shim_inject'
+        );
+        return true;
+      } catch (e) {
+        console.error('[window_open] shim inject failed:', tabId, e && e.message);
+        return false;
+      }
+    })();
+  }
+
   // 抓包用的 Network 域：默认在 tab 创建后、首个导航前启用。
   // Network.enable 必须显式带 maxPostDataSize，否则 Chromium 可能不内联
   // request.postData（POST 请求体就拿不到，只能靠 getRequestPostData 补）。