Skyvern CLI 与 MCP 能力对齐指南CLI/MCP 命令映射与 Agent 感知设计【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvernSkyvern 为浏览器自动化提供两套互补的交互入口本地终端里的skyvernCLI 与供 AI 助手调用的 MCPModel Context Protocol工具集。本文以 cli-parity.md 为核心梳理二者在核心命令上的映射关系并深入拆解 CLI 为 AI Agent 设计的Agent 感知特性——结构化 JSON 输出、非交互模式、确认跳过与命令发现机制最后从 commands/browser.py、mcp_tools/browser.py 与 commands/_output.py 等源码出发还原这些特性的底层实现。读完本文你将能在一套命令心智模型下自由切换 CLI 与 MCP并让任意 Agent 或 CI 流水线稳定、可解析地驱动 Skyvern。一、为什么需要 CLI/MCP 对齐Skyvern 的核心能力是用 AI 驱动浏览器完成任务而它暴露给开发者的方式有三种REST API、本地 CLI 与 MCP 服务器。其中 CLI 与 MCP 的目标用户高度重叠——都是把浏览器自动化交给程序或 Agent 执行——因此二者在命令设计上刻意保持一一对应。用 cli-parity.md 的话说Use CLI for local operator workflows and MCP tools for agent-driven integrations.CLI 面向本地操作员工作流MCP 工具面向 Agent 驱动的集成。这句话界定了选择边界CLI适合开发者在终端里亲自调试、验证、运行本地操作流程配合 Bash 脚本做自动化MCP适合把浏览器能力嵌入 Claude、Cursor、Windsurf 等 AI 编程助手的工具调用循环中。从仓库结构看这两套接口并非各自独立实现而是共享同一套核心执行逻辑commands/browser.py 中定义的 CLI 命令如navigate、act、extract见第 1075、1613、1647 行与 mcp_tools/browser.py 中的 MCP 工具都调用 core/browser_ops.py 中的do_navigate、do_act、do_extract等底层操作函数。对齐因此不仅是命名一致更是行为、状态与输出格式层面的实质一致。二、常用命令映射表cli-parity.md 给出了五组最常见的一一映射CLI 命令MCP 工具用途skyvern browser navigateskyvern_navigate导航到指定 URLskyvern browser actskyvern_act用自然语言指令执行浏览器动作skyvern browser extractskyvern_extract按 JSON Schema 结构化抽取页面数据skyvern workflow runskyvern_workflow_run运行工作流skyvern credential listskyvern_credential_list列出已保存的凭据这些映射在 mcp_tools/README.md 的 Tools 一节得到了完整印证浏览器动作类工具skyvern_act、skyvern_navigate、skyvern_click、skyvern_type等、数据抽取与校验类工具skyvern_extract、skyvern_validate、skyvern_evaluate、凭据类工具skyvern_credential_list、skyvern_login等与工作流类工具skyvern_workflow_create、skyvern_workflow_run等全部在列。需要说明两点扩展细节映射不止这五组。MCP 端共有 75 个工具覆盖标签页/iframe 管理skyvern_tab_*、skyvern_frame_*、网络与控制台检查skyvern_network_*、skyvern_console_messages、skyvern_har_*、浏览器状态与存储skyvern_state_save/load、skyvern_clipboard_*、缓存脚本skyvern_script_*等更广的范围。本文给出的五组是二者在常用操作上的精确对齐点。同一语义多种入口。例如登录能力CLI 侧通过skyvern browser login --url ... --credential-id ...使用MCP 侧则暴露为skyvern_login两者共享 mcp_tools/browser.py 中skyvern_login的实现——CLI 命令模块通过from skyvern.cli.mcp_tools.browser import skyvern_login as tool_login直接复用了它见 commands/browser.py。这从源码层面印证了对齐的实质一套实现双入口。三、Agent 感知 CLI为程序调用而设计原文档的核心论断是The CLI supports structured JSON output and non-interactive mode for AI agentsCLI 为 AI Agent 提供结构化 JSON 输出与非交互模式。这组特性在 cli-parity.md 中以表格形式列出特性CLI 标志环境变量结构化 JSON 输出任意命令加--json-非交互模式-SKYVERN_NON_INTERACTIVE1或CItrue跳过确认--yes或--force-命令发现skyvern capabilities --json-逐一展开说明其设计意图与使用方式。3.1 结构化 JSON 输出--jsonAgent 无法可靠地读懂人类友好的表格文本因此所有命令都支持--json标志输出可程序化解析的 JSON。例如skyvern browser navigate --url https://example.com --json skyvern browser extract --prompt Extract all prices --schema {type:object,...} --json skyvern workflow status --run-id wr_789 --json skyvern credential list --json在源码层面这一机制由 commands/_output.py 统一承载output()与output_error()在json_mode为真时会将结果封装为统一信封写入 stdoutcommands/_output.pyemit_tool_result()则直接透传 MCP 工具结果并补齐信封默认字段commands/_output.py。这意味着无论是 CLI 原生命令还是复用 MCP 实现的命令JSON 输出的结构都是一致的。3.2 非交互模式SKYVERN_NON_INTERACTIVE1/CItrueAgent 或 CI 无法响应交互式提示如确认对话框、凭据输入。设置SKYVERN_NON_INTERACTIVE1或CItrue后CLI 会抑制所有交互提示此时所有必需参数都必须通过标志或环境变量显式传入任何缺失都会在启用--json时以 JSON 错误返回而非等待用户输入。export SKYVERN_NON_INTERACTIVE1 skyvern browser act --prompt Click Sign In --json配合 agent-mode.md 中强调的凭据安全实践机密永远通过环境变量传入而非命令行标志标志在ps和/proc/*/cmdline中可见。可用环境变量包括SKYVERN_CRED_PASSWORD、SKYVERN_CRED_TOTP、SKYVERN_CRED_CARD_NUMBER、SKYVERN_CRED_CVV、SKYVERN_CRED_SECRET_VALUE、SKYVERN_CRED_USERNAME等且应在命令执行前先export避免写入 shell 历史。3.3 跳过确认--yes/--force删除凭据、关闭会话等破坏性操作默认要求确认。在非交互场景下用--yes或--force显式跳过skyvern credentials delete cred_abc123 --yes --json skyvern browser session close --force3.4 命令发现skyvern capabilities --jsonAgent 需要在不读文档的前提下知道CLI 能做什么capabilities命令即为此而生采用**渐进式披露progressive disclosure**策略控制 token 消耗skyvern capabilities --json # 顶层命令 直接子命令约 2K tokens skyvern capabilities workflow --json # 只看 workflow 命令组 skyvern capabilities --depth 0 --json # 仅命令名约 500 tokens skyvern capabilities --depth 3 --json # 完整命令树约 20K tokens skyvern capabilities --no-json # 人类可读输出其实现位于 commands/init.py 的capabilities命令第 138 行起默认depth1返回顶层命令与直接子命令--depth支持 0 到 5 的递归深度也可传入子命令名过滤范围。这套设计让 Agent 可以先用低 token 的概览决定方向再按需深入。四、统一 JSON 信封Agent 解析协议所有--json响应遵循同一信封结构cli-parity.md 原文{schema_version, ok, action, data, error, warnings, browser_context, artifacts, timing_ms}字段语义如下字段类型说明schema_versionstring信封协议版本当前为1.0常量ENVELOPE_SCHEMA_VERSION见 commands/_output.pyokboolean命令是否成功失败时配合error使用actionstring本次执行的动作标识如navigate、act、workflow_rundataany命令结果主体成功时的负载errorobject | null失败信息含message与hint字段warningsarray警告列表默认[]browser_contextobject | null浏览器上下文信息会话模式、会话 ID 等artifactsarray | null产生的工件截图、文件等timing_msobject | null各阶段耗时毫秒用于性能观察在 core/result.py 中可以看到该信封在结果模型层的完整定义browser_context默认BrowserContext(modenone)timing_ms默认为空字典而 commands/_output.py 在输出前会用setdefault补齐warnings、browser_context、artifacts、timing_ms等默认值保证即使底层结果缺少某字段Agent 拿到的 JSON 也始终形状稳定。Agent 侧的标准消费范式# 判断成功 skyvern workflow status --run-id wr_789 --json | jq .ok # 提取数据主体 skyvern browser extract --prompt ... --schema {...} --json | jq .data # 读取失败提示 skyvern browser act --prompt ... --json | jq .error一个实用细节capabilities命令的--json默认开启--json/--no-json而其他命令默认输出人类可读表格需显式加--json。Agent 若要长期稳定解析应在每次调用中显式声明--json不依赖默认值。五、选择指南与组合实践5.1 何时用 CLI何时用 MCP场景推荐入口理由本地调试浏览器自动化流程CLI命令即脚本配合--json可管道化CI/CD 流水线定时执行CLI SKYVERN_NON_INTERACTIVE1无交互、可跳过确认、输出稳定把浏览器能力嵌入 Coding AgentMCP工具即函数Agent 可直接调用 75 工具多页可复用自动化两者皆可底层一致CLIworkflow run⇄ MCPskyvern_workflow_run5.2 一条 Agent 感知的完整命令链以本地操作员 结构化输出为例串联全部 Agent 感知特性export SKYVERN_NON_INTERACTIVE1 # 1. 发现能力可选供 Agent 规划 skyvern capabilities --depth 0 --json # 2. 创建会话并执行 skyvern browser session create --timeout 30 --json skyvern browser navigate --url https://example.com --json skyvern browser extract \ --prompt Extract all product names and prices \ --schema {type:object,properties:{items:{type:array}}} \ --json | jq .data # 3. 校验与清理 skyvern browser validate --prompt Was the form submitted? --json skyvern browser session close --force --json5.3 深入阅读cli-parity.mdCLI/MCP 映射与 Agent 感知特性本文核心文档agent-mode.mdAgent 模式完整实践发现、非交互、凭据安全、结构化输出SKILL.mdCLI 任务分类决策规则与命令速查commands/browser.pyCLI 浏览器命令实现mcp_tools/browser.pyMCP 浏览器工具实现mcp_tools/README.mdMCP 服务器完整工具清单与各客户端接入配置commands/_output.pyJSON 信封的构造与补齐逻辑commands/init.pycapabilities命令发现实现core/browser_ops.pyCLI 与 MCP 共享的底层浏览器操作tool-map.md按结果分类的完整工具清单结语Skyvern 的 CLI 与 MCP 不是两套割裂的接口而是同一套浏览器自动化能力在本地操作与Agent 集成两个场景下的双入口。理解 cli-parity.md 中的映射表你就能以一套命令心智模型自由切换掌握--json统一信封、SKYVERN_NON_INTERACTIVE非交互模式与skyvern capabilities发现机制你就能让任何 Agent 和 CI 流水线以稳定、可解析、可观测的方式驱动 Skyvern 完成真实世界的浏览器任务。【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考