{ "canonical_name": "Skyvern-AI/skyvern", "compilation_id": "pack_a43b63e02b164cfb9e743321dfa7aab2", "created_at": "2026-05-12T01:29:00.486888+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=skill, recipe, host_instruction, eval, preflight", "recommended_asset_types=skill, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `pip install skyvern` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "pip install skyvern", "sandbox_container_image": "python:3.12-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "llm_execute_isolated_install", "sandbox_validation_id": "sbx_36c6ca95fdf6442d8ea98357c9fe2d80" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_d1375172a837399fc326bdbc81600dd7", "canonical_name": "Skyvern-AI/skyvern", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/Skyvern-AI/skyvern", "slug": "skyvern", "source_packet_id": "phit_28dea91e651e4c9f9ed6a1d14dc69ca8", "source_validation_id": "dval_c306c31c798e4351af3292c822347541" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 local_cli的用户", "github_forks": 1997, "github_stars": 21594, "one_liner_en": "", "one_liner_zh": "", "primary_category": { "category_id": "software-development", "confidence": "medium", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:git, cli" }, "target_user": "使用 local_cli 等宿主 AI 的用户", "title_en": "skyvern", "title_zh": "skyvern 能力包", "visible_tags": [ { "label_en": "Security & Permissions", "label_zh": "安全审查与权限治理", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-security-permissions", "type": "product_domain" }, { "label_en": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Natural-language Web Actions", "label_zh": "自然语言网页操作", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-natural-language-web-actions", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_28dea91e651e4c9f9ed6a1d14dc69ca8", "page_model": { "artifacts": { "artifact_slug": "skyvern", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "pip install skyvern", "label": "Python / pip · 官方安装入口", "source": "https://github.com/Skyvern-AI/skyvern#readme", "verified": true } ], "display_tags": [ "安全审查与权限治理", "网页任务自动化", "自然语言网页操作", "节点式流程编排", "评测体系" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 local_cli的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "local_cli", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "skill, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：what ensures it’s the correct one in that context?", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_77591d02b4fa4efdb89fba55a9a7f08a | https://github.com/Skyvern-AI/skyvern/issues/5637 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：what ensures it’s the correct one in that context?", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v1.0.29", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_d8e67eb179f5406fb5af75a063639216 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.29 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release v1.0.29", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Task Execution Performance: Seeking guidance on optimizing execution speed", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_7f47a5abded54abfb766032115bfa71c | https://github.com/Skyvern-AI/skyvern/issues/4375 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Task Execution Performance: Seeking guidance on optimizing execution speed", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Multi-session VNC support for local/self-hosted deployments (Live view & Take Control)", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_8f2671eacb334774963837f8f7e8edf4 | https://github.com/Skyvern-AI/skyvern/issues/4392 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：[Feature Request] Multi-session VNC support for local/self-hosted deployments (Live view & Take Control)", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Performance bottleneck: High latency for simple form-filling workflows", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_9820831a47af4ca28ef7abcc0fd7095e | https://github.com/Skyvern-AI/skyvern/issues/4439 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Performance bottleneck: High latency for simple form-filling workflows", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Release v1.0.34", "category": "维护坑", "evidence": [ "community_evidence:github | cevd_660eece743754686b70883d67faffd46 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.34 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release v1.0.34", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Release v1.0.35", "category": "维护坑", "evidence": [ "community_evidence:github | cevd_53f24132e3214005ba1dc606965c0eb7 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.35 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release v1.0.35", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "No sandbox install has been executed yet; downstream must verify before user use.", "category": "安全/权限坑", "evidence": [ "risks.safety_notes | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | No sandbox install has been executed yet; downstream must verify before user use." ], "severity": "medium", "suggested_check": "转成明确权限清单和安全审查提示。", "title": "存在安全注意事项", "user_impact": "用户安装前需要知道权限边界和敏感操作。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Clarification on the Custom credential documentation on the Delete API with empty body", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_a5164e5767dc4b618ce1c862ed440eaa | https://github.com/Skyvern-AI/skyvern/issues/4256 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Clarification on the Custom credential documentation on the Delete API with empty body", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：GROQ error", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_fb8dab5ab6224386a6b341234a8e90be | https://github.com/Skyvern-AI/skyvern/issues/4366 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：GROQ error", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.27", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_23488c9e7f354979bdbf8e9554b4b647 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.27 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release v1.0.27", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.30", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_6929e0e36e1549e9bd95f29d1d4cfbdf | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.30 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release v1.0.30", "user_impact": "可能影响授权、密钥配置或安全边界。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 23 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：what ensures it’s the correct one in that context?。", "title": "踩坑日志" }, "snapshot": { "contributors": null, "forks": 1997, "license": "unknown", "note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。", "stars": 21594, "open_issues": 146, "pushed_at": null }, "source_url": "https://github.com/Skyvern-AI/skyvern", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "", "title": "skyvern 能力包", "trial_prompt": "# skyvern - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 skyvern 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：Skyvern 项目介绍。围绕“Skyvern 项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速开始指南。围绕“快速开始指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. page-agents：AI 代理系统。围绕“AI 代理系统”模拟一次用户任务，不展示安装或运行结果。\n5. page-tasks：任务系统。围绕“任务系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Skyvern 项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速开始指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-agents\n输入：用户提供的“AI 代理系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-tasks\n输入：用户提供的“任务系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Skyvern 项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速开始指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-agents：Step 4 必须围绕“AI 代理系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-tasks：Step 5 必须围绕“任务系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Skyvern-AI/skyvern#readme\n- .claude/skills/bump-version/SKILL.md\n- docs/skill.md\n- skyvern/cli/skills/qa/SKILL.md\n- skyvern/cli/skills/skyvern/SKILL.md\n- skyvern/cli/skills/smoke-test/SKILL.md\n- skyvern/cli/skills/testing/SKILL.md\n- README.md\n- skyvern/__init__.py\n- docker-compose.yml\n- .env.example\n- skyvern/cli/quickstart.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 skyvern 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: Clarification on the Custom credential documentation on the Delete API w（https://github.com/Skyvern-AI/skyvern/issues/4256）；github/github_issue: GROQ error（https://github.com/Skyvern-AI/skyvern/issues/4366）；github/github_issue: Task Execution Performance: Seeking guidance on optimizing execution spe（https://github.com/Skyvern-AI/skyvern/issues/4375）；github/github_issue: [Feature Request] Multi-session VNC support for local/self-hosted deploy（https://github.com/Skyvern-AI/skyvern/issues/4392）；github/github_issue: persist_browser_session flag saves sessions but never retrieves them on （https://github.com/Skyvern-AI/skyvern/issues/4390）；github/github_issue: Performance bottleneck: High latency for simple form-filling workflows（https://github.com/Skyvern-AI/skyvern/issues/4439）；github/github_issue: what ensures it’s the correct one in that context?（https://github.com/Skyvern-AI/skyvern/issues/5637）；github/github_release: Release v1.0.36（https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.36）；github/github_release: Release v1.0.35（https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.35）；github/github_release: Release v1.0.34（https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.34）；github/github_release: Release v1.0.33（https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.33）；github/github_release: Release v1.0.32（https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.32）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "Clarification on the Custom credential documentation on the Delete API w", "url": "https://github.com/Skyvern-AI/skyvern/issues/4256" }, { "kind": "github_issue", "source": "github", "title": "GROQ error", "url": "https://github.com/Skyvern-AI/skyvern/issues/4366" }, { "kind": "github_issue", "source": "github", "title": "Task Execution Performance: Seeking guidance on optimizing execution spe", "url": "https://github.com/Skyvern-AI/skyvern/issues/4375" }, { "kind": "github_issue", "source": "github", "title": "[Feature Request] Multi-session VNC support for local/self-hosted deploy", "url": "https://github.com/Skyvern-AI/skyvern/issues/4392" }, { "kind": "github_issue", "source": "github", "title": "persist_browser_session flag saves sessions but never retrieves them on ", "url": "https://github.com/Skyvern-AI/skyvern/issues/4390" }, { "kind": "github_issue", "source": "github", "title": "Performance bottleneck: High latency for simple form-filling workflows", "url": "https://github.com/Skyvern-AI/skyvern/issues/4439" }, { "kind": "github_issue", "source": "github", "title": "what ensures it’s the correct one in that context?", "url": "https://github.com/Skyvern-AI/skyvern/issues/5637" }, { "kind": "github_release", "source": "github", "title": "Release v1.0.36", "url": "https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.36" }, { "kind": "github_release", "source": "github", "title": "Release v1.0.35", "url": "https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.35" }, { "kind": "github_release", "source": "github", "title": "Release v1.0.34", "url": "https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.34" }, { "kind": "github_release", "source": "github", "title": "Release v1.0.33", "url": "https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.33" }, { "kind": "github_release", "source": "github", "title": "Release v1.0.32", "url": "https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.32" } ], "status": "已收录 13 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "", "effort": "安装已验证", "forks": null, "icon": "code", "name": "skyvern 能力包", "risk": "可发布", "slug": "skyvern", "stars": null, "tags": [ "安全审查与权限治理", "网页任务自动化", "自然语言网页操作", "节点式流程编排", "评测体系" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/Skyvern-AI/skyvern 项目说明书\n\n生成时间：2026-05-12 01:23:02 UTC\n\n## 目录\n\n- [Skyvern 项目介绍](#page-introduction)\n- [快速开始指南](#page-quickstart)\n- [系统架构设计](#page-architecture)\n- [AI 代理系统](#page-agents)\n- [任务系统](#page-tasks)\n- [工作流系统](#page-workflows)\n- [浏览器自动化](#page-browser-automation)\n- [数据库与数据模型](#page-database)\n- [凭证管理系统](#page-credentials)\n- [前端组件结构](#page-frontend)\n\n\n\n## Skyvern 项目介绍\n\n### 相关页面\n\n相关主题：[快速开始指南](#page-quickstart), [系统架构设计](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n- [skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx)\n- [skyvern-frontend/src/routes/tasks/create/SavedTaskForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/tasks/create/SavedTaskForm.tsx)\n- [skyvern-frontend/src/routes/workflows/editor/Workspace.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/editor/Workspace.tsx)\n- [skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx)\n- [skyvern/cli/mcp_tools/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/mcp_tools/README.md)\n- [skyvern/forge/sdk/api/aws.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/api/aws.py)\n
\n\n# Skyvern 项目介绍\n\n## 项目概述\n\nSkyvern 是一个开源的 **Web 自动化平台**，通过自然语言描述即可自动化执行复杂的网络任务。该项目结合了大型语言模型（LLM）和浏览器自动化技术，使非技术用户也能轻松创建和管理自动化工作流程。\n\nSkyvern 的核心功能包括：\n\n- **自然语言驱动的网页导航**：用户只需描述任务目标，Skyvern 即可自动分析网页结构并执行相应操作\n- **多步骤工作流编排**：支持创建、编辑和调度复杂的自动化工作流\n- **身份验证与凭证管理**：内置对 TOTP/2FA、Magic Link 等多因素认证的支持\n- **浏览器会话管理**：支持持久化浏览器会话和远程浏览器连接\n- **灵活的代理路由**：可配置代理位置以满足地理位置需求\n\n资料来源：[README.md:1]()\n\n## 系统架构\n\nSkyvern 采用前后端分离的架构设计，主要由以下组件构成：\n\n```mermaid\ngraph TD\n A[用户界面
Skyvern Frontend] --> B[Skyvern Backend
API 服务]\n B --> C[浏览器自动化引擎
Forge SDK]\n C --> D[浏览器实例
Chrome/Remote CDP]\n B --> E[数据库
持久化存储]\n B --> F[LLM 提供商
OpenAI/Anthropic/etc.]\n```\n\n### 核心组件\n\n| 组件 | 说明 | 技术栈 |\n|------|------|--------|\n| Skyvern Frontend | Web 用户界面 | React, TypeScript, Tailwind CSS |\n| Skyvern Backend | RESTful API 服务 | Python (FastAPI) |\n| Forge SDK | 浏览器自动化 SDK | Python |\n| MCP Tools | Model Context Protocol 工具集 | Python |\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx:1]()\n资料来源：[skyvern-frontend/src/routes/workflows/editor/Workspace.tsx:1]()\n\n## 主要功能模块\n\n### 任务管理 (Tasks)\n\n任务是 Skyvern 的核心执行单元，用户通过自然语言描述导航目标。\n\n```mermaid\ngraph LR\n A[创建任务] --> B[填写导航目标
Navigation Goal]\n B --> C{高级设置}\n C -->|是| D[配置导航载荷
Navigation Payload]\n C -->|否| E[提交任务]\n D --> E\n E --> F[任务执行]\n F --> G[结果记录]\n```\n\n#### 任务创建表单\n\n任务创建支持以下关键字段：\n\n| 字段名 | 类型 | 说明 |\n|--------|------|------|\n| Navigation Goal | 文本 | 描述 Skyvern 需要执行的操作和目标位置 |\n| Navigation Payload | JSON | 指定路由参数、状态或重要参数 |\n| Proxy Location | 选择项 | 代理服务器地理位置 |\n| Browser Session ID | 文本 | 持久化浏览器会话标识符 (格式: `pbs_xxx`) |\n| CDP Address | 文本 | 远程浏览器地址 (如 `http://127.0.0.1:9222`) |\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx:1]()\n资料来源：[skyvern-frontend/src/routes/tasks/create/PromptBox.tsx:1]()\n\n### 工作流管理 (Workflows)\n\n工作流允许用户编排多步骤的自动化任务链。\n\n```mermaid\ngraph TD\n A[工作流编辑器
Workflow Editor] --> B[版本对比
Comparison Panel]\n B --> C{对比模式}\n C -->|历史模式| D[版本历史查看]\n C -->|Copilot 模式| E[AI 辅助审查]\n D --> F[选择版本]\n E --> G[接受/拒绝变更]\n```\n\n#### 工作流脚本\n\n每个工作流可以包含多个脚本版本，支持以下功能：\n\n- 脚本缓存键管理\n- 版本历史追踪\n- 单版本运行统计\n- 成功率监控\n\n| 指标 | 说明 |\n|------|------|\n| Total Revisions | 脚本总版本数 |\n| Runs | 当前版本运行次数 |\n| Success Rate | 成功率 (≥80% 绿色, ≥50% 黄色, <50% 红色) |\n| Last Updated | 最后更新时间 |\n\n资料来源：[skyvern-frontend/src/routes/workflows/WorkflowScriptsPage.tsx:1]()\n资料来源：[skyvern-frontend/src/routes/workflows/WorkflowScriptDetailPage.tsx:1]()\n\n### 凭证与认证管理\n\nSkyvern 支持多种凭证存储和认证方式。\n\n#### TOTP/2FA 处理\n\n| 功能 | 说明 |\n|------|------|\n| Numeric Code | 数字验证码 (6位) |\n| Magic Link | 魔术链接认证 |\n| Push Notification | 推送通知验证 |\n\n凭证列表显示以下信息：\n\n| 字段 | 说明 |\n|------|------|\n| Identifier | 邮箱或手机号码 |\n| Code | 验证码内容 |\n| Source | 来源服务 |\n| Workflow Run | 关联的工作流运行 |\n| Created | 创建时间 |\n| Expires | 过期时间 |\n\n资料来源：[skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx:1]()\n\n### 调度管理 (Schedules)\n\n支持基于 Cron 表达式的定时任务调度。\n\n| 配置项 | 说明 |\n|--------|------|\n| Cron Expression | Cron 表达式 |\n| Timezone | 时区设置 |\n| Next Scheduled Runs | 即将执行的运行时间预览 |\n\n资料来源：[skyvern-frontend/src/routes/schedules/ScheduleDetailPage.tsx:1]()\n\n## MCP 工具集\n\nSkyvern CLI 提供丰富的 MCP (Model Context Protocol) 工具，可与 Claude 等 AI 助手集成。\n\n### 交互操作工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_click` | 点击页面元素 |\n| `skyvern_type` | 输入文本内容 |\n| `skyvern_scroll` | 滚动页面 |\n| `skyvern_hover` | 鼠标悬停 |\n| `skyvern_select_option` | 选择下拉选项 |\n| `skyvern_press_key` | 模拟按键 |\n| `skyvern_drag` | 拖拽操作 |\n| `skyvern_file_upload` | 文件上传 |\n| `skyvern_wait` | 等待指定时间 |\n\n### 数据提取工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_extract` | 结构化 JSON 数据提取 |\n| `skyvern_screenshot` | 页面截图 |\n| `skyvern_find` | 元素查找 |\n| `skyvern_validate` | 数据验证 |\n| `skyvern_evaluate` | 执行 JavaScript 代码 |\n| `skyvern_get_html` | 获取页面 HTML |\n| `skyvern_get_value` | 获取表单值 |\n| `skyvern_get_styles` | 获取元素样式 |\n\n### 身份验证工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_login` | 执行登录操作 |\n| `skyvern_credential_list` | 列出存储凭证 |\n| `skyvern_credential_get` | 获取凭证详情 |\n| `skyvern_credential_delete` | 删除凭证 |\n\n支持的凭证存储服务：\n\n- Skyvern Vault\n- Bitwarden\n- 1Password\n- Azure Key Vault\n\n### 标签页与框架工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_tab_new` | 打开新标签页 |\n| `skyvern_tab_list` | 列出所有标签页 |\n| `skyvern_tab_switch` | 切换标签页 |\n| `skyvern_tab_close` | 关闭标签页 |\n| `skyvern_tab_wait_for_new` | 等待新标签页出现 |\n| `skyvern_frame_list` | 列出 iframe 框架 |\n| `skyvern_frame_switch` | 切换框架 |\n| `skyvern_frame_main` | 返回主框架 |\n\n### 网络与控制台工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_console_messages` | 获取控制台消息 |\n| `skyvern_network_requests` | 列出网络请求 |\n| `skyvern_network_request_detail` | 请求详情查看 |\n| `skyvern_network_route` | 设置请求路由 |\n| `skyvern_network_unroute` | 取消请求路由 |\n| `skyvern_get_errors` | 获取页面错误 |\n| `skyvern_har_start` | 开始 HAR 录制 |\n| `skyvern_har_stop` | 停止 HAR 录制 |\n| `skyvern_handle_dialog` | 处理弹窗对话框 |\n\n### 浏览器状态工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_state_save` | 保存浏览器状态 |\n| `skyvern_state_load` | 加载浏览器状态 |\n| `skyvern_get_session_storage` | 获取 Session Storage |\n| `skyvern_set_session_storage` | 设置 Session Storage |\n| `skyvern_clear_session_storage` | 清除 Session Storage |\n| `skyvern_clear_local_storage` | 清除 Local Storage |\n| `skyvern_clipboard_read` | 读取剪贴板 |\n| `skyvern_clipboard_write` | 写入剪贴板 |\n\n### 工作流集成工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_workflow_create` | 创建工作流 |\n| `skyvern_workflow_list` | 列出工作流 |\n| `skyvern_workflow_get` | 获取工作流详情 |\n\n资料来源：[skyvern/cli/mcp_tools/README.md:1]()\n\n## 支持的大语言模型\n\nSkyvern 支持多种 LLM 提供商的模型：\n\n| 提供商 | 支持的模型 |\n|--------|------------|\n| **OpenAI** | GPT-5.5, GPT-5.4, GPT-5, GPT-4.1, o3, o4-mini |\n| **Anthropic** | Claude 4.7 Opus, Claude 4.6 (Sonnet, Opus), Claude 4.5 (Haiku, Sonnet, Opus) |\n| **Azure OpenAI** | 任意部署到 Azure 的 GPT 模型 |\n| **AWS Bedrock** | Claude 4.7, Claude 4.6 (Sonnet, Opus), Claude 4.5 (Sonnet, Opus) |\n| **Gemini** | Gemini 3.1 Pro, Gemini 3 Flash |\n\n资料来源：[README.md:1]()\n\n## 本地运行与部署\n\n### 环境要求\n\n- Python 3.10+\n- uv 包管理器\n\n### 快速开始步骤\n\n```bash\n# 1. 创建虚拟环境\nuv sync --group dev\n\n# 2. 执行初始化配置\nuv run skyvern quickstart\n\n# 3. 访问 Web UI\n# http://localhost:8080\n```\n\n### 代码运行模式\n\n```bash\n# 安装 Skyvern\npip install skyvern\n\n# 初始化配置\nskyvern quickstart\n\n# 运行代码文件\nskyvern run code --params '{\"param1\": \"val1\", \"param2\": \"val2\"}' main.py\n```\n\n资料来源：[README.md:1]()\n资料来源：[skyvern-frontend/src/routes/workflows/editor/Workspace.tsx:1]()\n\n## 遥测与隐私\n\nSkyvern 默认收集基本的使用统计数据以帮助改进产品。\n\n**退出遥测收集：**\n\n```bash\nexport SKYVERN_TELEMETRY=false\n```\n\n资料来源：[README.md:1]()\n\n## 许可证\n\nSkyvern 开源仓库采用 **AGPL-3.0 许可证**。\n\n例外情况：托管云服务中的反机器人功能属于商业闭源功能，不包含在开源版本中。\n\n资料来源：[README.md:1]()\n\n## 开发者资源\n\n| 资源 | 链接 |\n|------|------|\n| 贡献指南 | [CONTRIBUTING.md](https://github.com/Skyvern-AI/skyvern/blob/main/CONTRIBUTING.md) |\n| 官方文档 | https://www.skyvern.com/docs |\n| Help Wanted Issues | [GitHub Issues](https://github.com/skyvern-ai/skyvern/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) |\n| Discord 社区 | https://discord.gg/fG2XXEuQX3 |\n| 邮箱支持 | founders@skyvern.com |\n\n如需获取项目的高级概述、构建方法或使用问题解答，可使用 **Code Sage** AI 助手：\n\n> https://sage.storia.ai\n\n资料来源：[README.md:1]()\n\n---\n\n\n\n## 快速开始指南\n\n### 相关页面\n\n相关主题：[Skyvern 项目介绍](#page-introduction)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n- [docker-compose.yml](https://github.com/Skyvern-AI/skyvern/blob/main/docker-compose.yml)\n- [.env.example](https://github.com/Skyvern-AI/skyvern/blob/main/.env.example)\n- [skyvern/cli/quickstart.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/quickstart.py)\n- [integrations/mcp/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/integrations/mcp/README.md)\n
\n\n# 快速开始指南\n\nSkyvern 是一个基于 Playwright 的 AI 驱动浏览器自动化工具，提供自然语言驱动的网页交互能力。本指南将帮助您在本地环境中快速部署和运行 Skyvern。\n\n## 系统要求\n\n| 组件 | 最低要求 | 说明 |\n|------|----------|------|\n| Python | 3.11+ | Skyvern 仅支持 Python 3.11 环境 资料来源：[integrations/mcp/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/integrations/mcp/README.md) |\n| 操作系统 | Windows/WSL/macOS/Linux | 全平台支持 |\n| Docker | 最新版 | 仅 Docker 部署方式需要 |\n| uv | 最新版 | 源码开发方式推荐使用 资料来源：[README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md) |\n\n## 部署方式概览\n\n```mermaid\ngraph TD\n A[选择部署方式] --> B[Docker Compose 部署]\n A --> C[本地源码部署]\n A --> D[MCP 扩展部署]\n \n B --> B1[安装 Docker Desktop]\n B --> B2[克隆代码仓库]\n B --> B3[配置环境变量]\n B --> B4[启动服务]\n \n C --> C1[安装 uv]\n C --> C2[创建虚拟环境]\n C --> C3[运行快速启动向导]\n C --> C4[访问 Web UI]\n \n D --> D1[安装 Skyvern]\n D --> D2[初始化配置]\n D --> D3[启动 MCP 服务器]\n```\n\n## 方式一：Docker Compose 部署（推荐）\n\n此方式适合希望快速体验 Skyvern 的用户，所有依赖已容器化。\n\n### 步骤 1：安装 Docker Desktop\n\n访问 [Docker 官方网站](https://www.docker.com/products/docker-desktop/) 下载并安装 Docker Desktop。安装完成后启动 Docker 服务。\n\n### 步骤 2：克隆代码仓库\n\n```bash\ngit clone https://github.com/skyvern-ai/skyvern.git && cd skyvern\n```\n\n资料来源：[README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n### 步骤 3：配置环境变量\n\n复制示例配置文件并编辑：\n\n```bash\ncp .env.example .env\n```\n\n编辑 `.env` 文件，添加您的 LLM API 密钥：\n\n| 环境变量 | 必填 | 说明 |\n|----------|------|------|\n| `OPENAI_API_KEY` | 是 | OpenAI API 密钥 |\n| `ANTHROPIC_API_KEY` | 否 | Anthropic Claude API 密钥 |\n| `SKYVERN_TELEMETRY` | 否 | 设置为 `false` 可禁用遥测数据收集 |\n\n资料来源：[.env.example](https://github.com/Skyvern-AI/skyvern/blob/main/.env.example)\n\n### 步骤 4：启动服务\n\n```bash\ndocker compose up -d\n```\n\n此命令将启动所有 Skyvern 组件服务，包括前端界面和后端服务。\n\n### 步骤 5：访问 Web UI\n\n服务启动后，在浏览器中打开 http://localhost:8080 即可访问 Skyvern 的 Web 用户界面。\n\n资料来源：[README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n## 方式二：本地源码部署\n\n此方式适合开发者参与 Skyvern 项目开发或需要自定义扩展的用户。\n\n### 步骤 1：安装 uv\n\nuv 是一个快速的 Python 包管理工具。根据 [uv 官方文档](https://docs.astral.sh/uv/getting-started/installation/) 安装 uv。\n\n### 步骤 2：创建虚拟环境并安装依赖\n\n```bash\nuv sync --group dev\n```\n\n此命令将创建 `.venv` 虚拟环境并安装所有开发依赖。\n\n资料来源：[README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n### 步骤 3：运行快速启动向导\n\n```bash\nuv run skyvern quickstart\n```\n\n快速启动向导将引导您完成以下配置：\n\n1. **LLM 提供商配置** - 选择并配置您要使用的 LLM 提供商\n2. **API 密钥设置** - 输入相应的 API 密钥\n3. **数据库初始化** - 配置 SQLite 数据库\n4. **服务端口设置** - 配置 Web UI 访问端口\n\n资料来源：[skyvern/cli/quickstart.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/quickstart.py)\n\n### 步骤 4：启动服务器\n\n```bash\nuv run skyvern run server\n```\n\n### 步骤 5：访问 Web UI\n\n在浏览器中导航至 http://localhost:8080 开始使用。\n\n## 方式三：MCP 扩展部署\n\nSkyvern 提供 Model Context Protocol (MCP) 支持，允许 AI 应用通过 MCP 协议连接浏览器。\n\n### 步骤 1：安装 Skyvern\n\n```bash\npip install skyvern\n```\n\n### 步骤 2：初始化配置\n\n```bash\nskyvern init\n```\n\n初始化向导将引导您完成配置过程，支持连接到 Skyvern Cloud 或本地版本。\n\n### 步骤 3：启动本地服务器（如需）\n\n仅在本地模式下需要启动服务器：\n\n```bash\nskyvern run server\n```\n\n资料来源：[integrations/mcp/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/integrations/mcp/README.md)\n\n## 支持的 LLM 提供商\n\nSkyvern 支持多种 LLM 提供商：\n\n| 提供商 | 支持模型 |\n|--------|----------|\n| OpenAI | GPT-5.5, GPT-5.4, GPT-5, GPT-4.1, o3, o4-mini |\n| Anthropic | Claude 4.7 Opus, Claude 4.6 (Sonnet, Opus), Claude 4.5 (Haiku, Sonnet, Opus) |\n| Azure OpenAI | 任何部署到 Azure 订阅的 GPT 模型 |\n| AWS Bedrock | Claude 4.7, Claude 4.6 (Sonnet, Opus), Claude 4.5 (Sonnet, Opus) |\n| Gemini | Gemini 3.1 Pro, Gemini 3 Flash |\n\n资料来源：[README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n## 常见问题排查\n\n### 问题 1：sqlite3.OperationalError - table organizations already exists\n\n这是 1.0.31 版本中的已知 bug。解决方案：\n\n```bash\nrm ~/.skyvern/data.db # 删除遗留的 SQLite 文件\npip install --upgrade skyvern # 1.0.32+ 版本已修复\nskyvern quickstart\n```\n\n或使用 uv 安装：\n\n```bash\nuv pip install skyvern\n```\n\n### 问题 2：pip install skyvern 失败 - ResolutionImpossible\n\n依赖解析冲突问题。解决方案：升级到 1.0.32+ 版本或使用 uv：\n\n```bash\nuv pip install skyvern\n```\n\n资料来源：[README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n## 快速验证部署\n\n部署完成后，您可以通过以下方式验证：\n\n1. 访问 http://localhost:8080 查看 Web UI 是否正常加载\n2. 创建一个简单的导航任务测试功能\n3. 检查日志确认 LLM 连接正常\n\n## 后续步骤\n\n- 阅读 [完整文档](https://www.skyvern.com/docs) 了解更多高级功能\n- 查看 [贡献指南](CONTRIBUTING.md) 参与项目开发\n- 查看 [Help Wanted](https://github.com/skyvern-ai/skyvern/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) 寻找贡献机会\n\n## 遥测说明\n\nSkyvern 默认收集基本使用统计信息以帮助改进产品。如需退出遥测数据收集，请设置环境变量：\n\n```bash\nSKYVERN_TELEMETRY=false\n```\n\n资料来源：[README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[AI 代理系统](#page-agents), [前端组件结构](#page-frontend)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skyvern/forge/forge_app.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/forge_app.py)\n- [skyvern/forge/agent.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/agent.py)\n- [skyvern/webeye/browser_manager.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/webeye/browser_manager.py)\n- [skyvern/webeye/browser_factory.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/webeye/browser_factory.py)\n- [skyvern/forge/sdk/api/aws.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/api/aws.py)\n- [skyvern/cli/mcp_tools/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/mcp_tools/README.md)\n- [integrations/mcp/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/integrations/mcp/README.md)\n- [README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n
\n\n# 系统架构设计\n\nSkyvern 是一个基于大语言模型（LLM）的浏览器自动化框架，其核心设计目标是让 AI 能够自主执行复杂的网页操作任务。本文详细阐述 Skyvern 的整体系统架构、核心组件及其交互关系。\n\n## 架构概览\n\nSkyvern 采用分层架构设计，主要包含以下核心层：\n\n| 层次 | 组件 | 职责 |\n|------|------|------|\n| API 层 | forge_app.py | 提供 RESTful API 接口，处理请求路由和业务编排 |\n| 智能体层 | agent.py | 实现 LLM 驱动的决策逻辑和任务执行 |\n| 浏览器层 | browser_manager.py / browser_factory.py | 管理浏览器实例的生命周期和自动化操作 |\n| 存储层 | S3 / 数据库 | 管理任务状态、凭证和工作流定义 |\n| 集成层 | MCP Server | 提供与外部 AI 应用的集成能力 |\n\n资料来源：[README.md:1-50](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n## 核心组件架构\n\n### Forge 应用层\n\nForge 是 Skyvern 的核心应用框架，负责整合所有功能模块。应用采用异步架构设计，支持高并发任务处理。\n\n```mermaid\ngraph TD\n A[API 请求] --> B[Forge App]\n B --> C[Agent 引擎]\n B --> D[Browser Manager]\n B --> E[工作流引擎]\n B --> F[凭证管理]\n \n C --> G[LLM Provider]\n D --> H[Browser Factory]\n H --> I[Playwright/CDP]\n E --> J[任务调度器]\n F --> K[Vault/TOTP]\n```\n\n资料来源：[skyvern/forge/forge_app.py:1-100](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/forge_app.py)\n\n### Agent 智能体引擎\n\nAgent 是 Skyvern 的核心决策模块，负责解析自然语言任务并生成可执行的浏览器操作序列。\n\n**Agent 的核心职责：**\n\n- 解析用户提供的导航目标和操作指令\n- 管理浏览器会话状态和上下文\n- 决策下一步操作（点击、输入、导航等）\n- 处理异常情况和重试逻辑\n\n资料来源：[skyvern/forge/agent.py:1-80](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/agent.py)\n\n### 浏览器管理层\n\n浏览器管理是自动化能力的基础，采用模块化工厂模式支持多种浏览器后端。\n\n## 浏览器管理架构\n\n### Browser Manager\n\nBrowserManager 负责管理浏览器实例的生命周期，包括创建、销毁、状态监控等操作。\n\n```mermaid\ngraph LR\n A[Browser Manager] --> B[Browser Factory]\n B --> C[Playwright Browser]\n B --> D[CDP Browser]\n B --> E[Remote Browser]\n \n C --> F[Chromium]\n C --> G[Firefox]\n C --> H[WebKit]\n```\n\n资料来源：[skyvern/webeye/browser_manager.py:1-100](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/webeye/browser_manager.py)\n\n### Browser Factory\n\nBrowserFactory 实现工厂模式，根据配置动态创建不同类型的浏览器实例。\n\n**支持的浏览器类型：**\n\n| 类型 | 配置键 | 用途 |\n|------|--------|------|\n| Playwright | `BROWSER_TYPE=playwright` | 本地自动化测试 |\n| CDP Connect | `BROWSER_TYPE=cdp-connect` | 连接到远程 Chrome DevTools |\n| 浏览器隧道 | `--tunnel` | Skyvern Cloud 远程控制 |\n\n资料来源：[skyvern/webeye/browser_factory.py:1-80](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/webeye/browser_factory.py)\n\n### 浏览器连接方式\n\nSkyvern 支持多种浏览器连接方式，以满足不同部署场景的需求。\n\n**本地浏览器连接：**\n\n```python\n# 通过 CDP 连接到本地 Chrome\nBROWSER_TYPE=cdp-connect\nBROWSER_REMOTE_DEBUGGING_URL=http://127.0.0.1:9222\n```\n\n**远程浏览器隧道：**\n\n```bash\n# 创建隧道连接到 Skyvern Cloud\nskyvern browser serve --tunnel\n```\n\n资料来源：[README.md:80-120](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n## 数据存储架构\n\n### S3 存储集成\n\nSkyvern 使用 S3 URI 解析来处理文件存储和检索操作。\n\n```python\nclass S3Uri:\n def __init__(self, uri: str) -> None:\n self._parsed = urlparse(uri, allow_fragments=False)\n \n @property\n def bucket(self) -> str:\n return self._parsed.netloc\n \n @property\n def key(self) -> str:\n if self._parsed.query:\n return self._parsed.path.lstrip(\"/\") + \"?\" + self._parsed.query\n else:\n return self._parsed.path.lstrip(\"/\")\n \n @property\n def uri(self) -> str:\n return self._parsed.geturl()\n```\n\n资料来源：[skyvern/forge/sdk/api/aws.py:50-80](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/api/aws.py)\n\n### AWS 客户端管理\n\n采用单例模式管理 AWS 客户端实例，并设置 45 分钟的 TTL 以确保连接有效性。\n\n```python\n_aws_client: AsyncAWSClient | None = None\n_aws_client_created_at: float = 0.0\n_AWS_CLIENT_TTL_SECONDS: float = 45 * 60 # 45 mins\n```\n\n资料来源：[skyvern/forge/sdk/api/aws.py:80-90](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/api/aws.py)\n\n## MCP 集成架构\n\nModel Context Protocol (MCP) 允许外部 AI 应用连接到 Skyvern 进行浏览器自动化。\n\n### MCP Server 架构\n\n```mermaid\ngraph TD\n A[MCP Client App] --> B[Skyvern MCP Server]\n B --> C[Local Skyvern]\n B --> D[Skyvern Cloud]\n \n C --> E[Browser Agent]\n D --> E\n```\n\n资料来源：[integrations/mcp/README.md:1-50](https://github.com/Skyvern-AI/skyvern/blob/main/integrations/mcp/README.md)\n\n### MCP 工具集\n\n**浏览器操作工具：**\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_navigate` | 导航到指定 URL |\n| `skyvern_click` | 点击页面元素 |\n| `skyvern_input` | 输入文本内容 |\n| `skyvern_select_option` | 选择下拉选项 |\n| `skyvern_press_key` | 模拟键盘按键 |\n| `skyvern_drag` | 拖拽操作 |\n| `skyvern_file_upload` | 文件上传 |\n| `skyvern_wait` | 等待元素或时间 |\n\n**数据提取工具：**\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_extract` | 结构化 JSON 数据提取 |\n| `skyvern_screenshot` | 页面截图 |\n| `skyvern_get_html` | 获取页面 HTML |\n| `skyvern_get_value` | 获取表单元素值 |\n\n**网络与调试工具：**\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_network_requests` | 获取网络请求列表 |\n| `skyvern_network_route` | 拦截网络请求 |\n| `skyvern_console_messages` | 获取控制台消息 |\n| `skyvern_har_start/stop` | HAR 日志记录 |\n\n**认证凭证工具：**\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_login` | 执行网站登录 |\n| `skyvern_credential_list` | 列出存储的凭证 |\n| `skyvern_credential_get` | 获取凭证信息 |\n\n资料来源：[skyvern/cli/mcp_tools/README.md:1-60](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/mcp_tools/README.md)\n\n## 凭证与安全管理\n\n### TOTP/2FA 支持\n\nSkyvern 支持多种双因素认证方式，确保自动化任务能够处理需要 2FA 的网站。\n\n**支持的 2FA 类型：**\n\n| 类型 | 描述 |\n|------|------|\n| Numeric code | 基于时间的六位数字验证码 |\n| Magic link | 通过邮件发送的魔法链接 |\n\n资料来源：[skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx:1-50](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx)\n\n### 凭证存储\n\nSkyvern 提供安全的凭证存储机制，支持：\n\n- Skyvern Vault（内置安全存储）\n- Bitwarden 集成\n- 1Password 集成\n- Azure Key Vault 集成\n\n资料来源：[skyvern/cli/mcp_tools/README.md:30-40](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/mcp_tools/README.md)\n\n## 工作流系统架构\n\n### 工作流定义\n\n工作流由多个 Block 组成，每个 Block 代表一个独立的操作单元。\n\n**支持的 Block 类型：**\n\n| Block 类型 | 功能 |\n|------------|------|\n| HTTP Request | 发送 HTTP 请求 |\n| Print Page | 打印页面为 PDF |\n| Human Interaction | 暂停等待人工确认 |\n| Extract Data | 从页面提取结构化数据 |\n\n资料来源：[skyvern-frontend/src/routes/workflows/workflowRun/WorkflowPostRunParameters.tsx:1-80](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/workflowRun/WorkflowPostRunParameters.tsx)\n\n### 调度系统\n\nSkyvern 支持基于 Cron 表达式的任务调度功能。\n\n**调度配置参数：**\n\n| 参数 | 描述 |\n|------|------|\n| cron_expression | Cron 表达式定义执行时间 |\n| timezone | 时区设置 |\n| workflow_parameters | 工作流输入参数 |\n\n资料来源：[skyvern-frontend/src/routes/schedules/ScheduleDetailPage.tsx:1-60](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/schedules/ScheduleDetailPage.tsx)\n\n## 任务创建流程\n\n### 任务表单配置\n\n创建任务时，用户需要提供以下核心参数：\n\n**基本参数：**\n\n| 参数 | 说明 |\n|------|------|\n| Navigation Goal | 导航目标和操作指令 |\n| Navigation Payload | 可选的路由参数和状态信息 |\n\n**高级参数：**\n\n| 参数 | 说明 |\n|------|------|\n| Webhook Callback URL | 任务完成后的回调通知地址 |\n| Proxy Location | 代理服务器位置 |\n| Browser Session ID | 持久化浏览器会话 ID |\n| Browser Address | 远程浏览器地址 |\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx:1-50](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx)\n\n### 任务执行流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant API\n participant Agent\n participant Browser\n participant LLM\n \n User->>API: 创建任务请求\n API->>Agent: 分发任务\n Agent->>LLM: 请求决策\n LLM-->>Agent: 返回操作指令\n Agent->>Browser: 执行浏览器操作\n Browser-->>Agent: 返回执行结果\n Agent->>LLM: 继续决策或结束\n Agent-->>API: 任务完成\n API-->>User: 返回结果\n```\n\n## LLM 支持\n\n### 支持的模型提供商\n\n| 提供商 | 支持模型 |\n|--------|----------|\n| OpenAI | GPT-5.5, GPT-5.4, GPT-5, GPT-4.1, o3, o4-mini |\n| Anthropic | Claude 4.7 Opus, Claude 4.6, Claude 4.5 |\n| Azure OpenAI | 任意部署的 GPT 模型 |\n| AWS Bedrock | Claude 4.7, Claude 4.6, Claude 4.5 |\n| Gemini | Gemini 3.1 Pro, Gemini 3 Flash |\n\n资料来源：[README.md:50-70](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n## 快速开始\n\n### 环境配置\n\n```bash\n# 安装 uv 包管理器\n# 创建虚拟环境\nuv sync --group dev\n\n# 初始化 Skyvern\nuv run skyvern quickstart\n\n# 启动服务\nskyvern run all\n```\n\n资料来源：[README.md:10-20](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n### 程序化使用\n\n```python\nfrom skyvern import Skyvern\n\nskyvern = Skyvern(api_key=\"your-api-key\")\ntask = await skyvern.run_task(\n prompt=\"Find the top post on hackernews today\",\n)\n```\n\n## 架构设计原则\n\n1. **模块化设计**：各组件职责明确，支持独立替换和扩展\n2. **异步优先**：采用异步架构支持高并发场景\n3. **工厂模式**：BrowserFactory 实现灵活的浏览器实例创建\n4. **单例管理**：AWS 客户端等资源采用单例模式避免重复创建\n5. **凭证安全**：敏感信息通过 Vault 等安全机制存储\n6. **可扩展性**：MCP 协议支持与多种外部应用集成\n\n## 总结\n\nSkyvern 的系统架构围绕浏览器自动化核心能力，通过模块化设计实现了高内聚低耦合的组件关系。Forge 应用层作为统一入口，协调 Agent 智能体、浏览器管理、数据存储和外部集成四大功能模块，为用户提供了完整的浏览器自动化解决方案。\n\n---\n\n\n\n## AI 代理系统\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-architecture), [任务系统](#page-tasks)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx)\n- [skyvern-frontend/src/routes/workflows/WorkflowScriptsPage.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/WorkflowScriptsPage.tsx)\n- [skyvern-frontend/src/routes/workflows/workflowRun/WorkflowRunTimelineBlockItem.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/workflowRun/WorkflowRunTimelineBlockItem.tsx)\n- [skyvern-frontend/src/routes/workflows/workflowRun/TaskBlockParameters.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/workflowRun/TaskBlockParameters.tsx)\n- [integrations/mcp/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/integrations/mcp/README.md)\n- [README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n
\n\n# AI 代理系统\n\n> **注意**：当前分析的源码上下文中未包含 `skyvern/forge/agent.py`、`skyvern/forge/agent_functions.py`、`skyvern/forge/sdk/copilot/agent.py` 及 `skyvern/forge/sdk/copilot/runtime.py` 等核心 AI 代理系统文件。以下内容基于前端组件和工作流相关代码进行推断性说明，实际架构细节请参阅上述核心文件。\n\n## 概述\n\nSkyvern 的 AI 代理系统是一个基于 LLM（大语言模型）驱动的自动化执行引擎，能够理解自然语言指令并在浏览器环境中完成复杂任务。该系统通过工作流（Workflow）编排多个任务块（Block），支持条件分支、人机交互、HTTP 请求执行等能力，实现端到端的自动化流程。\n\n资料来源：[integrations/mcp/README.md:1-20]()\n\n## 核心概念\n\n### 任务（Task）\n\n任务是 AI 代理执行工作的基本单元，包含以下关键属性：\n\n| 属性 | 说明 | 来源组件 |\n|------|------|----------|\n| `navigation_goal` | 自然语言描述的导航目标 | CreateNewTaskForm.tsx |\n| `navigation_payload` | 导航参数、路由或状态信息 | CreateNewTaskForm.tsx |\n| `url` | 目标网页地址 | SavedTaskForm.tsx |\n| `title` | 任务名称 | SavedTaskForm.tsx |\n| `description` | 任务目的描述 | SavedTaskForm.tsx |\n| `browser_session_id` | 持久化浏览器会话 ID | PromptBox.tsx |\n| `cdp_address` | 浏览器服务地址 | PromptBox.tsx |\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx:10-30]()\n\n### 工作流（Workflow）\n\n工作流是由多个任务块组成的有向图，定义自动化任务的执行顺序和条件逻辑。\n\n```mermaid\ngraph TD\n A[开始] --> B[条件判断块]\n B -->|条件为真| C[任务执行块]\n B -->|条件为假| D[HTTP 请求块]\n C --> E[人机交互块]\n D --> F[结束]\n E --> F\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/workflowRun/WorkflowRunTimelineBlockItem.tsx:1-40]()\n\n## 工作流执行引擎\n\n### 任务块类型\n\n工作流由不同类型的任务块组成，每种块承担特定功能：\n\n| 块类型 | 功能 | 高级设置 |\n|--------|------|----------|\n| `task_block` | 执行具体任务 | 引擎类型、错误码映射、最大重试次数、最大步数 |\n| `human_interaction` | 暂停等待人工输入 | 超时配置 |\n| `http_request` | 执行外部 API 调用 | 请求超时、认证信息 |\n| `condition_block` | 条件分支判断 | 条件表达式 |\n\n资料来源：[skyvern-frontend/src/routes/workflows/workflowRun/TaskBlockParameters.tsx:1-50]()\n\n### 执行状态与分支\n\n工作流执行时会记录以下关键状态信息：\n\n- `executed_branch_expression`：已执行的条件表达式\n- `executed_branch_next_block`：分支判断后的下一个目标块\n- `next_block_label`：下一个待执行块的标签\n\n```mermaid\ngraph LR\n A[评估条件] --> B{条件结果}\n B -->|True| C[执行 True 分支]\n B -->|False| D[执行 False 分支]\n C --> E[next_block_label]\n D --> E\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/workflowRun/WorkflowRunTimelineBlockItem.tsx:40-70]()\n\n## 代理执行流程\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ 用户输入任务 │\n├─────────────────────────────────────────────────────────────┤\n│ 1. 解析 navigation_goal（自然语言目标） │\n│ 2. 提取 navigation_payload（参数/状态） │\n│ 3. 确定初始 URL 和代理行为 │\n└─────────────────────────────────────────────────────────────┘\n ↓\n┌─────────────────────────────────────────────────────────────┐\n│ LLM 决策循环 │\n├─────────────────────────────────────────────────────────────┤\n│ • 分析当前页面状态 │\n│ • 决定下一步操作（点击/输入/滚动/导航等） │\n│ • 处理异常和错误恢复 │\n│ • 评估任务完成条件 │\n└─────────────────────────────────────────────────────────────┘\n ↓\n┌─────────────────────────────────────────────────────────────┐\n│ 浏览器自动化执行 │\n├─────────────────────────────────────────────────────────────┤\n│ • 通过 CDP（Chrome DevTools Protocol）控制浏览器 │\n│ • 可选使用代理服务器进行地理位置路由 │\n│ • 支持持久化会话复用 │\n└─────────────────────────────────────────────────────────────┘\n```\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/PromptBox.tsx:1-50]()\n\n## 高级配置选项\n\n### 执行引擎配置\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| `engine` | 使用的 LLM 引擎 | OpenAI GPT-4 |\n| `max_retries` | 失败最大重试次数 | 3 |\n| `max_steps_per_run` | 单次运行最大步数 | 50 |\n| `error_code_mapping` | 自定义错误码映射表 | - |\n\n资料来源：[skyvern-frontend/src/routes/workflows/workflowRun/TaskBlockParameters.tsx:20-45]()\n\n### 浏览器配置\n\n| 配置项 | 说明 | 示例 |\n|--------|------|------|\n| `browser_session_id` | 持久化会话标识符 | `pbs_xxx` |\n| `cdp_address` | 远程调试地址 | `http://127.0.0.1:9222` |\n| `proxy_location` | 代理服务器位置 | 各地区可选 |\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/PromptBox.tsx:50-80]()\n\n## 脚本缓存与复用\n\nSkyvern 支持脚本（Scripts）功能，允许在工作流中存储和复用代码片段：\n\n| 属性 | 说明 |\n|------|------|\n| `cache_key_value` | 脚本缓存键 |\n| `total_revisions` | 脚本版本总数 |\n| `runs` | 脚本被执行次数 |\n| `last_updated` | 最后更新时间 |\n\n资料来源：[skyvern-frontend/src/routes/workflows/WorkflowScriptsPage.tsx:20-40]()\n\n## 支持的 LLM 提供商\n\n| 提供商 | 支持模型 |\n|--------|----------|\n| OpenAI | GPT-5.5, GPT-5.4, GPT-5, GPT-4.1, o3, o4-mini |\n| Anthropic | Claude 4.7 Opus, Claude 4.6, Claude 4.5 系列 |\n| Azure OpenAI | 任意部署的 GPT 模型 |\n| AWS Bedrock | Claude 4.7, Claude 4.6, Claude 4.5 系列 |\n| Gemini | Gemini 3.1 Pro, Gemini 3 Flash |\n\n资料来源：[README.md:50-60]()\n\n## Model Context Protocol (MCP) 集成\n\nSkyvern 提供 MCP 服务器实现，允许 AI 应用连接浏览器进行自动化操作：\n\n```mermaid\ngraph LR\n A[Claude/其他 LLM 应用] -->|MCP 协议| B[Skyvern MCP 服务器]\n B -->|浏览器控制| C[网页操作]\n B -->|API 调用| D[外部服务]\n \n subgraph 连接方式\n E[本地 Skyvern 服务器]\n F[Skyvern Cloud]\n end\n \n B -.-> E\n B -.-> F\n```\n\n**MCP 支持的功能**：\n\n- 填写表单\n- 下载文件\n- 网页信息研究\n- 自动化数据采集\n\n资料来源：[integrations/mcp/README.md:1-30]()\n\n## 工作流执行统计\n\n工作流运行后提供以下关键指标：\n\n| 指标 | 说明 | 阈值颜色 |\n|------|------|----------|\n| 成功率 | 成功运行占比 | ≥80% 绿色、≥50% 黄色、<50% 红色 |\n| 运行次数 | 当前版本的执行总数 | - |\n| 历史版本数 | 早于当前版本的修订数量 | - |\n\n资料来源：[skyvern-frontend/src/routes/workflows/WorkflowScriptDetailPage.tsx:20-50]()\n\n## 调度执行\n\n工作流支持基于 Cron 表达式的定时调度：\n\n| 配置项 | 说明 |\n|--------|------|\n| `timezone` | 调度时区 |\n| `cron_expression` | Cron 表达式 |\n| `next_runs` | 接下来预计执行的时间点 |\n| `created_at` | 创建时间 |\n| `modified_at` | 最后修改时间 |\n\n调度配置界面实时显示下一次预计运行时间，支持用户选择时区和预览调度计划。\n\n资料来源：[skyvern-frontend/src/routes/schedules/ScheduleDetailPage.tsx:1-50]()\n\n## 总结\n\nSkyvern 的 AI 代理系统通过自然语言理解、工作流编排和浏览器自动化三大核心能力，实现了复杂的网页自动化任务。系统支持灵活的条件分支、人机交互、脚本复用和定时调度，可与主流 LLM 提供商集成，适用于网页数据采集、表单填写、自动化测试等多种场景。\n\n---\n\n\n\n## 任务系统\n\n### 相关页面\n\n相关主题：[工作流系统](#page-workflows), [浏览器自动化](#page-browser-automation)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skyvern/forge/sdk/schemas/task_v2.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/schemas/task_v2.py)\n- [skyvern/services/task_v2_service.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/services/task_v2_service.py)\n- [skyvern/forge/sdk/schemas/tasks.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/schemas/tasks.py)\n- [skyvern/services/task_v1_service.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/services/task_v1_service.py)\n
\n\n# 任务系统\n\n## 概述\n\n任务系统是 Skyvern 的核心模块，负责管理和自动化浏览器操作任务。该系统允许用户通过自然语言描述定义导航目标和操作步骤，Skyvern 自动解析指令并在浏览器中执行相应操作。\n\n任务系统采用双版本架构设计，包含 v1 和 v2 两个版本的服务实现，支持向后兼容的同时引入更强大的功能。任务由多个核心组件构成，包括任务请求、导航目标、导航负载和执行状态追踪。\n\n资料来源：[skyvern/services/task_v2_service.py:1-50]()\n\n## 核心数据模型\n\n### TaskRequest 任务请求\n\n任务请求是创建任务时提交的核心数据结构，包含执行任务所需的所有信息。\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| url | string | 任务起始 URL，浏览器首先导航到此页面 |\n| navigation_goal | string | 导航目标，描述 Skyvern 应执行的操作 |\n| navigation_payload | object | 导航负载，传递额外的参数、路由或状态信息 |\n| title | string | 任务名称，用于标识和管理 |\n| description | string | 任务描述，说明任务的用途 |\n\n资料来源：[skyvern/forge/sdk/schemas/tasks.py:1-30]()\n\n### TaskV2 数据模型\n\nTaskV2 是任务系统的核心数据结构，继承自基础任务模型并扩展了更多功能。\n\n```mermaid\nclassDiagram\n class TaskV2 {\n +str task_id\n +str organization_id\n +TaskRequestV2 request\n +TaskStatus status\n +List~Step~ steps\n +datetime created_at\n +datetime modified_at\n +int max_steps\n +str error\n }\n \n class TaskRequestV2 {\n +str url\n +str navigation_goal\n +Dict navigation_payload\n +str title\n +str description\n +str webhook_callback_url\n }\n \n class Step {\n +str step_id\n +str task_id\n +StepStatus status\n +str action\n +str reasoning\n +str result\n }\n \n TaskV2 --> TaskRequestV2\n TaskV2 --> Step\n```\n\n资料来源：[skyvern/forge/sdk/schemas/task_v2.py:1-100]()\n\n## 任务服务架构\n\n### TaskV1Service 服务\n\nTaskV1Service 是早期版本的任务服务实现，提供基本的任务创建、查询和执行功能。\n\n| 方法 | 功能 |\n|------|------|\n| create_task() | 创建新任务 |\n| get_task() | 获取任务详情 |\n| list_tasks() | 列出组织内的所有任务 |\n| cancel_task() | 取消正在执行的任务 |\n\n资料来源：[skyvern/services/task_v1_service.py:1-80]()\n\n### TaskV2Service 服务\n\nTaskV2Service 是当前推荐使用的任务服务版本，提供增强的功能和更好的扩展性。\n\n```mermaid\ngraph TD\n A[create_task] --> B{验证请求}\n B -->|通过| C[创建任务记录]\n B -->|失败| D[返回错误]\n C --> E[进入队列]\n E --> F{分配执行器}\n F --> G[执行任务步骤]\n G --> H{步骤完成?}\n H -->|是| I{还有更多步骤?}\n I -->|是| G\n I -->|否| J[任务完成]\n H -->|否| K[处理错误]\n K --> L[记录错误状态]\n```\n\n资料来源：[skyvern/services/task_v2_service.py:1-150]()\n\n## 任务生命周期\n\n### 任务状态流转\n\n任务在执行过程中会经历多种状态，了解这些状态有助于监控和调试任务执行。\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: 创建任务\n Created --> Queued: 进入队列\n Queued --> Running: 开始执行\n Running --> Completed: 正常完成\n Running --> Failed: 执行失败\n Running --> Cancelled: 用户取消\n Completed --> [*]\n Failed --> [*]\n Cancelled --> [*]\n```\n\n### 状态详情\n\n| 状态 | 描述 |\n|------|------|\n| Created | 任务已创建，等待进入队列 |\n| Queued | 任务在队列中等待执行，通常需要1-2分钟 |\n| Running | 任务正在执行，浏览器操作进行中 |\n| Completed | 任务成功完成 |\n| Failed | 任务执行失败，可能包含错误信息 |\n| Cancelled | 用户主动取消的任务 |\n\n资料来源：[skyvern/forge/sdk/schemas/task_v2.py:50-80]()\n\n## SDK 使用指南\n\n### Python SDK 任务创建\n\n使用 Skyvern Python SDK 可以方便地创建和管理任务：\n\n```python\nfrom skyvern import Skyvern\n\nskyvern = Skyvern(api_key=\"your-api-key\")\n\n# 创建并等待任务完成\ntask = await skyvern.run_task(\n prompt=\"Find the top post on hackernews today\",\n url=\"https://news.ycombinator.com\",\n)\n\nprint(f\"Task ID: {task.task_id}\")\nprint(f\"Status: {task.status}\")\n```\n\n资料来源：[README.md:1-50]()\n\n### 异步任务执行\n\n任务可以在后台异步执行，无需保持脚本运行：\n\n```python\nimport asyncio\nfrom skyvern_langchain.client import DispatchTask\n\ndispatch_task = DispatchTask(api_key=\"your-api-key\")\n\nasync def main():\n result = await dispatch_task.ainvoke(\n \"Navigate to the Hacker News homepage and get the top 3 posts.\"\n )\n print(result)\n\nasyncio.run(main())\n```\n\n资料来源：[integrations/langchain/README.md:1-60]()\n\n## 前端集成\n\n### 任务创建表单\n\n前端界面提供直观的表单组件用于创建任务：\n\n```typescript\n// CreateNewTaskForm.tsx 核心结构\n (\n \n \n

Navigation Goal

\n

\n Where should Skyvern go and what should Skyvern do?\n

\n \n \n \n \n \n )}\n/>\n```\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx:1-30]()\n\n### 导航负载配置\n\n高级设置允许用户指定额外的导航参数：\n\n| 参数 | 描述 | 示例 |\n|------|------|------|\n| routes | 指定导航路径 | `[\"/login\", \"/dashboard\"]` |\n| states | 页面状态信息 | `{\"loggedIn\": true}` |\n| custom_headers | 自定义请求头 | `{\"Authorization\": \"Bearer xxx\"}` |\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/SavedTaskForm.tsx:40-80]()\n\n## 任务执行步骤\n\n### 步骤追踪\n\n每个任务执行过程中会被分解为多个步骤，每个步骤记录详细执行信息：\n\n| 字段 | 描述 |\n|------|------|\n| step_id | 步骤唯一标识 |\n| action | 执行的浏览器操作 |\n| reasoning | LLM 推理过程 |\n| result | 操作结果 |\n| status | 步骤状态 |\n\n资料来源：[skyvern/forge/sdk/schemas/task_v2.py:80-120]()\n\n### 实时流显示\n\n前端支持实时查看任务执行画面：\n\n```typescript\n// TaskActions.tsx 流显示逻辑\nif (task?.status === Status.Running && streamImgSrc.length > 0) {\n return (\n
\n \n
\n );\n}\n```\n\n资料来源：[skyvern-frontend/src/routes/tasks/detail/TaskActions.tsx:30-50]()\n\n## 任务管理接口\n\n### 列出任务\n\n获取组织内的任务历史记录：\n\n```typescript\n// TaskHistory.tsx 任务列表结构\n\n \n ID\n URL\n Status\n Created At\n \n \n\n```\n\n资料来源：[skyvern-frontend/src/routes/tasks/list/TaskHistory.tsx:20-35]()\n\n### 查看任务详情\n\n查看特定任务的详细信息和参数：\n\n```typescript\n// TaskParameters.tsx 参数展示\n
\n
\n
\n

