BrowserSkill 三步上手：让 AI Agent 操作你已登录的真实浏览器，完整指南
项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkill BrowserSkill 是一套把 AI Agent 接入真实浏览器的本地桥接层，由常驻命令行工具 bsk 与浏览器扩展组成，让任意能执行 Shell 的 Agent 以你现有的 Chrome 登录态完成网页任务，适合需要 AI 浏览器自动化又怕维护测试账号的开发者。
为什么不用干净的测试浏览器
做浏览器自动化绕不开一个老问题：脚本需要一个"干净"的浏览器环境。这通常意味着注册测试账号、同步 Cookie、再想办法穿过登录墙。而账号状态一旦变动，整套脚本跟着失效，维护成本持续累积。
BrowserSkill 换了一个思路：不再另开环境，直接复用你日常浏览器里的登录态。Agent 全程只动页面本身，不碰你的账号密码和登录凭证，也不提取任何 Cookie、Token。它给自动化的四个约束是这样的：
- 任务不干扰你：所有操作发生在浏览器专门开给 Agent 的独立窗口（Agent Window），你主窗口里的文档和消息不受影响。
- 碰你的标签页要打招呼：Agent 默认只能操作 Agent Window 内的页面；要操作你自己打开的标签页，必须走借用流程、等你确认，用完归还。
- 纯 Shell 接口：
bsk命令行就是全部 API。没有 SDK，没有模型绑定，Cursor、Claude Code、Codex 等任何能跑 Shell 的 harness 都能接。 - 关键节点交还给人：登录、验证码、支付确认这类必须人来的步骤，Agent 把控制权暂交给你，处理完再继续。
装之前，先看请求怎么流转
一条 bsk 命令在机器里要走四站，每一站都是本地组件：
先解释三个词：daemon 是常驻后台的进程，负责接收请求并转发给浏览器；IPC 指同一台机器上进程间通信，这里走本地 socket；WebSocket 是浏览器扩展与 daemon 之间的双向长连接，本地模式下只监听回环地址。
四个值得知道的机制：
| 机制 | 现象 | 原因 |
|---|---|---|
| 超时设计 | 长命令不会"莫名断线" | CLI 侧 IPC 超时设为 35 秒，刻意比 daemon 的工具超时略长，调用方收到的是结构化超时响应而非连接消失 |
| 端口与发现 | 扩展连上后命令才放行 | 本地模式 daemon 的回环 WebSocket 默认监听 52800 端口，扩展弹窗保存匹配的端口；bsk session start 会先自动拉起 daemon，并等待扩展重连最多 35 秒才放行请求 |
| 空闲清理 | 会话最终会被回收 | 空闲超时默认 5 分钟，但只是安全网，不能替代显式的 session stop |
| 协议契约 | 两端行为可验证 | 每个工具的参数与结果契约集中在 crates/bsk-protocol/schema/ 的 JSON Schema，扩展端实现位于 apps/extension/src/ |
三步装好并验证
环境兼容性先看这里：
| 项目 | 支持情况 |
|---|---|
| 操作系统 | macOS（Apple Silicon / Intel）、Linux（x64 / ARM64）、Windows x64 |
| 浏览器 | Chrome、Microsoft Edge（Chromium 125+），其他 Chromium 内核浏览器未保证 |
| Agent 侧 | 任一能执行 Shell 的 Agent，或带对应插件的 DeepSeek Harness |
第 1 步：安装 CLI。 macOS / Linux 一条命令完成下载，装完把目录加进 PATH（二进制默认落在 ~/.local/bin）：
curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh
export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"
Windows 用 PowerShell：
irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex
正在运行的 Agent 可能缓存了旧 PATH，装完建议重启一次。
第 2 步：安装浏览器扩展。 从 Chrome Web Store 或 Edge 加载项商店安装 BrowserSkill，打开扩展弹窗确认本地连接已启用。
第 3 步：把 skill 操作手册装进 harness。 这会让 Agent 知道怎么调 bsk，把 cursor 换成你实际使用的 harness ID：
bsk install-skill --harness cursor --json
bsk install-skill --list 可查看全部支持的 harness ID。
最后跑一次体检命令，按提示处理警告与失败项：
bsk doctor
bsk --version 能输出版本号、扩展弹窗显示"已连接"，安装就算完成。
日常怎么用：会话、导航与元素引用
开会话。 任何任务前先启动会话，返回的 session_id 是 4 位小写字母，后续每条命令都用 --session 带上它：
bsk session start --json
打开页面并读取。 导航之后用 observe 获取页面元素，每个元素带一个 @eN 引用，它是后续所有点击、填写操作的坐标：
bsk navigate https://example.com --session <session-id>
bsk observe --session <session-id>
记住一个习惯：导航发生、或页面结构大变更之后，先重新 observe 拿到新鲜引用再动作。用过期引用只会得到失败。
收尾。 任务无论成败都要显式停止会话：
bsk session stop <session-id>
权限与接管：标签页借用与人工求助
标签页借用确认怎么配
Agent 默认只碰 Agent Window 里的页面。要操作你自己打开的标签页，按"先列出 → 再借用 → 用完归还"三步走：
bsk tab list --scope user --session <session-id>
bsk tab borrow <tab-id> --session <session-id>
# ...执行任务...
bsk tab return <tab-id> --session <session-id>
借用会等你确认，默认等待 60 秒；--timeout 120s 可改这个时长（需要 daemon 与扩展的协议版本在 1.2 及以上）。标签页用完立即归还，不要让它跨任务滞留在 Agent 手里。
request-help 的五种返回值怎么处理
遇到登录、CAPTCHA、OTP，或连续两次尝试毫无进展时，把控制权交还给你：
bsk request-help --session <session-id> --prompt "Please complete sign-in" --target @e3
这条命令有 5 分钟硬超时。返回值的处理策略：
| 返回值 | 含义 | 你的下一步 |
|---|---|---|
continued | 你处理完第一段，任务继续 | 重新 observe 拿新引用后继续 |
completed | 你已把阻塞解决 | 重新 observe 后继续任务 |
cancelled | 你拒绝了这次求助 | 停止该路径，不要重复请求 |
timed_out | 5 分钟内无人处理 | 视为阻塞未解决，不要立刻重试 |
disabled | 插件里关闭了人工协助 | 基于现有登录态尽力推进，而不是把任务判为完成 |
进阶用法
📸 长截图命令
截取整页长图，结束时自动恢复滚动位置：
bsk screenshot --session <session-id> --full-page --out page.png
采集与编码默认 2 分钟截止，长页面加 --timeout 5m。实现上图片按 512 像素高的瓦片分块存储，控制内存峰值，细节见 docs/long-screenshot.md。
🌐 服务器上的 Agent 怎么连本地浏览器
Agent 跑在服务器、浏览器在你电脑上时，走远程模式：扩展主动发起出站连接，本地不用开任何端口。用 bsk daemon start --mode server 配 TLS 证书自建鉴权服务器，再用 bsk daemon pair 生成一次性配对链接完成设备授权，凭据支持轮换与吊销。注意：远程模式下文件上传下载不可用。完整配置见 docs/remote-extension-connection.md。
🐞 网站调试取证
复现问题前先开采集，把你的每次操作关联到请求、响应体、Console 输出与页面变化，证据可导出为 JSON 事后复查。同样的限制：远程模式不支持文件上传下载。说明见 docs/website-debugging.md。
🤖 无人值守开关怎么配
扩展弹窗里有两个独立开关："借用标签页前确认"和"允许请求人工协助"。两个都关，则借用免确认、request-help 直接返回 disabled。插件里保存的设置对全部会话有最终决定权，旧版 --unattended 等命令行开关已弃用。
它适合谁，不适合谁
适合：Agent 要操作真实网站（后台系统、电商、SaaS），你不想维护一套测试账号；或者你希望自动化过程始终可见、可控、可中途接管。
不适合：纯无头批量抓取。BrowserSkill 为人机协作设计，不是爬虫工具。
延伸阅读：
- Agent 自助安装指引：把一句话发给 Agent，它能自己装好 CLI 和 skill
- 沙盒环境说明：沙盒回收后台进程时，如何在宿主侧托管 daemon
- 长截图说明：512 像素瓦片存储与内存峰值控制
- 远程连接说明：服务端 Agent 的配对、凭据轮换与吊销
- scroll-to 原语说明：滚动、可见区域与坐标的精确语义
- 架构文档与 协议契约：实现与协议的完整参考
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
