mcpField
A
ast-grep

ast-grep

github.com/ulpi-io开发5148 次安装10 周前更新
代码仓库

关于 ast-grep

将自然语言描述的代码结构查询转化为经过测试的 ast-grep 搜索规则，指导开发者检查工具、构造示例、搜索仓库并验证结果。

主要功能

  1. 01检查 ast-grep 是否可用
  2. 02明确语言与匹配目标
  3. 03按需检查 AST 结构
  4. 04用最小示例测试规则
  5. 05验证仓库搜索结果

适用场景

  1. 01在代码仓库中查找指定结构
  2. 02检查结构搜索规则是否误匹配
  3. 03生成可复用的 ast-grep 规则和结果报告

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ulpi-io/skills --skill ast-grep

安装后在 Claude Code 中输入/ast-grep确认已加载。

附带文件references/rule_reference.mdreferences/search-recipes.md

详细介绍

此技能可将自然语言形式的结构查询转换为经过测试的 ast-grep 搜索。

不可妥协的规则：

  1. 确认已安装 ast-grep 后再使用它。
  2. 在搜索代码库前，先创建一个符合目标模式的最小示例。
  3. 如果节点类型或匹配形状不确定，使用 --debug-query 检查 AST。
  4. 除非有具体理由不这样做，否则在关系规则中添加 stopBy: end。
  5. 先在示例上测试规则，再对整个代码库运行搜索。

ast-grep 代码搜索

输入

  • $request：要查找的结构模式，以及已知的语言、排除项或边界情况

目标

通过以下步骤生成可靠的结构化搜索：

  • 确认 ast-grep 可用
  • 明确目标模式和语言
  • 构建可行的最小规则
  • 先在示例代码上测试
  • 在报告结果前验证代码库中的搜索结果

步骤 0：验证可用性并明确查询

首先使用 ast-grep --version 确认已安装 ast-grep。

如果尚未安装：

  • 停止
  • 告知用户，此工作流需要 ast-grep
  • 提供安装说明，不要假装搜索可以继续

然后明确：

  • 编程语言
  • 哪些内容应该匹配
  • 哪些内容不应匹配
  • 用户关心的任何边界情况

只有在这些信息不明确到可能导致规则错误时，才使用 AskUserQuestion。

成功标准：已明确 ast-grep 是否可用、使用的语言以及模式意图。

步骤 1：创建最小示例并检查 AST

编写一个应当匹配的最小示例片段。

需要了解以下内容时，使用 --debug-query=cst 或 --debug-query=pattern：

  • 实际的节点类型
  • 元变量的解析方式
  • 目标结构在树中的位置

规则：

  • 示例尽可能精简
  • 如果节点类型名称或嵌套关系不确定，就检查 AST
  • 不要仅仅因为模式“看起来很明显”就跳过这一步

加载 references/rule_reference.md 了解语法细节，并加载 references/search-recipes.md 了解常见命令形式。

成功标准：目标形状已由经过测试的示例表示，并且已充分了解 AST 结构，足以编写规则。

步骤 2：编写可行的最小规则

从最简单的可行规则开始：

  • 直接结构匹配优先使用 pattern
  • 更复杂的结构使用 kind 和关系规则
  • 仅在需要时使用 all、any 或 not

规则：

  • 除非有意设置更严格的停止条件，否则在 inside 和 has 中添加 stopBy: end
  • 在证明规则不够用之前，保持规则精简
  • 使用内联 shell 命令时，正确转义元变量

加载 references/rule_reference.md 了解规则语义。

成功标准：规则语法有效，且对于该问题而言足够简单。

步骤 3：在示例上测试规则

使用 --stdin 或临时文件，针对示例片段测试规则。

检查：

  • 是否匹配预期示例
  • 是否明显过度匹配
  • 关系规则是否遍历了预期范围

如果规则失败：

  • 简化规则
  • 重新检查 AST
  • 调整节点类型名称或规则形状
  • 在接触代码库之前重新测试

成功标准：规则能正确匹配已知示例。

步骤 4：搜索代码库并验证结果

规则在示例上生效后，再对代码库运行搜索。

然后验证：

  • 匹配总数
  • 有代表性的文件路径和行号
  • 抽查 3 到 5 处，确认符合预期
  • 用户明确提及的边界情况

规则：

  • 如果最终发现 Grep 就足够了，应如实说明；但如果已经开始 ast-grep 搜索，就完成当前搜索
  • 如果规则变得过于复杂或脆弱，应缩小查询范围，而不是返回未经验证的噪声结果

加载 references/search-recipes.md 了解常见搜索和调试流程。

成功标准：代码库搜索结果可信、可复现，且没有明显噪声。

第 5 步：报告结果和可复用规则

报告：

  • 模式描述
  • 语言
  • 使用的规则类型
  • 匹配数量
  • 有代表性的文件:行号匹配结果
  • 最终可复用规则或命令形式

如果没有找到匹配项，请明确说明，并解释这可能意味着：

  • 不存在该模式
  • 规则范围有意设得较窄
  • 需要进一步澄清

成功标准：用户可以根据你的输出重新运行搜索或优化搜索条件。

约束

  • 不要添加 disable-model-invocation；这是一项非破坏性的搜索技能。
  • 不要添加 context: fork；用户通常希望结果出现在当前流程中。
  • 不要添加 paths:；这是一个通用搜索工作流。
  • 如果查询并非简单查询，不要使用未经测试的规则搜索代码仓库。
  • 不要在 SKILL.md 中内嵌冗长的 CLI 手册、配方目录或故障百科全书。
  • 如果普通 Grep 明显足够，就不要使用 ast-grep。

何时加载参考资料

  • references/rule_reference.md 用于 ast-grep 规则语法、关系规则、组合规则和元变量语义。

  • references/search-recipes.md 用于安装指南、命令模式、常见用例和调试流程。

输出规范

报告：

  1. 搜索的结构模式
  2. 使用的语言和规则类型
  3. 匹配数量和有代表性的文件:行号结果
  4. 最终规则或可复用的命令形式
  5. 重要注意事项或后续优化建议

评论

支持 Markdown