moai-tool-ast-grep

AST-Grep 集成

使用抽象语法树分析进行结构化代码搜索、代码检查和转换的工具。

快速参考

什么是 AST-Grep

AST-Grep（sg）是一款快速的多语言结构化代码搜索和转换工具。与基于正则表达式的搜索不同，它能够理解代码语法，并根据 AST 结构匹配模式。

适用场景

• 搜索正则表达式无法捕获的代码模式，例如嵌套函数调用
• 在多个文件中进行语义感知的重构
• 扫描安全漏洞模式，包括 SQL 注入和 XSS
• 处理 API 迁移和弃用
• 在语法层面强制执行代码风格规则

核心命令

模式搜索：执行 sg run，使用 pattern 选项指定要查找的代码模式，使用 lang 选项指定编程语言，并指定源目录路径。

使用规则进行安全扫描：执行 sg scan，使用 config 选项指向你的 sgconfig.yml 文件。

代码转换：执行 sg run，使用 pattern 选项指定要查找的代码，使用 rewrite 选项指定替换内容，使用 lang 选项指定语言，并指定源目录路径。

测试规则：执行 sg test，验证你的规则定义。

模式语法基础

美元符号后跟变量名（例如 VAR）可匹配任意单个 AST 节点，并作为用于捕获的元变量。

美元符号后跟三个美元符号和变量名（例如 ARGS）可使用可变参数捕获匹配零个或多个节点。

双美元符号后跟下划线可作为匿名捕获匹配任意单个节点，适用于不需要其值的情况。

支持的语言

Python、JavaScript、TypeScript、Go、Rust、Java、Kotlin、C、C++、Ruby、Swift、C#、PHP、Scala、Elixir、Lua、HTML、Vue、Svelte 等 30 多种语言。

---

实现指南

安装

在 macOS 上，使用 brew install ast-grep。

跨平台安装可通过 npm 使用 npm install -g @ast-grep/cli。

通过 Cargo 安装 Rust 版本，使用 cargo install ast-grep。

基本模式匹配

简单模式搜索

要查找所有 console.log 调用，请运行 sg，使用模式 console.log($MSG) 并指定 lang javascript。

要查找所有 Python 函数定义，请运行 sg，使用模式 def $FUNC($$$ARGS): $$$BODY 并指定 lang python。

要查找 React useState 钩子，请运行 sg，使用模式 useState($INIT) 并指定 lang tsx。

探索／搜索性能优化

与基于文本的搜索相比，AST-Grep 在探索代码库时可显著提升性能：

AST-Grep 在探索时速度更快的原因

• 结构化理解可消除误报（无关结果减少 50-80%）
• 语法感知匹配可减少对完整文件的扫描
• 单次遍历 AST，而不是多次遍历正则表达式

常见探索模式

查找所有符合某种模式的函数调用：

sg -p 'authenticate($$$)' --lang python -r src/

查找所有继承自基类的类：

sg -p 'class $A extends BaseService' --lang python -r src/

查找特定的导入模式：

sg -p 'import fastapi' --lang python -r src/

查找 React 钩子的使用情况：

sg -p 'useState($$)' --lang tsx -r src/

查找异步函数声明：

sg -p 'async def $NAME($$$ARGS):' --lang python -r src/

性能比较

• grep -r "class.*Service" src/ - 以文本方式扫描所有文件（大型代码库约需 10 秒）
• sg -p 'class $X extends Service' --lang python -r src/ - 结构化匹配（约需 2 秒）

与 Explore Agent 集成 使用 Explore Agent 时，AST-Grep 会自动优先用于：

• 类层次结构分析
• 函数签名匹配
• 导入依赖关系映射
• API 使用模式检测

元变量

元变量用于在模式中捕获匹配的 AST 节点。

单节点捕获使用 $NAME 语法。例如，模式 const $NAME = require($PATH) 会捕获变量名和路径。

可变参数捕获使用 $$$ARGS 语法。例如，模式 function $NAME($$$ARGS) 会捕获函数名和所有参数。

当需要匹配但不引用值时，可使用 $$_ 进行匿名单节点捕获。

代码转换

简单改写

要重命名函数，请运行 sg，使用模式 oldFunc($ARGS)、改写规则 newFunc($ARGS)，并指定 lang python。

要更新 API 调用，请运行 sg，使用模式 axios.get($URL)、改写规则 fetch($URL)，并指定 lang typescript。

使用 YAML 规则进行复杂转换

