关于mac版本快捷键无法使用单个修饰键作为快捷键

[woaiCarlos]

大部分使用场景下，vibe codding比较多，为了使用起来方便希望可以添加mac电脑版本，可以使用单个修饰键作为快捷键的功能

---------来自创世会员

[woaiCarlos]

问题分析

通过代码审查和实际测试，找到原因并验证了解决方案。

根本原因

项目使用 keyboard==0.13.5 库（位于 app/hotkeys.py）来注册快捷键：

hotkey_id = keyboard.add_hotkey(combo, callback)

keyboard 库在 macOS 上无法捕获单个修饰键（ctrl、alt/option、cmd、shift），原因：

1. macOS 系统会优先处理单个修饰键事件
2. keyboard 库依赖系统级键盘钩子，但 macOS 窗口管理器会拦截这些按键

解决方案

实测 pynput 库可以捕获单个修饰键！

测试代码

创建虚拟环境并安装 pynput：

python3 -m venv pynput_test_env
./pynput_test_env/bin/pip install pynput

测试脚本 test_modifier_keys.py：

#!/usr/bin/env python3
"""
测试 pynput 能否在 macOS 上捕获单个修饰键
"""
import sys
print(f"Python: {sys.version}")

try:
    from pynput import keyboard
    print("✅ pynput imported successfully")
except ImportError as e:
    print(f"❌ Import failed: {e}")
    sys.exit(1)

print("\n监听中...")
print("- 按下单个修饰键 (ctrl, alt/option, cmd, shift)")
print("- 按 ESC 键退出程序")

modifier_keys_pressed = set()

def on_press(key):
    global modifier_keys_pressed
    try:
        key_name = key.char if hasattr(key, 'char') and key.char else str(key)
    except:
        key_name = str(key)
    
    is_modifier = False
    modifier_name = None
    
    if hasattr(key, 'vk'):
        vk = key.vk
        if vk in (0x3B,):  # ctrl
            modifier_name = "CTRL"
            is_modifier = True
        elif vk in (0x3A,):  # alt/option
            modifier_name = "OPTION"
            is_modifier = True
        elif vk in (0x37,):  # cmd
            modifier_name = "CMD"
            is_modifier = True
        elif vk in (0x38,):  # shift
            modifier_name = "SHIFT"
            is_modifier = True
    
    if is_modifier:
        modifier_keys_pressed.add(modifier_name)
        print(f"🔵 修饰键按下: {modifier_name} (vk={vk})")
    else:
        if modifier_keys_pressed:
            print(f"📝 普通键按下: {key_name} | 当前修饰键: {modifier_keys_pressed}")
        else:
            print(f"📝 普通键按下: {key_name}")

def on_release(key):
    global modifier_keys_pressed
    try:
        key_name = key.char if hasattr(key, 'char') and key.char else str(key)
    except:
        key_name = str(key)
    
    is_modifier = False
    modifier_name = None
    
    if hasattr(key, 'vk'):
        vk = key.vk
        if vk in (0x3B,):
            modifier_name = "CTRL"
            is_modifier = True
        elif vk in (0x3A,):
            modifier_name = "OPTION"
            is_modifier = True
        elif vk in (0x37,):
            modifier_name = "CMD"
            is_modifier = True
        elif vk in (0x38,):
            modifier_name = "SHIFT"
            is_modifier = True
    
    if is_modifier:
        modifier_keys_pressed.discard(modifier_name)
        print(f"🔴 修饰键释放: {modifier_name} (vk={vk})")
    else:
        print(f"📝 普通键释放: {key_name}")

with keyboard.Listener(
    on_press=on_press,
    on_release=on_release,
    suppress=False
) as listener:
    listener.join()

运行测试：

./pynput_test_env/bin/python3 test_modifier_keys.py

测试结果

✅ macOS 14.x 实测通过：按下/释放单个修饰键（option、ctrl、cmd、shift）均能被 pynput 正确识别！

建议修改

将 app/hotkeys.py 中的 keyboard 库替换为 pynput，同时更新 requirements.txt 中的依赖即可支持 macOS 单个修饰键快捷键。