sqry-semantic-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sqry Semantic Code Search Skill

sqry 语义代码搜索技能

Use this skill when users ask to:

Find functions, classes, methods, or variables by name or kind
Search for code with specific visibility (public/private)
Trace call relationships (callers, callees, call paths)
Analyze code dependencies and impact of changes
Find duplicate code, circular dependencies, or unused symbols

当用户提出以下需求时可使用该技能：

按名称或类型查找函数、类、方法或变量
搜索具有特定可见性（公开/私有）的代码
追踪调用关系（调用方、被调用方、调用路径）
分析代码依赖和变更影响范围
查找重复代码、循环依赖或未使用的符号

What Makes sqry Different

sqry的独特优势

sqry uses "semantic" in the compiler sense, not the NLP sense. It parses code like a compiler using AST analysis and graph queries — not ML embeddings over text.

```
kind:function name:*auth*
```
- Find functions with "auth" in the name
```
callers:authenticate
```
- Find everything that calls
```
authenticate()
```
```
kind:class impl:Serialize
```
- Find classes implementing the Serialize trait
```
returns:Result
```
- Find functions returning Result types

sqry所说的「语义」是编译器层面的语义，而非NLP层面的语义。 它通过AST分析和图查询像编译器一样解析代码，而非基于文本的ML嵌入。

```
kind:function name:*auth*
```
- 查找名称中包含「auth」的函数
```
callers:authenticate
```
- 查找所有调用
```
authenticate()
```
的代码
```
kind:class impl:Serialize
```
- 查找实现了Serialize trait的类
```
returns:Result
```
- 查找返回Result类型的函数

Setup

安装配置

bash

undefined

bash

undefined

Install

安装

curl -fsSL https://raw.githubusercontent.com/verivus-oss/sqry/main/scripts/install.sh | bash -s -- --component all

Index your project

为你的项目构建索引

sqry index .

Configure MCP for your agent

为你的Agent配置MCP

sqry mcp setup --tool claude # or codex, gemini sqry mcp status

undefined

sqry mcp setup --tool claude # 也可以选择codex、gemini sqry mcp status

undefined

Quick Tool Selection

快速工具选择

This is the primary way to find the right tool. For full parameter details, see references/tool-reference.md.

I know the symbol name and want to...

See its definition ->
```
get_definition
```
See its signature/docs ->
```
get_hover_info
```
See all references ->
```
get_references
```
See who calls it ->
```
direct_callers
```
(depth=1) or
```
relation_query
```
(multi-depth)
See what it calls ->
```
direct_callees
```
(depth=1) or
```
relation_query
```
(multi-depth)
See who imports/exports/returns it ->
```
relation_query
```
with
```
relation_type
```
: imports, exports, returns
See call tree ->
```
call_hierarchy
```
See its context + source ->
```
explain_code
```
See what breaks if I change it ->
```
dependency_impact
```
Check if it's in a cycle ->
```
is_node_in_cycle
```
Find similar symbols ->
```
search_similar
```

I want to search for symbols...

By name substring ->
```
pattern_search
```
By name with ranking ->
```
get_workspace_symbols
```
By kind/visibility/language ->
```
semantic_search
```
With results grouped for RAG ->
```
hierarchical_search
```

I want to analyze the codebase...

Find circular dependencies ->
```
find_cycles
```
Find dead code ->
```
find_unused
```
Find duplicate code ->
```
find_duplicates
```
Compare git versions ->
```
semantic_diff
```
Get overall stats ->
```
get_graph_stats
```
Get health metrics ->
```
get_insights
```
Get complexity scores ->
```
complexity_metrics
```
Check Rust macro expansion cache ->
```
expand_cache_status
```

I want to visualize/export...

Dependency tree ->
```
show_dependencies
```
Subgraph around symbols ->
```
subgraph
```
Graph as DOT/Mermaid/D2 ->
```
export_graph
```
Call path between A and B ->
```
trace_path
```
Cross-language edges ->
```
cross_language_edges
```

I want to inspect the index...

