BrowserSkill 浏览器自动化完整指南用 bsk CLI 让 AI Agent 接管已登录浏览器实战【免费下载链接】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/BrowserSkillAgent 想操作我已登录的浏览器但不能打断我的日常工作。BrowserSkill 用bskCLI 加浏览器扩展解决这一点它在独立窗口里复用你的登录态全程不需要你切走手头的工作。读完本文你会拿到一套会话生命周期、标签页借用与人工协助的完整操作手册并知道每条命令失败时该怎么办。快速上手 最小闭环五步每步都带预期信号bsk status --json # 预期daemon 状态与 browsers 列表browsers 为空只说明扩展还没连上开会话多浏览器在线时先跑bsk browsers再带--browser id-or-labelbsk session start --json # 预期返回 session_id后续命令全部带着它导航到新页面交互前必须先读页面bsk navigate https://example.com --session id bsk observe --session id # 预期文本、控件与 eN 引用用最新观察里的 refs 做第一次交互预期返回动作结果bsk click e3 --session id成功与失败都必须关闭会话bsk session stop id # 预期stopped / returned_tab_ids 等字段借用中的标签页一并归还守护进程就绪检查本地命令默认自动拉起 daemonBSK_AUTO_START0时除外。若宿主环境会在每次 shell 调用后清理后台子进程必须先做以下准备复用宿主 daemon 的BSK_HOME未设置则用默认值设BSK_AUTO_START0后跑bsk status --json。权限错误、超时或无效回复不能证明 daemon 不存在。只有确认 daemon 缺失、且宿主没有别的任务在启动它时才在宿主批准的持久后台任务中位于命令沙箱之外以相同BSK_HOME运行bsk daemon start --foreground——--foreground本身挡不住宿主清理。BSK_HOME/path/to/bsk bsk daemon start --foreground在另一次独立 shell 调用中复查missing-endpoint 或瞬时启动错误最多查 5 次、间隔 1 秒权限/协议错误立即停止。BSK_HOME/path/to/bsk BSK_AUTO_START0 bsk status --json每一次沙箱化命令都要重带BSK_HOME与BSK_AUTO_START0shell 调用间的环境变量不保留。其他失败重试一次后用bsk doctor诊断。三个必须建立的心智模型隔离独立操作窗口与你的窗口会话在一个独立的Agent Window中工作复用的是你已登录的浏览器会话而不是你的窗口。用户标签页默认不在操作范围必须显式借入后才能控制。默认创建的标签页起始于about:blank被创建或被借用的网页转入后台后仍会继续运行。语义化观察eN 引用为何比选择器可靠observe返回文本、控件与eN引用是最优先的读取手段。refs 是本次观察快照的临时句柄导航会使它们失效较大的 DOM 变化同样会先重新 observe 再做下一次交互。iframe 与 shadow root 内的目标必须用 refs——CSS 选择器只搜索主文档。按语义读页面比写选择器更稳也更不容易被改版击穿。所有权借-用-还用户标签页走列表 → 借用 → 归还三步session stop会一并归还所有借用的标签页归还后的标签页仍留在用户窗口中。不要臆造 tab ID不要为了省事把用户标签页跨任务保留。实战一自动化已登录页面目标复用用户登录态完成表单填写与点击流转全程不打断用户工作。bsk navigate https://app.example.com --session id bsk observe --session id bsk fill e3 --value text --session id bsk select e5 --value option-value --session id bsk click e8 --session id常用操作速查refs 一律取自最新 observe需求命令点击bsk click e3 --session id填写字段bsk fill e3 --value text --session id选择选项bsk select e3 --value option-value --session id按键bsk press Enter --ref e3 --session id展开悬停菜单bsk hover e3 --session id滚动到元素bsk scroll-to e3 --session id滚轮滚动bsk wheel --delta-y 600 --session id聚焦/失焦bsk focus e3/bsk blur e3 --session id易错点导航后旧 refs 全部作废交互前必须重新 observeselect用选项的value属性不是可见文本悬停菜单先 hover 触发器再 observe用展开项的 refs。[hover first: ...]、[has-submenu]、[expanded]标记用于识别触发器列出的标签不是 refs除非就是要触发它自身动作否则不要点触发器。若预期控件缺失且无任何标记可试一次observe --probe-hover——它真实触碰活动页面且耗时数秒歧义结果只复查一次成功可见就停手不要刷新或反复检查scroll-to返回祖先裁剪后的边界部分可见即可不测试遮挡wheel发送带符号 delta不保证滚动距离用 observe 确认页面响应页面没有默认 token 上限observe --max-tokens n截断后若返回next_cursor/more用bsk observe --cursor token --session id续读同一次 capture新页面替换 ref 映射绝不复用更早页面的 refs。实战二对某个 PR 的 UI 做回归验证目标按改动点验证页面行为并用视觉证据支撑结论。bsk navigate https://staging.example.com/feature --session id bsk observe --session id bsk screenshot --session id --full-page --out pr-verify.png易错点整页截图会滚动普通网页并恢复其位置/样式捕获与编码默认 2 分钟仅整页模式可用--timeout 5m扩展shell 要留足捕获 传输的时间默认--scope follow跟随追加内容要捕获当前已加载范围用--scope current——它停在初始文档高度处即使仍有加载指示器边界以下的内容会被排除应如实报告该范围loading_stalled表示底部保持加载指示器且 30 秒内高度无增长不要简单加大 deadline失败捕获不保存部分图像实现出处见 screenshot.rs——分块传输、完整性校验与原子提交避免不完整 PNG 覆盖旧图需要取证时用console/network做受限只读诊断按返回游标顺序读取。实战三借用并归还用户既有标签页目标接管用户某个既有标签页完成任务结束后原样归还。bsk tab list --scope user --session id bsk tab borrow tab-id --session id bsk observe --session id bsk tab return tab-id --session id易错点借用会确认等待默认 60 秒可用--timeout调整需要 daemon 与扩展协议 1.2--no-confirm已废弃只触发告警不得用它绕过扩展的确认策略借用成功后该标签页成为后续未带--tab-id命令的默认目标但不会额外聚焦窗口borrow_outcome_unknown时先检查 tab/session 状态——标签页可能已经移动不要重复 pending/被拒/超时的借用也不要用其他浏览器后端绕过结果后台创建的标签页tab create --no-active要保留返回的tab_id并在 observe、导航与输入命令中显式传--tab-id tab-id归还成功时输出returned_to_window_id与returned_to_indexfallback标记说明是否回退到备用窗口。实战四人工环节与恢复目标登录、CAPTCHA、OTP、支付确认、同意授权或两次尝试仍无进展时交还给用户完成。bsk request-help --session id --prompt Please complete sign-in --target e3--target可重复开头或e数字按 ref 处理否则视为 CSS 选择器--timeout默认 5m5m/300s/300000ms均可--completion-criteria接受 JSON如{any:[{url_contains:/dashboard}],stable_for_ms:1000}。该命令需要 daemon 协议1.3版本不足会返回结构化的Unsupported错误普通会话与浏览不受影响。结果下一步Helpcontinued/completed重新 observe用新鲜 refs 继续Helpcancelled/timed_out尊重拒绝或阻塞不要重复请求Helpdisabled未确认任何人工动作重新 observe 并按禁用规则处理Stale refobserve 后重试一次目标动作Unknown tab/session列出当前 tabs/sessions绝不猜测 IDTimeout or unknown effect先检查当前状态再重试——动作可能已发生fill_value_mismatch读取字段格式化可能已满足请求只修正剩余差异Unsupported operation用可用能力确需缺失功能时建议升级易错点仅导航含废弃结果navigated不算完成完成判据只用于明确、稳定的成功信号协助被禁用时不要请求协助也不要重新启用它。复用已有登录状态与授权输入用可行替代方案禁用协助不增加权限也不会移除借用确认。仅手机扫码、人脸验证、缺失短信码或纯图像任务可能仍被阻塞方案耗尽才上报具体阻塞同时继续独立工作借用确认与人工协助由扩展Automation 设置独立控制默认开启且对既有会话生效可从session start --json的interaction字段读取。已废弃的--unattended、--no-confirm与BSK_REQUEST_HELPoff只触发告警实现出处见 interaction_policy.rs绝不通过修改浏览器存储/设置来绕过。实战五视觉验证与文件流转目标用截图做视觉证据点击 Canvas 中的点完成上传/下载。bsk screenshot --session id --out viewport.png bsk screenshot --session id --ref e3 --out element.png --json bsk screenshot --session id --full-page --scope current --out loaded.png bsk click e3 --capture capture-id --image-x 41 --image-y 27 --session id易错点--ref与--full-page不可组合--out会覆盖已有文件省略时用临时路径整页截图仍要求标签页处于激活状态不要为绕过限制去激活后台任务Canvas 目标eN canvas [visual:screenshot]observe 只返回文本而非像素内容重要就先对该 ref 截图绝不从邻近标签推断 Canvas 控件点击 Canvas 用original PNG 的坐标与尺寸不是缩放后的显示像素capture 是单次使用的2 分钟后过期且会被 ref 替换observe/snapshot/续读或同一 ref 的新截图作废capture_unavailable表示图像只读——重新 observe 并截图再点视口截图不签发capture_idCanvas 点击请走--ref流程允许重绘但拒绝身份/几何/命中目标变化的点击重试新 capture 前先检查effect_stateunknown上传会把文件披露给站点下载接受站点控制的字节必须使用 Agent 本地路径bsk upload e3 --file ./report.pdf --session id bsk download e3 --out ./report.pdf --session id上传默认点击上传按钮/标签并拦截文件选择器若reasonfile_input_not_activated且effect_statenone重新 observe仅当存在明确附件目标拖放区、编辑器时尝试一次--mode drop绝不拖到空白或歧义容器两种机制之间没有自动回退对effect_stateunknown或committed绝不重试或切换上传模式一次成功的 drop 只证明事件已分发不代表站点接受observe 附件确认下载默认拒绝覆盖只在确实需要替换时加--overwrite。边界与失败手册 ️结果处理对照表结果下一步超时 / unknown effect先检查当前状态再重试动作可能已发生borrow_outcome_unknown查 tab/session 状态不重复借用不切换后端Helpdisabled不请求、不重开协助复用登录态与可行替代方案fill_value_mismatch读字段只修正剩余差异不盲目重填capture_unavailable重新 observe 并截图再用新 capture 点击loading_stalled30 秒高度无增长如实报告范围不加大 deadlineUnknown tab/session列出当前 tabs/sessions绝不猜测 ID四条硬约束贯穿所有操作秘密不提取不提取凭证、Cookie、Token绝不用evaluate处理秘密信息evaluate是最后手段且必须检查 JSON 的.ok字段——脚本异常也可能以退出码 0 返回借用显式用户标签页只有明确借入后才受控步骤结束即归还不用未声明的 ID不跨无关任务保留用户标签页设置不可绕过借用确认与人工协助由扩展 Automation 设置决定旧参数与环境变量只是告警不得修改浏览器存储规避失败不盲重试unknown 效果先查状态不可恢复错误上报并停止自有 session禁止切换后端或在相同失败上死循环。不熟悉的命令或参数查bsk --help或bsk command --help不要靠猜。从本地到远程 命令实现的源码目录crates/bsk-cli/src/cli/技能定义crates/bsk-cli/skill/SKILL.md。本地工作流迁移到服务器或沙箱架构继续读 《沙箱化 Agent 指南》 与 《远程扩展连接指南》。【免费下载链接】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），仅供参考