浏览器会话助手（免费版）

> 打开URL、提取信息、返回结果。三步完成单次浏览器会话。
无需编写完整自动化脚本，通过简单的fetch命令即可完成单次页面抓取任务。免费版聚焦轻量场景，让浏览器自动化触手可及。

概述

免费版浏览器会话工具为个人开发者提供基础的浏览器会话管理能力。通过Docker容器化的Chrome实例，在隔离环境中执行页面操作，保障本地系统安全。

核心定位

import subprocess
import json
class BsessionFetcher:
    """浏览器会话抓取器（免费版）"""
    def __init__(self, container_name="agent-browser"):
        self.container = container_name
    def check_container(self):
        """检查容器是否运行"""
        try:
            result = subprocess.run(
                ["docker", "exec", self.container, "echo", "ok"],
                capture_output=True, text=True, timeout=5
            )
            return result.returncode == 0
        except Exception:
            return False
    def find_free_port(self, start=9222, max_try=10):
        """查找可用的CDP端口"""
        for port in range(start, start + max_try):
            check_cmd = f"docker exec {self.container} python3 -c \"import urllib.request; " \
                       f"urllib.request.urlopen('http://localhost:{port}/json/version', timeout=2)\""
run(check_cmd, shell=False, capture_output=True)
            if result.returncode != 0:
                return port
        return None
    def fetch_url(self, url, wait_seconds=5):
        """抓取单个URL内容"""
        if not self.check_container():
            return {"success": False, "error": "容器未运行，请先执行 setup"}
        port = self.find_free_port()
        if not port:
            return {"success": False, "error": "无可用CDP端口"}
        try:
            subprocess.run(
container, "python3", "-c",
                 f"import sys; sys.path.insert(0, '/app'); "
                 f"from lib.browser import start_chrome; "
                 f"start_chrome({port}, '/workspace/data/profile-tmp')"],
                capture_output=True, text=True, timeout=10
            )
container, "agent-browser",
                 "--cdp", str(port), "open", url],
                capture_output=True, text=True, timeout=30
            )
            import time
            time.sleep(wait_seconds)
container, "agent-browser",
                 "--cdp", str(port), "snapshot"],
                capture_output=True, text=True, timeout=10
            )
            return {
                "success": True,
                "content": result.stdout,
                "port": port,
                "url": url
            }
        except Exception as e:
            return {"success": False, "error": str(e)}
        finally:
container, "python3", "-c",
path.insert(0, '/app'); "
browser import stop_chrome; "
                 f"stop_chrome({port})"],
                capture_output=True, text=True, timeout=5
            )
fetcher = BsessionFetcher()
result = fetcher.fetch_url("https://example.com", wait_seconds=3)
print(result.get("content", "")[:500] if result.get("success") else result.get("error"))

输出: 返回单次页面抓取（fetch模式）的执行结果,包含操作状态和输出数据。
- 执行此能力时使用input_params参数,支持创建/查询/导出操作

2. 基础元素交互

class BsessionInteraction:
    """基础元素交互（免费版）"""
    def __init__(self, container="agent-browser", port=9222):
        self.container = container
        self.port = port
    def click_element(self, ref):
        """点击元素"""
        cmd = ["docker", "exec", self.container, "agent-browser",
               "--cdp", str(self.port), "click", ref]
run(cmd, capture_output=True, text=True)
    def fill_field(self, ref, value):
        """填写表单字段"""
container, "agent-browser",
port), "fill", ref, value]
run(cmd, capture_output=True, text=True)
    def take_snapshot(self):
        """获取页面快照"""
container, "agent-browser",
run(cmd, capture_output=True, text=True)
stdout if result.returncode == 0 else ""
interaction = BsessionInteraction(port=9222)
content = interaction.take_snapshot()

输出: 返回基础元素交互的执行结果,包含操作状态和输出数据。
- 执行此能力时使用input_params参数,支持创建/查询/导出操作

3. 会话列表查看

class SessionLister:
    """会话列表查看器（免费版）"""
    def list_sessions(self):
        """列出所有会话"""
        try:
                ["docker", "exec", "agent-browser", "python3", "-c",
                 "import sys; sys.path.insert(0, '/app'); "
                 "from lib.browser import list_sessions; "
                 "list_sessions()"],
                capture_output=True, text=True, timeout=10
            )
        except Exception as e:
            return f"查询失败：{e}"
    def show_session(self, session_name):
        """查看指定会话详情"""
        try:
                ["docker", "exec", "agent-browser", "bsession", "show", session_name],
                capture_output=True, text=True, timeout=10
            )
        except Exception as e:
            return f"查询失败：{e}"

