@glittering0717/ai-browser 1.3.1 → 2.1.0

package/src/main/capability_probe.js

@@ -115,7 +115,12 @@ export const PROBE_JS = `(function(){
 
     scan(window, 'top');
     Array.prototype.forEach.call(document.querySelectorAll('iframe'), function(f, i) {
-      var rec = { index: i, src: (f.getAttribute('src') || '').slice(0, 80),
+      // src_attr 是原始属性（可能是相对地址，也可能根本没有），src 是解析后的
+      // 绝对地址 —— 后者才能直接喂给 ui.new_tab / ui.navigate。此前只报相对
+      // 地址，等于告诉调用方"内容在那"，却给了一个不能用的地址。
+      var rec = { index: i,
+                  src: String(f.src || ''),
+                  src_attr: (f.getAttribute('src') || '').slice(0, 120),
                   sameOrigin: false, innerElements: 0, innerCanvas: 0, innerButtons: 0 };
       try {
         var d = f.contentDocument;
@@ -151,9 +156,13 @@ export async function probeCapabilities(pageManager, opts = {}) {
   // 1. Semantic tree — the single most informative signal. A page whose whole UI
   //    is canvas shows up as a tiny tree; that is the tell.
   let tree = null;
+  let treeCtx = null;
   try {
     const res = await pageManager.getTree(false, tid);
     tree = res && res.tree;
+    // 保留 context：frame_hints 里写着"跨进程帧并进去多少、还剩多少没进树"，
+    // 那是"树薄"最直接的解释，不该只留在 get_tree 的回执里让探针重新猜一遍。
+    treeCtx = (res && res.context) || null;
   } catch (e) { /* getTree timeout on a busy page must not kill the probe */ }
 
   const flat = [];
@@ -185,7 +194,7 @@ export async function probeCapabilities(pageManager, opts = {}) {
     } catch (e) { /* capture disabled — not an error worth failing on */ }
   }
 
-  const route = recommend({ flat, dom, endpoints });
+  const route = recommend({ flat, dom, endpoints, coverage: (treeCtx && treeCtx.page_coverage) || null });
   return {
     ok: true,
     tab: tid,
@@ -205,6 +214,12 @@ export async function probeCapabilities(pageManager, opts = {}) {
       visible: (dom && dom.canvases) || [],
     },
     iframes: (dom && dom.iframes) || [],
+    // 树对跨进程帧的覆盖率（来自 get_tree 的回执，不是探针自己算的）。
+    // null = 这个页面没有跨进程帧，或者读树失败。
+    frame_hints: (treeCtx && treeCtx.frame_hints) || null,
+    // 整页文字覆盖率（树里的正文字数 / 主文档 + 帧里看得见的字数）。
+    // "树薄"到底薄到什么程度，由这个数字回答，而不是由探针猜原因。
+    page_coverage: (treeCtx && treeCtx.page_coverage) || null,
     app_globals: (dom && dom.globals) || [],
     endpoints,
     route,
@@ -301,11 +316,48 @@ export function rankAppGlobals(globals) {
     .sort((a, b) => b.score - a.score);
 }
 
+/**
+ * "树为什么这么薄" —— 三种归因必须分开说。
+ *
+ * 事故（2026-10-19，超星泛雅学习页）：树只有 27 个节点、13 个可操作，探针**自己
+ * 测到了** 1 个跨进程 iframe（`iframe: 跨进程 1 个`、`canvas 顶层级 0`），却在
+ * 结论里写 "the UI is largely canvas-rendered, so the tree cannot see the content"。
+ * 归因错了：内容看不见是因为它在 iframe 里，不是因为它画在 canvas 上。这个错误
+ * 直接把 agent 推向 L3 指针手势 —— 也就是"在 canvas 上瞎点"，而正确动作是去读
+ * 那个 frame。
+ *
+ * 原来的写法是模板串里无条件带上 "largely canvas-rendered"，只有前半句
+ * `${totalCanvas ? ...}` 受条件控制。**"树薄 = canvas" 曾经是唯一已知原因，
+ * 后来 iframe 成了更常见的原因，这句文案却没跟着改。**
+ *
+ * @param {{elements:number, actionable:number, canvasTop:number, canvasInFrames:number, opaqueFrames:Array}} input
+ */
+export function describeThinTree(input) {
+  const o = input && typeof input === 'object' ? input : {};
+  const elements = Number(o.elements) || 0;
+  const actionable = Number(o.actionable) || 0;
+  const canvasTop = Number(o.canvasTop) || 0;
+  const canvasInFrames = Number(o.canvasInFrames) || 0;
+  const canvas = canvasTop + canvasInFrames;
+  const frames = (Array.isArray(o.opaqueFrames) ? o.opaqueFrames : []).filter(Boolean);
+  const head = `only ${elements} elements (${actionable} actionable)`;
+
+  if (canvas > 0) {
+    return `${head} and ${canvas} canvas element(s) (${canvasTop} top-level, ${canvasInFrames} in frames) — the UI is largely canvas-rendered, so the tree cannot see the content`;
+  }
+  if (frames.length) {
+    const first = frames.find((f) => f && f.src) || frames[0];
+    const where = first && first.src ? ` (first: ${String(first.src).slice(0, 100)})` : '';
+    return `${head} and ${frames.length} cross-process iframe(s) the top document cannot read${where} — the content is inside those frames, NOT on a canvas; the tree merges their nodes, and the frame src is directly navigable`;
+  }
+  return `${head}, no canvas and no cross-process frame — the page is either genuinely sparse (a form, a stub) or still loading; verify with ui.screenshot or retry once it settles before concluding the tree cannot see the content`;
+}
+
 /**
  * The actual deliverable: which route to take, and WHY (with the evidence).
  * Every claim cites the number that produced it, so a caller can disagree.
  */
-function recommend({ flat, dom, endpoints }) {
+export function recommend({ flat, dom, endpoints, coverage }) {
   const routes = [];
   const iframes = (dom && dom.iframes) || [];
   const globals = (dom && dom.globals) || [];
@@ -313,6 +365,14 @@ function recommend({ flat, dom, endpoints }) {
   const frameCanvas = iframes.reduce((s, f) => s + (f.innerCanvas || 0), 0);
   const totalCanvas = topCanvas + frameCanvas;
   const sameOriginFrame = iframes.find((f) => f.sameOrigin);
+  // 跨进程、且**有尺寸**的帧：内容在另一个渲染进程里，顶层文档读不到。广告/埋点
+  // 帧通常是 0×0，不算。这是"树薄"最常见的真实原因（泛雅、B站图文、掘金都属这类）。
+  const opaqueFrames = iframes.filter((f) => {
+    if (!f || f.sameOrigin) return false;
+    const box = f.box;
+    if (!Array.isArray(box)) return true; // 拿不到尺寸时按"可能是内容帧"处理
+    return (Number(box[2]) || 0) > 0 && (Number(box[3]) || 0) > 0;
+  });
   const ranked = rankAppGlobals(globals);
   const graphObj = ranked.length ? ranked[0].g : null;
   // Say so explicitly when the top candidate is a library rather than a model:
@@ -363,10 +423,23 @@ const actionable = flat.filter((n) => (n.actions || []).some((a) => a === 'click
 const rich = flat.length >= 60 && roleSet.size >= 4 && actionable >= 10;
   routes.push({
     route: 'L2_semantic_tree',
-    preferred: !graphObj && rich,
+    // 内容藏在跨进程帧里时，树仍然是**唯一**的结构化通路（默认读法会自动把帧里
+    // 的节点并进来），所以它该被推荐 —— 此前这种页面上 recommended 是**空数组**，
+    // 调用方问"走哪条路"得到一个空答案。
+    preferred: !graphObj && (rich || (opaqueFrames.length > 0 && totalCanvas === 0)),
     why: rich
       ? `${flat.length} elements, ${roleSet.size} distinct roles, ${actionable} with a click/type action — targets can be found by role/label and driven by data-ai-id, no coordinates`
-      : `only ${flat.length} elements (${actionable} actionable)${totalCanvas ? ` and ${totalCanvas} canvas element(s)` : ''} — the UI is largely canvas-rendered, so the tree cannot see the content`,
+      // 树薄时，把**实测的覆盖率**接在归因后面：归因说明"为什么薄"，数字说明
+      // "薄到什么程度"。没有数字的归因，就是这次事故里的那句 canvas。
+      : describeThinTree({
+        elements: flat.length,
+        actionable,
+        canvasTop: topCanvas,
+        canvasInFrames: frameCanvas,
+        opaqueFrames,
+      }) + (coverage && coverage.percent != null
+        ? ` [tree carries ${coverage.percent}% of the page's visible text: ${coverage.tree_chars}/${coverage.page_chars} chars]`
+        : ''),
     evidence: {
       elements: flat.length,
       actionable,
@@ -376,10 +449,25 @@ const rich = flat.length >= 60 && roleSet.size >= 4 && actionable >= 10;
       // to conclude "no canvas, must be DOM" — the opposite of the truth.
       canvas_top: topCanvas,
       canvas_in_frames: frameCanvas,
+      // 同样的道理适用于 iframe：说"有几个帧"不够，要说"哪几个帧，地址是什么"。
+      cross_process_frames: opaqueFrames.length,
+      canvas_rendered: totalCanvas > 0,
     },
     how: 'ui.get_tree to read; ui.act with the returned data-ai-id to click/type/setContent',
   });
 
