# zxcodeindex

**Repository Path**: yysimple/zxcodeindex

## Basic Information

- **Project Name**: zxcodeindex
- **Description**: 强大的代码索引，让claude code有Cursor的codeindex功能
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-22
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zxcodeindex

GitNexus 的 Python 实现 - 面向 AI 代理的代码智能分析工具。

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## 功能特性

- **代码分析**: 使用 Tree-sitter 解析多种编程语言
- **知识图谱**: 构建代码库的完整依赖图谱
- **MCP 服务**: 通过 Model Context Protocol 向 AI 编辑器暴露查询能力
- **双后端**: LadybugDB（文件存储，默认）和 Neo4j（专业图数据库）
- **多语言支持**: Python、JavaScript/TypeScript、Java、Go、Rust、C/C++、C#、PHP、Ruby

## 快速开始

### 安装

```bash
# 从源码安装（开发模式）
git clone https://github.com/yourusername/zxcodeindex.git
cd zxcodeindex
pip install -e .

# 或从 PyPI 安装（发布后可用）
pip install zxcodeindex

# 使用 Neo4j 后端（可选）
pip install zxcodeindex neo4j
```

### 基础用法

```bash
# 1. 进入项目目录并索引代码
cd /path/to/your/project
zxcodeindex analyze

# 2. 搜索代码
zxcodeindex query "UserService"

# 3. 查看符号详情
zxcodeindex context UserService

# 4. 依赖分析（查看谁调用了 UserService）
zxcodeindex impact UserService --direction upstream
```

### MCP 配置（Claude Code）

```bash
claude mcp add zxcodeindex -- zxcodeindex mcp
```

配置完成后，在 Claude Code 中可以直接询问：
- "这个项目有哪些主要模块？"
- "UserService 有哪些方法被调用？"
- "修改 validateUser 会影响哪些地方？"

## 配置说明

### 数据库选择

| 特性 | LadybugDB（默认） | Neo4j |
|------|------------------|-------|
| 配置 | 无需配置 | 需要 Neo4j 服务器 |
| 存储 | 本地 JSON 文件 | Neo4j 数据库 |
| 适用 | 个人/小型项目 | 团队/大型项目 |
| 切换 | 默认 | 见下方配置 |

### 环境变量配置

创建 `.env` 文件：

```ini
# 使用 LadybugDB（默认，无需配置）
ZXCODEINDEX_DB_TYPE=ladybug

# 或使用 Neo4j
ZXCODEINDEX_DB_TYPE=neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password
```

### Neo4j 安装（可选）

**macOS:**
```bash
brew install neo4j
brew services start neo4j
```

**Docker:**
```bash
docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your_password \
  neo4j:latest
```

## CLI 命令

| 命令 | 说明 |
|------|------|
| `zxcodeindex analyze [path]` | 索引代码库 |
| `zxcodeindex list` | 列出已索引的仓库 |
| `zxcodeindex status` | 查看当前仓库状态 |
| `zxcodeindex query <keyword>` | 搜索代码 |
| `zxcodeindex context <symbol>` | 查看符号详情 |
| `zxcodeindex impact <symbol>` | 依赖影响分析 |
| `zxcodeindex cypher "<query>"` | 执行 Cypher 查询 |
| `zxcodeindex mcp` | 启动 MCP 服务 |

## Cypher 查询示例

查看所有类：
```cypher
MATCH (n:Class) RETURN n.name, n.file_path LIMIT 20
```

查看类的方法：
```cypher
MATCH (c:Class {name: 'UserService'})-[:CONTAINS]->(m:Method)
RETURN m.name ORDER BY m.start_line
```

查看调用关系：
```cypher
MATCH (c:Class)-[:CONTAINS]->(m:Method)-[:CALLS]->(target)
WHERE c.name = 'UserService'
RETURN m.name AS method, target.name AS target
```

## 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 格式化代码
black src tests
isort src tests
```

## 项目结构

```
zxcodeindex/
├── src/zxcodeindex/
│   ├── cli/          # 命令行接口
│   ├── core/         # 核心模块
│   │   ├── lbug/     # 图数据库适配器
│   │   ├── search.py # 搜索功能
│   │   └── ...
│   ├── mcp/          # MCP 服务
│   └── parser/       # 代码解析器
├── requirements.txt          # 基础依赖
├── requirements-neo4j.txt    # Neo4j 可选依赖
└── .env.example      # 配置示例
```

## 常见问题

**Q: 索引返回 0 个节点？**
A: 安装语言解析器：`pip install tree-sitter-python tree-sitter-java`

**Q: 如何切换到 Neo4j？**
A: 创建 `.env` 文件，设置 `ZXCODEINDEX_DB_TYPE=neo4j`，然后重新运行 `zxcodeindex analyze`

**Q: MCP 查询不到结果？**
A: 重启 Claude Code 刷新 MCP 服务，或在 Claude Code 中输入 `/restart`

## License

MIT License