Brosh Browser Screenshot

brosh-浏览器截图工具

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

1.目录

• 特性
• 运作原理
• 安装

- 使用紫外线/紫外线（推荐） - 使用pip - 使用pipx - 来源

• 快速开始
• 用法

- 命令行接口 - MCP服务器模式 - Python API

• 命令参考

- 全局选项 - 命令

• 输出
• 高级用法

- 浏览器管理 - 自定义视口 - HTML提取 - 动画创作

• MCP集成

- 什么是MCP？ - 设置MCP服务器 - 配置Claude桌面

• 建筑
• 发展
• 故障排除
• 贡献
• 许可证

2.特点

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

3.工作原理

布罗什 作品来源：

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

该工具特别适用于：

• 文档：获取长期技术文档或API参考资料
• QA测试：可视化回归测试和错误报告
• 内容存档：通过全页面捕获来保留web内容
• 设计检查：与利益相关者共享完整的页面设计
• 人工智能集成：通过MCP为语言模型提供视觉上下文

4.安装

4.1.使用紫外线/紫外线（推荐）

紫外线 是一个快速的Python包管理器，它取代了pip、pip工具、pipx、poetry、pyenv和virtualenv。

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run brosh directly with uvx (no installation needed)
uvx brosh shot "https://example.com"

# Or install globally
uv tool install brosh

# Install with all extras
uv tool install "brosh[all]"

4.2.使用pip

# Basic installation
pip install brosh

# With all optional dependencies
pip install "brosh[all]"

4.3.使用pipx

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

# Install pipx (if not already installed)
python -m pip install --user pipx
python -m pipx ensurepath

# Install 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.快速入门

# Capture a single webpage
brosh shot "https://example.com"

# Start browser in debug mode for better performance
brosh run
brosh shot "https://example.com"

# Create an animated PNG showing the scroll
brosh shot "https://example.com" --format apng

# Capture with custom viewport
brosh --width 1920 --height 1080 shot "https://example.com"

# Extract HTML content
brosh shot "https://example.com" --html --json > content.json

6.使用方法

6.1.命令行接口

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

6.1.1.基本屏幕截图

# Simple capture
brosh shot "https://example.com"

# Capture with custom settings
brosh --width 1920 --height 1080 --zoom 125 shot "https://example.com"

# Capture entire page height (no viewport limit)
brosh --height -1 shot "https://example.com"

# Save to specific directory
brosh --output_dir ~/Screenshots shot "https://example.com"

# Organize by domain
brosh --subdirs shot "https://example.com"

6.1.2.高级捕获选项

# Start from specific element
brosh shot "https://docs.python.org" --from_selector "#functions"

# Limit number of screenshots
brosh shot "https://example.com" --max_frames 5

# Adjust scroll step (percentage of viewport)
brosh shot "https://example.com" --scroll_step 50

# Scale output images
brosh shot "https://example.com" --scale 75

# Create animated PNG
brosh shot "https://example.com" --format apng --anim_spf 1.0

# Extract visible HTML
brosh shot "https://example.com" --html --json > page_content.json

6.2.MCP服务器模式

作为MCP服务器运行，用于AI工具集成：

# Using the dedicated command
brosh-mcp

# Or via the main command
brosh mcp

6.3.Python API

import asyncio
from brosh import capture_webpage, capture_webpage_async

# Synchronous usage (automatically handles async for you)
def capture_sync():
    # Basic capture
    result = capture_webpage(
        url="https://example.com",
        width=1920,
        height=1080,
        scroll_step=100,
        format="png"
    )

    print(f"Captured {len(result)} screenshots")
    for path, data in result.items():
        print(f"  - {path}")
        print(f"    Text: {data['text'][:100]}...")

