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 是一套本地桥接层：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 CLI

CLI 自带 daemon，不需要单独安装。macOS（Apple Silicon / Intel）与 Linux（x64 / ARM64）用：

curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"

Windows（PowerShell，x64）用：

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

用空格选择你的 harness（Cursor、Claude Code、Codex、OpenClaw 等），回车确认；非交互场景写全参数，例如bsk install-skill --harness cursor --json。bsk install-skill --list可查看所有目标与安装路径。skill 本体是 crates/bsk-cli/skill/SKILL.md，教会 Agent 会话生命周期与命令语义；已有安装默认跳过，加--force才会覆盖。

第四步：跑通一次真实调用

先诊断，再手工闭环一遍（不依赖 Agent）：

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

session 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_HELP=off`已弃用，无法覆盖扩展设置
关闭人工协助后	`request-help`返回`disabled`，Agent 应重新 observe，用现有登录态与已授权输入继续，而不是判任务完成

求助与异常恢复

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 5m；follow模式底部 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/-vv（debug/trace）。一个值得注意的数字：工具调用的 IPC 超时设为 35 秒，略大于 daemon 的 30 秒工具超时——这样调用方收到的是 daemon 返回的结构化超时错误，而不是 IPC 连接先断开（crates/bsk-cli/src/cli/mod.rs）。

2. 会话启动的特殊等待。session start时 daemon 会持住这个 RPC，轮询等待扩展（重）连，上限 35 秒（EXTENSION_CONNECT_WAIT，crates/bsk-cli/src/daemon/browsers.rs）；CLI 侧的读取预算在此基础上再加 10 秒，避免在 daemon 答复前误报超时（crates/bsk-cli/src/cli/session.rs）。session stop的 IPC 预算则是 1 小时，因为停止过程包含标签归还与清理。

3. daemon 路由层。本地模式下 daemon 在回环地址监听 WebSocket，默认端口 52800（crates/bsk-cli/src/daemon/mod.rs），握手时校验Origin: chrome-extension://…。内存中维护browsers（已连接扩展）与sessions（Agent 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-store，browser-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-ttl`	5 分钟	单次配对链接有效期，最多 1 小时
`--device-ttl`	90 天	设备寿命，最多 366 天
`--renew-after`	30 天	必须小于设备寿命
`--max-connections`	64	在线浏览器容量，1–1000
`--authorize-rate-limit`	60/分钟/IP	1–60000

配对流程：服务器侧BSK_AUTO_START=0 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_START=0 bsk status --json BSK_HOME=/absolute/shared/bsk bsk daemon start --foreground

宿主与沙盒必须看到同一底层目录（含daemon.json与run/daemon.sock），只拼上相同的环境变量文本不够。先查后启：status成功即复用现有 daemon，browsers为空只说明扩展未连，不是再启一个的理由。细节见 docs/sandboxed-agents.md。

DeepSeek Harness 插件

dsh 走同一条bsk链路，但由官方插件注入原生browser_*工具并在 Web UI 展示任务预览，插件自带 skill，无需再bsk install-skill：

dsh 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、内嵌 skill
crates/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
线上协议与 schema：crates/bsk-protocol/README.md
远程连接（配对、TLS 反代、第三方网关协议）：docs/remote-extension-connection.md
沙盒托管：docs/sandboxed-agents.md
长截图参数与错误语义：docs/long-screenshot.md
scroll-to 原语的可见边界与中断契约：docs/scroll-to.md
网站调试工作流与留存限制：docs/website-debugging.md
浏览器 profile 选择：docs/browser-profiles.md
操作审计：docs/operation-audit.md
DSH 插件用法：packages/dsh-plugin-browserskill/README.md
版本变化：CHANGELOG.md
skill 参考文档（环境、标签与 profile、交互细节、截图、文件、求助恢复、调试）：crates/bsk-cli/skill/references/

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析