创建一个 YAML 规则文件，结构如下。将 id 字段设为唯一的规则标识符，例如 convert-var-to-const。将 language 设为目标语言，例如 javascript。在 rule 部分中，指定要匹配的模式，例如 var $NAME = $VALUE。将 fix 字段设为替换模式，例如 const $NAME = $VALUE。添加描述问题的 message，并将 severity 设为 warning 或 error。

运行 sg scan，并使用 rule 选项指向规则文件和源目录。

基于规则的扫描

配置文件

创建一个 sgconfig.yml 文件，包含以下部分。ruleDirs 部分列出包含规则文件的目录，例如 ./rules/security 和 ./rules/quality。testConfigs 部分指定测试文件模式。languageGlobs 部分将语言映射到文件模式：将 python 映射到 .py 文件，将 typescript 映射到 .ts 和 .tsx 文件，并将 javascript 映射到 .js 和 .jsx 文件。

安全规则示例

创建一个用于检测 SQL 注入的安全规则文件。将 id 设为 sql-injection-risk。将 language 设为 python，将 severity 设为 error。编写一条描述该漏洞的消息。在 rule 部分中，使用 any 操作符匹配多个模式，包括使用百分号格式化的 cursor.execute、使用 format 方法的 cursor.execute，以及使用 f-string 插值的 cursor.execute。将 fix 设为展示参数化查询的替代写法。

关系规则

用于限定范围搜索的 Inside 规则

创建一条规则，仅搜索函数声明内部的 console.log 调用。将模式设为 console.log($$$ARGS)，并添加 inside 约束，使用模式 function $NAME($$$PARAMS)。

用于检查包含内容的 Has 规则

创建一条规则，查找没有 await 的异步函数。将模式设为 async function $NAME($$$PARAMS)，并添加一个 not 约束，其中包含模式为 await $EXPR 的 has 规则。添加一条说明异步函数中没有 await 的消息。

Follows 和 Precedes 规则

创建一条用于检测缺少错误处理的规则。将模式设为匹配错误赋值 $ERR := $CALL，并添加一个 not 约束，其中的 follows 规则用于检查 if $ERR != nil 错误处理块。

组合规则

使用 all 操作符组合多个条件，创建复杂规则。例如，将模式 useState($INIT) 与 function component 的 inside 约束，以及针对 useEffect 调用的 not precedes 约束组合起来。

---

高级模式

如需全面的文档，包括复杂的多文件转换、自定义语言配置、CI/CD 集成模式和性能优化技巧，请参阅以下模块文件。

模式语法参考见 modules/pattern-syntax.md。

安全扫描规则模板见 modules/security-rules.md。

常见重构模式见 modules/refactoring-patterns.md。

特定语言的模式详见 modules/language-specific.md。

Context7 集成

如需获取最新的 AST-Grep 文档，请按以下两个步骤操作。

步骤 1：使用 mcp__context7__resolve-library-id，并以 ast-grep 为查询内容，解析库标识符。

步骤 2：使用 mcp__context7__get-library-docs，并传入已解析的库 ID，获取最新文档。

MoAI-ADK 集成

AST-Grep 通过 Tool Registry 集成到 MoAI-ADK 中，类型为 AST_ANALYZER，位于 internal/hook/registry.go；通过 PostToolUse Hook，在 Write/Edit 操作后自动进行安全扫描；并通过 Permissions 自动允许 Bash(sg:) 和 Bash(ast-grep:)。

运行扫描

要使用 MoAI-ADK 规则进行扫描，请运行 sg scan，并将配置指向 .claude/skills/moai-tool-ast-grep/rules/sgconfig.yml。

要扫描特定目录，请运行 sg scan，使用配置 sgconfig.yml 并指定 src/ 目录。

要生成适用于 CI/CD 的 JSON 输出，请运行 sg scan，使用配置和 json 标志，并将输出重定向到 results.json。

---

配合使用效果良好

• moai-workflow-testing：检测 DDD 集成和测试模式
• moai-foundation-quality：检查 TRUST 5 合规性和代码质量门禁
• moai-domain-backend：检测 API 模式并进行安全扫描
• moai-domain-frontend：优化 React/Vue 模式
• moai-lang-python：Python 专用安全和风格规则
• moai-lang-typescript：TypeScript 类型安全模式

相关 Agent

• expert-refactoring：基于 AST 的大规模重构
• expert-security：安全漏洞扫描
• manager-quality：代码复杂度分析
• expert-debug：基于模式的调试

---

参考

如需了解更多信息，请参阅 AST-Grep 官方文档 ast-grep.github.io、AST-Grep GitHub 仓库 github.com/ast-grep/ast-grep、Pattern Playground ast-grep.github.io/playground.html，以及规则配置参考 ast-grep.github.io/reference/yaml.html。