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 的演進歷程。本文以該變更日志為主線結(jié)合倉庫源碼系統(tǒng)梳理act/extract/observe/agent四大核心原語的演變、CUA 與 Hybrid 模式的出現(xiàn)、緩存與安全策略的完善幫助你在升級版本時快速定位行為差異并理解每個重要特性背后的實現(xiàn)細節(jié)。版本結(jié)構(gòu)概覽一個協(xié)議優(yōu)先的 Monorepo從 CHANGELOG 的開頭可以清晰看到當前倉庫是一個多語言、多包的工作區(qū)變更日志按以下產(chǎn)物分軌記錄TypeScript SDKpackages/sdk-ts主 SDK自 1.0.0 起持續(xù)演進Python SDKpackages/sdk-python與Go SDKpackages/sdk-go在 v4 時代與 TypeScript SDK 同步發(fā)布Extension Runtimepackages/extension瀏覽器擴展運行時作為協(xié)議層的執(zhí)行載體。工作區(qū)根目錄的 package.json 表明這是一個基于 pnpm Turbo 的 monoreponame: stagehand-workspaceversion: 4.0.0并使用 changesets 管理版本發(fā)布這解釋了 CHANGELOG 中Major / Minor / Patch Changes的分類來源。v4.0.0圍繞瀏覽器協(xié)議的全面重構(gòu)4.0.0 — 協(xié)議優(yōu)先架構(gòu)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 之上的封裝轉(zhuǎn)變?yōu)?*協(xié)議優(yōu)先protocol-first**的架構(gòu)三種語言 SDK 共享同一個 v4 瀏覽器協(xié)議擴展運行時Extension Runtime通過 JSON-RPC見 packages/protocol/json-rpc與各語言 SDK 通信。Python SDK 也在 4.0.0 中圍繞 v4 瀏覽器協(xié)議重建。從源碼結(jié)構(gòu)看v4 引入了統(tǒng)一的對象模型BrowserContext、Page、Locator、Response、Clipboard等見 packages/sdk-ts/src 與 packages/sdk-python/src/stagehand各語言保持 API 語義一致。4.0.1 — 擴展資產(chǎn)與環(huán)境變量4.0.1 引入了兩個重要的環(huán)境變量STAGEHAND_EXTENSION_ARCHIVE_PATH覆蓋擴展 zip 壓縮包路徑STAGEHAND_EXTENSION_DIRECTORY_PATH覆蓋擴展目錄路徑。這兩個變量的設(shè)計動機在 packages/sdk-ts/src/extensionAssets.ts 的源碼注釋中交代得很清楚針對會把模塊內(nèi)聯(lián)、導(dǎo)致import.meta.url基準路徑失效的打包器如 nitro、eve dev 的 authored-module 編譯器提供顯式路徑覆蓋能力。實現(xiàn)上通過nonEmpty()輔助函數(shù)保證空字符串/純空白會被忽略回退到包內(nèi)dist/assets/stagehand-extension.zip與dist/extension/。同版本還支持了通過STAGEHAND_EXTENSION_ARCHIVE_PATH覆蓋擴展資產(chǎn)位置并在 Browserbase 會話元數(shù)據(jù)中記錄 Stagehand SDK 版本便于服務(wù)端調(diào)試。4.0.2 — 運行時重連4.0.2 的補丁允許SDK 客戶端重新掛接到已初始化的 Stagehand 擴展運行時。這為連接已有瀏覽器會話含 Browserbase 遠程會話場景提供了更穩(wěn)定的保障TypeScript / Python / Go / Extension Runtime 四軌同步發(fā)布。核心原語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 起這些原語被統(tǒng)一放在 Page 層級stagehand.history數(shù)組會記錄act/extract/observe/goto調(diào)用即使由 agent 間接調(diào)用也會被捕獲。提取extract能力的持續(xù)加強1.7.0新增textExtract一種基于文本的長文提取方案默認extract走domExtractDOM 處理。1.14.0extract()無參數(shù)調(diào)用即可確定性地獲取頁面全文文本表示支持通過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參數(shù)可排除特定元素。3.5.0extract()新增screenshot選項——把當前視口截圖與 a11y 樹一同發(fā)送給模型提升對視覺信息的提取準確性。觀察observe與動作act的聯(lián)動1.12.0observe大升級為候選元素返回建議的 Playwright 方法及參數(shù)act可直接接受observe的輸出。1.14.0act()可在內(nèi)部改用observe()管道slowDomBasedAct: false時啟用帶來顯著的性能提升。3.0.8agent 的關(guān)閉工具更名為donepage.snapshot()與page.waitForSelector()被加入頁面原語。3.2.0新增page.setExtraHTTPHeaders()3.1.0 引入context.setExtraHTTPHeaders()。Agent 能力演進從原生循環(huán)到 CUA / Hybrid2.0.0 — agent 的誕生2.0.0 是里程碑版本核心亮點包括新增stagehand.agent一行代碼接入 SOTA 計算機使用模型Computer Use Model或 Browserbase 的 Open Operator提供原生 agentic loop不傳 provider 即可用與基于 LLM 的 agent 循環(huán)可用單一 prompt 構(gòu)建多步工作流支持將 agent 任務(wù)卸載offload到 Stagehand API原生支持 Anthropic 與 OpenAI 的 CUAComputer Using Agent模型可傳入 OpenAI 實例作為llmClient兼容 Ollama、Gemini、Braintrust 等 OpenAI 兼容模型。3.0.x — Hybrid 模式與 agent 工具鏈3.0.7新增hybrid 模式先實驗后轉(zhuǎn)正3.0.7 移出 experimental支持mode: cua替代舊cua: true支持 CUA 安全確認、坐標 hoverpage.hover、agent abort/停止、跨會話消息續(xù)跑。3.0.8支持從 agent 排除特定工具新增 agent 流式輸出stream: trueagent 結(jié)果支持結(jié)構(gòu)化輸出。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啟動修復(fù) Stagehand 生成的 shadow-root XPath 解析使確定性動作可命中 Web Component 內(nèi)部元素。3.7.0修復(fù) CUAkeypress按鍵組合同一 chord問題支持google/gemini-3.5-flashcomputer-use 模型setScreenshotProvider回調(diào)返回值從裸 base64 升級為{ base64, mediaType }ScreenshotProviderResultCUA 圖片載荷改用聲明式媒體類型修復(fù) 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 側(cè)實現(xiàn)見 packages/sdk-ts/src/browserContext.tsgetDomainPolicy/setDomainPolicy通過 RPC 下發(fā)到擴展運行時策略執(zhí)行與自動關(guān)閉違規(guī)彈窗的邏輯在擴展層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()可通過布爾參數(shù)keepAlive控制是否關(guān)閉瀏覽器mode枚舉取代舊的cua布爾值OpenAPI 規(guī)范同步更新。其他安全與兼容細節(jié)3.2.0localBrowserLaunchOptions新增cdpHeaders支持通過 CDP URL 連接已有瀏覽器時攜帶自定義 HTTP 頭clientOptions支持自定義 headers3.5.0新增ignoreDefaultArgs選項可選擇性移除 chrome-launcher 內(nèi)置默認參數(shù)如--disable-extensions2.1.0為 CDP 連接添加 user-agent3.1.0移除自動.env加載dotenv如需.env請顯式加載import dotenv from dotenv; dotenv.config({ path: .env });緩存從客戶端緩存到服務(wù)端緩存緩存一直是 Stagehand 的性能重點2.3.1啟用會話親和session affinity以優(yōu)化緩存3.1.0服務(wù)端緩存server-side caching上線——當env: BROWSERBASE時act()/extract()/observe()結(jié)果自動在服務(wù)端緩存相同輸入的重復(fù)調(diào)用即時返回、不消耗 LLM token默認開啟可用serverCache: false實例級或單次調(diào)用級關(guān)閉3.0.7緩存命中時可跳過 XPath 計算僅緩存開啟時計算 XPathagent 緩存失敗后不刷新等問題被修復(fù)3.6.0ActCache鍵派生對 URL 查詢參數(shù)排序后再哈?！Z義等價但參數(shù)順序不同的 URL如?utm_sourceemailid42vs?id42utm_sourceemail現(xiàn)在可以命中緩存同時保留 fragment 與重復(fù)鍵。模型與 Provider 支持矩陣CHANGELOG 記錄了持續(xù)的模型與 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原生結(jié)構(gòu)化輸出、adaptive thinking 含新的 xhigh effort、內(nèi)置服務(wù)端 refusal 回退到 claude-opus-4-8、google/gemini-3.5-flash、Gemini 3 flash/pro 等配置維度3.7.0 允許modelName: auto構(gòu)造函數(shù)級與單原語覆蓋ModelConfig支持自定義headersopenaiEndpointFormat: chat讓 OpenAI 兼容模型可選 Chat Completions API3.6.0 移除默認 temperature 設(shè)置避免不支持 temperature 的推理模型產(chǎn)生 provider 警告?？捎^測性Metrics、Logging 與 Verifier2.0.0新增stagehand.metricstoken 用量與logInferenceToFile記錄完整調(diào)用/響應(yīng)歷史pino 日志自定義錯誤類disablePino標志3.0.3metrics 暴露 reasoning 與 cached input tokens3.3.0API-backed 會話的agent.execute()用量計入stagehand.metrics支持 Browserbase verified session 設(shè)置3.6.0新增rubric-based verifier 引擎標準化公開 rubric 輸出與有界的失敗步驟解析與 verifier trajectory / rubric / evaluation-result 類型verifier 證據(jù)可從 agent evidence 回調(diào)捕獲用于離線評分見packages/evals/framework下的verifierGate.ts、verifierAdapter.ts、adHocRubric.ts3.2.0BROWSERBASE_FLOW_LOGS1啟用 FlowLogger。多頁與復(fù)雜 DOMIframe、Shadow DOM 與 OOPIF1.9.0on(popup)監(jiān)聽傳入 Page 對象以支持多頁2.4.3實驗性支持 Shadow DOMopen closed支持 iframe 內(nèi)滾動2.4.xiframe 移出 experimental修復(fù)嵌套 iframe XPath3.0.xpage.addInitScript()/context.addInitScript()并修復(fù) init scripts 在 OOPIF、SPIF、popup 頁面上的注入問題locator.count()/.nth()支持 Shadow DOM 與 XPath 謂詞3.1.0修復(fù) Shadow DOM 相關(guān).count()與 XPath 謂詞問題3.6.0修復(fù) Stagehand 生成的 shadow-root XPath確定性動作可定位 Web Component 內(nèi)部元素3.4.0修復(fù) OOPIF 頁面的 frame registry 處理。環(huán)境變量速查結(jié)合 CHANGELOG 與源碼當前值得關(guān)注的環(huán)境變量包括環(huán)境變量用途引入版本STAGEHAND_EXTENSION_ARCHIVE_PATH覆蓋擴展 zip 路徑針對內(nèi)聯(lián)打包器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 移除內(nèi)部 Playwright 依賴兼容 Playwright / Puppeteer / Patchrightact接受指令字符串而非動作字符串observeResult更名為actionModelConfiguration類型固化官方遷移指南見 packages/docs/v3/migrations/v2.mdx。v3 → v4圍繞 v4 協(xié)議重建TypeScript / Python / Go 三語言同步遷移指南見 packages/docs/v4/migrations/v3.mdx。v4 內(nèi)部遷移若從 Playwright 遷移到 Stagehand可參考 packages/docs/v4/migrations/playwright.mdx從 browser-use 遷移見 packages/docs/v4/migrations/browser-use.mdx。深入源碼的索引想要進一步驗證本文所述特性可以直接閱讀以下文件協(xié)議定義與類型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/領(lǐng)域策略測試packages/sdk-ts/tests/integration/contextDomainPolicy.test.ts變更日志原文CHANGELOG.md總結(jié)從 CHANGELOG 可以看到 Stagehand 的清晰演進主線封裝 Playwright → 原生 agent 循環(huán) → CUA / Hybrid 多模式 → 協(xié)議優(yōu)先的多語言 monorepo。對于開發(fā)者而言v4 意味著統(tǒng)一的行為契約與跨語言一致性而緩存、域名策略、verifier 等能力則讓瀏覽器 Agent 在生產(chǎn)環(huán)境中更可控、更可觀測。升級時建議優(yōu)先參考對應(yīng)版本的遷移指南并結(jié)合本文梳理的模型、緩存與環(huán)境變量差異進行回歸驗證?！久赓M下載鏈接】stagehandThe SDK For Browser Agents項目地址: https://gitcode.com/GitHub_Trending/stag/stagehand創(chuàng)作聲明：本文部分內(nèi)容由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 的演進歷程。本文以該變更日志為主線結(jié)合倉庫源碼系統(tǒng)梳理act/extract/observe/agent四大核心原語的演變、CUA 與 Hybrid 模式的出現(xiàn)、緩存與安全策略的完善幫助你在升級版本時快速定位行為差異并理解每個重要特性背后的實現(xiàn)細節(jié)。版本結(jié)構(gòu)概覽一個協(xié)議優(yōu)先的 Monorepo從 CHANGELOG 的開頭可以清晰看到當前倉庫是一個多語言、多包的工作區(qū)變更日志按以下產(chǎn)物分軌記錄TypeScript SDKpackages/sdk-ts主 SDK自 1.0.0 起持續(xù)演進Python SDKpackages/sdk-python與Go SDKpackages/sdk-go在 v4 時代與 TypeScript SDK 同步發(fā)布Extension Runtimepackages/extension瀏覽器擴展運行時作為協(xié)議層的執(zhí)行載體。工作區(qū)根目錄的 package.json 表明這是一個基于 pnpm Turbo 的 monoreponame: stagehand-workspaceversion: 4.0.0并使用 changesets 管理版本發(fā)布這解釋了 CHANGELOG 中Major / Minor / Patch Changes的分類來源。v4.0.0圍繞瀏覽器協(xié)議的全面重構(gòu)4.0.0 — 協(xié)議優(yōu)先架構(gòu)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 之上的封裝轉(zhuǎn)變?yōu)?*協(xié)議優(yōu)先protocol-first**的架構(gòu)三種語言 SDK 共享同一個 v4 瀏覽器協(xié)議擴展運行時Extension Runtime通過 JSON-RPC見 packages/protocol/json-rpc與各語言 SDK 通信。Python SDK 也在 4.0.0 中圍繞 v4 瀏覽器協(xié)議重建。從源碼結(jié)構(gòu)看v4 引入了統(tǒng)一的對象模型BrowserContext、Page、Locator、Response、Clipboard等見 packages/sdk-ts/src 與 packages/sdk-python/src/stagehand各語言保持 API 語義一致。4.0.1 — 擴展資產(chǎn)與環(huán)境變量4.0.1 引入了兩個重要的環(huán)境變量STAGEHAND_EXTENSION_ARCHIVE_PATH覆蓋擴展 zip 壓縮包路徑STAGEHAND_EXTENSION_DIRECTORY_PATH覆蓋擴展目錄路徑。這兩個變量的設(shè)計動機在 packages/sdk-ts/src/extensionAssets.ts 的源碼注釋中交代得很清楚針對會把模塊內(nèi)聯(lián)、導(dǎo)致import.meta.url基準路徑失效的打包器如 nitro、eve dev 的 authored-module 編譯器提供顯式路徑覆蓋能力。實現(xiàn)上通過nonEmpty()輔助函數(shù)保證空字符串/純空白會被忽略回退到包內(nèi)dist/assets/stagehand-extension.zip與dist/extension/。同版本還支持了通過STAGEHAND_EXTENSION_ARCHIVE_PATH覆蓋擴展資產(chǎn)位置并在 Browserbase 會話元數(shù)據(jù)中記錄 Stagehand SDK 版本便于服務(wù)端調(diào)試。4.0.2 — 運行時重連4.0.2 的補丁允許SDK 客戶端重新掛接到已初始化的 Stagehand 擴展運行時。這為連接已有瀏覽器會話含 Browserbase 遠程會話場景提供了更穩(wěn)定的保障TypeScript / Python / Go / Extension Runtime 四軌同步發(fā)布。核心原語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 起這些原語被統(tǒng)一放在 Page 層級stagehand.history數(shù)組會記錄act/extract/observe/goto調(diào)用即使由 agent 間接調(diào)用也會被捕獲。提取extract能力的持續(xù)加強1.7.0新增textExtract一種基于文本的長文提取方案默認extract走domExtractDOM 處理。1.14.0extract()無參數(shù)調(diào)用即可確定性地獲取頁面全文文本表示支持通過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參數(shù)可排除特定元素。3.5.0extract()新增screenshot選項——把當前視口截圖與 a11y 樹一同發(fā)送給模型提升對視覺信息的提取準確性。觀察observe與動作act的聯(lián)動1.12.0observe大升級為候選元素返回建議的 Playwright 方法及參數(shù)act可直接接受observe的輸出。1.14.0act()可在內(nèi)部改用observe()管道slowDomBasedAct: false時啟用帶來顯著的性能提升。3.0.8agent 的關(guān)閉工具更名為donepage.snapshot()與page.waitForSelector()被加入頁面原語。3.2.0新增page.setExtraHTTPHeaders()3.1.0 引入context.setExtraHTTPHeaders()。Agent 能力演進從原生循環(huán)到 CUA / Hybrid2.0.0 — agent 的誕生2.0.0 是里程碑版本核心亮點包括新增stagehand.agent一行代碼接入 SOTA 計算機使用模型Computer Use Model或 Browserbase 的 Open Operator提供原生 agentic loop不傳 provider 即可用與基于 LLM 的 agent 循環(huán)可用單一 prompt 構(gòu)建多步工作流支持將 agent 任務(wù)卸載offload到 Stagehand API原生支持 Anthropic 與 OpenAI 的 CUAComputer Using Agent模型可傳入 OpenAI 實例作為llmClient兼容 Ollama、Gemini、Braintrust 等 OpenAI 兼容模型。3.0.x — Hybrid 模式與 agent 工具鏈3.0.7新增hybrid 模式先實驗后轉(zhuǎn)正3.0.7 移出 experimental支持mode: cua替代舊cua: true支持 CUA 安全確認、坐標 hoverpage.hover、agent abort/停止、跨會話消息續(xù)跑。3.0.8支持從 agent 排除特定工具新增 agent 流式輸出stream: trueagent 結(jié)果支持結(jié)構(gòu)化輸出。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啟動修復(fù) Stagehand 生成的 shadow-root XPath 解析使確定性動作可命中 Web Component 內(nèi)部元素。3.7.0修復(fù) CUAkeypress按鍵組合同一 chord問題支持google/gemini-3.5-flashcomputer-use 模型setScreenshotProvider回調(diào)返回值從裸 base64 升級為{ base64, mediaType }ScreenshotProviderResultCUA 圖片載荷改用聲明式媒體類型修復(fù) 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 側(cè)實現(xiàn)見 packages/sdk-ts/src/browserContext.tsgetDomainPolicy/setDomainPolicy通過 RPC 下發(fā)到擴展運行時策略執(zhí)行與自動關(guān)閉違規(guī)彈窗的邏輯在擴展層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()可通過布爾參數(shù)keepAlive控制是否關(guān)閉瀏覽器mode枚舉取代舊的cua布爾值OpenAPI 規(guī)范同步更新。其他安全與兼容細節(jié)3.2.0localBrowserLaunchOptions新增cdpHeaders支持通過 CDP URL 連接已有瀏覽器時攜帶自定義 HTTP 頭clientOptions支持自定義 headers3.5.0新增ignoreDefaultArgs選項可選擇性移除 chrome-launcher 內(nèi)置默認參數(shù)如--disable-extensions2.1.0為 CDP 連接添加 user-agent3.1.0移除自動.env加載dotenv如需.env請顯式加載import dotenv from dotenv; dotenv.config({ path: .env });緩存從客戶端緩存到服務(wù)端緩存緩存一直是 Stagehand 的性能重點2.3.1啟用會話親和session affinity以優(yōu)化緩存3.1.0服務(wù)端緩存server-side caching上線——當env: BROWSERBASE時act()/extract()/observe()結(jié)果自動在服務(wù)端緩存相同輸入的重復(fù)調(diào)用即時返回、不消耗 LLM token默認開啟可用serverCache: false實例級或單次調(diào)用級關(guān)閉3.0.7緩存命中時可跳過 XPath 計算僅緩存開啟時計算 XPathagent 緩存失敗后不刷新等問題被修復(fù)3.6.0ActCache鍵派生對 URL 查詢參數(shù)排序后再哈?！Z義等價但參數(shù)順序不同的 URL如?utm_sourceemailid42vs?id42utm_sourceemail現(xiàn)在可以命中緩存同時保留 fragment 與重復(fù)鍵。模型與 Provider 支持矩陣CHANGELOG 記錄了持續(xù)的模型與 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原生結(jié)構(gòu)化輸出、adaptive thinking 含新的 xhigh effort、內(nèi)置服務(wù)端 refusal 回退到 claude-opus-4-8、google/gemini-3.5-flash、Gemini 3 flash/pro 等配置維度3.7.0 允許modelName: auto構(gòu)造函數(shù)級與單原語覆蓋ModelConfig支持自定義headersopenaiEndpointFormat: chat讓 OpenAI 兼容模型可選 Chat Completions API3.6.0 移除默認 temperature 設(shè)置避免不支持 temperature 的推理模型產(chǎn)生 provider 警告?？捎^測性Metrics、Logging 與 Verifier2.0.0新增stagehand.metricstoken 用量與logInferenceToFile記錄完整調(diào)用/響應(yīng)歷史pino 日志自定義錯誤類disablePino標志3.0.3metrics 暴露 reasoning 與 cached input tokens3.3.0API-backed 會話的agent.execute()用量計入stagehand.metrics支持 Browserbase verified session 設(shè)置3.6.0新增rubric-based verifier 引擎標準化公開 rubric 輸出與有界的失敗步驟解析與 verifier trajectory / rubric / evaluation-result 類型verifier 證據(jù)可從 agent evidence 回調(diào)捕獲用于離線評分見packages/evals/framework下的verifierGate.ts、verifierAdapter.ts、adHocRubric.ts3.2.0BROWSERBASE_FLOW_LOGS1啟用 FlowLogger。多頁與復(fù)雜 DOMIframe、Shadow DOM 與 OOPIF1.9.0on(popup)監(jiān)聽傳入 Page 對象以支持多頁2.4.3實驗性支持 Shadow DOMopen closed支持 iframe 內(nèi)滾動2.4.xiframe 移出 experimental修復(fù)嵌套 iframe XPath3.0.xpage.addInitScript()/context.addInitScript()并修復(fù) init scripts 在 OOPIF、SPIF、popup 頁面上的注入問題locator.count()/.nth()支持 Shadow DOM 與 XPath 謂詞3.1.0修復(fù) Shadow DOM 相關(guān).count()與 XPath 謂詞問題3.6.0修復(fù) Stagehand 生成的 shadow-root XPath確定性動作可定位 Web Component 內(nèi)部元素3.4.0修復(fù) OOPIF 頁面的 frame registry 處理。環(huán)境變量速查結(jié)合 CHANGELOG 與源碼當前值得關(guān)注的環(huán)境變量包括環(huán)境變量用途引入版本STAGEHAND_EXTENSION_ARCHIVE_PATH覆蓋擴展 zip 路徑針對內(nèi)聯(lián)打包器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 移除內(nèi)部 Playwright 依賴兼容 Playwright / Puppeteer / Patchrightact接受指令字符串而非動作字符串observeResult更名為actionModelConfiguration類型固化官方遷移指南見 packages/docs/v3/migrations/v2.mdx。v3 → v4圍繞 v4 協(xié)議重建TypeScript / Python / Go 三語言同步遷移指南見 packages/docs/v4/migrations/v3.mdx。v4 內(nèi)部遷移若從 Playwright 遷移到 Stagehand可參考 packages/docs/v4/migrations/playwright.mdx從 browser-use 遷移見 packages/docs/v4/migrations/browser-use.mdx。深入源碼的索引想要進一步驗證本文所述特性可以直接閱讀以下文件協(xié)議定義與類型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/領(lǐng)域策略測試packages/sdk-ts/tests/integration/contextDomainPolicy.test.ts變更日志原文CHANGELOG.md總結(jié)從 CHANGELOG 可以看到 Stagehand 的清晰演進主線封裝 Playwright → 原生 agent 循環(huán) → CUA / Hybrid 多模式 → 協(xié)議優(yōu)先的多語言 monorepo。對于開發(fā)者而言v4 意味著統(tǒng)一的行為契約與跨語言一致性而緩存、域名策略、verifier 等能力則讓瀏覽器 Agent 在生產(chǎn)環(huán)境中更可控、更可觀測。升級時建議優(yōu)先參考對應(yīng)版本的遷移指南并結(jié)合本文梳理的模型、緩存與環(huán)境變量差異進行回歸驗證?！久赓M下載鏈接】stagehandThe SDK For Browser Agents項目地址: https://gitcode.com/GitHub_Trending/stag/stagehand創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考