内容
# CodeGraph：基于 Neo4j 的代码智能平台
[](https://golang.org)
[](https://neo4j.com)
[](LICENSE)
CodeGraph 是一个全面的代码智能平台，利用 Neo4j 作为后端，创建 **代码属性图（CPG）**。它超越了传统的抽象语法树（AST）表示，捕捉语义关系、控制流、数据流以及代码与业务需求之间的联系。
## 🎯 什么是 CodeGraph？
CodeGraph 将您的代码库转化为一个可查询的知识图谱，实现：
- **深入的代码理解**：超越语法的语义分析
- **跨服务分析**：微服务架构的统一视图
- **影响分析**：了解变更的影响范围
- **数据流跟踪**：追踪数据在系统中的流动
- **业务到代码的追溯性**：链接需求到实现
- **类似 LSP 的功能**：跳转到定义、查找引用、实现
## 🏗️ 架构
该平台由三个主要管道组成：
1. **静态索引管道**：使用 SCIP 协议对稳定代码库进行全面索引
2. **增量索引管道**：使用 tree-sitter（计划中）进行实时更新
3. **文档索引管道**：与业务文档和规范集成（计划中）
## 快速开始（单体仓库）
### 前提条件
- Go 1.24+
- Docker
- Node.js 20+（用于 Nx 任务运行器）
### 1. 初始化整个平台
```bash
./tools/scripts/bootstrap.sh
```
这将启动 Neo4j + Qdrant + OpenSearch 并构建 CLI。
### 2. 运行单元测试（无需基础设施）
```bash
go test ./pkg/... ./libs/... ./test/...
```
### 3. 使用 Nx 任务编排运行
```bash
# 仅构建和测试更改的内容
npx nx affected -t build,test
# 构建特定应用程序
npx nx run cli-go:build
# 运行所有集成测试
npx nx run-many -t integration
```
### 4. 在本地启动平台
```bash
docker compose -f infra/docker/compose.platform.yml up -d
./bin/codegraph status
```
---
## 🚀 快速开始
### 一键安装
使用以下命令安装 CodeGraph，并配置所有内容（CLI、Neo4j、MCP 服务器）：
```bash
curl -fsSL https://raw.githubusercontent.com/yourusername/context-maximiser/main/install.sh | bash
```
或下载并本地运行：
```bash
git clone <仓库网址>
cd context-maximiser
./install.sh
```
安装程序将：
- ✅ 检查前提条件（Go、Docker）
- ✅ 构建 CodeGraph CLI
- ✅ 启动 Neo4j 数据库并使用 Docker
- ✅ 创建默认配置（`~/.codegraph.yaml`）
- ✅ 构建并配置 MCP 服务器以支持 Claude Code
- ✅ 设置所有内容，以便您可以立即开始索引
**无需每次都指定 Neo4j 凭证** - 它们存储在 `~/.codegraph.yaml` 中！
#### 安装环境变量
使用以下环境变量自定义安装：
```bash
# 自定义安装目录（默认：~/.codegraph）
export CODEGRAPH_INSTALL_DIR="/opt/codegraph"
# 自定义二进制目录（默认：/usr/local/bin）
export CODEGRAPH_BIN_DIR="$HOME/bin"
# 自定义 Neo4j 密码（默认：password123）
export CODEGRAPH_NEO4J_PASSWORD="your-secure-password"
# 使用自定义设置运行安装程序
./install.sh
```
#### 安装程序执行的操作
1. **检查前提条件**：验证 Go 和 Docker 是否已安装
2. **请求许可**：在启动 Docker 守护进程或安装到系统目录之前
3. **构建所有内容**：CLI 和 MCP 服务器
4. **配置数据库**：启动 Neo4j 并创建模式
5. **创建配置**：`~/.codegraph.yaml`，包含凭证（无需再次指定！）
6. **设置 MCP**：将 CodeGraph 自动添加到 Claude Code
---
### 手动安装
如果您更喜欢手动安装或需要更多控制：
#### 前提条件
- Go 1.24 或更高版本
- Docker 和 Docker Compose
- Git
- 语言特定的 SCIP 索引器（参见[支持的语言](#支持的语言)）
#### 1. 克隆和设置
```bash
git clone <仓库网址>
cd context-maximiser
# 安装 Go 依赖项
make install-deps
```
### 支持的语言
CodeGraph 通过 SCIP（源代码智能协议）索引器支持多种编程语言：
| 语言 | SCIP 索引器 | 安装 |
|----------|--------------|--------------|
| **Go** | [scip-go](https://github.com/sourcegraph/scip-go) | `go install github.com/sourcegraph/scip-go/cmd/scip-go@latest` |
| **TypeScript** | [scip-typescript](https://github.com/sourcegraph/scip-typescript) | `npm install -g @sourcegraph/scip-typescript` |
| **JavaScript** | [scip-typescript](https://github.com/sourcegraph/scip-typescript) | `npm install -g @sourcegraph/scip-typescript` |
| **Python** | [scip-python](https://github.com/sourcegraph/scip-python) | `pip install scip-python` |
| **Java/Scala/Kotlin** | [scip-java](https://sourcegraph.github.io/scip-java/) | 参见构建工具集成文档 |
#### 2. 启动 Neo4j 数据库
```bash
# 使用 Docker Compose 启动 Neo4j
make docker-up
# 等待 Neo4j 准备就绪（约 30 秒）
# Neo4j 将在 http://localhost:7474 上可用
# 用户名：neo4j，密码：password123
```
#### 3. 初始化数据库模式
```bash
# 创建所需的约束和索引
make neo4j-schema
# 验证模式创建
make neo4j-schema-info
```
#### 4. 索引您的第一个项目
```bash
# 索引此 Go 项目本身（自己测试！）
make index-self-scip
# 或索引任何具有自动检测的项目
./bin/codegraph index scip /path/to/your/project --service="my-service"
# 显式指定语言
./bin/codegraph index scip /path/to/typescript/project --language=typescript --service="frontend"
# 索引 Python 项目
./bin/codegraph index scip /path/to/python/project --language=python --service="ml-service"
```
#### 5. 查询图谱
```bash
# 搜索符号
go run ./cmd/codegraph query search "Client"
# 检查连接状态
go run ./cmd/codegraph status
```
## 📋 详细设置
### 手动设置步骤
1. **启动 Neo4j**：
```bash
docker-compose up -d
```
2. **构建 CLI**：
```bash
make build
```
3. **创建模式**：
```bash
./bin/codegraph schema create
```
4. **索引项目**：
```bash
./bin/codegraph index project . --service="my-service" --version="v1.0.0"
```
### 配置
为自定义配置创建 `~/.codegraph.yaml`：
```yaml
neo4j:
uri: "bolt://localhost:7687"
username: "neo4j"
password: "password123"
database: "neo4j"
verbose: false
```
## 🔍 使用示例
### CLI 命令
#### 数据库管理
```bash
# 检查 Neo4j 连接
codegraph status
# 创建/删除模式
codegraph schema create
codegraph schema drop
codegraph schema info
```
#### 代码索引
CodeGraph 自动检测项目语言或您可以显式指定：
```bash
# 索引并自动检测（推荐）
codegraph index scip ./my-project --service="order-service" --version="v2.1.0"
# 索引 TypeScript/JavaScript 项目
codegraph index scip ./frontend --language=typescript --service="web-app"
# 索引 Python 项目
codegraph index scip ./ml-service --language=python --service="ml-api"
# 显式索引 Go 项目
codegraph index scip . --language=go --service="api-gateway" --repo-url="https://github.com/company/api-gateway"
# 基于 AST 的索引（仅限 Go，旧版）
codegraph index project ./my-go-project --service="legacy-service"
```
#### 查询
```bash
# 搜索符号
codegraph query search "OrderService"
codegraph query search "calculateTotal"
# 高级查询（计划中）
codegraph query impact-analysis --function="processPayment"
codegraph query dependencies --service="order-service"
```
### 程序化使用
```go
package main
import (
"context"
"log"
"github.com/context-maximiser/code-graph/pkg/neo4j"
"github.com/context-maximiser/code-graph/pkg/query"
)
func main() {
// 创建 Neo4j 客户端
client, err := neo4j.NewClient(neo4j.Config{
URI: "bolt://localhost:7687",
Username: "neo4j",
Password: "password123",
Database: "neo4j",
})
if err != nil {
log.Fatal(err)
}
defer client.Close(context.Background())
// 创建 LSP 服务
lsp := query.NewLSPService(client)
// 查找符号定义
resp, err := lsp.GoToDefinition(context.Background(), query.GoToDefinitionRequest{
Symbol: "scip-go go github.com/context-maximiser/code-graph v1.0.0 pkg/neo4j/Client#",
})
if err != nil {
log.Fatal(err)
}
if resp.Found {
log.Printf("在 %s:%d 处找到定义",
resp.Definition.FilePath, resp.Definition.StartLine)
}
}
```
## 🔌 MCP 服务器
CodeGraph 提供了一个模型上下文协议（MCP）服务器，为 Claude Code 等 AI 助手提供代码智能工具。
### 与 Claude Code 集成
使用 `claude mcp add` 命令将 MCP 服务器添加到 Claude Code：
```bash
claude mcp add codegraph /Users/techsavvyash/Documents/sweatAndBlood/sabbatical/context-maximiser/mcp-server/codegraph-mcp NEO4J_URI=bolt://localhost:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=password123
```
用您的实际 CodeGraph 安装目录替换路径。
### 可用的 MCP 工具
MCP 服务器为 AI 助手提供以下工具：
**代码智能：**
- `codegraph_search` - 在代码库中搜索符号
- `codegraph_get_source` - 获取具有语法高亮的函数源代码
- `codegraph_analyze_function` - 分析具有调用者、被调用者和复杂度的函数
**文档智能：**
- `codegraph_index_documents` - 索引文档并链接到代码
- `codegraph_show_document` - 显示具有链接代码的文档内容
- `codegraph_link_features` - 使用 LLMs 将功能描述链接到代码
**服务架构：**
- `codegraph_list_services` - 列出所有服务及其元数据
- `codegraph_service_dependencies` - 显示服务依赖项（DEPENDS_ON）
- `codegraph_service_api_endpoints` - 列出服务暴露的 API 端点
- `codegraph_service_api_calls` - 显示服务发出的 API 调用
- `codegraph_cross_service_calls` - 查找服务之间的调用链
- `codegraph_service_architecture` - 具有依赖关系图的完整架构概览
### 构建 MCP 服务器
```bash
cd mcp-server
go build -o codegraph-mcp .
```
## 🗄️ 图谱模式
Neo4j 数据库使用基于代码属性图模型的丰富模式：
### 节点类型
- **服务**：微服务或应用程序组件
- **文件**：源代码文件
- **模块**：包/命名空间/模块
- **类/接口**：面向对象构造
- **函数/方法**：可执行代码单元
- **变量/参数**：数据容器
- **符号**：使用 SCIP 格式的规范定义
- **API 路由**：网络端点
- **文档**：业务/技术文档（计划中）
- **功能**：需求/功能（计划中）
### 关系类型
- **CONTAINS**：结构层次（类似 AST）
- **CALLS**：函数/方法调用
- **DEFINES/REFERENCES**：符号定义和用法
- **INHERITS_FROM/IMPLEMENTS**：OOP 关系
- **FLOWS_TO**：数据依赖（计划中）
- **NEXT_EXECUTION**：控制流（计划中）
- **EXPOSES_API**：API 端点处理程序（计划中）
### 示例查询
#### 查找服务中的所有函数：
```cypher
MATCH (s:Service {name: 'order-service'})-[:CONTAINS*]->(f:Function)
RETURN f.name, f.signature, f.filePath
```
#### 查找函数更改的 API 影响：
```cypher
MATCH (f:Function {name: 'calculateDiscount'})
MATCH (f)-[:CALLS*1..10]->(downstream:Function)
MATCH (downstream)-[:EXPOSES_API]->(route:APIRoute)
RETURN DISTINCT route.method, route.path
```
#### 查找函数的所有调用者：
```cypher
MATCH (caller)-[:CALLS]->(f:Function {name: 'validatePayment'})
RETURN caller.name, caller.filePath, caller.startLine
```
## 🛠️ 开发
### Makefile 目标
```bash
# 开发设置
make dev-setup # 完整的开发环境设置
make dev # 构建并索引当前项目
make dev-teardown # 清理开发环境
# 构建
make build # 构建 CLI
make build-server # 构建 API 服务器（计划中）
# 测试
make test # 运行单元测试
make test-integration # 运行集成测试
make test-coverage # 生成覆盖率报告
# 数据库操作
make docker-up # 启动 Neo4j
make docker-down # 停止 Neo4j
make docker-clean # 清理容器和卷
make db-reset # 完全重置数据库
# 代码质量
make lint # 运行 linter
make format # 格式化代码
```
### 项目结构
```
context-maximiser/
├── cmd/
│ └── codegraph/ # CLI 应用程序
├── pkg/
│ ├── models/ # 图数据模型
│ ├── neo4j/ # Neo4j 客户端和查询
│ ├── schema/ # 模式管理
│ ├── indexer/
│ │ └── static/ # Go AST 索引器
│ └── query/ # 查询服务（LSP，高级）
├── docs/
│ ├── rfc/ # 技术 RFC
│ ├── architecture/ # 架构文档
│ └── schema/ # 模式文档
├── test/
│ └── integration/ # 集成测试
├── docker-compose.yml # Neo4j 设置
└── Makefile # 开发命令
```
### 添加新功能
1. **新节点类型**：添加到 `pkg/models/node.go`
2. **新关系**：添加到 `pkg/models/relationship.go`
3. **模式更改**：更新 `pkg/schema/schema.go`
4. **索引逻辑**：扩展 `pkg/indexer/static/indexer.go`
5. **查询模式**：添加到 `pkg/query/` 服务
## 🔧 配置
### 环境变量
- `DEBUG=true` - 启用调试日志
- `NEO4J_URI` - Neo4j 连接 URI
- `NEO4J_USERNAME` - Neo4j 用户名
- `NEO4J_PASSWORD` - Neo4j 密码
- `NEO4J_DATABASE` - Neo4j 数据库名称
### CLI 标志
- `--verbose, -v` - 详细输出
- `--neo4j-uri` - Neo4j 连接 URI
- `--neo4j-user` - Neo4j 用户名
- `--neo4j-password` - Neo4j 密码
- `--config` - 自定义配置文件路径
## 📊 监控和性能
### 数据库性能
- 使用批处理操作（UNWIND + MERGE）进行高效写入
- 全面的索引策略以实现快速读取
- 连接池以实现并发访问
- 查询结果缓存（计划中）
### 监控查询
```cypher
// 检查按类型分组的节点数量
MATCH (n) RETURN labels(n), count(n)
// 检查关系数量
MATCH ()-[r]->() RETURN type(r), count(r)
// 查找昂贵的查询
CALL dbms.listQueries() YIELD query, elapsedTimeMillis
WHERE elapsedTimeMillis > 1000
RETURN query, elapsedTimeMillis
```
## 🤖 LLM 提供商支持
CodeGraph 支持多个 LLM 提供商，用于语义功能到代码的链接：
### 支持的提供商
- **LiteLLM**（推荐）- 100 多种模型的统一代理
- **Google Gemini** - 直接的 Google Gemini API 集成
- **OpenAI** - 直接的 OpenAI API 集成
### 快速设置
```bash
# 使用 LiteLLM（访问 100 多种模型）
export LLM_PROVIDER="litellm"
export LLM_BASE_URL="http://localhost:4000"
export LLM_API_KEY="sk-1234"
export LLM_TEXT_MODEL="openai/gpt-4"
export LLM_EMBEDDING_MODEL="openai/text-embedding-3-small"
# 使用 Gemini（向后兼容）
export GEMINI_API_KEY="your-key"
./bin/codegraph link features --gemini
# 直接使用 OpenAI
export LLM_PROVIDER="openai"
export LLM_API_KEY="sk-..."
export LLM_BASE_URL="https://api.openai.com/v1"
```
📖 **参见 [LLM 提供商迁移指南](docs/LLM_PROVIDER_MIGRATION.md) 了解详细设置**
---
## 🚧 路线图
### 第一阶段（当前）
- ✅ Neo4j 集成和模式
- ✅ Go AST 索引
- ✅ 基本 CLI 接口
- ✅ LSP 类似查询
- ✅ LLM 提供商抽象（Gemini，LiteLLM，OpenAI）
- ✅ RFC-002 语义功能链接
- 🔄 高级查询模式
### 第二阶段（下一个）
- [ ] 使用 tree-sitter 进行增量索引
- [ ] 具有 REST/GraphQL 端点的 API 服务器
- [ ] 图形可视化的 Web UI
- [ ] 支持其他语言（Java，Python，TypeScript）
### 第三阶段（未来）
- [ ] 文档索引和分析
- [ ] 功能到代码的追溯性
- [ ] 实时协作功能
- [ ] IDE 插件和集成
- [ ] CI/CD 管道集成
- [ ] 机器学习驱动的洞察
## 🤝 贡献
1. 复刻仓库
2. 创建功能分支：`git checkout -b feature/amazing-feature`
3. 进行更改并添加测试
4. 运行测试套件：`make test`
5. 提交拉取请求
### 开发指南
- 遵循 Go 最佳实践和惯例
- 为新功能编写全面测试
- 为用户可见的更改更新文档
- 使用约定提交消息
- 确保所有 CI 检查通过
## 📝 许可证
该项目在 MIT 许可证下获得许可 - 有关详细信息，请参见 [LICENSE](LICENSE) 文件。
## 🗑️ 卸载
要从系统中完全删除 CodeGraph：
```bash
# 运行卸载脚本
./uninstall.sh
# 或使用 curl（如果可用在线）
curl -fsSL https://raw.githubusercontent.com/yourusername/context-maximiser/main/uninstall.sh | bash
```
卸载程序将：
- 停止并删除 Neo4j Docker 容器
- 删除 CodeGraph 安装目录
- 删除 CLI 二进制文件
- 从 Claude Code 中删除 MCP 服务器
- 可选地删除配置文件
## 🆘 支持
- **问题**：[GitHub 问题](https://github.com/context-maximiser/code-graph/issues)
- **讨论**：[GitHub 讨论](https://github.com/context-maximiser/code-graph/discussions)
- **文档**：参见 `docs/` 目录
## 🙏 致谢
- **Neo4j** 提供强大的图数据库
- **SCIP 协议** 提供标准化的代码智能
- **Tree-sitter** 提供增量解析
- **Sourcegraph** 提供代码智能灵感
- **Go 团队** 提供优秀的 AST 库
---
**快乐的代码图谱绘制！ 🚀**
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器