macOS 键盘党：⌘⌘ cmdcmd 双键，实时秒切换窗口网格预览！安装、使用、配置、源码架构

📝

原文链接：https://mp.weixin.qq.com/s/NXP3pg-e3zHKpuXGEn2X1Q

macOS 键盘党：⌘⌘ cmdcmd 双键，实时秒切换窗口网格预览！安装、使用、配置、源码架构

macOS 用户最头疼的#窗口管理 #痛点:鼠标点来点去、Alt-Tab 切换慢、窗口堆叠看不清……开源项目 cmdcmd（GitHub: peterp/cmdcmd）彻底解决了这个问题。键盘优先的窗口切换器，只需同时轻敲左右两个 ⌘ 键（Command 键），就能瞬间把当前屏幕所有可见窗口“扇形展开”成一个实时预览网格（live previews），通过键盘或鼠标一键直达目标窗口。无需鼠标拖拽、无需第三方工具，完全本地运行，macOS 14+支持。

一、cmdcmd 全部核心功能详尽解析

cmdcmd 的设计理念是极致键盘优先 + 实时预览 + 可持久化，覆盖了几乎所有窗口管理场景：

1.触发机制：

默认 ⌘ + ⌘（同时轻敲左右 Command 键，中间不能有其他按键）。再次按 ⌘+⌘ 或 Esc 关闭覆盖层。支持自定义触发器（如 cmd+shift+space 或 F13），需 Accessibility 权限。

2.覆盖层（Overlay）交互（所有操作实时生效）：

○箭头键 / WASD：移动选中格

○1-9 数字键：直接选中对应格子

○Return：切换到选中窗口

○Space（按住）：Peek 模式，临时放大选中格预览（松开恢复）

○鼠标点击 / 拖拽：直接选中或重新排序格子

○⌘ + 箭头键：与相邻格子交换位置

○⌘W：关闭选中窗口

○⌘Delete：忽略/取消忽略选中窗口（持久化）

○⌘Y：切换“显示隐藏窗口”视图（被忽略窗口以低透明度显示，便于恢复）

○⌘F：进入搜索模式，按 App 名称 + 窗口标题子串匹配过滤格子

○⌥ + G/B/R/Y/O/P：给选中格子打标签（Green/Blue/Red/Yellow/Orange/Purple）

○⌥ + 0：清除标签

○Esc：关闭覆盖层

3.视觉与持久化特性：

○每个格子是实时直播预览（ScreenCaptureKit），支持动态内容更新

○空闲窗口（2.5秒无绘制活动）显示微妙空闲指示点（idle dot）

○格子顺序和忽略窗口按显示器持久化存储在 UserDefaults（tileOrder + ignoredWindows）

○最近使用 App 排序选项（可选）

○动画开关（显示/选中时的缩放过渡）

4.配置系统：

○右键 Dock 图标（⌘⌘） → Open Config… 打开 ~/Library/Application Support/cmdcmd/config.json

○支持自定义绑定、触发器、动画开关

○示例（自动生成，带 // 注释）：

●●●json

`{
       "animations": true,
       "trigger": "cmd-cmd",
       "bindings": {
         "h": "move-left",
         "j": "move-down",
         "k": "move-up",
         "l": "move-right",
         "cmd+x": "close"
       }
     }`

○支持的 Action：pick、dismiss、move-/swap-、pick-1~9、ignore、toggle-hidden、close、search、tag-*/clear 等

○修改后重启生效（或通过 Settings 窗口实时应用部分配置）

5.显示模式：

○Dock（默认）、Menu Bar、Hidden 三种

6.其他：

○Onboarding 首次启动引导权限

○内置 Settings 窗口（动画、实时预览开关）

○拖拽重新排序 + 标签 + 搜索 + 忽略 = 极致自定义

○支持多显示器（独立持久化）

二、安装方法

方式一：直接下载安装

1.访问 GitHub Releases：https://github.com/peterp/cmdcmd/releases

2.下载最新 .zip（v0.2.2+）

3.解压后打开 cmdcmd.app

4.首次启动会弹出 Onboarding 窗口，授予 Screen Recording（实时预览）和 Accessibility（全局热键 + 激活窗口）权限

5.点击 Grant 按钮跳转系统设置，开启后点击 Continue

6.完成后 Dock 出现 ⌘⌘ 图标，即可使用

方式二：从源码编译安装

●●●bash

`git clone https://github.com/peterp/cmdcmd.git
cd cmdcmd
./build-app.sh          # Debug 构建 → cmdcmd.app
# 或
./build-app.sh release  # Release 构建（签名）
open cmdcmd.app`

