@glittering0717/ai-browser 1.2.1 → 1.3.0

package/src/shared/config.js

@@ -12,12 +12,18 @@ const DEFAULT_UA =
 export const config = {
   // WebSocket JSON-RPC server + MCP auto-launch probe port
   wsPort: Number(process.env.AI_BROWSER_PORT) || 9223,
+  // Loopback-only by default: the JSON-RPC port has NO authentication, so
+  // binding 0.0.0.0 would let every host on the local network drive the
+  // browser and its logged-in sessions. Set AI_BROWSER_WS_HOST=0.0.0.0 only
+  // behind a firewall you trust, and know that the protocol itself is open.
+  wsBindHost: process.env.AI_BROWSER_WS_HOST || '127.0.0.1',
   // Electron userData dir — session/cookie persistence survives restart
   userDataDir: process.env.AI_BROWSER_USER_DATA || path.join(os.homedir(), '.ai-browser'),
   // Spoofed UA to mask the automation fingerprint
   userAgent: process.env.AI_BROWSER_UA || DEFAULT_UA,
-  // Height of the in-app tab strip below the window title bar
-  tabBarHeight: 36,
+  // Height of the in-app tab strip below the window title bar.
+  // 36px = tab row, 38px = toolbar row (address bar + back/forward/reload/stop).
+  tabBarHeight: 36 + 38,
   // The session every tab's BrowserView uses. **Must stay a single source of
   // truth**: session-level hooks (will-download, permission requests) are
   // installed on `session.fromPartition(viewPartition)`. Hooking

package/src/shared/deadline.js

@@ -78,6 +78,12 @@ export function actionDeadlineMs(action, params = {}) {
   } else if (action === 'clear') {
     // clear 要走编辑器状态提交与回读校验（多处 80~150ms 等待）。
     need = Math.max(need, 20000);
+  } else if (action === 'paste') {
+    // paste 本身不逐字符输入，但大型 HTML 经编辑器管线转换（Draft.js 的
+    // DraftPasteProcessor / ProseMirror 的 transformPastedHTML）可能很慢，
+    // 之后还有 350ms 等待 + 回读校验。按 payload 大小给余量。
+    const payload = Math.max(String(p.html || '').length, String(p.text || '').length);
+    need = Math.max(need, 20000 + payload / 4);
   }
 
   const env = Number(process.env.AI_BROWSER_ACTION_TIMEOUT_MS);

package/src/shared/deep_active.cjs

@@ -0,0 +1,31 @@
+'use strict';
+// src/shared/deep_active.cjs —— 「真正的焦点元素」表达式。
+//
+// 为什么需要它：`document.activeElement` 在 Web Component 里只到**宿主**为止。
+// 焦点实际在 `<bili-rich-text>` 的 shadow root 里那个 contenteditable 上，但
+// `document.activeElement` 返回的是 `bili-rich-text` 宿主本身，宿主上没有内容
+// （innerText 为空），于是所有"读回输入内容再和目标比对"的校验全部读到空串。
+//
+// 后果不是"慢"或"看不清"，而是**假阴性**：内容明明打进去了，回执却报
+// `Input not verified / actual_chars: 0`。调用方（尤其 agent）看到这个结论会
+// 再打一次，结果是**重复输入**——比直接报错更糟，因为它看起来像"上次没成功"。
+// 实测（2026-10-17，B站 opus 详情页评论框）：type 返回失败、actual_chars=0，
+// 而回读 value 是完整的一句话。
+//
+// 修法：沿 `shadowRoot.activeElement` 一路下钻，取最里层的那个。
+// 这条链是浏览器自己维护的焦点路径，不是猜 —— 每一层都是**该树内**的 activeElement。
+//
+// 返回值是一个**页面内可执行的 JS 表达式字符串**（不是函数），因为这些调用点
+// 全部是拼进 `executeJavaScript` 的一行脚本里，统一用表达式才不用改它们的形状。
+function deepActiveExpr() {
+  return '(function(){' +
+    'var e=null;try{e=document.activeElement}catch(x){return null}' +
+    // 防御死循环：shadow 嵌套深度有限，但页面可以自己构造循环引用。
+    'var g=0;while(e&&e.shadowRoot&&e.shadowRoot.activeElement&&g++<10){e=e.shadowRoot.activeElement}' +
+    'return e})()';
+}
+
+// 同源 iframe 里的焦点：顶层 document.activeElement 是 <iframe> 元素本身，
+// 这条链进不去（跨进程更进不去）。调用方要区分"在帧里"时自己判 tagName 即可，
+// 这里不多导出一个口径 —— 两处判断同一件事迟早会不一致。
+module.exports = { deepActiveExpr };

package/src/shared/error_banner.cjs

@@ -0,0 +1,43 @@
+// shared/error_banner.cjs — 主进程异常横幅的文案装配（纯函数，可在 vitest 里直接测）。
+//
+// 为什么单独一个文件：横幅内容有两条硬要求，都值得被钉住 ——
+//   ① **一行**。横幅只有 34px 高，异常消息里带换行（多行栈、带 \n 的 Error.message）
+//      会把文字挤没，用户看到一片红却读不到原因。
+//   ② **必须带日志路径**。横幅是提醒，不是全部信息：真正的栈在 error.jsonl 里。
+//      只写"出错了"等于把人重新推回"点掉之后无从查证"的老问题。
+//
+// 这些逻辑放在 main/index.js 里就没法测了（那个文件 import electron）。
+
+'use strict';
+
+const MAX_DETAIL = 220;
+const MAX_LOG_PATH = 120;
+
+// 压成一行 + 截断。用省略号而不是硬切，读的人才知道后面还有内容。
+function oneLine(input, max) {
+  const s = String(input === undefined || input === null ? '' : input)
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!s) return '';
+  if (s.length <= max) return s;
+  return s.slice(0, Math.max(0, max - 1)) + '…';
+}
+
+/**
+ * @param {{detail?: string, logPath?: string, at?: string, count?: number}} input
+ * @returns {{title: string, detail: string, log_path: string, at: string, count: number}}
+ */
+function buildBannerPayload(input) {
+  const src = input || {};
+  return {
+    title: 'AI Browser 主进程异常',
+    detail: oneLine(src.detail, MAX_DETAIL) || '(没有消息)',
+    // 路径也压一行：userData 可能被 AI_BROWSER_USER_DATA 指到很深的目录
+    log_path: oneLine(src.logPath, MAX_LOG_PATH),
+    at: src.at || new Date().toISOString(),
+    // 连续报错时横幅不叠加，只把次数写进角标 —— 一屏红块比一行红更烦人
+    count: Number(src.count) > 0 ? Math.floor(Number(src.count)) : 1,
+  };
+}
+
+module.exports = { buildBannerPayload, MAX_DETAIL };

