Skyvern 工具地图（Tool Map）：按目标场景精准选用浏览器自动化工具-平芜编程栈

Skyvern 工具地图（Tool Map）：按目标场景精准选用浏览器自动化工具

【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern

本篇指南围绕 Skyvern 仓库中 skills/skyvern/references/tool-map.md 这一"按结果目标（Outcome）组织的工具地图"展开，逐一解读 Skyvern MCP 工具集的分类逻辑、每个工具的定位与适用场景，并结合skyvern/cli/mcp_tools/下的真实实现源码，说明每个工具背后的调用链、参数行为与成本特征。读完本文，你将能够像熟练的 Agent 一样，根据"快速校验、单步操作、一次性探索、会话化站点操作、可复用工作流、凭据登录"等不同目标，从数十个skyvern_*工具中一眼选出最合适的那一个，并理解何时该用 CLI、何时该用 MCP。

为什么需要一张"按结果分类"的工具地图

Skyvern 的 MCP 工具面（surface）非常庞大。skyvern/cli/mcp_tools/init.py 中注册的工具数以十计，涵盖会话管理、浏览器原语、AI 驱动动作、工作流 CRUD、凭据、调度、脚本、存储、网络检查等。如果按"工具名"记忆，很容易在面对任务时选错工具：例如该用skyvern_validate的布尔校验场景误用了昂贵的skyvern_act，或者把一次性探索任务直接做成了不可复用的一次性运行。

tool-map.md的解法是按"你想达成的结果"（Outcome）而不是"工具长什么样"来组织工具：先明确本次交互的目标形态，再在该目标下挑选工具。这与 skyvern/cli/skills/skyvern/SKILL.md 中"Step 1: Classify Your Task"的任务分类决策表一脉相承——SKILL.md 把任务分为快速校验、快速检查、已知目标单步动作、未知目标单步动作、同页多步、一次性自主尝试、多页/可复用自动化七类，而 tool-map.md 则把同样的分类思想映射到了具体的工具名上。

快速校验与结构化提取：`skyvern_validate`与`skyvern_extract`

这是工具地图的第一类目标："快速检查或提取"。

工具	用途
`skyvern_validate`	针对当前页面回答一个"是/否"问题
`skyvern_extract`	从当前页面提取结构化数据

skyvern_validate是"最便宜的 AI 选项"，专门用于布尔断言。其实现位于 skyvern/cli/mcp_tools/browser.py#L2982-L3021，核心调用是await page.validate(prompt)，返回结果中携带valid布尔值以及对应的 SDK 等价调用await page.validate(...)。它只接受一个自然语言prompt（如"登录表单是否可见"），配合可选的session_id/cdp_url定位浏览器会话。SKILL.md 指出该工具"最多 2 步、返回布尔值"，成本为 1 次 LLM 调用加截图，是所有 AI 选项中成本最低的。典型用法是作为"动作后的断言"，例如表单提交后验证skyvern validate --prompt "Was the form submitted successfully?"。

skyvern_extract用于从当前页面提取结构化数据。实现位于 skyvern/cli/mcp_tools/browser.py#L2630-L2709，核心调用为await page.extract(prompt, schema=parsed_schema, skip_refresh=True)。它比"截图后让 LLM 读图"更可靠，因为 Skyvern 的专用提取 LLM 直接解读页面。关键参数包括：

prompt：用自然语言描述要提取的内容；
schema：可选的 JSON Schema 字符串，用于强制输出结构（通过parse_extract_schema校验，非法 JSON 会返回INVALID_INPUT错误）；
verbosity：summary或full，默认值由环境变量SKYVERN_MCP_EXTRACTION_DEFAULT_VERBOSITY控制；
response_offset_chars：字符偏移量，用于在超长响应被截断后继续分页取回（配合返回的_next_offset_chars）。

从注册代码（skyvern/cli/mcp_tools/init.py#L288-L293）可以看到，skyvern_extract的注解为只读（readOnlyHint=True）、开放世界（openWorldHint=True），并包了一层response_transformed响应格式化器，失败时提示可带verbosity='full'重试以取回完整数据。在 CLI 侧对应命令为skyvern browser extract（见 cli-parity.md）。

决策要点：只需要"是/否"答案时用validate，不要用extract或act；需要"把页面变成结构化数据"时用extract，并可配合 JSON Schema 约束输出。

单步操作：`skyvern_click`、`skyvern_type`、`skyvern_select_option`与`skyvern_act`

第二类目标是"执行单个动作"，工具地图将其细分为"已知目标"与"未知目标"两种情形。

工具	用途
`skyvern_click`	已知目标时点击元素
`skyvern_type`	已知目标时向元素输入文本
`skyvern_select_option`	选择下拉框选项
`skyvern_act`	不知道精确选择器时，用自然语言执行动作

