企业官网建设流程全解析

BrowserSkill 是一个连接 Cursor、Claude Code、Codex、OpenClaw、CodeBuddy、WorkBuddy、Pi、Hermes Agent 等 AI Agent 与你已登录浏览器之间的本地桥接工具，由bskCLI/daemon 与浏览器扩展两部分组成。读完本文，你将掌握从安装、配置到首次任务验证的完整流程，理解"Agent Window + 标签页借出/归还"的会话模型，并能根据工作环境（普通本机、沙箱化 Agent、远程服务器）选择正确的部署方式。

项目概览：Agent 与浏览器之间的本地桥梁

BrowserSkill 的核心设计思想非常明确：Agent 永远不直接操作你的浏览器。Agent 通过 shell 调用bskCLI 发起浏览器任务，本地的bsk daemon将请求路由到浏览器扩展，扩展在一个独立的Agent Window中执行自动化操作。你的日常浏览器窗口保持原样，不会被抢占。

当任务需要触碰你已打开的某个标签页时，Agent 必须**显式借用（borrow）**该标签页，任务完成后归还（return），其余浏览器窗口完全不受影响。这套借出/归还模型是整个产品的安全基石，也是理解 BrowserSkill 一切行为的前提。

核心优势

• 复用真实登录态：Agent 可以直接操作你已经登录的网站，无需单独准备测试账号，也不要求你导出 Cookie。
• 不打断你的工作：浏览器任务运行在独立的、可见的 Agent Window 中，你可以继续使用自己的浏览器。
• 不绑定任何 Agent：任何能够执行 shell 命令的 Agent 都可以通过bskCLI 使用 BrowserSkill，不锁定特定模型、Agent 框架或 harness。
• 内置人机协作（human-in-the-loop）：当任务遇到验证码、登录、确认对话框等只有人能完成的步骤时，Agent 可以调用bsk request-help请求你接管，完成后继续。

此外，扩展弹窗的Quick actions → Full-page screenshot提供整页长截图能力，Agent 也可通过bsk screenshot --session <id> --full-page --out page.png完成，完整的行为契约见 docs/long-screenshot.md。

运行时环境与系统要求

BrowserSkill 由两个本地运行时部件组成：bskCLI/daemon 与浏览器扩展。

两个部件必须协同工作：CLI 负责命令解析与本地 IPC，扩展负责在浏览器内执行自动化。缺一不可。

快速上手：两种安装路径

方式一：让 Agent 自己安装（推荐）

如果你已经在使用 Cursor、Claude Code、Codex 或其他 shell 型 Agent，只需把下面这一行发送给你的 Agent，它会自动完成 CLI 与 skill 的安装，并引导你加载扩展：

Set up browser-skill on this machine by following https://raw.githubusercontent.com/Tencent/BrowserSkill/main/AGENT_INSTALL.md

完整的人工安装步骤记录在 AGENT_INSTALL.md，下文手动安装流程与之对应。

方式二：手动安装

1. 安装bskCLI

macOS / Linux（推荐，安装到~/.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，同样安装到~/.local/bin）：

irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex

注意：export 只对当前 Unix shell 生效。运行中的 Agent 可能需要在每次 shell 调用中重复设置 PATH，或直接使用已安装二进制的绝对路径；如果安装后 Agent 仍保留旧 PATH，需要重启 Agent。请在将要使用它的终端或 Agent 环境中验证二进制：

bsk --version

2. 安装浏览器扩展

从浏览器官方商店安装 BrowserSkill：

其他 Chromium 系浏览器请安装 Chrome Web Store 构建版本。安装脚本位于仓库根目录 install.sh 与 install.ps1。

3. 安装 skill

BrowserSkill 随附一份 skill，用于教会你的 Agent harness 如何使用bsk。对受支持的 harness，一条命令即可安装：

bsk install-skill

按Space选择目标 Agent harness，按Enter完成安装。bsk install-skill --list可查看内部变体与安装路径。

非交互式安装时显式指定 harness，例如：

bsk install-skill --harness cursor --json

