Search Tool
基于 Cursor 官方 Semantic & Agentic Search 文档解释 Instant Grep、semantic search、indexing、privacy 和 Explore subagent。
Cursor Agent 的质量很大程度取决于它能不能找到正确上下文。官方 Search 文档说明，Agent 会组合多种 search tools：精确匹配用 Instant Grep，不知道名字时用 semantic search，复杂探索时连用搜索、读文件和追引用。
阅读目标：读完本章，你应该能判断什么时候给 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（向量嵌入，把文本转成高维向量便于按相似度检索），再按语义匹配。
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_modulesdist- build artifacts
- generated files
- 大型内容文件
- 与任务无关的产物目录
如果 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。
深读：为什么先搜索现有模式再改代码
真实项目里，很多 bug 来自“没找现有模式就新建一套”。Cursor 的 semantic search 和 grep 组合正是为了解决这个问题：先找到项目已有认证、错误处理、数据访问、UI 组件模式，再按本地约定改。
好的 prompt 不是“帮我做登录”，而是“先找现有登录、表单校验、API 请求、错误展示模式，再给最小实现计划”。
5. Explore subagent
官方文档说明，Agent 可以自动使用 Explore subagent。它在自己的 context window 中运行，使用更快模型执行大量并行搜索，只把相关 findings 返回主 conversation。
适合：
- 大代码库 broad search。
- 多模块影响面盘点。
- 找所有 validation、permission、billing、routing 入口。
- 不想把主上下文塞满 raw file contents 的场景。
你也可以直接要求：
Use a subagent to find all the places we validate user input.本章自检
完成本章后，用这 3 个问题检查自己是否真正理解：
- Instant Grep 和 semantic search 分别适合什么 prompt？
- Indexing 未完成或
.cursorignore不合理，会怎样影响 Agent？ - Explore subagent 为什么能减少主 conversation 的上下文压力？
通过标准：你能写出一条先搜索现有模式、再计划、最后才修改的 Agent prompt。
官方来源
- Cursor Semantic & Agentic Search —— 官方说明 Instant Grep、semantic search、indexing、privacy、Explore subagent 和 search tips。
- Cursor Codebase Indexing Help —— Help Center 说明 indexing 状态、reindex 和
.cursorignore。