项目定位与核心能力

Stagehand 是由 Browserbase 维护的 AI 驱动浏览器自动化框架，仓库采用 monorepo 形式管理多个相关包。除 TypeScript 主实现外，Python 版本在独立的 stagehand-python 仓库中维护，根目录 README 明确提示用户可前往该地址获取 资料来源：README.md:1-30。

仓库核心面向两类使用者：其一为希望通过 LLM 驱动浏览器完成自动化任务的应用开发者，其二为希望将浏览器作为工具暴露给大型语言模型或智能体（Agent）的工具构建者。packages/cli/guides/anthropic-managed-agents/README.md 展示了如何把 browse CLI 接入 Anthropic Managed Agents，实现 UI 测试、表单填写与开放网络导航等场景 资料来源：packages/cli/guides/anthropic-managed-agents/README.md:1-30。

仓库结构与多包组织

仓库根目录使用 pnpm workspaces 搭配 Turborepo 进行多包管理。package.json 声明了 pnpm 9.15.0 工具链与多项安全相关的 overrides（如 axios、lodash、jws、ws 等固定到无漏洞版本），并要求 Node ^20.19.0 || >=22.12.0 资料来源：package.json:1-60。

graph TB
    Root[Stagehand Monorepo<br/>pnpm + Turborepo] --> Core["packages/core<br/>@browserbasehq/stagehand"]
    Root --> CLI["packages/cli<br/>browse CLI"]
    Root --> Srv3["packages/server-v3<br/>Fastify API"]
    Root --> Srv4["packages/server-v4<br/>Fastify + OpenAPI"]

    CLI --> Driver["Driver Commands<br/>page-info / click / fill ..."]
    CLI --> FnInit["functions init<br/>initFunctionsProject"]
    CLI --> Sugg["command-suggestions<br/>aliasSuggestions"]
    Srv3 --> Env["env.ts<br/>BB_ENV / NODE_ENV"]

turbo.json 为不同包定义了独立的 build:esm、build:cjs、build:sea、gen:openapi 等任务，并通过 dependsOn: ["^build"] 确保依赖包按拓扑顺序构建 资料来源：turbo.json:1-80。其中 server-v3 任务还会产出 openapi.v3.yaml，而 server-v4 单独维护 openapi.v4.yaml 资料来源：turbo.json:20-40。

核心包与构建流程

核心库 `@browserbasehq/stagehand`

packages/core 是 Stagehand 的运行时核心。它通过 build:esm 与 build:cjs 双格式输出，在构建前会先执行 gen-version 与 build-dom-scripts 任务，对应 lib/v3/dom/build/ 与 lib/dom/build/ 目录的预处理 资料来源：turbo.json:50-90。packages/core/README.md 给出了克隆、安装、构建、运行示例脚本（./examples/example.ts）的标准流程，并说明 Stagehand 在同时配置 LLM 提供方 API Key 与 Browserbase 凭证时表现最佳 资料来源：packages/core/README.md:1-40。

`browse` 命令行工具

packages/cli 提供名为 browse 的 CLI 工具。它采用"轻量级会话守护进程"架构：首次命令启动守护进程，后续命令复用同一浏览器，使 cookie、标签页和 snapshot 引用在多次调用间持续存在；用户也可通过 --session <name> 或 BROWSE_SESSION 环境变量运行多个隔离浏览器 资料来源：packages/cli/README.md:1-40。

驱动层使用统一的处理器模式。例如 page-info.ts 中的 pageInfoHandlers 通过 Zod schema 校验参数，并支持 box、checked、html、markdown、text、title、url、value、visible 等多种查询类型，对应 get 与 is 两类操作 资料来源：packages/cli/src/lib/driver/commands/page-info.ts:1-40。

Functions 项目脚手架

packages/cli/src/lib/functions/init.ts 暴露 initFunctionsProject 接口，可根据所选包管理器（npm 或 pnpm）生成标准 Functions 项目。它会写入 package.json、.env、.gitignore、index.ts、tsconfig.json，并自动安装 @browserbasehq/sdk-functions、playwright-core 与 TypeScript 相关依赖 资料来源：packages/cli/src/lib/functions/init.ts:1-80。

命令兼容性与服务器运行时