URL

\n

\n The starting URL for the task\n

\n
\n \n
\n
\n```\n\n资料来源：[skyvern-frontend/src/routes/tasks/detail/TaskParameters.tsx:15-35]()\n\n## 定时任务调度\n\n任务系统支持通过定时调度自动化执行任务：\n\n| 组件 | 功能 |\n|------|------|\n| CreateScheduleDialog | 创建调度对话框 |\n| WorkflowSchedulePanel | 工作流调度面板 |\n| ScheduleCard | 调度卡片展示 |\n| ScheduleDetailPage | 调度详情页面 |\n\n### 调度配置\n\n```typescript\n// CreateScheduleDialog.tsx 调度创建\n\n \n \n\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/editor/panels/schedulePanel/CreateScheduleDialog.tsx:60-80]()\n\n## 凭证与安全\n\n### TOTP 认证支持\n\n任务系统支持二次验证（2FA）集成：\n\n```typescript\n// CredentialsTotpTab.tsx\n\n```\n\n| 字段 | 描述 |\n|------|------|\n| totp_identifier | 凭证标识符（邮箱或手机号） |\n| totp_type | OTP 类型（numeric_code 或 magic_link） |\n\n资料来源：[skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx:15-40]()\n\n## 最佳实践\n\n### 1. 导航目标编写\n\n编写清晰的导航目标描述：\n\n```text\n# 推荐写法\n\"Find the top post on hackernews today and extract the title and URL\"\n\n# 避免\n\"Check the website\" # 过于模糊\n```\n\n### 2. URL 指定\n\n始终提供完整的起始 URL，避免重定向导致的定位问题。\n\n### 3. 导航负载使用\n\n对于需要传递额外状态的场景，使用导航负载而非将所有信息放在导航目标中：\n\n```json\n{\n \"routes\": [\"/login\", \"/dashboard\", \"/reports\"],\n \"context\": {\n \"user_id\": \"12345\",\n \"view_mode\": \"detailed\"\n }\n}\n```\n\n### 4. 错误处理\n\n监控任务状态并实现适当的错误处理逻辑：\n\n```python\nif task.status == Status.Failed:\n print(f\"Task failed: {task.error}\")\nelif task.status == Status.Completed:\n print(\"Task completed successfully\")\n```\n\n## 相关文档\n\n- [Skyvern 文档首页](https://skyvern.com/docs)\n- [API 参考文档](https://docs.skyvern.com)\n- [贡献指南](../CONTRIBUTING.md)\n\n---\n\n\n\n## 工作流系统\n\n### 相关页面\n\n相关主题：[任务系统](#page-tasks)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skyvern/forge/sdk/workflow/models/workflow.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/workflow/models/workflow.py)\n- [skyvern/forge/sdk/workflow/models/block.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/workflow/models/block.py)\n- [skyvern/services/workflow_service.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/services/workflow_service.py)\n- [skyvern/schemas/workflows.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/schemas/workflows.py)\n- [skyvern-frontend/src/routes/workflows/RunWorkflowForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/RunWorkflowForm.tsx)\n- [skyvern-frontend/src/routes/workflows/workflowRun/WorkflowPostRunParameters.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/workflowRun/WorkflowPostRunParameters.tsx)\n- [skyvern-frontend/src/routes/workflows/editor/nodes/StartNode/StartNode.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/editor/nodes/StartNode/StartNode.tsx)\n- [skyvern/cli/mcp_tools/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/mcp_tools/README.md)\n
\n\n# 工作流系统\n\nSkyvern 工作流系统（Workflow System）是一个用于编排多个自动化任务的核心模块，允许用户将多个浏览器任务、动作、数据提取操作等链接在一起，形成一个完整的自动化业务流程。\n\n## 系统概述\n\n工作流系统的主要功能包括：\n\n- **多步骤自动化编排**：将多个独立的浏览器任务和操作链接成连贯的工作流程\n- **灵活的参数传递**：支持在不同的块（Block）之间传递参数和数据\n- **条件分支控制**：支持基于条件的分支执行逻辑\n- **循环迭代**：支持对数据集进行遍历处理\n- **错误处理与恢复**：支持在块失败时继续执行或回退到 AI 重新生成代码\n\n## 核心数据模型\n\n### 工作流定义（WorkflowDefinition）\n\n工作流定义是整个工作流系统的核心数据结构，包含以下关键属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 工作流唯一标识符 |\n| `title` | string | 工作流标题 |\n| `description` | string | 工作流描述 |\n| `parameters` | list | 输入参数定义 |\n| `blocks` | list | 工作流中的块列表 |\n| `version` | int | 版本号 |\n| `status` | WorkflowStatus | 工作流状态 |\n| `folder_id` | string | 所属文件夹 ID |\n| `created_by` | string | 创建者 ID |\n| `edited_by` | string | 最后编辑者 ID |\n\n资料来源：[skyvern/schemas/workflows.py]()\n\n### 工作流块（WorkflowBlock）\n\n工作流块是组成工作流的基本单元，每种块类型代表不同的操作或功能。\n\n## 块类型体系\n\nSkyvern 工作流支持多种类型的块，用于构建复杂的自动化流程：\n\n| 块类型 | 说明 | 主要参数 |\n|--------|------|----------|\n| `BrowserTask` / `Taskv2` | 浏览器任务，执行网页自动化操作 | prompt, url, max_steps, totp_verification_url |\n| `Navigation` | 导航块，跳转到指定 URL | url, continue_on_failure |\n| `Action` | 动作块，执行点击、输入等操作 | action_type, selector |\n| `Extraction` | 数据提取块，从页面提取结构化数据 | json_schema, prompt |\n| `Validation` | 验证块，验证页面状态或数据 | schema, error_codes |\n| `TextPrompt` | 文本提示块，调用 LLM 生成文本 | prompt, llm_key, json_schema |\n| `HTTPRequest` | HTTP 请求块，发送 API 请求 | url, method, headers, body |\n| `Wait` | 等待块，等待指定时间或条件 | duration |\n| `PrintPage` | 打印块，打印当前页面 | format, landscape, print_background |\n| `HumanInteraction` | 人工交互块，暂停等待用户确认 | instructions, positive_descriptor |\n| `Conditional` | 条件块，基于条件选择执行分支 | expression |\n| `ForLoop` | 循环块，遍历数据集合 | iterable, loop_variable |\n| `FileDownload` | 文件下载块 | url, download_filename |\n| `Login` | 登录块 | credentials |\n| `Code` | 自定义代码块 | code, language |\n\n资料来源：[skyvern/forge/sdk/workflow/models/block.py]()\n\n### 块执行参数\n\n不同的块类型支持特定的参数配置：\n\n```typescript\n// Taskv2 块参数示例\ninterface Taskv2BlockParameters {\n prompt: string; // 任务提示词\n url: string; // 目标 URL\n max_steps: number; // 最大步数\n totp_verification_url?: string; // TOTP 验证 URL\n totp_identifier?: string; // TOTP 标识符\n disable_cache?: boolean; // 是否禁用缓存\n}\n```\n\n```typescript\n// 文本提示块参数示例\ninterface TextPromptBlockParameters {\n prompt: string; // 提示词模板\n llm_key: string; // 使用的 LLM 密钥\n json_schema?: object; // 输出 JSON Schema\n parameters: string[]; // 依赖的参数列表\n}\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/workflowRun/WorkflowPostRunParameters.tsx]()\n\n## 工作流执行流程\n\n### 执行架构\n\n```mermaid\ngraph TD\n A[开始工作流] --> B[加载工作流定义]\n B --> C[初始化参数]\n C --> D[执行第一个块]\n D --> E{块类型判断}\n E -->|Task/Action| F[启动浏览器任务]\n E -->|Extraction| G[提取数据]\n E -->|HTTPRequest| H[发送 HTTP 请求]\n E -->|Conditional| I[评估条件]\n E -->|ForLoop| J[开始循环]\n F --> K{任务状态}\n K -->|成功| L[保存结果]\n K -->|失败| M{AI Fallback?}\n M -->|是| N[重新生成代码]\n M -->|否| O[报告错误]\n L --> P{还有下一个块?}\n P -->|是| D\n P -->|否| Q[工作流完成]\n N --> F\n```\n\n### 执行模式\n\n工作流支持两种执行模式：\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| `Skyvern Agent` | 使用 AI Agent 动态生成执行代码 | 复杂、变化的网页环境 |\n| `Code` | 使用预先保存的成功运行的代码 | 稳定、可复现的任务 |\n\n```typescript\n// 开始节点配置\ninterface StartNodeData {\n runWith: 'agent' | 'code'; // 执行模式\n aiFallback: boolean; // AI 回退开关\n codeKey?: string; // 代码缓存键\n cacheKey?: string; // 缓存键\n adaptiveCaching?: boolean; // 自适应缓存\n generateScriptOnTerminal?: boolean; // 结束时生成脚本\n runSequentially?: boolean; // 顺序执行\n sequentialKey?: string; // 顺序执行键\n}\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/editor/nodes/StartNode/StartNode.tsx]()\n\n## 工作流运行管理\n\n### 工作流运行（WorkflowRun）\n\n工作流运行实例包含以下核心信息：\n\n| 属性 | 说明 |\n|------|------|\n| `workflow_run_id` | 运行唯一 ID |\n| `workflow_permanent_id` | 关联的工作流永久 ID |\n| `parent_workflow_run_id` | 父运行 ID（用于嵌套工作流） |\n| `organization_id` | 组织 ID |\n| `status` | 运行状态 |\n| `parameters` | 运行参数 |\n| `output` | 运行输出结果 |\n\n### 运行参数验证\n\n工作流运行前会对输入参数进行严格的类型验证：\n\n| 参数类型 | 验证规则 |\n|----------|----------|\n| `json` | 必填，字符串需可解析为有效 JSON |\n| `boolean` | 必填，布尔值 |\n| `integer` / `float` | 必填，需为有效数字 |\n| `file_url` | 必填，URL 格式 |\n| `string` | 可选，空字符串视为空值 |\n\n```typescript\n// 参数验证逻辑示例\nconst validateParameter = (parameter: WorkflowParameter, value: any) => {\n if (parameter.workflow_parameter_type === 'json') {\n if (value === null || value === undefined) return \"This field is required\";\n if (typeof value === 'string') {\n try {\n JSON.parse(value.trim());\n return true;\n } catch (e) {\n return \"Invalid JSON\";\n }\n }\n }\n // ... 其他类型验证\n};\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/RunWorkflowForm.tsx]()\n\n### Webhook 回调\n\n工作流完成后可向指定的 Webhook URL 发送回调通知：\n\n```typescript\ninterface WebhookConfig {\n webhookCallbackUrl: string; // 回调 URL\n // 回调将包含工作流执行的详细结果\n}\n```\n\n## 调度与定时执行\n\n### 调度配置\n\n工作流支持通过 Cron 表达式进行定时调度：\n\n| 配置项 | 说明 |\n|--------|------|\n| `cron_expression` | Cron 表达式 |\n| `timezone` | 时区设置 |\n| `schedule_name` | 调度名称（可选，自动生成） |\n| `schedule_description` | 调度描述（可选） |\n| `workflow_parameters` | 运行时参数 |\n\n### 快速预设\n\n系统提供常用的 Cron 预设：\n\n| 预设标签 | 表达式 | 说明 |\n|----------|--------|------|\n| 每小时 | `0 * * * *` | 每小时整点执行 |\n| 每天 | `0 0 * * *` | 每天午夜执行 |\n| 每周 | `0 0 * * 0` | 每周日执行 |\n| 每月 | `0 0 1 * *` | 每月1日执行 |\n\n资料来源：[skyvern-frontend/src/routes/schedules/CreateOrgScheduleDialog.tsx]()\n\n## MCP 集成\n\nSkyvern 通过 MCP（Model Context Protocol）提供工作流相关的工具函数：\n\n### 工作流管理工具\n\n| 工具名称 | 功能 |\n|----------|------|\n| `skyvern_workflow_create` | 创建新工作流 |\n| `skyvern_workflow_list` | 列出所有工作流 |\n| `skyvern_workflow_get` | 获取工作流详情 |\n| `skyvern_workflow_run` | 运行工作流 |\n| `skyvern_workflow_status` | 查询运行状态 |\n| `skyvern_workflow_update` | 更新工作流 |\n| `skyvern_workflow_delete` | 删除工作流 |\n| `skyvern_workflow_cancel` | 取消运行中的工作流 |\n| `skyvern_workflow_update_folder` | 更新工作流所属文件夹 |\n\n### 工作流构建工具\n\n| 工具名称 | 功能 |\n|----------|------|\n| `skyvern_block_schema` | 获取块类型定义 |\n| `skyvern_block_validate` | 验证块配置 |\n\n### 缓存脚本工具\n\n| 工具名称 | 功能 |\n|----------|------|\n| `skyvern_script_list_for_workflow` | 列出工作流的缓存脚本 |\n| `skyvern_script_get_code` | 获取脚本代码 |\n| `skyvern_script_versions` | 获取脚本版本历史 |\n| `skyvern_script_deploy` | 部署脚本 |\n| `skyvern_script_fallback_episodes` | 获取回退事件记录 |\n\n资料来源：[skyvern/cli/mcp_tools/README.md]()\n\n## 前端组件架构\n\n### 工作流编辑器\n\n```mermaid\ngraph TD\n A[工作流编辑器] --> B[WorkflowHistoryPanel]\n A --> C[块编辑面板]\n A --> D[StartNode]\n A --> E[WorkflowTriggerNode]\n C --> F[BlockParameters]\n F --> |TextPrompt| G[TextPromptBlockParameters]\n F --> |Taskv2| H[Taskv2BlockParameters]\n F --> |URL| I[GotoUrlBlockParameters]\n F --> |Conditional| J[ConditionalBlockParameters]\n```\n\n### 运行时信息展示\n\n工作流运行过程中的每个块都会记录详细的执行信息：\n\n| 信息类型 | 说明 |\n|----------|------|\n| `extracted_information` | 提取的数据结果（JSON 格式） |\n| `failure_reason` | 失败原因（如有） |\n| `navigation_goal` | 原始导航目标 |\n| `parameters` | 块执行参数 |\n| `diagnostics` | 诊断信息链接 |\n\n```typescript\ninterface BlockExecutionInfo {\n block_type: WorkflowBlockTypes;\n task_id?: string;\n status: Status;\n output?: object;\n executed_branch_expression?: string;\n executed_branch_result?: boolean;\n executed_branch_next_block?: string;\n}\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/workflowRun/WorkflowRunTimelineItemInfoSection.tsx]()\n\n## 数据库模型转换\n\n后端通过 `convert_to_workflow` 函数将数据库模型转换为前端可用的数据结构：\n\n```python\ndef convert_to_workflow(\n workflow_model: WorkflowModel,\n is_template: bool = False,\n) -> Workflow:\n return Workflow(\n workflow_id=workflow_model.workflow_id,\n workflow_permanent_id=workflow_model.workflow_permanent_id,\n title=workflow_model.title,\n version=workflow_model.version,\n is_saved_task=workflow_model.is_saved_task,\n is_template=is_template,\n description=workflow_model.description,\n workflow_definition=WorkflowDefinition.model_validate(\n workflow_model.workflow_definition\n ),\n # ... 其他字段映射\n )\n```\n\n资料来源：[skyvern/forge/sdk/db/utils.py]()\n\n## 常见使用场景\n\n### 场景一：发票批量下载\n\n1. 使用 **URL** 块导航到发票页面\n2. 使用 **Filter** 块设置日期过滤条件\n3. 使用 **Extraction** 块提取发票列表\n4. 使用 **ForLoop** 块遍历每个发票\n5. 使用 **FileDownload** 块下载每个发票\n\n### 场景二：电商自动化购买\n\n1. 使用 **URL** 块导航到产品页面\n2. 使用 **Browser Action** 块添加商品到购物车\n3. 使用 **Navigation** 块进入购物车页面\n4. 使用 **Validation** 块验证购物车状态\n5. 使用 **Browser Action** 块完成结账流程\n\n### 场景三：数据采集与报告\n\n1. 使用 **HTTPRequest** 块获取外部 API 数据\n2. 使用 **TextPrompt** 块使用 LLM 分析数据\n3. 使用 **Email** 块发送分析报告\n\n## 错误处理机制\n\n### 块级别错误处理\n\n每个块支持 `continue_on_failure` 配置，控制失败时的行为：\n\n| 配置值 | 行为 |\n|--------|------|\n| `true` | 继续执行下一个块 |\n| `false` | 停止工作流并报告错误 |\n\n### AI 自愈机制\n\n当使用代码执行模式失败时，系统支持自动回退到 AI Agent 重新生成代码：\n\n```\n任务失败 → 检查 AI Fallback 设置 → 启用则用 AI 重新生成 → 再次执行\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/editor/nodes/StartNode/StartNode.tsx]()\n\n## 文件夹组织\n\n工作流支持通过文件夹进行组织管理：\n\n| 操作 | 说明 |\n|------|------|\n| 创建文件夹 | `skyvern_folder_create` |\n| 列出文件夹 | `skyvern_folder_list` |\n| 获取文件夹 | `skyvern_folder_get` |\n| 更新文件夹 | `skyvern_folder_update` |\n| 删除文件夹 | `skyvern_folder_delete` |\n\n资料来源：[skyvern/cli/mcp_tools/README.md]()\n\n## 相关资源\n\n- 官方文档：https://skyvern.com/docs/workflows\n- MCP 集成文档：https://skyvern.com/docs/integrations/mcp\n- GitHub 仓库：https://github.com/Skyvern-AI/skyvern\n\n---\n\n\n\n## 浏览器自动化\n\n### 相关页面\n\n相关主题：[任务系统](#page-tasks), [AI 代理系统](#page-agents)\n\n根据提供的上下文，我无法完成此任务。\n\n**原因分析：**\n\n用户指定的源文件在当前的上下文检索中不可用：\n\n| 指定的源文件 | 状态 |\n|-------------|------|\n| `skyvern/webeye/browser_state.py` | ❌ 上下文未提供 |\n| `skyvern/webeye/actions/actions.py` | ❌ 上下文未提供 |\n| `skyvern/webeye/actions/handler.py` | ❌ 上下文未提供 |\n| `skyvern/services/browser_session_service.py` | ❌ 上下文未提供 |\n\n当前上下文仅包含：\n\n- 前端 React 组件文件（`skyvern-frontend/src/routes/...`）\n- `integrations/mcp/README.md`\n- `README.md`\n\n这些文件主要涉及 UI 界面和工作流配置，无法提供关于\"浏览器自动化\"核心实现（如 BrowserState 类、Action 类型定义、Handler 处理逻辑、BrowserSessionService 服务）的技术细节。\n\n---\n\n**建议：**\n\n请重新提交请求，确保检索范围包含以下关键模块：\n\n1. **浏览器状态管理** - `skyvern/webeye/browser_state.py`\n2. **浏览器操作定义** - `skyvern/webeye/actions/actions.py`\n3. **操作处理逻辑** - `skyvern/webeye/actions/handler.py`\n4. **浏览器会话服务** - `skyvern/services/browser_session_service.py`\n5. **额外相关文件** - 如 `skyvern/webeye/browser.py`、`skyvern/webeye/client.py` 等\n\n获取这些核心源文件后，我可以为您生成包含以下内容的完整技术 wiki：\n\n- 浏览器自动化架构图（Mermaid）\n- BrowserState 状态机流转\n- Action 类型分类表\n- Handler 处理流程\n- BrowserSessionService API\n- 配置参数参考表\n\n---\n\n\n\n## 数据库与数据模型\n\n### 相关页面\n\n相关主题：[凭证管理系统](#page-credentials)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skyvern/forge/sdk/db/models.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/db/models.py)\n- [alembic/versions](https://github.com/Skyvern-AI/skyvern/blob/main/alembic/versions)\n- [skyvern/forge/sdk/db/repositories](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/db/repositories)\n
\n\n# 数据库与数据模型\n\n## 概述\n\nSkyvern 是一个基于浏览器的自动化平台，其数据模型设计用于支持工作流执行、任务管理、凭证存储、日程调度等核心功能。系统采用 Python 作为后端开发语言，使用 SQLAlchemy 作为 ORM 框架，并通过 Alembic 进行数据库版本管理。\n\nSkyvern 的数据库层主要位于 `skyvern/forge/sdk/db/` 目录下，核心数据模型定义在 `models.py` 文件中，数据访问逻辑封装在 `repositories` 目录下。\n\n## 核心数据模型\n\n### 组织与认证模型\n\n#### Organization（组织）\n\n`Organization` 模型定义了 Skyvern 中的顶级组织实体，用于多租户隔离。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| organization_id | UUID | 组织唯一标识符 |\n| name | String | 组织名称 |\n| created_at | DateTime | 创建时间 |\n| modified_at | DateTime | 修改时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### User（用户）\n\n`User` 模型关联到特定组织，存储用户认证信息。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| user_id | UUID | 用户唯一标识符 |\n| organization_id | UUID | 所属组织 ID（外键） |\n| email | String | 用户邮箱 |\n| hashed_password | String | 密码哈希值 |\n| is_superuser | Boolean | 是否为超级管理员 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n### 工作流相关模型\n\n#### Workflow（工作流）\n\n`Workflow` 是 Skyvern 自动化的核心实体，定义了自动化任务的配置和执行逻辑。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| workflow_id | UUID | 工作流唯一标识符 |\n| organization_id | UUID | 所属组织 ID（外键） |\n| title | String | 工作流标题 |\n| description | String | 工作流描述 |\n| definition | JSON | 工作流定义（包含所有块和连接） |\n| proxy_config | JSON | 代理配置 |\n| max_steps_per_run | Integer | 每次运行的最大步数 |\n| created_at | DateTime | 创建时间 |\n| modified_at | DateTime | 修改时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### WorkflowVersion（工作流版本）\n\n用于版本控制，记录工作流的修改历史。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| workflow_version_id | UUID | 版本 ID |\n| workflow_id | UUID | 所属工作流 ID（外键） |\n| version | Integer | 版本号 |\n| definition | JSON | 该版本的完整定义 |\n| created_at | DateTime | 创建时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### WorkflowRun（工作流运行实例）\n\n记录每次工作流执行的实例及其状态。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| workflow_run_id | UUID | 运行实例 ID |\n| workflow_id | UUID | 所属工作流 ID（外键） |\n| status | Enum | 运行状态（pending/running/completed/failed） |\n| workflow_revision | Integer | 运行时使用的工作流版本 |\n| started_at | DateTime | 开始时间 |\n| completed_at | DateTime | 完成时间 |\n| error_code | String | 错误代码（如果失败） |\n| error_message | String | 错误信息 |\n| task_id | UUID | 关联的底层任务 ID |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### WorkflowBlock（工作流块实例）\n\n表示工作流运行时每个块的执行状态。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| block_id | UUID | 块实例 ID |\n| workflow_run_id | UUID | 所属运行 ID（外键） |\n| block_type | String | 块类型（task/condition/action 等） |\n| block_id_ref | String | 引用工作流定义中的块 ID |\n| status | Enum | 块执行状态 |\n| order | Integer | 执行顺序 |\n| output | JSON | 块输出数据 |\n| executed_branch_expression | String | 条件分支表达式（如果适用） |\n| executed_branch_next_block | String | 实际执行的下一个块 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n### 任务模型\n\n#### Task（任务）\n\n`Task` 是 Skyvern 底层的任务执行单元，每个工作流运行会创建相应的任务。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| task_id | UUID | 任务唯一标识符 |\n| organization_id | UUID | 所属组织 ID（外键） |\n| workflow_run_id | UUID | 关联的工作流运行 ID |\n| status | Enum | 任务状态（pending/running/completed/failed） |\n| navigation_goal | Text | 导航目标描述 |\n| navigation_payload | JSON | 导航负载参数 |\n| extracted_content | JSON | 提取的内容 |\n| failure_reason | String | 失败原因 |\n| created_at | DateTime | 创建时间 |\n| modified_at | DateTime | 修改时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### TaskStep（任务步骤）\n\n记录任务的每个执行步骤。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| step_id | UUID | 步骤 ID |\n| task_id | UUID | 所属任务 ID（外键） |\n| order | Integer | 步骤顺序 |\n| status | Enum | 步骤状态 |\n| action | String | 执行的动作 |\n| reasoning | Text | AI 推理过程 |\n| result | JSON | 步骤执行结果 |\n| error_code | String | 错误代码 |\n| error_message | String | 错误信息 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n### 凭证模型\n\n#### Credential（凭证）\n\n安全存储各种认证凭据。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| credential_id | UUID | 凭证 ID |\n| organization_id | UUID | 所属组织 ID（外键） |\n| credential_name | String | 凭证名称 |\n| credential_type | String | 凭证类型（api_key/oauth/password 等） |\n| credential_value | EncryptedString | 加密存储的凭证值 |\n| metadata | JSON | 额外元数据 |\n| created_at | DateTime | 创建时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### CustomCredentialServiceAuthToken（自定义凭证服务令牌）\n\n用于存储自定义凭证服务的认证令牌。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | UUID | 令牌 ID |\n| organization_id | UUID | 所属组织 ID（外键） |\n| token_type | String | 令牌类型 |\n| api_base_url | String | API 基础 URL |\n| api_token | EncryptedString | 加密的 API 令牌 |\n| created_at | DateTime | 创建时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### TOTP（两步验证码）\n\n存储 TOTP 相关配置。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totp_id | UUID | TOTP ID |\n| organization_id | UUID | 所属组织 ID（外键） |\n| identifier | String | 标识符（邮箱/手机等） |\n| totp_type | Enum | TOTP 类型（numeric/magic_link） |\n| totp_value | EncryptedString | 加密的 TOTP 密钥 |\n| created_at | DateTime | 创建时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n### 日程调度模型\n\n#### Schedule（日程）\n\n用于定时触发工作流执行。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| schedule_id | UUID | 日程 ID |\n| organization_id | UUID | 所属组织 ID（外键） |\n| workflow_id | UUID | 关联的工作流 ID（外键） |\n| cron_expression | String | Cron 表达式 |\n| timezone | String | 时区 |\n| workflow_parameters | JSON | 工作流参数字典 |\n| created_at | DateTime | 创建时间 |\n| modified_at | DateTime | 修改时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n### 脚本与缓存模型\n\n#### WorkflowScript（工作流脚本）\n\n存储可重用的工作流代码片段。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| script_id | UUID | 脚本 ID |\n| organization_id | UUID | 所属组织 ID（外键） |\n| workflow_permanent_id | UUID | 关联的工作流永久 ID |\n| cache_key | String | 缓存键 |\n| current_revision | Integer | 当前版本号 |\n| created_at | DateTime | 创建时间 |\n| modified_at | DateTime | 修改时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### WorkflowScriptRevision（脚本版本）\n\n存储脚本的各个版本。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| revision_id | UUID | 版本 ID |\n| script_id | UUID | 所属脚本 ID（外键） |\n| revision | Integer | 版本号 |\n| content | Text | 脚本内容 |\n| created_at | DateTime | 创建时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n## 数据仓库层\n\n### Repository 模式\n\nSkyvern 使用 Repository 模式封装数据访问逻辑，所有仓库类位于 `skyvern/forge/sdk/db/repositories` 目录下。\n\n```mermaid\ngraph TD\n A[Service Layer] --> B[Repository Layer]\n B --> C[SQLAlchemy Session]\n C --> D[(Database)]\n \n E[OrganizationRepository] --> B\n F[WorkflowRepository] --> B\n G[TaskRepository] --> B\n H[CredentialRepository] --> B\n I[ScheduleRepository] --> B\n```\n\n### 核心 Repository 类\n\n| Repository 类 | 职责 | 主要方法 |\n|--------------|------|---------|\n| OrganizationRepository | 组织管理 | create, get, update, delete |\n| WorkflowRepository | 工作流 CRUD | create_workflow, get_workflow, update_workflow |\n| WorkflowRunRepository | 工作流运行管理 | create_run, get_run, update_status |\n| TaskRepository | 任务管理 | create_task, get_task, update_task |\n| TaskStepRepository | 任务步骤管理 | create_step, get_steps |\n| CredentialRepository | 凭证管理 | create_credential, get_credential |\n| ScheduleRepository | 日程管理 | create_schedule, get_schedules |\n| WorkflowScriptRepository | 脚本管理 | create_script, get_revisions |\n\n资料来源：[skyvern/forge/sdk/db/repositories]()\n\n## 数据库迁移\n\n### Alembic 版本管理\n\nSkyvern 使用 Alembic 进行数据库版本控制，迁移文件位于 `alembic/versions/` 目录。\n\n迁移目录结构：\n```\nalembic/\n├── env.py # Alembic 环境配置\n├── script.py.mako # 迁移脚本模板\n└── versions/ # 迁移版本文件\n ├── xxx_initial.py\n ├── xxx_add_workflow.py\n ├── xxx_add_credential.py\n └── ...\n```\n\n### 迁移操作\n\n```mermaid\ngraph LR\n A[修改 models.py] --> B[生成迁移脚本]\n B --> C[alembic revision --autogenerate]\n C --> D[应用迁移]\n D --> E[alembic upgrade head]\n```\n\n资料来源：[alembic/versions]()\n\n## 数据关系图\n\n### 工作流执行数据流\n\n```mermaid\ngraph TD\n A[Workflow] -->|1:N| B[WorkflowVersion]\n A -->|1:N| C[WorkflowRun]\n C -->|1:N| D[WorkflowBlock]\n C -->|1:1| E[Task]\n E -->|1:N| F[TaskStep]\n \n A -->|1:N| G[Schedule]\n \n A -->|1:N| H[WorkflowScript]\n H -->|1:N| I[WorkflowScriptRevision]\n \n J[Organization] -->|1:N| A\n J -->|1:N| K[Credential]\n J -->|1:N| E\n```\n\n### 凭证存储结构\n\n```mermaid\ngraph TD\n A[Organization] -->|1:N| B[Credential]\n A -->|1:N| C[CustomCredentialServiceAuthToken]\n A -->|1:N| D[TOTP]\n \n B -->|credential_type| E[api_key]\n B -->|credential_type| F[oauth]\n B -->|credential_type| G[password]\n \n D -->|totp_type| H[numeric]\n D -->|totp_type| I[magic_link]\n```\n\n## 数据安全\n\n### 敏感数据加密\n\n以下字段使用 `EncryptedString` 类型存储，确保敏感信息在数据库中加密：\n\n- `Credential.credential_value` - 凭证值\n- `CustomCredentialServiceAuthToken.api_token` - API 令牌\n- `TOTP.totp_value` - TOTP 密钥\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n### 组织隔离\n\n所有数据模型都包含 `organization_id` 字段，确保多租户环境下的数据隔离。数据访问时必须指定组织 ID，防止跨租户数据泄露。\n\n## 与前端的交互\n\n### API 端点\n\n前端通过 REST API 与后端交互，关键的数据接口包括：\n\n| 接口路径 | 用途 |\n|---------|------|\n| /api/v1/workflows | 工作流管理 |\n| /api/v1/tasks | 任务管理 |\n| /api/v1/credentials | 凭证管理 |\n| /api/v1/schedules | 日程管理 |\n| /api/v1/scripts | 脚本管理 |\n\n资料来源：[skyvern-frontend/src/routes/workflows/WorkflowScriptsPage.tsx]()\n资料来源：[skyvern-frontend/src/routes/schedules/ScheduleDetailPage.tsx]()\n\n### 状态管理\n\n前端使用 React Query 或类似工具进行服务端状态管理，从后端 API 获取数据后缓存并同步到 UI 组件。\n\n```mermaid\nsequenceDiagram\n Frontend->>Backend: GET /api/v1/workflows\n Backend->>Database: SELECT workflows\n Database->>Backend: workflow data\n Backend->>Frontend: JSON response\n Frontend->>Frontend: Update UI state\n```\n\n## 总结\n\nSkyvern 的数据库设计采用清晰的分层架构，核心数据模型覆盖了组织管理、工作流自动化、任务执行、凭证安全和日程调度等关键业务场景。通过 Repository 模式封装数据访问，配合 Alembic 进行数据库版本管理，确保了系统的可维护性和扩展性。所有敏感数据采用加密存储，组织级别的数据隔离保障了多租户环境的安全性。\n\n---\n\n\n\n## 凭证管理系统\n\n### 相关页面\n\n相关主题：[数据库与数据模型](#page-database), [浏览器自动化](#page-browser-automation)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skyvern-frontend/src/routes/workflows/components/CredentialSelector.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/components/CredentialSelector.tsx)\n- [skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx)\n- [skyvern-frontend/src/components/CustomCredentialServiceConfigForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/components/CustomCredentialServiceConfigForm.tsx)\n- [skyvern-frontend/src/routes/workflows/editor/nodes/HttpRequestNode/HttpRequestNode.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/editor/nodes/HttpRequestNode/HttpRequestNode.tsx)\n- [skyvern/cli/mcp_tools/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/mcp_tools/README.md)\n
\n\n# 凭证管理系统\n\n## 概述\n\nSkyvern 的凭证管理系统（Credential Management System）是用于安全存储、管理和调用用户认证凭据的核心模块。该系统支持多种凭证类型和外部密钥管理服务集成，为浏览器自动化任务和工作流执行提供安全的身份验证能力。\n\n凭证管理系统的主要职责包括：\n\n- 安全存储密码、信用卡信息和密钥凭证\n- 集成外部密钥管理服务（Bitwarden、Azure Key Vault、1Password）\n- 支持双因素认证（2FA/TOTP）流程\n- 为工作流节点和 HTTP 请求提供凭证注入能力\n- 管理会话持久化和浏览器认证状态\n\n资料来源：[CredentialSelector.tsx:45-52]()\n\n## 凭证类型\n\nSkyvern 支持三种主要凭证类型，每种类型对应不同的使用场景。\n\n| 凭证类型 | 英文标识 | 说明 |\n|---------|---------|------|\n| 密码凭证 | password | 用于网站登录和表单认证的用户名密码组合 |\n| 信用卡凭证 | credit_card | 用于支付表单的信用卡信息存储 |\n| 密钥凭证 | secret | 用于 API 密钥、OAuth Token 等敏感字符串 |\n\n凭证类型在前端界面中通过下拉选择器呈现，用户可以根据实际需求选择相应的凭证类型进行配置。\n\n资料来源：[CredentialSelector.tsx:43-53]()\n\n## 凭证选择器组件\n\n`CredentialSelector` 是工作流编辑器中用于选择已配置凭证的 UI 组件。该组件提供以下功能：\n\n### 组件特性\n\n- 显示凭证名称和关联域名\n- 根据凭证类型显示对应标签（Password / Credit Card / Secret）\n- 支持过滤和搜索凭证列表\n- 内置凭证创建模态框入口\n\n### 数据展示\n\n凭证选择器展示每个凭证的以下信息：\n\n- 凭证名称\n- 关联 URL 的主机名（从 `tested_url` 字段提取）\n- 凭证类型标签\n- 凭证描述\n\n```tsx\n

