浏览器自动化桥 Tencent/BrowserSkill

BrowserSkill

你的 Agent。你的浏览器。连接，就能协作。
让 AI Agent 在你熟悉、已登录的浏览器里办事。

English · 中文官网 ·演示视频 ·功能一览 ·网站调试 ·文档导航 ·更新日志

BrowserSkill 把你的 AI Agent 连接到 Chrome 或 Microsoft Edge，直接使用你已有的登录状态。 交给它读取、点击、填表或排查问题。任务在独立、可见的 Agent Window（代理窗口） 中运行，需要时由你接手；也可以显式借用已有标签页，任务结束后归还。

看看实际效果

▶ 观看演示 · 81 秒 · 中文版

https://github.com/user-attachments/assets/959cb520-80ba-4b9e-b6d8-d94523b03693

点击封面展开播放 · 下载 MP4 基于 main 版本，在本地演示网站中录制的真实浏览器操作。

用你熟悉的 Agent

Codex
Claude Code
Cursor
OpenClaw

CodeBuddy
WorkBuddy
Pi
Hermes Agent

这些 Agent，以及其他能调用 Shell 的 Agent，都可以通过同一套 bsk CLI 使用。DeepSeek Harness 还提供专用插件，直接使用浏览器工具并查看任务预览。Agent 和模型由你选择，BrowserSkill 负责连接浏览器。

能做什么

| 你想完成的事 | BrowserSkill 如何帮忙 |
| 用已有账号，做网站任务 | 复用浏览器登录态，读取文档、搜索内部网站，完成需要登录的网页流程。 |
| 一句指令，落实到操作 | 读取页面文本和控件，点击、输入、填写表单、拖拽元素、选择范围、管理标签页；截取可见区域或完整页面，在本地模式上传和下载文件。 |
| Agent 操作，你来掌控 | 共享控制让你与 Agent 协作；编辑时暂停 Agent，让它核对你的改动后继续。任务在独立窗口中可见运行，也可显式借用已有标签页。 |
| 网页表格，导出即用 | 将已加载的表格和列表导出为 JSON/CSV，保留列名、页面/frame 来源、合并单元格信息和完整性标记。结构化提取 |
| 操作出错，找到线索 | 关联操作、请求、响应正文、控制台和页面变化，检查性能、慢接口与疑似重复请求；用明确配置的 HTTP 规则或请求重放验证判断。网站调试 |
| 录下过程，随时回看 | 将一个已授权的任务标签页录制为无声 MP4，在扩展中预览、保存或删除。任务视频录制 |
| 页面就绪，再做下一步 | 设置明确的超时，等待目标元素满足指定条件后再继续操作。元素等待 |
| 已经观察，按需复用 | 用 step 执行一个已决定的动作并同步状态；明确保存完整观察结果，再用 view 搜索或分段阅读，无需重新采集页面。步骤与观察结果保存 |
| 浏览器与账号，选对再开工 | 为浏览器实例命名，让任务绑定指定 Profile；也可以让服务器上的 Agent 连接你电脑上的浏览器。浏览器 Profile |
| 任务结束，记录可查 | 重新打开浏览器本地的调试历史、导出 JSON，或单独开启操作审计，查看任务执行记录。操作审计 |

快速开始

本地自动化需要 AI Agent + bsk CLI + 浏览器扩展。CLI 自带后台守护进程（daemon），skill 则负责告诉 Agent 如何使用这些工具。

| 组件 | 支持环境 |
| CLI / daemon | macOS：Apple Silicon、Intel；Linux：x64、ARM64；Windows：x64 |
| 浏览器扩展 | 基于 Chromium 125 或更新版本的 Chrome、Microsoft Edge。其他 Chromium 浏览器可能可用，但不保证兼容。 |
| Agent 接入 | 能调用 Shell 的 Agent 配合 BrowserSkill skill，或 DeepSeek Harness 配合 DSH 插件。 |

让 Agent 帮你安装

把下面这句话发给 Agent：

按照 https://raw.githubusercontent.com/Tencent/BrowserSkill/main/AGENT_INSTALL.md 的说明，在本机安装并配置 browser-skill。

安装指南会引导 Agent 安装 CLI、选择对应的 skill 或 DSH 插件、检查连接，并完成第一次浏览器任务。你仍需在想使用的浏览器中安装扩展：

