# MiddleQ

**Repository Path**: ProgHub/MiddleQ

## Basic Information

- **Project Name**: MiddleQ
- **Description**: 在Mac上使用鼠标中键点击Dock栏的应用图标以快速退出该应用
- **Primary Language**: Swift
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-27
- **Last Updated**: 2026-03-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<h1 align="center">MiddleQ - MacOS Dock栏中键退出工具</h1>

<p align="center">
  <img src="resource/AppIcon.png" alt="MiddleQ Logo" width="128" height="128">
</p>
<p align="center">
  使用鼠标中键点击Dock栏中已启动的APP图标，可快速退出该应用。<br>
  <strong>当前版本：v1.4.0</strong> | <strong>系统要求：macOS 13.0+</strong>
</p>


---

## 🌟 特性亮点

- **⚡ 快捷高效**: 在 Dock 上中键点击即可秒退应用，无需右键菜单或 Cmd+Q
- **🧠 智能识别**: 自动识别点击的 Dock 图标并终止对应应用进程
- **🔄 自动扫描**: 首次启动自动扫描所有已安装应用，智能建立映射关系
- **⚙️ 灵活配置**: 支持手动添加自定义应用映射，满足特殊需求
- **🛡️ 安全防护**: 智能保护 Finder（访达）不被意外退出
- **🚀 开机自启**: 支持开机自动启动，后台静默运行（macOS 13.0+）
- **💻 双架构支持**: Universal Binary 同时支持 Intel 和 Apple Silicon
- **🍃 轻量级**: 菜单栏常驻，资源占用极低，几乎无感知

---


## 📖 核心原理

MiddleQ 之所以能实现“指哪打哪”的精准退出，主要依赖于 macOS 底层的 **辅助功能 (Accessibility)** 与 **事件监听 (Event Tap)** 机制：

* **全局“捕获”：** 软件启动后会创建一个全局的事件监听器，专门“盯着”鼠标的中键动作（在 macOS 内部被称为 Button 2）。
* **空间坐标定位：** 当你按下中键时，MiddleQ 会瞬间获取当前鼠标在屏幕上的物理坐标。
* **元素识别：** 利用 macOS 的辅助功能 API，软件会向系统询问：“在这一对坐标点上，到底住着哪个 UI 元素？”。如果系统反馈这是一个 **Dock 项目 (AXDockItem)**，MiddleQ 就会进一步提取该图标显示的名称（比如“Visual Studio Code”）。
* **精准打击：** 拿到名称后，软件会在后台运行的应用列表中寻找对应的进程。一旦匹配成功，立即发送退出指令，实现快速关闭。
* **安全屏障：** 为了防止误伤，软件内置了保护机制。即便你在“访达 (Finder)”上点击中键，它也会无视，确保访达不会被意外退出。

---

## ⚙️ 配置文件

### 连接名称与身份的桥梁

有些应用在 Dock 上显示的名称（如“Visual Studio Code”）与其真实的身份标识（Bundle ID）并不一致，此时使用默认的“名称匹配进程“的方式便会失效。为了解决这个“对不上号”的问题，MiddleQ 引入了一套映射系统，其核心就是位于用户资源库中的 **JSON 配置文件**。

### 它的作用

配置文件主要充当 **“翻译官”**。当自动扫描无法准确关联应用图标与运行进程时，你可以通过修改配置文件，手动告诉 MiddleQ：“看到 A 这个名字，请退出 B 这个程序”。

### 工作原理

1. **自动初始化：** 软件在启动时会自动扫描你系统中的 `/Applications` 目录和 `～/Applications` 目录 ，将大多数应用的名称与它们的唯一身份标识（Bundle ID）建立初步映射。
2. **配置优先：** 然后软件会继续加载位于 `~/Library/Application Support/MiddleQ/config.json` 的文件。如果你在文件中手动定义了映射关系，它的优先级将高于软件自动扫描的结果，因为扫描的结果可能不准确，比如他会把 `腾讯会议` 的名字识别为 `TencentMeeting`（后续会优化这点）。
3. **动态覆盖：** 当你编辑完配置文件，点击“重新加载映射”时，MiddleQ 会清空内存中的旧映射表，先进行应用扫描，再进行配置扫描，加载所有映射关系，确保拦截动作的准确性。

---


## 📦 安装

### 方法一：下载预编译版本（推荐）

