Claude Code 源码解析 (3)：文件搜索的底层原理

导读： 这是 Claude Code 20 个功能特性源码解析系列的第 3 篇，深入分析文件搜索工具 (Glob/Grep) 的底层原理。

---

📋 目录

1. 问题引入：为什么需要高效的文件搜索？
2. [技术原理：Glob 与 Grep 的核心算法](#技术原理 glob-与-grep-的核心算法)
3. 设计思想：为什么这样设计
4. 解决方案：完整实现详解
5. OpenClaw 最佳实践
6. 总结

---

问题引入：为什么需要高效的文件搜索？

痛点场景

场景 1：大海捞针

用户："帮我找一下项目中所有用到 axios 的地方"

AI 手动遍历：
for file in project/**/*:
    if file.contains("axios"):
        print(file)

10 万行代码 → 30 秒 → 用户等待...

场景 2：模糊记忆

用户："我记得有个文件叫 user_ 什么_controller.py"

AI：精确匹配失败
→ "没有找到 user__controller.py"
→ 但实际文件是：user_auth_controller.py

场景 3：内容搜索慢

用户："搜索所有包含 'TODO' 的 Python 文件"

AI 逐个文件读取 → 打开 1000 个文件 → 5 秒后返回结果

核心问题

设计 AI 助手的文件搜索工具时，面临以下挑战：

1. 性能问题

   • 大型项目 (10 万 + 文件) 如何快速搜索？
   • 如何避免遍历整个文件系统？

2. 准确性问题

   • 通配符匹配的规则是什么？
   • 如何处理边界情况？

3. 灵活性问题

   • 支持多种匹配模式 (通配符、正则)
   • 支持内容搜索 + 文件名搜索

4. 用户体验问题

   • 搜索结果如何呈现？
   • 如何支持分页、过滤？

Claude Code 用 GlobTool + GrepTool 解决了这些问题。

---

技术原理：Glob 与 Grep 的核心算法

整体架构

┌─────────────────────────────────────────────────────────────┐
│                    用户搜索请求                              │
│         "找一下所有 *.py 文件中包含 TODO 的行"                │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│  第 1 层：解析搜索条件                                        │
│  - 文件名模式：*.py                                         │
│  - 内容模式：TODO                                           │
│  - 排除模式：node_modules, .git                             │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│  第 2 层：Glob 匹配 (文件名)                                  │
│  - 通配符解析                                                 │
│  - 递归遍历                                                   │
│  - 并行处理                                                   │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│  第 3 层：Grep 匹配 (内容)                                    │
│  - 正则表达式编译                                           │
│  - 逐行扫描                                                   │
│  - 上下文提取                                                 │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│  第 4 层：结果聚合                                            │
│  - 去重                                                       │
│  - 排序                                                       │
│  - 分页                                                       │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│  返回结果                                                   │
│  - 文件列表 + 匹配行 + 上下文                                │
└─────────────────────────────────────────────────────────────┘

GlobTool：文件名模式匹配

通配符语法

通配符	含义	示例	匹配
*	任意字符 (不含路径分隔符)	*.py	test.py, main.py
**	任意字符 (含路径分隔符)	**/*.py	src/test.py, a/b/c.py
?	单个字符	test?.py	test1.py, testA.py
[abc]	字符集合	test[123].py	test1.py, test2.py
[!abc]	否定字符集合	test[!1].py	test2.py, testA.py

核心算法：通配符转正则

function globToRegex(pattern: string): RegExp {
  let regex = '';
  let i = 0;
  
  while (i < pattern.length) {
    const char = pattern[i];
    
    if (char === '*') {
      // 检查是否是 **
      if (pattern[i + 1] === '*') {
        regex += '.*';  // 匹配任意字符 (包括/)
        i += 2;
        // 跳过后续的 /
        if (pattern[i] === '/') i++;
      } else {
        regex += '[^/]*';  // 匹配任意字符 (不包括/)
        i++;
      }
    } else if (char === '?') {
      regex += '[^/]';  // 匹配单个字符 (不包括/)
      i++;
    } else if (char === '[') {
      // 字符集合
      const end = pattern.indexOf(']', i);
      regex += pattern.substring(i, end + 1);
      i = end + 1;
    } else if (['.', '^', '$', '+', '{', '}', '(', ')', '|', '\\'].includes(char)) {
      regex += '\\' + char;  // 转义特殊字符
      i++;
    } else {
      regex += char;
      i++;
    }
  }
  
  return new RegExp(`^${regex}$`);
}

示例：

模式：src/**/*.py

转换过程：
src/      → src/
**        → .*
/         → (跳过)
*.py      → [^/]*\.py

结果：^src/.*[^/]*\.py$

匹配：
✅ src/test.py
✅ src/a/b/c.py
❌ test.py (不在 src/ 下)

并行遍历实现

async function glob(
  pattern: string,
  options: GlobOptions
): Promise<string[]> {
  const regex = globToRegex(pattern);
  const results: string[] = [];
  
  // 使用并行遍历
  async function walkDir(dir: string): Promise<void> {
    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
    
    // 并行处理所有条目
    await Promise.all(entries.map(async (entry) => {
      const fullPath = path.join(dir, entry.name);
      
      // 检查是否排除
      if (isExcluded(fullPath, options.exclude)) {
        return;
      }
      
      // 检查是否匹配
      if (regex.test(fullPath)) {
        results.push(fullPath);
      }
      
      // 递归遍历子目录
      if (entry.isDirectory()) {
        await walkDir(fullPath);
      }
    }));
  }
  
  await walkDir(options.cwd || '.');
  return results;
}

性能优化：

// 使用 ripgrep (rg) 加速
import { exec } from 'child_process';

async function globFast(pattern: string): Promise<string[]> {
  return new Promise((resolve) => {
    exec(`rg --files --glob "${pattern}"`, (error, stdout) => {
      if (error) {
        resolve([]);
      } else {
        resolve(stdout.trim().split('\n').filter(Boolean));
      }
    });
  });
}

性能对比：

方法	1000 文件	1 万文件	10 万文件
原生遍历	50ms	500ms	5s
并行遍历	20ms	200ms	2s
ripgrep	5ms	50ms	500ms

GrepTool：内容搜索

核心算法：正则匹配

interface GrepResult {
  file: string;
  line: number;
  content: string;
  match: string;
}

async function grep(
  pattern: string,
  options: GrepOptions
): Promise<GrepResult[]> {
  const regex = new RegExp(pattern, options.flags || 'g');
  const results: GrepResult[] = [];
  
  // 获取匹配的文件列表
  const files = await glob(options.pattern || '**/*', {
    exclude: options.exclude,
  });
  
  // 并行搜索所有文件
  await Promise.all(files.map(async (file) => {
    try {
      const content = await fs.promises.readFile(file, 'utf-8');
      const lines = content.split('\n');
      
      for (let i = 0; i < lines.length; i++) {
        const line = lines[i];
        const match = line.match(regex);
        
        if (match) {
          results.push({
            file,
            line: i + 1,
            content: line,
            match: match[0],
          });
        }
      }
    } catch (error) {
      // 跳过无法读取的文件
    }
  }));
  
  return results;
}

上下文提取

interface GrepResultWithContext extends GrepResult {
  before: string[];  // 前 N 行
  after: string[];   // 后 N 行
}

function addContext(
  result: GrepResult,
  lines: string[],
  contextLines: number
): GrepResultWithContext {
  const lineIndex = result.line - 1;
  
  const before = lines.slice(
    Math.max(0, lineIndex - contextLines),
    lineIndex
  );
  
  const after = lines.slice(
    lineIndex + 1,
    Math.min(lines.length, lineIndex + contextLines + 1)
  );
  
  return {
    ...result,
    before,
    after,
  };
}

输出示例：

src/utils/helper.py:25:    # TODO: 优化性能
  前：def process_data(data):
  前：    result = []
  匹配：    # TODO: 优化性能
  后：    for item in data:
  后：        result.append(transform(item))

高性能实现 (使用 ripgrep)

interface RipgrepResult {
  path: string;
  line_number: number;
  lines: { text: string };
  submatches: { match: string; start: number; end: number }[];
}

async function grepWithRipgrep(
  pattern: string,
  options: GrepOptions
): Promise<GrepResult[]> {
  const args = [
    '--json',           // JSON 输出
    '--line-number',    // 显示行号
    pattern,
  ];
  
  // 添加文件模式
  if (options.pattern) {
    args.push('--glob', options.pattern);
  }
  
  // 添加排除
  if (options.exclude) {
    for (const exc of options.exclude) {
      args.push('--glob', `!${exc}`);
    }
  }
  
  // 添加上下文
  if (options.context) {
    args.push('--context', options.context.toString());
  }
  
  return new Promise((resolve) => {
    const process = spawn('rg', args, { cwd: options.cwd });
    const results: GrepResult[] = [];
    
    process.stdout.on('data', (data) => {
      const lines = data.toString().split('\n');
      for (const line of lines) {
        if (line.trim()) {
          const parsed = JSON.parse(line) as RipgrepResult;
          results.push({
            file: parsed.path,
            line: parsed.line_number,
            content: parsed.lines.text,
            match: parsed.submatches[0]?.match || '',
          });
        }
      }
    });
    
    process.on('close', () => {
      resolve(results);
    });
  });
}

性能对比：

方法	1000 文件	1 万文件	10 万文件
原生 JS	100ms	1s	10s
并行 JS	50ms	500ms	5s
ripgrep	10ms	100ms	1s

组合使用：Glob + Grep

async function search(
  fileNamePattern: string,
  contentPattern: string,
  options: SearchOptions
): Promise<SearchResult[]> {
  // 1. Glob 匹配文件名
  const files = await glob(fileNamePattern, {
    exclude: options.exclude,
  });
  
  // 2. Grep 匹配内容
  const results: SearchResult[] = [];
  
  for (const file of files) {
    const grepResults = await grepInFile(file, contentPattern);
    results.push(...grepResults);
  }
  
  // 3. 返回结果
  return results;
}

// 使用示例
const results = await search(
  '**/*.py',      // Python 文件
  'TODO',         // 包含 TODO
  { exclude: ['node_modules', '.git'] }
);

---

设计思想：为什么这样设计

思想 1：工具分离，各司其职

问题： 为什么不用一个工具完成所有搜索？

解决： Glob 和 Grep 分离。

工具	职责	优势
GlobTool	文件名匹配	快速过滤，不读取内容
GrepTool	内容匹配	精确搜索，支持正则

设计智慧：

分离关注点，每个工具做好一件事。

使用方式：

仅文件名搜索：
→ GlobTool ("找所有 *.py 文件")

仅内容搜索：
→ GrepTool ("找所有包含 TODO 的文件")

组合搜索：
→ GlobTool + GrepTool ("找所有 *.py 文件中包含 TODO 的行")

思想 2：性能优先，多层优化

优化层次：

第 1 层：排除无关目录
→ node_modules, .git, .venv

第 2 层：文件名预过滤
→ 先用 Glob 缩小范围

第 3 层：并行处理
→ 多文件同时搜索

第 4 层：原生工具
→ 使用 ripgrep (Rust 实现)

性能提升：

原始实现：10 万文件 → 10 秒
  ↓ 排除优化
5 秒
  ↓ 并行处理
2 秒
  ↓ ripgrep
0.5 秒

总提升：20 倍

思想 3：灵活匹配，适应用户习惯

问题： 用户的搜索习惯不同。

解决： 支持多种匹配模式。

// 模式 1：精确匹配
search("TODO")
→ 匹配 "TODO"

// 模式 2：正则匹配
search("TODO\\w+")
→ 匹配 "TODO123", "TODO_FIX"

// 模式 3：忽略大小写
search("todo", { caseSensitive: false })
→ 匹配 "TODO", "todo", "Todo"

// 模式 4：全词匹配
search("\\bTODO\\b")
→ 匹配 "TODO", 不匹配 "TODOLIST"

思想 4：结果友好，便于理解

问题： 搜索结果如何呈现？

解决： 结构化输出 + 上下文。

interface SearchResult {
  file: string;        // 文件路径
  line: number;        // 行号
  content: string;     // 完整行内容
  match: string;       // 匹配的部分
  before: string[];    // 前 N 行 (上下文)
  after: string[];     // 后 N 行 (上下文)
}

输出示例：

找到 3 个匹配：

1. src/utils/helper.py:25
   # TODO: 优化性能
   ───────────────────────
   def process_data(data):
       result = []
   →   # TODO: 优化性能
       for item in data:
           result.append(transform(item))

2. src/api/user.py:48
   # TODO: 添加缓存
   ...

思想 5：智能排除，减少干扰

默认排除：

const defaultExclude = [
  'node_modules/**',
  '.git/**',
  '.svn/**',
  '.hg/**',
  '__pycache__/**',
  '*.pyc',
  '*.pyo',
  '.DS_Store',
  'Thumbs.db',
];

为什么排除这些？

目录/文件	原因
node_modules	依赖库，通常不需要搜索
.git	版本控制元数据
pycache	Python 字节码缓存
*.pyc	编译后的文件

用户可覆盖：

// 搜索时指定包含
search("TODO", {
  exclude: [],  // 不排除任何目录
})

// 或添加自定义排除
search("TODO", {
  exclude: ['dist/**', 'build/**'],
})

---

解决方案：完整实现详解

GlobTool 实现

export class GlobTool extends Tool {
  name = 'glob';
  description = '搜索匹配模式的文件';
  
  inputSchema = {
    type: 'object',
    properties: {
      pattern: {
        type: 'string',
        description: 'Glob 模式，如 **/*.py',
      },
      cwd: {
        type: 'string',
        description: '搜索根目录',
      },
      exclude: {
        type: 'array',
        items: { type: 'string' },
        description: '排除的模式',
      },
    },
    required: ['pattern'],
  };
  
  async execute(input: GlobInput, context: ToolContext): Promise<ToolResult> {
    try {
      const files = await glob(input.pattern, {
        cwd: input.cwd || context.cwd,
        exclude: input.exclude || DEFAULT_EXCLUDE,
      });
      
      return {
        success: true,
        files,
        count: files.length,
      };
      
    } catch (error) {
      return {
        success: false,
        error: error.message,
      };
    }
  }
}

GrepTool 实现

export class GrepTool extends Tool {
  name = 'grep';
  description = '搜索文件内容';
  
  inputSchema = {
    type: 'object',
    properties: {
      pattern: {
        type: 'string',
        description: '正则表达式',
      },
      path: {
        type: 'string',
        description: '搜索路径',
      },
      pattern: {
        type: 'string',
        description: '文件模式 (如 *.py)',
      },
      exclude: {
        type: 'array',
        items: { type: 'string' },
        description: '排除的模式',
      },
      context: {
        type: 'number',
        description: '上下文行数',
      },
      flags: {
        type: 'string',
        description: '正则标志 (i=忽略大小写)',
      },
    },
    required: ['pattern'],
  };
  
  async execute(input: GrepInput, context: ToolContext): Promise<ToolResult> {
    try {
      const results = await grepWithRipgrep(input.pattern, {
        cwd: context.cwd,
        pattern: input.path,
        exclude: input.exclude,
        context: input.context || 2,
        flags: input.flags,
      });
      
      return {
        success: true,
        results,
        count: results.length,
      };
      
    } catch (error) {
      return {
        success: false,
        error: error.message,
      };
    }
  }
}

组合搜索实现

export class SearchTool extends Tool {
  name = 'search';
  description = '组合搜索 (文件名 + 内容)';
  
  async execute(input: SearchInput, context: ToolContext): Promise<ToolResult> {
    // 1. Glob 匹配文件名
    const files = await glob(input.filePattern, {
      cwd: context.cwd,
      exclude: input.exclude,
    });
    
    // 2. Grep 匹配内容
    const results: SearchResult[] = [];
    
    for (const file of files) {
      const content = await fs.promises.readFile(file, 'utf-8');
      const lines = content.split('\n');
      const regex = new RegExp(input.contentPattern, input.flags || 'g');
      
      for (let i = 0; i < lines.length; i++) {
        const match = lines[i].match(regex);
        if (match) {
          results.push({
            file,
            line: i + 1,
            content: lines[i],
            match: match[0],
            before: lines.slice(Math.max(0, i - 2), i),
            after: lines.slice(i + 1, i + 3),
          });
        }
      }
    }
    
    return {
      success: true,
      results,
      count: results.length,
      files: files.length,
    };
  }
}

性能优化：流式处理

async function grepStream(
  pattern: string,
  options: GrepOptions
): Promise<AsyncIterable<GrepResult>> {
  const regex = new RegExp(pattern, options.flags);
  
  // 使用流式处理，避免一次性加载所有文件
  return {
    async *[Symbol.asyncIterator]() {
      const files = await glob(options.pattern || '**/*');
      
      for (const file of files) {
        const stream = fs.createReadStream(file, { encoding: 'utf-8' });
        const reader = readline.createInterface({
          input: stream,
          crlfDelay: Infinity,
        });
        
        let lineNumber = 0;
        
        for await (const line of reader) {
          lineNumber++;
          
          if (regex.test(line)) {
            yield {
              file,
              line: lineNumber,
              content: line,
              match: line.match(regex)![0],
            };
          }
        }
      }
    },
  };
}

// 使用示例
const search = grepStream('TODO', { pattern: '**/*.py' });

for await (const result of search) {
  console.log(`${result.file}:${result.line}: ${result.content}`);
  // 可以提前终止
  if (result.line > 100) break;
}

---

OpenClaw 最佳实践

实践 1：创建搜索工具插件

目录结构：

~/.openclaw/extensions/file-search/
├── index.ts
├── tools/
│   ├── GlobTool.ts
│   ├── GrepTool.ts
│   └── SearchTool.ts
└── config.yaml

插件入口：

import { GlobTool } from './tools/GlobTool';
import { GrepTool } from './tools/GrepTool';
import { SearchTool } from './tools/SearchTool';

export const plugin = {
  name: 'file-search',
  version: '1.0.0',
  
  async init(gateway: any) {
    gateway.registerTool('glob', new GlobTool());
    gateway.registerTool('grep', new GrepTool());
    gateway.registerTool('search', new SearchTool());
    
    console.log('[file-search] 3 tools registered');
  },
};

实践 2：常用搜索命令

# 搜索所有 Python 文件
openclaw run glob --pattern "**/*.py"

# 搜索包含 TODO 的文件
openclaw run grep --pattern "TODO" --context 2

# 组合搜索：Python 文件中的 TODO
openclaw run search \
  --file-pattern "**/*.py" \
  --content-pattern "TODO"

# 排除 node_modules
openclaw run grep \
  --pattern "axios" \
  --exclude "node_modules/**"

# 忽略大小写
openclaw run grep \
  --pattern "todo" \
  --flags "i"

实践 3：Agent 对话集成

用户："帮我找一下项目中所有用到 axios 的地方"

AI：```bash
grep -r "axios" --include="*.py" --include="*.js"

找到 5 个匹配：

1. src/api/client.js:3
   import axios from ‘axios’;

2. src/api/user.js:5
   const response = await axios.get(‘/api/users’);

…

### 实践 4：性能调优

**配置文件：**

```yaml
# ~/.openclaw/config/search.yaml

# 默认排除
default_exclude:
  - node_modules/**
  - .git/**
  - dist/**
  - build/**
  - "*.pyc"
  - "*.pyo"

# 性能设置
performance:
  # 并行度
  parallelism: 4
  
  # 单个文件最大大小 (MB)
  max_file_size: 10
  
  # 最大结果数
  max_results: 1000
  
  # 使用 ripgrep
  use_ripgrep: true

实践 5：结果格式化

function formatResults(results: SearchResult[]): string {
  if (results.length === 0) {
    return '没有找到匹配的结果';
  }
  
  let output = `找到 ${results.length} 个匹配:\n\n`;
  
  for (const result of results.slice(0, 10)) {
    output += `${result.file}:${result.line}\n`;
    output += `${result.content}\n`;
    
    if (result.before.length > 0) {
      output += `前：${result.before.join('\\n')}\n`;
    }
    if (result.after.length > 0) {
      output += `后：${result.after.join('\\n')}\n`;
    }
    output += '\n';
  }
  
  if (results.length > 10) {
    output += `\n... 还有 ${results.length - 10} 个结果`;
  }
  
  return output;
}

---

总结

核心要点

1. 工具分离 - Glob 负责文件名，Grep 负责内容
2. 性能优先 - 排除优化、并行处理、原生工具
3. 灵活匹配 - 支持通配符、正则、大小写选项
4. 结果友好 - 结构化输出 + 上下文
5. 智能排除 - 默认排除无关目录

设计智慧

好的搜索工具，让用户感觉文件系统在”主动配合”。

Claude Code 的搜索工具设计告诉我们：

• 性能是搜索工具的生命线
• 灵活性决定用户体验
• 结果呈现影响使用效率

性能对比

操作	原始实现	优化后	提升
Glob 10 万文件	5s	0.5s	10 倍
Grep 10 万文件	10s	1s	10 倍
组合搜索	15s	1.5s	10 倍

下一步

• 创建 file-search 插件
• 集成 ripgrep
• 添加流式处理
• 优化结果展示

---

系列文章：

• [1] Bash 命令执行的安全艺术 (已发布)
• [2] 差异编辑的设计艺术 (已发布)
• [3] 文件搜索的底层原理 (本文)
• [4] 多 Agent 协作的架构设计 (待发布)
• …

上一篇： Claude Code 源码解析 (2)：差异编辑的设计艺术

---

关于作者： John，OpenClaw 平台开发者，专注 AI 助手架构设计与实现。