aerospace-macos-setup

AeroSpace macOS 设置

核心工作流

在 macOS 上进行 AeroSpace 实操设置和调试时使用此技能。优先通过已安装的 aerospace CLI 直接验证，而不是凭文档或记忆猜测。

1. 验证安装和运行状态：

command -v brew
brew list --cask nikitabobko/tap/aerospace
aerospace --version

如果 aerospace --version 显示 AeroSpace.app server version: Unknown，说明当前命令上下文无法连接到应用服务器。得出 AeroSpace 已停止的结论之前，先尝试在沙盒外以更高权限运行同一命令。

2. 启动 AeroSpace：

open -a AeroSpace
open -b bobko.aerospace

如果按应用名称启动的结果看起来不对，请使用 bundle id 形式。

3. 如果应用启动后立即退出，请检查辅助功能权限：

open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'

用户必须手动启用 /Applications/AeroSpace.app。此类故障的日志中通常会出现 TCCAccessRequest for kTCCServiceAccessibility。

4. 确认当前配置路径：

aerospace config --config-path

不要假设当前使用的是 ~/.aerospace.toml。在 aerospace reload-config 成功之前，AeroSpace 可能仍在使用 /Applications/AeroSpace.app/Contents/Resources/default-config.toml。

5. 确认当前快捷键绑定：

aerospace config --get mode.main.binding --json

如果缺少预期的快捷键绑定，请重新加载：

aerospace reload-config

用户配置

如果不存在用户配置，请从随附的默认配置创建一份：

cp /Applications/AeroSpace.app/Contents/Resources/default-config.toml ~/.aerospace.toml

编辑 ~/.aerospace.toml，通常在 [mode.main.binding] 下进行。手动编辑时使用 apply_patch。

要将整个应用或工作区移动到另一台显示器，优先移动工作区，而不是窗口：

ctrl-alt-shift-up = 'move-workspace-to-monitor --wrap-around up'
ctrl-alt-shift-down = 'move-workspace-to-monitor --wrap-around down'

对于水平排列的显示器：

ctrl-alt-shift-left = 'move-workspace-to-monitor --wrap-around left'
ctrl-alt-shift-right = 'move-workspace-to-monitor --wrap-around right'

只有在用户明确希望将单个窗口移入目标显示器当前可见的工作区时，才使用 move-node-to-monitor。如果目标工作区已有其他窗口，移动过去的窗口会以一半、三分之一等大小平铺。对于期望“把这个应用扔到另一块屏幕上并保持全尺寸”的用户，move-workspace-to-monitor 更符合他们的使用习惯。

避免将 alt-shift-left/right/up/down 用作全局快捷键。macOS 和文本应用通常会使用 Option + Shift + Arrow 来选择文本或输入特殊字符，因此用户可能会在 Google Docs 中看到文本被选中，或在终端中输入奇怪的字符。 如果终端标签页切换表现异常，避免使用普通的 ctrl-alt-up/down；某些终端或应用的快捷键路径可能会与不够明确的全局快捷键绑定冲突。

自动化测试

优先使用 AeroSpace 自带的测试方式：

aerospace trigger-binding --mode main ctrl-alt-shift-down
aerospace trigger-binding --mode main ctrl-alt-shift-up

然后验证前后状态：

aerospace list-monitors
aerospace list-monitors --focused
aerospace list-windows --focused --format '%{window-id} | %{app-name} | %{window-title} | %{monitor-id}'

此方式会测试已配置的快捷键绑定，无需依赖 macOS 传递实体按键。只有在 trigger-binding 通过后，专门调试操作系统级热键拦截时，才使用真实按键合成。

无需快捷键绑定、直接测试命令：

aerospace move-workspace-to-monitor --wrap-around down
aerospace move-workspace-to-monitor --wrap-around up

应用启动器快捷键

对于简单的应用启动或聚焦快捷键，请使用 AeroSpace exec-and-forget。open -a 会激活已有的应用实例；如果应用未运行，则会启动它。

对于常用应用，优先使用操作轻松的单手快捷键，并重新利用未使用的 AeroSpace 工作区字母：

alt-g = 'exec-and-forget open -a Ghostty'
alt-c = 'exec-and-forget open -a "Google Chrome"'

对于更安全但不够顺手的快捷键：

ctrl-alt-cmd-g = 'exec-and-forget open -a Ghostty'
ctrl-alt-cmd-c = 'exec-and-forget open -a "Google Chrome"'

避免将普通的 cmd-c 和 cmd-g 用作启动器快捷键。cmd-c 表示复制，cmd-g 通常表示查找下一个。只有在用户愿意放弃 AeroSpace 对 C 和 G 的工作区绑定时，才可使用 alt-c 和 alt-g。

无需按下实体按键即可测试启动器快捷键绑定：

aerospace trigger-binding --mode main ctrl-alt-cmd-g
aerospace trigger-binding --mode main ctrl-alt-cmd-c
aerospace trigger-binding --mode main alt-g
aerospace trigger-binding --mode main alt-c

Ghostty 原生标签页

不要反复尝试让 Ghostty 原生 macOS 标签页表现得像一个真正的 AeroSpace 窗口。Ghostty 原生标签页会被 macOS 窗口管理器 API 暴露为独立窗口，因此 AeroSpace 无法可靠地区分“新建标签页”和“新建窗口”。

有关详细的故障历史、临时解决方法和已知无效的修复方案，请阅读 references/ghostty-native-tabs-aerospace.md。

稳定的建议：在 AeroSpace 下避免使用 Ghostty 原生标签页。改用独立的 AeroSpace 工作区或窗口、Ghostty 分屏，或者在单个 Ghostty OS 窗口内使用 tmux 等终端复用器。有关迁移到 tmux 的路径，请阅读 references/tmux-in-ghostty.md。

调试清单

• 如果沙盒中的 CLI 调用无法连接，请在沙盒外运行 aerospace --version。
• 在沙盒外使用 ps -ax 确认 AeroSpace 正在运行。
• 如果启动或辅助功能行为不明确，请查看近期日志：

/usr/bin/log show --last 10m --predicate 'process == "AeroSpace" OR eventMessage CONTAINS "AeroSpace"'

• 每次创建或重新加载配置后，都运行 aerospace config --config-path 检查。
• 运行 aerospace config --get mode.main.binding --json，确认当前运行的服务已识别该绑定。
• 使用 trigger-binding --mode main <binding>，并比较触发前后的焦点窗口 monitor-id。
• 如果用户表示快捷键会输入字符或选中文本，请改用其他绑定，而不是继续调试 AeroSpace 窗口移动功能。
• 如果终端或浏览器的标签页切换异常，请移除基于标签页的默认 AeroSpace 绑定，例如 alt-tab 和 alt-shift-tab。
• 如果焦点或标签页切换时指针似乎会在显示器间移动，请设置 on-focused-monitor-changed = []。
• 如果点击终端标签页似乎会切换显示器，请使用 aerospace list-windows --all 检查所有终端窗口；该应用可能早已将不同窗口或标签页分散在多个显示器上。

辅助脚本

使用 scripts/aerospace_diagnose.sh 获取精简的诊断快照。如果套接字访问或进程列表功能受阻，请在沙盒外运行：

/Users/zakirov/.codex/skills/aerospace-macos-setup/scripts/aerospace_diagnose.sh