winpeekaboo

name	winpeekaboo
description	Windows UI automation CLI tool - Peekaboo Python port with screen capture, element targeting, input simulation, and window/app management.
homepage	https://github.com/your-repo/winpeekaboo
metadata	{"clawdbot":{"emoji":"󰁈","os":["win32"],"requires":{"py":["winpeekaboo"]},"install":[{"id":"pip","kind":"pip","package":"winpeekaboo","label":"Install WinPeekaboo (pip)"}]}}

WinPeekaboo

WinPeekaboo 是 Peekaboo 的 Python 移植版本，为 Windows 提供完整的 UI 自动化 CLI 工具：捕获屏幕、识别 UI 元素、模拟输入、管理窗口和应用。所有命令支持 --json 输出用于脚本化。运行 winpeekaboo 或 winpeekaboo <cmd> --help 查看完整帮助。

功能特性

核心命令

• see: 捕获屏幕并识别 UI 元素（支持 UI Automation）
• list: 列出 windows/apps/screens/elements
• image: 截图（全屏/指定窗口/区域）

交互命令

• click: 点击元素或坐标
• type: 输入文本
• press: 按键
• hotkey: 组合键（如 Ctrl+C）
• scroll: 滚动
• drag: 拖放操作

系统命令

• window: 窗口管理（activate/minimize/maximize/restore/close/move/resize）
• app: 应用管理（launch/quit/switch/list）

全局参数

• --version/-v: 显示版本信息
• --verbose: 详细输出

快速开始

# 安装
pip install winpeekaboo

# 列出所有窗口
winpeekaboo list windows

# 查看���幕和UI元素
winpeekaboo see --json

# 点击坐标
winpeekaboo click --on "100,200"

# 点击元素
winpeekaboo click --on "Open" --window "Notepad"

# 输入文本
winpeekaboo type --text "Hello, World!"

# 按键
winpeekaboo press --key "Enter"

# 组合键
winpeekaboo hotkey --keys "Ctrl+C"

通用参数

窗口目标

• --window/-w: 目标窗口标题

输出控制

• --json: JSON 格式输出
• --output/-o: 输出到文件

命令详解

see - 屏幕捕获与UI识别

# 捕获全屏
winpeekaboo see

# 捕获指定窗口
winpeekaboo see --window "Notepad"

# JSON 输出
winpeekaboo see --json

# 包含截图
winpeekaboo see --screenshot --output snapshot.json

click - 点击元素

# 通过坐标点击
winpeekaboo click --on "100,200"

# 通过元素名称点击
winpeekaboo click --on "Open" --window "Notepad"

# 指定鼠标按钮
winpeekaboo click --on "100,200" --button right

type - 输入文本

# 基础输入
winpeekaboo type --text "Hello, World!"

# 延迟输入（模拟人工打字）
winpeekaboo type --text "Hello" --delay 0.1

# 指定窗口
winpeekaboo type --text "text" --window "Notepad"

press/hotkey - 键盘操作

# 单个按键
winpeekaboo press --key "Enter"
winpeekaboo press --key "Escape"

# 组合键
winpeekaboo hotkey --keys "Ctrl+C"
winpeekaboo hotkey --keys "Ctrl+Shift+T"
winpeekaboo hotkey --keys "Alt+F4"

scroll - 滚动

# 向下滚动
winpeekaboo scroll --direction down --amount 3

# 向上滚动
winpeekaboo scroll --direction up --amount 5

drag - 拖放

# 从坐标拖到坐标
winpeekaboo drag --from "100,200" --to "300,400"

# 从元素拖到元素
winpeekaboo drag --from "Source" --to "Target" --window "App"

window - 窗口管理

# 列出窗口
winpeekaboo window list
winpeekaboo list windows

# 激活窗口
winpeekaboo window activate --title "Notepad"

# 最小化/最大化/还原
winpeekaboo window minimize --title "Notepad"
winpeekaboo window maximize --title "Notepad"
winpeekaboo window restore --title "Notepad"

# 关闭窗口
winpeekaboo window close --title "Notepad"

# 移动窗口
winpeekaboo window move --title "Notepad" --x 100 --y 100

# 调整窗口大小
winpeekaboo window resize --title "Notepad" --width 800 --height 600

app - 应用管理

# 列出应用
winpeekaboo app list
winpeekaboo list apps

# 启动应用
winpeekaboo app launch --name "notepad.exe"

# 启动并等待
winpeekaboo app launch --name "notepad.exe" --wait

# 启动带参数
winpeekaboo app launch --name "code.exe" --args "--new-window"

# 关闭应用
winpeekaboo app quit --name "Notepad"

# 切换到应用
winpeekaboo app switch --name "Notepad"

image - 截图

# 全屏截图
winpeekaboo image --output screenshot.png

# 指定窗口截图
winpeekaboo image --window "Notepad" --output notepad.png

# 区域截图
winpeekaboo image --region "100,100,800,600" --output region.png

# JPEG 格式
winpeekaboo image --output screenshot.jpg --format jpeg --quality 90

list - 列出资源

# 列出窗口
winpeekaboo list windows

# 列出应用
winpeekaboo list apps

# 列出屏幕
winpeekaboo list screens

# 列出窗口元素
winpeekaboo list elements --window "Notepad"

# 带过滤
winpeekaboo list windows --filter "Chrome"

# JSON 输出
winpeekaboo list windows --json

使用流程示例

自动化记事本操作

# 启动记事本
winpeekaboo app launch --name "notepad.exe" --wait

# 查看元素
winpeekaboo see --window "Notepad" --json

# 输入文本
winpeekaboo type --text "Hello from WinPeekaboo!" --window "Notepad"

# 保存（组合键）
winpeekaboo hotkey --keys "Ctrl+S" --window "Notepad"

# 等待保存对话框
sleep 1

# 输入文件名
winpeekaboo type --text "test.txt"

# 确认保存
winpeekaboo press --key "Enter"

窗口管理

# 列出所有窗口
winpeekaboo list windows --json

# 激活特定窗口
winpeekaboo window activate --title "Chrome"

# 移动并调整大小
winpeekaboo window move --title "Chrome" --x 0 --y 0
winpeekaboo window resize --title "Chrome" --width 1200 --height 800

# 最大化后还原
winpeekaboo window maximize --title "Chrome"
sleep 2
winpeekaboo window restore --title "Chrome"

注意事项

1. 安全机制: pyautogui 默认启用 failsafe，将鼠标移动到屏幕左上角可紧急停止
2. 权限: 某些操作可能需要管理员权限
3. 兼容性: 部分应用可能不支持 UI Automation
4. 查找元素: 使用 winpeekaboo see --json 查看可用的 UI 元素

作为 Python 库使用

from winpeekaboo import (
    WindowEnumerator,
    WindowManager,
    KeyboardSimulator,
    MouseSimulator,
    ElementFinder,
)

# 查找窗口
windows = WindowEnumerator.enumerate_windows()
notepad = WindowEnumerator.find_by_title("Notepad")

# 操作窗口
mgr = WindowManager()
mgr.activate(notepad.hwnd)

# 模拟输入
KeyboardSimulator.type_text("Hello, World!")
KeyboardSimulator.hotkey(["ctrl", "s"])

# 模拟鼠标
MouseSimulator.click_at(100, 200)