项目定位与核心价值

Skyvern 是一款基于 LLM 与计算机视觉的浏览器自动化开源项目，定位是为开发者和业务人员提供面向任意网站的智能化工作流执行能力。项目核心解决了传统基于 DOM/XPath 的自动化脚本"脆弱、易随前端布局变化而失效"的痛点，转而依赖视觉大模型理解网页结构并执行交互动作。

根据 README.md，项目同时提供两层能力：面向开发者的 Playwright 兼容 SDK，以及面向非技术用户的可视化无代码工作流构建器。开源版本采用 AGPL-3.0 协议发布，包含全部核心逻辑，仅反爬虫相关能力保留在商业云服务中。

资料来源：README.md:1-40

整体架构

项目由多个协同工作的子模块组成。下图展示了核心组件之间的关系：

flowchart TB
    A[用户层<br/>前端 UI / CLI / API] --> B[Skyvern Core<br/>Python 主服务]
    B --> C[LLM 路由<br/>api_handler_factory.py]
    B --> D[浏览器执行引擎<br/>Playwright 兼容]
    B --> E[工作流引擎<br/>Block DAG]
    C --> F[OpenAI / Anthropic / Gemini<br/>等视觉模型]
    D --> G[目标网站]
    E --> H[任务/工作流存储]
    I[MCP Server] -.connect.-> A
    J[Skills 包] -.辅助.-> A

skyvern/forge/sdk/api/llm/api_handler_factory.py 中的 LLMAPIHandlerFactory 负责统一调度不同 LLM 供应商，并在调用前根据模型能力（如是否支持 litellm.supports_reasoning）动态调整 thinking budget 与推理预算。

资料来源：skyvern/forge/sdk/api/llm/api_handler_factory.py:1-80

关键子系统

工作流与 Block 类型系统

Skyvern 的工作流采用 DAG（Directed Acyclic Graph）模型，由多个 Block 通过 next_block_label 串联而成。从 skyvern-ts/client/src/api/types/WorkflowDefinitionYamlBlocksItem.ts 可以看到，Block 类型已扩展到 20 余种，涵盖 Action、Code、Conditional、Extraction、ForLoop、WhileLoop、TaskV2、Validation、SendEmail、UploadToS3 等，分别对应点击交互、代码执行、条件分支、数据抽取、循环控制、任务封装、结果校验、消息通知与文件上传等场景。这种"块即能力"的设计使复杂工作流的构建既灵活又可声明化。

资料来源：skyvern-ts/client/src/api/types/WorkflowDefinitionYamlBlocksItem.ts:1-60

MCP 与 Skills 工具链

integrations/mcp/README.md 描述了 Skyvern 的 Model Context Protocol（MCP）服务器，它允许 Claude、Cursor、Windsurf 等 AI 编程助手直接控制浏览器，完成表单填写、文件下载、信息搜集等任务。skyvern/cli/mcp_tools/README.md 进一步指出，MCP 工具集已超过 75 个，覆盖浏览器会话生命周期、AI 行为、精度原语、一次性任务、凭据管理与工作流 CRUD 等方面。

配套的 skyvern/cli/skills/README.md 则提供针对编码代理的"技能包"，包含 qa、smoke-test、testing 三个场景：qa 用于基于 git diff 的前端变更回归测试，smoke-test 用于 CI 烟雾测试，testing 用于部署健康检查。

资料来源：integrations/mcp/README.md:1-30、skyvern/cli/mcp_tools/README.md:1-25、skyvern/cli/skills/README.md:1-30

前端与多端接入

skyvern-frontend/README.md 展示了基于 Vite 的 Web 前端启动流程：通过 VITE_SKYVERN_API_KEY 连接 Skyvern Cloud，并支持开发模式、生产构建与本地预览。结合 TypeScript 客户端（skyvern-ts），Skyvern 形成覆盖 Python 服务端、Node SDK、Web UI、MCP 协议的完整生态。

资料来源：skyvern-frontend/README.md:1-30

社区关注与版本演进

