BrowserSkill 实战入门：5 分钟让 AI 直接操作你的已登录浏览器，跑通第一个自动化任务
【免费下载链接】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 开测试账号了
想让 AI 帮你打开一个需要登录的站点、把里面的内容读出来做总结，最顺手的做法是直接用你自己浏览器里现成的登录状态。可多数浏览器自动化工具偏偏做不到这一点：要么强制你新建账号、要么开一个和你无关的隔离实例，折腾半天还没法接入手头的 AI 助手。BrowserSkill解决的正是这件事——它把任意支持 shell 的 AI 助手（Cursor、Claude Code、Codex 等）和你真实、已登录的 Chromium 浏览器接在一起，让你以一句自然语言驱动AI 浏览器自动化：读页面、点按钮、填表单、整页长截图都能做，而且任务全程运行在独立、可见的 Agent Window 里，不打断你手头的浏览。
它由两部分组成：bsk命令行工具（内含后台守护进程）和浏览器扩展。下面按"先跑通、再补细节"的顺序带你上手。
最快配置方法：装 → 连 → 发一句话
环境就绪后，我们先用最短路径跑一次完整闭环，让你 5 分钟内看到效果。
第 1 步：安装 bsk 命令行工具。先把仓库克隆到本地（也可以用仓库自带的安装脚本直接装）：
# 克隆仓库到本地 git clone https://gitcode.com/GitHub_Trending/br/BrowserSkill cd BrowserSkill然后运行安装脚本（默认装到~/.local/bin）：
# 一键安装 bsk CLI（macOS / Linux） bash install.sh export PATH="$HOME/.local/bin:$PATH" bsk --version # 确认 CLI 可执行Windows 用户在 PowerShell 里执行.\install.ps1后同样用bsk --version验证。
第 2 步：安装浏览器扩展。在 Chrome 应用商店或 Edge 加载项里搜索BrowserSkill安装，点开扩展弹窗，启用本地连接，看到"已连接"状态即可。
第 3 步：教 AI 使用 bsk。执行下面命令，在交互菜单里用空格选中你的 AI 助手，回车确认：
# 把 browser-skill 技能安装到你的 AI 助手 bsk install-skill第 4 步：发一句自然语言任务。新开一个 AI 会话，直接说：
打开 example.com，总结页面内容，完成后结束会话
AI 会自动执行一串bsk命令：
bsk session start --json # 启动浏览器会话，返回 session id bsk navigate https://example.com --session <id> # 在 Agent Window 中打开网页 bsk observe --session <id> # 读取页面文本与控件，控件带 @eN 编号 bsk session stop <id> # 结束会话收到 AI 返回的页面总结时，🎉 你已经跑通了第一个 BrowserSkill 任务。下面回头把每一步验证清楚，方便以后排错。
环境检查清单：一键自检环境
跑通之后，用这张清单确认每个环节真的健康。每项给出「做什么 → 验证信号 → 没通过怎么办」：
| 做什么 | 验证信号 | 没通过怎么办 |
|---|---|---|
运行bsk --version | 终端输出版本号 | 说明 PATH 未生效：重开终端，或直接用~/.local/bin/bsk绝对路径验证 |
运行bsk doctor | 所有检查项均无fail，extension connected为已连接 | 每个fail项都会附带 hint，照提示修一次后重跑 |
| 点开扩展弹窗 | 显示"已连接"，且端口与本地 daemon 一致（默认 52800） | 端口不一致时在弹窗里改回默认端口并重新启用连接 |
运行bsk install-skill后重开 AI 会话 | AI 能发现并调用browser-skill技能 | 技能在会话启动时加载，重启会话再试；未列出的助手可把 crates/bsk-cli/skill/ 整目录复制为browser-skill/ |
| 发一句"打开 example.com 并总结" | AI 成功读页、给出总结并停掉会话 | 对照下方排错速查定位 |
💡 小提示：
bsk doctor只是自检的第一关，它不验证技能是否被 AI 助手真正加载。如果没通过——也就是 AI 仍然"听不懂"浏览器任务——重启一次会话，多数情况就能解决。
清单全绿之后，我们进入由浅入深的实战。
递进式实战：从读页到复合流程
任务一：读页总结（你已经会了）
- 指令："打开 https://example.com，总结这个页面的内容。"
- 底层命令：
session start→navigate→observe→session stop（见上文）。 - 关键点：
observe返回的页面文本里，每个可交互控件都会获得@eN编号，后续所有操作都引用这些编号。
任务二：交互操作（点击 + 截图）
- 指令："在 example.com 上点击 More information 链接，然后把整页截一张图存到 current.png。"
- 底层命令：
bsk observe --session <id> # 先读页面，拿到目标控件编号 bsk click @e3 --session <id> # 点击上一次 observe 给出的编号 bsk navigate --session <id> https://example.com/ # 若点击发生了跳转，回到原页 bsk observe --session <id> # 跳转后编号会失效，必须重新 observe bsk screenshot --session <id> --out current.png # 保存可见区域截图⚠️ 注意：
@eN编号只在最近一次observe中有效，导航或页面大改动后都会过期。如果点击后找不到编号，先重新observe一次，别硬套旧编号。
任务三：复合流程（登录态 + 表单 + 长截图）
- 指令："用我的浏览器打开内部门户，读今天的公告摘要，在反馈框里填一句'已读'并提交，最后给我整页长截图和文字摘要。"
- 底层命令：
bsk navigate https://intranet.example --session <id> # 复用你已登录的账号，无需重新登录 bsk observe --session <id> # 读取公告列表与反馈表单 bsk fill @e7 --value "已读" --session <id> # 填写反馈框 bsk click @e9 --session <id> # 提交 bsk screenshot --session <id> --full-page --out page.png # 整页长截图 bsk session stop <id> # 收尾并归还借用的标签页💡 小提示：
--full-page会跟随文档滚动区域自动截长图，嵌套滚动面板和虚拟列表有已知限制，细节见 docs/long-screenshot.md。如果截图明显缺失底部内容，把页面里的嵌套滚动区先手动滚到底再重试。
机制揭秘：为什么它不打断你
BrowserSkill 的核心是Agent Window：每个bsk session start都会开一个独立、可见的浏览器窗口，AI 的所有操作只发生在这个窗口里，你原本的标签页完全不受影响。Agent Window 共享你选定 profile 的登录状态——所以内部门户、邮箱这类已登录站点 AI 可以直接用；但它并不是独立账号或安全沙箱，AI 拥有的是当前登录网站的权限，所以只交给它你信任的任务。
如果 AI 确实需要碰你已经打开的标签页，必须走显式的"借用"流程，并且默认需要你确认：
bsk tab borrow <tab-id> --session <id> # 借用你的标签页（扩展 Automation settings 默认开启确认） bsk tab return <tab-id> --session <id> # 用完归还；session stop 时也会自动归还整条请求链路是这样的：
AI 助手 ──shell──▶ bsk CLI ──JSON Lines / Unix Socket──▶ bsk daemon ──WebSocket(默认 52800)──▶ 浏览器扩展 ──CDP──▶ Agent Windowdaemon 会对同一个会话的工具调用做串行排队，保证动作不互相踩。想深入实现细节，可以读 docs/architecture.md。
命令速查：意图 → 命令 → 说明
| 意图 | 命令 | 说明 |
|---|---|---|
| 读取页面文本与控件 | bsk observe --session <id> | 返回文本 +@eN编号，是交互前的第一步 |
| 整页长截图 | bsk screenshot --session <id> --full-page --out page.png | 自动滚动拼接长图，也可只截可见区域 |
| 点击元素 | bsk click @e3 --session <id> | @e3来自最近一次observe |
| 填写输入框 | bsk fill @e3 --value "text" --session <id> | 适合表单自动填写 |
| 下拉选择 | bsk select @e3 --value "option-value" --session <id> | 传 option 的 value，不是显示文案 |
| 滚动到元素 | bsk scroll-to @e3 --session <id> | 让元素进入视口 |
| 轮式滚动 | bsk wheel --delta-y 600 --session <id> | 模拟滚轮输入 |
| 借用 / 归还标签页 | bsk tab borrow <tab-id>/bsk tab return <tab-id> | 需扩展确认；stop 时自动归还 |
排错速查：症状 → 原因 → 处理
| 症状 | 常见原因 | 处理 |
|---|---|---|
bsk doctor报extension connected: fail | 扩展未连接，或弹窗端口与 daemon 不一致（默认 52800） | 打开扩展弹窗，核对端口后重新启用连接，再跑一次 doctor |
终端提示找不到bsk命令 | PATH 未生效，或已运行的 AI 会话还持有旧 PATH | 重开终端，或在当前会话里export PATH="$HOME/.local/bin:$PATH"；AI 会话重启后生效 |
| AI 助手找不到 browser-skill 技能 | 技能在会话启动时加载，新会话还没开 | 重启 AI 会话；用bsk install-skill --list确认装对了目标 |
点击/填写报找不到@eN编号 | 编号在导航或大 DOM 变化后已过期 | 重新observe拿新编号再操作，不要复用旧编号 |
| 沙箱环境里命令一结束 daemon 就没了 | 沙箱会清理后台子进程 | 按 docs/sandboxed-agents.md 在持久宿主里保留 daemon，并设BSK_AUTO_START=0 |
| 远程/服务器上的 AI 连不上本机浏览器 | 尚未配对或端口不通 | 按 docs/remote-extension-connection.md 走配对流程；注意远程模式暂不支持文件上传下载 |
延伸玩法与下一步
跑通第一个任务后，不妨试试这些更进阶的方向：
- 网站调试取证：让 AI 复现一个线上 bug 并导出请求、响应与 Console 证据，完整工作流见 docs/website-debugging.md
- 指定浏览器 profile / 绑定已有标签页：docs/browser-profiles.md、docs/tabs-and-profiles 参考
- 沙箱与远程部署（服务器跑 AI、本机留浏览器）：docs/sandboxed-agents.md、docs/remote-extension-connection.md
- 操作审计与隐私策略：docs/operation-audit.md、apps/extension/PRIVACY.md
- 架构与协议：docs/architecture.md、crates/bsk-protocol/
- 更完整的命令与工作流约定都在 crates/bsk-cli/skill/SKILL.md 里，AI 助手会照着它执行
跑通之后，不妨试试一句更野的："帮我打开常看的那几个站点，整理今天的最新动态并发我摘要"——BrowserSkill 的能力上限，远不止打开一个网页。
【免费下载链接】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），仅供参考
