基于Gemini与Playwright构建智能浏览器代理：从自动化到认知决策

1. 项目概述：当浏览器学会“思考”

最近在折腾一个挺有意思的东西：让浏览器自己“动脑子”。听起来有点玄乎？简单说，就是结合 Google 最新的 Gemini 3.5 大语言模型和 Chrome 开发者工具，打造一个能理解页面、自动执行任务的智能代理。这不再是简单的录制回放，而是让浏览器具备一定的“认知”和“决策”能力。比如，你告诉它“帮我把这个商品列表里价格低于100块且评分高于4.5的都加入购物车”，它就能自己分析页面结构，找到符合条件的元素，并完成点击操作。这个项目的核心，就是利用 Gemini 3.5 强大的自然语言理解和代码生成能力，来驱动 Chrome DevTools Protocol 实现对浏览器的精准控制。

为什么是 Gemini 3.5 和 Chrome DevTools 这个组合？首先，Gemini 3.5 在代码生成、逻辑推理和上下文理解上表现非常出色，尤其是其免费、高频率的 API 调用限额，对于个人开发者和小型项目实验非常友好。其次，Chrome DevTools Protocol 是控制 Chrome 或 Chromium 内核浏览器的“终极武器”，它提供了从导航、DOM 操作到网络请求拦截等几乎所有的底层控制接口。将两者结合，相当于给浏览器装上了“大脑”和“神经”，使其能理解高级指令并转化为精确的底层操作。这不仅仅是自动化，更是迈向“智能体”的一步，在数据抓取、自动化测试、网页交互研究乃至日常办公自动化中，都有巨大的想象空间。

2. 核心架构与工具选型解析

2.1 为什么选择 Gemini 3.5 作为“大脑”

在众多大模型中选中 Gemini 3.5，是经过一番考量的。当前开源和闭源的模型选择很多，但构建一个稳定、高效的智能代理，模型需要满足几个关键点：出色的代码生成能力、稳定的长上下文支持、合理的成本以及便捷的 API 接入。

Gemini 3.5 的代码生成能力在多项基准测试中名列前茅，这对于将自然语言指令转化为操作浏览器的 JavaScript 或 Python 脚本至关重要。它的上下文窗口足够大，能记住我们与它多轮对话中设定的复杂任务规则和页面结构信息。最重要的是，其免费 tier 的调用限额（每分钟高达 60 次请求）对于开发和测试阶段绰绰有余，避免了初期投入成本。相比之下，一些同等能力的模型 API 调用成本高昂，而一些小型开源模型在复杂逻辑推理和指令遵循上又不够稳定。

在实际使用中，我通过google-generativeai这个官方 Python SDK 进行接入，非常方便。你需要做的就是在 Google AI Studio 创建一个 API Key，然后就可以开始调用了。模型的响应格式可以设定为json，这对于我们后续解析结构化指令（比如操作类型、目标元素选择器、等待条件等）提供了极大的便利。

2.2 Chrome DevTools Protocol：浏览器的“遥控器”

如果说 Gemini 是大脑，那么 CDP 就是连接大脑和浏览器身体的中枢神经。CDP 是一个基于 WebSocket 的协议，允许外部工具对 Chrome/Chromium 进行检测、调试和控制。我们熟知的 Chrome 开发者工具本身，就是通过 CDP 与浏览器通信的。

对于我们的智能代理项目，我们不直接使用原始的 WebSocket 连接，而是选择一个成熟的客户端库。puppeteer和playwright是两个最主流的选择。它们对 CDP 进行了高级封装，提供了更友好、更稳定的 API。

• Puppeteer：由 Chrome 团队维护，与 Chrome 浏览器契合度最高，API 设计简洁。如果你主要针对 Chrome 环境，它是一个非常可靠的选择。
• Playwright：由微软团队开发，支持 Chromium、Firefox 和 WebKit 三大内核，跨浏览器特性是其最大亮点。它的 API 设计更现代，在一些复杂场景（如自动等待、网络拦截）上可能更顺手。

在这个项目中，我选择了Playwright。原因在于其更强大的自动等待机制（减少了手动编写sleep的需要）以及对网络请求更精细的控制能力，这在处理现代动态网页时尤其重要。智能代理在操作过程中，经常需要等待元素出现、等待网络请求完成，Playwright 的内置等待策略能让我们更专注于业务逻辑。

2.3 系统工作流设计

整个智能代理的核心工作流是一个循环：解析指令 -> 分析页面 -> 生成操作 -> 执行反馈。

1. 指令接收与解析：用户输入自然语言指令，如“登录邮箱并查看未读邮件”。系统首先将指令发送给 Gemini 3.5，要求其将模糊的指令分解为具体的、可执行的步骤序列。例如，输出一个 JSON 数组：[{"action": "navigate", "url": "mail.example.com"}, {"action": "fill", "selector": "#username", "value": "my_email"}, ...]。

