Skyvern 开发指南CLI 命令、架构剖析与工程实践全解析【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern导读本文以仓库根目录 CLAUDE.md 为骨架系统梳理 Skyvern一个用 LLM 与计算机视觉驱动浏览器自动化的开源平台的日常开发命令、核心架构分层、数据流转链路、LLM 配置与工程规范。你将掌握从依赖安装、服务启停、数据库迁移到前后端调试、代码质量检查的完整工作流并理解 Agent 系统、浏览器引擎与工作流引擎在源码中的真实落点可直接用于在本地搭建、调试和扩展 Skyvern。一、为什么开发者需要这样一份指南Skyvern 是一个浏览器自动化平台核心思路是用 LLM 和计算机视觉与网站交互用户描述任务例如填表并提交下载发票系统规划动作、操作浏览器、校验结果。对贡献者或二次开发者而言这份指南的价值在于三点一条命令打通全栈skyvern run all同时拉起后端 API 与前端 UI配合quickstart自动完成数据库初始化降低环境搭建门槛架构边界清晰CLI 层、Agent 层、浏览器引擎层、服务层、SDK 层各司其职改代码前能快速定位归属模块规范内建Ruff、mypy、pytest、pre-commit 等工具链已在 pyproject.toml 中配置完毕按既定命令即可通过质量闸门。下文所有命令均以当前仓库Python 3.11、Node.js、UV 管理依赖、PostgreSQL 数据库为运行前提。二、开发命令速查后端、前端与数据库2.1 Python 后端命令命令作用源码落点uv sync安装全部 Python 依赖pyproject.tomlskyvern run all同时启动后端 API 与 UIrun_commands.py 中run_allskyvern run server仅启动后端 API 服务run_commands.py 中run_serverskyvern run ui仅启动前端 UIrun_commands.py 中run_uiskyvern status检查 API / UI / PostgreSQL 运行状态status.pyskyvern stop all停止全部服务8000/8080/9090 端口stop_commands.py 中stop_allskyvern quickstart首次安装向导含 DB 迁移quickstart.pyrun server背后的实现该命令最终通过 uvicorn 加载skyvern.forge.api_app:create_api_app工厂函数并绑定settings.PORT默认 8000。值得注意的实现细节默认绑定地址因平台而异Windows 上回退到127.0.0.1其余平台为0.0.0.0相关逻辑见 run_commands.py 中的_default_host()事件循环固定使用asyncio并启用websockets-sansio的 WebSocket 实现这是为了避免 uvloop 在连接取消场景下双重关闭复用文件描述符的已知问题端口冲突时_handle_port_conflict会先探测占用进程交互式终端询问是否强制结束或直接传--force。run all/run dev的差异run all通过start_services见 cli/utils.py在前台并行拉起前后端run dev则以后台守护进程方式启动并立即返回终端控制权适合持续开发场景停止时统一使用skyvern stop all。status如何判定组件存活见 status.py通过socket.create_connection探测 8000API可被PORT环境变量覆盖、8080UI、5432PostgreSQL三个端口支持--json输出便于脚本解析。2.2 代码质量与测试命令作用ruff check/ruff format静态检查与格式化mypy skyvern类型检查pytest tests/运行测试支持 asyncpre-commit run --all-files提交前全量钩子检查这些工具在 pyproject.toml 中均有明确配置Ruff 行宽 120、目标 Python 3.11mypy 启用了 SQLAlchemy 插件sqlalchemy.ext.mypy.pluginpre-commit作为开发依赖被固定在 4.6.0 以下。仓库测试分布在 tests/unit_tests/ 与 tests/unit/ 等目录运行入口为仓库根 pytest.ini 与 conftest.py。2.3 前端命令在 skyvern-frontend/ 目录内执行命令作用npm install安装前端依赖npm run dev启动 Vite 开发服务器npm run buildtsc --noEmit类型检查后执行vite build产物构建npm run lintESLint 检查--max-warnings 0零容忍npm run formatPrettier 全量格式化从 skyvern-frontend/package.json 可以看到更完整的脚本面start优先使用预构建的dist.template包做运行时注入并跳过重建否则执行npm run serve与 artifact 服务start-local则组合npm run dev与本地 artifact 服务器是skyvern run ui-dev的底层命令。2.4 数据库管理# 升级到最新 schema alembic upgrade head # 基于模型变更自动生成迁移脚本 alembic revision --autogenerate -m descriptionSkyvern 的迁移脚本集中在 alembic/versions/迁移引擎配置见 alembic/env.py 与 alembic.ini。值得注意的是skyvern quickstart与skyvern init在本地模式下会通过migrate_db()见 skyvern/utils/init.py自动执行迁移无需手工运行 alembic。三、架构总览五大核心组件CLAUDE.md 将 Skyvern 架构概括为用 LLM 分析截图规划动作、由浏览器引擎执行动作的自动化平台。其组件分层如下组件源码目录职责Agent 系统skyvern/forge/agent.pyLLM 驱动的智能体循环负责网页导航与任务执行公共库skyvern/library/面向用户的from skyvern import Skyvern接口及 SDK 风格封装浏览器引擎skyvern/webeye/基于 Playwright 的浏览器自动化 计算机视觉工作流引擎skyvern/services/编排多步骤复杂工作流API 层skyvern/forge/FastAPI REST API 与 WebSocket 支持3.1 Agent 系统智能体循环的核心skyvern/forge/agent.py 是仓库中体量最大的核心模块约 9000 行。从导入面可以清晰看到它的能力全景通过LLMAPIHandlerFactory、LLMCaller与LLMConfigRegistry管理多厂商模型调用通过skyvern.forge.prompts的提示词引擎驱动决策通过 Playwright 的Page对象执行浏览器动作同时处理 TOTP 验证码、下载文件、截图、失败分类failure_classifier与 OpenTelemetry 追踪等横切能力。3.2 公共库一行代码启动本地 SDKskyvern/library/skyvern.py 中的Skyvern类继承自生成的异步客户端AsyncSkyvern对外提供两种模式# 云模式连接 Skyvern Cloud需要 API Key skyvern Skyvern(api_keyyour-api-key) # 本地/嵌入式模式先运行 skyvern quickstart skyvern Skyvern.local()随后既可启动本地浏览器launch_local_browser(headlessFalse)也可使用云端浏览器并把 AI 任务与直接浏览器控制混用在同一会话browser await skyvern.launch_local_browser(headlessFalse) page await browser.get_working_page() await page.agent.run_task(Fill out the form and submit it) # 也可以先手动导航再让 AI 处理登录 await page.goto(https://example.com) await page.agent.login(credential_typeCredentialType.skyvern, credential_idcredential.credential_id) await page.click(#invoices-button)3.3 关键目录速查skyvern/forge/agent.py skyvern/forge/agent_functions.pyLLM 驱动的网页交互智能体循环skyvern/library/公开Skyvern类与库级 SDK 封装skyvern/webeye/浏览器自动化、DOM 抓取、动作执行skyvern/forge/FastAPI 服务器、API 端点、请求处理skyvern/forge/sdk/内部 SDKDB、路由、schema、工作流、copilot、执行器、缓存skyvern/services/任务、工作流、浏览器会话的业务逻辑skyvern/cli/命令行接口本指南第二节所有命令的源码所在skyvern/client/生成的 Python 客户端 SDKskyvern-frontend/基于 React 的任务管理与监控 UIalembic/数据库迁移脚本。四、工作流系统与数据流转4.1 工作流四要素CLAUDE.md 将工作流系统归纳为四个概念Blocks块模块化组件如导航、信息提取、校验、循环等Parameters参数在块之间传递的动态值Runs运行工作流的执行实例Browser Sessions浏览器会话跨工作流步骤持久化的浏览器状态。这些概念在 skyvern/services/ 与 skyvern/forge/sdk/ 中有大量实现落点alembic/versions/ 中如introduce_workflow_run_blocks、add_workflow_run_id_to_workflow_等迁移脚本也从数据模型层面印证了 block、workflow run、browser session 之间的关联。4.2 数据流五步链路用户通过 UI 或 API 创建任务 / 工作流Agent 系统基于截图分析用 LLM 规划动作序列浏览器引擎通过 Playwright 执行动作结果被采集、处理并存储工作流编排器管理多步骤序列。这条链路对应了 agent.py规划、webeye执行、services编排与持久化三个层次的协作。五、环境搭建与 LLM 配置5.1 环境前提Python 3.11pyproject.toml 限定3.11,3.15Node.jsUV 管理 Python 依赖PostgreSQLDocker 或本地安装均可浏览器依赖通过 Playwright 安装。5.2 LLM 配置环境变量与 init 向导LLM 配置有两种途径直接写环境变量或运行交互式skyvern init向导。核心变量如下变量含义LLM_KEY指定使用哪个模型主模型SECONDARY_LLM_KEY轻量级 Agent 操作使用的副模型支持范围包括 OpenAI、Anthropic、Azure OpenAI、AWS Bedrock、Gemini、Ollama。从 llm_setup.py 的源码看向导实际覆盖了比 CLAUDE.md 更多的前端OpenAI、xAI Grok、Anthropic、Azure、Gemini、Yutori Navigator、Ollama 共七类 provider每个 provider 通过ENABLE_*开关 *_API_KEY或 Azure 的 deployment/base/version 组合、Ollama 的OLLAMA_SERVER_URL/OLLAMA_MODEL/OLLAMA_SUPPORTS_VISION写入 .env最终把用户选择的模型名写入LLM_KEY。向导会自动生成一份完整的 .env 默认值包括ENVlocal、BROWSER_TYPEchromium-headful、BROWSER_STREAMING_MODEcdp、MAX_SCRAPING_RETRIES0、BROWSER_ACTION_TIMEOUT_MS5000、MAX_STEPS_PER_RUN50、LOG_LEVELINFO、PORT8000、DATABASE_STRINGpostgresqlpsycopg://skyvernlocalhost:5432/skyvern等。本地初始化流程还依次完成PostgreSQL 启动可--no-postgres跳过、数据库迁移、本地组织 API Key 生成、浏览器模式配置chromium-headful / chromium-headless / cdp-connect、SKYVERN_BASE_URLhttp://localhost:8000写入以及可选的 MCP 服务器配置。5.3 环境文件作用域CLAUDE.md 未展开、但源码中非常关键的一点Skyvern 支持三档后端环境文件作用域见 skyvern/utils/env_paths.pylegacy/current./.env自托管本地模式默认EnvIntent.SERVER只读取该作用域project./.skyvern/.env项目级EnvIntent.LOCAL默认写入位置global~/.skyvern/.env用户级EnvIntent.CLOUD默认写入位置。读取优先级可被SKYVERN_ENV_FILE环境变量整体覆盖各意图的读取顺序定义在_READ_SCOPE_ORDER中。这意味着同一台机器上云端 CLI 配置与自托管本地配置可以并存互不干扰。六、测试策略与代码风格6.1 测试分层单元测试位于 tests/unit_tests/另有 tests/unit/ 目录仓库根 pytest.ini 定义了收集规则集成测试依赖浏览器自动化环境使用带 async 支持的 pytestpytest-asyncio见 pyproject.toml dev 依赖组。6.2 代码风格约定Python 侧Ruff 负责 lint 与 format配置于 pyproject.toml行宽 120target-version py311TypeScript 侧ESLint Prettier配置于 skyvern-frontend/行宽统一 120 字符强制使用类型注解与 async/await 模式——这一点在 pyproject.toml 中通过 mypy 的 SQLAlchemy 插件与严格依赖锁定sqlalchemy[mypy]得到保障。七、从 CLAUDE.md 到实战一条可执行的开发闭环综合以上内容一次典型的本地开发闭环是# 1. 安装依赖Python 前端 uv sync cd skyvern-frontend npm install cd .. # 2. 首次初始化数据库 LLM 浏览器 MCP skyvern quickstart # 或更细粒度skyvern init # 3. 启动服务 skyvern run all # 前后端并行或 skyvern run server / skyvern run ui # 4. 日常检查 skyvern status # 各组件健康度 skyvern stop all # 停止服务 # 5. 改代码后的质量闸门 ruff check ruff format mypy skyvern pytest tests/ pre-commit run --all-files # 6. 数据库变更 alembic revision --autogenerate -m describe your change alembic upgrade head需要提醒的边界与限制端口约定API 默认 8000、UI 默认 8080、PostgreSQL 默认 5432skyvern status与skyvern stop all均按此约定工作本地 quickstart 与 Docker Compose 会各自创建 Postgres宿主 5432 端口同一时刻只能被一个容器占用切换方案前需清理旧容器quickstart 完成时终端会给出明确提示若在仓库源码之外以 pip 安装方式使用自托管服务路径需要skyvern[server]extrapip install skyvern[server]嵌入式本地 SDK 需要skyvern[local]纯云端 API 则只需pip install skyvernCLAUDE.md 面向 Claude Code 等编码代理设计本文所整理的命令与源码映射同样适用于人类开发者手工操作可直接作为团队 onboarding 手册使用。【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考