file-search

文件搜索技能

使用 ripgrep 搜索文本模式，并使用 ast-grep 搜索结构化代码模式，从而高效地搜索代码。

用途

文件搜索技能可使用 MassGen 环境中预装的两种强大搜索工具：

1. ripgrep (rg)：支持正则表达式的超快速文本搜索，可查找字符串、模式和文本匹配项
2. ast-grep (sg)：可根据抽象语法树查找代码模式的语法感知型结构搜索工具

使用这些工具了解代码库、查找用法模式、分析更改影响并定位特定代码结构。两者的速度都远超传统的 grep 或 find 命令。

何时使用此技能

以下情况可使用文件搜索技能：

• 了解新的代码库（查找入口点、关键类）
• 重构前查找函数、类或变量的所有用法
• 定位特定代码模式（错误处理、API 调用等）
• 搜索安全问题（硬编码凭据、SQL 查询、eval 用法）
• 分析依赖项和导入
• 查找 TODO、FIXME 或代码注释

以下情况选择 ripgrep：

• 基于文本的搜索（字符串、注释、变量名）
• 在大量文件中快速进行简单模式匹配
• 不需要关注代码的确切结构

以下情况选择 ast-grep：

• 结构化代码搜索（函数签名、类定义）
• 语法感知型匹配（理解代码语义）
• 复杂重构（查找特定代码模式）

调用搜索工具

在 MassGen 中，使用 execute_command 工具运行 ripgrep 和 ast-grep：

# Using ripgrep
execute_command("rg 'pattern' --type py src/")

# Using ast-grep
execute_command("sg --pattern 'class $NAME { $$$ }' --lang python")

这两种工具都预装在 MassGen Docker 容器中，可通过 Shell 执行。

定向搜索

重要：始终从范围明确、目标具体的搜索开始，以免结果过多。数千条匹配项会让分析变得不可能，还会浪费令牌。

以下策略适用于 ripgrep 和 ast-grep。

限定范围的策略

从一开始就应用这些策略，进行有效的定向搜索：

1. 指定文件类型/语言：始终按语言筛选

   # Ripgrep
   rg "function" --type py --type js
   
   # AST-grep
   sg --pattern 'function $NAME($$$) { $$$ }' --lang js
   

2. 指定目标目录：先搜索可能包含目标的目录

   # Ripgrep
   rg "LoginService" src/services/
   
   # AST-grep
   sg --pattern 'class LoginService { $$$ }' src/services/
   

3. 使用具体模式：尽可能让模式具体

   # Ripgrep: BAD - too broad
   rg "user"
   # Ripgrep: GOOD - more specific
   rg "class.*User.*Service" --type py
   
   # AST-grep: BAD - too broad
   sg --pattern '$X'
   # AST-grep: GOOD - more specific
   sg --pattern 'class $NAME extends UserService { $$$ }' --lang js
   

4. 限制结果数量：使用 head 限制结果数

   # Ripgrep
   rg "import" --type py | head -20
   rg "TODO" --count
   
   # AST-grep
   sg --pattern 'import $X from $Y' --lang js | head -20
   

逐步细化搜索

探索不熟悉的代码时，可使用以下工作流：

Ripgrep 示例：

# Step 1: Count matches to assess scope
rg "pattern" --count --type py

# Step 2: If too many results, add more filters
rg "pattern" --type py src/ --glob '!tests'

# Step 3: Show limited results to inspect
rg "pattern" --type py src/ | head -30

# Step 4: Once confirmed, get full results or target further
rg "pattern" --type py src/specific_module/

AST-grep 示例：

# Step 1: Assess scope with broad structural pattern
sg --pattern 'function $NAME($$$) { $$$ }' --lang js | head -10

# Step 2: If too many results, narrow to specific directory
sg --pattern 'function $NAME($$$) { $$$ }' --lang js src/

# Step 3: Make pattern more specific
sg --pattern 'async function $NAME($$$) { $$$ }' --lang js src/

# Step 4: Target exact location
sg --pattern 'async function $NAME($$$) { $$$ }' --lang js src/services/

