aiskillstore

ast-grep

@aiskillstore/ast-grep
aiskillstore
80
2 forks
Updated 1/18/2026
View on GitHub

语法感知的代码搜索、linting 和重写工具。支持基于 AST 的结构化代码搜索和批量代码转换。

Installation

$skills install @aiskillstore/ast-grep
Claude Code
Cursor
Copilot
Codex
Antigravity

Details

Repositoryaiskillstore/marketplace
Pathskills/dwsy/ast-grep/SKILL.md
Branchmain
Scoped Name@aiskillstore/ast-grep

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

skills list

Skill Instructions

name: ast-grep description: 语法感知的代码搜索、linting 和重写工具。支持基于 AST 的结构化代码搜索和批量代码转换。

AST-Grep

AST-Grep (ast-grep/sg) 是一个快速且用户友好的工具，用于代码搜索、linting 和大规模代码重写。

执行环境

路径类型说明
使用方式命令行工具，需要安装 ast-grep
调用场景语法感知的代码搜索、结构化代码分析、批量代码转换
工作目录项目根目录

安装

# macOS
brew install ast-grep

# Linux
cargo install ast-grep

# 验证安装
ast-grep --version

核心功能

1. 语法感知搜索

使用 AST（抽象语法树）进行代码搜索，而非简单的文本匹配。

# 搜索特定模式
ast-grep --lang python -p "def $FUNC($$$ARGS):"

# 搜索函数调用
ast-grep --lang ts -p "console.log($$$MSG)"

# 搜索条件语句
ast-grep --lang ts -p "if ($$COND) { $$$BODY }"

2. 代码 Linting

基于 AST 的代码检查，比传统 linter 更精确。

# 扫描项目
ast-grep scan -r sgconfig.yml

# 扫描特定目录
ast-grep scan src/

# 扫描特定文件
ast-grep scan src/main.ts

3. 代码重写

批量转换代码模式。

# 简单替换
ast-grep run -p "oldFunction($$$ARGS)" -r "newFunction($$ARGS)" --lang ts

# 复杂转换（使用 YAML 规则）
ast-grep run -r rule.yml

4. 规则测试

测试 ast-grep 规则是否正确。

# 测试规则
ast-grep test -r rule.yml

# 测试特定模式
ast-grep test -p "pattern" --lang ts

规则开发流程

通用流程

  1. 理解查询：明确用户需求，必要时询问更多细节
  2. 编写示例：编写匹配查询的简单代码示例
  3. 编写规则：编写匹配示例的 ast-grep 规则
  4. 测试规则：使用 test_match_code_rule 验证规则
    • 如果不匹配，移除部分子规则并调试
    • 如果使用 inside 或 has，确保使用 stopBy: end
  5. 搜索代码：使用规则搜索代码库

规则开发步骤

  1. 分解查询：将用户查询分解为更小的部分
  2. 识别子规则：识别可用于匹配代码的子规则
  3. 组合规则：使用关系规则或组合规则组合子规则
  4. 调试规则：如果规则不匹配示例代码，移除部分子规则并调试不匹配的部分
  5. 使用工具：使用 ast-grep mcp 工具转储 AST 或转储模式查询
  6. 测试规则：使用 ast-grep mcp 工具针对示例代码片段测试规则

规则类型

1. 原子规则

匹配单个 AST 节点，基于内在属性。

pattern - 模式匹配

# 字符串模式
pattern: console.log($ARG)

# 对象模式（更精细的控制）
pattern:
  selector: field_definition
  context: class { $F }
  strictness: relaxed

kind - 节点类型匹配

kind: call_expression

regex - 正则表达式匹配

regex: ^[a-z]+$

nthChild - 位置匹配

# 数字
nthChild: 1

# An+B 公式
nthChild: 2n+1

# 对象形式
nthChild:
  position: 1
  reverse: true
  ofRule:
    kind: function_declaration

range - 范围匹配

range:
  start:
    line: 0
    column: 0
  end:
    line: 0
    column: 10

2. 关系规则

基于目标节点与其他节点的关系过滤目标。

inside - 在父节点内

inside:
  pattern: class $C { $$$ }
  stopBy: end

has - 包含子节点

has:
  pattern: await $EXPR
  stopBy: end

precedes - 在节点之前

precedes:
  pattern: return $VAL

follows - 在节点之后

follows:
  pattern: import $M from '$P'

stopBy - 搜索终止控制

# neighbor（默认）：在直接周围节点不匹配时停止
stopBy: neighbor

# end：搜索到方向末尾（inside 为根，has 为叶子）
stopBy: end

# 规则对象：在周围节点匹配提供的规则时停止（包含）
stopBy:
  pattern: class $END

field - 字段匹配

has:
  field: operator
  pattern: $$OP

3. 组合规则

使用逻辑操作组合其他规则。

all - 逻辑与（AND）

all:
  - kind: call_expression
  - pattern: console.log($ARG)

any - 逻辑或（OR）

any:
  - pattern: console.log($ARG)
  - pattern: console.warn($ARG)
  - pattern: console.error($ARG)

not - 逻辑非（NOT）

not:
  pattern: console.log($ARG)

matches - 规则重用

matches: my-utility-rule-id

元变量

$VAR - 单个命名节点捕获