package/src/shared/find_ref.cjs

@@ -0,0 +1,44 @@
+'use strict';
+// shared/find_ref.cjs — 按 data-ai-id 找元素，**穿透影子根**。
+//
+// 为什么不能只用 document.querySelector：shadow boundary 是硬边界，顶层查询进不去。
+// Web Component 里的元素（B站 opus 的 <bili-comments>、YouTube 的 <ytd-*>、
+// 各设计系统的 <ui-*>）即使抽取层已经写了 data-ai-id，顶层也查不到 —— 报出来只是
+// "no element with data-ai-id=..."，读起来像"元素不存在"，实际是"查询路径够不着"。
+// 实测 2026-10-17：B站帖子详情页的评论输入框整个在 bili-comments 的 shadow root 里，
+// 抽取层补了下探（extractor.cjs 的 childrenOf）之后，解析这一侧也必须跟着穿透，
+// 否则就是"树里有、点不动"。
+//
+// 两半各自有存在的理由：
+//   findRef     —— 运行时函数，给能在页面里直接跑的代码用（preload/actions.cjs 自己
+//                  那份等价实现就是它，故意不跨界 require，避免一处路径写错连带
+//                  整个 preload 起不来）。
+//   findRefExpr —— 字符串表达式，给主进程"拼注入脚本"的地方用。返回自包含表达式，
+//                  所以可以原地替换 `document.querySelector(...)`，不需要在每个
+//                  IIFE 里补前置声明（这样的地方有十几处，漏一处就是一处静默失效）。
+
+function findRefExpr(idJsExpr) {
+  return "(function(id){var f=function(r){var e=null;"
+    + "try{e=r.querySelector('[data-ai-id=\"'+id+'\"]')}catch(x){e=null}"
+    + "if(e)return e;"
+    + "var a;try{a=r.querySelectorAll('*')}catch(x){return null}"
+    + "for(var i=0;i<a.length;i++){var s=a[i].shadowRoot;if(!s)continue;var h=f(s);if(h)return h}"
+    + "return null};return f(document)})(" + idJsExpr + ")";
+}
+
+// 在**某个子树内**穿透影子根找一个后代（按选择器）。
+//
+// 为什么还需要这个：找到编辑器外壳（例如 B站 的 <bili-rich-text> 宿主）之后，
+// 真正的 contenteditable 往往在它自己的 shadow root 里 —— `el.querySelector(
+// '[contenteditable=true]')` 同样不跨边界，于是"清空校验"读到空、把已经清干净
+// 的编辑器判成"没清掉"，接着又删一遍。读回口径必须和定位口径一样深。
+function findDescExpr(rootJsExpr, selectorJsExpr) {
+  return "(function(root,sel){var f=function(r){var e=null;"
+    + "try{e=r.querySelector(sel)}catch(x){e=null}"
+    + "if(e)return e;"
+    + "var a;try{a=r.querySelectorAll('*')}catch(x){return null}"
+    + "for(var i=0;i<a.length;i++){var s=a[i].shadowRoot;if(!s)continue;var h=f(s);if(h)return h}"
+    + "return null};return f(root)})(" + rootJsExpr + "," + selectorJsExpr + ")";
+}
+
+module.exports = { findRefExpr, findDescExpr };

