Hammerspoon 是一款免费、MIT 许可的 macOS 应用，将系统能力（窗口、屏幕、热键、应用与硬件事件、任务、提醒）通过 Lua 暴露出来。其配置位于 ~/.hammerspoon/init.lua。本技能通过 Hammerspoon 自带的 hs 命令行工具（基于 hs.ipc）驱动正在运行的应用，并以小型模块文件管理持久化行为，从而不重写用户已有配置。技能已在 macOS 27（arm64）上的 Hammerspoon 1.1.1 验证。
用途与两种执行方式： 本技能提供脚本 scripts/hsctl.py（基于 Python 3.9+ 标准库），用于与运行中的 Hammerspoon 交互。有两种完成任务的方式：一次性 Lua 代码（通过 hsctl.py run 或 inventory）适合查询问题（“哪些窗口开在哪里？”）或执行一次操作（“现在平铺这些窗口”），但不会在重载或重启后保留；代理模块（通过 hsctl.py install NAME file.lua）适合需要持续工作的功能，如热键、监视器或绑定到按键的布局，模块文件位于 ~/.hammerspoon/agent/NAME.lua，重载后依然有效。
主要能力：
- 检查环境：hsctl.py check 输出 JSON 并列出问题，包括 Hammerspoon 未安装、未启用 IPC、未授予辅助功能权限。
- 查询实时状态：hsctl.py inventory 列出屏幕、常规应用和标准可见窗口，--all 包含最小化、非标准及后台应用；run 可执行一次性 Lua 代码并返回 JSON 或文本。
- 安装持久模块：install 会进行语法检查、复制文件、重载并返回加载报告；首次使用时在 init.lua 末尾添加标记块并备份原文件。
- 调用模块动作：call NAME FUNC 可立即执行模块中定义的函数并打印返回值。
- 管理模块：list 列出模块、导出函数和活动热键；remove 删除模块并重载；disable-all/enable-all 批量停用/启用；restore 恢复 init.lua 备份；reload/restart 重载或重启。
- 查看错误：console --errors 显示错误行和堆栈，console -n 查看最近控制台输出。
使用方式：
- 运行 python3 scripts/hsctl.py check 检查环境，按提示修复问题（安装 Hammerspoon、启用 IPC、授予辅助功能权限）。
- 使用 inventory 回答窗口/屏幕查询，或使用 run -e 'return ...' 执行一次性 Lua。
- 需要持久行为时，编写返回表的 Lua 模块，将动作放在命名函数中，热键和监视器引用保存在模块表上，然后 install 并 call 验证效果。
- 安装后通过 list、inventory 或动作副作用确认效果，并可用 console --errors 检查回调错误。
适用场景与限制： 适用于 macOS 窗口管理自动化、多显示器布局、热键触发脚本、应用监视等。限制包括：需要用户手动授予辅助功能权限，否则 Hammerspoon 只能看到自身窗口且无法移动任何窗口；一次性 Lua 不会持久化；run 有 10 秒超时，且 Hammerspoon 单线程，慢操作会阻塞应用；热键回调无法通过模拟按键触发，需用 call 测试；应用匹配应使用 bundle ID 而非本地化名称；屏幕查找应使用名称模式并准备回退。详细 API、完整模块示例和常见问题见技能内参考文档。