确定性原语（0 次 LLM 调用）：skyvern_click、skyvern_type、skyvern_select_option属于"precision tools"（精确工具）家族，注册时带有browser_primitive与lean标签，注解为开放世界且可能产生破坏性副作用（_web_dest，见 skyvern/cli/mcp_tools/init.py#L354-L360）。它们的定位是：当提示词中已经包含选择器、id、XPath 或精确字段目标时使用，完全走确定性的 Playwright 路径，不消耗 LLM，因此最快。SKILL.md 的决策规则第 1 条明确写道："If the prompt includes a selector, id, XPath, or exact field target, use browser primitives — notact."

这些原语支持三种定位模式（SKILL.md Step 4）：

Intent（意图）：--intent "the Submit button"，由 AI 找元素；
Selector（选择器）：--selector "#submit-btn"，CSS/XPath，完全确定；
Hybrid（混合）：两者都给，选择器先缩小范围、AI 再确认。

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

自然语言动作（2-3 次 LLM 调用）：skyvern_act适用于"不知道精确选择器"的场景。实现位于 skyvern/cli/mcp_tools/browser.py#L3024-L3085，核心调用是await do_act(page, prompt, skip_refresh=True, use_economy_tree=True)。这里有两个重要的实现事实：

它不在推理中使用截图，而是使用"经济版可访问性树"（economy a11y tree）——因此对标签清晰、结构良好的元素效果很好，但对视觉复杂的目标不可靠；
它支持在一个 prompt 里链式执行多个动作，如"close the cookie banner, then click Sign In"；
它在入口处调用check_password_prompt(prompt)做守卫检查，一旦检测到密码类内容会直接返回INVALID_INPUT错误——绝不允许把密码写进act的 prompt，必须改用skyvern_login。

决策要点：目标确定（有选择器）就用原语，零成本零 AI；目标不确定且同页、标签清晰就用act；视觉复杂的目标则优先考虑skyvern_observe+skyvern_execute组合（stdio 场景）或混合定位模式。

一次性自主尝试：`skyvern_run_task`

第三类目标是"可抛弃的一次性自主试验"。

工具	用途
`skyvern_run_task`	用一个 prompt 和 URL 执行一次性的探索性自动化

skyvern_run_task的实现位于 skyvern/cli/mcp_tools/browser.py#L3088-L3204，内部调用page.agent.run_task(...)，始终使用 engine 2.0。关键参数包括prompt、url（可选，省略则用当前页）、data_extraction_schema（JSON Schema 字符串，定义要提取的数据）、max_steps、timeout_seconds（默认 180 秒，范围 10-1800）。

它的定位在注册代码里被写得很直白（skyvern/cli/mcp_tools/init.py#L207-L211）：

"Run a one-off autonomous trial via the highest-cost AI path. Not for production or reusable automations."

也就是说，它走成本最高的全自主 AI 路径，只用于"试一次看看是否可行"的探索，绝不应该用于需要反复运行或多页面的生产自动化。SKILL.md 的触发信号是"try this once"、"see if this works"。同时它也有双重安全限制：包含密码模式的 prompt 会被直接拒绝（提示改用skyvern_login），云浏览器场景下访问 localhost URL 会被拒绝。

决策要点：探索可行性用run_task；一旦任务值得重跑、调试或共享，就应升级为 workflow（见下一节）。

打开并操作一个网站：会话生命周期与组合动作

第四类目标是"打开并操作一个网站"，这是工具地图中工具数量最多的一类，因为真实网站操作几乎总是"会话 + 导航 + 动作 + 校验 + 截图"的组合。

工具	用途
`skyvern_browser_session_create`	启动一个新的浏览器会话
`skyvern_browser_session_connect`	附加到已存在的会话
`skyvern_browser_session_list`	列出活跃会话
`skyvern_browser_session_get`	获取会话详情
`skyvern_browser_session_close`	关闭一个会话
`skyvern_navigate`	导航到 URL
`skyvern_act`	执行 AI 驱动的动作
`skyvern_extract`	提取结构化数据
`skyvern_validate`	断言页面上的一个条件
`skyvern_screenshot`	截图

会话管理的五个工具实现在 skyvern/cli/mcp_tools/session.py，注册时带有session标签（skyvern/cli/mcp_tools/init.py#L271-L275）。会话是"浏览器上下文"的载体——几乎所有浏览器工具都接受可选的session_id（格式pbs_...）与cdp_url参数，底层通过get_page(session_id=..., cdp_url=...)解析目标页面。SKILL.md 强调"每个浏览器命令都需要一个会话"，并且会话状态在命令之间保持：session create之后，后续命令自动附加到当前会话，可用--session pbs_...覆盖，用完用skyvern browser session close关闭。创建会话时支持--timeout（分钟，源码中DEFAULT_TIMEOUT/MIN_TIMEOUT/MAX_TIMEOUT定义在 skyvern/schemas/browser_session_timeouts.py）、--local（用于 localhost 或自托管）、--cdp（附加到既有 Chrome）等模式。

