Skyvern CLI：从环境搭建到任务编排的全流程管理指南

引言：为什么选择Skyvern CLI？

在自动化工作流日益复杂的今天，命令行工具凭借其高效、可脚本化的特性成为开发者的首选。Skyvern CLI作为Skyvern项目的核心操作入口，不仅提供了环境初始化、服务管理等基础功能，还支持工作流编排、任务监控等高级操作。本文将通过"功能场景→操作步骤→进阶技巧"的三段式框架，帮助你快速掌握Skyvern CLI的使用方法，让自动化任务管理变得简单高效。

一、环境初始化：从零开始搭建Skyvern

场景描述

当你首次接触Skyvern项目，需要在本地环境快速部署并验证核心功能时，环境初始化是第一步。这一场景适用于开发者初次上手、团队新成员加入或CI/CD环境的自动化部署。

核心命令

基础版：

skyvern quickstart

进阶版（跳过浏览器安装并仅启动API服务）：

skyvern quickstart --skip-browser-install --server-only

参数解析

• --skip-browser-install：跳过Chromium浏览器的自动安装，适用于已有浏览器环境或资源受限的场景。
• --server-only：仅启动API服务器（默认8000端口），不启动UI界面，适合服务器环境或纯后端集成。
• --no-postgres：不启动PostgreSQL容器，适用于使用外部数据库或仅测试API功能的场景。

常见问题

• Docker未运行：命令会自动检测Docker状态，如未运行将提示启动Docker。
• 端口占用：若8000端口被占用，可通过skyvern stop server停止占用进程，或使用--port参数指定其他端口。
• 初始化失败：可删除~/.skyvern目录后重新执行命令，该目录存储了Skyvern的配置和缓存文件。

实现原理：quickstart命令通过调用init_command.py中的初始化函数配置环境，再通过utils.py中的start_services函数启动Docker容器集群，包括API服务、数据库和可选的UI服务。

验证方法

执行以下命令检查服务状态：

skyvern status

若输出中包含"API Server: running on port 8000"，则表示环境初始化成功。

二、服务管理：灵活控制Skyvern服务生命周期

场景描述

在日常开发中，你可能需要根据不同需求启动或停止Skyvern的各个组件。例如，开发API功能时只需启动后端服务，而演示时则需要同时启动UI界面。

核心命令

启动所有服务：

skyvern run all

单独启动UI服务：

skyvern run ui --port 8081

停止指定端口的API服务：

skyvern stop server --port 8001

参数解析

• run all：启动API服务器（8000）、UI服务器（8080）和数据库服务。
• run server --port：指定API服务器端口，默认为8000。
• run ui --port：指定UI服务器端口，默认为8080。
• stop server --port：停止指定端口的API服务器，不指定则停止默认端口。

常见问题

• 端口冲突：使用--port参数自定义端口，如skyvern run ui --port 8081。
• 服务启动失败：检查日志文件~/.skyvern/logs/server.log获取详细错误信息。
• UI无法连接API：确保API服务器已启动，且UI的环境变量VITE_API_URL指向正确的API地址。

实现原理：服务启动通过run_commands.py中的run_server和run_ui函数实现，前者使用uvicorn启动FastAPI应用，后者通过Node.js启动Vite开发服务器。

验证方法

• API服务：访问http://localhost:8000/health，返回{"status": "healthy"}表示正常。
• UI服务：访问http://localhost:8080，能看到Skyvern控制台界面即表示启动成功。

三、工作流管理：从创建到运行的全流程控制

场景描述

工作流是Skyvern的核心功能，适用于需要按步骤执行的自动化任务，如数据爬取、表单提交等。例如，你需要创建一个工作流，自动访问新闻网站并提取头条信息。

核心命令

列出所有工作流：

skyvern workflow list --page 1 --page-size 10

运行指定工作流：

skyvern workflow run wf_12345 --parameters '{"url": "https://news.ycombinator.com"}' --title "Hacker News 头条提取"

查看工作流运行状态：

skyvern workflow status run_67890 --tasks

参数解析

• workflow list --page --page-size：分页列出工作流，便于管理大量工作流。
• workflow run <workflow_id> --parameters：传递JSON格式的参数，用于动态配置工作流。
• workflow status <run_id> --tasks：查看工作流运行详情，包括每个任务的状态。

常见问题

• 工作流ID获取：通过workflow list命令查看所有工作流及其ID。
• 参数格式错误：确保--parameters后的JSON字符串格式正确，可使用在线JSON验证工具检查。
• 工作流运行失败：使用--tasks选项查看具体任务的错误信息，定位问题所在。

实现原理：工作流管理通过workflow.py中的函数与Skyvern API交互，将用户命令转换为API请求，实现工作流的创建、运行和监控。

验证方法

运行工作流后，通过以下命令检查任务状态：

skyvern tasks list --workflow-run-id run_67890

若任务状态为"completed"，则表示工作流执行成功。

图：Skyvern工作流编辑器界面，展示了一个包含多个步骤的工作流定义

四、任务管理：精细化监控与控制

场景描述

当工作流运行出现异常时，需要查看具体任务的执行情况，定位问题原因。例如，工作流中的某个页面访问失败，需要查看该任务的详细日志。

核心命令

列出指定工作流的所有任务：

skyvern tasks list --workflow-run-id run_67890

取消正在运行的任务：

skyvern tasks cancel task_54321

参数解析

• tasks list --workflow-run-id：按工作流运行ID筛选任务，便于跟踪特定工作流的执行情况。
• tasks cancel <task_id>：取消指定任务，适用于任务卡死或不再需要执行的场景。

常见问题

• 任务ID获取：通过tasks list命令查看任务ID。
• 任务取消失败：若任务已完成，取消命令将无效，需确认任务当前状态。
• 日志查看：任务日志存储在~/.skyvern/logs/tasks/目录下，可直接查看文件获取详细信息。

实现原理：任务管理通过tasks.py中的函数调用Skyvern SDK，与API服务器交互获取任务列表和状态信息。

验证方法

取消任务后，通过tasks list命令检查任务状态是否变为"cancelled"。

五、高级功能：脚本运行与MCP服务器

场景描述

对于复杂的自动化需求，可能需要编写自定义Python脚本。例如，你需要处理工作流输出的数据并生成报表，可通过Skyvern CLI直接运行脚本。

核心命令

运行Python脚本（带命令行参数）：

skyvern run code data_processing.py -p input_file=data.csv -p output_file=report.csv

启动MCP服务器：

skyvern run mcp --port 5000

参数解析

• run code <script.py> -p：通过命令行参数传递键值对，脚本中可通过sys.argv获取。
• run code --params：传递JSON字符串参数，适合复杂数据结构。
• run mcp --port：指定MCP服务器端口，默认为5000。

常见问题

• 脚本依赖缺失：确保脚本所需的Python包已安装，可通过pip install命令安装。
• MCP服务器冲突：若5000端口被占用，使用--port参数指定其他端口。
• 脚本权限问题：确保脚本有可执行权限，或通过python script.py方式运行。

实现原理：run code命令通过run_commands.py中的run_code函数执行脚本，支持多种参数传递方式，并提供错误处理和日志记录。

验证方法

脚本运行完成后，检查输出文件是否生成；MCP服务器启动后，访问http://localhost:5000查看是否返回MCP服务状态。

实用资源

• 官方文档：README.md
• CLI源代码：skyvern/cli/
• 工作流示例：docs/cookbooks/