screenshot-capture

使用 mss 和 Pillow 在 Windows 上捕获屏幕截图。提供全屏、区域和多显示器捕获，并输出为 PIL 图像、PNG 文件或 base64 字符串。当用户要求截屏、捕获屏幕内容、获取屏幕信息或需要 AI 视觉 API 的屏幕图像时使用。

# Screenshot Capture

基于 mss + Pillow 的高性能屏幕截图工具，适用于 Windows 桌面自动化、AI 视觉分析等场景。

## 依赖

```bash
uv add mss pillow
# 或
pip install mss pillow
```

## 快速开始

### 作为 Python 模块使用

```python
from scripts.screenshot import ScreenCapture

with ScreenCapture() as sc:
    # 获取屏幕分辨率
    width, height = sc.screen_size

    # 全屏截图 → PIL Image
    img = sc.capture()

    # 截图保存为文件
    sc.capture_to_file("output.png")

    # 截图转 base64 (用于发送给视觉 API)
    b64 = sc.capture_to_base64(quality=85, fmt="JPEG")
```

### 作为 CLI 工具使用

```bash
# 查看显示器信息
python scripts/screenshot.py info

# 截图保存到文件
python scripts/screenshot.py capture -o my_screenshot.png

# 截图输出 base64
python scripts/screenshot.py base64 --format JPEG --quality 85
```

## 核心 API

| 方法 | 说明 | 返回值 |
|------|------|--------|
| `screen_size` | 主显示器 (宽, 高) | `tuple[int, int]` |
| `all_screen_size` | 虚拟全屏 (宽, 高)，多屏合并 | `tuple[int, int]` |
| `monitors` | 所有显示器详细信息 | `list[dict]` |
| `capture(monitor, region, delay)` | 截图 → PIL Image | `Image.Image` |
| `capture_to_file(filepath, ...)` | 截图 → PNG/JPG 文件 | `Path` |
| `capture_to_base64(quality, fmt, ...)` | 截图 → base64 字符串 | `str` |

## 常见场景

### 发送截图给 OpenAI 视觉 API

```python
from openai import OpenAI
from scripts.screenshot import ScreenCapture

client = OpenAI()
with ScreenCapture() as sc:
    b64 = sc.capture_to_base64(fmt="JPEG", quality=85)

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "描述截图内容"},
            {"type": "image_url", "image_url": {
                "url": f"data:image/jpeg;base64,{b64}",
                "detail": "high",
            }},
        ],
    }],
)
```

### 截取指定区域

```python
with ScreenCapture() as sc:
    region = {"left": 100, "top": 200, "width": 800, "height": 600}
    img = sc.capture(region=region)
    img.save("region.png")
```

### 自动保存每步截图

```python
with ScreenCapture(save_dir="screenshots") as sc:
    for i in range(5):
        sc.capture_to_base64(step=i)  # 自动保存为 screenshots/step_000.jpg 等
```

## 详细参考

完整 API 参数说明见 [reference.md](reference.md)。