XORE Search Engine - 全文搜索和语义搜索

这个crate提供基于Tantivy的全文搜索和基于ONNX的语义搜索功能。

模块

• scanner: 高性能文件扫描器，支持并行遍历和多种过滤条件
• indexer: Tantivy 索引构建器
• incremental: 增量索引器，支持文件监控和自动更新
• query: 搜索查询引擎
• tokenizer: 中英文混合分词器
• watcher: 文件监控和事件处理

XORE Explore the Abyss, Extract the Core English | 简体中文

一站式极致性能本地开发者工具，将语义搜索与数据即时分析深度融合，毫秒级响应，零配置体验，专为开发者与 AI Agents 深度优化。

目录

• 项目简介
• 核心特性
• 技术架构
• 快速开始
  • 环境要求
  • 编译安装
• 项目结构
• 配置说明
• 开发指南
• 性能基准
• 更新日志
• 贡献指南
• 许可证
• 致谢

项目简介

XORE 是一款使用 Rust 开发的高性能本地 CLI 工具，旨在为开发者提供极速的文件搜索和数据处理能力。

这是什么？

XORE 不是简单的搜索工具（如 ripgrep）+ 数据工具（如 DuckDB）的组合，而是一个让搜索即分析、分析即搜索的一体化工具。它将全文搜索、语义搜索和数据处理引擎深度整合，提供极简配置体验。

为什么做这个？

传统的开发工作流中，文件搜索和数据分析是两个独立的环节：

• 用 grep/ripgrep 找到文件后，还需要手动打开、解析、分析
• 用 awk/pandas/DuckDB 分析数据时，缺乏语义理解能力
• 需要在多个工具间切换，效率低下，这点在Coding Agent工作流中尤为明显，反复切换工具和上下文，导致效率大幅下降，token用量大量增加。

XORE 通过 Rust 的零成本抽象和高性能库，将这些能力统一到一个工具中，提升开发者和 Agent 的效率。

适用场景

• 数据工程师：快速探索本地数据集，进行质量检查和转换
• 后端开发者：分析日志文件，审计配置文件，查找代码片段
• DevOps 工程师：排查生产问题，监控指标分析
• 研究人员：处理实验数据，文献检索和整理
• AI Agents：提供 Agent 友好的接口，支持结构化摘要和智能采样，极大节省 Token 用量和对话轮次。

MCP 服务器支持

XORE 提供 MCP 服务器实现，可集成到 Roo Code、Claude Desktop 等 AI 助手中。详见 MCP 服务器文档。

核心特性

🤖 针对Agent优化 (xore agent)

• 结构化摘要：xore agent schema 仅返回数据结构与分布，不搬运原始数据。
• 智能采样：xore agent sample 自动提取最具代表性的数据样本。
• Token 预算控制：自动对长文本进行语义压缩，保留核心逻辑（如函数头/尾），中略冗余实现。
• Agent 修复建议：报错信息自动转化为可执行的修复指令。
• 智能目录预览：xore agent peek 目录扫描和智能预览，支持 JSON/树形/Markdown 输出
• 全局文件监控：xore agent abyss 实时监控用户主目录下的文件变化

🔍 智能搜索引擎

• 语义块切片：基于 Tree-sitter 感知代码结构，返回完整的函数/类块而非单纯的行。
• 全文搜索：基于 Tantivy 的高性能倒排索引，BM25 排序。
• 模糊与前缀：支持 ~term 模糊匹配与 term* 前缀搜索。
• 增量索引：毫秒级文件监控更新（--watch），确保 Agent 看到的是最新状态。
• 守护进程模式：xore watch start 后台运行，支持 status/logs/stop 管理

⚡ 高性能数据处理

• 计算下推：在本地利用 Polars 引擎完成 SQL 过滤、聚合，仅输出结果，避免向 Agent 传输原始数据。
• 零拷贝读取：大文件（>1MB）自动使用 memmap2 内存映射，GB 级数据秒级加载。
• 惰性求值：LazyFrame 延迟执行优化内存占用，支持处理远超内存大小的超大规模数据集。
• 多格式支持：原生支持 CSV, JSON, Parquet, Arrow 等，自动 Schema 推断。

🎯 数据质量分析

• 自动 Profiling：统计分析、缺失值检测（百分比）、重复行识别。
• 类型推断：智能识别列类型和数据模式，自动推断 Schema。
• 离群值检测：IQR 方法检测数值列异常值（API 可用）。
• 列统计：唯一值数量、缺失值分布、数据类型信息。

🚀 极致性能

• 零拷贝设计：内存映射和零拷贝 I/O
• SIMD 加速：向量化计算优化
• 智能缓存：多级缓存策略
• 毫秒级响应：本地数据即时查询

技术架构

核心技术栈

• Rust 1.91+ - 系统编程语言，保证性能和内存安全
• Tantivy 0.22 - 全文搜索引擎
• Polars 0.45 - 高性能 DataFrame 库
• ONNX Runtime 2.0 - 机器学习推理引擎
• Tokio 1.35 - 异步运行时
• Clap 4.5 - 命令行参数解析

项目模块

xore/
├── xore-cli/         # CLI 界面和命令路由
├── xore-core/        # 核心类型和配置管理
├── xore-search/      # 搜索引擎模块
├── xore-process/     # 数据处理引擎
├── xore-ai/          # 语义搜索和嵌入
└── docs/    # 项目文档

快速开始

环境要求

• Rust >= 1.91.0
• Cargo >= 1.91.0
• 操作系统：macOS、Linux 或 Windows

编译安装

快速安装（推荐）

# 方式一：一键安装脚本（macOS/Linux）
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/shuheng-mo/xore/releases/latest/download/xore-installer.sh | sh

# 方式二：使用 cargo-binstall
cargo binstall xore

