CodeBendKit/codeseek
GitHub: CodeBendKit/codeseek
基于 Rust 的代码智能 CLI 工具，通过调用图分析与混合语义搜索为 AI 编程助手提供精准的代码检索与导航能力。
Stars: 818 | Forks: 43
# CodeSeek
**为 Claude Code 打造的代码智能 CLI 工具。** 基于 AST 的调用图分析 + 语义搜索 —— 直接在你的终端中运行。
## 快速开始
```
# 通过 npm 安装（自动处理 setup wizard + binary download）
npm install -g codeseek
# 首次运行 — 交互式 setup wizard 配置你的 embedding model
codeseek
# 索引你的项目
codeseek init
# 按符号名称搜索代码
codeseek search main --limit 10
# 查询 call graph
codeseek callers main
codeseek callees process_data
# 作为 MCP tools 注册到 Claude Code / Codex
codeseek install
# 检查状态
codeseek status
# 在 git commits 上自动索引
codeseek install-hooks
```
自然语言代码搜索示例
```
╰─$ codeseek search 'how the code embedding work'
1. get_embedding (0.7973)
/home/do/ssd/iohub/dev/codeseek/rust-core/src/services/embedding_service.rs:0
2. EmbeddingService (0.2855)
/home/do/ssd/iohub/dev/codeseek/rust-core/src/services/embedding_service.rs:0
3. EmbeddingData (0.1449)
/home/do/ssd/iohub/dev/codeseek/rust-core/src/services/embedding_service.rs:0
4. EmbeddingResponse (0.1304)
/home/do/ssd/iohub/dev/codeseek/rust-core/src/services/embedding_service.rs:0
5. default_model (0.0450)
/home/do/ssd/iohub/dev/codeseek/rust-core/src/config.rs:0
```
函数调用图示例
```
╰─$ codeseek callgraph apply_rerank
Call graph for 'apply_rerank' (depth=1):
== Callers (upstream, depth=1) ==
search (/home/do/ssd/iohub/dev/codeseek/rust-core/src/services/hybrid_search.rs:210)
== Callees (downstream, depth=1) ==
rerank (/home/do/ssd/iohub/dev/codeseek/rust-core/src/services/reranker_service.rs:331)
config (/home/do/ssd/iohub/dev/codeseek/rust-core/src/services/hybrid_search.rs:325)
```
## 安装
### npm
```
npm install -g codeseek
```
npm 包提供了一个轻量级的 JS 封装，负责处理以下内容：
| 步骤 | 描述 |
|------|-------------|
| **首次运行向导** | 通过交互式 CLI 提示输入 embedding API token、模型和 base URL |
| **二进制文件下载** | 自动从 GitHub Releases 拉取适用于你平台的正确 Rust 二进制文件 |
| **透传** | 将所有命令（`init`、`search`、`callers` 等）转发给原生二进制文件 |
支持的平台：
| 平台 | 架构 |
|----------|-------------|
| macOS | arm64 (Apple Silicon), x64 (Intel) |
| Linux | x64 |
### Homebrew
```
brew tap CodeBendKit/codeseek git@github.com:CodeBendKit/codeseek.git
brew install codeseek
```
### 从源码构建
```
# 安装 protoc
# macos: brew install protobuf
# ubuntu: sudo apt install protoc
git clone https://github.com/CodeBendKit/codeseek.git
cd codeseek
./build.sh --release
```
`build.sh` 会编译 TypeScript 封装（`dist/`）和 Rust 二进制文件，然后将其安装到 `~/.codeseek/bin/`。
## 命令
| 命令 | 描述 |
|---------|-------------|
| `codeseek` | 首次设置向导（交互式配置 embedding 模型） |
| `codeseek init` | 构建/更新代码索引（首次运行为全量构建，此后基于 MD5 增量更新） |
| `codeseek status` | 索引统计信息：函数、文件、上次更新时间 |
| `codeseek search ` | 符号名称搜索（依次回退：向量 → 图谱名称匹配） |
| `codeseek callers ` | 查找调用该符号的函数 |
| `codeseek callees ` | 查找该符号调用的函数 |
| `codeseek callgraph ` | 查询具有可配置深度（双向）的调用图 |
| `codeseek list` | 列出所有已索引的项目及其路径 |
| `codeseek install` | 在 Claude Code / Codex 中将 codeseek 注册为 MCP 工具 |
| `codeseek uninstall` | 移除 MCP 集成 |
| `codeseek uninit` | 删除当前项目的索引 |
| `codeseek install-hooks` | 安装 git hooks（post-commit/post-merge → `codeseek init`） |
| `codeseek serve --mcp` | 启动 MCP 服务器（stdio JSON-RPC，由 Claude Code 内部使用） |
所有查询命令均支持 `--json` 以获取机器可读的输出。
## Claude Code / Codex 集成
```
codeseek install
```
将 MCP 服务器配置写入：
| Agent | 配置文件 |
|-------|------------|
| **Claude Code** | `~/.claude.json`（全局，所有项目）或 `./.mcp.json`（项目本地） |
| **Codex CLI** | `~/.codex/config.toml` |
Claude Code 在重启后会自动发现这些工具：
| 工具 | 功能 |
|------|-----------|
| `codeseek_search` | 按名称查找符号 |
| `codeseek_callers` | 追踪上游调用者 |
| `codeseek_callees` | 追踪下游被调用者 |
| `codeseek_callgraph` | 查询具有可配置深度（双向）的调用图 |
| `codeseek_status` | 检查索引健康状况 |
移除集成：
```
codeseek uninstall
```
## 工作原理
### 索引构建 (`codeseek init`)
```
Source files
→ Tree-sitter AST parse (7 languages)
→ Extract functions / classes / methods
→ Batch embed via API (20 texts per call, SQLite cache)
→ Store vectors in LanceDB
→ Build BM25 index in Tantivy
→ Serialize call graph (PetCodeGraph)
→ Save to ~/.codeseek//
```
**幂等性**：首次运行为全量构建，后续运行会对比 MD5 哈希值 —— 仅对发生更改的文件进行重新处理。使用 `codeseek install-hooks` 可在 git commit/merge 时自动重新索引。
### 混合搜索管道 (`codeseek 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)
└─────────────────┘
```
| 阶段 | 技术 | 作用 | 速度 |
|-------|-----------|------|:-----:|
| **稠密搜索** | LanceDB + Embedding 模型 | 语义向量相似度 | 快速 |
| **稀疏搜索** | Tantivy BM25 | 关键词与 token 匹配 | 快速 |
| **RRF 融合** | Reciprocal Rank Fusion | 公平合并异构分数 | 瞬间 |
| **重排器** | Cross-Encoder (Qwen3-Reranker-4B) | 全交互精确度评分 | ~1-2秒 |
| **回退机制** | PetCodeGraph | 基于图谱的名称搜索（无需 API） | 瞬间 |
如果 embedding/重排器不可用，管道会优雅地回退到基于图谱的名称搜索。
### 存储
- **配置**: `~/.codeseek/config.json`（全局，所有项目共享）
- **索引**: `~/.codeseek//`
- `project.json` — 项目元数据
- `graph.bin` — 序列化的调用图
- `embeddings.lance/` — LanceDB 向量数据
- `tantivy_bm25/` — BM25 全文索引
- `file_hashes.json` — MD5 增量跟踪
没有 daemon，没有 HTTP 服务器。每个命令都是一个独立的进程。
## 支持的语言
| 语言 | 函数 | 结构体/类 | 调用图 |
|----------|:---------:|:---------------:|:----------:|
| Rust | ✅ | ✅ | ✅ |
| Python | ✅ | ✅ | ✅ |
| JavaScript | ✅ | ✅ | ✅ |
| TypeScript | ✅ | ✅ | ✅ |
| Go | ✅ | ✅ | ✅ |
| C/C++ | ✅ | ✅ | ✅ |
| Java | ✅ | ✅ | ✅ |
## 配置
`~/.codeseek/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": 20,
"vector_top_k": 20,
"rrf_k": 60,
"rrf_top_k": 20
},
"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` | 将代码转换为向量以进行稠密搜索 | 索引构建期间 |
| `Qwen/Qwen3-Reranker-4B` | 对（查询，代码）对进行精确度评分 | 搜索期间 |
在首次运行时通过交互式向导进行设置，或手动创建。
## 开发
```
cd rust-core
# 构建
cargo build
# 构建并安装到 ~/.codeseek/bin/
cd .. && ./build.sh --release
# 运行测试
cargo test
# 编译 TypeScript wrapper
npm run build
```
## 许可证
MIT
技术栈：Tree-sitter · Petgraph · LanceDB · Tantivy · Tokio · Clap
标签：AI编程助手, MCP, Rust, SOC Prime, 代码智能, 可视化界面, 开发工具, 网络流量审计, 语义搜索, 通知系统