code-symbols

用途

code-symbols 技能用于在代码中查找和编辑符号，基于 ast-grep（sg）进行结构化代码搜索。它依赖 tree-sitter 解析，因此可以按代码结构（如函数定义、类定义、符号用法）进行匹配，而不仅是文本匹配。适用于查找函数定义、类定义、符号用法、重命名符号等场景。

主要能力

结构化代码搜索：基于 tree-sitter 解析，按语法结构匹配代码。
支持 31 种语言，涵盖 Web、系统、脚本、JVM 等类别。
支持元变量模式：$NAME 匹配单个节点，$$$ 匹配零个或多个节点，$_ 匹配但不捕获。
支持符号重命名：可预览、应用或交互式执行重写。
支持 JSON 输出，便于结合 jq 等工具进一步处理。

支持的语言

Web：JavaScript、TypeScript、HTML、CSS、JSON
系统：C、C++、Go、Rust
脚本：Python、Ruby、PHP、Lua、Bash
JVM：Java、Kotlin、Scala
其他：Swift、Haskell、Elixir、Nix

不支持：Clojure、Erlang、R、MATLAB。Clojure 代码请使用 clj-symbols 技能。

使用方式

前置条件：安装 ast-grep CLI。

安装命令：

# npm
npm install --global @ast-grep/cli

# Homebrew
brew install ast-grep

# Cargo
cargo install ast-grep --locked

验证安装：ast-grep --version 或 sg --version。

常用命令：

查找模式：ast-grep run --pattern 'PATTERN' --lang LANG path/
以 JSON 查找：ast-grep run --pattern 'PATTERN' --lang LANG path/ --json
重命名符号：ast-grep run --pattern 'old' --rewrite 'new' --lang LANG path/ --update-all

模式语法要求模式必须是 tree-sitter 可解析的有效代码。

元变量示例：

$NAME：匹配单个节点，例如 function $NAME() {}
$$$：匹配零个或多个节点，例如 function foo($$$)
$_：匹配但不捕获，例如 $_($$$)

基础示例：

# 匹配任意函数调用
ast-grep run --pattern '$FUNC($$$)' --lang js path/

# 匹配特定函数
ast-grep run --pattern 'myFunction($$$)' --lang js path/

# 匹配变量赋值
ast-grep run --pattern 'const $NAME = $VALUE' --lang js path/

查找函数定义示例：

# JavaScript
ast-grep run --pattern 'function $NAME($$$) { $$$ }' --lang js path/

# Python
ast-grep run --pattern 'def $NAME($$$):' --lang py path/

# Go
ast-grep run --pattern 'func $NAME($$$)' --lang go path/

查找符号用法示例：

ast-grep run --pattern 'myFunction($$$)' --lang js path/
ast-grep run --pattern '$OBJ.myMethod($$$)' --lang js path/

重命名符号示例：

# 预览
ast-grep run --pattern 'oldName' --rewrite 'newName' --lang js src/

# 应用
ast-grep run --pattern 'oldName' --rewrite 'newName' --lang js src/ --update-all

# 交互式
ast-grep run --pattern 'oldName' --rewrite 'newName' --lang js src/ --interactive

JSON 输出示例：

ast-grep run --pattern '$FUNC($$$)' --lang js path/ --json

结合 jq 解析：

ast-grep run --pattern 'function $NAME($$$) { $$$ }' --lang js path/ --json \
  | jq '.[] | {name: .metaVariables.single.NAME.text, file, line: .range.start.line}'

适用场景

按结构查找函数、类等代码元素。
查找特定符号的使用位置。
安全地重命名符号，支持预览、应用和交互式模式。
需要语言特定模式匹配时。
需要准确符号边界时。

限制

不支持 Clojure、Erlang、R、MATLAB。
模式必须是 tree-sitter 可解析的有效代码。
若仅按名称（文本模式）查找或追求最大速度，建议使用 ripgrep（rg）；按结构查找或需要准确符号边界时使用 ast-grep。

附加参考

语言模式：参见 references/languages.md，包含 JS、TS、Python、Go、Rust 模式。
编辑：参见 references/editing.md，包含重写、重命名和 YAML 规则。
工作流：参见 references/workflows.md，包含常见工作流。