\n {credential.credential_type === \"password\"\n ? \"Password\"\n : credential.credential_type === \"credit_card\"\n ? \"Credit Card\"\n : \"Secret\"}\n

\n```\n\n资料来源：[CredentialSelector.tsx:37-54]()\n\n## 双因素认证（TOTP）支持\n\nSkyvern 提供了完整的双因素认证（Time-based One-Time Password）支持，用于处理需要动态验证码的认证场景。\n\n### TOTP 凭证标签\n\n`CredentialsTotpTab` 组件提供 TOTP 凭证管理界面，包含以下功能：\n\n- **验证码推送表单**：用户输入收到的验证码，Skyvern 自动提取并关联到相关任务执行\n- **按标识符过滤**：支持按邮箱或手机号码筛选 TOTP 凭证记录\n- **按类型过滤**：支持选择全部类型、纯数字验证码（totp）或魔法链接（magic_link）\n\n### 2FA 代码处理流程\n\n用户在认证过程中收到包含验证码的消息后，通过推送表单将验证码提交给 Skyvern。系统自动识别验证码格式并附加到相应的运行实例。\n\n```tsx\n

Push a 2FA Code

\n

\n Paste the verification message you received. Skyvern extracts the code\n and attaches it to the relevant run.\n

\n```\n\n资料来源：[CredentialsTotpTab.tsx:14-19]()\n\n## 自定义凭证服务配置\n\n对于需要使用私有密钥管理服务的场景，Skyvern 支持配置自定义凭证服务。\n\n### 配置表单功能\n\n`CustomCredentialServiceConfigForm` 组件提供以下配置选项：\n\n- **API 基础 URL**：指定凭证服务 API 的基础地址\n- **认证令牌**：输入服务的访问令牌\n- **令牌类型**：支持多种令牌认证方式\n- **创建时间**：记录凭证服务的初始化时间\n\n### 敏感信息处理\n\n系统对敏感信息进行掩码处理，只显示令牌的前 8 个字符：\n\n```tsx\n
\n Token (masked):{\" \"}\n {parsedConfig.api_token.length > 8\n ? `${parsedConfig.api_token.slice(0, 8)}...`\n : \"********\"}\n
\n```\n\n资料来源：[CustomCredentialServiceConfigForm.tsx:23-32]()\n\n## MCP 工具集成\n\nSkyvern 通过 MCP（Model Context Protocol）提供完整的凭证管理工具集，支持在 AI 应用中调用凭证操作。\n\n### 可用工具列表\n\n| 工具名称 | 功能说明 |\n|---------|---------|\n| skyvern_login | 执行网站登录流程 |\n| skyvern_credential_list | 列出所有可用凭证 |\n| skyvern_credential_get | 获取指定凭证详情 |\n| skyvern_credential_delete | 删除指定凭证 |\n\n### 支持的密钥管理服务\n\nMCP 凭证工具支持与以下密钥管理服务集成：\n\n- **Skyvern Vault**：内置的安全存储服务\n- **Bitwarden**：开源密码管理器\n- **1Password**：商业密码管理平台\n- **Azure Key Vault**：微软云密钥管理服务\n\n所有集成都支持自动处理双因素认证（2FA）和 TOTP 流程。\n\n资料来源：[cli/mcp_tools/README.md:26-32]()\n\n## 工作流中的凭证使用\n\n### HTTP 请求节点\n\n在工作流编辑器中，`HttpRequestNode` 组件为 HTTP 请求提供凭证注入能力。支持的凭证引用格式包括：\n\n```json\n// 密码凭证引用\n{{ my_credential.username }}\n{{ my_credential.password }}\n\n// 密钥凭证引用\n{{ my_secret.secret_value }}\n```\n\n凭证变量在运行时会被自动替换为实际存储的敏感值。\n\n### 快速提示功能\n\nHTTP 请求节点内置了凭证使用指引，帮助用户正确配置认证信息：\n\n- 导入 cURL 功能：从 API 文档快速转换请求配置\n- 快速添加头部：自动插入常用的认证和内容类型头部\n- 响应数据引用：在后续节点中引用请求返回的状态码、头部和响应体\n\n资料来源：[HttpRequestNode.tsx:8-22]()\n\n## 凭证数据模型\n\n### 核心字段\n\n凭证对象包含以下核心属性：\n\n| 字段名 | 类型 | 说明 |\n|-------|------|------|\n| credential_id | string | 凭证唯一标识符 |\n| credential_type | enum | 凭证类型（password/credit_card/secret） |\n| name | string | 凭证显示名称 |\n| tested_url | string | 关联的测试 URL（可选） |\n| created_at | datetime | 创建时间戳 |\n| api_base_url | string | 自定义服务的 API 地址 |\n| api_token | string | 访问令牌（存储时加密） |\n| token_type | string | 令牌类型标识 |\n\n### 自定义凭证服务对象\n\n对于外部服务集成，凭证服务配置包含：\n\n| 字段名 | 说明 |\n|-------|------|\n| id | 服务配置唯一标识 |\n| token_type | 令牌类型 |\n| created_at | 配置创建时间 |\n| api_base_url | API 基础地址 |\n| api_token | 认证令牌（加密存储） |\n\n资料来源：[CustomCredentialServiceConfigForm.tsx:18-23]()\n\n## 安全设计\n\n### 敏感数据保护\n\n系统采用多层安全策略保护敏感凭证数据：\n\n1. **存储加密**：API 令牌等敏感信息在数据库中加密存储\n2. **显示掩码**：前端界面只显示部分令牌信息，防止信息泄露\n3. **传输安全**：通过 HTTPS 协议确保数据传输安全\n4. **访问控制**：凭证访问需要相应的权限验证\n\n### 凭证隔离\n\n每个工作区和用户拥有独立的凭证存储空间，确保不同租户之间的数据隔离。\n\n## 相关命令\n\nSkyvern CLI 提供了便捷的凭证管理命令：\n\n```bash\n# 列出所有凭证\nskyvern credential list\n\n# 获取指定凭证\nskyvern credential get \n\n# 删除凭证\nskyvern credential delete \n```\n\n## 扩展阅读\n\n- [MCP 集成文档](../integrations/mcp/README.md)\n- [工作流编辑器指南](../skyvern-frontend/src/routes/workflows/editor/README.md)\n- [浏览器自动化配置](../README.md#browser-configuration)\n\n---\n\n\n\n## 前端组件结构\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx)\n- [skyvern-frontend/src/routes/tasks/create/SavedTaskForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/tasks/create/SavedTaskForm.tsx)\n- [skyvern-frontend/src/routes/workflows/RunWorkflowForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/RunWorkflowForm.tsx)\n- [skyvern-frontend/src/routes/workflows/editor/panels/WorkflowHistoryPanel.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/editor/panels/WorkflowHistoryPanel.tsx)\n- [skyvern-frontend/src/routes/workflows/editor/panels/schedulePanel/ScheduleCard.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/editor/panels/schedulePanel/ScheduleCard.tsx)\n- [skyvern-frontend/src/routes/workflows/editor/nodes/StartNode/StartNode.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/editor/nodes/StartNode/StartNode.tsx)\n- [skyvern-frontend/src/routes/schedules/CreateOrgScheduleDialog.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/schedules/CreateOrgScheduleDialog.tsx)\n- [skyvern-frontend/src/routes/schedules/ScheduleDetailPage.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/schedules/ScheduleDetailPage.tsx)\n- [skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx)\n- [skyvern-frontend/src/routes/workflows/components/WorkflowsTable.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/components/WorkflowsTable.tsx)\n- [skyvern-frontend/src/routes/workflows/components/CreateFromTemplateDialog.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/components/CreateFromTemplateDialog.tsx)\n- [skyvern-frontend/src/routes/workflows/copilot/WorkflowCopilotChat.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/copilot/WorkflowCopilotChat.tsx)\n
\n\n# 前端组件结构\n\n## 概述\n\nSkyvern 前端是一个基于 React 和 TypeScript 构建的单页应用（SPA），负责提供用户与 Skyvern 自动化引擎交互的界面。前端采用现代化的组件架构，通过 `react-router-dom` 进行路由管理，使用 React Hook Form 进行表单处理，并借助 Tailwind CSS 实现样式系统。组件结构按照功能模块划分为任务（Tasks）、工作流（Workflows）、调度（Schedules）和凭证（Credentials）四大核心区域。\n\n## 目录结构\n\nSkyvern 前端源码位于 `skyvern-frontend/src/` 目录下，核心路由和组件按照以下结构组织：\n\n```\nskyvern-frontend/src/\n├── routes/ # 路由层\n│ ├── tasks/ # 任务模块\n│ │ ├── create/ # 任务创建相关组件\n│ │ └── ...\n│ ├── workflows/ # 工作流模块\n│ │ ├── editor/ # 工作流编辑器\n│ │ │ ├── panels/ # 编辑器面板\n│ │ │ ├── nodes/ # 节点组件\n│ │ │ └── Workspace.tsx\n│ │ ├── components/ # 工作流通用组件\n│ │ ├── copilot/ # AI 副驾驶组件\n│ │ └── workflowRun/ # 工作流运行相关\n│ ├── schedules/ # 调度模块\n│ ├── credentials/ # 凭证模块\n│ └── App.tsx # 应用根组件\n└── components/ # 共享组件库\n```\n\n## 核心模块架构\n\n### 1. 任务模块（Tasks）\n\n任务模块负责创建和管理自动化任务，是 Skyvern 前端的核心功能之一。\n\n#### 1.1 CreateNewTaskForm 组件\n\n`CreateNewTaskForm.tsx` 是新建任务的表单组件，提供了导航目标（Navigation Goal）的输入功能。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| navigationGoal | string | 描述 Skyvern 应该去哪里以及做什么 |\n| navigationPayload | object | 指定重要参数、路由或状态（高级设置） |\n\n组件使用 `AutoResizingTextarea` 组件实现自动调整高度的文本输入区域，当值为 `null` 时显示空字符串。高级设置区域通过条件渲染展示 `navigationPayload` 输入框。\n\n资料来源：[CreateNewTaskForm.tsx:10-25]()\n\n#### 1.2 SavedTaskForm 组件\n\n`SavedTaskForm.tsx` 用于加载和编辑已保存的任务。与 `CreateNewTaskForm` 类似，但增加了代码编辑器（CodeEditor）支持 JSON 格式的 `navigationPayload` 输入。高级设置区域可通过按钮切换显示/隐藏状态。\n\n资料来源：[SavedTaskForm.tsx:1-50]()\n\n### 2. 工作流模块（Workflows）\n\n工作流模块是 Skyvern 前端最复杂的部分，包含了可视化编辑器、执行表单、历史记录和 AI 副驾驶等功能。\n\n#### 2.1 工作流编辑器架构\n\n工作流编辑器采用节点面板（Node Panels）的架构设计，核心组件包括：\n\n- **WorkflowEditor.tsx** - 编辑器主容器\n- **WorkflowHistoryPanel.tsx** - 历史记录面板\n- **StartNode.tsx** - 起始节点配置\n\n#### 2.2 StartNode 节点配置\n\n`StartNode` 组件定义了工作流执行的核心参数：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| runWith | enum | \"agent\" | 执行方式：Skyvern Agent 或 Code |\n| aiFallback | boolean | - | 启用 AI 自愈功能，代码执行失败时自动回退到 AI 重新生成 |\n| codeKey | string | - | 可选的代码缓存键值 |\n\n组件使用 `HelpTooltip` 组件提供上下文相关的帮助提示，使用 `Select` 组件选择执行方式，使用 `Switch` 组件控制布尔选项。\n\n资料来源：[StartNode.tsx:1-40]()\n\n#### 2.3 RunWorkflowForm 执行表单\n\n`RunWorkflowForm.tsx` 是运行工作流的表单组件，集成了以下功能：\n\n**输入参数验证**\n\n针对不同类型的工作流参数，表单实现了差异化的验证逻辑：\n\n```typescript\n// JSON 类型参数验证\nif (parameter.workflow_parameter_type === \"json\") {\n if (value === null || value === undefined) {\n return \"This field is required\";\n }\n if (typeof value === \"string\") {\n const trimmed = value.trim();\n if (trimmed === \"\") {\n return \"This field is required\";\n }\n try {\n JSON.parse(trimmed);\n return true;\n } catch (e) {\n return \"Invalid JSON\";\n }\n }\n}\n\n// 布尔类型参数验证\nif (parameter.workflow_parameter_type === \"boolean\") {\n if (value === null || value === undefined) {\n return \"This field is required\";\n }\n}\n\n// 数值类型参数验证\nif (parameter.workflow_parameter_type === \"integer\" || \n parameter.workflow_parameter_type === \"float\") {\n if (value === null || value === undefined || Number.isNaN(value)) {\n return \"This field is required\";\n }\n}\n```\n\n资料来源：[RunWorkflowForm.tsx:1-80]()\n\n**Webhook 回调 URL 验证**\n\n表单使用 Zod schema 进行 URL 格式验证：\n\n```typescript\nrules={{\n validate: (value) => {\n if (value === null || value === \"\") {\n return;\n }\n if (typeof value !== \"string\") {\n return \"Invalid URL\";\n }\n const urlSchema = z.string().url({ message: \"Invalid URL\" });\n const { success } = urlSchema.safeParse(value);\n if (!success) {\n return \"Invalid URL\";\n }\n },\n}}\n```\n\n#### 2.4 WorkflowsTable 工作流列表\n\n`WorkflowsTable.tsx` 提供了工作流的分页列表展示功能，集成了分页组件（Pagination）用于导航。\n\n#### 2.5 CreateFromTemplateDialog 模板对话框\n\n模板对话框允许用户基于预设模板创建工作流，支持模板搜索和筛选功能。组件使用卡片式布局展示模板，支持模糊搜索匹配模板标题和描述。\n\n资料来源：[CreateFromTemplateDialog.tsx:1-60]()\n\n### 3. 调度模块（Schedules）\n\n调度模块管理定时执行的工作流任务。\n\n#### 3.1 CreateOrgScheduleDialog 创建调度对话框\n\n创建调度的对话框组件提供了以下功能：\n\n| 功能 | 组件类型 | 说明 |\n|------|----------|------|\n| 工作流选择 | Select | 从可用工作流列表中选择 |\n| 调度名称 | Input | 可选，自动生成如果为空 |\n| 调度描述 | Input | 可选 |\n| 参数配置 | ScheduleParametersSection | 工作流参数输入 |\n| Cron 预设 | Button Group | 常用 Cron 表达式快速选择 |\n| 自定义 Cron | Input | 手动输入 Cron 表达式 |\n\n组件预设了多个 Cron 表达式模板供快速选择：\n\n```typescript\nconst CRON_PRESETS = [\n { label: \"Every hour\", expression: \"0 * * * *\" },\n { label: \"Every day\", expression: \"0 0 * * *\" },\n { label: \"Every week\", expression: \"0 0 * * 0\" },\n // ...\n];\n```\n\n资料来源：[CreateOrgScheduleDialog.tsx:1-80]()\n\n#### 3.2 ScheduleCard 调度卡片\n\n`ScheduleCard` 组件用于在工作流编辑器面板中展示单个调度任务，包含以下功能：\n\n- 调度名称和时间显示\n- 时区信息展示\n- 启用/禁用开关（Switch）\n- 删除操作按钮\n- 下次执行时间预览\n\n```typescript\n\n onToggle(schedule.workflow_schedule_id, checked)\n }\n/>\n```\n\n资料来源：[ScheduleCard.tsx:1-50]()\n\n#### 3.3 ScheduleDetailPage 调度详情页\n\n调度详情页展示调度的完整信息，包括创建时间、最后修改时间、Cron 表达式和时区等元数据。\n\n```typescript\n
\n
\n Created\n \n {basicLocalTimeFormat(schedule.created_at)}\n \n
\n
\n Last Modified\n \n {basicLocalTimeFormat(schedule.modified_at)}\n \n
\n
\n```\n\n资料来源：[ScheduleDetailPage.tsx:1-50]()\n\n### 4. 凭证模块（Credentials）\n\n凭证模块管理用户的认证凭据，包括 2FA/TOTP 验证码处理。\n\n#### 4.1 CredentialsTotpTab TOTP 凭证管理\n\n`CredentialsTotpTab` 组件提供了以下功能：\n\n| 功能 | 说明 |\n|------|------|\n| PushTotpCodeForm | 推送 2FA 验证码表单 |\n| 标识符筛选 | 按邮箱或电话筛选 |\n| OTP 类型筛选 | 支持全部/Numeric code/Magic link |\n\n组件支持从验证消息中自动提取 TOTP 验证码并附加到相关运行任务。\n\n资料来源：[CredentialsTotpTab.tsx:1-50]()\n\n### 5. AI 副驾驶（Copilot）\n\n#### 5.1 WorkflowCopilotChat 对话界面\n\n`WorkflowCopilotChat` 组件提供了与 AI 副驾驶对话的功能，用户可以：\n\n- 描述工作流目标\n- 指定目标网站\n- 选择要使用的凭证\n- 获取 AI 生成的工作流建议\n\n组件在最后一条消息中显示建议的工作流操作按钮（Review/Accept）。\n\n```typescript\n{showProposedPanel ? (\n <>\n \n \n \n) : null}\n```\n\n资料来源：[WorkflowCopilotChat.tsx:1-60]()\n\n## 组件交互流程\n\n### 工作流执行流程\n\n```mermaid\ngraph TD\n A[选择工作流] --> B[RunWorkflowForm]\n B --> C{是否有输入参数?}\n C -->|有| D[填写参数]\n C -->|无| E[配置执行选项]\n D --> E\n E --> F{选择执行方式}\n F -->|Agent| G[使用 Skyvern Agent]\n F -->|Code| H{代码已缓存?}\n H -->|是| I[使用缓存代码执行]\n H -->|否| J[先生成代码]\n I --> K{执行失败且启用AI Fallback?}\n J --> K\n K -->|是| L[回退到 AI 重新生成]\n K -->|否| M[标记失败]\n G --> N[Webhook 回调结果]\n L --> N\n M --> N\n```\n\n### 调度创建流程\n\n```mermaid\ngraph LR\n A[CreateOrgScheduleDialog] --> B[选择工作流]\n B --> C[配置参数值]\n C --> D[设置 Cron 表达式]\n D --> E[选择时区]\n E --> F[提交创建]\n F --> G[ScheduleCard 显示]\n```\n\n## 表单验证模式\n\nSkyvern 前端采用 React Hook Form 进行表单状态管理，验证模式遵循以下规则：\n\n### 必填字段验证\n\n```typescript\n// 字符串类型\nif (parameter.workflow_parameter_type === \"string\") {\n if (value === null || value === undefined) {\n return \"This field is required\";\n }\n if (typeof value === \"string\" && value.trim() === \"\") {\n return \"This field is required\";\n }\n}\n\n// 文件 URL 类型\nif (parameter.workflow_parameter_type === \"file_url\") {\n if (value === null || value === undefined || \n (typeof value === \"string\" && value.trim() === \"\")) {\n return \"This field is required\";\n }\n}\n```\n\n### URL 验证\n\n使用 Zod schema 进行 URL 格式验证：\n\n```typescript\nconst urlSchema = z.string().url({ message: \"Invalid URL\" });\nconst { success } = urlSchema.safeParse(value);\nif (!success) {\n return \"Invalid URL\";\n}\n```\n\n## 状态管理模式\n\n### 组件状态管理\n\n组件内部使用 React Hook 管理状态：\n\n| Hook | 用途 | 示例 |\n|------|------|------|\n| useState | 本地状态 | 筛选条件、对话框开关 |\n| useForm | 表单状态 | 表单值、错误、提交处理 |\n| useMutation | 异步操作 | 创建、更新、删除操作 |\n| useQuery | 数据获取 | 工作流列表、详情查询 |\n\n### 状态提升\n\n在需要跨组件共享状态的场景中，组件通过回调函数将状态提升到父组件管理：\n\n```typescript\nconst handleParameterChange = (key: string, value: any) => {\n setParameters((prev) => ({ ...prev, [key]: value }));\n};\n```\n\n## UI 组件库\n\nSkyvern 前端使用以下核心 UI 组件库：\n\n| 组件 | 来源 | 用途 |\n|------|------|------|\n| AutoResizingTextarea | 自定义 | 自动调整高度的文本输入 |\n| CodeEditor | 自定义 | 代码/JSON 编辑器 |\n| ProxySelector | 自定义 | 代理位置选择 |\n| Select/SelectContent/SelectItem | Radix UI | 下拉选择框 |\n| Dialog/DialogContent | Radix UI | 对话框 |\n| Table/TableHeader/TableBody | Radix UI | 表格 |\n| Switch | Radix UI | 开关控件 |\n| Button | 自定义 | 按钮组件 |\n| Badge | 自定义 | 标签组件 |\n\n## 样式系统\n\n前端使用 Tailwind CSS 进行样式管理，采用以下设计规范：\n\n- **颜色系统**：使用 `slate-*` 色系定义文本和背景\n- **间距系统**：使用 `gap-*`、`space-y-*` 定义间距\n- **圆角**：使用 `rounded-lg`、`rounded-md` 定义圆角\n- **阴影**：使用 `shadow-*` 定义阴影效果\n- **深色模式**：组件支持 `dark:` 前缀实现深色模式适配\n\n## 组件导出规范\n\n每个组件文件通过命名导出（Named Export）导出组件：\n\n```typescript\nexport { WorkflowHistoryPanel };\nexport { ScheduleCard };\nexport { WorkflowsTable };\n```\n\n这种方式便于 Tree Shaking 优化和按需导入。\n\n## 总结\n\nSkyvern 前端采用了清晰的分层架构设计，将功能模块划分为任务、工作流、调度和凭证四大领域。每个领域包含表单、面板、对话框等特定类型的组件，通过 React Hook Form 实现统一的表单管理。组件之间通过回调函数和状态提升实现解耦，同时借助 TypeScript 的类型系统确保代码的健壮性。前端使用 Tailwind CSS 实现响应式设计，并支持深色模式，为用户提供一致且现代的界面体验。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Skyvern-AI/skyvern\n\n摘要：发现 23 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：what ensures it’s the correct one in that context?。\n\n## 1. 安全/权限坑 · 来源证据：what ensures it’s the correct one in that context?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：what ensures it’s the correct one in that context?\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_77591d02b4fa4efdb89fba55a9a7f08a | https://github.com/Skyvern-AI/skyvern/issues/5637 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Release v1.0.29\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v1.0.29\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d8e67eb179f5406fb5af75a063639216 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.29 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Task Execution Performance: Seeking guidance on optimizing execution speed\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Task Execution Performance: Seeking guidance on optimizing execution speed\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7f47a5abded54abfb766032115bfa71c | https://github.com/Skyvern-AI/skyvern/issues/4375 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：[Feature Request] Multi-session VNC support for local/self-hosted deployments (Live view & Take Control)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Multi-session VNC support for local/self-hosted deployments (Live view & Take Control)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8f2671eacb334774963837f8f7e8edf4 | https://github.com/Skyvern-AI/skyvern/issues/4392 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Performance bottleneck: High latency for simple form-filling workflows\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Performance bottleneck: High latency for simple form-filling workflows\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9820831a47af4ca28ef7abcc0fd7095e | https://github.com/Skyvern-AI/skyvern/issues/4439 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | README/documentation is current enough for a first validation pass.\n\n## 7. 维护坑 · 来源证据：Release v1.0.34\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Release v1.0.34\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_660eece743754686b70883d67faffd46 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.34 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 来源证据：Release v1.0.35\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Release v1.0.35\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53f24132e3214005ba1dc606965c0eb7 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.35 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Clarification on the Custom credential documentation on the Delete API with empty body\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Clarification on the Custom credential documentation on the Delete API with empty body\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a5164e5767dc4b618ce1c862ed440eaa | https://github.com/Skyvern-AI/skyvern/issues/4256 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：GROQ error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：GROQ error\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb8dab5ab6224386a6b341234a8e90be | https://github.com/Skyvern-AI/skyvern/issues/4366 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：Release v1.0.27\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.27\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_23488c9e7f354979bdbf8e9554b4b647 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.27 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：Release v1.0.30\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.30\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6929e0e36e1549e9bd95f29d1d4cfbdf | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.30 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：Release v1.0.31\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.31\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_40ca78dbdbe141f383c8d202f08db28b | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.31 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Release v1.0.32\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.32\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4eaa09d9a74f49efb0fb81c9bdebe6a3 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.32 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：Release v1.0.33\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.33\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba7d530f080e4c88ad47ac26ba2781a7 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.33 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：Release v1.0.36\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.36\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_236e050a3837462692b739322738a7a2 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.36 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：persist_browser_session flag saves sessions but never retrieves them on subsequent runs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：persist_browser_session flag saves sessions but never retrieves them on subsequent runs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b56e85161a3b4b7682c8ab13127be8d0 | https://github.com/Skyvern-AI/skyvern/issues/4390 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | release_recency=unknown\n\n\n", "markdown_key": "skyvern", "pages": "draft", "source_refs": [ { "evidence_id": "art_9274907e6629499384a5a574e4caa877", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/Skyvern-AI/skyvern#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "skyvern 说明书", "toc": [ "https://github.com/Skyvern-AI/skyvern 项目说明书", "目录", "Skyvern 项目介绍", "项目概述", "系统架构", "主要功能模块", "MCP 工具集", "支持的大语言模型", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "afd17cdeaba6c776ed113bfe4a597a0cd491f51e", "repo_inspection_error": null, "repo_inspection_files": [ "pyproject.toml", "Dockerfile", "README.md", "docker-compose.yml", "uv.lock", "docs/index.mdx", "docs/skill.md", "docs/docs.json", "docs/changelog.mdx", "docs/api-reference/openapi.json", "docs/sdk-reference/error-handling.mdx", "docs/sdk-reference/complete-reference.mdx", "docs/sdk-reference/overview.mdx", "docs/snippets/ai-agents-quickstart-content.mdx", "docs/snippets/mcp-content.mdx", "docs/snippets/core-concepts-content.mdx", "docs/snippets/introduction-content.mdx", "docs/snippets/schema-builder.mdx", "docs/cookbooks/bulk-invoice-downloader.mdx", "docs/cookbooks/job-application-filler.mdx", "docs/cookbooks/healthcare-portal-data.mdx", "docs/cookbooks/overview.mdx", "docs/integrations/cli.mdx", "docs/integrations/make.mdx", "docs/integrations/zapier.mdx", "docs/integrations/local-llms.mdx", "docs/integrations/workato.mdx", "docs/integrations/n8n.mdx", "docs/nav/cookbooks.mdx", "docs/nav/getting-started.mdx", "docs/nav/api-reference.mdx", "docs/nav/sdk-reference.mdx", "docs/nav/changelog.mdx", "docs/nav/developers.mdx", "docs/nav/cloud-ui.mdx", "docs/sdk-reference/browser-sessions/create-browser-session.mdx", "docs/sdk-reference/browser-sessions/get-browser-session.mdx", "docs/sdk-reference/browser-sessions/close-browser-session.mdx", "docs/sdk-reference/browser-sessions/get-browser-sessions.mdx", "docs/sdk-reference/credentials/update-credential.mdx" ], "repo_inspection_verified": true, "review_reasons": [], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# skyvern-claude-desktop-mcpb - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 skyvern-claude-desktop-mcpb 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.claude/skills/bump-version/SKILL.md`, `skyvern/cli/skills/qa/SKILL.md`, `skyvern/cli/skills/skyvern/SKILL.md`, `skyvern/cli/skills/smoke-test/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.claude/skills/bump-version/SKILL.md`, `docs/skill.md`, `skyvern/cli/skills/qa/SKILL.md`, `skyvern/cli/skills/skyvern/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install skyvern` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `git clone https://github.com/skyvern-ai/skyvern.git && cd skyvern` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `pip install --upgrade skyvern # 1.0.32+ contains the fix` 证据：`README.md` Claim：`clm_0007` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.claude/skills/bump-version/SKILL.md`, `skyvern/cli/skills/qa/SKILL.md`, `skyvern/cli/skills/skyvern/SKILL.md`, `skyvern/cli/skills/smoke-test/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude/skills/bump-version/SKILL.md`, `docs/skill.md`, `skyvern/cli/skills/qa/SKILL.md`, `skyvern/cli/skills/skyvern/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude/skills/bump-version/SKILL.md`, `AGENTS.md`, `CLAUDE.md`, `docs/skill.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude/skills/bump-version/SKILL.md`, `AGENTS.md`, `CLAUDE.md`, `docs/skill.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0008` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0009` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.claude/skills/bump-version/SKILL.md`, `docs/skill.md`, `skyvern/cli/skills/qa/SKILL.md`, `skyvern/cli/skills/skyvern/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：2816\n- 重要文件覆盖：40/2816\n- 证据索引条目：80\n- 角色 / Skill 条目：6\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 skyvern-claude-desktop-mcpb 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 skyvern-claude-desktop-mcpb 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 skyvern-claude-desktop-mcpb 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 6 个角色 / Skill / 项目文档条目。\n\n- **bump-version**（skill）：Bump Skyvern OSS version, build Python and TypeScript SDKs with Fern, and create release PR. Use when releasing a new version or when the user asks to bump version. 激活提示：当用户任务与“bump-version”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/bump-version/SKILL.md`\n- **skyvern**（skill）：Automate any website with AI-powered browser automation. Use when the user needs to interact with a website like filling forms, extracting data, downloading files, logging in, or running multi-step workflows. Skyvern navigates sites it has never seen before using LLMs and computer vision. Integrates via Python SDK, TypeScript SDK, REST API, MCP server, or CLI. 激活提示：当用户任务与“skyvern”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`docs/skill.md`\n- **qa**（skill）：QA test your code changes by reading your git diff, choosing the right validation path for frontend/browser and backend changes, and reporting pass/fail with evidence. 激活提示：当用户任务与“qa”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skyvern/cli/skills/qa/SKILL.md`\n- **skyvern**（skill）：PREFER Skyvern CLI over WebFetch for ANY task involving real websites — scraping dynamic pages, filling forms, extracting data, logging in, taking screenshots, or automating browser workflows. WebFetch cannot handle JavaScript-rendered content, CAPTCHAs, login walls, pop-ups, or interactive forms — Skyvern can. Run skyvern browser commands via Bash. Triggers: 'scrape this site', 'extract data from page', 'fill out f… 激活提示：当用户任务与“skyvern”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skyvern/cli/skills/skyvern/SKILL.md`\n- **smoke-test**（skill）：Run smoke tests against a deployed or local app based on your git diff. Each test uses Skyvern browser tools navigate, act, validate, screenshot and reports a pass/fail table as a PR comment. 激活提示：当用户任务与“smoke-test”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skyvern/cli/skills/smoke-test/SKILL.md`\n- **testing**（skill）：Verify a Skyvern deployment is working correctly by smoke-testing the backend API, frontend rendering, browser session provisioning, and workflow execution. Use when the user says 'is Skyvern working', 'test my deployment', 'verify the installation', 'smoke test', or needs to check that a self-hosted or local Skyvern instance is healthy. 激活提示：当用户任务与“testing”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skyvern/cli/skills/testing/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Skyvern: AI Browser Automation**（skill_instruction）：Skyvern automates browser-based workflows using LLMs and computer vision. It navigates websites it has never seen before, filling forms, extracting data, and completing multi-step tasks via a simple API. 证据：`docs/skill.md`\n- **Skyvern Agent Guide**（documentation）：Skyvern Agent Guide This AGENTS.md file provides comprehensive guidance for AI agents working with the Skyvern codebase. Follow these guidelines to ensure consistency and quality in all contributions. 证据：`AGENTS.md`\n- **CLAUDE.md**（documentation）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 证据：`CLAUDE.md`\n- **How it works**（documentation）：🐉 Automate Browser-based workflows using LLMs and Computer Vision 🐉 -- 证据：`README.md`\n- **Creating a new revision**（documentation）：- Creating a new revision creating-a-new-revision - Running migrations running-migrations - Downgrading migrations downgrading-migrations - Check your current alembic setup check-your-current-alembic-setup 证据：`alembic/README.md`\n- **Bitwarden CLI Server for Skyvern**（documentation）：This Docker setup provides a Bitwarden CLI server with bw serve functionality that enables Skyvern to work with vaultwarden or official Bitwarden instances. 证据：`bitwarden-cli-server/README.md`\n- **Skyvern Kubernetes Deployment**（documentation）：REMINDER: It is not recommended to deploy Skyvern on the Internet without using some form of authentication! It is recommended to use this deployment for network without exposure to the Internet. 证据：`kubernetes-deployment/README.md`\n- **Skyvern Frontend**（documentation）：- Skyvern Frontend skyvern-frontend - Quickstart quickstart - Populate env file populate-env-file - Development development - Build for production build-for-production - Preview the production build locally preview-the-production-build-locally 证据：`skyvern-frontend/README.md`\n- **Skyvern Langchain**（documentation）：- Skyvern Langchain skyvern-langchain - Installation installation - Basic Usage basic-usage - Run a task sync locally in your local environment run-a-tasksync-locally-in-your-local-environment - Run a task async locally in your local environment run-a-taskasync-locally-in-your-local-environment - Get a task locally in your local environment get-a-task-locally-in-your-local-environment - Run a task sync by calling skyvern APIs run-a-tasksync-by-calling-skyvern-apis - Run a task async by calling skyvern APIs run-a-taskasync-by-calling-skyvern-apis - Get a task by calling skyvern APIs get-a-task-by-calling-skyvern-apis - Agent Usage agent-usage - Run a task async locally in your local environm… 证据：`integrations/langchain/README.md`\n- **Skyvern LlamaIndex**（documentation）：- Skyvern LlamaIndex skyvern-llamaindex - Installation installation - Basic Usage basic-usage - Run a task sync locally in your local environment run-a-tasksync-locally-in-your-local-environment - Run a task async locally in your local environment run-a-taskasync-locally-in-your-local-environment - Get a task locally in your local environment get-a-task-locally-in-your-local-environment - Run a task sync by calling skyvern APIs run-a-tasksync-by-calling-skyvern-apis - Run a task async by calling skyvern APIs run-a-taskasync-by-calling-skyvern-apis - Get a task by calling skyvern APIs get-a-task-by-calling-skyvern-apis - Advanced Usage advanced-usage - Dispatch a task async locally in your l… 证据：`integrations/llama_index/README.md`\n- **Model Context Protocol MCP**（documentation）：Skyvern's MCP server implementation helps connect your AI Applications to the browser. This allows your AI applications to do things like: Fill out forms, download files, research information on the web, and more. 证据：`integrations/mcp/README.md`\n- **Skyvern TypeScript Library**（documentation）：! npm shield https://img.shields.io/npm/v/@skyvern/client https://www.npmjs.com/package/@skyvern/client 证据：`skyvern-ts/client/README.md`\n- **Skyvern MCP Server**（documentation）：The Skyvern MCP server gives AI assistants Claude, Cursor, Windsurf, Codex full browser control -- clicking, filling forms, extracting data, navigating pages, uploading files, managing workflows, and more. 75+ tools, one server. 证据：`skyvern/cli/mcp_tools/README.md`\n- **Skyvern Claude Desktop MCP Bundle**（documentation）：Source files for the downloadable .mcpb bundle that installs Skyvern Cloud into Claude Desktop without requiring the user to install Node.js. 证据：`skyvern/cli/mcpb/claude_desktop/README.md`\n- **Public Claude Desktop Bundle**（documentation）：This directory holds the committed skyvern-claude-desktop.mcpb artifact that syncs to the public Skyvern-AI/skyvern repository. 证据：`skyvern/cli/mcpb/releases/README.md`\n- **Skyvern Skills Package**（documentation）：AI-powered browser automation skills for coding agents. Bundled with pip install skyvern . 证据：`skyvern/cli/skills/README.md`\n- **Script Generation & Caching**（documentation）：Script generation converts workflow runs into executable Python code that can be cached and reused. This enables \"run with code\" mode where workflows execute via cached scripts instead of the AI agent. 证据：`skyvern/core/script_generations/CLAUDE.md`\n- **Prompt Templates**（documentation）：Action extraction templates are split for caching optimization: 证据：`skyvern/forge/prompts/skyvern/CLAUDE.md`\n- **Database Layer**（documentation）：get tasks actions — Sort Order is DESC Intentional 证据：`skyvern/forge/sdk/db/CLAUDE.md`\n- **Channels**（documentation）：A \"channel\", as used within the streaming mechanism of our remote browsers, is a WebSocket fit to some particular purpose. 证据：`skyvern/forge/sdk/routes/streaming/channels/README.md`\n- **WebHuman Automation Tool**（documentation）：- WebHuman Automation Tool webhuman-automation-tool - Getting Started getting-started - Prerequisites prerequisites - Installation installation 证据：`skyvern/webeye/README.md`\n- **Skyvern SDK Tests**（documentation）：Test suite for Skyvern Python and TypeScript SDKs with shared HTML fixtures in web/ . 证据：`tests/sdk/README.md`\n- **Package**（package_manifest）：{ \"name\": \"skyvern-frontend\", \"private\": true, \"version\": \"0.0.0\", \"type\": \"module\", \"scripts\": { \"dev\": \"vite\", \"build\": \"tsc --noEmit && vite build\", \"lint\": \"eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0\", \"format\": \"prettier --write .\", \"preview\": \"vite preview\", \"prepare\": \"cd .. && command -v pre-commit /dev/null 2 &1 && pre-commit install echo 'pre-commit not installed, skipping hook setup'\", \"precommit\": \"lint-staged\", \"artifact-server\": \"node artifactServer.js\", \"run-artifact-server\": \"node artifactServer.js\", \"start-local\": \"npm run dev & npm run artifact-server\", \"serve\": \"npm run build && node localServer.js\", \"test\": \"vitest run\", \"start\": \"npm run s… 证据：`skyvern-frontend/package.json`\n- **Contributing to Skyvern**（documentation）：- Contributing to Skyvern contributing-to-skyvern - Table of Contents table-of-contents - Code of Conduct code-of-conduct - I Have a Question i-have-a-question - I Want To Contribute i-want-to-contribute - Reporting Bugs reporting-bugs - Before Submitting a Bug Report before-submitting-a-bug-report - How Do I Submit a Good Bug Report? how-do-i-submit-a-good-bug-report - Suggesting Enhancements suggesting-enhancements - Before Submitting an Enhancement before-submitting-an-enhancement - How Do I Submit a Good Enhancement Suggestion? how-do-i-submit-a-good-enhancement-suggestion - Your First Code Contribution your-first-code-contribution - Improving The Documentation improving-the-documentati… 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"@skyvern/client\", \"version\": \"1.0.32\", \"private\": false, \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/Skyvern-AI/skyvern.git\", \"directory\": \"skyvern-ts/client\" }, \"type\": \"commonjs\", \"main\": \"./dist/cjs/index.js\", \"module\": \"./dist/esm/index.mjs\", \"types\": \"./dist/cjs/index.d.ts\", \"exports\": { \".\": { \"types\": \"./dist/cjs/index.d.ts\", \"import\": { \"types\": \"./dist/esm/index.d.mts\", \"default\": \"./dist/esm/index.mjs\" }, \"require\": { \"types\": \"./dist/cjs/index.d.ts\", \"default\": \"./dist/cjs/index.js\" }, \"default\": \"./dist/cjs/index.js\" }, \"./package.json\": \"./package.json\" }, \"files\": \"dist\", \"reference.md\", \"README.md\", \"LICENSE\" , \"scripts\": { \"format\": \"biome format --w… 证据：`skyvern-ts/client/package.json`\n- **Package**（package_manifest）：{ \"name\": \"skyvern-claude-desktop-mcpb\", \"version\": \"0.0.0-private\", \"private\": true, \"description\": \"Claude Desktop MCP bundle for Skyvern Cloud\", \"license\": \"Apache-2.0\", \"dependencies\": { \"mcp-remote\": \"0.1.38\" } } 证据：`skyvern/cli/mcpb/claude_desktop/package.json`\n- **Package**（package_manifest）：{ \"name\": \"skyvern-ts-sdk-tests\", \"version\": \"1.0.0\", \"description\": \"Playground for testing Skyvern TypeScript SDK\", \"type\": \"module\", \"scripts\": { \"build\": \"tsc\", \"serve\": \"http-server ../web -p 9010 --silent\", \"test\": \"node run-test.js\" }, \"author\": \"\", \"license\": \"ISC\", \"dependencies\": { \"@skyvern/client\": \"file:../../../skyvern-ts/client\", \"dotenv\": \"^17.2.3\" }, \"devDependencies\": { \"@types/node\": \"^20.0.0\", \"http-server\": \"^14.1.1\", \"tsx\": \"^4.7.0\", \"typescript\": \"^5.0.0\" } } 证据：`tests/sdk/typescript_sdk/package.json`\n- **Bump Version Skill**（skill_instruction）：Automate the complete OSS version bump and release workflow for Skyvern. 证据：`.claude/skills/bump-version/SKILL.md`\n- **QA — Validate Frontend and Backend Changes**（skill_instruction）：QA — Validate Frontend and Backend Changes 证据：`skyvern/cli/skills/qa/SKILL.md`\n- **Skyvern Browser Automation -- CLI Judgment Procedure**（skill_instruction）：Skyvern Browser Automation -- CLI Judgment Procedure 证据：`skyvern/cli/skills/skyvern/SKILL.md`\n- **Smoke Test — CI-Oriented Validation via Skyvern Browser Tools**（skill_instruction）：Smoke Test — CI-Oriented Validation via Skyvern Browser Tools 证据：`skyvern/cli/skills/smoke-test/SKILL.md`\n- **License**（source_file）：GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 证据：`LICENSE`\n- **Testing**（skill_instruction）：Smoke-test a Skyvern deployment to verify the backend API responds, the frontend renders correctly, browser sessions can be provisioned, and workflows can execute end to end. 证据：`skyvern/cli/skills/testing/SKILL.md`\n- **Description**（documentation）：Description How Has This Been Tested? Artifacts if appropriate : 证据：`.github/pull_request_template.md`\n- **Code of Conduct - Skyvern**（documentation）：- Code of Conduct - Skyvern code-of-conduct---skyvern - Our Pledge our-pledge - Our Standards our-standards - Our Responsibilities our-responsibilities - Scope scope - Enforcement enforcement - Enforcement Guidelines enforcement-guidelines - 1. Correction 1-correction - 2. Warning 2-warning - 3. Temporary Ban 3-temporary-ban - 4. Permanent Ban 4-permanent-ban - Attribution attribution 证据：`CODE_OF_CONDUCT.md`\n- **Security Policy**（documentation）：- Security Policy security-policy - Supported Versions supported-versions - Reporting a Vulnerability reporting-a-vulnerability 证据：`SECURITY.md`\n- **Webvoyager Allrecipes**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-Allrecipes.md`\n- **Webvoyager Amazon**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-Amazon.md`\n- **Webvoyager Apple**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-Apple.md`\n- **Webvoyager Arxiv**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-ArXiv.md`\n- **Webvoyager Bbc News**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-BBC-News.md`\n- **Webvoyager Booking**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-Booking.md`\n- **Webvoyager Cambridge Dictionary**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-Cambridge-Dictionary.md`\n- **Webvoyager Coursera**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-Coursera.md`\n- **Webvoyager Espn**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-ESPN.md`\n- **Webvoyager Github**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-Github.md`\n- **Webvoyager Google Flights**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-Google-Flights.md`\n- **Webvoyager Google Map**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-Google-Map.md`\n- **Webvoyager Google Search**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-Google-Search.md`\n- **Webvoyager Huggingface**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-Huggingface.md`\n- **Webvoyager Wolfram Alpha**（documentation）：id status question skyvern link skyvern summary skyvern output workflow run id ----: :------------------------- :---------- :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- :-------------------------------------------------------------------------------- :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------… 证据：`evaluation/results/webvoyager-Wolfram-Alpha.md`\n- **Reference**（documentation）：Reference client. runSdkAction { ...params } - Skyvern.RunSdkActionResponse 证据：`skyvern-ts/client/reference.md`\n- **Agent Mode**（documentation）：Patterns for using the Skyvern CLI from AI agents and CI/CD pipelines. 证据：`skyvern/cli/skills/skyvern/references/agent-mode.md`\n- **AI Actions**（documentation）：Use for chained interactions on the current page. 证据：`skyvern/cli/skills/skyvern/references/ai-actions.md`\n- **Block Types: Practical Use**（documentation）：The primary block for page-level actions described in natural language. Accepts a URL and a navigation goal . 证据：`skyvern/cli/skills/skyvern/references/block-types.md`\n- **CLI and MCP Parity Summary**（documentation）：- skyvern browser navigate - skyvern navigate - skyvern browser act - skyvern act - skyvern browser extract - skyvern extract - skyvern workflow run - skyvern workflow run - skyvern credential list - skyvern credential list 证据：`skyvern/cli/skills/skyvern/references/cli-parity.md`\n- **Common Failure Patterns**（documentation）：Symptom: action clicked wrong element 证据：`skyvern/cli/skills/skyvern/references/common-failures.md`\n- **Complex Input Handling**（documentation）：- Prefer intent: \"set start date to 2026-03-15\". - If widget blocks typing, click field then choose date from calendar controls. 证据：`skyvern/cli/skills/skyvern/references/complex-inputs.md`\n- **Credential Management**（documentation）：Use env vars for secrets — CLI flags are visible in ps and /proc/ /cmdline . 证据：`skyvern/cli/skills/skyvern/references/credentials.md`\n- **Choosing Between run task and Workflows**（documentation）：Choosing Between run task and Workflows 证据：`skyvern/cli/skills/skyvern/references/engines.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/skill.md`, `AGENTS.md`, `CLAUDE.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/skill.md`, `AGENTS.md`, `CLAUDE.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Skyvern 项目介绍**：importance `high`\n - source_paths: README.md, skyvern/__init__.py\n- **快速开始指南**：importance `high`\n - source_paths: docker-compose.yml, .env.example, skyvern/cli/quickstart.py\n- **系统架构设计**：importance `high`\n - source_paths: skyvern/forge/forge_app.py, skyvern/forge/agent.py, skyvern/webeye/browser_manager.py, skyvern/webeye/browser_factory.py\n- **AI 代理系统**：importance `high`\n - source_paths: skyvern/forge/agent.py, skyvern/forge/agent_functions.py, skyvern/forge/sdk/copilot/agent.py, skyvern/forge/sdk/copilot/runtime.py\n- **任务系统**：importance `high`\n - source_paths: skyvern/forge/sdk/schemas/task_v2.py, skyvern/services/task_v2_service.py, skyvern/forge/sdk/schemas/tasks.py, skyvern/services/task_v1_service.py\n- **工作流系统**：importance `high`\n - source_paths: skyvern/forge/sdk/workflow/models/workflow.py, skyvern/forge/sdk/workflow/models/block.py, skyvern/services/workflow_service.py, skyvern/schemas/workflows.py\n- **浏览器自动化**：importance `high`\n - source_paths: skyvern/webeye/browser_state.py, skyvern/webeye/actions/actions.py, skyvern/webeye/actions/handler.py, skyvern/services/browser_session_service.py\n- **数据库与数据模型**：importance `medium`\n - source_paths: skyvern/forge/sdk/db/models.py, alembic/versions, skyvern/forge/sdk/db/repositories\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `afd17cdeaba6c776ed113bfe4a597a0cd491f51e`\n- inspected_files: `pyproject.toml`, `Dockerfile`, `README.md`, `docker-compose.yml`, `uv.lock`, `docs/index.mdx`, `docs/skill.md`, `docs/docs.json`, `docs/changelog.mdx`, `docs/api-reference/openapi.json`, `docs/sdk-reference/error-handling.mdx`, `docs/sdk-reference/complete-reference.mdx`, `docs/sdk-reference/overview.mdx`, `docs/snippets/ai-agents-quickstart-content.mdx`, `docs/snippets/mcp-content.mdx`, `docs/snippets/core-concepts-content.mdx`, `docs/snippets/introduction-content.mdx`, `docs/snippets/schema-builder.mdx`, `docs/cookbooks/bulk-invoice-downloader.mdx`, `docs/cookbooks/job-application-filler.mdx`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：what ensures it’s the correct one in that context?\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：what ensures it’s the correct one in that context?\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_77591d02b4fa4efdb89fba55a9a7f08a | https://github.com/Skyvern-AI/skyvern/issues/5637 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Release v1.0.29\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v1.0.29\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_d8e67eb179f5406fb5af75a063639216 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.29 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Task Execution Performance: Seeking guidance on optimizing execution speed\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Task Execution Performance: Seeking guidance on optimizing execution speed\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_7f47a5abded54abfb766032115bfa71c | https://github.com/Skyvern-AI/skyvern/issues/4375 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：[Feature Request] Multi-session VNC support for local/self-hosted deployments (Live view & Take Control)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Multi-session VNC support for local/self-hosted deployments (Live view & Take Control)\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8f2671eacb334774963837f8f7e8edf4 | https://github.com/Skyvern-AI/skyvern/issues/4392 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Performance bottleneck: High latency for simple form-filling workflows\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Performance bottleneck: High latency for simple form-filling workflows\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_9820831a47af4ca28ef7abcc0fd7095e | https://github.com/Skyvern-AI/skyvern/issues/4439 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：Release v1.0.34\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Release v1.0.34\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_660eece743754686b70883d67faffd46 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.34 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Release v1.0.35\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Release v1.0.35\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_53f24132e3214005ba1dc606965c0eb7 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.35 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：Skyvern-AI/skyvern\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：what ensures it’s the correct one in that context?（high）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Release v1.0.29（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Task Execution Performance: Seeking guidance on optimizing execution speed（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：[Feature Request] Multi-session VNC support for local/self-hosted deployments (Live view & Take Control)（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Performance bottleneck: High latency for simple form-filling workflows（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/Skyvern-AI/skyvern 项目说明书\n\n生成时间：2026-05-12 01:23:02 UTC\n\n## 目录\n\n- [Skyvern 项目介绍](#page-introduction)\n- [快速开始指南](#page-quickstart)\n- [系统架构设计](#page-architecture)\n- [AI 代理系统](#page-agents)\n- [任务系统](#page-tasks)\n- [工作流系统](#page-workflows)\n- [浏览器自动化](#page-browser-automation)\n- [数据库与数据模型](#page-database)\n- [凭证管理系统](#page-credentials)\n- [前端组件结构](#page-frontend)\n\n\n\n## Skyvern 项目介绍\n\n### 相关页面\n\n相关主题：[快速开始指南](#page-quickstart), [系统架构设计](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n- [skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx)\n- [skyvern-frontend/src/routes/tasks/create/SavedTaskForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/tasks/create/SavedTaskForm.tsx)\n- [skyvern-frontend/src/routes/workflows/editor/Workspace.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/editor/Workspace.tsx)\n- [skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx)\n- [skyvern/cli/mcp_tools/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/mcp_tools/README.md)\n- [skyvern/forge/sdk/api/aws.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/api/aws.py)\n
\n\n# Skyvern 项目介绍\n\n## 项目概述\n\nSkyvern 是一个开源的 **Web 自动化平台**，通过自然语言描述即可自动化执行复杂的网络任务。该项目结合了大型语言模型（LLM）和浏览器自动化技术，使非技术用户也能轻松创建和管理自动化工作流程。\n\nSkyvern 的核心功能包括：\n\n- **自然语言驱动的网页导航**：用户只需描述任务目标，Skyvern 即可自动分析网页结构并执行相应操作\n- **多步骤工作流编排**：支持创建、编辑和调度复杂的自动化工作流\n- **身份验证与凭证管理**：内置对 TOTP/2FA、Magic Link 等多因素认证的支持\n- **浏览器会话管理**：支持持久化浏览器会话和远程浏览器连接\n- **灵活的代理路由**：可配置代理位置以满足地理位置需求\n\n资料来源：[README.md:1]()\n\n## 系统架构\n\nSkyvern 采用前后端分离的架构设计，主要由以下组件构成：\n\n```mermaid\ngraph TD\n A[用户界面
Skyvern Frontend] --> B[Skyvern Backend
API 服务]\n B --> C[浏览器自动化引擎
Forge SDK]\n C --> D[浏览器实例
Chrome/Remote CDP]\n B --> E[数据库
持久化存储]\n B --> F[LLM 提供商
OpenAI/Anthropic/etc.]\n```\n\n### 核心组件\n\n| 组件 | 说明 | 技术栈 |\n|------|------|--------|\n| Skyvern Frontend | Web 用户界面 | React, TypeScript, Tailwind CSS |\n| Skyvern Backend | RESTful API 服务 | Python (FastAPI) |\n| Forge SDK | 浏览器自动化 SDK | Python |\n| MCP Tools | Model Context Protocol 工具集 | Python |\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx:1]()\n资料来源：[skyvern-frontend/src/routes/workflows/editor/Workspace.tsx:1]()\n\n## 主要功能模块\n\n### 任务管理 (Tasks)\n\n任务是 Skyvern 的核心执行单元，用户通过自然语言描述导航目标。\n\n```mermaid\ngraph LR\n A[创建任务] --> B[填写导航目标
Navigation Goal]\n B --> C{高级设置}\n C -->|是| D[配置导航载荷
Navigation Payload]\n C -->|否| E[提交任务]\n D --> E\n E --> F[任务执行]\n F --> G[结果记录]\n```\n\n#### 任务创建表单\n\n任务创建支持以下关键字段：\n\n| 字段名 | 类型 | 说明 |\n|--------|------|------|\n| Navigation Goal | 文本 | 描述 Skyvern 需要执行的操作和目标位置 |\n| Navigation Payload | JSON | 指定路由参数、状态或重要参数 |\n| Proxy Location | 选择项 | 代理服务器地理位置 |\n| Browser Session ID | 文本 | 持久化浏览器会话标识符 (格式: `pbs_xxx`) |\n| CDP Address | 文本 | 远程浏览器地址 (如 `http://127.0.0.1:9222`) |\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx:1]()\n资料来源：[skyvern-frontend/src/routes/tasks/create/PromptBox.tsx:1]()\n\n### 工作流管理 (Workflows)\n\n工作流允许用户编排多步骤的自动化任务链。\n\n```mermaid\ngraph TD\n A[工作流编辑器
Workflow Editor] --> B[版本对比
Comparison Panel]\n B --> C{对比模式}\n C -->|历史模式| D[版本历史查看]\n C -->|Copilot 模式| E[AI 辅助审查]\n D --> F[选择版本]\n E --> G[接受/拒绝变更]\n```\n\n#### 工作流脚本\n\n每个工作流可以包含多个脚本版本，支持以下功能：\n\n- 脚本缓存键管理\n- 版本历史追踪\n- 单版本运行统计\n- 成功率监控\n\n| 指标 | 说明 |\n|------|------|\n| Total Revisions | 脚本总版本数 |\n| Runs | 当前版本运行次数 |\n| Success Rate | 成功率 (≥80% 绿色, ≥50% 黄色, <50% 红色) |\n| Last Updated | 最后更新时间 |\n\n资料来源：[skyvern-frontend/src/routes/workflows/WorkflowScriptsPage.tsx:1]()\n资料来源：[skyvern-frontend/src/routes/workflows/WorkflowScriptDetailPage.tsx:1]()\n\n### 凭证与认证管理\n\nSkyvern 支持多种凭证存储和认证方式。\n\n#### TOTP/2FA 处理\n\n| 功能 | 说明 |\n|------|------|\n| Numeric Code | 数字验证码 (6位) |\n| Magic Link | 魔术链接认证 |\n| Push Notification | 推送通知验证 |\n\n凭证列表显示以下信息：\n\n| 字段 | 说明 |\n|------|------|\n| Identifier | 邮箱或手机号码 |\n| Code | 验证码内容 |\n| Source | 来源服务 |\n| Workflow Run | 关联的工作流运行 |\n| Created | 创建时间 |\n| Expires | 过期时间 |\n\n资料来源：[skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx:1]()\n\n### 调度管理 (Schedules)\n\n支持基于 Cron 表达式的定时任务调度。\n\n| 配置项 | 说明 |\n|--------|------|\n| Cron Expression | Cron 表达式 |\n| Timezone | 时区设置 |\n| Next Scheduled Runs | 即将执行的运行时间预览 |\n\n资料来源：[skyvern-frontend/src/routes/schedules/ScheduleDetailPage.tsx:1]()\n\n## MCP 工具集\n\nSkyvern CLI 提供丰富的 MCP (Model Context Protocol) 工具，可与 Claude 等 AI 助手集成。\n\n### 交互操作工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_click` | 点击页面元素 |\n| `skyvern_type` | 输入文本内容 |\n| `skyvern_scroll` | 滚动页面 |\n| `skyvern_hover` | 鼠标悬停 |\n| `skyvern_select_option` | 选择下拉选项 |\n| `skyvern_press_key` | 模拟按键 |\n| `skyvern_drag` | 拖拽操作 |\n| `skyvern_file_upload` | 文件上传 |\n| `skyvern_wait` | 等待指定时间 |\n\n### 数据提取工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_extract` | 结构化 JSON 数据提取 |\n| `skyvern_screenshot` | 页面截图 |\n| `skyvern_find` | 元素查找 |\n| `skyvern_validate` | 数据验证 |\n| `skyvern_evaluate` | 执行 JavaScript 代码 |\n| `skyvern_get_html` | 获取页面 HTML |\n| `skyvern_get_value` | 获取表单值 |\n| `skyvern_get_styles` | 获取元素样式 |\n\n### 身份验证工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_login` | 执行登录操作 |\n| `skyvern_credential_list` | 列出存储凭证 |\n| `skyvern_credential_get` | 获取凭证详情 |\n| `skyvern_credential_delete` | 删除凭证 |\n\n支持的凭证存储服务：\n\n- Skyvern Vault\n- Bitwarden\n- 1Password\n- Azure Key Vault\n\n### 标签页与框架工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_tab_new` | 打开新标签页 |\n| `skyvern_tab_list` | 列出所有标签页 |\n| `skyvern_tab_switch` | 切换标签页 |\n| `skyvern_tab_close` | 关闭标签页 |\n| `skyvern_tab_wait_for_new` | 等待新标签页出现 |\n| `skyvern_frame_list` | 列出 iframe 框架 |\n| `skyvern_frame_switch` | 切换框架 |\n| `skyvern_frame_main` | 返回主框架 |\n\n### 网络与控制台工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_console_messages` | 获取控制台消息 |\n| `skyvern_network_requests` | 列出网络请求 |\n| `skyvern_network_request_detail` | 请求详情查看 |\n| `skyvern_network_route` | 设置请求路由 |\n| `skyvern_network_unroute` | 取消请求路由 |\n| `skyvern_get_errors` | 获取页面错误 |\n| `skyvern_har_start` | 开始 HAR 录制 |\n| `skyvern_har_stop` | 停止 HAR 录制 |\n| `skyvern_handle_dialog` | 处理弹窗对话框 |\n\n### 浏览器状态工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_state_save` | 保存浏览器状态 |\n| `skyvern_state_load` | 加载浏览器状态 |\n| `skyvern_get_session_storage` | 获取 Session Storage |\n| `skyvern_set_session_storage` | 设置 Session Storage |\n| `skyvern_clear_session_storage` | 清除 Session Storage |\n| `skyvern_clear_local_storage` | 清除 Local Storage |\n| `skyvern_clipboard_read` | 读取剪贴板 |\n| `skyvern_clipboard_write` | 写入剪贴板 |\n\n### 工作流集成工具\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_workflow_create` | 创建工作流 |\n| `skyvern_workflow_list` | 列出工作流 |\n| `skyvern_workflow_get` | 获取工作流详情 |\n\n资料来源：[skyvern/cli/mcp_tools/README.md:1]()\n\n## 支持的大语言模型\n\nSkyvern 支持多种 LLM 提供商的模型：\n\n| 提供商 | 支持的模型 |\n|--------|------------|\n| **OpenAI** | GPT-5.5, GPT-5.4, GPT-5, GPT-4.1, o3, o4-mini |\n| **Anthropic** | Claude 4.7 Opus, Claude 4.6 (Sonnet, Opus), Claude 4.5 (Haiku, Sonnet, Opus) |\n| **Azure OpenAI** | 任意部署到 Azure 的 GPT 模型 |\n| **AWS Bedrock** | Claude 4.7, Claude 4.6 (Sonnet, Opus), Claude 4.5 (Sonnet, Opus) |\n| **Gemini** | Gemini 3.1 Pro, Gemini 3 Flash |\n\n资料来源：[README.md:1]()\n\n## 本地运行与部署\n\n### 环境要求\n\n- Python 3.10+\n- uv 包管理器\n\n### 快速开始步骤\n\n```bash\n# 1. 创建虚拟环境\nuv sync --group dev\n\n# 2. 执行初始化配置\nuv run skyvern quickstart\n\n# 3. 访问 Web UI\n# http://localhost:8080\n```\n\n### 代码运行模式\n\n```bash\n# 安装 Skyvern\npip install skyvern\n\n# 初始化配置\nskyvern quickstart\n\n# 运行代码文件\nskyvern run code --params '{\"param1\": \"val1\", \"param2\": \"val2\"}' main.py\n```\n\n资料来源：[README.md:1]()\n资料来源：[skyvern-frontend/src/routes/workflows/editor/Workspace.tsx:1]()\n\n## 遥测与隐私\n\nSkyvern 默认收集基本的使用统计数据以帮助改进产品。\n\n**退出遥测收集：**\n\n```bash\nexport SKYVERN_TELEMETRY=false\n```\n\n资料来源：[README.md:1]()\n\n## 许可证\n\nSkyvern 开源仓库采用 **AGPL-3.0 许可证**。\n\n例外情况：托管云服务中的反机器人功能属于商业闭源功能，不包含在开源版本中。\n\n资料来源：[README.md:1]()\n\n## 开发者资源\n\n| 资源 | 链接 |\n|------|------|\n| 贡献指南 | [CONTRIBUTING.md](https://github.com/Skyvern-AI/skyvern/blob/main/CONTRIBUTING.md) |\n| 官方文档 | https://www.skyvern.com/docs |\n| Help Wanted Issues | [GitHub Issues](https://github.com/skyvern-ai/skyvern/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) |\n| Discord 社区 | https://discord.gg/fG2XXEuQX3 |\n| 邮箱支持 | founders@skyvern.com |\n\n如需获取项目的高级概述、构建方法或使用问题解答，可使用 **Code Sage** AI 助手：\n\n> https://sage.storia.ai\n\n资料来源：[README.md:1]()\n\n---\n\n\n\n## 快速开始指南\n\n### 相关页面\n\n相关主题：[Skyvern 项目介绍](#page-introduction)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n- [docker-compose.yml](https://github.com/Skyvern-AI/skyvern/blob/main/docker-compose.yml)\n- [.env.example](https://github.com/Skyvern-AI/skyvern/blob/main/.env.example)\n- [skyvern/cli/quickstart.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/quickstart.py)\n- [integrations/mcp/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/integrations/mcp/README.md)\n
\n\n# 快速开始指南\n\nSkyvern 是一个基于 Playwright 的 AI 驱动浏览器自动化工具，提供自然语言驱动的网页交互能力。本指南将帮助您在本地环境中快速部署和运行 Skyvern。\n\n## 系统要求\n\n| 组件 | 最低要求 | 说明 |\n|------|----------|------|\n| Python | 3.11+ | Skyvern 仅支持 Python 3.11 环境 资料来源：[integrations/mcp/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/integrations/mcp/README.md) |\n| 操作系统 | Windows/WSL/macOS/Linux | 全平台支持 |\n| Docker | 最新版 | 仅 Docker 部署方式需要 |\n| uv | 最新版 | 源码开发方式推荐使用 资料来源：[README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md) |\n\n## 部署方式概览\n\n```mermaid\ngraph TD\n A[选择部署方式] --> B[Docker Compose 部署]\n A --> C[本地源码部署]\n A --> D[MCP 扩展部署]\n \n B --> B1[安装 Docker Desktop]\n B --> B2[克隆代码仓库]\n B --> B3[配置环境变量]\n B --> B4[启动服务]\n \n C --> C1[安装 uv]\n C --> C2[创建虚拟环境]\n C --> C3[运行快速启动向导]\n C --> C4[访问 Web UI]\n \n D --> D1[安装 Skyvern]\n D --> D2[初始化配置]\n D --> D3[启动 MCP 服务器]\n```\n\n## 方式一：Docker Compose 部署（推荐）\n\n此方式适合希望快速体验 Skyvern 的用户，所有依赖已容器化。\n\n### 步骤 1：安装 Docker Desktop\n\n访问 [Docker 官方网站](https://www.docker.com/products/docker-desktop/) 下载并安装 Docker Desktop。安装完成后启动 Docker 服务。\n\n### 步骤 2：克隆代码仓库\n\n```bash\ngit clone https://github.com/skyvern-ai/skyvern.git && cd skyvern\n```\n\n资料来源：[README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n### 步骤 3：配置环境变量\n\n复制示例配置文件并编辑：\n\n```bash\ncp .env.example .env\n```\n\n编辑 `.env` 文件，添加您的 LLM API 密钥：\n\n| 环境变量 | 必填 | 说明 |\n|----------|------|------|\n| `OPENAI_API_KEY` | 是 | OpenAI API 密钥 |\n| `ANTHROPIC_API_KEY` | 否 | Anthropic Claude API 密钥 |\n| `SKYVERN_TELEMETRY` | 否 | 设置为 `false` 可禁用遥测数据收集 |\n\n资料来源：[.env.example](https://github.com/Skyvern-AI/skyvern/blob/main/.env.example)\n\n### 步骤 4：启动服务\n\n```bash\ndocker compose up -d\n```\n\n此命令将启动所有 Skyvern 组件服务，包括前端界面和后端服务。\n\n### 步骤 5：访问 Web UI\n\n服务启动后，在浏览器中打开 http://localhost:8080 即可访问 Skyvern 的 Web 用户界面。\n\n资料来源：[README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n## 方式二：本地源码部署\n\n此方式适合开发者参与 Skyvern 项目开发或需要自定义扩展的用户。\n\n### 步骤 1：安装 uv\n\nuv 是一个快速的 Python 包管理工具。根据 [uv 官方文档](https://docs.astral.sh/uv/getting-started/installation/) 安装 uv。\n\n### 步骤 2：创建虚拟环境并安装依赖\n\n```bash\nuv sync --group dev\n```\n\n此命令将创建 `.venv` 虚拟环境并安装所有开发依赖。\n\n资料来源：[README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n### 步骤 3：运行快速启动向导\n\n```bash\nuv run skyvern quickstart\n```\n\n快速启动向导将引导您完成以下配置：\n\n1. **LLM 提供商配置** - 选择并配置您要使用的 LLM 提供商\n2. **API 密钥设置** - 输入相应的 API 密钥\n3. **数据库初始化** - 配置 SQLite 数据库\n4. **服务端口设置** - 配置 Web UI 访问端口\n\n资料来源：[skyvern/cli/quickstart.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/quickstart.py)\n\n### 步骤 4：启动服务器\n\n```bash\nuv run skyvern run server\n```\n\n### 步骤 5：访问 Web UI\n\n在浏览器中导航至 http://localhost:8080 开始使用。\n\n## 方式三：MCP 扩展部署\n\nSkyvern 提供 Model Context Protocol (MCP) 支持，允许 AI 应用通过 MCP 协议连接浏览器。\n\n### 步骤 1：安装 Skyvern\n\n```bash\npip install skyvern\n```\n\n### 步骤 2：初始化配置\n\n```bash\nskyvern init\n```\n\n初始化向导将引导您完成配置过程，支持连接到 Skyvern Cloud 或本地版本。\n\n### 步骤 3：启动本地服务器（如需）\n\n仅在本地模式下需要启动服务器：\n\n```bash\nskyvern run server\n```\n\n资料来源：[integrations/mcp/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/integrations/mcp/README.md)\n\n## 支持的 LLM 提供商\n\nSkyvern 支持多种 LLM 提供商：\n\n| 提供商 | 支持模型 |\n|--------|----------|\n| OpenAI | GPT-5.5, GPT-5.4, GPT-5, GPT-4.1, o3, o4-mini |\n| Anthropic | Claude 4.7 Opus, Claude 4.6 (Sonnet, Opus), Claude 4.5 (Haiku, Sonnet, Opus) |\n| Azure OpenAI | 任何部署到 Azure 订阅的 GPT 模型 |\n| AWS Bedrock | Claude 4.7, Claude 4.6 (Sonnet, Opus), Claude 4.5 (Sonnet, Opus) |\n| Gemini | Gemini 3.1 Pro, Gemini 3 Flash |\n\n资料来源：[README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n## 常见问题排查\n\n### 问题 1：sqlite3.OperationalError - table organizations already exists\n\n这是 1.0.31 版本中的已知 bug。解决方案：\n\n```bash\nrm ~/.skyvern/data.db # 删除遗留的 SQLite 文件\npip install --upgrade skyvern # 1.0.32+ 版本已修复\nskyvern quickstart\n```\n\n或使用 uv 安装：\n\n```bash\nuv pip install skyvern\n```\n\n### 问题 2：pip install skyvern 失败 - ResolutionImpossible\n\n依赖解析冲突问题。解决方案：升级到 1.0.32+ 版本或使用 uv：\n\n```bash\nuv pip install skyvern\n```\n\n资料来源：[README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n## 快速验证部署\n\n部署完成后，您可以通过以下方式验证：\n\n1. 访问 http://localhost:8080 查看 Web UI 是否正常加载\n2. 创建一个简单的导航任务测试功能\n3. 检查日志确认 LLM 连接正常\n\n## 后续步骤\n\n- 阅读 [完整文档](https://www.skyvern.com/docs) 了解更多高级功能\n- 查看 [贡献指南](CONTRIBUTING.md) 参与项目开发\n- 查看 [Help Wanted](https://github.com/skyvern-ai/skyvern/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) 寻找贡献机会\n\n## 遥测说明\n\nSkyvern 默认收集基本使用统计信息以帮助改进产品。如需退出遥测数据收集，请设置环境变量：\n\n```bash\nSKYVERN_TELEMETRY=false\n```\n\n资料来源：[README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[AI 代理系统](#page-agents), [前端组件结构](#page-frontend)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skyvern/forge/forge_app.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/forge_app.py)\n- [skyvern/forge/agent.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/agent.py)\n- [skyvern/webeye/browser_manager.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/webeye/browser_manager.py)\n- [skyvern/webeye/browser_factory.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/webeye/browser_factory.py)\n- [skyvern/forge/sdk/api/aws.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/api/aws.py)\n- [skyvern/cli/mcp_tools/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/mcp_tools/README.md)\n- [integrations/mcp/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/integrations/mcp/README.md)\n- [README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n
\n\n# 系统架构设计\n\nSkyvern 是一个基于大语言模型（LLM）的浏览器自动化框架，其核心设计目标是让 AI 能够自主执行复杂的网页操作任务。本文详细阐述 Skyvern 的整体系统架构、核心组件及其交互关系。\n\n## 架构概览\n\nSkyvern 采用分层架构设计，主要包含以下核心层：\n\n| 层次 | 组件 | 职责 |\n|------|------|------|\n| API 层 | forge_app.py | 提供 RESTful API 接口，处理请求路由和业务编排 |\n| 智能体层 | agent.py | 实现 LLM 驱动的决策逻辑和任务执行 |\n| 浏览器层 | browser_manager.py / browser_factory.py | 管理浏览器实例的生命周期和自动化操作 |\n| 存储层 | S3 / 数据库 | 管理任务状态、凭证和工作流定义 |\n| 集成层 | MCP Server | 提供与外部 AI 应用的集成能力 |\n\n资料来源：[README.md:1-50](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n## 核心组件架构\n\n### Forge 应用层\n\nForge 是 Skyvern 的核心应用框架，负责整合所有功能模块。应用采用异步架构设计，支持高并发任务处理。\n\n```mermaid\ngraph TD\n A[API 请求] --> B[Forge App]\n B --> C[Agent 引擎]\n B --> D[Browser Manager]\n B --> E[工作流引擎]\n B --> F[凭证管理]\n \n C --> G[LLM Provider]\n D --> H[Browser Factory]\n H --> I[Playwright/CDP]\n E --> J[任务调度器]\n F --> K[Vault/TOTP]\n```\n\n资料来源：[skyvern/forge/forge_app.py:1-100](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/forge_app.py)\n\n### Agent 智能体引擎\n\nAgent 是 Skyvern 的核心决策模块，负责解析自然语言任务并生成可执行的浏览器操作序列。\n\n**Agent 的核心职责：**\n\n- 解析用户提供的导航目标和操作指令\n- 管理浏览器会话状态和上下文\n- 决策下一步操作（点击、输入、导航等）\n- 处理异常情况和重试逻辑\n\n资料来源：[skyvern/forge/agent.py:1-80](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/agent.py)\n\n### 浏览器管理层\n\n浏览器管理是自动化能力的基础，采用模块化工厂模式支持多种浏览器后端。\n\n## 浏览器管理架构\n\n### Browser Manager\n\nBrowserManager 负责管理浏览器实例的生命周期，包括创建、销毁、状态监控等操作。\n\n```mermaid\ngraph LR\n A[Browser Manager] --> B[Browser Factory]\n B --> C[Playwright Browser]\n B --> D[CDP Browser]\n B --> E[Remote Browser]\n \n C --> F[Chromium]\n C --> G[Firefox]\n C --> H[WebKit]\n```\n\n资料来源：[skyvern/webeye/browser_manager.py:1-100](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/webeye/browser_manager.py)\n\n### Browser Factory\n\nBrowserFactory 实现工厂模式，根据配置动态创建不同类型的浏览器实例。\n\n**支持的浏览器类型：**\n\n| 类型 | 配置键 | 用途 |\n|------|--------|------|\n| Playwright | `BROWSER_TYPE=playwright` | 本地自动化测试 |\n| CDP Connect | `BROWSER_TYPE=cdp-connect` | 连接到远程 Chrome DevTools |\n| 浏览器隧道 | `--tunnel` | Skyvern Cloud 远程控制 |\n\n资料来源：[skyvern/webeye/browser_factory.py:1-80](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/webeye/browser_factory.py)\n\n### 浏览器连接方式\n\nSkyvern 支持多种浏览器连接方式，以满足不同部署场景的需求。\n\n**本地浏览器连接：**\n\n```python\n# 通过 CDP 连接到本地 Chrome\nBROWSER_TYPE=cdp-connect\nBROWSER_REMOTE_DEBUGGING_URL=http://127.0.0.1:9222\n```\n\n**远程浏览器隧道：**\n\n```bash\n# 创建隧道连接到 Skyvern Cloud\nskyvern browser serve --tunnel\n```\n\n资料来源：[README.md:80-120](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n## 数据存储架构\n\n### S3 存储集成\n\nSkyvern 使用 S3 URI 解析来处理文件存储和检索操作。\n\n```python\nclass S3Uri:\n def __init__(self, uri: str) -> None:\n self._parsed = urlparse(uri, allow_fragments=False)\n \n @property\n def bucket(self) -> str:\n return self._parsed.netloc\n \n @property\n def key(self) -> str:\n if self._parsed.query:\n return self._parsed.path.lstrip(\"/\") + \"?\" + self._parsed.query\n else:\n return self._parsed.path.lstrip(\"/\")\n \n @property\n def uri(self) -> str:\n return self._parsed.geturl()\n```\n\n资料来源：[skyvern/forge/sdk/api/aws.py:50-80](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/api/aws.py)\n\n### AWS 客户端管理\n\n采用单例模式管理 AWS 客户端实例，并设置 45 分钟的 TTL 以确保连接有效性。\n\n```python\n_aws_client: AsyncAWSClient | None = None\n_aws_client_created_at: float = 0.0\n_AWS_CLIENT_TTL_SECONDS: float = 45 * 60 # 45 mins\n```\n\n资料来源：[skyvern/forge/sdk/api/aws.py:80-90](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/api/aws.py)\n\n## MCP 集成架构\n\nModel Context Protocol (MCP) 允许外部 AI 应用连接到 Skyvern 进行浏览器自动化。\n\n### MCP Server 架构\n\n```mermaid\ngraph TD\n A[MCP Client App] --> B[Skyvern MCP Server]\n B --> C[Local Skyvern]\n B --> D[Skyvern Cloud]\n \n C --> E[Browser Agent]\n D --> E\n```\n\n资料来源：[integrations/mcp/README.md:1-50](https://github.com/Skyvern-AI/skyvern/blob/main/integrations/mcp/README.md)\n\n### MCP 工具集\n\n**浏览器操作工具：**\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_navigate` | 导航到指定 URL |\n| `skyvern_click` | 点击页面元素 |\n| `skyvern_input` | 输入文本内容 |\n| `skyvern_select_option` | 选择下拉选项 |\n| `skyvern_press_key` | 模拟键盘按键 |\n| `skyvern_drag` | 拖拽操作 |\n| `skyvern_file_upload` | 文件上传 |\n| `skyvern_wait` | 等待元素或时间 |\n\n**数据提取工具：**\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_extract` | 结构化 JSON 数据提取 |\n| `skyvern_screenshot` | 页面截图 |\n| `skyvern_get_html` | 获取页面 HTML |\n| `skyvern_get_value` | 获取表单元素值 |\n\n**网络与调试工具：**\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_network_requests` | 获取网络请求列表 |\n| `skyvern_network_route` | 拦截网络请求 |\n| `skyvern_console_messages` | 获取控制台消息 |\n| `skyvern_har_start/stop` | HAR 日志记录 |\n\n**认证凭证工具：**\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `skyvern_login` | 执行网站登录 |\n| `skyvern_credential_list` | 列出存储的凭证 |\n| `skyvern_credential_get` | 获取凭证信息 |\n\n资料来源：[skyvern/cli/mcp_tools/README.md:1-60](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/mcp_tools/README.md)\n\n## 凭证与安全管理\n\n### TOTP/2FA 支持\n\nSkyvern 支持多种双因素认证方式，确保自动化任务能够处理需要 2FA 的网站。\n\n**支持的 2FA 类型：**\n\n| 类型 | 描述 |\n|------|------|\n| Numeric code | 基于时间的六位数字验证码 |\n| Magic link | 通过邮件发送的魔法链接 |\n\n资料来源：[skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx:1-50](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx)\n\n### 凭证存储\n\nSkyvern 提供安全的凭证存储机制，支持：\n\n- Skyvern Vault（内置安全存储）\n- Bitwarden 集成\n- 1Password 集成\n- Azure Key Vault 集成\n\n资料来源：[skyvern/cli/mcp_tools/README.md:30-40](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/mcp_tools/README.md)\n\n## 工作流系统架构\n\n### 工作流定义\n\n工作流由多个 Block 组成，每个 Block 代表一个独立的操作单元。\n\n**支持的 Block 类型：**\n\n| Block 类型 | 功能 |\n|------------|------|\n| HTTP Request | 发送 HTTP 请求 |\n| Print Page | 打印页面为 PDF |\n| Human Interaction | 暂停等待人工确认 |\n| Extract Data | 从页面提取结构化数据 |\n\n资料来源：[skyvern-frontend/src/routes/workflows/workflowRun/WorkflowPostRunParameters.tsx:1-80](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/workflowRun/WorkflowPostRunParameters.tsx)\n\n### 调度系统\n\nSkyvern 支持基于 Cron 表达式的任务调度功能。\n\n**调度配置参数：**\n\n| 参数 | 描述 |\n|------|------|\n| cron_expression | Cron 表达式定义执行时间 |\n| timezone | 时区设置 |\n| workflow_parameters | 工作流输入参数 |\n\n资料来源：[skyvern-frontend/src/routes/schedules/ScheduleDetailPage.tsx:1-60](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/schedules/ScheduleDetailPage.tsx)\n\n## 任务创建流程\n\n### 任务表单配置\n\n创建任务时，用户需要提供以下核心参数：\n\n**基本参数：**\n\n| 参数 | 说明 |\n|------|------|\n| Navigation Goal | 导航目标和操作指令 |\n| Navigation Payload | 可选的路由参数和状态信息 |\n\n**高级参数：**\n\n| 参数 | 说明 |\n|------|------|\n| Webhook Callback URL | 任务完成后的回调通知地址 |\n| Proxy Location | 代理服务器位置 |\n| Browser Session ID | 持久化浏览器会话 ID |\n| Browser Address | 远程浏览器地址 |\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx:1-50](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx)\n\n### 任务执行流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant API\n participant Agent\n participant Browser\n participant LLM\n \n User->>API: 创建任务请求\n API->>Agent: 分发任务\n Agent->>LLM: 请求决策\n LLM-->>Agent: 返回操作指令\n Agent->>Browser: 执行浏览器操作\n Browser-->>Agent: 返回执行结果\n Agent->>LLM: 继续决策或结束\n Agent-->>API: 任务完成\n API-->>User: 返回结果\n```\n\n## LLM 支持\n\n### 支持的模型提供商\n\n| 提供商 | 支持模型 |\n|--------|----------|\n| OpenAI | GPT-5.5, GPT-5.4, GPT-5, GPT-4.1, o3, o4-mini |\n| Anthropic | Claude 4.7 Opus, Claude 4.6, Claude 4.5 |\n| Azure OpenAI | 任意部署的 GPT 模型 |\n| AWS Bedrock | Claude 4.7, Claude 4.6, Claude 4.5 |\n| Gemini | Gemini 3.1 Pro, Gemini 3 Flash |\n\n资料来源：[README.md:50-70](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n## 快速开始\n\n### 环境配置\n\n```bash\n# 安装 uv 包管理器\n# 创建虚拟环境\nuv sync --group dev\n\n# 初始化 Skyvern\nuv run skyvern quickstart\n\n# 启动服务\nskyvern run all\n```\n\n资料来源：[README.md:10-20](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n\n### 程序化使用\n\n```python\nfrom skyvern import Skyvern\n\nskyvern = Skyvern(api_key=\"your-api-key\")\ntask = await skyvern.run_task(\n prompt=\"Find the top post on hackernews today\",\n)\n```\n\n## 架构设计原则\n\n1. **模块化设计**：各组件职责明确，支持独立替换和扩展\n2. **异步优先**：采用异步架构支持高并发场景\n3. **工厂模式**：BrowserFactory 实现灵活的浏览器实例创建\n4. **单例管理**：AWS 客户端等资源采用单例模式避免重复创建\n5. **凭证安全**：敏感信息通过 Vault 等安全机制存储\n6. **可扩展性**：MCP 协议支持与多种外部应用集成\n\n## 总结\n\nSkyvern 的系统架构围绕浏览器自动化核心能力，通过模块化设计实现了高内聚低耦合的组件关系。Forge 应用层作为统一入口，协调 Agent 智能体、浏览器管理、数据存储和外部集成四大功能模块，为用户提供了完整的浏览器自动化解决方案。\n\n---\n\n\n\n## AI 代理系统\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-architecture), [任务系统](#page-tasks)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx)\n- [skyvern-frontend/src/routes/workflows/WorkflowScriptsPage.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/WorkflowScriptsPage.tsx)\n- [skyvern-frontend/src/routes/workflows/workflowRun/WorkflowRunTimelineBlockItem.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/workflowRun/WorkflowRunTimelineBlockItem.tsx)\n- [skyvern-frontend/src/routes/workflows/workflowRun/TaskBlockParameters.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/workflowRun/TaskBlockParameters.tsx)\n- [integrations/mcp/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/integrations/mcp/README.md)\n- [README.md](https://github.com/Skyvern-AI/skyvern/blob/main/README.md)\n
\n\n# AI 代理系统\n\n> **注意**：当前分析的源码上下文中未包含 `skyvern/forge/agent.py`、`skyvern/forge/agent_functions.py`、`skyvern/forge/sdk/copilot/agent.py` 及 `skyvern/forge/sdk/copilot/runtime.py` 等核心 AI 代理系统文件。以下内容基于前端组件和工作流相关代码进行推断性说明，实际架构细节请参阅上述核心文件。\n\n## 概述\n\nSkyvern 的 AI 代理系统是一个基于 LLM（大语言模型）驱动的自动化执行引擎，能够理解自然语言指令并在浏览器环境中完成复杂任务。该系统通过工作流（Workflow）编排多个任务块（Block），支持条件分支、人机交互、HTTP 请求执行等能力，实现端到端的自动化流程。\n\n资料来源：[integrations/mcp/README.md:1-20]()\n\n## 核心概念\n\n### 任务（Task）\n\n任务是 AI 代理执行工作的基本单元，包含以下关键属性：\n\n| 属性 | 说明 | 来源组件 |\n|------|------|----------|\n| `navigation_goal` | 自然语言描述的导航目标 | CreateNewTaskForm.tsx |\n| `navigation_payload` | 导航参数、路由或状态信息 | CreateNewTaskForm.tsx |\n| `url` | 目标网页地址 | SavedTaskForm.tsx |\n| `title` | 任务名称 | SavedTaskForm.tsx |\n| `description` | 任务目的描述 | SavedTaskForm.tsx |\n| `browser_session_id` | 持久化浏览器会话 ID | PromptBox.tsx |\n| `cdp_address` | 浏览器服务地址 | PromptBox.tsx |\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx:10-30]()\n\n### 工作流（Workflow）\n\n工作流是由多个任务块组成的有向图，定义自动化任务的执行顺序和条件逻辑。\n\n```mermaid\ngraph TD\n A[开始] --> B[条件判断块]\n B -->|条件为真| C[任务执行块]\n B -->|条件为假| D[HTTP 请求块]\n C --> E[人机交互块]\n D --> F[结束]\n E --> F\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/workflowRun/WorkflowRunTimelineBlockItem.tsx:1-40]()\n\n## 工作流执行引擎\n\n### 任务块类型\n\n工作流由不同类型的任务块组成，每种块承担特定功能：\n\n| 块类型 | 功能 | 高级设置 |\n|--------|------|----------|\n| `task_block` | 执行具体任务 | 引擎类型、错误码映射、最大重试次数、最大步数 |\n| `human_interaction` | 暂停等待人工输入 | 超时配置 |\n| `http_request` | 执行外部 API 调用 | 请求超时、认证信息 |\n| `condition_block` | 条件分支判断 | 条件表达式 |\n\n资料来源：[skyvern-frontend/src/routes/workflows/workflowRun/TaskBlockParameters.tsx:1-50]()\n\n### 执行状态与分支\n\n工作流执行时会记录以下关键状态信息：\n\n- `executed_branch_expression`：已执行的条件表达式\n- `executed_branch_next_block`：分支判断后的下一个目标块\n- `next_block_label`：下一个待执行块的标签\n\n```mermaid\ngraph LR\n A[评估条件] --> B{条件结果}\n B -->|True| C[执行 True 分支]\n B -->|False| D[执行 False 分支]\n C --> E[next_block_label]\n D --> E\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/workflowRun/WorkflowRunTimelineBlockItem.tsx:40-70]()\n\n## 代理执行流程\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ 用户输入任务 │\n├─────────────────────────────────────────────────────────────┤\n│ 1. 解析 navigation_goal（自然语言目标） │\n│ 2. 提取 navigation_payload（参数/状态） │\n│ 3. 确定初始 URL 和代理行为 │\n└─────────────────────────────────────────────────────────────┘\n ↓\n┌─────────────────────────────────────────────────────────────┐\n│ LLM 决策循环 │\n├─────────────────────────────────────────────────────────────┤\n│ • 分析当前页面状态 │\n│ • 决定下一步操作（点击/输入/滚动/导航等） │\n│ • 处理异常和错误恢复 │\n│ • 评估任务完成条件 │\n└─────────────────────────────────────────────────────────────┘\n ↓\n┌─────────────────────────────────────────────────────────────┐\n│ 浏览器自动化执行 │\n├─────────────────────────────────────────────────────────────┤\n│ • 通过 CDP（Chrome DevTools Protocol）控制浏览器 │\n│ • 可选使用代理服务器进行地理位置路由 │\n│ • 支持持久化会话复用 │\n└─────────────────────────────────────────────────────────────┘\n```\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/PromptBox.tsx:1-50]()\n\n## 高级配置选项\n\n### 执行引擎配置\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| `engine` | 使用的 LLM 引擎 | OpenAI GPT-4 |\n| `max_retries` | 失败最大重试次数 | 3 |\n| `max_steps_per_run` | 单次运行最大步数 | 50 |\n| `error_code_mapping` | 自定义错误码映射表 | - |\n\n资料来源：[skyvern-frontend/src/routes/workflows/workflowRun/TaskBlockParameters.tsx:20-45]()\n\n### 浏览器配置\n\n| 配置项 | 说明 | 示例 |\n|--------|------|------|\n| `browser_session_id` | 持久化会话标识符 | `pbs_xxx` |\n| `cdp_address` | 远程调试地址 | `http://127.0.0.1:9222` |\n| `proxy_location` | 代理服务器位置 | 各地区可选 |\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/PromptBox.tsx:50-80]()\n\n## 脚本缓存与复用\n\nSkyvern 支持脚本（Scripts）功能，允许在工作流中存储和复用代码片段：\n\n| 属性 | 说明 |\n|------|------|\n| `cache_key_value` | 脚本缓存键 |\n| `total_revisions` | 脚本版本总数 |\n| `runs` | 脚本被执行次数 |\n| `last_updated` | 最后更新时间 |\n\n资料来源：[skyvern-frontend/src/routes/workflows/WorkflowScriptsPage.tsx:20-40]()\n\n## 支持的 LLM 提供商\n\n| 提供商 | 支持模型 |\n|--------|----------|\n| OpenAI | GPT-5.5, GPT-5.4, GPT-5, GPT-4.1, o3, o4-mini |\n| Anthropic | Claude 4.7 Opus, Claude 4.6, Claude 4.5 系列 |\n| Azure OpenAI | 任意部署的 GPT 模型 |\n| AWS Bedrock | Claude 4.7, Claude 4.6, Claude 4.5 系列 |\n| Gemini | Gemini 3.1 Pro, Gemini 3 Flash |\n\n资料来源：[README.md:50-60]()\n\n## Model Context Protocol (MCP) 集成\n\nSkyvern 提供 MCP 服务器实现，允许 AI 应用连接浏览器进行自动化操作：\n\n```mermaid\ngraph LR\n A[Claude/其他 LLM 应用] -->|MCP 协议| B[Skyvern MCP 服务器]\n B -->|浏览器控制| C[网页操作]\n B -->|API 调用| D[外部服务]\n \n subgraph 连接方式\n E[本地 Skyvern 服务器]\n F[Skyvern Cloud]\n end\n \n B -.-> E\n B -.-> F\n```\n\n**MCP 支持的功能**：\n\n- 填写表单\n- 下载文件\n- 网页信息研究\n- 自动化数据采集\n\n资料来源：[integrations/mcp/README.md:1-30]()\n\n## 工作流执行统计\n\n工作流运行后提供以下关键指标：\n\n| 指标 | 说明 | 阈值颜色 |\n|------|------|----------|\n| 成功率 | 成功运行占比 | ≥80% 绿色、≥50% 黄色、<50% 红色 |\n| 运行次数 | 当前版本的执行总数 | - |\n| 历史版本数 | 早于当前版本的修订数量 | - |\n\n资料来源：[skyvern-frontend/src/routes/workflows/WorkflowScriptDetailPage.tsx:20-50]()\n\n## 调度执行\n\n工作流支持基于 Cron 表达式的定时调度：\n\n| 配置项 | 说明 |\n|--------|------|\n| `timezone` | 调度时区 |\n| `cron_expression` | Cron 表达式 |\n| `next_runs` | 接下来预计执行的时间点 |\n| `created_at` | 创建时间 |\n| `modified_at` | 最后修改时间 |\n\n调度配置界面实时显示下一次预计运行时间，支持用户选择时区和预览调度计划。\n\n资料来源：[skyvern-frontend/src/routes/schedules/ScheduleDetailPage.tsx:1-50]()\n\n## 总结\n\nSkyvern 的 AI 代理系统通过自然语言理解、工作流编排和浏览器自动化三大核心能力，实现了复杂的网页自动化任务。系统支持灵活的条件分支、人机交互、脚本复用和定时调度，可与主流 LLM 提供商集成，适用于网页数据采集、表单填写、自动化测试等多种场景。\n\n---\n\n\n\n## 任务系统\n\n### 相关页面\n\n相关主题：[工作流系统](#page-workflows), [浏览器自动化](#page-browser-automation)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skyvern/forge/sdk/schemas/task_v2.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/schemas/task_v2.py)\n- [skyvern/services/task_v2_service.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/services/task_v2_service.py)\n- [skyvern/forge/sdk/schemas/tasks.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/schemas/tasks.py)\n- [skyvern/services/task_v1_service.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/services/task_v1_service.py)\n
\n\n# 任务系统\n\n## 概述\n\n任务系统是 Skyvern 的核心模块，负责管理和自动化浏览器操作任务。该系统允许用户通过自然语言描述定义导航目标和操作步骤，Skyvern 自动解析指令并在浏览器中执行相应操作。\n\n任务系统采用双版本架构设计，包含 v1 和 v2 两个版本的服务实现，支持向后兼容的同时引入更强大的功能。任务由多个核心组件构成，包括任务请求、导航目标、导航负载和执行状态追踪。\n\n资料来源：[skyvern/services/task_v2_service.py:1-50]()\n\n## 核心数据模型\n\n### TaskRequest 任务请求\n\n任务请求是创建任务时提交的核心数据结构，包含执行任务所需的所有信息。\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| url | string | 任务起始 URL，浏览器首先导航到此页面 |\n| navigation_goal | string | 导航目标，描述 Skyvern 应执行的操作 |\n| navigation_payload | object | 导航负载，传递额外的参数、路由或状态信息 |\n| title | string | 任务名称，用于标识和管理 |\n| description | string | 任务描述，说明任务的用途 |\n\n资料来源：[skyvern/forge/sdk/schemas/tasks.py:1-30]()\n\n### TaskV2 数据模型\n\nTaskV2 是任务系统的核心数据结构，继承自基础任务模型并扩展了更多功能。\n\n```mermaid\nclassDiagram\n class TaskV2 {\n +str task_id\n +str organization_id\n +TaskRequestV2 request\n +TaskStatus status\n +List~Step~ steps\n +datetime created_at\n +datetime modified_at\n +int max_steps\n +str error\n }\n \n class TaskRequestV2 {\n +str url\n +str navigation_goal\n +Dict navigation_payload\n +str title\n +str description\n +str webhook_callback_url\n }\n \n class Step {\n +str step_id\n +str task_id\n +StepStatus status\n +str action\n +str reasoning\n +str result\n }\n \n TaskV2 --> TaskRequestV2\n TaskV2 --> Step\n```\n\n资料来源：[skyvern/forge/sdk/schemas/task_v2.py:1-100]()\n\n## 任务服务架构\n\n### TaskV1Service 服务\n\nTaskV1Service 是早期版本的任务服务实现，提供基本的任务创建、查询和执行功能。\n\n| 方法 | 功能 |\n|------|------|\n| create_task() | 创建新任务 |\n| get_task() | 获取任务详情 |\n| list_tasks() | 列出组织内的所有任务 |\n| cancel_task() | 取消正在执行的任务 |\n\n资料来源：[skyvern/services/task_v1_service.py:1-80]()\n\n### TaskV2Service 服务\n\nTaskV2Service 是当前推荐使用的任务服务版本，提供增强的功能和更好的扩展性。\n\n```mermaid\ngraph TD\n A[create_task] --> B{验证请求}\n B -->|通过| C[创建任务记录]\n B -->|失败| D[返回错误]\n C --> E[进入队列]\n E --> F{分配执行器}\n F --> G[执行任务步骤]\n G --> H{步骤完成?}\n H -->|是| I{还有更多步骤?}\n I -->|是| G\n I -->|否| J[任务完成]\n H -->|否| K[处理错误]\n K --> L[记录错误状态]\n```\n\n资料来源：[skyvern/services/task_v2_service.py:1-150]()\n\n## 任务生命周期\n\n### 任务状态流转\n\n任务在执行过程中会经历多种状态，了解这些状态有助于监控和调试任务执行。\n\n```mermaid\nstateDiagram-v2\n [*] --> Created: 创建任务\n Created --> Queued: 进入队列\n Queued --> Running: 开始执行\n Running --> Completed: 正常完成\n Running --> Failed: 执行失败\n Running --> Cancelled: 用户取消\n Completed --> [*]\n Failed --> [*]\n Cancelled --> [*]\n```\n\n### 状态详情\n\n| 状态 | 描述 |\n|------|------|\n| Created | 任务已创建，等待进入队列 |\n| Queued | 任务在队列中等待执行，通常需要1-2分钟 |\n| Running | 任务正在执行，浏览器操作进行中 |\n| Completed | 任务成功完成 |\n| Failed | 任务执行失败，可能包含错误信息 |\n| Cancelled | 用户主动取消的任务 |\n\n资料来源：[skyvern/forge/sdk/schemas/task_v2.py:50-80]()\n\n## SDK 使用指南\n\n### Python SDK 任务创建\n\n使用 Skyvern Python SDK 可以方便地创建和管理任务：\n\n```python\nfrom skyvern import Skyvern\n\nskyvern = Skyvern(api_key=\"your-api-key\")\n\n# 创建并等待任务完成\ntask = await skyvern.run_task(\n prompt=\"Find the top post on hackernews today\",\n url=\"https://news.ycombinator.com\",\n)\n\nprint(f\"Task ID: {task.task_id}\")\nprint(f\"Status: {task.status}\")\n```\n\n资料来源：[README.md:1-50]()\n\n### 异步任务执行\n\n任务可以在后台异步执行，无需保持脚本运行：\n\n```python\nimport asyncio\nfrom skyvern_langchain.client import DispatchTask\n\ndispatch_task = DispatchTask(api_key=\"your-api-key\")\n\nasync def main():\n result = await dispatch_task.ainvoke(\n \"Navigate to the Hacker News homepage and get the top 3 posts.\"\n )\n print(result)\n\nasyncio.run(main())\n```\n\n资料来源：[integrations/langchain/README.md:1-60]()\n\n## 前端集成\n\n### 任务创建表单\n\n前端界面提供直观的表单组件用于创建任务：\n\n```typescript\n// CreateNewTaskForm.tsx 核心结构\n (\n \n \n