2. 页面上下文获取：在执行每个步骤前，代理需要通过 Playwright 获取当前页面的“快照”。这个快照不仅仅是截图，更重要的是结构化的信息：当前 URL、页面标题、以及所有关键交互元素的 CSS 选择器、文本内容、可见状态等。这些信息将被整理成一段清晰的文本描述，作为上下文再次喂给 Gemini。

3. 动态操作生成：将“当前页面快照”和“下一步待执行动作”一起发送给 Gemini。模型需要根据实时页面状态，动态调整或细化操作。例如，指令是“点击登录按钮”，但模型发现页面上有两个可能的按钮（一个在页头，一个在表单内），它就需要结合上下文（“你正在登录表单中”）选择最可能的那一个，并生成精确的 Playwright 操作代码，如await page.click('form button[type=\"submit\"]')。

4. 执行与容错：执行生成的代码。这里必须有坚固的容错机制。如果执行失败（例如元素未找到、超时），需要将错误信息（如TimeoutError: Waiting for selector \"form button\"）反馈给 Gemini，让它分析失败原因并尝试生成备用方案（比如换一个选择器，或者先滚动到元素可见区域）。

这个循环的关键在于，Gemini 不仅生成初始计划，还在每一步都充当“实时决策者”，根据浏览器反馈的环境信息调整策略，这比传统的固定脚本自动化要灵活和健壮得多。

3. 环境搭建与核心代码实现

3.1 基础环境配置

首先，我们需要一个干净的 Python 环境（建议 3.9 以上）。使用虚拟环境是个好习惯。

# 创建并激活虚拟环境 python -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows # 安装核心依赖 pip install google-generativeai playwright

安装 Playwright 后，还需要安装它所需的浏览器内核。这一步只需做一次：

playwright install chromium

这里选择安装 Chromium 就足够了，因为它最轻量且与 CDP 兼容性最好。接下来，去 Google AI Studio 创建一个 API 密钥并妥善保存。

3.2 智能代理核心类封装

我将核心功能封装在一个SmartBrowserAgent类中，这样逻辑更清晰，也便于扩展。

