ZCode agent-browser 会话管理完全指南多会话隔离、状态持久化与并发浏览实战【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode本篇指南聚焦 ZCode 仓库内置的 agent-browser 技能位于 .agents/skills/agent-browser中关于浏览器会话管理的核心参考文档系统讲解如何通过--session命名会话实现 Cookie、存储、缓存等浏览器上下文的完全隔离如何借助state save/state load实现登录态的持久化复用以及如何在同一台机器上并发运行多个互不干扰的浏览任务。读完本文你将掌握命名会话的创建、隔离属性清单、状态文件结构与手动/自动持久化两种方案、默认会话与清理机制以及可直接落地的认证复用、并发爬取、A/B 测试等实战脚本。说明agent-browser 技能文档源自 vercel-labs/agent-browser由 ZCode 本地集成并适配参见仓库根目录 THIRD-PARTY-NOTICES.md 中的许可与来源说明。技能允许通过Bash(npx agent-browser:*)或Bash(agent-browser:*)调用底层通过 CDPChrome DevTools Protocol直接驱动 Chrome/Chromium安装后运行agent-browser install即可下载 Chrome。目录命名会话--session 的用法会话隔离属性清单会话状态持久化常见实战模式默认会话会话清理最佳实践从文档到源码会话相关命令与配置的交叉印证命名会话--session 的用法--session是 agent-browser 实现多会话隔离的核心标志。每传入一个不同的会话名CLI 就会为它创建一个独立的浏览器上下文彼此之间在 Cookie、存储、标签页等维度上完全隔离因此你可以同时维护登录态会话与匿名浏览会话而不互相污染# 会话 1认证流程 agent-browser --session auth open https://app.example.com/login # 会话 2公开浏览独立的 cookies、storage agent-browser --session public open https://example.com # 命令按会话隔离执行 agent-browser --session auth fill e1 userexample.com agent-browser --session public get text body从 commands.md 的命令参考可以确认--session name是全局标志作用于该命令对应的整个会话。同时它还支持环境变量方式设置默认会话名export AGENT_BROWSER_SESSIONmysession # 默认会话名这意味着在同一进程中例如 CI 脚本或 Agent 的连续工具调用中你可以通过环境变量批量切换目标会话而不必在每个命令后都追加--session。ZCode 桌面端还在此基础上增加了会话作用域概念在 browser-use-plugin/docs/overview.md 中可以看到browser.tabs.get(tabId)会把标签页绑定并激活到其所属的窗口/工作区/会话作用域渲染器仅在对应作用域处于前台时才展示该标签页后台会话永远不会抢占用户当前的界面——这说明命名会话的隔离理念在 ZCode 的浏览器插件中同样贯穿到了 UI 层。会话隔离属性清单每个会话拥有独立的一套浏览器状态这是隔离的具体含义。依据参考文档每个命名会话独立维护以下内容Cookies登录态、会话令牌互不共享LocalStorage / SessionStorage站点本地存储完全隔离IndexedDB离线数据库独立CacheHTTP 缓存独立Browsing history浏览历史独立Open tabs打开中的标签页互不可见这一点与 authentication.md 中描述的持久化配置文件--profile可持久化 cookies、IndexedDB、service workers、cache形成互补--session强调的是内存级的运行时隔离进程内互不干扰而--profile强调磁盘级的长期持久化跨进程重启保留。实际使用中两者可以结合例如为不同测试用户各建一个 profile再用不同 session 名同时运行。会话状态持久化会话隔离是运行时行为而状态持久化解决的是关掉浏览器后如何恢复登录态的问题。参考文档给出了最直接的手动方案state save与state load。保存会话状态# 保存 cookies、storage 与认证状态 agent-browser state save /path/to/auth-state.json加载会话状态# 恢复已保存的状态 agent-browser state load /path/to/auth-state.json # 使用已认证的会话继续访问 agent-browser open https://app.example.com/dashboard状态文件内容结构state save产出的 JSON 文件结构如下覆盖了 Web 应用认证所需的全部关键数据{ cookies: [...], localStorage: {...}, sessionStorage: {...}, origins: [...] }需要特别指出的是状态文件以明文保存会话令牌。SKILL.md 与 authentication.md 均强调应将其加入.gitignore、用后即删并可通过环境变量AGENT_BROWSER_ENCRYPTION_KEY开启静态加密。补充自动持久化--session-name除了手动 save/loadSKILL.md 还提供了一种按名字自动保存/恢复的机制与本文主题强相关注意它使用的是--session-name而非--session两者语义不同前者会自动落盘到~/.agent-browser/sessions/# 关闭时自动保存状态下次启动时自动恢复 agent-browser --session-name myapp open https://app.example.com/login # ... 完成登录流程 ... agent-browser close # 状态自动保存到 ~/.agent-browser/sessions/ # 下次运行状态自动恢复 agent-browser --session-name myapp open https://app.example.com/dashboard # 静态加密 export AGENT_BROWSER_ENCRYPTION_KEY$(openssl rand -hex 32) agent-browser --session-name secure open https://app.example.com # 管理已保存的状态 agent-browser state list agent-browser state show myapp-default.json agent-browser state clear myapp agent-browser state clean --older-than 7此外SKILL.md 还提到可以用--session-name与手动state load结合先agent-browser --session-name myapp state load ./my-auth.json导入认证态此后该名字的状态即自动保存/恢复。常见实战模式参考文档给出了三种可直接复制运行的实战脚本覆盖了会话管理最典型的三个场景。模式一认证会话复用核心思路是登录一次多次复用有状态文件就直接加载并打开目标页没有则执行完整登录流程最后把状态保存下来#!/bin/bash # 保存登录状态一次多次复用 STATE_FILE/tmp/auth-state.json # 检查是否已有保存的状态 if [[ -f $STATE_FILE ]]; then agent-browser state load $STATE_FILE agent-browser open https://app.example.com/dashboard else # 执行登录 agent-browser open https://app.example.com/login agent-browser snapshot -i agent-browser fill e1 $USERNAME agent-browser fill e2 $PASSWORD agent-browser click e3 agent-browser wait --load networkidle # 保存以备复用 agent-browser state save $STATE_FILE fi这段逻辑在仓库自带的模板 templates/authenticated-session.sh 中有更完整的工程化实现它通过set -euo pipefail保证错误即停加载状态后用get url判断当前 URL 是否仍停留在 login/signin 页面来探测会话是否过期过期则清除状态文件重新登录还内置了发现模式先跑一次输出表单结构人工确认e1/e2/e3引用后再填登录流程并推荐使用 auth vaultauth save/auth login替代模板让 LLM 全程不接触明文密码。模式二并发爬取利用命名会话 shell 后台任务与wait可以并行启动多个互不干扰的会话同时抓取多个站点#!/bin/bash # 并发抓取多个站点 # 启动所有会话 agent-browser --session site1 open https://site1.com agent-browser --session site2 open https://site2.com agent-browser --session site3 open https://site3.com wait # 从每个会话提取内容 agent-browser --session site1 get text body site1.txt agent-browser --session site2 get text body site2.txt agent-browser --session site3 get text body site3.txt # 清理 agent-browser --session site1 close agent-browser --session site2 close agent-browser --session site3 close要点有二一是wait确保所有会话完成页面加载后再开始提取二是任务结束必须逐个close会话见下文会话清理避免守护进程残留。模式三A/B 测试会话面向同一站点的不同页面变体可以用两个会话并行打开并截图对比# 测试不同的用户体验 agent-browser --session variant-a open https://app.com?varianta agent-browser --session variant-b open https://app.com?variantb # 对比截图 agent-browser --session variant-a screenshot /tmp/variant-a.png agent-browser --session variant-b screenshot /tmp/variant-b.png默认会话当省略--session时所有命令自动落到默认会话上# 以下命令使用同一个默认会话 agent-browser open https://example.com agent-browser snapshot -i agent-browser close # 关闭默认会话默认会话适合快速、单任务的场景一旦需要并行或隔离就应该切换到命名会话。需要提醒的是close不带--session时关闭的是默认会话不要误以为它能清理其他命名会话。会话清理会话的创建与关闭必须成对出现否则浏览器守护进程会泄漏# 关闭指定会话 agent-browser --session auth close # 列出当前活跃会话 agent-browser session listSKILL.md 的补充细节如果上次会话没有正常关闭守护进程可能仍在运行此时先执行agent-browser close清理后再开始新工作对于临时/CI 环境还可以设置空闲自动关停AGENT_BROWSER_IDLE_TIMEOUT_MS60000 agent-browser open example.com即在 60 秒无活动后自动关闭守护进程避免 CI 挂机占用资源。最佳实践参考文档在结尾给出四条操作性极强的实践准则值得逐条落实1. 会话命名要有语义# 好意图清晰 agent-browser --session github-auth open https://github.com agent-browser --session docs-scrape open https://docs.example.com # 避免无意义的名字 agent-browser --session s1 open https://github.com2. 用完必须清理# 任务结束后关闭会话 agent-browser --session auth close agent-browser --session scrape close3. 安全处理状态文件# 不要提交状态文件其中包含认证令牌 echo *.auth-state.json .gitignore # 用后即删 rm /tmp/auth-state.json4. 为长任务设置超时# 为自动化脚本设置超时 timeout 60 agent-browser --session long-task get text body此外SKILL.md 在多 Agent 并发一节给出了同样的建议多个 Agent 或自动化并发运行时务必使用命名会话如--session agent1、--session agent2避免冲突并通过session list检查活跃会话。从文档到源码会话相关命令与配置的交叉印证在 commands.md 中与本文主题直接相关的命令与配置可交叉印证如下项形式用途会话标志--session name命令级指定隔离会话环境变量AGENT_BROWSER_SESSIONmysession设置默认会话名会话列表agent-browser session list查看活跃会话状态保存agent-browser state save file导出 cookies/storage/认证态状态恢复agent-browser state load file导入会话状态空闲回收AGENT_BROWSER_IDLE_TIMEOUT_MS守护进程空闲自动关闭从 ZCode 的集成方式看.agents/skills/agent-browser/SKILL.md 的 frontmatter 将该技能暴露为Bash(npx agent-browser:*)与Bash(agent-browser:*)两类允许工具即 Agent 通过 bash 调用 CLI 完成浏览器操作多命令之间通过后台守护进程保持浏览器存活因此链式调用与跨命令的会话状态都能持续生效。参考文档 authentication.md 进一步覆盖了 OAuth/SSO、2FA、HTTP Basic Auth、Cookie 认证与令牌刷新等认证态场景与本文的会话持久化配合使用可以构建完整的一次登录、长期复用、多路并行的浏览器自动化体系。【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
