Stagehand - AI 驅動的瀏覽器自動化框架

專案概述

Stagehand 是一個生產就緒的 AI 瀏覽器自動化框架，由 Browserbase 公司開發。它解決了現有瀏覽器自動化工具的痛點：要麼需要編寫低階程式碼（如 Selenium、Playwright、Puppeteer），要麼使用高階代理但在生產環境中不可預測。

核心特性

1. 彈性控制方式

• 程式碼與自然語言結合：開發者可以選擇何時使用程式碼，何時使用自然語言
• AI 導航：在不熟悉的頁面上使用 AI 進行導航
• 精確控制：在明確知道要做什麼時使用程式碼（Playwright）

2. 預覽和快取功能

• 操作預覽：在執行之前預覽 AI 操作
• 快取機制：輕鬆快取可重複的操作，節省時間和令牌消耗

3. 一鍵整合電腦視覺模型

• SOTA 模型支援：一行程式碼即可整合 OpenAI 和 Anthropic 的最新電腦視覺模型
• 無縫整合：引入 stagehand.agent：一種強大的新方法，只需一行程式碼即可將 SOTA 電腦視覺模型或 Browserbase 的 Open Operator 整合到 Stagehand 中

快速入門

安裝

npx create-browser-app

本地開發

git clone https://github.com/browserbase/stagehand.git
cd stagehand
npm install
npx playwright install
npm run build
npm run example # 執行 ./examples/example.ts 中的範例腳本

環境配置

cp .env.example .env
nano .env # 編輯 .env 文件添加 API 密鑰

使用範例

基本用法

// 使用 Playwright 函數操作頁面物件
const page = stagehand.page;
await page.goto("https://github.com/browserbase");

// 使用 act() 執行單一操作
await page.act("click on the stagehand repo");

// 使用電腦視覺代理執行更大的操作
const agent = stagehand.agent({
  provider: "openai",
  model: "computer-use-preview",
});
await agent.execute("Get to the latest PR");

// 使用 extract() 從頁面讀取資料
const { author, title } = await page.extract({
  instruction: "extract the author and title of the PR",
  schema: z.object({
    author: z.string().describe("The username of the PR author"),
    title: z.string().describe("The title of the PR"),
  }),
});

核心方法

1. act() 方法

• 執行單一瀏覽器操作
• 支援自然語言指令
• 適用於點擊、輸入、導航等操作

2. extract() 方法

• 從頁面提取結構化資料
• 整合 Zod 模式驗證
• 支援複雜的資料提取任務

3. observe() 方法

• 觀察頁面狀態與變化
• 用於條件判斷與狀態監控

4. agent() 方法（V2 新功能）

• 整合先進的電腦視覺模型
• 支援多步驟工作流程
• 適用於複雜互動場景

版本 2.0 新功能

Stagehand V2 引入了多項重大改進：

效能提升

• 閃電般的 act 和 extract：重大效能改進，使自動化運行更快
• 基於 a11y-tree 的優化：更快的可訪問性樹基礎的 act/extract 方法

強化日誌記錄

• 更好的自動化過程可見性
• 改進的日誌記錄與除錯功能

全面文件

• 完全重新設計的文件網站
• 更好的範例、指南與最佳實踐

錯誤處理改進

• 更穩定的錯誤處理機制
• 更好的錯誤訊息與除錯支援

技術架構

依賴關係

• Playwright：作為網頁自動化的核心骨幹
• Zod：用於資料結構驗證
• TypeScript：主要開發語言

多語言支援

除了 TypeScript/JavaScript 版本，專案還提供：

• Python 版本

與 Browserbase 的整合

Browserbase 是您的雲端瀏覽器供應商，使用 Stagehand 建構更強大的功能，包括會話回放、提示可觀察性與驗證碼解決等進階功能。

總結

Stagehand 是一個革命性的瀏覽器自動化框架，它完美融合了傳統程式碼控制的精確性與 AI 自然語言處理的彈性。無論是簡單的網頁操作還是複雜的資料提取任務，Stagehand 都能提供生產級解決方案。其 2.0 版本的效能提升與新功能使其成為現代瀏覽器自動化的首選工具。