Phoenix-PC 内置浏览器(In-App Browser, IAB)技术方案

1 · 摘要 / 一页概览

2 · 背景与目标

2.1 phoenix-pc 现状

本节基于直接探索 apps/desktop/src/main/browser/window.ts、packages/app/src/browser/runtime/、packages/sdk/src/vm/tools/function-tools/search/browser.ts、packages/sdk/src/browser/ 得出。

2.2 为什么要 Backend C(IAB)

语雀调研 Q1 给出的结论(直接引用):

支持 C,作为「无登录态场景」+「Linux 兜底」+「无扩展用户的 onboarding 体验」补充 backend,不替代 A/B。

2.3 本次范围 / 不在范围

2.4 已确认的关键决策

3 · 总体架构

3.1 phoenix-pc 三 Backend 共存定位

3.2 IAB 内部三层架构(Owner / Main / Agent)

3.3 核心数据流

3.3.1 用户视角:打开侧边栏 + agent 浏览页面

4 · 关键技术决策(带 Codex 实测证据)

证据来源:/Applications/Codex.app/Contents/Resources/app.asar v26.513.20950 解包后逐函数验证(main-kSlb32Yb.js 1.21 MB / comment-preload.js 36.4 MB / app-session-O7kcZj7R.js 4.43 MB / bootstrap.js 3.7 KB / package.json)。

5 · 代码地图与目录布局

新增文件(标 ★)

phoenix-pc/
├── apps/desktop/
│   └── src/
│       ├── main/
│       │   └── browser/
│       │       ├── window.ts                          # 现有(独立 BrowserPreview)
│       │       ├── normalize-url.ts                   # 现有
│       │       └── iab/                               ★ 本次新增
│       │           ├── index.ts                       ★ 入口:registerIabSidebar()
│       │           ├── sidebar-manager.ts             ★ IabSidebarManager(双形态切换)
│       │           ├── session-registry.ts            ★ IabSessionRegistry(tabIdsByPageKey 等)
│       │           ├── cdp-bridge.ts                  ★ IabCdpBridge(debugger.attach/sendCommand)
│       │           ├── input-translator.ts            ★ in-page 翻译器(从 Codex gP() 移植)
│       │           ├── iab-transport.ts               ★ 适配 ExtensionTransport 接口
│       │           ├── screenshot.ts                  ★ capturePage / Page.captureScreenshot 双策略
│       │           ├── navigation-guard.ts            ★ Page.navigationBlocked 接管
│       │           ├── dialog-handler.ts              ★ alert/beforeunload auto-accept
│       │           ├── ipc-handlers.ts                ★ 'phoenix-iab:*' channel 路由
│       │           └── constants.ts                   ★ partition 名 / token 名 / 超时常量
│       ├── preload/
│       │   └── browser/
│       │       ├── content.ts                         # 现有(BrowserPreview)
│       │       ├── toolbar.ts                         # 现有
│       │       └── iab/                               ★ 本次新增
│       │           ├── iab-content.ts                 ★ guest webContents preload(轻量,只暴露 inspect token)
│       │           └── iab-toolbar.ts                 ★ toolbar webContents preload
│       └── renderer/
│           ├── browser/
│           │   ├── toolbar.html                       # 现有
│           │   └── toolbar.ts                         # 现有
│           └── iab/                                   ★ 本次新增
│               ├── sidebar.tsx                        ★ React sidebar 组件(嵌入主聊天 UI)
│               ├── toolbar.html                       ★ IAB toolbar HTML
│               ├── toolbar.tsx                        ★ IAB toolbar React 组件
│               └── styles.css                         ★ IAB UI 样式
│
├── packages/
│   ├── sdk/
│   │   └── src/
│   │       └── vm/tools/function-tools/search/
│   │           ├── browser.ts                         ⚙ 修改:增加 backend='iab' 路由
│   │           └── browser_utils/
│   │               ├── handle-iab-action.ts           ★ 类似 handleRelayDirectAction 的 IAB 适配器
│   │               └── iab-runtime-bridge.ts          ★ 主进程 ↔ tool 桥(走 ipcMain.handle)
│   │
│   └── app/
│       └── src/
│           └── browser/
│               └── runtime/
│                   ├── extension-transport.ts          # 现有(B 用)
│                   ├── browser-runtime.ts              # 现有
│                   ├── tier0-actions.ts                # 现有
│                   ├── actions/                        # 现有 9 个 action,本次 0 改动 ★
│                   └── iab-transport.ts                ★ 新增:IabTransport(实现 ExtensionTransport 接口)
│                                                      # 注:与 main 进程的 iab-transport.ts 是配对关系,
│                                                      # 这里是 renderer/agent 侧的桩,通过 IPC 转到 main
│
└── docs/browser/
    ├── embed-browser-research.md                       # 现有(已评审)
    └── embed-browser-plan.html                         ★ 本文档