+  if (opaqueFrames.length && !rich) {
+    routes.push({
+      route: 'NOTE_cross_process_iframe',
+      preferred: false,
+      why: `${opaqueFrames.length} cross-process iframe(s) hold content the top document cannot read — the semantic tree splices their nodes in (context.frame_hints tells you how much actually made it), and .frames[].src is absolute`,
+      evidence: {
+        frames: opaqueFrames.slice(0, 4).map((f) => ({ src: f.src || null, box: f.box || null })),
+      },
+      how: 'ui.get_tree merges frame nodes automatically; if context.frame_hints.text_coverage is low, ui.new_tab / ui.navigate to frames[].src and read the frame as a top-level document',
+    });
+  }
+
   routes.push({
     route: 'L3_pointer_gestures',
     preferred: false,

package/src/main/index.js

@@ -7,6 +7,7 @@ import { startWSServer } from './ws_server.js';
 import { PageManager } from './page_manager.js';
 import { config } from '../shared/config.js';
 import { parseWatchdogTargets, isWatchdogEnabled } from '../shared/watchdog.js';
+import { wrapSetActive } from '../shared/tab_hooks.js';
 import { initErrorLog, recordError, markShutdown, getLogPath } from './error_log.js';
 import errorBanner from '../shared/error_banner.cjs';
 
@@ -299,6 +300,12 @@ let navStateInterval = null;
 let navStateWc = null;
 let networkWatchdog = null;
 let isQuitting = false;
+// 退出时固化会话 cookie 的一次性开关：cleanupAndQuit 分流用（见其注释），
+// 固化期间的其他重入调用被忽略，固化完成后经 _finishCleanup 继续退出。
+let cookiePersistDone = false;
+// 退出流程总开关：第一条退出路径（ui.quit / 关窗 / before-quit）置位后，
+// 其余路径全部忽略；固化完成回来时走 _finishCleanup 而不是再进这里。
+let cleanupStarted = false;
 
 // === Single instance lock — second launch just focuses the existing window ===
 const gotLock = app.requestSingleInstanceLock();
@@ -492,12 +499,13 @@ function createWindow() {
     wc.on('did-navigate-in-page', push);
     wc.on('page-title-updated', push);
   };
-  const origSetActive = pageManager.setActive.bind(pageManager);
-  pageManager.setActive = function (tabId) {
-    origSetActive(tabId);
+  // 包一层只为了挂「地址栏跟随」这块副作用，返回值必须原样透传 ——
+  // ws_server 的 ui.set_active_tab 靠它回 { ok }（2026-10-19 测到过包装吞掉
+  // 返回值导致 agent 收到空回执的事故，见 shared/tab_hooks.js 注释）。
+  wrapSetActive(pageManager, (tabId) => {
     wireNavState(tabId);
     pushNavState();
-  };
+  });
   wireNavState(pageManager.activeTab);
   // 兜底轮询：只覆盖上面事件没抓到的情况（低频，成本可忽略）
   navStateInterval = setInterval(pushNavState, 1500);
@@ -799,9 +807,86 @@ app.whenReady().then(() => {
   }
 });
 
+// Chromium 默认在退出时**清除会话 cookie**（无过期时间的那些）。扫码/账密
+// 登录产生的 JWT、SESSION 基本都是会话 cookie —— 于是 ai-browser 每次
+// ui.quit / 关窗重启都掉登录态，agent 侧表现为"重启后站点又让我登录"。
+// 退出前把它们逐个 set 成带远期过期时间的持久 cookie（值不变，只获得
+// 落盘资格；服务端本来就认的是 value，本地过期时间不影响校验）。
+// before-quit / window-all-closed / ui.quit 三条退出路径都经 cleanupAndQuit，
+// 在那里先等这一步做完再真正 app.quit()。
+async function persistSessionCookies() {
+  try {
+    const ses = session.fromPartition(config.viewPartition);
+    const all = await ses.cookies.get({});
+    const nowSec = Math.floor(Date.now() / 1000);
+    const horizon = nowSec + 400 * 24 * 3600; // ~13 个月，长于任何服务端会话
+    const isDurable = (c) => !!(c.expirationDate && c.expirationDate > nowSec + 7 * 24 * 3600);
+    const todo = all.filter((c) => !isDurable(c));
+    let n = 0;
+    for (let i = 0; i < todo.length; i++) {
+      const c = todo[i];
+      const host = (c.domain || '').replace(/^\./, '');
+      if (!host) continue;
+      const details = {
+        url: (c.secure ? 'https://' : 'http://') + host + (c.path || '/'),
+        name: c.name,
+        value: c.value,
+        path: c.path || '/',
+        secure: !!c.secure,
+        httpOnly: !!c.httpOnly,
+        expirationDate: horizon,
+      };
+      // 域 cookie（.example.com）要显式带 domain；host-only 的绝不能带，
+      // 带了会从"仅本主机"放宽成"子域共享"，是安全隐患。
+      if (c.domain && c.domain.startsWith('.')) details.domain = c.domain;
+      if (c.sameSite && c.sameSite !== 'unspecified') details.sameSite = c.sameSite;
+      try {
+        await ses.cookies.set(details);
+        n++;
+      } catch (e) {
+        console.error('[index] persist cookie failed:', c.name, e && e.message);
+      }
+      // 分批让出：Chromium 的 cookie store 是 grouped commit（几十毫秒一批），
+      // 一口气把全部 set 发完，提交永远追不上 —— app.quit() 一到，没提交的
+      // 全丢（实测 86 个 set 全部"成功"但磁盘只剩 2 个，2026-10-19）。
+      // 每 10 个停 100ms，让每一批都有机会落盘。
+      if (i % 10 === 9) await new Promise((r) => setTimeout(r, 100));
+    }
+    // 最后一组的 grouped commit 也要时间，等 2 秒再让 cleanupAndQuit 继续。
+    if (n > 0) {
+      await new Promise((r) => setTimeout(r, 2000));
+      console.log(`[index] persisted ${n} session cookies before quit`);
+    }
+  } catch (e) {
+    console.error('[index] persistSessionCookies failed:', e && e.message);
+  }
+}
+
 function cleanupAndQuit() {
-  if (isQuitting) return;
+  // cleanupStarted 防的是"多条退出路径同时触发"（ui.quit + window close +
+  // before-quit 可能叠着来），它必须在第一次进入时就置位；isQuitting 只被
+  // watchdog 等查询用。
+  if (cleanupStarted) return;
+  cleanupStarted = true;
   isQuitting = true;
+  // 先固化会话 cookie，再走原有收尾。异步等完成（通常几百毫秒到几秒）——
+  // 直接 app.quit() 会把还没提交的 cookies.set 全部打断，等于没固化。
+  // 注意：finally 回来的这次调用不能被 cleanupStarted 挡掉（第一版就是
+  // 这么写成死锁的 —— app.quit() 永远执行不到，app 退不掉），所以分流：
+  // 固化中的重入走 _finishCleanup，其他重入直接忽略。
+  if (!cookiePersistDone) {
+    cookiePersistDone = true;
+    persistSessionCookies()
+      .catch(() => {})
+      .finally(() => { _finishCleanup(); });
+    return;
+  }
+  _finishCleanup();
+}
+
+// 真正的收尾 + app.quit()。与 cleanupAndQuit 分开，避免防重入标志把
+// "固化完成后回来继续退出"这条必经之路也挡掉。
+function _finishCleanup() {
   // 收尾行：日志里**没有** shutdown 行，就说明上一次是硬退（崩溃 / 被 kill）——
   // 这是事后判断"到底有没有崩过"最直接的依据。
   try { markShutdown('cleanup'); } catch {}
@@ -827,4 +912,12 @@ function cleanupAndQuit() {
 }
 
 app.on('window-all-closed', cleanupAndQuit);
-app.on('before-quit', cleanupAndQuit);
+// before-quit 里 preventDefault：固化会话 cookie 是异步的（要等 cookies.set
+// 分批提交完），不拦住默认退出流程的话窗口/视图先被拆，固化就写一半。
+// cleanupStarted 之后的第二次 before-quit（我们自己 app.quit() 触发的）
+// 不再拦截，直接放行。
+app.on('before-quit', (e) => {
+  if (cleanupStarted) return;
+  e.preventDefault();
+  cleanupAndQuit();
+});

package/src/main/mcp_args.js

@@ -0,0 +1,122 @@
+// main/mcp_args.js — MCP 参数映射：对外分组，对内扁平
+//
+// 为什么要有这一层：
+// 2026-10 之前，工具的专属参数被**拍平**到顶层（browse_act 27 个顶层参数），
+// agent 每次要读完 27 个才能找到自己需要的 3 个，而且平面命名空间必然撞车。
+// 实际撞过：drag 的 dx/dy 与 wheel 的 delta_x/delta_y 都往 params.dx/dy 上写，
+// 对象字面量后者胜出 → `browse_act({action:'drag', dx:100})` 的 dx 被清成
+// undefined，拖拽按偏移量的用法静默失效（无异常、无日志）。
+//
+// 现在分成三层：
+//   schema（mcp_tools.js）  只暴露分组，agent 少读
+//   本文件                  分组 → 扁平，单一映射点
+//   page_manager            只认扁平（保持不动，避免第二套名字）
+//
+// ⚠️ 向后兼容是硬要求：**旧的扁平参数继续被接受**。已经写好的脚本和提示词
+// 不该因为我们的 API 整理而失效。分组只是"读起来更省"，不是"旧写法作废"。
+
+/** null/undefined 都退回 fallback；0 和 false 是有效值，必须保留。 */
+function pick(v, fallback) {
+  return v === undefined || v === null ? fallback : v;
+}
+
+/**
+ * browse_act 的参数映射。
+ * 返回 page_manager `ui.act` 认识的那套扁平 params。
+ */
+export function actParams(args = {}) {
+  const action = typeof args.action === 'string' ? args.action : '';
+  const click = args.click || {};
+  const read = args.read || {};
+  const press = args.press || {};
+  const wheel = args.wheel || {};
+  const drag = args.drag || {};
+
+  const params = {
+    text: args.text,
+    html: args.html,
+    value: args.value,
+    file: args.file,
+    timeout_ms: args.timeout_ms,
+    offset: pick(read.offset, args.offset),
+    limit: pick(read.limit, args.limit),
+    url: pick(click.url, args.url),
+    keep_tab: pick(click.keep_tab, args.keep_tab),
+    // 点完等新标签记录出现的时间（默认 150ms，0 = 不等）。见 page_manager._awaitOpenedTab。
+    opened_tab_wait_ms: pick(click.opened_tab_wait_ms, args.opened_tab_wait_ms),
+    key: pick(press.key, args.key),
+    keys: pick(press.keys, args.keys),
+  };
+
+  // drag 与 wheel 在 page_manager 里共用 dx/dy 两个字段，由 action 决定语义。
+  // 所以这里**必须按 action 二选一**，绝不能两个分支都无条件写 —— 那正是
+  // 上面说的覆盖事故的来源。
+  if (action === 'drag') {
+    params.to_target = pick(drag.target_to, args.to_target);
+    params.dx = pick(drag.dx, args.dx);
+    params.dy = pick(drag.dy, args.dy);
+    params.to_x = pick(drag.to && drag.to.x, args.to_x);
+    params.to_y = pick(drag.to && drag.to.y, args.to_y);
+    params.from_anchor = pick(drag.from && drag.from.anchor, pick(drag.from_anchor, args.from_anchor));
+    params.to_anchor = pick(drag.to && drag.to.anchor, pick(drag.to_anchor, args.to_anchor));
+    params.hold = pick(drag.hold, args.hold);
+    params.button = pick(drag.button, args.button);
+
+    // 起点：显式坐标（可无 target，用于在空白画布上起拖）
+    const from = drag.from;
+    if (from && from.x !== undefined && from.y !== undefined) {
+      params.from = { x: from.x, y: from.y };
+    } else if (args.from_x !== undefined && args.from_y !== undefined) {
+      params.from = { x: args.from_x, y: args.from_y };
+    }
+  } else if (action === 'wheel') {
+    params.dx = pick(wheel.dx, args.delta_x);
+    params.dy = pick(wheel.dy, args.delta_y);
+    params.hold = pick(wheel.hold, args.hold);
+  }
+
+  return params;
+}
+
+/**
+ * browse_network 的参数映射。
+ * list/clear/configure 走 ui.network_<op>，get 走 ui.network_get。
+ */
+export function networkParams(args = {}) {
+  const f = args.filters || {};
+  const inc = args.include || {};
+  const off = args.body_offset || {};
+  const cfg = args.configure || {};
+
+  const statusMin = pick(f.status_min, args.status_min);
+  const statusMax = pick(f.status_max, args.status_max);
+
+  return {
+    // list / clear / configure
+    tab: args.tab,
+    method: pick(f.method, args.method),
+    url_contains: pick(f.url_contains, args.url_contains),
+    status:
+      statusMin !== undefined || statusMax !== undefined
+        ? { min: statusMin, max: statusMax }
+        : undefined,
+    resource_type: pick(f.resource_type, args.resource_type),
+    state: pick(f.state, args.state),
+    started_after: pick(f.started_after, args.started_after),
+    started_before: pick(f.started_before, args.started_before),
+    limit: pick(f.limit, args.limit),
+    before_seq: pick(f.before_seq, args.before_seq),
+    enabled: pick(cfg.enabled, args.enabled),
+    capture_bodies: pick(cfg.capture_bodies, args.capture_bodies),
+    // get
+    network_id: args.network_id,
+    include_request_headers: pick(inc.request_headers, args.include_request_headers),
+    include_request_body: pick(inc.request_body, args.include_request_body),
+    include_response_headers: pick(inc.response_headers, args.include_response_headers),
+    include_response_body: pick(inc.response_body, args.include_response_body),
+    include_sensitive_headers: pick(inc.sensitive_headers, args.include_sensitive_headers),
+    body_limit: pick(inc.body_limit, args.body_limit),
+    request_body_offset: pick(off.request, args.request_body_offset),
+    response_body_offset: pick(off.response, args.response_body_offset),
+  };
+}