Spotlight - macOS 快速启动器

一个简洁、高效的 macOS Spotlight 替代品，专为快速启动应用、搜索网页历史和智能补全打造。

✨ 核心特性

🎯 全局快捷键

• 默认 Command + Space 随时呼出搜索窗口
• 完全可自定义快捷键组合
• 支持为常用应用设置专属快捷键

🔍 智能搜索

• 应用程序搜索 - 快速启动本地应用
• Chrome 书签 - 访问收藏的网页
• Chrome 历史 - 智能访问频率排序
• 词典翻译 - 英文单词即时翻译
• IDE 项目 - 快速打开 CLion、PyCharm、GoLand 项目
• 钉钉搜索 - 自动跳转到钉钉搜索联系人

⚡️ 魔法后缀

使用特殊后缀精确过滤搜索结果：

• 关键词 ding - 在钉钉中搜索联系人
• 关键词 cl/qo/py/gl - 搜索对应 IDE 的项目

🎨 现代化界面

• 浮动窗口设计，始终置顶
• 支持编辑快捷键（Command+V/C/X/A/Z）
• 键盘导航（↑↓ 选择，Enter 执行，Escape 关闭）
• 不在 Dock 显示，不干扰工作流

📋 系统要求

• macOS 13.0 (Ventura) 或更高版本
• Swift 5.9+
• Xcode Command Line Tools

🚀 快速开始

安装方式一：打包安装（推荐）

# 1. 赋予执行权限
chmod +x package.sh

# 2. 打包成 .app 应用
./package.sh

# 3. 安装到应用目录
cp -r .build/Spotlight.app /Applications/

安装方式二：直接编译运行

# 使用 Swift 编译
swift build

# 运行
.build/debug/Spotlight

首次运行配置

1️⃣ 辅助功能权限（必需）

用于监听全局快捷键：

1. 打开 系统设置 → 隐私与安全性 → 辅助功能
2. 点击 + 添加 Spotlight.app
3. 确保开关为开启状态

2️⃣ 完全磁盘访问权限（可选）

用于读取 Chrome 书签和历史记录：

1. 打开 系统设置 → 隐私与安全性 → 完全磁盘访问权限
2. 点击 + 添加 Spotlight.app
3. 确保开关为开启状态

💡 提示：不授予此权限时，应用仍可正常搜索应用程序，但无法访问浏览器数据。

🎮 使用指南

基本操作

1. 呼出搜索 - 按 Command + Space
2. 输入关键词 - 直接输入应用名或网址关键词
3. 选择结果 - 用 ↑ ↓ 键或鼠标
4. 打开 - 按 Enter 或点击
5. 关闭 - 按 Escape 或点击窗口外

搜索示例

# 搜索应用
chrome          → Google Chrome
vscode          → Visual Studio Code

# 搜索书签和历史
github          → GitHub 主页、Issues、仓库等
qoder           → Qoder 编辑器页面

# 翻译单词
hello           → 显示词典释义

# 只搜索应用
chrome ap       → 只显示 Chrome 应用

# 搜索 CLion 项目
myproject cl    → 打开 CLion 中的 myproject

# 钉钉搜索
张三 ding       → 在钉钉中搜索联系人"张三"

设置快捷键

点击菜单栏图标 🔍 → 设置：

• 自定义主快捷键
• 配置应用专属快捷键
• 管理 IDE 项目路径

📁 项目结构

Spotlight/
├── Sources/                      # 源代码
│   ├── main.swift               # 应用入口
│   ├── AppDelegate.swift        # 应用代理
│   ├── SearchWindow.swift       # 搜索窗口 UI
│   ├── SearchEngine.swift       # 搜索引擎
│   ├── ConfigManager.swift      # 配置管理
│   ├── GlobalHotKeyMonitor.swift # 全局快捷键
│   ├── DictionaryService.swift  # 词典服务
│   ├── IDEProjectService.swift  # IDE 项目管理
│   ├── SettingsView.swift       # 设置界面
│   ├── Logger.swift             # 日志系统
│   └── UsageHistory.swift       # 使用历史
├── Tests/                        # 测试代码
│   ├── UnitTests/               # 单元测试
│   └── E2ETests/                # 端到端测试
├── package.sh                    # 打包脚本
├── run_tests.sh                  # 测试脚本
├── ide_config.json              # IDE 配置
├── Spotlight.entitlements       # 权限配置
└── Package.swift                 # Swift Package 配置