packages/cli/src/lib/command-suggestions.ts 维护了一张别名映射表，把旧版 Commander 时代的命令（如 sessions、projects、goto、navigate）映射到当前 oclif 命令树（如 cloud:sessions:list、cloud:projects:list、open）。容错逻辑限制 token 数量不超过 4、编辑距离不超过 5，避免对未知输入做过于宽松的猜测 资料来源：packages/cli/src/lib/command-suggestions.ts:1-60。

packages/server-v3 是基于 Fastify 5.8.5 的 HTTP 服务器，整合了 fastify-zod-openapi、fastify-metrics、pino 与 pino-pretty，并通过 @t3-oss/env-core 加载 NODE_ENV 与 BB_ENV（取值 local/dev/prod）等运行时配置 资料来源：packages/server-v3/src/lib/env.ts:1-20、资料来源：packages/server-v3/package.json:1-40。

See Also

• 构建系统与 Turborepo 任务
• browse CLI 驱动与命令系统
• Stagehand 核心库与 v3 API

概述与设计目标

Stagehand 是一个面向 LLM 驱动的浏览器自动化框架，其核心 API 与执行原语围绕"可观测、可组合、可在本地与云端复用"三条原则设计。整个仓库以 monorepo 形式组织，包含 packages/core（核心库）、packages/cli（browse 命令行）、packages/server-v3（Fastify 服务器）以及 packages/evals 等子包，由 turbo.json 中定义的构建管线统一编排 资料来源：package.json:9-20 资料来源：turbo.json:1-50。

browse CLI 是 Stagehand 暴露给终端和 LLM 代理的最直接原语层。它通过一个轻量级的 per-session 守护进程来执行命令，首次调用启动守护进程，后续命令复用同一个浏览器，从而在多次调用间保留 Cookie、Tab 和 snapshot 引用 资料来源：packages/cli/README.md:21-33。

页面信息原语（Page Info Primitives）

page-info.ts 集中实现了对当前活动页面的查询操作。pageInfoHandlers 提供 get 与 is 两组命令，覆盖 box（元素中心坐标）、checked（勾选状态）、html、markdown、text、title、url、value（输入值）、visible（可见性）等枚举值 资料来源：packages/cli/src/lib/driver/commands/page-info.ts:7-40。

其执行模式统一为：先通过 manager.activePage() 获取当前页面，再以 manager.resolveSelector() 解析选择器，最后用 Playwright 的 deepLocator() 执行具体动作。例如 markdown 分支会先调用 locator.innerHtml() 获取 HTML，再通过 NodeHtmlMarkdown.translate() 转换为 Markdown，从而为 LLM 提供结构化文本输入 资料来源：packages/cli/src/lib/driver/commands/page-info.ts:25-31。这种"统一调度 + 多后端实现"的模式构成了 Stagehand 的基础执行原语。

函数项目初始化与函数原语

init.ts 中的 initFunctionsProject() 函数用于脚手架一个基于 browse functions 的 TypeScript 函数项目。该函数会校验项目名称、创建目录结构、生成 package.json、.env、.gitignore、示例 index.ts 函数和 tsconfig.json，并通过 runPackageManager() 安装 @browserbasehq/sdk-functions 与 playwright-core 等依赖 资料来源：packages/cli/src/lib/functions/init.ts:34-110。

index.ts 模板内置了一个 defineFunction 示例，演示如何调用 page.extract() 从 Hacker News 抓取标题并返回结构化结果，这代表了"函数即原子能力"的设计——每个函数可独立部署、定向调用，便于在 LLM agent 编排中被组合为更复杂的工作流 资料来源：packages/cli/src/lib/functions/init.ts:1-20。

命令映射与兼容层

为兼容旧版 Commander 时代的命令语法及常见的 LLM 代理猜测，command-suggestions.ts 维护了一张别名映射表 aliasSuggestions，将 sessions、projects、goto 等旧命令映射到 cloud:sessions:list、cloud:projects:list、open 等当前命令树 资料来源：packages/cli/src/lib/command-suggestions.ts:17-31。

匹配算法基于 Levenshtein 距离，使用 fastest-levenshtein 库，并设置 maxSuggestionDistance = 5 与 maxCommandTokens = 4 的安全边界，避免将用户任意输入回显到建议中。safeTokenPattern 进一步保证只接受字母开头的合法 token 资料来源：packages/cli/src/lib/command-suggestions.ts:33-50。

模板与服务器协同

