BrowserSkill browser-skill 实战指南bsk CLI 驱动登录态浏览器无需打断你的工作完成自动化任务【免费下载链接】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/BrowserSkillBrowserSkill 把bskCLI 和浏览器扩展组合成一套 AI Agent 浏览器扩展自动化方案Agent 在你已登录的 Chromium 里读页面、填表单、点按钮、存文件全部动作都收进一个独立的 Agent Window——一个专门给 Agent 用的浏览器窗口不碰你正在看的标签页。跑起来之前daemon 就绪检查与环境分支处理本地命令执行时会先探测 IPC 端点daemon 在线就直接复用离线且BSK_AUTO_START未设为0时才自动 spawn。但宿主环境若会在每次 shell 调用结束后清掉后台子进程Windows 上很常见就得手动保证 daemon 存活。⚡ 关键动作只有一个复用宿主 daemon 的BSK_HOME未设置就用默认值设BSK_AUTO_START0后跑bsk status --json然后根据返回信号走分支——观察到的信号判定处置status 正常返回browsers列表为空daemon 活着扩展还没连上等扩展连接或bsk doctor排查检查明确报告 endpoint 缺失且没有其他任务在启动 daemondaemon 确实不在在宿主批准的持久后台任务里命令沙箱之外用同样的BSK_HOME跑bsk daemon start --foreground并保持该任务存活——--foreground本身挡不住宿主清理权限错误 / 超时 / 无效回复不能证明 daemon 缺失别据此下结论先看bsk logs再复查 status宿主任务退出含锁错误或始终未就绪启动失败查看其输出与bsk logs先确认是否已有别的 daemon再决定要不要启动启动等待期间对 missing-endpoint 或瞬时错误最多做 5 次、间隔 1 秒的检查遇到权限/协议错误立即停。拿到成功响应前不要继续。每一条沙箱命令都要带上相同的BSK_HOME和BSK_AUTO_START0shell 调用之间的环境变量不会自动保留。未解决的错误上报即可不要反复循环启动、删运行时文件或重启共享 daemon。daemon 就绪检查的自动 spawn 逻辑可在 ensure_daemon.rs 里看到完整的探测与截止时间控制。远程部署或沙箱宿主只需一句话Agent 跑在服务器上、扩展从用户电脑发起出站连接即可流程完全不变细节见远程扩展连接指南和沙箱化 Agent 指南。端到端操作闭环一次完整任务从开轮到标签页归还把一次任务当成一条流水线从用户请求里定义成功标准 → 开轮 → 读页 → 用 refs 动手 → 关轮。bsk session start --json返回的session_id必须存下来后面所有会话命令都靠它多个浏览器在线时先bsk browsers列出实例再用--browser id-or-label指定纯后台干活就只在session start上加--no-focus。新页面走navigate交互前必须先observe把页面读进来。之后每选一个动作都用最新观察返回的eNrefs导航或 DOM 发生有意义变化后refs 就作废重新 observe 再动手。结果含糊时最多复查一次一旦成功信号可见就收手别刷新、别反复确认。⚠️ 无论成功还是失败都要执行bsk session stop id除非保持会话打开本身就是需求——停止会话会一并归还所有借来的标签页归还后的标签页原样留在用户窗口里。不要指望空闲清理来兜底也不要为了收尾去停/重启共享 daemon。bsk session start --json # 记下返回的 session_id bsk navigate https://example.com --session id bsk observe --session id # 拿到 eN refs bsk fill e3 --value hello --session id bsk observe --session id # DOM 变化后刷新 refs bsk session stop id # 成功或失败都要执行对不熟悉的命令或参数查bsk --help或bsk command... --help不要猜。跟着 trace 复现时按语义目标和取值依次执行而不是复用旧的 refs达到目标即停——trace 本身不授予额外授权。能力矩阵bsk observe eN refs 与读取、交互、视觉、文件四层分工读取层。observe是默认首选返回文本、控件和eNrefsiframe/shadow-root 里的目标只能靠 refsCSS 选择器只搜主文档。分工上snapshot给你静态可访问性树get-html给你精确标记或隐藏元数据——为找普通控件就一上来抓 HTML 是本末倒置按 HTML/截图发现找到的控件动手前也得先取新鲜 refs。页面很长时用--max-tokens n设软上限约 4 字符/token返回next_cursor/more就续读bsk observe --cursor token --session id。续读读的是同一次 capture不刷新、不 hover但每个页面都会替换 ref 映射绝不复用更早页面的 refs任何新 observe/snapshot 或页面身份变化都会使 cursor 失效只能重新 observe。参数互斥关系--cursor与--max-depth/--probe-hover/--debug-surfaces冲突写在 observe.rs 的参数定义里。交互层。全部以 ref 为靶需求命令点击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 --session id/bsk blur e3 --session id两个易踩的点select认选项的value属性而非可见文本悬停标记[hover first: …]、[has-submenu]、[expanded]是识别菜单触发器的线索——先 hover 触发器再 observe用展开项的 ref别直接点触发器除非就是要触发它列出的标签也不是 refs。控件确实缺失且无标记时可试一次--probe-hover它真实触碰页面、耗时数秒。scroll-to返回顶层视口 CSS 像素下被祖先裁剪后的边界部分可见即可但完全不测遮挡wheel只发带符号 delta不保证滚动距离用 observe 确认页面响应。视觉层。截图返回本地 PNG 路径需要看图说话--out会覆盖已有文件省略则落到临时路径--ref与--full-page互斥。bsk screenshot --session id --out viewport.png bsk screenshot --session id --ref e3 --out element.png --json bsk screenshot --session id --full-page --out page.png bsk screenshot --session id --full-page --scope current --out loaded.png整页模式会滚动普通网页再拼回并恢复位置/样式默认--scope follow跟随追加内容--scope current停在初始文档高度——即使底部还有加载指示器边界以下内容被排除汇报时要如实说清范围别声称整条 feed 都加载了。捕获/编码默认 2m仅整页模式可用--timeout 5m延长loading_stalled表示底部卡着加载器且 30s 高度零增长别靠加大 deadline 硬扛。受控标签页的视口截图在后台也能工作需显式--tab-id整页截图则要求标签页处于激活状态。 对eN canvas [visual:screenshot]这类目标observe 只给文本不给像素——内容重要就对该 ref 截图要点击画布里看到的点保留该截图的capture_id再用bsk click e3 --capture id --image-x x --image-y y点击坐标必须是原始 PNG的像素而非缩放显示值capture 单次使用、2m 过期且会被新 observe/snapshot/续读或同一 ref 的新截图作废。canvas 没有 DOM 语义填写、IME、拖拽、hover、HTML 提取统统不可用capture_unavailable表示图像只读重新 observe 再截图重试前先看effect_stateunknown。整页分块传输与原子写入的细节见 screenshot.rs。文件层。bsk upload e3 --file ./report.pdf --session id会把文件披露给站点bsk download e3 --out ./report.pdf --session id则是接受站点控制的字节路径都用 Agent 本地路径。上传默认点击上传按钮并拦截文件选择器若返回reasonfile_input_not_activated且effect_statenone重新 observe仅当存在明确附件目标拖放区、编辑器时才试一次--mode drop绝不拖到空白处或歧义容器两种机制之间没有自动回退。对effect_stateunknown或committed绝不重试、绝不切换模式——observe 附件确认才算数。下载默认拒绝覆盖确需替换才加--overwrite。borrow-return 所有权协议Agent Window 标签页借用确认与超时处置核心规则一句话用户标签页的默认状态是不可控只有显式bsk tab borrow tab-id --session id之后才进入 Agent 的可控范围相关步骤一结束就bsk tab return tab-id --session id归还。bsk tab list --scope user --session id先列出候选--scope支持user/agent/all默认all。借用会在 Agent Window 内选中被借标签页使其成为后续未带--tab-id命令的默认目标但不会额外聚焦窗口。对后台创建的标签页tab create --no-active保留返回的tab_id并在 observe、导航与输入命令里显式传--tab-id tab-id——被创建和被借用的网页转后台后依然继续运行别假设它睡着了。默认创建的标签页起始于about:blank。反例清单这些都会破坏所有权边界臆造 tab ID或在无关任务之间保留用户标签页重复已经 pending、被拒绝或超时的借用请求对borrow_outcome_unknown用其他浏览器后端绕过结果——标签页可能已经移动先查 tab/session 状态为了跳过确认去改浏览器存储或扩展设置。借用结果处置pending确认等待中等结果不重复发起rejected用户拒绝尊重拒绝换方案或走人工协助timed_out确认超时不重复请求按阻塞处理borrow_outcome_unknown先查 tab/session 状态再决定标签页可能已移动tab borrow --timeout 120s只改变确认等待时长默认 60s自定义等待需要 daemon 与扩展协议 1.2。借用确认由扩展保存的 Automation 设置独立控制对既有会话同样生效需要时可从session start --json或session list --json的interaction字段读取。借用的 IPC 超时构成、归还成功时打印的returned_to_window_id/returned_to_index与fallback标记都能在 tab.rs 的借用参数与结果渲染里对照。request-help 人工协助结果分支速查与失败降级策略启用协助的前提下遇到登录、CAPTCHA、OTP、支付确认、同意授权或者同一件事尝试两次毫无进展就交给真人bsk request-help --session id --prompt Please complete sign-in --target e3prompt 写精确--target用新鲜目标值以开头或形如e数字按 ref 解析否则视为 CSS 选择器没有合适控件就省略--completion-criteria接受 JSON如{any:[{url_contains:/dashboard}],stable_for_ms:1000}只配明确、稳定的成功信号--timeout默认 5m。调用前会做 daemon 协议 1.3 检查不满足时返回结构化Unsupported错误并明确普通会话与浏览仍可用。结果下一步continued/completed重新 observe用新鲜 refs 继续cancelled/timed_out尊重拒绝或阻塞不重复请求disabled没人确认过任何人工动作重新 observe按下方禁用规则降级Stale refobserve 后把目标动作重试一次Unknown tab/session列出当前 tabs/sessions绝不猜 ID、不串用别的任务的 sessionTimeout / unknown effect先检查当前状态再重试——动作可能已经发生fill_value_mismatch读一下字段格式化可能已满足请求只修正剩余差异不盲目重填Unsupported operation用现有能力仅当确实需要缺失功能才建议升级记牢两条仅导航含已废弃的结果navigated不算完成 同一个失败上不死循环、不重复 unknown 效果、不切换后端绕限制。Help disabled 时的降级路径是不请求协助、也不去重新启用复用已有登录状态、被授权的输入与可行替代方案——禁用协助不会增加权限也不会移除借用确认或宿主限制。授权范围内有视觉能力的模型可以试图形化校验仅限手机扫码、人脸验证、缺失短信码或纯图像任务对纯文本模型可能仍被阻塞。只有输入/能力缺失或可行方案耗尽时才上报具体阻塞并继续独立工作不可恢复的失败上报后停掉自己拥有的 session。实现细节参数解析、ref/selector 判别、协议检查见 human_loop.rs。安全不变量清单登录态浏览器自动化不能碰的五条底线秘密不可触碰不提取凭证、Cookie、Token不用evaluate处理秘密信息。为什么这套工具跑在用户真实的登录 profile 上任何一次提取都是直接的数据泄漏。借用必须显式用户标签页只有明确 borrow 后才受控步骤结束即 return绝不用未声明的 ID 或跨任务保留借来的标签页。为什么Agent Window 隔离与借还协议是用户浏览器主权的最小保障破坏它等于替用户做了没被授权的决定。设置不可绕过--unattended、--no-confirm、BSK_REQUEST_HELPoff已废弃只触发告警、不再改变策略更不许改浏览器存储来规避。为什么借用确认与人工协助由扩展 Automation 设置裁决CLI 侧保留旧参数只为兼容解析。失败不盲重试effect_stateunknown先查状态再决定不可恢复错误上报并停止自有 session禁止死循环、重复未知效果或切换后端。为什么动作可能已经发生二次触发比漏触发更危险。Canvas 与 evaluate 有边界Canvas 点击只认原图坐标 单次capture_id重绘导致的身份/几何变化必须拒绝evaluate是最后手段且必须检查 JSON 的.ok字段——脚本异常也会以退出码 0 返回。为什么canvas 无 DOM 语义可校验脚本通道的错误也不会体现在进程退出码上。这些约束在源码里不是文档口号协议版本不足时require_help_support等检查返回结构化Unsupported而非静默降级旧参数只经过warn_legacy_override打一条警告见 interaction_policy.rs。进阶远程部署与沙箱环境的迁移路径把整套流程搬到服务器并不复杂Agent 跑在远端扩展在用户电脑上发起出站连接无需开放入站端口任务照旧使用独立 Agent Window 与借还协议唯一的变化是配对与网络配置。 沙箱宿主的关键差异只有 daemon 生命周期——按前文的判定表把bsk daemon start --foreground放进宿主批准的持久后台任务之后每条命令保持相同的BSK_HOME与BSK_AUTO_START0。其余能力observe、borrow、request-help、截图、文件流转全部原样可用约束边界也原样生效。完整配对步骤见远程扩展连接指南宿主终端替代方案与 PowerShell 示例见沙箱化 Agent 指南技能全文以 SKILL.md 为准。【免费下载链接】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），仅供参考