package/src/shared/frame_probe.cjs

@@ -0,0 +1,112 @@
+// src/shared/frame_probe.cjs — 跨进程子帧（OOPIF）探测的纯函数部分
+//
+// 背景（B站图文编辑器隐形两小时的事故）：站点把富文本编辑器放进跨进程
+// iframe。同源 DOM 通路（preload extractor 的 contentDocument 递归）对
+// OOPIF 恒返回 null，于是那部分内容在默认语义树里**完全不存在** —— 不是
+// "读出来是空的"，是连占位都没有。能救场的只有 AX 路径（getFullAXTree
+// 走 CDP，天生跨帧），但调用方无从知道该切过去。
+//
+// 本模块只放纯函数：探测本身在 extractor 里（要 DOM），判定与摘要放这里
+// （要可单测，且 page_manager 的自动路由要用同一把尺）。
+
+'use strict';
+
+/**
+ * 汇总 extractor 收集到的不可读子帧。
+ * @param {Array<{id:string,src:string,width:number,height:number}>} frames
+ * @returns {{count:number, visible_count:number, suggestion:string|null}}
+ */
+function summarizeOpaqueFrames(frames) {
+  const list = Array.isArray(frames) ? frames.filter((f) => f && typeof f === 'object') : [];
+  const visible = list.filter((f) => (f.width || 0) > 0 && (f.height || 0) > 0);
+  if (!list.length) {
+    return { count: 0, visible_count: 0, suggestion: null };
+  }
+  return {
+    count: list.length,
+    visible_count: visible.length,
+    // 建议文案里必须出现 ax:true —— 那是唯一的补救通路，且此前无任何地方
+    // 告诉调用方它存在。
+    suggestion: 'page has cross-process iframe(s) whose content is invisible to the default DOM read path — retry with get_tree {ax:true} (CDP Accessibility reads across frames)',
+  };
+}
+
+/**
+ * 是否值得为这批帧自动补一次 AX 读取。
+ * 判定故意保守：只有"确有可见的不可读帧"才自动路由。不可见的帧（width/height
+ * 为 0，通常是埋点/广告帧）不值得让每次 get_tree 都多付一次 CDP 往返。
+ */
+function shouldAutoAx(summary) {
+  return !!(summary && typeof summary.visible_count === 'number' && summary.visible_count > 0);
+}
+
+/**
+ * 自动 AX 读取的结果如何写进 context.frame_hints。
+ * 三种结局分开说：合并成功 / 合并没有新内容 / AX 本身失败。调用方需要能
+ * 区分"已经尽力了"和"还有一条没走过的路"。
+ */
+function describeAutoAx(outcome) {
+  const o = outcome && typeof outcome === 'object' ? outcome : {};
+  if (o.merged) {
+    return { auto_ax: 'merged', frames_read: Number(o.framesRead) || 0 };
+  }
+  if (o.error) {
+    return { auto_ax: 'failed', reason: String(o.error) };
+  }
+  return { auto_ax: 'no-new-content' };
+}
+
+/**
+ * 把子帧读到的"该填什么 / 错在哪"合进顶层 context。
+ *
+ * 为什么需要：extractPageContext 只在顶层文档里扫描，而真正要填的字段常常在
+ * 跨进程子帧里（B站图文的标题框、掘金编辑器）。于是 required_hints 和
+ * validation_errors 会在**最需要它们的那一类页面上**恰好为空 —— 这比没有这个
+ * 字段更糟，因为调用方会读成"这页没有必填项"。
+ *
+ * 纯函数：不读 DOM、不改入参。子帧来源的条目带 frame 字段，调用方能看出它
+ * 不是顶层文档说的。
+ */
+function mergeFrameContext(ctx, frames) {
+  const base = ctx && typeof ctx === 'object' ? ctx : {};
+  const hints = Array.isArray(base.required_hints) ? base.required_hints.slice() : [];
+  const ves = Array.isArray(base.validation_errors) ? base.validation_errors.slice() : [];
+  const seenHint = new Set(hints);
+  const seenVE = new Set(ves.map((e) => (e && e.near ? e.near : '') + '\u0000' + ((e && e.text) || '')));
+  let added = 0;
+  for (const f of frames || []) {
+    const fc = f && f.context;
+    if (!fc) continue;
+    const where = f.key || f.label || 'subframe';
+    for (const h of fc.required_hints || []) {
+      const t = String(h || '').trim();
+      if (!t || seenHint.has(t)) continue;
+      seenHint.add(t);
+      hints.push(t);
+      added += 1;
+    }
+    for (const e of fc.validation_errors || []) {
+      const text = String((e && e.text) || '').trim();
+      if (!text) continue;
+      const near = String((e && e.near) || '');
+      const key = near + '\u0000' + text;
+      if (seenVE.has(key)) continue;
+      seenVE.add(key);
+      ves.push({ text, near, frame: where });
+      added += 1;
+    }
+  }
+  if (!added) return null;
+  const out = {};
+  if (hints.length) out.required_hints = hints.slice(0, 40);
+  if (ves.length) out.validation_errors = ves.slice(0, 30);
+  out.frame_context_merged = added;
+  return out;
+}
+
+module.exports = {
+  summarizeOpaqueFrames,
+  shouldAutoAx,
+  describeAutoAx,
+  mergeFrameContext,
+};