import asyncio import json import google.generativeai as genai from playwright.async_api import async_playwright, Page, TimeoutError as PlaywrightTimeoutError class SmartBrowserAgent: def __init__(self, api_key: str, model_name: str = "gemini-1.5-pro"): """ 初始化智能代理 :param api_key: Gemini API 密钥 :param model_name: 使用的模型名称，默认为 gemini-1.5-pro """ genai.configure(api_key=api_key) self.model = genai.GenerativeModel( model_name, generation_config={ "temperature": 0.1, # 低随机性，确保生成的操作代码稳定可靠 "response_mime_type": "application/json", # 强制返回 JSON 格式 } ) self.playwright = None self.browser = None self.page: Page = None self.context = "" # 用于存储多轮对话的上下文 async def start_browser(self, headless: bool = False): """启动浏览器实例。调试阶段建议 headless=False 以便观察。""" self.playwright = await async_playwright().start() self.browser = await self.playwright.chromium.launch(headless=headless) self.page = await self.browser.new_page() # 设置默认超时和视口大小 await self.page.set_viewport_size({"width": 1280, "height": 720}) self.page.set_default_timeout(30000) # 30秒 async def get_page_context(self) -> str: """获取当前页面的结构化上下文信息，这是给模型看的‘眼睛’""" if not self.page: return "Browser not started." # 获取核心页面信息 url = self.page.url title = await self.page.title() # 获取所有可能有交互性的元素信息（这是一个简化示例，实际可以更精细） # 这里我们获取所有 button, a, input, select 元素的简要信息 elements_info = await self.page.evaluate(""" () => { const items = []; const selectors = 'button, a[href], input:not([type="hidden"]), select, textarea, [role="button"], [role="link"]'; document.querySelectorAll(selectors).forEach(el => { const rect = el.getBoundingClientRect(); if (rect.width > 0 && rect.height > 0) { // 粗略判断可见 items.push({ tag: el.tagName.toLowerCase(), text: (el.textContent || el.value || el.placeholder || '').slice(0, 50).trim(), id: el.id, classes: Array.from(el.classList).join('.'), type: el.type, name: el.name, selector: `#${el.id}` || `.${Array.from(el.classList).join('.')}` || el.tagName.toLowerCase() }); } }); return JSON.stringify(items); } """) context = f""" 当前页面状态： - 网址：{url} - 标题：{title} - 可交互元素（部分）： {elements_info} 请根据以上页面状态，执行用户指令。你的响应必须是严格的 JSON 格式，包含 `action` 和 `code` 字段。 `action` 字段描述你要做什么（如：`navigate`, `click`, `fill`, `extract`, `done`）。 `code` 字段是可直接在 Playwright Page 对象上执行的 JavaScript 代码字符串。 """ return context async def execute_instruction(self, user_instruction: str): """核心方法：执行一条自然语言指令""" print(f"\n[用户指令] {user_instruction}") # 将指令和当前页面上下文组合成提示词 page_context = await self.get_page_context() prompt = f""" {page_context} 用户指令：{user_instruction} 请分析当前页面和用户指令，决定下一步操作。如果任务已完成，`action` 设为 `done`。 """ # 调用 Gemini 模型 try: response = await self.model.generate_content_async(prompt) # 解析模型返回的 JSON response_text = response.text.strip('```json\n').strip('\n```').strip() decision = json.loads(response_text) action = decision.get("action") code = decision.get("code") print(f"[模型决策] Action: {action}, Code: {code}") if action == "done": print("任务完成。") return True if code: # 在 Playwright 页面上下文中执行生成的代码 result = await self.page.evaluate(code) print(f"[执行结果] {result}") # 执行后稍作等待，让页面状态稳定 await self.page.wait_for_timeout(1000) # 递归执行，直到任务完成或达到最大步数（此处省略循环控制逻辑） # 实际应用中，这里应有一个循环或状态机来管理多步任务 return False except json.JSONDecodeError as e: print(f"模型返回非 JSON 格式: {response.text}") return True except PlaywrightTimeoutError as e: print(f"执行超时: {e}") # 可以将超时错误反馈给模型，让其重试或调整策略 return False except Exception as e: print(f"执行过程中发生错误: {e}") return True async def close(self): """清理资源""" if self.browser: await self.browser.close() if self.playwright: await self.playwright.stop()

这个类封装了核心流程：启动浏览器、获取页面上下文、调用 Gemini 决策、执行操作。get_page_context函数是关键，它决定了模型能“看到”多少页面信息。上面的实现是一个基础版本，实际应用中可能需要提取更丰富的信息，如表单结构、数据列表、特定区域截图等。

3.3 一个完整的任务执行示例

假设我们要让代理完成“打开 GitHub 趋势页面，并获取前三个仓库的名字”这个任务。我们不会直接写死操作，而是通过自然语言驱动。

import asyncio from smart_browser_agent import SmartBrowserAgent # 假设上面的类保存在这个文件 async def main(): agent = SmartBrowserAgent(api_key="YOUR_GEMINI_API_KEY") try: # 1. 启动浏览器（非无头模式，方便观察） await agent.start_browser(headless=False) # 2. 执行一个多步指令。在实际智能体中，这个指令会被模型分解。 # 这里我们模拟一个分步过程。 instructions = [ "导航到 GitHub 趋势页面 (https://github.com/trending)", "等待页面上的仓库列表加载出来", "提取列表中最前面三个仓库的名字和链接", ] for instr in instructions: done = await agent.execute_instruction(instr) if done: break # 可以在这里加入更复杂的循环和状态判断逻辑 # 3. 最后，我们可以手动检查一下结果，或者让模型输出总结 final_data = await agent.page.evaluate(""" () => { const repos = []; document.querySelectorAll('article h2 a').forEach((link, index) => { if (index < 3) { repos.push({ name: link.textContent.trim(), url: link.href }); } }); return repos; } """) print("提取到的仓库信息：", final_data) await asyncio.sleep(5) # 暂停一下，看看结果 finally: await agent.close() if __name__ == "__main__": asyncio.run(main())

在这个示例中，execute_instruction方法会被调用三次。每次调用，模型都会根据当时的页面状态和新的指令来决定做什么。第一次，页面是空的，所以它会生成导航代码。第二次，页面正在加载，它可能会生成一个等待某个特定选择器出现的代码。第三次，页面加载完毕，它会生成提取数据的代码。这种“感知-决策-执行”的循环，正是智能代理的核心。

4. 高级技巧与优化策略

4.1 提升模型“视力”：更丰富的页面上下文

基础的元素选择器信息往往不够。为了处理更复杂的页面，我们需要给模型提供更强大的“视力”。

• 屏幕截图+视觉模型：除了 DOM 信息，还可以截取当前屏幕或特定区域的截图，使用 Gemini 1.5 Pro 等支持多模态的模型进行视觉分析。这对于识别图标、验证码、或布局极其复杂的组件（如 Canvas 绘图）非常有效。你可以将截图转换为 base64 编码，与文本上下文一起发送给模型。
• 可访问性树：通过await page.accessibility.snapshot()获取页面的可访问性树。这棵树描述了页面的语义结构（如按钮、标题、区域），对于理解页面的功能区域比纯 DOM 更高效。
• 网络请求监控：通过 Playwright 监听网络请求 (page.on(‘request’)和page.on(‘response’))。将关键的 API 请求和响应（特别是 XHR/Fetch 请求）摘要提供给模型。当用户指令是“获取列表数据”时，模型可能会发现直接调用底层 API 比操作 DOM 更高效。

4.2 设计高效的提示工程

模型的性能很大程度上取决于你如何“提问”。针对浏览器代理任务，提示词需要精心设计。

系统提示词：在初始化模型时，可以设定一个系统角色。

self.model = genai.GenerativeModel( model_name, system_instruction="""你是一个专业的网页自动化助手。你的任务是将用户的自然语言指令转化为对网页的安全、精确操作。 你必须始终以 JSON 格式响应，包含 `action` 和 `code` 字段。 `action` 必须是以下之一：`navigate`, `click`, `fill`, `select`, `scroll`, `extract`, `wait`, `done`。 `code` 必须是单行或可在 Playwright Page 上下文中安全执行的 JavaScript 代码片段。 优先使用稳定且唯一的 CSS 选择器（如ID、具有特定意义的类）。避免使用可能变化的索引位置。 如果指令不明确或无法在当前页面执行，请询问澄清问题，`action` 设为 `clarify`。 """ )

上下文管理：维持一个对话历史列表，将之前的交互（用户指令、模型决策、执行结果）作为上下文传递给下一次调用。这能让模型记住任务目标，做出连贯的决策。但要注意上下文长度限制，必要时进行摘要。

结构化输出：强制要求 JSON 输出 (response_mime_type=“application/json”) 是保证后续代码能稳定解析的关键。可以定义更复杂的输出模式，比如包含备用选择器、预期结果描述等字段。

4.3 实现健壮的错误处理与重试机制

网络环境、页面动态变化、模型“幻觉”都会导致操作失败。一个工业级的代理必须有完善的错误处理。

• 操作失败检测：Playwright 操作（如click,fill）会抛出异常。捕获这些异常，并将错误信息（如Error: Element not found for selector: .btn-submit）反馈给模型。提示模型分析错误原因并生成新的策略，例如：“选择器.btn-submit未找到。当前页面有一个button[type=‘submit’]和一个#loginBtn。请根据页面上下文，选择一个更可能正确的选择器重试。”
• 超时与等待策略：不要依赖固定的sleep。使用 Playwright 的wait_for_selector,wait_for_function,wait_for_load_state等方法，并设置合理的超时时间。模型生成的代码应包含这些等待逻辑。
• 循环与终止条件：对于一个多步任务，需要设置最大步数限制，防止进入死循环。同时，定义清晰的任务完成状态（例如，成功跳转到某个 URL、成功获取到目标数据），让模型能准确判断何时返回action: “done”。

5. 实战应用场景与避坑指南

5.1 典型应用场景剖析

1. 复杂数据抓取与整理：传统爬虫难以处理需要登录、交互（点击“加载更多”、下拉筛选）的网站。智能代理可以理解“登录后，点开第二个选项卡，筛选2023年的数据，然后导出CSV”这样的指令，模拟真人操作完成数据获取。难点在于对抗网站的反爬机制（如指纹识别），需要配合 Playwright 的上下文伪装、代理轮换等高级功能。

2. 自动化测试与监控：不仅仅是回归测试。你可以告诉代理：“每天上午9点，检查官网的订单提交流程是否畅通，从商品页加入购物车到支付成功，并截图最后一步。”它能生成测试脚本并执行，发现页面改版导致的元素选择器失效时，还能尝试自我修复（通过更新的页面上下文寻找新选择器）。

3. 个人工作流自动化：处理那些没有开放 API 的网页工具。例如，“每周一早上，从内部报表网站下载上周的销售数据表，重命名为‘销售_YYYYMMDD.xlsx’，并发送邮件给团队。”这需要结合文件操作、邮件发送等本地能力，代理可以生成 Python 主脚本，调用 Playwright 完成网页部分。

4. 研究与竞品分析：快速遍历竞品网站的功能点。“遍历这个 SaaS 产品的定价页面、文档页面和博客，总结出它们强调的五个核心功能特性。”代理可以自动导航、滚动、点击，并将页面关键文本提取出来供进一步分析。

5.2 常见问题与排查技巧实录

在实际开发中，我踩过不少坑，这里总结几个最典型的：

问题1：模型生成的 CSS 选择器不稳定，经常失效。

• 现象：今天还能用的.btn-primary，明天页面改版就找不到了。
• 根因：模型倾向于使用它“看到”的文本和类名，但这些往往是前端框架动态生成或可变的。
• 解决方案：
  • 提示词引导：在系统提示中强调“优先使用id、name、>