把 browser-use Python…

当需要将 browser-use（Python）的 Agent 脚本转换/重写为 Stagehand v3（TypeScript）并部署到 Browserbase 时，用一套有判断力的重构流程替代机械转译。

适用场景

解决思路

1. 先获取源码：拿到 browser-use 脚本文件；若用户只描述脚本则索要文件。默认目标为 TypeScript Stagehand on Browserbase，除非用户另有说明。
2. 先做范围判断：若源码是 browser-use 作为 MCP server 运行（uvx browser-use --mcp、mcpServers 配置），则没有 Stagehand 等价物，标记为超出范围，不要臆造；若 browser-use 调用嵌在更大应用中（类/工具包装、web 路由、队列任务），只转换 browser-use 部分并保留周边应用胶水代码。
3. 检测 browser-use 变体：区分 legacy（0.12 之前）、stable 与 Rust beta（仅当 import 来自 browser_use.beta 时才算 beta；顶层 from browser_use import Agent, ChatBrowserUse 在 0.13.x 仍属 stable，ChatBrowserUse 本身不是 beta 标志）。所有变体翻译方式相同，不确定时按 stable 映射处理，翻译前先规范化 legacy 名称，并说明检测到的变体。
4. 盘点脚本：在写任何 TypeScript 前提取结构化清单——Task(s)（task= 字符串，拆分为有序步骤）、Model（Chat* provider + model id）、Browser 配置（本地 vs cdp_url/Browserbase、headless、代理、user_data_dir/storage_state）、结构化输出（output_model_schema Pydantic 模型）、Secrets（sensitive_data、环境变量、登录流程）、Guardrails（allowed_domains、max_steps）、自定义 actions（@tools.action / Controller 函数，判断是确定性副作用还是 agent 能力）、Setup（initial_actions、次级模型 page_extraction_llm、planner_llm）。
5. 逐步决定确定性级别：已知 URL 导航 → page.goto(url)（不用 AI）；页面操作 → act("…")，若重复则先 observe() 一次再重放 act(action)（不再调用 LLM）；读取数据 → extract("…", zodSchema)；真正开放式 → 保留 stagehand.agent().execute(...)（用 maxSteps/systemPrompt 收紧）。流程已知时默认分解，仅在未知时保留 agent()；首次 lift-and-shift 可接受忠实的 agent() 翻译，但要说明并给出优化路径。
6. 写代码前先核对 API：对照已安装包（node_modules/@browserbasehq/stagehand 类型）或 https://docs.stagehand.dev/v3 确认即将使用的签名；若安装版本与快照不同，以安装版本为准。
7. 产出可运行的 Stagehand v3 TypeScript：import { Stagehand } from "@browserbasehq/stagehand"；提取时 import { z } from "zod"；用 const page = stagehand.context.pages()[0] 获取页面；AI 方法调用在实例上（stagehand.act/extract/observe），绝不用 page.act(...)；模型写成 "provider/model" 字符串；默认 env: "BROWSERBASE"，env: "LOCAL" 作为开发选项；密钥通过 variables 和 process.env 传入，绝不硬编码；开头 await stagehand.init()，finally 中 await stagehand.close()。
8. 包含项目脚手架：package.json 使用 type: module、start 脚本 tsx index.ts，依赖 @browserbasehq/stagehand ^3.0.0、dotenv ^16.0.0、zod ^3.25.0，devDependencies tsx ^4.0.0、typescript ^5.0.0；.env 含 BROWSERBASE_API_KEY、BROWSERBASE_PROJECT_ID 及与模型匹配的 provider key（如 ANTHROPIC_API_KEY）。仅当自定义 browser-use action 映射为 agent tool 时才加 "ai": "^5.0.0"（Vercel AI SDK），且必须 pin v5 而非 v4——Stagehand 3.6.x 捆绑 ai v5，tool 的 schema 字段是 inputSchema，v4 的 tool() 助手会输出 parameters 导致类型检查失败；若无法控制 hoisted ai 版本，跳过 tool() 助手，直接传普通对象 { description, inputSchema: zodSchema, execute }。
9. 写迁移总结：说明检测到的变体与每步的确定性选择（哪些变成确定性/AI/agent）及理由；列出需要人工审查的项（丢失的 allowed_domains guardrails、自定义 action 逻辑、次级模型意图、含糊的 task 字符串）；给出推荐下一步（用 Browserbase Context 复用认证、生产环境缓存，或流程不透明时走 trace-assisted 路径）。
10. 仅在必要时提供 trace-assisted 路径：若源码是一个大型不透明 agent(task=…)、不稳定、或重写无法自信映射，则提议该工作流（在 Browserbase 上运行原脚本、拉取 sessions.logs.list、根据观察到的行为重写）；未经用户同意不要运行任何东西。
11. 完成前跑验证清单：AI 方法在实例上而非 page；页面经 stagehand.context.pages()[0] 获取；模型是 "provider/model" 字符串且对应 provider key 在 .env；extract 用 zod schema 且 zod 在依赖中；密钥用 variables + process.env 无硬编码；有 init()/close() 且 close() 在 finally；每个 browser-use 步骤都被有意放置在确定性谱系上；迁移总结列出确定性选择与需人工审查项。
12. 避免常见错误：不要从旧博客复制 v2 语法（page.act()、stagehand.page、modelName/modelClientOptions、enableCaching），用 v3；不要把每步都翻译成 act()（导航用 page.goto，可重复步骤用 observe→act 缓存，不要每步都花 LLM 调用）；不要全部默认 agent()（那只是在新框架里复现 browser-use 的非确定性，已知流程要分解）；不要静默丢弃 allowed_domains（Stagehand 无域名防火墙，标记待审查）；不要臆造 Browserbase/Stagehand 选项，不确定的字段查 https://docs.stagehand.dev/v3 或 https://docs.browserbase.com。

适用边界 · 注意事项

• 源码是 browser-use 作为 MCP server 运行（uvx browser-use --mcp、mcpServers 配置）时——没有 Stagehand 等价物，超出范围。
• 安装的 Stagehand 主版本不是 3 时——本技能仅作概念参考，所有签名须按实时文档处理。
• 用户只想做机械转译、拒绝按确定性谱系重构时——本流程的核心价值是有判断力的重构而非逐行翻译。