内容
<p align="center">
<img src="docs/banner.svg" alt="codegraph" width="100%"/>
</p>
<p align="center">
<a href="https://github.com/isink17/codegraph/releases/latest"><img src="https://img.shields.io/github/v/release/isink17/codegraph?color=00ff88&style=flat-square&label=release" alt="最新版本"/></a>
<a href="https://pkg.go.dev/github.com/isink17/codegraph"><img src="https://img.shields.io/badge/go-1.23+-00d4ff?style=flat-square&logo=go&logoColor=white" alt="Go 版本"/></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-FSL--1.1--MIT-ffaa44?style=flat-square" alt="许可证"/></a>
<img src="https://img.shields.io/badge/platforms-Linux%20%7C%20macOS%20%7C%20Windows-8899aa?style=flat-square" alt="支持平台"/>
<img src="https://img.shields.io/badge/MCP%20tools-29-00ff88?style=flat-square" alt="MCP 工具"/>
</p>
<br/>
`codegraph` 是一个**本地优先的代码上下文引擎和 MCP 服务器**，它在 SQLite 中为您的源代码仓库构建了一个持久的知识图谱。它为 AI 编程助手提供了深入的结构感知能力，包括符号、调用图、依赖关系和语义搜索，而无需向云端发送任何字节。
**单个二进制文件。零配置。无需外部数据库。无需 API 密钥。**
---
## 为什么使用 codegraph？
AI 编程助手非常强大，但它们大部分时间都花在**发现**要修改的内容上——grep 文件、阅读代码、从部分证据中重建调用图。
**codegraph 转移了这一成本。** 一次调用 `context_for_task` 即可返回智能体需要的确切文件、符号和关系。一次调用 `agentic_query` 即可获得由图遍历和语义搜索支持的综合答案。
```
❌ 没有 codegraph
AI 读取文件 → grep 模式 → 在上下文收集上消耗令牌
✅ 使用 codegraph
AI 调用 context_for_task("为 HTTP 客户端添加重试逻辑")
→ 立即获取相关文件、函数、调用者、被调用者和测试
```
---
## 工作原理
```
您的代码 ──▶ tree-sitter AST ──▶ SQLite 图 ──▶ MCP 工具 ──▶ AI 助手
│ │ │
12 种语言 符号、边 29 种工具
框架检测 嵌入式 智能推理
导入解析 会话内存 混合搜索
```
`codegraph index .` 会遍历您的仓库，使用 tree-sitter 解析每个文件，使用四种策略（精确、名称、后缀、方法接收器）解析导入，并将完全链接的符号图写入本地 `codegraph.sqlite`。然后，MCP 服务器通过 29 种结构化工具向任何兼容的 AI 助手公开该图，无需云端、无需 Docker、无需 API 密钥。
---
## 功能
### 🔍 解析和索引
- **tree-sitter 解析**，适用于所有 12 种支持的语言——强大的 AST 提取，而不是正则表达式
- **4 种策略导入解析**——精确、名称、后缀和方法接收器匹配
- **跨语言链接**——连接语言边界上的符号
- **增量更新**——仅重新索引更改的文件；在大型仓库中速度快
- **框架检测**——识别 20 多种框架（Express、Django、gin、React、Spring、Laravel 等）
### 🔎 搜索和查询
- **混合搜索**——向量相似性（Ollama 嵌入）+ FTS5，融合互惠排名融合
- **语义搜索**——按含义查找代码，而不仅仅是文本
- **调用图遍历**——调用者、被调用者、传递依赖链
- **影响分析**——在更改之前了解会发生什么
- **死代码检测**——查找具有零引用的符号
- **架构概览**——语言分解、入口点、中心符号、耦合指标
### 🤖 AI 集成
- **29 种 MCP 工具**——适用于 AI 编程助手的综合 API
- **智能推理**——在本地 Ollama LLM 上进行 ReAct 循环，链接工具并合成答案
- **上下文构建**——一次工具调用返回智能体任务所需的一切
- **会话内存**——在会话之间持久化读取、编辑、决策和事实
- **令牌基准测试**——衡量与天真文件读取相比的节省
### 📊 图分析
- **PageRank**——在您的代码库中找到最重要的符号
- **耦合指标**——识别紧密耦合的文件对
- **循环检测**——在文件级别找到循环依赖
- **交互式可视化**——带有搜索和缩放的 D3.js 力导向图
### 🛠 开发人员体验
- **单个 Go 二进制文件**——无运行时依赖，跨平台
- **零配置 SQLite**——无需 Docker，无需外部数据库
- **`codegraph install`**——自动检测和配置 Claude Code、Cursor、Windsurf、Gemini CLI
- **文件监视**——文件更改时自动重新索引
- **100% 本地**——无数据离开您的机器
---
## 支持的语言
所有语言都使用 tree-sitter 进行 AST 解析：
| 语言 | 扩展名 |
|---|---|
| Go | `.go` |
| Python | `.py` |
| TypeScript | `.ts`, `.tsx` |
| JavaScript | `.js`, `.jsx`, `.mjs` |
| Java | `.java` |
| Kotlin | `.kt`, `.kts` |
| Rust | `.rs` |
| C# | `.cs` |
| Ruby | `.rb` |
| Swift | `.swift` |
| PHP | `.php` |
| C / C++ | `.c`, `.h`, `.cpp`, `.hpp`, `.cc` |
> Node.js 仓库受支持；完整的 tree-sitter 节点支持仍在进行中。
---
## 快速入门
### 1. 安装
```bash
go install github.com/isink17/codegraph/cmd/codegraph@latest
```
需要 Go 1.23+ 和 C 编译器（用于 tree-sitter CGo 绑定）。
### 从源代码构建
```bash
git clone https://github.com/isink17/codegraph
cd codegraph
go build ./cmd/codegraph
go test ./...
```
需要 Go 1.23+ 和 C 编译器（用于 tree-sitter CGo 绑定）。
#### 清洁重建
```bash
cd your-project
codegraph index . --rebuild
```
在需要从头开始进行完整重新索引时使用此命令。
`codegraph index . --rebuild` 需要对仓库数据库的独家访问权限。
如果重建失败，因为数据库正在使用中，请停止 `codegraph serve` 或其他 `codegraph` 进程并重试。
使用 `codegraph clean .` 进行数据库维护任务，如 WAL 检查点、VACUUM、FTS 优化、分析 和 增量真空。
### 版本
```bash
codegraph --version
codegraph version
```
仅打印已安装的本地版本。不与 GitHub 联系。
### 2. 自动配置您的 AI 工具
```bash
codegraph install
```
检测 Claude Code、Cursor、Windsurf 和 Gemini CLI 并自动写入 MCP 配置。
### 3. 索引您的项目
```bash
cd your-project
codegraph index .
```
### 4. 启动 MCP 服务器
```bash
codegraph serve
```
仓库根目录从 git 自动检测（或回落到当前工作目录）。
就这样。您的 AI 助手现在对代码具有深入的结构理解。
---
## MCP 设置
### 自动配置（推荐）
```bash
codegraph install
```
### 手动设置
<details>
<summary><strong>Claude Code</strong> — 添加到 <code>.mcp.json</code></summary>
```json
{
"mcpServers": {
"codegraph": {
"command": "codegraph",
"args": ["serve"]
}
}
}
```
</details>
<details>
<summary><strong>Cursor / Windsurf</strong> — 添加到 <code>mcp.json</code></summary>
```json
{
"mcpServers": {
"codegraph": {
"command": "codegraph",
"args": ["serve"]
}
}
}
```
</details>
<details>
<summary><strong>Codex</strong> — 添加到 <code>config.toml</code></summary>
```toml
[mcp_servers.codegraph]
command = "codegraph"
args = ["serve"]
startup_timeout_sec = 60
```
</details>
参阅 [`examples/`](examples/) 目录以获取更多配置示例。
---
## MCP 工具（29 个）
### 代码智能
| 工具 | 描述 |
|---|---|
| `find_symbol` | 按精确或模糊查询查找符号 |
| `search_symbols` | 搜索符号名称、签名和文档（FTS5） |
| `search_semantic` | 混合语义搜索（启用嵌入时为向量 + FTS） |
| `find_callers` | 查找调用给定函数的内容 |
| `find_callees` | 查找给定函数调用的内容 |
| `get_impact_radius` | 估计更改周围的影响符号和文件 |
| `trace_dependencies` | 跟踪传递依赖链（上游/下游） |
| `find_related_tests` | 为符号、文件或一组更改的文件查找测试 |
| `find_dead_code` | 查找没有调用者或引用的符号 |
| `context_for_task` | 为自然语言任务构建聚焦的上下文包 |
### 架构和分析
| 工具 | 描述 |
|---|---|
| `architecture_overview` | 语言分解、目录、入口点、中心符号 |
| `graph_analytics` | PageRank、耦合度量或循环检测 |
| `detect_frameworks` | 检测仓库中使用的框架和库 |
| `cross_language_links` | 查找和创建跨语言符号引用 |
| `benchmark_tokens` | 估计令牌节省与读取原始文件 |
### 仓库管理
| 工具 | 描述 |
|---|---|
| `index_repo` | 将仓库索引到本地代码图 |
| `update_graph` | 仅更新更改的文件 |
| `list_files` | 列出索引文件并带有可选路径过滤器 |
| `graph_stats` | 仓库图统计 |
| `supported_languages` | 列出支持的语言和扩展名 |
| `list_repos` | 列出已知仓库 |
| `list_scans` | 列出最近的扫描 |
| `latest_scan_errors` | 列出最后一次扫描的索引错误 |
### 会话内存
| 工具 | 描述 |
|---|---|
| `session_log` | 记录会话事件（读取、编辑、决策、任务、事实） |
| `session_history` | 获取会话事件历史 |
| `session_hot_files` | 获取最频繁访问的文件 |
| `session_context` | 获取用于预加载的聚合会话上下文 |
### 智能体
| 工具 | 描述 |
|---|---|
| `agentic_query` | 询问由本地 AI 智能体回答的问题，该智能体推理代码图（需要 Ollama） |
---
## CLI 参考
```bash
# 设置
codegraph install # 自动配置 AI 工具
codegraph doctor # 检查安装健康状况
codegraph config show # 显示当前配置
codegraph --version # 打印当前版本
codegraph version # 打印当前版本
# 索引
codegraph index <path> # 完整索引
codegraph update <path> # 增量更新
codegraph watch <path> # 监视和自动重新索引
codegraph clean <path> # 清洁数据库
# MCP 服务器
codegraph serve [--repo-root <path>] # 启动 MCP 服务器（自动检测仓库根目录）
# 查询
codegraph stats <path> # 图表统计
codegraph find-symbol <path> <query> # 查找符号
codegraph search <path> <query> # 全文符号搜索
codegraph callers <path> --symbol <name> # 查找调用者
codegraph callees <path> --symbol <name> # 查找被调用者
codegraph impact <path> --symbol <name> # 影响分析
# 测试
codegraph affected-tests [--stdin] <files> # 受更改文件影响的测试
# 可视化和导出
codegraph visualize [--repo-root <path>] # 交互式 D3.js 图表（自动检测仓库根目录）
codegraph graph export <path> --format dot # 以 Graphviz DOT 导出
codegraph graph export <path> --format json # 以 JSON 导出
# 基准测试
codegraph benchmark # 令牌节省基准测试
```
### 受 Git 影响的测试
```bash
# 查找未提交更改影响的测试
git diff --name-only | codegraph affected-tests --stdin
# CI 集成
TESTS=$(git diff --name-only HEAD~1 | codegraph affected-tests --stdin)
go test $TESTS
```
将 `--repo-root .` 替换为空字符串，如果您已经在要检查的仓库中。
---
## 可选：嵌入和智能体模式
codegraph 完全无需外部服务即可运行。启用这些功能以获得增强功能：
### 向量嵌入（通过 Ollama）
启用混合语义搜索（向量 + FTS）：
```bash
# 安装并拉取嵌入模型
ollama pull nomic-embed-text
# 初始化仓库配置
codegraph config init --repo .
```
编辑 `.codegraph/config.json`:
```json
{
"embedding": {
"enabled": true,
"model": "nomic-embed-text"
}
}
```
然后重新索引以生成嵌入：
```bash
codegraph index . --force
```
### 智能体推理（通过 Ollama）
`agentic_query` 工具使用本地 LLM 在图上进行 ReAct 循环推理：
```bash
ollama pull llama3.2
```
编辑 `.codegraph/config.json`:
```json
{
"agent": {
"enabled": true,
"model": "llama3.2"
}
}
```
---
## 配置
### 全局配置
| 平台 | 路径 |
|---|---|
| macOS | `~/Library/Application Support/codegraph/config.json` |
| Linux | `${XDG_CONFIG_HOME:-~/.config}/codegraph/config.json` |
| Windows | `%AppData%\codegraph\config.json` |
### 仓库配置
使用 `codegraph config init --repo .` 在 `.codegraph/config.json` 处创建：
```json
{
"include": [],
"exclude": ["vendor/**", "node_modules/**"],
"languages": [],
"embedding": {
"enabled": false,
"model": "nomic-embed-text"
},
"agent": {
"enabled": false,
"model": "llama3.2"
}
}
```
### 仓库根目录解析
当省略 `--repo-root`（CLI）或 `repo_root`（MCP 工具参数）时，codegraph 使用以下方法解析仓库根目录：
1. 调用 `repo_root` 的 MCP 工具参数
2. `--repo-root` CLI 标志（进程级默认值）
3. `git rev-parse --show-toplevel` 从当前工作目录
4. `os.Getwd()`（当前工作目录）
5. 返回错误
### 忽略文件
在仓库根目录创建 `.codegraphignore`（语法与 `.gitignore` 相同）：
```
build/
dist/
*.generated.go
```
> **注意：** 常见生成目录（`node_modules`、`.next`、`.nuxt` 等）始终被跳过且无法取消忽略。
---
## 架构
```
cmd/codegraph CLI 入口点
internal/
agent/ 智能体推理（Ollama 的 ReAct 循环）
cli/ 命令处理程序和 MCP 自动配置
config/ 配置加载和路径解析
embedding/ 向量嵌入（Ollama HTTP 客户端）
export/ JSON 和 DOT 图表导出
framework/ 框架检测（20 多个框架）
graph/ 核心类型（Symbol、Edge、Reference、…）
indexer/ 仓库扫描、增量更新、嵌入
mcp/ MCP 标准输入/输出服务器（29 种工具）
parser/ 解析器接口和适配器
treesitter/ Tree-sitter 适配器（12 种语言）
golang/ Go AST 解析器（旧版）
python/ Python 启发式解析器（旧版）
heuristic/ 正则表达式解析器（旧版备用）
query/ 查询编排和混合搜索
store/ SQLite 存储、迁移、图表分析
viz/ 交互式 D3.js 图表可视化
watcher/ 文件监视和延迟更新
```
---
## 从源代码构建
```bash
git clone https://github.com/isink17/codegraph
cd codegraph
go build ./cmd/codegraph
go test ./...
```
需要 Go 1.23+ 和 C 编译器用于 tree-sitter CGo 绑定。
进行干净的重建：
```bash
codegraph index . --rebuild
```
此重建路径需要对仓库数据库的独家访问权限。如果它失败，因为另一个 `codegraph` 进程持有数据库，请停止该进程并重试。
---
## 许可证
该项目根据 **功能源许可证，版本 1.1，MIT 未来许可证** (`FSL-1.1-MIT`) 授权。
在每个版本的发布日期的第二周年，该版本转换为 MIT 许可证。有关完整条款，请参阅 [`LICENSE`](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器