---
title: "Search Tool"
description: "基於 Cursor 官方 Semantic & Agentic Search 文件解釋 Instant Grep、semantic search、indexing、privacy 和 Explore subagent。"
verifiedAt: "2026-05-09"
---

Cursor Agent 的質量很大程度取決於它能不能找到正確上下文。官方 Search 文件說明，Agent 會組合多種 search tools：精確匹配用 Instant Grep，不知道名字時用 semantic search，複雜探索時連用搜尋、讀檔案和追引用。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能判斷什麼時候給 Agent 精確符號，什麼時候描述行為，並知道 indexing 和 `.cursorignore` 如何影響結果。

## 1. Instant Grep 與 Semantic Search

官方文件把搜尋分成兩類。

| 搜尋方式 | 適合 | 例子 |
| --- | --- | --- |
| Instant Grep | 已知函式名、變數名、錯誤字串、regex pattern | `PaymentFailedError`、`import.*PaymentService` |
| Semantic Search | 不知道準確名字，只知道行為或概念 | “where do we handle authentication?” |

Instant Grep 支援 full regex 和 word-boundary matching。Semantic search 則依賴程式碼庫 indexing（索引），把程式碼切成 chunks（語義片段），生成 vector embeddings（向量嵌入，把文本轉成高維向量便於按相似度檢索），再按語義匹配。

```mermaid
flowchart TD
  Prompt["搜尋需求"] --> Known{"知道精確符號或字串"}
  Known -->|是| Grep["Instant Grep"]
  Known -->|否| Semantic["Semantic Search"]
  Semantic --> Entry["找到入口"]
  Entry --> Grep2["Grep 追引用"]
  Grep --> Read["Read files"]
  Grep2 --> Read
  Read --> Context["形成上下文"]
```

## 2. Indexing 怎麼工作

官方說明：

- 開啟 workspace 後自動開始 indexing。
- Cursor 把程式碼切成 meaningful chunks。
- 每個 chunk 轉成 vector embedding。
- Semantic search 在 80% completion 後可用。
- index 每 5 分鐘自動同步一次，只處理 changed files。

變化處理：

| Change | Action |
| --- | --- |
| New files | 自動加入 index |
| Modified files | 刪除舊 embeddings，建立新 embeddings |
| Deleted files | 從 index 移除 |

可以在 **Cursor Settings > Indexing** 檢視狀態或觸發 re-index。Help Center 也說明可從 status bar 看進度，並透過 command palette 搜尋 Reindex。

## 3. ignore files 會影響搜尋質量

官方說明 Cursor indexes all files except ignore files，例如 `.gitignore` 和 `.cursorignore`。

為了提高搜尋質量，應排除：

- `node_modules`
- `dist`
- build artifacts
- generated files
- 大型內容檔案
- 與任務無關的產物目錄

> [!IMPORTANT]
> 如果 Agent 老是找到無關上下文，不一定是模型問題。先檢查 index 狀態和 `.cursorignore`。

## 4. 隱私和安全邊界

官方 Search 文件說明：

- File paths 傳送到 Cursor servers 前會加密。
- Code content 不以 plaintext 儲存。
- Indexing 時 code content 在記憶體中使用，然後丟棄。
- Embeddings 建立時不存 filenames 或 source code。
- Agent 搜尋時，Cursor 檢索 embeddings，並在 client side 解密 chunks。
- 6 周不活動後 indexed codebases 會刪除；重新開啟專案會觸發 re-indexing。

<details>
<summary>深讀：為什麼先搜尋現有模式再改程式碼</summary>

真實專案裡，很多 bug 來自“沒找現有模式就新建一套”。Cursor 的 semantic search 和 grep 組合正是為了解決這個問題：先找到專案已有認證、錯誤處理、資料訪問、UI 元件模式，再按本地約定改。

好的 prompt 不是“幫我做登入”，而是“先找現有登入、表單校驗、API 請求、錯誤展示模式，再給最小實現計劃”。
</details>

## 5. Explore subagent

官方文件說明，Agent 可以自動使用 Explore subagent。它在自己的 context window 中執行，使用更快模型執行大量並行搜尋，只把相關 findings 返回主 conversation。

適合：

- 大程式碼庫 broad search。
- 多模組影響面盤點。
- 找所有 validation、permission、billing、routing 入口。
- 不想把主上下文塞滿 raw file contents 的場景。

你也可以直接要求：

```text
Use a subagent to find all the places we validate user input.
```

## 本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

1. Instant Grep 和 semantic search 分別適合什麼 prompt？
2. Indexing 未完成或 `.cursorignore` 不合理，會怎樣影響 Agent？
3. Explore subagent 為什麼能減少主 conversation 的上下文壓力？

透過標準：你能寫出一條先搜尋現有模式、再計劃、最後才修改的 Agent prompt。

## 官方來源

- [Cursor Semantic & Agentic Search](https://cursor.com/docs/agent/tools/search.md) —— 官方說明 Instant Grep、semantic search、indexing、privacy、Explore subagent 和 search tips。
- [Cursor Codebase Indexing Help](https://cursor.com/help/customization/indexing.md) —— Help Center 說明 indexing 狀態、reindex 和 `.cursorignore`。

## 接下來去哪

<Cards>
  <Card title="Plan Mode" description="搜尋到上下文後，複雜任務回到 Plan Mode 審查方案。" href="/zh-Hant/docs/cursor/official/01-agent-workflow/12-plan-mode" />
  <Card title="Rules" description="把專案搜尋和上下文習慣沉澱到 rules。" href="/zh-Hant/docs/cursor/official/02-context-customization/20-rules" />
</Cards>