Navigation Goal

\n

\n Where should Skyvern go and what should Skyvern do?\n

\n \n \n \n \n \n )}\n/>\n```\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx:1-30]()\n\n### 导航负载配置\n\n高级设置允许用户指定额外的导航参数：\n\n| 参数 | 描述 | 示例 |\n|------|------|------|\n| routes | 指定导航路径 | `[\"/login\", \"/dashboard\"]` |\n| states | 页面状态信息 | `{\"loggedIn\": true}` |\n| custom_headers | 自定义请求头 | `{\"Authorization\": \"Bearer xxx\"}` |\n\n资料来源：[skyvern-frontend/src/routes/tasks/create/SavedTaskForm.tsx:40-80]()\n\n## 任务执行步骤\n\n### 步骤追踪\n\n每个任务执行过程中会被分解为多个步骤，每个步骤记录详细执行信息：\n\n| 字段 | 描述 |\n|------|------|\n| step_id | 步骤唯一标识 |\n| action | 执行的浏览器操作 |\n| reasoning | LLM 推理过程 |\n| result | 操作结果 |\n| status | 步骤状态 |\n\n资料来源：[skyvern/forge/sdk/schemas/task_v2.py:80-120]()\n\n### 实时流显示\n\n前端支持实时查看任务执行画面：\n\n```typescript\n// TaskActions.tsx 流显示逻辑\nif (task?.status === Status.Running && streamImgSrc.length > 0) {\n return (\n
\n \n
\n );\n}\n```\n\n资料来源：[skyvern-frontend/src/routes/tasks/detail/TaskActions.tsx:30-50]()\n\n## 任务管理接口\n\n### 列出任务\n\n获取组织内的任务历史记录：\n\n```typescript\n// TaskHistory.tsx 任务列表结构\n\n \n ID\n URL\n Status\n Created At\n \n \n\n```\n\n资料来源：[skyvern-frontend/src/routes/tasks/list/TaskHistory.tsx:20-35]()\n\n### 查看任务详情\n\n查看特定任务的详细信息和参数：\n\n```typescript\n// TaskParameters.tsx 参数展示\n
\n
\n
\n

