AI Agent与Playwright：用自然语言搭建浏览器自动化桥梁

浏览器自动化这个领域，说新不新，说旧也不旧。过去十来年，我用过的自动化工具从按键精灵到Selenium再到Puppeteer，每一次迭代解决了一部分问题，又带来新的复杂度。真正让我觉得“这事被重新定义了”的，是最近半年在Cursor里用AI Agent模式做浏览器自动化——你不再需要一行行手写选择器、反复试运行修等待时间，而是可以用大白话描述“帮我去某个网站把这几页数据整理出来”，AI Agent会自己去规划步骤、生成脚本、执行、看错误、再修复。这条从“自然语言”到“浏览器操作”的链路，就是我说的“桥梁”。

这篇文章想把这座桥的原理、搭建方式和踩坑实录完整拆一遍，适合两类人看：一类是想把重复网页操作（比如查数据、填表单、扒资料）自动化却总被脚本折腾到放弃的普通用户，另一类是已经在用AI编程工具、想探索AI Agent落地场景的开发者。文中不会只丢给你一套配置命令，还会讲清楚每一步背后的设计原因，以及我在实践中交了学费才明白的教训。

1. 整体架构拆解：是谁在桥的两端搭起了路

1.1 传统浏览器自动化的痛点在哪里

先说说过去为什么这件事这么难。早年间用Selenium写自动化脚本，流程基本是：打开浏览器，定位元素，执行操作，处理等待，反复调试。最大的痛点有三个。

第一个是选择器的脆弱性。页面上一个按钮的class从btn-primary改成btn-danger，脚本就当场崩溃。今天前端框架迭代又频繁，哪怕是一个很小的交互改动，都可能把精心维护的脚本击穿。我维护过一套数据采集脚本，平均每两周就要因为前端调整修一次选择器，时间完全耗在无价值的“找茬”上。

第二个是等待策略的玄学。程序不知道页面资源什么时候加载完，只能用time.sleep(3)这种笨办法。等短了元素没出来，等久了整个流程慢如蜗牛。更麻烦的是有些页面是懒加载的，你得自己处理滚动、判断“加载中”的状态，这些逻辑写起来不复杂，但琐碎到让人烦躁。

第三个是异常处理的死角太多。弹窗、验证码、登录超时、网络抖动，任何一个意外都能让脚本卡死在一个未知状态，然后你只能对着屏幕发呆，一步步排查到底卡在哪个环节。

这些痛点让我形成了根深蒂固的印象：浏览器自动化是一门“能做，但伺候起来很烦”的技术。如果不是高频需求，很少有人愿意花这个维护成本。

1.2 AI Agent改变了什么

AI Agent的出现，改变的不是“自动化的底层执行方式”——底层依然是调用浏览器引擎去真实操作网页——而是改变了“人如何与这套系统交互”。过去你得把需求翻译成精确的代码指令，现在你只需要描述“我想要什么结果”，剩下的拆解、翻译、执行、校验、修错，全部由AI Agent完成。

我拿自己在Cursor里的实际用法举例。我有个需求：每天早上去某资讯站抓取当日更新的十条行业快讯，整理成表格。传统做法是写一个爬虫脚本，处理翻页、解析DOM、清洗数据。用Cursor的Agent模式，我只需要输入一句话：“打开资讯站的行业频道，把今天发布的文章标题和摘要抓下来，输出成Markdown表格，不要包含付费内容。”Agent会自己决定用什么选择器、怎么等待页面加载、怎么提取字段，然后运行脚本、检查输出、发现问题再迭代修复。

这里面最关键的变化是“闭环”。传统脚本写完，你得自己贴到终端跑，看报错，再回去改。Cursor的Agent模式能直接读终端输出，看到错误信息后自己分析原因、修改代码、重新运行，直到跑通为止。人从“全流程驾驶员”变成了“提需求+验收结果”的角色。

1.3 Cursor在其中的桥梁定位

那为什么标题里要提“Cursor”而不是笼统说“AI编程工具”？因为Cursor目前是AI Agent与浏览器自动化集成得最顺手、可复制性最强的方案之一。它本质上是一个高度集成AI能力的编辑器，但Agent模式的运作方式让它超越了一般意义的编辑器，变成了一座真正的桥。

这座桥连接的三端是：你的自然语言需求、机器可执行的浏览器操作代码、以及浏览器内部的实时状态。桥面有两层：一层是语言层，把自然语言翻译成程序代码；另一层是执行层，把代码映射成浏览器内部真实的DOM操作和事件触发。