package/src/shared/hit_point.cjs

@@ -0,0 +1,80 @@
+'use strict';
+// findRefExpr 是这里的地基：定位本身也得能穿透 shadow，否则连 el 都拿不到，
+// 命中判定再对也没用（"树里有、点不动"）。
+const { findRefExpr } = require('./find_ref.cjs');
+
+// shared/hit_point.cjs — "指针落在这个坐标上，到底会命中谁"，**穿透影子根**。
+//
+// 为什么不能只用 document.elementFromPoint：它和 querySelector 一样，被 shadow
+// boundary 挡住 —— 对影子内部的元素，它返回的是**宿主**（离目标最近的那个
+// 自定义元素），不是元素本身。
+//
+// 实测证据（2026-10-18，B站 视频页评论区，整块装在 <bili-comments> 的 shadow 里）：
+//   树里报的 bounds => {x:733,y:377,w:24,h:24}     ← 坐标本身是准的
+//   document.elementFromPoint(745,389) => bili-comments   ← 宿主
+//   containsHit => false
+// 于是"点击前先证明坐标会落在目标上"这道校验对影子内部元素**恒为假**，
+// 点击只能回退到 preload 的 el.click()（非受信合成事件）。这在 CKEditor /
+// ProseMirror / Draft.js 之类只认真实指针序列的编辑器上会直接失效，
+// 而且"回退"这个事实不会出现在返回里 —— 看着成功，机制已经降级了。
+//
+// 修法：命中后逐级下钻。`ShadowRoot` 实现了 `DocumentOrShadowRoot`，所以
+// `shadowRoot.elementFromPoint(x,y)` 是标准 API（不是 hack），坐标与
+// document 版本同为视口坐标。一直钻到没有 shadowRoot 或钻不动为止。
+//
+// 配套的第二处修正：判定"命中即目标"必须用**含 shadow 的包含关系**。
+// `Node.contains()` 不是 shadow-including 的 —— 隔着一层 shadow 它照样返回
+// false（影子树是独立的 node tree）。上溯要写 `parentNode || ShadowRoot.host`。
+//
+// 隔离实验（tools/_oneoff/shadow_hittest.html + shadow_hittest_probe.cjs）：
+//   A 裸元素        flat=A-plain  deep=A-plain  旧判定 true  新判定 true
+//   B 一层 shadow   flat=DIV(宿主) deep=B-inner  旧判定 false 新判定 true
+//   C 两层 shadow   flat=DIV(宿主) deep=C-deep   旧判定 false 新判定 true
+//   D shadow 内被盖 flat=DIV       deep=DIV      旧判定 false 新判定 false ← 阴性仍守住
+// 新判定是旧判定的严格超集：任何原本为真的情形仍为真（命中链是目标的祖先链），
+// 只是把"隔着 shadow 其实命中了"这一整类假阴性补回来。
+
+// 下钻层数上限：防御性。真实页面不会嵌套 32 层 shadow，但万一某页自己套娃，
+// 宁可停下返回宿主的命中结果，也不要在页面里转不出来（这个 JS 是注入到页面
+// 上下文里同步跑的，死循环等于页面卡死）。
+const MAX_DEPTH = 32;
+
+// 最深命中元素。传进来的 x/y 是**已求值**的 JS 表达式字符串（例如 "745" 或 "c.x"）。
+function deepHitExpr(xJs, yJs) {
+  return '(function(x,y){var h=null;try{h=document.elementFromPoint(x,y);}catch(e){h=null}' +
+    'var g=0;' +
+    'while(h&&h.shadowRoot&&g++<' + MAX_DEPTH + '){' +
+    'var n=null;try{n=h.shadowRoot.elementFromPoint(x,y);}catch(e){n=null}' +
+    'if(!n||n===h)break;h=n;}' +
+    'return h;})(' + xJs + ',' + yJs + ')';
+}
+
+// 含 shadow 的"anc 是不是 n 的（含自身）祖先"。上溯时遇到 ShadowRoot 就跳到 host。
+function shadowAncestorOfExpr(ancJs, nodeJs) {
+  return '(function(anc,n){var c=n,g=0;while(c&&g++<128){if(c===anc)return true;' +
+    'c=c.parentNode||c.host||null;}return false;})(' + ancJs + ',' + nodeJs + ')';
+}
+
+// 坐标会不会落在 el 上。el 用 data-ai-id 定位（本身已穿透 shadow，见 find_ref.cjs）。
+// 判定：最深命中元素 === el，或 el 是它的含 shadow 祖先。
+// **不能**反过来接受 hit.contains(el)：那等于"父元素当然包含子元素"，会把
+// "按在了外层容器上"这种失败情形原样放行（拖拽连接点那处踩过，见 page_manager）。
+function hitTestExpr(idJs, xJs, yJs) {
+  return '(function(){var el=' + findRefExpr(idJs) + ';if(!el)return false;' +
+    'var h=' + deepHitExpr(xJs, yJs) + ';if(!h)return false;' +
+    'return ' + shadowAncestorOfExpr('el', 'h') + ';})()';
+}
+
+// "这个点上实际是哪个元素" —— 用于回执/错抓检测。
+// 返回 {el:"TAG cls", id:最近一个带 data-ai-id 的含 shadow 祖先的 id} 或 null。
+// 原来用 e.closest('[data-ai-id]')，同样跨不过 shadow：影子内部的元素 closest
+// 走到影子树顶就停，永远返回 null，于是"抓错节点"的检测被静默跳过。
+function hitInfoExpr(xJs, yJs) {
+  return '(function(){var e=' + deepHitExpr(xJs, yJs) + ';if(!e)return null;' +
+    'var c=e,id=null,g=0;' +
+    'while(c&&g++<128){if(c.getAttribute){var v=c.getAttribute("data-ai-id");if(v){id=v;break;}}' +
+    'c=c.parentNode||c.host||null;}' +
+    'return {el:(e.tagName||"")+" "+(typeof e.className==="string"?e.className:"").slice(0,60),id:id};})()';
+}
+
+module.exports = { deepHitExpr, hitTestExpr, hitInfoExpr, shadowAncestorOfExpr, MAX_DEPTH };