URL

\n

\n The starting URL for the task\n

\n
\n \n
\n
\n```\n\n资料来源：[skyvern-frontend/src/routes/tasks/detail/TaskParameters.tsx:15-35]()\n\n## 定时任务调度\n\n任务系统支持通过定时调度自动化执行任务：\n\n| 组件 | 功能 |\n|------|------|\n| CreateScheduleDialog | 创建调度对话框 |\n| WorkflowSchedulePanel | 工作流调度面板 |\n| ScheduleCard | 调度卡片展示 |\n| ScheduleDetailPage | 调度详情页面 |\n\n### 调度配置\n\n```typescript\n// CreateScheduleDialog.tsx 调度创建\n\n \n \n\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/editor/panels/schedulePanel/CreateScheduleDialog.tsx:60-80]()\n\n## 凭证与安全\n\n### TOTP 认证支持\n\n任务系统支持二次验证（2FA）集成：\n\n```typescript\n// CredentialsTotpTab.tsx\n\n```\n\n| 字段 | 描述 |\n|------|------|\n| totp_identifier | 凭证标识符（邮箱或手机号） |\n| totp_type | OTP 类型（numeric_code 或 magic_link） |\n\n资料来源：[skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx:15-40]()\n\n## 最佳实践\n\n### 1. 导航目标编写\n\n编写清晰的导航目标描述：\n\n```text\n# 推荐写法\n\"Find the top post on hackernews today and extract the title and URL\"\n\n# 避免\n\"Check the website\" # 过于模糊\n```\n\n### 2. URL 指定\n\n始终提供完整的起始 URL，避免重定向导致的定位问题。\n\n### 3. 导航负载使用\n\n对于需要传递额外状态的场景，使用导航负载而非将所有信息放在导航目标中：\n\n```json\n{\n \"routes\": [\"/login\", \"/dashboard\", \"/reports\"],\n \"context\": {\n \"user_id\": \"12345\",\n \"view_mode\": \"detailed\"\n }\n}\n```\n\n### 4. 错误处理\n\n监控任务状态并实现适当的错误处理逻辑：\n\n```python\nif task.status == Status.Failed:\n print(f\"Task failed: {task.error}\")\nelif task.status == Status.Completed:\n print(\"Task completed successfully\")\n```\n\n## 相关文档\n\n- [Skyvern 文档首页](https://skyvern.com/docs)\n- [API 参考文档](https://docs.skyvern.com)\n- [贡献指南](../CONTRIBUTING.md)\n\n---\n\n\n\n## 工作流系统\n\n### 相关页面\n\n相关主题：[任务系统](#page-tasks)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skyvern/forge/sdk/workflow/models/workflow.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/workflow/models/workflow.py)\n- [skyvern/forge/sdk/workflow/models/block.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/workflow/models/block.py)\n- [skyvern/services/workflow_service.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/services/workflow_service.py)\n- [skyvern/schemas/workflows.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/schemas/workflows.py)\n- [skyvern-frontend/src/routes/workflows/RunWorkflowForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/RunWorkflowForm.tsx)\n- [skyvern-frontend/src/routes/workflows/workflowRun/WorkflowPostRunParameters.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/workflowRun/WorkflowPostRunParameters.tsx)\n- [skyvern-frontend/src/routes/workflows/editor/nodes/StartNode/StartNode.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/editor/nodes/StartNode/StartNode.tsx)\n- [skyvern/cli/mcp_tools/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/mcp_tools/README.md)\n
\n\n# 工作流系统\n\nSkyvern 工作流系统（Workflow System）是一个用于编排多个自动化任务的核心模块，允许用户将多个浏览器任务、动作、数据提取操作等链接在一起，形成一个完整的自动化业务流程。\n\n## 系统概述\n\n工作流系统的主要功能包括：\n\n- **多步骤自动化编排**：将多个独立的浏览器任务和操作链接成连贯的工作流程\n- **灵活的参数传递**：支持在不同的块（Block）之间传递参数和数据\n- **条件分支控制**：支持基于条件的分支执行逻辑\n- **循环迭代**：支持对数据集进行遍历处理\n- **错误处理与恢复**：支持在块失败时继续执行或回退到 AI 重新生成代码\n\n## 核心数据模型\n\n### 工作流定义（WorkflowDefinition）\n\n工作流定义是整个工作流系统的核心数据结构，包含以下关键属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 工作流唯一标识符 |\n| `title` | string | 工作流标题 |\n| `description` | string | 工作流描述 |\n| `parameters` | list | 输入参数定义 |\n| `blocks` | list | 工作流中的块列表 |\n| `version` | int | 版本号 |\n| `status` | WorkflowStatus | 工作流状态 |\n| `folder_id` | string | 所属文件夹 ID |\n| `created_by` | string | 创建者 ID |\n| `edited_by` | string | 最后编辑者 ID |\n\n资料来源：[skyvern/schemas/workflows.py]()\n\n### 工作流块（WorkflowBlock）\n\n工作流块是组成工作流的基本单元，每种块类型代表不同的操作或功能。\n\n## 块类型体系\n\nSkyvern 工作流支持多种类型的块，用于构建复杂的自动化流程：\n\n| 块类型 | 说明 | 主要参数 |\n|--------|------|----------|\n| `BrowserTask` / `Taskv2` | 浏览器任务，执行网页自动化操作 | prompt, url, max_steps, totp_verification_url |\n| `Navigation` | 导航块，跳转到指定 URL | url, continue_on_failure |\n| `Action` | 动作块，执行点击、输入等操作 | action_type, selector |\n| `Extraction` | 数据提取块，从页面提取结构化数据 | json_schema, prompt |\n| `Validation` | 验证块，验证页面状态或数据 | schema, error_codes |\n| `TextPrompt` | 文本提示块，调用 LLM 生成文本 | prompt, llm_key, json_schema |\n| `HTTPRequest` | HTTP 请求块，发送 API 请求 | url, method, headers, body |\n| `Wait` | 等待块，等待指定时间或条件 | duration |\n| `PrintPage` | 打印块，打印当前页面 | format, landscape, print_background |\n| `HumanInteraction` | 人工交互块，暂停等待用户确认 | instructions, positive_descriptor |\n| `Conditional` | 条件块，基于条件选择执行分支 | expression |\n| `ForLoop` | 循环块，遍历数据集合 | iterable, loop_variable |\n| `FileDownload` | 文件下载块 | url, download_filename |\n| `Login` | 登录块 | credentials |\n| `Code` | 自定义代码块 | code, language |\n\n资料来源：[skyvern/forge/sdk/workflow/models/block.py]()\n\n### 块执行参数\n\n不同的块类型支持特定的参数配置：\n\n```typescript\n// Taskv2 块参数示例\ninterface Taskv2BlockParameters {\n prompt: string; // 任务提示词\n url: string; // 目标 URL\n max_steps: number; // 最大步数\n totp_verification_url?: string; // TOTP 验证 URL\n totp_identifier?: string; // TOTP 标识符\n disable_cache?: boolean; // 是否禁用缓存\n}\n```\n\n```typescript\n// 文本提示块参数示例\ninterface TextPromptBlockParameters {\n prompt: string; // 提示词模板\n llm_key: string; // 使用的 LLM 密钥\n json_schema?: object; // 输出 JSON Schema\n parameters: string[]; // 依赖的参数列表\n}\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/workflowRun/WorkflowPostRunParameters.tsx]()\n\n## 工作流执行流程\n\n### 执行架构\n\n```mermaid\ngraph TD\n A[开始工作流] --> B[加载工作流定义]\n B --> C[初始化参数]\n C --> D[执行第一个块]\n D --> E{块类型判断}\n E -->|Task/Action| F[启动浏览器任务]\n E -->|Extraction| G[提取数据]\n E -->|HTTPRequest| H[发送 HTTP 请求]\n E -->|Conditional| I[评估条件]\n E -->|ForLoop| J[开始循环]\n F --> K{任务状态}\n K -->|成功| L[保存结果]\n K -->|失败| M{AI Fallback?}\n M -->|是| N[重新生成代码]\n M -->|否| O[报告错误]\n L --> P{还有下一个块?}\n P -->|是| D\n P -->|否| Q[工作流完成]\n N --> F\n```\n\n### 执行模式\n\n工作流支持两种执行模式：\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| `Skyvern Agent` | 使用 AI Agent 动态生成执行代码 | 复杂、变化的网页环境 |\n| `Code` | 使用预先保存的成功运行的代码 | 稳定、可复现的任务 |\n\n```typescript\n// 开始节点配置\ninterface StartNodeData {\n runWith: 'agent' | 'code'; // 执行模式\n aiFallback: boolean; // AI 回退开关\n codeKey?: string; // 代码缓存键\n cacheKey?: string; // 缓存键\n adaptiveCaching?: boolean; // 自适应缓存\n generateScriptOnTerminal?: boolean; // 结束时生成脚本\n runSequentially?: boolean; // 顺序执行\n sequentialKey?: string; // 顺序执行键\n}\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/editor/nodes/StartNode/StartNode.tsx]()\n\n## 工作流运行管理\n\n### 工作流运行（WorkflowRun）\n\n工作流运行实例包含以下核心信息：\n\n| 属性 | 说明 |\n|------|------|\n| `workflow_run_id` | 运行唯一 ID |\n| `workflow_permanent_id` | 关联的工作流永久 ID |\n| `parent_workflow_run_id` | 父运行 ID（用于嵌套工作流） |\n| `organization_id` | 组织 ID |\n| `status` | 运行状态 |\n| `parameters` | 运行参数 |\n| `output` | 运行输出结果 |\n\n### 运行参数验证\n\n工作流运行前会对输入参数进行严格的类型验证：\n\n| 参数类型 | 验证规则 |\n|----------|----------|\n| `json` | 必填，字符串需可解析为有效 JSON |\n| `boolean` | 必填，布尔值 |\n| `integer` / `float` | 必填，需为有效数字 |\n| `file_url` | 必填，URL 格式 |\n| `string` | 可选，空字符串视为空值 |\n\n```typescript\n// 参数验证逻辑示例\nconst validateParameter = (parameter: WorkflowParameter, value: any) => {\n if (parameter.workflow_parameter_type === 'json') {\n if (value === null || value === undefined) return \"This field is required\";\n if (typeof value === 'string') {\n try {\n JSON.parse(value.trim());\n return true;\n } catch (e) {\n return \"Invalid JSON\";\n }\n }\n }\n // ... 其他类型验证\n};\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/RunWorkflowForm.tsx]()\n\n### Webhook 回调\n\n工作流完成后可向指定的 Webhook URL 发送回调通知：\n\n```typescript\ninterface WebhookConfig {\n webhookCallbackUrl: string; // 回调 URL\n // 回调将包含工作流执行的详细结果\n}\n```\n\n## 调度与定时执行\n\n### 调度配置\n\n工作流支持通过 Cron 表达式进行定时调度：\n\n| 配置项 | 说明 |\n|--------|------|\n| `cron_expression` | Cron 表达式 |\n| `timezone` | 时区设置 |\n| `schedule_name` | 调度名称（可选，自动生成） |\n| `schedule_description` | 调度描述（可选） |\n| `workflow_parameters` | 运行时参数 |\n\n### 快速预设\n\n系统提供常用的 Cron 预设：\n\n| 预设标签 | 表达式 | 说明 |\n|----------|--------|------|\n| 每小时 | `0 * * * *` | 每小时整点执行 |\n| 每天 | `0 0 * * *` | 每天午夜执行 |\n| 每周 | `0 0 * * 0` | 每周日执行 |\n| 每月 | `0 0 1 * *` | 每月1日执行 |\n\n资料来源：[skyvern-frontend/src/routes/schedules/CreateOrgScheduleDialog.tsx]()\n\n## MCP 集成\n\nSkyvern 通过 MCP（Model Context Protocol）提供工作流相关的工具函数：\n\n### 工作流管理工具\n\n| 工具名称 | 功能 |\n|----------|------|\n| `skyvern_workflow_create` | 创建新工作流 |\n| `skyvern_workflow_list` | 列出所有工作流 |\n| `skyvern_workflow_get` | 获取工作流详情 |\n| `skyvern_workflow_run` | 运行工作流 |\n| `skyvern_workflow_status` | 查询运行状态 |\n| `skyvern_workflow_update` | 更新工作流 |\n| `skyvern_workflow_delete` | 删除工作流 |\n| `skyvern_workflow_cancel` | 取消运行中的工作流 |\n| `skyvern_workflow_update_folder` | 更新工作流所属文件夹 |\n\n### 工作流构建工具\n\n| 工具名称 | 功能 |\n|----------|------|\n| `skyvern_block_schema` | 获取块类型定义 |\n| `skyvern_block_validate` | 验证块配置 |\n\n### 缓存脚本工具\n\n| 工具名称 | 功能 |\n|----------|------|\n| `skyvern_script_list_for_workflow` | 列出工作流的缓存脚本 |\n| `skyvern_script_get_code` | 获取脚本代码 |\n| `skyvern_script_versions` | 获取脚本版本历史 |\n| `skyvern_script_deploy` | 部署脚本 |\n| `skyvern_script_fallback_episodes` | 获取回退事件记录 |\n\n资料来源：[skyvern/cli/mcp_tools/README.md]()\n\n## 前端组件架构\n\n### 工作流编辑器\n\n```mermaid\ngraph TD\n A[工作流编辑器] --> B[WorkflowHistoryPanel]\n A --> C[块编辑面板]\n A --> D[StartNode]\n A --> E[WorkflowTriggerNode]\n C --> F[BlockParameters]\n F --> |TextPrompt| G[TextPromptBlockParameters]\n F --> |Taskv2| H[Taskv2BlockParameters]\n F --> |URL| I[GotoUrlBlockParameters]\n F --> |Conditional| J[ConditionalBlockParameters]\n```\n\n### 运行时信息展示\n\n工作流运行过程中的每个块都会记录详细的执行信息：\n\n| 信息类型 | 说明 |\n|----------|------|\n| `extracted_information` | 提取的数据结果（JSON 格式） |\n| `failure_reason` | 失败原因（如有） |\n| `navigation_goal` | 原始导航目标 |\n| `parameters` | 块执行参数 |\n| `diagnostics` | 诊断信息链接 |\n\n```typescript\ninterface BlockExecutionInfo {\n block_type: WorkflowBlockTypes;\n task_id?: string;\n status: Status;\n output?: object;\n executed_branch_expression?: string;\n executed_branch_result?: boolean;\n executed_branch_next_block?: string;\n}\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/workflowRun/WorkflowRunTimelineItemInfoSection.tsx]()\n\n## 数据库模型转换\n\n后端通过 `convert_to_workflow` 函数将数据库模型转换为前端可用的数据结构：\n\n```python\ndef convert_to_workflow(\n workflow_model: WorkflowModel,\n is_template: bool = False,\n) -> Workflow:\n return Workflow(\n workflow_id=workflow_model.workflow_id,\n workflow_permanent_id=workflow_model.workflow_permanent_id,\n title=workflow_model.title,\n version=workflow_model.version,\n is_saved_task=workflow_model.is_saved_task,\n is_template=is_template,\n description=workflow_model.description,\n workflow_definition=WorkflowDefinition.model_validate(\n workflow_model.workflow_definition\n ),\n # ... 其他字段映射\n )\n```\n\n资料来源：[skyvern/forge/sdk/db/utils.py]()\n\n## 常见使用场景\n\n### 场景一：发票批量下载\n\n1. 使用 **URL** 块导航到发票页面\n2. 使用 **Filter** 块设置日期过滤条件\n3. 使用 **Extraction** 块提取发票列表\n4. 使用 **ForLoop** 块遍历每个发票\n5. 使用 **FileDownload** 块下载每个发票\n\n### 场景二：电商自动化购买\n\n1. 使用 **URL** 块导航到产品页面\n2. 使用 **Browser Action** 块添加商品到购物车\n3. 使用 **Navigation** 块进入购物车页面\n4. 使用 **Validation** 块验证购物车状态\n5. 使用 **Browser Action** 块完成结账流程\n\n### 场景三：数据采集与报告\n\n1. 使用 **HTTPRequest** 块获取外部 API 数据\n2. 使用 **TextPrompt** 块使用 LLM 分析数据\n3. 使用 **Email** 块发送分析报告\n\n## 错误处理机制\n\n### 块级别错误处理\n\n每个块支持 `continue_on_failure` 配置，控制失败时的行为：\n\n| 配置值 | 行为 |\n|--------|------|\n| `true` | 继续执行下一个块 |\n| `false` | 停止工作流并报告错误 |\n\n### AI 自愈机制\n\n当使用代码执行模式失败时，系统支持自动回退到 AI Agent 重新生成代码：\n\n```\n任务失败 → 检查 AI Fallback 设置 → 启用则用 AI 重新生成 → 再次执行\n```\n\n资料来源：[skyvern-frontend/src/routes/workflows/editor/nodes/StartNode/StartNode.tsx]()\n\n## 文件夹组织\n\n工作流支持通过文件夹进行组织管理：\n\n| 操作 | 说明 |\n|------|------|\n| 创建文件夹 | `skyvern_folder_create` |\n| 列出文件夹 | `skyvern_folder_list` |\n| 获取文件夹 | `skyvern_folder_get` |\n| 更新文件夹 | `skyvern_folder_update` |\n| 删除文件夹 | `skyvern_folder_delete` |\n\n资料来源：[skyvern/cli/mcp_tools/README.md]()\n\n## 相关资源\n\n- 官方文档：https://skyvern.com/docs/workflows\n- MCP 集成文档：https://skyvern.com/docs/integrations/mcp\n- GitHub 仓库：https://github.com/Skyvern-AI/skyvern\n\n---\n\n\n\n## 浏览器自动化\n\n### 相关页面\n\n相关主题：[任务系统](#page-tasks), [AI 代理系统](#page-agents)\n\n根据提供的上下文，我无法完成此任务。\n\n**原因分析：**\n\n用户指定的源文件在当前的上下文检索中不可用：\n\n| 指定的源文件 | 状态 |\n|-------------|------|\n| `skyvern/webeye/browser_state.py` | ❌ 上下文未提供 |\n| `skyvern/webeye/actions/actions.py` | ❌ 上下文未提供 |\n| `skyvern/webeye/actions/handler.py` | ❌ 上下文未提供 |\n| `skyvern/services/browser_session_service.py` | ❌ 上下文未提供 |\n\n当前上下文仅包含：\n\n- 前端 React 组件文件（`skyvern-frontend/src/routes/...`）\n- `integrations/mcp/README.md`\n- `README.md`\n\n这些文件主要涉及 UI 界面和工作流配置，无法提供关于\"浏览器自动化\"核心实现（如 BrowserState 类、Action 类型定义、Handler 处理逻辑、BrowserSessionService 服务）的技术细节。\n\n---\n\n**建议：**\n\n请重新提交请求，确保检索范围包含以下关键模块：\n\n1. **浏览器状态管理** - `skyvern/webeye/browser_state.py`\n2. **浏览器操作定义** - `skyvern/webeye/actions/actions.py`\n3. **操作处理逻辑** - `skyvern/webeye/actions/handler.py`\n4. **浏览器会话服务** - `skyvern/services/browser_session_service.py`\n5. **额外相关文件** - 如 `skyvern/webeye/browser.py`、`skyvern/webeye/client.py` 等\n\n获取这些核心源文件后，我可以为您生成包含以下内容的完整技术 wiki：\n\n- 浏览器自动化架构图（Mermaid）\n- BrowserState 状态机流转\n- Action 类型分类表\n- Handler 处理流程\n- BrowserSessionService API\n- 配置参数参考表\n\n---\n\n\n\n## 数据库与数据模型\n\n### 相关页面\n\n相关主题：[凭证管理系统](#page-credentials)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skyvern/forge/sdk/db/models.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/db/models.py)\n- [alembic/versions](https://github.com/Skyvern-AI/skyvern/blob/main/alembic/versions)\n- [skyvern/forge/sdk/db/repositories](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/sdk/db/repositories)\n
\n\n# 数据库与数据模型\n\n## 概述\n\nSkyvern 是一个基于浏览器的自动化平台，其数据模型设计用于支持工作流执行、任务管理、凭证存储、日程调度等核心功能。系统采用 Python 作为后端开发语言，使用 SQLAlchemy 作为 ORM 框架，并通过 Alembic 进行数据库版本管理。\n\nSkyvern 的数据库层主要位于 `skyvern/forge/sdk/db/` 目录下，核心数据模型定义在 `models.py` 文件中，数据访问逻辑封装在 `repositories` 目录下。\n\n## 核心数据模型\n\n### 组织与认证模型\n\n#### Organization（组织）\n\n`Organization` 模型定义了 Skyvern 中的顶级组织实体，用于多租户隔离。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| organization_id | UUID | 组织唯一标识符 |\n| name | String | 组织名称 |\n| created_at | DateTime | 创建时间 |\n| modified_at | DateTime | 修改时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### User（用户）\n\n`User` 模型关联到特定组织，存储用户认证信息。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| user_id | UUID | 用户唯一标识符 |\n| organization_id | UUID | 所属组织 ID（外键） |\n| email | String | 用户邮箱 |\n| hashed_password | String | 密码哈希值 |\n| is_superuser | Boolean | 是否为超级管理员 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n### 工作流相关模型\n\n#### Workflow（工作流）\n\n`Workflow` 是 Skyvern 自动化的核心实体，定义了自动化任务的配置和执行逻辑。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| workflow_id | UUID | 工作流唯一标识符 |\n| organization_id | UUID | 所属组织 ID（外键） |\n| title | String | 工作流标题 |\n| description | String | 工作流描述 |\n| definition | JSON | 工作流定义（包含所有块和连接） |\n| proxy_config | JSON | 代理配置 |\n| max_steps_per_run | Integer | 每次运行的最大步数 |\n| created_at | DateTime | 创建时间 |\n| modified_at | DateTime | 修改时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### WorkflowVersion（工作流版本）\n\n用于版本控制，记录工作流的修改历史。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| workflow_version_id | UUID | 版本 ID |\n| workflow_id | UUID | 所属工作流 ID（外键） |\n| version | Integer | 版本号 |\n| definition | JSON | 该版本的完整定义 |\n| created_at | DateTime | 创建时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### WorkflowRun（工作流运行实例）\n\n记录每次工作流执行的实例及其状态。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| workflow_run_id | UUID | 运行实例 ID |\n| workflow_id | UUID | 所属工作流 ID（外键） |\n| status | Enum | 运行状态（pending/running/completed/failed） |\n| workflow_revision | Integer | 运行时使用的工作流版本 |\n| started_at | DateTime | 开始时间 |\n| completed_at | DateTime | 完成时间 |\n| error_code | String | 错误代码（如果失败） |\n| error_message | String | 错误信息 |\n| task_id | UUID | 关联的底层任务 ID |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### WorkflowBlock（工作流块实例）\n\n表示工作流运行时每个块的执行状态。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| block_id | UUID | 块实例 ID |\n| workflow_run_id | UUID | 所属运行 ID（外键） |\n| block_type | String | 块类型（task/condition/action 等） |\n| block_id_ref | String | 引用工作流定义中的块 ID |\n| status | Enum | 块执行状态 |\n| order | Integer | 执行顺序 |\n| output | JSON | 块输出数据 |\n| executed_branch_expression | String | 条件分支表达式（如果适用） |\n| executed_branch_next_block | String | 实际执行的下一个块 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n### 任务模型\n\n#### Task（任务）\n\n`Task` 是 Skyvern 底层的任务执行单元，每个工作流运行会创建相应的任务。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| task_id | UUID | 任务唯一标识符 |\n| organization_id | UUID | 所属组织 ID（外键） |\n| workflow_run_id | UUID | 关联的工作流运行 ID |\n| status | Enum | 任务状态（pending/running/completed/failed） |\n| navigation_goal | Text | 导航目标描述 |\n| navigation_payload | JSON | 导航负载参数 |\n| extracted_content | JSON | 提取的内容 |\n| failure_reason | String | 失败原因 |\n| created_at | DateTime | 创建时间 |\n| modified_at | DateTime | 修改时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### TaskStep（任务步骤）\n\n记录任务的每个执行步骤。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| step_id | UUID | 步骤 ID |\n| task_id | UUID | 所属任务 ID（外键） |\n| order | Integer | 步骤顺序 |\n| status | Enum | 步骤状态 |\n| action | String | 执行的动作 |\n| reasoning | Text | AI 推理过程 |\n| result | JSON | 步骤执行结果 |\n| error_code | String | 错误代码 |\n| error_message | String | 错误信息 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n### 凭证模型\n\n#### Credential（凭证）\n\n安全存储各种认证凭据。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| credential_id | UUID | 凭证 ID |\n| organization_id | UUID | 所属组织 ID（外键） |\n| credential_name | String | 凭证名称 |\n| credential_type | String | 凭证类型（api_key/oauth/password 等） |\n| credential_value | EncryptedString | 加密存储的凭证值 |\n| metadata | JSON | 额外元数据 |\n| created_at | DateTime | 创建时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### CustomCredentialServiceAuthToken（自定义凭证服务令牌）\n\n用于存储自定义凭证服务的认证令牌。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | UUID | 令牌 ID |\n| organization_id | UUID | 所属组织 ID（外键） |\n| token_type | String | 令牌类型 |\n| api_base_url | String | API 基础 URL |\n| api_token | EncryptedString | 加密的 API 令牌 |\n| created_at | DateTime | 创建时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### TOTP（两步验证码）\n\n存储 TOTP 相关配置。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| totp_id | UUID | TOTP ID |\n| organization_id | UUID | 所属组织 ID（外键） |\n| identifier | String | 标识符（邮箱/手机等） |\n| totp_type | Enum | TOTP 类型（numeric/magic_link） |\n| totp_value | EncryptedString | 加密的 TOTP 密钥 |\n| created_at | DateTime | 创建时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n### 日程调度模型\n\n#### Schedule（日程）\n\n用于定时触发工作流执行。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| schedule_id | UUID | 日程 ID |\n| organization_id | UUID | 所属组织 ID（外键） |\n| workflow_id | UUID | 关联的工作流 ID（外键） |\n| cron_expression | String | Cron 表达式 |\n| timezone | String | 时区 |\n| workflow_parameters | JSON | 工作流参数字典 |\n| created_at | DateTime | 创建时间 |\n| modified_at | DateTime | 修改时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n### 脚本与缓存模型\n\n#### WorkflowScript（工作流脚本）\n\n存储可重用的工作流代码片段。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| script_id | UUID | 脚本 ID |\n| organization_id | UUID | 所属组织 ID（外键） |\n| workflow_permanent_id | UUID | 关联的工作流永久 ID |\n| cache_key | String | 缓存键 |\n| current_revision | Integer | 当前版本号 |\n| created_at | DateTime | 创建时间 |\n| modified_at | DateTime | 修改时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n#### WorkflowScriptRevision（脚本版本）\n\n存储脚本的各个版本。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| revision_id | UUID | 版本 ID |\n| script_id | UUID | 所属脚本 ID（外键） |\n| revision | Integer | 版本号 |\n| content | Text | 脚本内容 |\n| created_at | DateTime | 创建时间 |\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n## 数据仓库层\n\n### Repository 模式\n\nSkyvern 使用 Repository 模式封装数据访问逻辑，所有仓库类位于 `skyvern/forge/sdk/db/repositories` 目录下。\n\n```mermaid\ngraph TD\n A[Service Layer] --> B[Repository Layer]\n B --> C[SQLAlchemy Session]\n C --> D[(Database)]\n \n E[OrganizationRepository] --> B\n F[WorkflowRepository] --> B\n G[TaskRepository] --> B\n H[CredentialRepository] --> B\n I[ScheduleRepository] --> B\n```\n\n### 核心 Repository 类\n\n| Repository 类 | 职责 | 主要方法 |\n|--------------|------|---------|\n| OrganizationRepository | 组织管理 | create, get, update, delete |\n| WorkflowRepository | 工作流 CRUD | create_workflow, get_workflow, update_workflow |\n| WorkflowRunRepository | 工作流运行管理 | create_run, get_run, update_status |\n| TaskRepository | 任务管理 | create_task, get_task, update_task |\n| TaskStepRepository | 任务步骤管理 | create_step, get_steps |\n| CredentialRepository | 凭证管理 | create_credential, get_credential |\n| ScheduleRepository | 日程管理 | create_schedule, get_schedules |\n| WorkflowScriptRepository | 脚本管理 | create_script, get_revisions |\n\n资料来源：[skyvern/forge/sdk/db/repositories]()\n\n## 数据库迁移\n\n### Alembic 版本管理\n\nSkyvern 使用 Alembic 进行数据库版本控制，迁移文件位于 `alembic/versions/` 目录。\n\n迁移目录结构：\n```\nalembic/\n├── env.py # Alembic 环境配置\n├── script.py.mako # 迁移脚本模板\n└── versions/ # 迁移版本文件\n ├── xxx_initial.py\n ├── xxx_add_workflow.py\n ├── xxx_add_credential.py\n └── ...\n```\n\n### 迁移操作\n\n```mermaid\ngraph LR\n A[修改 models.py] --> B[生成迁移脚本]\n B --> C[alembic revision --autogenerate]\n C --> D[应用迁移]\n D --> E[alembic upgrade head]\n```\n\n资料来源：[alembic/versions]()\n\n## 数据关系图\n\n### 工作流执行数据流\n\n```mermaid\ngraph TD\n A[Workflow] -->|1:N| B[WorkflowVersion]\n A -->|1:N| C[WorkflowRun]\n C -->|1:N| D[WorkflowBlock]\n C -->|1:1| E[Task]\n E -->|1:N| F[TaskStep]\n \n A -->|1:N| G[Schedule]\n \n A -->|1:N| H[WorkflowScript]\n H -->|1:N| I[WorkflowScriptRevision]\n \n J[Organization] -->|1:N| A\n J -->|1:N| K[Credential]\n J -->|1:N| E\n```\n\n### 凭证存储结构\n\n```mermaid\ngraph TD\n A[Organization] -->|1:N| B[Credential]\n A -->|1:N| C[CustomCredentialServiceAuthToken]\n A -->|1:N| D[TOTP]\n \n B -->|credential_type| E[api_key]\n B -->|credential_type| F[oauth]\n B -->|credential_type| G[password]\n \n D -->|totp_type| H[numeric]\n D -->|totp_type| I[magic_link]\n```\n\n## 数据安全\n\n### 敏感数据加密\n\n以下字段使用 `EncryptedString` 类型存储，确保敏感信息在数据库中加密：\n\n- `Credential.credential_value` - 凭证值\n- `CustomCredentialServiceAuthToken.api_token` - API 令牌\n- `TOTP.totp_value` - TOTP 密钥\n\n资料来源：[skyvern/forge/sdk/db/models.py]()\n\n### 组织隔离\n\n所有数据模型都包含 `organization_id` 字段，确保多租户环境下的数据隔离。数据访问时必须指定组织 ID，防止跨租户数据泄露。\n\n## 与前端的交互\n\n### API 端点\n\n前端通过 REST API 与后端交互，关键的数据接口包括：\n\n| 接口路径 | 用途 |\n|---------|------|\n| /api/v1/workflows | 工作流管理 |\n| /api/v1/tasks | 任务管理 |\n| /api/v1/credentials | 凭证管理 |\n| /api/v1/schedules | 日程管理 |\n| /api/v1/scripts | 脚本管理 |\n\n资料来源：[skyvern-frontend/src/routes/workflows/WorkflowScriptsPage.tsx]()\n资料来源：[skyvern-frontend/src/routes/schedules/ScheduleDetailPage.tsx]()\n\n### 状态管理\n\n前端使用 React Query 或类似工具进行服务端状态管理，从后端 API 获取数据后缓存并同步到 UI 组件。\n\n```mermaid\nsequenceDiagram\n Frontend->>Backend: GET /api/v1/workflows\n Backend->>Database: SELECT workflows\n Database->>Backend: workflow data\n Backend->>Frontend: JSON response\n Frontend->>Frontend: Update UI state\n```\n\n## 总结\n\nSkyvern 的数据库设计采用清晰的分层架构，核心数据模型覆盖了组织管理、工作流自动化、任务执行、凭证安全和日程调度等关键业务场景。通过 Repository 模式封装数据访问，配合 Alembic 进行数据库版本管理，确保了系统的可维护性和扩展性。所有敏感数据采用加密存储，组织级别的数据隔离保障了多租户环境的安全性。\n\n---\n\n\n\n## 凭证管理系统\n\n### 相关页面\n\n相关主题：[数据库与数据模型](#page-database), [浏览器自动化](#page-browser-automation)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skyvern-frontend/src/routes/workflows/components/CredentialSelector.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/components/CredentialSelector.tsx)\n- [skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx)\n- [skyvern-frontend/src/components/CustomCredentialServiceConfigForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/components/CustomCredentialServiceConfigForm.tsx)\n- [skyvern-frontend/src/routes/workflows/editor/nodes/HttpRequestNode/HttpRequestNode.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/editor/nodes/HttpRequestNode/HttpRequestNode.tsx)\n- [skyvern/cli/mcp_tools/README.md](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/cli/mcp_tools/README.md)\n
\n\n# 凭证管理系统\n\n## 概述\n\nSkyvern 的凭证管理系统（Credential Management System）是用于安全存储、管理和调用用户认证凭据的核心模块。该系统支持多种凭证类型和外部密钥管理服务集成，为浏览器自动化任务和工作流执行提供安全的身份验证能力。\n\n凭证管理系统的主要职责包括：\n\n- 安全存储密码、信用卡信息和密钥凭证\n- 集成外部密钥管理服务（Bitwarden、Azure Key Vault、1Password）\n- 支持双因素认证（2FA/TOTP）流程\n- 为工作流节点和 HTTP 请求提供凭证注入能力\n- 管理会话持久化和浏览器认证状态\n\n资料来源：[CredentialSelector.tsx:45-52]()\n\n## 凭证类型\n\nSkyvern 支持三种主要凭证类型，每种类型对应不同的使用场景。\n\n| 凭证类型 | 英文标识 | 说明 |\n|---------|---------|------|\n| 密码凭证 | password | 用于网站登录和表单认证的用户名密码组合 |\n| 信用卡凭证 | credit_card | 用于支付表单的信用卡信息存储 |\n| 密钥凭证 | secret | 用于 API 密钥、OAuth Token 等敏感字符串 |\n\n凭证类型在前端界面中通过下拉选择器呈现，用户可以根据实际需求选择相应的凭证类型进行配置。\n\n资料来源：[CredentialSelector.tsx:43-53]()\n\n## 凭证选择器组件\n\n`CredentialSelector` 是工作流编辑器中用于选择已配置凭证的 UI 组件。该组件提供以下功能：\n\n### 组件特性\n\n- 显示凭证名称和关联域名\n- 根据凭证类型显示对应标签（Password / Credit Card / Secret）\n- 支持过滤和搜索凭证列表\n- 内置凭证创建模态框入口\n\n### 数据展示\n\n凭证选择器展示每个凭证的以下信息：\n\n- 凭证名称\n- 关联 URL 的主机名（从 `tested_url` 字段提取）\n- 凭证类型标签\n- 凭证描述\n\n```tsx\n