当前社区最关注的议题集中在模型可扩展性与执行性能上：用户希望支持 OpenRouter 等多模型聚合网关（Issue #991）、本地 Ollama 与 Llama 3 集成（Issue #239）、跨平台快速上手（Issue #68），以及减少桌面端元素以降低成本（Issue #51）和优化登录后表单填写等长链路任务速度（Issue #4375）。最新发布版本 v1.0.43（提交 2a4a20c05）修复了 Copilot 代码绑定、任务 V2 中 credit 数据捕获以及元素树抓取硬化等问题，表明项目正持续打磨稳定性与可观测性。

许可证与遥测

Skyvern 默认收集基础使用统计以辅助产品迭代，可通过设置 SKYVERN_TELEMETRY=false 环境变量关闭。开源仓库以 AGPL-3.0 协议发布，反爬虫相关增强功能仅在托管云服务中提供。

资料来源：README.md:30-50

See Also

• 快速入门与跨平台安装
• MCP 集成与 AI 代理桥接
• 工作流 Block 类型参考
• 前端开发与本地预览
• LLM 路由与模型配置

概述

Skyvern 的 Server 模块是整个项目的核心运行时，负责对外暴露工作流执行、任务调度、LLM 推理与浏览器自动化能力。skyvern-ts/client/src/api/types/ 下的 TypeScript 类型由 Fern 从 OpenAPI/服务端 schema 自动生成，完整描绘了 Server 所提供 API 的形状；这些类型涵盖工作流定义、块（block）配置、分支条件、参数注入等核心数据模型 WorkflowDefinitionYamlBlocksItem.ts。

Server 同时作为 MCP（Model Context Protocol）服务器运行，可被 Claude、Cursor、Windsurf 等 AI 客户端直接调用，暴露超过 75 个浏览器操作相关工具 cli/mcp_tools/README.md。

工作流块（Block）类型

Server 的工作流由一系列块组成，块之间可通过 next_block_label 显式连接形成 DAG，未指定时按顺序执行 WorkflowDefinitionYamlBlocksItem.ts。主要块类型包括：

每个块共享通用字段 label、output_parameter、continue_on_failure、model、disable_cache、ignore_workflow_system_prompt、next_loop_on_failure 与 parameters，便于复用与模板化 PrintPageBlock.ts。

分支条件与 LLM 集成

Server 当前的分支判定支持两种条件类型：自然语言描述（PromptBranchCriteria，由 LLM 解释）和 Jinja2 模板表达式（JinjaBranchCriteria，由服务端模板引擎求值）PromptBranchCriteria.ts JinjaBranchCriteria.ts。

LLM 调用由 LLMAPIHandlerFactory 统一管理，并在 v1.0.43 中引入了对 Gemini 路由/回退模型的 reasoning 能力检测优化，以支持 thinking budget 控制 api_handler_factory.py。单元测试中可见 LLM 输出的标准动作结构：reasoning、confidence_float、action_type（如 CLICK、INPUT_TEXT）、id、text 等字段 utils_test.py。

架构总览

flowchart LR
    Client[Web UI / API Client] -->|REST| Server(Skyvern Server)
    MCPClient[Claude / Cursor / Windsurf] -->|MCP| Server
    Server --> Workflow[Workflow Engine]
    Server --> LLM[LLM API Handler]
    Server --> Browser[Browser Automation]
    Workflow --> Blocks{Block DAG}
    Blocks --> Browser
    Blocks --> LLM
    Blocks --> S3[AWS S3 / Email / HTTP]

部署与社区关注点

• 平台支持：integrations/mcp/README.md 强调 Skyvern 目前仅在 Python 3.11 环境下运行 integrations/mcp/README.md。社区长期呼吁补充 Linux/Windows 的快速开始脚本（Issue #68）。
• 模型可扩展性：社区关注通过 OpenRouter（#991）与 Ollama（#239）扩展 Server 的 LLM 后端，以降低推理成本并便于本地实验。
• 执行性能：在 task_v2 内的 navigate 块中存在 credit 数据捕获问题已在 v1.0.43（#6698）中修复，element-tree 抓取也被加固（#6697），有助于缩短 5 分钟级工作流（#4375）的运行耗时。
• MCP 集成：Server 同时作为 HTTP/streamable-http MCP 端点运行，AI 客户端可通过 x-api-key 头鉴权调用 cli/mcp_tools/README.md。

