ast-grep（ast-grep代码搜索技能）Skill 是什么？如何下载？

ast-grep代码搜索技能Skill：让 AI 用抽象语法树帮你精准找到「有结构的代码」

一句话定位：它把「我想找所有用了 await 但没写 try-catch 的异步函数」这类自然语言需求，翻译成可执行的 ast-grep 结构化搜索规则。
核心能力：基于抽象语法树（AST）匹配代码结构，而不是简单匹配字符串，因此能区分「注释里的 console.log」和「真正执行的 console.log」。
交付物明确：技能会给出可复用的 YAML 规则文件、内联规则命令、测试样例代码，以及调试方法（--debug-query）。
适合人群：做代码审计、技术债治理、批量重构、框架迁移的开发者和技术负责人。
上手门槛：只需会用自然语言描述需求；命令行部分由技能生成，复制即可运行。

1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？

技能基本信息

项目	内容
中文名	ast-grep代码搜索技能Skill
英文名	ast-grep
技能ID	11799
技能类型	结构化代码搜索 / 规则编写指南类技能

它解决什么问题

传统的 grep、ripgrep 是「文本匹配」：搜 await 会把注释、字符串、文档里的人名一起搜出来；搜「异步函数里有没有错误处理」几乎无从下手。而 ast-grep 用抽象语法树做匹配，理解的是「这是一个函数声明节点」「这个节点下面有 await 表达式」这类结构关系。

问题在于：ast-grep 的规则语法（kind、has、inside、all/any/not、stopBy: end、元变量 $VAR）对新手并不友好。这个技能的价值，就是把「写规则」这一步交给 AI——你描述需求，它产出规则、测试样例和可执行命令。

「一键安装」的思路与步骤

AI 技能的安装本质是「让助手具备某项专业能力」，通常分三步走：

安装前提
- 你使用的 AI 助手 / Agent 平台支持加载自定义技能（Skill），并且已开启技能目录或技能市场功能（具体入口以官方说明为准）。
- 本机需要能运行 ast-grep 命令行，用于实际执行搜索；若尚未安装，请参照 ast-grep 官方文档完成安装（安装方式与版本要求以官方说明为准）。
导入技能
- 在技能市场搜索技能ID 11799，或按名称搜索「ast-grep代码搜索技能Skill」，点击安装 / 添加到我的技能（不同平台按钮名称不同，以官方说明为准）。
- 若平台支持本地技能目录导入，可将技能包放入对应目录后重启或刷新技能列表。
验证是否生效
- 在对话中提一个结构化搜索需求，例如：「帮我找 JavaScript 项目里所有使用了 await 但没有 try-catch 的函数」。
- 生效标志：助手输出的是 ast-grep 规则（YAML 或内联规则命令），包含 kind: function_declaration、has、stopBy: end、not 等元素，而不是简单给你一条 grep 命令。
- 若助手仍只会给文本搜索方案，说明技能未加载成功，请检查技能是否处于启用状态。

说明：本技能本身是「规则编写指南」，不包含计费信息，是否收费取决于你使用的 AI 平台与 ast-grep 工具自身的授权方式，均以官方说明为准。

2. 该技能的主要功能和特点

核心功能

自然语言转规则：把「查找具有特定参数的函数调用」「查找类方法里的 console.log」等口语化需求，翻译成合法的 ast-grep 规则。
结构化匹配：基于 AST 而非纯文本，按节点类型（kind）和模式（pattern）匹配代码结构。
关系规则：支持 inside（在某个结构内部）、has（包含某个子结构）等关系查询，用于表达「A 里面有没有 B」。
复合逻辑：支持 all、any、not 组合，能表达「有 await 且没有 try-catch」这种带否定的复杂查询。
元变量匹配：$VAR 匹配单个节点、$$$ 匹配多个节点，像写模板一样写搜索表达式。
两种执行方式：ast-grep run 用于简单模式搜索，ast-grep scan 用于复杂 YAML 规则搜索，且都支持 --json 结构化输出。
可调试：提供 --debug-query=cst、--debug-query=ast、--debug-query=pattern 三种视图，帮助理解代码被解析成什么结构、模式被如何解释。
标准化工作流：技能内置「理解查询 → 写示例代码 → 写规则 → 测试规则 → 搜索代码库」五步流程，避免一上来就写复杂规则导致失败。

和普通工具比强在哪

对比点	普通文本搜索	本技能加持下的 ast-grep
匹配依据	字符串	抽象语法树结构
能否表达「没有」	不能	能（`not` + `has`）
能否表达「在……内部」	不能	能（`inside`）
能否跳过注释和字符串	需额外规则	天然按语法节点匹配
写规则的门槛	——	由 AI 生成，用户只需描述需求

3. 如何使用该技能？

技能内置了标准化的五步工作流，按顺序执行即可。

步骤 1：把需求说清楚

用自然语言告诉助手你要找什么，尽量补充三个信息：编程语言、目标结构、边界情况。例如：

