Skyvern CLI 浏览器自动化决策指南从任务分类到工作流构建的完整实操手册【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvernSkyvern 使用 AI 来导航和操作真实网站——动态渲染页面、表单填写、数据抽取、登录、截图乃至跨页面的完整业务流程都可以通过skyvern命令行完成。本文基于仓库内 skyvern/cli/skills/skyvern/SKILL.md 编写它本质上是一份面向 AI Agent 与开发者的CLI 判断程序先对任务分类再按分类选择最合适的命令组合最后验证与排错。读完本文你将掌握skyvern browser系列命令的完整调用链、任务分类决策表、会话与凭据管理、工作流构建及常见故障恢复方法能够独立把一段自然语言需求翻译为可运行、可复用、可调试的浏览器自动化流程。一、核心决策框架先分类再执行SKILL.md 开宗明义地要求任何任务的第一步永远是分类Classify Your Task。不同任务对AI 参与程度、截图依赖、成本、确定性的要求完全不同选错工具会导致成本浪费或结果不可靠。下表是官方给出的六类任务与对应命令的完整映射是全文决策的基石分类触发信号CLI 命令成本行为说明快速检查是/否用户是否已登录skyvern browser validate1 次 LLM 截图轻量校验最多 2 步返回布尔值是最便宜的 AI 选项快速检视页面上显示了什么skyvern browser extract1 次 LLM 截图专用抽取 LLM schema 校验 缓存单动作目标已知点击 #submitskyvern browser click/type0 次 LLM确定性的 Playwright无 AI最快单动作目标未知点击提交按钮skyvern browser act2-3 次 LLM无截图推理中不含截图使用经济型无障碍树视觉目标请用混合模式selector intent同页多步填写表单并提交skyvern browser act或原语链2-3 次 LLM 或 0 次 LLM标签清晰时用act已知选择器时直接用 click/type/select一次性自主试验试一次、看是否可行skyvern browser run-task较高一次性自主代理用于探索不要用于重复或跨页面生产自动化多页/可复用自动化完成多页向导、每周自动执行skyvern workflow createrunN 次 LLM 截图每个步骤一个 block每个 block 都有视觉推理、校验和可复用的运行历史MCP 说明官方原文如果你使用的是 Skyvern MCP 而非 CLI在同页多步 UI 工作中stdio 模式优先observe executerefs 在下次 observe、导航或页面/文档上下文变化前持续有效。在托管的无状态 HTTP 模式上优先使用selector或intent参数——前序调用的 refs 无法解析且一次 execute 批处理只能在调用前可预知时使用 refs永远不能根据内联 observe 结果自适应调整。CLI 不直接暴露该组合。这一分类优先的设计与 browser 命令实现 中每个子命令的定位完全对应validate、extract、act、run-task分别承载不同层级的 AI 参与度而click、type、select、press-key、wait则提供零 AI 的确定性原语。二、决策规则六条硬性判断标准分类表之后SKILL.md 给出六条决策规则用于在具体需求与命令之间快速收敛提示中已包含 selector、id、XPath 或精确字段目标 → 使用浏览器原语click/type/select不要用act只需要是/否答案 → 用validate不要用extract或act工作停留在单页且标签清晰 → 用act或原语链用户说试一次、看是否可行、明确是一次性探索试验 → 用run-task任务跨多页且需要可复用、可调度、可重复或明确要求配置成自动化 → 用workflow create永远不要直接输入密码始终使用已存储的凭据配合skyvern browser login。规则 6 在源码层面有双重保障act命令执行前会调用check_password_prompt(prompt)守卫拦截包含密码意图的提示词见 commands/browser.pyevaluate执行 JS 表达式前也有check_js_password守卫commands/browser.py从命令入口就杜绝密码明文进入交互链。关于规则 4 与 5 的边界可参考 references/engines.md真正的自动化工作默认走 workflow只有一次性探索、结果可丢弃、仅用于验证可行性时才用run-task。经验法则任务一旦跨页面边界或听起来是真实自动化而非试验就先构建 workflow。三、会话管理一切浏览器命令的前提SKILL.md 明确指出每个浏览器命令都需要一个会话session请先创建它。会话状态在命令之间持续保留session create之后的命令会自动附着到该会话。# 云端会话默认适用于公网 URL skyvern browser session create --timeout 30 # 本地会话用于 localhost URL 或自托管模式 skyvern browser session create --local --timeout 30 # 通过 CDP 连接已有浏览器 skyvern browser session connect --cdp ws://localhost:9222会话创建后后续命令自动附着如需显式指定用--session pbs_...覆盖结束后关闭skyvern browser session close。关于会话复用的深入策略见 references/sessions.md要点如下运行时会话复用把pbs_*ID 作为browser_session_id传给workflow run或run task让一次性运行继续使用已打开的浏览器。适用于后续任务依赖刚打开的会话状态或链式工作流运行需要首轮登录态不要跨 block 传 session同一 workflow 内的 blocks 默认共享一个浏览器会话不要传browser_session_id注意区分这不是 workflow 级的 Save Reuse Session 开关persist_browser_session该开关默认关闭除非用户明确要求跨运行保留状态否则保持关闭何时开新会话会话失效/过期、站点有严格反自动化锁定、需要并行运行独立任务登录后必须校验用skyvern validate加具体条件头像可见、登出按钮存在、账户面板标题出现而不是笼统地问是否登录成功。四、按分类执行命令全解与源码印证4.1 快速检查是/否——validateskyvern browser validate --prompt Is the user logged in? Look for a dashboard or avatar.返回 true/false。这是最便宜的 AI 选项布尔判断优先于 extract 或 act。源码中该命令返回结构为{prompt: prompt, valid: valid}commands/browser.pyvalid字段即布尔结果配合--json可直接被程序消费。4.2 快速检视——extractskyvern 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}}}}}}使用截图 专用抽取 LLM比截图人读更好因为 Skyvern 的 LLM 会真正理解页面语义。--schema提供 JSON Schema 以约束结构化输出。命令实现见 commands/browser.py。schema 设计模式详见 references/schemas.md。4.3 单动作目标已知——click / type / selectskyvern browser click --selector #submit-btn skyvern browser type --text userco.com --selector #email skyvern browser select --value US --intent the country dropdown确定性的 Playwright 执行零 AI 参与速度最快。click支持三种定位模式这也是 references/precision-actions.md 的主题Intent意图--intent the Submit button由 AI 定位元素Selector选择器--selector #submit-btnCSS/XPath完全确定性Hybrid混合两者同时给出selector 先缩小范围、AI 再做确认适用于页面嘈杂的场景。以click为例源码参数还支持--timeout毫秒默认 30000、--buttonleft/right/middle、--click-count双击传 2见 commands/browser.py。同族的确定性原语还包括press-key、wait等可组合成完全无 AI 的原语链。4.4 单动作目标未知与同页多步——actskyvern browser act --prompt Click the Sign In button skyvern browser act --prompt Close the cookie banner, then click Sign In skyvern browser act --prompt Fill the shipping form and click Continue警告官方原文act的 LLM 推理中没有截图它使用经济型无障碍树economy accessibility tree。对标签清晰的元素足够好用对视觉复杂的目标请使用 MCP 的 observeexecutestdio 模式托管无状态 HTTP 上用 selector/intent或使用混合模式。同页多步场景下当字段与按钮标签清晰、流程停留在单页时用act若需要更精确的控制就把工作拆成click、type、select、press-key、wait原语链。act返回{prompt: ..., completed: ...}实现见 commands/browser.py。4.5 一次性自主试验——run-taskskyvern browser run-task \ --url https://example.com \ --prompt Check whether the checkout flow works end to end and extract the confirmation number用于验证可行性或一次性探索。一旦任务重要到需要重跑、调试或分享就应转换为 workflow。从源码看commands/browser.py该命令还支持--schema数据抽取 JSON Schema、--max-steps最大 Agent 步数、--timeout默认 180 秒范围 10–1800 秒并可在 cloud 模式下沿用当前会话、或通过--cdp接管本地浏览器。4.6 多页/可复用自动化——workflowskyvern workflow create --definition checkout-workflow.yaml skyvern workflow run --id wpid_123 --wait skyvern workflow status --run-id wr_789每个导航 block 都带视觉推理与校验。复杂流程务必拆成多个 block每页/每步一个 block。首次运行走 AI后续运行回放缓存脚本SKILL.md 标注可快 10–100 倍调试时用--run-with agent强制 AI 模式。五、验证页面变更后必做的收尾动作SKILL.md 要求任何改变页面的动作之后都要验证。三个互补手段skyvern browser screenshot # 视觉检查 skyvern browser validate --prompt Was the form submitted successfully? # 布尔断言 skyvern browser evaluate --expression document.title # JS 状态检查screenshot支持--full-page整页滚动截图、--selector仅截某元素和--output自定义输出路径无输出路径时自动以screenshot_时间戳.png保存为 artifactcommands/browser.pyevaluate直接在当前页执行 JavaScript 表达式返回{result: ...}commands/browser.py适合检查document.title、document.querySelectorAll(table tr).length这类确定性状态。验证驱动的调试工作流可进一步参考 references/screenshots.md。六、错误恢复常见失败模式速查SKILL.md 提供了简洁的故障-修复对照表结合 references/common-failures.md 可得到完整目录问题修复动作点错了元素在提示词中补充上下文位置、标签、区块改用混合模式selector intent抽取返回空结果等待内容就绪放宽 required 字段先校验行/卡片数量再抽取登录通过但下一步仍提示未登录确保使用同一个 session在登录后追加 validate 校验元素找不到加等待skyvern browser wait --selector #el --state visible提示词过载拆分为更小的目标——每个命令只表达一个意图七、凭据管理绝不直接输入密码这是本技能的安全底线永远不要通过skyvern browser type或act输入密码始终使用已存储的凭据。skyvern credentials add --name my-login --type password --username userco.com skyvern credential list # 找到 credential ID skyvern browser login --url https://login.example.com --credential-id cred_123凭据类型password、credit_card、secret同时支持 bitwarden、1password、azure_vault 三种外部 provider——login命令的--credential-type参数正是skyvern | bitwarden | 1password | azure_vault四选一并通过--bitwarden-item-id、--onepassword-vault-id、--azure-vault-name等参数指定远端条目commands/browser.py。references/credentials.md 补充了生产级安全实践# 用环境变量传密钥不要用 CLI flag —— flag 会在 ps 和 /proc/*/cmdline 中可见 export SKYVERN_CRED_PASSWORDs3cret skyvern credentials add --name prod-login --type password \ --username userexample.com --json # 带 TOTP 的登录凭据 export SKYVERN_CRED_PASSWORDs3cret export SKYVERN_CRED_TOTPJBSWY3DPEHPK3PXP skyvern credentials add --name prod-mfa --type password \ --username userexample.com --json # 信用卡敏感字段走环境变量 export SKYVERN_CRED_CARD_NUMBER4111111111111111 export SKYVERN_CRED_CVV123 skyvern credentials add --name test-card --type credit_card \ --exp-month 12 --exp-year 2027 --card-brand visa \ --holder-name John Doe --json # 密钥API key、token 等 export SKYVERN_CRED_SECRET_VALUEsk_live_abc123 skyvern credentials add --name api-token --type secret \ --secret-label Stripe key --json可用环境变量全集SKYVERN_CRED_PASSWORD、SKYVERN_CRED_TOTP、SKYVERN_CRED_CARD_NUMBER、SKYVERN_CRED_CVV、SKYVERN_CRED_SECRET_VALUE、SKYVERN_CRED_USERNAME、SKYVERN_CRED_EXP_MONTH、SKYVERN_CRED_EXP_YEAR、SKYVERN_CRED_CARD_BRAND、SKYVERN_CRED_HOLDER_NAME、SKYVERN_CRED_SECRET_LABEL。其他命令skyvern credential list --json列表、skyvern credential get --id cred_abc123 --json查询、skyvern credentials delete cred_abc123 --yes --json删除。命名规范建议采用环境目标域名组合如prod-salesforce-primary、staging-hubspot-sandbox。安全性方面密钥只用环境变量、日志中绝不打印密钥、确认 credential ID 对应正确的系统、主动清理过期凭据。八、工作流构建速查与状态生命周期8.1 工作流快速参考skyvern workflow create --definition 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 # 发现 block 类型 skyvern block validate --block-json block.json # 创建前校验 block引擎选择已知路径 1.0默认动态规划 2.0。拿不准时就拆成多个 1.0 block状态生命周期created - queued - running - completed | failed | canceled | terminated | timed_out复杂流程拆成每步一个 blocknavigationblock 负责动作extractionblock 负责数据。references/status-lifecycle.md 补充了非终态paused运行挂起可恢复并给出运维建议按工作流类别定义最大运行时长、对超过阈值仍卡在非终态的运行告警、按失败特征归类以便排优先级。8.2 工作流定义示例仓库 examples/login-and-extract.json 给出了登录并抽取账户摘要的完整 v2 工作流定义声明portal_urlstring与login_credentialcredential_id两个 workflow 参数第一个loginblock 用parameter_keys引用凭据并给出complete_criterion账户面板可见且登录表单消失成功后经next_block_label流转到extractionblock后者用data_extraction_goal与data_schema定义抽取目标。这是一个 block 一步的范本。更多模板见 examples 目录及 references/quick-start-patterns.md。九、常见模式登录、分页与调试9.1 登录流程skyvern credential list # 找到 credential ID 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登录后必须执行 validate 校验且后续步骤沿用同一会话。navigate命令默认超时 30000ms--wait-until支持load、domcontentloaded、networkidle、commit四种等待条件commands/browser.py。9.2 分页循环skyvern browser extract --prompt Extract all rows skyvern browser validate --prompt Is there a Next button that is not disabled? # 若为 true skyvern browser act --prompt Click the Next page button # 重复抽取。停止条件无下一页、出现重复首行、达到最大页数限制。references/pagination.md 给出了配套护栏用意图Next page而非硬编码 selector 翻页在输出元数据中记录页码按稳定键id、url、titledate去重抽取结构意外变化时快速失败。9.3 调试三板斧skyvern browser screenshot # 视觉状态 skyvern browser evaluate --expression document.title skyvern browser evaluate --expression document.querySelectorAll(table tr).length十、Agent 模式与结构化输出所有命令都接受--json输出结构化结果。设置SKYVERN_NON_INTERACTIVE1可禁止交互提示CI 环境下CItrue同样生效。完整的命令发现用skyvern capabilities --jsonreferences/agent-mode.mdskyvern capabilities --json # 顶层命令概览默认约 1.4K tokens skyvern capabilities workflow --json # 下钻到具体命令组 skyvern capabilities --depth 3 --json # 完整命令树约 20K tokens按需开启每条--json响应都使用统一信封结构{schema_version, ok, action, data, error, warnings, browser_context, artifacts, timing_ms}便于 Agent 或 CI 脚本做程序化解析。此模式专为 AI Agent 与 CI/CD 流水线设计——所有必需值通过环境变量或 flag 传入、错误以 JSON 返回可完全无人值守运行。十一、深度参考索引SKILL.md 末尾给出了完整的参考文档导航全部位于 skyvern/cli/skills/skyvern/references 目录参考文档内容prompt-writing.md提示词模板与反模式outcome-first 模板Goal/Site/Constraints/Success criteria/Outputengines.mdtask 与 workflow 的选型时机schemas.md抽取用 JSON Schema 模式pagination.md分页策略与护栏block-types.mdworkflow block 类型详解与示例parameters.md参数设计与变量用法ai-actions.mdAI 动作模式与示例precision-actions.mdintent-only / selector-only / hybrid 三种定位模式credentials.md凭据命名、生命周期与安全sessions.md会话复用与新鲜度决策common-failures.md失败模式目录与修复screenshots.md截图驱动的调试工作流status-lifecycle.md运行状态机与运维指导rerun-playbook.md重跑流程与对比complex-inputs.md日期选择器、文件上传、下拉框等复杂输入tool-map.md按目标分类的完整工具清单cli-parity.mdCLI/MCP 映射与 Agent 感知特性quick-start-patterns.md快速上手示例、常用模式与工作流模板小结Skyvern CLI 的精髓在于分类-执行-验证-恢复的闭环先用任务分类表与六条决策规则锁定命令层级从零 AI 的原语到全 AI 的 workflow再通过会话与凭据保证状态安全与身份安全最后用 validate/screenshot/evaluate 三件套闭环验证配合错误恢复速查表处理异常。对于跨页面的可复用业务始终优先构建一页一 block的工作流让首次运行的 AI 推理沉淀为后续可高速回放的缓存脚本——这就是把会点按钮的 AI升级为可运维的自动化资产的完整路径。【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Skyvern CLI 浏览器自动化决策指南：从任务分类到工作流构建的完整实操手册
Skyvern CLI 浏览器自动化决策指南从任务分类到工作流构建的完整实操手册【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvernSkyvern 使用 AI 来导航和操作真实网站——动态渲染页面、表单填写、数据抽取、登录、截图乃至跨页面的完整业务流程都可以通过skyvern命令行完成。本文基于仓库内 skyvern/cli/skills/skyvern/SKILL.md 编写它本质上是一份面向 AI Agent 与开发者的CLI 判断程序先对任务分类再按分类选择最合适的命令组合最后验证与排错。读完本文你将掌握skyvern browser系列命令的完整调用链、任务分类决策表、会话与凭据管理、工作流构建及常见故障恢复方法能够独立把一段自然语言需求翻译为可运行、可复用、可调试的浏览器自动化流程。一、核心决策框架先分类再执行SKILL.md 开宗明义地要求任何任务的第一步永远是分类Classify Your Task。不同任务对AI 参与程度、截图依赖、成本、确定性的要求完全不同选错工具会导致成本浪费或结果不可靠。下表是官方给出的六类任务与对应命令的完整映射是全文决策的基石分类触发信号CLI 命令成本行为说明快速检查是/否用户是否已登录skyvern browser validate1 次 LLM 截图轻量校验最多 2 步返回布尔值是最便宜的 AI 选项快速检视页面上显示了什么skyvern browser extract1 次 LLM 截图专用抽取 LLM schema 校验 缓存单动作目标已知点击 #submitskyvern browser click/type0 次 LLM确定性的 Playwright无 AI最快单动作目标未知点击提交按钮skyvern browser act2-3 次 LLM无截图推理中不含截图使用经济型无障碍树视觉目标请用混合模式selector intent同页多步填写表单并提交skyvern browser act或原语链2-3 次 LLM 或 0 次 LLM标签清晰时用act已知选择器时直接用 click/type/select一次性自主试验试一次、看是否可行skyvern browser run-task较高一次性自主代理用于探索不要用于重复或跨页面生产自动化多页/可复用自动化完成多页向导、每周自动执行skyvern workflow createrunN 次 LLM 截图每个步骤一个 block每个 block 都有视觉推理、校验和可复用的运行历史MCP 说明官方原文如果你使用的是 Skyvern MCP 而非 CLI在同页多步 UI 工作中stdio 模式优先observe executerefs 在下次 observe、导航或页面/文档上下文变化前持续有效。在托管的无状态 HTTP 模式上优先使用selector或intent参数——前序调用的 refs 无法解析且一次 execute 批处理只能在调用前可预知时使用 refs永远不能根据内联 observe 结果自适应调整。CLI 不直接暴露该组合。这一分类优先的设计与 browser 命令实现 中每个子命令的定位完全对应validate、extract、act、run-task分别承载不同层级的 AI 参与度而click、type、select、press-key、wait则提供零 AI 的确定性原语。二、决策规则六条硬性判断标准分类表之后SKILL.md 给出六条决策规则用于在具体需求与命令之间快速收敛提示中已包含 selector、id、XPath 或精确字段目标 → 使用浏览器原语click/type/select不要用act只需要是/否答案 → 用validate不要用extract或act工作停留在单页且标签清晰 → 用act或原语链用户说试一次、看是否可行、明确是一次性探索试验 → 用run-task任务跨多页且需要可复用、可调度、可重复或明确要求配置成自动化 → 用workflow create永远不要直接输入密码始终使用已存储的凭据配合skyvern browser login。规则 6 在源码层面有双重保障act命令执行前会调用check_password_prompt(prompt)守卫拦截包含密码意图的提示词见 commands/browser.pyevaluate执行 JS 表达式前也有check_js_password守卫commands/browser.py从命令入口就杜绝密码明文进入交互链。关于规则 4 与 5 的边界可参考 references/engines.md真正的自动化工作默认走 workflow只有一次性探索、结果可丢弃、仅用于验证可行性时才用run-task。经验法则任务一旦跨页面边界或听起来是真实自动化而非试验就先构建 workflow。三、会话管理一切浏览器命令的前提SKILL.md 明确指出每个浏览器命令都需要一个会话session请先创建它。会话状态在命令之间持续保留session create之后的命令会自动附着到该会话。# 云端会话默认适用于公网 URL skyvern browser session create --timeout 30 # 本地会话用于 localhost URL 或自托管模式 skyvern browser session create --local --timeout 30 # 通过 CDP 连接已有浏览器 skyvern browser session connect --cdp ws://localhost:9222会话创建后后续命令自动附着如需显式指定用--session pbs_...覆盖结束后关闭skyvern browser session close。关于会话复用的深入策略见 references/sessions.md要点如下运行时会话复用把pbs_*ID 作为browser_session_id传给workflow run或run task让一次性运行继续使用已打开的浏览器。适用于后续任务依赖刚打开的会话状态或链式工作流运行需要首轮登录态不要跨 block 传 session同一 workflow 内的 blocks 默认共享一个浏览器会话不要传browser_session_id注意区分这不是 workflow 级的 Save Reuse Session 开关persist_browser_session该开关默认关闭除非用户明确要求跨运行保留状态否则保持关闭何时开新会话会话失效/过期、站点有严格反自动化锁定、需要并行运行独立任务登录后必须校验用skyvern validate加具体条件头像可见、登出按钮存在、账户面板标题出现而不是笼统地问是否登录成功。四、按分类执行命令全解与源码印证4.1 快速检查是/否——validateskyvern browser validate --prompt Is the user logged in? Look for a dashboard or avatar.返回 true/false。这是最便宜的 AI 选项布尔判断优先于 extract 或 act。源码中该命令返回结构为{prompt: prompt, valid: valid}commands/browser.pyvalid字段即布尔结果配合--json可直接被程序消费。4.2 快速检视——extractskyvern 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}}}}}}使用截图 专用抽取 LLM比截图人读更好因为 Skyvern 的 LLM 会真正理解页面语义。--schema提供 JSON Schema 以约束结构化输出。命令实现见 commands/browser.py。schema 设计模式详见 references/schemas.md。4.3 单动作目标已知——click / type / selectskyvern browser click --selector #submit-btn skyvern browser type --text userco.com --selector #email skyvern browser select --value US --intent the country dropdown确定性的 Playwright 执行零 AI 参与速度最快。click支持三种定位模式这也是 references/precision-actions.md 的主题Intent意图--intent the Submit button由 AI 定位元素Selector选择器--selector #submit-btnCSS/XPath完全确定性Hybrid混合两者同时给出selector 先缩小范围、AI 再做确认适用于页面嘈杂的场景。以click为例源码参数还支持--timeout毫秒默认 30000、--buttonleft/right/middle、--click-count双击传 2见 commands/browser.py。同族的确定性原语还包括press-key、wait等可组合成完全无 AI 的原语链。4.4 单动作目标未知与同页多步——actskyvern browser act --prompt Click the Sign In button skyvern browser act --prompt Close the cookie banner, then click Sign In skyvern browser act --prompt Fill the shipping form and click Continue警告官方原文act的 LLM 推理中没有截图它使用经济型无障碍树economy accessibility tree。对标签清晰的元素足够好用对视觉复杂的目标请使用 MCP 的 observeexecutestdio 模式托管无状态 HTTP 上用 selector/intent或使用混合模式。同页多步场景下当字段与按钮标签清晰、流程停留在单页时用act若需要更精确的控制就把工作拆成click、type、select、press-key、wait原语链。act返回{prompt: ..., completed: ...}实现见 commands/browser.py。4.5 一次性自主试验——run-taskskyvern browser run-task \ --url https://example.com \ --prompt Check whether the checkout flow works end to end and extract the confirmation number用于验证可行性或一次性探索。一旦任务重要到需要重跑、调试或分享就应转换为 workflow。从源码看commands/browser.py该命令还支持--schema数据抽取 JSON Schema、--max-steps最大 Agent 步数、--timeout默认 180 秒范围 10–1800 秒并可在 cloud 模式下沿用当前会话、或通过--cdp接管本地浏览器。4.6 多页/可复用自动化——workflowskyvern workflow create --definition checkout-workflow.yaml skyvern workflow run --id wpid_123 --wait skyvern workflow status --run-id wr_789每个导航 block 都带视觉推理与校验。复杂流程务必拆成多个 block每页/每步一个 block。首次运行走 AI后续运行回放缓存脚本SKILL.md 标注可快 10–100 倍调试时用--run-with agent强制 AI 模式。五、验证页面变更后必做的收尾动作SKILL.md 要求任何改变页面的动作之后都要验证。三个互补手段skyvern browser screenshot # 视觉检查 skyvern browser validate --prompt Was the form submitted successfully? # 布尔断言 skyvern browser evaluate --expression document.title # JS 状态检查screenshot支持--full-page整页滚动截图、--selector仅截某元素和--output自定义输出路径无输出路径时自动以screenshot_时间戳.png保存为 artifactcommands/browser.pyevaluate直接在当前页执行 JavaScript 表达式返回{result: ...}commands/browser.py适合检查document.title、document.querySelectorAll(table tr).length这类确定性状态。验证驱动的调试工作流可进一步参考 references/screenshots.md。六、错误恢复常见失败模式速查SKILL.md 提供了简洁的故障-修复对照表结合 references/common-failures.md 可得到完整目录问题修复动作点错了元素在提示词中补充上下文位置、标签、区块改用混合模式selector intent抽取返回空结果等待内容就绪放宽 required 字段先校验行/卡片数量再抽取登录通过但下一步仍提示未登录确保使用同一个 session在登录后追加 validate 校验元素找不到加等待skyvern browser wait --selector #el --state visible提示词过载拆分为更小的目标——每个命令只表达一个意图七、凭据管理绝不直接输入密码这是本技能的安全底线永远不要通过skyvern browser type或act输入密码始终使用已存储的凭据。skyvern credentials add --name my-login --type password --username userco.com skyvern credential list # 找到 credential ID skyvern browser login --url https://login.example.com --credential-id cred_123凭据类型password、credit_card、secret同时支持 bitwarden、1password、azure_vault 三种外部 provider——login命令的--credential-type参数正是skyvern | bitwarden | 1password | azure_vault四选一并通过--bitwarden-item-id、--onepassword-vault-id、--azure-vault-name等参数指定远端条目commands/browser.py。references/credentials.md 补充了生产级安全实践# 用环境变量传密钥不要用 CLI flag —— flag 会在 ps 和 /proc/*/cmdline 中可见 export SKYVERN_CRED_PASSWORDs3cret skyvern credentials add --name prod-login --type password \ --username userexample.com --json # 带 TOTP 的登录凭据 export SKYVERN_CRED_PASSWORDs3cret export SKYVERN_CRED_TOTPJBSWY3DPEHPK3PXP skyvern credentials add --name prod-mfa --type password \ --username userexample.com --json # 信用卡敏感字段走环境变量 export SKYVERN_CRED_CARD_NUMBER4111111111111111 export SKYVERN_CRED_CVV123 skyvern credentials add --name test-card --type credit_card \ --exp-month 12 --exp-year 2027 --card-brand visa \ --holder-name John Doe --json # 密钥API key、token 等 export SKYVERN_CRED_SECRET_VALUEsk_live_abc123 skyvern credentials add --name api-token --type secret \ --secret-label Stripe key --json可用环境变量全集SKYVERN_CRED_PASSWORD、SKYVERN_CRED_TOTP、SKYVERN_CRED_CARD_NUMBER、SKYVERN_CRED_CVV、SKYVERN_CRED_SECRET_VALUE、SKYVERN_CRED_USERNAME、SKYVERN_CRED_EXP_MONTH、SKYVERN_CRED_EXP_YEAR、SKYVERN_CRED_CARD_BRAND、SKYVERN_CRED_HOLDER_NAME、SKYVERN_CRED_SECRET_LABEL。其他命令skyvern credential list --json列表、skyvern credential get --id cred_abc123 --json查询、skyvern credentials delete cred_abc123 --yes --json删除。命名规范建议采用环境目标域名组合如prod-salesforce-primary、staging-hubspot-sandbox。安全性方面密钥只用环境变量、日志中绝不打印密钥、确认 credential ID 对应正确的系统、主动清理过期凭据。八、工作流构建速查与状态生命周期8.1 工作流快速参考skyvern workflow create --definition 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 # 发现 block 类型 skyvern block validate --block-json block.json # 创建前校验 block引擎选择已知路径 1.0默认动态规划 2.0。拿不准时就拆成多个 1.0 block状态生命周期created - queued - running - completed | failed | canceled | terminated | timed_out复杂流程拆成每步一个 blocknavigationblock 负责动作extractionblock 负责数据。references/status-lifecycle.md 补充了非终态paused运行挂起可恢复并给出运维建议按工作流类别定义最大运行时长、对超过阈值仍卡在非终态的运行告警、按失败特征归类以便排优先级。8.2 工作流定义示例仓库 examples/login-and-extract.json 给出了登录并抽取账户摘要的完整 v2 工作流定义声明portal_urlstring与login_credentialcredential_id两个 workflow 参数第一个loginblock 用parameter_keys引用凭据并给出complete_criterion账户面板可见且登录表单消失成功后经next_block_label流转到extractionblock后者用data_extraction_goal与data_schema定义抽取目标。这是一个 block 一步的范本。更多模板见 examples 目录及 references/quick-start-patterns.md。九、常见模式登录、分页与调试9.1 登录流程skyvern credential list # 找到 credential ID 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登录后必须执行 validate 校验且后续步骤沿用同一会话。navigate命令默认超时 30000ms--wait-until支持load、domcontentloaded、networkidle、commit四种等待条件commands/browser.py。9.2 分页循环skyvern browser extract --prompt Extract all rows skyvern browser validate --prompt Is there a Next button that is not disabled? # 若为 true skyvern browser act --prompt Click the Next page button # 重复抽取。停止条件无下一页、出现重复首行、达到最大页数限制。references/pagination.md 给出了配套护栏用意图Next page而非硬编码 selector 翻页在输出元数据中记录页码按稳定键id、url、titledate去重抽取结构意外变化时快速失败。9.3 调试三板斧skyvern browser screenshot # 视觉状态 skyvern browser evaluate --expression document.title skyvern browser evaluate --expression document.querySelectorAll(table tr).length十、Agent 模式与结构化输出所有命令都接受--json输出结构化结果。设置SKYVERN_NON_INTERACTIVE1可禁止交互提示CI 环境下CItrue同样生效。完整的命令发现用skyvern capabilities --jsonreferences/agent-mode.mdskyvern capabilities --json # 顶层命令概览默认约 1.4K tokens skyvern capabilities workflow --json # 下钻到具体命令组 skyvern capabilities --depth 3 --json # 完整命令树约 20K tokens按需开启每条--json响应都使用统一信封结构{schema_version, ok, action, data, error, warnings, browser_context, artifacts, timing_ms}便于 Agent 或 CI 脚本做程序化解析。此模式专为 AI Agent 与 CI/CD 流水线设计——所有必需值通过环境变量或 flag 传入、错误以 JSON 返回可完全无人值守运行。十一、深度参考索引SKILL.md 末尾给出了完整的参考文档导航全部位于 skyvern/cli/skills/skyvern/references 目录参考文档内容prompt-writing.md提示词模板与反模式outcome-first 模板Goal/Site/Constraints/Success criteria/Outputengines.mdtask 与 workflow 的选型时机schemas.md抽取用 JSON Schema 模式pagination.md分页策略与护栏block-types.mdworkflow block 类型详解与示例parameters.md参数设计与变量用法ai-actions.mdAI 动作模式与示例precision-actions.mdintent-only / selector-only / hybrid 三种定位模式credentials.md凭据命名、生命周期与安全sessions.md会话复用与新鲜度决策common-failures.md失败模式目录与修复screenshots.md截图驱动的调试工作流status-lifecycle.md运行状态机与运维指导rerun-playbook.md重跑流程与对比complex-inputs.md日期选择器、文件上传、下拉框等复杂输入tool-map.md按目标分类的完整工具清单cli-parity.mdCLI/MCP 映射与 Agent 感知特性quick-start-patterns.md快速上手示例、常用模式与工作流模板小结Skyvern CLI 的精髓在于分类-执行-验证-恢复的闭环先用任务分类表与六条决策规则锁定命令层级从零 AI 的原语到全 AI 的 workflow再通过会话与凭据保证状态安全与身份安全最后用 validate/screenshot/evaluate 三件套闭环验证配合错误恢复速查表处理异常。对于跨页面的可复用业务始终优先构建一页一 block的工作流让首次运行的 AI 推理沉淀为后续可高速回放的缓存脚本——这就是把会点按钮的 AI升级为可运维的自动化资产的完整路径。【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考