BrowserSkill 实战指南：如何装好 bsk CLI 与浏览器扩展，让 AI 智能体操作真实浏览器
项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkill BrowserSkill 是面向 AI 智能体的浏览器自动化方案：任何能执行 shell 命令的智能体，都能直接调用你已登录的 Chrome 或 Edge 读页面、填表单、截图，动作圈在独立的 Agent Window 里，不碰你正在用的标签页。读完本文，你能装好 bsk CLI 与浏览器扩展、跑通全链路检查，并让智能体完成第一个真实浏览任务。
一句话原理
系统由三块组成：bsk 命令行（内置常驻 daemon，即后台驻留进程）、真正执行点击/输入/截图的浏览器扩展，以及一份教智能体调用命令的 skill 文档。一次调用的流转：智能体在 shell 里执行 bsk 命令 → CLI 经本地 IPC 把请求交给 daemon → daemon 通过 WebSocket 转发给扩展（默认回环端口 52800）→ 扩展驱动浏览器，结果原路返回。它不做登录决策，只按指令操作你真实登录着的那台浏览器。
上手前自检
- 系统：macOS（Apple Silicon / Intel）、Linux（x64 / ARM64）或 Windows x64
- 浏览器：Chrome 或 Microsoft Edge，Chromium 125 及以上
- 权限：全程无需管理员，CLI 默认装到
~/.local/bin - 智能体：任一能执行 shell 命令的环境，如 Cursor、Claude Code、Codex
里程碑一：装好 bsk CLI 并确认版本
macOS / Linux 终端执行：
curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh
export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"
bsk --version
Windows 用 PowerShell（无需管理员）：
irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex
bsk --version
成功判据：终端打出版本号即可。CLI、扩展、DSH 插件共用同一版本号，当前发布为 0.3.3。如果提示 command not found，开一个新终端，或直接改用绝对路径 ~/.local/bin/bsk。
里程碑二：连接浏览器扩展
- 在 Chrome Web Store 或 Edge 附加组件商店搜索 "BrowserSkill" 并安装，把图标固定到工具栏
- 点击图标打开 popup，启用本地连接
- 核对 popup 显示的端口与本地 daemon 一致（默认 52800）
成功判据：popup 显示已连接（Connected）状态。连了多个浏览器实例时，可在 popup 给每个浏览器起名字方便区分。失败路径：先核对端口，再重启浏览器或 daemon 后重看状态。
里程碑三：装好 skill 并跑通 doctor 检查
交互式安装，用 Space 选中你的智能体环境，Enter 确认：
bsk install-skill
脚本化场景直接指定目标：
bsk install-skill --harness cursor --json
bsk doctor
成功判据：安装日志打印出 skill 目标路径；bsk doctor 的 daemon、IPC、扩展连接逐项通过。每个 fail 行都会附带 hint，照做后重跑一次即可。注意：doctor 通过不代表 skill 已被智能体发现，需另开一个智能体会话确认它能识别 browser-skill。若环境不在列表里，把 crates/bsk-cli/skill/ 整个目录复制到该环境的 skills 目录、命名为 browser-skill/（含 references/ 子目录）。
最小验证任务
新建一个智能体会话，发送：
Use browser-skill to open https://example.com, summarize the page, and end the browser session when finished.
预期输出：智能体先执行 bsk session start 建立会话，导航到 example.com，读取页面文本并返回一段摘要（"Example Domain" 的介绍），最后用 bsk session stop 结束会话。拿到摘要，说明链路全程打通。
不想开智能体时，也可以直接验证 CLI：
bsk session start --json
bsk navigate https://example.com --session <id>
bsk observe --session <id>
bsk session stop <id>
成功判据：observe 返回页面文本内容。任务结束后务必 session stop，包括失败的任务。
故障排查的 5 条自查路径
bsk: command not found原因：PATH 未生效，或终端还是旧会话 动作：重跑export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH，或打开新终端；智能体里改用绝对路径bsk doctor报扩展未连接 原因：popup 端口与本地 daemon 不一致，或 daemon 尚未启动 动作：核对 popup 里的端口，重启浏览器或 daemon 后再跑bsk doctor- CLI、daemon、扩展版本不一致 原因：三者版本必须一致，否则部分功能不可用 动作：
bsk update --yes更新 CLI，在商店里更新扩展，重跑bsk doctor - 已运行的智能体找不到新装的 bsk 原因：智能体启动时缓存了旧 PATH 动作：重启该会话，或为它配置二进制的绝对路径
- 沙箱宿主收走了后台 daemon 原因：会回收命令子进程的宿主（如 WorkBuddy / CodeBuddy）杀掉后台 daemon 动作：共享
BSK_HOME并设置BSK_AUTO_START=0让 daemon 常驻，细节见沙箱智能体指南
延伸入口
- 架构文档：CLI / daemon / 扩展如何协作
- 远程浏览器连接：服务器上的智能体 + 本地浏览器
- CLI 源码、协议与 JSON Schema、更新日志
装完之后，下次会话里凡是需要真实浏览器的任务，智能体会自己打开 Agent Window 操作页面，再把结果交还给你的会话。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
