spotlight

使用 macOS Spotlight 索引 (mdfind) 搜索文件和内容。当用户要求搜索 macOS 上的本地文件、文档或目录时使用。支持 PDF、Word 文档、文本文件等中的文本内容搜索。对于大型文档集合，比 grep 快得多。仅适用于启用了 Spotlight 的 macOS 系统。

# Spotlight Search

Search local files using macOS Spotlight indexing system.

## When to Use

Use this skill when:
- User asks to search files or directories on macOS
- Need to find documents containing specific text
- Searching large document collections (faster than grep)
- Need to search inside PDFs, Word docs, or other indexed formats

## Quick Start

```bash
scripts/spotlight-search.sh <directory> <query> [--limit N]
```

**Examples:**

```bash
scripts/spotlight-search.sh ~/Documents "machine learning"
scripts/spotlight-search.sh ~/research "neural networks" --limit 10
scripts/spotlight-search.sh ~/Downloads "meeting notes" --limit 5
```

## Search Features

- **Fast**: Uses system-level Spotlight index (no file scanning)
- **Content-aware**: Searches inside PDF, docx, txt, md, etc.
- **Multilingual**: Supports Chinese, Japanese, and all languages
- **Metadata**: Returns file path, type, and size

## Output Format

```
🔍 Searching in /path/to/directory for: query

✅ Found N results (showing up to M):

📄 /full/path/to/file.pdf [pdf, 2.3M]
📄 /full/path/to/document.txt [txt, 45K]
📁 /full/path/to/folder/
```

## Supported File Types

Spotlight automatically indexes:
- Text files (txt, md, csv, json, xml, etc.)
- Documents (pdf, docx, pages, rtf, etc.)
- Code files (py, js, java, c, etc.)
- Emails and contacts
- Images (with embedded metadata/OCR)

## Limitations

