---
title: "搜索与导航"
description: "Glob 按名称找文件，Grep 按内容搜代码——两个维度覆盖代码库定位需求。理解搜索结果排序、token 预算控制和多后端 Web 搜索的设计。"
keywords: ["代码搜索", "Glob", "Grep", "ripgrep", "文件搜索"]
---

## 两个搜索维度

| 维度 | 工具 | 适用场景 |
|------|------|---------|
| **按名称找文件** | Glob | "找到所有测试文件"、"找 config 开头的文件" |
| **按内容找代码** | Grep | "哪里定义了这个函数"、"谁在调用这个 API" |

两者共享同一个 ripgrep 引擎，通过不同的参数组合实现不同搜索模式。

## ripgrep 的内嵌策略

Claude Code 不依赖系统安装的 ripgrep。它使用三级降级策略确保在任何环境下都能工作：

| 优先级 | 方式 | 场景 |
|--------|------|------|
| 1 | 系统 PATH 中的 rg | 用户自定义安装 |
| 2 | 编译进二进制的 rg | Bun 静态编译模式 |
| 3 | vendor 目录中的预编译二进制 | npm 安装模式 |

**设计考量**：搜索是 AI 最频繁使用的操作之一，不能因为用户没装 ripgrep 就降级到低效方案。但也不能假设系统 ripgrep 总是可用——不同环境的安装差异太大了。

## 搜索结果的设计考量

### 结果数量与 Token 预算

默认最多返回 250 条匹配。这不是随意选择的数字：

- 每条匹配行约 50-100 token
- 250 条 ≈ 12,500-25,000 token
- 这大约占 200K 上下文窗口的 6-12%
- 超过这个比例，AI 的推理质量会下降

AI 可以按需调整 `head_limit` 参数——搜索小项目时可以用更大的值。

### 按修改时间排序

Glob 默认把**最近修改的文件排在前面**。这不是文件系统的默认排序，而是刻意的设计决策：

**设计假设**：最近修改的文件最可能与当前任务相关。

**实际效果**：AI 优先看到"活"的代码，而不是沉寂的历史文件。当用户说"帮我修这个 bug"时，最近改过的文件通常就是 bug 所在。

### 错误恢复

ripgrep 执行有专门的错误恢复策略：

| 错误 | 处理 |
|------|------|
| 资源不足 | 自动切换到单线程模式重试 |
| 超时 | 返回已有部分结果，丢弃可能不完整的最后一行 |
| 进程无响应 | 5 秒后强制终止 |

**设计哲学**：部分结果比没有结果好。即使搜索没完成，AI 也能基于已有信息做出判断。

## ToolSearch：在 50+ 工具中发现目标

当可用工具超过 50 个时（含 MCP 提供的外部工具），AI 可能不知道该用哪个。ToolSearch 提供了工具发现机制。

### 搜索算法

```
输入: "database connection"
  → 精确匹配工具名（快速路径）
  → MCP 前缀匹配（"mcp__postgres" 匹配所有 postgres 工具）
  → 关键词拆分 + 加权评分
  → 按分数排序，返回 top-N
```

评分权重：工具名精确匹配（10分）> 工具名部分匹配（5分）> 搜索提示匹配（4分）> 描述匹配（2分）。MCP 工具额外加分，因为它们通常按功能组织。

### 延迟加载

不是所有工具都常驻内存。MCP 工具和低频工具被标记为延迟加载——只有在 ToolSearch 选中后才真正加载。这减少了每次 API 调用的 token 开销（工具描述占用大量 token）。

## Web 搜索与抓取

AI 的信息获取不局限于本地代码。WebSearch 搜索互联网，WebFetch 抓取特定网页内容——和人类开发者的工作方式一致。

### WebSearch 的多后端设计

WebSearch 通过适配器模式支持三种搜索后端：

| 后端 | 适用场景 | 需要 API 密钥 |
|------|---------|:------------:|
| **Anthropic API** | 使用官方 API 的用户 | 是 |
| **Bing** | 第三方代理/非官方端点 | 否 |
| **Brave** | 需要 Brave 搜索 | 是 |

**设计考量**：不是所有用户都使用 Anthropic 官方 API。第三方代理（OpenAI 兼容、Bedrock 等）无法使用 Anthropic 的服务端搜索工具，因此需要独立的搜索后端。

Bing 适配器直接抓取搜索页面并解析结果。它使用完整的浏览器请求头绕过反爬机制，并解码 Bing 的重定向 URL 获取真实链接。

### WebFetch 的安全防护

WebFetch 不只是"抓取 URL"——它有完整的安全防护层：

| 防护 | 说明 |
|------|------|
| 域名预检 | 调用 Anthropic API 检查域名是否在黑名单中 |
| 重定向控制 | 仅允许同域重定向，跨域重定向需要 AI 重新调用 |
| 内容大小限制 | 单次响应上限 10MB |
| URL 验证 | 长度、协议、公网域名检查 |

**预批准域名**：约 90 个主流技术文档站点（MDN、Python docs、React docs 等）无需手动授权即可抓取。对预批准域名，WebFetch 跳过摘要步骤直接返回原文——因为技术文档本身的结构化程度已经足够好。

## 接下来

- **Shell 执行** — Bash 的沙箱和超时控制
- **任务管理** — TaskCreate/TaskUpdate 的追踪系统
- **工具系统** — 理解所有工具的统一接口设计