Keyhac：Python 脚本化的跨平台键盘自定义工具 #

Keyhac 是什么？ #

Keyhac 是一款用 Python 脚本驱动的键盘自定义工具，能够把系统级键盘钩子交到用户手里，重新定义键盘上每一个按键的行为。你只需编写一个 ~/.keyhac/config.py 文件，就能在 Windows 与 macOS 上运行同一份配置——把按键映射为其他按键、按键序列或 Python 函数，并为不同应用定义独立的按键表。它还内置剪贴板历史、窗口控制、键盘宏与控制台检查器，甚至可以让 AI 助手读取当前屏幕并生成自动化动作，随后脱离 AI 离线运行。对于需要深度定制输入效率、批量操作无 API 应用的用户来说，Keyhac 把键盘变成了一个可编程的自动化入口。

Keyhac 有哪些亮点特色？ #

• Python 脚本化按键：每个按键都能绑定真正的 Python 函数，支持 key → key、key → key 序列、key → Python function 三种映射方式，配置即代码，可版本管理、可复用。
• 一份配置跨平台运行：Keyhac 2 由 Windows（1.x）与 macOS（1.x）两条产品线合并为共享代码库，同一个 config.py 在两大系统上无需修改即可运行，差异部分只需用 keymap.platform 分支处理。
• 按应用独立按键表：可根据应用名、窗口标题、Win32 窗口类，或完整的无障碍焦点路径（macOS 的 AX、Windows 的 UI Automation）精确匹配，甚至能细化到“仅在该应用的文本编辑窗格内生效”。
• 自建修饰键体系：支持用户修饰键（User0–User3），把任意键变成应用不可见的自定义修饰键，还提供“单次修饰键”——轻按触发一次动作，按住则作为修饰键使用。
• 多键序列与 Emacs 风格前缀：支持类似 Emacs 的前缀键序列，并通过气泡提示当前已激活的前缀，无需记忆复杂组合。
• 剪贴板历史与窗口控制：内置持久化剪贴板历史弹窗，支持输入过滤、回车粘贴回原应用；同时提供窗口移动、贴靠/平铺、最小化、激活与启动应用等能力，并感知多显示器。
• AI 辅助编写自动化：连接 Claude Desktop 或任意 MCP 客户端后，AI 可读取当前应用的无障碍树、针对真实元素名编写 Action、运行并读取报错自行修复；生成的动作随后以纯 Python 离线毫秒级运行，无需 token 与模型。
• 控制台检查器与安全设计：控制台窗口提供实时日志、最后按键与焦点路径检查器，帮助你确认到底该绑定什么；AI 集成默认关闭，端点仅监听回环地址、使用启动时生成的令牌、开启一小时后自动关闭。

免费下载 Keyhac #

以下为官方提供的各平台安装包，点击链接即可下载。

提示：Windows 用户也可通过 Microsoft Store 安装（winget install --id 9P8H1PG6PRHH --source msstore），支持自动更新且无 SmartScreen 警告；macOS 用户安装 .dmg 后需在系统设置中授予“辅助功能”权限。

Keyhac 如何使用？ #

1. 首次启动生成配置：第一次运行 Keyhac 时，它会基于一份带完整注释的模板，在 ~/.keyhac/config.py 生成默认配置文件。
2. 打开配置：点击托盘（Windows）或菜单栏（macOS）中的键帽图标，选择“Edit Config”，即可用默认编辑器打开 config.py。
3. 编写按键映射：配置中定义一个 configure(keymap) 函数，在其中通过 keymap.define_keytable() 创建按键表，例如把 Fn-J 映射为 Left，把 Fn-A 映射为 Home + Shift-End 序列，或把 Fn-H 绑定到一个 Python 函数。
4. 按应用定制：使用 app="chrome|Safari" 等条件参数，为特定应用定义专属按键表；也可用 title=、class_name= 或 focus_path_pattern= 做更精细的匹配。
5. 重载与调试：修改保存后，从托盘/菜单栏选择“Reload Config”即可生效；若配置出错，Keyhac 会保留上一份按键映射并在控制台显示错误。控制台窗口（“Open Console”）可实时查看日志、最后按键与焦点路径，帮助你确认绑定目标。

Keyhac 的常见问题？ #

Keyhac 会不会联网或上传数据？ 不会。Keyhac 完全在本机运行，不进行更新检查，也没有任何遥测。键盘钩子固然会“看到”每一次按键，但全部在进程内处理，不存储任何内容；唯二受你控制的例外是键盘宏录制时的内存缓冲，以及你主动开启的剪贴板历史。

为什么 macOS 上第一次启动要授予“辅助功能”权限？ Keyhac 的键盘钩子依赖 macOS 的辅助功能权限才能工作，没有它无法拦截和改写按键。该权限绑定在应用包上，因此后续更新不会丢失。如果你从 Keyhac for macOS 1.x 升级，由于 Keyhac 2 使用独立的应用身份（crftwr.Keyhac2），需要重新授予一次，并建议移除 1.x 的旧条目。

