@glittering0717/ai-browser 1.2.1 → 1.2.2

package/README.md

@@ -11,7 +11,7 @@
   <img alt="MIT" src="https://img.shields.io/badge/license-MIT-blue.svg">
   <img alt="Electron" src="https://img.shields.io/badge/built%20with-Electron%2033-9cf">
   <img alt="Platforms" src="https://img.shields.io/badge/platforms-macOS%20%E2%80%A2%20Linux-blueviolet">
-  <img alt="Tests" src="https://img.shields.io/badge/tests-411%20unit%20%2B%20409%20e2e-2ea043">
+  <img alt="Tests" src="https://img.shields.io/badge/tests-427%20unit%20%2B%20428%20e2e-2ea043">
   <img alt="MCP" src="https://img.shields.io/badge/spec-MCP%20(stdio)-f5b23b">
 </p>
 
@@ -565,9 +565,11 @@ npm run value        # value truncation contract + read-only get_value — 15 ch
 npm run canvas       # canvas draw-call capture — 13 checks
 npm run modeldiff    # canvas app data-model diff (the "unchanged" false green) — 12 checks
 npm run audit        # every advertised action must exist; wait/downloads/permissions/quit — 35 checks
+npm run nav          # address bar + load-failure error page (the "white screen" report) — 19 checks
 npm run focus        # no focus stealing + full capability while backgrounded — 32 checks
 npm run interact     # trusted drag / key press / wheel (pointer gestures) — 31 checks
 npm run view         # viewport repaint + snapshot/diff verification — 28 checks
+npm run e2e:all      # 一次跑完上面全部套件（每个独立端口）+ 可信汇总 — 428 checks
 npm run realsites    # navigate/read/act against a matrix of real sites
 ```
 
@@ -575,6 +577,16 @@ All e2e suites boot a genuine Electron against offline fixtures and exit non-zer
 Together they cover what jsdom structurally cannot: preload integrity, `ui.evaluate` under a strict
 CSP, CDP click hit-testing, multi-tab lifecycle, event fan-out, and the `evaluate` guard rails.
 
+**Each suite proves it is talking to the browser it just started.** Before any assertion runs it
+calls `ui.server_info` and compares the returned `pid` against the child process it spawned; a
+mismatch aborts with exit 4 instead of quietly producing results about somebody else's instance.
+That gap was measured, not assumed: with an impostor WebSocket server holding the port, a suite
+happily sent `ui.new_tab` / `ui.evaluate` / `ui.get_tree` to it and never noticed. Repro:
+`REPRO_PORT=9799 node e2e/_repro_identity.cjs`.
+
+`npm run e2e:all` also gives every suite its own port, because they share `/tmp/ai-browser-e2e-<port>`
+as the profile and therefore Electron's single-instance lock too.
+
 They all need the WS port free — stop a running `npm start` first, or point them elsewhere:
 
 ```bash
@@ -635,7 +647,13 @@ Two things it changed in the product:
 the page through `ui.evaluate`.
 
 **`npm run network`** — that a POST can be captured with its full request body, that headers are
