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/BrowserSkill

BrowserSkill 是一个面向 AI Agent 浏览器操作的本地桥接工具。它由bskCLI、daemon 和浏览器扩展三部分组成，装好之后，任何能执行 shell 命令的 Agent（Cursor、Claude Code、Codex 等）都能直接驱动你已登录的浏览器。任务运行在独立的 Agent Window 里，你自己开的窗口照常使用，互不干扰。如果你的日常需求是让 Agent 完成需要登录的网站操作，这套工具值得花三分钟装上。

它解决什么问题

BrowserSkill 针对两个高频痛点：Agent 拿不到登录态，以及 Agent 会占用你正在用的浏览器窗口。

登录态拿不到：Agent 自己开的浏览器是空白状态，要么重新走注册流程，要么搬运 Cookie 和凭据，麻烦且有安全风险。
窗口被抢占：Agent 直接接管你当前窗口，边下命令边被它翻页面，工作被打断。

一句话定义：BrowserSkill 是 Agent 与浏览器之间的本地桥接层。Agent 通过 shell 下指令，扩展在独立窗口里执行；它复用你真实的登录状态，且不提取凭据、Cookie 或 Token。

📦 三分钟装好 BrowserSkill

目标是三步：装上 CLI、装上扩展、用bsk doctor验证连接。

组件	要求
CLI / daemon	macOS（Apple Silicon、Intel）、Linux（x64、ARM64）、Windows x64
浏览器扩展	Chrome、Microsoft Edge，以及 Chromium 125+ 的其他浏览器
Agent	任意能调用 Shell 的 Agent，或 DeepSeek Harness（走专用插件）

推荐路径是把一句话发给 Agent，让它自助安装：

按照仓库里 AGENT_INSTALL.md 的说明，在本机安装并配置 browser-skill

Agent 会完成 CLI 安装、skill 选择和连接检查；扩展需要你在 Chrome Web Store 或 Edge 加载项商店自行添加。手动安装时，macOS/Linux 直接运行仓库根目录的install.sh，Windows 用 PowerShell 运行install.ps1，默认装到~/.local/bin。给 Agent 装 skill 用非交互形式：

bsk install-skill --harness cursor --json bsk doctor

bsk install-skill不带参数时进入交互模式，用空格选择 harness。bsk doctor解决失败项后，打开扩展弹窗确认显示"已连接"，再用bsk --version核对 CLI 版本。如果你的 Agent 沙盒会在每条命令后回收后台进程，参考 docs/sandboxed-agents.md：daemon 留在宿主侧，沙盒内通过共享的BSK_HOME和BSK_AUTO_START=0连接。

skill 本体在 crates/bsk-cli/skill/SKILL.md，它教 Agent 按"启动会话 → 观察 → 操作 → 停止会话"的节奏工作。

🖱️ 能做什么：核心命令速查

拿到session_id和新鲜的@eNref，八类命令就能覆盖页面操作。

bsk session start --json bsk navigate https://example.com --session <id> bsk observe --session <id>

目标	命令
点击	`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 screenshot --session <id> --out page.png`
上传 / 下载	`bsk upload @e3 --file ./a.pdf`/`bsk download @e3 --out ./a.pdf`
借用用户标签	`bsk tab borrow <tab-id>`/`bsk tab return <tab-id>`

必须知道的语义细节：

@eNref 只对当次观察有效。导航或 DOM 大改动后会失效，操作前重新observe。
select取选项的value属性值，不是可见文字。
scroll-to返回的是按祖先裁剪后的可见边界，单位为顶层 viewport CSS 像素；部分可见即成功，完全隐藏才失败，完整约定见 docs/scroll-to.md。
借用用户标签页要"借前确认、用完即还"。tab borrow --timeout 120s只延长确认等待时间（默认 60 秒），不决定是否需要确认。
上传会把文件披露给站点，下载默认拒绝覆盖，需要时加--overwrite；两边都用你本地的路径。
大观察结果用observe --max-tokens <n>控制，配合返回的 cursor 续读。
任务无论成败都要bsk session stop <id>收尾，借用的标签随之归还。

🤝 人机协作与无人值守

遇到登录、验证码、支付确认这类必须人出场的步骤，Agent 可以主动交棒，也可以整体关闭求助。

bsk request-help --session <id> --prompt "请完成登录" --target @e3

返回结果	下一步
`continued`/`completed`	重新 observe，用新 ref 继续
`cancelled`/`timed_out`	尊重拒绝，不要重复请求
`disabled`	没有人完成操作；按现有能力继续
Stale ref	observe 后重试一次目标动作
超时或效果未知	先检查当前状态，动作可能已生效

扩展弹窗里有两个独立开关，默认都开，浏览器侧保存的设置对已有和新建会话都有最终决定权：