# Asynchronous usage (for integration with async applications)
async def capture_async():
    # Capture with HTML extraction
    result = await capture_webpage_async(
        url="https://example.com",
        html=True,
        max_frames=3,
        from_selector="#main-content"
    )

    # Result is a dict with paths as keys and metadata as values
    for path, data in result.items():
        print(f"\nScreenshot: {path}")
        print(f"Selector: {data['selector']}")
        print(f"Text preview: {data['text'][:200]}...")
        if 'html' in data:
            print(f"HTML preview: {data['html'][:200]}...")

# Run the examples
capture_sync()
asyncio.run(capture_async())

# Convenience functions
from brosh import capture_full_page, capture_visible_area, capture_animation

# Capture entire page in one screenshot
full_page = capture_full_page("https://example.com")

# Capture only visible viewport
visible = capture_visible_area("https://example.com")

# Create animated PNG
animation = capture_animation("https://example.com")

7.命令参考

7.1.全局选项

这些选项可以与任何命令一起使用：

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 |浮点|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.文件命名约定

屏幕截图以描述性文件名保存：

{domain}-{timestamp}-{scroll_position}-{section}.{format}

例子：

github_com-250612-185234-00500-readme.png
│         │              │     │
│         │              │     └── Section identifier
│         │              └──────── Scroll position (0-9999)
│         └─────────────────────── Timestamp (YYMMDD-HHMMSS)
└───────────────────────────────── Domain name

8.2.输出格式

• 便携式网络图形：无损压缩，最佳质量（默认）
• JPG：文件大小较小，适合拍照
• APNG：显示滚动序列的动画PNG

8.3.JSON输出

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

默认输出（不带--html）：

{
  "/path/to/screenshot1.png": {
    "selector": "main.content",
    "text": "# Main Content\n\nThis is the extracted text in Markdown format..."
  }
}

带有--html标志：

{
  "/path/to/screenshot1.png": {
    "selector": "main.content",
    "html": "...",
    "text": "# Main Content\n\nThis is the extracted text in Markdown format..."
  }
}

这 text 字段包含使用html2text转换为Markdown格式的可见内容，这使得以编程方式处理内容变得容易。

9.高级使用

9.1.浏览器管理

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

# Start Chrome in debug mode
brosh --app chrome run

# Your regular browsing session remains active
# brosh connects to it for screenshots

# Take screenshots with your logged-in session
brosh shot "https://github.com/notifications"

# Quit when done
brosh --app chrome quit

9.2.自定义视口

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

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

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

# Tablet
brosh --width 1024 --height 768 shot "https://example.com"

# Mobile
brosh --width 375 --height 812 shot "https://example.com"

9.3.HTML提取

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

# Get HTML with screenshots
brosh shot "https://example.com" --html --json > content.json

# Process the extracted content
cat content.json | jq 'to_entries | .[] | {
  screenshot: .key,
  wordCount: (.value.html | split(" ") | length)
}'

9.4.动画创作

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

# Standard animation (0.5 seconds per frame)
brosh shot "https://example.com" --format apng

# Faster animation
brosh shot "https://example.com" --format apng --anim_spf 0.2

# Slower, more detailed
brosh shot "https://example.com" --format apng --anim_spf 1.0 --scroll_step 50

10.MCP集成

10.1.什么是MCP？

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

10.2.设置MCP服务器

10.2.1.使用uvx（推荐）

# Run directly without installation
uvx brosh-mcp

# Or install as a tool
uv tool install brosh
uvx brosh-mcp

10.2.2.配置Claude桌面

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

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %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"
    }
  }
}

要查找完整路径，请执行以下操作：

# On Unix-like systems
which brosh-mcp

# Or with Python
python -c "import shutil; print(shutil.which('brosh-mcp'))"

10.2.3.替代配置

直接使用Python：

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

使用特定的Python路径：

{
  "mcpServers": {
    "brosh": {
      "command": "/usr/local/bin/python3",
      "args": ["-m", "brosh", "mcp"]
    }
  }
}

10.3.与克劳德一起使用

配置后，您可以要求Claude：

• “截取python.org文档的屏幕截图”
• “用动画捕捉整个React主页”
• “获取GitHub趋势页面的屏幕截图并提取可见的HTML”
• “让我看看黑客新闻主页是什么样子的”

