[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-hyperbrowserai--HyperAgent":3,"tool-hyperbrowserai--HyperAgent":62},[4,18,28,37,45,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":24,"last_commit_at":25,"category_tags":26,"status":17},9989,"n8n","n8n-io\u002Fn8n","n8n 是一款面向技术团队的公平代码（fair-code）工作流自动化平台，旨在让用户在享受低代码快速构建便利的同时，保留编写自定义代码的灵活性。它主要解决了传统自动化工具要么过于封闭难以扩展、要么完全依赖手写代码效率低下的痛点，帮助用户轻松连接 400 多种应用与服务，实现复杂业务流程的自动化。\n\nn8n 特别适合开发者、工程师以及具备一定技术背景的业务人员使用。其核心亮点在于“按需编码”：既可以通过直观的可视化界面拖拽节点搭建流程，也能随时插入 JavaScript 或 Python 代码、调用 npm 包来处理复杂逻辑。此外，n8n 原生集成了基于 LangChain 的 AI 能力，支持用户利用自有数据和模型构建智能体工作流。在部署方面，n8n 提供极高的自由度，支持完全自托管以保障数据隐私和控制权，也提供云端服务选项。凭借活跃的社区生态和数百个现成模板，n8n 让构建强大且可控的自动化系统变得简单高效。",184740,2,"2026-04-19T23:22:26",[16,14,13,15,27],"插件",{"id":29,"name":30,"github_repo":31,"description_zh":32,"stars":33,"difficulty_score":10,"last_commit_at":34,"category_tags":35,"status":17},10095,"AutoGPT","Significant-Gravitas\u002FAutoGPT","AutoGPT 是一个旨在让每个人都能轻松使用和构建 AI 的强大平台，核心功能是帮助用户创建、部署和管理能够自动执行复杂任务的连续型 AI 智能体。它解决了传统 AI 应用中需要频繁人工干预、难以自动化长流程工作的痛点，让用户只需设定目标，AI 即可自主规划步骤、调用工具并持续运行直至完成任务。\n\n无论是开发者、研究人员，还是希望提升工作效率的普通用户，都能从 AutoGPT 中受益。开发者可利用其低代码界面快速定制专属智能体；研究人员能基于开源架构探索多智能体协作机制；而非技术背景用户也可直接选用预置的智能体模板，立即投入实际工作场景。\n\nAutoGPT 的技术亮点在于其模块化“积木式”工作流设计——用户通过连接功能块即可构建复杂逻辑，每个块负责单一动作，灵活且易于调试。同时，平台支持本地自托管与云端部署两种模式，兼顾数据隐私与使用便捷性。配合完善的文档和一键安装脚本，即使是初次接触的用户也能在几分钟内启动自己的第一个 AI 智能体。AutoGPT 正致力于降低 AI 应用门槛，让人人都能成为 AI 的创造者与受益者。",183572,"2026-04-20T04:47:55",[13,36,27,14,15],"语言模型",{"id":38,"name":39,"github_repo":40,"description_zh":41,"stars":42,"difficulty_score":10,"last_commit_at":43,"category_tags":44,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":46,"name":47,"github_repo":48,"description_zh":49,"stars":50,"difficulty_score":24,"last_commit_at":51,"category_tags":52,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",161147,"2026-04-19T23:31:47",[14,13,36],{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":59,"last_commit_at":60,"category_tags":61,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,27],{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":77,"owner_email":77,"owner_twitter":78,"owner_website":79,"owner_url":80,"languages":81,"stars":94,"forks":95,"last_commit_at":96,"license":97,"difficulty_score":24,"env_os":98,"env_gpu":98,"env_ram":98,"env_deps":99,"category_tags":110,"github_topics":111,"view_count":24,"oss_zip_url":77,"oss_zip_packed_at":77,"status":17,"created_at":118,"updated_at":119,"faqs":120,"releases":151},7998,"hyperbrowserai\u002FHyperAgent","HyperAgent","AI Browser Automation","HyperAgent 是一款将大语言模型（LLM）与 Playwright 浏览器自动化框架深度融合的开源工具。它旨在解决传统网页自动化脚本脆弱、维护成本高且难以应对动态页面变化的痛点，让开发者只需使用自然语言指令即可驱动浏览器完成复杂任务，无需再编写繁琐且易失效的选择器代码。\n\n这款工具特别适合需要构建智能爬虫、自动化测试流程或数据处理工作流的开发者使用。其核心亮点在于提供了如 `page.ai()`、`page.perform()` 和 `page.extract()` 等简洁 API，用户可以直接用通俗语言下达“搜索商品并提取价格”等指令。此外，HyperAgent 内置了防检测机制以规避反爬虫拦截，支持动作缓存功能以减少重复的大模型调用成本，并能无缝切换回标准 Playwright 模式以兼顾性能与灵活性。它还具备云端扩展能力，可轻松支撑数百个并发会话，是连接人工智能与网页交互的高效桥梁。","\u003Cdiv align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhyperbrowserai_HyperAgent_readme_8b024b8b6f65.png\" alt=\"Hyperagent Banner\" width=\"800\"\u002F>\n\n  \u003Cp align=\"center\">\n    \u003Cstrong>Intelligent Browser Automation with LLMs\u003C\u002Fstrong>\n  \u003C\u002Fp>\n\n  \u003Cp align=\"center\">\n    \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@hyperbrowser\u002Fagent\">\n      \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@hyperbrowser\u002Fagent?style=flat-square\" alt=\"npm version\" \u002F>\n    \u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhyperbrowserai\u002Fhyperagent\u002Fblob\u002Fmain\u002FLICENSE\">\n      \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fl\u002F@hyperbrowser\u002Fagent?style=flat-square\" alt=\"license\" \u002F>\n    \u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002FzsYzsgVRjh\" style=\"text-decoration:none;\">\n      \u003Cimg alt=\"Discord\" src=\"https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F1313014141165764619?style=flat-square&color=blue\">\n    \u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fx.com\u002FAkshayShekhaw12\">\n      \u003Cimg alt=\"X (formerly Twitter) Follow\" src=\"https:\u002F\u002Fimg.shields.io\u002Ftwitter\u002Ffollow\u002FAkshayShekhaw12?style=social\">\n    \u003C\u002Fa>\n  \u003C\u002Fp>\n\u003C\u002Fdiv>\n\n## Overview\n\nHyperagent is Playwright supercharged with AI. No more brittle scripts, just powerful natural language commands.\nJust looking for scalable headless browsers or scraping infra? Go to [Hyperbrowser](https:\u002F\u002Fapp.hyperbrowser.ai\u002F) to get started for free!\n\nView HyperAgent docs here: https:\u002F\u002Fwww.hyperbrowser.ai\u002Fdocs\u002Fhyperagent\u002Fintroduction\n\n### Features\n\n- 🤖 **AI Commands**: Simple APIs like `page.ai()`, `page.extract()` and `executeTask()` for any AI automation\n- ⚡ **Fallback to Regular Playwright**: Use regular Playwright when AI isn't needed\n- 🥷 **Stealth Mode** – Avoid detection with built-in anti-bot patches\n- ☁️ **Cloud Ready** – Instantly scale to hundreds of sessions via [Hyperbrowser](https:\u002F\u002Fapp.hyperbrowser.ai\u002F)\n- 🔌 **MCP Client** – Connect to tools like Composio for full workflows (e.g. writing web data to Google Sheets)\n- 📼 **Action Caching** – Record and replay workflows deterministically without LLM calls\n\n## Quick Start\n\n### Installation\n\n```bash\n# Using npm\nnpm install @hyperbrowser\u002Fagent\n\n# Using yarn\nyarn add @hyperbrowser\u002Fagent\n```\n\n### CLI\n\n```bash\n$ npx @hyperbrowser\u002Fagent -c \"Find a route from Miami to New Orleans, and provide the detailed route information.\"\n```\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhyperbrowserai_HyperAgent_readme_4d916198393a.gif\" alt=\"Hyperagent Demo\"\u002F>\n\u003C\u002Fp>\n\nThe CLI supports options for debugging or using hyperbrowser instead of a local browser\n\n```bash\n-d, --debug                       Enable debug mode\n-c, --command \u003Ctask description>  Command to run\n--hyperbrowser                    Use Hyperbrowser for the browser provider\n```\n\n### Library\n\n```typescript\nimport { HyperAgent } from \"@hyperbrowser\u002Fagent\";\nimport { z } from \"zod\";\n\n\u002F\u002F Initialize the agent\nconst agent = new HyperAgent({\n  llm: {\n    provider: \"openai\",\n    model: \"gpt-4o\",\n  },\n});\n\n\u002F\u002F Execute a task\nconst result = await agent.executeTask(\n  \"Navigate to amazon.com, search for 'laptop', and extract the prices of the first 5 results\"\n);\nconsole.log(result.output);\n\n\u002F\u002F Use page.ai, page.perform, and page.extract\nconst page = await agent.newPage();\nawait page.goto(\"https:\u002F\u002Fflights.google.com\", { waitUntil: \"load\" });\nawait page.ai(\"search for flights from Rio to LAX from July 16 to July 22\");\nawait page.perform(\"click the search button\");\nconst res = await page.extract(\n  \"give me the flight options\",\n  z.object({\n    flights: z.array(\n      z.object({\n        price: z.number(),\n        departure: z.string(),\n        arrival: z.string(),\n      })\n    ),\n  })\n);\nconsole.log(res);\n\n\u002F\u002F Clean up\nawait agent.closeAgent();\n```\n\n## Two Modes of Operation\n\nHyperAgent provides two complementary APIs optimized for different use cases:\n\n### 🎯 `page.perform()` - Single Granular Actions\n\n> `page.aiAction()` is deprecated and remains available as an alias; prefer `page.perform()` going forward.\n\n**Best for**: Single, specific actions like \"click login\", \"fill email with test@example.com\"\n\n**Advantages**:\n- ⚡ **Fast** - Uses accessibility tree (no screenshots)\n- 💰 **Cheap** - Single LLM call per action\n- 🎯 **Reliable** - Direct element finding and execution\n- 📊 **Efficient** - Text-based DOM analysis with automatic ad-frame filtering\n\n**Example**:\n```typescript\nconst page = await agent.newPage();\nawait page.goto(\"https:\u002F\u002Fexample.com\u002Flogin\");\n\n\u002F\u002F Fast, reliable single actions\nawait page.perform(\"fill email with user@example.com\");\nawait page.perform(\"fill password with mypassword\");\nawait page.perform(\"click the login button\");\n```\n\n### 🧠 `page.ai()` - Complex Multi-Step Tasks\n\n**Best for**: Complex workflows requiring multiple steps and visual context\n\n**Advantages**:\n\n- 🖼️ **Visual Understanding** - Can use screenshots with element overlays\n- 🎭 **Complex Tasks** - Handles multi-step workflows automatically\n- 🧠 **Context-Aware** - Better at understanding page layout and relationships\n- 🔄 **Adaptive** - Can adjust strategy based on page state\n\n**Parameters**:\n\n- `useDomCache` (boolean): Reuse DOM snapshots for speed\n- `enableVisualMode` (boolean): Enable screenshots and overlays (default: false)\n\n**Example**:\n\n```typescript\nconst page = await agent.newPage();\nawait page.goto(\"https:\u002F\u002Fflights.google.com\");\n\n\u002F\u002F Complex task with multiple steps handled automatically\nawait page.ai(\"search for flights from Miami to New Orleans on July 16\", {\n  useDomCache: true,\n});\n```\n\n### 🎨 Mix and Match\n\nCombine both APIs for optimal performance:\n\n```typescript\n\u002F\u002F Use perform for fast, reliable individual actions\nawait page.perform(\"click the search button\");\nawait page.perform(\"type laptop into search\");\n\n\u002F\u002F Use ai() for complex, multi-step workflows\nawait page.ai(\"filter results by price under $1000 and sort by rating\");\n\n\u002F\u002F Extract structured data\nconst products = await page.extract(\n  \"get the top 5 products\",\n  z.object({\n    products: z.array(z.object({ name: z.string(), price: z.number() }))\n  })\n);\n```\n\n## ☁️ Cloud\n\nYou can scale HyperAgent with cloud headless browsers using Hyperbrowser\n\n1. Get a free api key from [Hyperbrowser](https:\u002F\u002Fapp.hyperbrowser.ai\u002F)\n2. Add it to your env as `HYPERBROWSER_API_KEY`\n3. Set your `browserProvider` to `\"Hyperbrowser\"`\n\n```typescript\nconst agent = new HyperAgent({\n  browserProvider: \"Hyperbrowser\",\n});\n\nconst response = await agent.executeTask(\n  \"Go to hackernews, and list me the 5 most recent article titles\"\n);\n\nconsole.log(response);\nawait agent.closeAgent();\n```\n\n## Usage Guide\n\n### Multi-Page Management\n\n```typescript\n\u002F\u002F Create and manage multiple pages\nconst page1 = await agent.newPage();\nconst page2 = await agent.newPage();\n\n\u002F\u002F Execute tasks on specific pages\nconst page1Response = await page1.ai(\n  \"Go to google.com\u002Ftravel\u002Fexplore and set the starting location to New York. Then, return to me the first recommended destination that shows up. Return to me only the name of the location.\"\n);\nconst page2Response = await page2.ai(\n  `I want to plan a trip to ${page1Response.output}. Recommend me places to visit there.`\n);\n\nconsole.log(page2Response.output);\n\n\u002F\u002F Get all active pages\nconst pages = await agent.getPages();\nawait agent.closeAgent();\n```\n\n## Customization\n\n### Output Schema Definition\n\nHyperAgent can extract data in a specified schema. The schema can be passed in at a per-task level\n\n```typescript\nimport { z } from \"zod\";\n\nconst agent = new HyperAgent();\nconst agentResponse = await agent.executeTask(\n  \"Navigate to imdb.com, search for 'The Matrix', and extract the director, release year, and rating\",\n  {\n    outputSchema: z.object({\n      director: z.string().describe(\"The name of the movie director\"),\n      releaseYear: z.number().describe(\"The year the movie was released\"),\n      rating: z.string().describe(\"The IMDb rating of the movie\"),\n    }),\n  }\n);\nconsole.log(agentResponse.output);\nawait agent.closeAgent();\n```\n\n```bash\n{\n  \"director\": \"Lana Wachowski, Lilly Wachowski\",\n  \"releaseYear\": 1999,\n  \"rating\": \"8.7\u002F10\"\n}\n```\n\n### Using Different LLM Providers\n\nHyperagent supports multiple LLM providers with native SDKs for better performance and reliability.\n\n```typescript\n\u002F\u002F Using OpenAI\nconst agent = new HyperAgent({\n  llm: {\n    provider: \"openai\",\n    model: \"gpt-4o\",\n  },\n});\n\n\u002F\u002F Using Anthropic's Claude\nconst agent = new HyperAgent({\n  llm: {\n    provider: \"anthropic\",\n    model: \"claude-sonnet-4-0\",\n  },\n});\n\n\u002F\u002F Using Google Gemini\nconst agent = new HyperAgent({\n  llm: {\n    provider: \"gemini\",\n    model: \"gemini-2.5-flash\",\n  },\n});\n\n\u002F\u002F Using DeepSeek\nconst agent = new HyperAgent({\n  llm: {\n    provider: \"deepseek\",\n    model: \"deepseek-chat\",\n  },\n});\n```\n\n### MCP Support\n\nHyperAgent functions as a fully functional MCP client. For best results, we recommend using\n`gpt-4o` as your LLM.\n\nHere is an example which reads from wikipedia, and inserts information into a google sheet using the composio Google Sheet MCP. For the full example, see [here](https:\u002F\u002Fgithub.com\u002Fhyperbrowserai\u002FHyperAgent\u002Ftree\u002Fmain\u002Fexamples\u002Fmcp\u002Fgoogle-sheets\u002Fmost-populated-states.ts)\n\n```typescript\nconst agent = new HyperAgent({\n  llm: llm,\n  debug: true,\n});\n\nawait agent.initializeMCPClient({\n  servers: [\n    {\n      command: \"npx\",\n      args: [\n        \"@composio\u002Fmcp@latest\",\n        \"start\",\n        \"--url\",\n        \"https:\u002F\u002Fmcp.composio.dev\u002Fgooglesheets\u002F...\",\n      ],\n      env: {\n        npm_config_yes: \"true\",\n      },\n    },\n  ],\n});\n\nconst response = await agent.executeTask(\n  \"Go to https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FList_of_U.S._states_and_territories_by_population and get the data on the top 5 most populous states from the table. Then insert that data into a google sheet. You may need to first check if there is an active connection to google sheet, and if there isn't connect to it and present me with the link to sign in. \"\n);\n\nconsole.log(response);\nawait agent.closeAgent();\n```\n\n### Custom Actions\n\nHyperAgent's capabilities can be extended with custom actions. Custom actions require 3 things:\n\n- type: Name of the action. Should be something descriptive about the action.\n- actionParams: A zod object describing the parameters that the action may consume.\n- run: A function that takes in a context, and the params for the action and produces a result based on the params.\n\nHere is an example that performs a search using Exa\n\n```typescript\nconst exaInstance = new Exa(process.env.EXA_API_KEY);\n\nexport const RunSearchActionDefinition: AgentActionDefinition = {\n  type: \"perform_search\",\n  actionParams: z.object({\n    search: z\n      .string()\n      .describe(\n        \"The search query for something you want to search about. Keep the search query concise and to-the-point.\"\n      ),\n  }).describe(\"Search and return the results for a given query.\"),\n  run: async function (\n    ctx: ActionContext,\n    params: { search: string }\n  ): Promise\u003CActionOutput> {\n    const results = (await exaInstance.search(params.search, {})).results\n      .map(\n        (res) =>\n          `title: ${res.title} || url: ${res.url} || relevance: ${res.score}`\n      )\n      .join(\"\\n\");\n\n    return {\n      success: true,\n      message: `Successfully performed search for query ${params.search}. Got results: \\n${results}`,\n    };\n  },\n};\n\nconst agent = new HyperAgent({\n  customActions: [RunSearchActionDefinition],\n});\n\nconst result = await agent.executeTask(\n  \"Search about the news for today in New York\"\n);\n```\n\n## 📼 Action Caching\n\nHyperAgent automatically records every action during `page.ai()` runs, capturing XPaths, frame indices, and execution details. This enables deterministic replay without LLM calls—perfect for regression testing, CI pipelines, and cost optimization.\n\n### How It Works\n\nEvery `page.ai()` run produces an `actionCache` containing the exact sequence of actions performed:\n\n```typescript\nconst page = await agent.newPage();\nconst { actionCache } = await page.ai(\n  \"Go to flights.google.com and search for flights from Rio to LAX\"\n);\n\n\u002F\u002F actionCache contains the recorded steps\nconsole.log(actionCache);\n```\n\nExample cache entry:\n```json\n{\n  \"taskId\": \"86d13abe-b9f3-4ca3-a9bb-bdeddf234cd1\",\n  \"createdAt\": \"2025-12-06T05:44:52.257Z\",\n  \"status\": \"completed\",\n  \"steps\": [\n    {\n      \"stepIndex\": 0,\n      \"instruction\": \"Click on the departure field\",\n      \"elementId\": \"0-138\",\n      \"method\": \"click\",\n      \"arguments\": [],\n      \"frameIndex\": 0,\n      \"xpath\": \"\u002Fhtml[1]\u002Fbody[1]\u002Fdiv[1]\u002Finput[1]\",\n      \"actionType\": \"actElement\",\n      \"success\": true\n    }\n  ]\n}\n```\n\n### Replaying Cached Actions\n\nReplay a recorded session using `runFromActionCache()`. It attempts XPath-based execution first (no LLM calls), falling back to LLM only if the page structure has changed:\n\n```typescript\nimport { ActionCacheOutput } from \"@hyperbrowser\u002Fagent\";\nimport fs from \"fs\";\n\n\u002F\u002F Load a previously saved action cache\nconst cache: ActionCacheOutput = JSON.parse(\n  fs.readFileSync(\"action-cache.json\", \"utf-8\")\n);\n\nconst agent = new HyperAgent();\nconst page = await agent.newPage();\n\n\u002F\u002F Replay the cached actions\nconst replay = await page.runFromActionCache(cache, {\n  maxXPathRetries: 3,  \u002F\u002F Retry XPath resolution up to 3 times before LLM fallback\n  debug: true,\n});\n\nconsole.log(replay);\n\u002F\u002F {\n\u002F\u002F   replayId: \"...\",\n\u002F\u002F   sourceTaskId: \"86d13abe-...\",\n\u002F\u002F   status: \"completed\",\n\u002F\u002F   steps: [{ stepIndex: 0, usedXPath: true, fallbackUsed: false, success: true }]\n\u002F\u002F }\n\nawait agent.closeAgent();\n```\n\n### Generating Replay Scripts\n\nGenerate a standalone TypeScript script from an action cache for easy integration into your test suite:\n\n```typescript\nconst { actionCache } = await page.ai(\"search for flights from Miami to NYC\");\n\n\u002F\u002F Generate a replay script\nconst script = agent.createScriptFromActionCache(actionCache.steps);\nconsole.log(script);\n```\n\nThis produces a script using typed helper methods like `performClick()`, `performType()`, etc., that can be run independently.\n\n### Use Cases\n\n- **Regression Testing**: Record a workflow once, replay it in CI without LLM costs\n- **Flaky Test Debugging**: Compare XPath-based replay vs LLM-driven execution\n- **Cost Optimization**: Cache expensive multi-step workflows and replay deterministically\n- **Workflow Templates**: Save common flows (login, checkout) and replay across environments\n\n## CDP First\n\nHyperAgent speaks Chrome DevTools Protocol natively. Element lookup, scrolling, typing, frame management, and screenshots all go through CDP so every action has exact coordinates, execution contexts, and browser events. This allows for more custom commands and deep iframe tracking.\n\nHyperAgent integrates seamlessly with Playwright, so you can still use familiar commands, while the actions take full advantage of native CDP protocol with fast locators and advanced iframe tracking.\n\n**Key Features:**\n\n- **Auto-Ad Filtering**: Automatically filters out ad and tracking iframes to keep context clean\n- **Deep Iframe Support**: Tracking across nested and cross-origin iframes (OOPIFs)\n- **Exact Coordinates**: Actions use precise CDP coordinates for reliability\n\nKeep in mind that CDP is still experimental, and stability is not guaranteed. If you'd like the agent to use Playwright's native locators\u002Factions instead, set `cdpActions: false` when you create the agent and it will fall back automatically.\n\nThe CDP layer is still evolving—expect rapid polish (and the occasional sharp edge). If you hit something quirky you can toggle CDP off for that workflow and drop us a bug report.\n\n## Contributing\n\nWe welcome contributions to Hyperagent! Here's how you can help:\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature\u002FAmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature\u002FAmazingFeature`)\n5. Open a Pull Request\n\n## Support\n\n- 📚 [Documentation](https:\u002F\u002Fdocs.hyperbrowser.ai\u002Fhyperagent\u002Fintroduction)\n- 💬 [Discord Community](https:\u002F\u002Fdiscord.gg\u002FzsYzsgVRjh)\n- 🐛 [Issue Tracker](https:\u002F\u002Fgithub.com\u002Fhyperbrowserai\u002FHyperAgent\u002Fissues)\n- 📧 [Email Support](mailto:info@hyperbrowser.ai)\n","\u003Cdiv align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhyperbrowserai_HyperAgent_readme_8b024b8b6f65.png\" alt=\"Hyperagent Banner\" width=\"800\"\u002F>\n\n  \u003Cp align=\"center\">\n    \u003Cstrong>基于大语言模型的智能浏览器自动化\u003C\u002Fstrong>\n  \u003C\u002Fp>\n\n  \u003Cp align=\"center\">\n    \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@hyperbrowser\u002Fagent\">\n      \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@hyperbrowser\u002Fagent?style=flat-square\" alt=\"npm版本\" \u002F>\n    \u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fhyperbrowserai\u002Fhyperagent\u002Fblob\u002Fmain\u002FLICENSE\">\n      \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fl\u002F@hyperbrowser\u002Fagent?style=flat-square\" alt=\"许可证\" \u002F>\n    \u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002FzsYzsgVRjh\" style=\"text-decoration:none;\">\n      \u003Cimg alt=\"Discord\" src=\"https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F1313014141165764619?style=flat-square&color=blue\">\n    \u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fx.com\u002FAkshayShekhaw12\">\n      \u003Cimg alt=\"X (原Twitter) 关注\" src=\"https:\u002F\u002Fimg.shields.io\u002Ftwitter\u002Ffollow\u002FAkshayShekhaw12?style=social\">\n    \u003C\u002Fa>\n  \u003C\u002Fp>\n\u003C\u002Fdiv>\n\n## 概述\n\nHyperagent 是由 AI 驱动的 Playwright 扩展。告别脆弱的脚本，只需强大的自然语言指令即可完成任务。  \n如果您只是在寻找可扩展的无头浏览器或爬虫基础设施，请访问 [Hyperbrowser](https:\u002F\u002Fapp.hyperbrowser.ai\u002F) 免费开始使用！\n\n在此查看 HyperAgent 文档：https:\u002F\u002Fwww.hyperbrowser.ai\u002Fdocs\u002Fhyperagent\u002Fintroduction\n\n### 功能\n\n- 🤖 **AI 命令**：提供简洁的 API，如 `page.ai()`、`page.extract()` 和 `executeTask()`，适用于任何 AI 自动化场景\n- ⚡ **回退到常规 Playwright**：当不需要 AI 时，可直接使用常规 Playwright\n- 🥷 **隐身模式** – 内置反机器人补丁，避免被检测\n- ☁️ **云端就绪** – 通过 [Hyperbrowser](https:\u002F\u002Fapp.hyperbrowser.ai\u002F) 即时扩展至数百个会话\n- 🔌 **MCP 客户端** – 可连接 Composio 等工具实现完整工作流（例如将网页数据写入 Google Sheets）\n- 📼 **操作缓存** – 录制并确定性地重放工作流，无需调用 LLM\n\n## 快速入门\n\n### 安装\n\n```bash\n# 使用 npm\nnpm install @hyperbrowser\u002Fagent\n\n# 使用 yarn\nyarn add @hyperbrowser\u002Fagent\n```\n\n### CLI\n\n```bash\n$ npx @hyperbrowser\u002Fagent -c \"查找从迈阿密到新奥尔良的路线，并提供详细的路线信息。\"\n```\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhyperbrowserai_HyperAgent_readme_4d916198393a.gif\" alt=\"Hyperagent 演示\"\u002F>\n\u003C\u002Fp>\n\nCLI 支持调试选项，或选择使用 Hyperbrowser 而不是本地浏览器：\n\n```bash\n-d, --debug                       启用调试模式\n-c, --command \u003C任务描述>          要执行的命令\n--hyperbrowser                    使用 Hyperbrowser 作为浏览器提供商\n```\n\n### 库\n\n```typescript\nimport { HyperAgent } from \"@hyperbrowser\u002Fagent\";\nimport { z } from \"zod\";\n\n\u002F\u002F 初始化代理\nconst agent = new HyperAgent({\n  llm: {\n    provider: \"openai\",\n    model: \"gpt-4o\",\n  },\n});\n\n\u002F\u002F 执行任务\nconst result = await agent.executeTask(\n  \"导航到 amazon.com，搜索 'laptop'，并提取前 5 条结果的价格\"\n);\nconsole.log(result.output);\n\n\u002F\u002F 使用 page.ai、page.perform 和 page.extract\nconst page = await agent.newPage();\nawait page.goto(\"https:\u002F\u002Fflights.google.com\", { waitUntil: \"load\" });\nawait page.ai(\"搜索 7 月 16 日至 22 日从里约热内卢飞往洛杉矶的航班\");\nawait page.perform(\"点击搜索按钮\");\nconst res = await page.extract(\n  \"给我航班选项\",\n  z.object({\n    flights: z.array(\n      z.object({\n        price: z.number(),\n        departure: z.string(),\n        arrival: z.string(),\n      })\n    ),\n  })\n);\nconsole.log(res);\n\n\u002F\u002F 清理\nawait agent.closeAgent();\n```\n\n## 两种运行模式\n\nHyperAgent 提供两种互补的 API，分别针对不同用例进行了优化：\n\n### 🎯 `page.perform()` - 单一细粒度操作\n\n> `page.aiAction()` 已弃用，仍作为别名保留；建议今后优先使用 `page.perform()`。\n\n**适用场景**：单一、特定的操作，例如“点击登录”、“填写邮箱 test@example.com”\n\n**优势**：\n- ⚡ **快速** - 使用无障碍树（无需截图）\n- 💰 **经济** - 每次操作仅需一次 LLM 调用\n- 🎯 **可靠** - 直接定位并执行元素操作\n- 📊 **高效** - 基于文本的 DOM 分析，自动过滤广告框架\n\n**示例**：\n```typescript\nconst page = await agent.newPage();\nawait page.goto(\"https:\u002F\u002Fexample.com\u002Flogin\");\n\n\u002F\u002F 快速、可靠的单个操作\nawait page.perform(\"填写邮箱 user@example.com\");\nawait page.perform(\"填写密码 mypassword\");\nawait page.perform(\"点击登录按钮\");\n```\n\n### 🧠 `page.ai()` - 复杂多步骤任务\n\n**适用场景**：需要多步骤操作且依赖视觉上下文的复杂流程\n\n**优势**：\n\n- 🖼️ **视觉理解** - 可使用带有元素叠加的截图\n- 🎭 **复杂任务** - 自动处理多步骤工作流\n- 🧠 **上下文感知** - 更好地理解页面布局和元素关系\n- 🔄 **自适应** - 可根据页面状态调整策略\n\n**参数**：\n\n- `useDomCache` (boolean): 重复使用 DOM 快照以提高速度\n- `enableVisualMode` (boolean): 启用截图和叠加层（默认为 false）\n\n**示例**：\n\n```typescript\nconst page = await agent.newPage();\nawait page.goto(\"https:\u002F\u002Fflights.google.com\");\n\n\u002F\u002F 自动处理的复杂多步骤任务\nawait page.ai(\"搜索 7 月 16 日从迈阿密飞往新奥尔良的航班\", {\n  useDomCache: true,\n});\n```\n\n### 🎨 混合使用\n\n结合两种 API 以获得最佳性能：\n\n```typescript\n\u002F\u002F 使用 perform 进行快速、可靠的单个操作\nawait page.perform(\"点击搜索按钮\");\nawait page.perform(\"在搜索框中输入 laptop\");\n\n\u002F\u002F 使用 ai() 处理复杂、多步骤的工作流\nawait page.ai(\"筛选价格低于 1000 美元的结果，并按评分排序\");\n\n\u002F\u002F 提取结构化数据\nconst products = await page.extract(\n  \"获取前 5 名产品\",\n  z.object({\n    products: z.array(z.object({ name: z.string(), price: z.number() }))\n  })\n);\n```\n\n## ☁️ 云端\n\n您可以通过 Hyperbrowser 的云无头浏览器来扩展 HyperAgent。\n\n1. 从 [Hyperbrowser](https:\u002F\u002Fapp.hyperbrowser.ai\u002F) 获取免费 API 密钥\n2. 将其添加到环境变量中，命名为 `HYPERBROWSER_API_KEY`\n3. 将 `browserProvider` 设置为 `\"Hyperbrowser\"`\n\n```typescript\nconst agent = new HyperAgent({\n  browserProvider: \"Hyperbrowser\",\n});\n\nconst response = await agent.executeTask(\n  \"前往 hackernews，列出最近 5 篇文章的标题\"\n);\n\nconsole.log(response);\nawait agent.closeAgent();\n```\n\n## 使用指南\n\n### 多页面管理\n\n```typescript\n\u002F\u002F 创建并管理多个页面\nconst page1 = await agent.newPage();\nconst page2 = await agent.newPage();\n\n\u002F\u002F 在特定页面上执行任务\nconst page1Response = await page1.ai(\n  \"前往 google.com\u002Ftravel\u002Fexplore，并将出发地设置为纽约。然后，返回给我第一个出现的推荐目的地。只返回地点名称。\"\n);\nconst page2Response = await page2.ai(\n  `我想计划一次去 ${page1Response.output} 的旅行。请推荐一些值得一去的地方。`\n);\n\nconsole.log(page2Response.output);\n\n\u002F\u002F 获取所有活动页面\nconst pages = await agent.getPages();\nawait agent.closeAgent();\n```\n\n## 自定义功能\n\n### 输出模式定义\n\nHyperAgent 可以按照指定的模式提取数据。模式可以在每个任务级别传递。\n\n```typescript\nimport { z } from \"zod\";\n\nconst agent = new HyperAgent();\nconst agentResponse = await agent.executeTask(\n  \"导航到 imdb.com，搜索‘黑客帝国’，并提取导演、上映年份和评分\",\n  {\n    outputSchema: z.object({\n      director: z.string().describe(\"电影导演的名字\"),\n      releaseYear: z.number().describe(\"电影的上映年份\"),\n      rating: z.string().describe(\"电影在 IMDb 上的评分\"),\n    }),\n  }\n);\nconsole.log(agentResponse.output);\nawait agent.closeAgent();\n```\n\n```bash\n{\n  \"director\": \"拉娜·沃卓斯基、莉莉·沃卓斯基\",\n  \"releaseYear\": 1999,\n  \"rating\": \"8.7\u002F10\"\n}\n```\n\n### 使用不同的大模型提供商\n\nHyperAgent 支持多种大模型提供商，并提供原生 SDK 以提升性能和可靠性。\n\n```typescript\n\u002F\u002F 使用 OpenAI\nconst agent = new HyperAgent({\n  llm: {\n    provider: \"openai\",\n    model: \"gpt-4o\",\n  },\n});\n\n\u002F\u002F 使用 Anthropic 的 Claude\nconst agent = new HyperAgent({\n  llm: {\n    provider: \"anthropic\",\n    model: \"claude-sonnet-4-0\",\n  },\n});\n\n\u002F\u002F 使用 Google Gemini\nconst agent = new HyperAgent({\n  llm: {\n    provider: \"gemini\",\n    model: \"gemini-2.5-flash\",\n  },\n});\n\n\u002F\u002F 使用 DeepSeek\nconst agent = new HyperAgent({\n  llm: {\n    provider: \"deepseek\",\n    model: \"deepseek-chat\",\n  },\n});\n```\n\n### MCP 支持\n\nHyperAgent 可以作为功能齐全的 MCP 客户端使用。为了获得最佳效果，我们建议使用 `gpt-4o` 作为您的大模型。\n\n以下是一个从维基百科读取信息，并使用 Composio 的 Google 表格 MCP 将信息插入 Google 表格的示例。完整示例请参见 [这里](https:\u002F\u002Fgithub.com\u002Fhyperbrowserai\u002FHyperAgent\u002Ftree\u002Fmain\u002Fexamples\u002Fmcp\u002Fgoogle-sheets\u002Fmost-populated-states.ts)。\n\n```typescript\nconst agent = new HyperAgent({\n  llm: llm,\n  debug: true,\n});\n\nawait agent.initializeMCPClient({\n  servers: [\n    {\n      command: \"npx\",\n      args: [\n        \"@composio\u002Fmcp@latest\",\n        \"start\",\n        \"--url\",\n        \"https:\u002F\u002Fmcp.composio.dev\u002Fgooglesheets\u002F...\",\n      ],\n      env: {\n        npm_config_yes: \"true\",\n      },\n    },\n  ],\n});\n\nconst response = await agent.executeTask(\n  \"前往 https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FList_of_U.S._states_and_territories_by_population，获取表格中人口最多的前五州的数据。然后将这些数据插入 Google 表格。你可能需要先检查是否已连接到 Google 表格，如果没有，请先连接，并向我提供登录链接。\"\n);\n\nconsole.log(response);\nawait agent.closeAgent();\n```\n\n### 自定义操作\n\n可以通过自定义操作扩展 HyperAgent 的功能。自定义操作需要满足以下三个条件：\n\n- type：操作名称，应能描述该操作的内容。\n- actionParams：一个 Zod 对象，用于描述该操作可能接收的参数。\n- run：一个函数，接受上下文和操作参数，并根据参数生成结果。\n\n以下是一个使用 Exa 进行搜索的示例：\n\n```typescript\nconst exaInstance = new Exa(process.env.EXA_API_KEY);\n\nexport const RunSearchActionDefinition: AgentActionDefinition = {\n  type: \"perform_search\",\n  actionParams: z.object({\n    search: z\n      .string()\n      .describe(\n        \"您想要搜索的内容查询。请保持查询简洁明了。\"\n      ),\n  }).describe(\"搜索并返回给定查询的结果。\"),\n  run: async function (\n    ctx: ActionContext,\n    params: { search: string }\n  ): Promise\u003CActionOutput> {\n    const results = (await exaInstance.search(params.search, {})).results\n      .map(\n        (res) =>\n          `标题: ${res.title} || 链接: ${res.url} || 相关性: ${res.score}`\n      )\n      .join(\"\\n\");\n\n    return {\n      success: true,\n      message: `成功执行了关于 ${params.search} 的搜索。结果如下：\\n${results}`,\n    };\n  },\n};\n\nconst agent = new HyperAgent({\n  customActions: [RunSearchActionDefinition],\n});\n\nconst result = await agent.executeTask(\n  \"搜索今天纽约的新闻\"\n);\n```\n\n## 📼 操作缓存\n\nHyperAgent 会在每次 `page.ai()` 运行时自动记录所有操作，包括 XPath、框架索引和执行细节。这使得无需调用大模型即可进行确定性重放，非常适合回归测试、CI 流水线和成本优化。\n\n### 工作原理\n\n每次 `page.ai()` 运行都会生成一个包含所执行操作序列的 `actionCache`：\n\n```typescript\nconst page = await agent.newPage();\nconst { actionCache } = await page.ai(\n  \"前往 flights.google.com，搜索从里约热内卢飞往洛杉矶的航班\"\n);\n\n\u002F\u002F actionCache 包含记录的步骤\nconsole.log(actionCache);\n```\n\n缓存条目示例：\n```json\n{\n  \"taskId\": \"86d13abe-b9f3-4ca3-a9bb-bdeddf234cd1\",\n  \"createdAt\": \"2025-12-06T05:44:52.257Z\",\n  \"status\": \"completed\",\n  \"steps\": [\n    {\n      \"stepIndex\": 0,\n      \"instruction\": \"点击出发地字段\",\n      \"elementId\": \"0-138\",\n      \"method\": \"click\",\n      \"arguments\": [],\n      \"frameIndex\": 0,\n      \"xpath\": \"\u002Fhtml[1]\u002Fbody[1]\u002Fdiv[1]\u002Finput[1]\",\n      \"actionType\": \"actElement\",\n      \"success\": true\n    }\n  ]\n}\n```\n\n### 重放缓存的操作\n\n可以使用 `runFromActionCache()` 重放已记录的会话。它首先尝试基于 XPath 执行（无需调用大模型），只有当页面结构发生变化时才会回退到大模型：\n\n```typescript\nimport { ActionCacheOutput } from \"@hyperbrowser\u002Fagent\";\nimport fs from \"fs\";\n\n\u002F\u002F 加载之前保存的操作缓存\nconst cache: ActionCacheOutput = JSON.parse(\n  fs.readFileSync(\"action-cache.json\", \"utf-8\")\n);\n\nconst agent = new HyperAgent();\nconst page = await agent.newPage();\n\n\u002F\u002F 重放缓存的操作\nconst replay = await page.runFromActionCache(cache, {\n  maxXPathRetries: 3,  \u002F\u002F 在回退到大模型之前，最多尝试 3 次解析 XPath\n  debug: true,\n});\n\nconsole.log(replay);\n\u002F\u002F {\n\u002F\u002F   replayId: \"...\",\n\u002F\u002F   sourceTaskId: \"86d13abe-...\",\n\u002F\u002F   status: \"completed\",\n\u002F\u002F   steps: [{ stepIndex: 0, usedXPath: true, fallbackUsed: false, success: true }]\n\u002F\u002F }\n\nawait agent.closeAgent();\n```\n\n### 生成回放脚本\n\n从操作缓存中生成一个独立的 TypeScript 脚本，以便轻松集成到您的测试套件中：\n\n```typescript\nconst { actionCache } = await page.ai(\"搜索从迈阿密飞往纽约的航班\");\n\n\u002F\u002F 生成回放脚本\nconst script = agent.createScriptFromActionCache(actionCache.steps);\nconsole.log(script);\n```\n\n这将生成一个使用类型化辅助方法（如 `performClick()`、`performType()` 等）的脚本，可以独立运行。\n\n### 使用场景\n\n- **回归测试**：只需录制一次工作流，在 CI 中无需 LLM 成本即可回放。\n- **不稳定测试调试**：比较基于 XPath 的回放与 LLM 驱动的执行结果。\n- **成本优化**：缓存昂贵的多步骤工作流，并以确定性方式回放。\n- **工作流模板**：保存常用流程（登录、结账等），并在不同环境中回放。\n\n## CDP 优先\n\nHyperAgent 原生支持 Chrome 开发者工具协议。元素查找、滚动、输入、框架管理以及截图等操作都通过 CDP 进行，因此每个操作都有精确的坐标、执行上下文和浏览器事件。这使得自定义命令更加灵活，并能深入跟踪嵌套 iframe。\n\nHyperAgent 可与 Playwright 无缝集成，您仍然可以使用熟悉的命令，同时这些操作会充分利用原生 CDP 协议，实现快速定位和高级 iframe 跟踪。\n\n**主要特性：**\n\n- **自动广告过滤**：自动过滤广告和跟踪 iframe，保持上下文干净。\n- **深度 iframe 支持**：跨嵌套和跨源 iframe（OOPIF）的跟踪。\n- **精确坐标**：操作使用精确的 CDP 坐标，确保可靠性。\n\n请注意，CDP 仍处于实验阶段，稳定性无法保证。如果您希望代理使用 Playwright 的原生定位器\u002F操作，请在创建代理时设置 `cdpActions: false`，它将自动回退到 Playwright 的默认行为。\n\nCDP 层仍在不断演进——预计会有快速的改进（但也可能偶尔出现一些问题）。如果遇到特殊情况，您可以为该工作流关闭 CDP 功能，并向我们提交 bug 报告。\n\n## 贡献\n\n我们欢迎对 Hyperagent 的贡献！以下是您可以帮助的方式：\n\n1. 克隆仓库并创建分支。\n2. 创建您的功能分支（`git checkout -b feature\u002FAmazingFeature`）。\n3. 提交更改（`git commit -m '添加 AmazingFeature'`）。\n4. 推送到分支（`git push origin feature\u002FAmazingFeature`）。\n5. 打开一个 Pull Request。\n\n## 支持\n\n- 📚 [文档](https:\u002F\u002Fdocs.hyperbrowser.ai\u002Fhyperagent\u002Fintroduction)\n- 💬 [Discord 社区](https:\u002F\u002Fdiscord.gg\u002FzsYzsgVRjh)\n- 🐛 [问题追踪](https:\u002F\u002Fgithub.com\u002Fhyperbrowserai\u002FHyperAgent\u002Fissues)\n- 📧 [邮件支持](mailto:info@hyperbrowser.ai)","# HyperAgent 快速上手指南\n\nHyperAgent 是一款由 AI 大语言模型（LLM）驱动的智能浏览器自动化工具。它基于 Playwright 构建，允许开发者使用自然语言命令控制浏览器，无需编写脆弱的选择器脚本，同时保留了原生 Playwright 的高性能与灵活性。\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **Node.js**: 建议版本 v18 或更高。\n*   **包管理器**: npm, yarn, 或 pnpm。\n*   **LLM API Key**: 您需要拥有支持的 LLM 提供商 API Key（如 OpenAI, Anthropic, Google Gemini, DeepSeek 等）。\n    *   *注：国内开发者可使用 DeepSeek 或符合网络环境的其他模型提供商。*\n*   **环境变量**: 确保在终端中配置好对应的 API Key（例如 `OPENAI_API_KEY` 或 `DEEPSEEK_API_KEY`）。\n\n## 安装步骤\n\n通过 npm 或 yarn 安装 HyperAgent 核心包：\n\n```bash\n# 使用 npm\nnpm install @hyperbrowser\u002Fagent\n\n# 使用 yarn\nyarn add @hyperbrowser\u002Fagent\n```\n\n> **提示**：如果在国内安装速度较慢，可配置淘宝镜像源：\n> `npm config set registry https:\u002F\u002Fregistry.npmmirror.com`\n\n## 基本使用\n\nHyperAgent 提供两种主要使用方式：命令行工具 (CLI) 和 TypeScript\u002FJavaScript 库。\n\n### 1. 命令行快速体验 (CLI)\n\n无需编写代码，直接在终端运行自然语言任务：\n\n```bash\nnpx @hyperbrowser\u002Fagent -c \"Find a route from Miami to New Orleans, and provide the detailed route information.\"\n```\n\n**常用参数：**\n*   `-c, --command`: 要执行的任务描述。\n*   `-d, --debug`: 开启调试模式。\n*   `--hyperbrowser`: 使用 Hyperbrowser 云服务而非本地浏览器。\n\n### 2. 代码集成 (Library)\n\n以下是使用 TypeScript 进行初始化和执行任务的最小化示例：\n\n```typescript\nimport { HyperAgent } from \"@hyperbrowser\u002Fagent\";\nimport { z } from \"zod\";\n\n\u002F\u002F 1. 初始化 Agent (以 OpenAI 为例，也可替换为 deepseek, anthropic 等)\nconst agent = new HyperAgent({\n  llm: {\n    provider: \"openai\", \u002F\u002F 或 \"deepseek\", \"anthropic\", \"gemini\"\n    model: \"gpt-4o\",\n  },\n});\n\n\u002F\u002F 2. 执行简单任务\nconst result = await agent.executeTask(\n  \"Navigate to amazon.com, search for 'laptop', and extract the prices of the first 5 results\"\n);\nconsole.log(result.output);\n\n\u002F\u002F 3. 高级用法：混合使用精确操作与 AI 意图理解\nconst page = await agent.newPage();\nawait page.goto(\"https:\u002F\u002Fflights.google.com\", { waitUntil: \"load\" });\n\n\u002F\u002F 使用自然语言执行复杂搜索\nawait page.ai(\"search for flights from Rio to LAX from July 16 to July 22\");\n\n\u002F\u002F 使用精确指令点击按钮 (更快、更稳定)\nawait page.perform(\"click the search button\");\n\n\u002F\u002F 结构化提取数据\nconst res = await page.extract(\n  \"give me the flight options\",\n  z.object({\n    flights: z.array(\n      z.object({\n        price: z.number(),\n        departure: z.string(),\n        arrival: z.string(),\n      })\n    ),\n  })\n);\nconsole.log(res);\n\n\u002F\u002F 4. 清理资源\nawait agent.closeAgent();\n```\n\n### 核心 API 说明\n\n*   **`page.ai()`**: 适用于复杂的多步骤工作流。它能理解视觉上下文，自动处理多个操作步骤。\n*   **`page.perform()`**: 适用于单一的颗粒化动作（如“点击登录”、“填写邮箱”）。基于无障碍树执行，速度快且成本低。\n*   **`page.extract()`**: 配合 Zod Schema 使用，从页面提取结构化数据。\n\n### 云端扩展 (可选)\n\n若需大规模并发或避免本地环境配置问题，可接入 Hyperbrowser 云服务：\n\n1.  在 [Hyperbrowser](https:\u002F\u002Fapp.hyperbrowser.ai\u002F) 获取免费 API Key。\n2.  设置环境变量 `HYPERBROWSER_API_KEY`。\n3.  初始化时指定 `browserProvider: \"Hyperbrowser\"`。\n\n```typescript\nconst agent = new HyperAgent({\n  browserProvider: \"Hyperbrowser\",\n});\n\u002F\u002F 后续用法与本地上完全一致\n```","某电商数据分析师需要每日从多个动态渲染的竞品网站抓取最新价格与库存信息，以生成市场趋势报告。\n\n### 没有 HyperAgent 时\n- **脚本极其脆弱**：传统爬虫依赖固定的 CSS 选择器，一旦网站微调布局或更新类名，脚本立即报错停止，维护成本极高。\n- **难以应对反爬**：面对带有行为检测的网站，需额外集成复杂的指纹伪装库和代理池，配置繁琐且容易被识别封锁。\n- **开发周期漫长**：针对每个新网站都需要编写大量的定位逻辑和等待代码，从调研到产出稳定脚本往往耗时数天。\n- **数据结构化困难**：从动态加载的复杂页面中提取非标准化数据（如促销规则、多规格价格）需要编写大量正则或解析逻辑，容易出错。\n\n### 使用 HyperAgent 后\n- **指令即代码**：直接使用自然语言描述任务（如“提取前 5 个商品的价格”），HyperAgent 利用 LLM 自动理解页面结构，不再受 DOM 变动影响。\n- **内置隐身模式**：工具自带抗检测补丁，自动处理指纹伪装，无需额外配置即可绕过主流反爬机制，稳定获取数据。\n- **极速落地**：只需几行代码调用 `page.extract` 并定义 Zod  schema，即可在几分钟内完成新站点的数据采集流程开发。\n- **智能结构化输出**：直接让 AI 将页面上的非结构化文本转换为标准的 JSON 对象，自动处理多规格、折扣计算等复杂逻辑。\n\nHyperAgent 将原本需要数天维护的脆弱爬虫脚本，转变为只需一句自然语言指令即可稳定运行的智能自动化流程，极大释放了数据获取效率。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fhyperbrowserai_HyperAgent_4d916198.gif","hyperbrowserai","Hyperbrowser","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fhyperbrowserai_526c3081.png","Browser Infrastructure for AI Agents",null,"hyperbrowser","https:\u002F\u002Fwww.hyperbrowser.ai","https:\u002F\u002Fgithub.com\u002Fhyperbrowserai",[82,86,90],{"name":83,"color":84,"percentage":85},"TypeScript","#3178c6",97.2,{"name":87,"color":88,"percentage":89},"JavaScript","#f1e05a",2.8,{"name":91,"color":92,"percentage":93},"Shell","#89e051",0,1274,151,"2026-04-15T06:55:01","NOASSERTION","未说明",{"notes":100,"python":101,"dependencies":102},"该工具是基于 Node.js 的库（非 Python），需通过 npm 或 yarn 安装。核心依赖是 Playwright 用于浏览器自动化，并支持多种 LLM 提供商（OpenAI, Anthropic, Google Gemini, DeepSeek）。可选使用 Hyperbrowser 云服务进行扩展，或使用 MCP 客户端连接外部工具（如 Composio）。","不适用 (基于 Node.js)",[103,104,105,106,107,108,109],"@hyperbrowser\u002Fagent","playwright","zod","openai","anthropic","google-generative-ai","deepseek",[15,36,14,27,13],[112,113,104,114,115,116,117],"ai","automation","llm","agent","chrome","web","2026-03-27T02:49:30.150509","2026-04-20T16:17:05.872159",[121,126,131,136,141,146],{"id":122,"question_zh":123,"answer_zh":124,"source_url":125},35805,"遇到 'messageLike is not iterable' 错误怎么办？","这通常是由于 LangChain 或 OpenAI 库的版本不匹配导致的。请检查并更新您的 `langchain` 和 `@langchain\u002Fopenai` 依赖包到兼容版本。维护者建议在后续版本中增加版本检查以避免此类问题，但当前最直接的解决方法是统一相关库的版本。","https:\u002F\u002Fgithub.com\u002Fhyperbrowserai\u002FHyperAgent\u002Fissues\u002F29",{"id":127,"question_zh":128,"answer_zh":129,"source_url":130},35806,"Agent 任务陷入无限循环并一直打印 'no dom state, waiting 1 second' 如何解决？","这是一个已知 bug，当页面导航导致执行上下文销毁时，`getDom()` 返回 null 而非抛出错误，导致重试机制失效从而进入死循环。该问题已在 v0.9.0 版本中修复（参考 PR #50）。请将 `@hyperbrowser\u002Fagent` 升级到 0.9.0 或更高版本来解决此问题。","https:\u002F\u002Fgithub.com\u002Fhyperbrowserai\u002FHyperAgent\u002Fissues\u002F48",{"id":132,"question_zh":133,"answer_zh":134,"source_url":135},35807,"使用 page.extract() 时任务在 2 步后就被取消且输出为空，如何处理复杂提取任务？","这是因为旧版本中 `page.extract()` 方法硬编码了 `maxSteps: 2` 的限制。该限制已在 v0.11.0 版本中移除，并添加了可配置参数。此外，v0.10.0 已移除了对 LangChain 的依赖。建议先将库升级到 v0.10.0 以上，最好直接使用 v0.11.0 或更新版本，以便支持更复杂的提取步骤。","https:\u002F\u002Fgithub.com\u002Fhyperbrowserai\u002FHyperAgent\u002Fissues\u002F54",{"id":137,"question_zh":138,"answer_zh":139,"source_url":140},35808,"HyperAgent 是否支持模拟不同尺寸的手机设备？","是的，社区已通过 PR #25 添加了手机设备尺寸的支持。请确保您的库版本包含了此更新，或者查看相关 Pull Request 以手动应用设备尺寸配置。","https:\u002F\u002Fgithub.com\u002Fhyperbrowserai\u002FHyperAgent\u002Fissues\u002F22",{"id":142,"question_zh":143,"answer_zh":144,"source_url":145},35809,"Agent 无法正确识别或响应页面上的模态框（Modals）怎么办？","这是由元素高亮代码在处理重叠元素（overlay）时的缺陷引起的。维护者指出该问题将通过新的高亮代码逻辑进行修复。如果遇到此问题，建议关注仓库的最新更新，升级到包含新高亮代码修复的版本通常能解决模态框识别错乱的问题。","https:\u002F\u002Fgithub.com\u002Fhyperbrowserai\u002FHyperAgent\u002Fissues\u002F10",{"id":147,"question_zh":148,"answer_zh":149,"source_url":150},35810,"在使用 hyperbrowser 提供商时，如何获取实时的浏览器访问 URL？","这是一个功能请求，旨在让用户在使用 hyperbrowser 提供商时能够打印出实时的调试 URL。虽然具体实现代码未在评论中详细列出，但该需求已被记录并在讨论中（Issue #16），通常这类功能会在后续版本更新中加入，用于方便开发者调试 Agent 的实际运行页面。","https:\u002F\u002Fgithub.com\u002Fhyperbrowserai\u002FHyperAgent\u002Fissues\u002F16",[152],{"id":153,"version":154,"summary_zh":155,"released_at":156},281013,"v1.0.0","版本 1.0.0 发布","2025-11-19T00:17:41"]