• 显式--harness在 harness 未被检测到时同样有效；
• --yes单独使用会安装到所有检测到的 harness，若一个都没检测到则失败；
• 安装自定义指令：bsk install-skill --harness cursor --source ./SKILL.md，显式--source即使内容与内置 skill 一致也保持自定义；
• 已存在的安装默认跳过，除非加--force。

skill 的自动更新遵循"内容基线"策略：daemon 启动、session start、doctor只在当前内容与上次安装版本一致时才自动更新托管 skill；本地编辑会被保留并使自动更新暂停。doctor对历史文件不一致、本地编辑或无法识别的来源标记给出WARN与恢复选项，但不会让健康检查失败（--json报告status: "warn"与ok: true）。若要保留当前指令为显式自定义，运行bsk install-skill --harness cursor --source <existing-SKILL.md> --force；若要恢复内置 skill 并恢复自动更新，运行不带--source的bsk install-skill --harness cursor --force。

其他 shell 型 harness 也可手动安装：将 skill/SKILL.md 复制到 harness 的 skills 目录，命名为browser-skill/SKILL.md。DeepSeek Harness 使用专门的插件，见下文"DeepSeek Harness 插件"。

4. 验证连接

运行bsk doctor并遵循其提示，打开扩展弹窗确认已连接。先解释所有警告、解决所有失败，再开始测试浏览器操作。注意：doctor在没有安装 skill 时也能通过（报告N/A），因此 skill 的发现情况需要单独验证。

首次使用验证

启动一个新的 Agent 会话，确认browser-skill在 harness 中可用，然后请它打开https://example.com并总结页面内容。对于支持斜杠命令调用 skill 的 harness，例如：

/browser-skill open example.com and summarize what is on the page.

成功的首次检查会读取页面并停止其 BrowserSkill 会话。若 skill 缺失，请检查目标 harness 与安装路径后重试。

沙箱化 Agent 环境的特殊配置

如果你的 Agent 沙箱会在每条命令结束后收割后台进程（Linux WorkBuddy 的 bubblewrap 式 Bash 沙箱即如此，Windows 上部分 Agent 的 shell 任务同样如此），需要把 daemon 放在持久的主机执行环境中，沙箱内只通过共享本地 IPC 发起浏览器命令：

BSK_HOME=/absolute/shared/bsk BSK_AUTO_START=0 bsk status --json

• status 成功：复用该 daemon，空的browsers列表表示 IPC 就绪但扩展尚未连接，不需要另起 daemon；
• daemon 缺失：若已有主机任务在启动它，则进入就绪检查；否则在沙箱外的持久后台任务中运行BSK_HOME=/absolute/shared/bsk bsk daemon start --foreground；
• 权限错误、超时或无效响应：先检查报告路径、主机任务与 IPC 权限，这些错误不能证明 daemon 不存在。

所有沙箱内命令都必须使用相同的BSK_HOME与BSK_AUTO_START=0，因为环境变量可能不会在多次 shell 调用之间保留。详见 docs/sandboxed-agents.md 及其 PowerShell 示例。

更新机制

默认本地安装直接更新：

bsk update --yes

Windows 若报告"staged update"，请等待替换完成后再检查bsk --version。安装更新时该命令会用默认启动设置重启正在运行的 daemon；若你曾用安装器替换过二进制，则在任务结束后用bsk daemon restart重启现有 daemon。

对于自定义端口、主机托管的沙箱 daemon 或远程服务器，应在其宿主或 supervisor 中停止 daemon，运行bsk update --yes --no-restart-daemon，再用原来的参数与BSK_HOME启动；托管期间在 Agent 命令中设置BSK_AUTO_START=0。参见 docs/sandboxed-agents.md 与 docs/remote-extension-connection.md。

扩展通过浏览器商店更新；解压式开发构建则需重新构建并重新加载。商店发布可能滞后于 CLI 版本。用bsk --version与bsk status检查 CLI、daemon、扩展版本，再运行bsk doctor——整页截图等新功能需要三端版本匹配。受管理的 CLI skill 会在 daemon 启动、session start或doctor时同步，本地编辑与自定义 skill 会被保留；更新后请启动新的 Agent 会话以加载新指令。完整变更记录见 CHANGELOG.md。

