MacRightClick 是一款专为 macOS 设计的免费开源右键上下文菜单（Context Menu）增强助手。它支持 28 种日常右键操作，包括新建多种格式文档、打开终端或编辑器、提取文件哈希、生成二维码、图片格式转换等。项目采用 “分布式信号 + BSD kqueue (DispatchSource)” 的队列化分发机制，兼顾 FinderSync 扩展、站外分发和本地开发调试场景。
- 🚀 队列化动作消费：右键点击会写入独立 UUID 事件文件，宿主 App 按顺序消费，避免连续点击覆盖单个 pending 文件。
- 🔒 清晰的共享通道：当前官网分发路线使用扩展沙盒中介目录保持 Ad-hoc 与 Developer ID 环境路径一致；通过队列化数据中介与双通道信号机制，规避强沙盒下 DistributedNotification
userInfo被剥离的问题。若未来切换 Mac App Store，应改为正式 App Group 与 security-scoped access。 - 🎨 非阻塞磨砂玻璃 HUD：彻底弃用传统的同步阻塞弹窗，独创实现了带有原生 macOS 磨砂玻璃、圆角卡片、淡入淡出微动画、2.5 秒自动关闭的非模态
NSPanel浮动通知面板（HUD），不强占系统焦点，体验极其优雅。 - 🦁 现代 SMAppService 登录项自启：依托 macOS 13+
SMAppServiceAPI 注册登录项。用户可在系统的“系统设置 -> 通用 -> 登录项”中管理。 - ✂️ 访达已剪切文件原生状态角标：原生利用
FIFinderSyncController的 Badging 功能，为处于“已剪切”挂起状态下的文件、文件夹渲染精致的剪刀角标。且结合分布式通知信号触发 Finder 秒级重绘，彻底解决以往用户“不知道是否成功剪切”的交互痛点。 - 🔋 系统托盘与 Dock 无缝转换：支持退入系统托盘常驻运行。偏好设置红叉拦截，在退出时隐藏 Dock 栏并将 AppKit 策略调整为
.accessory以达到极轻量常驻；点击托盘时重新挂载为.regular并置顶，保障高贵的苹果原生手感。 - 🖥️ Universal 2 双架构支持：支持 Apple Silicon (M1/M2/M3/M4) 与 Intel (x86_64) 双架构编译。
| 📂 新建文件类 | 📝 文件管理类 | 💻 终端与编辑器 | 🧰 实用小工具 |
|---|---|---|---|
- 新建 .txt 文本文档- 新建 .md Markdown 文档- 新建 .json 数据包- 新建 .csv 数据表格- 新建 .html 网页文档- 新建 .docx Word 骨架- 新建 .xlsx Excel 骨架- 新建 .pptx PowerPoint 骨架- 新建 .pdf PDF 骨架 |
- 剪切文件 (Cut) - 粘贴文件 (Paste) - 永久删除（高级，默认关闭） - 拷贝文件完整路径 - 拷贝文件名 - 复制到...（高级，默认关闭） - 移动到...（高级，默认关闭） |
- 在当前目录打开终端 (Terminal) - 在当前目录打开 iTerm2 - 在当前目录打开 Warp - 用 VSCode 打开目标 - 用 Sublime Text 打开目标 - 用 Cursor 打开目标 |
- 提取文件 MD5 校验码 - 提取文件 SHA256 校验码 - 切换系统隐藏文件显示状态（高级，默认关闭） - 从剪贴板生成二维码窗口 - 转换为 PNG 格式图片 - 转换为 JPEG 格式图片 |
MacRightClick 采用集中式数据通道隔离抽象层：上层 Action 逻辑、SwiftUI 界面和 Finder 访达交互由 SharedStorageManager 托管，底层负责队列事件、配置文件和共享日志。
sequenceDiagram
participant User as 用户右键菜单 (Finder)
participant FS as FinderSync 插件 (沙盒)
participant SC as 中介共享物理文件夹 (/Library/Containers/guyue.RightClickAssistant.Extension/Data)
participant Host as 主程序 MacRightClick (AppMain 事件循环)
Note over Host: static func main() -> AppMain 入口启动
Note over Host: 静态持有 AppDelegate 实例 & 唤醒生命周期！
User->>FS: 右键点击 "新建 文本文件 (.txt)"
Note over FS: actionMenuItemSelected 回调
FS->>SC: 1. 物理写入中介 PendingActions/{timestamp}-{uuid}.json
FS->>SC: 2. 通过 OSLog 写入 subsystem=guyue.RightClickAssistant（category=ext / storage）
FS->>Host: 3. 发送 DistributedNotification (guyue.RightClickAssistant.triggerActionSignal) 纯空信号 (双保险 1)
SC-->>Host: 4. 触发 BSD kqueue 内核事件 (双保险 2: 0.001ms 瞬时直达)
Note over Host: 双保险任意一路触发消费入口
Note over Host: objc_sync_enter 互斥锁原子锁定
Host->>SC: 5. 按创建时间消费队列中的所有 JSON 事件
Host->>SC: 6. 物理删除已消费事件文件 (单次高安全性消费)
Host->>Host: 7. ActionDispatcher.shared.dispatch(高特权执行业务 - 后台并发队列)
Host-->>User: 8. 在用户目标下秒级诞生 "未命名.txt"！
推荐下载 Universal 2 双架构 (Apple Silicon + Intel x86_64) 磁盘映像包。正式发布版应使用 Developer ID 签名、Hardened Runtime、Apple notarization 与 stapler 附票；本地开发版仍可使用 Ad-hoc 签名调试。
| 📦 格式 | 下载链接 | 适用场景 & 特性 |
|---|---|---|
| 磁盘映像 (DMG) | 下载最新 RightClickAssistant-Latest.dmg | 推荐。拖拽即可安装，适合常规使用。 |
| 绿色压缩包 (ZIP) | 下载最新 RightClickAssistant-Latest.zip | 解压即可运行，适合测试或临时使用。 |
Tip
📌 所有历史版本与更新日志：您可以随时访问 GitHub Releases 页面 查阅所有的历史发布版本、多架构安装包以及详尽的 Release Note 演进过程。
当前项目主路线是 官网 / GitHub Releases 站外分发。正式发布时使用：
DISTRIBUTION_ROUTE=website-release \
DEVELOPER_ID_APPLICATION="Developer ID Application: Your Name (TEAMID)" \
NOTARY_PROFILE="your-notarytool-profile" \
./Scripts/build.sh这条路线会启用 Developer ID 签名、Hardened Runtime、notarytool 提交、公证完成后对 .app 与 .dmg 执行 stapler staple。
Mac App Store 不是当前默认路线。若未来切换到 Mac App Store，请先阅读 Mac App Store 架构迁移文档，其中详细列出了 App Sandbox、App Group、security-scoped bookmarks 等必备前提。
根目录下配备了标准的 Universal 2 多架构极速编译打包工具：
./Scripts/build.sh编译完成后，制品将保存在 build/ 目录下：
- 📍 宿主应用路径:
build/RightClickAssistant.app - 📦 分发 Zip 包路径:
build/RightClickAssistant.zip
项目包含本机验证工具。您可以通过以下命令执行编译、卸载旧包、部署、拉起进程并运行核心断言测试：
./Scripts/build.sh && ./Scripts/uninstall.sh && cp -R build/RightClickAssistant.app /Applications/ && open /Applications/RightClickAssistant.app && sleep 5 && ./ActionVerifier_bin自检输出报告：
==============================================================================
📊 [Verifier] 物理自检结束！
🟢 通过项: 10 / 10
🔴 失败项: 0 / 10
==============================================================================
✅ [Verifier] 验证通过：多进程动作队列、生命周期与核心 Action 逻辑符合预期。
自检完成后，您可以运行内置卸载脚本，注销 Finder 扩展、清理沙盒缓存，并重启 Finder 释放扩展会话：
./Scripts/uninstall.sh由于本开源项目在本地使用 Ad-Hoc 临时自签名编译（未向苹果公司缴纳年费购买商业开发者证书并进行官方公证 Notarization），其他用户在下载并安装、运行此软件时，可能会遇到 macOS 系统级安全防御拦截。请按照以下步骤轻松排除：
- 原因：macOS Gatekeeper 安全机制对非商业证书签名的外来下载软件会自动打上“隔离属性”并拦截运行。
- 解决办法：
- 将应用拖入
/Applications文件夹； - 打开系统的 终端 (Terminal) 软件，执行以下命令物理移除隔离标记：
xattr -cr /Applications/RightClickAssistant.app
- 重新双击运行应用。
- 将应用拖入
- 原因：macOS 默认不会在系统后台自动注册和激活第三方的 FinderSync 插件。特别是在本地编译、或者是从浏览器下载但未将其移动到
/Applications文件夹、以及存在 Gatekeeper 隔离标记时，系统的pluginkit守护进程会漏掉扫描注册。 - 解决办法（极简智能推荐）：
- 主程序引导：主程序会读取当前 macOS 系统版本，并在主界面中显示对应的扩展启用步骤与系统设置入口。点击概览页橙色的「一键注册扩展」按钮，App 会自动执行
pluginkit -a注册 +pluginkit -e use启用 +killall Finder重启访达三步，无需再去系统设置里手动勾选。 - 终端手动注册：
若您在扩展页面中找不到“右键助手”，请打开 Mac 的 终端 (Terminal.app)，依次执行以下注册并启用命令（注册和启用是两步，缺一不可）：
- 场景 A：如果您已将 App 安装在
/Applications（推荐）：pluginkit -a /Applications/RightClickAssistant.app/Contents/PlugIns/RightClickAssistantExtension.appex pluginkit -e use -i guyue.RightClickAssistant.Extension
- 场景 B：如果您是在克隆的源码目录本地编译：
pluginkit -a \$(pwd)/build/RightClickAssistant.app/Contents/PlugIns/RightClickAssistantExtension.appex pluginkit -e use -i guyue.RightClickAssistant.Extension
killall Finder重启访达即可生效。 - 场景 A：如果您已将 App 安装在
- 手动备用步骤：
- 打开 Mac 的 系统设置 (System Settings)；
- 依次进入：隐私与安全性 (Privacy & Security) -> 扩展 (Extensions)；
- 双击点击 访达 (Finder) 选项；
- 找到 “右键助手扩展”，手动将其勾选勾亮开启服务；
- 若尚未显示，可右键点开一个 Finder 窗口，或在终端执行
killall Finder重启访达。
- 主程序引导：主程序会读取当前 macOS 系统版本，并在主界面中显示对应的扩展启用步骤与系统设置入口。点击概览页橙色的「一键注册扩展」按钮，App 会自动执行
- 原因：MacRightClick 的架构属于“双通道多进程沙盒穿透分发”架构。Finder 菜单负责展示，真正的业务（如新建 Word 骨架、计算哈希等高特权文件读写）是由主 App 在后台常驻处理的。
- 解决办法：
- 主 App 在刚拉起时，已通过
ProcessInfo.beginActivity申请了系统级高优保活豁免，确保不被 macOS App Nap 机制挂起和冻结； - 主 App 支持点击红叉后隐藏到系统菜单栏，并在设置界面支持“开机自启动”（基于 macOS
SMAppService机制）。如果你希望右键服务随登录启动，可以开启此项。
- 主 App 在刚拉起时，已通过
-
新版（推荐）：日志统一走 OSLog，不再写文件。在终端运行：
log show --predicate 'subsystem == "guyue.RightClickAssistant"' --last 5m --info或在「主控制台」(
Console.app) 中按subsystem == "guyue.RightClickAssistant"过滤。可用 category 包括host/ext/storage/action/ui。 -
旧版兼容：早期版本曾把日志追加到
~/Library/Containers/<extBundle>/Data/Library/Logs/extension.log。本版本起该文件不再被追加；如本机仍存在旧文件，可在「设置 → 诊断」点「导出旧日志（如有）」一键定位。 -
详细调试日志：默认关闭。在「设置 → 诊断 → 启用详细调试日志」打开后，会让
.debug级别走 OSLog 记录菜单渲染、路径监听等细节。
- 项目不包含广告，也不会主动收集或上传使用数据。
- 详细调试日志默认关闭。开启后，日志可能包含菜单渲染、路径监听和动作过滤信息，请仅在排查问题时使用。
- 高风险动作（永久删除、跨目录复制/移动、切换隐藏文件）默认关闭，并在执行前显示确认。
- 正式站外发布版应使用 Developer ID、Hardened Runtime、Apple notarization，并对
.app与.dmg执行 stapler 附票。
- fix(ext): 「一键注册扩展」现在自动执行
pluginkit -a注册 +pluginkit -e use启用 +killall Finder重启访达三步，不再仅注册不生效。 - fix(ux): 「一键注册扩展」按钮颜色统一为橙色，与未激活态 warning 基调一致，消除文本与实际颜色不一致的 bug。
- fix(host):
processPendingAction异步化 + Distribution 路线感知 UserDefaults 路由，斩断启动期cfprefsd死锁。 - fix(storage): PendingAction 改 lease/ack/reclaim 三件套，进程崩溃不丢事件。
- fix(filemanage): paste 走
BackgroundActionRunner，跨盘大文件不再阻塞 folder-monitor 队列；彻底删除走DeletionRequestCoordinator，斩断死锁链。 - fix(interactive): moveTo/copyTo/toggleHidden 走
InteractiveActionRunner，斩断 P0-1/P0-2 死锁。 - fix(host+ext): statusItem 兜底 + FinderSync 启动时自愈拉起主 App。
- fix(ci): hdiutil create 加 detach 清理 + 重试，消除 CI DMG 打包 Resource busy 竞态。
- feat(ux): 右键菜单作用范围默认
.everywhere，新增 WatchScope 开关；概览页单一引导入口；高级页恢复默认拆两档；权限页改事件驱动。 - feat(hud): HUD 跟随鼠标所在屏幕，支持点击/Esc 立即关闭。
- feat(safety): 状态栏托盘移除切换隐藏文件入口，
killall Finder改 AppleScript 优雅退出。 - feat(filemanage): 永久删除走 HIG critical 三按钮，新增移到废纸篓中间档；跨卷 Copy-Then-Delete 事务化。
- feat(newfile): Office 三件套改读 Bundle Templates 最小骨架，可双击直开。
- feat(qr): 二维码窗口加保存为 PNG / 拷贝图片按钮，长内容滚动文本预览。
- feat(cache): 新增
AppLog/Distribution/ActionConfigCache/InstalledAppRegistry四个共享模块，菜单渲染主路径走进程内缓存。 - feat(stress): 新增
run_stress.py/run_reclaim_stress.py真机压测 harness，压测进 CI。 - build: entitlements 外置 + 按
DISTRIBUTION_ROUTE选模板，release/MAS 启用-O。 - core: 全面适配 Swift 6.1 并发安全检查（
@MainActor/nonisolated(unsafe)/Sendable）。
完整变更日志见 CHANGELOG.md，发布说明见 GitHub Releases v1.0.1。
本项目基于 MIT 开源许可证。