sqry - Semantic Code Search

sqry

sqry 是一款本地语义代码搜索工具。它会将源代码解析为由 AST 支持的符号和关系图，让你能够询问那些无法通过文本搜索可靠回答的代码问题。

所有操作都在你的计算机上运行。索引和查询不会发起网络请求，sqry 也不会发送任何遥测数据。

网站：https://sqry.dev

当前功能

• 支持 37 种语言插件，其中 28 种完整支持关系，9 种支持符号提取和导入。按构建成本计算，29 种位于默认快速路径上；json 已编译，但由于耗时较长，默认不启用；另有 7 种专业插件需要通过 Cargo 功能启用。sqry://meta/manifest MCP 资源会报告已安装二进制文件的这些计数。
• 按符号类型、语言、可见性、名称、返回类型、引用和关系进行结构化查询。
• 图分析涵盖调用方、被调用方、导入、导出、调用路径、循环、未使用符号、重复项、影响、语义差异和聚焦子图。
• 对受支持的图路径，提供基于边的 returns:<TypeName> 和支持解析的 resolved_via:<kind> 谓词。请参阅调用解析谓词。
• 跨语言 FFI 边。C、C++、C#、Elixir、Haskell、Kotlin、Lua、PHP、R、Ruby 和 Rust 插件会从 extern "C"、DllImport / P/Invoke、JNI、Ruby FFI attach_function 和 R .Call / Rcpp 等机制生成 FfiCall 边。可使用 sqry graph cross-language 或 cross_language_edges MCP 工具查询。
• 使用 sqry shape-match 进行结构形状匹配，可找到函数体结构相似、标识符各不相同的函数。
• 声明式规则层。sqry rules run 可针对图执行随附的规则 ID 和规则包，或你自己的 TOML 规则包；rules_run MCP 工具提供相同的引擎。
• Go 上下文传播分析（sqry context-propagation），用于查找丢弃 context.Context 的调用点。
• Rust 宏边界分析：sqry cache expand 会构建宏展开缓存；--expand-cache 会将宏生成的符号作为可搜索节点；--cfg 会将受 #[cfg] 控制的符号标记为启用或禁用。两种索引路径选项都不会执行代码，并会记录在索引清单中；此后每次持久化重建都会重用该记录，直到使用 --no-macro-options（或 reset_macro_options）清除记录：包括 sqry index --force、sqry update、sqry watch、sqry query 自动索引和 --auto-rebuild、守护进程（sqry daemon rebuild、其文件监视器触发的重建及其 MCP rebuild_index）、LSP（sqry.index、其自动索引和自我修复），以及独立 MCP（rebuild_index 和其自动索引）。在已有索引上使用这些选项时，需要加上 --force。相对路径 --expand-cache 会相对于当前工作目录解析；MCP 的 expand_cache 字段会相对于其 path 参数指定的目录解析（该目录本身，或文件的父目录）；daemon/rebuild 则会相对于其重建的工作区解析。目录必须存在；如果目录的规范路径不是有效的 UTF-8，则会拒绝使用，因为清单会将该路径记录为 JSON 文本。--cfg 不接受空值、仅含空白的值，或前后带有空白的值。
• 以 Mermaid、Graphviz DOT 或 D2 格式进行可视化和导出（sqry visualize、sqry export）。
• 交互式 Shell（sqry shell）和批处理运行器（sqry batch），可在多次查询期间保持会话缓存处于热状态。
• 使用 sqry update 和 sqry watch 刷新索引；两者都会执行完整重建，并重用索引记录的插件选择和宏选项（没有任何命令只对已更改的文件重新索引）。
• 通过 .sqry-workspace 注册表和 VS Code .code-workspace sqry.workspace 块进行工作区感知索引。
• 通过 sqryd 为编辑器、MCP 和重复执行的 Agent 工作流共享加载图数据。
• 使用 sqry overview 一次性了解代码仓库概况（Agent 可使用对应的 generate_overview MCP 工具）：一份报告汇总承载关键功能的枢纽、路径和包子系统、复杂度热点、潜在问题，以及可直接运行的后续查询。
• 集成 MCP，支持 AI 助手。独立的 sqry-mcp 目前提供 39 个工具；由守护进程托管的 MCP 提供其中 17 个工具。请使用 tools/list、sqry-mcp --list-tools 或 sqry://meta/manifest 获取权威目录。
• 支持 LSP 和 VS Code 扩展，适用于编辑器工作流。

何时使用 sqry

需要结构化答案时，请使用 sqry：