修改文件清单

6 · 详细模块设计

M1 · WebContentsView 双视图 + 双形态(sidebar / standalone)

核心逻辑:

• sidebar 模式:IAB 不创建独立 BrowserWindow,而是把 toolbarView + contentView 直接 attach 到 mainWindow(mainWindow.contentView.addChildView(toolbarView))。bounds 通过监听 mainWindow resize + Renderer 的 sidebar-resize IPC 同步
• standalone 模式:复用现有 main/browser/window.ts 的 previewWindow 形态;新创建 BrowserWindow 容纳 toolbar+content。从 sidebar 切换时:① 把 toolbarView/contentView 从 mainWindow detach,② 创建 standalone BrowserWindow,③ 把两个 view attach 过去,④ guest webContents 不重建,debugger 不 detach,会话不丢
• 形态切换:不重建 webContents,只改 view 的宿主 window。partition 不变,登录态不丢

// apps/desktop/src/main/browser/iab/sidebar-manager.ts (骨架)
import { BrowserWindow, WebContentsView, session } from 'electron'
import { IAB_PARTITION, TOOLBAR_HEIGHT } from './constants'

export type IabMode = 'sidebar' | 'standalone'

export class IabSidebarManager {
  private toolbarView: WebContentsView | null = null
  private contentView: WebContentsView | null = null
  private hostWindow: BrowserWindow | null = null
  private mode: IabMode = 'sidebar'
  private sidebarWidth = 480

  constructor(private opts: {
    mainWindowProvider: () => BrowserWindow | null
    onTabReady: (tabId: string, webContents: Electron.WebContents) => void
  }) {}

  async open(url: string, conversationId: string, mode: IabMode = 'sidebar') {
    this.ensureViews()
    await this.setMode(mode)
    this.setConversationId(conversationId)
    await this.contentView!.webContents.loadURL(url)
  }

  private ensureViews() {
    if (this.contentView) return
    const sess = session.fromPartition(IAB_PARTITION)
    this.toolbarView = new WebContentsView({
      webPreferences: {
        preload: getPreloadPath('browser/iab/iab-toolbar'),
        sandbox: false,        // toolbar 是我们自己的 UI,需要 IPC
        contextIsolation: true,
        nodeIntegration: false,
        session: sess,
      },
    })
    this.contentView = new WebContentsView({
      webPreferences: {
        preload: getPreloadPath('browser/iab/iab-content'),
        sandbox: true,         // guest 页面,严格沙盒
        contextIsolation: true,
        nodeIntegration: false,
        webviewTag: false,
        session: sess,
      },
    })
    // CDP 桥与生命周期注册由 IabCdpBridge / IabSessionRegistry 接管
    this.opts.onTabReady('iab-tab-1', this.contentView.webContents)
  }

  async setMode(mode: IabMode) {
    if (this.mode === mode && this.hostWindow) return
    // 1. detach from current host
    if (this.hostWindow && !this.hostWindow.isDestroyed()) {
      this.hostWindow.contentView.removeChildView(this.toolbarView!)
      this.hostWindow.contentView.removeChildView(this.contentView!)
    }
    // 2. resolve new host
    if (mode === 'sidebar') {
      this.hostWindow = this.opts.mainWindowProvider()
    } else {
      this.hostWindow = this.createStandaloneWindow()
    }
    // 3. attach
    this.hostWindow!.contentView.addChildView(this.toolbarView!)
    this.hostWindow!.contentView.addChildView(this.contentView!)
    this.mode = mode
    this.layoutBounds()
  }

  private layoutBounds() {
    if (!this.hostWindow) return
    const b = this.hostWindow.getContentBounds()
    if (this.mode === 'sidebar') {
      const x = b.width - this.sidebarWidth
      this.toolbarView!.setBounds({ x, y: 0, width: this.sidebarWidth, height: TOOLBAR_HEIGHT })
      this.contentView!.setBounds({ x, y: TOOLBAR_HEIGHT, width: this.sidebarWidth, height: b.height - TOOLBAR_HEIGHT })
    } else {
      this.toolbarView!.setBounds({ x: 0, y: 0, width: b.width, height: TOOLBAR_HEIGHT })
      this.contentView!.setBounds({ x: 0, y: TOOLBAR_HEIGHT, width: b.width, height: b.height - TOOLBAR_HEIGHT })
    }
  }
}

M2 · CDP 桥(webContents.debugger)

