布罗什

Name: 布罗什
Author: twardoch

作者：twardoch3 星标更新：2025-07-18

安装使用来源：spider==github.com

项目介绍

brosh - 浏览器截图工具

一个强大的浏览器截图工具，使用Playwright的异步API捕捉网页滚动截图。支持智能区域识别、多种输出格式（包括动画PNG）以及与MCP（模型上下文协议）集成。

1. 目录

功能
工作原理
安装
快速开始
用法
命令参考
- 全局选项
- 命令
输出
高级用法
MCP集成
架构
开发
故障排除
贡献
许可证

2. 功能

🚀 异步Playwright集成：快速且可靠的浏览器自动化
🔍 智能区域检测：自动识别可见部分以生成描述性文件名
🖼️ 多种格式：PNG、JPG和动画PNG（APNG）输出
🌐 浏览器支持：Chrome、Edge和Safari（macOS）
🔌 远程调试：连接到现有浏览器会话，保留cookies/认证
🤖 MCP服务器：通过模型上下文协议集成AI工具
📄 HTML提取：可选捕获可见元素的HTML内容
📝 文本提取：自动将可见内容转换为Markdown文本
📐 灵活滚动：可配置滚动步骤和起始位置
🎯 精确控制：设置视口大小、缩放级别和输出比例
🔄 自动重试：具有可配置重试逻辑的强大错误处理

3. 工作原理

brosh的工作方式如下：

浏览器连接：连接到调试模式下的现有浏览器或启动新实例
页面导航：导航到指定的URL并等待内容加载
智能滚动：按可配置的步骤滚动页面，捕获截图
区域检测：识别可见标题和元素以创建有意义的文件名
图像处理：应用缩放、格式转换，并根据需要创建动画
输出组织：保存带有描述性名称的截图，包括域名、时间戳和区域

该工具特别适用于：

文档：捕获长篇技术文档或API引用
质量保证测试：视觉回归测试和错误报告
内容归档：通过全页捕获保存网络内容
设计审查：与利益相关者分享完整的页面设计
AI集成：通过MCP向语言模型提供视觉上下文

4. 安装

4.1. 使用uv/uvx（推荐）

uv是一个快速的Python包管理器，替代了pip、pip-tools、pipx、poetry、pyenv和virtualenv。

# 安装uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 使用uvx直接运行brosh（无需安装）
uvx brosh shot "https://example.com"

# 或全局安装
uv tool install brosh

# 带所有额外依赖项安装
uv tool install "brosh[all]"

4.2. 使用pip

# 基础安装
pip install brosh

# 带所有可选依赖项
pip install "brosh[all]"

4.3. 使用pipx

pipx在隔离环境中安装Python应用程序。

# 安装pipx（如果尚未安装）
python -m pip install --user pipx
python -m pipx ensurepath

# 安装brosh
pipx install brosh

4.4. 从源代码安装

git clone https://github.com/twardoch/brosh.git
cd brosh
pip install -e ".[all]"

4.5. 安装Playwright浏览器驱动

安装后，您需要安装浏览器驱动程序：

playwright install

5. 快速开始

# 捕获单个网页
brosh shot "https://example.com"

# 启动浏览器以进行调试模式以提高性能
brosh run
brosh shot "https://example.com"

# 创建显示滚动的动画PNG
brosh shot "https://example.com" --format apng

# 使用自定义视口捕获
brosh --width 1920 --height 1080 shot "https://example.com"

# 提取HTML内容
brosh shot "https://example.com" --html --json > content.json

6. 用法

6.1. 命令行界面

brosh提供了基于Fire的CLI，具有直观的命令和选项。

6.1.1. 基本截图捕获

# 简单捕获
brosh shot "https://example.com"

# 使用自定义设置捕获
brosh --width 1920 --height 1080 --zoom 125 shot "https://example.com"

# 捕获整个页面高度（无视口限制）
brosh --height -1 shot "https://example.com"

# 保存到特定目录
brosh --output_dir ~/Screenshots shot "https://example.com"