模板系统通过 templates/api.ts 暴露统一的拉取接口，调用 Browserbase 的 https://www.browserbase.com/api/templates 端点，并始终附加 scope=all 以避开 CLI 不适用的 playgroundRunnable 过滤 资料来源：packages/cli/src/lib/templates/api.ts:18-24。

服务器层 server-v3 使用 Fastify 5.x、Playwright 1.55.x、Zod 4.x 等版本作为依赖栈，配合 pino 日志、fastify-metrics 指标与 fastify-zod-openapi OpenAPI 生成，构建出可通过 CLI 调用的 HTTP 端点 资料来源：packages/server-v3/package.json:15-35。

架构总览

flowchart LR
    A[LLM Agent / 用户] -->|browse 命令| B[CLI 入口 oclif]
    B --> C[command-suggestions<br/>别名与纠错]
    B --> D[driver/commands<br/>page-info 等原语]
    D --> E[Session Daemon<br/>Playwright]
    E -->|本地或 Browserbase| F[Chromium 浏览器]
    B --> G[functions/init<br/>脚手架]
    B --> H[templates/api<br/>模板拉取]
    H --> I[Browserbase Templates API]
    E -.HTTP.-> J[server-v3 Fastify]
    J --> K[Playwright + Zod OpenAPI]

社区关注点与已知限制

社区中关于"将 Stagehand 挂载到现有 Playwright 页面以支持视频录制"的高热度讨论（#507）反映出当前 init() 模式下难以直接接管外部 page 上下文。browse CLI 通过守护进程复用浏览器的设计从侧面缓解了这一问题，但若需在自定义 Playwright 套件中嵌入 Stagehand，仍需通过外部 CDP 协议桥接。此外，#1645 指出 AISdkClient 与 Vercel AI SDK v6+ 的 LanguageModelV3 存在类型不兼容，需要在执行原语层进行模型抽象的升级。

参见

• Stagehand 官方文档
• browse CLI README
• core 库 README

1. 概览与仓库角色

Stagehand 是 Browserbase 维护的 AI 浏览器自动化框架，其核心思想是让大语言模型（LLM）解释自然语言指令，并将其映射为浏览器中的实际操作（点击、填写、抓取）。仓库采用 pnpm + Turborepo 的多包结构，主要由三个子包组成：

• @browserbasehq/stagehand：核心 Node.js SDK，提供面向程序员的 API。
• @browserbasehq/stagehand-server-v3：基于 Fastify 的服务器侧实现，暴露 HTTP 接口与 OpenAPI 契约。
• browse CLI：面向 Agent 的命令行工具，提供 click、fill、snapshot、screenshot 等原子操作。

README.md 将 MODEL_API_KEY 与 Browserbase 凭据列为运行示例的必备环境变量，说明 LLM 接入与浏览器运行时是 Stagehand 启动的两大前提。

2. LLM 集成与可扩展性

2.1 构建与依赖基线

package.json 在 engines 中规定 Node ^20.19.0 || >=22.12.0，并通过 pnpm.overrides 集中固定 axios、ws、esbuild、hono、follow-redirects 等关键依赖的版本。这样无论上层使用哪一种 LLM SDK，都能在同一基线下编译运行。资料来源：package.json:engines 资料来源：package.json:pnpm.overrides

2.2 双产物与 DOM 脚本

turbo.json 为 stagehand 包定义了 build:esm 与 build:cjs 任务，且都显式依赖 gen-version 与 build-dom-scripts。这意味着无论用户最终消费 ESM 还是 CJS，浏览器侧脚本都会被先注入产物，从而保证 LLM 推理层与 DOM 注入层的一致性。资料来源：turbo.json:@browserbasehq/stagehand#build:esm 资料来源：turbo.json:@browserbasehq/stagehand#build:cjs

2.3 社区扩展诉求

社区里关于 LLM 替换的讨论非常集中：

• Issue #183 希望把 Ollama 接入，并允许"自带 LLM"。
• Issue #307 期待像 Tongyi、Gemini 等模型也能通过 options 切换。
• Issue #1645 要求 AISdkClient 升级到 Vercel AI SDK 的 LanguageModelV3 类型。

这些讨论都指向同一个事实：核心 SDK 的 LLM 客户端层需要一个稳定的抽象，以便在不修改业务代码的情况下替换底层模型。资料来源：README.md

3. Agent 验证：browse CLI 与 Server-v3

3.1 原子化的 DOM 验证命令

