企业官网建设流程全解析

Skyvern CLI 与 MCP 能力对齐指南：CLI/MCP 命令映射与 Agent 感知设计

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

Skyvern 为浏览器自动化提供两套互补的交互入口：本地终端里的skyvernCLI 与供 AI 助手调用的 MCP（Model 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 给出了五组最常见的一一映射：

这些映射在 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等）全部在列。

需要说明两点扩展细节：

1. 映射不止这五组。MCP 端共有 75+ 个工具，覆盖标签页/iframe 管理（skyvern_tab_*、skyvern_frame_*）、网络与控制台检查（skyvern_network_*、skyvern_console_messages、skyvern_har_*）、浏览器状态与存储（skyvern_state_save/load、skyvern_clipboard_*）、缓存脚本（skyvern_script_*）等更广的范围。本文给出的五组是二者在"常用操作"上的精确对齐点。
2. 同一语义，多种入口。例如登录能力，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 agents"（CLI 为 AI Agent 提供结构化 JSON 输出与非交互模式）。这组特性在 cli-parity.md 中以表格形式列出：

逐一展开说明其设计意图与使用方式。

3.1 结构化 JSON 输出（--json）

Agent 无法可靠地"读懂"人类友好的表格文本，因此所有命令都支持--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为真时，会将结果封装为统一信封写入 stdout（commands/_output.py）；emit_tool_result()则直接透传 MCP 工具结果并补齐信封默认字段（commands/_output.py）。这意味着无论是 CLI 原生命令还是复用 MCP 实现的命令，JSON 输出的结构都是一致的。

3.2 非交互模式（SKYVERN_NON_INTERACTIVE=1/CI=true）

Agent 或 CI 无法响应交互式提示（如确认对话框、凭据输入）。设置SKYVERN_NON_INTERACTIVE=1或CI=true后，CLI 会抑制所有交互提示；此时所有必需参数都必须通过标志或环境变量显式传入，任何缺失都会在启用--json时以 JSON 错误返回，而非等待用户输入。

export SKYVERN_NON_INTERACTIVE=1 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 --force

3.4 命令发现（skyvern capabilities --json）

Agent 需要在不读文档的前提下知道"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 行起）：默认depth=1返回顶层命令与直接子命令；--depth支持 0 到 5 的递归深度；也可传入子命令名过滤范围。这套设计让 Agent 可以先用低 token 的概览决定方向，再按需深入。

四、统一 JSON 信封：Agent 解析协议

所有--json响应遵循同一信封结构（cli-parity.md 原文）：

{schema_version, ok, action, data, error, warnings, browser_context, artifacts, timing_ms}

字段语义如下：

在 core/result.py 中可以看到该信封在结果模型层的完整定义（browser_context默认BrowserContext(mode="none")，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

5.2 一条 Agent 感知的完整命令链

以"本地操作员 + 结构化输出"为例，串联全部 Agent 感知特性：

export SKYVERN_NON_INTERACTIVE=1 # 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 --json

5.3 深入阅读

• cli-parity.md：CLI/MCP 映射与 Agent 感知特性（本文核心文档）
• agent-mode.md：Agent 模式完整实践（发现、非交互、凭据安全、结构化输出）
• SKILL.md：CLI 任务分类决策规则与命令速查
• commands/browser.py：CLI 浏览器命令实现
• mcp_tools/browser.py：MCP 浏览器工具实现
• mcp_tools/README.md：MCP 服务器完整工具清单与各客户端接入配置
• commands/_output.py：JSON 信封的构造与补齐逻辑
• commands/init.py：capabilities命令发现实现
• core/browser_ops.py：CLI 与 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