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 提供 CLI 与浏览器扩展可让 AI Agent 在服务器上运行同时通过扩展控制用户本机的真实、已登录浏览器。本文以 docs/remote-extension-connection.md 为核心结合仓库源码与测试系统讲解远程连接的整体架构、独立服务器部署、TLS 反向代理、配对与首次验证流程、第三方网关协议以及浏览器权限与任务生命周期。读完本文你将掌握如何部署一台安全的远程bsk服务器、如何完成端到端配对与验证以及这套无账号体系的设备授权协议在扩展端与 Rust 服务端各自的实现细节。远程连接的整体设计远程模式解决的核心问题是Agent 进程与浏览器不在同一台机器上。Agent 运行在服务器而 BrowserSkill 扩展控制着用户电脑上的浏览器。与常见的服务器监听、客户端主动连入不同这里的架构正好反过来扩展主动发起出站连接用户电脑不需要任何入站端口也不需要在路由器或防火墙上做端口映射任务依然使用独立的Agent WindowAgent 专属窗口并完整保留用户标签页的借用-归还borrow-and-return流程bsk内置设备配对、连接认证、凭据续期与吊销不需要任何账号系统或认证网关如果已有第三方网关扩展也可以按照协议与它配对。一句话概括职责边界浏览器电脑上只需要扩展Agent、CLI 与 daemon 全部放在服务器上。从源码结构看这套能力在仓库中分属两条清晰的实现路径扩展端TypeScriptapps/extension/src/transport/目录下的 remote-endpoint.ts、remote-authorization.ts、remote-storage.ts 负责配对链接解析、授权交换与凭据持久化服务端Rustcrates/bsk-cli/src/daemon/remote/下的 server.rs、authorization.rs、rate_limit.rs 负责 TLS 监听、授权存储、连接容量与限流。本地模式默认工作流不受影响远程模式引入后本地模式依然是默认选项。启动命令没有任何变化bsk daemon start # 等价写法bsk daemon start --mode local本地模式只监听 loopback回环地址原有的 CLI 命令与扩展端口设置全部继续有效。用户可以在扩展弹窗中选择Local connection来离开远程连接——这一操作会结束当前任务。从扩展实现看本地与远程的切换由 remote-storage.ts 中的REMOTE_CONNECTION_MODE开关驱动选择本地模式后即使 IndexedDB 凭据库不可用也会先把模式置为local并清理遗留的旧版密钥保证显式选择本地始终可以作为恢复手段。独立服务器部署部署前提服务器模式要求 Agent、CLI 与 daemon 运行在同一 OS 用户下。自动化命令继续走原有的本地 IPC socket而对外公开的监听器只接受经过认证的扩展连接与凭据交换。部署前必须确认三项前提缺一不可服务器可被浏览器电脑访问公网可达的主机名/端口有浏览器可信任的证书路径或已有的 TLS 反向代理公网地址、端口与证书配置正确。如果任一前提缺失应先向用户说明缺失项再继续部署。启动命令与参数假设已为browser.example.com准备好证书与私钥启动命令如下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要点说明证书必须被用户浏览器信任且证书主机名必须与--public-url一致。bsk自身不签发证书也不会修改浏览器的信任设置服务器模式保持前台运行空闲时不会自动退出建议交给进程管理器supervisor托管更换证书需要携带相同参数重启服务器不会自动更新或自我重启会话空闲限制仍然生效。在 Agent 环境中需要设置两个关键环境变量BSK_AUTO_START0让已停止的托管服务器被正确报告为不可用而不是由 CLI 试图重新拉起BSK_HOMEdaemon 与 CLI 客户端必须保持一致。这个私有目录必须跨服务重启和容器替换持久化因为它保存设备授权device grants与本地 IPC 元数据但绝不能在多个独立运行的服务器之间共享也不能与不受信任的 OS 用户共享。设备授权管理服务器配置完成后可以在服务器的本地 CLI 上管理设备授权bsk daemon devices bsk daemon revoke DEVICE_ID bsk daemon revoke --allbsk daemon devices输出设备与浏览器 ID、标签和过期时间永远不输出凭据本身revoke --all同时使未使用的配对链接失效吊销既会关闭现有连接也会拒绝新连接。吊销的生效机制值得深入理解对应 server.rs 中ConnectionAuthorization的实现活跃与空闲连接以 1 秒为周期轮询持久化授权消息处理只检查内存中的取消状态磁盘检查在异步执行器之外运行读取的是原子发布的快照不获取写锁授权读取失败会直接关闭连接fail-closed授权写入等待写锁最多 500ms发生争用时返回可重试的 HTTP 503而不会使合法连接失效吊销通常在下一个检查周期生效受调度与存储延迟影响页面上已执行的动作无法撤销。在服务端实现中所有写入都通过AuthorizationStore::transaction完成先获取排他文件锁最多等待 500ms再写入临时文件、fsync后原子替换tempfile::NamedTempFile::persist参见 authorization.rs 的transaction方法。服务器配置参数以下参数均可在服务器启动时配置Flag默认值含义--pairing-ttl5m一次性配对链接的有效期最多一小时--device-ttl90d设备有效期自配对或成功续期起算最多 366 天--renew-after30d扩展应该提前续期的时间点必须小于设备有效期--max-connections64在线浏览器容量取值 1–1000容量满时已有设备可以替换自己的连接--authorize-rate-limit60每个对端 IP 每分钟的配对/续期请求数取值 1–60000连接容量与限流浏览器连接与配对/续期请求使用独立的容量预算超出--max-connections的新浏览器会收到HTTP 503并带Retry-After响应头服务器同时将并发的 TCP/TLS/HTTP 建连过程限制为 64 个在建连早期阶段过载时新连接会被丢弃并输出限频告警从 server.rs 中的Semaphore::new(64)与 60 秒一次的告警节流可见普通 HTTP 响应会关闭连接Connection: close避免空闲 keep-alive 客户端占用建连容量。授权交换被限流时返回HTTP 429并带Retry-After。限流器rate_limit.rs的细节包括最多保留1024 个对端计数器超出的新对端共享一个有界溢出配额而不会驱逐已有计数器避免重置滥用者的预算一个全局预算限制为配置的每对端限额的16 倍用于限制总交换请求量防止轮换 IP 绕过限流见total.take(now, self.per_peer.saturating_mul(16))这些限制用于约束工作量但作者在文档中明确说明在持续分布式攻击下并不保证可用性。凭据续期机制扩展会在启动时以及选中远程连接期间周期性地检查续期本地模式没有续期闹钟。弹窗会显示授权过期时间并报告续期失败或需要重新配对的状态。续期机制有非常严谨的容错设计对应 remote-authorization.ts临时失败会保留当前凭据且每分钟最多重试一次RENEWAL_RETRY_MS 60_000如果过期后仍离线需要重新生成配对链接续期会轮换凭据请求发出前会先把待用新凭据pendingToken持久化这样即使 HTTP 响应丢失也能在 service worker 或服务器重启后用相同的旧/新凭据对重试——即使本地记录的旧过期时间已过弹窗能够区分未确认的续期unconfirmed与已知过期expired这两种状态修改生命周期参数只会影响后续交换不影响已签发的授权。在服务端续期同样支持精确重试authorization.rs 的exchange在renew分支中记录previous_hash对同一旧/新凭据对的重复请求返回与首次完全相同的响应且旧凭据不会轮换到其他替换凭据吊销也会使重试失效。TLS 反向代理部署如果不想让bsk直接暴露证书可以用常规 TLS 反向代理终结 HTTPS/WSS——代理不需要实现认证逻辑bsk daemon start --mode server --listen 127.0.0.1 --port 52800 \ --public-url wss://browser.example.com/extension代理需要遵守以下约定将/extension与/extension/authorize两个路径都转发到127.0.0.1:52800保留路径与 WebSocket 升级头保留Origin、Authorization与Sec-WebSocket-Protocol头绝不记录授权头、WebSocket 子协议值与请求体不要把凭据放进 query string认证仍然由内置服务器负责代理注入的用户头无法绕过认证。反向代理下的注意事项服务器看到的是代理的 IP因此代理后面的所有客户端共享同一个每对端授权限流。应在代理层配置每客户端限流并按预期聚合流量调大--authorize-rate-limit服务器不信任X-Forwarded-For或其他客户端 IP 头没有原生 TLS 时监听器必须绑定 loopback纯ws://公共 URL仅允许用于 loopback 开发非 loopback 的浏览器连接必须使用 WSS修改已配置的公共 URL 需要先吊销已有授权并生成新的配对链接服务端configure会强制校验见 authorization.rs。扩展端的 URL 校验同样严格remote-endpoint.ts 的parseRemoteEndpoint只允许wss:协议ws:仅当主机名是127.0.0.1、localhost或[::1]时放行并拒绝 URL 中携带用户名、密码或查询参数。配对与验证端到端四步流程配对链接是绝密信息它是一次性使用、默认 5 分钟过期的链接。完整流程分四步每一步都应有对应证据。第 1 步服务器操作者生成配对链接在另一个服务器 shell 中使用 daemon 的 OS 用户与一致的BSK_HOME执行BSK_AUTO_START0 bsk daemon pair输出形如wss://HOST/PATH#PAIRING_SECRET。生成后应立即告诉浏览器用户链接已就绪等待浏览器配对。服务端实现authorization.rs 的pair会检查服务器已启动--mode server、清理过期配对、并将未使用配对链接限制在 100 个以内。配对凭据是 32 字节随机数经 base64url 编码的 43 字符令牌服务端只保存其 SHA-256 哈希。第 2 步浏览器用户配对浏览器用户按照 AGENT_INSTALL.md 中的连接浏览器扩展章节安装扩展如未安装然后打开扩展弹窗选择Remote connection粘贴完整的配对链接并保存。保存链接会切换连接模式并结束现有任务。扩展会把配对密钥替换为设备凭据之后等待已连接状态。这一过程在扩展端的实现remote-authorization.ts中对应activateRemoteEndpoint→authorize(endpoint, pair, newToken())扩展把wss://协议改写为https://POST 到{path}/authorize携带Authorization: Bearer PAIRING_SECRET请求体为{ action: pair, next_token: …, label: Chrome · BrowserSkill }同时redirect: error拒绝重定向、credentials: omit不发 cookie、10 秒超时。第 3 步Agent 在服务器上确认浏览器在线BSK_AUTO_START0 bsk status --json确认预期浏览器出现在输出中。注意仅生成了链接或保存了配对都不等于连接已经激活。如果 Agent 无法访问服务器应将服务器侧验证报告为待定。第 4 步首次使用验证对于 CLI Agent从status中取出浏览器的instance_id作为browser-id启动测试会话并保留返回的session_idBSK_AUTO_START0 bsk session start --browser browser-id --no-focus --json然后用返回的会话 ID下文以id代替完成读页面与停止测试会话BSK_AUTO_START0 bsk navigate https://example.com --session id BSK_AUTO_START0 bsk observe --session id BSK_AUTO_START0 bsk session stop id成功或失败都必须停止测试会话并报告任何清理错误。使用 DeepSeek Harnessdsh时通过其注入的浏览器工具完成相同的 start / navigate / observe / stop 生命周期——服务器搭建与配对仍属操作者步骤。反馈准则只报告有证据的阶段证据向用户的反馈配对链接已生成链接已就绪等待浏览器配对。服务器列出了预期的已连接浏览器浏览器已连接首次使用验证待定。页面已读取且测试会话已停止远程首次使用验证完成。某一步失败或无法检查说明最后验证到的阶段、观察到的错误或缺失的访问权限以及下一步动作。配对链接过期或已被使用应让服务器操作者重新生成。其他连接失败请勿一律归因于链接过期应按弹窗错误提示检查端点、TLS 与代理配置。第三方网关协议扩展使用同一套协议连接bsk或任何兼容网关——它不调用任何特定提供商的登录 API。网关可以使用任意账号或管理系统来签发配对链接但必须实现下述面向浏览器的契约配对链接格式wss://HOST/PATH#PAIRING_SECRET。fragment 中包含 32–256 个 base64url 字符在任何网络请求发出前被移除fragment 本就不会随请求发送。扩展端校验见 remote-endpoint.ts正则^[A-Za-z0-9_-]{32,256}$授权交换扩展 POST 到https://HOST/PATH/authorize携带Authorization: Bearer PAIRING_SECRET与 JSON{ action: pair, next_token: …, label: … }。next_token是新生成的随机 256 位、无填充 base64url 凭据43 个字符与扩展端newToken()生成 32 字节后 base64url 编码的结果一致。网关必须一次性消费配对密钥并把替换凭据绑定到一个设备。配对密钥不能打开 WebSocket成功响应HTTP 200 返回{ device_id: 32 lowercase hex characters, expires_at: RFC3339 timestamp, renew_after: RFC3339 timestamp, service_name: optional display name }。无效或未授权的交换返回非 2xx。扩展拒绝重定向、不发送 cookie对应redirect: error与credentials: omitWebSocket 升级升级到wss://HOST/PATH时以恰好一个Sec-WebSocket-Protocol: bsk-auth.DEVICE_TOKEN子协议认证。网关必须在升级前校验并回显所选子协议。仅凭浏览器形态的 Origin 永远不构成授权服务端 server.rs 中 Origin 校验只是前置条件真正的认证来自bsk-auth.前缀令牌。凭据属于特定端点不能用于授权另一台设备或另一个部署续期使用同一 POST 端点与当前令牌action: renew并携带新的next_token保持相同的device_id。旧凭据对新连接失效。对相同旧/新凭据对的精确重试必须返回与首次相同的成功响应旧凭据不得轮换到不同的替换凭据。吊销同样会使重试失效。续期期间授权仍有效的已连接 socket 可以保持打开升级后的会话支持现有原生握手与 RPC 帧扩展端首个帧必须是system.handshake见 handshake.ts协议版本为1.3。所有 RPC 路由、响应、事件与会话状态都必须绑定到已认证的设备不得信任设备自报的浏览器 ID 去授权另一台设备的任务。过期或吊销时关闭活跃 socket 并取消其未完成工作。网关可以把这套协议桥接到其服务器上的本地bskdaemon从而保持该 daemon 的 loopback/IPC 边界私有。如果网关只是把凭据转发给内置服务器是无效的内置服务器只接受自己签发的授权。浏览器权限与任务生命周期配对即设备级授权只与你信任能操作浏览器的服务器配对。配对后的服务器可以创建 Agent Window 并使用该浏览器配置文件导航包括其中已登录的网站会话。配对是设备授权不是受限账号更不是网站沙箱——请把它当作把浏览器钥匙交给对方来对待。内容访问必须通过显式借用远程内容读取、截图、录制与页面操作都要求任务显式创建或借用borrow标签页列出标签页标题与 URL 仍然可用目的是选择要借用的标签页用户标签页被移入或通过 Agent Window 打开不会自动获得授权借用使用已有的浏览器控制确认偏好远程请求标志无法改变该偏好借用归还后远程内容访问立即结束远程录制期间归还标签页会先取消录制再释放标签页。弹出窗口与 OAuth 场景这条规则同样适用于页面通过target_blank、window.open或 OAuth 流程打开的标签页/窗口——opener 关系不授予控制权。如果这类标签页已经在 Agent Window 内则无法原地借用浏览器用户必须先把它移回普通浏览器窗口Agent 才能走常规借用流程。通过bsk tab create显式创建的标签页则立即受控。自动弹窗授权不在当前版本范围内。断开与清理语义断开连接会取消任务工作归还借用的标签页关闭任务创建的标签页用户创建的标签页在清理后保留。失败的回退failed returns会保留窗口必须在重连前解决。重连会启动新任务命令与会话绝不重放。远程认证失败时不会自动选择本地连接。版本限制当前版本不支持远程上传与下载会返回unsupported错误本地文件传输行为不变。截图与其他既有 RPC 内容结果仍然支持。当前没有网关预览/focus 侧协议、后台任务标签组或替代窗口模型。凭据存储与信任边界扩展侧设备凭据存放在扩展源extension-origin的 IndexedDB中普通扩展设置只保存选中的连接模式与非机密修订号revision。全新本地配置文件与显式选择的本地模式不会读取该凭据库。远程存储失败时弹窗报告错误且不会自动回退即使凭据库不可用显式选择本地连接也能恢复启动。旧版远程设置会在恢复普通设置访问前完成迁移见 remote-storage.ts 的initializeRemoteStorage服务端侧独立服务器以私有文件权限0600与原子写入持久化哈希后的凭据SHA-256authorization.rs文件内容永不包含明文令牌——测试pairing_is_one_use_durable_private_and_stores_only_hashes直接断言了这一点信任边界整个浏览器配置与BSK_HOME都应视为可信本地数据TLS 私钥需要单独保护。验证与测试构建 CLI 与扩展后运行常规 Rust 与扩展测试套件真实的浏览器回归测试还需要一个独立的 Chrome for Testing 可执行文件cargo test --workspace pnpm --filter browser-skill/extension test cargo build -p bsk pnpm --filter browser-skill/extension build BSK_REMOTE_CLI/absolute/path/to/target/debug/bsk \ BSK_REMOTE_CHROME/absolute/path/to/chrome-for-testing \ pnpm --filter browser-skill/extension test src/transport/__tests__/remote-connection.browser.test.ts远程服务器的集成测试覆盖可参考 remote_server.rs 与扩展端tests目录凭据交换、轮换重试、稳定设备路由、替换连接、吊销、连接容量、文件锁争用与原生 TLS单元测试额外覆盖限流饱和、扩展存储不可用、本地恢复、续期重试频率与弹窗授权状态。其中crates/bsk-cli/src/daemon/remote/authorization.rs内置的测试如only_one_concurrent_pairing_exchange_succeeds、rotation_retry_survives_restart_without_restoring_old_credentials、expired_and_revoked_pairings_and_grants_fail_closed与rate_limit.rs内置测试如proxy_clients_share_the_configured_peer_budget、rotating_addresses_cannot_exceed_the_total_budget直接印证了本文前述的安全语义。注意TLS 测试固件包含仅供测试使用的私钥绝不可用于部署。【免费下载链接】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），仅供参考 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 提供 CLI 与浏览器扩展可让 AI Agent 在服务器上运行同时通过扩展控制用户本机的真实、已登录浏览器。本文以 docs/remote-extension-connection.md 为核心结合仓库源码与测试系统讲解远程连接的整体架构、独立服务器部署、TLS 反向代理、配对与首次验证流程、第三方网关协议以及浏览器权限与任务生命周期。读完本文你将掌握如何部署一台安全的远程bsk服务器、如何完成端到端配对与验证以及这套无账号体系的设备授权协议在扩展端与 Rust 服务端各自的实现细节。远程连接的整体设计远程模式解决的核心问题是Agent 进程与浏览器不在同一台机器上。Agent 运行在服务器而 BrowserSkill 扩展控制着用户电脑上的浏览器。与常见的服务器监听、客户端主动连入不同这里的架构正好反过来扩展主动发起出站连接用户电脑不需要任何入站端口也不需要在路由器或防火墙上做端口映射任务依然使用独立的Agent WindowAgent 专属窗口并完整保留用户标签页的借用-归还borrow-and-return流程bsk内置设备配对、连接认证、凭据续期与吊销不需要任何账号系统或认证网关如果已有第三方网关扩展也可以按照协议与它配对。一句话概括职责边界浏览器电脑上只需要扩展Agent、CLI 与 daemon 全部放在服务器上。从源码结构看这套能力在仓库中分属两条清晰的实现路径扩展端TypeScriptapps/extension/src/transport/目录下的 remote-endpoint.ts、remote-authorization.ts、remote-storage.ts 负责配对链接解析、授权交换与凭据持久化服务端Rustcrates/bsk-cli/src/daemon/remote/下的 server.rs、authorization.rs、rate_limit.rs 负责 TLS 监听、授权存储、连接容量与限流。本地模式默认工作流不受影响远程模式引入后本地模式依然是默认选项。启动命令没有任何变化bsk daemon start # 等价写法bsk daemon start --mode local本地模式只监听 loopback回环地址原有的 CLI 命令与扩展端口设置全部继续有效。用户可以在扩展弹窗中选择Local connection来离开远程连接——这一操作会结束当前任务。从扩展实现看本地与远程的切换由 remote-storage.ts 中的REMOTE_CONNECTION_MODE开关驱动选择本地模式后即使 IndexedDB 凭据库不可用也会先把模式置为local并清理遗留的旧版密钥保证显式选择本地始终可以作为恢复手段。独立服务器部署部署前提服务器模式要求 Agent、CLI 与 daemon 运行在同一 OS 用户下。自动化命令继续走原有的本地 IPC socket而对外公开的监听器只接受经过认证的扩展连接与凭据交换。部署前必须确认三项前提缺一不可服务器可被浏览器电脑访问公网可达的主机名/端口有浏览器可信任的证书路径或已有的 TLS 反向代理公网地址、端口与证书配置正确。如果任一前提缺失应先向用户说明缺失项再继续部署。启动命令与参数假设已为browser.example.com准备好证书与私钥启动命令如下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要点说明证书必须被用户浏览器信任且证书主机名必须与--public-url一致。bsk自身不签发证书也不会修改浏览器的信任设置服务器模式保持前台运行空闲时不会自动退出建议交给进程管理器supervisor托管更换证书需要携带相同参数重启服务器不会自动更新或自我重启会话空闲限制仍然生效。在 Agent 环境中需要设置两个关键环境变量BSK_AUTO_START0让已停止的托管服务器被正确报告为不可用而不是由 CLI 试图重新拉起BSK_HOMEdaemon 与 CLI 客户端必须保持一致。这个私有目录必须跨服务重启和容器替换持久化因为它保存设备授权device grants与本地 IPC 元数据但绝不能在多个独立运行的服务器之间共享也不能与不受信任的 OS 用户共享。设备授权管理服务器配置完成后可以在服务器的本地 CLI 上管理设备授权bsk daemon devices bsk daemon revoke DEVICE_ID bsk daemon revoke --allbsk daemon devices输出设备与浏览器 ID、标签和过期时间永远不输出凭据本身revoke --all同时使未使用的配对链接失效吊销既会关闭现有连接也会拒绝新连接。吊销的生效机制值得深入理解对应 server.rs 中ConnectionAuthorization的实现活跃与空闲连接以 1 秒为周期轮询持久化授权消息处理只检查内存中的取消状态磁盘检查在异步执行器之外运行读取的是原子发布的快照不获取写锁授权读取失败会直接关闭连接fail-closed授权写入等待写锁最多 500ms发生争用时返回可重试的 HTTP 503而不会使合法连接失效吊销通常在下一个检查周期生效受调度与存储延迟影响页面上已执行的动作无法撤销。在服务端实现中所有写入都通过AuthorizationStore::transaction完成先获取排他文件锁最多等待 500ms再写入临时文件、fsync后原子替换tempfile::NamedTempFile::persist参见 authorization.rs 的transaction方法。服务器配置参数以下参数均可在服务器启动时配置Flag默认值含义--pairing-ttl5m一次性配对链接的有效期最多一小时--device-ttl90d设备有效期自配对或成功续期起算最多 366 天--renew-after30d扩展应该提前续期的时间点必须小于设备有效期--max-connections64在线浏览器容量取值 1–1000容量满时已有设备可以替换自己的连接--authorize-rate-limit60每个对端 IP 每分钟的配对/续期请求数取值 1–60000连接容量与限流浏览器连接与配对/续期请求使用独立的容量预算超出--max-connections的新浏览器会收到HTTP 503并带Retry-After响应头服务器同时将并发的 TCP/TLS/HTTP 建连过程限制为 64 个在建连早期阶段过载时新连接会被丢弃并输出限频告警从 server.rs 中的Semaphore::new(64)与 60 秒一次的告警节流可见普通 HTTP 响应会关闭连接Connection: close避免空闲 keep-alive 客户端占用建连容量。授权交换被限流时返回HTTP 429并带Retry-After。限流器rate_limit.rs的细节包括最多保留1024 个对端计数器超出的新对端共享一个有界溢出配额而不会驱逐已有计数器避免重置滥用者的预算一个全局预算限制为配置的每对端限额的16 倍用于限制总交换请求量防止轮换 IP 绕过限流见total.take(now, self.per_peer.saturating_mul(16))这些限制用于约束工作量但作者在文档中明确说明在持续分布式攻击下并不保证可用性。凭据续期机制扩展会在启动时以及选中远程连接期间周期性地检查续期本地模式没有续期闹钟。弹窗会显示授权过期时间并报告续期失败或需要重新配对的状态。续期机制有非常严谨的容错设计对应 remote-authorization.ts临时失败会保留当前凭据且每分钟最多重试一次RENEWAL_RETRY_MS 60_000如果过期后仍离线需要重新生成配对链接续期会轮换凭据请求发出前会先把待用新凭据pendingToken持久化这样即使 HTTP 响应丢失也能在 service worker 或服务器重启后用相同的旧/新凭据对重试——即使本地记录的旧过期时间已过弹窗能够区分未确认的续期unconfirmed与已知过期expired这两种状态修改生命周期参数只会影响后续交换不影响已签发的授权。在服务端续期同样支持精确重试authorization.rs 的exchange在renew分支中记录previous_hash对同一旧/新凭据对的重复请求返回与首次完全相同的响应且旧凭据不会轮换到其他替换凭据吊销也会使重试失效。TLS 反向代理部署如果不想让bsk直接暴露证书可以用常规 TLS 反向代理终结 HTTPS/WSS——代理不需要实现认证逻辑bsk daemon start --mode server --listen 127.0.0.1 --port 52800 \ --public-url wss://browser.example.com/extension代理需要遵守以下约定将/extension与/extension/authorize两个路径都转发到127.0.0.1:52800保留路径与 WebSocket 升级头保留Origin、Authorization与Sec-WebSocket-Protocol头绝不记录授权头、WebSocket 子协议值与请求体不要把凭据放进 query string认证仍然由内置服务器负责代理注入的用户头无法绕过认证。反向代理下的注意事项服务器看到的是代理的 IP因此代理后面的所有客户端共享同一个每对端授权限流。应在代理层配置每客户端限流并按预期聚合流量调大--authorize-rate-limit服务器不信任X-Forwarded-For或其他客户端 IP 头没有原生 TLS 时监听器必须绑定 loopback纯ws://公共 URL仅允许用于 loopback 开发非 loopback 的浏览器连接必须使用 WSS修改已配置的公共 URL 需要先吊销已有授权并生成新的配对链接服务端configure会强制校验见 authorization.rs。扩展端的 URL 校验同样严格remote-endpoint.ts 的parseRemoteEndpoint只允许wss:协议ws:仅当主机名是127.0.0.1、localhost或[::1]时放行并拒绝 URL 中携带用户名、密码或查询参数。配对与验证端到端四步流程配对链接是绝密信息它是一次性使用、默认 5 分钟过期的链接。完整流程分四步每一步都应有对应证据。第 1 步服务器操作者生成配对链接在另一个服务器 shell 中使用 daemon 的 OS 用户与一致的BSK_HOME执行BSK_AUTO_START0 bsk daemon pair输出形如wss://HOST/PATH#PAIRING_SECRET。生成后应立即告诉浏览器用户链接已就绪等待浏览器配对。服务端实现authorization.rs 的pair会检查服务器已启动--mode server、清理过期配对、并将未使用配对链接限制在 100 个以内。配对凭据是 32 字节随机数经 base64url 编码的 43 字符令牌服务端只保存其 SHA-256 哈希。第 2 步浏览器用户配对浏览器用户按照 AGENT_INSTALL.md 中的连接浏览器扩展章节安装扩展如未安装然后打开扩展弹窗选择Remote connection粘贴完整的配对链接并保存。保存链接会切换连接模式并结束现有任务。扩展会把配对密钥替换为设备凭据之后等待已连接状态。这一过程在扩展端的实现remote-authorization.ts中对应activateRemoteEndpoint→authorize(endpoint, pair, newToken())扩展把wss://协议改写为https://POST 到{path}/authorize携带Authorization: Bearer PAIRING_SECRET请求体为{ action: pair, next_token: …, label: Chrome · BrowserSkill }同时redirect: error拒绝重定向、credentials: omit不发 cookie、10 秒超时。第 3 步Agent 在服务器上确认浏览器在线BSK_AUTO_START0 bsk status --json确认预期浏览器出现在输出中。注意仅生成了链接或保存了配对都不等于连接已经激活。如果 Agent 无法访问服务器应将服务器侧验证报告为待定。第 4 步首次使用验证对于 CLI Agent从status中取出浏览器的instance_id作为browser-id启动测试会话并保留返回的session_idBSK_AUTO_START0 bsk session start --browser browser-id --no-focus --json然后用返回的会话 ID下文以id代替完成读页面与停止测试会话BSK_AUTO_START0 bsk navigate https://example.com --session id BSK_AUTO_START0 bsk observe --session id BSK_AUTO_START0 bsk session stop id成功或失败都必须停止测试会话并报告任何清理错误。使用 DeepSeek Harnessdsh时通过其注入的浏览器工具完成相同的 start / navigate / observe / stop 生命周期——服务器搭建与配对仍属操作者步骤。反馈准则只报告有证据的阶段证据向用户的反馈配对链接已生成链接已就绪等待浏览器配对。服务器列出了预期的已连接浏览器浏览器已连接首次使用验证待定。页面已读取且测试会话已停止远程首次使用验证完成。某一步失败或无法检查说明最后验证到的阶段、观察到的错误或缺失的访问权限以及下一步动作。配对链接过期或已被使用应让服务器操作者重新生成。其他连接失败请勿一律归因于链接过期应按弹窗错误提示检查端点、TLS 与代理配置。第三方网关协议扩展使用同一套协议连接bsk或任何兼容网关——它不调用任何特定提供商的登录 API。网关可以使用任意账号或管理系统来签发配对链接但必须实现下述面向浏览器的契约配对链接格式wss://HOST/PATH#PAIRING_SECRET。fragment 中包含 32–256 个 base64url 字符在任何网络请求发出前被移除fragment 本就不会随请求发送。扩展端校验见 remote-endpoint.ts正则^[A-Za-z0-9_-]{32,256}$授权交换扩展 POST 到https://HOST/PATH/authorize携带Authorization: Bearer PAIRING_SECRET与 JSON{ action: pair, next_token: …, label: … }。next_token是新生成的随机 256 位、无填充 base64url 凭据43 个字符与扩展端newToken()生成 32 字节后 base64url 编码的结果一致。网关必须一次性消费配对密钥并把替换凭据绑定到一个设备。配对密钥不能打开 WebSocket成功响应HTTP 200 返回{ device_id: 32 lowercase hex characters, expires_at: RFC3339 timestamp, renew_after: RFC3339 timestamp, service_name: optional display name }。无效或未授权的交换返回非 2xx。扩展拒绝重定向、不发送 cookie对应redirect: error与credentials: omitWebSocket 升级升级到wss://HOST/PATH时以恰好一个Sec-WebSocket-Protocol: bsk-auth.DEVICE_TOKEN子协议认证。网关必须在升级前校验并回显所选子协议。仅凭浏览器形态的 Origin 永远不构成授权服务端 server.rs 中 Origin 校验只是前置条件真正的认证来自bsk-auth.前缀令牌。凭据属于特定端点不能用于授权另一台设备或另一个部署续期使用同一 POST 端点与当前令牌action: renew并携带新的next_token保持相同的device_id。旧凭据对新连接失效。对相同旧/新凭据对的精确重试必须返回与首次相同的成功响应旧凭据不得轮换到不同的替换凭据。吊销同样会使重试失效。续期期间授权仍有效的已连接 socket 可以保持打开升级后的会话支持现有原生握手与 RPC 帧扩展端首个帧必须是system.handshake见 handshake.ts协议版本为1.3。所有 RPC 路由、响应、事件与会话状态都必须绑定到已认证的设备不得信任设备自报的浏览器 ID 去授权另一台设备的任务。过期或吊销时关闭活跃 socket 并取消其未完成工作。网关可以把这套协议桥接到其服务器上的本地bskdaemon从而保持该 daemon 的 loopback/IPC 边界私有。如果网关只是把凭据转发给内置服务器是无效的内置服务器只接受自己签发的授权。浏览器权限与任务生命周期配对即设备级授权只与你信任能操作浏览器的服务器配对。配对后的服务器可以创建 Agent Window 并使用该浏览器配置文件导航包括其中已登录的网站会话。配对是设备授权不是受限账号更不是网站沙箱——请把它当作把浏览器钥匙交给对方来对待。内容访问必须通过显式借用远程内容读取、截图、录制与页面操作都要求任务显式创建或借用borrow标签页列出标签页标题与 URL 仍然可用目的是选择要借用的标签页用户标签页被移入或通过 Agent Window 打开不会自动获得授权借用使用已有的浏览器控制确认偏好远程请求标志无法改变该偏好借用归还后远程内容访问立即结束远程录制期间归还标签页会先取消录制再释放标签页。弹出窗口与 OAuth 场景这条规则同样适用于页面通过target_blank、window.open或 OAuth 流程打开的标签页/窗口——opener 关系不授予控制权。如果这类标签页已经在 Agent Window 内则无法原地借用浏览器用户必须先把它移回普通浏览器窗口Agent 才能走常规借用流程。通过bsk tab create显式创建的标签页则立即受控。自动弹窗授权不在当前版本范围内。断开与清理语义断开连接会取消任务工作归还借用的标签页关闭任务创建的标签页用户创建的标签页在清理后保留。失败的回退failed returns会保留窗口必须在重连前解决。重连会启动新任务命令与会话绝不重放。远程认证失败时不会自动选择本地连接。版本限制当前版本不支持远程上传与下载会返回unsupported错误本地文件传输行为不变。截图与其他既有 RPC 内容结果仍然支持。当前没有网关预览/focus 侧协议、后台任务标签组或替代窗口模型。凭据存储与信任边界扩展侧设备凭据存放在扩展源extension-origin的 IndexedDB中普通扩展设置只保存选中的连接模式与非机密修订号revision。全新本地配置文件与显式选择的本地模式不会读取该凭据库。远程存储失败时弹窗报告错误且不会自动回退即使凭据库不可用显式选择本地连接也能恢复启动。旧版远程设置会在恢复普通设置访问前完成迁移见 remote-storage.ts 的initializeRemoteStorage服务端侧独立服务器以私有文件权限0600与原子写入持久化哈希后的凭据SHA-256authorization.rs文件内容永不包含明文令牌——测试pairing_is_one_use_durable_private_and_stores_only_hashes直接断言了这一点信任边界整个浏览器配置与BSK_HOME都应视为可信本地数据TLS 私钥需要单独保护。验证与测试构建 CLI 与扩展后运行常规 Rust 与扩展测试套件真实的浏览器回归测试还需要一个独立的 Chrome for Testing 可执行文件cargo test --workspace pnpm --filter browser-skill/extension test cargo build -p bsk pnpm --filter browser-skill/extension build BSK_REMOTE_CLI/absolute/path/to/target/debug/bsk \ BSK_REMOTE_CHROME/absolute/path/to/chrome-for-testing \ pnpm --filter browser-skill/extension test src/transport/__tests__/remote-connection.browser.test.ts远程服务器的集成测试覆盖可参考 remote_server.rs 与扩展端tests目录凭据交换、轮换重试、稳定设备路由、替换连接、吊销、连接容量、文件锁争用与原生 TLS单元测试额外覆盖限流饱和、扩展存储不可用、本地恢复、续期重试频率与弹窗授权状态。其中crates/bsk-cli/src/daemon/remote/authorization.rs内置的测试如only_one_concurrent_pairing_exchange_succeeds、rotation_retry_survives_restart_without_restoring_old_credentials、expired_and_revoked_pairings_and_grants_fail_closed与rate_limit.rs内置测试如proxy_clients_share_the_configured_peer_budget、rotating_addresses_cannot_exceed_the_total_budget直接印证了本文前述的安全语义。注意TLS 测试固件包含仅供测试使用的私钥绝不可用于部署。【免费下载链接】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），仅供参考