# Browser Use

> 统一处理浏览器使用任务，支持可见浏览器 CDP 直连、专用 headless CDP、agent-browser。Use when the user asks to browse websites, interact with pages, fill forms, capture screenshots, reuse an existing Chrome/Chromium/Edge login session, work with an already-open browser/sidebar browser, access login-only/internal/dynamic pages, or automate browser actions.

- Skill: `agentflocks/browser-use` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add agentflocks/browser-use`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agentflocks/browser-use/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: agentflocks (https://skillmd.com/u/agentflocks)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/agentflocks/browser-use

---


# Browser Use

## 适用范围

当任务需要真实浏览器环境时使用本 skill，包括：

- 打开网页、浏览页面、点击按钮、填写表单
- 截图、抓取页面内容、提取链接或媒体资源
- 访问登录后页面、内部系统、动态渲染页面
- 复用用户当前浏览器的登录态

## 浏览器使用模式说明

| 模式 | 说明 | 何时使用 |
| --- | --- | --- |
| `agent-browser` | 独立浏览器自动化模式 | 用户明确说用 `agent-browser`|
| `cdp-direct` | 复用本机 Chromium 系浏览器的 CDP 直连模式 | 用户明确说用 CDP 模式|
| `cdp-headless` | 通过 `BU_CDP_WS` / `BU_CDP_URL` 连接独立 headless Chromium 实例 | 只有用户明确要求 headless，或任务本身是后台任务/定时任务，或系统不支持可视化 |

- 用户明确指出模式后，直接阅读执行规则部分
- 当用户没有明确指出使用模式时，进入下一步自动判定

## 自动判定与失败处理

当用户没有明确指出使用模式时,按以下 4 步自动判定 + 失败处理:

### Step 1: 是否需要 headless

满足以下任一条件时,判定为“使用 headless 浏览器实例的 `cdp-direct` 流程”:

- 任务天然是后台执行
- 任务属于定时任务 / `CI` / `cron`
- 用户明确要求本次使用 headless 浏览器
- 系统不支持可视化,如服务器

如果判定需要 headless,则按以下顺序执行:

- 先读取 `references/cdp-headless.md`
- 优先使用显式提供的 `BU_CDP_WS` / `BU_CDP_URL`
- 不要引导用户去操作日常浏览器 profile 的 inspect 授权页
- 如果没有显式 CDP endpoint,再按 `references/cdp-headless.md` 中当前平台对应的后台启动方式启动专用 Chromium 实例;必须让浏览器进程脱离当前 shell 独立存活,并为它分配未被占用的专用 remote debugging 端口,优先复用安装脚本设置的 `AGENT_BROWSER_EXECUTABLE_PATH`
- 连通后读取 `references/cdp-direct.md`,后续页面操作统一按 `cdp-direct` 工作流执行

### Step 2: 跑 CDP 可用性检测

先执行:

```bash
flocks browser --doctor
```

该命令会检查 `flocks browser` 的 daemon 是否可用、Chrome/Chromium/Edge 是否运行,以及当前是否有可用的浏览器连接。不要只看命令退出码；必须优先读取 `next action` 行，再结合 `browser running` / `daemon alive` / `active browser connections` 三行判断。

### Step 3: 根据 doctor 输出决定模式

| 结果 | 触发条件 | 一线修复 | 仍失败兜底 |
|---|---|---|---|
| **A** | `next action` 以 `ready` 开头 | 立即确定 `CDP 直连`,阅读 `references/cdp-direct.md`,之后不再切到 `agent-browser` | — |
| **B** | `next action` 以 `attach` 开头 | 不要先反复 `--setup`；按输出执行 `flocks browser -c 'print(page_info())'` 或 `flocks browser -c 'print(list_tabs(include_chrome=False))'` 触发一次实际连接/观察 | 如果 `-c` 失败或仍无连接，执行 `flocks browser --reload` 清理旧 daemon，再执行 `flocks browser --setup`；按 setup 提示在当前 profile 的 inspect 页面完成 Allow 后重试 |
| **C** | `next action` 以 `setup` 开头 | 先执行 `flocks browser --setup`（不包短超时），再运行 `--doctor` 确认 | 如提示 remote debugging 未启用、`DevToolsActivePort` 缺失、403 handshake 或 not live yet，按 `references/cdp-setup.md` 先完成当前 profile 的 inspect/Allow；只有该流程重试后仍失败，才使用独立 profile 固定端口兜底 |
| **D** | `next action` 提示启动浏览器或提供 endpoint | 明确告知需要先启动 Chrome/Chromium/Edge/Brave，或提供 CDP endpoint | **不**擅自降级到 curl/webfetch；坚持告知 skill 边界 |

### Step 4: 跨模式通用失败

| 触发条件 | 一线修复 | 仍失败兜底 |
|---|---|---|
| `cdp-headless` 启动了专用 Chromium 实例 | 记 PID + 日志 + 专用 profile 路径 | 任务结束或明确放弃才清理;**不**关闭用户提供的远程浏览器 |
| 模式已确定后用户改主意 | 重新跑 `--doctor` 走 Result A/B/C 判定 | 避免同时加载 `cdp-direct.md` + `agent-browser.md` |


## 执行规则

1. 模式一旦确定，立即读取对应的 reference。
2. `cdp-headless` 是唯一例外：先读取 `references/cdp-headless.md` 完成浏览器启动与连接，再读取 `references/cdp-direct.md` 执行通用页面操作。
3. 在 `cdp-headless` 中，如果当前任务自己启动了专用浏览器实例，必须记录 PID / 日志 / 专用 profile，并只在任务结束或明确放弃后清理自己启动的实例；不要关闭用户提供的远程浏览器。
4. 不要同时加载 `references/cdp-direct.md` 和 `references/agent-browser.md`。
5. `flocks browser` 的 daemon 文件默认放在 `~/.flocks/browser/`（设置 `FLOCKS_ROOT` 时改为 `$FLOCKS_ROOT/browser/`）。默认 session 使用 `bu.*`；命名 session 使用 `bu-<BU_NAME>.*`。`.lock` 是启动互斥文件，可能在 daemon 退出后继续存在，不要手工删除 socket、port、PID 或 lock 文件，应使用 `flocks browser --reload`。
6. 基础操作能力（打开、观察、点击、输入、滚动、截图、提取、等待、关闭）优先按 `references/cdp-direct.md` 的“基础操作速查”执行

## 产品经验Skill

把特定产品页/网站的浏览器操作经验，沉淀到对应产品 skill，实现可复用。

适合沉淀的经验包括：

- 已确认某产品的稳定登录的方法
- 更稳定的页面进入方式，例如“优先直接拼 URL，不走菜单”
- 表格、筛选器、分页、弹窗、下载、详情展开等可靠操作路径
- 某站点特有的等待条件、重渲染特征、虚拟列表/SPA 交互怪癖
- 特定操作的成功经验，失败案例（特定操作失败 2 次以上，最终成功的经验）

具体怎么沉淀到 产品skill，请阅读 `references/browser-experience-in-skill.md`。

## References

- `references/browser-experience-in-skill.md`：如何把浏览器经验沉淀到产品 skill，以及推荐记录模板
- `references/cdp-headless.md`：`cdp-headless` 的全平台启动、连接与排障方式
- `references/cdp-direct.md`：以 `flocks browser` 作为 CDP 直连入口的启动方式、API、页面探索策略、错误处理
- `references/agent-browser.md`：agent-browser 的使用说明、错误处理等