sqry index .
sqry overview            # orient in an unfamiliar repo, then run the queries it suggests
sqry query "kind:function AND visibility:public AND lang:rust"
sqry query "returns:Result"
sqry graph direct-callers authenticate
sqry graph trace-path main handle_request
sqry visualize "callers:authenticate" --format mermaid

简单的文本搜索请使用 ripgrep，语法重写模式请使用 ast-grep，策略实施请使用语言检查工具，完整的编辑器语义请使用 IDE 语言服务器。sqry 专注于本地语义代码搜索。

安装

Linux 和 macOS

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

Shell 安装程序会下载发行版资源，默认验证 SHA256 校验和，并安装：

• sqry
• sqry-mcp
• sqry-lsp
• sqryd

支持的发行平台包括 Linux x86_64/arm64（glibc 和 musl 构建）、macOS x86_64/arm64，以及 Windows x86_64。

常用选项：

curl -fsSL https://raw.githubusercontent.com/verivus-oss/sqry/main/scripts/install.sh | \
  bash -s -- --component all --version vX.Y.Z --verify-signatures

--verify-signatures 需要 gh 或 Cosign。它会验证来自 release-distribute.yml 的当前 release-artifacts.attestation.json GitHub 构件证明；较早的发行版仍可回退到旧版的逐项资源 Cosign 捆绑包。SHA256 验证仍是默认的完整性检查。

Windows

Invoke-WebRequest https://raw.githubusercontent.com/verivus-oss/sqry/main/scripts/install.ps1 -OutFile install.ps1
Get-Content .\install.ps1
.\install.ps1 -Component all -VerifySignatures

PowerShell 安装程序会下载 Windows x86_64 发行版 ZIP，默认验证校验和，并将 sqry.exe、sqry-mcp.exe、sqry-lsp.exe 和 sqryd.exe 安装到用户安装目录。

需要确保可复现时，请使用固定版本的发行版：

.\install.ps1 -Component all -Version vX.Y.Z -VerifySignatures

Homebrew

Homebrew 是目前由公开发行清单支持的包管理器渠道。

brew tap verivus-oss/sqry
brew install sqry

该 formula 会为 Linux x86_64/arm64 和 macOS x86_64/arm64 安装 sqry、sqry-mcp、sqry-lsp 和 sqryd。

在发行控制渠道完善并通过验证之前，Scoop、Winget、AUR、Nix 和 Snap 不会作为公开发行资源提供。

从源代码构建

git clone https://github.com/verivus-oss/sqry.git
cd sqry
cargo install --path sqry-cli
cargo install --path sqry-mcp
cargo install --path sqry-lsp
cargo install --path sqry-daemon

要求：

• Rust 1.94+，使用 Edition 2024。
• 仓库在 rust-toolchain.toml 中固定了工具链版本 1.94.1。
• 完整的工作区构建会编译捆绑的 tree-sitter 语法和语言插件，可能需要大量磁盘空间。

Agent 设置

两个步骤即可将已安装的二进制文件连接到编码 Agent。请按顺序执行：MCP 为 Agent 提供工具，技能则告诉它何时使用这些工具。

1. 接入 MCP 服务

sqry mcp setup --tool claude --scope global
sqry mcp setup --tool codex --scope global
sqry mcp setup --tool gemini --scope global
sqry mcp status

除非确实需要按项目配置，否则请传入 --scope global。有关作用域的用途以及如何在写入前预览更改，请参阅 MCP 和编辑器。

连接 Agent 后，sqry-mcp 会将自己的参考资料作为 MCP 资源提供（sqry://docs/tool-guide、sqry://docs/query-syntax、sqry://docs/patterns、sqry://docs/architecture、sqry://docs/capability-map、sqry://meta/manifest）。这些内容随二进制文件一同打包并与其版本同步，因此 Agent 读取的工具参考资料不会与它实际可调用的工具脱节。

2. 添加 Agent 技能

这些技能会教 Agent 在任务中途使用 sqry，而不是退回到文本搜索。这种选择工具的判断能力无法仅靠工具文档提供，因此技能与上述 MCP 资源分开发布。

这些技能位于 verivus-oss/sqry-skills，共发布八项：核心路由技能 sqry-semantic-search，以及分别适用于 Claude Code、Codex、Gemini CLI、Grok、OpenCode、Antigravity 和 Mistral Vibe 的技能。

该仓库根目录本身也是兼容 Claude 的插件，会一并注册这些技能、sqry-mcp 和 sqry-lsp。将其克隆到 Agent 读取的插件目录中，或让 Agent 指向一个检出目录：