输出: 返回会话列表查看的执行结果,包含操作状态和输出数据。
能力覆盖范围：本skill的核心能力覆盖以下场景关键词：浏览器会话管理免、支持一次性页面抓、基础会话列表与简、易调试、浏览器会话助手免、费版是面向个人开、发者的轻量浏览器、会话管理工具、提取信息、返回结果、三步流程、无需编写完整脚本、即可完成单次页面、抓取任务、when、需要代码生成、编程辅助、调试测试、开发部署时使用、不适用于无明确技、术栈的模糊需求、适用于独立开发者、企业团队和自动化、工作流场景等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。
- 执行此能力时使用input_params参数,支持创建/查询/导出操作

使用场景

场景一：单次页面信息提取

场景描述：需要快速提取某网页的标题和正文内容。

fetcher = BsessionFetcher()
result = fetcher.fetch_url("https://news.example.com/article/123", wait_seconds=3)
if result.get("success"):
    content = result["content"]
    title = content.split("\n")[0] if content else "未获取到标题"
    print(f"标题：{title}")
    print(f"内容长度：{len(content)} 字符")
else:
    print(f"抓取失败：{result.get('error')}")

场景二：简易登录测试

场景描述：测试某网站的登录流程是否正常。

fetcher = BsessionFetcher()
result = fetcher.fetch_url("https://app.example.com/login")
interaction = BsessionInteraction(port=result.get("port", 9222))
snapshot = interaction.take_snapshot()

场景三：学习浏览器自动化

场景描述：初学者通过单次抓取学习浏览器自动化基础。

print("=== 浏览器会话基础流程 ===")
print("1. 检查容器状态")
fetcher = BsessionFetcher()
if fetcher.check_container():
    print("   容器运行中")
else:
    print("   容器未运行，请先执行 setup")
print("\n2. 查找可用端口")
port = fetcher.find_free_port()
print(f"   可用端口：{port}")
print("\n3. 抓取页面")
result = fetcher.com")
print(f"   抓取结果：{'成功' if result.get('success') else '失败'}")
print("\n4. 解析内容")
if result.get("success"):
    content_length = len(result.get("content", ""))
    print(f"   内容长度：{content_length} 字符")

快速开始

1. 阅读## 核心能力章节了解skill功能
2. 按## 依赖说明配置环境
3. 执行所需能力对应的命令
4. 参考## 错误处理章节处理异常
5. 查看## FAQ解答常见疑问

30秒上手

docker exec agent-browser echo ok
docker exec agent-browser agent-browser --cdp 9222 open "https://example.com"
sleep 3
docker exec agent-browser agent-browser --cdp 9222 snapshot

120秒标准搭建

cd ~/.bsession/
docker compose up -d
docker exec agent-browser python3 -c "
import sys; sys.path.insert(0, '/app')
from lib.browser import list_sessions
print('环境正常')
"
docker exec agent-browser agent-browser --cdp 9222 open "https://news.example.com"
sleep 5
docker exec agent-browser agent-browser --cdp 9222 snapshot > page_content.txt
docker exec agent-browser python3 -c "
import sys; sys.path.insert(0, '/app')
from lib.browser import stop_chrome
stop_chrome(9222)
"

结果处理: 执行完成后,查看输出结果确认操作状态。成功时输出包含处理摘要和结果数据;失败时根据错误信息排查问题,查阅错误处理章节获取恢复步骤。

配置示例

基础配置

import os
class BsessionConfig:
    """bsession配置（免费版）"""
    CONTAINER_NAME = os.getenv("BSESSION_CONTAINER", "agent-browser")
    DEFAULT_PORT = int(os.getenv("BSESSION_PORT", "9222"))
    WORKSPACE = os.getenv("BSESSION_WORKSPACE", "~/.bsession/workspace/")
    WAIT_TIMEOUT = int(os.getenv("BSESSION_WAIT", "5"))
    MAX_PORTS_TRY = int(os.getenv("BSESSION_MAX_PORTS", "10"))
    @classmethod
    def show(cls):
        print("=== bsession 配置 ===")
        print(f"容器名称：{cls.CONTAINER_NAME}")
        print(f"默认端口：{cls.DEFAULT_PORT}")
        print(f"工作空间：{cls.WORKSPACE}")
        print(f"等待时间：{cls.WAIT_TIMEOUT}s")
        print(f"最大端口尝试：{cls.MAX_PORTS_TRY}")