安装 Chrome 扩展 · 安装 Edge 扩展

手动安装步骤

1. 安装 CLI

macOS / Linux：

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

默认安装到 ~/.local/bin。在实际使用工具的终端或 Agent 环境中检查：

bsk --version

如果已启动的 Agent 找不到 bsk，重启 Agent 以加载新的 PATH，或配置安装后二进制的绝对路径。

2. 连接扩展

从 Chrome Web Store 或 Edge 加载项商店 安装扩展。打开弹窗，开启本地连接，在 CLI 启动后检查连接状态。

3. 给 Agent 安装 skill

bsk install-skill

按 空格 选择使用的 Agent，按 Enter 安装。非交互安装时显式指定目标，例如：

bsk install-skill --harness cursor --json

用 bsk install-skill --list 查看支持的目标和安装路径。已有安装默认跳过，只有显式使用 --force 才会覆盖。其他 Agent 可将完整的 crates/bsk-cli/skill/ 目录复制到其 skill 目录下，命名为 browser-skill/，保留其中的 references/。

DSH 用户安装 插件 即可，插件已包含 skill。

4. 验证连接

bsk doctor

解决失败项，确认扩展显示已连接。再开启一个新的 Agent 会话，确认能发现 browser-skill；doctor 通过并不代表 Agent 已加载 skill。

试一个任务

连接成功后，对 Agent 说：

使用 browser-skill 打开 https://example.com，总结页面内容，完成后结束浏览器会话。

Agent 默认在后台打开独立代理窗口、读取页面、返回总结，并结束任务。误入代理窗口的外部链接或手动新建标签会移回最近使用的普通用户窗口；没有用户窗口时会新建一个。分流发生在标签创建之后，可能短暂显示在代理窗口中。页面打开的子标签、人类协助和录制流程会保留。支持 skill 斜杠命令的 Agent，也可以通过 /browser-skill 调用。

将任一受控标签移出原代理窗口会结束整个浏览器会话，保留全部页面并清除控制标识；借用页也留在当前位置。拖回标签不会恢复任务，需要由用户决定是否重新开始。同窗口内调整标签顺序不受影响，正常结束会话仍按原规则归还借用页、清理任务页。

网页打开原生弹窗时，Chrome 仍可能激活窗口。对于观察到的任务弹窗，若用户没有切换窗口，扩展会恢复之前的 Chrome 用户窗口或最小化状态。Chrome 公开扩展 API 无法保证完全没有瞬时激活，也无法恢复其他应用的焦点。

直接试用 CLI

先创建会话，记下返回的 session_id：

bsk session start --json

将下面每条命令中的 <id> 替换为该值。有多个浏览器连接时，在创建会话时用 --browser <实例 ID 或名称> 选择目标。默认后台创建，仍兼容 --no-focus；显式使用 --focus 可将新窗口置于前台。请求人类帮助和交互录制仍会将相关窗口置于前台。

bsk navigate https://example.com --session <id>
bsk observe --session <id>
bsk screenshot --session <id> --out example.png
bsk session stop <id>

通过 bsk --help 或 bsk <命令> --help 查看参数。完成或失败后都应结束会话；借用的标签页会归还到原窗口。

在 WorkBuddy/CodeBuddy 或会回收命令子进程的宿主中，Agent 应先复用已有 daemon；需要启动时，在宿主管理的后台任务中运行 bsk daemon start --foreground，并在另一条工具调用中验证连接。宿主配置指南说明了如何共用 BSK_HOME、设置 BSK_AUTO_START=0，以及宿主无法维持任务时的独立终端兜底方式。

DeepSeek Harness 插件

DSH 插件 在 DeepSeek Harness Web UI 中提供原生 bsk_ 工具、浏览器任务预览和截图结果。它使用同一套 bsk CLI 与扩展，并自带 BrowserSkill skill。

升级到 0.4.1：先更新 CLI 和正在运行的 daemon，再更新扩展和插件。重启 DSH profile，并重新调用 /browser-skill，让已有对话加载新的 target 策略及控制、观察指引。详见 0.4.1 升级指南；从 0.3.3 以前的版本升级时，还需要完成工具名称迁移。

安装好 DeepSeek Harness、pnpm 和 bsk，连接扩展后，将插件加入你的 profile：

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

