用途：hai-ast-grep 针对“匹配依赖代码语法结构”的搜索、lint 或重写场景，要求最终交付的不只是模式本身，而是一个经过正向和反向用例验证、能命中该命中的、不误伤不该命中的命令或规则。
主要能力：ast-grep 借助 tree-sitter 将代码解析为 AST 做精确匹配。一次性搜索与重写可直接走 CLI；可复用的 lint/codemod 规则用 YAML 编写。常用标志包括 -p 指定 AST 模式、-r 指定重写模板（在 run 中；在 scan 中 -r 指规则文件，勿混淆）、-l 指定语言、-i 逐条交互确认、-U 应用全部重写、-C 上下文行、--json 机器可读输出。默认子命令即 run，无需 YAML 或 sgconfig；可复用项目扫描才需要 sgconfig.yml 与规则目录。
使用方式：先用 CLI 探索模式，如 ast-grep run -p 'console.log($ARG)' src/，模式不匹配时用 --debug-query ast 查看节点类型。随后写规则文件，lint 规则包含 id、language、pattern、message、severity；需要自动修复时加一行 fix: 并用 ast-grep scan -r rules/x.yml --update-all src/ 应用，scan 不加该标志只报告。验证必须同时通过正向夹具（应匹配）与反向夹具（看似相似但不应匹配）；出现误报时用 constraints、not、inside、has 收窄，再重跑两个夹具。语法上用 $VAR 匹配单节点、$$$ARGS 匹配多节点。交付应包含 Goal、Rule、Fix（如适用）、Validation（夹具与命令及结果）、Notes 五部分。
适用场景与限制：适合跨多处调用点的结构化搜索或重写、CI 守卫、可复用 codemod。若只是纯文本或正则替换、单文件一次性修改、类型驱动的语义重构、主观代码质量审查、纯格式或导入排序，则应改用 grep/sed、直接编辑编译器、格式化工具等，ast-grep 在此类场景属于过度设计。项目配置、规则语法细节与常见模式见 references 下相应文档。部分细节暂未提供。