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），仅供参考