升级到 0.3.0 的注意点：--unattended、tab borrow --no-confirm、BSK_REQUEST_HELP=off不再绕过确认或禁用求助，请改用下文描述的扩展设置。

自动化设置：借阅确认与人机协作开关

扩展弹窗中有两个相互独立的Automation settings，默认均开启，且用户保存的浏览器设置为每个会话的权威配置：

设置随浏览器配置自动保存，对现有与新会话都生效。关闭确认会释放挂起的借用确认；关闭帮助会以disabled结束挂起的求助请求。重新开启则恢复后续操作的行为（包括用旧--unattended标志创建的会话）。已完成的借用不会被撤销，已结束的求助不会被重开。允许帮助只让request-help可用，并不要求每个浏览器动作都请求许可——任务授权与宿主规则仍然适用。

任务用bsk session start启动；加--no-focus可避免聚焦 Agent Window。需要无人值守时，请在扩展中关闭对应设置。--unattended、tab borrow --no-confirm、BSK_REQUEST_HELP=off为兼容性保留但已弃用，不能覆盖扩展开关；CLI 与 daemon 使用这些输入时会记录提示。依赖这些输入避免等待的脚本必须改用浏览器设置。session start --json与session list --json会报告浏览器生效的interaction策略。

当帮助被禁用时，request-help直接返回disabled且不确认任何人工动作；skill 会引导 Agent 重新观察，并利用现有登录态、已授权输入与可用工具尽力完成授权步骤。在任务授权与宿主规则允许时，支持图像理解的模型可以尝试图形化验证；仅手机可用的 QR 扫码、人脸验证、不可用的短信验证码、纯文本模型的图片验证码等仍可能受阻。disabled结果既不代表任务完成，也不授予额外权限。

偏好加载失败时，运行时保留已知值，无有效值则默认两者开启，不会写回默认值或阻塞会话创建；弹窗会报告读取失败并阻止保存，写入失败不会被当作成功。浏览器断开时产生的是错误，而不是基于命令行标志或环境变量的本地disabled结果。

tab borrow --timeout 60s只控制确认等待时间（默认 60s），不决定是否要求确认。协议 1.3 保持与 1.0–1.2 的兼容；滚动升级期间普通会话与默认借阅仍可用。自定义借用等待需要 daemon 与扩展均为协议 1.2+，仅该操作在不受支持时返回升级错误。request-help需要 daemon 协议 1.3（旧 daemon 可本地应答而不咨询浏览器），建议同时更新 CLI、运行中的 daemon 与扩展以获得完整的设置强制力。

DeepSeek Harness 插件

使用 DeepSeek Harness（dsh）时，BrowserSkill 提供 npm 上的@wxg-prc-cpg/browser-skill-dsh-plugin一等公民插件，为 Agent 提供原生browser_*工具，并在 Web UI 中实时展示浏览器会话。插件代表 Agent 运行bsk。

先安装bskCLI 并连接浏览器扩展，再将插件加入 dsh profile 并启动（将web替换为你的 profile 名）：

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

插件自带browser-skillskill，因此 dsh 无需bsk install-skill。已安装的插件不会自动更新，升级命令：

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

升级后重启 profile。用法与配置详见 packages/dsh-plugin-browserskill/README.md。

工作原理：CLI、daemon、扩展三件套

BrowserSkill 是 Agent harness 与浏览器之间的本地桥：

Agent 从不直接与浏览器通信。它请bskCLI 执行浏览器任务 → 本地 daemon 将请求路由到扩展 → 扩展在 Agent Window 中执行。DeepSeek Harness 通过插件走同一条路径：Agent 调用注入的browser_*工具，插件代其调用bsk。

三个组件的职责（源码级）

从 docs/architecture.md 可以确认三个组件的分工：

bskCLI（crates/bsk-cli）

• 解析动宾子命令（bsk session start、bsk click…）；
• 通过 IPC 发现运行中的 daemon，仅在发现失败或监听器缺失时自动启动一个（BSK_AUTO_START=0可禁用隐式启动）；
• 在 Unix 上通过$BSK_HOME/run/daemon.sock（Windows 为命名管道）讲 JSON Lines 协议，默认 home 为~/.bsk；
• 默认输出人类可读结果，--json输出结构化响应。

