用途：ast-grep 用于按代码结构而非文本进行搜索。当需求涉及语法形状（后代、祖先、调用形式、装饰器、缺失结构、嵌套上下文）或多语言结构搜索时使用；精确名称、字符串、注释等简单文本用 rg，类型解析、引用、导入、重命名安全等语义事实用语言工具。
主要能力：支持单节点模式搜索与 YAML 规则；规则可使用 has、inside、not、any、all、regex、nthChild 及可复用元数据；支持 --json 输出供下游脚本消费；提供 --debug-query=ast 或 cst 打印解析树用于调试。
使用方式：先确定语言与目标文件，写一个最小 fixture（含正例，必要时加反例），从最简单模式开始，用 ast-grep run --pattern ... --lang ... 做单节点搜索，复杂需求改用 YAML 规则文件。规则文件可避免 shell 引号问题，复杂搜索优先使用。示例：ast-grep scan --rule async-await.yml ./src，加 --json 输出 JSON。内联规则仅用于快速检查，必须包含 id、language、rule 三个字段。Windows 上规则文件需保存为 UTF-8 无 BOM，否则 scan --rule 可能报缺少 language 字段。
适用场景：语法感知的代码搜索、结构重构发现、多语言结构匹配、查找特定调用形式或缺失结构。
限制：不适用于纯文本搜索或语义分析；需注意假阴性与假阳性，例如 JavaScript/TypeScript 中“函数”可能对应 function_declaration、function、arrow_function、method_definition 及类字段或对象属性中的函数；React 需区分 .js、.jsx、.ts、.tsx；Python 缩进敏感的多行模式需先检查解析形状。--debug-query 会打印诊断输出并可能以非零状态退出，应视为调试输出而非搜索失败。若未安装 ast-grep，应说明并提供 rg 回退，但不得把回退伪装成结构化搜索。