结果过多时

如果搜索返回数百条匹配项（适用于 rg 和 sg）：

1. 添加文件类型/语言筛选条件：使用 --type py（rg）或 --lang python（sg）
2. 缩小目录范围：搜索 src/，而不是 .
3. 让模式更具体：为模式添加上下文
4. 使用单词边界：使用 -w 标志，仅匹配完整单词（rg）
5. 通过管道传递给 head：使用 | head -50 限制输出
6. 排除测试文件：使用 --glob '!*test*'（rg），或避开测试目录（sg）

细化示例：

# Step 1: Too broad (10,000+ matches)
rg "error"

# Step 2: Add file type (1,000 matches)
rg "error" --type py

# Step 3: Add directory scope (200 matches)
rg "error" --type py src/

# Step 4: Make pattern specific (20 matches)
rg "raise.*Error" --type py src/

# Step 5: Target exact location (5 matches)
rg "raise.*Error" --type py src/services/

使用方法

Ripgrep (rg)

# Basic text search
rg "pattern" --type py --type js

# Common flags
-i              # Case-insensitive
-w              # Match whole words only
-l              # Show only filenames
-n              # Show line numbers
-C 3            # Show 3 lines of context
--count         # Count matches per file
--glob '!dir'   # Exclude directory

# Examples
rg "function.*login" --type js src/
rg -i "TODO" --count
rg "auth|login|session" --type py

AST-Grep (sg)

# Structural code search
sg --pattern 'function $NAME($$$) { $$$ }' --lang js

# Metavariables
$VAR     # Matches single AST node
$$$      # Matches zero or more nodes

# Examples
sg --pattern 'class $NAME { $$$ }' --lang python
sg --pattern 'import $X from $Y' --lang js
sg --pattern 'async function $NAME($$$) { $$$ }' src/

常见搜索模式

# Security issues
rg -i "password\s*=\s*['\"]" --type py
rg "\beval\(" --type js

# TODOs and comments
rg "TODO|FIXME|HACK"

# Code structures
sg --pattern 'class $NAME { $$$ }' --lang python
sg --pattern 'try { $$$ } catch ($E) { $$$ }' --lang js

# Dependencies
rg "from requests import" --type py
rg "require\(['\"]" --type js

# Refactoring
rg "\.old_method\(" --type py
rg "@deprecated" -A 5

文件类型筛选条件

常见的 ripgrep 文件类型：py、js、ts、rust、go、java、c、cpp、html、css、json、yaml、md

使用 --type-list 查看所有可用类型，或定义自定义类型：

rg --type-add 'config:*.{yml,yaml,toml,ini}' --type config "pattern"

性能提示

请参阅“定向搜索”部分，了解全面的策略。关键提示：

# Limit scope to specific directories
rg "pattern" src/

# Filter by file type
rg "pattern" --type py --type js

# Exclude large directories
rg "pattern" --glob '!{node_modules,venv,.git}'

# Use fixed strings (no regex) for speed
rg -F "exact string"

# Count before viewing full results
rg "pattern" --count --type py

最佳实践

1. 先缩小范围，再逐步扩大：从一开始就使用具体的模式、文件类型和目录范围
2. 先计数，再查看：使用 --count 或 | head -N 预览结果数量
3. 始终指定文件类型：使用 --type（rg）或 --lang（sg）按语言筛选
4. 排除常见干扰项：养成添加 --glob '!{node_modules,venv,.git,dist,build}' 的习惯
5. 组合使用工具：使用 rg 搜索文本模式，使用 sg 搜索结构化代码模式
6. 策略性地使用上下文：添加 -C N 查看周围行，但注意输出量

故障排除

• 未找到匹配项：检查文件类型筛选条件，尝试使用 -i 忽略大小写，先搜索部分模式
• 速度太慢：使用 --glob 排除目录，使用 --type 限制文件类型，缩小搜索路径
• AST-grep 问题：确认 --lang 是否正确，尝试更简单的模式，使用 rg 确认代码是否存在

资源

• Ripgrep 文档
• AST-grep 文档