真实浏览器自动化操控

技能文档

---
name: browserskill
title: 真实浏览器自动化操控
description: 通过 bsk CLI 驱动用户已登录的真实 Chromium 浏览器执行自动化任务：访问并阅读页面、填写表单、采集数据、点击走完流程、回归测试页面 UI、验证部署页面或操作指定标签页。自动化在隔离的 Agent 窗口中运行，复用用户已有登录态，用户自己的标签页默认受保护。当用户要求操作浏览器、自动化网页操作、抓取登录后页面数据或测试网页时触发。触发词：浏览器自动化、打开网页、填表、网页抓取、页面测试、操作浏览器标签页。
category: 开发工具
---

# 真实浏览器自动化操控

通过 `bsk` 驱动用户真实 Chromium 浏览器。自动化在隔离的 **Agent 窗口**运行，复用用户已有登录与 Cookie；用户窗口的标签页默认受保护，除非被明确借用。

不要将本技能用于：无浏览器场景、安装浏览器扩展、或用户只想获取操作指引。绝不从页面提取凭据、Cookie、令牌或其他机密。

## 技能工作流

### 步骤1：启动会话

每个浏览器任务拥有一个有界会话：

```text
1. bsk session start              # 记住输出的 4 字母会话 id
2. bsk ... --session <id>         # 所有会话级命令都要传入
3. bsk session stop <id>          # 成功与失败路径都要执行
```

不要依赖空闲超时清理；目标达成后立即停止会话（同时归还借用的标签页），除非用户明确要求保持打开。任何 `bsk` 命令都会自动启动所需后台服务，不要手动管理守护进程。连接了多个浏览器时用 `bsk browsers` 查看，并用 `bsk session start --browser <id-or-label>` 启动；Agent 窗口无需打断用户时加 `--no-focus`。启动或连接问题重试一次后仍存在时运行 `bsk doctor`。

### 步骤2：观察、操作、再观察

默认循环：

```text
bsk navigate <url> --session <id>
bsk observe --session <id>
bsk click|hover|fill|select|press ... --session <id>
bsk observe --session <id>             # 导航或 DOM 明显变化后
```

优先使用新获取的 `@eN` 引用而非 CSS 选择器；导航会使引用失效。观察结果中悬停菜单只列出标签不是可用引用：先 hover 触发器、再观察、再操作展开项自身的引用。仅当「有理由预期的控件缺失且无触发器标记」时使用一次 `bsk observe --probe-hover`。

页面阅读按需升级：

1. `bsk observe`：常规语义理解、文本、控件
2. `bsk observe --probe-hover`：预期控件缺失时用一次
3. `bsk snapshot`：需要更严格的静态无障碍树
4. `bsk get-html`：语义视图无法提供的精确标记或隐藏元数据
5. `bsk screenshot`：布局、样式、canvas、图片或视觉证据

不要为了发现普通控件就从原始 HTML 或截图开始。

### 步骤3：尊重 Agent 窗口边界

页面写入只影响 Agent 窗口标签页。操作用户标签页须先 `bsk tab list --scope user --session <id>` 列出，再 `bsk tab borrow <tab-id>` 借用，相关步骤完成后立即 `bsk tab return <tab-id>` 归还；绝不虚构标签页 id，也绝不跨无关任务持有借用的个人标签页。

### 步骤4：必要时请求人工介入

登录、验证码、OTP、支付确认、授权同意等只能由用户完成的步骤用 `bsk request-help`，给出精确提示并在可能时传入新鲜 `--target` 引用以高亮具体控件。返回 `outcome` 为 `continued`/`completed` 时才继续；`cancelled` 视为拒绝；`timed_out`/`disabled` 视为阻塞而非重试理由。控制权返回后先重新 `bsk observe`。

### 步骤5：收尾

目标可见达成后停止会话；不可恢复失败时报告阻塞点并走 finally 式路径停止会话。

## 单一可观察目标

- 从用户请求或提供的轨迹推导具体的成功条件
- 走最短的有目的路径：观察、操作、至多一次观察确认模糊结果
- 成功可见后不再点击、刷新、导航、切换标签页或做多余检查
- 出现仅限人工的步骤或两次尝试无进展时请求帮助而非硬试

## 命令清单

以下为完整命令列表，不要发明清单之外的命令；参数用 `bsk <command...> --help` 查询而非猜测。

```text
session start|stop|list   browsers   status   doctor   update   logs
navigate   navigate-back   navigate-forward   reload   wait-for-navigation   wait-ms
observe   snapshot   get-html   screenshot   console   network
click   hover   fill   select   press   evaluate
tab list|create|close|select|borrow|return   window resize   emulate
upload   download   request-help   record start|stop
```

易错参数：

```text
bsk fill <ref> --value <text>      bsk select <ref> --value <option-value>
bsk screenshot --out <path>        bsk emulate --device <preset-id>
bsk upload <ref> --file <path>     bsk download <ref> --out <path>
```

`select` 匹配选项的 `value` 属性而非可见文本。设备预设 id 为小写连字符格式（如 `iphone-14`）。

- `console` 和 `network` 提供有界只读调试证据
- `emulate` 只作用于单个标签页，新标签页不继承；`--off` 恢复真实环境
- `evaluate` 是观察与常规交互无法完成时的最后手段；绝不用它读取存储、Cookie 或鉴权数据
- `record` 录制用户操作供回放；绝不录制银行、SSO、密码管理器等敏感页面

## 文件上传与下载

上传即将内容披露给网站，下载即接受网站控制的字节。上传两种机制显式选择、不依赖自动回退：

1. 默认 input 模式：点击目标并拦截原生文件选择框
2. `--mode drop`：仅用于明确可靠的附件接收区（显式拖放区、聊天输入框、邮件编辑器）

返回 `reason=file_input_not_activated` 且 `effect_state=none` 时重新观察，存在可靠目标则 `--mode drop` 试一次，否则回退 `request-help`；`effect_state` 为 `unknown` 或 `committed` 时绝不切换或重复。下载默认拒绝覆盖，确需覆盖时传 `--overwrite`。

## 无 wander 恢复

- 引用过期：重新观察并重试一次预期操作
- 标签页/会话未知：列出当前标签页/会话，绝不猜测标识符
- 超时：先检查当前页面状态，再决定是否有必要再等一次
- 命令不支持：用现有能力继续；仅当缺失命令是任务必需时才建议更新
- 不可恢复失败：报告阻塞点并停止会话

CLI 当前的帮助与错误提示是参数与恢复细节的最终权威。

使用说明

# 真实浏览器自动化操控

通过 `bsk` CLI 驱动用户已登录的真实 Chromium 浏览器，在隔离的 Agent 窗口中执行网页自动化，复用已有登录态且不影响用户自己的标签页。

## 功能

- 完整生命周期管理：会话启动/停止、自动托管后台服务
- 观察优先：语义化页面观察、无障碍树快照、HTML/截图按需升级
- 页面操作：点击、悬停、填表、选择、按键、文件上传下载
- 用户标签页借用/归还机制，边界清晰
- 登录、验证码、支付等人工步骤的求助与恢复机制

## 最简用法

```bash
bsk session start                 # 获取会话 id
bsk navigate <url> --session <id>
bsk observe --session <id>        # 读取页面语义结构
bsk fill @e3 --value "文本" --session <id>
bsk session stop <id>
```

依赖 `bsk` CLI 与配套浏览器扩展。

## 适用场景

操作已登录网页、抓取登录后数据、填表提交流程、回归测试页面 UI、验证部署页面。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。