常见失败模式

• 平台兼容性：仅 Python 3.11 受官方测试支持，其它版本可能引发依赖异常。
• LLM 路由识别：自定义 Gemini 路由/回退模型（命名中含 fallback）不被 LiteLLM 识别，需在 api_handler_factory.py 中显式开启 reasoning 支持 api_handler_factory.py。
• 缓存与系统提示：disable_cache 与 ignore_workflow_system_prompt 字段需谨慎设置，否则可能导致块之间上下文不一致 UrlBlock.ts。
• 移动端布局：桌面优先的浏览器动作在移动端页面上元素更多，可能拖慢执行（社区 Issue #51）。

See Also

• Workflow 模块
• LLM 抽象与路由
• MCP 集成
• Browser 自动化引擎

概述与定位

Skyvern 的 Api 模块 是项目对外暴露的能力边界，涵盖两个相互协作的层面：其一是基于 TypeScript + Fern 自动生成的 TypeScript 客户端 SDK，其二是位于 skyvern/forge/sdk/api/llm/ 之下的服务端 LLM 调用层。该模块把"工作流编排"、"任务执行"、"浏览器会话"与"LLM 推理"统一收敛到一套类型化、可追溯的接口上。

skyvern-ts/client/src/api/types/ 下的所有类型文件头部都明确标注："This file was auto-generated by Fern from our API Definition"，说明它们源自单一 API 描述源，避免了文档与代码漂移。README.md 同时指出项目默认会上报匿名遥测（可通过 SKYVERN_TELEMETRY=false 关闭），这与 Api 模块中丰富的 Token 计量字段（如 Thought.thought_cost）形成了端到端的可观测闭环。资料来源：README.md:1-50

工作流 Block 类型体系

Api 模块的核心抽象是 Workflow Block（工作流积木）。每种 Block 都实现统一的 label / next_block_label / output_parameter / continue_on_failure 字段，从而能够串联成 DAG（有向无环图），省略 next_block_label 时默认按顺序连接。资料来源：skyvern-ts/client/src/api/types/UrlBlock.ts:1-15

下表汇总了 SDK 中关键 Block 的用途与典型字段：

所有任务型 Block 都支持 max_retries、max_steps_per_run、disable_cache、ignore_workflow_system_prompt、next_loop_on_failure 等控制位，便于在 DAG 中对失败恢复、上下文缓存、系统提示词注入等行为做精细调整。资料来源：skyvern-ts/client/src/api/types/TaskBlock.ts:1-30

分支条件则通过 PromptBranchCriteria（自然语言描述）和 JinjaBranchCriteria（Jinja2 模板）两类对象表达，二者都包含 expression 与可选 description，与 Block 一起支撑条件路由。资料来源：skyvern-ts/client/src/api/types/PromptBranchCriteria.ts:1-7

请求对象与查询能力

skyvern-ts/client/src/api/client/requests/ 目录封装了入参 DTO（数据传输对象）。以下模式在多个请求对象中重复出现，可视为 SDK 的一致约定：

• 分页：通过 page 与 page_size 组合实现，例如 GetScriptsRequest 与 GetWorkflowsRequest。资料来源：skyvern-ts/client/src/api/client/requests/GetScriptsRequest.ts:1-12
• 模糊检索：使用 search_key 进行大小写不敏感的子串匹配，匹配范围会按文件注释精确列出（如工作流检索覆盖标题、文件夹名、参数元数据）。资料来源：skyvern-ts/client/src/api/client/requests/GetWorkflowsRequest.ts:13-19
• 状态过滤：GetWorkflowRunsByIdRequest 允许按 status（数组或单值）筛选运行，并可结合 error_code 做错误码精确匹配。资料来源：skyvern-ts/client/src/api/client/requests/GetWorkflowRunsByIdRequest.ts:11-19
• 软删除兼容：ListBrowserProfilesRequest 通过 include_deleted 控制是否返回已删除的浏览器档案。资料来源：skyvern-ts/client/src/api/client/requests/ListBrowserProfilesRequest.ts:1-16