- **macOS only**: Requires Spotlight indexing
- **Indexed directories only**: External drives may not be indexed
- **Keyword search**: Not semantic (use embedding-based search for semantic queries)
- **Privacy**: Respects Spotlight privacy settings (excluded directories won't appear)

## Check Indexing Status

```bash
# Check if a volume is indexed
mdutil -s /path/to/volume

# Enable indexing (requires admin)
sudo mdutil -i on /path/to/volume
```

## Integration with LLM Workflows

**Pattern: Search + Extract + Summarize**

1. Use `spotlight-search.sh` to find relevant files
2. Use `read` tool to extract content from top results
3. Summarize or answer user's question based on extracted content

**Example workflow:**

```
User: "Find all documents about machine learning in my research folder"

1. Run: spotlight-search.sh ~/research "machine learning" --limit 10
2. Read top 3-5 results with read tool
3. Summarize findings for user
```

## Advanced Query Syntax

Spotlight supports advanced query operators:

```bash
# Exact phrase
spotlight-search.sh ~/Documents "\"machine learning\""

# AND operator
spotlight-search.sh ~/Documents "neural AND networks"

# OR operator
spotlight-search.sh ~/Documents "AI OR artificial intelligence"

# Metadata queries
spotlight-search.sh ~/Documents "kMDItemContentType == 'com.adobe.pdf'"
```

## Troubleshooting

**No results found:**
- Check if directory is indexed: `mdutil -s /path`
- Wait for indexing to complete (new files may take minutes)
- Verify Spotlight is enabled in System Preferences

**Incorrect results:**
- Spotlight uses fuzzy matching and synonyms
- Use exact phrase search: `"exact phrase"`
- Check privacy settings (some folders may be excluded)

## Performance

- **Instant**: Pre-indexed, no file scanning needed
- **Scales well**: Handles millions of files
- **Low CPU**: No processing overhead (vs grep/ripgrep)

**Comparison:**

| Tool | Speed | Content Search | Multilingual |
|------|-------|----------------|--------------|
| Spotlight | ⚡ Instant | ✅ Yes | ✅ Yes |
| grep/ripgrep | 🐢 Slow | ✅ Yes | ✅ Yes |
| find | ⚡ Fast | ❌ No | N/A |

## Platform Notes

- **macOS only**: This skill requires macOS Spotlight
- **Linux alternative**: Use `grep -r` or `ripgrep`
- **Windows alternative**: Use Windows Search or Everything search

---

## 中文说明

# Spotlight 搜索

使用 macOS Spotlight 索引系统搜索本地文件。

## 何时使用

在以下情况使用此技能：
- 用户要求在 macOS 上搜索文件或目录
- 需要查找包含特定文本的文档
- 搜索大型文档集合（比 grep 更快）
- 需要在 PDF、Word 文档或其他已索引格式内部进行搜索

## 快速开始

```bash
scripts/spotlight-search.sh <directory> <query> [--limit N]
```

**示例：**

```bash
scripts/spotlight-search.sh ~/Documents "machine learning"
scripts/spotlight-search.sh ~/research "neural networks" --limit 10
scripts/spotlight-search.sh ~/Downloads "meeting notes" --limit 5
```

## 搜索特性

- **快速**：使用系统级 Spotlight 索引（无需扫描文件）
- **内容感知**：在 PDF、docx、txt、md 等内部搜索
- **多语言**：支持中文、日文以及所有语言
- **元数据**：返回文件路径、类型和大小

## 输出格式

```
🔍 Searching in /path/to/directory for: query

✅ Found N results (showing up to M):

📄 /full/path/to/file.pdf [pdf, 2.3M]
📄 /full/path/to/document.txt [txt, 45K]
📁 /full/path/to/folder/
```

## 支持的文件类型

Spotlight 会自动索引：
- 文本文件（txt、md、csv、json、xml 等）
- 文档（pdf、docx、pages、rtf 等）
- 代码文件（py、js、java、c 等）
- 邮件和联系人
- 图像（带有嵌入元数据/OCR）

## 限制

- **仅限 macOS**：需要 Spotlight 索引
- **仅限已索引目录**：外部驱动器可能未被索引
- **关键词搜索**：非语义搜索（语义查询请使用基于嵌入的搜索）
- **隐私**：遵守 Spotlight 隐私设置（被排除的目录不会出现）

## 检查索引状态

```bash
# Check if a volume is indexed
mdutil -s /path/to/volume

# Enable indexing (requires admin)
sudo mdutil -i on /path/to/volume
```

## 与 LLM 工作流的集成

**模式：搜索 + 提取 + 总结**

1. 使用 `spotlight-search.sh` 查找相关文件
2. 使用 `read` 工具从靠前的结果中提取内容
3. 基于提取的内容总结或回答用户的问题

**示例工作流：**

```
User: "Find all documents about machine learning in my research folder"

1. Run: spotlight-search.sh ~/research "machine learning" --limit 10
2. Read top 3-5 results with read tool
3. Summarize findings for user
```

## 高级查询语法

Spotlight 支持高级查询运算符：

```bash
# Exact phrase
spotlight-search.sh ~/Documents "\"machine learning\""

# AND operator
spotlight-search.sh ~/Documents "neural AND networks"

# OR operator
spotlight-search.sh ~/Documents "AI OR artificial intelligence"

# Metadata queries
spotlight-search.sh ~/Documents "kMDItemContentType == 'com.adobe.pdf'"
```

## 故障排除

**未找到结果：**
- 检查目录是否已索引：`mdutil -s /path`
- 等待索引完成（新文件可能需要几分钟）
- 在“系统偏好设置”中确认 Spotlight 已启用

**结果不正确：**
- Spotlight 使用模糊匹配和同义词
- 使用精确短语搜索：`"exact phrase"`
- 检查隐私设置（某些文件夹可能被排除）

## 性能

- **即时**：预先索引，无需扫描文件
- **扩展性好**：可处理数百万个文件
- **低 CPU**：无处理开销（相较于 grep/ripgrep）

**对比：**

| 工具 | 速度 | 内容搜索 | 多语言 |
|------|-------|----------------|--------------|
| Spotlight | ⚡ 即时 | ✅ 是 | ✅ 是 |
| grep/ripgrep | 🐢 慢 | ✅ 是 | ✅ 是 |
| find | ⚡ 快 | ❌ 否 | 不适用 |

## 平台说明

- **仅限 macOS**：此技能需要 macOS Spotlight
- **Linux 替代方案**：使用 `grep -r` 或 `ripgrep`
- **Windows 替代方案**：使用 Windows 搜索或 Everything 搜索