git clone --depth 1 https://github.com/verivus-oss/sqry-skills ~/.grok/plugins/sqry
# or, without installing:  claude --plugin-dir /path/to/sqry-skills

若只需使用技能，不需要插件接入：

npx skills add https://github.com/verivus-oss/sqry-skills

各 Agent 的路径以及 doctor.sh 健康检查均记录在该仓库的 README 中。目前 Shell 安装程序和 Homebrew formula 都不会安装这些技能，因此此步骤需手动完成。

首次索引

# Build the default fast-path index.
sqry index .

# Check status without rebuilding.
sqry index --status --json .

# Force a rebuild after upgrading across graph-format or semantics changes.
sqry index --force .

索引构件位于 .sqry/ 下。除非有意共享，否则请将 .sqry/ 和旧版 .sqry-index 构件添加到项目的忽略规则中。

索引验证

sqry search main . --validate fail --auto-rebuild
sqry index --status --metrics-format prometheus .

--validate 接受 off、warn（默认值）或 fail。使用 fail 时，过期索引会导致命令以退出代码 2 中止，而不是返回基于该索引计算的结果，因此可将其用作 CI 门禁。--auto-rebuild 会让 fail 先重建一次过期索引，然后在新索引上运行；在 warn 和 off 下不起作用。命令自身的参数（模式、各种形式的查询、--var、模糊算法）会在重建前检查，因此，如果命令拒绝某个参数，索引会保持原样。唯一的阈值是 --threshold-orphaned-files RATIO（0.0 到 1.0，默认值为 0.20）：当索引文件中已不在磁盘上的文件占比超过该值时，验证就会触发。因此，--threshold-orphaned-files 0.5 可容忍一半文件缺失，而 0 则不容忍任何文件缺失。

请注意其限制：这些是全局标志，但验证只会在 sqry search 和 sqry query 子命令中运行（不会在 sqry <pattern> 简写中运行，也不会在修订版本查询中运行，因为后者读取的是守护进程持有的修订版本）。如果索引已存在，将这些标志传给 sqry index 不会触发验证。

--metrics-format prometheus 会输出兼容 OpenMetrics 格式的文本，用于抓取索引状态。

插件选择

sqry 会记录构建索引时使用的插件集，以便后续加载图的命令重用相同语义。

sqry index .                         # default fast path
sqry index --include-high-cost .     # all compiled non-default plugins
sqry index --exclude-high-cost .     # force the fast path
sqry index --enable-plugin json .    # opt into one plugin
sqry index --disable-plugin json .   # opt out of one plugin

注册表包含快速插件、高墙钟时间插件和可选的专业插件。json 属于高墙钟时间插件。可选的专业插件包括 apex、abap、servicenow-xanadu-js、servicenow-xml、terraform、puppet 和 pulumi，前提是使用相应的 Cargo features 或 specialty-plugins 编译。

有关清理构件、插件分级和高成本行为，请参阅索引。

查询示例

# Symbol and attribute predicates.
sqry query "kind:function AND name:parse_*"
sqry query "kind:struct AND lang:rust"
sqry query "kind:function AND returns:Result"

# Relation predicates.
sqry query "callers:authenticate"
sqry query "callees:handle_request"
sqry query "imports:serde"

# Planner-backed query.
sqry plan-query "kind:function callers:main"

# Resolution-aware call filtering where populated by graph metadata.
sqry plan-query "kind:function callers:my_read resolved_via:binding_plane"

returns:<TypeName> 使用图中的 TypeOf{Return} 边。

调用解析谓词

resolved_via:<kind> 按生成该边的绑定类型筛选调用边。这与解析器的置信度高低是不同的问题：duck_typed 边不是低置信度的 direct 边，而是表示该调用通过 Python 鸭子类型而非语法引用完成绑定的记录。了解绑定机制后，你可以区分编译器能够检查的调用和只能在运行时解析的调用。

解析器接受以下八个值：

值	绑定机制
direct	由语言插件解析的语法调用
type_match	按类型与兼容签名匹配的间接调用
binding_plane	绑定平面中的指定初始化器见证
virtual_dispatch	JVM 虚方法或抽象方法分派
interface_dispatch	Go 接口分派
duck_typed	Python 鸭子类型分派
structural	TypeScript 结构化分派
promiscuous_elided	超出扇出上限，因此解析器记录诊断性自环，而非 N 个目标

# Callers of my_read that only bind through the binding plane,
# not through a plain syntactic call.
sqry plan-query "kind:function callers:my_read resolved_via:binding_plane"

