---
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="/docs/cursor/official/01-agent-workflow/12-plan-mode" />
  <Card title="Rules" description="把项目搜索和上下文习惯沉淀到 rules。" href="/docs/cursor/official/02-context-customization/20-rules" />
</Cards>