# 按域名组织
brosh --subdirs shot "https://example.com"

6.1.2. 高级捕获选项

# 从特定元素开始
brosh shot "https://docs.python.org" --from_selector "#functions"

# 限制截图数量
brosh shot "https://example.com" --max_frames 5

# 调整滚动步长（视口百分比）
brosh shot "https://example.com" --scroll_step 50

# 缩放输出图像
brosh shot "https://example.com" --scale 75

# 创建动画PNG
brosh shot "https://example.com" --format apng --anim_spf 1.0

# 提取可见HTML
brosh shot "https://example.com" --html --json > page_content.json

6.2. MCP服务器模式

作为MCP服务器运行以集成AI工具：

# 使用专用命令
brosh-mcp

# 或通过主命令
brosh mcp

6.3. Python API

import asyncio
from brosh import capture_webpage, capture_webpage_async

# 同步使用（自动处理异步）
def capture_sync():
    # 基本捕获
    result = capture_webpage(
        url="https://example.com",
        width=1920,
        height=1080,
        scroll_step=100,
        format="png"
    )

    print(f"捕获了 {len(result)} 张截图")
    for path, data in result.items():
        print(f"  - {path}")
        print(f"    文本: {data['text'][:100]}...")

# 异步使用（用于集成异步应用程序）
async def capture_async():
    # 捕获并提取HTML
    result = await capture_webpage_async(
        url="https://example.com",
        html=True,
        max_frames=3,
        from_selector="#main-content"
    )

    # 结果是字典，键为路径，值为元数据
    for path, data in result.items():
        print(f"\n截图: {path}")
        print(f"选择器: {data['selector']}")
        print(f"文本预览: {data['text'][:200]}...")
        if 'html' in data:
            print(f"HTML预览: {data['html'][:200]}...")

# 运行示例
capture_sync()
asyncio.run(capture_async())

# 方便函数
from brosh import capture_full_page, capture_visible_area, capture_animation

# 捕获整个页面的一张截图
full_page = capture_full_page("https://example.com")

# 只捕获可见视口
visible = capture_visible_area("https://example.com")

# 创建动画PNG
animation = capture_animation("https://example.com")

7. 命令参考

7.1. 全局选项

这些选项可用于任何命令：

选项	类型	默认值	描述
`--app`	str	自动检测	使用的浏览器：`chrome`、`edge`、`safari`
`--width`	int	屏幕宽度	视口宽度（像素）
`--height`	int	屏幕高度	视口高度（像素）（-1表示全页）
`--zoom`	int	100	缩放级别百分比（10-500）
`--output_dir`	str	~/Pictures	截图输出目录
`--subdirs`	bool	False	为每个域名创建子目录
`--verbose`	bool	False	启用调试日志

7.2. 命令

7.2.1. `run` - 启动浏览器以进行调试模式

brosh [--app BROWSER] run [--force_run]

以远程调试模式启动浏览器，以便更好地进行多次捕获。

选项：

--force_run：即使已经运行也要强制重启

7.2.2. `quit` - 关闭浏览器

brosh [--app BROWSER] quit

关闭以调试模式启动的浏览器。

7.2.3. `shot` - 捕获截图

brosh [OPTIONS] shot URL [SHOT_OPTIONS]

必需：

URL：要捕获的网页URL

截图选项：

选项	类型	默认值	描述
`--scroll_step`	int	100	滚动步长（视口高度的百分比）（10-200）
`--scale`	int	100	输出图像缩放百分比（10-200）
`--format`	str	png	输出格式：`png`、`jpg`、`apng`
`--anim_spf`	float	0.5	APNG每帧秒数
`--html`	bool	False	提取可见元素的HTML内容
`--json`	bool	False	以JSON格式输出结果
`--max_frames`	int	0	最大截图数量（0表示全部）
`--from_selector`	str	""	开始捕获的CSS选择器

7.2.4. `mcp` - 运行MCP服务器

brosh mcp

启动MCP服务器以集成AI工具。