package/src/shared/input_verify.js

@@ -0,0 +1,47 @@
+// 输入校验用的文本归一化。
+//
+// 为什么需要它：`ui.act {action:'type'|'setContent'}` 走 CDP 受信键入，输完之后要
+// 回读可编辑区内容，确认"字真的打出去了"。回读来的文本和输入的目标文本不会逐字节
+// 相等 —— 富文本编辑器会按自己的排版规则重写内容（最常见的是把一个语义换行渲染成
+// 一串 \n）。直接逐字比对会让**已经成功**的输入被判成失败，回一个
+// `cdp-input-failed`，调用方据此重试或放弃。这属于谎报，是本项目最忌讳的一类问题。
+//
+// 用法：
+//   normalizeInputText(s)  —— 校验主口径：忽略排版空白 + 压缩连续换行
+//   skeletalInputText(s)   —— 兜底口径：连换行一起剥，只用于判断"内容有没有落上去"
+//
+// 设计取舍（重要）：绝不能简单粗暴地把 \s 全剥掉。那样 "a\nb\nc" 与 "abc" 会等价，
+// 段落结构整个没了还判成功 —— 等于把谎报换成另一种谎报。所以：
+//   - 排版空白（空格 / tab）压掉：编辑器加缩进用户看不出来，不算差异；
+//   - 换行**参与**比对：段落结构必须保住；
+//   - 但连续换行压成一个：分几层由编辑器决定，不该由调用方的文本决定。
+
+/** 校验主口径：\r\n 归一 → 压排版空白 → 连续换行压成一个。 */
+export function normalizeInputText(s) {
+  return String(s || '')
+    .replace(/\r\n?/g, '\n')
+    .replace(/[^\S\n]+/g, '')
+    .replace(/\n{2,}/g, '\n');
+}
+
+/** 兜底口径：在 normalizeInputText 之上再剥掉所有换行，得到纯内容指纹。 */
+export function skeletalInputText(s) {
+  return normalizeInputText(s).replace(/\n+/g, '');
+}
+
+/**
+ * 判定一次输入是否达到了预期。
+ * @param {string} expected 调用方想写入的文本
+ * @param {string} actual   回读到的可编辑区内容
+ * @returns {{ok: boolean, landed: boolean}} ok=按主口径达标；landed=忽略全部空白后内容已到位（排版被重排过）
+ */
+export function verifyInputText(expected, actual) {
+  const want = normalizeInputText(expected);
+  const got = normalizeInputText(actual);
+  // clear（空目标）：允许残留空块外壳 —— 浏览器永远会留一个空块承载光标。
+  if (!want) return { ok: skeletalInputText(actual) === '', landed: true };
+  const ok = got.includes(want);
+  // 忽略全部空白后再比一次：相等说明东西其实打进去了、只是被编辑器重新排了版。
+  const landed = ok || skeletalInputText(actual) === skeletalInputText(expected);
+  return { ok, landed };
+}