# 有效
pattern: console.log($GREETING)

# 匹配
console.log('Hello World')

$$VAR - 单个未命名节点捕获

# 匹配操作符
rule:
  kind: binary_expression
  has:
    field: operator
    pattern: $$OP

$$$VAR - 多节点捕获

# 匹配零个或多个节点（非贪婪）
pattern: console.log($$$)

# 匹配可变参数
pattern: function $FUNC($$$ARGS) { $$$ }

_VAR - 非捕获元变量

# 不捕获，可以匹配不同内容
pattern: $_FUNC($_FUNC)

# 匹配
test(a)
testFunc(1 + 1)

编写规则的最佳实践

  1. 始终使用 stopBy: end：对于关系规则，确保搜索到方向末尾
has:
  pattern: await $EXPR
  stopBy: end
  1. 简单结构使用 pattern：代码结构简单时直接使用模式
pattern: console.log($ARG)
  1. 复杂结构使用 rule：代码结构复杂时使用规则分解
rule:
  kind: function_declaration
  has:
    pattern: await $EXPR
  1. 使用 kind 调试：如果 pattern 不工作，先用 kind 匹配节点类型
# 先确认节点类型
kind: call_expression

# 再使用 has 或 inside
has:
  pattern: console.log($ARG)
  1. 关系规则无匹配时添加 stopBy：确保搜索到末尾
inside:
  pattern: class $C { $$$ }
  stopBy: end

YAML 规则配置

简单规则

# rule.yml
id: no-console-log
language: ts
rule:
  pattern: console.log($$$MSG)

复杂规则

# complex-rule.yml
id: prefer-const
language: ts
rule:
  all:
    - pattern: let $VAR = $INIT
    - not:
        pattern: $VAR = $EXPR

带修复的规则

# fix-rule.yml
id: no-var
language: ts
rule:
  pattern: var $VAR = $INIT
fix: const $VAR = $INIT

使用关系规则

# async-without-await.yml
id: async-without-await
language: ts
rule:
  all:
    - pattern: async function $FUNC($$$ARGS) { $$$BODY }
    - not:
        has:
          pattern: await
          stopBy: end

常用场景

1. 查找特定代码模式

# 查找所有 console.log
ast-grep -p "console.log($$$MSG)" --lang ts

# 查找所有未使用的变量
ast-grep -p "let $VAR = $INIT" --lang ts | grep -v "$VAR ="

2. 重构代码

# 替换 var 为 const
ast-grep run -p "var $VAR = $INIT" -r "const $VAR = $INIT" --lang ts

# 重命名函数
ast-grep run -p "oldFunc($$$ARGS)" -r "newFunc($$ARGS)" --lang ts

3. 代码审计

# 查找潜在的安全问题
ast-grep -p "eval($$$EXPR)" --lang js

# 查找 SQL 注入风险
ast-grep -p "query('$$SQL')" --lang py

4. API 迁移

# 迁移旧 API 到新 API
ast-grep run -p "oldApi($$$ARGS)" -r "newApi($$ARGS)" --lang ts

# 批量更新导入
ast-grep run -p "from 'old-lib' import $$IMPORT" -r "from 'new-lib' import $$IMPORT" --lang ts

与其他工具对比

特性ast-grepgrepripgrep
语法感知是否否
代码结构理解是否否
跨语言支持是否否
性能快快最快
重写功能是否否

参考资源

集成 Pi 工作流

Phase 1: 上下文检索

当需要理解代码结构时，使用 ast-grep 进行语法感知搜索：

# 查找特定模式
ast-grep -p "pattern" --lang <language>

Phase 4: 编码实施

使用 ast-grep 进行批量代码转换：

# 应用重构规则
ast-grep run -r rule.yml

Phase 5: 审计

使用 ast-grep 验证代码质量：

# 扫描潜在问题
ast-grep scan -r sgconfig.yml

注意事项

  • ast-grep 需要安装才能使用
  • 模式语法需要熟悉 AST 结构
  • 复杂规则建议先测试再应用
  • 大规模重构前建议备份代码
  • 使用 stopBy: end 确保关系规则搜索完整
  • 元变量必须符合语法要求（$VAR, $$VAR, $$$VAR）

More by aiskillstore

View all
clean-code-reviewer
80

Analyze code quality based on "Clean Code" principles. Identify naming, function size, duplication, over-engineering, and magic number issues with severity ratings and refactoring suggestions. Use when the user requests code review, quality check, refactoring advice, Clean Code analysis, code smell detection, or mentions terms like 代码体检, 代码质量, 重构检查.

angular-20-standalone-component
80

Create Angular 20 standalone components using modern patterns: Signals for state management, input()/output() functions (not decorators), @if/@for/@switch control flow (not *ngIf/*ngFor), inject() dependency injection (not constructor), and OnPush change detection. Use this skill when scaffolding new UI components that need reactive state, form handling, or integration with services following the three-layer architecture.

rn-styling
80

Styling patterns for React Native with NativeWind and BrandColors. Use when working with styles, themes, colors, responsive layouts, or platform-specific UI in Expo/React Native.

founder-os
80

Manages founder business portfolio, signals, vault, and snapshots. Tracks business health, stores credentials securely, and generates AI-powered business analytics and recommendations.