browser_开发编程 skill-PHP中文网

browser

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

浏览器自动化 — 配置 bsession 环境，单次抓取网站信息，创建一次性或循环的脚本化自动化，或调试现有的...

/浏览器技能

功能概述

/浏览器技能是一项面向实际任务的技能，主要用于您帮助用户在 bsession Docker 容器内自动设置浏览器—— 无论是初始设置、快速交互获取、脚本自动化( 一拍或重复) , 或。它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。

核心要点

使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。
该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。
从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。

使用与执行

实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。

结果检查与注意事项

执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。

/browser 技能

您帮助用户在 bsession Docker 容器内自动化浏览器操作——无论是初始环境搭建、快速交互式抓取、脚本化自动化（一次性或周期性任务），还是调试已有会话。

这是一个全局技能——可在任意代码仓库中使用。bsession 安装于 ~/.bsession/，且 bsession CLI 已加入系统 PATH。

路径解析

执行任何操作前，请先确定如何访问 bsession。按以下顺序检查：

bsession 在 PATH 中 → 使用 bsession
~/.bsession/bsession 存在 → 使用 ~/.bsession/bsession
当前目录下存在 ./bsession → 使用 ./bsession
以上均未找到，但容器正在运行（docker exec agent-browser echo ok 成功）→ 使用 docker exec agent-browser python3 /app/session.py 作为 CLI

同理，解析工作区（workspace）路径：

~/.bsession/workspace/ 存在 → 使用该路径
当前目录下存在 ./workspace/ → 使用该路径
执行 docker exec agent-browser ls /workspace/conf → 通过 docker exec 访问文件

在整个会话中，所有命令均需使用上述已解析的路径。

常量（默认值）

BSESSION_HOME：~/.bsession/ —— bsession 源码与 docker-compose 配置所在目录
WORKSPACE：~/.bsession/workspace/（默认值，可覆盖）—— 或按上述逻辑解析所得路径
bsession CLI：按上述逻辑解析所得

路由逻辑

解析用户输入的斜杠命令参数：

无参数或 list → 列表模式（显示所有可用脚本与会话）
setup → 设置模式（安装并配置 bsession）
fetch → 抓取模式（交互式一次性提取，可选持久化）
new → 创建模式（生成脚本模板——一次性或周期性任务）
run → 运行模式（执行已保存的会话并展示结果）
其他情况 → 调试模式（检查/修复已有会话）

前置检查（除 setup 外的所有模式）

除设置模式外，其余所有模式运行前，均需验证容器是否正在运行：

docker exec agent-browser echo ok 2>/dev/null

若该命令失败，请提示用户执行以下任一操作：

运行 /browser setup 进行全新安装；或
进入 bsession 项目目录后运行 docker compose up -d

列表模式（`/browser` 或 `/browser list`）

列出所有可用脚本、其状态及功能说明。

步骤 1：获取会话状态

bsession list

步骤 2：读取脚本文档字符串（docstring）

遍历 ~/.bsession/workspace/scripts/ 下每个 .py 文件，读取其模块级文档字符串（即文件顶部三重引号包裹的字符串）。

步骤 3：读取配置文件

遍历 ~/.bsession/workspace/conf/ 下每个 .conf 文件，读取 [env] 区段以展示当前配置。

步骤 4：以表格形式呈现

输出如下格式的摘要信息：

Session       Status    Type        Description
─────────────────────────────────────────────────────────────────
uscis         running   recurring   USCIS 案件状态监控器
price-check   stopped   one-shot    Amazon 商品价格爬虫

可用命令：
  /browser            调试某个会话
  /browser new        创建新的自动化任务
  /browser fetch       快速一次性抓取

设置模式（`/browser setup`）

运行安装脚本：

bash ~/.openclaw/workspace/skills/browser/scripts/install.sh

支持传入选项：

bash ~/.openclaw/workspace/skills/browser/scripts/install.sh --workspace /path/to/workspace
bash ~/.openclaw/workspace/skills/browser/scripts/install.sh --vnc-password secret
bash ~/.openclaw/workspace/skills/browser/scripts/install.sh --repo https://github.com/gaxxx/bsession.git

运行前请向用户询问自定义选项。该脚本将自动完成 Docker 环境检查、uv/Python 安装、镜像构建、容器启动及 CLI 初始化等全部流程。

抓取模式（`/browser fetch` ）