package/src/shared/key_dispatch.cjs

@@ -0,0 +1,37 @@
+'use strict';
+// src/shared/key_dispatch.cjs —— 「这一次按键该发什么 CDP 事件」的纯决策。
+//
+// 抽成纯函数只为一件事：这是"按了等于没按"那类缺陷的唯一入口，必须能单测。
+// 藏在 PageManager 里就只能靠真起一个 Electron 才能验证。
+//
+// 核心事实：CDP 的 `rawKeyDown` **刻意不带 text**，浏览器只派发 keydown、
+// 不产生 keypress。而 Enter 激活聚焦元素（<button> 的 click、<a> 的跳转、
+// 表单的隐式提交）走的正是默认动作 —— 也就是 keypress。
+// 实测（tools/_oneoff/probe_press_enter.cjs，file:// 页面）：focus 一个 button
+// 后 ui.act press Enter，页面收到 keydown（e.key==='Enter'、isTrusted=true），
+// 但 onclick **一次都没触发**；同元素 click 正常。
+// Puppeteer 的 keyboard.press('Enter') 有效，是因为它的键表给 Enter 配了
+// text='\r'，走的是**带 text 的 keyDown**。
+//
+// 两种语义必须分开，不能全局替换：
+//   activate=true  → 带 text 的 keyDown（产生默认动作）
+//   activate 缺省  → rawKeyDown（+ 可选 char），type 的段间换行依赖它
+// 理由见 page_manager._cdpKey 的注释：type 里"先发不带 text 的 Enter，看编辑器
+// 有没有自己分段，没分才补 char"这个策略不能被改坏。
+function keyDispatchPlan(p, opts) {
+  const spec = p || {};
+  const activating = !!(opts && opts.activate);
+  // 只有 Enter 需要"补"一个默认文本：它的默认动作在 keypress 上。
+  // 其它键（Tab/Delete/方向键）的默认动作在 keydown 上，rawKeyDown 已经够。
+  let text = '';
+  if (activating) {
+    if (spec.text === undefined) text = spec.key === 'Enter' ? '\r' : '';
+    else text = spec.text || '';
+  }
+  if (activating && text) {
+    return { type: 'keyDown', text, charText: '' };
+  }
+  return { type: 'rawKeyDown', text: '', charText: spec.text || '' };
+}
+
+module.exports = { keyDispatchPlan };

package/src/shared/nav_wait.cjs

@@ -0,0 +1,47 @@
+// src/shared/nav_wait.cjs — ui.navigate 的完成信号（纯函数）
+//
+// 事故：SPA（尤其带 markdown 高亮的编辑器）永远不 fire `load`，而 navigate 走的是
+// `webContents.loadURL()` —— 它在 did-finish-load 才 resolve。于是导航"成功"的页面
+// 被当成超时：30s 空等，期间 tab 被拖到无响应，之后所有 act/evaluate 连锁超时，
+// agent 据此得出"编辑器坏了"的结论。
+//
+// load 不是可用的完成信号。这里把"等到哪一步"显式化：
+//   commit          主帧导航已提交（最快；内容可能还没渲染）
+//   domcontentloaded DOM 就绪（默认；SPA 在这一步就能返回）
+//   load            连子资源一起等（老行为，只在确实需要时用）
+
+'use strict';
+
+const LEVELS = ['commit', 'domcontentloaded', 'load'];
+const DEFAULT_LEVEL = 'domcontentloaded';
+
+// 同义词归一。刻意不接受 networkidle：它需要网络空闲探测，本实现里没有对应
+// 机制 —— 承诺一个做不到的档位，比只给三个真实档位更糟。
+const ALIASES = {
+  commit: 'commit',
+  dom: 'domcontentloaded',
+  domready: 'domcontentloaded',
+  domcontentloaded: 'domcontentloaded',
+  interactive: 'domcontentloaded',
+  load: 'load',
+  full: 'load',
+};
+
+/**
+ * 归一 wait_until。返回 { value } 或 { error }（error 可直接给调用方看）。
+ */
+function normalizeWaitUntil(v) {
+  if (v === undefined || v === null || v === '') return { value: DEFAULT_LEVEL };
+  const key = String(v).toLowerCase().replace(/[\s_-]/g, '');
+  const hit = ALIASES[key];
+  if (!hit) {
+    return {
+      error: 'unknown wait_until: ' + JSON.stringify(String(v))
+        + ' — valid values are ' + LEVELS.join(' | ')
+        + '. Default is domcontentloaded; use load only when you really need subresources.',
+    };
+  }
+  return { value: hit };
+}
+
+module.exports = { normalizeWaitUntil, LEVELS, DEFAULT_LEVEL };

