像X光一样透视代码结构：Probe query 的AST模式匹配实战指南-平芜编程栈

【免费下载链接】probe

AI-friendly semantic code search engine for large codebases. Combines ripgrep speed with tree-sitter AST parsing. Powers AI coding assistants with precise, context-aware code understanding.

项目地址：https://gitcode.com/gh_mirrors/probe17/probe

点击查看免费下载

Probe是一款面向大型代码库的 AI 友好语义代码搜索引擎，它把 ripgrep 的扫描速度与 tree-sitter 的 AST 解析能力结合在一起。其中最有"透视"能力的，正是probe query命令——它不靠关键字碰运气，而是直接按AST 模式匹配代码的语法结构：函数叫foo还是bar无所谓，只要长得像fn $NAME($$$PARAMS) { $$$BODY }，一个都跑不掉。本指南面向新手，带你从零写对第一条结构查询命令。

为什么叫"X光"？——AST 模式匹配的原理

普通文本搜索只能看"表面"：变量改个名字，搜索结果就变了。而probe query借助 tree-sitter 把代码解析成语法树（Abstract Syntax Tree），再用带元变量的模式在树上做结构匹配。

简单说就是三步：

Parse：tree-sitter 把源码解析成 AST，理解出"这里是一个函数、那里是一个类"
Match：你的模式里$NAME、$$$BODY这类占位符可以吞掉任意具体的名字或代码块
Report：返回完整代码块、文件行号、语言与模式命中详情

所以无论代码里函数叫什么名字，只要结构一致，它都能被"照"出来。相关原理可参考 docs/reference/how-it-works.md。

3分钟上手：安装与第一条 query 命令

如果你还没装过 Probe，一条命令即可（npm 全局安装）：

npm install -g @probelabs/probe@latest

然后对着自己的项目跑第一条 AST 查询——找出 Rust 源码里所有函数定义：

probe query "fn $NAME($$$PARAMS) { $$$BODY }" ./src -l rust

或者更经典的场景——找出前端代码里所有 ReactuseState调用：

probe query "useState($INITIAL)" ./src --language javascript

输出默认是带颜色的终端样式：先给出文件路径:行号，再展示命中的完整代码块，一眼就能看到结构全貌。

元变量语法速查：只需认识 3 个占位符

probe query使用 ast-grep 风格的模式语法，核心只有三种元变量：

写法	含义	例子
`$NAME`	匹配单个节点	`fn $NAME()`命中`fn foo()`
`$$$BODY`	匹配多个节点（参数、函数体等）	`{ $$$BODY }`命中任意函数体
`$_`	匹配任意单个节点（匿名）	`if $_ { }`

新手最容易犯的两个错：

忘了$前缀——元变量必须以$开头，否则按字面量处理
没加--language参数——模式必须与目标语言语法一致，建议始终显式指定

完整的模式示例（Rust / JavaScript / Python / Go 各语言的函数、类、导入、错误处理写法）都整理在 docs/guides/query-patterns.md，可直接当抄写本用。

实战清单：5 类最常用的 AST 结构搜索

下面这几条是日常开发中使用率最高的模式，建议收藏：

1️⃣ 找出所有返回 Result 的 Rust 函数

probe query "fn $NAME($$$) -> Result<$OK, $ERR> { $$$ }" ./src -l rust

2️⃣ 找出所有 Python 带装饰器的函数

probe query "@$DECORATOR def $NAME($$$PARAMS): $$$BODY" ./src -l python

3️⃣ 找出所有fetch网络调用及它们的参数

probe query "fetch($URL, $$$OPTS)" ./src -l javascript

4️⃣ 找出所有 try-catch 错误处理块

probe query "try { $$$TRY } catch ($ERR) { $$$CATCH }" ./src -l javascript

5️⃣ 找出所有with上下文管理语句

probe query "with $CONTEXT as $VAR: $$$BODY" ./src -l python

💡经验法则：先写宽松，再逐步收紧。先用fn $NAME($$$PARAMS) { $$$BODY }找到大致范围，再逐步加上返回类型、async、pub等约束，比一上来就写死具体签名更容易命中。

输出格式与上下文增强：给 AI 喂料的关键

probe query默认输出彩色终端文本，也可以切换成更适合工具链的格式：

# Markdown，方便贴进笔记或 PR probe query "fn $NAME()" ./src --format markdown # JSON，供脚本或 AI Agent 消费 probe query "fetch($$$ARGS)" ./src -l typescript --format json

重点推荐--with-context参数：每个命中结果除了代码本身，还会附带"所属函数/方法名、作用域行号、关联注释"等上下文字段（schema 见 docs/probe-cli/query.md 中的 Owner Context 示例）。对 AI 编程助手来说，"这个调用发生在哪个函数里"往往比调用本身更重要，这一个参数就能省掉大量二次检索。

其他常用参数：

参数	作用
`-l, --language`	指定解析语言（rust / python / typescript / go…）
`--max-results`	限制返回条数，先试水再放量
`--allow-tests`	把测试文件也纳入搜索
`-i, --ignore`	按模式忽略特定路径
`--strict`	禁用纯文本回退，仅做 AST 匹配

一个实用技巧：对没有对应解析器的文件（如.conf、.txt），query 会自动回退为逐行文本搜索；加--text-extension还能把自定义后缀强制按文本处理，文档配置目录也能用同一条命令查。

query 还是 search？一张表帮你选

Probe 同时提供search（语义/文本搜索）和query（AST 结构搜索），新手常常纠结用哪个：

场景	推荐命令
你知道确切的代码结构，名字无关紧要	`probe query`
找某个概念/关键词，名字就是线索	`probe search`
重构：找出所有"长这样"的代码	`probe query`
初探陌生代码库	`probe search`

推荐的组合拳：先用 search 按概念缩小文件范围，再用 query 按结构精确狙击——

# 第一步：找出含 middleware 概念的文件 probe search "middleware" ./src --files-only # 第二步：在这些文件里按结构找 Express 风格处理函数 probe query "function $NAME(req, res, next) { $$$ }" ./src/middleware -l javascript

这一工作流的更多细节见 docs/guides/query-patterns.md 的 "Combining Tools" 章节。

常见问题排查与性能技巧

搜不到结果？按顺序检查三件事：

--language是否匹配目标文件（模式语法随语言而异）
模式是否太具体——把类型、参数换成$占位符放宽
是否漏掉了测试目录——需要时加--allow-tests

结果太多、太慢？

用--max-results 5先小样本试跑，确认模式方向对了再放开
把搜索范围从整个仓库收窄到具体目录
用语言参数过滤，避免解析无关文件类型

query需要对文件做完整解析，因此比纯文本search稍慢，但在大型代码库上依然可用——Probe 底层的 ripgrep 扫描与并行处理逻辑见 src/search/。

【免费下载链接】probe

AI-friendly semantic code search engine for large codebases. Combines ripgrep speed with tree-sitter AST parsing. Powers AI coding assistants with precise, context-aware code understanding.

项目地址：https://gitcode.com/gh_mirrors/probe17/probe

点击查看免费下载