BrowserSkill — 驱动本机浏览器的技能

通过已安装的 bsk CLI（腾讯 BrowserSkill）操作本机 Chrome 浏览器。无需 CDP、无需自建桥接，扩展已装、daemon 常驻。

前置条件检查（每次调用前快速确认）

1. daemon 是否在运行：

   $bsk = "$env:USERPROFILE\.local\bin\bsk.exe"
   & $bsk status

   • 输出应含 browsers connected 1。若无，先 & $bsk daemon start 并等待 5 秒。
2. 浏览器是否连接：& $bsk browsers 应列出 chrome 实例。
3. 若无 session：& $bsk session start --json 创建（可能需等 30~90 秒，因为扩展 Service Worker 周期唤醒；用后台 job 等待再取结果）。

核心工作流

1. 创建/复用 session（Agent Window）

$s = & $bsk session start --json    # 返回 {session_id, agent_window_id}
$sid = ($s | ConvertFrom-Json).session_id

⚠️ 若命令长时间无输出：SW 休眠导致 RPC 未达扩展。用 Start-Job 后台运行 + Start-Sleep 30~90 秒再 Receive-Job 取结果，这是已知时序问题，不是故障。

2. 导航到 URL

& $bsk navigate --session $sid "https://example.com"
# 输出: tab=<id> reached=load url=...

3. 读取页面内容（快照）

& $bsk snapshot --session $sid --json
# 返回 aria 语义快照: @e1 button "xxx"、StaticText 值、table 行列
# 元素用 @eN 引用，供后续 click/fill 使用

4. 交互操作

& $bsk click  --session $sid @e5          # 点击 @e5
& $bsk fill   --session $sid @e12 "text"  # 填输入框
& $bsk press  --session $sid Enter        # 按键
& $bsk select --session $sid @e18 "value" # 下拉选择
& $bsk screenshot --session $sid          # 截图（默认保存 PNG）
& $bsk get-html --session $sid            # 原始 HTML
& $bsk observe --session $sid             # 语义观察

5. 标签页管理

& $bsk tab list --session $sid            # 列出所有标签页（含 user 作用域）
& $bsk tab select --session $sid <id>     # 聚焦标签页
& $bsk tab borrow --session $sid <id>     # 借用用户标签页
& $bsk tab return --session $sid <id>     # 归还

6. 结束会话

& $bsk session stop $sid      # 停止单个 session（SESSION_ID 是位置参数）
& $bsk session stop --all     # 停止全部

关键注意事项

• 路径：bsk 在 C:\Users\Administrator\.local\bin\bsk.exe，已加入 PATH，但脚本里用完整变量更稳。
• 时序：SW 每 ~30 秒唤醒（bh-keepalive），RPC 若赶上休眠会卡住。任何命令超过 15 秒无响应，改用后台 job + 等待，不要重复前台重试。
• daemon 保活：daemon 可能被会话回收，操作前先 status 确认，必要时重启动。
• 编码：PowerShell 5.1 控制台是 GBK，中文会乱码。读页面内容时设置 [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 或把结果写文件再用 UTF-8 读。
• 安全：bsk 操作的是您已登录的真实浏览器，点击/填写是真实操作。涉及提交、付款、删除等高风险动作前，先向用户确认。
• screenshot 输出：默认保存到当前目录或指定路径，注意收集文件位置给用户。
• session 列表：& $bsk session list 查看活跃 session；daemon 重启后 session 失效需重建。

失败排查

• requested resource does not exist / session not registered：session 已失效（daemon 重启），重建 session。
• waiting for browser extension to connect：扩展 SW 休眠，等待 30~90 秒重试。
• error: unexpected argument：参数格式错，用 & $bsk <cmd> --help 查用法。
• 中文字符乱码：非数据损坏，是控制台编码，用文件+UTF-8 读取解决。