🔧 技术栈

类别	技术
语言	Swift 5.9+
UI 框架	SwiftUI + AppKit
系统框架	Carbon (快捷键)、Cocoa
数据库	SQLite3 (浏览器历史)
存储	UserDefaults (配置)
架构	MVVM

🎯 核心功能实现

搜索源与优先级

1. 应用程序 (最高优先级)

   • 扫描 /Applications、~/Applications、/System/Applications
   • 提取应用元数据和图标

2. IDE 项目 (最高优先级)

   • 支持 CLion、PyCharm、GoLand、VSCode 等
   • 通过 URL Scheme 打开项目

3. 钉钉搜索 (最高优先级)

   • 自动跳转到钉钉搜索联系人
   • 使用 AppleScript 自动化操作
   • 剪贴板内容自动备份与恢复

4. 词典翻译 (中优先级)

   • 系统词典服务
   • 显示音标和详细释义

5. Chrome 书签 (中优先级)

   • 从 ~/Documents/Spotlight/bookmarks_*.html 读取
   • 需手动导出书签

6. Chrome 历史 (低优先级)

   • 读取 ~/Library/Application Support/Google/Chrome/Default/History
   • 按访问频率智能排序
   • 定时刷新（每 30 秒）

模糊匹配算法

• 精确匹配 - 100 分
• 前缀匹配 - 90 分
• 包含匹配 - 80 分
• 多关键词 - AND 逻辑，所有关键词必须匹配

智能排序

结合以下因素：

• 匹配分数
• 类型优先级
• 使用历史频率

🧪 测试

# 运行所有测试
chmod +x run_tests.sh
./run_tests.sh

# 或使用 Swift Package Manager
swift test

测试覆盖率：

• ConfigManager: ~95%
• SearchEngine: ~85%
• GlobalHotKeyMonitor: ~75%
• 总体: ~70%

📝 日志系统

查看日志

# 打包应用日志位置
~/Library/Logs/Spotlight/spotlight-YYYY-MM-DD.log

# 实时查看
tail -f ~/Library/Logs/Spotlight/spotlight-$(date +%Y-%m-%d).log

# 直接运行二进制时，日志输出到控制台
./Spotlight 2>&1 | tee debug.log

日志级别

• DEBUG - 调试信息
• INFO - 一般信息
• WARN - 警告信息
• ERROR - 错误信息

🐛 故障排查

快捷键不响应

1. 检查辅助功能权限是否已授予
2. 重启应用
3. 查看日志中的错误信息

无法读取浏览器数据

1. 检查完全磁盘访问权限
2. 确保 Chrome 历史文件存在
3. 完全退出应用后重启

输入框无法输入

1. 点击输入框获得焦点
2. 检查窗口是否成为 Key Window
3. 查看日志中的 TextField 状态

无法打开 .app 文件

# 移除隔离属性
xattr -d com.apple.quarantine /Applications/Spotlight.app

🛣️ 路线图

v1.1（进行中）

• 词典翻译功能
• IDE 项目集成
• 编辑快捷键支持
• 性能优化
• 更多浏览器支持

v2.0（计划中）

• 文件系统搜索
• 计算器功能
• 插件系统
• 自定义主题
• 剪贴板历史

🤝 贡献

欢迎贡献代码、报告 Bug 或提出建议！

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 提交 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🙏 致谢

• Carbon Framework - 全局快捷键支持
• SwiftUI - 现代化 UI 框架
• 所有贡献者和使用者

---

享受你的个性化 Spotlight！ 🚀

报告问题 · 功能建议