packages/cli/src/lib/driver/commands/page-info.ts 实现了 pageInfoHandlers，提供 get 与 is 两条命令，覆盖以下只读验证：

资料来源：packages/cli/src/lib/driver/commands/page-info.ts:pageInfoHandlers

3.2 提取到验证的函数模板

packages/cli/src/lib/functions/init.ts 中的 initFunctionsProject 会为 browse functions 项目生成模板：写入 package.json（dev 脚本为 browse functions dev index.ts，deploy 脚本为 browse functions publish index.ts）、.env、.gitignore、入口 index.ts 和 tsconfig.json，并按所选的 npm/pnpm 自动安装 @browserbasehq/sdk-functions 与 playwright-core。这意味着 Agent 在完成一次 extract 之后，可以把验证逻辑封装为可部署函数，从而与 LLM 调用解耦。资料来源：packages/cli/src/lib/functions/init.ts:initFunctionsProject

3.3 服务器侧的 OpenAPI 契约

packages/server-v3/src/lib/env.ts 使用 @t3-oss/env-core 与 zod/v4 校验 NODE_ENV 与 BB_ENV，并通过 enum 把 BB_ENV 限制为 local、dev、prod 之一。packages/server-v3/package.json 引入 fastify、fastify-zod-openapi、playwright、fastify-swagger-ui 等依赖，说明 v3 服务器既能托管浏览器执行环境，也能通过 OpenAPI 自动生成供 Agent 调用的契约，从而在 LLM 与验证逻辑之间形成稳定接口。资料来源：packages/server-v3/src/lib/env.ts:env 资料来源：packages/server-v3/package.json:dependencies

3.4 与 Anthropic Managed Agents 的端到端集成

packages/cli/guides/anthropic-managed-agents/README.md 描述了最完整的"LLM → Agent → 浏览器"验证范式：在控制台创建 Environment 并把 browse 设为默认 npm 包，再以 BROWSERBASE_API_KEY 命名环境变量创建凭据库，即可在沙箱内通过 browse click、browse network 等命令驱动浏览器。资料来源：packages/cli/guides/anthropic-managed-agents/README.md

4. 端到端架构

flowchart LR
  A[LLM Provider<br/>OpenAI / Anthropic / Google / Groq / Ollama] --> B[stagehand core<br/>@browserbasehq/stagehand]
  B --> C[browse CLI<br/>@browserbasehq/browse]
  B --> D[stagehand-server-v3<br/>Fastify + OpenAPI]
  C --> E[Agent Validation<br/>Anthropic Managed Agents / 自定义]
  D --> E
  E --> F[Browserbase Cloud<br/>or local Chromium]

社区中 Issue #507 正在推动让 Stagehand 接入既有 Playwright Page 以便在 e2e 测试中获得视频录制；Issue #389 提议让 extract 返回可复用的解析计划，避免多次实例化时重复调用 LLM。两者都验证了一个方向：在 LLM 抽象稳定的前提下，"驱动"与"验证"两侧的能力都应做成可替换模块。资料来源：README.md

5. 小结

• LLM 集成通过 MODEL_API_KEY 与多客户端抽象完成，社区正在推动 Ollama、Vercel AI SDK v3 等扩展。
• browse CLI 与 stagehand-server-v3 共同提供 Agent 验证所需的原子操作和 HTTP 接口。
• initFunctionsProject 让用户快速搭建"提取 → 验证"函数模板。
• Turborepo 任务图与 pnpm overrides 保证 ESM/CJS 双产物的稳定性。

See Also

• README.md
• packages/core/README.md
• packages/cli/README.md
• packages/cli/guides/anthropic-managed-agents/README.md
• packages/cli/src/lib/driver/commands/page-info.ts
• packages/cli/src/lib/functions/init.ts
• packages/server-v3/src/lib/env.ts

1. 概述与目标

Stagehand 仓库的 packages/cli、packages/server-v3 与根级构建系统共同构成了项目的"CLI、Server 栈与部署基础设施"。该层负责三件事：把浏览器自动化能力以 browse 命令的形式暴露给 Agent 与开发者、运行配套的 server 服务以提供会话与上下文能力,以及通过 Turbo 与多产物(ESM / CJS / SEA)构建来支持本地、容器化与单可执行文件等多种部署形态。