将 web 替换为自己的 profile 名称。确保启动 DSH 的环境能通过 PATH 找到 bsk，或配置插件的 bskPath。在对话中调用 /browser-skill 并描述任务即可，无需再执行 bsk install-skill。

插件使用与配置 · npm 包

网站调试

让 Agent 看到问题发生时的浏览器证据。 在你有权调试的网站上，先开启采集，再复现问题，随后在扩展中查看，或交给 Agent 分析。

- 沿着操作找原因：查看一次操作关联的请求、控制台输出、表单字段值，以及即时或延后的页面变化；既记录 Agent 操作，也记录受支持的手动操作。
- 展开请求看细节：读取已保留的请求头、提交数据、响应正文、耗时与错误，筛选流量或直接查看某个 JSON 字段。
- 检查性能和接口：查看页面加载指标、接口耗时统计和疑似重复请求；缺失或不完整的数据会明确标记。
- 验证并保留证据：配置任务内的请求修改、拦截、模拟响应或同源请求重放，导出 JSON，供后续复查和分享。

例如可以这样交代任务：

使用 browser-skill 排查 http://localhost:3000 的表单保存失败问题。复现前开启网站调试，检查请求、响应和控制台，最后导出调试证据并结束会话。

也可以在扩展中打开快捷功能 → 网站调试，对已有任务启动采集。调试页将操作时间线、请求、控制台、页面状态、性能和 API 分析放在一起。任务结束后，即使没有连接 daemon，仍可打开历史查看记录；新的 Agent 任务需要你提供导出的文件，才能分析已结束任务的历史。

请求重放会使用页面当前会话发送一次新请求，可能改变服务端数据。采集和脱敏均有限制，保存的证据仍可能包含敏感信息。完整流程、CLI 示例及限制见网站调试指南。

更多用法

截取完整页面

打开快捷功能 → 长截图，选择自动滚动、手动滚动拼接长图或截取可见区域。这个扩展功能无需连接 Agent 或 daemon，也可以独立使用。

对 Agent 会话中的页面，可以执行：

bsk screenshot --session <id> --full-page --out page.png

Agent 截图支持后台标签页，无需将窗口切到前台；原文档仍可访问时，完成后会恢复滚动位置。长截图沿页面文档滚动，嵌套滚动面板和虚拟列表存在支持限制。详见长截图指南。

使用指定浏览器 Profile

在目标 Profile 的扩展弹窗中点击复制此 Profile 的指令，将指令和任务一起发给 Agent。也可以设置唯一的浏览器名称，再显式选择：

bsk browsers
bsk session start --browser "工作账号" --no-focus --json

这个名称由你在 BrowserSkill 中设置，不会自动读取 Chrome 的 Profile 名称。每个会话固定使用选定的实例。详见Profile 选择指南。

Agent 在服务器，浏览器在本机

保留本机浏览器和登录态，让 Agent、CLI 与 daemon 在服务器运行。扩展通过经过鉴权的 WSS 与服务器配对，由浏览器主动建立连接，本机无需开放入站端口。

内置服务端支持设备配对、续期和撤销授权。bsk upload 和 bsk download 文件传输命令仍仅支持本地模式。经过授权的视频导出可以写入 CLI 所在计算机，包括远程服务器；扩展中的“另存为 MP4”写入浏览器所在计算机。详见远程连接指南。

浏览器控制与隐私

新任务默认启用共享控制。BrowserSkill 会观察受控标签页中的页面变化和受支持的手动活动，让 Agent 在你编辑时让出控制权，并在再次操作前同步状态。即使调试、审计和视频录制均关闭，这种协调仍会进行。你可以通过任务的手动接管与恢复功能决定何时继续。共享控制指南

代理窗口共享所选 Profile 的登录态，它不是独立账号，也不是安全沙盒。Agent 可以使用已登录网站授予的权限执行操作，请选择你信任的 Agent 和任务。

扩展提供两个默认开启、相互独立的自动化设置：

| 设置 | 控制什么 |
| 借用标签页前确认 | Agent 接管你已有的标签页之前，先请求确认。关闭后允许免确认借用。 |
| 允许请求人工协助 | 允许 Agent 请你处理登录、验证或其他需要本人参与的步骤。 |

