sqry-codex

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sqry for OpenAI Codex

适用于OpenAI Codex的sqry

This skill configures the Codex CLI agent to use sqry's MCP server for AST-based semantic code search across 37 languages.

本Skill用于配置Codex CLI Agent，使其可以调用sqry的MCP服务器，实现支持37种语言的、基于AST的语义代码搜索功能。

Setup

安装配置步骤

1. Install sqry

1. 安装sqry

bash

undefined

bash

undefined

Recommended: signed release installer

推荐：签名版本安装器

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

Fallback: build from source

备选方案：从源码编译

cargo install sqry-cli cargo install sqry-mcp

Alternative package manager

其他包管理器安装方式

brew install verivus-oss/sqry/sqry

undefined

brew install verivus-oss/sqry/sqry

undefined

2. Index your project

2. 为你的项目构建索引

bash

cd /path/to/your/project
sqry index .

bash

cd /path/to/your/project
sqry index .

3. Configure MCP server

3. 配置MCP服务器

Recommended:

bash

sqry mcp setup --tool codex
sqry mcp status

This writes a global entry to

~/.codex/config.toml

toml

[mcp_servers.sqry]
command = "/absolute/path/to/sqry-mcp"

Codex uses global MCP config and CWD-based workspace discovery. Start Codex from the project directory you want to analyze.

推荐配置方式：

bash

sqry mcp setup --tool codex
sqry mcp status

上述命令会在

~/.codex/config.toml

中写入全局配置项：

toml

[mcp_servers.sqry]
command = "/absolute/path/to/sqry-mcp"

Codex会使用全局MCP配置并基于当前工作目录自动识别工作区，请从你需要分析的项目目录下启动Codex。

4. Verify

4. 验证配置

After restarting Codex, test with:

"Use sqry to show graph stats for this project"

重启Codex后，使用以下指令测试配置是否生效：

"Use sqry to show graph stats for this project"

Skill Dependency

Skill依赖

This skill covers Codex CLI setup and integration patterns. Also load the
sqry-semantic-search
skill for tool selection guidance, query syntax, and disambiguation strategies.

sqry-semantic-search uses tiered discovery to save tokens: it loads a compact Quick Tool Selection guide first. If you need full parameter details, load

sqry-semantic-search/references/tool-reference.md

. For advanced workflows (security audit, pre-change analysis), load

sqry-semantic-search/references/workflows.md

. Only load what you need.

本Skill仅涵盖Codex CLI的安装配置与集成模式说明。请同时加载
sqry-semantic-search
Skill，以获取工具选择指南、查询语法和歧义处理策略相关说明。

sqry-semantic-search采用分层加载机制节省Token：默认会先加载精简版快速工具选择指南。如果你需要完整的参数说明，可加载

sqry-semantic-search/references/tool-reference.md

。如果需要了解高级工作流（安全审计、变更前分析），可加载

sqry-semantic-search/references/workflows.md

，请按需加载所需内容。

Quick Tool Selection

快速工具选择指南

I know the symbol name and want to...

See its definition →
```
mcp__sqry__get_definition
```

See who calls it →

mcp__sqry__direct_callers

(depth=1) or

mcp__sqry__relation_query

(multi-depth)

See what it calls →
```
mcp__sqry__direct_callees
```
See what breaks if I change it →
```
mcp__sqry__dependency_impact
```
Understand it with context →
```
mcp__sqry__explain_code
```

I want to search for symbols...

By name substring →
```
mcp__sqry__pattern_search
```
By kind/visibility/language →
```
mcp__sqry__semantic_search
```
With RAG-optimized grouping →
```
mcp__sqry__hierarchical_search
```

I want to analyze the codebase...

Circular dependencies →
```
mcp__sqry__find_cycles
```
Dead code →
```
mcp__sqry__find_unused
```
Change impact →
```
mcp__sqry__dependency_impact
```
Trace call path A→B →
```
mcp__sqry__trace_path
```

已知符号名称，需要执行以下操作时...

查看符号定义 →
```
mcp__sqry__get_definition
```
查看调用该符号的代码 →
```
mcp__sqry__direct_callers
```
（深度=1）或
```
mcp__sqry__relation_query
```
（多层深度）
查看该符号调用的其他内容 →
```
mcp__sqry__direct_callees
```
查看修改该符号会影响哪些内容 →
```
mcp__sqry__dependency_impact
```
结合上下文理解符号功能 →
```
mcp__sqry__explain_code
```

需要搜索符号时...

按名称子串搜索 →
```
mcp__sqry__pattern_search
```
按类型/可见性/语言搜索 →
```
mcp__sqry__semantic_search
```
使用RAG优化的分组搜索 →
```
mcp__sqry__hierarchical_search
```

需要分析代码库时...

查找循环依赖 →
```
mcp__sqry__find_cycles
```
查找死代码 →
```
mcp__sqry__find_unused
```
变更影响分析 →
```
mcp__sqry__dependency_impact
```
追踪A到B的调用路径 →
```
mcp__sqry__trace_path
```

Handling Ambiguous Symbols

歧义符号处理

When using