这种“桥”的位置注定了它需要一个能感知代码执行结果的Agent。这就是为什么普通的AI聊天窗口搞不定——你在网页里问“怎么写一个爬虫”，它能给你一段理论正确的代码，但它看不到你的项目依赖、目录结构、运行时环境，所以生成的代码大概率跑不起来。而Cursor的Agent能读你的项目文件、执行命令、看报错日志，它有完整的上下文感知能力，才能真正把“建议”变成“能跑的方案”。

2. 工具选型与配置要点：为什么是Playwright

2.1 浏览器控制方案对比

构建这座“桥”的公路面，目前主流选择有三条：Selenium、Puppeteer、Playwright。我在不同的项目阶段都试过，直接说结论：如果是配AI Agent使用，Playwright是当前的最优解，没有之一。

Selenium的问题不在于不能做自动化，而在于它的API设计太面向过程，AI Agent生成出来的代码往往会裹上大量样板代码，调试成本高。Puppeteer的问题是绑死了Chrome生态，而且它的API对元素等待的自动处理不如Playwright，Agent写完脚本后经常要花精力补等待逻辑。

Playwright最打动我的是它的“自动等待”设计。它的每个操作（点击、填写、提取）都会自动等待元素处于可交互状态，Agent生成的脚本里不需要到处塞sleep。这对AI生成代码的场景简直太关键了——因为大部分AI写代码时，对页面加载时序的判断很粗糙，自动等待机制正好弥补了这个弱点，让生成代码的“一次通过率”大幅提升。

2.2 环境初始化与依赖安装

环境配置顺序很重要。我先说一个省钱省时间的经验：在项目里单独开一个子目录给自动化脚本用，别跟主项目混在一起。因为Playwright下载的浏览器体积不小，独立目录方便日后清理，也避免把不相关依赖带进主项目的构建流程。

初始化的操作如下，分步骤做：

mkdir browser-automation cd browser-automation npm init -y npm install playwright @playwright/test npx playwright install chromium

这里有个细节值得解释：npm install playwright是核心库，@playwright/test是测试运行器，它在Agent模式下有独特价值——Agent可以用npx playwright test来跑脚本并且拿到格式化的断言输出和错误信息。如果只装了核心库，Agent得自己写一堆输出逻辑才能判断执行结果，调试效率会低不少。

npx playwright install chromium是下载Chromium浏览器内核。这一步经常被新手跳过，然后运行时直接报“浏览器未安装”的错误。默认情况下Playwright不走系统浏览器，而是用自己的内核副本，这样最大的好处是版本可控，不被电脑上浏览器的自动更新干扰。

装完之后，做一次冒烟验证。新建一个smoke.spec.js：

const { test } = require('@playwright/test'); test('smoke', async ({ page }) => { await page.goto('https://example.com'); const title = await page.title(); console.log('页面标题是：', title); });

用npx playwright test smoke.spec.js跑一下。如果没有任何报错，说明桥的路基是稳的。我习惯每次新建项目都留这么一个小脚本，排障时能一键区分“环境坏了”还是“脚本坏了”。

2.3 让Agent更懂你的：配置与对话策略

装好基础依赖，接下来要考虑“怎么让Agent产出稳定代码”。我在实际使用中总结了三层配置，每一层都是踩坑换来的。

第一层是项目级约束，也就是给Cursor写的.cursorrules文件。如果你没有这个概念，它就是项目根目录下一个纯文本文件，里面记录了你希望AI在生成代码时遵守的规则。我给自动化项目写的规则是：

请使用Playwright完成浏览器自动化任务。 所有脚本必须使用async/await，禁止使用window.setTimeout等待。 优先使用page.locator()而不是page.$()。 对于可能不存在的元素，使用locator.count()判断后再操作。 每次导航后，至少验证一次页面关键元素或URL变化。

为什么写这几条？因为AI默认写的代码风格五花八门，有时候会用老式的page.$()，有时候会塞进多个await page.waitForTimeout(3000)。有了规则约束，生成的代码风格稳定，后续你自己审查也省心。

第二层是会话级约束。每次开Agent任务时，把目标描述得具体一点，包括：目标URL、要采集的数据字段、输出格式、需要规避的内容。不要写“抓一下那个网站”，要写“打开https://example.com/news，提取页面上所有文章标题和发布时间，输出为JSON文件，保存到output目录”。描述越具体，Agent自己写代码时拆解步骤就越准。