browse CLI 是一组面向 Agent 的浏览器工具集合,被官方定义为 browse.sh 的官方客户端,提供滚动、点击、填表、截图等 30+ DOM 命令 资料来源：packages/cli/README.md:9-15。同时,Stagehand 也鼓励"将 Stagehand 与 Playwright 一起使用",因此 CLI 与 server 必须能在本地 Chromium、远程 CDP 连接以及 Browserbase Cloud session 之间无缝切换 资料来源：README.md:67-70。

2. CLI 架构:`browse` 与 Daemon 模式

2.1 长驻守护进程与会话隔离

browse 采用"每会话一个轻量守护进程"的模型:第一次命令启动守护进程,后续命令复用同一浏览器,使得 cookies、标签页与 snapshot 引用在多次调用间保持有效。可以通过 --session <name> 或 BROWSE_SESSION 环境变量同时运行多个相互隔离的浏览器,并用 browse stop 关闭某个会话 资料来源：packages/cli/README.md:28-36。

2.2 浏览器目标与驱动命令

每个驱动命令统一接受目标选择标志(默认本地托管浏览器,设置 BROWSERBASE_API_KEY 后切到远程)。页面信息类命令通过 Zod 进行强类型参数校验,支持 box / checked / html / markdown / text / title / url / value / visible 九种 what 取值,并使用 node-html-markdown 把 HTML 渲染为 Markdown 资料来源：packages/cli/src/lib/driver/commands/page-info.ts:1-37。

2.3 命令建议与兼容性

CLI 内置 command-suggestions.ts 模糊匹配引擎,使用 fastest-levenshtein 计算编辑距离。它将旧的 Commander 时代语法(如 sessions、goto、navigate)映射到当前 oclif 命令树(cloud:sessions:list、open 等),并通过 safeTokenPattern 与 maxCommandTokens 防止用户输入污染建议结果 资料来源：packages/cli/src/lib/command-suggestions.ts:1-44。

3. Server 栈:`server-v3` 与环境配置

packages/server-v3 是面向运行时的 server 包,使用 @t3-oss/env-core + Zod 进行强类型环境变量校验。它在 schema 中定义了 NODE_ENV(development / production / staging / test)与 BB_ENV(local / dev / prod)两个关键维度,并在 runtimeEnv 中给出默认值,任何不合法值都会在启动时直接失败 资料来源：packages/server-v3/src/lib/env.ts:1-19。

server-v3 的工具链包含 tsx、vite、vitest 等现代 TypeScript 工具,并通过 npm 作用域 @browserbasehq/stagehand-server-v3 发布,目录为 packages/server-v3 资料来源：packages/server-v3/package.json:5-21。这与根级 monorepo 的包命名空间保持一致,便于 Turborepo 进行依赖编排。

4. 部署基础设施:构建矩阵与 Functions 脚手架

4.1 多产物构建(ESM / CJS / SEA)