「在 JavaScript 项目里，找出所有使用了 await，但没有包在 try-catch 里的函数声明。」

步骤 2：让助手生成示例代码

技能会先产出一段最小可复现的示例代码，用于自测规则是否写对：

// test_example.js
async function example() {
  const result = await fetchData();
  return result;
}

步骤 3：生成规则文件

助手会输出一份 YAML 规则，例如：

id: async-with-await
language: javascript
rule:
  kind: function_declaration
  has:
    pattern: await $EXPR
    stopBy: end

写规则时的关键原则（技能会主动遵守）：

关系规则（inside、has）一律加 stopBy: end，确保遍历到子树末尾，而不是遇到第一个不匹配节点就停止；
简单结构用 pattern，复杂结构用 kind + has/inside；
复杂查询用 all、any、not 拆成小子规则组合。

步骤 4：在小样本上测试

两种测试方式，技能会根据复杂度推荐：

# 方式 A：内联规则快速验证（注意 $ 在双引号内需要转义为 \$）
echo "async function test() { await fetch(); }" | ast-grep scan --inline-rules "id: test
language: javascript
rule:
  kind: function_declaration
  has:
    pattern: await \$EXPR
    stopBy: end" --stdin

# 方式 B：规则文件测试（复杂规则推荐）
ast-grep scan --rule test_rule.yml test_example.js

如果没匹配上，按技能给出的调试顺序排查：简化规则 → 补 stopBy: end → 用 --debug-query 看 AST → 核对 kind 值是否适用于该语言。

步骤 5：在全量代码库执行

# 简单模式搜索
ast-grep run --pattern 'console.log($ARG)' --lang javascript /path/to/project

# 复杂规则搜索
ast-grep scan --rule my_rule.yml /path/to/project

# 需要接入其他脚本时，输出 JSON
ast-grep scan --rule my_rule.yml --json /path/to/project

输入与输出说明

输入：一句自然语言需求 + 目标代码库路径或代码片段。
输出：示例代码、YAML 规则、可直接执行的命令行、命中的代码位置（加 --json 时是结构化结果）。

复合查询示例：找出「有 await 但没有 try-catch」的函数

ast-grep scan --inline-rules "id: async-no-trycatch
language: javascript
rule:
  all:
    - kind: function_declaration
    - has:
        pattern: await \$EXPR
        stopBy: end
    - not:
        has:
          pattern: try { \$\$\$ } catch (\$E) { \$\$\$ }
          stopBy: end" /path/to/project

4. 同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
ast-grep（本技能）	基于 AST 的结构化代码搜索与规则化扫描	模式匹配、关系规则、复合逻辑、JSON 输出、调试视图	需安装 ast-grep CLI；规则语法有学习曲线，但本技能可代写规则	批量重构定位、代码审计、规范落地	优势：轻量、快、规则可版本化复用、支持多语言；不足：复杂规则仍需理解 AST 概念，跨过程/跨文件的数据流分析能力有限
grep / ripgrep	文本搜索工具	正则匹配、按文件类型过滤	几乎零门槛	快速找字符串、日志排查	优势：极快、人人会用；不足：不理解代码结构，无法表达「包含」「在……内部」「不存在」等语义，误报多
Semgrep	面向安全与代码规范的模式化静态扫描	规则库、跨函数语义匹配、CI 集成	需安装并学习 YAML 规则体系，规则更复杂	安全漏洞扫描、团队级规则治理	优势：安全规则生态成熟、CI 集成好；不足：配置与规则学习成本更高，单次本地快查不如 ast-grep 轻便
IDE 结构化搜索（如 IntelliJ 类 IDE 的 Structural Search）	编辑器内置的结构化查找	按模板匹配代码结构、作用域筛选	无需额外安装，但入口分散、模板语法各 IDE 不同	单项目内的交互式查找与替换	优势：所见即所得、可直接替换；不足：难以脚本化、难以进 CI、跨项目批量处理能力弱

选型建议：只需要找字符串 → 用 ripgrep；需要把结构化查询写进流水线、又要保持轻量 → ast-grep；需要成熟的安全规则库和团队级合规体系 → Semgrep；只在 IDE 里手动找一找 → 用 IDE 自带能力。而「规则不会写」这件事，正是本技能要解决的问题。

5. 该技能的典型应用场景与实际体验情况

场景一：代码审计与风险排查（技术负责人 / 安全工程师）

痛点：想知道项目里哪些异步调用「裸奔」没有错误处理，人工翻代码效率极低，正则又搜不准。
使用方式：描述需求后，技能直接给出 all + has + not 的复合规则并附测试样例。
实际体验：上手难度低，第一次使用只需描述需求；效果上能精确定位到函数级节点，误报明显少于正则。注意点：务必确认 stopBy: end 已添加，否则可能漏掉嵌套较深的目标。

场景二：批量重构前的「摸底」（后端 / 前端开发）