BsessionConfig.show()

容器路径解析

import os
from pathlib import Path
def resolve_bsession_paths():
    """解析bsession路径（按优先级）"""
    paths = {
        "bsession_home": None,
        "workspace": None,
        "cli_path": None
    }
    cli_candidates = [
        os.getenv("BSESSION_CLI"),
        os.path.expanduser("~/.bsession/bsession"),
        "./bsession"
    ]
    for candidate in cli_candidates:
        if candidate and os.path.exists(candidate):
            paths["cli_path"] = candidate
            break
    workspace_candidates = [
        os.getenv("BSESSION_WORKSPACE"),
        os.path.expanduser("~/.bsession/workspace/"),
        "./workspace/"
    ]
    for candidate in workspace_candidates:
path.exists(candidate):
            paths["workspace"] = candidate
            break
    paths["bsession_home"] = os.path.expanduser("~/.bsession/")
    return paths
paths = resolve_bsession_paths()
for k, v in paths.items():
    print(f"{k}: {v}")

优选实践

1. 资源清理

def safe_fetch(url):
    fetcher = BsessionFetcher()
    try:
        return fetcher.fetch_url(url)
    finally:
        subprocess.run(
            ["docker", "exec", "agent-browser", "python3", "-c",
path.insert(0, '/app'); "
browser import cleanup_temp; cleanup_temp()"],
            capture_output=True
        )

错误处理

def robust_fetch(url, max_retries=2):
    """带错误恢复的抓取"""
    for attempt in range(max_retries):
        try:
            fetcher = BsessionFetcher()
            result = fetcher.fetch_url(url)
                return result
            print(f"第{attempt+1}次失败：{result.get('error')}")
        except Exception as e:
            print(f"第{attempt+1}次异常：{e}")
    return {"success": False, "error": "重试次数已用完"}

3. 端口管理 - 处理方式: 按上述步骤操作并确认结果

class PortManager:
    """端口管理器"""
    USED_PORTS = set()
    @classmethod
    def get_free_port(cls, start=9222):
        for port in range(start, start + 20):
            if port not in cls.USED_PORTS:
                cls.USED_PORTS.add(port)
                return port
        return None
    @classmethod
    def release_port(cls, port):
        cls.USED_PORTS.discard(port)

错误场景2

检查error_code并按照处理方式进行排查。

错误场景3

常见问题

Q1：免费版支持定时任务吗？

不支持。免费版仅支持单次（one-shot）抓取任务。如需定时执行（如每30分钟检查一次）、循环监控、状态变化检测等场景，需升级至专业版。

Q2：Docker容器未运行怎么办？

请按以下步骤排查：(1) 检查Docker是否安装并运行：docker ps；(2) 启动bsession容器：cd ~/.bsession && docker compose up -d；(3) 验证容器状态：docker exec agent-browser echo ok。如首次使用，需执行 setup 命令初始化环境。

Q3：抓取的页面内容为空？

可能原因：(1) 页面加载未完成，增加 wait_seconds 参数；(2) 页面使用JavaScript动态渲染，需等待更长；(3) 触发反爬机制，建议降低抓取频率；(4) 容器内Chrome版本过旧，更新镜像。

Q4：如何保存抓取结果以便复用？

免费版不持久化会话状态。可通过 > 重定向输出到文件，或使用Python脚本保存为JSON。如需将会话保存为可复用的脚本（conf+py文件），需升级专业版。

Q5：多个URL抓取会冲突吗？

免费版单次只处理一个URL。如需同时抓取多个URL，建议串行执行并合理设置间隔（建议2-5秒），避免触发反爬。专业版支持并发批量处理。

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• Docker: 20+（运行bsession容器）
• Python: 3.8+（容器内执行）

依赖详情

用户: 执行核心功能
Skill: 正在执行核心功能...
Skill: 执行完成,结果如下: 操作成功

安全注意事项