Skyvern Browser Automation

Skyvern 浏览器自动化 — CLI 判断流程

Skyvern 使用 AI 来导航和交互网站。以下每个命令都是可运行的 skyvern <command> 调用。

何时使用此技能

• 当需要 AI 辅助的浏览器自动化来进行导航、数据提取、表单填写、登录流程或可复用的网站工作流时使用。
• 当确定性选择器不可用，而 Skyvern 的视觉/无障碍推理可以识别页面控件时使用。
• 当一次性浏览器任务需要变成可重复执行的工作流（包含运行历史和验证）时使用。

第一步：分类你的任务（始终先执行此步骤）

MCP 说明： 如果你使用 Skyvern MCP 而非 CLI，对于同页多步骤 UI 工作优先使用 observe + execute。CLI 不直接暴露这对命令。

第二步：应用这些决策规则

1. 如果提示中包含选择器、id、XPath 或精确字段目标，使用浏览器原语 — 而非 act。
2. 如果只需要是/否答案，使用 validate — 而非 extract 或 act。
3. 如果工作停留在一个页面且标签清晰，使用 act 或原语链。
4. 如果用户说"试一次看看"、"看看是否可行"，或明确想要一次性探索试验，使用 run-task。
5. 如果任务跨越多页且需要可复用、可调度、可重复，或明确要"设置"为自动化，使用 workflow create。
6. 永远不要直接输入密码。始终使用 skyvern browser login 配合存储的凭证。

第三步：创建会话

每个浏览器命令都需要一个会话。先创建一个：

# 云端会话（默认 — 适用于公开 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 create 之后，后续命令自动附加。 使用 --session pbs_... 覆盖。完成后关闭：skyvern browser session close。

第四步：按分类执行

快速检查（是/否）

skyvern browser validate --prompt "Is the user logged in? Look for a dashboard or avatar."

返回 true/false。最便宜的 AI 选项 — 对于布尔检查优先使用而非 extract 或 act。

快速检查

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"}}}}}}'

使用截图 + 专用提取 LLM。比截图+读取更好，因为 Skyvern 的 LLM 会解释页面。

单次操作（已知目标）

skyvern browser click --selector "#submit-btn"
skyvern browser type --text "user@co.com" --selector "#email"
skyvern browser select --value "US" --intent "the country dropdown"

确定性。无 AI。三种定位模式：

1. 意图：--intent "the Submit button"（AI 查找元素）
2. 选择器：--selector "#submit-btn"（CSS/XPath，确定性）
3. 混合：两者结合（选择器缩小范围，AI 确认）

单次操作（未知目标）

skyvern browser act --prompt "Click the Sign In button"
skyvern browser act --prompt "Close the cookie banner, then click Sign In"

警告： act 的 LLM 推理中没有截图。它使用经济型无障碍树。 对于标签清晰的元素效果良好。对于视觉复杂的目标，使用 MCP observe+click 或混合模式。

同页多步骤

skyvern browser act --prompt "Fill the shipping form and click Continue"

当字段和按钮标签清晰且流程停留在一个页面时使用 act。 如果需要更精细的控制，将工作拆分为 click、type、select、press-key 和 wait。

一次性自主试验

skyvern browser run-task \
  --url "https://example.com" \
  --prompt "Check whether the checkout flow works end to end and extract the confirmation number"

使用 run-task 来验证可行性或进行一次性探索。如果任务变得足够重要需要重新运行、调试或分享，请将其转换为工作流。

多页或可复用自动化 — 每步一个块构建工作流

skyvern workflow create --definition @checkout-workflow.yaml
skyvern workflow run --id wpid_123 --wait
skyvern workflow status --run-id wr_789

每个导航块使用视觉推理 + 验证运行。将复杂流程拆分为多个块（每页/每步一个）。首次运行使用 AI；后续运行回放缓存脚本。

重复/生产

skyvern workflow create --definition @workflow.yaml
skyvern workflow run --id wpid_123 --params '{"email":"user@co.com"}'
skyvern workflow status --run-id wr_789

拆分为每步一个块。使用导航块执行操作，使用提取块获取数据。 首次运行使用 AI；后续运行回放缓存脚本（快 10-100 倍）。 设置 --run-with agent 强制 AI 模式用于调试。

第五步：验证

在改变页面的操作后始终验证：

skyvern browser screenshot                          # 视觉检查
skyvern browser validate --prompt "Was the form submitted successfully?"  # 布尔断言
skyvern browser evaluate --expression "document.title"                    # JS 状态检查

第六步：错误恢复

凭证

永远不要通过 skyvern browser type 或 act 输入密码。始终使用存储的凭证：

skyvern credentials add --name "my-login" --type password --username "user@co.com"
skyvern credential list                          # 查找凭证 ID
skyvern browser login --url "https://login.example.com" --credential-id cred_123

类型：password、credit_card、secret。还支持 bitwarden、1password 和 azure_vault 提供商。

工作流快速参考

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                # 发现块类型
skyvern block validate --block-json @block.json       # 创建前验证

引擎：已知路径 = 1.0（默认）。动态规划 = 2.0。有疑问时拆分为多个 1.0 块。 状态生命周期：created -> queued -> running -> completed | failed | canceled | terminated | timed_out

常见模式

登录流程：

skyvern credential list                          # 查找凭证 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

分页循环：

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"
# 重复提取。停止条件：没有下一页按钮、首行重复、或达到最大页数限制。

调试：

skyvern browser screenshot                       # 视觉状态
skyvern browser evaluate --expression "document.title"
skyvern browser evaluate --expression "document.querySelectorAll('table tr').length"

局限性

• 不要使用 Skyvern 绕过网站访问控制、速率限制、同意网关或禁止自动化的条款。
• 浏览器自动化可以改变远程状态；在提交表单、购买、删除或发送消息之前确认用户意图。
• 对于稳定的生产流程优先使用确定性选择器；AI 操作可能误读未标记或视觉上模糊的控件。
• 仅在支持的凭证库中存储凭证，永远不要通过 type 或 act 直接输入密码。

代理模式

所有命令接受 --json 以获取结构化输出。设置 SKYVERN_NON_INTERACTIVE=1 防止提示。 使用 skyvern capabilities --json 进行完整命令发现。参见 references/agent-mode.md。

深入参考