痛点：准备把旧 API 调用统一替换，需要先统计影响面，但调用写法五花八门。
使用方式：先用 ast-grep run --pattern 'oldApi($$$)' 做粗筛，再用规则文件做精筛，--json 输出后交给脚本统计。
实际体验：产出可直接落地，命令复制即用；对多语言项目友好，换 --lang 即可。注意点：不同语言的 kind 名称不同，遇到不匹配时用 --debug-query=cst 查真实节点类型。

场景三：编码规范落地（团队 TL / 代码质量负责人）

痛点：规范里写着「类方法中不允许直接 console.log」，但靠 Code Review 靠人眼盯不现实。
使用方式：让技能生成「console.log 出现在 method_definition 内部」的规则，保存为 YAML 文件长期复用。
实际体验：规则文件可入库、可评审、可复用，比一次性命令更有长期价值。注意点：首次编写需用示例代码验证，确认无意外的边界情况。

场景四：接手陌生代码库（新入职工程师）

痛点：不熟悉项目结构，想知道「哪些函数用了某个特定参数」「这个模式在哪些地方出现」。
使用方式：直接把疑问抛给助手，让技能翻译成查询。
实际体验：学习曲线被显著压平，不用先啃完规则文档就能拿到结果；但对「跨文件、跨函数调用链」的深层语义问题，仍需结合其他分析手段。

6. 该技能能为用户带来的价值

把「会不会写规则」变成「会不会描述需求」：ast-grep 的能力上限很高，但规则语法是最大门槛；本技能把这层门槛转移给 AI，用户只需用中文说清楚要找什么。
显著缩短单次排查时间：原本需要「查文档 → 试错 → 调规则 → 再试错」的循环，被压缩成「描述 → 拿到规则 → 小样本验证 → 全库执行」四步，复杂查询的首次成功率明显提升。
减少误报带来的二次人工成本：结构化匹配天然排除注释、字符串中的干扰项，审计和重构摸底的结果更干净。
沉淀可复用的团队资产：产出的 YAML 规则文件可以入库、评审、复用，逐步形成团队自己的「代码结构规则库」，长期价值随时间累积。
降低新人和非本语言开发者的门槛：不熟某门语言的 AST 节点命名，也能靠 --debug-query 反向确认，学习成本可控。
天然适配自动化流水线：--json 输出便于接入脚本、报表或 CI 检查，让结构化搜索从「个人技巧」变成「工程能力」。

7. 常见问题 FAQ

Q1：这个技能怎么安装？装完怎么确认能用？

在支持 AI 技能的平台中搜索技能ID 11799 或名称「ast-grep代码搜索技能Skill」并添加，具体入口与按钮以官方说明为准；若平台支持本地目录导入，放入技能目录后刷新即可。验证方法：问一个结构化搜索问题（例如「找 JS 里没有 try-catch 的 await 函数」），如果助手返回的是带 kind、has、stopBy: end 的 ast-grep 规则，说明已生效。另外，实际执行搜索还需要本机安装 ast-grep 命令行工具，安装方式以官方说明为准。

Q2：这个技能收费吗？

技能本身是一份规则编写指南，不包含内置的计费信息。是否产生费用取决于你使用的 AI 平台订阅方案，以及 ast-grep 工具自身的授权方式，请以官方说明为准。

Q3：它和直接用 grep 有什么区别？我用 grep 也能搜到代码啊。

grep 匹配的是「文本」，ast-grep 匹配的是「语法结构」。举个典型例子：你要找「使用了 await 但没有 try-catch 的函数」，grep 无法表达「没有」这个条件，也分不清注释里的 await 和真实调用；而 ast-grep 可以用 all + has + not 精确表达。简单找字符串用 grep 更快，涉及结构关系的查询就该用结构化搜索。

Q4：我不会写 YAML 规则，也不懂 AST，能用吗？

可以。这正是本技能的核心价值——你负责描述需求，技能负责翻译成规则，并给出示例代码、测试命令和调试建议。需要你配合的只有两点：说清楚用哪种编程语言、说清楚要包含或排除哪些情况。

Q5：规则跑出来没有匹配结果，怎么办？

按技能给的排查顺序处理：先简化规则去掉子规则看是否命中；再检查关系规则是否加了 stopBy: end；然后用 ast-grep run --debug-query=cst 查看真实 AST 结构，确认 kind 值是否正确（不同语言节点名不同）；最后检查内联规则里的 $ 是否被 shell 吞掉，需要写成 \$VAR 或用单引号包裹。把这些信息反馈给助手，它通常能直接给出修正版规则。

Q6：和 Semgrep 相比该选哪个？

追求轻量、快速、规则可读性高，并且希望把结构化查询灵活嵌进日常脚本与重构流程，选 ast-grep；需要成熟的安全规则库、团队级合规治理与更重的跨函数分析能力，选 Semgrep。两者并不冲突，很多团队是「日常快查用 ast-grep，安全扫描用 Semgrep」。