Stagehand 瀏覽器 Agent SDK 版本演進全解從 v1 到 v4 的核心能力與升級指南【免費下載鏈接】stagehandThe SDK For Browser Agents項目地址: https://gitcode.com/GitHub_Trending/stag/stagehandStagehand 是面向瀏覽器 Agent 的 SDK本倉庫 CHANGELOG.md 完整記錄了其公開 TypeScript 與 Python SDK4.0.0 之前僅描述 TypeScript SDK從 1.x 到 4.x 的演進歷程。本文以該變更日志為主線結合倉庫源碼系統梳理act/extract/observe/agent四大核心原語的演變、CUA 與 Hybrid 模式的出現、緩存與安全策略的完善幫助你在升級版本時快速定位行為差異并理解每個重要特性背后的實現細節。版本結構概覽一個協議優先的 Monorepo從 CHANGELOG 的開頭可以清晰看到當前倉庫是一個多語言、多包的工作區變更日志按以下產物分軌記錄TypeScript SDKpackages/sdk-ts主 SDK自 1.0.0 起持續演進Python SDKpackages/sdk-python與Go SDKpackages/sdk-go在 v4 時代與 TypeScript SDK 同步發布Extension Runtimepackages/extension瀏覽器擴展運行時作為協議層的執行載體。工作區根目錄的 package.json 表明這是一個基于 pnpm Turbo 的 monoreponame: stagehand-workspaceversion: 4.0.0并使用 changesets 管理版本發布這解釋了 CHANGELOG 中Major / Minor / Patch Changes的分類來源。v4.0.0圍繞瀏覽器協議的全面重構4.0.0 — 協議優先架構v4 是 CHANGELOG 中最重要的一次 Major 版本其核心表述為Rebuilt Stagehand around its v4 browser protocol and TypeScript SDK. Stagehand is now a protocol-first monorepo with TypeScript, Python, and Go SDKs over a shared core.這標志著 Stagehand 從Playwright 之上的封裝轉變為**協議優先protocol-first**的架構三種語言 SDK 共享同一個 v4 瀏覽器協議擴展運行時Extension Runtime通過 JSON-RPC見 packages/protocol/json-rpc與各語言 SDK 通信。Python SDK 也在 4.0.0 中圍繞 v4 瀏覽器協議重建。從源碼結構看v4 引入了統一的對象模型BrowserContext、Page、Locator、Response、Clipboard等見 packages/sdk-ts/src 與 packages/sdk-python/src/stagehand各語言保持 API 語義一致。4.0.1 — 擴展資產與環境變量4.0.1 引入了兩個重要的環境變量STAGEHAND_EXTENSION_ARCHIVE_PATH覆蓋擴展 zip 壓縮包路徑STAGEHAND_EXTENSION_DIRECTORY_PATH覆蓋擴展目錄路徑。這兩個變量的設計動機在 packages/sdk-ts/src/extensionAssets.ts 的源碼注釋中交代得很清楚針對會把模塊內聯、導致import.meta.url基準路徑失效的打包器如 nitro、eve dev 的 authored-module 編譯器提供顯式路徑覆蓋能力。實現上通過nonEmpty()輔助函數保證空字符串/純空白會被忽略回退到包內dist/assets/stagehand-extension.zip與dist/extension/。同版本還支持了通過STAGEHAND_EXTENSION_ARCHIVE_PATH覆蓋擴展資產位置并在 Browserbase 會話元數據中記錄 Stagehand SDK 版本便于服務端調試。4.0.2 — 運行時重連4.0.2 的補丁允許SDK 客戶端重新掛接到已初始化的 Stagehand 擴展運行時。這為連接已有瀏覽器會話含 Browserbase 遠程會話場景提供了更穩定的保障TypeScript / Python / Go / Extension Runtime 四軌同步發布。核心原語act / extract / observe 的演進早期從stagehand.act()到stagehand.page.act()1.8.0 將act/extract/observe從 Stagehand 頂層遷移到page對象stagehand.act()→stagehand.page.act()并引入StagehandPage/StagehandContext包裝對象以增強底層 Playwright 能力。2.0.0 起這些原語被統一放在 Page 層級stagehand.history數組會記錄act/extract/observe/goto調用即使由 agent 間接調用也會被捕獲。提取extract能力的持續加強1.7.0新增textExtract一種基于文本的長文提取方案默認extract走domExtractDOM 處理。1.14.0extract()無參數調用即可確定性地獲取頁面全文文本表示支持通過selectorXPath做定向提取只處理目標元素降低 token 消耗、提升速度const weatherData await stagehand.page.extract({ instruction: extract the weather data for Sun, Feb 23 at 11PM, schema: z.object({ temperature: z.string(), weather_description: z.string(), wind: z.string(), humidity: z.string(), barometer: z.string(), visibility: z.string(), }), modelName, selector: xpath, // 目標元素的 xpath限制 DOM 處理范圍 });2.0.0默認使用 a11y無障礙樹作為提取上下文。3.4.0extract()與observe()新增ignoreSelectors參數可排除特定元素。3.5.0extract()新增screenshot選項——把當前視口截圖與 a11y 樹一同發送給模型提升對視覺信息的提取準確性。觀察observe與動作act的聯動1.12.0observe大升級為候選元素返回建議的 Playwright 方法及參數act可直接接受observe的輸出。1.14.0act()可在內部改用observe()管道slowDomBasedAct: false時啟用帶來顯著的性能提升。3.0.8agent 的關閉工具更名為donepage.snapshot()與page.waitForSelector()被加入頁面原語。3.2.0新增page.setExtraHTTPHeaders()3.1.0 引入context.setExtraHTTPHeaders()。Agent 能力演進從原生循環到 CUA / Hybrid2.0.0 — agent 的誕生2.0.0 是里程碑版本核心亮點包括新增stagehand.agent一行代碼接入 SOTA 計算機使用模型Computer Use Model或 Browserbase 的 Open Operator提供原生 agentic loop不傳 provider 即可用與基于 LLM 的 agent 循環可用單一 prompt 構建多步工作流支持將 agent 任務卸載offload到 Stagehand API原生支持 Anthropic 與 OpenAI 的 CUAComputer Using Agent模型可傳入 OpenAI 實例作為llmClient兼容 Ollama、Gemini、Braintrust 等 OpenAI 兼容模型。3.0.x — Hybrid 模式與 agent 工具鏈3.0.7新增hybrid 模式先實驗后轉正3.0.7 移出 experimental支持mode: cua替代舊cua: true支持 CUA 安全確認、坐標 hoverpage.hover、agent abort/停止、跨會話消息續跑。3.0.8支持從 agent 排除特定工具新增 agent 流式輸出stream: trueagent 結果支持結構化輸出。3.4.0默認 agent 模式改為 hybrid并對不兼容的模型自動路由到 DOM 模式playwright-core/puppeteer-core/patchright-core從 optionalDependencies 移入 peerDependencies。3.6.x / 3.7.x — WebMCP 與 CUA 精修3.6.0新增WebMCP支持本地瀏覽器默認以--enable-featuresWebMCPTesting,DevToolsWebMCPSupport啟動修復 Stagehand 生成的 shadow-root XPath 解析使確定性動作可命中 Web Component 內部元素。3.7.0修復 CUAkeypress按鍵組合同一 chord問題支持google/gemini-3.5-flashcomputer-use 模型setScreenshotProvider回調返回值從裸 base64 升級為{ base64, mediaType }ScreenshotProviderResultCUA 圖片載荷改用聲明式媒體類型修復 malformed UTF-16 快照文本進入模型提示的問題。安全與策略Domain Policy、Cookie 與 Headers3.7.0 — 域名策略Domain Policy3.7.0 為 context 引入域名訪問控制 API// 僅允許訪問指定域名 await context.setDomainPolicy({ allowedDomains: [allowed.domain] }); // 阻止訪問指定域名 await context.setDomainPolicy({ blockedDomains: [some.domain] });SDK 側實現見 packages/sdk-ts/src/browserContext.tsgetDomainPolicy/setDomainPolicy通過 RPC 下發到擴展運行時策略執行與自動關閉違規彈窗的邏輯在擴展層packages/extension/understudy/context.ts與 packages/extension/controllers/contextController.ts。集成測試見 packages/sdk-ts/tests/integration/contextDomainPolicy.test.ts。3.1.0 — Cookie 管理與 keepAlive新增context.addCookies()、context.clearCookies()、context.cookies()三個 Cookie 管理 APIstagehand.close()可通過布爾參數keepAlive控制是否關閉瀏覽器mode枚舉取代舊的cua布爾值OpenAPI 規范同步更新。其他安全與兼容細節3.2.0localBrowserLaunchOptions新增cdpHeaders支持通過 CDP URL 連接已有瀏覽器時攜帶自定義 HTTP 頭clientOptions支持自定義 headers3.5.0新增ignoreDefaultArgs選項可選擇性移除 chrome-launcher 內置默認參數如--disable-extensions2.1.0為 CDP 連接添加 user-agent3.1.0移除自動.env加載dotenv如需.env請顯式加載import dotenv from dotenv; dotenv.config({ path: .env });緩存從客戶端緩存到服務端緩存緩存一直是 Stagehand 的性能重點2.3.1啟用會話親和session affinity以優化緩存3.1.0服務端緩存server-side caching上線——當env: BROWSERBASE時act()/extract()/observe()結果自動在服務端緩存相同輸入的重復調用即時返回、不消耗 LLM token默認開啟可用serverCache: false實例級或單次調用級關閉3.0.7緩存命中時可跳過 XPath 計算僅緩存開啟時計算 XPathagent 緩存失敗后不刷新等問題被修復3.6.0ActCache鍵派生對 URL 查詢參數排序后再哈希——語義等價但參數順序不同的 URL如?utm_sourceemailid42vs?id42utm_sourceemail現在可以命中緩存同時保留 fragment 與重復鍵。模型與 Provider 支持矩陣CHANGELOG 記錄了持續的模型與 Provider 擴展Provider 維度OpenAI含自定義 baseURL、Anthropic含 CUA 專用computer-use-2025-11-24beta 頭與computer_20251124工具版本、Google Gemini / Vertex支持自定義 provider headers如X-Goog-Priority、Azure OpenAI3.6.0 起支持 Microsoft Entra ID 認證、AWS Bedrockprovider 枚舉、Groq、Cerebras、Codex 模型、GLMprompt-based JSON fallback、微軟 Fara-7B模型維度gpt-4.5-preview、gpt-5.x系列、o1/o3-mini、claude-4.x、claude-fable-53.6.0原生結構化輸出、adaptive thinking 含新的 xhigh effort、內置服務端 refusal 回退到 claude-opus-4-8、google/gemini-3.5-flash、Gemini 3 flash/pro 等配置維度3.7.0 允許modelName: auto構造函數級與單原語覆蓋ModelConfig支持自定義headersopenaiEndpointFormat: chat讓 OpenAI 兼容模型可選 Chat Completions API3.6.0 移除默認 temperature 設置避免不支持 temperature 的推理模型產生 provider 警告。可觀測性Metrics、Logging 與 Verifier2.0.0新增stagehand.metricstoken 用量與logInferenceToFile記錄完整調用/響應歷史pino 日志自定義錯誤類disablePino標志3.0.3metrics 暴露 reasoning 與 cached input tokens3.3.0API-backed 會話的agent.execute()用量計入stagehand.metrics支持 Browserbase verified session 設置3.6.0新增rubric-based verifier 引擎標準化公開 rubric 輸出與有界的失敗步驟解析與 verifier trajectory / rubric / evaluation-result 類型verifier 證據可從 agent evidence 回調捕獲用于離線評分見packages/evals/framework下的verifierGate.ts、verifierAdapter.ts、adHocRubric.ts3.2.0BROWSERBASE_FLOW_LOGS1啟用 FlowLogger。多頁與復雜 DOMIframe、Shadow DOM 與 OOPIF1.9.0on(popup)監聽傳入 Page 對象以支持多頁2.4.3實驗性支持 Shadow DOMopen closed支持 iframe 內滾動2.4.xiframe 移出 experimental修復嵌套 iframe XPath3.0.xpage.addInitScript()/context.addInitScript()并修復 init scripts 在 OOPIF、SPIF、popup 頁面上的注入問題locator.count()/.nth()支持 Shadow DOM 與 XPath 謂詞3.1.0修復 Shadow DOM 相關.count()與 XPath 謂詞問題3.6.0修復 Stagehand 生成的 shadow-root XPath確定性動作可定位 Web Component 內部元素3.4.0修復 OOPIF 頁面的 frame registry 處理。環境變量速查結合 CHANGELOG 與源碼當前值得關注的環境變量包括環境變量用途引入版本STAGEHAND_EXTENSION_ARCHIVE_PATH覆蓋擴展 zip 路徑針對內聯打包器4.0.1STAGEHAND_EXTENSION_DIRECTORY_PATH覆蓋擴展目錄路徑4.0.1STAGEHAND_API_URL覆蓋 Stagehand API 地址STAGEHAND_BASE_URL為已棄用回退3.4.0BROWSERBASE_API_KEYBrowserbase 會話認證projectId 自 3.2.0 起可選長期BROWSERBASE_FLOW_LOGS置 1 啟用 FlowLogger3.2.0升級路徑v2 → v33.0.0 移除內部 Playwright 依賴兼容 Playwright / Puppeteer / Patchrightact接受指令字符串而非動作字符串observeResult更名為actionModelConfiguration類型固化官方遷移指南見 packages/docs/v3/migrations/v2.mdx。v3 → v4圍繞 v4 協議重建TypeScript / Python / Go 三語言同步遷移指南見 packages/docs/v4/migrations/v3.mdx。v4 內部遷移若從 Playwright 遷移到 Stagehand可參考 packages/docs/v4/migrations/playwright.mdx從 browser-use 遷移見 packages/docs/v4/migrations/browser-use.mdx。深入源碼的索引想要進一步驗證本文所述特性可以直接閱讀以下文件協議定義與類型packages/protocol/stagehand.v4.json、packages/protocol/schemas.ts、packages/protocol/json-rpc/schemas.tsTS SDK 核心packages/sdk-ts/src/browserContext.ts、packages/sdk-ts/src/page.ts、packages/sdk-ts/src/stagehand.tsPython SDKpackages/sdk-python/src/stagehand/Go SDKpackages/sdk-go/stagehand.go擴展運行時packages/extension/runtime.ts、packages/extension/understudy/領域策略測試packages/sdk-ts/tests/integration/contextDomainPolicy.test.ts變更日志原文CHANGELOG.md總結從 CHANGELOG 可以看到 Stagehand 的清晰演進主線封裝 Playwright → 原生 agent 循環 → CUA / Hybrid 多模式 → 協議優先的多語言 monorepo。對于開發者而言v4 意味著統一的行為契約與跨語言一致性而緩存、域名策略、verifier 等能力則讓瀏覽器 Agent 在生產環境中更可控、更可觀測。升級時建議優先參考對應版本的遷移指南并結合本文梳理的模型、緩存與環境變量差異進行回歸驗證。【免費下載鏈接】stagehandThe SDK For Browser Agents項目地址: https://gitcode.com/GitHub_Trending/stag/stagehand創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 Stagehand 瀏覽器 Agent SDK 版本演進全解：從 v1 到 v4 的核心能力與升級指南
Stagehand 瀏覽器 Agent SDK 版本演進全解從 v1 到 v4 的核心能力與升級指南【免費下載鏈接】stagehandThe SDK For Browser Agents項目地址: https://gitcode.com/GitHub_Trending/stag/stagehandStagehand 是面向瀏覽器 Agent 的 SDK本倉庫 CHANGELOG.md 完整記錄了其公開 TypeScript 與 Python SDK4.0.0 之前僅描述 TypeScript SDK從 1.x 到 4.x 的演進歷程。本文以該變更日志為主線結合倉庫源碼系統梳理act/extract/observe/agent四大核心原語的演變、CUA 與 Hybrid 模式的出現、緩存與安全策略的完善幫助你在升級版本時快速定位行為差異并理解每個重要特性背后的實現細節。版本結構概覽一個協議優先的 Monorepo從 CHANGELOG 的開頭可以清晰看到當前倉庫是一個多語言、多包的工作區變更日志按以下產物分軌記錄TypeScript SDKpackages/sdk-ts主 SDK自 1.0.0 起持續演進Python SDKpackages/sdk-python與Go SDKpackages/sdk-go在 v4 時代與 TypeScript SDK 同步發布Extension Runtimepackages/extension瀏覽器擴展運行時作為協議層的執行載體。工作區根目錄的 package.json 表明這是一個基于 pnpm Turbo 的 monoreponame: stagehand-workspaceversion: 4.0.0并使用 changesets 管理版本發布這解釋了 CHANGELOG 中Major / Minor / Patch Changes的分類來源。v4.0.0圍繞瀏覽器協議的全面重構4.0.0 — 協議優先架構v4 是 CHANGELOG 中最重要的一次 Major 版本其核心表述為Rebuilt Stagehand around its v4 browser protocol and TypeScript SDK. Stagehand is now a protocol-first monorepo with TypeScript, Python, and Go SDKs over a shared core.這標志著 Stagehand 從Playwright 之上的封裝轉變為**協議優先protocol-first**的架構三種語言 SDK 共享同一個 v4 瀏覽器協議擴展運行時Extension Runtime通過 JSON-RPC見 packages/protocol/json-rpc與各語言 SDK 通信。Python SDK 也在 4.0.0 中圍繞 v4 瀏覽器協議重建。從源碼結構看v4 引入了統一的對象模型BrowserContext、Page、Locator、Response、Clipboard等見 packages/sdk-ts/src 與 packages/sdk-python/src/stagehand各語言保持 API 語義一致。4.0.1 — 擴展資產與環境變量4.0.1 引入了兩個重要的環境變量STAGEHAND_EXTENSION_ARCHIVE_PATH覆蓋擴展 zip 壓縮包路徑STAGEHAND_EXTENSION_DIRECTORY_PATH覆蓋擴展目錄路徑。這兩個變量的設計動機在 packages/sdk-ts/src/extensionAssets.ts 的源碼注釋中交代得很清楚針對會把模塊內聯、導致import.meta.url基準路徑失效的打包器如 nitro、eve dev 的 authored-module 編譯器提供顯式路徑覆蓋能力。實現上通過nonEmpty()輔助函數保證空字符串/純空白會被忽略回退到包內dist/assets/stagehand-extension.zip與dist/extension/。同版本還支持了通過STAGEHAND_EXTENSION_ARCHIVE_PATH覆蓋擴展資產位置并在 Browserbase 會話元數據中記錄 Stagehand SDK 版本便于服務端調試。4.0.2 — 運行時重連4.0.2 的補丁允許SDK 客戶端重新掛接到已初始化的 Stagehand 擴展運行時。這為連接已有瀏覽器會話含 Browserbase 遠程會話場景提供了更穩定的保障TypeScript / Python / Go / Extension Runtime 四軌同步發布。核心原語act / extract / observe 的演進早期從stagehand.act()到stagehand.page.act()1.8.0 將act/extract/observe從 Stagehand 頂層遷移到page對象stagehand.act()→stagehand.page.act()并引入StagehandPage/StagehandContext包裝對象以增強底層 Playwright 能力。2.0.0 起這些原語被統一放在 Page 層級stagehand.history數組會記錄act/extract/observe/goto調用即使由 agent 間接調用也會被捕獲。提取extract能力的持續加強1.7.0新增textExtract一種基于文本的長文提取方案默認extract走domExtractDOM 處理。1.14.0extract()無參數調用即可確定性地獲取頁面全文文本表示支持通過selectorXPath做定向提取只處理目標元素降低 token 消耗、提升速度const weatherData await stagehand.page.extract({ instruction: extract the weather data for Sun, Feb 23 at 11PM, schema: z.object({ temperature: z.string(), weather_description: z.string(), wind: z.string(), humidity: z.string(), barometer: z.string(), visibility: z.string(), }), modelName, selector: xpath, // 目標元素的 xpath限制 DOM 處理范圍 });2.0.0默認使用 a11y無障礙樹作為提取上下文。3.4.0extract()與observe()新增ignoreSelectors參數可排除特定元素。3.5.0extract()新增screenshot選項——把當前視口截圖與 a11y 樹一同發送給模型提升對視覺信息的提取準確性。觀察observe與動作act的聯動1.12.0observe大升級為候選元素返回建議的 Playwright 方法及參數act可直接接受observe的輸出。1.14.0act()可在內部改用observe()管道slowDomBasedAct: false時啟用帶來顯著的性能提升。3.0.8agent 的關閉工具更名為donepage.snapshot()與page.waitForSelector()被加入頁面原語。3.2.0新增page.setExtraHTTPHeaders()3.1.0 引入context.setExtraHTTPHeaders()。Agent 能力演進從原生循環到 CUA / Hybrid2.0.0 — agent 的誕生2.0.0 是里程碑版本核心亮點包括新增stagehand.agent一行代碼接入 SOTA 計算機使用模型Computer Use Model或 Browserbase 的 Open Operator提供原生 agentic loop不傳 provider 即可用與基于 LLM 的 agent 循環可用單一 prompt 構建多步工作流支持將 agent 任務卸載offload到 Stagehand API原生支持 Anthropic 與 OpenAI 的 CUAComputer Using Agent模型可傳入 OpenAI 實例作為llmClient兼容 Ollama、Gemini、Braintrust 等 OpenAI 兼容模型。3.0.x — Hybrid 模式與 agent 工具鏈3.0.7新增hybrid 模式先實驗后轉正3.0.7 移出 experimental支持mode: cua替代舊cua: true支持 CUA 安全確認、坐標 hoverpage.hover、agent abort/停止、跨會話消息續跑。3.0.8支持從 agent 排除特定工具新增 agent 流式輸出stream: trueagent 結果支持結構化輸出。3.4.0默認 agent 模式改為 hybrid并對不兼容的模型自動路由到 DOM 模式playwright-core/puppeteer-core/patchright-core從 optionalDependencies 移入 peerDependencies。3.6.x / 3.7.x — WebMCP 與 CUA 精修3.6.0新增WebMCP支持本地瀏覽器默認以--enable-featuresWebMCPTesting,DevToolsWebMCPSupport啟動修復 Stagehand 生成的 shadow-root XPath 解析使確定性動作可命中 Web Component 內部元素。3.7.0修復 CUAkeypress按鍵組合同一 chord問題支持google/gemini-3.5-flashcomputer-use 模型setScreenshotProvider回調返回值從裸 base64 升級為{ base64, mediaType }ScreenshotProviderResultCUA 圖片載荷改用聲明式媒體類型修復 malformed UTF-16 快照文本進入模型提示的問題。安全與策略Domain Policy、Cookie 與 Headers3.7.0 — 域名策略Domain Policy3.7.0 為 context 引入域名訪問控制 API// 僅允許訪問指定域名 await context.setDomainPolicy({ allowedDomains: [allowed.domain] }); // 阻止訪問指定域名 await context.setDomainPolicy({ blockedDomains: [some.domain] });SDK 側實現見 packages/sdk-ts/src/browserContext.tsgetDomainPolicy/setDomainPolicy通過 RPC 下發到擴展運行時策略執行與自動關閉違規彈窗的邏輯在擴展層packages/extension/understudy/context.ts與 packages/extension/controllers/contextController.ts。集成測試見 packages/sdk-ts/tests/integration/contextDomainPolicy.test.ts。3.1.0 — Cookie 管理與 keepAlive新增context.addCookies()、context.clearCookies()、context.cookies()三個 Cookie 管理 APIstagehand.close()可通過布爾參數keepAlive控制是否關閉瀏覽器mode枚舉取代舊的cua布爾值OpenAPI 規范同步更新。其他安全與兼容細節3.2.0localBrowserLaunchOptions新增cdpHeaders支持通過 CDP URL 連接已有瀏覽器時攜帶自定義 HTTP 頭clientOptions支持自定義 headers3.5.0新增ignoreDefaultArgs選項可選擇性移除 chrome-launcher 內置默認參數如--disable-extensions2.1.0為 CDP 連接添加 user-agent3.1.0移除自動.env加載dotenv如需.env請顯式加載import dotenv from dotenv; dotenv.config({ path: .env });緩存從客戶端緩存到服務端緩存緩存一直是 Stagehand 的性能重點2.3.1啟用會話親和session affinity以優化緩存3.1.0服務端緩存server-side caching上線——當env: BROWSERBASE時act()/extract()/observe()結果自動在服務端緩存相同輸入的重復調用即時返回、不消耗 LLM token默認開啟可用serverCache: false實例級或單次調用級關閉3.0.7緩存命中時可跳過 XPath 計算僅緩存開啟時計算 XPathagent 緩存失敗后不刷新等問題被修復3.6.0ActCache鍵派生對 URL 查詢參數排序后再哈希——語義等價但參數順序不同的 URL如?utm_sourceemailid42vs?id42utm_sourceemail現在可以命中緩存同時保留 fragment 與重復鍵。模型與 Provider 支持矩陣CHANGELOG 記錄了持續的模型與 Provider 擴展Provider 維度OpenAI含自定義 baseURL、Anthropic含 CUA 專用computer-use-2025-11-24beta 頭與computer_20251124工具版本、Google Gemini / Vertex支持自定義 provider headers如X-Goog-Priority、Azure OpenAI3.6.0 起支持 Microsoft Entra ID 認證、AWS Bedrockprovider 枚舉、Groq、Cerebras、Codex 模型、GLMprompt-based JSON fallback、微軟 Fara-7B模型維度gpt-4.5-preview、gpt-5.x系列、o1/o3-mini、claude-4.x、claude-fable-53.6.0原生結構化輸出、adaptive thinking 含新的 xhigh effort、內置服務端 refusal 回退到 claude-opus-4-8、google/gemini-3.5-flash、Gemini 3 flash/pro 等配置維度3.7.0 允許modelName: auto構造函數級與單原語覆蓋ModelConfig支持自定義headersopenaiEndpointFormat: chat讓 OpenAI 兼容模型可選 Chat Completions API3.6.0 移除默認 temperature 設置避免不支持 temperature 的推理模型產生 provider 警告。可觀測性Metrics、Logging 與 Verifier2.0.0新增stagehand.metricstoken 用量與logInferenceToFile記錄完整調用/響應歷史pino 日志自定義錯誤類disablePino標志3.0.3metrics 暴露 reasoning 與 cached input tokens3.3.0API-backed 會話的agent.execute()用量計入stagehand.metrics支持 Browserbase verified session 設置3.6.0新增rubric-based verifier 引擎標準化公開 rubric 輸出與有界的失敗步驟解析與 verifier trajectory / rubric / evaluation-result 類型verifier 證據可從 agent evidence 回調捕獲用于離線評分見packages/evals/framework下的verifierGate.ts、verifierAdapter.ts、adHocRubric.ts3.2.0BROWSERBASE_FLOW_LOGS1啟用 FlowLogger。多頁與復雜 DOMIframe、Shadow DOM 與 OOPIF1.9.0on(popup)監聽傳入 Page 對象以支持多頁2.4.3實驗性支持 Shadow DOMopen closed支持 iframe 內滾動2.4.xiframe 移出 experimental修復嵌套 iframe XPath3.0.xpage.addInitScript()/context.addInitScript()并修復 init scripts 在 OOPIF、SPIF、popup 頁面上的注入問題locator.count()/.nth()支持 Shadow DOM 與 XPath 謂詞3.1.0修復 Shadow DOM 相關.count()與 XPath 謂詞問題3.6.0修復 Stagehand 生成的 shadow-root XPath確定性動作可定位 Web Component 內部元素3.4.0修復 OOPIF 頁面的 frame registry 處理。環境變量速查結合 CHANGELOG 與源碼當前值得關注的環境變量包括環境變量用途引入版本STAGEHAND_EXTENSION_ARCHIVE_PATH覆蓋擴展 zip 路徑針對內聯打包器4.0.1STAGEHAND_EXTENSION_DIRECTORY_PATH覆蓋擴展目錄路徑4.0.1STAGEHAND_API_URL覆蓋 Stagehand API 地址STAGEHAND_BASE_URL為已棄用回退3.4.0BROWSERBASE_API_KEYBrowserbase 會話認證projectId 自 3.2.0 起可選長期BROWSERBASE_FLOW_LOGS置 1 啟用 FlowLogger3.2.0升級路徑v2 → v33.0.0 移除內部 Playwright 依賴兼容 Playwright / Puppeteer / Patchrightact接受指令字符串而非動作字符串observeResult更名為actionModelConfiguration類型固化官方遷移指南見 packages/docs/v3/migrations/v2.mdx。v3 → v4圍繞 v4 協議重建TypeScript / Python / Go 三語言同步遷移指南見 packages/docs/v4/migrations/v3.mdx。v4 內部遷移若從 Playwright 遷移到 Stagehand可參考 packages/docs/v4/migrations/playwright.mdx從 browser-use 遷移見 packages/docs/v4/migrations/browser-use.mdx。深入源碼的索引想要進一步驗證本文所述特性可以直接閱讀以下文件協議定義與類型packages/protocol/stagehand.v4.json、packages/protocol/schemas.ts、packages/protocol/json-rpc/schemas.tsTS SDK 核心packages/sdk-ts/src/browserContext.ts、packages/sdk-ts/src/page.ts、packages/sdk-ts/src/stagehand.tsPython SDKpackages/sdk-python/src/stagehand/Go SDKpackages/sdk-go/stagehand.go擴展運行時packages/extension/runtime.ts、packages/extension/understudy/領域策略測試packages/sdk-ts/tests/integration/contextDomainPolicy.test.ts變更日志原文CHANGELOG.md總結從 CHANGELOG 可以看到 Stagehand 的清晰演進主線封裝 Playwright → 原生 agent 循環 → CUA / Hybrid 多模式 → 協議優先的多語言 monorepo。對于開發者而言v4 意味著統一的行為契約與跨語言一致性而緩存、域名策略、verifier 等能力則讓瀏覽器 Agent 在生產環境中更可控、更可觀測。升級時建議優先參考對應版本的遷移指南并結合本文梳理的模型、緩存與環境變量差異進行回歸驗證。【免費下載鏈接】stagehandThe SDK For Browser Agents項目地址: https://gitcode.com/GitHub_Trending/stag/stagehand創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考