# 方式三：源码编译安装
cargo install --path xore-cli

手动编译

• 克隆项目

git clone https://github.com/shuheng-mo/xore.git
cd xore

• 编译

# Debug 构建（开发调试）
cargo build

# Release 构建（生产使用）
cargo build --release

• 安装到系统路径（可选）

cargo install --path xore-cli

• 验证安装

xore --version
# 输出：xore 1.0.0

详细使用文档

请参阅 docs/README.md 获取完整的使用指南。

项目结构

xore/
├── xore-cli/              # CLI 命令行界面
├── xore-config/           # 配置管理模块
├── xore-core/             # 核心共享模块
├── xore-search/           # 搜索引擎
├── xore-process/          # 数据处理引擎
├── xore-ai/               # AI 语义搜索模块
├── docs/                  # 项目文档
└── examples/              # 示例数据和脚本

配置说明

XORE 使用配置文件来管理默认行为和性能参数。配置文件位于 ~/.xore/config.toml。

默认配置

[search]
# 索引存储路径
index_path = "~/.xore/index"
# 工作线程数（默认使用所有 CPU 核心）
num_threads = 0
# 自动重建索引的天数
auto_rebuild_days = 30
# 最大索引大小（GB）
max_index_size_gb = 10

[process]
# 启用惰性求值
lazy_execution = true
# 分块大小（MB）
chunk_size_mb = 64
# 最大内存使用（GB）
max_memory_gb = 4

[ai]
# 嵌入模型路径
model_path = "~/.xore/models/embedding.onnx"
# 向量维度
embedding_dim = 384
# 批处理大小
batch_size = 32

[ui]
# 彩色输出
colored = true
# 进度条
progress_bar = true
# 详细模式
verbose = false

环境变量

开发指南

开发流程

1. Fork 项目仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 编写代码和测试
4. 运行测试 (cargo test)
5. 代码格式化 (cargo fmt)
6. 代码检查 (cargo clippy)
7. 提交更改 (git commit -m 'feat: Add some AmazingFeature')
8. 推送到分支 (git push origin feature/AmazingFeature)
9. 提交 Pull Request

代码规范

项目遵循 Rust 官方代码风格：

# 自动格式化代码
cargo fmt --all

# 代码质量检查
cargo clippy --all-targets --all-features -- -D warnings

# 运行所有测试
cargo test --all

# 生成文档
cargo doc --no-deps --open

提交规范

遵循 Conventional Commits 规范：

<type>(<scope>): <subject>

<body>

<footer>

类型（Type）：

• feat: 新功能
• fix: 修复 Bug
• docs: 文档更新
• style: 代码格式调整
• refactor: 代码重构
• perf: 性能优化
• test: 测试相关
• chore: 构建/工具链更新

示例：

feat(search): add semantic search support

Implement semantic search using ONNX Runtime with
MiniLM-L6 embedding model.

Closes #123

本地开发

# 启用详细日志
RUST_LOG=debug cargo run -- find "test"

# 使用 cargo-watch 自动重新编译
cargo watch -x 'run -- find "test"'

# 运行基准测试
cargo bench

# 分析代码覆盖率
cargo tarpaulin --out Html

性能基准

基于最新测试数据集的实际测试结果：

搜索性能对比

数据处理性能对比

性能优势

内存占用

• 索引: 约为原始数据的 15-20%
• 大文件: 使用 mmap 零拷贝，内存占用接近于零
• 运行时: 峰值内存 < 数据大小的 2 倍

测试环境：macOS (Apple Silicon), 对比 ripgrep 15.1.0, DuckDB v1.4.4, Python 3.14.3

更新日志

查看 CHANGELOG.md 了解详细的版本历史。

v1.2.0 (2026-03-08)

Agent 增强与守护进程支持

• ✨ 新增 xore agent peek 命令：智能目录预览，支持 JSON/树形/Markdown 输出
• ✨ 新增 xore watch 守护进程管理命令：支持 start/status/logs/stop
• ✨ 新增 xore agent abyss 全局文件监控守护进程
• ✨ Find 命令新增 --watch-daemon 参数
• 📝 完善项目文档和测试覆盖

v1.1.0 (2026-03-07)

MCP 服务器与错误处理优化

• ✨ 新增 MCP 服务器支持（集成到 Roo Code 等 AI 助手）
• ✨ 扩展错误处理系统，提供友好的错误提示
• ✨ 新增智能推荐系统
• ✨ 实现语义搜索 CLI 集成

v1.0.0 (2026-01-11)

初始版本发布

• ✨ 实现全文搜索引擎（基于 Tantivy）
• ✨ 实现语义搜索（基于 ONNX Runtime）
• ✨ 实现数据处理引擎（基于 Polars）
• ✨ 支持 SQL 查询
• ✨ 数据质量分析功能
• 📝 完善项目文档
• ✅ 添加单元测试和集成测试

贡献指南

感谢你对 XORE 项目的关注！我们欢迎各种形式的贡献。

如何贡献

• 报告 Bug：在 Issues 页面提交问题
• 功能建议：提出新功能的想法和建议
• 代码贡献：提交 Pull Request
• 文档改进：帮助改进文档质量
• 测试反馈：在不同环境下测试并反馈问题

详细的贡献指南请查看 CONTRIBUTING.md。

贡献者

感谢所有为 XORE 做出贡献的开发者！

许可证

查看 LICENSE 文件了解详情。

致谢

XORE 的开发离不开以下优秀的开源项目：

• Tantivy - 高性能全文搜索引擎
• Polars - 快速的 DataFrame 库
• ONNX Runtime - 跨平台 ML 推理引擎
• Tokio - 异步运行时
• Clap - 命令行参数解析库

特别感谢 Rust 社区提供的强大生态系统。