-redacted by default, and that bodies paginate instead of being silently truncated.
+redacted by default, and that bodies paginate instead of being silently truncated. It also pins the
+eviction rule: the retained byte budget is **global across tabs**, so a background tab quietly
+filling it used to evict the body the agent was about to read on the *active* tab — the request
+really happened and the body really was captured, it just got pushed out by someone else's noise.
+Eviction now sacrifices non-active tabs first (including the background body being stored), and
+`ui.network_configure` reports `active_tab` / `body_bytes` so a future `evicted` can be attributed
+instead of guessed at.
 
 **`npm run modeldiff`** — the suite for the one place `ui.diff` used to lie. A canvas-rendered app's
 DOM is a still photograph: dragging a node or editing a widget repaints `<canvas>` and moves

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittering0717/ai-browser",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "AI-native browser — renders pixels for humans, structured semantic-tree API for agents. No screenshots, no OCR, no coordinate guessing.",
   "main": "src/main/index.js",
   "bin": {
@@ -65,7 +65,9 @@
     "realsites:meta": "vitest run tests/test_realsites_sites.js",
     "mcp": "node src/main/mcp_server.js",
     "modeldiff": "node e2e/modeldiff_ws.cjs",
-    "audit": "node e2e/audit_ws.cjs"
+    "nav": "node e2e/nav_ws.cjs",
+    "audit": "node e2e/audit_ws.cjs",
+    "e2e:all": "node e2e/run_all.cjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/src/main/index.js

@@ -60,6 +60,8 @@ let wsServer = null;
 let tabBarView = null;
 let pageManager = null;
 let tabRefreshInterval = null;
+let navStateInterval = null;
+let navStateWc = null;
 let networkWatchdog = null;
 let isQuitting = false;
 
@@ -110,15 +112,25 @@ function createWindow() {
   pageManager = PageManager.getInstance(mainWindow);
   pageManager._preloadPath = path.join(__dirname, '../preload/bridge.cjs');
 
-  // Create first tab
-  pageManager.newTab('https://www.baidu.com');
+  // Create first tab.
+  //
+  // 默认页用 baidu.com：国内可达、无登录墙、重定向链短。但注意它**不是**必须的 ——
+  // 用户报"打开 ai-browser 白屏"时，我们实测过两种独立成因（见 showInitialWindow
+  // 的注释），跟默认页选谁无关；换成 about:blank 只会把"加载失败的白屏"变成
+  // "空白页的白屏"，问题更大（连错误提示都没有）。
+  //
+  // 可由 AI_BROWSER_START_URL 覆盖；设为空字符串则开空白页。
+  const START_URL = process.env.AI_BROWSER_START_URL !== undefined
+    ? (process.env.AI_BROWSER_START_URL || null)
+    : 'https://www.baidu.com';
+  pageManager.newTab(START_URL);
 
   // Start WS server — pass cleanupAndQuit so ui.quit can shut down the app
   wsServer = startWSServer(pageManager, PORT, cleanupAndQuit);
 
   // === Tab bar IPC ===
   ipcMain.on('tab:new', () => {
-    pageManager.newTab('https://www.baidu.com');
+    pageManager.newTab(START_URL);
     refreshTabBar();
   });
   ipcMain.on('tab:close', (_e, tabId) => {
@@ -131,6 +143,41 @@ function createWindow() {
   });
   ipcMain.handle('tab:list', () => pageManager.listTabs());
 
+  // === 地址栏 / 导航按钮 ===
+  ipcMain.handle('nav:state', () => {
+    const wc = activeWebContents();
+    if (!wc) return { tab: null, url: '', canBack: false, canForward: false, loading: false, status: '' };
+    return {
+      tab: pageManager.activeTab,
+      url: wc.getURL(),
+      canBack: wc.navigationHistory ? wc.navigationHistory.canGoBack() : wc.canGoBack(),
+      canForward: wc.navigationHistory ? wc.navigationHistory.canGoForward() : wc.canGoForward(),
+      loading: wc.isLoading(),
+      status: wc.isLoading() ? '加载中…' : '',
+    };
+  });
+  ipcMain.on('nav:go', (_e, input) => {
+    const wc = activeWebContents();
+    const url = normalizeUrlInput(input);
+    if (!wc || !url) return;
+    try { wc.loadURL(url); } catch (e) { console.error('[index] nav:go failed:', e.message); }
+  });
+  ipcMain.on('nav:back', () => { const wc = activeWebContents(); if (wc && wc.navigationHistory) wc.navigationHistory.goBack(); });
+  ipcMain.on('nav:forward', () => { const wc = activeWebContents(); if (wc && wc.navigationHistory) wc.navigationHistory.goForward(); });
+  ipcMain.on('nav:reload', () => { const wc = activeWebContents(); if (wc) wc.reload(); });
+  ipcMain.on('nav:stop', () => { const wc = activeWebContents(); if (wc) wc.stop(); });
+  // 错误页里的重试 / 返回（错误页是我们自己的 renderer，同样走 ipc）
+  ipcMain.on('error-page:navigate', (_e, input) => {
+    const wc = activeWebContents();
+    const url = normalizeUrlInput(input);
+    if (!wc || !url) return;
+    try { wc.loadURL(url); } catch (e) { console.error('[index] error-page navigate failed:', e.message); }
+  });
+  ipcMain.on('error-page:back', () => {
+    const wc = activeWebContents();
+    if (wc && wc.navigationHistory) wc.navigationHistory.goBack();
+  });
+
   // Intercept new-window / window.open → new tab instead of new window
   ipcMain.on('tab:new-url', (_e, url) => {
     pageManager.newTab(url);
@@ -188,6 +235,32 @@ function createWindow() {
   // Refresh tab bar periodically
   tabRefreshInterval = setInterval(refreshTabBar, 2000);
 
+  // === 地址栏状态跟随 ===
+  // 导航可能来自三方：人在地址栏输入、agent 调 ui.navigate、页面自己跳转。
+  // 地址栏必须反映**真实**状态，所以这里订阅激活 tab 的 webContents 事件主动推，
+  // 而不是靠定时轮询（轮询有最多 2s 的滞后，人会以为按钮坏了）。
+  const wireNavState = (tabId) => {
+    const wc = activeWebContents();
+    if (!wc) return;
+    if (navStateWc === wc) return;         // 同一个 tab 重复 setActive，不重复挂
+    navStateWc = wc;
+    const push = () => pushNavState();
+    wc.on('did-start-loading', push);
+    wc.on('did-stop-loading', push);
+    wc.on('did-navigate', push);
+    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);
+    wireNavState(tabId);
+    pushNavState();
+  };
+  wireNavState(pageManager.activeTab);
+  // 兜底轮询：只覆盖上面事件没抓到的情况（低频，成本可忽略）
+  navStateInterval = setInterval(pushNavState, 1500);
+
   // === #5: NetworkService self-heal watchdog ===
   // The Electron NetworkService can wedge as a whole (port stays listening but
   // every ui.navigate fails ERR_FAILED while curl works fine). A clean relaunch
@@ -209,6 +282,12 @@ function createWindow() {
  * 焦点，人可以继续在原来的窗口里做事；人手动 `npm start` 时窗口照常显示在前台。
  *
  * AI_BROWSER_FOCUS=always / never 可整体覆盖（见 page_manager._focusWindow）。
+ *
+ * 另外：**等首屏 DOM 就绪再 show**。2026-10-14 实测偶发（12 次启动里 1 次）
+ * 窗口已显示但 document.body 还是 null、页面整个是白的 —— 用户报的"打开
+ * ai-browser 白屏"其中一类就是这个：不是连接错（网络是通的，DNS 也解析了），
+ * 是窗口在渲染器还没画出第一帧时就显示了。等到 dom-ready（或最多 3s 兜底）
+ * 再显示，窗口一出现就是有内容的。
  */
 function showInitialWindow() {
   if (!mainWindow) return;
@@ -219,12 +298,85 @@ function showInitialWindow() {
   // 策略只决定**显示时抢不抢焦点**：只有人手动启动、或显式 always，才显示并激活；
   // agent 拉起（或 never）走 showInactive —— 窗口出现，但键盘焦点留在用户那边。
   const shouldActivate = policy === 'always' || (policy !== 'never' && !byAgent);
-  try {
-    if (shouldActivate) mainWindow.show();
-    else mainWindow.showInactive();
-  } catch (e) {
-    try { mainWindow.show(); } catch (e2) { /* 窗口已销毁 */ }
-  }
+
+  const doShow = () => {
+    if (!mainWindow || mainWindow.isDestroyed()) return;
+    try {
+      if (shouldActivate) mainWindow.show();
+      else mainWindow.showInactive();
+    } catch (e) {
+      try { mainWindow.show(); } catch (e2) { /* 窗口已销毁 */ }
+    }
+  };
+
+  // 等首屏内容就绪。上限 3s：网络再慢也不该让窗口迟迟不出现（人看不到窗口
+  // 比看到白屏更糟），超时就先显示，剩下的交给 did-fail-load 错误页兜底。
+  const firstView = pageManager && pageManager.tabs.get(pageManager.activeTab);
+  const wc = firstView && firstView.webContents;
+  if (!wc || wc.isDestroyed()) { doShow(); return; }
+  let shown = false;
+  // reason: 为什么在这个时刻显示。必须如实记录 —— 之前 waited_for_dom 恒为
+  // true（3s 兜底显示时也报 true），于是"到底等到了 dom-ready 没有"看不出来，
+  // 白屏缺陷和"我们主动选择先显示"被混成同一种结果。
+  const showOnce = (reason) => {
+    if (shown) return;
+    shown = true;
+    // 同步先落一条记录：哪怕 renderer 还没就绪（executeJavaScript 会 reject），
+    // "窗口在这一刻显示了、而页面是空的"这个事实本身也必须留下 —— 那正是要抓的
+    // 白屏形态。若等 Promise 成功才记，renderer 起不来时记录永远是 null，
+    // 观测口在最需要它的时候失灵。
+    const rec = {
+      tab: pageManager.activeTab,
+      body_len: null,
+      ready_state: null,
+      // 'dom-ready' | 'fail-load' | 'renderer-ready' | 'timeout'
+      show_reason: reason || 'unknown',
+      // 真话：只有 3s 兜底（renderer 迟迟没到）才是 false。
+      waited_for_dom: reason !== 'timeout',
+      renderer_ready: false,
+    };
+    pageManager.windowShownAt = rec;
+    // 再把"窗口在这一刻显示、且此刻页面是什么状态"广播出去。
+    // 为什么值得多这一个事件：白屏类缺陷的根因是"窗口显示了但渲染器还没画出
+    // 第一帧"，而这只能从窗口侧观测 —— WS 端口就绪不等于窗口已显示（端口在
+    // createWindow 里就开了，比 showInitialWindow 早），所以从 agent 侧 polling
+    // 永远测不到这个时序。有了这个事件，e2e 才能断言"显示的瞬间页面已有内容"。
+    // 读数走 pageManager.evaluate（CDP Runtime.evaluate），不用
+    // webContents.executeJavaScript：高层 API 在 renderer 尚未完全就绪时会 reject
+    // （实测禁硬件加速 + 首次创建 GL context 失败时，dom-ready 已到但
+    // executeJavaScript 仍失败，而页面随后照常加载、CDP 读数正常）。
+    // 观测口必须能在最需要它的时候读数，否则等于没有。
+    const readReady = () => pageManager.evaluate(
+      '(function(){var b=document.body;return JSON.stringify({body:b?b.innerHTML.length:-1,ready:document.readyState});})()',
+      pageManager.activeTab
+    );
+    Promise.resolve()
+      .then(() => readReady())
+      .then((v) => {
+        rec.renderer_ready = true;
+        try {
+          const p = JSON.parse(v);
+          rec.body_len = p.body;
+          rec.ready_state = p.ready;
+        } catch (e) { /* 非预期返回，留 null */ }
+        try { pageManager._broadcast('window_shown', rec); } catch (e) { /* 无订阅者 */ }
+      })
+      .catch(() => {
+        // 真的读不到（renderer 始终没起来）—— 这本身就是要抓的白屏形态，
+        // 记录里 renderer_ready 保持 false，让 e2e 看得见。
+      });
+    doShow();
+  };
+  wc.once('dom-ready', () => showOnce('dom-ready'));
+  wc.once('did-fail-load', () => showOnce('fail-load'));   // 失败也要显示（错误页会接手）
+  setTimeout(() => showOnce('timeout'), 3000);
+  // dom-ready 可能在上面注册**之前**就已经触发过（缓存命中时 baidu 首屏
+  // 一到就 ready，而 showInitialWindow 是 createWindow 的最后一步）——
+  // once() 收不到已经过去的事件，那就只能干等 3s 兜底。先主动查一次
+  // readyState（走 CDP，见 showOnce 里的说明），已经就绪就立刻显示。
+  pageManager.evaluate('(function(){return document.readyState;})()', pageManager.activeTab)
+    .then((rs) => { if (rs && rs !== 'loading') showOnce('renderer-ready'); })
+    .catch(() => { /* renderer 未就绪，等事件 */ });
 }
 
 // Probe one target through the NetworkService from the main process. Reuses
@@ -312,6 +464,56 @@ function refreshTabBar() {
   }
 }
 
+// === 地址栏 / 前进 / 后退 / 刷新 / 停止 ===
+//
+// 为什么必须有：窗口是真实可见的普通窗口，产品承诺人可以随时手动介入
+// （登录、扫码、过滑块、纠正 agent 的操作）。但原先窗口里只有 tab 条，
+// 没有地址栏也没有任何导航按钮 —— 人要介入时连"打开某个页面"都做不到，
+// 只能干等 agent。用户原话："现在有时候需要我操作一下，比如登录验证码等，
+// 页面都打不开，非常难受。"
+//
+// 这里的每一行都只操作 activeTab 的 webContents，不碰页面内容，也不引入
+// 任何人机协作状态机 —— 就是普通浏览器的地址栏。
+
+/** 当前激活 tab 的 webContents，没有则 null。 */
+function activeWebContents() {
+  if (!pageManager) return null;
+  const view = pageManager.tabs.get(pageManager.activeTab);
+  if (!view || view.webContents.isDestroyed()) return null;
+  return view.webContents;
+}
+
+/** 把地址栏需要的一切状态推给 tab bar renderer。 */
+function pushNavState() {
+  if (!tabBarView || tabBarView.webContents.isDestroyed()) return;
+  const wc = activeWebContents();
+  const state = wc ? {
+    tab: pageManager.activeTab,
+    url: wc.getURL(),
+    canBack: wc.navigationHistory ? wc.navigationHistory.canGoBack() : wc.canGoBack(),
+    canForward: wc.navigationHistory ? wc.navigationHistory.canGoForward() : wc.canGoForward(),
+    loading: wc.isLoading(),
+    status: wc.isLoading() ? '加载中…' : '',
+  } : { tab: null, url: '', canBack: false, canForward: false, loading: false, status: '' };
+  tabBarView.webContents.executeJavaScript(
+    'window.__onNavState && window.__onNavState(' + JSON.stringify(state) + ')'
+  ).catch(() => {});
+}
+
+/**
+ * 把用户输入解析成可加载的 URL。
+ * 只做最小处理：带协议的直接用；否则按 https 猜；纯查询词不进这里
+ * （地址栏输入什么就打开什么，不做搜索跳转 —— 那会替用户做决定）。
+ */
+function normalizeUrlInput(input) {
+  const s = String(input || '').trim();
+  if (!s) return null;
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(s)) return s;          // http:// https:// file:// …
+  if (/^(about|file|data):/i.test(s)) return s;
+  if (/^localhost(:\d+)?(\/|$)/i.test(s)) return 'http://' + s;
+  return 'https://' + s;
+}
+
 app.whenReady().then(() => {
   createWindow();
   // 下载与权限的 session 级钩子。必须装在 will-download 上，否则 Electron 默认

package/src/main/network_monitor.js

@@ -165,10 +165,22 @@ export class NetworkMonitor {
     this.captureEnabled = opts.captureEnabled !== undefined ? opts.captureEnabled : envFlag('AI_BROWSER_NETWORK_CAPTURE', true);
     this.sensitiveAllowed = opts.sensitiveAllowed !== undefined ? opts.sensitiveAllowed : envFlag('AI_BROWSER_NETWORK_SENSITIVE', false);
     this.globalCaptureBodies = 'api';
+    // 当前活跃 tab（由 page_manager 在 setActive / closeTab 时同步进来）。
+    // 只被 body 淘汰顺序用：null 表示不知道/没有活跃 tab，此时退回纯按新旧。
+    // 注意它可以是 null，所以下面 _enforceBodyLimit 里判等不能假设非空。
+    this.activeTabId = null;
   }
 
   // ==== 配置 ============================================================
 
+  /**
+   * 告知活跃 tab。page_manager 是唯一调用方（setActive / closeTab 换活跃页时）。
+   * 传 null = 没有活跃 tab（最后一个 tab 关掉了）。
+   */
+  setActiveTab(tabId) {
+    this.activeTabId = tabId == null ? null : tabId;
+  }
+
   setBodyFetcher(tabId, fn) { this._fetchers.set(tabId, fn); }
   clearBodyFetcher(tabId) { this._fetchers.delete(tabId); }
 
@@ -204,16 +216,36 @@ export class NetworkMonitor {
 
   _enforceRecordLimit(protectId) {
     while (this._records.size > this.limits.maxRecords) {
-      let victim = null;
-      for (const id of this._order) {
-        if (id === protectId) continue;
-        victim = id; break;
-      }
+      const victim = this._evictionVictim(protectId);
       if (!victim) break;
       this._dropRecord(victim);
     }
   }
 
+  // 淘汰候选：**非活跃 tab 的最旧一条**优先；一条都没有（全是活跃 tab 的，或
+  // 根本不知道活跃 tab）才退到全局最旧。
+  //
+  // 为什么两处淘汰都要挑 tab：全局上限（记录数 / body 字节）是跨 tab 共享的，
+  // 而后台 tab 会持续累积。实测默认页 baidu.com 挂久了之后，agent 正在操作的
+  // 那个 tab 的 POST 请求体被挤成 evicted（e2e/network_ws.cjs N-04/N-05 红）——
+  // 请求确实发生了、body 也确实拿到过，只是被后台噪声顶掉，agent 读到的是
+  // evicted 而不是内容。让活跃 tab 有优先保留权，后台 tab 超限时先牺牲自己。
+  //
+  // activeTabId 为 null（无活跃 tab / 单测未接线）时，`tab_id !== null` 恒真，
+  // 直接返回全局最旧 —— 与改动前完全一致。
+  _evictionVictim(protectId) {
+    const active = this.activeTabId;
+    let fallback = null;
+    for (const id of this._order) {
+      if (id === protectId) continue;
+      const rec = this._records.get(id);
+      if (!rec) continue;
+      if (fallback === null) fallback = id;
+      if (rec.tab_id !== active) return id;
+    }
+    return fallback;
+  }
+
   _dropRecord(networkId) {
     const rec = this._records.get(networkId);
     if (!rec) return;
@@ -225,25 +257,35 @@ export class NetworkMonitor {
     this._droppedRecords += 1;
   }
 
-  // body 超限：优先淘汰最旧的 response body，其次 request body；metadata 保留。
+  // body 超限淘汰：先 response body 后 request body（同一次超限里），同一种 body
+  // 内部按 _order 由旧到新。**并且先淘汰非活跃 tab 的**（见 _evictionVictim 的
+  // 注释：全局 32MB 配额跨 tab 共享，后台 tab 会把活跃 tab 的 body 顶成 evicted）。
+  // metadata 不淘汰，只丢 body 内容，记录仍然查得到。
+  //
+  // 单 tab 场景下行为不变（活跃 tab 就是唯一的 tab，排序等价于纯按新旧）。
   _enforceBodyLimit(protectId) {
     if (this._bodyBytes <= this.limits.maxBodyBytes) return;
-    for (const pass of ['response', 'request']) {
-      for (const id of this._order) {
-        if (this._bodyBytes <= this.limits.maxBodyBytes) return;
-        if (id === protectId) continue;
-        const rec = this._records.get(id);
-        if (!rec) continue;
-        if (pass === 'response' && rec._respBody) {
-          this._bodyBytes -= rec._respBodyBytes || 0;
-          rec._respBody = null; rec._respBodyBytes = 0;
-          rec.response_body_state = 'evicted';
-          rec._respEvicted = true;
-        } else if (pass === 'request' && rec._reqBody) {
-          this._bodyBytes -= rec._reqBodyBytes || 0;
-          rec._reqBody = null; rec._reqBodyBytes = 0;
-          rec.request_body_state = 'evicted';
-          rec._reqEvicted = true;
+    const active = this.activeTabId;
+    // 两轮：先把非活跃 tab 的 body 淘汰掉，仍然超限才动活跃 tab 自己的。
+    for (const phase of ['background', 'active']) {
+      for (const pass of ['response', 'request']) {
+        for (const id of this._order) {
+          if (this._bodyBytes <= this.limits.maxBodyBytes) return;
+          if (id === protectId) continue;
+          const rec = this._records.get(id);
+          if (!rec) continue;
+          if (phase === 'background' ? rec.tab_id === active : rec.tab_id !== active) continue;
+          if (pass === 'response' && rec._respBody) {
+            this._bodyBytes -= rec._respBodyBytes || 0;
+            rec._respBody = null; rec._respBodyBytes = 0;
+            rec.response_body_state = 'evicted';
+            rec._respEvicted = true;
+          } else if (pass === 'request' && rec._reqBody) {
+            this._bodyBytes -= rec._reqBodyBytes || 0;
+            rec._reqBody = null; rec._reqBodyBytes = 0;
+            rec.request_body_state = 'evicted';
+            rec._reqEvicted = true;
+          }
         }
       }
     }
@@ -283,7 +325,19 @@ export class NetworkMonitor {
       rec.response_body_state = overCap ? 'partial' : 'captured';
     }
     this._bodyBytes += bytes;
-    this._enforceBodyLimit(rec.network_id);
+    // "刚存进来的这条不在本轮淘汰里"是给活跃 tab 的特权，不是普适规则。
+    //
+    // 后台 tab 的 body 没有这个权利：否则一条 40KB 的后台响应体会先把活跃
+    // tab 里的小 body 全部挤掉（实测 baidu 默认页的一条响应把活跃 tab 上
+    // "GET-PAYLOAD-OK" 这 28 字节的响应顶成 evicted —— e2e/network_ws.cjs
+    // N-12 间歇红）。让它自己先被牺牲，活跃 tab 的 body 就不受影响：后台的
+    // body 反正没人看，而"活跃 tab 里明明还在配额内的小 body 消失了"是硬伤。
+    //
+    // activeTabId == null（没接线 / 单 tab）时一律按活跃处理 —— 保持改动前的
+    // 行为，不让新增逻辑在没有 tab 语义的场景里改变语义。
+    const active = this.activeTabId;
+    const isActive = active == null || rec.tab_id === active;
+    this._enforceBodyLimit(isActive ? rec.network_id : null);
     return body;
   }
 
@@ -522,6 +576,10 @@ export class NetworkMonitor {
       max_records: this.limits.maxRecords,
       body_bytes: this._bodyBytes,
       max_body_bytes: this.limits.maxBodyBytes,
+      // 淘汰优先级看这个：非活跃 tab 的 body / 记录先被牺牲。null = 不知道活跃
+      // tab（此时按纯新旧淘汰）。暴露出来是因为"我的 body 怎么被 evicted 了"
+      // 这类问题只能靠它定位 —— 曾经它就是个黑盒。
+      active_tab: this.activeTabId,
     };
   }
 
@@ -531,6 +589,11 @@ export class NetworkMonitor {
       enabled: !!cfg.enabled,
       capture_bodies: cfg.capture_bodies,
       since: this._startedAt,
+      // 当前全局占用与淘汰优先级。body 被 evicted 时，先看这里就能分清是
+      // "自己这个 tab 太多了"还是"后台 tab 把自己顶了"。
+      body_bytes: this._bodyBytes,
+      max_body_bytes: this.limits.maxBodyBytes,
+      active_tab: this.activeTabId,
       limits: {
         max_records: this.limits.maxRecords,
         max_body_bytes: this.limits.maxBodyBytes,

package/src/main/page_manager.js

@@ -2,6 +2,8 @@
 // One Electron process, one WS server, multiple tabs.
 // Agent routes via tab ID. Tab 0 is default.
 import { ipcMain, BrowserView } from 'electron';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { config } from '../shared/config.js';
 import axExtractor from './axExtractor.js';
 import { NetworkMonitor, MAX_POST_DATA_SIZE } from './network_monitor.js';
@@ -15,6 +17,9 @@ import valueContract from '../shared/value_contract.cjs';
 
 const { expandValueFetchTree } = valueContract;
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
 // canvas 绘制调用记录：默认开。关闭开关 AI_BROWSER_CANVAS_HOOK=0。
 const CANVAS_BRIDGE_KEY = '__aiCanvasBridge';
 
@@ -103,6 +108,11 @@ class PageManager {
     this.tabs = new Map();       // tabId -> BrowserView
     this.activeTab = null;
     this.tabCounter = 0;
+    // 窗口首次显示时的那一刻状态（tab / body_len / ready_state）。
+    // 白屏类缺陷的根因是"窗口显示了但渲染器还没画出第一帧"，而这只能从窗口侧
+    // 观测 —— WS 端口在 createWindow 中途就开了，比 showInitialWindow 早。
+    // 由 index.js 的 showInitialWindow 填写，ui.window_shown 读取。
+    this.windowShownAt = null;
     this.subscriptions = new Map();
     this._pendingRequests = new Map();
     this._requestId = 0;
@@ -259,7 +269,12 @@ class PageManager {
 
   _layoutAllViews(bounds) {
     for (const [id, view] of this.tabs) {
-      view.setBounds({ x: 0, y: 36, width: bounds.width, height: bounds.height - 36 });
+      view.setBounds({
+        x: 0,
+        y: config.tabBarHeight,
+        width: bounds.width,
+        height: bounds.height - config.tabBarHeight,
+      });
     }
   }
 
@@ -444,13 +459,34 @@ class PageManager {
     // loadURL resolves at did-finish-load, which is exactly when the old
     // pixels may still be on screen — repaint here as well as from the event
     // hooks, so a programmatic navigate never depends on hook timing.
+    //
+    // 失败时的返回值要说清楚**发生了什么**，而不是笼统的 ok:false。因为
+    // did-fail-load 现在会把页面换成我们自己的错误页（见
+    // _attachLoadFailureHooks），那次 loadURL(error_page) 会以 ERR_ABORTED
+    // 打断当前这次 loadURL 的 Promise —— 如果不区分，agent 收到的就是
+    // {ok:false, error:"ERR_ABORTED (-3) loading 'file://.../error_page.html'"}，
+    // 它会以为自己的导航请求坏了，而实际上错误页已经接管、信息全在那儿。
     try {
       await withDeadline(view.webContents.loadURL(url), 30000, 'navigate');
     } catch (e) {
+      const msg = String((e && e.message) || e);
+      // 错误页已接管：这不是调用方的错，是目标站点不可达。
+      // 两个判据（都不可省）：_failureGuard 里还有这个 tab（错误页刚加载、
+      // did-finish-load 还没来清标记），或者当前 URL 已经是我们的错误页。
+      const onErrorPage = String(view.webContents.getURL() || '').indexOf('error_page.html') >= 0;
+      if ((this._failureGuard && this._failureGuard.has(tid)) || onErrorPage) {
+        return {
+          ok: false,
+          error: msg,
+          error_page: true,
+          hint: '目标站点加载失败，已显示错误页（可重试 / 改网址）。'
+            + ' 失败详情在页面里，用 ui.get_tree 或 ui.evaluate 读取。',
+        };
+      }
       if (e && e.__deadline) {
         return { ok: false, error: `${e.message} — the page never finished loading; it may still be loading in the background` };
       }
-      return { ok: false, error: String((e && e.message) || e).slice(0, 300) };
+      return { ok: false, error: msg.slice(0, 300) };
     }
     this.repaint(tid);
     return { ok: true };
@@ -1952,9 +1988,77 @@ class PageManager {
       // repaint — which was one of the paths that showed a stale view.
       this._attachRepaintHooks(tabId, view);
     }
+
+    this._attachLoadFailureHooks(tabId, view);
     return tabId;
   }
 
+  /**
+   * 导航失败 → 显示我们自己的错误页，而不是 Chromium 的 chrome-error:// 空白页。
+   *
+   * 为什么必须有：实测（2026-10-14）断网后 ui.navigate 到一个不存在的站点，
+   * 页面停在 chrome-error://chromewebdata/，document.body 长度 0、
+   * 截图 15KB（正常渲染 220KB），**白屏 8 秒不恢复、页面上零个字的提示**。
+   * 这正是用户报的"打开 ai-browser 白屏"：不是启动 bug，是连接失败后
+   * 浏览器给了一个空白文档，而我们对这个事件零监听。
+   *
+   * 不替换成错误页的话，人（产品承诺人可以随时手动介入）看到一块白，
+   * agent（ui.get_tree）也读不到任何东西 —— 两头都瞎。
+   *
+   * 只处理 isMainFrame 的失败：子资源（图片/字体/JS）加载失败太常见，
+   * 不该把整个页面换成错误页。aborted 是页面自己取消的请求（通常是正常的
+   * 跳转竞态），也不算失败。
+   */
+  _attachLoadFailureHooks(tabId, view) {
+    if (!view || !view.webContents || view.webContents.isDestroyed()) return;
+    if (!this._failureHooked) this._failureHooked = new WeakSet();
+    if (this._failureHooked.has(view.webContents)) return;
+    this._failureHooked.add(view.webContents);
+
+    view.webContents.on('did-fail-load', (_e, errorCode, errorDescription, validatedURL, isMainFrame) => {
+      if (!isMainFrame) return;
+      // -3 = ERR_ABORTED：页面自己取消的请求，通常是导航竞态，不是真的失败。
+      if (errorCode === -3) return;
+      // 防重入：错误页自己加载失败时不要无限套娃。
+      // 用普通 Set 而不是 WeakSet —— tabId 是整数，WeakSet.add(整数) 会抛
+      // "Invalid value used in weak set"，而那行异常会从 Electron 的事件回调里
+      // 冒出去，把 loadURL 的 Promise 一起挂死（实测：navigate 到不通的端口，
+      // WS 请求 10s 不返回、页面停在 chrome-error:// 白屏）。
+      if (!this._failureGuard) this._failureGuard = new Set();
+      if (this._failureGuard.has(tabId)) return;
+      this._failureGuard.add(tabId);
+
+      let pagePath = null;
+      try {
+        pagePath = path.join(__dirname, '../renderer/error_page.html');
+      } catch (_) { return; }
+
+      const q = new URLSearchParams({
+        url: String(validatedURL || ''),
+        code: String(errorCode),
+        text: String(errorDescription || ''),
+      });
+      try {
+        view.webContents.loadURL('file://' + pagePath + '?' + q.toString());
+      } catch (e) {
+        console.error('[page_manager] error page load failed:', e.message);
+        this._failureGuard.delete(tabId);
+        return;
+      }
+      // 让 agent 也能读到失败（订阅了事件的会话），而不是只有人看得到。
+      this._broadcast('load_failed', {
+        tab: tabId,
+        url: String(validatedURL || ''),
+        error_code: errorCode,
+        error: String(errorDescription || ''),
+      });
+      // 错误页本身加载成功后清掉防重入标记，否则同 tab 后续失败都不显示。
+      view.webContents.once('did-finish-load', () => {
+        if (this._failureGuard) this._failureGuard.delete(tabId);
+      });
+    });
+  }
+
   /**
    * Attach compositor-repaint hooks to a tab's webContents.
    * Idempotent per tab: re-registering would schedule redundant remove/add
@@ -2072,6 +2176,9 @@ class PageManager {
       // switch to first remaining tab — must re-addBrowserView
       const first = this.tabs.keys().next();
       this.activeTab = first.done ? null : first.value;
+      // 上面是直接改 activeTab（没走 setActive），monitor 不会自己知道；
+      // 不同步的话它会一直拿已关闭的 tab 当"活跃 tab"，淘汰顺序就反了。
+      this.networkMonitor.setActiveTab(this.activeTab);
       if (!first.done) {
         const nextView = this._getView(this.activeTab);
         this.window.addBrowserView(nextView);
@@ -2129,6 +2236,8 @@ class PageManager {
       try { this.window.removeBrowserView(view); } catch(e) {}
     }
     this.activeTab = tabId;
+    // body / 记录淘汰要"先牺牲后台 tab"，所以必须让它知道谁是活跃的。
+    this.networkMonitor.setActiveTab(tabId);
     const view = this._getView(tabId);
     if (view) {
       this.window.addBrowserView(view);
@@ -2183,8 +2292,12 @@ class PageManager {
 
   _layoutView(view) {
     const bounds = this.window.getContentBounds();
-    const TAB_BAR_HEIGHT = 36;
-    view.setBounds({ x: 0, y: TAB_BAR_HEIGHT, width: bounds.width, height: bounds.height - TAB_BAR_HEIGHT });
+    view.setBounds({
+      x: 0,
+      y: config.tabBarHeight,
+      width: bounds.width,
+      height: bounds.height - config.tabBarHeight,
+    });
   }
 
   addSubscription(sessionId, events) {
@@ -2690,6 +2803,10 @@ class PageManager {
         sensitive_headers_optin: this.networkMonitor.sensitiveAllowed,
       },
       limits: this.networkMonitor.captureInfo(tabId).limits,
+      // 诊断用：淘汰优先级与当前占用。回答"我的 body 为什么是 evicted"。
+      active_tab: this.networkMonitor.captureInfo(tabId).active_tab,
+      body_bytes: this.networkMonitor.captureInfo(tabId).body_bytes,
+      max_body_bytes: this.networkMonitor.captureInfo(tabId).max_body_bytes,
       note: 'retention limits are controlled by AI_BROWSER_NETWORK_* env only, never by this call',
     };
   }

package/src/main/ws_server.js

@@ -33,8 +33,27 @@ function findWaitTarget(tree, target) {
   return findInTree(tree, 'label', String(target));
 }
 
+// 进程启动时刻（秒）。供 ui.server_info 报出去 —— pid 会被复用，只比 pid
+// 不够稳；pid + started_at 两个一起才足以判定"是不是同一个进程"。
+const serverStartedAt = Math.floor(Date.now() / 1000);
+
 export function startWSServer(pageManager, port = config.wsPort, onQuit = null) {
-  const wss = new WebSocketServer({ port });
+  // Bind loopback only — the protocol carries no auth. ws' default (host
+  // omitted) is 0.0.0.0, which would expose the browser — including all its
+  // persisted logins — to the entire local network. Override via
+  // AI_BROWSER_WS_HOST only with eyes open.
+  const wss = new WebSocketServer({ port, host: config.wsBindHost });
+
+  // Passing a host pushes Node onto the async DNS-lookup listen path, so
+  // wss.address() is null until 'listening'. Cache it and let callers await.
+  let bound = null;
+  const ready = new Promise((resolve, reject) => {
+    wss.once('listening', () => { bound = wss.address(); resolve(bound); });
+    wss.once('error', reject);
+  });
+  ready.then(() => {
+    console.log(`AI Browser WS server listening on ws://${bound.address}:${bound.port}`);
+  }).catch(() => {});
 
   wss.on('connection', (ws, _req) => {
     const sessionId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
@@ -196,11 +215,39 @@ export function startWSServer(pageManager, port = config.wsPort, onQuit = null)
             send({ jsonrpc: '2.0', id, result: { tabs } });
             break;
           }
+          // 窗口首次显示的时刻与当时页面状态。
+          // 存在的理由：白屏类缺陷的根因是"窗口显示了但渲染器还没画出第一帧"，
+          // 而这只能从窗口侧观测 —— WS 端口在 createWindow 中途就开了，比
+          // showInitialWindow 早，从 agent 侧轮询永远测不到那个时序。
+          // 一次性记录：窗口只首次显示一次，之后一直是它。
+          case 'ui.window_shown': {
+            send({ jsonrpc: '2.0', id, result: { shown: pageManager.windowShownAt || null } });
+            break;
+          }
           case 'ui.set_active_tab': {
             const ok = pageManager.setActive(params.tab);
             send({ jsonrpc: '2.0', id, result: { ok } });
             break;
           }
+          // 服务端的进程身份。存在的理由（2026-10-15 实测）：调用方**无法确认
+          // 自己连上的是不是自己拉起的那个实例**。决定性实验——在"端口忙"预检
+          // 之后让一个冒牌 WS server 抢占端口，e2e 套件照常发出 ui.new_tab /
+          // ui.evaluate / ui.get_tree 却毫不知情：测的是别人的实例，结果毫无
+          // 意义，而且不报错，只给出一堆莫名其妙的失败。
+          // 有了 pid，调用方就能核对"是不是我 spawn 的那个进程"。
+          case 'ui.server_info': {
+            send({
+              jsonrpc: '2.0', id,
+              result: {
+                pid: process.pid,
+                // 进程启动时刻（秒）。pid 可被复用，两个数字一起才够稳。
+                started_at: serverStartedAt,
+                ws_port: port,
+                platform: process.platform,
+              },
+            });
+            break;
+          }
           // === Subscribe/unsubscribe (with response) ===
           case 'ui.subscribe': {
             const events = params.events || [];
@@ -426,10 +473,13 @@ export function startWSServer(pageManager, port = config.wsPort, onQuit = null)
     });
   });
 
-  console.log('AI Browser WS server listening on ws://localhost:' + port);
   return {
-    // Actual bound port (for tests that pass port 0 to grab an ephemeral one).
-    port: wss.address().port,
+    // Resolves once the socket is actually bound (port 0 → ephemeral port known).
+    ready,
+    // Actual bound port/address; null until ready.
+    get port() { return bound ? bound.port : null; },
+    // Security invariant: must be a loopback literal.
+    get host() { return bound ? bound.address : null; },
     close: () => {
       for (const client of wss.clients) {
         try { client.terminate(); } catch (e) {}

package/src/renderer/error_page.html

@@ -0,0 +1,125 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<title>页面无法打开</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  html, body { height: 100%; }
+  body {
+    background: #1e1e1e;
+    color: #d4d4d4;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', sans-serif;
+    font-size: 13px;
+    display: flex;
+    align-items: flex-start;
+    justify-content: center;
+    padding: 48px 24px;
+  }
+  .box { max-width: 560px; width: 100%; }
+  h1 { font-size: 17px; font-weight: 600; color: #f48771; margin-bottom: 4px; }
+  .sub { color: #888; font-size: 12px; margin-bottom: 20px; }
+  .url {
+    background: #252526; border: 1px solid #3c3c3c; border-radius: 4px;
+    padding: 8px 10px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 12px; color: #9cdcfd; word-break: break-all; margin-bottom: 16px;
+  }
+  .reason { margin-bottom: 20px; line-height: 1.6; }
+  .reason b { color: #ce9178; font-weight: 600; }
+  .hint { color: #858585; font-size: 12px; line-height: 1.7; margin-bottom: 24px; }
+  .hint li { margin-left: 18px; margin-bottom: 4px; }
+  .row { display: flex; gap: 8px; }
+  button {
+    background: #0e639c; color: #fff; border: none; border-radius: 4px;
+    padding: 7px 16px; font-size: 12px; cursor: pointer; font-family: inherit;
+  }
+  button:hover { background: #1177bb; }
+  button.ghost { background: #3a3d41; }
+  button.ghost:hover { background: #4a4d51; }
+  input {
+    flex: 1; background: #3c3c3c; border: 1px solid #3c3c3c; border-radius: 4px;
+    color: #d4d4d4; padding: 7px 10px; font-size: 12px; font-family: inherit;
+    min-width: 0;
+  }
+  input:focus { outline: none; border-color: #0e639c; }
+</style>
+</head>
+<body>
+<div class="box">
+  <h1>这个页面打不开</h1>
+  <div class="sub">网络请求失败，浏览器没有拿到任何内容</div>
+
+  <div class="url" id="url"></div>
+
+  <div class="reason" id="reason"></div>
+
+  <div class="hint">
+    常见原因：
+    <li>网络不通，或 DNS 解析失败</li>
+    <li>站点本身不可达 / 已下线</li>
+    <li>公司网络或代理拦截了该域名</li>
+  </div>
+
+  <div class="row">
+    <button id="retry">重试</button>
+    <button id="back" class="ghost">返回上一页</button>
+  </div>
+  <div class="row" style="margin-top:8px">
+    <input id="go" type="text" placeholder="输入网址后按回车打开">
+  </div>
+</div>
+
+<script>
+  // 主进程通过 query 把失败信息带进来。这个页面本身也在 renderer 里跑，
+  // 但它是**我们自己**的页面，不是站点内容 —— 所以人能在这里手动重试 /
+  // 改网址，这正是产品承诺的"随时可以手动介入"。
+  var q = new URLSearchParams(location.search);
+  var failedUrl = q.get('url') || '';
+  var errCode = q.get('code') || '';
+  var errText = q.get('text') || '';
+  document.getElementById('url').textContent = failedUrl || '(未知网址)';
+
+  var REASONS = {
+    '-3': '网络中断（ERR_INTERNET_DISCONNECTED）',
+    '-102': '连接被拒绝（ERR_CONNECTION_REFUSED）',
+    '-105': 'DNS 解析失败，找不到这个域名（ERR_NAME_NOT_RESOLVED）',
+    '-106': '网络不可达（ERR_INTERNET_DISCONNECTED）',
+    '-109': '连接超时，站点没有响应（ERR_CONNECTION_TIMED_OUT）',
+    '-118': '连接超时（ERR_CONNECTION_TIMED_OUT）',
+    '-130': '代理连接失败（ERR_PROXY_CONNECTION_FAILED）',
+    '-200': '证书错误，站点证书无效（ERR_CERT_AUTHORITY_INVALID）',
+    '-201': '证书已过期（ERR_CERT_DATE_INVALID）',
+    '-202': '证书包含错误的主机名（ERR_CERT_COMMON_NAME_INVALID）',
+    '-501': '服务器不支持安全连接（ERR_SSL_PROTOCOL_ERROR）',
+    '-324': '服务器响应为空（ERR_EMPTY_RESPONSE）',
+    '-329': '内容被阻止（ERR_BLOCKED_BY_CLIENT）',
+  };
+  var r = document.getElementById('reason');
+  var known = REASONS[errCode];
+  if (known) {
+    r.innerHTML = '错误类型：<b>' + known + '</b><br>错误码：' + errCode;
+  } else if (errText) {
+    r.innerHTML = '错误类型：<b>' + errText.replace(/</g, '&lt;') + '</b><br>错误码：' + errCode;
+  } else {
+    r.textContent = '错误码：' + (errCode || '(未知)');
+  }
+
+  // 这些按钮要能真的动：走 setWindowOpenHandler 拦不住的本地协议，
+  // 所以用 webContents 回主进程的 ipc。
+  var { ipcRenderer } = require('electron');
+  document.getElementById('retry').addEventListener('click', function () {
+    if (failedUrl) ipcRenderer.send('error-page:navigate', failedUrl);
+  });
+  document.getElementById('back').addEventListener('click', function () {
+    ipcRenderer.send('error-page:back');
+  });
+  var go = document.getElementById('go');
+  go.value = failedUrl;
+  go.addEventListener('keydown', function (e) {
+    if (e.key === 'Enter' && go.value.trim()) {
+      ipcRenderer.send('error-page:navigate', go.value.trim());
+    }
+  });
+</script>
+</body>
+</html>

package/src/renderer/tab_bar.html

@@ -2,114 +2,174 @@
 <html>
 <head>
 <meta charset="utf-8">
+<title>AI Browser</title>
 <style>
   * { margin: 0; padding: 0; box-sizing: border-box; }
+  html, body { height: 100%; overflow: hidden; }
   body {
-    height: 36px;
     background: #1a1a1a;
     display: flex;
-    align-items: center;
-    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+    flex-direction: column;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', sans-serif;
     font-size: 12px;
     color: #ccc;
     user-select: none;
     -webkit-app-region: drag;
   }
-  #tabs {
-    display: flex;
-    flex: 1;
-    overflow: hidden;
-    -webkit-app-region: no-drag;
-  }
+  /* ---- 第一行：tab 条 ---- */
+  #tabs-row { display: flex; align-items: stretch; height: 36px; flex: none; }
+  #tabs { display: flex; flex: 1; overflow: hidden; }
   .tab {
-    display: flex;
-    align-items: center;
-    max-width: 200px;
-    min-width: 80px;
-    padding: 0 12px;
-    height: 36px;
-    cursor: pointer;
-    border-right: 1px solid #2a2a2a;
+    display: flex; align-items: center;
+    max-width: 200px; min-width: 80px; padding: 0 12px; height: 36px;
+    cursor: pointer; border-right: 1px solid #2a2a2a;
     transition: background 0.15s;
+    -webkit-app-region: no-drag;
   }
   .tab:hover { background: #2a2a2a; }
   .tab.active { background: #2d2d30; color: #fff; border-bottom: 2px solid #007acc; }
   .tab-title {
-    flex: 1;
-    overflow: hidden;
-    text-overflow: ellipsis;
-    white-space: nowrap;
+    flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
     margin-right: 8px;
   }
   .tab-close {
-    width: 16px;
-    height: 16px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    border-radius: 3px;
-    font-size: 14px;
-    color: #666;
-    cursor: pointer;
+    width: 16px; height: 16px; display: flex; align-items: center;
+    justify-content: center; border-radius: 3px; font-size: 14px; color: #666;
+    cursor: pointer; flex: none;
   }
   .tab-close:hover { background: #3a3a3a; color: #fff; }
   #new-tab {
-    width: 36px;
-    height: 36px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    font-size: 20px;
-    cursor: pointer;
-    color: #888;
-    -webkit-app-region: no-drag;
+    width: 36px; height: 36px; display: flex; align-items: center;
+    justify-content: center; font-size: 20px; cursor: pointer; color: #888;
+    -webkit-app-region: no-drag; flex: none;
   }
   #new-tab:hover { background: #2a2a2a; color: #fff; }
-  .tab-id { color: #555; font-size: 10px; margin-right: 4px; }
+  .tab-id { color: #555; font-size: 10px; margin-right: 4px; flex: none; }
+
+  /* ---- 第二行：工具栏（地址栏 + 导航按钮）---- */
+  #toolbar {
+    display: flex; align-items: center; gap: 6px;
+    height: 38px; padding: 0 8px; flex: none;
+    background: #202021; border-bottom: 1px solid #333;
+  }
+  .nav-btn {
+    width: 30px; height: 26px; display: flex; align-items: center;
+    justify-content: center; border: none; border-radius: 4px;
+    background: transparent; color: #bbb; font-size: 14px; cursor: pointer;
+    -webkit-app-region: no-drag; flex: none; padding: 0;
+    font-family: inherit;
+  }
+  .nav-btn:hover:not(:disabled) { background: #3a3a3a; color: #fff; }
+  .nav-btn:disabled { color: #4a4a4a; cursor: default; }
+  #addr {
+    flex: 1; min-width: 0; height: 26px;
+    background: #3c3c3c; border: 1px solid #3c3c3c; border-radius: 4px;
+    color: #e8e8e8; padding: 0 10px; font-size: 12px; font-family: inherit;
+    -webkit-app-region: no-drag;
+  }
+  #addr:focus { outline: none; border-color: #007acc; background: #2d2d2d; }
+  #status {
+    font-size: 11px; color: #777; flex: none; max-width: 260px;
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  }
+  #status.busy { color: #e0a33e; }
 </style>
 </head>
 <body>
-<div id="tabs"></div>
-<div id="new-tab">+</div>
+<div id="tabs-row">
+  <div id="tabs"></div>
+  <div id="new-tab" title="新建标签页">+</div>
+</div>
+
+<div id="toolbar">
+  <button class="nav-btn" id="back"    title="后退" disabled>&#8592;</button>
+  <button class="nav-btn" id="forward" title="前进" disabled>&#8594;</button>
+  <button class="nav-btn" id="reload"  title="刷新">&#8635;</button>
+  <button class="nav-btn" id="stop"    title="停止加载" disabled>&times;</button>
+  <input id="addr" type="text" placeholder="输入网址，回车打开" spellcheck="false" autocomplete="off">
+  <span id="status"></span>
+</div>
+
 <script>
 const { ipcRenderer } = require('electron');
 
+const $ = (id) => document.getElementById(id);
+const tabsEl = $('tabs'), addrEl = $('addr'), statusEl = $('status');
+const backBtn = $('back'), fwdBtn = $('forward'), reloadBtn = $('reload'), stopBtn = $('stop');
+
+// ---- tab 条（原有逻辑，保持可用）----
+// 主进程通过 window.__onNavState 推送地址栏状态（push 模式）。
+// 也暴露 window.__applyNavState 供本地自取（nav:state invoke 的回落）。
+window.__onNavState = function (s) { applyNavState(s); };
+function applyNavState(s) {
+  activeTab = s.tab;
+  // 地址栏只在不是用户正在输入时才更新，否则会打断打字
+  if (document.activeElement !== addrEl) addrEl.value = s.url || '';
+  backBtn.disabled = !s.canBack;
+  fwdBtn.disabled = !s.canForward;
+  reloadBtn.style.display = s.loading ? 'none' : '';
+  stopBtn.style.display = s.loading ? '' : 'none';
+  stopBtn.disabled = !s.loading;
+  statusEl.textContent = s.status || '';
+  statusEl.className = s.loading ? 'busy' : '';
+  addrEl.style.borderColor = s.loading ? '#e0a33e' : '';
+}
+
 async function renderTabs() {
   try {
     const tabs = await ipcRenderer.invoke('tab:list');
-    const container = document.getElementById('tabs');
-    container.innerHTML = '';
+    tabsEl.innerHTML = '';
     for (const tab of tabs) {
       const el = document.createElement('div');
       el.className = 'tab' + (tab.active ? ' active' : '');
       const title = (tab.title || tab.url || 'New Tab').slice(0, 30);
       el.innerHTML = '<span class="tab-id">[' + tab.id + ']</span>' +
-        '<span class="tab-title">' + title + '</span>' +
+        '<span class="tab-title">' + escapeHtml(title) + '</span>' +
         '<span class="tab-close" data-id="' + tab.id + '">&times;</span>';
-      el.addEventListener('click', function(e) {
+      el.addEventListener('click', function (e) {
         if (e.target.classList.contains('tab-close')) {
           ipcRenderer.send('tab:close', parseInt(e.target.dataset.id));
         } else {
           ipcRenderer.send('tab:activate', tab.id);
         }
       });
-      container.appendChild(el);
+      tabsEl.appendChild(el);
     }
-  } catch(e) {
-    // ipcRenderer not ready yet
-  }
+  } catch (e) { /* ipcRenderer 尚未就绪 */ }
+}
+function escapeHtml(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 
-// expose for main process to call
-window.renderTabs = renderTabs;
+// ---- 地址栏 + 导航按钮 ----
+// 所有交互都走 ipc 到主进程，由主进程操作对应 tab 的 webContents。
+// 这里不直接碰页面：地址栏必须能反映**真实**状态（包括 agent 造成的导航），
+// 所以显示数据全部由主进程推送，本地不缓存。
+let activeTab = null;
 
-document.getElementById('new-tab').addEventListener('click', function() {
-  ipcRenderer.send('tab:new');
+ipcRenderer.on('nav:state', (_e, s) => applyNavState(s));
+
+backBtn.addEventListener('click', () => ipcRenderer.send('nav:back'));
+fwdBtn.addEventListener('click', () => ipcRenderer.send('nav:forward'));
+reloadBtn.addEventListener('click', () => ipcRenderer.send('nav:reload'));
+stopBtn.addEventListener('click', () => ipcRenderer.send('nav:stop'));
+
+addrEl.addEventListener('keydown', (e) => {
+  if (e.key !== 'Enter') return;
+  const v = addrEl.value.trim();
+  if (!v) return;
+  addrEl.blur();
+  ipcRenderer.send('nav:go', v);
 });
+// 聚焦时全选，方便直接输入覆盖（浏览器惯例）
+addrEl.addEventListener('focus', () => addrEl.select());
+
+$('new-tab').addEventListener('click', () => ipcRenderer.send('tab:new'));
 
-// Initial render + periodic refresh
+// 初始拉一次状态，然后 tab 条照旧定时刷新
+ipcRenderer.invoke('nav:state').then((s) => { if (s) applyNavState(s); });
 renderTabs();
 setInterval(renderTabs, 1500);
 </script>
 </body>
-</html>
+</html>

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/protocol.js

@@ -76,6 +76,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/version.js

@@ -2,4 +2,4 @@
 // Kept in JS (not imported from package.json) to avoid Node import-attribute
 // (JSON module) compatibility issues inside Electron. package.json "version"
 // is manually synced to this value; tests assert they match.
-export const VERSION = '1.2.1';
+export const VERSION = '1.2.2';