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, schemaparsed_schema, skip_refreshTrue)。它比截图后让 LLM 读图更可靠因为 Skyvern 的专用提取 LLM 直接解读页面。关键参数包括prompt用自然语言描述要提取的内容schema可选的 JSON Schema 字符串用于强制输出结构通过parse_extract_schema校验非法 JSON 会返回INVALID_INPUT错误verbositysummary或full默认值由环境变量SKYVERN_MCP_EXTRACTION_DEFAULT_VERBOSITY控制response_offset_chars字符偏移量用于在超长响应被截断后继续分页取回配合返回的_next_offset_chars。从注册代码skyvern/cli/mcp_tools/init.py#L288-L293可以看到skyvern_extract的注解为只读readOnlyHintTrue、开放世界openWorldHintTrue并包了一层response_transformed响应格式化器失败时提示可带verbosityfull重试以取回完整数据。在 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 4Intent意图--intent the Submit button由 AI 找元素Selector选择器--selector #submit-btnCSS/XPath完全确定Hybrid混合两者都给选择器先缩小范围、AI 再确认。例如 CLI 侧skyvern browser click --selector #submit-btn、skyvern browser type --text userco.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_refreshTrue, use_economy_treeTrue)。这里有两个重要的实现事实它不在推理中使用截图而是使用经济版可访问性树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_observeskyvern_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_schemaJSON Schema 字符串定义要提取的数据、max_steps、timeout_seconds默认 180 秒范围 10-1800。它的定位在注册代码里被写得很直白skyvern/cli/mcp_tools/init.py#L207-L211Run 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导航到 URLskyvern_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_screenshotskyvern/cli/mcp_tools/init.py#L313-L324它们在一次调用里完成导航取数截图减少 Agent 的往返次数且都通过response_transformed包装、失败时可用verbosityfull重试取回完整数据。决策要点真实站点操作请遵循建会话 → 导航 → 动作 → 校验 → 截图的闭环把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-L368hover/scroll属于非破坏性的页面状态变更_web_mutpress_key可能提交表单或触发页面状态变化_web_destwait是只读等待_web_roevaluate可执行任意 JS_web_dest并带response_transformed包装与verbosityfull恢复提示。skyvern_wait在 SKILL.md 的错误恢复表中被推荐用于元素找不到的场景skyvern browser wait --selector #el --state visibleskyvern_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而不是塞进一个大的actpromptSKILL.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配合verbosityfull重试以恢复完整运行输出。决策要点任务跨多页、需要定时/重复执行、或明确要求搭建自动化时用 workflow 而非run_task用block schema与block validate在创建前完成 block 定义的正确性检查。工作流 Block 工具skyvern_block_schema与skyvern_block_validate第七类目标是工作流 Block 的发现与校验服务于 workflow 构建的前置环节。工具用途skyvern_block_schema获取某种 block 类型的 schemaskyvern_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。同族还包含 1Passwordskyvern_onepassword_*与 Bitwardenskyvern_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_idbitwarden需要bitwarden_item_idonepassword需要onepassword_vault_idonepassword_item_idazure_vault需要 vault 名称与用户名/密码 key。登录完成后照例用validate断言登录态、用screenshot留证。CLI 侧的标准登录流程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决策要点需要登录时先credential_list找到凭据 ID再browser session createnavigatelogin之后用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 executeref 跨调用保持托管无状态 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 驱动的集成场景。延伸阅读skills/skyvern/references/quick-start-patterns.md快速上手示例、常见模式与工作流模板skills/skyvern/references/engines.md何时用 task、何时用 workflowskills/skyvern/references/schemas.md提取场景的 JSON Schema 写法skills/skyvern/references/status-lifecycle.md运行状态机与对应处理建议skyvern/cli/mcp_tools/init.py全部 MCP 工具的注册清单、标签与注解是验证本文所有工具定位的第一手依据【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考