BrowserSkill 部署与原理实战指南：让 AI Agent 复用你的登录态浏览器

BrowserSkill 部署与原理实战指南让 AI Agent 复用你的登录态浏览器【免费下载链接】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 是一套本地桥接层bskCLI 与 daemon 在一端浏览器扩展在另一端让 Cursor、Claude Code、Codex 等任意能调用 Shell 的 AI Agent 直接操作你已登录的 Chrome 或 Microsoft Edge而任务全部跑在独立的 Agent Window 里不占用你正在用的窗口。读完本文你可以完成从安装、连接验证到一次真实页面任务的全流程并能向别人讲清一条bsk click命令从 Shell 到浏览器标签页的完整路径。为什么需要它两个真实场景场景一让 Agent 查内部系统而不给账号。你要让 Agent 读一个只有公司 SSO 能进的仪表盘。传统做法要么造测试账号要么让 Agent 走 API而 BrowserSkill 的做法是直接用你浏览器里现成的登录态——Agent Window 与你的配置文件共享会话任务结束后关闭窗口即可凭据从未离开浏览器README.md 明确声明Agent Window 不是独立账号也不是安全沙箱。场景二调试一个只在浏览器里能复现的 bug。让 Agent 先启动网站调试捕获复现操作然后把请求、响应体、Console 输出和页面变更连成证据链导出 JSON。捕获在你授权调试的站点上完成保留记录默认 30 天过期受 50 条 / 50 MiB 的留存预算约束docs/website-debugging.md。两个场景共同依赖的能力是读取与交互命令、标签借用与归还、human-in-loop 求助、以及有界的只读诊断console、network。最短路径上手装好、连上、跑通一次闭环第一步安装 bsk CLICLI 自带 daemon不需要单独安装。macOSApple Silicon / Intel与 Linuxx64 / ARM64用curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh export PATH${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATHWindowsPowerShellx64用irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex二进制默认落在~/.local/bin在你将要执行命令的终端里验证bsk --version如果已在运行的 Agent 找不到bsk重启它或改用绝对路径README.md 的快速开始一节。不想用安装脚本时也可以克隆仓库后用 Rust stable Node.js 22 pnpm 自行构建pnpm install --frozen-lockfile、cargo build --release --locked产物在target/release/。第二步连接浏览器扩展从 Chrome Web Store 或 Edge 加载项商店安装 BrowserSkill 扩展打开其弹窗启用本地连接并确认状态。第三步安装 skill 让 Agent 会用它bsk install-skill用空格选择你的 harnessCursor、Claude Code、Codex、OpenClaw 等回车确认非交互场景写全参数例如bsk install-skill --harness cursor --json。bsk install-skill --list可查看所有目标与安装路径。skill 本体是 crates/bsk-cli/skill/SKILL.md教会 Agent 会话生命周期与命令语义已有安装默认跳过加--force才会覆盖。第四步跑通一次真实调用先诊断再手工闭环一遍不依赖 Agentbsk doctor bsk session start --no-focus --json bsk navigate https://example.com --session id bsk observe --session id bsk session stop idsession start返回的session_id是后续所有 session 级命令的凭据。成功后再启动一个 Agent 会话让它打开 example.com 并总结页面能读回页面并主动停止会话才算真正跑通——doctor 通过只说明链路健康不代表 Agent 已发现browser-skill。能力详解按任务拆解三步验证连接步骤命令预期健康检查bsk doctor失败项按提示修复无 skill 时该项显示 N/A查看浏览器bsk browsers列出已连接扩展实例查看会话bsk session list新会话出现在列表中多浏览器并存时bsk session start --browser id-or-label显式绑定实例标签在扩展的 BrowserSkill 弹窗中命名不取自 Chrome 的 profile 名docs/browser-profiles.md。日常操作命令与语义交互前先observe用该次观察返回的新鲜eNref 行动导航或大规模 DOM 变化后重新 observe需求命令点击bsk click e3 --session id填写字段bsk fill e3 --value text --session id选择下拉项bsk select e3 --value option-value --session id按键bsk press Enter --ref e3 --session id悬停展开菜单bsk hover e3 --session id滚入视口bsk scroll-to e3 --session id滚轮bsk wheel --delta-y 600 --session id聚焦 / 失焦bsk focus e3/bsk blur e3加--session条件 → 动作规则源自 crates/bsk-cli/skill/SKILL.md当select定位选项时必须使用选项的value属性而非可见标签之后用 observe 验证结果。当悬停菜单预期控件缺失且页面无[hover ...]、[has-submenu]、[expanded]标记时只尝试一次observe --probe-hover。当观察结果过大时用observe --max-tokens n截断拿到next_cursor后用bsk observe --cursor token --session id续读同一份捕获不重新悬停crates/bsk-cli/src/cli/observe.rs。当结果模糊时只复查一次成功可见即停止不要反复刷新确认。标签借用的归还时机借用流程bsk tab list --scope user --session id查目标 →bsk tab borrow tab-id --session id→ 用完bsk tab return tab-id --session id。默认确认等待 60 秒--timeout 120s只改变等待时长是否弹窗由扩展设置决定自定义等待要求 daemon 与扩展都支持协议 1.2否则 CLI 直接拒绝crates/bsk-cli/src/cli/tab.rs。session stop会顺带归还全部借用的标签归还后标签留在原窗口不会被关闭。规则说明不要编造 tab ID一律来自tab list返回值tab create --no-active的后台标签必须记住tab_id后续命令显式传--tab-id借用确认、人工协助两个开关扩展弹窗中独立保存对所有会话最终生效--unattended、tab borrow --no-confirm、BSK_REQUEST_HELPoff已弃用无法覆盖扩展设置关闭人工协助后request-help返回disabledAgent 应重新 observe用现有登录态与已授权输入继续而不是判任务完成求助与异常恢复登录、验证码、OTP、支付确认或两次尝试仍无进展时发起人工求助bsk request-help --session id --prompt Please complete sign-in --target e3结果 → 下一步决策表结果下一步continued/completed重新 observe用新 refs 继续cancelled/timed_out尊重拒绝不重复请求disabled未发生人工操作按禁用协助规则继续已授权步骤ref 过期observe 后重试一次目标动作超时或效果未知先检查当前状态再重试动作可能已发生fill_value_mismatch先读回字段值格式可能已满足只补剩余差异截图与 Canvas 点击bsk screenshot --session id --out viewport.png bsk screenshot --session id --ref e3 --out element.png --json bsk screenshot --session id --full-page --out page.png--ref与--full-page互斥--out覆盖已有文件省略则用临时路径。Canvas 内容带eN canvas [visual:screenshot]标记后用截图返回的capture_id与原始 PNG 坐标点击画布内位置bsk click e3 --capture capture-id --image-x x --image-y y --session id。capture 单次使用、约 2 分钟过期。长截图full-page的关键语义见 docs/long-screenshot.md--scope follow默认跟随追加内容--scope current只覆盖捕获开始时测量的文档区域采集与编码截止默认 2 分钟长页面可--timeout 5mfollow模式底部 30 秒有加载指示器但高度不增长时提前报loading_stalled失败不保留部分图片。插件 Quick Actions 里同一套捕获还分三种模式Full page · Automatic、Long image · I scroll、Visible area且快捷功能在 CLI 连接关闭时也可用。文件传输与诊断边界bsk upload e3 --file ./report.pdf --session id bsk download e3 --out ./report.pdf --session id当目标文件已存在时下载默认拒绝覆盖显式加--overwrite才替换。当需要页面诊断时用console/network做有界只读读取emulate --device iphone-14只影响单个标签--off恢复。evaluate是最后手段必须检查 JSON 结果的.ok字段因为脚本抛异常时 CLI 退出码仍可能为 0。绝不 evaluate 敏感信息绝不提取凭据、Cookie、Token此约束写在 crates/bsk-cli/skill/SKILL.md 顶部。内部机制一条命令的完整链路数据流图分层拆解每层的源码依据1. CLI 层。bsk用 clap 派生解析动词-名词子命令树覆盖 session、tab、screenshot、observe、navigate、click 等全部命令crates/bsk-cli/src/cli/mod.rs。全局标志有--json机器可读输出、--quiet、-v/-vvdebug/trace。一个值得注意的数字工具调用的 IPC 超时设为 35 秒略大于 daemon 的 30 秒工具超时——这样调用方收到的是 daemon 返回的结构化超时错误而不是 IPC 连接先断开crates/bsk-cli/src/cli/mod.rs。2. 会话启动的特殊等待。session start时 daemon 会持住这个 RPC轮询等待扩展重连上限 35 秒EXTENSION_CONNECT_WAITcrates/bsk-cli/src/daemon/browsers.rsCLI 侧的读取预算在此基础上再加 10 秒避免在 daemon 答复前误报超时crates/bsk-cli/src/cli/session.rs。session stop的 IPC 预算则是 1 小时因为停止过程包含标签归还与清理。3. daemon 路由层。本地模式下 daemon 在回环地址监听 WebSocket默认端口 52800crates/bsk-cli/src/daemon/mod.rs握手时校验Origin: chrome-extension://…。内存中维护browsers已连接扩展与sessionsAgent Window 绑定两张表每会话一个队列串行化指向同一 session 的工具调用不同 session 之间并行。状态落在~/.bsk/可用BSK_HOME覆盖daemon.lock保证单实例daemon.json记录 socket 路径、PID、端口与版本docs/architecture.md。4. 扩展执行层。扩展是 WXT 构建的 MV3 应用transport/是 WebSocket 传输tools/的ToolDispatcher分发到 21 个工具处理器session-manager/管理会话、Agent Window 与e1形式的 ref-storebrowser-driver/用 CDP 驱动真实浏览器操作docs/architecture.md。5. 会话与沙箱模型。session ID 目前是 4 位小写字母写操作只允许落在 Agent Window 内的标签除非该标签已被显式借用——这是不打断你的工作的机制基础。空闲超时session 默认 5 分钟只是安全网Agent 工作流必须显式bsk session stop id收尾docs/architecture.md、crates/bsk-cli/src/daemon/start.rs。6. 协议契约。共享线上类型集中在 crates/bsk-protocol/其 schema/ 目录为每个工具提供参数/结果 JSON Schema如tool_click_params.json、tool_observe_params.json扩展端的 TypeScript 类型在 apps/extension/src/transport/types.ts 中镜像同一帧结构靠测试与 schema dump 保持同步。进阶与边界服务器部署与远程配对Agent 跑在服务器、浏览器留在你电脑上的拓扑下由扩展发起出站连接你的电脑无需开放入站端口。独立服务器模式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.pem参数默认值约束--pairing-ttl5 分钟单次配对链接有效期最多 1 小时--device-ttl90 天设备寿命最多 366 天--renew-after30 天必须小于设备寿命--max-connections64在线浏览器容量1–1000--authorize-rate-limit60/分钟/IP1–60000配对流程服务器侧BSK_AUTO_START0 bsk daemon pair生成链接 → 扩展弹窗选 Remote connection 粘贴保存 → 服务器侧bsk status --json确认目标浏览器出现 → 用instance_id跑一次 start/navigate/observe/stop 闭环。生成链接或保存配对本身不构成活跃连接必须按证据逐阶段确认。bsk daemon devices查看授权、bsk daemon revoke DEVICE_ID或--all吊销revoke --all同时作废旧配对链接。完整约定见 docs/remote-extension-connection.md。边界条件当连接是远程时文件上传/下载返回unsupported截图等其余内容型 RPC 仍可用。当target_blank、window.open或 OAuth 弹出新标签时它们不会自动获得控制权必须显式借用。当服务器经 TLS 反代暴露时代理需转发/extension与/extension/authorize并保留 WebSocket 升级头不信任X-Forwarded-For每客户端限流放在代理侧。沙盒环境的 daemon 托管当 Agent 沙盒在每条命令结束后回收子进程时默认自动启动会失败此时把 daemon 留在宿主侧持久运行沙盒内所有命令统一带共享目录与禁用隐式启动BSK_HOME/absolute/shared/bsk BSK_AUTO_START0 bsk status --json BSK_HOME/absolute/shared/bsk bsk daemon start --foreground宿主与沙盒必须看到同一底层目录含daemon.json与run/daemon.sock只拼上相同的环境变量文本不够。先查后启status成功即复用现有 daemonbrowsers为空只说明扩展未连不是再启一个的理由。细节见 docs/sandboxed-agents.md。DeepSeek Harness 插件dsh 走同一条bsk链路但由官方插件注入原生browser_*工具并在 Web UI 展示任务预览插件自带 skill无需再bsk install-skilldsh plugin --profile web add wxg-prc-cpg/browser-skill-dsh-plugin dsh --profile web插件不自动更新升级用dsh plugin --profile web update wxg-prc-cpg/browser-skill-dsh-plugin --latest之后重启该 profile。源码与配置见 packages/dsh-plugin-browserskill/README.md其中 skill.ts 负责 skill 注入tools.ts 定义工具。升级与版本兼容先结束活动任务再bsk update --yes默认本地配置下会重启运行中的 daemon。用bsk --version、bsk status核对 CLI、daemon 与扩展版本再跑一次bsk doctor。需要记住的兼容约束长截图、--scope current等新功能要求 CLI 与扩展版本匹配旧扩展不确认current时 CLI 拒绝落盘。自定义借用等待时间与新版request-help分别要求协议 1.2 / 1.3混用版本时保留历史行为只升级扩展无法改变旧 CLI 的可执行行为。受管 skill 在 daemon 启动、session start或doctor时自动同步内容与你上次安装不一致本地编辑或自定义时暂停更新并保留文件doctor以 WARN 说明原因不会让健康检查失败。开发者视角仓库目录速览本仓库是 Cargo pnpm 双 workspace核心目录一句话职责路径职责crates/bsk-cli/bsk二进制CLI 命令树、daemon、内嵌 skillcrates/bsk-protocol/共享线上协议类型与 JSON Schema 生成apps/extension/WXT/MV3 扩展browser-driver、content 覆盖层、session-manager、tools、transport、long-screenshot、recording 等模块packages/dsh-plugin-browserskill/DeepSeek Harness 官方插件packages/ui/、packages/i18n/扩展共享 UI 组件与 9 种语言本地化evals/browser/基于确定性本地页面的浏览器能力测试台与具体 Agent 解耦docs/架构、远程连接、沙盒、长截图、调试、审计等专题文档scripts/发布与 skill 打包校验脚本延伸资料参数级细节收敛到对应文档正文不再展开安装与 Agent 自助配置AGENT_INSTALL.md架构总览含模块依赖图、文件传输边界docs/architecture.md线上协议与 schemacrates/bsk-protocol/README.md远程连接配对、TLS 反代、第三方网关协议docs/remote-extension-connection.md沙盒托管docs/sandboxed-agents.md长截图参数与错误语义docs/long-screenshot.mdscroll-to 原语的可见边界与中断契约docs/scroll-to.md网站调试工作流与留存限制docs/website-debugging.md浏览器 profile 选择docs/browser-profiles.md操作审计docs/operation-audit.mdDSH 插件用法packages/dsh-plugin-browserskill/README.md版本变化CHANGELOG.mdskill 参考文档环境、标签与 profile、交互细节、截图、文件、求助恢复、调试crates/bsk-cli/skill/references/【免费下载链接】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），仅供参考