macOS 修饰键映射器

一个轻量的 Python/Tk GUI，小窗即可切换 Command / Control / Option 的行为。只在窗口打开且点击"开始映射"时生效，适合在 Windows 端远程控制 macOS 时临时把 Ctrl 当成 Command，也适合用 Mac 键盘远控 Windows 时快速调换三大键。

项目结构与说明

key_mapper_py/
├── pyproject.toml         # 项目元数据、依赖定义，uv 使用
├── uv.lock                # 锁定依赖版本
├── README.md              # 使用说明、打包指南（本文档）
├── KeyMapper.spec         # PyInstaller 打包配置，生成 .app/.exe
├── .gitignore             # Git 忽略规则
├── src/
│   ├── key_mapper.egg-info/ # 构建/安装生成的包元数据（自动生成，可不提交）
│   └── key_mapper/
│       ├── __init__.py    # 包初始化
│       └── main.py        # GUI 与按键重映射核心逻辑
├── dist/                  # 打包产物输出（PyInstaller 生成，可忽略提交）
├── build/                 # PyInstaller 中间文件（可清理）
└── .venv/                 # 虚拟环境（忽略提交，uv 创建）

环境准备

项目已自带 pyproject.toml，请用已安装的 uv：

uv sync

首装会拉取 pyobjc 组件（允许 uv 访问网络）。生成的虚拟环境位于 .venv/。

运行

uv run key-mapper

首次运行会弹出辅助功能权限请求；若未弹出，可在 系统设置 → 隐私与安全性 → 辅助功能 中手动勾选终端（或 .venv/bin/python）。

使用说明

• 为 Command/Control/Option 选择目标：Command (⌘) / Control (⌃) / Option (⌥) / 不改动。
• 默认映射：Command → Control，Control → Command，Option 保持不变，适合 Mac 键盘远程 Windows；若 Windows 键盘远程 Mac，可将 Command 设为“不改动”、Control 设为 Command (⌘)，让常用 Ctrl 快捷键触发 Command。
• 点击“开始映射”启用；点击“停止”或关闭窗口即停用，进程退出也会自动关闭监听，状态提示在窗口下方。
• 不修改系统设置、不常驻后台，关闭窗口或退出进程后不再拦截按键。
• 若终端出现 IMKCFRunLoopWakeUpReliable 之类的提示，这是 macOS 输入法的噪声日志，已在程序内做了初始化处理，可忽略，不影响功能。

打包成 macOS 应用

已内置 PyInstaller 的配置文件 KeyMapper.spec，默认应用名与图标（根目录 round.png/logo.icns）都已写好，带隐藏依赖声明（Quartz/CoreFoundation）。推荐步骤：

1. 安装打包器（一次即可）：

uv add pyinstaller

2. 生成 .app 和单文件可执行：

uv run pyinstaller KeyMapper.spec

产物：

• dist/macOS 修饰键映射器.app：双击运行，首次需在“隐私与安全性”允许。
• dist/macOS 修饰键映射器：单文件可执行。

3. 自定义图标（可选）：

   • 方式 1：直接替换根目录的 logo.icns
   • 方式 2：修改 logo.iconset/ 中的 PNG 图标源文件，然后重新生成：

     iconutil -c icns logo.iconset

   • 之后重新运行打包命令即可

4. 清理（可选）：rm -rf build KeyMapper.spec~。

若之前遇到 “No EXECUTABLE entry found in the TOC!” 报错，已修正 spec，直接重新运行上面的命令即可。

常见问题

• 提示无法创建事件监听：通常是辅助功能权限未开启，授予后重新点"开始映射"即可。
• 想恢复原样：选择"停止"或把三个选择都设为"不改动"。

开源许可

本项目采用 MIT License 开源。