Check index health ->
```
get_index_status
```
List indexed files ->
```
list_files
```
List indexed symbols ->
```
list_symbols
```
See all symbols in a file ->
```
get_document_symbols
```
Rebuild from scratch ->
```
rebuild_index
```

I need natural language help...

Translate English to sqry query ->
```
sqry_ask
```

这是查找合适工具的主要方式。如需完整参数详情，请参考 references/tool-reference.md。

我知道符号名称，想要...

查看它的定义 ->
```
get_definition
```
查看它的签名/文档 ->
```
get_hover_info
```
查看所有引用 ->
```
get_references
```
查看谁调用了它 ->
```
direct_callers
```
（深度=1）或
```
relation_query
```
（多深度）
查看它调用了什么 ->
```
direct_callees
```
（深度=1）或
```
relation_query
```
（多深度）
查看谁导入/导出/返回了它 -> 搭配
```
relation_type
```
（imports、exports、returns）使用
```
relation_query
```
查看调用树 ->
```
call_hierarchy
```
查看它的上下文+源码 ->
```
explain_code
```
查看修改它会影响什么 ->
```
dependency_impact
```
检查它是否处于循环依赖中 ->
```
is_node_in_cycle
```
查找相似符号 ->
```
search_similar
```

我想要搜索符号...

按名称子串搜索 ->
```
pattern_search
```
按名称排序搜索 ->
```
get_workspace_symbols
```
按类型/可见性/语言搜索 ->
```
semantic_search
```
获取适合RAG的分组结果 ->
```
hierarchical_search
```

我想要分析代码库...

查找循环依赖 ->
```
find_cycles
```
查找死代码 ->
```
find_unused
```
查找重复代码 ->
```
find_duplicates
```
对比git版本差异 ->
```
semantic_diff
```
获取整体统计信息 ->
```
get_graph_stats
```
获取健康指标 ->
```
get_insights
```
获取复杂度评分 ->
```
complexity_metrics
```
检查Rust宏展开缓存 ->
```
expand_cache_status
```

我想要可视化/导出...

依赖树 ->
```
show_dependencies
```
符号周边子图 ->
```
subgraph
```
导出为DOT/Mermaid/D2格式的图 ->
```
export_graph
```
A和B之间的调用路径 ->
```
trace_path
```
跨语言关联边 ->
```
cross_language_edges
```

我想要检查索引...

检查索引健康状态 ->
```
get_index_status
```
列出已索引文件 ->
```
list_files
```
列出已索引符号 ->
```
list_symbols
```
查看某个文件中的所有符号 ->
```
get_document_symbols
```
从零重建索引 ->
```
rebuild_index
```

我需要自然语言帮助...

将英语翻译成sqry查询语句 ->
```
sqry_ask
```

Tool Categories (34 tools)

工具分类（共34个工具）

Tool names use the

mcp__sqry__

prefix in Claude Code, or equivalent for your agent. Load references/tool-reference.md for full parameter schemas.

Category	Tools	When to load details
Search (6)	semantic_search, hierarchical_search, explain_code, search_similar, pattern_search, get_workspace_symbols	Need `filters` , `include_classpath` , or pagination params
Navigation (4)	get_definition, get_references, get_hover_info, get_document_symbols	Usually no extra params needed
Relations (6)	relation_query, direct_callers, direct_callees, call_hierarchy, trace_path, dependency_impact	Need `max_depth` , `max_results` , or `relation_type` options
Graph (4)	subgraph, export_graph, show_dependencies, cross_language_edges	Need `format` , `include` filters, or `max_nodes`
Analysis (7)	semantic_diff, find_duplicates, find_cycles, is_node_in_cycle, find_unused, complexity_metrics, sqry_ask	Need `cycle_type` , `threshold` , or diff filters
Index (7)	get_index_status, get_graph_stats, get_insights, list_files, list_symbols, rebuild_index, expand_cache_status	Usually no extra params needed

在Claude Code中工具名称使用

mcp__sqry__

前缀，其他Agent可使用对应等价前缀。加载 references/tool-reference.md 可查看完整参数 schema。

