核心功能与使用方式
Spotlight Search 是专为 macOS 设计的本地文件全文检索技能，通过调用系统级 Spotlight 索引数据库（mdfind），无需逐文件扫描即可在毫秒级返回结果。典型调用方式为 scripts/spotlight-search.sh <目录> <关键词> [--limit N]，支持中文、日文等多语言内容检索，并能深入 PDF、docx、txt、md、代码文件等格式的内部文本。
显著优势
性能碾压传统工具：相比 grep -r 或 ripgrep 的逐字节扫描，Spotlight 利用预建索引实现近乎瞬时的响应，在大型文档库（数万文件）场景下速度差距可达 10-100 倍。其内容感知能力覆盖 Office 文档、PDF 甚至图片 OCR 文本，这是纯文本工具无法比拟的。多语言支持原生内置于系统索引，无需额外配置编码或分词器。
关键局限与风险
平台锁定：完全依赖 macOS Spotlight 基础设施，Linux/Windows 用户无法使用。索引覆盖范围受系统隐私设置约束——外部磁盘、加密文件夹或用户手动排除的目录可能被跳过，导致"漏搜"。技术层面，Spotlight 仅支持关键词匹配，不理解语义（如搜索"深度学习"不会返回"神经网络"相关文档），复杂场景需配合向量检索工具。
适用人群
macOS 重度用户、学术研究者（管理大量 PDF 文献）、法律/金融从业者（检索合同与报告）、开发者（快速定位代码中的特定注释或文档）。特别适合已启用 Spotlight 且文件结构规范的专业用户。
常规风险与注意事项
- 隐私边界：技能默认遵循"搜索→展示→确认"安全模式，严禁在未经用户明确授权时自动读取文件内容，仅返回文件路径列表供用户选择。
- 权限红线：文档中明确警示禁止自动执行
sudo命令（如sudo mdutil -i on），此类需要管理员权限的索引管理操作必须由用户本人在终端手动完成。 - 索引延迟：新创建或修改的文件可能存在分钟级索引延迟，紧急场景下可能返回过时结果。
- 模糊匹配副作用：Spotlight 默认启用同义词和模糊匹配，可能返回相关性较低的结果，需使用
"精确短语"语法强制精确匹配。