BrowserSkill 完整上手指南：3 条路径让 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
你让 Agent 去处理一个需要登录的网站，它却总在反复重新登录、卡在验证码，或者直接占用你正在用的浏览器标签页。BrowserSkill 就是为这类痛点设计的：它是 Agent 与真实浏览器之间的本地桥接层，让 Cursor、Claude Code、Codex、OpenClaw 等任意能调用 Shell 的 Agent，直接操作你已经登录的浏览器。任务跑在独立的 Agent Window 里，不打断你的日常浏览；需要碰你已打开的标签时，它先显式借用、用完归还，其余窗口不受影响。
项目定位与适用对象
一句话：BrowserSkill 是bskCLI/daemon 与浏览器扩展组成的本地桥接层，负责把你手里的 Agent 接到你已登录的浏览器上。
- 适合你：正在用任意能调用 Shell 的 Agent（Cursor、Claude Code、Codex、OpenClaw、CodeBuddy、WorkBuddy、Pi、Hermes Agent 等），想让它们读取、填写、点击、截图你已登录的网站，但不想为此维护测试账号，也不想被打断工作。
- 不适合：需要完全隔离、无登录态的"干净"环境——Agent Window 共享所选 Profile 的登录态，不是独立账号，也不是安全沙盒。
- 关键约束：它绝不提取凭据、Cookie、Token 等敏感信息，也不收集产品遥测。
| 组件 | 支持范围 |
|---|---|
| CLI / daemon | macOS（Apple Silicon、Intel）、Linux（x64、ARM64）、Windows x64 |
| 浏览器扩展 | Chromium 125+ 的 Chrome、Microsoft Edge；其他 Chromium 浏览器通常可用 |
| Agent 接入 | 任意能调用 Shell 的 Agent（配 BrowserSkill skill）；DeepSeek Harness 用专用插件 |
动手前的准备
开工前把这三件事确认清楚，能避免 90% 的连接问题。
- 本机环境：macOS / Linux / Windows x64 任一即可；Agent 所在的终端能找到
bsk命令（装完会提示更新PATH，已启动的 Agent 记得重启或改用二进制绝对路径）。 - 浏览器扩展：目标浏览器安装对应扩展（Chrome 或 Edge），并能在弹窗里看到"已连接 / READY"。
- 沙盒特殊情况：如果你的 Agent 沙盒会在每条命令结束后回收后台进程，请先读 docs/sandboxed-agents.md——在宿主侧保持 daemon 存活，沙盒内用共享的
BSK_HOME和BSK_AUTO_START=0连接。普通本地环境默认自动拉起 daemon，无需额外配置。
三条上手路径
三条路径任选其一，互不冲突，选最贴合你习惯的。
路径 A：把一句话丢给 Agent，让它自助安装
把下面这句话发给你的 Agent，它会按仓库自带的安装指引完成 CLI、skill 安装并引导你加载扩展：
按照 AGENT_INSTALL.md 的说明，在本机安装并配置 browser-skill指引文件见 AGENT_INSTALL.md。你仍需手动在浏览器里装好扩展。
验证点：Agent 完成后，bsk doctor全绿、扩展弹窗显示"已连接"，且新开的 Agent 会话能发现browser-skill。doctor 通过不等于 Agent 已加载 skill，需单独确认。
路径 B：手动安装 CLI + 扩展 + skill
curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh bsk install-skillWindows PowerShell 用irm .../install.ps1 | iex。装完bsk install-skill按空格选择目标 harness、回车安装；非交互可写bsk install-skill --harness cursor --json。然后从 Chrome / Edge 商店安装扩展并打开弹窗。
验证点：bsk --version有输出，bsk doctor通过，扩展显示"已连接"。
路径 C：DeepSeek Harness 专用插件
在 DeepSeek Harness（dsh）下不用装 skill，直接装官方插件，它会注入原生browser_*工具并在 Web UI 实时展示会话：
dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin dsh --profile web把web换成你的 profile 名。插件已内置browser-skill，无需再跑bsk install-skill。
验证点：dsh启动后调用/browser-skill，能描述任务并在 Web UI 看到浏览器任务预览。用法见 packages/dsh-plugin-browserskill/README.md。
第一次跑通：端到端最小流程
连接成功后，先让 Agent 打开一个页面并总结，或直接敲下面四步。四步走通，说明全链路可用。
- 启动会话——
bsk session start --json，记下返回的session_id（多浏览器时加--browser <id>）。成功的样子：拿到一个字符串形式的session_id。 - 打开页面——
bsk navigate https://example.com --session <id>。成功的样子：Agent Window 打开该地址，无报错。 - 读取页面——
bsk observe --session <id>。成功的样子：返回页面文本与一组新鲜@eNrefs。 - 停止会话——
bsk session stop <id>。成功的样子：会话结束，借用的标签被归还回原窗口。
⚠️ 注意：无论成功还是失败都执行第 4 步（除非用户要求保留会话）。不要靠空闲清理结束任务，也不要用重启共享 daemon 来收尾。
进阶场景
场景一：借用你已打开的标签页
Agent 要操作你已打开的页面时，必须显式借用，相关步骤一结束立即归还：
bsk tab list --scope user --session <id> bsk tab borrow <tab-id> --session <id> bsk tab return <tab-id> --session <id>像"借书-还书"：借来的标签在 Agent Window 里成为后续命令的默认目标，用完归还原窗口。精确地说，tab borrow只在该窗口中选择该标签作为默认目标，不额外聚焦窗口；后台创建的标签（tab create --no-active）要自己保存tab_id，并在命令里显式传--tab-id。不要编造 tab ID，也不要让用户标签跨无关任务保留。
场景二：无人值守与人工接管
插件弹窗有两个默认开启、相互独立的开关：借用标签页前确认和允许请求人工协助。浏览器里保存的设置对已有和新建会话都有最终决定权。
- 需要人处理登录、验证码、支付确认等步骤，或两次尝试无进展时，请求接管：
bsk request-help --session <id> --prompt "Please complete sign-in" --target @e3。 - 返回
continued/completed→ 重新 observe，用新 refs 继续；返回cancelled/timed_out→ 尊重拒绝，不重复请求；返回disabled→ 没人真的操作过，重新 observe 并遵循禁用协助规则。 - 关闭"人工协助"后
request-help返回disabled，不代表步骤已完成。此时 Agent 应利用现有登录态、已授权输入和可行替代方案继续推进；纯手机扫码、人脸、缺失短信码、纯文本模型识别不了的图形验证码可如实报告受阻，但别因此把任务判为完成或受阻。
⚠️ 注意：--unattended、tab borrow --no-confirm、BSK_REQUEST_HELP=off这些旧参数只保留兼容识别、已弃用，不能覆盖插件开关。需要后台打开窗口用session start --no-focus。
场景三：服务器上的 Agent 操作本地浏览器
Agent、CLI、daemon 都跑在服务器上，浏览器留在你本机。扩展主动发起出站 WSS 连接，本机无需开放入站端口，任务仍走独立 Agent Window 和借用-归还流程。
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配对验证按"生成链接 → 服务器列出已连浏览器 → 测试会话读页并成功停止"的证据链走：服务器侧BSK_AUTO_START=0 bsk daemon pair生成一次性链接（默认 5 分钟过期），浏览器弹窗选Remote connection粘贴保存，再用BSK_AUTO_START=0 bsk status --json确认目标浏览器出现，最后以其中的instance_id启动会话读页。
| 启动参数 | 默认值 | 含义 |
|---|---|---|
--pairing-ttl | 5m | 一次性配对有效期，最多 1 小时 |
--device-ttl | 90d | 设备凭据寿命，最多 366 天 |
--renew-after | 30d | 扩展应续期时间点，须小于设备寿命 |
--max-connections | 64 | 在线浏览器容量（1–1000） |
⚠️ 注意：证书主机名必须与公网 URL 匹配，bsk不签发证书、不改浏览器信任；BSK_HOME是私有目录，含设备授权，须跨重启持久化，不要在多台独立服务器或不受信任的用户间共享。远程模式暂不支持上传/下载（返回unsupported）。详见 docs/remote-extension-connection.md。
亮点特性：整页长截图
长页面要留档时，最烦的就是手动滚动拼接、内存还容易爆。BrowserSkill 的整页长截图从顶部增量滚动、按重叠视口拼接，边滚边等加载稳定，完成后恢复原始滚动位置；新捕获是一组 512px 高的 PNG 瓦片存在扩展的 OPFS 里，配合专用 worker 流式编码，避免构建整图缓冲（基准里 3170×100062 像素的页面，RGBA 缓冲峰值仅约 41.7 MiB，而整图需约 1.27 GB）。
让 Agent 直接截取当前会话页面：
bsk screenshot --session <id> --full-page --out page.png默认采集/编码超时两分钟，长页面加--timeout 5m；--scope current只捕获开始时测量的区域。⚠️ 注意：需要 CLI 与扩展版本匹配，更新 CLI 后跑bsk daemon restart；嵌套滚动面板和虚拟化列表不受支持。更多模式（自动/我滚动/可见区域）与存储细节见 docs/long-screenshot.md。
它到底怎么工作
Agent 不直接碰浏览器，整条链路被严格分层：
bsk session start通过ensure_daemon自动拉起 daemon，再发类型化 RPC；daemon 侧会持有session.start，直到扩展（重）连上才放行。- 线上协议类型与每个工具的参数/结果 JSON Schema 集中在 crates/bsk-protocol，
schema/下能找到tool_session_start_params.json、tool_navigate_params.json、tool_observe_params.json等契约。 - 扩展端在 apps/extension/src 实现浏览器自动化、录制、长截图、审计等模块。
各模块一句话职责：crates/bsk-cli 是 CLI + daemon + 内置 skill；crates/bsk-protocol 是共享协议与 Schema；apps/extension 是浏览器自动化与调试工作区；packages/dsh-plugin-browserskill 是 DeepSeek Harness 集成；packages/ui、packages/i18n、packages/vom 是共享 UI、多语言与页面观察；evals/browser 是本地浏览器能力评测台。
常见问题
问：升级后某些行为变了 / 提示旧参数无效？bsk update --yes会先装新版并重启运行中的 daemon；若你手动替换了二进制，补一句bsk daemon restart。--unattended、tab borrow --no-confirm、BSK_REQUEST_HELP=off从 0.3.0 起不再能关闭确认或人工协助，改到插件弹窗里开关。
问：为什么request-help或借用等待时间不生效？自定义借用等待时间、新版request-help都要求 daemon 与扩展协议版本够高（前者需 1.2+，request-help需 1.3）。版本不匹配时只限制当次操作并提示升级，不会断开连接。用bsk --version、bsk status、bsk doctor核对 CLI、daemon、扩展三方版本一致。
问：我改了 skill 文件，为什么它不再自动更新？受管 skill 只在文件内容仍与上次安装/同步一致时自动同步；检测到本地编辑就保留文件、暂停更新，doctor会给出WARN与恢复方法。想恢复内置并重新启用更新：bsk install-skill --harness <name> --force（不带--source）。
问：浏览器设置和命令行参数冲突时听谁的？浏览器里保存的开关拥有最终决定权，对已有和新建会话都生效；旧参数只保留兼容识别、不能覆盖。偏好读取失败时 daemon 保留已有有效值、不写回默认，也不阻止新建会话。
问：断开连接 / 停止会话会丢数据或删记录吗？停止或断开会取消任务工作、归还借用标签、关闭任务创建的标签，但你手动创建的标签存活。已保存的网站调试历史、审计记录不会被删，各自 30 天后过期；远程模式暂不支持上传/下载。
本项目采用 MIT 许可证。更多细节见 docs/ 下的架构、长截图、远程连接、scroll-to 与沙盒配置说明。
【免费下载链接】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），仅供参考