mcp__sqry__direct_callers

mcp__sqry__direct_callees

, or

mcp__sqry__call_hierarchy

with common names (

handle

new

init

process

run

), the tool may fail or return wrong results.

Always disambiguate by providing

file_path

json

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

Or use a qualified name:

"symbol": "UserService::authenticate"

If relation tools fail, fall back to

mcp__sqry__get_references

with a

path

filter to scope results.

当你对常见名称（

handle

、

new

、

init

、

process

、

run

）使用

mcp__sqry__direct_callers

、

mcp__sqry__direct_callees

或

mcp__sqry__call_hierarchy

工具时，工具可能会执行失败或返回错误结果。

请始终提供
file_path
来消除歧义：

json

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

或者使用限定名称：

"symbol": "UserService::authenticate"

如果关联查询工具执行失败，可回退到使用带

path

过滤条件的

mcp__sqry__get_references

来限定结果范围。

Tool Naming in Codex

Codex中的工具命名规则

Codex uses the

mcp__sqry__

prefix for sqry MCP tools:

mcp__sqry__semantic_search
mcp__sqry__relation_query
mcp__sqry__dependency_impact
mcp__sqry__explain_code
mcp__sqry__trace_path
...

Codex会为sqry MCP工具添加

mcp__sqry__

前缀：

mcp__sqry__semantic_search
mcp__sqry__relation_query
mcp__sqry__dependency_impact
mcp__sqry__explain_code
mcp__sqry__trace_path
...

Recommended AGENTS.md Addition

Code Search

代码搜索

Use sqry MCP tools for semantic code search:

```
mcp__sqry__semantic_search
```
- Find symbols by structure
```
mcp__sqry__relation_query
```
- Find callers, callees, imports
```
mcp__sqry__dependency_impact
```
- Analyze change impact
```
mcp__sqry__explain_code
```
- Understand a symbol with context

Use

rg

for literal text search. Use sqry for everything structural.

undefined

使用sqry MCP工具执行语义代码搜索：

```
mcp__sqry__semantic_search
```
- 按结构查找符号
```
mcp__sqry__relation_query
```
- 查找调用方、被调用方、导入关系
```
mcp__sqry__dependency_impact
```
- 分析变更影响范围
```
mcp__sqry__explain_code
```
- 结合上下文理解符号功能

字面量文本搜索请使用

rg

，所有结构类搜索请使用sqry。

undefined

Workflow

工作流

Use
```
mcp__sqry__semantic_search
```
or
```
mcp__sqry__pattern_search
```
to discover relevant code before reading files.
Use
```
mcp__sqry__dependency_impact
```
before modifying shared symbols.
Run the narrowest relevant tests first, then broader checks for shared paths.
Report files changed, behavior impact, and tests run in handoff.

读取文件前先使用

mcp__sqry__semantic_search

或

mcp__sqry__pattern_search

查找相关代码。

修改公共符号前先使用
```
mcp__sqry__dependency_impact
```
评估影响。
优先运行范围最小的相关测试，再对公共路径执行更广泛的检查。
交接时说明修改的文件、影响的行为和已运行的测试。

Common Codex Patterns

常用Codex使用模式

Find and understand a symbol

查找并理解符号

1. mcp__sqry__semantic_search   query: "kind:function name:process_order"
2. mcp__sqry__explain_code      file_path: "src/orders.rs", symbol_name: "process_order"
3. mcp__sqry__direct_callers    symbol: "process_order"

1. mcp__sqry__semantic_search   query: "kind:function name:process_order"
2. mcp__sqry__explain_code      file_path: "src/orders.rs", symbol_name: "process_order"
3. mcp__sqry__direct_callers    symbol: "process_order"

Pre-change impact analysis

变更前影响分析

1. mcp__sqry__dependency_impact  symbol: "shared_utility", max_depth: 3
2. mcp__sqry__find_cycles        (check for circular deps)
3. Make changes
4. mcp__sqry__semantic_diff      base: {ref: "main"}, target: {ref: "HEAD"}

1. mcp__sqry__dependency_impact  symbol: "shared_utility", max_depth: 3
2. mcp__sqry__find_cycles        (检查循环依赖)
3. 执行变更
4. mcp__sqry__semantic_diff      base: {ref: "main"}, target: {ref: "HEAD"}

Recent Features (since v6.0)

近期新功能（v6.0版本起）

Plugin cost tiering

插件成本分层

Plugins classified as
```
Fast
```
(default) or
```
HighWallClock
```
High-cost plugins (JSON, ServiceNow XML) excluded from default index

CLI:

--include-high-cost

--exclude-high-cost

--enable-plugin ID

--disable-plugin ID

Env:
```
SQRY_INCLUDE_HIGH_COST=1
```

插件分为
```
Fast
```
（默认）和
```
HighWallClock
```
两类
高成本插件（JSON、ServiceNow XML）默认不会被纳入索引

CLI参数：

--include-high-cost

--exclude-high-cost

、

--enable-plugin ID

--disable-plugin ID

环境变量：
```
SQRY_INCLUDE_HIGH_COST=1
```

