1. 项目概述与核心价值最近在折腾一个自动化项目需要让程序能像真人一样在网页上操作比如自动填表、点击按钮、提取数据。传统的方案像用 Playwright 或 Puppeteer 写脚本虽然功能强大但有个硬伤太“脆”了。页面结构稍微一变比如一个按钮的 CSS 类名改了或者一个输入框的 ID 变了整个脚本就挂了得手动去改代码里的选择器。这种维护成本对于需要长期运行或者处理大量不同网站的任务来说简直是噩梦。就在我头疼的时候发现了 HyperAgent。它的定位非常清晰给 Playwright 加上 AI 大脑。简单说它让你可以用自然语言比如“点击登录按钮”、“搜索笔记本电脑并提取前五个结果的价格”来驱动浏览器而不是去写那些脆弱的 CSS 或 XPath 选择器。这背后的核心是把大型语言模型LLM的理解能力与 Playwright 强大的浏览器控制能力结合了起来。LLM 负责“看懂”页面理解你的指令并规划操作步骤Playwright 则负责精准地执行这些操作。这样一来脚本的健壮性大大提升因为 LLM 能根据页面的实际内容和语义来定位元素而不是依赖那些容易变化的底层代码标识。HyperAgent 适合谁呢我觉得有三类人特别需要它。第一类是自动化测试工程师尤其是做端到端E2E测试的他们经常要应对频繁变化的 UIHyperAgent 的 AI 驱动方式能显著降低测试脚本的维护成本。第二类是数据工程师或分析师需要从各种结构不一的网站上爬取数据手动写解析规则太费时用自然语言描述需要什么数据让 AI 去识别和提取效率高得多。第三类是任何需要构建复杂网页自动化工作流的开发者比如自动完成一系列表单填写、内容发布、监控报警等任务。HyperAgent 提供了一个更高抽象层的 API让你专注于“做什么”而不是“怎么做”。2. 核心设计思路与两种操作模式解析HyperAgent 的设计哲学很务实不是所有场景都需要动用“重型”的 AI 模型。因此它提供了两种互补的操作模式page.perform()和page.ai()让你可以根据任务的复杂度和对性能、成本的要求进行灵活选择。理解这两种模式的差异和适用场景是高效使用 HyperAgent 的关键。2.1page.perform()精准快速的单步操作page.perform()是为单一、明确的动作设计的。比如“点击登录按钮”、“在搜索框输入‘笔记本电脑’”、“勾选同意条款复选框”。它的工作流程非常直接理解指令将你的自然语言指令如“fill email with userexample.com”发送给 LLM。解析页面LLM 会分析当前页面的可访问性树Accessibility Tree和 DOM 文本内容。这里有个关键优化它会自动过滤掉广告 iframe 等无关内容让分析更聚焦。定位与执行LLM 判断出需要操作的元素如一个typeemail的输入框并生成一个精确的定位指令通常是 XPath。然后HyperAgent 通过 Chrome DevTools Protocol (CDP) 原生驱动使用这个定位信息去执行点击、输入等操作。注意page.perform()默认不启用视觉模式即不截图完全基于文本和可访问性信息进行分析。这带来了几个显著优势速度极快省去了截图、上传图片、视觉模型推理的时间通常响应在秒级以内。成本极低每次调用只产生一次 LLM 的文本交互费用对于 OpenAI GPT-4o 这类模型单次调用成本可能只有几分钱。可靠性高对于有明确文本标签或语义清晰的元素按钮、链接、输入框基于文本的定位非常准确。实操心得对于登录、表单填写、导航菜单点击这类标准化操作page.perform()是首选。它的执行路径非常确定调试起来也简单。我建议在编写自动化流程时先把所有能明确用page.perform()描述的步骤都写出来这能构成一个稳定、低成本的操作骨架。2.2page.ai()处理复杂多步骤任务当你的指令变得复杂比如“在航班搜索网站上查找从迈阿密到新奥尔良、7月16日出发的航班并筛选出价格低于500美元的选项”这时page.perform()就力不从心了。page.ai()正是为这类需要多步骤决策和视觉上下文理解的任务而生。page.ai()的工作模式更像一个自主智能体Agent任务分解LLM 首先会理解你的复杂指令并将其分解成一系列原子操作步骤。环境感知对于每一步它可能需要结合视觉信息。当enableVisualMode: true时HyperAgent 会截取页面截图并可能生成元素叠加层帮助模型理解元素的相对位置和视觉特征。规划与执行模型根据当前页面状态文本视觉规划下一步最佳操作然后执行。执行后页面状态更新模型再次评估循环此过程直到任务完成或无法继续。它的优势在于处理模糊指令能理解“那个蓝色的按钮”、“右边栏的第一个商品”这类依赖视觉或相对位置的描述。自动纠错与适应如果某一步失败了比如元素没找到模型可能会尝试替代方案比如滚动页面、点击其他标签页或者重新表述查找条件。端到端自动化你只需要给出最终目标中间的所有点击、输入、等待、翻页等操作都由 AI 自动完成。参数详解useDomCache: boolean这是一个性能优化选项。设置为true时HyperAgent 会在一次ai()调用中缓存 DOM 快照后续步骤复用避免重复获取和解析 DOM能大幅提升复杂任务的速度。enableVisualMode: boolean默认为false。设置为true会启用截图和视觉分析。这能极大提升对复杂、非标准或图形化界面的理解能力但代价是速度变慢需要截图和视觉模型推理和成本增加。实操心得page.ai()非常强大但也更“重”。我的经验是不要一上来就对整个流程使用ai()。更好的策略是“混合模式”用perform()处理明确的、结构化的步骤如导航到特定URL填写已知字段用ai()处理其中复杂的、需要“智能”判断的子任务。例如先perform(“goto product listing page”)再ai(“sort by price from low to high and click the second item”)。3. 环境搭建与基础使用实战理论讲完了我们动手把环境搭起来跑几个实实在在的例子。我会从安装开始带你一步步体验 HyperAgent 的核心 API。3.1 安装与初始化首先确保你的 Node.js 环境在 18 或以上版本。然后通过 npm 或 yarn 安装 HyperAgent# 使用 npm npm install hyperbrowser/agent # 使用 yarn yarn add hyperbrowser/agent安装完成后我们来创建一个最简单的智能体。你需要一个 LLM 的 API 密钥这里以 OpenAI 为例它也支持 Anthropic、Google Gemini、DeepSeek 等。import { HyperAgent } from hyperbrowser/agent; // 初始化智能体指定 LLM 提供商和模型 const agent new HyperAgent({ llm: { provider: openai, // 也可以是 anthropic, gemini, deepseek model: gpt-4o, // 根据提供商选择对应模型如 claude-3-5-sonnet-20241022, gemini-2.0-flash apiKey: process.env.OPENAI_API_KEY, // 建议从环境变量读取 }, // 可选启用调试模式会输出详细的执行日志 debug: false, }); // 记得在任务结束后关闭智能体释放浏览器资源 // await agent.closeAgent();这里有几个关键点需要注意API 密钥管理永远不要将 API 密钥硬编码在代码中。使用process.env或类似的机密管理服务。模型选择gpt-4o在视觉和理解能力上很强但成本也高。对于纯文本操作gpt-4o-mini是性价比很高的选择。Anthropic 的 Claude 3.5 Sonnet 在长上下文和复杂指令遵循上表现优异。根据你的任务需求和预算做权衡。调试模式在开发阶段将debug设为true非常有用。你会在控制台看到 LLM 的思考过程、它尝试定位的元素、执行的命令等这对于排查为什么 AI 没有按预期操作至关重要。3.2 执行第一个自动化任务executeTaskexecuteTask是最高阶的 API你只需要告诉它最终目标它就会自动管理页面生命周期打开、导航、执行、关闭。const result await agent.executeTask( Navigate to amazon.com, search for wireless headphones, and extract the titles and prices of the first 3 results ); console.log(任务输出:, result.output); console.log(任务是否成功:, result.success); console.log(执行步骤详情:, result.steps);执行这段代码你会看到 HyperAgent 自动打开浏览器访问亚马逊在搜索框输入“wireless headphones”点击搜索然后从结果页中提取前三项的商品标题和价格最后以结构化的格式返回。result.steps里包含了它分解和执行的所有子步骤是理解 AI 工作流程的绝佳材料。踩坑记录在我第一次使用executeTask时指令是“去谷歌航班查票”。结果 AI 打开了google.com然后在首页的搜索框里输入了“flights”这显然不对。问题在于指令不够精确。修改为“Navigate to the websiteflights.google.com”后它就能正确导航到目标网站了。所以给 AI 的指令要尽可能清晰、无歧义包含关键网址和具体的操作对象。3.3 精细控制使用page.ai()和page.perform()对于需要更多控制权的场景我们可以手动创建页面对象并混合使用ai()和perform()。const page await agent.newPage(); // 创建一个新的浏览器页面 // 第一步导航到目标网站使用 perform 进行明确的导航操作 await page.goto(https://flights.google.com, { waitUntil: load }); // 第二步执行一个复杂的多步骤任务让 AI 自动处理 const aiResult await page.ai(search for flights from New York to London in next month, { useDomCache: true, // 启用 DOM 缓存加速 // enableVisualMode: true, // 如果页面很复杂可以开启视觉模式 }); console.log(AI 任务完成最终页面状态或输出:, aiResult.output); // 第三步在 AI 操作后的页面上进行一个明确的单步操作 await page.perform(click the flexible dates checkbox); // 第四步从当前页面提取结构化数据 import { z } from zod; const extractionSchema z.object({ availableFlights: z.array( z.object({ airline: z.string(), departureTime: z.string(), arrivalTime: z.string(), price: z.number(), stops: z.number(), }) ).describe(List of available flight options), }); const extractedData await page.extract( get all the flight options shown on the page, extractionSchema // 使用 Zod 定义期望的数据结构 ); console.log(提取到的航班数据:, extractedData); // 最后别忘了关闭页面或智能体 // await page.close(); // await agent.closeAgent();这个例子展示了典型的混合编程模式goto是标准的 Playwright 方法用于初始导航。ai()处理了“搜索航班”这个包含多个潜在步骤选择出发地、目的地、日期、点击搜索的复杂任务。perform()用于执行一个非常明确的后续操作点击“灵活日期”复选框。extract()是 HyperAgent 的另一个强大功能它利用 LLM 理解页面内容并按照你定义的 Zod Schema 将非结构化的网页信息转换成结构化的 JSON 数据。这对于数据爬取和整合工作流来说是革命性的。重要提示page.extract()非常依赖 LLM 对页面内容的理解。为了提高提取准确性最好在指令中明确指出你要提取的数据位于页面的哪个部分例如“从左侧的搜索结果列表中提取...”。同时Zod Schema 的定义要尽可能详细使用.describe()方法为每个字段添加描述这能极大地引导 LLM 找到正确信息。4. 高级特性与生产级应用当你掌握了基础操作后HyperAgent 的一些高级特性可以帮助你将自动化脚本提升到生产级别应对更复杂、更稳定的需求。4.1 动作缓存实现零成本回放这是 HyperAgent 最让我惊艳的功能之一。每次page.ai()执行时它都会在后台默默记录下所有操作步骤的“指纹”包括点击元素的 XPath、所在的 iframe 索引、输入的文字等。这个记录被称为actionCache。为什么需要这个功能想象一下你有一个每周需要运行一次的报表自动化流程它需要登录系统、导航到某个复杂报表页面、设置一堆筛选条件、然后导出数据。每次都用ai()跑不仅慢需要 AI 重新思考而且贵每次都要花 LLM 的调用费。有了动作缓存你可以把第一次成功执行的动作序列保存下来以后直接“回放”这些精确的物理操作完全绕过 LLM速度极快且成本为零。// 1. 记录一次 AI 操作 const page await agent.newPage(); await page.goto(https://example.com/complex-workflow); const { actionCache } await page.ai(perform the monthly sales data extraction workflow); // actionCache 现在包含了所有步骤的详细信息 // 2. 将缓存保存到文件 import fs from fs/promises; await fs.writeFile(monthly_report_cache.json, JSON.stringify(actionCache, null, 2)); // 3. 下次需要执行相同任务时直接回放 const savedCache JSON.parse(await fs.readFile(monthly_report_cache.json, utf-8)); const samePage await agent.newPage(); await samePage.goto(https://example.com/complex-workflow); const replayResult await samePage.runFromActionCache(savedCache, { maxXPathRetries: 2, // 如果页面结构微调导致 XPath 失效重试2次后会自动回退到 LLM 模式 }); if (replayResult.status completed) { console.log(缓存回放成功未使用 LLM。); } else { console.log(部分步骤回放失败已自动使用 LLM 补全。); }生产环境建议将动作缓存集成到你的 CI/CD 流程中。对于核心的自动化流程先由人工或在一个稳定环境下执行一次生成“黄金标准”缓存。然后在自动化测试或定时任务中使用这个缓存进行回放。这既保证了操作的确定性又极大降低了运行成本和提高了速度。4.2 结构化数据提取与模式验证page.extract()配合 Zod 库将非结构化网页数据转换为强类型 TypeScript 对象的过程变得异常优雅和可靠。import { z } from zod; const productSchema z.object({ name: z.string().describe(The full name/title of the product), price: z.number().describe(The current price in dollars, as a number), isInStock: z.boolean().describe(Whether the product is currently available for purchase), rating: z.number().min(0).max(5).optional().describe(Average customer rating out of 5), features: z.array(z.string()).describe(List of key features or bullet points), }); const page await agent.newPage(); await page.goto(https://www.example-electronics.com/product/xyz123); const data await page.extract( Extract the product information from the main product detail section. Ignore any customer reviews or related products., productSchema ); // TypeScript 会自动推断 data 的类型为 { name: string; price: number; ... } console.log(data.name); // 字符串 console.log(data.price); // 数字 console.log(data.features); // 字符串数组 // 你可以安全地将 data 存入数据库或进行后续处理深度解析这里的魔法在于 Zod Schema 不仅定义了数据类型还通过.describe()为 LLM 提供了额外的上下文。当你说“price”LLM 可能找到 “$299.99” 或 “299.99”。Zod 的z.number()会确保最终输出是数字299.99。z.boolean()会让 LLM 去判断页面上是否有“Out of Stock”或“Add to Cart”按钮来推断库存状态。这种“声明式数据提取”大大减少了后续数据清洗的工作量。4.3 连接外部工具MCP 客户端集成HyperAgent 内置了 MCPModel Context Protocol客户端支持。MCP 是一种让 LLM 安全、可控地使用外部工具和数据的协议。通过集成 MCP 服务器你的 HyperAgent 可以突破浏览器的限制与数据库、API、文件系统、甚至其他软件如 Google Sheets进行交互。一个典型的场景是从网页抓取数据然后自动写入 Google 表格。const agent new HyperAgent({ llm: { provider: openai, model: gpt-4o }, debug: true, }); // 初始化 MCP 客户端连接到一个 Google Sheets 的 MCP 服务器 await agent.initializeMCPClient({ servers: [ { command: npx, args: [ composio/mcplatest, start, --url, YOUR_COMPOSIO_GOOGLE_SHEETS_CONNECTION_URL, // 需要从 Composio 等平台获取 ], }, ], }); // 现在你可以给 AI 一个包含跨工具操作的复杂指令 const result await agent.executeTask( 1. Go to https://news.ycombinator.com 2. Extract the top 10 story titles and their points. 3. Open (or create) a Google Sheet named Hacker News Top Stories. 4. Write the extracted data into the first two columns of the sheet. ); console.log(result.output); // 可能会输出类似“数据已成功写入 Google Sheets链接是...”这个例子展示了 HyperAgent 作为自动化“中枢”的潜力。它不仅能操作浏览器还能通过 MCP 协调其他工具完成端到端的业务流程自动化。目前除了 Composio社区也在为 Slack、Notion、GitHub 等开发 MCP 服务器生态正在快速扩展。4.4 云端扩展与隐身模式对于大规模爬取或需要高并发执行的场景在本地运行浏览器实例很快就会遇到资源瓶颈。HyperAgent 可以与 Hyperbrowser 云服务无缝集成。const agent new HyperAgent({ browserProvider: Hyperbrowser, // 切换到云浏览器提供商 // llm 配置... // 环境变量中需要设置 HYPERBROWSER_API_KEY }); // 接下来的所有操作都会在云端浏览器中执行 const result await agent.executeTask(Scrape product listings from 10 different e-commerce sites);云端模式的好处是显而易见的弹性伸缩、无需管理本地浏览器环境、更好的 IP 匿名性对于防屏蔽很重要。Hyperbrowser 还提供了内置的隐身模式通过一系列技术手段如修改 WebGL 指纹、字体列表、Canvas 指纹等来让自动化浏览器更难以被网站的反爬虫机制检测到。关于隐身模式的思考虽然这个功能很强大但必须负责任地使用。请务必遵守目标网站的robots.txt协议并控制请求频率避免对对方服务器造成压力。自动化工具赋予我们能力也要求我们承担相应的伦理和责任。5. 常见问题、调试技巧与性能优化在实际使用中你肯定会遇到 AI 不按预期执行的情况。别担心这是常态。下面是我踩过无数坑后总结出的排查清单和优化建议。5.1 AI 执行失败或行为怪异问题现象page.ai()执行后没达到效果或者点击了错误的元素。排查步骤开启调试模式初始化HyperAgent时设置debug: true。控制台会输出 LLM 的思考链Chain-of-Thought你能看到它是如何理解你的指令、如何分解步骤、以及它认为当前页面上有哪些可操作元素。这是最重要的调试信息。检查页面加载状态在调用ai()或perform()前确保页面已经完全加载。使用await page.goto(url, { waitUntil: networkidle })或await page.waitForLoadState(networkidle)。AI 是基于当前 DOM 快照做决策的如果页面还在加载它的决策依据就是错误的。简化并精确化指令AI 不是人它需要清晰无歧义的指令。将“找一下便宜的商品”改为“在页面左侧的筛选器中找到‘价格’滑块将上限设置为100美元然后点击‘应用筛选’按钮”。多用名词少用代词。启用视觉模式如果页面元素没有清晰的文本标签比如一个图标按钮或者布局非常复杂尝试在page.ai()中设置enableVisualMode: true。这会让 AI 看到页面截图从而根据视觉特征定位元素。分而治之如果一个复杂的ai()指令失败了尝试把它拆分成几个更小的ai()或perform()指令。先让 AI 完成第一步你检查结果再执行第二步。5.2page.extract()提取数据不准确问题现象提取到的字段为空、错位或者格式不对。解决方案优化 Schema 描述Zod Schema 中的.describe()是你的好朋友。尽可能详细地描述每个字段。例如不要只写price: z.number()而是写price: z.number().describe(“The product’s current price, usually a number with a dollar sign like $29.99, ignore any strikethrough or original prices”)。限定提取范围在给extract()的指令中明确指定从页面的哪个区域提取。例如“从 id 为search-results的 div 容器中提取所有产品信息”或者“只提取主内容区域main标签内的表格数据”。后处理验证对于关键数据可以在提取后加入简单的验证逻辑。比如检查价格是否为正数日期格式是否符合预期。如果验证失败可以尝试重新提取或记录错误。5.3 性能优化与成本控制HyperAgent 的消耗主要在两方面LLM API 调用和浏览器资源本地或云端。优化策略优先使用page.perform()对于所有明确的、单一的操作坚决用perform()代替ai()。这是降低成本和提升速度最有效的方法。善用useDomCache: true在单个page.ai()调用中如果涉及多个步骤务必开启此选项。它能避免重复的 DOM 获取和解析。合理选择 LLM 模型对于不需要复杂推理的简单指令如点击、输入可以使用更小、更便宜的模型如gpt-4o-mini。只在处理复杂视觉任务或逻辑时使用gpt-4o或claude-3-5-sonnet。实现动作缓存对于需要重复执行的稳定流程务必使用前面介绍的 Action Caching 功能。第一次生成缓存后后续执行几乎零成本。管理页面生命周期避免频繁创建和关闭浏览器页面。如果有一系列任务要在同一个网站进行尽量复用同一个page对象。任务全部完成后再调用agent.closeAgent()来清理资源。5.4 稳定性与错误处理自动化脚本需要长期稳定运行良好的错误处理机制必不可少。async function robustAiTask(page, instruction, maxRetries 2) { let lastError; for (let i 0; i maxRetries; i) { try { const result await page.ai(instruction, { useDomCache: true, // 可以在这里根据重试次数调整超时等参数 }); if (result.success) { return result; } // 如果 AI 返回了 success: false也视为一种需要重试的失败 lastError new Error(AI task failed: ${result.error}); } catch (error) { lastError error; console.warn(Attempt ${i 1} failed:, error.message); // 可以在这里加入一些恢复操作比如刷新页面 // await page.reload(); await page.waitForTimeout(2000); // 等待2秒再重试 } } throw lastError; // 重试多次后仍失败抛出错误 } // 使用示例 try { await robustAiTask(page, complete the checkout process); } catch (error) { console.error(关键自动化流程失败:, error); // 发送警报邮件、记录日志、触发备用流程等 }这个简单的重试包装函数可以处理网络波动、页面临时性加载问题以及 AI 偶尔的“抽风”。对于关键业务流结合动作缓存和重试机制能构建出相当鲁棒的自动化解决方案。经过几个月的实战HyperAgent 已经成了我处理网页自动化任务的首选工具。它并没有完全取代传统 Playwright 脚本而是提供了一种更高维度的互补方案。对于快速原型、处理变化频繁的页面、或者需要自然语言交互的场景它的价值无可替代。而它的 Action Caching 和 MCP 集成等特性又让它具备了支撑生产级应用的能力。如果你也在为脆弱的自动化脚本而烦恼或者想探索 AI 如何改变人机交互的方式HyperAgent 绝对值得你花时间深入尝试。