agent-browser 架构设计
🏗️ agent-browser 的架构┌─────────────────────────────────────────────────┐│ agent-browser MCP │├─────────────────────────────────────────────────┤│ ││ ┌──────────────────┐ ┌────────────────┐ ││ │ @ref 缓存系统 │ ───▶ │ Token 优化 │ ││ └──────────────────┘ └────────────────┘ ││ ▲ ││ │ ││ ┌────────┴────────────────────────────────┐ ││ │ BrowserManager │ ││ │ - launch() │ ││ │ - getPage() │ ││ │ - getSnapshot() │ ││ │ - getLocatorFromRef(ref) │ ││ └────────────────────────────────────────┘ ││ ▲ ││ │ │├───────────┴─────────────────────────────────┤│ playwright-core ││ (浏览器自动化引擎) │└─────────────────────────────────────────────┘
📦 缓存机制详解
1️⃣ Snapshot（一次性抓取，建立缓存）
// 第一次调用 snapshot
browser_snapshot({ interactive: true })// 内部执行：
async getSnapshot() {const page = this.getPage();// 1. 用 Playwright 抓取页面const snapshot = await getEnhancedSnapshot(page, {interactive: true // 只抓可交互元素});// 2. 缓存 ref 映射this.refMap = snapshot.refs;// refMap = {// "e1": { selector: "button", role: "button", name: "登录" },// "e2": { selector: "input[type='email']", role: "textbox", name: "邮箱" },// ...// }// 3. 返回简洁的树结构return snapshot;
}
返回格式：
@e1 [button] "登录"
@e2 [textbox] "邮箱"
@e3 [textbox] "密码"
@e4 [checkbox] "记住我"
@e5 [link] "忘记密码"
2️⃣ 后续交互（使用缓存，省 Token）
// 用户说：点击登录按钮
browser_click({ element: "@e1" })// 内部执行：
async click(element) {// 1. 从缓存中查找const refData = this.refMap["e1"];// refData = { selector: "button", role: "button", name: "登录" }// 2. 用 Playwright 定位并点击const locator = this.getLocatorFromRef("e1");await locator.click();
}
💡 关键设计点
1. 一次性抓取 vs 多次查询
| 方式 | Playwright MCP | agent-browser MCP |
|---|---|---|
| 获取元素 | 每次都用 selector 查询 DOM | Snapshot 一次，缓存所有元素 |
| Token 成本 | 每次查询都消耗 | 一次成本，多次复用 |
2. Ref 的生命周期
// 1. 导航到新页面
await browser_navigate({ url: "https://example.com" })// 2. Snapshot（建立缓存）
await browser_snapshot({ interactive: true })
// 返回：@e1, @e2, @e3 ...// 3. 使用 ref（从缓存读取）
await browser_click({ element: "@e1" }) // 从缓存获取
await browser_fill({ element: "@e2", text: "test" }) // 从缓存获取// 4. 页面导航后，缓存失效
await browser_click({ element: "@e5" }) // 假设这是链接，会导航// 5. 必须重新 snapshot
await browser_snapshot({ interactive: true })
// 返回新的 refs：@e1, @e2 ...（与之前不同）
3. 智能缓存失效
// src/browser/manager.ts 中的 ref 管理
export class BrowserManager {private refMap: RefMap = {}; // 缓存private lastSnapshot: string = '';async getSnapshot() {const snapshot = await getEnhancedSnapshot(page, options);// 每次 snapshot 都会更新缓存this.refMap = snapshot.refs; // 覆盖旧缓存this.lastSnapshot = snapshot.tree;return snapshot;}getLocatorFromRef(refArg: string): Locator | null {const ref = parseRef(refArg); // "e1" 或 "@e1"const refData = this.refMap[ref]; // 从缓存读取if (!refData) return null; // ref 不存在或已失效// 用缓存的 selector 创建 locatorreturn page.locator(refData.selector);}
}
🎯 Playwright 作为底层引擎
agent-browser 完全依赖 Playwright 做底层操作：
| 操作 | Playwright 原生调用 | agent-browser 封装 |
|---|---|---|
| 启动浏览器 | await chromium.launch() | browserManager.launch() |
| 获取页面 | page.locator() | browserManager.getLocatorFromRef("@e1") |
| 点击 | await locator.click() | 同左 |
| 填写 | await locator.fill() | 同左 |
| 截图 | await page.screenshot() | 同左 |
agent-browser 没有重写自动化逻辑，只是加了缓存层。
📊 Token 节省的来源
传统方式（Playwright MCP）:
每次交互 = 完整 CSS selector
click("#auth-container > div.login-wrapper > form > div:nth-child(5) > button")↑ 每个 token 都要传
agent-browser 方式:
第一次: snapshot（一次性成本，几百 token）
后续: click("@e1") ← 只传 2-3 个 token
✅ 总结
- 底层依赖：agent-browser 100% 基于 Playwright 实现浏览器自动化，未重写核心逻辑。
- 核心优化：通过 snapshot 一次性抓取页面元素并建立 ref-selector 缓存映射，替代每次交互都查询 DOM 的方式。
- Token 节省：首次 snapshot 付出一次性 Token 成本，后续交互仅需传递简短的 ref ID（如 @e1），大幅降低 Token 消耗，且页面导航后缓存会失效，需重新 snapshot。