// apps/desktop/src/main/browser/iab/cdp-bridge.ts
import type { WebContents } from 'electron'
import { IAB_CDP_TIMEOUT_MS } from './constants'
import { translateInputCommand } from './input-translator'

export class IabCdpBridge {
  constructor(private wc: WebContents) {}

  async attach() {
    if (!this.wc.debugger.isAttached()) {
      this.wc.debugger.attach('1.3')
    }
    this.wc.debugger.on('message', (_e, method, params) => this.dispatchEvent(method, params))
  }

  async sendCommand(method: string, params: Record<string, unknown> = {}) {
    // K4 · Input.* 翻译为 in-page JS
    if (method.startsWith('Input.')) {
      return translateInputCommand(this.wc, method, params)
    }
    // K5 · captureBeyondViewport 走真实 CDP
    // K7 · 必须包超时
    return withTimeout(
      this.wc.debugger.sendCommand(method, params),
      IAB_CDP_TIMEOUT_MS,
      `Timed out running CDP command "${method}"`,
    )
  }

  detach() {
    if (this.wc.debugger.isAttached()) {
      try { this.wc.debugger.detach() } catch {}
    }
  }

  private cdpEventListeners = new Set<(method: string, params: unknown) => void>()
  onCdpEvent(cb: (method: string, params: unknown) => void) {
    this.cdpEventListeners.add(cb)
    return () => this.cdpEventListeners.delete(cb)
  }
  private dispatchEvent(method: string, params: unknown) {
    for (const cb of this.cdpEventListeners) cb(method, params)
  }
}

function withTimeout<T>(p: Promise<T>, ms: number, msg: string): Promise<T> {
  return new Promise((resolve, reject) => {
    let done = false
    const t = setTimeout(() => { if (!done) { done = true; reject(new Error(msg)) } }, ms)
    t.unref?.()
    p.then(v => { if (!done) { done = true; clearTimeout(t); resolve(v) } },
            e => { if (!done) { done = true; clearTimeout(t); reject(e) } })
  })
}

M3 · Input 翻译器(in-page JS,保 focus)

来源:Codex main-kSlb32Yb.js 函数 gP(),完整 5KB,从反编译里直接抠出。本次方案原样移植(改名 / 去掉 Codex 业务命名空间)。

// apps/desktop/src/main/browser/iab/input-translator.ts
import type { WebContents } from 'electron'

const TRANSLATOR_IIFE = `(${iabInputTranslator.toString()})`

export async function translateInputCommand(
  wc: WebContents,
  method: string,
  params: Record<string, unknown>,
) {
  const expr = `${TRANSLATOR_IIFE}(${JSON.stringify({ method, params })});`
  const r = await wc.executeJavaScript(expr, true /* userGesture */)
  if (r && typeof r === 'object' && (r as any).ok === true) return {}
  const err = (r && (r as any).error) || 'unknown translation failure'
  throw new Error(`Unable to translate ${method} in IAB: ${err}`)
}

// 注入到 page 内执行的翻译器(不是真的从这里 export,需要改成字符串模板)
function iabInputTranslator(cmd: { method: string; params: any }) {
  // ── 关键实现要点(完整版从 Codex gP() 1:1 抠出) ──
  // 1. elementFromPoint(x, y) + shadow DOM 递归 + same-origin iframe 递归
  // 2. cross-origin iframe 显式抛错(K9)
  // 3. PointerEvent + MouseEvent 双发(modern + legacy 兼容)
  // 4. mousedown → focus(label.control 或最近 focusable 父节点) → click 自动序列
  // 5. wheel → 自定义滚动容器查找 + scrollBy({behavior:'auto'})
  // 6. __phoenixIabExpectedInputTargetToken 元素 token 校验(K10)
  // 7. 鼠标键映射:left=0 / middle=1 / right=2 / back=3 / forward=4
  return { ok: true /* | error: 'msg' */ }
}

M4 · 截图双策略

// apps/desktop/src/main/browser/iab/screenshot.ts
import type { WebContents } from 'electron'

export async function iabScreenshot(
  wc: WebContents,
  bridge: IabCdpBridge,
  opts: { fullPage?: boolean; clip?: { x: number; y: number; width: number; height: number } } = {},
): Promise<Buffer> {
  // K5 · 默认走 capturePage(),GPU compositor,2-3x 快
  if (!opts.fullPage && !opts.clip) {
    const img = await wc.capturePage()
    return img.toPNG()
  }
  // K8 · 全页或带 clip 走真实 CDP,必须特判 captureBeyondViewport
  const params: Record<string, unknown> = {
    format: 'png',
    captureBeyondViewport: opts.fullPage === true,
    fromSurface: true,
  }
  if (opts.clip) params.clip = opts.clip
  const r = await bridge.sendCommand('Page.captureScreenshot', params) as { data: string }
  return Buffer.from(r.data, 'base64')
}