导航与校验闭环：skyvern_navigate是纯导航原语；skyvern_screenshot用于视觉检查；skyvern_validate用于布尔断言；skyvern_extract用于取数。SKILL.md 的"Step 5: Verify"给出了标准的事后验证三板斧：

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

值得注意：注册代码中还提供了一组"组合工具"——skyvern_navigate_and_screenshot、skyvern_extract_and_screenshot、skyvern_navigate_extract_and_screenshot（skyvern/cli/mcp_tools/init.py#L313-L324），它们在一次调用里完成"导航+取数+截图"，减少 Agent 的往返次数，且都通过response_transformed包装、失败时可用verbosity='full'重试取回完整数据。

决策要点：真实站点操作请遵循"建会话 → 导航 → 动作 → 校验 → 截图"的闭环，把validate作为每次页面状态变更后的断言，避免用昂贵工具做廉价校验。

浏览器原语：`skyvern_hover`、`skyvern_scroll`、`skyvern_press_key`、`skyvern_wait`、`skyvern_evaluate`

第五类目标是"浏览器原语"——最底层的确定性操作，全部不带 AI 推理，适合在动作链中精确控制页面。

工具	用途
`skyvern_hover`	悬停在元素上
`skyvern_scroll`	滚动页面
`skyvern_press_key`	按下键盘按键
`skyvern_wait`	等待一个条件或一段时间
`skyvern_evaluate`	在页面中执行 JavaScript

从注册注解看（skyvern/cli/mcp_tools/init.py#L354-L368），hover/scroll属于非破坏性的页面状态变更（_web_mut），press_key可能提交表单或触发页面状态变化（_web_dest），wait是只读等待（_web_ro），evaluate可执行任意 JS（_web_dest），并带response_transformed包装与verbosity='full'恢复提示。

skyvern_wait在 SKILL.md 的错误恢复表中被推荐用于"元素找不到"的场景：skyvern browser wait --selector "#el" --state visible；
skyvern_evaluate是调试利器，例如skyvern browser evaluate --expression "document.querySelectorAll('table tr').length"可以在不写脚本的情况下检查页面 DOM 状态；
同族原语还包括skyvern_find（查找元素）、skyvern_drag（拖拽）、skyvern_file_upload（文件上传）、剪贴板读写、iframe 切换、标签页管理等，虽然不在 tool-map.md 的五张表中，但都属于"浏览器原语"这一类别，可在 skyvern/cli/mcp_tools/init.py 的browser_primitive标签下统一发现。

决策要点：当需要"严格可控"时，把多步流程拆成原语链（click/type/select/press-key/wait），而不是塞进一个大的actprompt；SKILL.md 的建议是"one intent per command"（每条命令只做一个意图）。

构建可复用或多页面自动化：`skyvern_workflow_*`全家桶

第六类目标是"构建可复用或多页面的自动化"，这是从一次性探索走向生产化的关键升级路径。

工具	用途
`skyvern_workflow_create`	创建工作流定义
`skyvern_workflow_list`	列出工作流
`skyvern_workflow_get`	获取工作流详情
`skyvern_workflow_run_list`	列出某个工作流的运行记录
`skyvern_workflow_update`	更新工作流
`skyvern_workflow_delete`	删除工作流
`skyvern_workflow_run`	执行工作流
`skyvern_workflow_status`	检查运行状态
`skyvern_workflow_retry`	重试一个已终止的工作流运行
`skyvern_workflow_cancel`	取消一个运行中的工作流

这些工具全部实现在 skyvern/cli/mcp_tools/workflow.py，注册时带workflow标签，且不需要浏览器（skyvern/cli/mcp_tools/init.py#L484-L508）。其中skyvern_workflow_list、skyvern_workflow_get、skyvern_workflow_run_list还分别包了size_capped或guard_definition_size做响应体积防护，避免超长工作流定义撑爆上下文。

工作流方法论的要点（来自 SKILL.md Step 4/5）：

每个步骤一个 block：把跨页面的复杂流程拆成多个 block（每个页面/步骤一个），每个 block 拥有视觉推理、验证与可复用的运行历史；
首次运行走 AI，后续运行回放缓存脚本：第一次运行时用 AI 学习路径，之后的运行回放已缓存的脚本（SKILL.md 称快 10-100 倍）；
调试时强制 AI 模式：--run-with agent可在调试时强制走 AI 路径；
状态生命周期：created -> queued -> running -> completed | failed | canceled | terminated | timed_out（对应 references/status-lifecycle.md）。