1. 从 [Releases](https://github.com/yourusername/MiddleQ/releases) 页面下载最新的 `.dmg` 文件
2. 双击打开 DMG 文件
3. 将 `MiddleQ.app` 拖拽到 `Applications` 文件夹
4. 首次运行时系统会提示安全性警告，前往 **系统偏好设置 > 隐私与安全性** 允许运行

### 方法二：源码编译

```bash
# 克隆仓库
git clone https://github.com/yourusername/MiddleQ.git
cd MiddleQ

# 授权脚本可执行权限
chmod +x build.sh
chmod +x package_dmg.sh

# 编译应用（如果需要自定义版本号，可以先修改version.txt中的版本号，执行脚本会自动同步到应用配置）
./build.sh

# 打包为 DMG（可选）
./package_dmg.sh
```

编译产物：
- `MiddleQ.app` - 可直接运行的应用
- `MiddleQ_v1.3.0.dmg` - 安装包（用于分发）

---

## 🚀 使用方法

### 基本操作

1. **启动 MiddleQ**
   - 在 Applications 文件夹中找到并运行 `MiddleQ.app`
   - 运行后会在菜单栏显示鼠标图标 🖱️

2. **授予辅助功能权限**
   - 系统会弹出权限请求对话框
   - 前往 **系统偏好设置 > 隐私与安全性 > 辅助功能**
   - 点击左下角锁图标解锁
   - 添加并勾选 `MiddleQ.app`

3. **使用中键退出应用**
   - 在 Dock 中使用鼠标中键（滚轮按键）点击任意运行中的应用图标
   - 该应用会立即退出

### 菜单栏功能

点击菜单栏的 🖱️ 图标可以访问以下功能：

| 功能             | 快捷键 | 说明            |
|----------------|--------|---------------|
| **开机自动启动**     | - | 开启/关闭开机自启动    |
| **编辑配置文件**     | `⌘E` | 打开配置文件进行编辑    |
| **重新扫描映射**     | `⌘R` | 编辑完成后重新加载映射关系 |
| **退出 MiddleQ** | `⌘Q` | 完全退出应用        |

---

## ⚙️ 配置

### 配置文件位置

```
~/Library/Application Support/MiddleQ/config.json
```

### 手动配置说明

对于某些不生效的应用，可以手动添加映射：

#### 步骤一：使用终端命令获取应用 Bundle ID

```bash
# 使用 mdls 命令（推荐）
mdls -name kMDItemCFBundleIdentifier /Applications/应用名称.app
```

#### 步骤二：编辑配置文件

1. 点击菜单栏图标 > **"编辑配置文件"**（或按 `⌘E`）
2. 在打开的 JSON 文件中添加映射，其中key是应用在Dock栏中显示的名称，value是应用的Bundle ID
3. 保存文件（`⌘S`）
4. 点击菜单栏图标 > **"重新加载映射"**（或按 `⌘R`）

### 配置示例

```
{
  "Chrome": "com.google.Chrome",
  "微信": "com.tencent.xinWeChat",
  "QQ": "com.tencent.qq",
  "钉钉": "com.alibaba.DingTalkMac",
  "Visual Studio Code": "com.microsoft.VSCode"
}
```

> 💡 **提示**: 大多数应用已被自动扫描添加，仅在特殊情况下需要手动配置。

---

## 🔧 开发

### 技术栈

- **语言**: Swift 5+
- **平台**: macOS 13.0+
- **架构支持**: Intel (x86_64) + Apple Silicon (arm64) 通用二进制
- **依赖框架**: 
  - Cocoa (AppKit) - 应用界面
  - ApplicationServices - 辅助功能 API
  - ServiceManagement - SMAppService 开机自启
  - UserNotifications - 用户通知




## 🔒 安全性和权限

### 所需权限

| 权限类型 | 用途 | 授权方式 |
|---------|------|---------|
| **辅助功能权限** | 监听全局鼠标事件、访问 Dock 元素信息 | 系统弹窗引导至隐私设置 |
| **文件系统访问** | 读写配置文件 (`~/Library/Application Support/MiddleQ/`) | 应用沙盒自动授权 |

### 隐私承诺

- ✅ **零数据收集**: 不收集、上传任何用户数据
- ✅ **零网络连接**: 纯本地应用，无任何网络请求
- ✅ **开源透明**: 代码完全开源，可随时审计
- ✅ **最小权限**: 仅请求必要权限，无过度索权

---

## 🐛 故障排除

### 常见问题

#### Q: 应用无法正常工作

**A**: 请按以下步骤检查：

1. **检查辅助功能权限**
   ```
   系统偏好设置 > 隐私与安全性 > 辅助功能
   ```
   确保 `MiddleQ.app` 已勾选

2. **重启应用**
   - 退出 MiddleQ（菜单栏 > 退出 MiddleQ）
   - 重新启动 MiddleQ.app

3. **查看日志**
   ```bash
   log stream --predicate 'process == "MiddleQ"' --info
   ```

#### Q: 某些应用无法通过中键退出

**A**: 

1. **刷新应用映射**
   - 点击菜单栏 > "扫描所有应用"
   - 等待扫描完成

2. **仍然无效则手动添加映射**
   ```bash
   # 获取 Bundle ID
   mdls -name kMDItemCFBundleIdentifier /Applications/问题应用.app
   
   # 编辑配置文件添加映射
   # 菜单栏 > 编辑配置文件
   ```

3. **检查应用名称**
   - 确认 Dock 中显示的名称与配置 key 一致
   - 注意大小写和空格

#### Q: 开机自启功能不可用

**A**: 

- **系统版本要求**: macOS 13.0 或更高版本
- **检查方法**:  > 关于本机 > 查看 macOS 版本
- **替代方案**: 旧版本系统可手动添加到登录项

#### Q: 配置文件格式错误

**A**: 

1. **恢复默认配置**
   ```bash
   # 删除配置文件
   rm ~/Library/Application\ Support/MiddleQ/config.json
   
   # 重启应用会自动创建新文件
   ```

2. **JSON 语法检查**
   - 确保使用双引号 `"`
   - 键值对用冒号 `:` 分隔
   - 最后一项后不加逗号

---

## 📄 许可证

本项目采用 **MIT 许可证** - 查看 [LICENSE](LICENSE) 文件了解详情

**简要说明**：
- ✅ 可自由使用、修改、分发
- ✅ 可用于商业用途
- ❗ 需保留原始版权声明
- ❗ 不提供任何担保

---

## 🙏 致谢

- 感谢所有贡献者和用户的支持
- 特别感谢开源社区提供的各种工具和库
- 基于 macOS Accessibility API 实现

---

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- **Issues**: [提交问题](https://gitee.com/ProgHub/MiddleQ/issues)
- **邮箱**: wang.chaofan@foxmail.com
---

<p align="center">
  Made with ❤️ for macOS users<br>
  <strong>版本：1.4.0</strong> | <strong>最后更新：2026-03-05</strong>
</p>