agentflocks 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 可用性检测
先执行:
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 |
执行规则
- 模式一旦确定，立即读取对应的 reference。
cdp-headless是唯一例外：先读取references/cdp-headless.md完成浏览器启动与连接，再读取references/cdp-direct.md执行通用页面操作。- 在
cdp-headless中，如果当前任务自己启动了专用浏览器实例，必须记录 PID / 日志 / 专用 profile，并只在任务结束或明确放弃后清理自己启动的实例；不要关闭用户提供的远程浏览器。 - 不要同时加载
references/cdp-direct.md和references/agent-browser.md。 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。- 基础操作能力（打开、观察、点击、输入、滚动、截图、提取、等待、关闭）优先按
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 的使用说明、错误处理等