第三层是权限与执行边界的设定。Cursor的Agent模式可以自行安装依赖、执行命令、修改文件，理论上很方便，但也意味着它可能做出超出预期的操作。我在配置里给Agent设置了“执行命令之前先向我确认”，尤其是npm install这类会影响依赖树的命令。这个设置一开始觉得繁琐，实际用下来发现它反而是个很好的“刹车机制”，避免Agent在调试时反复装重复依赖。

3. 实战流程：从一句话到一个能跑的自动化脚本

3.1 需求描述与任务拆解方法

理论讲完了，上真案例。我挑一个典型场景来演示：一个文章归档站，需要把当前列表页的标题和摘要抓下来存成结构化文件。这类任务在浏览器自动化里非常典型，又不会涉及复杂的登录逻辑，适合作为起步案例。

我通常会用这种结构的描述来向Agent下达任务：

在项目根目录新建脚本archive.js。 任务目标：打开 https://example.com/articles 页面。 等待页面中出现 .article-list 容器，然后找到容器内所有 .article-item 元素。 对每个元素提取：标题（h2.article-title的文本）、摘要（p.article-summary的文本）、发布日期（time.article-date的text或datetime属性）。 将结果按日期降序排列，保存到 output/articles.json。 如果页面为空，把错误信息写入 output/error.log。

这个描述的写法有三个设计点。第一点，我给了明确的文件路径和输出格式，Agent不会自己发挥跑偏；第二点，我指认了容器选择器.article-list和元素选择器.article-item的对应关系，这比让AI自己去猜稳定得多；第三点，我特意写了“如果页面为空怎么处理”的兜底逻辑，不然AI默认只在控制台打印结果，失败时你根本不知道发生了什么。

3.2 Agent生成脚本的执行链路

把需求提交给Agent后，它内部的思维链大致是这样的：首先识别这是一个浏览器自动化任务，要用Playwright解决；然后判断项目里没有安装依赖，自动执行npm install playwright；接着按我的要求创建archive.js；写入初步脚本后运行，发现选择器或页面结构的问题就修；最后把结果写到output/articles.json。

生成的脚本核心部分长这样（这是经过几轮调试后的稳定版本）：

const { chromium } = require('playwright'); (async () => { const browser = await chromium.launch({ headless: true }); const page = await browser.newPage(); await page.goto('https://example.com/articles', { waitUntil: 'domcontentloaded' }); const container = page.locator('.article-list'); await container.waitFor({ state: 'visible', timeout: 15000 }); const items = page.locator('.article-item'); const count = await items.count(); const results = []; for (let i = 0; i < count; i++) { const item = items.nth(i); const title = (await item.locator('h2.article-title').textContent())?.trim(); const summary = (await item.locator('p.article-summary').textContent())?.trim(); const date = await item.locator('time.article-date').getAttribute('datetime'); if (title) { results.push({ title, summary, date }); } } results.sort((a, b) => (a.date || '').localeCompare(b.date || '')); const fs = require('fs'); fs.mkdirSync('output', { recursive: true }); fs.writeFileSync('output/articles.json', JSON.stringify(results, null, 2)); console.log(`采集完成，共 ${results.length} 条数据`); await browser.close(); })();

这段代码里值得注意的细节是container.waitFor({ state: 'visible' })，这个步骤很关键。AI生成的很多脚本喜欢用page.waitForTimeout(2000)，但这个等待是不确定性的赌博。用waitFor关联到真实元素状态，页面晚加载几秒都没关系，只要元素可见就会继续往下走。

还有一个细节：提取字段时用了textContent()?.trim()，这里加了空值保护和去空格。AI不加这些也不影响“跑通”，但会影响数据质量——模板里常见的换行和空格会把字段搞得很脏。我在规则里给Agent强调过“提取文本后必须trim”，实践中效果显著。

3.3 人工审查该看什么地方

说一个很多人忽略的事：AI生成代码的第一版确实能跑通，但跑通不等于跑对。你需要对生成脚本做几处人工审查。

第一处是选择器是否绑定了语义化的属性。AI默认会用class命中元素，这当然可以工作，但更稳的语义定位是类似getByRole('heading', { name: 'xxx' })或getByText('xxx')。如果页面上有role或者aria-label，建议让Agent优先用这些属性，因为它们更稳定，class一变脚本就瘫。