M5 · 单 partition + data-conversation-id 隔离

// apps/desktop/src/main/browser/iab/constants.ts
export const IAB_PARTITION = 'persist:phoenix-iab'             // K6 · 单 partition
export const IAB_CDP_TIMEOUT_MS = 30_000                        // K7
export const IAB_CONVERSATION_ATTR = 'iab-conversation-id'      // 挂到 dataset 里
export const IAB_INPUT_TOKEN_KEY = '__phoenixIabExpectedInputTargetToken'  // K10
export const TOOLBAR_HEIGHT = 48

设置 conversationId 不放在 <webview> data-* 上(我们用 WebContentsView 没有 webview 元素),改放在 IabSessionRegistry 的 routeKey 里,事件回流时通过 webContents.id 反查。partition 全局只有一个,登录态跨会话共享(对齐 Codex 体验)。

清理:

// 提供 IPC: 'phoenix-iab:clear-storage' { storages: ['cookies'|'siteData'|'cache'] }
import { session } from 'electron'
async function clearIabStorage(storages: string[]) {
  const sess = session.fromPartition(IAB_PARTITION)
  await Promise.all(storages.map(s => {
    if (s === 'cache') return sess.clearCache()
    return sess.clearStorageData({ storages: s === 'cookies' ? ['cookies'] : ['cookies', 'localstorage', 'indexdb', 'serviceworkers'] })
  }))
}

M6 · IAB Lifecycle Registry

对应 Codex 的 tabIdsByPageKey / routeKeysByTabId / debuggerListeners / cdpEventListeners 注册表,字段命名沿用 Codex(表达力好)。

// apps/desktop/src/main/browser/iab/session-registry.ts
import type { WebContents } from 'electron'
import { IabCdpBridge } from './cdp-bridge'

export interface IabTabState {
  tabId: string                    // 'phoenix-iab-tab:1'
  cdpTabId: string                 // 与 tabId 同义,用于对外暴露
  conversationId: string
  windowId: number                 // 宿主 BrowserWindow.id
  routeKey: string                 // `${windowId}:${conversationId}`
  webContents: WebContents
  bridge: IabCdpBridge
  url: string
  title: string
  faviconUrl: string | null
}

export class IabSessionRegistry {
  private tabsById = new Map<string, IabTabState>()
  private tabIdsByPageKey = new Map<string, string>()  // routeKey → tabId
  private routeKeysByTabId = new Map<string, string>()
  private seq = 0

  registerTab(conversationId: string, windowId: number, wc: WebContents, bridge: IabCdpBridge) {
    const tabId = `phoenix-iab-tab:${++this.seq}`
    const routeKey = `${windowId}:${conversationId}`
    const state: IabTabState = {
      tabId, cdpTabId: tabId, conversationId, windowId, routeKey,
      webContents: wc, bridge, url: '', title: '', faviconUrl: null,
    }
    this.tabsById.set(tabId, state)
    this.tabIdsByPageKey.set(routeKey, tabId)
    this.routeKeysByTabId.set(tabId, routeKey)
    wc.once('destroyed', () => this.unregisterTab(tabId))
    return state
  }

  unregisterTab(tabId: string) {
    const t = this.tabsById.get(tabId)
    if (!t) return
    t.bridge.detach()
    this.tabsById.delete(tabId)
    this.routeKeysByTabId.delete(tabId)
    this.tabIdsByPageKey.delete(t.routeKey)
  }

  getTabByConversation(conversationId: string, windowId: number) {
    const tabId = this.tabIdsByPageKey.get(`${windowId}:${conversationId}`)
    return tabId ? this.tabsById.get(tabId) : null
  }

  getTab(tabId: string) { return this.tabsById.get(tabId) }
}

M7 · IabTransport(适配 ExtensionTransport 接口,复用 tier0-actions)

关键:让 C 复用 B 的 packages/app/src/browser/runtime/actions/* 不改一行代码。做法:在 packages/app/src/browser/runtime/iab-transport.ts 实现一个与 ExtensionTransport 同型的 transport,内部走 IPC 转发到 main 进程的 IabCdpBridge。

// packages/app/src/browser/runtime/iab-transport.ts
// 与 extension-transport.ts 同型 — 只在桌面端 main 进程或注入 IPC bridge 的 renderer 用

export interface IabTransportConfig {
  send: (method: string, params: unknown) => Promise<unknown>  // 由 main 进程注入
}

export class IabTransport {
  isConnected = true
  constructor(private cfg: IabTransportConfig) {}

  /**
   * tier0-actions 调用形态:
   *   transport.call('CDP.send', { targetId, cdpMethod:'Page.navigate', cdpParams:{url} })
   *   transport.call('snapshot', {...})
   *   transport.call('aria-snapshot', {...})  // 由 actions/snapshot.ts 决定
   */
  async call(method: string, params: unknown): Promise<unknown> {
    return this.cfg.send(method, params)
  }
}

