Pywayne Gui

Windows GUI automation toolkit for global hotkeys and window management. Use when users need to register global hotkeys, find/control windows, automate GUI o...

Security Scan

The SKILL.md describes a Python Windows GUI library and commands that are coherent with GUI automation, but the skill bundle contains no code or install specification (and does not declare the Python dependencies), creating a meaningful mismatch you should verify before installing or running.

Purpose & Capability

The skill claims to provide a Python package api (from pywayne.gui) for registering global hotkeys and window control. However the registry entry is instruction-only with no code files and no install spec — the described package is not provided by the skill. That mismatch means the skill is effectively documentation for an external package rather than a self-contained integration.

Instruction Scope

The runtime instructions and examples stick to Windows GUI automation: registering global hotkeys, enumerating and manipulating windows, and using pyautogui/pyuserinput/pywin32. They do not instruct reading unrelated system files, exfiltrating secrets, or contacting external endpoints.

Install Mechanism

There is no install specification for the skill; the SKILL.md merely lists pip install commands for dependencies. Because the skill does not include the pywayne package or declare how to install it, it relies on an external package being present in the environment — a gap that could lead to confusion or accidental execution of an unexpectedly sourced package.

Credentials

The skill requests no environment variables, credentials, or config paths. The listed dependencies (pywin32, pyuserinput, pyautogui) are appropriate for Windows GUI automation and are proportional to the described functionality.

Persistence & Privilege

always is false and the skill does not request system-wide persistence or modify other skills' configs. Note: the skill's functionality (global hotkeys, window control) can affect the user desktop and may require administrator privileges for some operations, but the bundle does not request elevated platform privileges itself.

What to consider before installing

This skill appears to be documentation for a Python package (pywayne.gui) rather than a complete skill bundle. Before installing or running anything: 1) Verify the actual Python package: search PyPI and GitHub for 'pywayne' or 'pywayne.gui' and review the repository and release artifacts. 2) If you intend to use this skill inside an agent, prefer a skill that either includes the package or an explicit, trusted install step (e.g., a link to an official GitHub release or PyPI). 3) Install and test the package in an isolated environment (VM or container) first — GUI automation libraries can take actions on your desktop, register global hotkeys, and may require admin rights for some operations. 4) If you can't find a trusted upstream source, do not run code that imports 'pywayne' from this skill. 5) If you permit the agent to invoke this skill autonomously, be aware it could trigger hotkeys or manipulate windows; limit autonomous use if you don't fully trust the package/source.

Windows 图形用户界面自动化工具，提供全局热键监听和窗口操作功能。

Quick Start

from pywayne.gui import GlobalHotKeys, GuiOperation

# 全局热键
g = GlobalHotKeys()

@g.register(GlobalHotKeys.VK_F1, GlobalHotKeys.MOD_SHIFT)
def shift_f1():
    print('Shift+F1 被按下')

# 启动监听（按 Q 或 Ctrl+C 退出）
GlobalHotKeys.listen()

Dependencies

包	用途	安装命令
pywin32	Windows API 封装	pip install pywin32
pyuserinput	键盘鼠标输入	pip install pyuserinput
pyautogui	GUI 自动化	pip install pyautogui

GlobalHotKeys - 全局热键

注册全局热键，在全局范围内监听键盘事件。

注册热键

from pywayne.gui import GlobalHotKeys

g = GlobalHotKeys()

# 装饰器方式注册
@g.register(GlobalHotKeys.VK_F1, GlobalHotKeys.MOD_SHIFT)
def shift_f1():
    print('Shift+F1')

# 组合键修饰符（支持组合使用）
g.register(GlobalHotKeys.VK_F1, GlobalHotKeys.MOD_CTRL | GlobalHotKeys.MOD_SHIFT)

# 直接调用 register 方法
def handler():
    print('Ctrl+A 被按下')
GlobalHotKeys.register(GlobalHotKeys.VK_A, GlobalHotKeys.MOD_CTRL, handler)

启动监听

# 启动消息循环，开始监听热键
GlobalHotKeys.listen()

停止条件

按以下任意组合键会停止监听循环：

• Q 键
• Ctrl + C

虚拟键码

常用虚拟键码（VK_*）：

按键	键码	组合键
A-Z	VK_A 到 VK_Z	ord('A') 到 ord('Z')
0-9	VK_0 到 VK_9	ord('0') 到 ord('9')
F1-F12	VK_F1 到 VK_F12	-