package/src/shared/protocol.js

@@ -59,6 +59,10 @@ export function parseMessage(msg) {
 export const VALID_METHODS = [
   'ui.get_tree',
   'ui.act',
+  'ui.auth_state',
+  // 视口截图（P0-1）：操作失败时的第一诊断手段，弥补元素树看不见的
+  // 浮层/canvas/遮挡/渲染错位。返回 base64，默认 png。
+  'ui.screenshot',
   'ui.navigate',
   'ui.repaint',
   'ui.snapshot',
@@ -68,6 +72,10 @@ export const VALID_METHODS = [
   'ui.subscribe',
   'ui.unsubscribe',
   'ui.downloads',
+  // 主进程错误日志（只读）。界面弹过"js 崩溃"原生框、或某个动作莫名失败时，
+  // 这里是唯一能查到 stack 与"出错那一刻在调什么"的地方 —— 此前这类异常只活在
+  // 那个框里，点掉即永久丢失。
+  'ui.errors',
   'ui.get_focused',
   'ui.peek',
   'ui.wait',
@@ -76,6 +84,13 @@ export const VALID_METHODS = [
   'ui.close_tab',
   'ui.list_tabs',
   'ui.set_active_tab',
+  // 窗口首次显示的时刻与当时页面状态。白屏类缺陷的根因是"窗口显示了但渲染器
+  // 还没画出第一帧"，而这只能从窗口侧观测（WS 端口比 showInitialWindow 早开），
+  // 所以留一个查询口；见 e2e/nav_ws.cjs NV-A。
+  'ui.window_shown',
+  // 服务端进程身份（pid + 启动时刻）。调用方据此核对"我连上的是不是我拉起的
+  // 那个实例" —— 连错实例时结果毫无意义但不会报错，是最难查的一类。
+  'ui.server_info',
   'ui.canvas_configure',
   'ui.canvas_list',
   'ui.canvas_read',

package/src/shared/ref_guard.cjs

@@ -0,0 +1,133 @@
+// src/shared/ref_guard.cjs — ui.act target 的形状体检（纯函数）
+//
+// 坑：ui.act 的 target 是 get_tree 返回的 data-ai-id（如 `e:button-12`、
+// `axf-3-1`，或元素原生 id），**不是按钮上可见的文字**。传 "发布" 这类
+// label 时，最终以 `[data-ai-id="发布"]` 去查，命中不到，回一句
+// "Target not found for ref: 发布" —— 字面没错，但完全没有指出"你传的是
+// 文字不是 id"这个真正原因，调用方容易反复重试同一个错误形状。
+//
+// 这里在入口把明显不像 ref 的形状挡下来，并给可操作的提示。判定从宽：
+// 只拒**几乎不可能是 id** 的输入（含空白字符、超长、以引号/括号开头），
+// 原生 id 一律放行 —— 误拒一个合法 id 比漏放一个 label 更糟。
+
+'use strict';
+
+const MAX_REF_LEN = 120;
+
+// CJK（含全角标点）。ref 里不会出现，文案里必然出现。
+const CJK_RE = /[\u3000-\u303f\u4e00-\u9fff\uff00-\uffef]/;
+// 选择器的"结构符"。要求**至少有一个**，而不是"有空格就算"——
+// 否则 "Publish now" 这种英文按钮文案会被当成后代选择器放行，
+// 那恰恰是这套体检要拦的东西。
+const SELECTOR_MARK_RE = /[.#\[>]|\*/;
+// 选择器里允许出现的字符集合（够覆盖后代/子代/属性/伪类/分组选择器的常见写法）。
+const SELECTOR_CHARS_RE = /^[A-Za-z0-9_\-.#\[\]="'>+~:*()\s]+$/;
+
+/**
+ * 是否"像一条 CSS 选择器"。
+ * 用于 upload：上传控件常常既没有 data-ai-id、也没有可用的原生 id
+ * （B站「本地上传」是个纯 div 菜单项，AX 树里根本没有它），只能靠选择器定位。
+ * 判定刻意从严：必须**无 CJK + 含结构符 + 字符集合法**，避免把页面文案放进来。
+ */
+function looksLikeCssSelector(t) {
+  if (!t) return false;
+  if (CJK_RE.test(t)) return false;
+  if (!SELECTOR_MARK_RE.test(t)) return false;
+  return SELECTOR_CHARS_RE.test(t);
+}
+
+/**
+ * 把复合选择器拆成"逐段"的简单选择器（只按**顶层**复合子拆，属性值/伪类
+ * 参数里的空格引号不算）。返回形如 ['.a', '.b', '[type=file]']。
+ * 拆的时候丢掉组合子（`>` `+` `~` 与空格一样处理），因为回退只关心"哪几层"，
+ * 不关心层与层之间是父子还是兄弟 —— 原始写法会由调用方原样保留为第一个候选。
+ */
+function splitCompoundSelector(t) {
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let cur = '';
+  for (let i = 0; i < t.length; i++) {
+    const ch = t[i];
+    if (quote) {
+      cur += ch;
+      if (ch === '\\') { cur += t[i + 1] || ''; i++; continue; }
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { quote = ch; cur += ch; continue; }
+    if (ch === '[' || ch === '(') { depth++; cur += ch; continue; }
+    if (ch === ']' || ch === ')') { depth = Math.max(0, depth - 1); cur += ch; continue; }
+    if (depth === 0 && /[\s>+~]/.test(ch)) {
+      if (cur) { parts.push(cur); cur = ''; }
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur) parts.push(cur);
+  return parts;
+}
+
+/**
+ * 选择器的回退候选，**由长到短**：`.a .b .c` → `['.a .b .c', '.a .b', '.a']`。
+ *
+ * 为什么需要：大量上传组件在"已经有文件"的状态下会把上传区（连同它内部那个
+ * 永远隐藏的 `<input type=file>`）整个卸载，只留一个封面预览。此时
+ * `.container-coverimage-box .el-upload__input` 查不到任何元素 —— 但它的祖先
+ * `.container-coverimage-box` 还在，点它能重新唤出选择器。调用方拿这串候选
+ * 逐个试，第一个命中的就是"还能点的那一层"。
+ *
+ * 非选择器形状（真的 data-ai-id）原样返回单元素数组，不改变既有行为。
+ */
+function selectorAncestors(t) {
+  const s = String(t || '').trim();
+  if (!s) return [];
+  if (!looksLikeCssSelector(s)) return [s];
+  const parts = splitCompoundSelector(s);
+  if (parts.length <= 1) return [s];
+  // 第一个永远是原样的完整选择器（保留 `>` `+` 这些精确组合子），后面才是
+  // 逐层退化的版本 —— 优先精确命中，实在没有才放宽成后代匹配。
+  const out = [s];
+  for (let n = parts.length - 1; n >= 1; n--) {
+    const cand = parts.slice(0, n).join(' ');
+    if (cand !== s) out.push(cand);
+  }
+  return out;
+}
+
+/**
+ * target 是否"看着像"一个 data-ai-id。
+ * @param {string} target
+ * @param {{allowSelector?: boolean}} [opts] allowSelector：该动作是否接受 CSS
+ *        选择器（目前只有 upload）。开启后选择器形态直接放行，其余判定不变。
+ * @returns {string|null} null 表示放行；字符串是拒绝原因（可直接给调用方看）。
+ */
+function refShapeError(target, opts) {
+  if (target === undefined || target === null || target === '') return null; // 空由调用方按各动作规则处理
+  const t = String(target);
+  const allowSelector = !!(opts && opts.allowSelector);
+  if (allowSelector && looksLikeCssSelector(t)) return null;
+  if (/\s/.test(t)) {
+    return 'target looks like visible text, not a data-ai-id: ' + JSON.stringify(t.slice(0, 60))
+      + ' — pass the id from get_tree (e.g. "e:button-12", "axf-3-1", or the element\'s native id), not the label on screen'
+      + (allowSelector ? '; a CSS selector (e.g. ".el-upload__input") is also accepted for upload' : '');
+  }
+  // 纯 CJK、且不含任何 ASCII 字母/数字/结构符（`:` `-` `_` 等）——不可能是
+  // data-ai-id。树里的 ref 要么带结构前缀（`e:button-12` / `axf-3-1`），要么
+  // 是站点的原生 id（ASCII）。真实站点上"发布"/"点击发布"这类输入就是按钮
+  // 文案，放行只会让它变成一句无方向的 "Target not found"。
+  // 混了 ASCII 的一律放行（`e:按钮-1` 可能是合法 id）。
+  if (CJK_RE.test(t) && !/[A-Za-z0-9]/.test(t)) {
+    return 'target looks like visible text, not a data-ai-id: ' + JSON.stringify(t.slice(0, 60))
+      + ' — pass the id from get_tree (e.g. "e:button-12", "axf-3-1"). If this really is the element\'s native id, locate it with ui.evaluate instead';
+  }
+  if (t.length > MAX_REF_LEN) {
+    return 'target is ' + t.length + ' chars — data-ai-id values are short ids from get_tree, not text';
+  }
+  if (/^["'`()[\]{}]/.test(t)) {
+    return 'target starts with a quote/bracket — pass the bare id from get_tree, not a selector';
+  }
+  return null;
+}
+
+module.exports = { refShapeError, looksLikeCssSelector, selectorAncestors, splitCompoundSelector, MAX_REF_LEN };