## 项目概述

CodeGraph 是一个为 AI 编程代理（如 Claude Code、Cursor、Codex、Gemini 等）提供预索引代码知识图谱的工具。它通过 Rust 内核解析代码，构建包含符号、调用边和依赖关系的知识图谱，并自动同步代码变更，使代理能够通过一次工具调用获取精确的代码上下文，从而减少 token 消耗和工具调用次数，且完全在本地运行。

## 核心功能

- **预索引代码知识图谱**：解析代码结构，构建符号、调用边和依赖关系图。
- **自动同步**：通过文件监听器自动更新索引，无需手动重新运行。
- **精准上下文**：一次工具调用返回相关符号、调用路径和影响范围。
- **多语言支持**：支持 TypeScript、Python、Go、Rust、Java 等 20+ 种语言。
- **框架感知路由**：识别 Django、Flask、Express 等 17 种 Web 框架的路由。
- **跨语言桥接**：支持 Swift ↔ Objective-C、React Native 等混合代码库。
- **100% 本地**：所有数据存储在本地 SQLite 数据库中，无外部服务。

## 适用与不适用场景

**适用场景：**
- 大型代码库的架构理解与代码搜索。
- AI 编程代理需要快速获取代码上下文以减少 token 消耗。
- 需要跨文件追踪调用链和影响分析的开发场景。

**不适用场景：**
- 小型项目（文件数少）可能无法体现性能优势。
- 需要实时动态分析（如反射、动态分发）的代码。
- 对隐私要求极高，不允许任何本地索引的场景。

## 技术架构与依赖

- **核心引擎**：Rust 编写的解析内核，使用 tree-sitter 语法解析。
- **存储**：本地 SQLite 数据库（`.codegraph/codegraph.db`），支持 FTS5 全文搜索。
- **运行时**：自带 Node.js 运行时，无需额外安装。
- **依赖**：无外部服务，无 API 密钥。

## 安装与快速开始

```bash
# 安装 CLI（无需 Node.js）
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# 或使用 npm
npm i -g @colbymchenry/codegraph

# 连接 AI 代理
codegraph install

# 初始化项目并构建索引
cd your-project
codegraph init
```

## 典型使用方法

```bash
# 搜索符号
codegraph query "UserService"

# 探索相关代码
codegraph explore "How does a request reach the database?"

# 查看调用者/被调用者
codegraph callers "UserService.getUser"
codegraph callees "UserService.getUser"

# 影响分析
codegraph impact "UserService"

# 查找受影响的测试文件
codegraph affected src/utils.ts
```

## 配置与部署要点

- **零配置**：默认无需配置，自动识别语言和排除目录。
- **自定义扩展名**：通过 `codegraph.json` 映射非标准文件扩展名。
- **排除/包含目录**：通过 `codegraph.json` 的 `exclude` 和 `include` 字段控制。
- **环境变量**：如 `CODEGRAPH_WATCH_DEBOUNCE_MS` 调整监听延迟，`CODEGRAPH_NO_DAEMON=1` 禁用后台守护进程。
- **部署**：支持 Windows、macOS、Linux 的 x64 和 arm64 架构。

## 限制、风险与许可证

- **限制**：静态分析无法覆盖所有动态行为（如反射、动态分发）。
- **风险**：索引可能因代码变更而漂移，需定期重建（`codegraph index`）。
- **许可证**：MIT。

## 官方链接

- [GitHub 仓库](https://github.com/colbymchenry/codegraph)
- [文档与网站](https://colbymchenry.github.io/codegraph/)
- [npm 包](https://www.npmjs.com/package/@colbymchenry/codegraph)

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、文档、基准测试报告。
- 分析时间：2026-08-06。