Agent skill

ast-grep

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

View SKILL.md on GitHub Repository
Stars 232
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/dwsy/ast-grep

SKILL.md

AST-Grep

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

执行环境

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

安装

bash
# macOS
brew install ast-grep

# Linux
cargo install ast-grep

# 验证安装
ast-grep --version

核心功能

1. 语法感知搜索

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

bash
# 搜索特定模式
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 更精确。

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

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

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

3. 代码重写

批量转换代码模式。

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

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

4. 规则测试

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

bash
# 测试规则
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 - 模式匹配

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

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

kind - 节点类型匹配

yaml
kind: call_expression

regex - 正则表达式匹配

yaml
regex: ^[a-z]+$

nthChild - 位置匹配

yaml
# 数字
nthChild: 1

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

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

range - 范围匹配

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

2. 关系规则

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

inside - 在父节点内

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

has - 包含子节点

yaml
has:
  pattern: await $EXPR
  stopBy: end

precedes - 在节点之前

yaml
precedes:
  pattern: return $VAL

follows - 在节点之后

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

stopBy - 搜索终止控制

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

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

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

field - 字段匹配

yaml
has:
  field: operator
  pattern: $$OP

3. 组合规则

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

all - 逻辑与（AND）

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

any - 逻辑或（OR）

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

not - 逻辑非（NOT）

yaml
not:
  pattern: console.log($ARG)

matches - 规则重用

yaml
matches: my-utility-rule-id

元变量

$VAR - 单个命名节点捕获

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

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

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

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

$$$VAR - 多节点捕获

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

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

_VAR - 非捕获元变量

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

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

编写规则的最佳实践

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

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

YAML 规则配置

简单规则

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

复杂规则

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

带修复的规则

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

使用关系规则

yaml
# 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. 查找特定代码模式

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

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

2. 重构代码

bash
# 替换 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. 代码审计

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

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

4. API 迁移

bash
# 迁移旧 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-grep grep ripgrep
语法感知 是 否 否
代码结构理解 是 否 否
跨语言支持 是 否 否
性能 快 快 最快
重写功能 是 否 否

参考资源

集成 Pi 工作流

Phase 1: 上下文检索

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

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

Phase 4: 编码实施

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

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

Phase 5: 审计

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

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

注意事项

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

aiskillstore/marketplace

perigon-backend

Perigon ASP.NET Core + EF Core + Aspire conventions

232 15
Explore
aiskillstore/marketplace

perigon-agent

Pointers for Copilot/agents to apply Perigon conventions

232 15
Explore
aiskillstore/marketplace

perigon-angular

Angular 21+ standalone/Material/signal conventions for Perigon WebApp

232 15
Explore
aiskillstore/marketplace

fastapi-mastery

Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.

232 15
Explore
aiskillstore/marketplace

context7-efficient

Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.

232 15
Explore
aiskillstore/marketplace

browser-use

Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.

232 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results