企业官网建设流程全解析

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/BrowserSkill

Agent 想操作我已登录的浏览器，但不能打断我的日常工作。BrowserSkill 用bskCLI 加浏览器扩展解决这一点：它在独立窗口里复用你的登录态，全程不需要你切走手头的工作。读完本文，你会拿到一套会话生命周期、标签页借用与人工协助的完整操作手册，并知道每条命令失败时该怎么办。

快速上手 🚀

最小闭环五步，每步都带预期信号：

bsk status --json # 预期：daemon 状态与 browsers 列表；browsers 为空只说明扩展还没连上

1. 开会话，多浏览器在线时先跑bsk browsers再带--browser <id-or-label>：

bsk session start --json # 预期：返回 session_id，后续命令全部带着它

2. 导航到新页面，交互前必须先读页面：

bsk navigate https://example.com --session <id> bsk observe --session <id> # 预期：文本、控件与 @eN 引用

3. 用最新观察里的 refs 做第一次交互，预期返回动作结果；

bsk click @e3 --session <id>

4. 成功与失败都必须关闭会话：

bsk session stop <id> # 预期：stopped / returned_tab_ids 等字段，借用中的标签页一并归还

守护进程就绪检查

本地命令默认自动拉起 daemon（BSK_AUTO_START=0时除外）。若宿主环境会在每次 shell 调用后清理后台子进程，必须先做以下准备：

1. 复用宿主 daemon 的BSK_HOME（未设置则用默认值），设BSK_AUTO_START=0后跑bsk status --json。权限错误、超时或无效回复不能证明 daemon 不存在。
2. 只有确认 daemon 缺失、且宿主没有别的任务在启动它时，才在宿主批准的持久后台任务中（位于命令沙箱之外）以相同BSK_HOME运行bsk daemon start --foreground——--foreground本身挡不住宿主清理。

BSK_HOME=/path/to/bsk bsk daemon start --foreground

3. 在另一次独立 shell 调用中复查：missing-endpoint 或瞬时启动错误最多查 5 次、间隔 1 秒；权限/协议错误立即停止。

BSK_HOME=/path/to/bsk BSK_AUTO_START=0 bsk status --json

每一次沙箱化命令都要重带BSK_HOME与BSK_AUTO_START=0，shell 调用间的环境变量不保留。其他失败重试一次后用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）：

易错点：

• 导航后旧 refs 全部作废，交互前必须重新 observe；
• select用选项的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_index；fallback标记说明是否回退到备用窗口。

实战四：人工环节与恢复

目标：登录、CAPTCHA、OTP、支付确认、同意授权，或两次尝试仍无进展时，交还给用户完成。

bsk request-help --session <id> --prompt "Please complete sign-in" --target @e3

--target可重复，@开头或e<数字>按 ref 处理，否则视为 CSS 选择器；--timeout默认 5m（5m/300s/300000ms均可）；--completion-criteria接受 JSON，如{"any":[{"url_contains":"/dashboard"}],"stable_for_ms":1000}。该命令需要 daemon 协议1.3，版本不足会返回结构化的Unsupported错误，普通会话与浏览不受影响。

易错点：

• 仅导航（含废弃结果navigated）不算完成；完成判据只用于明确、稳定的成功信号；
• 协助被禁用时：不要请求协助也不要重新启用它。复用已有登录状态与授权输入，用可行替代方案；禁用协助不增加权限，也不会移除借用确认。仅手机扫码、人脸验证、缺失短信码或纯图像任务可能仍被阻塞；方案耗尽才上报具体阻塞，同时继续独立工作；
• 借用确认与人工协助由扩展Automation 设置独立控制，默认开启且对既有会话生效，可从session start --json的interaction字段读取。已废弃的--unattended、--no-confirm与BSK_REQUEST_HELP=off只触发告警（实现出处见 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_id，Canvas 点击请走--ref流程；允许重绘，但拒绝身份/几何/命中目标变化的点击；重试新 capture 前先检查effect_state=unknown；
• 上传会把文件披露给站点，下载接受站点控制的字节，必须使用 Agent 本地路径：

bsk upload @e3 --file ./report.pdf --session <id> bsk download @e3 --out ./report.pdf --session <id>

• 上传默认点击上传按钮/标签并拦截文件选择器；若reason=file_input_not_activated且effect_state=none，重新 observe，仅当存在明确附件目标（拖放区、编辑器）时尝试一次--mode drop，绝不拖到空白或歧义容器；两种机制之间没有自动回退；
• 对effect_state=unknown或committed绝不重试或切换上传模式；一次成功的 drop 只证明事件已分发，不代表站点接受，observe 附件确认；
• 下载默认拒绝覆盖，只在确实需要替换时加--overwrite。

边界与失败手册 🛡️

结果处理对照表：

四条硬约束，贯穿所有操作：

1. 秘密不提取：不提取凭证、Cookie、Token，绝不用evaluate处理秘密信息（evaluate是最后手段，且必须检查 JSON 的.ok字段——脚本异常也可能以退出码 0 返回）；
2. 借用显式：用户标签页只有明确借入后才受控，步骤结束即归还；不用未声明的 ID，不跨无关任务保留用户标签页；
3. 设置不可绕过：借用确认与人工协助由扩展 Automation 设置决定，旧参数与环境变量只是告警，不得修改浏览器存储规避；
4. 失败不盲重试：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