第二处是查它有没有做异常兜底。我见过Agent写了数据提取逻辑，但整个脚本没有try-catch，如果页面改了结构，代码会直接抛异常退出，你拿不到任何部分结果。后来我在.cursorrules里加了要求：“主流程必须包裹try-catch，失败时写入error.log”，就顺多了。

第三处是看输出格式是否方便消费。JSON格式要注意中文字段是否需要转义，直接写文件其实没问题，但如果你打算把输出重定向到终端，建议让AI把结果写成表格字符串，别输出成对象转字符串的样子，否则控制台里全是[object Object]，根本没法看。

我在验证这些点时会做一个快速迭代动作：跑完一次脚本后，手动打开output/articles.json看前三条数据和原始页面核对，确认字段匹配。这个“人工抽样验证”虽然土，但它能防住AI最典型的幻觉问题——代码逻辑看着没毛病，提取的内容却是页面上的广告文案或者面包屑导航。

4. 进阶场景与复杂问题排查

4.1 登录态保持与上下文复用

网页自动化的第一个大坑是登录态。很多目标网站要登录后才开放数据，每次脚本跑都重新登录，不仅慢，还容易触发账号风险控制。我在讲配置时提过storageState，这是处理登录态的利器。

思路很简单：手动登录一次，把Cookie和本地存储状态保存成文件，后面跑脚本时直接加载这份状态，免登录。具体三步走：

// 第一步：手动登录并保存状态 const { chromium } = require('playwright'); (async () => { const browser = await chromium.launch({ headless: false }); const context = await browser.newContext(); const page = await context.newPage(); await page.goto('https://example.com/login'); // 这里手动完成登录操作 await page.waitForTimeout(5000); await context.storageState({ path: 'auth.json' }); await browser.close(); })();

// 第二步：复用它 const context = await browser.newContext({ storageState: 'auth.json' });

这套方案比直接操作Cookie数组要稳得多，因为它连localStorage、sessionStorage这些一并记住了。我的经验是：登录态文件要定期刷新，多数站点Cookie有效期在七天到一个月之间，过期后脚本会静默地跳到登录页，而旧脚本往往还在傻傻地提取页面代码，提取了半天一堆空值。我加了一个“登录态校验点”在脚本开头：进入页面后先检查URL里是否出现login字样，如果出现就中止执行并报警。

4.2 滚动加载与动态渲染的内容怎么抓全

另一类高频问题是页面用JavaScript异步加载内容，就是你往下滚，数据才往下冒。比如微博式的时间线、瀑布流列表、百度图片这类站点。AI写脚本面对无限滚动页面时有个思维惯性：直接提取当前DOM里所有元素，滚动行为不写。结果就是只抓到第一屏。

要让Agent写出正确的无限滚动逻辑，描述里需要明确“滚动到底部直到不再有新的内容出现”。对应的代码逻辑是：

let previousHeight = 0; while (previousHeight < (await page.evaluate(() => document.body.scrollHeight))) { previousHeight = await page.evaluate(() => document.body.scrollHeight); await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight)); await page.waitForTimeout(800); // 给接口留响应时间 }

轮询滚动高度直到不再变化，这个方案有一个缺陷：如果加载是异步渐进的，你可能会在数据还没灌进来时误判“停止加载”。经验做法是在页面底部放一个“已加载全部”或“没有更多了”的提示，用那个元素是否出现来做终止条件。如果目标页面没有这类提示，就得指定一个最大滚动次数，比如30次，到了就退出。

动态渲染的坑也值得专门提一句。不少前端框架页面是“壳子先出，数据后填”的，脚本跳转成功后马上提取内容，看到的全是加载骨架屏。我见过Agent生成的脚本用waitForTimeout(1000)，这在网络好的时候够用，网络一波动就完蛋。稳妥的写法是等待某个“数据加载完成的特征元素”出现，比如骨架屏消失、某个有内容的正文节点出现。我在.cursorrules里加过一条：“禁止使用固定时间和DOM内容渲染完成后再提取的代码”，本质上是这个意思。

4.3 常见翻车场景速查表

这节直接上一份常见问题速查表，都是我真实踩过的坑。按“现象—原因—解法”三栏列出来，方便直接用：