浏览器中保存的设置对已有和新建会话生效。旧的 --unattended、tab borrow --no-confirm、BSK_REQUEST_HELP=off 不能覆盖这些设置。关闭人工协助不代表待处理步骤已经完成。关闭代理窗口可以停止其中的任务。

BrowserSkill 没有必须使用的云服务，也不收集产品遥测。自动化结果交给你选定的 daemon 或网关，以及使用它的 Agent；对应 Agent 或服务可能按自身政策处理或保留数据。扩展不会自行调用 AI 提供商。

| 可选历史与视频记录 | 保存位置 | 需要知道的事 |
| 网站调试 | 当前浏览器配置中，远程模式也一样 | 保存采集到的数据，包括可获取的正文和字段值。已停止记录 30 天后过期，保留预算为 50 条／50 MiB，达到限制时可能提前清理。删除记录前需先停止采集。 |
| 操作审计 | daemon 所在主机的 BSK_HOME/audit | 默认关闭。记录任务与操作元数据，不记录输入值、页面正文、截图或文件内容。已结束任务 30 天后过期。 |
| 任务视频 | 当前浏览器配置；导出副本保存在指定位置 | 主动开启后，录制一个已授权标签页的无声视频；单个视频上限为 10 分钟／256 MiB，创建 24 小时后过期，临时视频预算为 1 GiB。视频库支持预览、导出和删除。 |
| 观察结果及 step 响应 | CLI 所在计算机上明确指定的 JSON 路径，也可能是远程服务器 | --save-full／DSH saveFull 会在显示过滤前保存完整响应。文件不会自动过期，需要在该计算机上删除；view 读取历史数据，不会刷新浏览器状态。 |

这些功能均支持导出和删除。结束任务或断开连接不会删除保留的历史或视频，过期数据会在访问或清理时处理。导出的文件、Agent 或网关已经收到的副本需要另行管理。调试数据会过滤已知敏感信息，但不能保证完全脱敏。视频画面不会自动脱敏，分享前请检查可见内容。

隐私政策 · 操作审计 · 调试历史与保留限制

升级

升级到 0.4.1 时，先更新 CLI 并重启正在运行的 daemon，再更新扩展，最后更新 DSH。 CLI/daemon 和扩展 0.4.1 使用协议 1.8，新的默认 target 策略要求两端均支持 1.8。仅替换二进制不会更新通过前台或外部进程管理器运行的旧 daemon，仍需在所属宿主中重启。使用新流程时请配套使用 0.4.1 组件。

已有脚本需要遵循共享控制流程：首次导航后执行 bsk cooperate sync，将返回的 context_id 作为 --context 传入。target 策略下，DOM 操作和补充观察可以复用该控制上下文，决策依赖的业务事实用 --expect 显式校验。脚本、无目标按键和视觉操作还需将同步返回的 observation_id 作为 --observation 传入。人工介入或导航后重新同步；若要保留每个上下文只执行一次操作的流程，在首次同步时指定 --policy strict。继续任务前请加载新版 skill。

先结束正在执行的浏览器任务，再更新 CLI：

bsk update --yes

默认本地配置下，这条命令会在 daemon 继续服务的同时安装新版本并检查它能否运行，然后用新版本在原端口重启 daemon。重启后的 daemon 没有就绪时，会放回旧版本并用它重启 daemon。通过 --foreground 启动的 daemon 不会被停止，会继续运行旧版本，请在它所在的终端或进程管理器中重启。如果 bsk update 运行在无法重新启动后台 daemon 的环境里（例如 Windows Job 禁止 breakaway 的沙盒），后台 daemon 同样不会被停止，请在沙盒外执行 bsk daemon restart。如果使用安装脚本替换了二进制，请随后执行 bsk daemon restart。

由 bsk 在后台启动的 daemon 还会每 30 分钟检查一次新版本。没有 Agent 会话时，它按同样方式安装新版本，再用新版本启动一个 daemon，确认新版本的 daemon 已在原端口服务后才退出。新 daemon 退出，或 20 秒内没有就绪时，它会被停止，当前 daemon 放回旧版本，在原端口继续服务，6 小时后再尝试这个版本。交接期间浏览器连接会短暂断开并自动重连。更新过程中 daemon 因其他原因（例如空闲超时）停止时，会先放回旧版本再退出。通过 --foreground 启动的 daemon 归所在终端或进程管理器管理，只提示新版本：执行 bsk update，再在那里重启 daemon。bsk 无法在可执行文件所在目录写入时，也只提示新版本，请用原来的安装脚本或包管理器升级。设置 BSK_AUTO_UPDATE=off 可关闭 daemon 自动升级，手动 bsk update 仍然可用。