修饰键（MOD_*）：

修饰键	常量
Alt	MOD_ALT
Ctrl	MOD_CTRL
Shift	MOD_SHIFT
Win	MOD_WIN

修饰键可使用 | 组合，如 MOD_CTRL | MOD_SHIFT。

GuiOperation - 窗口操作

提供 Windows 窗口查找、控制和操作功能。

初始化

from pywayne.gui import GuiOperation

gui = GuiOperation()

find_window

查找包含指定关键字的窗口，返回窗口句柄列表。

# 查找包含"记事本"的窗口
notepad_handles = gui.find_window('记事本')

# 查找包含"微信"的窗口
wechat_handles = gui.find_window('微信')

# 多关键字匹配
handles = gui.find_window('Visual', 'Studio')

参数说明：

• *keys: 按关键字匹配窗口标题

返回值：

• 匹配的窗口句柄列表（hwnd）
• 未找到时返回空列表

get_windows_attr

获取指定窗口的属性信息。

hwnd = gui.find_window('记事本')[0]
title, class_name = gui.get_windows_attr(hwnd)
print(f"窗口标题: {title}")
print(f"窗口类名: {class_name}")

返回值：

• 找到窗口：(窗口标题, 窗口类名)
• 窗口不存在：('', '')

maximize_window

将指定窗口最大化。

hwnd = gui.find_window('记事本')[0]
gui.maximize_window(hwnd)

bring_to_top

将指定窗口置于顶层。

hwnd = gui.find_window('记事本')[0]
gui.bring_to_top(hwnd)

close_window

关闭指定窗口。

hwnd = gui.find_window('记事本')[0]
gui.close_window(hwnd)

change_window_name

修改指定窗口的标题。

hwnd = gui.find_window('记事本')[0]
gui.change_window_name(hwnd, '新标题')

get_window_rect

获取窗口的矩形坐标。

hwnd = gui.find_window('记事本')[0]
rect = gui.get_window_rect(hwnd)
print(f"窗口位置: {rect}")

返回值：(left, top, right, bottom)

get_child_windows

获取指定窗口的子窗口列表。

hwnd = gui.find_window('记事本')[0]
children = gui.get_child_windows(hwnd)
print(f"子窗口数量: {len(children)}")

使用示例

示例 1：热键自动化

from pywayne.gui import GlobalHotKeys

g = GlobalHotKeys()

@g.register(GlobalHotKeys.VK_F10, GlobalHotKeys.MOD_SHIFT)
def screenshot_hotkey():
    print('截图热键被触发')
    # 执行截图逻辑...

@g.register(GlobalHotKeys.VK_Q, GlobalHotKeys.MOD_CTRL)
def copy_hotkey():
    print('复制热键被触发')
    # 执行复制逻辑...

GlobalHotKeys.listen()

示例 2：窗口自动化

from pywayne.gui import GuiOperation
import time

gui = GuiOperation()

# 查找记事本窗口
notepad = gui.find_window('记事本')
if notepad:
    print('未找到记事本')
    exit()

# 置顶并最大化
gui.bring_to_top(notepad[0])
time.sleep(0.5)
gui.maximize_window(notepad[0])

# 修改窗口标题
gui.change_window_name(notepad[0], '自动化控制中...')

示例 3：综合自动化

from pywayne.gui import GuiOperation, GlobalHotKeys
from pywayne.gui import PyMouse, PyKeyboard

gui = GuiOperation()
g = GlobalHotKeys()

@g.register(GlobalHotKeys.VK_F1, GlobalHotKeys.MOD_SHIFT)
def auto_test():
    # 查找测试软件窗口
    st_window = gui.find_window('ST测试软件')
    if not st_window:
        return

    st_hwnd = st_window[0]
    gui.bring_to_top(st_hwnd)

    # 获取子窗口
    for child in gui.get_child_windows(st_hwnd):
        title, cls = gui.get_windows_attr(child)
        print(f'子窗口: {title}')

    # 操作完成后关闭
    gui.close_window(st_hwnd)

GlobalHotKeys.listen()

注意事项

1. 平台限制: 本模块仅支持 Windows 系统
2. 依赖安装: 使用前需确保已安装 pywin32、pyuserinput、pyautogui
3. 管理员权限: 某些操作可能需要管理员权限
4. 窗口状态: 查找和操作仅对可见且启用的窗口有效
5. 热键冲突: 注册的热键可能与其他软件冲突