这些坑里，弹窗遮挡是最高频的。前端开发的习惯是把各种运营弹窗和公告提示挂在页面最上层，自动化脚本傻乎乎地去点击目标按钮，结果每次都被透明的遮罩挡住。我实际用的办法是在脚本一开始就检测页面是否存在类似.modal, .popup, [class*="dialog"]的元素，有的话先点掉。这个策略放在脚本最前面，能省掉一大半的点击超时问题。

4.4 与AI协作的稳定习惯

最后说说如何通过调整使用AI的方式，让Agent生成的脚本更稳定。这些习惯不是AI层面的，是人机协作层面的。

第一个习惯是“小步验证，一次只改一个点”。如果你让Agent一次性搞定登录、翻页、提取、存库、发通知，它能力再强也会在某个环节出纰漏，而且出了问题排查起来非常费劲。我通常是拆成三步走：先让Agent写出“只打开页面提取第一页数据”的基础版，跑通了；再追加“登录态模拟”的版块；最后才加“翻页遍历”。每一次新功能都独立验证，这样Agent出错了你能精准定位到是哪一步加的代码坏了。

第二个习惯是“用注释约束Agent”。Cursor的Agent在生成代码时会考虑代码上下文，所以你在文件顶部或者任务描述里用注释写一行“这里不要用网络轮询”，它大概率会遵守。这种用自然语言向代码库注入约束的方式，比在对话里说完就忘强得多。

第三个习惯是“保留一套黄金脚本”。我习惯在项目里维护一个golden.spec.js——内置断言的稳定版本。平时做改动实验都在分支上折腾，只有验证通过的改动才合到主脚本。Agent跑出来的新脚本不直接覆盖黄金版本，而是先并行跑一遍，对比输出差异。这个习惯帮我避免了很多次“AI改一行代码以为没问题，结果把整条流程带崩了”的窘境。

5. 从轻量脚本到稳定服务的扩展思路

一定会有读者问：这套方案能不能做成长期跑的服务？我在实际项目里确实做过类似扩展，分享几条思路，但不会展开成完整教程，因为不同业务场景差异太大。

核心思路是两层拆分：采集逻辑和调度逻辑分开。采集逻辑就是你在Cursor里写好的Playwright脚本，调度部分可以用一个很小的Node服务，按cron表达式定时跑去执行。数据落地这一步，可以省掉专门部署数据库，先用JSON、CSV这样简单格式落到磁盘，数据量上来后再考虑换成数据库。

另一个值得考虑的是失败重试和告警机制。我在调度服务里加了一层简单封装：脚本执行结束会返回退出码，非零退出码就触发重跑，连续三次失败则发一封邮件或Webhook消息提醒人工介入。这一步看似简单，但特别重要——无人值守的自动化程序最怕的不是出错，是出错后没人知道，然后数据一直缺失。

关于是否要上更重的浏览器农场方案，比如分布式容器、云端浏览器集群，我的态度是：先不要。多数场景下，一台普通电脑或一台轻量云服务器跑单实例的Chromium已经够用了。真正的瓶颈往往在目标网站的访问频率限制上，而不是你本机的并发能力。等哪天你发现一个任务要跑几个小时，再考虑并行化也来得及。

如果只是个人使用或者小团队内部工具，我最推荐的是：把项目存储到Git仓库，脚本参数化，目标URL、输出路径、间隔时间都用环境变量或配置文件管理。这样改需求时只需要调整配置，不需要让AI重新生成整套代码。参数化的难度不高，但收益很大。

最后分享一个小技巧：如果你用Cursor的Agent开发自动化脚本，尽量用npx playwright test来跑，而不是直接node xxx.js。因为测试运行器能提供更友好的错误信息、断言机制和测试报告，AI Agent在读到失败信息时，能更准确地定位问题，修复效率高不少。这算是我用了一两个月Agent式浏览器自动化后最想分享的一条经验。

浏览器自动化的技术底座这么多年来没有本质变化，变的从来都是使用者与工具的交互方式。Cursor的AI Agent把之前繁琐的“程序员与代码”的协作，压缩成了“人与意图”的协作。你可以不熟选择器语法，可以不记得Playwright的API，只要需求描述清楚，Agent能把剩下的活干完。我个人的体会是，这类工具最适合的应用场景不是替代复杂的大型爬虫系统，而是把那些“每天花五分钟但极其机械”的网页操作彻底交给机器。别想着一次管制太多，从最简单的取数脚本开始，跑通了再加需求，这个过程本身就是对“AI Agent + 浏览器自动化”这套组合最物有所值的用法。