CLI 侧的标准用法：

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_workflow_run和skyvern_workflow_status的响应同样经过response_transformed包装（格式化工具名为format_workflow_response），失败时提示用返回的run_id配合verbosity='full'重试以恢复完整运行输出。

决策要点：任务跨多页、需要定时/重复执行、或明确要求"搭建自动化"时，用 workflow 而非run_task；用block schema与block validate在创建前完成 block 定义的正确性检查。

工作流 Block 工具：`skyvern_block_schema`与`skyvern_block_validate`

第七类目标是"工作流 Block 的发现与校验"，服务于 workflow 构建的前置环节。

工具	用途
`skyvern_block_schema`	获取某种 block 类型的 schema
`skyvern_block_validate`	校验 block 定义

这两个工具注册在block_discovery标签下，均为只读、无需浏览器（skyvern/cli/mcp_tools/init.py#L442-L447），与skyvern_workflow_knowledge、skyvern_code_block_lint、skyvern_code_block_synthesize、skyvern_trajectory_get并列。它们在 skyvern/cli/mcp_tools/blocks.py 中实现。

CLI 侧对应命令为skyvern block schema --type navigation与skyvern block validate --block-json @block.json（见 SKILL.md 的 Workflow Quick Reference）。典型工作流是：先用block schema发现某类型（如navigation、extraction）的字段结构，再按结构编写 block 定义，最后在创建 workflow 前用block validate校验，把错误挡在创建之前。

凭据操作：`skyvern_credential_*`与`skyvern_login`

最后一类目标是"操作凭据"，其核心原则是：永远不要通过type或act输入密码，一律使用已存储的凭据（SKILL.md 决策规则第 6 条）。

工具	用途
`skyvern_credential_list`	列出已存储的凭据
`skyvern_credential_get`	获取凭据详情
`skyvern_credential_delete`	删除凭据
`skyvern_login`	在浏览器会话中使用凭据登录

凭据工具的实现在 skyvern/cli/mcp_tools/credential.py，注册时带credential标签、无需浏览器（skyvern/cli/mcp_tools/init.py#L454-L456）。同族还包含 1Password（skyvern_onepassword_*）与 Bitwarden（skyvern_bitwarden_*）的配置与条目列举工具，SKILL.md 补充支持azure_vault提供方，凭据类型包括password、credit_card、secret。

skyvern_login实现在 skyvern/cli/mcp_tools/browser.py#L3216 起，入口处有一张_CREDENTIAL_REQUIRED_FIELDS映射表，按credential_type校验必填字段：skyvern类型需要credential_id，bitwarden需要bitwarden_item_id，onepassword需要onepassword_vault_id+onepassword_item_id，azure_vault需要 vault 名称与用户名/密码 key。登录完成后照例用validate断言登录态、用screenshot留证。

CLI 侧的标准登录流程：

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

决策要点：需要登录时，先credential_list找到凭据 ID，再browser session create+navigate+login，之后用validate --prompt "Is the user logged in?"校验。任何把密码写进 prompt 的尝试都会被act与run_task的守卫逻辑直接拦截。

贯穿始终的两条决策主线

综合 tool-map.md 与 SKILL.md，可以把工具选择收敛为两条主线：

主线一：按"结果形态"分层。快速校验用validate；取数用extract；已知目标单步用原语（click/type/select）；未知目标单步用act；一次性探索用run_task；多页/可复用/可调度用 workflow；登录一律走凭据 +login。

主线二：按"成本与确定性"权衡。原语类工具 0 次 LLM 调用（确定性 Playwright，最快）；validate约 1 次 LLM 加截图（最便宜的 AI 选项）；act约 2-3 次 LLM、无截图（经济版可访问性树）；run_task走最高成本的自主 AI 路径；workflow 每个 block 都有视觉推理与验证（N 次 LLM + 截图），但换来可复用、可调试、可回放脚本的生产能力。

如果使用 MCP 而非 CLI，还需要留意 SKILL.md 中的 MCP 提示：同页多步 UI 工作在 stdio 场景优先observe + execute（ref 跨调用保持），托管无状态 HTTP 场景则优先selector/intent参数（跨调用的 ref 不生效）。CLI 与 MCP 的对应关系可参考 references/cli-parity.md，其给出的公共映射为：skyvern browser navigate -> skyvern_navigate、skyvern browser act -> skyvern_act、skyvern browser extract -> skyvern_extract、skyvern workflow run -> skyvern_workflow_run、skyvern credential list -> skyvern_credential_list——CLI 适合本地操作者工作流，MCP 工具适合 Agent 驱动的集成场景。

Skyvern 工具地图（Tool Map）：按目标场景精准选用浏览器自动化工具