8. 输出

8.1. 文件命名约定

截图保存时带有描述性文件名：

{域名}-{时间戳}-{滚动位置}-{区域}.{格式}

示例：

github_com-250612-185234-00500-readme.png
│         │              │     │
│         │              │     └── 区域标识符
│         │              └──────── 滚动位置（0-9999）
│         └─────────────────────── 时间戳（YYMMDD-HHMMSS）
└───────────────────────────────── 域名

8.2. 输出格式

PNG：无损压缩，最佳质量（默认）
JPG：较小的文件大小，适合照片
APNG：显示滚动序列的动画PNG

8.3. JSON输出

该工具现在总是从可见元素中提取文本内容。当使用--json时：

默认输出（无--html）：

{
  "/path/to/screenshot1.png": {
    "selector": "main.content",
    "text": "# 主内容\n\n这是以Markdown格式提取的文本..."
  }
}

带--html标志：

{
  "/path/to/screenshot1.png": {
    "selector": "main.content",
    "html": "<main class='content'>...</main>",
    "text": "# 主内容\n\n这是以Markdown格式提取的文本..."
  }
}

text字段包含使用html2text转换为Markdown格式的可见内容，便于编程处理。

9. 高级用法

9.1. 浏览器管理

brosh可以连接到您的现有浏览器会话，保留cookies、认证和扩展：

# 以调试模式启动Chrome
brosh --app chrome run

# 您的常规浏览会话仍然有效
# brosh连接到它进行截图

# 使用登录会话进行截图
brosh shot "https://github.com/notifications"

# 完成后退出
brosh --app chrome quit

9.2. 自定义视口

通过设置视口尺寸模拟不同的设备：

# 桌面 - 4K
brosh --width 3840 --height 2160 shot "https://example.com"

# 桌面 - 1080p
brosh --width 1920 --height 1080 shot "https://example.com"

# 平板电脑
brosh --width 1024 --height 768 shot "https://example.com"

# 移动设备
brosh --width 375 --height 812 shot "https://example.com"

9.3. HTML提取

为每个截图提取可见元素的HTML内容：

# 获取HTML与截图
brosh shot "https://example.com" --html --json > content.json

# 处理提取的内容
cat content.json | jq 'to_entries | .[] | {
  screenshot: .key,
  wordCount: (.value.html | split(" ") | length)
}'

9.4. 动画创建

创建平滑动画显示页面滚动：

# 标准动画（每帧0.5秒）
brosh shot "https://example.com" --format apng

# 更快的动画
brosh shot "https://example.com" --format apng --anim_spf 0.2

# 更慢，更详细
brosh shot "https://example.com" --format apng --anim_spf 1.0 --scroll_step 50

10. MCP集成

10.1. 什么是MCP？

模型上下文协议（MCP）是一种开放标准，使AI应用程序能够无缝地与外部数据源或工具集成。brosh实现了MCP服务器，允许像Claude这样的AI助手捕获和分析网络内容。

10.2. 设置MCP服务器

10.2.1. 使用uvx（推荐）

# 直接运行无需安装
uvx brosh-mcp

# 或作为工具安装
uv tool install brosh
uvx brosh-mcp

10.2.2. 配置Claude桌面

将brosh添加到您的Claude桌面配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "brosh": {
      "command": "uvx",
      "args": ["brosh-mcp"],
      "env": {
        "FASTMCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

注意： 如果遇到uvx问题，您可以使用brosh-mcp的完整路径：

{
  "mcpServers": {
    "brosh": {
      "command": "/path/to/python/bin/brosh-mcp",
      "args": [],
      "type": "stdio"
    }
  }
}

找到完整路径的方法：

# 在类Unix系统上
which brosh-mcp

# 或使用Python
python -c "import shutil; print(shutil.which('brosh-mcp'))"

10.2.3. 替代配置

直接使用Python：

{
  "mcpServers": {
    "brosh": {
      "command": "python",
      "args": ["-m", "brosh", "mcp"]
    }

布罗什