mcpField
H
hammerspoon-macos-setup

hammerspoon-macos-setup

github.com/arthurzakirov生产力197 次安装2 周前更新
代码仓库

关于 hammerspoon-macos-setup

hammerspoon-macos-setup 是用于在 macOS 安装和管理模块化 Hammerspoon 配置的 Agent 技能，涵盖初始化、窗口与显示器快捷操作及运行状态核验。

主要功能

  1. 01安装或刷新配置
  2. 02备份受管理的配置
  3. 03模块化窗口与显示器控制
  4. 04Spaces 和窗口快捷键
  5. 05运行状态与操作核验

适用场景

  1. 01在 macOS 配置 Hammerspoon
  2. 02跨显示器排列窗口
  3. 03查找并聚焦窗口
  4. 04权限变更后检查快捷键操作

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/arthurzakirov/agentdesk --skill hammerspoon-macos-setup

安装后在 Claude Code 中输入/hammerspoon-macos-setup确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
assets/hammerspoon/
init.lua
assets/hammerspoon/modules/
chrome.lua
claude.lua
core.lua
displays.lua
layout.lua
spaces.lua
window_picker.lua
scripts/
install-hammerspoon-config.sh

详细介绍

Hammerspoon macOS 设置

请将随附的模块化配置作为唯一事实来源。它将显示器移动、窗口布局、Spaces、窗口选择器、Chrome 和 Claude 桌面行为分别放在 assets/hammerspoon/modules/ 下。

安装或刷新

运行：

scripts/install-hammerspoon-config.sh

安装程序：

  • 要求使用 macOS 和 Homebrew；
  • 如果尚未安装 Hammerspoon，则进行安装；
  • 更改现有受管理配置前先备份；
  • 将 ~/.hammerspoon/init.lua 和 ~/.hammerspoon/modules 符号链接到此技能随附的资源，同时保留 Spoons/ 等无关条目；
  • 启动 Hammerspoon，并通过配置启用登录时启动。

这些符号链接使已安装的 AgentDesk 技能成为实时事实来源。更新仓库检出内容或刷新 SkillPort 后，稳定路径指向的文件也会随之更新；按 ctrl+alt+cmd+r 重新加载 Hammerspoon 以应用新版本。如果链接已指向此技能版本，重新运行安装程序不会产生额外变更。

不要将凭据、私人设备清单、显示器序列号或账户数据复制到此公开配置中。显示器编号根据虚拟桌面位置动态分配。

权限

Hammerspoon 需要 macOS 辅助功能权限。权限被停用时，请打开系统设置 → 隐私与安全性 → 辅助功能。通过 Computer Use 启用此设置需要在操作时确认。

更改权限后，重新启动 Hammerspoon。权限行显示已勾选并不足以证明权限可用：请验证 hs.accessibilityState() 并执行一次实际窗口操作。

必备快捷键

  • ctrl+alt+left、ctrl+alt+right、ctrl+alt+return：左半屏、右半屏、最大化。
  • ctrl+alt+cmd+j/k/l/ö：将窗口发送到显示器 1–4 并最大化，顺序为从左到右、从上到下。
  • ctrl+alt+cmd+u/i/o/p：聚焦显示器 1–4。
  • ctrl+alt+cmd+h：标识编号显示器。
  • ctrl+alt+cmd+/：可搜索的窗口选择器。
  • ctrl+alt+cmd+r：重新加载配置。

显示器模块会优先使用标准 macOS **窗口 → 移至…**菜单。这样可以避免 macOS Tahoe 的一种故障模式：辅助功能报告的 AXApplication 占位对象大小为零，而不是可用的窗口对象。对于没有标准菜单的应用，则会回退到直接使用 hs.window 移动窗口。

验证

检查运行时状态：

/opt/homebrew/bin/hs -c 'return tostring(hs.accessibilityState()) .. "|" .. tostring(hs.autoLaunch()) .. "|" .. tostring(#hs.hotkey.getHotkeys())'

然后向一个临时的可见窗口发送实际快捷键，并在每次按键后验证可观察到的结果：

  1. 目视确认左半屏、右半屏和最大化效果。
  2. 对每个已连接的显示器按键进行确认：移动后，检查目标显示器是否已从应用的**移至…**菜单中消失。
  3. 未连接的第四台显示器应视为未经测试；不要声称窗口已成功移动到该显示器。
  4. 故障排除后，确认 AltTab 和任何用户要求的启动器仍在运行。

不能仅因为快捷键已注册或函数返回时没有错误就报告成功。

评论

支持 Markdown