mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-18 06:15:51 +00:00
46fecb590b
移除 TypeScript 代码、源码路径和适配器实现细节， 聚焦结果排序的设计假设、token预算控制、 多后端搜索的适配器选型和 WebFetch 安全防护层。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
117 lines
5.0 KiB
Plaintext
117 lines
5.0 KiB
Plaintext
---
|
||
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 的追踪系统
|
||
- **工具系统** — 理解所有工具的统一接口设计
|