让 AI Agent 在你已登录的浏览器里工作，你继续做自己的事。
English · 中文
快速开始 · 网站调试 · DSH 插件 · 文档导航 · 更新日志
BrowserSkill 把你的 AI Agent 连接到 Chrome 或 Microsoft Edge，直接使用你已有的登录状态。 你可以让它读取页面、填写表单、完成网站操作、截取长图，也可以让它调查某个请求为什么失败。任务在独立、可见的 Agent Window（代理窗口） 中运行；需要操作已有标签页时，显式借用，任务结束后归还。
Cursor、Claude Code、Codex、OpenClaw、CodeBuddy、WorkBuddy、Pi、Hermes Agent 等能调用 Shell 的 Agent，都可以通过 bsk CLI 使用。DeepSeek Harness 还提供专用插件，直接使用浏览器工具并查看任务预览。Agent 和模型由你选择，BrowserSkill 负责连接浏览器。
| 能力 | 你可以用它做什么 |
|---|---|
| 使用已有账号工作 | 复用浏览器登录态，读取文档、搜索内部网站、填写表单，完成需要登录的网站流程。 |
| 看得见的浏览器任务 | 给 Agent 一个独立窗口，需要时借用已有标签页；遇到登录、验证等步骤，可以由你接手。 |
| 读取、操作与截图 | 读取页面文本和控件，点击、输入、管理标签页，截取可见区域或完整页面，在本地模式上传和下载文件。 |
| 带着证据调试网站 | 把操作与请求、响应正文、控制台和页面变化关联起来，检查性能、慢接口与疑似重复请求，用明确配置的 HTTP 规则或请求重放验证问题。 |
| 选对浏览器和账号 | 为浏览器实例命名，让任务绑定指定 Profile；也可以让服务器上的 Agent 连接你电脑上的浏览器。 |
| 回看任务过程 | 重新打开浏览器本地的调试历史、导出 JSON，或单独开启操作审计，查看任务执行记录。 |
| 提取结构化数据 | 将已加载的表格和列表导出为 JSON/CSV，保留列名、页面/frame 来源、合并单元格信息和完整性标记。见结构化提取说明。 |
| 录制任务视频 | 让 Agent 将一个已授权标签页录制为无声 MP4，再从扩展中预览、保存或删除视频。见任务视频录制。 |
| 等待页面条件 | 设置明确的超时，等待目标元素满足指定条件后再继续操作。见元素等待。 |
看看 Agent 如何完成一次浏览器任务：
github.-.mp4
本地自动化需要 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：
按照 https://raw.githubusercontent.com/Tencent/BrowserSkill/main/AGENT_INSTALL.md 的说明，在本机安装并配置 browser-skill。
安装指南会引导 Agent 安装 CLI、选择对应的 skill 或 DSH 插件、检查连接，并完成第一次浏览器任务。你仍需在想使用的浏览器中安装扩展：
手动安装步骤
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，或配置安装后二进制的绝对路径。
从 Chrome Web Store 或 Edge 加载项商店 安装扩展。打开弹窗，开启本地连接，在 CLI 启动后检查连接状态。
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。
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，以及宿主无法维持任务时的独立终端兜底方式。
DSH 插件 在 DeepSeek Harness Web UI 中提供原生 bsk_* 工具、浏览器任务预览和截图结果。它使用同一套 bsk CLI 与扩展，并自带 BrowserSkill skill。
**升级到 0.3.3：**先更新 CLI 和扩展，再更新插件。六个 browser_* 工具已改名为 bsk_*，不保留旧名称别名。请更新自定义工具调用和策略，重启 DSH profile，并在已有对话中重新调用 /browser-skill。详见迁移指南。
安装好 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。
让 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.pngAgent 截图支持后台标签页，无需将窗口切到前台；原文档仍可访问时，完成后会恢复滚动位置。长截图沿页面文档滚动，嵌套滚动面板和虚拟列表存在支持限制。详见长截图指南。
在目标 Profile 的扩展弹窗中点击复制此 Profile 的指令，将指令和任务一起发给 Agent。也可以设置唯一的浏览器名称，再显式选择：
bsk browsers
bsk session start --browser "工作账号" --no-focus --json这个名称由你在 BrowserSkill 中设置，不会自动读取 Chrome 的 Profile 名称。每个会话固定使用选定的实例。详见Profile 选择指南。
保留本机浏览器和登录态，让 Agent、CLI 与 daemon 在服务器运行。扩展通过经过鉴权的 WSS 与服务器配对，由浏览器主动建立连接，本机无需开放入站端口。
内置服务端支持设备配对、续期和撤销授权。bsk upload 和 bsk download 文件传输命令仍仅支持本地模式。经过授权的视频导出可以写入 CLI 所在计算机，包括远程服务器；扩展中的“另存为 MP4”写入浏览器所在计算机。详见远程连接指南。
代理窗口共享所选 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。视频库支持预览、导出和删除。 |
这些功能均支持导出和删除。结束任务或断开连接不会删除保留的历史或视频，过期数据会在访问或清理时处理。导出的文件、Agent 或网关已经收到的副本需要另行管理。调试数据会过滤已知敏感信息，但不能保证完全脱敏。视频画面不会自动脱敏，分享前请检查可见内容。
先结束正在执行的浏览器任务，再更新 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:buildCLI 产物位于 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；附上浏览器证据前，请移除敏感数据。
扩展界面支持英语、简体中文、繁体中文、韩语、日语、法语、意大利语、西班牙语、德语和巴西葡萄牙语。翻译贡献见多语言说明。