knowledge-browser-automation

## Module Structure 原生 Browser Tool 使用一个惰性进程级 Chromium 池，每个 Session 获取独立临时 `BrowserContext`。Agent 工具和 Web 用户测试浏览器都复用 `SessionBrowserRuntime` 契约，但拥有不同 runtime 实例；Web Preview iframe 仍是独立展示能力。 ### Directory Layout - `packages/cli/src/browser/` — 安装检查、进程池、安全、快照权威、制品和 Session runtime - `packages/cli/src/tools/builtin/browser/` — 六个 Agent 工具及有界结果封装 - `packages/cli/src/api/browserSchemas.ts` — Web Browser 请求与共享结果类型 - `packages/cli/src/server/routes/browser.ts` — Web 用户测试浏览器 API - `packages/cli/src/server/WebBrowserSessionRegistry.ts` — Web Session 对应的独立 runtime 注册表 - `packages/cli/web/src/components/preview/` — Preview/Test/External 面板 - `packages/cli/web/src/store/BrowserActivityStore.ts` — Agent Browser tool 活动投影 ### Key Entry Points - `BrowserProcessPool.acquire()` in `packages/cli/src/browser/BrowserProcessPool.ts` — 惰性启动 Chromium 并分配 Context lease - `SessionBrowserRuntime` in `packages/cli/src/browser/SessionBrowserRuntime.ts` — 导航、观察、交互、等待、诊断与页面生命周期 - `BrowserSnapshotAuthority` in `packages/cli/src/browser/BrowserSnapshotAuthority.ts` — 最新 snapshot/ref 的短期授权 - `createBrowserTools()` in `packages/cli/src/tools/builtin/browser/browserTools.ts` — 将 runtime 暴露为六个 deferred 工具 - `BrowserRoutes()` in `packages/cli/src/server/routes/browser.ts` — Web 测试模式的 HTTP 控制面 ## Gotchas - 六个 Browser 工具都没有 opt-in `isRetrySafe`，即使 Snapshot/Wait/Inspect 是 `ReadOnly` 也默认不可自动重放；浏览器断线、超时或动作结果不确定时必须由 Agent 重新观察后显式决定 (`packages/cli/src/tools/builtin/browser/browserTools.ts`, `packages/cli/src/tools/core/createTool.ts`) - `BrowserInteract` 每次尝试在 Playwright 动作前就使输入 snapshot 失效，无论动作成功、超时还是部分失败；同一 `snapshotId/ref` 不能用于第二个动作 (`packages/cli/src/browser/SessionBrowserRuntime.ts`, `packages/cli/src/tools/builtin/browser/browserTools.ts`) - 动作开始后的异常可能返回 `actionApplied='unknown'` 与 `sideEffectsUncertain=true`；此时不能盲目重试提交、点击或输入，必须先获取新快照检查实际页面状态 (`packages/cli/src/browser/types.ts`, `packages/cli/src/browser/SessionBrowserRuntime.ts`) - `applied_observation_failed` 是动作已完成的成功结果，只代表后续观察失败；把它当作动作失败重试会重复副作用 (`packages/cli/src/browser/types.ts`, `packages/cli/src/tools/builtin/browser/browserTools.ts`) - `expectedOrigin` 必须使用含有效端口的 canonical origin，例如 HTTPS 默认端口也归一为 `:443`；它必须同时匹配页面授权 origin、当前 origin 和 snapshot origin (`packages/cli/src/browser/BrowserSecurity.ts`, `packages/cli/src/browser/SessionBrowserRuntime.ts`) - 跨源顶层导航和 popup 在 route 层阻断；同源页面可加载跨源子资源，但跨源或 opaque sandbox iframe 的 ref 不能继承顶层授权 (`packages/cli/src/browser/SessionBrowserRuntime.ts`, `git:7467bfc4`) - popup 在 Frame 尚不可用时只能通过 opener/referrer 归属；多个候选导致归属不唯一时 fail closed，不能借用同源的另一个页面授权 (`packages/cli/src/browser/SessionBrowserRuntime.ts`, `git:35e51f5a`) - fill/type 会拒绝密码、OTP、卡号、安全码、token/key 等凭据控件；可访问名称过长或 `aria-labelledby` 名称不可确认时同样按敏感控件拒绝 (`packages/cli/src/browser/BrowserSecurity.ts`, `packages/cli/src/browser/SessionBrowserRuntime.ts`) - Download 永远取消并使发起交互返回 `browser_download_blocked`；截图才会进入私有 Session artifact store (`packages/cli/src/browser/SessionBrowserRuntime.ts`, `packages/cli/src/browser/BrowserArtifactStore.ts`) - `BrowserWait` 和 `BrowserInspect` 要求已有页面，断线或 reset 后不能隐式恢复；恢复入口只能是 Navigate、Snapshot 或 Page open (`packages/cli/src/browser/SessionBrowserRuntime.ts`, `docs/superpowers/specs/2026-08-25-native-browser-tool-design.md`) - Chromium 不会随 npm 安装自动下载；缺失或沙箱启动失败统一返回 `browser_not_installed`，安装必须显式执行 `blade browser install` (`packages/cli/src/browser/BrowserInstallation.ts`, `packages/cli/src/browser/BrowserProcessPool.ts`) - Agent Browser、Web 用户 Test Browser 与 Preview iframe 相互独立；在一个表面导航不会共享另一个 runtime 的 cookies、页面或 snapshot ID (`packages/cli/src/agent/runtime/SessionRuntime.ts`, `packages/cli/src/server/WebBrowserSessionRegistry.ts`, `packages/cli/web/src/components/preview/BrowserPreview.tsx`) ## Architecture - `BrowserProcessPool` 是唯一 Chromium owner，启动 single-flight，最多 8 个 Context；最后一个 lease 释放时立即关闭浏览器，意外 disconnect 递增 generation 并使旧 lease 失效 (`packages/cli/src/browser/BrowserProcessPool.ts`) - 每个 `SessionBrowserRuntime` 最多 8 页、32 个排队操作，并通过 FIFO gate 串行所有六类操作；工具层的 `parallelism='exclusive'` 与 runtime gate 共同覆盖不同 executor 共享同一 Session runtime 的情况 (`packages/cli/src/browser/BrowserOperationGate.ts`, `packages/cli/src/tools/builtin/browser/browserTools.ts`) - snapshot authority 绑定 page ID、page generation、origin、snapshot ID 和每个 ref 的 role/name fingerprint；交互前再抓 fresh ARIA snapshot 比对，拒绝 DOM 漂移和 ref 重用 (`packages/cli/src/browser/BrowserSnapshotAuthority.ts`, `packages/cli/src/browser/SessionBrowserRuntime.ts`) - `BrowserNavigate` 临时授权一个目标 origin，commit 后才固化为页面授权；失败时只在页面仍停留原授权 origin 时保留旧授权，否则清空 (`packages/cli/src/browser/SessionBrowserRuntime.ts`) - Browser metadata 使用显式字段投影，而页面主体放在 `<browser_data trust="untrusted">` 内并限制总量；Web 活动 Store 只解析白名单中的页面、origin、URL、错误和交互几何 (`packages/cli/src/tools/builtin/browser/browserTools.ts`, `packages/cli/web/src/store/BrowserActivityStore.ts`) - 截图使用 SHA-256 内容寻址的私有 Session 存储，单件 8 MiB、每 Session 32 件/64 MiB；ACP 风格调用不暴露本地路径 (`packages/cli/src/browser/BrowserArtifactStore.ts`, `packages/cli/src/tools/artifacts/SessionArtifactStore.ts`) ## Decisions - Browser 作为原生 ToolRegistry 能力而非 MCP，是为了完整复用权限、Hook、准入、取消、会话持久化和跨表面投影 (`docs/superpowers/specs/2026-08-25-native-browser-tool-design.md`, `git:90fad7fe`) - 采用 ARIA snapshot + opaque ref，不开放 CSS/XPath/evaluate；这限制模型只能操作最新观察中明确出现的控件 (`packages/cli/src/browser/BrowserSnapshotAuthority.ts`, `packages/cli/tests/security/browser-tool-boundary.test.ts`) - Context 是临时且 Session 隔离的，不恢复 cookies/storage；一个浏览器进程只用于资源共享，不构成跨 Session 页面状态共享 (`packages/cli/src/browser/BrowserProcessPool.ts`, `packages/cli/tests/integration/browser-tool-chromium.test.ts`) - 浏览器进程只继承显式 OS 环境白名单并强制 `chromiumSandbox: true`，Provider 凭据和 Session 环境不进入 Chromium (`packages/cli/src/browser/BrowserInstallation.ts`, `packages/cli/src/browser/BrowserProcessPool.ts`) ## Patterns - Navigate/Interact/Page 是 `Execute`，Snapshot/Wait/Inspect 是 `ReadOnly`，但六者都 exclusive；Plan 模式可观察现有页面，却不能导航、交互或管理页面 (`packages/cli/src/tools/builtin/browser/browserTools.ts`, `packages/cli/src/tools/registry/ToolRegistry.ts`) - `BrowserPage(open)` 只创建 `about:blank`，新 HTTP(S) 目的地始终经 `BrowserNavigate` 形成独立权限签名 (`packages/cli/src/browser/SessionBrowserRuntime.ts`, `packages/cli/src/tools/builtin/browser/browserTools.ts`) - URL 投影保留 query key 但把所有值替换为 `[redacted]`，并移除 fragment；诊断只保留方法、资源类型、状态和净化 URL，不记录 headers/body/cookies (`packages/cli/src/browser/BrowserSecurity.ts`, `packages/cli/src/browser/SessionBrowserRuntime.ts`) - Web 只把无序号的 live `tool.start/tool.result` 映射为 Agent Browser 活动，durable replay 不会重新播放鼠标或 loading 状态 (`packages/cli/web/src/store/session/handlers/eventHandlers.ts`, `packages/cli/web/src/store/BrowserActivityStore.ts`) ## Resource And Failure Bounds - ARIA snapshot 上限 48 KiB、默认深度 12/最大 20；截断按完整 UTF-8 行完成，重复 ref 直接使 snapshot 失效 (`packages/cli/src/browser/constants.ts`, `packages/cli/src/browser/BrowserSnapshotAuthority.ts`) - console、page-error、network 各保留最新 256 项，单次最多返回 100 项且总工具输出不超过 64 KiB；容量耗尽不驱逐其他 Session (`packages/cli/src/browser/constants.ts`, `packages/cli/src/browser/SessionBrowserRuntime.ts`) - Runtime reset/disconnect 会递增代际并清空页面与 snapshot 投影；dispose 先关闭 gate、取消 queued/active 操作，再释放 Context lease (`packages/cli/src/browser/SessionBrowserRuntime.ts`) - Web 路由把未安装/断线/已释放映射为 503、Context 容量映射为 429、无效参数映射为 400，其余状态冲突映射为 409 (`packages/cli/src/server/routes/browser.ts`)