BrowserSkill 深度指南：登录态复用驱动浏览器自动化，不打断前台浏览

BrowserSkill 深度指南登录态复用驱动浏览器自动化不打断前台浏览【免费下载链接】BrowserSkillLet AI agents use your real, logged-in browser without interrupting your work. CLI extension for browser automation across any shell-capable AI agent.项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkillBrowserSkill 是连接 AI Agent 与真实浏览器的本地桥接层由bskCLI/daemon 与浏览器扩展协同工作让任意能调用 Shell 的 Agent 复用已登录状态执行浏览器自动化。它绝不提取凭据、Cookie、Token也不触碰未被授权的标签页。读完本文可完成部署并理解从 CLI 到扩展的完整链路。设计决策与约束独立窗口隔离浏览器任务在Agent Window一个独立、可见的浏览器窗口中运行常规浏览窗口全程不受干扰。显式借用协议触碰用户已打开的标签页必须显式borrow任务结束归还避免自动化越权访问。安全边界前置「Never extract credentials, cookies, tokens」写进 crates/bsk-cli/skill/SKILL.md 顶部Agent 在安装 skill 的那一刻就获得该约束。结构化超时优先CLI 的工具调用 IPC 超时设为 35 秒略大于 daemon 的 30 秒工具超时确保调用方收到的是 daemon 的结构化超时响应而非 IPC 连接先断开见 crates/bsk-cli/src/cli/mod.rs#L71-L75。用户开关拥有最终决定权借用确认、人工协助两个开关在插件弹窗中保存--unattended、BSK_REQUEST_HELPoff等旧参数只保留兼容识别不能覆盖插件设置。无账号系统远程连接依赖内置的设备配对、凭据轮换与吊销不要求鉴权网关或账号体系。架构总览数据流向为 Agent →bskCLI → 本地 daemon → 浏览器扩展 → Agent WindowAgent 从不直连浏览器。组件职责通信方式bskCLI子命令解析、自动拉起 daemon、类型化 RPC本地 JSON-line IPCbsk daemon会话与队列管理、路由、设备授权回环 WebSocket浏览器扩展执行 CDP 自动化、截图、录制持有 WebSocket 连接CLI 侧的严格分层体现在session start经ensure_daemon自动拉起 daemon 后daemon 会持住该 RPC 等待扩展重连CLI 的超时预算因此必须大于 daemon 的等待窗口否则会在 daemon 答复前就抛出虚假超时见 crates/bsk-cli/src/cli/session.rs#L26-L32。线上协议类型与 JSON Schema 全部集中在crates/bsk-protocolschema/目录下每个工具如tool_navigate_params.json、tool_observe_params.json都有参数与结果契约。最小部署路径macOS/Linux 安装 CLI 到~/.local/bin# 下载并执行官方安装脚本 curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh export PATH${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATHWindowsPowerShell一条命令完成安装irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex随后从 Chrome Web Store 或 Edge 加载项商店安装扩展再安装 skill 并做健康检查# 交互式选择 harnessSpace 选择Enter 安装验证连接状态 bsk install-skill bsk doctor沙盒环境若会在命令结束后回收后台进程需在宿主侧保持 daemon 存活沙盒内通过共享BSK_HOME与BSK_AUTO_START0连接详见 docs/sandboxed-agents.md。bsk doctor输出各项状态未安装任何 skill 时该项显示N/A仍可整体通过skill 是否被发现需另行验证。首次使用验证开一个新 Agent 会话让它打开https://example.com并总结页面成功后应调用session stop。升级一行命令先结束正在执行的浏览器任务bsk update --yes该命令安装新版本时会以默认启动配置重启运行中的 daemon用安装脚本替换二进制的场景则在任务结束后手动bsk daemon restart。商店更新扩展开发时加载的解压版本需重新构建并重新加载。商店版本可能晚于 CLI 上线。用bsk --version、bsk status核对 CLI、daemon 与扩展版本后再跑bsk doctor长截图等新功能要求两侧版本匹配。核心操作手册创建与终结会话bsk session提供start/stop/list三个子命令。关键 flag--json返回结构化输出session start必须从中保留session_id后续所有 session-scoped 命令都依赖它--no-focus在后台打开 Agent Window 不抢焦点--browser id-or-label在多浏览器多 profile场景指定目标。# 启动会话并拿到 session_id bsk session start --json # 列出活动会话 bsk session list --json # 停止单个会话位置参数接收 ID或 --all 停止全部 bsk session stop session_id无论成功失败都应session stop除非用户要求保持这也同时归还借用的标签。不要依赖空闲清理结束任务也不要为了结束任务重启共享 daemon。导航与观察导航后必须重新 observeeNref 来自某次观察捕获导航或大规模 DOM 变化后旧 ref 失效。交互前先读页面模糊结果只检查一次成功可见即停止行动。# 导航到目标 URL随后捕获一份带 eN ref 的语义化观察结果 bsk navigate https://example.com --session id bsk observe --session id大观察结果用observe --max-tokens n截断配合返回的next_cursor续读# 用上一次返回的游标续读同一份捕获每页替换 ref 映射不刷新也不悬停 bsk observe --cursor token --session id交互原语需求命令关键语义点击bsk click e3 --session id使用观察返回的新鲜 ref填写bsk fill e3 --value text --session id触发fill_value_mismatch时先读字段选择选项bsk select e3 --value option-value --session id用value属性值而非可见标签按键bsk press Enter --ref e3 --session id向目标 ref 派发按键组合悬停bsk hover e3 --session id先 hover 触发器再 observe露出元素bsk scroll-to e3 --session id返回顶层 viewport CSS 像素边界滚轮bsk wheel --delta-y 600 --session id带符号增量不保证精确距离易错点select传的是选项value属性值传可见文本会选不中。悬停标记[hover first: ...]、[has-submenu]、[expanded]用于识别触发器预期控件缺失且无标记时可尝试一次observe --probe-hover。wheel只发送带符号增量页面实际位移取决于滚动容器与惯性。scroll-to部分可见即成功完全隐藏或被裁剪的目标失败完整约定见 docs/scroll-to.md。标签借用协议借用前先列出用户标签相关步骤一结束立即归还不编造 tab IDbsk tab list --scope user --session id bsk tab borrow tab-id --session id bsk tab return tab-id --session idborrow 在 Agent Window 中选择该标签作为后续命令的默认目标不额外聚焦窗口后台创建的标签tab create --no-active要保留返回的tab_id并在各命令显式传--tab-id。插件弹窗两个开关组合出确认行为借用确认人工协助实际行为开开借用需确认求助正常弹窗开关借用需确认求助返回disabled关开借用免确认求助正常弹窗关关借用免确认求助返回disabledtab borrow --timeout 120s只改变确认等待时长默认 60 秒不决定是否需要确认。自定义借用等待时间要求 daemon 和扩展都支持协议 1.2不支持时只限制该次操作并提示升级。新版 CLI 的request-help要求 daemon 协议 1.3因为旧 daemon 可能在本地返回而不询问浏览器该限制不断开连接。人工介入与失败恢复登录、验证码、OTP、支付确认或两次尝试仍无进展时请求人工接管# 向人发起求助可附带提示语与目标 ref bsk request-help --session id --prompt Please complete sign-in --target e3结果下一步动作continued/completed重新 observe用新 ref 继续cancelled/timed_out尊重拒绝或阻塞不重复请求disabled未发生任何人工操作重新 observestale ref / 超时效果未知先观察当前状态最多重试一次fill_value_mismatch时先读字段再修正剩余差异未知标签或会话时列出当前标签/会话绝不猜 ID。禁用协助后的行为边界不请求协助也不重新启用它。利用现有登录态、已授权输入和可行替代方案完成已授权步骤手机扫码、人脸验证、缺失的短信码、纯文本模型无法识别的图形验证码可以如实报告受阻但继续可独立完成的工作。协助不可用不增加授权也不能仅因此判定任务完成或受阻。截图与 Canvas三种模式视口截图bsk screenshot --session id --out viewport.png元素截图加--ref e3与--full-page互斥整页截图加--full-page。返回本地 PNG 路径--json包含尺寸与字节数--out省略时用临时路径。Canvas 内容带eN canvas [visual:screenshot]标记。点击图中某点需保留截图的capture_id坐标用原始 PNG 像素# capture_id 来自截图结果--image-x/y 为原始 PNG 坐标 bsk click e3 --capture capture-id --image-x 320 --image-y 180 --session idCapture 单次使用2 分钟后过期ref 替换或更新截图也会使其失效。文件类工具bsk upload e3 --file ./report.pdf --session id会把文件披露给站点bsk download默认拒绝覆盖需要时加--overwrite。evaluate是最后手段必须检查 JSON 的.ok字段因为脚本异常时 CLI 退出码仍可能为 0。长截图子系统插件快捷功能提供三种捕获模式Full page · Automatic从顶部增量滚动并跟随追加内容、Long image · I scroll从当前位置手动滚动屏间保留重叠、Visible area捕获一次当前视口。CLI 侧对应bsk screenshot --session id --full-page --out page.png默认采集与编码超时两分钟长页面可加--timeout 5m支持 Ctrl-C 取消并恢复原始滚动位置。--scope follow默认跟随追加内容直到页面稳定--scope current只捕获捕获开始时测量的文档区域CSS 像素仍会滚动该区域露出懒加载图片但后续高度增长不扩展范围。JSON 结果包含确认的scope旧扩展不确认current时 CLI 拒绝保存。存储上一次捕获是一组 512 像素高的 PNG 瓦片加小型 manifest存放在扩展的OPFSOrigin Private File System中捕获期间只解码当前截图和小型工作 canvas不分配全页 canvas。下载由专用 worker 顺序读瓦片、应用 PNG Up filter 并用流式 zlib 写出不构建全图像素缓冲。基准测试中 3170×100062 像素的结果 RGBA 缓冲峰值约 41.7 MiB而完整全图需要约 1.27 GB见 docs/long-screenshot.md#L147。远程连接与鉴权扩展发起出站连接用户电脑无需开放任何入站端口服务器上的 Agent 经内置鉴权服务与本地浏览器配对。本地模式默认模式daemon 监听回环地址bsk daemon start # 等价于 bsk daemon start --mode local扩展中选择Local connection可退出远程连接会结束当前任务。独立服务器模式持有受浏览器信任的证书后启动服务器模式保持前台运行空闲不退出bsk daemon start --mode server \ --listen 0.0.0.0 --port 52800 \ --public-url wss://browser.example.com:52800/extension \ --tls-cert /etc/bsk/fullchain.pem \ --tls-key /etc/bsk/privkey.pemFlag默认值含义--pairing-ttl5m一次性配对有效期上限 1 小时--device-ttl90d设备寿命上限 366 天--renew-after30d扩展续期时间点须小于设备寿命--max-connections64在线浏览器容量1–1000--authorize-rate-limit60每对端 IP 每分钟配对/续期请求数授权管理用bsk daemon devices输出设备与浏览器 ID、标签、过期时间绝不输出凭据、bsk daemon revoke DEVICE_ID、bsk daemon revoke --all同时使未使用的配对链接失效。Agent 环境设置BSK_AUTO_START0让已停止的受管服务器被如实报告为不可用daemon 与 CLI 保持BSK_HOME一致该私有目录包含设备授权须跨重启与容器替换持久化。TLS 反向代理传统代理可终结 HTTPS/WSS 而无需实现鉴权daemon 监听127.0.0.1:52800--public-url wss://browser.example.com/extension将/extension与/extension/authorize两个路径转发过去并保留 WebSocket 升级头。保留Origin、Authorization、Sec-WebSocket-Protocol头绝不记录鉴权头、子协议值或请求体不在查询串中传凭据。服务器在代理后看到的是代理 IP每客户端限流须在代理侧配置服务器不信任X-Forwarded-For。无原生 TLS 时监听必须在回环非回环浏览器连接要求 WSS。配对验证流程服务器操作者生成配对链接BSK_AUTO_START0 bsk daemon pair。浏览器用户扩展弹窗选择Remote connection粘贴完整配对链接并保存。链接机密、单次使用、默认 5 分钟过期保存后配对密钥被替换为设备凭据。服务器上的 AgentBSK_AUTO_START0 bsk status --json确认目标浏览器出现生成链接或保存配对本身不是活跃连接的证明。Agent 首次验证用status中的浏览器instance_id作browser-idBSK_AUTO_START0 bsk session start --browser browser-id --no-focus --json BSK_AUTO_START0 bsk navigate https://example.com --session id BSK_AUTO_START0 bsk observe --session id BSK_AUTO_START0 bsk session stop id验证阶段按证据反馈生成链接 → 服务器列出已连接浏览器 → 页面读取成功且测试会话成功停止。远程上传/下载当前版本返回unsupported断开连接会取消任务、归还借用标签并关闭任务创建的标签用户创建的标签在清理中存活。插件与生态DeepSeek Harness 走独立插件wxg-prc-cpg/browser-skill-dsh-plugin提供原生browser_*工具并在 Web UI 展示会话dsh plugin --profile web add wxg-prc-cpg/browser-skill-dsh-plugin dsh plugin --profile web update wxg-prc-cpg/browser-skill-dsh-plugin --latest插件自带browser-skillskill无需install-skill升级后需重启该 profile。其余能调 Shell 的 harness 手动将SKILL.md复制到其 skills 目录下的browser-skill/即可。仓库结构Cargo pnpm 混合 workspace主要顶层目录crates/bsk-cli/ —bskCLI 与本地 daemon含cli/命令树、daemon/路由与授权、skill/内置 skill。crates/bsk-protocol/ — 共享协议类型schema/目录为每个工具提供参数/结果 JSON Schema。apps/extension/ — 浏览器扩展含 browser-driver、session-manager、long-screenshot、tools、transport 等模块与 vitest 测试。packages/dsh-plugin-browserskill/ — DeepSeek Harness 插件源码。packages/ui/ 与 packages/i18n/ — 扩展 UI 组件与 9 语种本地化。evals/browser/ — 确定性本地页面与 Agent 无关的浏览器能力测试台。延伸阅读docs/sandboxed-agents.mdAgent 沙盒回收后台进程时的 daemon 托管方案BSK_HOMEBSK_AUTO_START0。docs/remote-extension-connection.md服务器模式、TLS 反向代理、配对验证与第三方网关协议。docs/long-screenshot.md捕获模式、--scope语义、超时与错误码、存储与导出细节。AGENT_INSTALL.md交给 Agent 自助安装与配置 browser-skill 的完整说明。【免费下载链接】BrowserSkillLet AI agents use your real, logged-in browser without interrupting your work. CLI extension for browser automation across any shell-capable AI agent.项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考