一次性操作：打开指定 URL，提取信息并返回结果。不生成脚本、不创建配置文件、不启用循环。

步骤 1：查找可用的 CDP 端口

docker exec agent-browser python3 -c "
import urllib.request
try:
    urllib.request.urlopen('http://localhost:9222/json/version', timeout=2)
    print('IN_USE')
except:
    print('FREE')
"

若端口 9222 已被占用，则尝试 9223、9224 等后续端口。在空闲端口上启动临时 Chrome 实例：

docker exec agent-browser python3 -c "
import sys; sys.path.insert(0, '/app')
from lib.browser import start_chrome
pid = start_chrome(PORT, '/workspace/data/profile-tmp')
print(f'Chrome started, pid={pid}')
"

步骤 2：导航并提取内容

docker exec agent-browser agent-browser --cdp PORT open "URL"
sleep 5
docker exec agent-browser agent-browser --cdp PORT snapshot

如检测到 Cloudflare 验证页，则处理如下：

docker exec agent-browser python3 -c "
import sys; sys.path.insert(0, '/app')
from lib.browser import ab, is_cloudflare, wait_for_cloudflare
snap = ab(PORT, 'snapshot')
if is_cloudflare(snap):
    wait_for_cloudflare(PORT, snap)
    snap = ab(PORT, 'snapshot')
print(snap)
"

步骤 3：解析与交互

docker exec agent-browser agent-browser --cdp PORT fill REF "value"
docker exec agent-browser agent-browser --cdp PORT click REF
docker exec agent-browser agent-browser --cdp PORT snapshot

步骤 4：返回结果

解析关键信息，并以清晰格式呈现。

步骤 5：提供持久化选项

返回结果后，始终询问用户是否希望将其保存为可复用脚本。若用户确认，则在 ~/.bsession/workspace/ 下创建对应的一次性脚本与配置文件。

步骤 6：清理资源

docker exec agent-browser python3 -c "
import sys; sys.path.insert(0, '/app')
from lib.browser import stop_chrome
stop_chrome(PORT)
"

创建模式（`/browser new` ）

向用户提问：

目标 URL 是什么？
是一次性任务还是周期性任务？
需要检测或提取哪些内容？
结果应发送至何处（Webhook、文件等）？
需要哪些环境变量？

随后依据下方参考章节中的约定，在 ~/.bsession/workspace/conf/.conf 和 ~/.bsession/workspace/scripts/.py 中生成对应模板。

运行模式（`/browser run` ）

验证会话是否存在：bsession show
运行该会话：bsession run
等待执行完成并实时查看日志：bsession logs -n 50
展示结果。若执行失败，则自动切换至调试模式。

调试模式（`/browser` ）

收集状态信息：bsession list、bsession show ，并读取日志与脚本内容
诊断问题：Cloudflare 卡住、元素未找到、进程崩溃、数据错误、进程已退出等
修改脚本或配置文件后，执行 bsession restart

脚本编写规范

导入语句：

import os, re, sys, time
sys.path.insert(0, "/app")
from lib.browser import (
    ab, ab_quiet, find_ref, is_cloudflare, wait_for_cloudflare,
    send_webhook, make_logger,
)

从环境变量加载配置：

port = int(os.environ.get("CDP_PORT", 9222))
session_name = os.environ.get("SESSION_NAME", "")
webhook_url = os.environ.get("N8N_WEBHOOK_URL", "")
check_interval = int(os.environ.get("CHECK_INTERVAL", 1800))

核心执行流程： 打开 URL → 等待加载 → 截图 → 处理 Cloudflare → 查找元素 → 交互操作 → 解析结果

一次性任务： 执行完毕即退出。周期性任务： 使用 while True 包裹主逻辑，配合 sleep，比对状态变化，并在状态变更时触发 Webhook。

参考：lib/browser.py

ab(port, cmd, *args) / ab_quiet(port, cmd, *args) —— 执行 agent-browser 命令
find_ref(snapshot, pattern) / find_all_refs(snapshot, pattern) —— 解析可访问性树（accessibility tree）
is_cloudflare(snapshot) / wait_for_cloudflare(port, snapshot, ...) —— Cloudflare 验证页处理
send_webhook(url, payload) —— 向 Webhook 地址 POST JSON 数据
make_logger(session_name) —— 创建带时间戳的日志记录器