浏览器智能体实战 · 第 3 章 Stagehand 实战

浏览器智能体实战 · 第 3 章 Stagehand 实战

章节摘要：Stagehand（Browserbase 出品，约 2.6 万 stars，2026-10-16 社区口径；MIT 许可；TypeScript 为主、附 Python 绑定；当前 v3.7.3）代表与第 2 章相反的哲学：代码优先、Agent 兜底——能写代码的步骤就写代码，Agent 只接住代码接不住的部分。3.1 节讲理念：纯代码、纯 Agent、混合三种模式的确定性、成本、可测性对比，「Agent 调用的真实成本」的算术，以及何时该用 Agent 的判定树。3.2 节讲三原语编程：act、extract、observe 的 API 实战（指令书写原则、zod 数据模式、候选清单消费、错误处理与重试），代码统一为可直接语法检查的 ES2020 模块形态。3.3 节讲渐进式固化：从全 act 起步，经 observe 检视、结果缓存，逐步换成 Playwright 原生调用的四步法——observe 的产物如何变成缓存，缓存如何失效回退，固化的收益怎么度量。本章与第 2 章互为镜像：一个从自主往回收，一个从代码往外放。

学习目标

• 用确定性、成本、可测性三个维度对比纯代码、纯 Agent、混合三种模式。
• 算清 Agent 调用的真实成本（每步一次模型调用的乘法关系）。
• 熟练使用 act、extract、observe 的 API，写出符合规范的指令与数据模式。
• 为 act 实现带退避的重试与候选为空的降级处理。
• 执行渐进式固化四步法，把 observe 结果变成可失效、可回退的缓存。
• 说出哪些步骤不该固化，避免把适应性优化掉。

核心概念速览

代码优先的判定树（本章核心决策图）

  这个步骤的页面结构稳定吗？
   ├── 稳定 ──────────────▶ 直接写 Playwright 代码
   │                        （零模型调用，完全确定）
   └── 不稳定，语义清楚吗？
        ├── 清楚 ──────────▶ 用 act 指令（语义锚稳）
        │                    （一次模型调用）
        └── 完全动态 ───────▶ Agent 循环兜底
                             （每步模型调用，概率路径）

  运行一段时间后：高频路径沿树向上固化（3.3 节）
​

一句话金句：能写代码的地方就写代码，Agent 只接住代码接不住的那部分。

子章节导航

• 第 3.1 节《代码优先理念》：三种模式的四维对比、Agent 成本算术、判定树与「兜底」的确切含义。
• 第 3.2 节《三原语编程》：初始化、act 指令三原则、extract 的 zod 模式、observe 消费、错误处理与重试。
• 第 3.3 节《渐进式固化》：固化四步法、observe 结果变缓存、失效回退、收益度量与不固化清单。

按序读：3.1 立哲学，3.2 给武器，3.3 串成工作流。3.2 可当 API 速查反复回看。

子章节之间的逻辑关系

┌────────────────┐   哲学落到 API    ┌────────────────┐   API 串成流程   ┌────────────────┐
│ 3.1 代码优先    │ ──────────────▶ │ 3.2 三原语编程   │ ─────────────▶ │ 3.3 渐进式固化  │
│ 判定树+成本算术  │                 │ act/extract/     │                │ act→observe→   │
│                │                 │ observe+错误处理  │                │ 缓存→代码      │
└───────┬────────┘                 └───────┬────────┘                 └───────┬────────┘
        │ 产物：模式选择观                   │ 产物：可运行三原语代码           │ 产物：固化工作流
        └──────────────────────────────────┴───────────────┬───────────────┘
                                                           ▼
                                      第 4 章 结构化快照（换一种页面表示，验证思路不变）
​

前置知识与后续延伸

• 前置：第 1 章全部（三原语语义与靶场走查是本章的直接前置）；第 0.2 节 Node 环境与 Stagehand 安装。
• 延伸阅读：Stagehand 官方文档与示例（写法以官方为准）；《深入理解 AI Agent》第 9 章——从原理侧看「代码与模型分工」这个工程问题的理论基础。
• 后续：第 6 章为固化后的代码路径与保留的 Agent 路径分别设计验证；第 7 章处理 Browserbase 云端会话与本地会话的切换；第 11 章把固化覆盖率当生产指标。

合规声明：本节内容仅用于你有权访问的站点与授权自动化场景；请遵守目标站点的服务条款，自动化访问的速率与方式应可被站点方接受。