ast-grep（命令名 sg）是一款按 AST 结构而非文本进行代码搜索的工具。它通过可解析的代码模式配合 $VAR 元变量作为通配符来匹配代码结构，适合在需要查找代码模式或进行大规模重构时使用。
主要能力
基本搜索： ast-grep run -l ts --pattern 'console.log($X)' src/ ast-grep run --pattern '$FUNC()' agent/extensions/ # 自动检测语言
模式语法
$VAR — 匹配单个 AST 节点（仅大写：$MOD、$_）
$$$VAR — 匹配零个或多个节点（函数参数、语句）
$_VAR — 非捕获（同名可匹配不同内容）
模式必须是有效代码：import { $X } from "$Y" 可用，裸写 from $X 会失败
常见模式
查找再导出（barrel 文件）： ast-grep run -l ts --pattern 'export * from "$Y"' ./ ast-grep run -l ts --pattern 'export { $$$X } from "$Y"' ./
查找来自某模块的所有导入： ast-grep run -l ts --pattern 'import { $$$X } from "$MOD"' ./
查找具有特定结构的函数调用： ast-grep run -l ts --pattern 'console.log($MSG)' ./ ast-grep run -l ts --pattern 'fetch($URL).then($H)' ./
检测反模式（Promise.all 内的 await）：
ast-grep run -l ts --pattern 'await $X' ./
--selector call_expression
--pattern 'Promise.all($$_)'
规则
模式必须是有效且可解析的代码 — 用 --debug-query=ast 测试
使用 $VAR（大写）作为元变量；$_VAR 用于非捕获
当模式静默失败时使用 --debug-query=ast
先在 playground 中验证复杂模式
适用场景
适用于按代码结构查找模式、批量重构、检测反模式等任务。
限制
模式必须是有效且可解析的代码，否则会失败；建议使用 --debug-query=ast 调试，并先在 playground 中验证复杂模式。