---

name: structural-search description: "使用 ast-grep 按 AST 结构搜索代码。查找语义模式如函数调用、导入、类定义，而非文本模式。触发条件：find all calls to X、search for pattern、refactor usages、find where function is used、structural search、ast-grep、sg。" license: MIT compatibility: "需要 ast-grep (sg) CLI 工具。安装：brew install ast-grep (macOS) 或 cargo install ast-grep (跨平台)。" allowed-tools: "Bash" metadata: author: claude-mods

结构化搜索

按抽象语法树（AST）结构搜索代码。查找正则表达式无法可靠匹配的语义模式。

工具

| 工具 | 命令 | 用途 | |------|---------|---------| | ast-grep | sg -p 'pattern' | AST 感知的代码搜索 |

模式语法

| 模式 | 匹配 | 示例 | |---------|---------|---------| | $NAME | 命名标识符 | function $NAME() {} | | $_ | 任意单个节点 | console.log($_) | | $$$ | 零个或多个节点 | function $_($$$) {} |

十大必备模式

# 1. 查找 console.log 调用
sg -p 'console.log($_)'

# 2. 查找 React hooks
sg -p 'const [$_, $_] = useState($_)'
sg -p 'useEffect($_, [$$$])'

# 3. 查找函数定义
sg -p 'function $NAME($$$) { $$$ }'
sg -p 'def $NAME($$$): $$$' --lang python

# 4. 查找导入
sg -p 'import $_ from "$_"'
sg -p 'from $_ import $_' --lang python

# 5. 查找异步模式
sg -p 'await $_'
sg -p 'async function $NAME($$$) { $$$ }'

# 6. 查找错误处理
sg -p 'try { $$$ } catch ($_) { $$$ }'
sg -p 'if err != nil { $$$ }' --lang go

# 7. 查找潜在问题
sg -p '$_ == $_'           # == 而非 ===
sg -p 'eval($_)'           # 安全风险
sg -p '$_.innerHTML = $_'  # XSS 向量

# 8. 预览重构
sg -p 'console.log($_)' -r 'logger.info($_)'

# 9. 应用重构
sg -p 'var $NAME = $_' -r 'const $NAME = $_' --rewrite

# 10. 搜索特定语言
sg -p 'pattern' --lang typescript

快速参考

| 任务 | 命令 | |------|---------| | 查找模式 | sg -p 'pattern' | | 指定语言 | sg -p 'pattern' --lang python | | 替换（预览） | sg -p 'old' -r 'new' | | 替换（应用） | sg -p 'old' -r 'new' --rewrite | | 显示上下文 | sg -p 'pattern' -A 3 | | JSON 输出 | sg -p 'pattern' --json | | 仅文件列表 | sg -p 'pattern' -l | | 计数匹配 | sg -p 'pattern' --count | | 运行 YAML 规则 | sg scan |

何时使用

• 查找函数/方法的所有用法
• 定位特定代码模式（hooks、API 调用）
• 准备大规模重构
• 当正则表达式会产生误匹配时
• 检测反模式和安全问题
• 创建自定义 lint 规则

附加资源

完整模式请加载：

• ./references/js-ts-patterns.md - JavaScript/TypeScript 模式
• ./references/python-patterns.md - Python 模式
• ./references/go-rust-patterns.md - Go 和 Rust 模式
• ./references/security-ops.md - 安全漏洞检测
• ./references/advanced-usage.md - YAML 规则和工具集成
• ./assets/rule-template.yaml - 自定义规则入门模板