借用前确认	允许人工协助	实际行为
开	开	借用需确认；求助正常弹窗
开	关	借用需确认；求助返回`disabled`
关	开	借用免确认；求助正常弹窗
关	关	借用免确认；求助返回`disabled`

关闭借用确认会放行待确认请求；关闭协助会把等待中的求助结束为disabled。重新打开开关后，后续操作恢复原行为。
旧的--unattended、tab borrow --no-confirm、BSK_REQUEST_HELP=off不再能覆盖开关，仅为兼容保留识别。
关闭协助不代表步骤已完成，也不增加任何授权。Agent 应先用现有登录态和已授权输入把能做的做完；仅手机扫码、人脸验证、拿不到的短信码可以如实报告受阻，其余可独立完成的工作要继续。

📷 进阶场景

基础跑通之后，长截图、服务器侧 Agent 和 DSH 集成是三个进阶方向。

长截图三种模式怎么选

扩展"快捷功能 → 长截图"和 Agent 命令共用同一套捕获、拼片与导出管线。

Full page · Automatic：从顶部开始增量滚动，跟随追加内容。
Long image · I scroll：从当前位置开始，你手动滚动并保留重叠，完成后点Finish and keep。
Visible area：只截当前视口一次。

Agent 侧一条命令即可：

bsk screenshot --session <id> --full-page --timeout 5m --out page.png

默认捕获与编码截止 2 分钟，--timeout可延长；支持 Ctrl-C 取消，结束后恢复原始滚动位置。
--scope follow（默认）跟随追加内容；--scope current只捕获开始时测量的文档区域，后续长高不再扩展范围。
内部浏览器页面、嵌套滚动面板和虚拟化列表不支持；捕获期间保持标签可见。
存储上，新捕获是 512 像素高的 PNG 瓦片，写在扩展的 OPFS 里，导出时流式压缩，不构建整页像素缓冲。细节见 docs/long-screenshot.md。快捷功能在 CLI 连接关闭时也可独立使用。

远程连接：Agent 在服务器，浏览器在你电脑

扩展主动发起出站 WSS 连接，你的电脑无需开放入站端口；任务照常用独立 Agent Window 和借用-归还流程。本地模式就是默认行为：

bsk daemon start

服务器模式换成：

bsk daemon start --mode server --listen 0.0.0.0 --port 52800 \ --public-url wss://browser.example.com/extension

配对验证按三步走：

服务器侧BSK_AUTO_START=0 bsk daemon pair生成配对链接（单次使用，默认 5 分钟过期）。
扩展弹窗选Remote connection，粘贴链接并保存。
BSK_AUTO_START=0 bsk status --json确认浏览器出现，再用它的instance_id启动会话读页，验证成功后bsk session stop。

设备授权用bsk daemon devices查看、bsk daemon revoke --all吊销；吊销同时断开现有连接并拒绝新连接。注意远程模式当前不支持文件上传/下载。TLS 反向代理、--pairing-ttl等启动参数、第三方网关协议都在 docs/remote-extension-connection.md 里。

DeepSeek Harness 插件

在 DSH 下不用bsk install-skill，官方插件自带 skill，并提供原生browser_*工具和 Web UI 任务预览：

dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin dsh --profile web

把web换成你的 profile 名，确保该环境 PATH 能找到bsk。插件不会自动更新，升级后重启 profile。用法与配置见 packages/dsh-plugin-browserskill/README.md。

⚙️ 它是怎么工作的

整条链路只有四跳：CLI → daemon → 扩展 → Agent Window，每一层职责固定。

CLI（crates/bsk-cli/）：命令树与 daemon。命令按需自动拉起 daemon，再发出类型化 RPC。
daemon：持有请求直到扩展（重）连上，路由到对应浏览器；session start在扩展未连好时不会直接失败。
协议（crates/bsk-protocol）：所有线上类型与 JSON Schema 集中在此，每个工具的参数和结果契约都在 schema 目录。
扩展（apps/extension/src/）：浏览器内执行自动化、录制、长截图与审计。

排障与版本对齐

多数问题落在三件事上：doctor 输出、版本匹配、升级顺序。

doctor 的WARN是提示而非失败：典型场景是受管 skill 检测到本地编辑、暂停自动同步，或来源无法识别。按提示处理即可，例如用bsk install-skill --harness cursor --force恢复内置 skill，或用--source加--force显式标记为自定义。
受管 skill 在 daemon 启动、session start、doctor时自动同步；内容未变的才更新，本地编辑和自定义 skill 一律保留。
版本匹配：长截图等新能力要求 CLI 与扩展构建一致。更新 CLI 后运行bsk daemon restart重启运行中的 daemon；扩展走商店更新，DSH 插件单独更新。
升级顺序：先结束进行中的浏览器任务，再更新。

bsk update --yes bsk daemon restart

最后用bsk --version、bsk status、bsk doctor核对 CLI、daemon 与扩展的版本和连接。

企业官网建设流程全解析