hammerspoon

hammerspoon

主机范围：mini/macOS。请在 joi/Linux 上禁用此技能；共享源文件可以保留在仓库中。不要在主机之间同步激活链接，也不要仅仅因为本地主机没有 Hammerspoon 就切换到 SSH。远程操作遵循会话的主机授权策略。

一次性操作 = 一次 hs -q -c '<lua>' 调用。持久行为（快捷键、监视器、菜单栏）= ~/.hammerspoon/ 中的模块。操作示例：REFERENCE.md。

就绪状态

hs -q -c 'return "ok"' 必须打印 ok。如果没有：

• 退出码 69 / "can't access message port" → Hammerspoon 未运行（open -a Hammerspoon），或未加载 hs.ipc → 确保 ~/.hammerspoon/init.lua 中有 require("hs.ipc")；pathwatcher 会自动重新加载配置，约 2 秒后重试。
• 缺少 hs 二进制文件 → 告诉用户在 Hammerspoon 控制台中运行 hs.ipc.cliInstall("/opt/homebrew")。
• 窗口/应用调用静默无效 → hs -c 'return hs.accessibilityState()' 必须返回 true；如果为 false，请用户在“系统设置”→“隐私与安全性”→“辅助功能”中授予权限。

一次性模式

hs -q -c 'hs.application.launchOrFocus("Obsidian") return "ok"'
hs -q -t 15 -c '<anything touching AppleScript or many windows>'   # default IPC timeout is 4s; busy main loop can also cause one-off "receive timeout" — retry

• return 最终值，否则不会有输出；表会打印为地址 — return hs.json.encode(tbl)（hs.geometry 矩形需要 .table；NaN 值会导致 encode 静默返回 nil — tostring() 是安全的回退方案）。
• Shell 参数用单引号括起来，Lua 内部使用双引号。多行内容：使用 heredoc hs -q <<'EOF' ... EOF，或 hs -q /path/file.lua（路径必须以 ~、./ 或 / 开头）。
• 退出码：65 = Lua 错误（错误信息在 stderr 中），69 = 未运行 / 缺少 ipc。
• 一次性状态会消失：通过 hs -c 创建的计时器、监视器和回调会在调用结束后被 GC 回收，永远不会触发 — 任何必须持久存在或稍后触发的内容都应使用持久模式。
• 顺序执行：异步状态（焦点变化、标签页加载）不会在单个代码块内稳定下来，而且 hs.timer.usleep 会阻塞 Hammerspoon 本身。一次调用中执行操作，在 shell 中 sleep，然后在下一次调用中读取状态。

持久模式

对于快捷键/监视器/菜单栏项目：编写 ~/.hammerspoon/<name>.lua，并将 require("<name>") 添加到 ~/.hammerspoon/init.lua。请先阅读 ~/.hammerspoon/AGENTS.md — 其中包含项目惯例。

• 将计时器/监视器/菜单栏对象保存在全局变量或模块级变量中，否则 GC 会静默销毁它们。
• 每次保存文件，pathwatcher 都会重新加载配置 — 请一次性写入完整文件（使用 Write，而非增量编辑），并注意 hs.reload() 会清除所有交互式全局变量。
• 保存后验证：hs -q -c 'return "alive"'（重新加载约需 1–2 秒），然后通过 hs -q -c 'return hs.console.getConsole()' | tail -20 检查是否存在加载错误。

安全

• 优先使用 :kill()（正常退出），而非 :kill9()；退出可能有未保存内容的应用前，请先向用户确认。
• 绝不要打开模态对话框（hs.dialog）或在其他应用中触发警报 — 它们会阻塞事件处理。
• hs.execute 会阻塞 Hammerspoon 的主循环（导致其所有快捷键/菜单栏冻结）；优先直接运行 shell 命令，或在模块中使用 hs.task。
• hs.eventtap.keyStrokes/点击会发送到当前获得焦点的对象 — 仅在用户明确要求执行相应操作时使用。