分类	工具	何时需要加载详情
搜索（6个）	semantic_search, hierarchical_search, explain_code, search_similar, pattern_search, get_workspace_symbols	需要 `filters` 、 `include_classpath` 或分页参数时
导航（4个）	get_definition, get_references, get_hover_info, get_document_symbols	通常不需要额外参数
关系查询（6个）	relation_query, direct_callers, direct_callees, call_hierarchy, trace_path, dependency_impact	需要 `max_depth` 、 `max_results` 或 `relation_type` 选项时
图操作（4个）	subgraph, export_graph, show_dependencies, cross_language_edges	需要 `format` 、 `include` 过滤器或 `max_nodes` 时
分析（7个）	semantic_diff, find_duplicates, find_cycles, is_node_in_cycle, find_unused, complexity_metrics, sqry_ask	需要 `cycle_type` 、 `threshold` 或差异过滤器时
索引（7个）	get_index_status, get_graph_stats, get_insights, list_files, list_symbols, rebuild_index, expand_cache_status	通常不需要额外参数

Query Basics

查询基础

Queries use

field:value

predicates. Multiple predicates are AND-combined.

kind:function name:*auth*       # functions with "auth" in name
callers:authenticate            # who calls authenticate?
kind:class path:src/models      # classes in src/models
lang:rust kind:struct impl:Debug # Rust structs implementing Debug

Key fields:

name

kind

path