Time-expensive MCP operations

高耗时MCP操作

```
rebuild_index
```
: 10min timeout, full graph rebuild -- only when index stale
```
semantic_diff
```
: creates git worktrees + indexes -- scope with file/kind filters
```
find_cycles
```
,
```
complexity_metrics
```
: can timeout on large graphs -- scope to files
```
find_duplicates
```
: quadratic scaling -- filter by file/language/kind
```
call_hierarchy
```
depth>2,
```
dependency_impact
```
depth>3: exponential growth

```
rebuild_index
```
：10分钟超时，全量重建依赖图——仅在索引过期时使用
```
semantic_diff
```
：创建git工作树+构建索引——使用文件/类型过滤条件缩小范围
```
find_cycles
```
、
```
complexity_metrics
```
：在大型依赖图上可能超时——限定文件范围使用
```
find_duplicates
```
：二次方时间复杂度——按文件/语言/类型过滤使用
```
call_hierarchy
```
深度>2、
```
dependency_impact
```
深度>3：指数级时间增长

Macro boundary analysis (Rust)

宏边界分析（Rust）

CLI:

sqry cache expand

--enable-macro-expansion

--cfg

--cfg-filter

--include-generated

--macro-boundaries

MCP:
```
mcp__sqry__expand_cache_status
```
tool, macro metadata in search/definition results

CLI参数：

sqry cache expand

、

--enable-macro-expansion

、

--cfg

、

--cfg-filter

、

--include-generated

、

--macro-boundaries

MCP功能：
```
mcp__sqry__expand_cache_status
```
工具、搜索/定义结果中包含宏元数据

JVM classpath analysis

JVM类路径分析

CLI:

--classpath

--classpath-depth

--classpath-file

MCP:
```
include_classpath
```
parameter on search tools,
```
provenance
```
field in results

CLI参数：

--classpath

、

--classpath-depth

、

--classpath-file

MCP功能：搜索工具支持
```
include_classpath
```
参数、结果中包含
```
provenance
```
字段

Security defaults

安全默认配置

MCP redaction preset now
```
"minimal"
```
by default (was
```
"none"
```
)
Override:
```
SQRY_REDACTION_PRESET=none
```
Index timeout: 600s, query timeout: 60s

MCP脱敏预设默认改为
```
"minimal"
```
（此前为
```
"none"
```
）
覆盖配置：
```
SQRY_REDACTION_PRESET=none
```
索引超时：600秒，查询超时：60秒

Other

其他更新

37 language plugins (added JSON, ServiceNow XML)
Snapshot format V7 -- rebuild index on major version upgrade
Multi-root VS Code workspace support

新增37个语言插件（新增JSON、ServiceNow XML支持）
快照格式V7——大版本升级后需要重建索引
支持多根目录VS Code工作区

Troubleshooting

问题排查

No tools visible: Restart Codex after running
```
sqry mcp setup --tool codex
```
Empty results: Run
```
sqry index .
```
to build the index
Stale results: Run
```
sqry index --force .
```
to force rebuild
Snapshot version mismatch: Run
```
rm -rf .sqry/graph && sqry index .
```
after major upgrades
Missing JSON/ServiceNow symbols: Rebuild with
```
sqry index --include-high-cost
```
Check health: Call
```
mcp__sqry__get_index_status
```

看不到可用工具：执行
```
sqry mcp setup --tool codex
```
后重启Codex
返回空结果：执行
```
sqry index .
```
构建索引
结果过期：执行
```
sqry index --force .
```
强制重建索引
快照版本不匹配：大版本升级后执行
```
rm -rf .sqry/graph && sqry index .
```
找不到JSON/ServiceNow符号：使用
```
sqry index --include-high-cost
```
重建索引
检查运行状态：调用
```
mcp__sqry__get_index_status
```

sqry-codex

Original

Translation

sqry for OpenAI Codex

适用于OpenAI Codex的sqry

Setup

安装配置步骤

1. Install sqry

1. 安装sqry

Recommended: signed release installer

推荐：签名版本安装器

Fallback: build from source

备选方案：从源码编译

Alternative package manager

其他包管理器安装方式

2. Index your project

2. 为你的项目构建索引

3. Configure MCP server

3. 配置MCP服务器

4. Verify

4. 验证配置

Skill Dependency

Skill依赖

Quick Tool Selection

快速工具选择指南

Handling Ambiguous Symbols

歧义符号处理

Tool Naming in Codex

Codex中的工具命名规则

Recommended AGENTS.md Addition

推荐添加到AGENTS.md的内容

Code Search

代码搜索

Workflow

工作流

Common Codex Patterns

常用Codex使用模式

Find and understand a symbol

查找并理解符号

Pre-change impact analysis

变更前影响分析

Recent Features (since v6.0)

近期新功能（v6.0版本起）

Plugin cost tiering

插件成本分层

Time-expensive MCP operations

高耗时MCP操作

Macro boundary analysis (Rust)

宏边界分析（Rust）

JVM classpath analysis

JVM类路径分析

Security defaults

安全默认配置

Other

其他更新

Troubleshooting

问题排查