Skyvern 浏览器自动化快速上手从工具分类到多步工作流的实战模式【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern导读本文是 SkyvernAI 驱动的浏览器工作流自动化引擎的快速起步实战指南围绕官方技能文档 quick-start-patterns.md 展开。文章按先分类、再选工具、后执行的思路系统覆盖快速验证、结构化提取、已知/未知目标的单动作操作、同页多步交互、一次性自主试验、多页可复用工作流以及安全登录、浏览器调试、脚本编写等高频模式。读完你不仅能根据任务形态快速匹配正确的 MCP 工具或 CLI 命令还能直接用 Python SDK 与完整的工作流 JSON 定义落地一个真实的多步表单自动化。一、先分类再动手六类任务与工具映射在开始任何自动化之前第一步永远是判断任务属于哪一类。Skyvern 把浏览器自动化任务归纳为六种分类每种对应不同的工具、成本和可靠性特征分类典型信号工具成本特征适用说明快速检查是/否用户是否已登录skyvern_validate1 次 LLM 截图轻量验证最多 2 步返回布尔值是成本最低的 AI 选项快速提取结构化数据提取所有价格skyvern_extract1 次 LLM 截图专用提取 LLM schema 校验 缓存单动作已知目标点击 #submitskyvern_click/skyvern_type0 次 LLM确定性 Playwright 操作最快且无 AI 参与单动作未知目标点击登录按钮skyvern_act23 次 LLM无截图基于精简可访问性树推理视觉复杂目标建议用混合模式同页多步填写表单并提交skyvern_observeskyvern_execute或act/原语链23 次 LLM 或 0 次标签清晰用act已知选择器直接用 click/type/select多页/可复用自动化走一遍多页向导、每周自动化skyvern_workflow_createskyvern_workflow_runN 次 LLM 截图每个步骤一个 block带视觉推理、验证与可复用运行历史与之对应的 CLI 命令则通过skyvern browser subcommand暴露validate、extract、click、type、select、act、run-task、workflow create/run/status。完整的 CLI 与 MCP 工具映射表参见 cli-parity.md全部工具按结果分类的清单参见 tool-map.md。核心决策规则提示中已含选择器/id/XPath 时用浏览器原语而非act只想要是/否答案时用validate而非extract或act同页且标签清晰用act或原语链试一次看看用run-task跨页且要可复用/可调度/要搭建起来的用workflow create绝不手动输入密码一律用已保存凭据配合skyvern browser login。二、快速检查与快速提取最轻量的两种 AI 操作2.1 快速检查是/否——skyvern_validate对页面做布尔断言是成本最低的 AI 用法适合登录态确认、提交成功校验等场景skyvern_validate(promptIs the user logged in?)实现上skyvern_validate走的是轻量验证链路最多 2 步返回布尔结果。在 CLI 中对应skyvern browser validate --prompt Is the user logged in? Look for a dashboard or avatar.2.2 快速提取结构化数据——skyvern_extract需要把当前页面状态转成结构化数据时使用skyvern_extract可选的 JSON Schema 会强制输出结构skyvern_extract(promptExtract all prices, schema{type:object,properties:{...}})从源码实现看browser.pyskyvern_extract会在执行前用parse_extract_schema校验传入的 schema非法 schema 会被GuardError拦截并返回INVALID_INPUT错误随后通过专用提取 LLM 完成抽取并默认返回完整提取结果可通过verbositysummary选择精简响应。CLI 等价命令含完整 schema 示例skyvern browser extract \ --prompt Extract all product names and prices \ --schema {type:object,properties:{items:{type:array,items:{type:object,properties:{name:{type:string},price:{type:string}}}}}}提示它比截图 人工读图更可靠因为 Skyvern 的 LLM 直接理解页面语义更复杂的 schema 设计模式可参考 schemas.md。三、单动作操作已知目标与未知目标3.1 已知目标确定性原语0 次 LLM 调用当提示中已经包含选择器或精确目标时使用确定性 Playwright 原语速度快且结果可预期skyvern_click(selector#submit) # 点击 skyvern_type(selector#email, textuserco.com) # 输入CLI 对应三种定位模式# IntentAI 找元素 skyvern browser select --value US --intent the country dropdown # SelectorCSS/XPath确定性 skyvern browser click --selector #submit-btn skyvern browser type --text userco.com --selector #email # Hybridselector 缩小范围AI 确认三种模式各有取舍Intent用 AI 定位元素Selector完全确定性、无 AIHybrid选择器 意图既能靠选择器锁定元素、又让 AI 确认语义是生产脚本的推荐模式。详见 precision-actions.md。3.2 未知目标自然语言动作——skyvern_act不知道精确选择器时用自然语言描述动作skyvern_act(promptClick the Sign In button)CLI 等价skyvern browser act --prompt Click the Sign In button skyvern browser act --prompt Close the cookie banner, then click Sign In需要注意act的 LLM 推理过程不包含截图依赖精简的可访问性树适合标签清晰的元素对视觉复杂目标应改用混合模式selector intent或 MCP 的 observeexecute。误点击时的排查手段见 common-failures.md 中的失败模式目录。四、同页多步交互observe execute 与引用生命周期同页多步比如填完表单再提交是 MCP 场景下的高频需求标准流程是skyvern_observe()返回页面元素引用e0、e1、……由你的 LLM 决定要操作哪些引用用skyvern_execute(...)批量执行这些引用对应的动作skyvern_execute( steps[ {tool: click, params: {ref: e0}}, {tool: type, params: {ref: e1, text: hello}}, ] )4.1 引用refs的生命周期stdio 与 HTTP 的差异stdio 传输refs 会跨调用持续有效直到下一次observe、导航或页面/文档上下文发生变化。因此可以观察 → 决策 → 分批执行循环推进。托管无状态 HTTP前序调用返回的 refs 无法在后续调用中解析应优先使用selector或intent参数。即便在单次skyvern_execute批内也只有在调用前就能确定引用的前提下才可使用 refs——内联 observe 返回的 refs 不能在批内再做适应性选择。CLI 本身不直接暴露 observe/execute 这对组合同页多步在 CLI 侧推荐用act标签清晰时或 click/type/select/wait 原语链。4.2 会话是命令之间的粘合剂所有浏览器命令都需要一个会话且会话状态在命令之间保持# 云会话默认适合公网 URL skyvern browser session create --timeout 30 # 本地会话localhost 或自托管 skyvern browser session create --local --timeout 30 # 通过 CDP 连接现有浏览器 skyvern browser session connect --cdp ws://localhost:9222session create之后后续命令自动挂载可用--session pbs_...覆盖结束后执行skyvern browser session close。更完整的会话复用/新鲜度决策见 sessions.md。五、一次性自主试验skyvern_run_task当用户只是想试一次看能否跑通、结果是可丢弃的探索性试验时使用skyvern_run_taskskyvern_run_task(promptTry the checkout flow once and tell me whether it succeeds)CLI 对应skyvern browser run-task \ --url https://example.com \ --prompt Check whether the checkout flow works end to end and extract the confirmation numberrun-task是一次性的自主代理式探索成本更高不要用它来做周期性或多页的生产自动化。判断标准详见 engines.md任务跨页、或用户提到 set up / automate / reusable / repeat / schedule就构建 workflow只有现在就想要一次性结果、不值得保存时才用run-task。它特别适合在投入构建 workflow 之前先验证可行性。六、复杂多步自动化工作流三件套跨页、可复用、可调度、需要块级可观测性与重跑能力的任务应构建工作流。MCP 侧是标准三连skyvern_workflow_create( definition{title:Checkout,workflow_definition:{blocks:[ {block_type:navigation,label:shipping,navigation_goal:Fill shipping info}, {block_type:navigation,label:payment,navigation_goal:Select payment and submit}, {block_type:extraction,label:confirm,data_extraction_goal:Extract order number} ]}}, formatjson ) - skyvern_workflow_run(workflow_idwpid_...) - skyvern_workflow_status(run_idwr_...)CLI 等价链路skyvern workflow create --definition checkout-workflow.yaml # 创建 skyvern workflow run --id wpid_123 --wait # 运行并等待 skyvern workflow status --run-id wr_789 # 查询状态 skyvern workflow list --search invoice # 检索 skyvern block schema --type navigation # 查看块类型 schema skyvern block validate --block-json block.json # 创建前校验6.1 块类型速查工作流由块block组成每个块负责一个步骤。最常用的几类完整清单见 block-types.mdnavigation核心块用自然语言描述页面级动作接受 URL navigation_goalextraction把可见页面状态转成结构化输出配data_extraction_goal与data_schemalogin凭据式认证流与credential_id工作流参数配合可用complete_criterion确认登录成功wait处理异步页面过渡如 spinner 消失、成功横幅出现、表格行数非零conditional处理已知分支状态如可选的 MFA 弹窗条件要窄且可测试for_loop / while_loop前者遍历已有列表提取行、上传文件、用户提供的 URL后者循环直到条件变化如分页的 Next 按钮可用、轮询到完成尽量用 Jinja2 条件表达来自结构化输出的布尔值提示词条件仅在必须依赖视觉状态时使用。工作流运行状态生命周期为created - queued - running - completed | failed | canceled | terminated | timed_out详细状态解读见 status-lifecycle.md。七、常用模式登录、调试与可行性验证7.1 安全登录绝不通过type或act手动输入密码始终使用已保存凭据# MCP 流程 skyvern_credential_list # 1. 找到凭据 skyvern_browser_session_create # 2. 启动会话 skyvern_navigate(urlhttps://login.example.com) # 3. 进入登录页 skyvern_login(credential_idcred_...) # 4. AI 完成整个登录流程 skyvern_screenshot # 5. 截图验证CLI 等价skyvern credentials add --name my-login --type password --username userco.com skyvern credential list skyvern browser session create skyvern browser navigate --url https://login.example.com skyvern browser login --url https://login.example.com --credential-id cred_123 skyvern browser validate --prompt Is the user logged in? skyvern browser screenshot凭据类型支持password、credit_card、secret并支持 bitwarden、1password、azure_vault 等外部提供商详见 credentials.md。登录后务必用具体条件做验证用户头像可见、登出按钮存在、仪表盘标题出现再继续后续步骤。7.2 调试浏览器问题skyvern_browser_session_create - skyvern_navigate - perform actions - skyvern_console_messages(levelerror) # 查看 JS 报错 skyvern_network_requests # 查看 API 调用CLI 侧可组合screenshot视觉状态、evaluate --expression document.titleJS 状态、evaluate --expression document.querySelectorAll(table tr).lengthDOM 计数快速定位。常见问题速查表问题修复动作点错了元素给提示补充上下文改用混合模式selector intent提取结果为空等待内容加载放宽必填字段先检查行数登录通过但下一步失败确保同一会话登录后加 validate 检查元素找不到加等待skyvern browser wait --selector #el --state visible提示词过载拆成更小目标一条命令一个意图7.3 构建工作流前的可行性验证先在站点上交互式走一遍对每个页面用skyvern_act操作、用skyvern_screenshot验证。确认可行后再把各步骤组装成 workflowskyvern_workflow_create。这样能把能不能跑通的不确定性在成本最低的阶段消化掉而不是直接构建多块工作流后才发现不可行。八、编写脚本Python SDK 与混合定位模式8.1 使用正确的 SDK 入口编写脚本时使用 Skyvern Python SDKfrom skyvern import Skyvern绝不从skyvern.cli.mcp_tools导入——那是内部服务器模块不是公开 API。SDK 入口类定义在 skyvern.py 中class Skyvern(AsyncSkyvern)浏览器级操作封装在 skyvern_browser_page.py 等模块中。8.2 利用sdk_equivalent字段自动转换脚本CLI 在 verbose 模式--verbose下每个工具响应都会附带一个sdk_equivalent字段直接给出该次操作对应的 SDK 调用代码方便把交互式操作逐步沉淀为可维护脚本。该字段由 MCP 工具层统一组装见 browser.py 的响应构造逻辑例如导航操作会生成await page.goto({url!r})形式的等价代码。8.3 混合 xpathprompt 模式生产脚本推荐生产脚本推荐确定性定位 AI 语义确认的混合模式XPath 负责锁定元素prompt 让 AI 理解该元素的业务语义await page.click(xpath//button[idsubmit], promptthe Submit button) await page.fill(xpath//input[nameemail], userexample.com, promptemail input field)这样既保留了 XPath 的确定性、又让 LLM 能校验交互语义避免在页面结构微调时误操作。九、完整工作流示例多块表单应用下面是一个可直接落地的多块表单应用定义演示参数声明、变量插值与块编排的完整写法{ title: Multi-Step Form Application, workflow_definition: { parameters: [ {parameter_type: workflow, key: business_name, workflow_parameter_type: string}, {parameter_type: workflow, key: owner_name, workflow_parameter_type: string}, {parameter_type: workflow, key: owner_id, workflow_parameter_type: string} ], blocks: [ {block_type: navigation, label: select_entity_type, url: https://example.com/form/step1, title: Select Entity Type, navigation_goal: Select Sole Proprietor as the entity type and click Continue.}, {block_type: navigation, label: enter_business_info, title: Enter Business Info, navigation_goal: Fill in the business name as {{business_name}} and click Continue., parameter_keys: [business_name]}, {block_type: navigation, label: enter_owner_info, title: Enter Owner Info, navigation_goal: Enter the responsible party name {{owner_name}} and ID {{owner_id}}. Click Continue., parameter_keys: [owner_name, owner_id]}, {block_type: extraction, label: extract_confirmation, title: Extract Confirmation, data_extraction_goal: Extract the confirmation number from the success page, data_schema: {type: object, properties: {confirmation_number: {type: string}}}} ] } }9.1 关键语义解读参数声明parameters数组声明工作流级输入parameter_type为workflowworkflow_parameter_type指明类型。仓库内置示例 multi-page-form.json 还展示了带version: 2与next_block_label显式块顺序的写法login-and-extract.json 与 conditional-retry.json 分别覆盖登录提取与条件重试场景可直接参考。变量插值用{{parameter_key}}在任意块字段中引用工作流输入参数例如Fill in the business name as {{business_name}}。参数设计规范命名明确、按需传递、避免密钥泄漏进描述与运行日志见 parameters.md。同会话自动共享同一运行内的所有块自动共享同一个浏览器会话无需也不应手动传browser_session_id——跨块状态传递是内建的运行时会话复用仅用于跨独立运行延续状态。运行方式创建后通过skyvern_workflow_run(workflow_idwpid_...)执行传入运行参数CLI 用--params {email:userco.com}再用skyvern_workflow_status(run_idwr_...)跟踪结果。首次运行由 AI 推理执行后续运行会重放缓存的脚本显著提速调试需要强制 AI 模式时使用--run-with agent。十、把模式固化为流程验证与沉淀每次页面变更后验证截图做视觉确认validate做布尔断言表单是否提交成功evaluate检查 JS 状态。详见 screenshots.md 的截图主导调试流程。分页循环extract提取全部行 →validate检查 Next 按钮是否可用 → 可用则act点击 → 重复提取终止条件为无 Next 按钮、出现重复首行或达到页数上限。完整策略见 pagination.md。任务等级判定临时试验用run-task正式自动化一律先workflow create一次性的 MCP 交互可通过sdk_equivalent逐步转成 SDK 脚本最终沉淀为带混合定位模式的生产代码。Agent 化接入CLI 支持--json结构化输出与SKYVERN_NON_INTERACTIVE1非交互模式skyvern capabilities --json可发现全部命令方便 Agent 与自动化流水线集成见 cli-parity.md 与 agent-mode.md。从快速验证一个页面到沉淀一个可重跑的多页工作流本文覆盖的六类工具模式覆盖了浏览器自动化的完整生命周期。实际落地时先对照第一节的分类表选对工具再按对应小节的可运行示例执行就能在成本、速度与可靠性之间拿到最优组合。【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考