/browser 技能

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

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

路径解析

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

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

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

1. ~/.bsession/workspace/ 存在 → 使用该路径
2. 当前目录下存在 ./workspace/ → 使用该路径
3. 执行 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 ）

向用户提问：

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

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

运行模式（/browser run ）

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

调试模式（/browser ）

1. 收集状态信息：bsession list、bsession show ，并读取日志与脚本内容
2. 诊断问题：Cloudflare 卡住、元素未找到、进程崩溃、数据错误、进程已退出等
3. 修改脚本或配置文件后，执行 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) —— 创建带时间戳的日志记录器