直接运行二进制：

●●●bash

`swift build
.build/debug/cmdcmd`

构建脚本 build-app.sh 会自动 swift build + ad-hoc codesign + 打包 .app。

make-icon.sh 可重新生成 AppIcon。

项目使用 Swift Package Manager（Package.swift），依赖仅系统框架（AppKit、ScreenCaptureKit 等）。

三、使用方法

1.安装完成后，按 ⌘ + ⌘ 召唤覆盖层。

2.用箭头/WASD 移动，数字键直达，或搜索（⌘F）过滤。

3.按住 Space Peek 快速预览内容。

4.需要忽略烦人窗口？选中后 ⌘Delete。

5.想自定义热键？编辑 config.json，重启即可。

6.多显示器自动适配，每个屏幕独立记忆顺序和忽略列表。

7.右键 Dock 图标可快速打开 Settings/Config/Check Updates。

高级技巧：

●标签颜色快速视觉分类（6 种颜色）

●显示隐藏窗口模式快速恢复被忽略窗口

●空闲点提示帮助识别“卡住”的后台窗口

四、技术原理、架构与实现方式

cmdcmd 架构简洁高效，全部代码位于 Sources/cmdcmd/（~94% Swift），核心文件对应职责：

整体架构图：

●main.swift：入口 + AppDelegate（Dock 菜单、Updater、Display Mode）

●CmdChord.swift：核心触发器

●SpaceTracker.swift：窗口/空间枚举

●Overlay.swift + OverlayView.swift：覆盖层 UI 与逻辑

●Tile.swift：单个实时预览格子

●GridLayout.swift：网格计算

●Config.swift + Keymap.swift：配置与按键映射

●HotkeyMonitor.swift：备用普通热键支持

●Onboarding.swift：权限引导

●其他：HintPill、Log 等辅助

关键技术实现：

1.双 ⌘ 键检测（CmdChord.swift）：

使用 NSEvent 全局/本地监视器 + CGEvent tap（sessionEventTap，listenOnly 模式）。通过 flagsChanged 和 keyDown 事件精确判断左右 Command（kVK_Command / kVK_RightCommand）同时按下且无污染（无其他键）。contaminated 标志确保纯净 chord。比普通热键更优雅，无需额外 Accessibility 之外的权限。

2.窗口枚举与空间感知（SpaceTracker.swift）：

使用私有 CGS/SkyLight API（CGSMainConnectionID、CGSCopyManagedDisplaySpaces、CGSCopySpacesForWindows、CGSGetActiveSpace）获取精确 Space 信息 + CGWindowListCopyWindowInfo（onScreenOnly）。支持多显示器、Space 类型（user/fullscreen/system/tiled）。这比标准 API 更精准地处理 macOS Spaces 切换场景。

3.实时预览实现（Tile.swift + ScreenCaptureKit）：

每个 Tile 创建独立 SCStream，遵循 SCStreamOutput / SCStreamDelegate。使用 CALayer 渲染（content layer + number chip + title pill + idle dot）。内置帧缓存（LRU，限 100 帧）、自动重启流（最多 6 次，处理最小化/DRM/挂起场景）。空闲检测基于 ~2.5s 无绘制活动。支持 DRM 保护内容优雅降级（跳过崩溃帧）。

4.网格布局（GridLayout.swift）：

纯数学计算：根据窗口数量、屏幕宽高比、padding 动态计算 cols/rows + 每格尺寸，确保最佳填充且保持窗口原始 aspect ratio。

5.持久化与配置：

UserDefaults 存储 tileOrder + ignoredWindows（per displayKey = display UUID）。Config.json 使用 JSON + // 注释剥离解析，支持 bindings override。

6.动画与性能：

CATransaction + 自定义 fadeInAndUp 辅助。预热 SCShareableContent，缓存 ShareableContent，异步 refreshAndReconcile（新窗口淡入、关闭窗口淡出）。

7.发布流程：

Changeset 驱动（.changeset/*.md），release.sh 自动 bump 版本、生成 CHANGELOG、appcast.xml、Sparkle 签名、GitHub Release。

权限说明（项目 Onboarding 明确列出）：

●Screen Recording：ScreenCaptureKit 实时捕获

●Accessibility：全局 chord 监听 + 激活目标窗口

项目预发布状态，但已非常稳定（v0.2.x 修复了 phantom tiles、aspect ratio、peek 动画、搜索崩溃等）。