# SlowQ
**Repository Path**: pandaboby/SlowQ
## Basic Information
- **Project Name**: SlowQ
- **Description**: SlowQ(慢Q)—— 防止误触 Command+Q 退出的 macOS 菜单栏工具
- **Primary Language**: Swift
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-21
- **Last Updated**: 2026-09-26
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README

# SlowQ · 慢Q
**防误触退出助手**
> 退一步,再确认。
一个接管全局 ⌘Q 的 macOS 原生菜单栏工具
[](#系统要求)
[](#项目结构)
[](#工作原理)
[](LICENSE)
[](https://github.com/PandaBoby/SlowQ/stargazers)
**中文** · [English](README.en.md)
---
## 这是什么
在 macOS 上,`⌘Q` 会**立刻**退出当前应用——正在编辑的文档、没保存的草稿、跑着的任务,一次误触就没了。
SlowQ(慢Q)把 `⌘Q` 变成"需要按住"的操作:按下时屏幕中央浮出倒计时圆环,**按住满 3 秒**才真正退出,**中途松手立即取消**。它通过系统级事件拦截接管**所有应用**的 `⌘Q`,无需逐个配置。
> 灵感来自 Chrome 的 "Hold ⌘Q to quit"。
## 特性
| | |
|---|---|
| 🌐 **全局接管** | 基于 `CGEventTap` 的系统级拦截,对任意应用生效,无需逐应用设置 |
| ⏱️ **可调时长** | 菜单栏一键切换 1 / 2 / 3 / 5 秒,设置自动记忆 |
| 🎨 **精致 HUD** | 深色毛玻璃卡片 + 弹性入场动画 + 蓝→红渐变进度环 + 即将触发时的脉冲光晕 |
| 🔒 **隐私优先** | 日志默认关闭;开启后也只记录 `⌘Q` 事件,绝不落盘其他按键 |
| 🪶 **轻量常驻** | 菜单栏应用,不占 Dock;动画循环仅在 HUD 显示时运行,空闲零开销 |
| 🚫 **可随时停用** | 菜单栏一键暂停拦截;支持 5/15/60 分钟定时暂停并自动恢复 |
| 🚀 **登录自启** | 可设为登录时自动启动,常驻守护不用手动打开 |
| 🙈 **图标可隐藏** | 隐藏菜单栏图标;每次启动保留 10 秒逃生窗口,不会「藏丢」 |
## 效果
按下 `⌘Q` 时,屏幕中央出现这样的浮层(圆环随进度由蓝转红填充):
```text
╭──────────────────────────╮
│ ⌘ │
│ ╭──────╮ │
│ ╱ ╲ │
│ │ 2.4 │ │
│ ╲ ╱ │
│ ╰──────╯ │
│ │
│ 按住 ⌘Q 退出 │
╰──────────────────────────╯
```
- **按住到 0.0** → 底部文案变为「松开以退出」,松手后应用退出
- **提前松手** → 浮层淡出,什么都不会发生
## 系统要求
- macOS **13 (Ventura)** 或更高
- 构建需要 Xcode Command Line Tools(`xcode-select --install`)
## 安装
### 方式一:下载预编译包(推荐)
从 [**Releases**](https://github.com/PandaBoby/SlowQ/releases/latest) 下载(Gitee 镜像同步发布:[**Gitee Releases**](https://gitee.com/pandaboby/SlowQ/releases)):
| 文件 | 说明 |
|---|---|
| `SlowQ-x.y.z-macos-universal.dmg` | 推荐。打开后把 SlowQ 拖进 Applications |
| `SlowQ-x.y.z-macos-universal.zip` | 解压后把 `SlowQ.app` 拖进 Applications |
> **通用二进制**,同时支持 Apple Silicon 与 Intel Mac。
**首次打开必读 ⚠️** —— 本应用未做 Apple 开发者签名与公证(需 99 美元/年的账号),macOS 会拦截首次启动。执行一次即可:
```bash
xattr -dr com.apple.quarantine /Applications/SlowQ.app
```
或者在 Finder 里**右键**点 `SlowQ.app` → **打开** → 在弹窗里再点 **打开**。
> 若提示「已损坏,无法打开」,说明右键方式不适用,请用上面的 `xattr` 命令。
### 方式二:从源码构建
```bash
git clone https://github.com/PandaBoby/SlowQ.git # 或 Gitee: https://gitee.com/pandaboby/SlowQ.git
cd SlowQ
./build-app.sh # 构建通用二进制并打包为 SlowQ/.build-app/SlowQ.app
open SlowQ/.build-app/SlowQ.app
```
需要 Xcode Command Line Tools(`xcode-select --install`)。`build-app.sh` 会自动完成:生成菜单栏图标 → 编译(arm64 + x86_64)→ 打包 `.app` → 生成 `.icns` → adhoc 签名。
> 开发构建产物放在隐藏目录 `.build-app/` 下,Spotlight 不索引点号目录,因此它**不会出现在 Launchpad 或 Finder 搜索里**,不会和 `/Applications` 里的正式版重复。
发布打包用 `./release.sh`(产出 zip/dmg 到 `dist/`):
```bash
./release.sh --publish # 发布 GitHub Release
./release.sh --gitee # 发布 Gitee Release(需 ~/.token/gitee-token)
./release.sh --publish --gitee # 两边同时发布
```
## ⚠️ 首次运行必须授权
macOS 要求拦截全局键盘事件的应用获得**辅助功能**权限,否则拦截完全不生效:
1. 启动 `SlowQ.app`(中文系统显示为「慢Q」)
2. 打开 **系统设置 → 隐私与安全性 → 辅助功能**
3. 找到 **慢Q**(英文系统显示 **SlowQ**)并勾选 —— 若列表中没有,点 `+` 手动添加 `/Applications/SlowQ.app`(开发构建为 `SlowQ/.build-app/SlowQ.app`)
4. SlowQ 会**自动检测**到授权并立即生效,无需重启
授权成功后菜单栏出现蜗牛图标。验证是否生效:看 `~/Library/Logs/SlowQ.log` 是否出现 `event tap 安装成功`(需先开启日志,见下)。
## 使用
**拦截 ⌘Q**
- 任意应用按 `⌘Q` → 浮层出现 → 按住满设定时长 → 松手退出该应用
- 中途松手 → 取消
**菜单栏图标**
| 菜单项 | 作用 |
|---|---|
| 停用 / 启用拦截 ⌘Q | 临时关闭拦截(如需要连续退出多个应用) |
| 暂停拦截 → 5 / 15 / 60 分钟 | 定时暂停,**到点自动恢复**,菜单里实时显示剩余时间 |
| 按住时长 → 0.5/1/2/3/5 秒 | 调整长按时长,自动记忆 |
| 登录时自动启动 | 开机自动运行(基于系统 `SMAppService` 登录项) |
| 隐藏菜单栏图标 | 隐藏菜单栏图标,适合不想让它占菜单栏空间的用户 |
| 关于 慢Q | 查看版本与项目地址 |
| 退出 慢Q (⌥⌘Q) | 退出 SlowQ 自身(用 `⌥⌘Q` 避免被自己拦截) |
**关于「隐藏菜单栏图标」的找回方式**
图标隐藏后拦截**依然生效**,只是菜单栏上没有入口了。找回方式:
> ### 🐌 再次打开 慢Q 即可
> 在 **启动台 / 应用程序文件夹 / Dock** 里再点一次 慢Q(即使它已经在后台运行),
> 菜单栏图标就会立刻回来,同时**屏幕顶部中央**会弹出一条「菜单栏图标已恢复」的提示。
几个细节:
- 点击隐藏时,**屏幕顶部中央**会立刻弹出**「菜单栏图标已隐藏 · 再次打开 慢Q 即可恢复」**的提示条,当场告诉你找回路子
- 重新打开**不会**启动第二个进程 —— 只是把图标显示回来,并自动清除「隐藏」设置
- 另外每次启动应用时,图标都会先显示 **10 秒**;这 10 秒内打开一次菜单也会取消隐藏
> 实现细节:macOS 会把状态栏项的可见性持久化到应用偏好里(`NSStatusItem VisibleCC …`),隐藏过一次后,重启时新建的实例默认仍是隐藏的 —— 所以代码里每次启动都显式置为可见,并实现了 `applicationShouldHandleReopen` 来响应"再次打开应用"。
## 工作原理
```text
物理 ⌘Q
│
▼
┌─────────────────────────────┐
│ CGEventTap │ ← session 级、head insert,先于所有应用拿到事件
│ (keyDown / keyUp / flags) │
└─────────────┬───────────────┘
│ 吞掉 ⌘Q,启动计时
▼
┌───────────────┐
│ 状态机 │ idle → holding → fired
│ holding 期间 │ 吞掉所有 key repeat
└───────┬───────┘
│ 计时达到阈值
▼
┌───────────────┐
│ 向最前台应用 │ postToPid 投递一次合成 ⌘Q
│ 投递合成 ⌘Q │ (投递期间暂停 tap,避免自我拦截)
└───────────────┘
```
几个关键设计:
- **key repeat 必须吞掉**:按住键时系统会持续补发 `keyDown`,只拦第一个会导致应用被后续 repeat 立刻退出 —— 早期版本的"不生效"就是这个 bug
- **`postToPid` 而非 `CGEventPost`**:定向投递给目标进程,不经会话 tap,因此不会与自身拦截形成循环
- **暂停窗口兜底**:投递合成事件时 tap 会短暂停用,期间到达的**物理** `⌘Q` 同样被吞掉,防止绕过
- **授权轮询**:启动时若未授权则每秒检测,授权后自动装载 tap,无需重启
## 配置
设置通过 `UserDefaults`(domain `com.slowq.app`)持久化:
```bash
defaults write com.slowq.app holdSeconds -float 3 # 长按时长(秒)
defaults write com.slowq.app statusIconTemplate -bool true # 强制菜单栏图标为单色(默认:自动识别)
defaults write com.slowq.app debugLog -bool true # 调试日志(默认关闭)
# 查看日志
tail -f ~/Library/Logs/SlowQ.log
```
## 项目结构
```text
SlowQ/
├── build-app.sh # 一键构建:图标 → 编译 → 打包 → 签名
├── tools/
│ ├── gen-statusbar.swift # 菜单栏图标生成器(裁透明边距 + 等比缩放)
│ └── gen-appicon.swift # App 图标生成器(保持宽高比,避免拉伸)
├── SlowQ/
│ ├── Package.swift # SwiftPM 清单
│ ├── SlowQ.png / .svg # 图标源(替换后重新构建即可换图标)
│ └── src/
│ ├── main.swift # 入口
│ ├── AppDelegate.swift # 事件拦截 + 状态机 + 菜单栏 + HUD
│ └── Resources/ # 生成好的菜单栏图标(1x / 2x)
└── README.md / README.en.md
```
## 故障排查
**拦截不生效**
1. 确认菜单栏有 SlowQ 图标(没有说明进程没起来)
2. 检查辅助功能权限是否被勾选
3. **重新构建后权限可能失效**:adhoc 签名会随二进制变化,导致 macOS 认为这不是同一个应用。修复:
```bash
tccutil reset Accessibility com.slowq.app
# 然后重新打开 SlowQ,在系统设置中重新勾选
```
> 实测:仅"关掉开关再打开"**不足以**恢复授权,必须 `tccutil reset` 后重新勾选。
**菜单栏图标在深色菜单栏下看不清**
SlowQ 使用**自动**模式:若图标本身是单色(如纯黑剪影),会自动作为模板图使用,由系统按菜单栏明暗渲染(深色→白色、浅色→黑色),不会出现黑图标配黑背景;有真实彩色的图标则保留原色。
只有当你在终端手动设过 `defaults write com.slowq.app statusIconTemplate -bool false`(强制彩色)且图标恰好是纯黑时才可能隐形,恢复自动:
```bash
defaults delete com.slowq.app statusIconTemplate
```
**想换图标**
替换 `SlowQ/SlowQ.png`(建议 1024×1024 或更高的透明背景 PNG)后重新运行 `./build-app.sh`。
## 开发
```bash
cd SlowQ
swift build # 调试构建
swift build -c release # 发布构建
```
改完源码后跑 `./build-app.sh` 重新打包;改了图标源则重复同样命令即可。
## 命名与品牌
| 项 | 内容 |
|---|---|
| 应用名 | SlowQ |
| 中文名 | 慢Q |
| 中文副标题 | 防误触退出助手 |
| App Store 标题 | 慢Q - 防误触退出 |
| GitHub 描述 | SlowQ(慢Q)—— 防止误触 Command+Q 退出的 macOS 菜单栏工具 |
| 中文 Slogan | 退一步,再确认。 |
| 英文 Slogan | Slow down quitting. |
中文系统下应用显示为 **慢Q**(通过 `InfoPlist.strings` 本地化),英文系统显示 **SlowQ** —— 因此 Finder 图标名与「辅助功能」权限列表里出现的都是 **慢Q**。
## 许可证
本项目基于 [Apache License 2.0](LICENSE) 开源。
```text
Copyright 2026 PandaBoby
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
```
**[⬆ 回到顶部](#slowq)** · [English README](README.en.md)