// main 进程注入的 send 实现:
// async function iabSendImpl(method, params) {
//   if (method === 'CDP.send') {
//     const { targetId, cdpMethod, cdpParams } = params as any
//     const tab = registry.getTab(targetId)
//     if (!tab) throw new Error(`Unknown IAB tab: ${targetId}`)
//     return tab.bridge.sendCommand(cdpMethod, cdpParams ?? {})
//   }
//   throw new Error(`IAB transport: method '${method}' not supported`)
// }

M8 · browser tool 增加 'iab' backend

// packages/sdk/src/vm/tools/function-tools/search/browser_shared/contracts.ts (修改)
- export type BrowserBackend = 'sdk' | 'app'
+ export type BrowserBackend = 'sdk' | 'app' | 'iab'

// packages/sdk/src/vm/tools/function-tools/search/browser.ts (路由层修改)
const backend: BrowserBackend = resolveBackend(options, runtime)
switch (backend) {
  case 'sdk':
    return executePlaywrightAction(...)
  case 'app':
    return handleRelayDirectAction(...)
  case 'iab':                                              // ★ 新增
    return handleIabAction(action, params, options)        // ★
}

// packages/sdk/src/vm/tools/function-tools/search/browser_utils/handle-iab-action.ts (新增)
export async function handleIabAction(action, params, opts) {
  // 通过 IPC 桥(IabRuntimeBridge)转发到 main 进程,main 进程内构造 IabTransport
  // 再走 packages/app/src/browser/runtime/tier0-actions.ts 的 executeTier0Action()
  return await iabRuntimeBridge.execute(action, params)
}

backend 选择策略(resolveBackend):

M9 · IPC 通道清单

7 · 与已有 BrowserPreview 的演化关系

当前 apps/desktop/src/main/browser/window.ts(510 行)是一个独立 BrowserWindow 形态的 BrowserPreview。本次 IAB 不删除它,而是按下面方式演化:

8 · 实施路线(W1-W4 MVP)

9 · 验收标准

10 · 风险与坑(基于 Codex 反编译提炼)

11 · Alternatives(本次未采纳但保留)

12 · 后续演进(P1/P2/P3 Roadmap)

这些来自语雀调研 §3.4 / §B.3,IAB 上线后跟进。本次 plan 不实施,但列出来让 reader 看到全景。

13 · 附录 · 关键文件路径与对照

13.1 phoenix-pc 现有相关文件(已存在,本次复用 / 演化)

13.2 Codex IAB 反编译关键证据(可自行复现)

# 1) parse asar pickle header(无需 npm 安装,纯 python)
python3 - <<'EOF'
import struct, json
with open("/Applications/Codex.app/Contents/Resources/app.asar","rb") as f:
    head = f.read(16)
    outer = struct.unpack('<I', head[4:8])[0]
    jlen  = struct.unpack('<I', head[12:16])[0]
    f.seek(16); manifest = json.loads(f.read(jlen).decode('utf-8'))
print(list(manifest['files']['.vite']['files']['build']['files'].keys()))
EOF
# 输出包含:bootstrap.js / main-kSlb32Yb.js / app-session-O7kcZj7R.js /
#           comment-preload.js / preload.js / sandbox-preload.js / ...

# 2) 关键字符串 grep(确认 K1-K15 全部命中)
grep -oE "webviewTag|will-attach-webview|debugger\.attach|capturePage|IAB_LIFECYCLE|\
browser-use-iab|tabIdsByPageKey|routeKeysByTabId|captureBeyondViewport|\
__codexIabExpectedInputTargetToken|persist:codex-browser-app-route|non_mcp_app_sandbox_webview" \
  /tmp/codex-extract/main.js | sort | uniq -c

13.3 Codex 新增命名(phoenix-pc 沿用语义,改 namespace)

本文档为技术方案 DRAFT,等待评审。落地实施前还需:① 主聊天窗口 layout 组件路径定位与改造方案确认;② phoenix-pc Electron 版本与 WebContentsView API 兼容性核对;③ 与 packages/sdk owner 同步 backend selector 策略变更。