用途：在 macOS 上通过命令行与 Hammerspoon 交互，完成一次性动作或配置持久自动化。
主要能力：一次性调用用 hs -q -c '<lua>'，可执行启动、退出或聚焦应用和浏览器标签，以及音量、Wi-Fi、caffeinate、提醒和剪贴板等操作；需要持续生效的热键、watchers、菜单栏项则写成 ~/.hammerspoon/ 下的模块。使用前先确认就绪：hs -q -c 'return "ok"' 须输出 ok。若退出码 69 或提示 can't access message port，说明 Hammerspoon 未运行或 hs.ipc 未加载，可 open -a Hammerspoon，并在 ~/.hammerspoon/init.lua 中确保 require("hs.ipc")。hs 命令缺失时，让用户在 Hammerspoon 控制台运行 hs.ipc.cliInstall("/opt/homebrew")。窗口或应用调用静默无效时，hs -c 'return hs.accessibilityState()' 须为 true，否则到系统设置中授予辅助功能权限。
使用方式要点：需要返回最终值才有输出；表会打印为地址，可用 hs.json.encode(tbl) 输出，几何矩形需 .table。shell 参数用单引号，Lua 内用双引号。多行可用 heredoc hs -q <<'EOF' … EOF，或 hs -q /path/file.lua，路径须以 ~、./ 或 / 开头。退出码 65 表示 Lua 错误，69 表示未运行或 ipc 缺失。一次性调用创建的 timers、watchers、callbacks 会被回收、不会触发，需持久则用持久模式。异步状态（焦点切换、标签加载）不会在单个代码块内稳定，shell 中 sleep 后再用下一次调用读取。
持久模式：写 ~/.hammerspoon/<name>.lua，并在 init.lua 中 require("<name>")。先读 ~/.hammerspoon/AGENTS.md 了解约定。timers、watchers、menubar 对象须挂到全局或模块级变量以免被 GC。pathwatcher 每次保存都会重载，应写完整文件并用完整写入而非增量编辑；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/clicks 作用于当前焦点，仅应在用户明确要求时使用。此为 macOS 主机范围内技能，Linux 等其它主机上应保持禁用；具体价格、平台范围等资料暂未提供。