企业官网建设流程全解析

Stagehand 页面改版后 act 动作失效如何用 selfHeal 与 observe 重放恢复

【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand

当一个页面的 UI 改版后，你之前记录下来的Action里保存的 selector 可能不再能在页面上解析，把该Action传给act()做重放就会失败。Stagehand v4 文档针对这种情况给出两条恢复路径：在实例上开启selfHeal，让重放失败时自动重新推理并重试一次；或者用observe()在新页面上重新发现候选动作，校验method和selector后，把新的Action再交给act()做确定性重放。两条路径可以叠加使用。本文以 TypeScript SDK 为例，Python 和 Go 的对应写法见 act 文档和 observe 文档。

前提：你的自动化在重放 Action 而不是传指令

恢复动作失效有一个适用前提：你的脚本把observe()返回的Action对象传给act()做重放，而不是每次传自然语言指令。文档明确了两种输入的差异（见 act 文档）：

• 传字符串指令：act()会跑一次模型推理来定位目标；
• 传Action：直接按记录的 selector 重放，不做任何推理。

实例本身按 Stagehand reference 的常规方式创建：Stagehand.create()是唯一的实例构建方式，browser句柄来自localBrowser.launch()、localBrowser.connect()或browserbase.launch()。

开启 selfHeal：重放失败时自动重推一次

selfHeal是Stagehand.create()的一个可选布尔参数。reference 文档对它的定义是：控制 Stagehand 在记录的 selector 不再解析时，是否重新推理并重试该动作。

import { Stagehand, localBrowser } from "@browserbasehq/stagehand"; const browser = await localBrowser.launch(); const stagehand = await Stagehand.create({ browser, selfHeal: true });

文档给出关于重放与selfHeal的关键行为说明（act 文档）：

重放一个Action会跳过模型推理、页面快照和 DOM-settle 等待，并且不查询服务端缓存。如果记录的 selector 不再解析且selfHeal开启，Stagehand 会重新推理该动作并重试一次。

也就是说，页面没变时重放是零推理的；页面改版后 selector 失效时，selfHeal给你一次重新推理的自动恢复机会，但它只重试一次，不是无限重试。

另外，Playwright 迁移文档在讨论"selector 频繁变动"的场景（营销页、第三方结算页、A/B 测试的 UI）时，给出的建议就是改用act()并打开selfHeal，让记录的 action 在 selector 失效时重新推理。这正是页面改版导致动作失效的典型场景。

用 observe 重新发现并校验动作

observe()会扫描当前页面、返回结构化的动作列表，每个Action带description、method、arguments、selector四个字段（见 observe 文档的返回值示例，文档示例输出）：

[ { description: 'Learn more button', method: 'click', arguments: [], selector: 'xpath=/html[1]/body[1]/shadow-demo[1]//div[1]/button[1]' } ]

改版后恢复的主路径是：先用observe()描述你要做的动作，确认返回的method符合预期，再把第一个候选动作直接回传给act()重放（act 文档的 best practice 写法）：

const { data: actions } = await stagehand.observe("click the login button"); const [action] = actions; if (action?.method === "click") { // No inference: Stagehand replays the observed action await stagehand.act(action); }

如果一次要恢复多个步骤（比如整个表单被改版），observe 文档的 plan-then-execute 模式适用：只调用一次observe()发现全部字段，然后逐个把Action回传给act()，每次重放都不再触发推理：

const { data: formFields } = await stagehand.observe("find all form input fields"); for (const field of formFields) { // No LLM call: Stagehand replays the observed action await stagehand.act(field); }

回传前先校验method是否落在你接受的范围内，observe 文档在"Wrong method suggested"排查项里给出了这个模式：

const { data: actions } = await stagehand.observe("find the submit button"); const [action] = actions; // Validate method before acting const validMethods = ["click", "fill", "type", "press"]; if (action && validMethods.includes(action.method || "")) { await stagehand.act(action); } else { console.warn(`Unexpected method: ${action?.method}`); }

验证恢复结果

act()的返回值分两部分：data装动作结果，metadata带 action ID 和缓存状态。act 文档给出的成功返回示例（文档示例输出）：

{ data: { success: true, message: 'Action [click] performed successfully on selector: xpath=/html[1]/body[1]/div[1]/span[1]', actionDescription: 'Favorite Colour', actions: [ /* 实际执行的动作与 selector */ ] }, metadata: { actionId: 'act_01HZY...', cache: { status: 'MISS', missReason: 'not_found' } } }

判断恢复是否成功，看两点：data.success是否为true，message里记录的 selector 是否指向了改版后页面上的真实目标。metadata.cache.status取值为"HIT"、"MISS"或"DISABLED"；注意重放Action本身不查询服务端缓存，所以缓存命中与否不能用来判断重放成败。

如果恢复后仍有动作超时或找不到元素，act 文档的"Action failed or timed out"排查项给出的处理顺序：

• 确保页面已完全加载（示例用page.waitForLoadState("domcontentloaded")）；
• 目标可能在 iframe 里，Stagehand 会自动遍历 iframe，但传一个 target locator 可以帮助；
• 增大act()的timeout；
• 先用observe()确认元素确实存在，再换更具体的指令重试；
• 页面在加载后仍持续变动时，在构造函数上调大domSettleTimeoutMs。

如果observe()返回空列表，按 observe 文档的"No elements found"排查项处理：确认元素在页面上、用更具体的指令（例如 "find the blue submit button" 而不是 "find button"）、调用前确认页面已加载、把 Stagehand 配置的日志级别设为debug检查检测行为。

边界与限制

• 重放Action跳过模型推理、页面快照和 DOM-settle 等待，也不查询服务端缓存——页面未改版时这是优势，改版后 selector 失效则完全依赖selfHeal或手动observe()恢复。
• selfHeal是构造时的实例级选项，文档没有给出按单次act()调用覆盖它的写法；它只在 selector 失效时重推并重试一次。
• locator/ignoreLocators目标只影响指令式act()调用；传Action时 Stagehand 直接重放该动作记录的 selector，这些目标参数不生效。
• Stagehand v4 通过 CDP 直接驱动浏览器，没有 Puppeteer/Playwright 页面互操作，act()默认作用于活动页面，多页面场景通过page选项指定。

下一步

• act 完整文档：返回值结构、缓存、变量与三种语言的完整示例。
• observe 完整文档：定位范围（locator、ignoreLocators）、带变量的先校验后执行模式。
• Stagehand reference：Stagehand.create()全部参数，包括selfHeal、domSettleTimeoutMs、cache、logging。
• 缓存指南：恢复稳定后，可用服务端缓存减少重复调用的模型开销。

【免费下载链接】stagehandThe SDK For Browser Agents项目地址: https://gitcode.com/GitHub_Trending/stag/stagehand