关于 ast-grep
ast-grep 是一项将自然语言代码搜索需求转成 ast-grep 规则的技能，可先用示例验证，再在代码库中运行，并提供规则编写与调试流程。
主要功能
- 01将查询转为 ast-grep 规则
- 02用示例代码测试规则
- 03按模式或规则搜索代码
- 04调试语法与 AST 匹配
适用场景
- 01查找符合指定结构的代码
- 02编写和调整关系规则
- 03规则未匹配时检查 AST 节点
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/ast-grep确认已加载。
附带文件references/rule_reference.md
详细介绍
ast-grep 代码搜索
将自然语言查询转换为 ast-grep 规则，使用示例验证规则，然后在代码库中运行。完整规则语法（原子规则、关系规则、复合规则、元变量、故障排查和实例）见 references/rule_reference.md——编写简单的 pattern 以外的规则时，请阅读该文档。
前置条件
ast-grep --version 必须能正常运行。如果缺少该命令，请执行：brew install ast-grep（macOS）、npm i -g @ast-grep/cli 或 cargo install ast-grep。请使用 ast-grep 调用（sg 别名与系统的 sg 冲突）。
工作流
- 明确需求——使用什么语言？要匹配的确切结构是什么？有哪些需要纳入或排除的边缘情况？
- 制作示例——编写一段应该匹配的小代码片段，并保存到临时文件中。
- 编写规则——从最简单的可行方案开始，再逐步增加复杂度：
- 直接代码结构使用
pattern→ 节点类型使用kind→ 关系规则使用has/inside→ 复合规则使用all/any/not。 - 关系规则中始终添加
stopBy: end，这样规则会遍历整个子树，而不是在遇到第一个不匹配项时停止。
- 直接代码结构使用
- 针对示例测试，直到规则匹配为止（参见下文的调试部分）。
- 规则匹配后，在代码库中运行。
命令
| 目标 | 命令 |
|---|---|
| 搜索简单模式 | ast-grep run --pattern 'console.log($ARG)' --lang js . |
| 搜索规则文件 | ast-grep scan --rule rule.yml /path |
| 内联规则，无需文件 | ast-grep scan --inline-rules "$YAML" /path |
| 在代码片段上测试规则 | echo '<code>' | ast-grep scan --inline-rules "$YAML" --stdin |
检查 AST，查找 kind 值 | ast-grep run --pattern '<code>' --lang js --debug-query=cst |
在上述任一命令中添加 --json，即可获取结构化输出。--debug-query 接受 cst（所有节点）、ast（仅命名节点）或 pattern（ast-grep 如何读取你的模式）。
简单的单节点匹配请使用 run --pattern；需要关系或复合逻辑时，请使用 scan（规则文件或内联规则）。
内联规则中的转义
Shell 会展开 $，因此在双引号括起的 --inline-rules 中请写作 \$VAR，或者用单引号括起 YAML：
ast-grep scan --inline-rules "rule: {pattern: 'console.log(\$ARG)'}" .
ast-grep scan --inline-rules 'rule: {pattern: "console.log($ARG)"}' .
无法匹配的规则的调试方法
- 简化——将子规则逐步缩减到最小的失败部分。
- 确认关系规则包含
stopBy: end。 - 使用
--debug-query=cst查看实际节点结构，并确认kind值正确。 - 检查元变量是否已检测到（参见参考文档中的元变量说明）。
资源
- references/rule_reference.md——完整规则语法和实例。
- ast-grep 文档 · playground，可用于在线测试模式。
评论
支持 Markdown