(alias:

file

lang

(alias:

language

parent

scope.name

scope.type

scope.ancestor

Relation fields:

callers

callees

imports

exports

returns

impl

references

Operators:

field:value

(exact/glob),

field~=pattern

(regex)

Filters (JSON parameter, not query string):

visibility

("public"/"private"),

language

(array),

symbol_kind

(array),

score_min

(float)

For full predicate reference, see references/query-syntax.md.

查询使用

字段:值

谓词格式，多个谓词默认按AND逻辑组合。

kind:function name:*auth*       # 名称中包含auth的函数
callers:authenticate            # 谁调用了authenticate？
kind:class path:src/models      # src/models下的类
lang:rust kind:struct impl:Debug # 实现了Debug trait的Rust结构体

核心字段：

name

、

kind

、

path

（别名：

file

）、

lang

（别名：

language

）、

parent

、

scope.name

、

scope.type

、

scope.ancestor

关系字段：

callers

、

callees

、

imports

、

exports

、

returns

、

impl

、

references

运算符：

字段:值

（精确匹配/glob匹配）、

字段~=pattern

（regex匹配）

过滤器（JSON参数，非查询字符串）：

visibility

（"public"/"private"）、

language

（数组）、

symbol_kind

（数组）、

score_min

（浮点数）

完整谓词参考请查看 references/query-syntax.md。

Handling Ambiguous Symbols

处理歧义符号

When names like

new

init

handle

process

exist in multiple files:

Scope with
file_path
:

{ "symbol": "handle", "file_path": "src/api/router.rs" }

Use qualified names:
```
"symbol": "UserService::authenticate"
```
Fall back to
get_references
with
```
path
```
filter when relation tools fail
Search first: Use
```
semantic_search
```
with
```
kind:
```
+
```
name:
```
+
```
path:
```
to find the exact symbol, then use its qualified name

Rule of thumb: If the name could exist in more than one file, always provide

file_path

or use a qualified name.

当

new

、

init

、

handle

、

process

这类名称存在于多个文件中时：

通过
file_path
限定范围：

{ "symbol": "handle", "file_path": "src/api/router.rs" }

使用限定名称：
```
"symbol": "UserService::authenticate"
```
当关系工具查询失败时，搭配
path
过滤器回退到
get_references
先搜索：使用搭配
```
kind:
```
+
```
name:
```
+
```
path:
```
的
```
semantic_search
```
找到精确符号，再使用它的限定名称

经验法则：如果名称可能存在于多个文件中，始终提供

file_path

或使用限定名称。

Output Size Tips

输出大小优化建议

Some tools produce large output. Always start narrow, expand if needed:

Use
```
direct_callers
```
(depth=1) before
```
call_hierarchy
```
(full tree)
Set
```
max_results
```
,
```
max_depth
```
, or
```
max_nodes
```
conservatively first
Add
```
path
```
,
```
kind
```
, or
```
language
```
filters to reduce noise
Prefer
```
get_hover_info
```
over
```
explain_code
```
for quick lookups

For per-tool risk scenarios and mitigations, see references/tool-reference.md.

部分工具会产生大量输出，请始终遵循先缩小范围，按需扩展的原则：

先使用
```
direct_callers
```
（深度=1）再使用
```
call_hierarchy
```
（完整树）
一开始保守设置
```
max_results
```
、
```
max_depth
```
或
```
max_nodes
```
的数值
添加
```
path
```
、
```
kind
```
或
```
language
```
过滤器减少噪音
快速查询优先使用
```
get_hover_info
```
而非
```
explain_code
```

每个工具的风险场景和缓解方案请查看 references/tool-reference.md。

Supported Languages (37)

支持的语言（37种）

Full relation support (28): C, C++, C#, CSS, Dart, Elixir, Go, Groovy, Haskell, HTML, Java, JavaScript, Kotlin, Lua, Perl, PHP, Python, R, Ruby, Rust, Scala, Shell, SQL, Svelte, Swift, TypeScript, Vue, Zig

Symbol extraction + imports (9): JSON, Oracle PL/SQL, Pulumi, Puppet, Salesforce Apex, SAP ABAP, ServiceNow Xanadu, ServiceNow XML, Terraform

Note: JSON and ServiceNow XML are

HighWallClock

plugins, excluded from the default index. Include them with

--include-high-cost

SQRY_INCLUDE_HIGH_COST=1

, or per-plugin:

--enable-plugin json

--enable-plugin servicenow-xml

完整关系支持（28种）：C、C++、C#、CSS、Dart、Elixir、Go、Groovy、Haskell、HTML、Java、JavaScript、Kotlin、Lua、Perl、PHP、Python、R、Ruby、Rust、Scala、Shell、SQL、Svelte、Swift、TypeScript、Vue、Zig

仅符号提取+导入支持（9种）：JSON、Oracle PL/SQL、Pulumi、Puppet、Salesforce Apex、SAP ABAP、ServiceNow Xanadu、ServiceNow XML、Terraform

注意：JSON和ServiceNow XML属于

HighWallClock

插件，默认不纳入索引。如需包含可使用

--include-high-cost

、

SQRY_INCLUDE_HIGH_COST=1

，或按插件启用：

--enable-plugin json

、

--enable-plugin servicenow-xml

。

When NOT to Use sqry

何时不应该使用sqry

Literal text search: Use grep/rg for exact text patterns
File finding: Use find/glob for file names
Reading files: Use cat/read for file contents
Code execution: sqry only searches, doesn't run code

精确文本搜索：使用grep/rg搜索精确文本模式
查找文件：使用find/glob匹配文件名
读取文件：使用cat/read获取文件内容
代码执行：sqry仅用于搜索，不会运行代码

Reference Files (load on demand)

参考文件（按需加载）

Only load these when you need details beyond Quick Tool Selection:

references/tool-reference.md - Full tool tables with all parameters, filter details, output size risks
references/query-syntax.md - Complete predicate syntax, MCP vs CLI differences, quoting rules
references/graph-queries.md - Graph tool parameters, edge types, use cases
references/workflows.md - Step-by-step workflows: understand-before-changing, security audit
references/examples.md - 50+ example queries across all categories

仅当你需要快速工具选择之外的详情时才加载这些文件：

references/tool-reference.md - 包含所有参数、过滤器详情、输出大小风险的完整工具表
references/query-syntax.md - 完整谓词语法、MCP与CLI差异、引号规则
references/graph-queries.md - 图工具参数、边类型、使用场景
references/workflows.md - 分步工作流：变更前理解代码、安全审计
references/examples.md - 覆盖所有分类的50+示例查询