turbo.json 定义了完整的构建任务图。build:esm 与 build:cjs 分别产出 dist/esm/ 与 dist/cjs/,并以 ^build:esm / ^build:cjs 声明依赖,实现 ESM-优先、并行 CJS 的双格式交付 资料来源：turbo.json:1-20。build:sea:esm 与 build:sea:cjs 进一步把代码打包成 Node 单可执行文件(SEA),其输入会排除 dist/sea/** 与 dist/app.mjs,并读取 SEA_BUILD_MODE / SEA_TARGET_PLATFORM / SEA_TARGET_ARCH / SEA_BINARY_NAME 等环境变量 资料来源：turbo.json:21-58。

4.2 Functions 项目脚手架

CLI 提供了 browse functions init 类能力,直接在 packages/cli/src/lib/functions/init.ts 中实现:它会创建带 package.json(包含 dev / deploy 脚本)、.env、.gitignore、入口 index.ts 与 tsconfig.json 的最小可部署项目,并按用户选择的 npm / pnpm 自动安装 @browserbasehq/sdk-functions 与 playwright-core 资料来源：packages/cli/src/lib/functions/init.ts:42-78。脚手架同时初始化 git 仓库,并以 JSON 输出下一步操作清单 资料来源：packages/cli/src/lib/functions/init.ts:79-105。

4.3 依赖收敛与安全基线

根 package.json 集中维护了一组 pnpm.overrides,对 axios、lodash、minimatch、hono、esbuild、tar 等高风险传递依赖强制升级到安全版本,并要求 Node ^20.19.0 || >=22.12.0 资料来源：package.json:1-40。这一基线确保 CLI、server 与 SEA 产物在不同部署环境下行为一致。

5. 与 Agent 生态的集成

CLI 被设计为可被 Anthropic Managed Agents 等托管 Agent 直接调用。集成路径是:在 Browserbase 创建一个 Environment 并把 browse 设为默认 npm 包,同时创建名为 BROWSERBASE_API_KEY 的环境变量型凭据,即可让 Agent 通过 browse click、browse network 等命令观察并控制网页 资料来源：packages/cli/guides/anthropic-managed-agents/README.md:1-25。该指南还指出 CLI 兼容三种浏览器目标——本地 Chromium、任意 CDP 连接、原生 Browserbase Cloud session——这与 CLI 的 --local / 默认行为完全对应 资料来源：packages/cli/guides/anthropic-managed-agents/README.md:13-20。

6. 端到端工作流

下面用 Mermaid 描述一次典型的 CLI 调用生命周期,涵盖命令解析、守护进程、驱动执行、server 校验与多产物分发:

flowchart LR
  A[Agent / Developer] -->|browse click ...| B[oclif CLI 解析]
  B -->|sanitize + suggest| C[Driver Command Handlers]
  C --> D{Session 守护进程}
  D -->|本地| E[Managed Chromium]
  D -->|CDP/Browserbase| F[Cloud Session]
  F --> G[server-v3 校验 BB_ENV / NODE_ENV]
  C --> H[page-info Zod 校验]
  H --> I[HTML → Markdown 渲染]
  I --> J[JSON 结果回传]
  E --> J
  turbo[Turborepo 构建矩阵] -->|esm / cjs / sea| K[发布产物]
  K --> A

7. 常见失败模式与排查

• 会话未释放:忘记调用 browse stop 会让守护进程常驻,可通过 --session 显式隔离 资料来源：packages/cli/README.md:34-36。
• 环境变量缺失:server-v3 启动时若 NODE_ENV / BB_ENV 校验失败,进程会立即退出,需检查部署平台的 env 注入 资料来源：packages/server-v3/src/lib/env.ts:11-18。
• Playwright 视频录制:社区报告(issue #507)显示直接把 Stagehand 嵌入 Playwright 时,需要让它 attach 到既有 page 才能正常录像——这与 CLI 守护进程模型的设计动机一致 资料来源：README.md:67-70。
• 构建产物不一致:build:sea:* 任务会忽略 dist/sea/** 与 dist/app.mjs 作为输入,因此手工修改这些目录不会触发重建 资料来源：turbo.json:21-58。

See Also

• LLM 客户端与模型集成
• Act / Observe / Extract 核心 API
• Browserbase Cloud 与 Contexts 集成

Pitfall Log / 踩坑日志

项目：browserbase/stagehand

摘要：发现 10 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：运行坑 - 来源证据：evals(cua): add a deterministic CUA agent regression task。

1. 运行坑 · 来源证据：evals(cua): add a deterministic CUA agent regression task

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：evals(cua): add a deterministic CUA agent regression task
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/browserbase/stagehand/issues/2188 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安全/权限坑 · 来源证据：Can't use AWS Bedrock custom Llm on BROWSERBASE Env

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Can't use AWS Bedrock custom Llm on BROWSERBASE Env
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/browserbase/stagehand/issues/899 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：Add AgentWeb — free business data API for agents

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add AgentWeb — free business data API for agents
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/browserbase/stagehand/issues/1985 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://www.npmjs.com/package/@browserbasehq/stagehand | README/documentation is current enough for a first validation pass.

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://www.npmjs.com/package/@browserbasehq/stagehand | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://www.npmjs.com/package/@browserbasehq/stagehand | no_demo; severity=medium

7. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://www.npmjs.com/package/@browserbasehq/stagehand | no_demo; severity=medium

8. 安全/权限坑 · 来源证据：Add x402 agent payments: let AI agents pay per browser session autonomously (USDC, no shared credit pools)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add x402 agent payments: let AI agents pay per browser session autonomously (USDC, no shared credit pools)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/browserbase/stagehand/issues/1950 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

9. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://www.npmjs.com/package/@browserbasehq/stagehand | issue_or_pr_quality=unknown

10. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://www.npmjs.com/package/@browserbasehq/stagehand | release_recency=unknown