Claude将使用brosh捕获屏幕截图，并可以分析视觉内容或提取的HTML。

11.建筑

该项目分为模块化组件：

src/brosh/
├── __init__.py      # Package exports
├── __main__.py      # CLI entry point
├── api.py           # Public API functions
├── cli.py           # Command-line interface
├── tool.py          # Main screenshot tool
├── browser.py       # Browser management
├── capture.py       # Screenshot capture logic
├── image.py         # Image processing
├── models.py        # Data models
├── mcp.py           # MCP server implementation
└── texthtml.py      # HTML/text processing

11.1.关键组件

• API层：同时提供同步(capture_webpage)异步(capture_webpage_async)接口
• 浏览器管理器：处理浏览器检测、启动和连接
• Capture管理器：管理滚动和屏幕截图捕获
• 图像处理器：处理图像缩放、转换和动画
• 浏览器截图工具：协调捕获过程
• 浏览器截图CLI：提供命令行界面
• MCP服务器：基于FastMCP的服务器，用于AI工具集成

12.发展

12.1.设置开发环境

# Clone the repository
git clone https://github.com/twardoch/brosh.git
cd brosh

# Install with development dependencies
pip install -e ".[dev,test,all]"

# Install pre-commit hooks
pre-commit install

12.2.运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src/brosh --cov-report=term-missing

# Run specific test
pytest tests/test_capture.py -v

12.3.代码质量

# Format code
ruff format src/brosh tests

# Lint code
ruff check src/brosh tests

# Type checking
mypy src/brosh

12.4.建筑文件

# Install docs dependencies
pip install -e ".[docs]"

# Build documentation
sphinx-build -b html docs/source docs/build

13.故障排除

13.1.常见问题

13.1.1.未找到浏览器

错误： “找不到chrome安装”

解决方案： 确保Chrome/Edge/Safari安装在默认位置，或明确指定浏览器：

brosh --app edge shot "https://example.com"

13.1.2.连接超时

错误： “无法连接到浏览器”

解决方案： 首先在调试模式下启动浏览器：

brosh run
# Then in another terminal:
brosh shot "https://example.com"

13.1.3.屏幕截图超时

错误： “位置X的屏幕截图超时”

解决方案： 增加超时时间或降低页面复杂性：

# Simpler format
brosh shot "https://example.com" --format jpg

# Fewer screenshots
brosh shot "https://example.com" --scroll_step 200

13.1.4.权限不足

错误： 保存屏幕截图时“权限被拒绝”

解决方案： 检查输出目录权限或使用其他目录：

brosh --output_dir /tmp/screenshots shot "https://example.com"

13.2.调试模式

启用详细日志记录以排除问题：

brosh --verbose shot "https://example.com"

13.3.平台特定注意事项

13.3.1.macOS

• Safari需要在“开发”菜单中启用“允许远程自动化”
• Retina显示屏会自动检测和处理

13.3.2.视窗

• 如果遇到权限问题，请以管理员身份运行
• Chrome/Edge必须安装在默认的程序文件位置

13.3.3.Linux

• 安装其他依赖项： sudo apt-get install libnss3 libxss1
• 无显示器的服务器可能需要无头模式

14.贡献

欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。

14.1.开发过程

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/AmazingFeature)
3. 提交您的更改(git commit -m 'Add some AmazingFeature')
4. 推到分支(git push origin feature/AmazingFeature)
5. 打开拉取请求

14.2.代码的风格

• 遵循PEP 8指南
• 对所有函数使用类型提示
• 将文档字符串添加到所有公共函数中
• 保持功能集中和模块化
• 为新功能编写测试

15.许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

• 由...创建 Adam Twardoch
• 创建于 Anthropic 软件
• 用途 剧作家 实现可靠的浏览器自动化
• 用途 火 对于CLI界面
• 实现 FastMCP 用于模型上下文协议支持