iohub/codexray

# CodeXRay **面向 AI 时代的代码搜索与知识引擎。** 语义 + 全文混合搜索，实时索引，调用图 + 代码向量 + 提交向量 + 知识向量 —— 统一集成于一个原生 MCP server 中。 ## 核心亮点 ### 🧠 混合搜索引擎 —— 语义 + 全文双通道 超越了简单的关键词匹配。Dense vector 搜索能够理解代码意图（"登录逻辑" → `authenticateUser`），而 BM25 全文搜索则锁定精确匹配。结果通过 RRF 融合，并由 Cross-Encoder 重新排序以确保精度。当 embedding API 不可用时，会优雅地降级为 graph search —— 永不中断。 ### 🔗 4D 知识图谱 调用图 + 代码向量 + 提交向量 + 知识向量 —— 全方位的四维代码库感知。Tree-sitter AST 解析 7 种语言，以构建完整的函数/类/方法关系： - **谁调用了这个函数？** - **这个函数依赖什么？** - **通过描述功能来查找代码** ### ⚡ 实时增量索引 首次运行时进行全量构建，此后仅重新处理更改的文件（MD5 diff）。在 MCP 启动时自动索引，并在 runtime 期间监视文件更改。自动清理孤立的 embeddings —— 索引绝不会臃肿。 ### 🔌 原生 MCP，本地优先 专为 Claude Code/Codex CLI MCP stdio 协议构建。安装时会自动注册 MCP —— 无需手动配置，无需常驻 daemon。随 Claude Code 启动和退出，零残留。所有代码和数据均保留在本地，无需 SaaS。 ## 快速开始 ### 推荐方式 —— 一条 curl 命令 ``` curl -fsSL https://raw.githubusercontent.com/iohub/codexray/main/install.sh | sh ``` 自动检测 OS/arch/libc，下载、安装并注册 MCP。之后重启 Claude Code —— 搞定。 **首次运行：** `codexray install` 会自动启动一个用于配置 embedding API 的交互式向导（graph search 无需配置即可工作）。 ### 手动下载（以 Linux musl 为例） ``` curl -L -o codexray.tar.gz https://github.com/iohub/codexray/releases/latest/download/codexray-linux-x64-musl.tar.gz tar -xzf codexray.tar.gz ./codexray install && rm codexray.tar.gz ``` 其他平台：从 [最新发布版本](https://github.com/iohub/codexray/releases/latest) 中将 `linux-x64-musl` 替换为 `darwin-arm64`、`darwin-x64` 或 `linux-x64`。 ### 从源码构建 ``` git clone https://github.com/iohub/codexray.git && cd codexray cargo build --release && ./rust-core/target/release/codexray install ``` ## 工作原理 ### 索引构建 ``` Source files → Tree-sitter AST parse (7 languages) → Extract functions / classes / methods → Build call graph (PetCodeGraph) → Batch embed via API (SQLite cache) → Store vectors in LanceDB → Build BM25 index in Tantivy → Save to ~/.codexray// ``` **幂等性**：索引构建是增量的 —— 首次运行为全量构建，后续运行会对比 MD5 哈希值，仅重新处理发生更改的文件。 ### 混合搜索 Pipeline (`codexray search`) ``` ┌─────────────────────┐ User query ────────────→│ Embedding Model │──→ Query vector └─────────────────────┘ │ ┌───────────────────────┼───────────────────────┐ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Dense Search │ │ Sparse Search│ │ Graph Search │ │ (LanceDB ANN)│ │ (Tantivy BM25)│ │ (PetCodeGraph)│ └──────┬───────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ └──────────────────────┼──────────────────────┘ ▼ ┌─────────────────┐ │ RRF Fusion │ ← Reciprocal Rank Fusion │ (Top-20 candidates)│ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Reranker │ ← Cross-Encoder fine re-ranking │ (Qwen3-Reranker)│ scores each (query, code) pair └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Final Results │ ← Top-5 (or Top-N) └─────────────────┘ ``` | 阶段 | 技术 | 作用 | |-------|-----------|------| | **Dense Search** | LanceDB + Embedding 模型 | 语义向量相似度 | | **Sparse Search** | Tantivy BM25 | 关键词与 token 匹配 | | **RRF Fusion** | Reciprocal Rank Fusion | 公平合并不同维度的分数 | | **Reranker** | Cross-Encoder (Qwen3-Reranker-4B) | 全交互精准打分 | | **Fallback** | PetCodeGraph | 基于 graph 的名称搜索（无需 API） | 如果 embedding/reranker 不可用，pipeline 会优雅地降级为基于 graph 的名称搜索和仅 BM25 模式。 ### 自动索引模式 | 模式 | 时机 | 触发条件 | |------|------|---------| | **MCP server** | 启动时 + 文件更改 | `codexray install` + 重启 Claude Code | MCP server 会在启动时自动索引，在 runtime 期间监视文件更改，并注入 CLAUDE.md 以供工具发现。 ### 存储路径 - **配置文件**: `~/.codexray/config.json`（全局，跨所有项目共享） - **索引**: `~/.codexray//` - `project.json` — 项目元数据 - `graph.bin` — 序列化的调用图 - `embeddings.lance/` — LanceDB 向量数据 - `tantivy_bm25/` — BM25 全文索引 - `file_hashes.json` — MD5 增量跟踪 - `embedding_hashes.json` — Embedding 增量跟踪 无需 daemon，无需 HTTP server。每个 CLI 命令都是独立运行的进程。 ## 支持的语言 | 语言 | 函数 | 结构体/类 | 调用图 | |----------|:---------:|:---------------:|:----------:| | Rust | ✅ | ✅ | ✅ | | Python | ✅ | ✅ | ✅ | | JavaScript | ✅ | ✅ | ✅ | | TypeScript | ✅ | ✅ | ✅ | | Go | ✅ | ✅ | ✅ | | C/C++ | ✅ | ✅ | ✅ | | Java | ✅ | ✅ | ✅ | ## 配置说明 `~/.codexray/config.json`: ``` { "embedding": { "provider": "openai-compatible", "model": "Qwen/Qwen3-Embedding-4B", "api_token": "sk-...", "api_base_url": "https://api.siliconflow.cn/v1", "dimensions": 2560 }, "index": { "min_code_block_length": 16, "enable_reranker": true, "hybrid": { "enable_bm25": true, "bm25_top_k": 100, "vector_top_k": 100, "rrf_k": 60, "rrf_top_k": 20, "short_code_threshold": 30, "short_code_penalty": 0.5 }, "reranker": { "enabled": true, "model": "Qwen/Qwen3-Reranker-4B", "api_token": "sk-...", "api_base_url": "https://api.siliconflow.cn/v1/rerank", "top_n": 5, "candidate_multiplier": 5, "timeout_secs": 60 } }, "installed_hooks": {} } ``` ### 模型角色 | 模型 | 角色 | 时机 | |-------|------|------| | `Qwen/Qwen3-Embedding-4B` | 将代码转换为向量以供 dense search | 索引构建 | | `Qwen/Qwen3-Reranker-4B` | 对 (query, code) 对进行精准打分 | 搜索时刻 | 通过首次运行时的交互式向导进行设置，或手动创建。如果 embedding API 不可用，基于 graph 的搜索依然可用。 ## 开发指南 ``` cd rust-core # Build cargo build # Build release cargo build --release # 运行测试 cargo test # 运行特定测试 cargo test test_build_graph_functionality -- --nocapture ``` ## License MIT 技术栈：Tree-sitter · Petgraph · LanceDB · Tantivy · Tokio · Clap · Axum

标签：AI编程助手, MCP服务, SOC Prime, 代码分析, 代码搜索引擎, 凭证管理, 可视化界面, 开发工具, 语义检索, 通知系统