framework 筛选以类型化 MCP 参数的形式提供。规划器也会解析 framework:<id>，但只有在运行过提取器的地方才会填充框架路由元数据。未匹配应视为元数据缺失，而非框架未使用的证明。

有关图谓词、快照表述、影响分析、语义差异和可视化，请参阅高级分析。

工作区

当一个逻辑项目跨越多个仓库或文件夹时，请使用工作区。

sqry workspace init .
sqry workspace scan .
sqry workspace status . --json
sqry workspace clean .

工作区配置可以来自 .sqry-workspace 注册表，或包含 sqry.workspace 块的 VS Code .code-workspace 文件。请参阅工作区。

守护进程

sqryd 会让图状态保持预热，以支持重复的 CLI、LSP、MCP 和编辑器工作流。

sqry daemon start
sqry daemon load .
sqry daemon status --json
sqry daemon rebuild . --force
sqry daemon logs --follow

请参阅守护进程模式。

MCP 与编辑器

使用以下配置 MCP 客户端：

sqry mcp setup --tool claude --scope global
sqry mcp setup --tool codex --scope global
sqry mcp setup --tool gemini --scope global

--scope 默认为 auto：如果工作目录位于某个仓库内，则会解析为 Claude Code 的项目级条目；否则会报错。对于整台机器通用的条目，请传入 --scope global；若要固定到某个仓库，请在该仓库内传入 --scope project。Codex 和 Gemini CLI 仅支持全局配置，因此这两个作用域对它们的效果相同，工作区解析则依据工具的启动目录。sqry mcp setup --dry-run 会打印变更内容，但不会写入；sqry mcp status 会报告当前配置。

独立运行的 sqry-mcp 提供完整的本地工具集。sqry-mcp --daemon 会连接到 sqryd，并提供由守护进程托管的工具子集。workspace_status.source_root_id 是不透明的显示／关联令牌，不是路径。请参阅 MCP 指南 和 sqry-mcp/README.md 中的组件文档。

MCP 搜索工具将字符串谓词与结构化 JSON 参数分开处理：

{
  "name": "semantic_search",
  "arguments": {
    "query": "kind:function items:true",
    "filters": {
      "language": ["rust"],
      "visibility": "public"
    }
  }
}

在 query 中使用 items:true 或 is_definition:true，设置仅匹配定义的查询谓词。调用 list_symbols 时，请使用结构化的 items_only 参数：

{
  "name": "list_symbols",
  "arguments": {
    "kind": "function",
    "language": "rust",
    "items_only": true
  }
}

如果图是在 V16 定义信号快照格式之前构建的，仅匹配定义的查询谓词和 list_symbols.items_only 会返回 reindexRequired／需要重新索引的提示，而不是信任过期的标记数据。

VS Code 扩展请参阅 sqry-vscode/README.md 和 sqry-vscode/USER_GUIDE.md。

用户指南

• 快速入门
• 用户指南索引
• 索引
• 工作区
• 守护进程模式
• MCP 指南
• 查询语言
• 仓库概览
• 规则
• 上下文传播
• Doctor
• 修订版本感知型工作区
• 高级分析
• 结构形状匹配
• 可视化

安全与供应链

• 发布制品附带 GitHub OIDC 无密钥证明，作为 release-artifacts.attestation.json 资源发布，并可使用 gh attestation verify 或 Cosign 验证。SHA256SUMS.txt 会随附发布，两个安装程序默认都会验证校验和。
• 每个版本还会发布一份发布清单和一份发布账本资源，记录构建经过的阶段。
• 依赖项在 CI 中由 cargo-vet（导入 Mozilla、Google、Bytecode Alliance 和 ISRG 的审计集）、cargo-deny 和 cargo-audit 把关。Clippy 以 -D warnings 运行。
• 查询规划器的文本解析器每晚使用 cargo-fuzz 进行模糊测试。每个 PR 都会对变更行运行 cargo-mutants，并在 master 上针对金丝雀 crate 基线运行；目前它只报告问题，不会阻止合并。
• SBOM（CycloneDX 和 SPDX）及 OpenVEX 文档由单独的工作流生成。

除非某个制品出现在你要安装的版本的资源列表中，否则不要假定它已提供。报告漏洞请参阅 SECURITY.md。

项目范围

sqry 是一个采用 MIT 许可证的开源项目，专注于一个产品目标：本地语义代码搜索。它不是托管搜索平台、代码检查工具、IDE 替代品或通用指标平台。