bsk doctor 会显示最近一次更新的结果；bsk home 下的 update-state.json 记录了它的阶段、结果和错误原因。同一个可执行文件的更新会依次进行，即使来自不同的 bsk home 也是如此，靠的是它旁边的 .bsk.update.lock（Windows 上为 .bsk.exe.update.lock），这个文件会一直保留。更新确认成功前，旧版本会以 .bsk.old-（Windows 上为 .bsk.exe.old-*）的名字留在新版本旁边；仍在运行的旧版本会保留到对应进程退出，之后再启动 daemon 时会清理。Windows 上的自更新依赖重命名正在运行的可执行文件，NTFS 支持这一操作；文件系统不支持时，更新会失败，已安装的版本保持不变。bsk 支持 Windows 10 和 Windows Server 2016 及以上版本。

扩展通过浏览器商店更新。DSH 插件需要单独更新，完成后重启对应 profile：

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

通过 bsk --version、bsk status 和 bsk doctor 检查版本与连接。使用新功能时，保持 CLI、正在运行的 daemon、扩展和可选 DSH 插件版本匹配。本 README 介绍当前仓库的能力，商店版本可能因审核而滞后；已发布内容以更新日志和 Releases 为准。

受管理的 CLI skill 在文件未被修改时，会随 daemon 启动、session start 或 doctor 自动同步；本地修改和自定义 skill 会保留。开启新的 Agent 会话以加载更新后的指令，doctor 会提示暂停同步的安装。

自定义端口、沙盒宿主和远程服务器

在 daemon 所属宿主或进程管理器中停止服务，执行 bsk update --yes --no-restart-daemon，再使用原参数与 BSK_HOME 启动。管理期间，在 Agent 命令中设置 BSK_AUTO_START=0。具体步骤见沙盒或远程连接指南。

文档导航

| 你想做什么 | 文档 |
| 让 Agent 安装并验证连接 | 安装指南 |
| 排查网站或接口问题 | 网站调试 |
| 截取长页面 | 长截图 |
| 录制并保存任务视频 | 任务视频录制 |
| 导出表格或列表 | 结构化提取 |
| 等待元素条件 | 元素等待 |
| 使用指定账号或 Profile | 浏览器 Profile |
| 连接服务器上的 Agent | 远程浏览器连接 |
| 在沙盒中使用 | 沙盒环境配置 |
| 回看任务操作元数据 | 操作审计 |
| 接入 DeepSeek Harness | DSH 插件 |
| 了解项目实现 | 架构 · 协议 |

面向开发者

项目使用 Rust + pnpm workspace。源码构建需要 Rust stable、Node.js 22，以及 package.json 声明的 pnpm 版本：

pnpm install --frozen-lockfile
cargo build --release --locked
pnpm ext:build

CLI 产物位于 target/release/；将 apps/extension/dist/chrome-mv3/ 作为解压后的扩展加载。开发扩展时使用 pnpm ext:dev。

| 目录 | 内容 |
| crates/bsk-cli | CLI、daemon 和内置 Agent skill |
| crates/bsk-protocol | 通信类型与 JSON Schema |
| apps/extension | 浏览器自动化、调试工作区和扩展界面 |
| packages/dsh-plugin-browserskill | DeepSeek Harness 集成 |
| packages/ui、packages/i18n、packages/vom | 共享 UI、多语言和页面观察 |
| evals/browser | 本地测试页面与浏览器能力评测 |

相关检查包括 cargo test --workspace --locked、pnpm ext:test 和 pnpm lint。可复现的浏览器用例见评测指南。欢迎通过 GitHub Issues 报告问题，或提交聚焦的 PR；附上浏览器证据前，请移除敏感数据。

扩展界面支持英语、简体中文、繁体中文、韩语、日语、法语、意大利语、西班牙语、德语和巴西葡萄牙语。翻译贡献见多语言说明。

贡献者

感谢每一位贡献代码、文档、翻译与反馈的朋友。

查看 GitHub 贡献记录 ·提交问题与建议

许可证

MIT