Windows 下 Keyhac 对管理员权限窗口无效怎么办？ 这是 Windows 的安全边界：除非 Keyhac 自身以管理员身份运行，否则它无法看到或修改发往提权窗口的键盘输入。仅当你确实需要在提权应用内使用绑定键时，才以管理员身份运行 Keyhac。

剪贴板历史会把密码也存到磁盘吗？ 剪贴板历史默认写入 ~/.keyhac/clipboard.json（仅文本，单条最多 64 KB）。如果你经常从密码管理器复制密码，可以在 config.py 中设置 keymap.clipboard_history.persist = False 让历史仅保留在内存，或用 keymap.clipboard_history.max_items = 100 限制条数。

AI 集成是否安全、是否必须联网？ AI 集成默认关闭，需要在控制台窗口中手动勾选开启。其本地端点仅监听回环地址，位于启动时生成的令牌之后，并在开启一小时后自动关闭。运行阶段完全不涉及 AI——生成的动作就是普通的 Python 类，在按键上离线、以毫秒级速度运行。

从 Keyhac 1.x 升级后配置还能用吗？ 大部分 keyhac-mac 配置只需少量修改即可运行。已知差异包括：keymap.focus 变为可移植的 Focus（底层 UIElement 通过 keymap.focus.native 访问）、Hook/Console/Chooser/Clipboard 等核心对象不再直接暴露、MoveWindow(...) 已完整移植（签名相同）。Windows 用户的数据目录也从 %APPDATA%\Keyhac 迁移到了 ~/.keyhac，首次运行时会提示复制旧配置，但仍需做一次 API 迁移。

Keyhac 如何安装？ #

macOS（macOS 15 或更高版本） #

1. 下载 Keyhac-<version>-macos.dmg 并打开。
2. 将 Keyhac.app 拖入“应用程序”文件夹并启动。
3. 首次启动时，macOS 会提示授予“辅助功能”权限，前往“系统设置 → 隐私与安全性 → 辅助功能”中勾选 Keyhac（键盘钩子必需，缺此不可用）。
4. Keyhac 是菜单栏应用，出现在菜单栏的键帽图标处，不会显示 Dock 图标。
5. 如需开机自启，在“系统设置 → 通用 → 登录项”中添加 Keyhac.app。

Windows（Windows 10/11，64 位） #

方式一：Microsoft Store（推荐）

1. 打开 Microsoft Store 搜索 Keyhac 安装，或在终端执行：winget install --id 9P8H1PG6PRHH --source msstore。
2. Store 版本可自动更新、没有 SmartScreen 警告，并默认设置为开机启动（可在“设置 → 应用 → 启动”中调整）。

方式二：Zip 绿色包

1. 下载 Keyhac-<version>-win64.zip，解压到任意目录（例如 C:\Program Files\Keyhac 或用户目录下的某个文件夹）。
2. 运行 Keyhac.exe。若 SmartScreen 提示“无法识别的应用”，选择“更多信息 → 仍要运行”。
3. 如需开机自启，把 Keyhac.exe 的快捷方式放入启动文件夹（按 Win-R 输入 shell:startup）。

可移植模式（仅 Windows）：把 config.py 放在 Keyhac.exe 同级目录，该目录即成为数据目录，配置、剪贴板历史和设置全部保存在可执行文件旁，不写入用户配置文件——适合 U 盘携带或多套独立环境并存。

Keyhac 如何卸载？ #

macOS #

1. 退出 Keyhac（菜单栏图标 → Quit Keyhac）。
2. 删除“应用程序”中的 Keyhac.app。
3. 删除配置与数据目录 ~/.keyhac。
4. 前往“系统设置 → 隐私与安全性 → 辅助功能”，移除其中的 Keyhac 条目。

Windows（Microsoft Store 版本） #

1. 退出 Keyhac（托盘图标 → Quit Keyhac）。
2. 在“设置 → 应用 → 已安装的应用”中卸载 Keyhac，或执行 winget uninstall Keyhac。
3. 删除数据目录 ~/.keyhac。

Windows（Zip 绿色版） #

1. 退出 Keyhac（托盘图标 → Quit Keyhac）。
2. 删除解压出来的 Keyhac 程序目录。
3. 删除数据目录 ~/.keyhac；若你使用了可移植模式，数据目录即程序目录，会随程序目录一并删除。
4. 如果曾把快捷方式放入启动文件夹，记得一并移除。

说明：若启用了可移植模式，控制台窗口的记住位置（HKCU\Software\PuiKit\FrameAutosave）与 keyhac-error.log 是少数仍位于程序目录之外的内容，前者不影响使用，后者的日志文件可手动删除。