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

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

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

简单说就是三步：

1. Parse：tree-sitter 把源码解析成 AST，理解出"这里是一个函数、那里是一个类"
2. Match：你的模式里$NAME、$$$BODY这类占位符可以吞掉任意具体的名字或代码块
3. 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 风格 的模式语法，核心只有三种元变量：

新手最容易犯的两个错：

• 忘了$前缀——元变量必须以$开头，否则按字面量处理
• 没加--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 编程助手来说，"这个调用发生在哪个函数里"往往比调用本身更重要，这一个参数就能省掉大量二次检索。

其他常用参数：

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

query 还是 search？一张表帮你选

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

推荐的组合拳：先用 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" 章节。

常见问题排查与性能技巧

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

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

结果太多、太慢？

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

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

延伸阅读

想继续深入 Probe 的 AST 能力，推荐按这个顺序看：

• Query 命令完整参考：docs/probe-cli/query.md
• 结构搜索模式大全：docs/guides/query-patterns.md
• search 命令对比阅读：docs/probe-cli/search.md
• 支持的语言清单：docs/reference/supported-languages.md
• extract 命令（按行号提取完整代码块）：docs/probe-cli/extract.md
• query 引擎核心实现：src/search/query.rs、src/query.rs

掌握probe query之后，你会发现"找出项目里所有长这样的代码"这件事，从翻文件变成了 10 秒钟的事。