每次 LLM 调用后，Thought 资源会保留 input_token_count、output_token_count、reasoning_token_count、cached_token_count、thought_cost、last_llm_model 等计量数据，可结合运行 ID、Block ID 进行回溯，是社区用户反馈"任务执行慢"（Issue #4375）时定位瓶颈的关键。资料来源：skyvern-ts/client/src/api/types/Thought.ts:1-20

服务端 LLM 调用编排

服务端侧，skyvern/forge/sdk/api/llm/api_handler_factory.py 负责把 Block 触发的 LLM 调用串接起来。它在发起请求前会通过 app.ARTIFACT_MANAGER.prepare_llm_artifact（或批处理模式 accumulate_screenshot_to_step_archive）将 Prompt 与截图持久化到对象存储，并在 OpenTelemetry Span 上记录 bundled 与 persist 属性，从而把"调用 → 工件 → 计费"链路打通。资料来源：skyvern/forge/sdk/api/llm/api_handler_factory.py:1-40

社区关注点（Issue #991 OpenRouter、Issue #239 Ollama）实际上都是请求在 Block 中传入的 model 字段如何被解析与路由——例如 TaskBlock、TextPromptBlock 都在类型层暴露了 model?: Record<string, unknown>，使得接入新的多模态或本地模型时只需在 api_handler_factory.py 增补解析分支，而不需要修改 SDK 表面。资料来源：skyvern-ts/client/src/api/types/TextPromptBlock.ts:1-13

常见失败模式与排障建议

1. DAG 顺序回退：若省略 next_block_label 却仍期望分支，需确认 PromptBranchCriteria 的 description 是否清晰——Jinja 条件会基于参数值评估，描述不充分会导致表达式求值失败。资料来源：skyvern-ts/client/src/api/types/JinjaBranchCriteria.ts:1-6
2. 缓存与提示词冲突：ignore_workflow_system_prompt 与 disable_cache 同时为 true 时，每次 Block 都会重新提示 LLM，是 Issue #4375 报告的执行变慢的常见诱因，建议仅在调试时打开。资料来源：skyvern-ts/client/src/api/types/NavigationBlock.ts:1-18
3. 跨平台 Quickstart：Issue #68 反馈 setup.sh 仅在 macOS 验证；Windows/Linux 用户应阅读 README.md 中"Quickstart"小节，并自行替换脚本中的 brew 步骤。
4. 遥测干扰：在 CI 中若不希望上报使用数据，记得在环境变量中显式设置 SKYVERN_TELEMETRY=false。资料来源：README.md:1-20

See Also

• 工作流 Block DSL：skyvern-ts/client/src/api/types/
• LLM 调用与遥测：skyvern/forge/sdk/api/llm/api_handler_factory.py
• 任务执行慢的优化思路：GitHub Issue #4375
• OpenRouter / Ollama 等模型接入讨论：GitHub Issue #991、#239

Pitfall Log / 踩坑日志

项目：Skyvern-AI/skyvern

摘要：发现 7 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Live browser stream stuck on about:blank in run/builder view until the Browser Sessions list is opened (self-hosted, sp…。

1. 安装坑 · 来源证据：Live browser stream stuck on about:blank in run/builder view until the Browser Sessions list is opened (self-hosted, sp…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Live browser stream stuck on about:blank in run/builder view until the Browser Sessions list is opened (self-hosted, split UI/API behind reverse proxy)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Skyvern-AI/skyvern/issues/6703 | 来源类型 github_issue 暴露的待验证使用条件。

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/Skyvern-AI/skyvern | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/Skyvern-AI/skyvern | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/Skyvern-AI/skyvern | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/Skyvern-AI/skyvern | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/Skyvern-AI/skyvern | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/Skyvern-AI/skyvern | release_recency=unknown