Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* BrowserWebviewPool —— RSB web-browser plugin 的 webview 实例池(LRU, K=5)。
*
* 为什么要 pool:每个 web-browser tab 在 DOM 上有自己的 body slot,但 `<webview>`
* 被 React unmount 或跨父节点搬动时,guest webContents 会被销毁/重建,
* 未提交表单、页面内存和浏览历史不能靠复用 DOM 对象保留。池用"停车区"
* 暂存没有 body slot 的 wrapper;已附着页面的 guest 保留依靠 Shell 让宿主
* 常驻并保持祖先位置稳定。正常切换只隐藏宿主,不能经过停车区。
*
* **关键:不要用 React Portal**。Portal 内部跨 reconcile 的搬动会触发 React 把
* 节点 remove + insert,这中间一帧会让 webview detach 丢 webContents。所以
* 整个 pool 走 vanilla DOM,React 只在 effect 里调 `pool.acquire / appendTo`。
*
* LRU(K=5):超过 5 个浏览器 tab 时,淘汰最久未访问的 webview(销毁其
* webContents)。用户开第 6 个 tab 时,最早访问那个被淘汰;淘汰只销毁后台
* webview 实例,**不删 tab**(tab 仍在 RSB tabbar,只是下次激活时会重新创建
* webview + 重新加载)。
*
* 生命周期:
* - acquire(tabId):取/创建 entry,LRU 标 touch,超 K 淘汰最旧
* - acquire / peek 的 wrapper:首次附着到 body slot,切换时留在原 slot
* - touch(tabId):tab 被激活时显式触发 LRU 时间戳更新
* - release(tabId):tab 关闭时显式销毁
*
* dev / HMR 注意:模块重载会丢失模块级单例,旧 webview 实例可能游离 —— Phase 4
* 范围内不处理(全量 reload 时 document.body 会被换,旧节点跟着被 GC)。线上
* 不会触发。
*/
import type { WebviewTag } from 'electron';
import { BROWSER_PARTITION } from './browserPartition';
export type BrowserWebviewGuestFailure =
| { kind: 'render-process-gone'; reason: string }
| { kind: 'unresponsive'; reason: 'unresponsive' };
interface PoolEntry {
tabId: string;
/** webview 的外层 wrapper。首次附着到 caller slot 后,切换只隐藏常驻宿主。
* 真正卸载时可停回 pool container 暂存 DOM,但跨父节点移动不保留 guest。 */
wrapper: HTMLDivElement;
/** 真 `<webview>` 元素,挂在 wrapper 内部。 */
webview: WebviewTag;
/** 单调递增计数,LRU 用 —— 越大越新,淘汰挑最小那个。比 Date.now() 不依赖
* 系统时钟,且能区分同帧多次访问。 */
lastAccess: number;
/** Pool 创建 webview 后立即记录 guest 故障,避免 React hook 尚未绑定时丢事件。 */
guestFailure: BrowserWebviewGuestFailure | null;
}
const POOL_CAPACITY = 5;
const POOL_CONTAINER_ID = 'browser-webview-pool';
class BrowserWebviewPoolImpl {
private entries = new Map<string, PoolEntry>();
private accessCounter = 0;
private container: HTMLDivElement | null = null;
/**
* Automation pin set — tabIds the main-process bridge has marked
* "busy executing automation steps". LRU eviction MUST skip these so the
* automation backend (Phase 3) doesn't get a destroyed webContents mid-call.
*
* The pin is purely advisory at this layer: it never prevents a user from
* closing the tab (explicit `release(tabId)` still works); it only changes
* who the LRU picks when capacity is reached. If every tab in the pool is
* pinned, evictLRU falls back to evicting the oldest one anyway (capacity
* trumps pin) — automation will fail with a clear error rather than the
* pool growing unbounded.
*/
private pinned = new Set<string>();
/**
* pool 的不可见"停车区" —— 没挂到任何 tab body slot 的 wrapper 暂存在这里。
* 保持正常尺寸并留在宿主的合成范围内,供后台 guest 布局、接收输入和截图;
* 移入/移出这里不保证原 guest 或页面状态保留。
*
* lazy 创建:首次 acquire 时才挂到 document.body。
*/
private ensureContainer(): HTMLDivElement {
if (this.container) return this.container;
const existing = document.getElementById(POOL_CONTAINER_ID);
if (existing instanceof HTMLDivElement) {
this.container = existing;
return existing;
}
const div = document.createElement('div');
div.id = POOL_CONTAINER_ID;
// A 1×1 viewport breaks layout and hit testing; an off-screen guest can
// also fail native capturePage with UnknownVizError. Keep it transparent
// at the host origin without hiding or detaching its rendering surface.
div.style.cssText = 'position:fixed;left:0;top:0;width:1280px;height:720px;opacity:0;z-index:-1;pointer-events:none;display:grid;grid-template-columns:1280px;grid-template-rows:720px;';
div.setAttribute('aria-hidden', 'true');
document.body.appendChild(div);
this.container = div;
return div;
}
/**
* 取或创建 pool entry。
* - 命中 → touch LRU,返回现有
* - 未命中 → 创建新 wrapper + webview,触发可能的 LRU 淘汰
*/
acquire(tabId: string): PoolEntry {
const existing = this.entries.get(tabId);
if (existing) {
existing.lastAccess = ++this.accessCounter;
return existing;
}
// 容量满 → 淘汰最旧(选剔除规则:tabId !== 当前请求的)
if (this.entries.size >= POOL_CAPACITY) {
this.evictLRU();
}
const container = this.ensureContainer();
const wrapper = document.createElement('div');
wrapper.dataset.poolTabId = tabId;
// Park every guest in the same cell so later pages do not stack outside
// the host's compositor bounds. Grid placement is inert in a visible slot.
// wrapper 自身负责把 webview 填满它 —— caller slot 给 wrapper 多大宽高,
// webview 跟着拉伸。display:flex 让 webview 100% 填充。
// background 用主题 surface token(规则 16:走 token,不写 hex pair):
// Win 下 webview 首次 attach 前会显示一帧灰白(规则 15 实测),给 wrapper
// 设 surface 色让过渡帧贴近主题(light → 浅,dark → 深),guest 加载后由
// 网页内容覆盖。Mac 实测也会有半帧灰过渡,顺手统一处理。
wrapper.style.cssText =
'position:relative;width:100%;height:100%;display:flex;background-color:var(--surface);grid-area:1 / 1;';
const webview = document.createElement('webview') as WebviewTag;
// 强制 partition —— main 端 hardener 也会兜底,但这里显式写,debug 时更明显。
webview.setAttribute('partition', BROWSER_PARTITION);
// 让 window.open / target=_blank 进入 guestContents.setWindowOpenHandler。
// main 端仍会 deny 原生弹窗并转成 RSB 新 tab;这里不是放开外弹窗。
webview.setAttribute('allowpopups', 'true');
// webview 元素自身透明 —— 灰底兜底交给 wrapper 处理(见上方注释)。
webview.setAttribute('style', 'flex:1;width:100%;height:100%;');
wrapper.appendChild(webview);
const entry: PoolEntry = {
tabId,
wrapper,
webview,
lastAccess: ++this.accessCounter,
guestFailure: null,
};
this.observeGuestLifecycle(entry);
container.appendChild(wrapper);
this.entries.set(tabId, entry);
this.fireEntryCreated(tabId);
return entry;
}
/** 仅取已存在的 entry(用于切 tab 时 touch 而不创建);不存在返回 null。 */
peek(tabId: string): PoolEntry | null {
return this.entries.get(tabId) ?? null;
}
/** 显式 touch LRU 时间戳(tab 激活时调,避免后台 tab 比前台还新)。 */
touch(tabId: string): void {
const e = this.entries.get(tabId);
if (e) e.lastAccess = ++this.accessCounter;
}
/**
* 显式释放 tabId 对应的 entry:从 DOM 移除 wrapper + 从 entries map 删除。
* webview DOM 节点被 remove 后,guest webContents 自动 destroy(Electron 行为)。
* 用户关闭 web-browser tab 时调。
*
* 释放也清掉 automation pin —— pin 跟 entry 生命周期绑定,tab 都不存在了 pin
* 没意义。pinChangeListeners 通知 caller(主要是 rsbBrowserBridge renderer 端
* helper)同步上报 main 端释放。
*/
release(tabId: string): void {
const e = this.entries.get(tabId);
if (!e) return;
e.wrapper.remove();
this.entries.delete(tabId);
if (this.pinned.delete(tabId)) {
this.firePinChange(tabId, false);
}
this.fireRelease(tabId);
}
/**
* 标记 tabId 为 automation pinned —— LRU 淘汰会跳过它。
* 同步操作,幂等(重复 pin 同一 tabId 返回 false 表示状态未变,不触发 listener)。
* pin 一个未知 tabId 也允许(记录意图);未来 caller acquire(tabId) 时,pin 状态
* 已就位。
*/
pinForAutomation(tabId: string): boolean {
if (this.pinned.has(tabId)) return false;
this.pinned.add(tabId);
this.firePinChange(tabId, true);
return true;
}
unpinForAutomation(tabId: string): boolean {
if (!this.pinned.delete(tabId)) return false;
this.firePinChange(tabId, false);
return true;
}
isPinnedForAutomation(tabId: string): boolean {
return this.pinned.has(tabId);
}
/**
* 订阅 pin 状态变化(automation 期间防 LRU 用)。仅供调试 / 上报通道使用,
* 业务逻辑请通过 pin 状态判断分支。
*/
onPinChange(listener: (tabId: string, pinned: boolean) => void): () => void {
this.pinListeners.add(listener);
return () => {
this.pinListeners.delete(listener);
};
}
/**
* 订阅 entry 释放事件。rsbBrowserBridge helper 用它把 release 同步到 main 端
* 的 TabRegistry —— LRU 淘汰用户感知不到,但 main 端必须及时清掉 webContentsId
* 映射,否则 backend 拿到 stale id 调 webContents.fromId 会返回 null。
*/
onRelease(listener: (tabId: string) => void): () => void {
this.releaseListeners.add(listener);
return () => {
this.releaseListeners.delete(listener);
};
}
/**
* 订阅 guest 自关事件(guest 页面调 `window.close()`)。pool 只广播 tabId,
* "该不该真关"的裁决(popup-spawned 判定、store closeTab)在订阅方。
*/
onGuestClose(listener: (tabId: string) => void): () => void {
this.guestCloseListeners.add(listener);
return () => {
this.guestCloseListeners.delete(listener);
};
}
/**
* 订阅新 entry 创建。Shell 中已挂载但隐藏的 hook 用它观察 Agent 显式创建的
* webview;命中已有 entry 的 acquire 不触发。
*/
onEntryCreated(listener: (tabId: string) => void): () => void {
this.entryCreatedListeners.add(listener);
return () => {
this.entryCreatedListeners.delete(listener);
};
}
/**
* guest 生命周期监听必须在 wrapper 接入 document 前安装。Agent 可以在隐藏 tab
* 上显式创建并立即驱动 webview;React hook 收到 entry-created 后才会重新绑定,
* 这段间隙内的崩溃 / 卡死状态由 entry 暂存。
*/
private observeGuestLifecycle(entry: PoolEntry): void {
const onRenderProcessGone = (event: Electron.RenderProcessGoneEvent) => {
entry.guestFailure = {
kind: 'render-process-gone',
reason: event.details.reason,
};
};
const onUnresponsive = () => {
entry.guestFailure = { kind: 'unresponsive', reason: 'unresponsive' };
};
const onResponsive = () => {
if (entry.guestFailure?.kind === 'unresponsive') {
entry.guestFailure = null;
}
};
const onStartLoading = () => {
entry.guestFailure = null;
};
// guest `window.close()` → webview 'close' DOM 事件。监听挂在 pool 层而不是
// useBrowserWebview:hook 只在 tab 被用户看着时才绑定(隐藏 tab 甚至不物化
// webview),而 OAuth callback 页的自关可能发生在后台 tab(eager-spawn /
// 用户已切走)。谁来关、允不允许关由订阅方(rsbBrowserBridge,带
// popup-spawned 判定)决定,pool 只负责广播。
const onGuestClose = () => this.fireGuestClose(entry.tabId);
entry.webview.addEventListener('render-process-gone', onRenderProcessGone);
entry.webview.addEventListener('unresponsive', onUnresponsive);
entry.webview.addEventListener('responsive', onResponsive);
entry.webview.addEventListener('did-start-loading', onStartLoading);
entry.webview.addEventListener('close', onGuestClose);
}
/**
* LRU 淘汰 —— 内部用。优先挑最旧的**未 pinned** entry。如果所有 entry 都
* pinned,fallback 到挑最旧的(capacity 限制比 pin 更高优先级);理论上不会
* 发生(pin 数远小于 POOL_CAPACITY),fallback 是防御式兜底,触发时:
* - release 触发 onRelease listener → bridge 通知 main TabRegistry release
* - 同时 webview DOM 被移除,Electron 销毁 guest webContents
* - main 端 registry 的 destroyed listener 兜底清理(双重保险)
* 因此后续 automation backend 调 `registry.getWebContentsByTabId()` 拿到 null,
* 给出清晰的 lookup miss(而不是 pool 不断膨胀)。
*/
private evictLRU(): void {
let oldestUnpinned: PoolEntry | null = null;
let oldestAny: PoolEntry | null = null;
for (const e of this.entries.values()) {
if (!oldestAny || e.lastAccess < oldestAny.lastAccess) oldestAny = e;
if (this.pinned.has(e.tabId)) continue;
if (!oldestUnpinned || e.lastAccess < oldestUnpinned.lastAccess) oldestUnpinned = e;
}
const victim = oldestUnpinned ?? oldestAny;
if (victim) this.release(victim.tabId);
}
private pinListeners = new Set<(tabId: string, pinned: boolean) => void>();
private releaseListeners = new Set<(tabId: string) => void>();
private guestCloseListeners = new Set<(tabId: string) => void>();
private entryCreatedListeners = new Set<(tabId: string) => void>();
private firePinChange(tabId: string, pinned: boolean): void {
for (const l of this.pinListeners) {
try {
l(tabId, pinned);
} catch {
// listener throw should not break pool internal state mutation
}
}
}
private fireRelease(tabId: string): void {
for (const l of this.releaseListeners) {
try {
l(tabId);
} catch {
// listener throw must not stop the pool from advancing
}
}
}
private fireGuestClose(tabId: string): void {
for (const l of this.guestCloseListeners) {
try {
l(tabId);
} catch {
// listener throw must not stop the pool from advancing
}
}
}
private fireEntryCreated(tabId: string): void {
for (const l of this.entryCreatedListeners) {
try {
l(tabId);
} catch {
// listener throw must not break entry creation
}
}
}
/**
* 释放 pool 内全部 entry。侧边栏宿主窗口切换(内嵌 → 独立子窗口)时调用:
* 本 renderer 的 webview 即将失去宿主语义,留着就是僵尸实例(占内存,且 main
* 端 TabRegistry 的 webContentsId 指向旧窗口 → 自动化 backend 串窗)。逐个走
* release,onRelease 链自动通知 main 清注册。
*/
releaseAll(): void {
for (const tabId of [...this.entries.keys()]) {
this.release(tabId);
}
}
/** 调试用:当前 pool 内的 tabId 列表(按 lastAccess 升序,最旧在前)。 */
inspectTabIds(): string[] {
return [...this.entries.values()]
.sort((a, b) => a.lastAccess - b.lastAccess)
.map((e) => e.tabId);
}
}
/** 全局单例 —— 整个 renderer 进程共享一个 pool。 */
export const browserWebviewPool = new BrowserWebviewPoolImpl();
/** Pool 容量常量(给单测 / 调用方做容量假设)。 */
export const BROWSER_WEBVIEW_POOL_CAPACITY = POOL_CAPACITY;