Skyvern 会话复用Session Reuse实战指南跨运行继承浏览器登录状态【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern本篇指南围绕 Skyvern 的**运行时会话复用runtime session reuse**机制展开讲解如何把一次会话生成的pbs_*会话 ID 作为browser_session_id传给skyvern_workflow_run或skyvern_run_task让后续的一次性运行无缝接续已打开的浏览器及其登录状态。读完本文你将掌握运行时会话复用与工作流级持久化的本质区别、何时复用/何时新建的判定方法以及登录后如何用skyvern_validate做具体断言来确认会话有效。本文主体内容源自 skyvern/cli/skills/skyvern/references/sessions.md并辅以仓库源码佐证。先分清两种会话机制运行时复用 ≠ 工作流级持久化sessions.md开篇就划清了边界本文讨论的是runtime session reuse——把pbs_*ID 作为browser_session_id传给skyvern_workflow_run或skyvern_run_task让一次性运行继续使用已经打开的浏览器。它不是工作流层面的 Save Reuse Session 开关即persist_browser_session。两者的区别可以总结为维度运行时会话复用runtime session reuse工作流级持久化persist_browser_session承载形式运行请求中的browser_session_id参数pbs_*工作流定义/创建请求中的布尔字段作用范围跨独立运行共享浏览器状态跨工作流运行保留状态存档、profile 写回默认值不传即不复用默认为false关闭适用场景一次登录后紧接的后续任务、链式工作流显式要求跨运行保留状态的场景在源码中persist_browser_session的默认值确认为Falseskyvern/schemas/workflows.py 中WorkflowCreateYAMLRequest定义了persist_browser_session: bool False第 1638 行相邻还有reuse_browser_session: bool False第 1639 行。后端读取持久化状态的逻辑集中在 skyvern/forge/sdk/workflow/browser_session_persistence.py 的retrieve_persisted_workflow_browser_state_dir。原文档给出的操作原则非常明确除非用户明确要求跨运行保留状态否则不要设置persist_browser_session。该开关默认关闭且应保持关闭。同一运行内部Block 之间天然共享会话不要传 browser_session_id一个很容易踩的坑是在同一次运行内部给各个 Block 之间传递browser_session_id来保持状态。这是完全不必要的。SKILL.md明确指出Blocks inside a single workflow already share one browser session automatically — do NOT passbrowser_session_idto keep state between blocks of the same run.即单个工作流内部的多个 Block 会自动共享同一个浏览器会话登录态、页面状态在 Block 之间天然延续无需任何额外参数。仓库自带的 login-and-extract.json 示例就是这一设计的最佳写照一个loginBlock带complete_criterion: The account dashboard is visible and no login form is present.后紧跟一个extractionBlock两个 Block 通过next_block_label串联登录成功后直接在同一浏览器里提取账户摘要全程没有出现browser_session_id。运行时会话复用只服务于跨独立运行across separate runs的场景。何时复用会话何时从零开始references/sessions.md给出了两条明确的应用决策清单这是判断是否使用browser_session_id的核心依据。应该复用运行时会话Reuse的场景依赖型后续任务某个后续任务依赖你刚刚打开的会话中的状态例如刚登录完就要立刻抓取数据、执行操作链式工作流运行后一个工作流运行需要继承前一个运行已经建立好的认证状态避免重复登录。典型形态第一次运行负责打开网站并完成登录第二次运行带着browser_session_id继续在这个已认证的浏览器里执行任务。应该重新开始Start fresh的场景会话看起来无效或已过期登录态失效、页面已回退到登录页站点有严格的反自动化锁定策略复用旧会话反而容易触发风控或封禁并行运行相互独立的任务多个互不相关的任务并行执行时各自使用独立会话更安全避免共享状态相互干扰。获取一个可复用的会话创建、连接与关闭要拿到pbs_*会话 ID需要先创建会话。SKILL.md的 Step 3 给出了三种途径# 云端会话默认适用于公网 URL skyvern browser session create --timeout 30 # 本地会话用于 localhost URL 或自托管模式 skyvern browser session create --local --timeout 30 # 通过 CDP 连接已有浏览器 skyvern browser session connect --cdp ws://localhost:9222会话状态会在命令之间保持session create之后后续命令自动附加到该会话如需显式指定可用--session pbs_...覆盖任务结束后用skyvern browser session close关闭。对应的 CLI 实现位于 skyvern/cli/commands/browser.pysession create第 710 行起支持--timeout会话超时分钟数默认 60、--proxy如 RESIDENTIAL、--local、--headless和--json参数成功后会保存session_id、mode和timeout_minutessession close第 755 行起支持--session指定会话 ID 或--cdp指定要断开的 WebSocket 地址关闭云端会话时还会尽力抓取录制文件recordings和下载文件downloaded_files的 URL 供后续查看。跨运行复用把 pbs_* 传给 skyvern_workflow_run 或 skyvern_run_task这是整个机制的核心操作。无论是工作流运行还是任务运行在发起第二次运行时带上之前会话的pbs_*ID 即可。场景一工作流运行复用skyvern_workflow_run在 MCP 工具 skyvern/cli/mcp_tools/workflow.py 中skyvern_workflow_run的第 2080–2082 行定义了browser_session_id参数其说明为Reuse an existing browser session (pbs_...) to preserve login state即复用现有浏览器会话pbs_...以保留登录状态。该工具签名还包含workflow_idwpid_...、parametersJSON 字符串、webhook_url、proxy_location、wait、timeout_seconds默认 300范围 10–3600与run_with等参数。典型调用形态skyvern_workflow_run( workflow_idwpid_123, parameters{email:userco.com}, browser_session_idpbs_xxx, # 复用已登录会话 waittrue )场景二一次性任务复用skyvern_run_task在 skyvern/cli/mcp_tools/browser.py 中skyvern_run_task第 3088 行起通过session_id参数接收pbs_*会话 ID其文档描述为 Browser session ID (pbs_...)。其余参数包括prompt自然语言任务描述、cdp_url、url运行前导航到的地址省略则使用当前页面、data_extraction_schemaJSON Schema、max_steps和timeout_seconds默认 180范围 10–1800。该工具始终使用 engine 2.0定位为一次性探索性任务不适合生产级或可复用自动化。典型调用形态skyvern_run_task( prompt在已登录状态下导出本月订单列表, session_idpbs_xxx, # 复用先前登录的会话 urlhttps://example.com/orders )互斥约束start_fresh_browser 与 browser_session_id 不能同时使用值得注意的源码细节在 skyvern/forge/sdk/workflow/models/workflow.py 中WorkflowRun模型持有browser_session_id: str | None None第 50 行并带有显式校验逻辑第 91 行起start_fresh_browsercannot be combined withbrowser_session_id也就是说强制新开浏览器与复用指定会话在语义上互斥二者同时设置会被拒绝。设计意图在于start_fresh_browser是显式要求干净环境而复用会话则隐含接受历史状态两者不可能同时成立。关键验证步骤登录后必须用具体条件做断言复用会话的前提是会话确实有效。原文档强调登录完成后应执行skyvern_validate并给出具体的、可观测的校验条件而不是模糊的是否登录成功用户头像可见user avatar visible登出按钮存在logout button present账户仪表盘标题已显示account dashboard heading shown。选择其中一个或组合作为校验条件即可。skyvern_validate是 skyvern/cli/mcp_tools/browser.py 中第 2982 行起定义的 MCP 工具参数为prompt校验条件描述如 the login form is visible可配合session_id与cdp_url使用。它是 Skyvern 最廉价的 AI 判定路径返回布尔值只回答 yes/no 问题不做数据抽取。其 SDK 等价调用为await page.validate(prompt)。调用示例skyvern_validate( prompt用户头像可见且页面上不存在登录表单, session_idpbs_xxx )返回true才说明会话处于可用状态可以放心交给后续任务复用返回false则按重新开始策略处理新开会话重新登录。端到端实操示例登录 → 验证 → 复用将上述步骤串起来一个完整的登录 跨运行复用链路如下# 第一步创建会话拿到 pbs_xxx skyvern browser session create --timeout 30 # 第二步在会话中完成登录不要用 type 直接输入密码务必使用存储的凭据 skyvern credentials add --name my-login --type password --username userco.com skyvern credential list # 找到 credential ID skyvern browser login --url https://login.example.com --credential-id cred_123 # 第三步用具体条件验证登录成功 skyvern browser validate --prompt Is the user logged in? Look for a dashboard or avatar. # 第四步后续运行携带 --session pbs_xxx 复用该登录态 skyvern browser run-task --url https://example.com/orders --prompt 导出订单列表 --session pbs_xxx对于工作流场景则是把browser_session_id作为运行参数传入skyvern_workflow_run见上文场景一。如果采用工作流定义方式可以参考仓库示例 login-and-extract.json登录 Block 使用complete_criterion描述登录成功的可验证标准仪表盘可见且无登录表单后续 Block 在同一会话中继续执行——这正是单次运行内 Block 自动共享会话的标准写法与跨运行的browser_session_id复用形成互补。会话健康度与运行状态的生命周期联动复用会话时还应关注运行状态的生命周期。references/status-lifecycle.md给出典型流转created - queued - running - completed | failed | canceled | terminated | timed_out其中paused是唯一的非终态附加状态运行被挂起可恢复。实操建议为每类工作流定义最大运行时长对长时间停留在非终态的运行设置告警超阈值即排查追踪失败特征failure signatures用于后续会话策略的优先级排序。当一次复用运行以failed、timed_out等终态结束时通常意味着会话状态可能已损坏或页面发生结构性变化下一次运行应优先考虑新建会话而不是继续复用同一个pbs_*。常见陷阱与注意事项汇总不要在同一次运行的 Block 之间传browser_session_id——Block 已自动共享会话传了反而可能造成混淆不要随意打开persist_browser_session——该开关默认关闭False见 skyvern/schemas/workflows.py 第 1638 行仅在用户明确要求跨运行状态保留时才考虑启用工作流未开启持久化时后端在浏览器档案相关路由中会直接返回 400 Workflow does not persist browser sessions见 skyvern/forge/sdk/routes/browser_profiles.py登录验证必须具体化——skyvern_validate的 prompt 要落到头像可见 / 登出按钮存在 / 仪表盘标题显示这类可观测断言上避免模糊描述导致误判风控敏感的站点优先新建会话——会话复用的收益省去重复登录在有严格反自动化锁定的站点上可能被风控成本抵消并行独立任务各用各的会话——相互无关的任务并行执行时共享会话可能产生状态竞争会话过期即重建——session create的--timeout决定会话存活时长CLI 默认 60 分钟见 skyvern/cli/commands/browser.py 第 712 行超时后继续复用会得到无效会话应重新创建。总结Skyvern 的会话复用是一个轻量、按需的机制默认每个运行自带浏览器状态Block 之间自动共享只有当你想让下一次独立运行接续前一次的登录态时才需要把pbs_*作为browser_session_id传给skyvern_workflow_run或skyvern_run_task。复用的前提是会话有效——登录后务必用skyvern_validate配合头像、登出按钮、仪表盘标题等具体断言验证当会话过期、站点风控严格或任务彼此独立时则应果断新建会话。掌握复用三问跨运行吗状态有效吗站点允许吗就能安全高效地利用会话复用减少重复登录、串联复杂自动化流程。【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考