用途：ast-grep 是快速、基于 Rust 的 CLI 工具，用 tree-sitter 解析代码并匹配语法树而非文本。当你关心的是代码的语法结构（如“所有形如 X 的调用”、模式重写、codemod、lint 规则）时使用它；纯文本、字符串、错误信息、配置值、文件名应改用 grep/rg/fd；跳转定义、跨作用域引用、类型、作用域感知重命名应使用 LSP/编译器工具；跨整个代码库的传递调用者、循环导入、死代码检测需要基于 ast-grep --json 输出编写图脚本，ast-grep 本身只做逐文件匹配。
主要能力：三种模式——搜索/重写用 ast-grep run -p '<pattern>'（默认命令），一次性查询与 codemod；lint 用 ast-grep scan，配合 YAML 规则集与 CI 检查；探索用 ast-grep outline 查看文件的符号、导入、导出。支持 JavaScript、TypeScript、TSX、Python、Rust、Go、Java、C、C++、C#、Kotlin、Swift、Ruby、PHP 等 25+ 语言。元变量 $VAR 匹配恰好一个 AST 节点，$$$ARGS 匹配零个或多个；参数、形参、函数体默认用 $$$，foo($ARG) 只匹配单参数调用，这是漏匹配最常见原因；重复名要求内容一致，$A == $A 匹配 x == x 而非 x == y；名称用 A-Z、_、数字，$var 无效，$_NAME 为非捕获。
使用方式：安装前先 which ast-grep，未安装可运行 bash <SKILL_DIR>/scripts/install.sh，脚本依次尝试 brew、cargo、npm、pip3、MacPorts 并验证结果；手动安装见 https://ast-grep.github.io/guide/quick-start.html。注意某些系统的 sg 是别的二进制（shell group），始终使用全名 ast-grep。示例：ast-grep -p 'console.log($$$ARGS)' -l ts src/；重写 var 为 const 并逐条交互确认：ast-grep -p 'var $N = $V' -r 'const $N = $V' -l js --interactive src/；全部应用：ast-grep -p '$P && $P()' -r '$P?.()' -l ts -U src/；仅列出含匹配的文件：--files-with-matches；JSON 输出：--json=compact（注意 --json 的值需用 =）；内联 YAML 规则：ast-grep scan --inline-rules '...'；stdin 测试模式：echo 'var x = 1' | ast-grep -p 'var $N = $V' -l js --stdin。模式务必用单引号，双引号会让 shell 先展开 $NAME。在线试验场：https://ast-grep.github.io/playground.html。
标准重写流程：搜索检查匹配；必要时加 --json=compact 核对匹配边界；加 -r 预览 diff（只打印不写入）；加 --interactive 逐条审阅或 -U 全部应用；再次搜索应返回退出码 1（无匹配），然后运行项目测试。重命名需多轮处理（定义、调用点、导入是不同节点类型）。
限制：ast-grep 匹配语法而非语义，无法区分不同作用域中的同名符号；用 ast-grep 重命名是精确的语法替换（会跳过注释、字符串和 oldNameHelper），但会命中所有作用域，真正语义重命名应优先用 LSP，无 LSP 时使用并核对 diff。模式无法匹配注释或字符串内容内部。代码库很小（少于 5 个文件）时直接读文件即可。有语法错误的文件通常仍可工作，tree-sitter 错误恢复仍能匹配有效区域。CLI 无状态，不启动服务、不建索引，与 LSP 工具无运行时冲突。退出码：run 中 0 表示至少一个匹配，1 表示无匹配（脚本中“无匹配”不是错误）；scan 中 0 表示干净，1 表示发现 error 级诊断，可用作 CI 门禁；其他非零码表示用法或配置错误（如 2 标志错误、8 无效模式/规则）。管道会掩盖退出码，需要 ast-grep 状态时设置 set -o pipefail。内容基于 ast-grep 0.45.1 验证，标志可能随版本变化，命令失败时查看 ast-grep <cmd> --help。参考文件按需读取：references/cli-reference.md、pattern-syntax.md、rule-yaml.md、pattern-cookbook.md。附带脚本 scripts/install.sh 与 scripts/json-summary.py（汇总 --json 输出，统计每文件匹配数并给出紧凑匹配列表）。