\n {credential.credential_type === \"password\"\n ? \"Password\"\n : credential.credential_type === \"credit_card\"\n ? \"Credit Card\"\n : \"Secret\"}\n

\n```\n\n资料来源：[CredentialSelector.tsx:37-54]()\n\n## 双因素认证（TOTP）支持\n\nSkyvern 提供了完整的双因素认证（Time-based One-Time Password）支持，用于处理需要动态验证码的认证场景。\n\n### TOTP 凭证标签\n\n`CredentialsTotpTab` 组件提供 TOTP 凭证管理界面，包含以下功能：\n\n- **验证码推送表单**：用户输入收到的验证码，Skyvern 自动提取并关联到相关任务执行\n- **按标识符过滤**：支持按邮箱或手机号码筛选 TOTP 凭证记录\n- **按类型过滤**：支持选择全部类型、纯数字验证码（totp）或魔法链接（magic_link）\n\n### 2FA 代码处理流程\n\n用户在认证过程中收到包含验证码的消息后，通过推送表单将验证码提交给 Skyvern。系统自动识别验证码格式并附加到相应的运行实例。\n\n```tsx\n

Push a 2FA Code

\n

\n Paste the verification message you received. Skyvern extracts the code\n and attaches it to the relevant run.\n

\n```\n\n资料来源：[CredentialsTotpTab.tsx:14-19]()\n\n## 自定义凭证服务配置\n\n对于需要使用私有密钥管理服务的场景，Skyvern 支持配置自定义凭证服务。\n\n### 配置表单功能\n\n`CustomCredentialServiceConfigForm` 组件提供以下配置选项：\n\n- **API 基础 URL**：指定凭证服务 API 的基础地址\n- **认证令牌**：输入服务的访问令牌\n- **令牌类型**：支持多种令牌认证方式\n- **创建时间**：记录凭证服务的初始化时间\n\n### 敏感信息处理\n\n系统对敏感信息进行掩码处理，只显示令牌的前 8 个字符：\n\n```tsx\n
\n Token (masked):{\" \"}\n {parsedConfig.api_token.length > 8\n ? `${parsedConfig.api_token.slice(0, 8)}...`\n : \"********\"}\n
\n```\n\n资料来源：[CustomCredentialServiceConfigForm.tsx:23-32]()\n\n## MCP 工具集成\n\nSkyvern 通过 MCP（Model Context Protocol）提供完整的凭证管理工具集，支持在 AI 应用中调用凭证操作。\n\n### 可用工具列表\n\n| 工具名称 | 功能说明 |\n|---------|---------|\n| skyvern_login | 执行网站登录流程 |\n| skyvern_credential_list | 列出所有可用凭证 |\n| skyvern_credential_get | 获取指定凭证详情 |\n| skyvern_credential_delete | 删除指定凭证 |\n\n### 支持的密钥管理服务\n\nMCP 凭证工具支持与以下密钥管理服务集成：\n\n- **Skyvern Vault**：内置的安全存储服务\n- **Bitwarden**：开源密码管理器\n- **1Password**：商业密码管理平台\n- **Azure Key Vault**：微软云密钥管理服务\n\n所有集成都支持自动处理双因素认证（2FA）和 TOTP 流程。\n\n资料来源：[cli/mcp_tools/README.md:26-32]()\n\n## 工作流中的凭证使用\n\n### HTTP 请求节点\n\n在工作流编辑器中，`HttpRequestNode` 组件为 HTTP 请求提供凭证注入能力。支持的凭证引用格式包括：\n\n```json\n// 密码凭证引用\n{{ my_credential.username }}\n{{ my_credential.password }}\n\n// 密钥凭证引用\n{{ my_secret.secret_value }}\n```\n\n凭证变量在运行时会被自动替换为实际存储的敏感值。\n\n### 快速提示功能\n\nHTTP 请求节点内置了凭证使用指引，帮助用户正确配置认证信息：\n\n- 导入 cURL 功能：从 API 文档快速转换请求配置\n- 快速添加头部：自动插入常用的认证和内容类型头部\n- 响应数据引用：在后续节点中引用请求返回的状态码、头部和响应体\n\n资料来源：[HttpRequestNode.tsx:8-22]()\n\n## 凭证数据模型\n\n### 核心字段\n\n凭证对象包含以下核心属性：\n\n| 字段名 | 类型 | 说明 |\n|-------|------|------|\n| credential_id | string | 凭证唯一标识符 |\n| credential_type | enum | 凭证类型（password/credit_card/secret） |\n| name | string | 凭证显示名称 |\n| tested_url | string | 关联的测试 URL（可选） |\n| created_at | datetime | 创建时间戳 |\n| api_base_url | string | 自定义服务的 API 地址 |\n| api_token | string | 访问令牌（存储时加密） |\n| token_type | string | 令牌类型标识 |\n\n### 自定义凭证服务对象\n\n对于外部服务集成，凭证服务配置包含：\n\n| 字段名 | 说明 |\n|-------|------|\n| id | 服务配置唯一标识 |\n| token_type | 令牌类型 |\n| created_at | 配置创建时间 |\n| api_base_url | API 基础地址 |\n| api_token | 认证令牌（加密存储） |\n\n资料来源：[CustomCredentialServiceConfigForm.tsx:18-23]()\n\n## 安全设计\n\n### 敏感数据保护\n\n系统采用多层安全策略保护敏感凭证数据：\n\n1. **存储加密**：API 令牌等敏感信息在数据库中加密存储\n2. **显示掩码**：前端界面只显示部分令牌信息，防止信息泄露\n3. **传输安全**：通过 HTTPS 协议确保数据传输安全\n4. **访问控制**：凭证访问需要相应的权限验证\n\n### 凭证隔离\n\n每个工作区和用户拥有独立的凭证存储空间，确保不同租户之间的数据隔离。\n\n## 相关命令\n\nSkyvern CLI 提供了便捷的凭证管理命令：\n\n```bash\n# 列出所有凭证\nskyvern credential list\n\n# 获取指定凭证\nskyvern credential get \n\n# 删除凭证\nskyvern credential delete \n```\n\n## 扩展阅读\n\n- [MCP 集成文档](../integrations/mcp/README.md)\n- [工作流编辑器指南](../skyvern-frontend/src/routes/workflows/editor/README.md)\n- [浏览器自动化配置](../README.md#browser-configuration)\n\n---\n\n\n\n## 前端组件结构\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/tasks/create/CreateNewTaskForm.tsx)\n- [skyvern-frontend/src/routes/tasks/create/SavedTaskForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/tasks/create/SavedTaskForm.tsx)\n- [skyvern-frontend/src/routes/workflows/RunWorkflowForm.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/RunWorkflowForm.tsx)\n- [skyvern-frontend/src/routes/workflows/editor/panels/WorkflowHistoryPanel.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/editor/panels/WorkflowHistoryPanel.tsx)\n- [skyvern-frontend/src/routes/workflows/editor/panels/schedulePanel/ScheduleCard.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/editor/panels/schedulePanel/ScheduleCard.tsx)\n- [skyvern-frontend/src/routes/workflows/editor/nodes/StartNode/StartNode.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/editor/nodes/StartNode/StartNode.tsx)\n- [skyvern-frontend/src/routes/schedules/CreateOrgScheduleDialog.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/schedules/CreateOrgScheduleDialog.tsx)\n- [skyvern-frontend/src/routes/schedules/ScheduleDetailPage.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/schedules/ScheduleDetailPage.tsx)\n- [skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/credentials/CredentialsTotpTab.tsx)\n- [skyvern-frontend/src/routes/workflows/components/WorkflowsTable.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/components/WorkflowsTable.tsx)\n- [skyvern-frontend/src/routes/workflows/components/CreateFromTemplateDialog.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/components/CreateFromTemplateDialog.tsx)\n- [skyvern-frontend/src/routes/workflows/copilot/WorkflowCopilotChat.tsx](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern-frontend/src/routes/workflows/copilot/WorkflowCopilotChat.tsx)\n
\n\n# 前端组件结构\n\n## 概述\n\nSkyvern 前端是一个基于 React 和 TypeScript 构建的单页应用（SPA），负责提供用户与 Skyvern 自动化引擎交互的界面。前端采用现代化的组件架构，通过 `react-router-dom` 进行路由管理，使用 React Hook Form 进行表单处理，并借助 Tailwind CSS 实现样式系统。组件结构按照功能模块划分为任务（Tasks）、工作流（Workflows）、调度（Schedules）和凭证（Credentials）四大核心区域。\n\n## 目录结构\n\nSkyvern 前端源码位于 `skyvern-frontend/src/` 目录下，核心路由和组件按照以下结构组织：\n\n```\nskyvern-frontend/src/\n├── routes/ # 路由层\n│ ├── tasks/ # 任务模块\n│ │ ├── create/ # 任务创建相关组件\n│ │ └── ...\n│ ├── workflows/ # 工作流模块\n│ │ ├── editor/ # 工作流编辑器\n│ │ │ ├── panels/ # 编辑器面板\n│ │ │ ├── nodes/ # 节点组件\n│ │ │ └── Workspace.tsx\n│ │ ├── components/ # 工作流通用组件\n│ │ ├── copilot/ # AI 副驾驶组件\n│ │ └── workflowRun/ # 工作流运行相关\n│ ├── schedules/ # 调度模块\n│ ├── credentials/ # 凭证模块\n│ └── App.tsx # 应用根组件\n└── components/ # 共享组件库\n```\n\n## 核心模块架构\n\n### 1. 任务模块（Tasks）\n\n任务模块负责创建和管理自动化任务，是 Skyvern 前端的核心功能之一。\n\n#### 1.1 CreateNewTaskForm 组件\n\n`CreateNewTaskForm.tsx` 是新建任务的表单组件，提供了导航目标（Navigation Goal）的输入功能。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| navigationGoal | string | 描述 Skyvern 应该去哪里以及做什么 |\n| navigationPayload | object | 指定重要参数、路由或状态（高级设置） |\n\n组件使用 `AutoResizingTextarea` 组件实现自动调整高度的文本输入区域，当值为 `null` 时显示空字符串。高级设置区域通过条件渲染展示 `navigationPayload` 输入框。\n\n资料来源：[CreateNewTaskForm.tsx:10-25]()\n\n#### 1.2 SavedTaskForm 组件\n\n`SavedTaskForm.tsx` 用于加载和编辑已保存的任务。与 `CreateNewTaskForm` 类似，但增加了代码编辑器（CodeEditor）支持 JSON 格式的 `navigationPayload` 输入。高级设置区域可通过按钮切换显示/隐藏状态。\n\n资料来源：[SavedTaskForm.tsx:1-50]()\n\n### 2. 工作流模块（Workflows）\n\n工作流模块是 Skyvern 前端最复杂的部分，包含了可视化编辑器、执行表单、历史记录和 AI 副驾驶等功能。\n\n#### 2.1 工作流编辑器架构\n\n工作流编辑器采用节点面板（Node Panels）的架构设计，核心组件包括：\n\n- **WorkflowEditor.tsx** - 编辑器主容器\n- **WorkflowHistoryPanel.tsx** - 历史记录面板\n- **StartNode.tsx** - 起始节点配置\n\n#### 2.2 StartNode 节点配置\n\n`StartNode` 组件定义了工作流执行的核心参数：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| runWith | enum | \"agent\" | 执行方式：Skyvern Agent 或 Code |\n| aiFallback | boolean | - | 启用 AI 自愈功能，代码执行失败时自动回退到 AI 重新生成 |\n| codeKey | string | - | 可选的代码缓存键值 |\n\n组件使用 `HelpTooltip` 组件提供上下文相关的帮助提示，使用 `Select` 组件选择执行方式，使用 `Switch` 组件控制布尔选项。\n\n资料来源：[StartNode.tsx:1-40]()\n\n#### 2.3 RunWorkflowForm 执行表单\n\n`RunWorkflowForm.tsx` 是运行工作流的表单组件，集成了以下功能：\n\n**输入参数验证**\n\n针对不同类型的工作流参数，表单实现了差异化的验证逻辑：\n\n```typescript\n// JSON 类型参数验证\nif (parameter.workflow_parameter_type === \"json\") {\n if (value === null || value === undefined) {\n return \"This field is required\";\n }\n if (typeof value === \"string\") {\n const trimmed = value.trim();\n if (trimmed === \"\") {\n return \"This field is required\";\n }\n try {\n JSON.parse(trimmed);\n return true;\n } catch (e) {\n return \"Invalid JSON\";\n }\n }\n}\n\n// 布尔类型参数验证\nif (parameter.workflow_parameter_type === \"boolean\") {\n if (value === null || value === undefined) {\n return \"This field is required\";\n }\n}\n\n// 数值类型参数验证\nif (parameter.workflow_parameter_type === \"integer\" || \n parameter.workflow_parameter_type === \"float\") {\n if (value === null || value === undefined || Number.isNaN(value)) {\n return \"This field is required\";\n }\n}\n```\n\n资料来源：[RunWorkflowForm.tsx:1-80]()\n\n**Webhook 回调 URL 验证**\n\n表单使用 Zod schema 进行 URL 格式验证：\n\n```typescript\nrules={{\n validate: (value) => {\n if (value === null || value === \"\") {\n return;\n }\n if (typeof value !== \"string\") {\n return \"Invalid URL\";\n }\n const urlSchema = z.string().url({ message: \"Invalid URL\" });\n const { success } = urlSchema.safeParse(value);\n if (!success) {\n return \"Invalid URL\";\n }\n },\n}}\n```\n\n#### 2.4 WorkflowsTable 工作流列表\n\n`WorkflowsTable.tsx` 提供了工作流的分页列表展示功能，集成了分页组件（Pagination）用于导航。\n\n#### 2.5 CreateFromTemplateDialog 模板对话框\n\n模板对话框允许用户基于预设模板创建工作流，支持模板搜索和筛选功能。组件使用卡片式布局展示模板，支持模糊搜索匹配模板标题和描述。\n\n资料来源：[CreateFromTemplateDialog.tsx:1-60]()\n\n### 3. 调度模块（Schedules）\n\n调度模块管理定时执行的工作流任务。\n\n#### 3.1 CreateOrgScheduleDialog 创建调度对话框\n\n创建调度的对话框组件提供了以下功能：\n\n| 功能 | 组件类型 | 说明 |\n|------|----------|------|\n| 工作流选择 | Select | 从可用工作流列表中选择 |\n| 调度名称 | Input | 可选，自动生成如果为空 |\n| 调度描述 | Input | 可选 |\n| 参数配置 | ScheduleParametersSection | 工作流参数输入 |\n| Cron 预设 | Button Group | 常用 Cron 表达式快速选择 |\n| 自定义 Cron | Input | 手动输入 Cron 表达式 |\n\n组件预设了多个 Cron 表达式模板供快速选择：\n\n```typescript\nconst CRON_PRESETS = [\n { label: \"Every hour\", expression: \"0 * * * *\" },\n { label: \"Every day\", expression: \"0 0 * * *\" },\n { label: \"Every week\", expression: \"0 0 * * 0\" },\n // ...\n];\n```\n\n资料来源：[CreateOrgScheduleDialog.tsx:1-80]()\n\n#### 3.2 ScheduleCard 调度卡片\n\n`ScheduleCard` 组件用于在工作流编辑器面板中展示单个调度任务，包含以下功能：\n\n- 调度名称和时间显示\n- 时区信息展示\n- 启用/禁用开关（Switch）\n- 删除操作按钮\n- 下次执行时间预览\n\n```typescript\n\n onToggle(schedule.workflow_schedule_id, checked)\n }\n/>\n```\n\n资料来源：[ScheduleCard.tsx:1-50]()\n\n#### 3.3 ScheduleDetailPage 调度详情页\n\n调度详情页展示调度的完整信息，包括创建时间、最后修改时间、Cron 表达式和时区等元数据。\n\n```typescript\n
\n
\n Created\n \n {basicLocalTimeFormat(schedule.created_at)}\n \n
\n
\n Last Modified\n \n {basicLocalTimeFormat(schedule.modified_at)}\n \n
\n
\n```\n\n资料来源：[ScheduleDetailPage.tsx:1-50]()\n\n### 4. 凭证模块（Credentials）\n\n凭证模块管理用户的认证凭据，包括 2FA/TOTP 验证码处理。\n\n#### 4.1 CredentialsTotpTab TOTP 凭证管理\n\n`CredentialsTotpTab` 组件提供了以下功能：\n\n| 功能 | 说明 |\n|------|------|\n| PushTotpCodeForm | 推送 2FA 验证码表单 |\n| 标识符筛选 | 按邮箱或电话筛选 |\n| OTP 类型筛选 | 支持全部/Numeric code/Magic link |\n\n组件支持从验证消息中自动提取 TOTP 验证码并附加到相关运行任务。\n\n资料来源：[CredentialsTotpTab.tsx:1-50]()\n\n### 5. AI 副驾驶（Copilot）\n\n#### 5.1 WorkflowCopilotChat 对话界面\n\n`WorkflowCopilotChat` 组件提供了与 AI 副驾驶对话的功能，用户可以：\n\n- 描述工作流目标\n- 指定目标网站\n- 选择要使用的凭证\n- 获取 AI 生成的工作流建议\n\n组件在最后一条消息中显示建议的工作流操作按钮（Review/Accept）。\n\n```typescript\n{showProposedPanel ? (\n <>\n \n \n \n) : null}\n```\n\n资料来源：[WorkflowCopilotChat.tsx:1-60]()\n\n## 组件交互流程\n\n### 工作流执行流程\n\n```mermaid\ngraph TD\n A[选择工作流] --> B[RunWorkflowForm]\n B --> C{是否有输入参数?}\n C -->|有| D[填写参数]\n C -->|无| E[配置执行选项]\n D --> E\n E --> F{选择执行方式}\n F -->|Agent| G[使用 Skyvern Agent]\n F -->|Code| H{代码已缓存?}\n H -->|是| I[使用缓存代码执行]\n H -->|否| J[先生成代码]\n I --> K{执行失败且启用AI Fallback?}\n J --> K\n K -->|是| L[回退到 AI 重新生成]\n K -->|否| M[标记失败]\n G --> N[Webhook 回调结果]\n L --> N\n M --> N\n```\n\n### 调度创建流程\n\n```mermaid\ngraph LR\n A[CreateOrgScheduleDialog] --> B[选择工作流]\n B --> C[配置参数值]\n C --> D[设置 Cron 表达式]\n D --> E[选择时区]\n E --> F[提交创建]\n F --> G[ScheduleCard 显示]\n```\n\n## 表单验证模式\n\nSkyvern 前端采用 React Hook Form 进行表单状态管理，验证模式遵循以下规则：\n\n### 必填字段验证\n\n```typescript\n// 字符串类型\nif (parameter.workflow_parameter_type === \"string\") {\n if (value === null || value === undefined) {\n return \"This field is required\";\n }\n if (typeof value === \"string\" && value.trim() === \"\") {\n return \"This field is required\";\n }\n}\n\n// 文件 URL 类型\nif (parameter.workflow_parameter_type === \"file_url\") {\n if (value === null || value === undefined || \n (typeof value === \"string\" && value.trim() === \"\")) {\n return \"This field is required\";\n }\n}\n```\n\n### URL 验证\n\n使用 Zod schema 进行 URL 格式验证：\n\n```typescript\nconst urlSchema = z.string().url({ message: \"Invalid URL\" });\nconst { success } = urlSchema.safeParse(value);\nif (!success) {\n return \"Invalid URL\";\n}\n```\n\n## 状态管理模式\n\n### 组件状态管理\n\n组件内部使用 React Hook 管理状态：\n\n| Hook | 用途 | 示例 |\n|------|------|------|\n| useState | 本地状态 | 筛选条件、对话框开关 |\n| useForm | 表单状态 | 表单值、错误、提交处理 |\n| useMutation | 异步操作 | 创建、更新、删除操作 |\n| useQuery | 数据获取 | 工作流列表、详情查询 |\n\n### 状态提升\n\n在需要跨组件共享状态的场景中，组件通过回调函数将状态提升到父组件管理：\n\n```typescript\nconst handleParameterChange = (key: string, value: any) => {\n setParameters((prev) => ({ ...prev, [key]: value }));\n};\n```\n\n## UI 组件库\n\nSkyvern 前端使用以下核心 UI 组件库：\n\n| 组件 | 来源 | 用途 |\n|------|------|------|\n| AutoResizingTextarea | 自定义 | 自动调整高度的文本输入 |\n| CodeEditor | 自定义 | 代码/JSON 编辑器 |\n| ProxySelector | 自定义 | 代理位置选择 |\n| Select/SelectContent/SelectItem | Radix UI | 下拉选择框 |\n| Dialog/DialogContent | Radix UI | 对话框 |\n| Table/TableHeader/TableBody | Radix UI | 表格 |\n| Switch | Radix UI | 开关控件 |\n| Button | 自定义 | 按钮组件 |\n| Badge | 自定义 | 标签组件 |\n\n## 样式系统\n\n前端使用 Tailwind CSS 进行样式管理，采用以下设计规范：\n\n- **颜色系统**：使用 `slate-*` 色系定义文本和背景\n- **间距系统**：使用 `gap-*`、`space-y-*` 定义间距\n- **圆角**：使用 `rounded-lg`、`rounded-md` 定义圆角\n- **阴影**：使用 `shadow-*` 定义阴影效果\n- **深色模式**：组件支持 `dark:` 前缀实现深色模式适配\n\n## 组件导出规范\n\n每个组件文件通过命名导出（Named Export）导出组件：\n\n```typescript\nexport { WorkflowHistoryPanel };\nexport { ScheduleCard };\nexport { WorkflowsTable };\n```\n\n这种方式便于 Tree Shaking 优化和按需导入。\n\n## 总结\n\nSkyvern 前端采用了清晰的分层架构设计，将功能模块划分为任务、工作流、调度和凭证四大领域。每个领域包含表单、面板、对话框等特定类型的组件，通过 React Hook Form 实现统一的表单管理。组件之间通过回调函数和状态提升实现解耦，同时借助 TypeScript 的类型系统确保代码的健壮性。前端使用 Tailwind CSS 实现响应式设计，并支持深色模式，为用户提供一致且现代的界面体验。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Skyvern-AI/skyvern\n\n摘要：发现 23 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：what ensures it’s the correct one in that context?。\n\n## 1. 安全/权限坑 · 来源证据：what ensures it’s the correct one in that context?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：what ensures it’s the correct one in that context?\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_77591d02b4fa4efdb89fba55a9a7f08a | https://github.com/Skyvern-AI/skyvern/issues/5637 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Release v1.0.29\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v1.0.29\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d8e67eb179f5406fb5af75a063639216 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.29 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Task Execution Performance: Seeking guidance on optimizing execution speed\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Task Execution Performance: Seeking guidance on optimizing execution speed\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7f47a5abded54abfb766032115bfa71c | https://github.com/Skyvern-AI/skyvern/issues/4375 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：[Feature Request] Multi-session VNC support for local/self-hosted deployments (Live view & Take Control)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Multi-session VNC support for local/self-hosted deployments (Live view & Take Control)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8f2671eacb334774963837f8f7e8edf4 | https://github.com/Skyvern-AI/skyvern/issues/4392 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Performance bottleneck: High latency for simple form-filling workflows\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Performance bottleneck: High latency for simple form-filling workflows\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9820831a47af4ca28ef7abcc0fd7095e | https://github.com/Skyvern-AI/skyvern/issues/4439 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | README/documentation is current enough for a first validation pass.\n\n## 7. 维护坑 · 来源证据：Release v1.0.34\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Release v1.0.34\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_660eece743754686b70883d67faffd46 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.34 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 来源证据：Release v1.0.35\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Release v1.0.35\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53f24132e3214005ba1dc606965c0eb7 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.35 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Clarification on the Custom credential documentation on the Delete API with empty body\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Clarification on the Custom credential documentation on the Delete API with empty body\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a5164e5767dc4b618ce1c862ed440eaa | https://github.com/Skyvern-AI/skyvern/issues/4256 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：GROQ error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：GROQ error\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb8dab5ab6224386a6b341234a8e90be | https://github.com/Skyvern-AI/skyvern/issues/4366 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：Release v1.0.27\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.27\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_23488c9e7f354979bdbf8e9554b4b647 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.27 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：Release v1.0.30\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.30\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6929e0e36e1549e9bd95f29d1d4cfbdf | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.30 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：Release v1.0.31\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.31\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_40ca78dbdbe141f383c8d202f08db28b | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.31 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Release v1.0.32\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.32\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4eaa09d9a74f49efb0fb81c9bdebe6a3 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.32 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：Release v1.0.33\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.33\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba7d530f080e4c88ad47ac26ba2781a7 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.33 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：Release v1.0.36\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.36\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_236e050a3837462692b739322738a7a2 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.36 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：persist_browser_session flag saves sessions but never retrieves them on subsequent runs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：persist_browser_session flag saves sessions but never retrieves them on subsequent runs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b56e85161a3b4b7682c8ab13127be8d0 | https://github.com/Skyvern-AI/skyvern/issues/4390 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：Skyvern-AI/skyvern\n\n摘要：发现 23 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：what ensures it’s the correct one in that context?。\n\n## 1. 安全/权限坑 · 来源证据：what ensures it’s the correct one in that context?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：what ensures it’s the correct one in that context?\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_77591d02b4fa4efdb89fba55a9a7f08a | https://github.com/Skyvern-AI/skyvern/issues/5637 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：Release v1.0.29\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release v1.0.29\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d8e67eb179f5406fb5af75a063639216 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.29 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Task Execution Performance: Seeking guidance on optimizing execution speed\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Task Execution Performance: Seeking guidance on optimizing execution speed\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7f47a5abded54abfb766032115bfa71c | https://github.com/Skyvern-AI/skyvern/issues/4375 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：[Feature Request] Multi-session VNC support for local/self-hosted deployments (Live view & Take Control)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature Request] Multi-session VNC support for local/self-hosted deployments (Live view & Take Control)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8f2671eacb334774963837f8f7e8edf4 | https://github.com/Skyvern-AI/skyvern/issues/4392 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 5. 配置坑 · 来源证据：Performance bottleneck: High latency for simple form-filling workflows\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Performance bottleneck: High latency for simple form-filling workflows\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9820831a47af4ca28ef7abcc0fd7095e | https://github.com/Skyvern-AI/skyvern/issues/4439 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | README/documentation is current enough for a first validation pass.\n\n## 7. 维护坑 · 来源证据：Release v1.0.34\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Release v1.0.34\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_660eece743754686b70883d67faffd46 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.34 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 维护坑 · 来源证据：Release v1.0.35\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Release v1.0.35\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53f24132e3214005ba1dc606965c0eb7 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.35 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 12. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 来源证据：Clarification on the Custom credential documentation on the Delete API with empty body\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Clarification on the Custom credential documentation on the Delete API with empty body\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a5164e5767dc4b618ce1c862ed440eaa | https://github.com/Skyvern-AI/skyvern/issues/4256 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：GROQ error\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：GROQ error\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fb8dab5ab6224386a6b341234a8e90be | https://github.com/Skyvern-AI/skyvern/issues/4366 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：Release v1.0.27\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.27\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_23488c9e7f354979bdbf8e9554b4b647 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.27 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 安全/权限坑 · 来源证据：Release v1.0.30\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.30\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6929e0e36e1549e9bd95f29d1d4cfbdf | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.30 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：Release v1.0.31\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.31\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_40ca78dbdbe141f383c8d202f08db28b | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.31 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：Release v1.0.32\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.32\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4eaa09d9a74f49efb0fb81c9bdebe6a3 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.32 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：Release v1.0.33\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.33\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba7d530f080e4c88ad47ac26ba2781a7 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.33 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：Release v1.0.36\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Release v1.0.36\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_236e050a3837462692b739322738a7a2 | https://github.com/Skyvern-AI/skyvern/releases/tag/v1.0.36 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：persist_browser_session flag saves sessions but never retrieves them on subsequent runs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：persist_browser_session flag saves sessions but never retrieves them on subsequent runs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b56e85161a3b4b7682c8ab13127be8d0 | https://github.com/Skyvern-AI/skyvern/issues/4390 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 22. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | issue_or_pr_quality=unknown\n\n## 23. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | art_9274907e6629499384a5a574e4caa877 | https://github.com/Skyvern-AI/skyvern#readme | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# skyvern - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 skyvern 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：Skyvern 项目介绍。围绕“Skyvern 项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速开始指南。围绕“快速开始指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. page-agents：AI 代理系统。围绕“AI 代理系统”模拟一次用户任务，不展示安装或运行结果。\n5. page-tasks：任务系统。围绕“任务系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Skyvern 项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速开始指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-agents\n输入：用户提供的“AI 代理系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-tasks\n输入：用户提供的“任务系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Skyvern 项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速开始指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-agents：Step 4 必须围绕“AI 代理系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-tasks：Step 5 必须围绕“任务系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Skyvern-AI/skyvern#readme\n- .claude/skills/bump-version/SKILL.md\n- docs/skill.md\n- skyvern/cli/skills/qa/SKILL.md\n- skyvern/cli/skills/skyvern/SKILL.md\n- skyvern/cli/skills/smoke-test/SKILL.md\n- skyvern/cli/skills/testing/SKILL.md\n- README.md\n- skyvern/__init__.py\n- docker-compose.yml\n- .env.example\n- skyvern/cli/quickstart.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 skyvern 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：Skyvern-AI/skyvern\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install skyvern\n```\n\n来源：https://github.com/Skyvern-AI/skyvern#readme\n\n## 来源\n\n- docs: https://github.com/Skyvern-AI/skyvern#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_c306c31c798e4351af3292c822347541" }