Xray——高性能代码智能引擎
基于倒排索引+AST的大规模代码库代码智能引擎。毫秒内容搜索、结构化代码导航（类、方法、调用树）、代码历史分析和用于AI代理集成的原生MCP服务器——在一个静态链接的Rust二进制文件中。旨在通过为代理提供对代码库的直接结构化访问，而不是依赖于浅层文本搜索和缓慢的多工具编排，使GenAI工作流程更快、更深入、更精确。
在具有66K个文件、878K个定义的真实生产代码库上进行测量(完整基准测试):
| 度量 | 值 |
|---|---|
| 索引内容搜索（MCP，内存中） | 1.7-2.3毫秒 每个查询（子字符串，典型） |
| 内容搜索——高频词 | ~15ms （208K次） |
| 呼叫树——被叫者（方向=向下） | 0.5毫秒 |
| 呼叫树——呼叫者（方向=向上，深度3） | 3-11毫秒 |
| 查找实现（baseType） | 1.3毫秒 |
| 按属性查找 | 0.4毫秒 |
| 指数构建 | 7-16秒 （内容）， 16-32秒 （AST定义）--因CPU而异 |
| 增量更新 | **\ \*“With xray”列中的时间为 纯工具执行时间 （索引查找+响应）。在实践中，增加约1-2秒的LLM延迟（模型思维+MCP往返），这超出了工具的控制范围。 |
📖 更多： 用例和LLM工作流 --详细的场景包括人工智能驱动的架构探索、自动化影响分析，以及一个真实世界的案例研究，在该案例中，我们在5分钟内对3800线系统进行了逆向工程。
文档
| 文档 | 描述 |
|---|---|
| 安装指南 | 下载预构建 xray.exe，将VS Code Copilot Chat/Roo Code/Cline配置为MCP客户端（Windows） |
| 用例和LLM工作流 | 现实世界场景、现成的LLM工具链和案例研究 |
| CLI参考 | 所有带有示例和选项的命令 |
| MCP服务器指南 | 设置、工具API、JSON-RPC示例 |
| 建筑 | 系统概述、组件设计、数据流图 |
| DI支持 | 什么在MEDI/Autofac/Lamar/SimpleInjector等中自动解决，什么不是，以及DI形代码库的配方 |
| 存储模型 | 索引格式、序列化、过时、增量更新 |
| 并发 | 线程模型、锁策略、监视器设计 |
| 权衡 | 考虑备选方案的设计决策 |
| 基准测试 | 性能数据、规模估计、行业比较 |
| E2E测试计划 | 端到端测试用例（CLI+MCP），按工具模块化——8个规范文件+README |
| 更新日志 | 按类别组织的所有显著更改（功能、修复、性能） |
特性
- 并行文件系统漫游 --使用所有可用的CPU内核以实现最大吞吐量
- 文件名索引 --用于即时文件查找的预构建索引（如 一切)
- 反转内容索引 --语言无关的标记器将标记映射到文件，以便在任何文本文件（如Elasticsearch）中进行即时全文搜索
- TF-IDF排名 --内容搜索结果按相关性排序，最相关的文件优先
- 相关性排名 —
xray_definitions和xray_fast按匹配质量排序的结果：完全匹配→ 前缀→ 包含类型和名称长度的断开器 - 正则表达式支持 --用于模式匹配的完整Rust正则表达式语法
- 尊重
.gitignore--自动跳过忽略的文件 - 扩展过滤 --将搜索限制在特定文件类型
- MCP服务器 --用于异步启动的AI代理（Roo Code、Cline或任何兼容MCP的客户端）的本地模型上下文协议服务器，名为
XRAY_POLICY初始化指导和响应策略提醒，以减少工具选择偏差 - GenAI接地 --为代理提供对代码、历史记录、调用树和安全编辑工作流的直接结构化访问，从而能够比逐个工具的通用编排得出更深入、更准确的结论
- 同步重新索引后
xray_edit--文件编辑响应现在会在返回之前刷新内存中的反向内容和定义索引，因此后续xray_grep/xray_definitions/xray_callers/xray_fast调用可以看到零延迟的新内容（无需等待500毫秒的FS监视器去抖动） xray_edit从设计上讲，工作空间范围是不可知的 --与读取/索引工具不同，xray_edit接受两条相对路径（解析为--dir)以及磁盘上任何位置的绝对路径。这是有意为之：它允许一个服务器实例处理跨多个工作区的编辑、草稿目录或工具配置，而无需重新启动。只读工具(xray_grep,xray_definitions,xray_callers,xray_fast)保持工作区绑定，以保持内存中索引的作用域，避免将工作区拓扑泄漏到磁盘。- 代码定义索引 --用于结构化代码搜索的树型AST解析 *（C#、Types/TSX、Rust）*，基于正则表达式的解析 *结构化查询语言* （.sql文件：存储过程、表、视图、函数、类型、索引、列和SP主体中的调用站点），以及按需树型解析 *XML/.csproj/.config/.props/.targets/.resx/.nuspec/.vsixmanifest/.appxmanifest/.manifestxml*.富含模板元数据的Angular组件（选择器、HTML模板的子组件）
- DI感知呼叫树 —
xray_callers通过接口接收器（构造函数/属性/方法/字段注入）、I前缀约定、声明来解析调用者base_types，DI注入字段的模糊字段名匹配(_userService,m_userService)，以及每种方法的局部变量类型推断（var、cast、，as、等待、模式匹配）。跨MEDI/Autofac/Lamar/SimpleInjector/DryIoc/Ninject/MEF/源生成器工作，无需解析容器注册。看 DI支持 对于完整的矩阵和限制。 - 代码复杂性度量 --AST索引期间计算的7个指标：圈复杂度、认知复杂度（SonarSource）、最大嵌套深度、参数计数、返回/抛出计数、调用计数、lambda计数。查询方式
includeCodeStats，按任何指标排序，过滤min*阈值 - 并行标记化 --内容索引标记化在所有CPU核心上并行化
- 并行解析 --具有延迟语法加载的多线程树保姆解析
- 文件监视器 --文件更改时的增量索引更新（每个文件\ 固定到释放标签上，而不是
main为了再现性，请更换main在URL中，例如。v0.5.0.通行证 `-RepoPath
以非交互方式定位特定的仓库。添加 -EnableCopilotCli 和 -EnableVSCode 跳过交互式客户端提示。 -UseBasicParsing` 在Windows PowerShell 5.1上是必需的（在PowerShell 7+上是不允许的），并且避免了IE引擎安全提示。
脚本将：
- 下载最新
xray.exe从 到%LOCALAPPDATA%\xray\ - 扫描存储库并建议要索引的文件扩展名
- 创建您选择加入的MCP配置--
.vscode/mcp.json为了 VS代码复制聊天 和.mcp.json为了 GitHub Copilot命令行界面 （每个单独提示，或通过-EnableVSCode/-EnableCopilotCli) - 保护配置免受攻击
git pull并防止将本地xray条目泄露到提交中：
- 追踪 .mcp.json （共享回购案例）→ 每个克隆 git污迹/清洁过滤器 (xray-mcp)所以 git status 保持干净，上游更改会悄无声息地应用 - 追踪 .vscode/mcp.json （共享回购案例）→ 每克隆相同筛选器(xray-vscode-mcp)，绑定到VS Code形状 servers 容器 - 未跟踪 .vscode/mcp.json → git update-index --skip-worktree - 未跟踪文件→ .git/info/exclude
看 安装指南 有关污迹/清洁过滤器设计、手动设置、Cline配置和Roo Code注释（ -EnableRoo 开关当前为禁止操作）。
选项C——从源代码构建。
git clone https://github.com/pustynsky/xray
cd xray
cargo build --release使用功能标志构建
树型语言解析器可以通过Cargo功能进行配置。SQL解析器始终是内置的（基于正则表达式，不依赖于树），并且不是特征门控的。默认功能支持C#、Types/TSX、Rust和XML按需解析：
# Default: C#, TypeScript/TSX, Rust, XML on-demand (+ SQL always-on)
cargo build --release
# C# only (drops TypeScript/Rust/XML tree-sitter grammars; SQL still works)
cargo build --release --no-default-features --features lang-csharp
# C# + Rust, no TypeScript/XML
cargo build --release --no-default-features --features lang-csharp,lang-rust
# Smallest binary: no tree-sitter at all (SQL regex parser + content/file indexes only)
cargo build --release --no-default-features| 特性 | 依赖关系 | 分析器 |
|---|---|---|
lang-csharp *（默认）* | tree-sitter, tree-sitter-c-sharp | C#AST（树保姆） |
lang-typescript *（默认）* | tree-sitter, tree-sitter-typescript | TypeScript/TSX AST（树型） |
lang-rust *（默认）* | tree-sitter, tree-sitter-rust | Rust AST（树保姆） |
lang-xml *（默认）* | tree-sitter, tree-sitter-xml | XML/ .csproj / .config / .props / .targets / .resx / .nuspec / .vsixmanifest / .appxmanifest / .manifestxml （按需，树保姆） |
| *（始终内置，无功能）* | *（无）* | SQL DDL（基于正则表达式：存储过程、表、视图、函数、类型、索引、列、调用站点） |
CLI使用情况
# Build content index for C# files
xray content-index -d C:\Projects -e cs
# Search by token (TF-IDF ranked)
xray grep "HttpClient" -d C:\Projects -e cs
# Search file names (instant)
xray fast "UserService" -d C:\Projects -e cs看 CLI参考 对于所有命令和选项。
MCP服务器（AI代理集成）
# Start MCP server with file watching and code definitions
xray serve --dir C:\Projects --ext cs --watch --definitions有关最终用户设置（下载二进制文件，配置Copilot Chat/Roo Code/Cline），请参阅 安装指南有关工具API、JSON-RPC架构和协议详细信息，请参阅 MCP服务器指南.
架构概述
该引擎使用三种独立的索引类型和一个git历史缓存：
| 索引 | 文件 | 创建者 | 搜索者 | 商店 |
|---|---|---|---|---|
| 文件名 | .file-list | xray index | xray fast | 文件路径、大小、时间戳 |
| 内容 | .word-search | xray content-index | xray grep | Token→ （文件、行号）地图 |
| 定义 | .code-structure | xray def-index | xray_definitions / xray_callers | AST提取的类、方法、调用站点 |
| Git历史记录 | .git-history | 背景（自动） | xray_git_history / xray_git_diff / xray_git_authors / xray_git_activity / xray_git_blame / xray_branch_status | 提交元数据、文件到提交映射、分支状态 |
索引存储在 %LOCALAPPDATA%\xray\ 并且对于内容搜索来说是语言无关的，对于定义来说是语言特定的：C#、TypeScript/TSX和Rust通过树形图；通过内置的正则表达式解析器执行SQL；XML/ .csproj / .config / .props / .targets / .resx / .nuspec / .appxmanifest / .vsixmanifest / .manifestxml 通过树状图按需解析（不批量索引）。当发生以下情况时，git历史缓存会在后台自动构建 .git 目录存在。看 建筑 了解详情。
有关调用者树验证的详细信息（DI解析、类型推断、假阳性过滤）和Angular模板元数据，请参阅 建筑.
依赖项
| 板条箱 | 用途 |
|---|---|
| 相似的 | 统一差异生成 xray_edit 工具 |
| 忽略 | 并行目录行走（来自ripgrep） |
| 拍手 | CLI参数解析 |
| 正则表达式 | 正则表达式支持 |
| 序列化与反序列化 + 指定的 | 索引和git缓存的快速二进制序列化 |
| Serde JSON | MCP协议的JSON序列化 |
| 通知 | 跨平台文件系统通知 |
| 目录 | 特定于平台的数据目录路径 |
| 树保姆 | 用于代码定义提取的增量解析（C#、Types/TSX、Rust） |
| lz4_flex | 磁盘索引文件的LZ4帧压缩 |
| 含羞草酸 | 高性能内存分配器 |
| 这个错误 | 人体工程学错误类型定义 |
| 追踪 + 追踪订户 | 结构化诊断日志记录 |
| ctrlc | 优雅的停机信号处理 |
| 标准 | 统计基准测试（dev） |
| 预试验 | 基于属性的测试（dev） |
测试
# Run all unit tests (~2600+; cargo test --list reports 2,609 in xray bin + 107 in lib)
cargo test
# Run benchmarks
cargo bench
# Run E2E tests (~35 CLI + MCP tests in e2e-test.ps1; full E2E spec catalog in docs/e2e/ is larger)
pwsh -File e2e-test.ps1为了可维护性，测试文件按语言模块拆分——请参阅 建筑 对于完整的模块结构。关键测试类别：
| 类别 | 覆盖范围 |
|---|---|
| 单元测试 | 标记器、路径规范化、陈旧性、序列化往返、TF-IDF排名 |
| 集成 | 构建+搜索ContentIndex，构建FileIndex，MCP服务器端到端 |
| MCP协议 | JSON-RPC解析、初始化、工具/列表、工具/调用、通知、错误 |
| 子字符串/三角图 | 三角图生成、索引构建、子字符串搜索、集成测试 |
| 定义 | C#（树保姆）、Types/TSX（树保姆”）、Rust（树保姆“）、SQL（基于正则表达式）、增量更新 |
| 调用者 | 调用树向上/向下、DI解析、过载、周期、影响分析 |
| Git缓存 | 流解析程序、路径规范化、查询API、序列化往返、磁盘持久化、HEAD验证 |
| 属性测试 | 标记器不变量、发布往返、索引一致性、TF-IDF排序 |
| 基准 | 令牌化器吞吐量、索引查找延迟、TF-IDF评分、正则表达式扫描 |
作者
谢尔盖·普斯廷斯基
许可证
根据以下任一方式获得许可：