bsk daemon（同一二进制：bsk daemon）

• 本地模式在回环 WebSocket 上监听（默认52800，可用bsk daemon start --port配置）供扩展连接；
• 校验握手Origin: chrome-extension://…；
• 维护browsers（已连接扩展）与sessions（Agent Window 绑定）；
• 按会话串行化针对同一会话的工具调用队列；
• 将tool.*RPC 转发到正确的扩展连接。

状态文件位于~/.bsk/：daemon.lock（单实例咨询锁）、daemon.json（sock_path/pid/ws_port/version）、daemon.log（滚动跟踪日志）、daemon.pid。

bsk扩展（apps/extension）WXT/MV3 Chromium 扩展，React 弹窗 + service worker 后台。transport/提供可插拔 Transport（v1 为WSTransport）；tools/的ToolDispatcher管理约 21 个工具处理器；session-manager/管理会话、Agent Window 与@e1引用存储；browser-driver/提供 CDP 驱动的浏览器操作；content/在 Agent Window 中渲染控制覆盖层。

bsk-protocol（crates/bsk-protocol）提供共享 Rust 类型与 JSON Schema 生成，TypeScript 在 apps/extension/src/transport/types.ts 中镜像帧结构。

一次典型工具调用的完整链路

1. Agent 运行bsk click @e1 --tab-id 42 --session ab12；
2. CLI 确保 daemon 运行，打开 UDS，发送一行 JSON 请求；
3. daemon 将 sessionab12解析到浏览器客户端，经 WS 转发tool.click；
4. 扩展的 dispatcher 校验沙箱规则，通过BrowserDriver调用 CDP；
5. 响应沿 CLI ← daemon ← 扩展返回，CLI 打印结果并退出。

会话与沙箱模型

• Session= 不透明 ID + 专用 Agent Window + 会话级 ref-store + 借阅表；多个会话对应多个 Agent Window，完全隔离；
• 沙箱约束：写工具要求标签页位于 Agent Window 内，除非该标签页是从用户 profile借用的；
• 必须显式停止会话（bsk session stop），空闲超时（默认 5 分钟）只是安全网；
• 远程内容读取与操作要求任务创建或显式借用的标签页；页面弹出的弹窗或移入 Agent Window 的用户标签页不会自动获得控制权。

tab list的--scope参数控制可见范围：user（用户 profile 窗口，默认）、agent（仅当前会话的 Agent Window）、all（Agent Window + 用户窗口）。

并发策略：同一会话由 daemon 串行化 RPC（保证 ref-store 安全）；不同会话并行；连接多个浏览器时用bsk session start --browser <id>指定。

连接安全

• 本地模式 WebSocket 绑定回环地址；服务器模式通过认证的 WSS 允许远程访问；
• WS 升级时对扩展 origin 做白名单校验；
• 网站 Cookie 始终留在用户浏览器 profile 中；远程设备凭据存于扩展 origin 的 IndexedDB，内置服务器的凭据哈希存于私有BSK_HOME；
• evaluate在沙箱模式下仅限 Agent Window 标签页；
• 可选的操作审计记录在 daemon 所在主机（本地在本机、远程在服务器），支持导出、删除与 30 天保留，详见 docs/operation-audit.md。

给开发者的仓库导览

仓库是 Cargo + pnpm workspace：

• crates/bsk-cli —bskCLI 与本地 daemon；
• crates/bsk-protocol — 共享线格式与 JSON Schema；
• apps/extension — 浏览器扩展；
• packages/ui 与 packages/i18n/README.md — 共享扩展 UI 支持，含英文、简体中文、韩文本地化；
• packages/dsh-plugin-browserskill — DeepSeek Harness 插件；
• evals/browser/README.md — 确定性的本地页面与 Agent 无关的浏览器能力评估。

对开发者还有两份深度参考：完整架构见 docs/architecture.md；scroll-to原语参考见 docs/scroll-to.md，覆盖其 CLI、协议与插件入口、可见边界与中断行为。

许可证

BrowserSkill 以 MIT 许可证开源，详见 LICENSE。