wehub-resource-sync
846 lines
58 KiB
Markdown
846 lines
58 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/colbymchenry/codegraph) · [上游 README](https://github.com/colbymchenry/codegraph/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<div align="center">
|
||
|
||
# CodeGraph
|
||
|
||
## 🎉 1.0 已发布！
|
||
|
||
已安装？运行 `codegraph upgrade`
|
||
|
||
在 X 上关注 [@getcodegraph](https://x.com/getcodegraph) 获取更新。
|
||
|
||
### 用语义代码智能增强 Claude Code、Cursor、Codex、OpenCode、Hermes Agent、Gemini、Antigravity 和 Kiro
|
||
|
||
**精准上下文 · 更少的工具调用 · 更快的回答 · 100% 本地运行**
|
||
|
||
### [文档与网站 →](https://colbymchenry.github.io/codegraph/)
|
||
|
||
[](https://www.npmjs.com/package/@colbymchenry/codegraph)
|
||
[](https://opensource.org/licenses/MIT)
|
||
[](https://nodejs.org/)
|
||
|
||
[](#supported-platforms)
|
||
[](#supported-platforms)
|
||
[](#supported-platforms)
|
||
|
||
[](#supported-agents)
|
||
[](#supported-agents)
|
||
[](#supported-agents)
|
||
[](#supported-agents)
|
||
[](#supported-agents)
|
||
[](#supported-agents)
|
||
[](#supported-agents)
|
||
[](#supported-agents)
|
||
|
||
<br>
|
||
|
||
**CodeGraph 平台即将到来** —— 对于每个 PR，精确了解要测试什么、什么可能出错、哪些流程受影响、以及业务逻辑是否被破坏。
|
||
|
||
<a href="https://getcodegraph.com"><img alt="加入早期 Beta 访问等候名单" src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/waitlist.svg?v=2" height="52"></a>
|
||
|
||
<sub>获取托管产品的<b>早期 Beta 访问权</b> · <a href="https://getcodegraph.com">getcodegraph.com</a></sub>
|
||
|
||
</div>
|
||
|
||
## 目录
|
||
|
||
- [快速开始](#get-started)
|
||
- [语言支持](#language-support)
|
||
- [为什么选择 CodeGraph？](#why-codegraph)
|
||
- [关键特性](#key-features)
|
||
- [框架感知路由](#framework-aware-routes)
|
||
- [iOS / React Native / Expo 混合桥接](#mixed-ios--react-native--expo-bridging)
|
||
- [快速上手](#quick-start)
|
||
- [工作原理](#how-it-works)
|
||
- [CLI 参考](#cli-reference)
|
||
- [MCP 工具](#mcp-tools)
|
||
- [库使用](#library-usage)
|
||
- [配置](#configuration)
|
||
- [遥测](#telemetry)
|
||
- [支持平台](#supported-platforms)
|
||
- [支持的 Agent](#supported-agents)
|
||
- [支持的语言](#supported-languages)
|
||
- [实测跨文件覆盖率](#measured-cross-file-coverage)
|
||
- [故障排除](#troubleshooting)
|
||
- [Star 历史](#star-history)
|
||
- [许可证](#license)
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装 CLI
|
||
|
||
**无需 Node.js** —— 一条命令即可获取适用于你操作系统的正确构建版本：
|
||
|
||
```bash
|
||
# macOS / Linux
|
||
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
|
||
|
||
# Windows (PowerShell)
|
||
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
|
||
```
|
||
|
||
<details>
|
||
<summary><b>已经有 Node？改用 npm（适用于任意版本）</b></summary>
|
||
|
||
```bash
|
||
npm i -g @colbymchenry/codegraph
|
||
```
|
||
|
||
<sub>CodeGraph 自带运行时 —— 无需编译，无原生构建，在任何环境下运行一致。安装程序会将 `codegraph` 添加到 PATH，但<b>不会更改你当前的 shell</b> —— 在下一步之前请打开一个新终端，以便命令能被正确解析。</sub>
|
||
|
||
<sub>**随时升级**，运行 `codegraph upgrade` —— 它会检测你的安装方式（bundle、npm 或 npx）并原地更新。添加 `--check` 查看是否有可用更新，或使用 `codegraph upgrade <version>` 锁定版本。</sub>
|
||
|
||
</details>
|
||
|
||
### 2. 连接你的 Agent
|
||
|
||
在一个**新终端**中，运行安装程序将 CodeGraph 连接到你使用的 Agent：
|
||
|
||
```bash
|
||
codegraph install
|
||
```
|
||
|
||
<sub>自动检测并配置 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE 和 Kiro —— 将 CodeGraph MCP 服务器接入每个 Agent。**这一步是将 CodeGraph 连接到你的 Agent 的关键；** 第 1 步中安装 CLI 并不会自动完成连接。它仅配置 Agent —— 并**不会**索引任何代码；构建每个项目图是第 3 步中独立的 `codegraph init` 命令。（快捷方式：`npx @colbymchenry/codegraph` 会一次性下载并运行全部操作。）</sub>
|
||
|
||
### 3. 初始化每个项目
|
||
|
||
```bash
|
||
cd your-project
|
||
codegraph init
|
||
```
|
||
|
||
<sub>`codegraph init` 会在同一步中创建本地的 `.codegraph/` 目录并构建完整图 —— 一条命令，一步完成。</sub>
|
||
|
||
<div align="center">
|
||
|
||
|
||
|
||
</div>
|
||
|
||
### 4. 无需再同步！
|
||
|
||
自动同步默认启用。CodeGraph 会监视项目，并在每次文件变更时更新图 —— 无论是你的 Agent 编辑代码，还是你添加、修改或删除文件。**索引永不过期，无需重新运行。**
|
||
|
||
### 卸载
|
||
|
||
改变主意了？一条命令即可从 CodeGraph 配置过的每个 Agent 中移除 CodeGraph **以及** CLI 本身 —— 它会找到所有已安装的版本（独立 bundle、npm 全局包、启动器链接），并在删除前展示给你：
|
||
|
||
```bash
|
||
codegraph uninstall
|
||
```
|
||
|
||
添加 `--keep-cli` 仅移除 Agent 配置而保留 CLI。
|
||
|
||
<sub>反转安装程序 —— 从每个已配置的 Agent 中移除 CodeGraph 的 MCP 服务器配置、指令和权限。你的项目索引（`.codegraph/`）保持不变；每个项目可使用 `codegraph uninit` 单独删除。使用 `--target` 从特定 Agent 中移除，或使用 `--yes` 以非交互方式运行。</sub>
|
||
|
||
---
|
||
|
||
## 语言支持
|
||
|
||
以下每种语言都获得相同的处理 —— 完整的结构提取和跨文件解析，统一整合到一张图中，无需逐个语言配置：
|
||
|
||
<p align="center">
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/typescript.svg?v=1" width="104" height="104" alt="TypeScript" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/javascript.svg?v=1" width="104" height="104" alt="JavaScript" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/arkts.svg?v=1" width="104" height="104" alt="ArkTS" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/python.svg?v=1" width="104" height="104" alt="Python" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/go.svg?v=1" width="104" height="104" alt="Go" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/rust.svg?v=1" width="104" height="104" alt="Rust" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/java.svg?v=1" width="104" height="104" alt="Java" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/csharp.svg?v=1" width="104" height="104" alt="C#" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/php.svg?v=1" width="104" height="104" alt="PHP" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/ruby.svg?v=1" width="104" height="104" alt="Ruby" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/c.svg?v=1" width="104" height="104" alt="C" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/cpp.svg?v=1" width="104" height="104" alt="C++" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/objective-c.svg?v=1" width="104" height="104" alt="Objective-C" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/metal.svg?v=1" width="104" height="104" alt="Metal" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/cuda.svg?v=1" width="104" height="104" alt="CUDA" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/swift.svg?v=1" width="104" height="104" alt="Swift" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/kotlin.svg?v=1" width="104" height="104" alt="Kotlin" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/scala.svg?v=1" width="104" height="104" alt="Scala" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/dart.svg?v=1" width="104" height="104" alt="Dart" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/svelte.svg?v=1" width="104" height="104" alt="Svelte" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/vue.svg?v=1" width="104" height="104" alt="Vue" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/astro.svg?v=1" width="104" height="104" alt="Astro" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/liquid.svg?v=1" width="104" height="104" alt="Liquid" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/delphi.svg?v=1" width="104" height="104" alt="Pascal / Delphi" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/lua.svg?v=1" width="104" height="104" alt="Lua" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/r.svg?v=1" width="104" height="104" alt="R" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/luau.svg?v=1" width="104" height="104" alt="Luau" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/cfml.svg?v=1" width="104" height="104" alt="CFML" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/cobol.svg?v=1" width="104" height="104" alt="COBOL" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/vbnet.svg?v=1" width="104" height="104" alt="Visual Basic .NET" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/erlang.svg?v=1" width="104" height="104" alt="Erlang" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/solidity.svg?v=1" width="104" height="104" alt="Solidity" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/terraform.svg?v=1" width="104" height="104" alt="Terraform / OpenTofu" />
|
||
<img src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/languages/nix.svg?v=1" width="104" height="104" alt="Nix" />
|
||
</p>
|
||
|
||
<sub>各语言的具体说明——扩展、框架以及究竟会提取什么——见 [支持的语言](#supported-languages)。</sub>
|
||
|
||
---
|
||
|
||
## 为什么选择 CodeGraph？
|
||
|
||
当 AI agent 需要理解代码——回答问题或做出修改——它只能用最慢的方式摸索结构：grep、glob 和 Read，一次一个文件，手工重建调用路径和依赖关系。在真正开始干活之前，就已经堆了一大堆工具调用和往返。
|
||
|
||
**CodeGraph 一次调用就把 agent 需要的精确代码交给它。** 它是你代码库中每个符号、调用边和依赖关系的预构建知识图谱——因此 agent 不必爬文件，而是问一个问题，就能拿回相关源码、这些符号之间的调用路径（包括 grep 跟不上的动态派发跳转），以及一次变更的影响范围。**精准上下文，而非逐文件搜索**——这意味着无论代码库大小，工具调用更少、回答更快。
|
||
|
||
<img width="1536" height="1024" alt="token-cost-savings-scale" src="https://github.com/user-attachments/assets/eb74a11a-a3ab-4b01-80a6-19f78352ae8e" />
|
||
|
||
> **关于成本的说明：** CodeGraph 在*每个*代码库上的优势都是精度与速度——更少的工具调用、更快的回答。它也能降低 token 和美元成本，但这些节省是**随规模变化的**：在规模适中的代码库上小而嘈杂，只有等到仓库又大又缠、达到 Google 或 Microsoft monorepo 那种规模，再乘以整个团队每日的 agent 使用量，才会累积成真正的成本项。在 500 个文件的项目上，采用 CodeGraph 是为了速度；当代码库（和团队）变大时，成本节省才会显现。
|
||
|
||
### 基准测试结果
|
||
|
||
在跨越 7 种语言的 **7 个真实开源代码库**上测试，比较 agent（Claude Code，headless）在**启用**与**未启用** CodeGraph 的情况下回答一个架构问题，**每臂 4 次运行的中位数**。_于 2026-06-02 在 Opus 4.8 上重新验证，使用当前构建（以 `codegraph_explore` 为主要工具）。_
|
||
|
||
> **普遍收益——每个仓库、每种规模：工具调用减少 58% · 速度提升 22% · 文件读取降至约零。**
|
||
|
||
可靠、普遍的回报是**精准上下文与速度**：CodeGraph 把 agent 的 grep/find/Read 爬取压缩成少量直接查询——即使目标方法埋在上千行的文件里，也能返回你问的确切方法——因此它以**近乎零文件读取**作答，而未使用 CodeGraph 的 agent 却把预算花在发现上。**Tokens** 和 **Cost** 列也是真实的，但——如上所述——它们是**随规模变化的**：每次查询在绝对值上小而嘈杂，只有在大代码库、高用量规模下才会累积成真正的钱。
|
||
|
||
| Codebase | Language | Tool calls | Time | File reads | Tokens | Cost |
|
||
|----------|----------|------------|------|------------|--------|------|
|
||
| **VS Code** | TypeScript · ~10k files | 81% fewer | 11% faster | 0 vs 9 | 64% fewer | 18% cheaper |
|
||
| **Excalidraw** | TypeScript · ~640 | 40% fewer | 27% faster | 0 vs 7 | 25% fewer | even |
|
||
| **Django** | Python · ~3k | 77% fewer | 13% faster | 0 vs 9 | 60% fewer | 8% cheaper |
|
||
| **Tokio** | Rust · ~790 | 57% fewer | 18% faster | 0 vs 8 | 38% fewer | even |
|
||
| **OkHttp** | Java · ~645 | 50% fewer | 31% faster | 0 vs 4 | 54% fewer | 25% cheaper |
|
||
| **Gin** | Go · ~110 | 44% fewer | 24% faster | 1 vs 6 | 23% fewer | 19% cheaper |
|
||
| **Alamofire** | Swift · ~110 | 58% fewer | 33% faster | 0 vs 9 | 64% fewer | 40% cheaper |
|
||
|
||
<sub>**File reads** = agent 在**启用**与**未启用** CodeGraph 时打开文件的中位数——精准上下文收益浓缩在一列。**Tokens** 和 **Cost** 同样是启用 vs 未启用的差值；它们具有方向性（各次运行会波动），且按单次查询的绝对值而言很小——这就是为什么只有在大规模下才会成为成本项。`codegraph_explore` 还会把冗余的可互换实现折叠为签名，因此响应大小按*答案*而非文件数量来定。</sub>
|
||
|
||
<details>
|
||
<summary><strong>各仓库明细——WITH vs WITHOUT（4 次中位数）</strong></summary>
|
||
|
||
**VS Code** · ~10k files
|
||
| Metric | WITH cg | WITHOUT cg | Δ |
|
||
|---|---|---|---|
|
||
| Time | 1m 59s | 2m 13s | 11% faster |
|
||
| File Reads | 0 | 9 | −9 |
|
||
| Grep/Bash | 0 | 11 | −11 |
|
||
| Tool calls | 4 | 21 | 81% fewer |
|
||
| Total tokens | 640k | 1.79M | 64% fewer |
|
||
| Cost | $0.68 | $0.83 | 18% cheaper |
|
||
|
||
**Excalidraw** · ~640 files
|
||
| Metric | WITH cg | WITHOUT cg | Δ |
|
||
|---|---|---|---|
|
||
| Time | 1m 32s | 2m 6s | 27% faster |
|
||
| File Reads | 0 | 7 | −7 |
|
||
| Grep/Bash | 1 | 8 | −7 |
|
||
| Tool calls | 9 | 15 | 40% fewer |
|
||
| Total tokens | 1.27M | 1.69M | 25% fewer |
|
||
| Cost | $0.78 | $0.78 | even |
|
||
|
||
**Django** · ~3k files
|
||
| Metric | WITH cg | WITHOUT cg | Δ |
|
||
|---|---|---|---|
|
||
| Time | 1m 43s | 1m 58s | 13% faster |
|
||
| File Reads | 0 | 9 | −9 |
|
||
| Grep/Bash | 0 | 5 | −5 |
|
||
| Tool calls | 3 | 13 | 77% fewer |
|
||
| Total tokens | 559k | 1.41M | 60% fewer |
|
||
| Cost | $0.57 | $0.62 | 8% cheaper |
|
||
|
||
**Tokio** · ~790 files
|
||
| Metric | WITH cg | WITHOUT cg | Δ |
|
||
|---|---|---|---|
|
||
| Time | 1m 55s | 2m 20s | 18% faster |
|
||
| File Reads | 0 | 8 | −8 |
|
||
| Grep/Bash | 0 | 6 | −6 |
|
||
| Tool calls | 6 | 14 | 57% fewer |
|
||
| Total tokens | 1.08M | 1.73M | 38% fewer |
|
||
| Cost | $0.82 | $0.82 | even |
|
||
|
||
**OkHttp** · ~645 files
|
||
| Metric | WITH cg | WITHOUT cg | Δ |
|
||
|---|---|---|---|
|
||
| Time | 1m 1s | 1m 29s | 31% faster |
|
||
| File Reads | 0 | 4 | −4 |
|
||
| Grep/Bash | 2 | 6 | −4 |
|
||
| Tool calls | 5 | 10 | 50% fewer |
|
||
| Total tokens | 502k | 1.10M | 54% fewer |
|
||
| Cost | $0.41 | $0.55 | 25% cheaper |
|
||
|
||
**Gin** · ~110 files
|
||
| Metric | WITH cg | WITHOUT cg | Δ |
|
||
|---|---|---|---|
|
||
| Time | 1m 14s | 1m 37s | 24% faster |
|
||
| File Reads | 1 | 6 | −5 |
|
||
| Grep/Bash | 1 | 2 | −1 |
|
||
| Tool calls | 5 | 9 | 44% fewer |
|
||
| Total tokens | 651k | 847k | 23% fewer |
|
||
| Cost | $0.46 | $0.57 | 19% cheaper |
|
||
|
||
**Alamofire** · ~110 files
|
||
| Metric | WITH cg | WITHOUT cg | Δ |
|
||
|---|---|---|---|
|
||
| Time | 1m 35s | 2m 21s | 33% faster |
|
||
| File Reads | 0 | 9 | −9 |
|
||
| Grep/Bash | 0 | 4 | −4 |
|
||
| Tool calls | 5 | 12 | 58% fewer |
|
||
| Total tokens | 766k | 2.10M | 64% fewer |
|
||
| Cost | $0.57 | $0.95 | 40% cheaper |
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><strong>完整基准测试细节</strong></summary>
|
||
|
||
**方法论。** 每臂为 `claude -p`（Claude Opus 4.8）headless 运行于仓库，配置 `--strict-mcp-config`：**WITH** = 启用 CodeGraph 的 MCP server，**WITHOUT** = 空 MCP 配置。内置 Read/Grep/Bash 对两臂均可用。每个仓库同一问题，**每臂 4 次运行，报告中位数**。Cost = 该次运行的 `total_cost_usd`；Tokens = 处理的总 token（输入含缓存 + 输出）；Time = 挂钟时间；Tool calls = 每次工具调用，包括模型派生的任何 sub-agent 内部的调用。仓库克隆于 `--depth 1`，并由为其提供服务的同一 CodeGraph 构建索引。于 2026-06-02 在当前构建上重新验证。这些数字低于此前 Opus 4.7 验证——并非 CodeGraph 退步，而是更强的原生基线：Opus 4.8 在主线程上高效 grep/read，而不是扇出到大规模 Explore-subagent 扫描，因此 no-CodeGraph 臂比过去更精简。各仓库数字会随 without 臂的折腾程度而次次波动（4 次中位数能平滑，但尾部仍在——例如 Django 的 without 臂某一批达到 $2.71/14m）。
|
||
|
||
**查询：**
|
||
| Codebase | Query |
|
||
|----------|-------|
|
||
| VS Code | "How does the extension host communicate with the main process?" |
|
||
| Excalidraw | "How does Excalidraw render and update canvas elements?" |
|
||
| Django | "How does Django's ORM build and execute a query from a QuerySet?" |
|
||
| Tokio | "How does tokio schedule and run async tasks on its runtime?" |
|
||
| OkHttp | "How does OkHttp process a request through its interceptor chain?" |
|
||
| Gin | "How does gin route requests through its middleware chain?" |
|
||
| Alamofire | "How does Alamofire build, send, and validate a request?" |
|
||
|
||
**CodeGraph 为何胜出：** 有索引可用时，agent 直接作答——通常一次 `codegraph_explore` 就返回相关源码——然后停止，通常零文件读取。没有它时，agent 把大部分预算花在发现（find/ls/grep）上，然后才读到正确代码。CodeGraph 只有在被*直接*查询时才有帮助，因此其指令引导 agent 直接作答，而不是把探索委托给读文件的 sub-agent——否则 sub-agent 无论如何都会读文件，CodeGraph 就成了开销。
|
||
</details>
|
||
|
||
</details>
|
||
|
||
---
|
||
|
||
## 核心特性
|
||
|
||
| | |
|
||
|---|---|
|
||
| **精准上下文（Surgical Context）** | 一次工具调用即可返回入口点、相关符号和代码片段——无需缓慢地逐文件探索 |
|
||
| **全文搜索（Full-Text Search）** | 借助 FTS5，在整个代码库中按名称即时查找代码 |
|
||
| **影响分析（Impact Analysis）** | 在修改前追踪任意符号的调用方、被调用方及完整影响范围 |
|
||
| **始终最新（Always Fresh）** | 文件监视器使用原生操作系统事件（FSEvents/inotify/ReadDirectoryChangesW）并配合防抖自动同步——图随你编码实时更新，零配置 |
|
||
| **20+ 种语言** | TypeScript、JavaScript、ArkTS、Python、Go、Rust、Java、C#、VB.NET、PHP、Ruby、C、C++、CUDA、Objective-C、Metal、Swift、Kotlin、Scala、Dart、Lua、Luau、R、Nix、Erlang、CFML、COBOL、Solidity、Terraform/OpenTofu、Svelte、Vue、Astro、Liquid、Pascal/Delphi |
|
||
| **框架感知路由（Framework-aware Routes）** | 识别 Web 框架路由文件，并在 17 种框架中将 URL 模式与其处理程序关联 |
|
||
| **混合 iOS / React Native / Expo** | 补全静态解析会遗漏的跨语言调用链：Swift ↔ ObjC 桥接、React Native 传统桥接 + TurboModules + Fabric 视图组件、原生 → JS 事件发射器、Expo Modules |
|
||
| **100% 本地** | 数据不会离开你的机器。无需 API 密钥。无外部服务。仅使用 SQLite 数据库 |
|
||
|
||
<details>
|
||
<summary><strong>自动同步如何工作——以及为何你无需手动运行 <code>codegraph sync</code></strong></summary>
|
||
|
||
当你的 agent（Claude Code、Cursor、Codex、opencode）启动 `codegraph serve --mcp` 时，三层机制让索引与代码保持同步——并确保 agent 在编辑与下一次同步之间的短暂窗口期内绝不会无声地得到错误答案：
|
||
|
||
1. **带防抖自动同步的文件监视器。** 原生 FSEvents / inotify / ReadDirectoryChangesW 监视器捕获每一次源文件的创建/修改/删除，并在防抖窗口后触发重新索引（默认 `2000ms`，可通过 `CODEGRAPH_WATCH_DEBOUNCE_MS` 调整，上限为 `[100ms, 60s]`）。连续编辑会合并为一次同步。
|
||
|
||
2. **按文件的陈旧状态横幅。** 在短暂的防抖窗口内，会引用仍处于待同步状态的文件的 MCP 工具响应，会在开头附加 `⚠️` 横幅，标明该文件并告知 agent 直接 `Read`。响应未引用的待同步文件则显示为小页脚。无论哪种方式，agent 都会收到明确信号——已在 Claude Code 中验证，agent 会在打开文件前明确说出 "Reading the file directly for the live content"。
|
||
|
||
3. **连接时追平。** 当 MCP 服务器（重新）连接时，codegraph 在回答第一个查询前会对工作树执行快速的 `(size, mtime)` + 内容哈希对账——因此在 MCP 服务器未运行期间所做的编辑（来自终端的 `git pull`、其他编辑器的修改、已退出的先前 agent 会话）会在下一次会话的首次工具调用时被吸收。
|
||
|
||
```
|
||
agent writes src/Widget.ts
|
||
→ watcher fires (<100ms)
|
||
→ debounce (default 2s)
|
||
→ sync; Widget.ts is in the index
|
||
→ next agent query sees it
|
||
```
|
||
|
||
**随时验证**：使用 `codegraph status`（CLI）。如有待处理项，你会看到 `### Pending sync:` 部分，其中列出文件及其编辑时长。
|
||
|
||
少数情况下手动 `codegraph sync` 仍有意义：监视器被禁用（沙盒环境，或 `CODEGRAPH_NO_DAEMON=1`），或者你在 agent 会话外针对索引编写脚本，并希望在脚本开始时执行预检同步。
|
||
|
||
→ 完整深入解读见 [指南 → 为项目建立索引](https://colbymchenry.github.io/codegraph/guides/indexing/#stay-fresh-automatically).
|
||
|
||
</details>
|
||
|
||
---
|
||
|
||
## 框架感知路由
|
||
|
||
CodeGraph 会检测 Web 框架路由文件，并发出 `route` 节点，通过 `references` 边与其处理类或函数关联。查询视图/控制器的调用方现在会显示绑定它的 URL 模式。
|
||
|
||
| 框架 | 识别的形态 |
|
||
|---|---|
|
||
| **Django** | `path()`、`re_path()`、`url()`、`include()`，位于 `urls.py` 中（CBV `.as_view()`、dotted paths） |
|
||
| **Flask** | `@app.route('/path', methods=[...])`、blueprint routes |
|
||
| **FastAPI** | `@app.get(...)`、`@router.post(...)`，所有标准 HTTP 方法 |
|
||
| **Express** | `app.get(...)`、`router.post(...)`，含中间件链 |
|
||
| **NestJS** | `@Controller` + `@Get/@Post/...`，GraphQL `@Resolver` + `@Query/@Mutation`，`@MessagePattern`/`@EventPattern`，`@SubscribeMessage` |
|
||
| **Laravel** | `Route::get()`、`Route::resource()`、`Controller@action`，元组语法 |
|
||
| **Drupal** | `*.routing.yml` routes（`_controller`、`_form`、entity handlers）；`hook_*` implementations 位于 `.module`/`.theme`/`.install`/`.inc` |
|
||
| **Rails** | `get '/x', to: 'users#index'`，哈希火箭 `=>` 语法 |
|
||
| **Spring** | `@GetMapping`、`@PostMapping`、`@RequestMapping`，标注在方法上 |
|
||
| **Play** | `GET`/`POST`/… 动词路由，位于 `conf/routes` → `Controller.method` actions（Scala + Java） |
|
||
| **Gin / chi / gorilla / mux** | `r.GET(...)`、`router.HandleFunc(...)` |
|
||
| **Axum / actix / Rocket** | `.route("/x", get(handler))` |
|
||
| **ASP.NET** | `[HttpGet("/x")]` attributes，标注在 action 方法上 |
|
||
| **Vapor** | `app.get("x", use: handler)` |
|
||
| **React Router** / **SvelteKit** | 路由组件节点 |
|
||
| **Vue Router** / **Nuxt** | `pages/` 基于文件的路由、`server/api/` 端点、route middleware |
|
||
| **Astro** | `src/pages/` 基于文件的路由（`.astro` pages + `.ts` 端点，`[param]`/`[...rest]` 语法） |
|
||
|
||
---
|
||
|
||
## 混合 iOS / React Native / Expo 桥接
|
||
|
||
真实的 iOS 与 React Native 代码库横跨多种语言——Swift 调用方调用经自动桥接的 Objective-C 选择器，JS 文件通过 React Native bridge 调用原生模块，JSX 组件委托给原生视图管理器。静态 tree-sitter 提取会在每种语言边界处停止。CodeGraph 将它们桥接起来，使 `codegraph_explore` 跨越鸿沟端到端连接调用链——调用路径与影响半径会跨越边界，而不是在边界处中断。
|
||
|
||
| 边界 | JS / Swift 侧 | 原生侧 | 方式 |
|
||
|---|---|---|---|
|
||
| **Swift → ObjC** | Swift `obj.foo(bar:)` | ObjC selector `-fooWithBar:` | `@objc` auto-bridging rules（含 init/property/protocol 形式）+ Cocoa preposition prefixes（`With`/`For`/`By`/`In`/`On`/`At`/…） |
|
||
| **ObjC → Swift** | ObjC `[obj fooWithBar:]` | Swift `@objc func foo(bar:)` | 反向桥接名称候选；从源码验证 `@objc` exposure |
|
||
| **React Native legacy bridge** | JS `NativeModules.X.fn(...)` | ObjC `RCT_EXPORT_METHOD` / `RCT_REMAP_METHOD` · Java/Kotlin `@ReactMethod` | 解析宏/注解声明以构建 JS 名称 → 原生方法映射 |
|
||
| **React Native TurboModules** | JS `import M from './NativeM'; M.fn(...)` | 与 Codegen 规范匹配的原生实现 | 将 `Native<X>.ts` spec interface 视为权威依据 |
|
||
| **RN native → JS events** | JS `new NativeEventEmitter(...).addListener('e', cb)` | ObjC `[self sendEventWithName:@"e" body:...]` · Swift `sendEvent(withName: "e", ...)` · Java/Kotlin `.emit("e", ...)` | 以字面事件名作为键的合成跨语言事件通道 |
|
||
| **Expo Modules** | JS `requireNativeModule('X').fn(...)` | Swift / Kotlin `Module { Name("X"); AsyncFunction("fn") { ... } }` | 解析 Expo DSL 字面量；合成方法节点通过现有名称匹配解析 |
|
||
| **Fabric view components** | JSX `<MyView prop={v}/>` | TS Codegen spec + native impl class | Spec → `component` 节点；基于约定的名称+后缀查找（`View`/`ComponentView`/`Manager`/`ViewManager`）桥接到原生侧 |
|
||
| **Legacy Paper view managers** | JSX `<MyView prop={v}/>` | ObjC `RCT_EXPORT_VIEW_PROPERTY` · Java/Kotlin `@ReactProp` | 与 Fabric 相同——Paper 时代的声明同样会生成 `component` + `property` 节点 |
|
||
|
||
**已在真实代码库上验证**（每种桥接均有小型 + 中型 + 大型项目）：
|
||
|
||
| 桥接 | 小型 | 中型 | 大型 |
|
||
|---|---|---|---|
|
||
| Swift ↔ ObjC | [Charts](https://github.com/danielgindi/Charts) | [realm-swift](https://github.com/realm/realm-swift) | [Wikipedia-iOS](https://github.com/wikimedia/wikipedia-ios) |
|
||
| RN legacy bridge | [AsyncStorage](https://github.com/react-native-async-storage/async-storage) | [react-native-svg](https://github.com/software-mansion/react-native-svg) | [react-native-firebase](https://github.com/invertase/react-native-firebase) |
|
||
| RN native → JS events | [RNGeolocation](https://github.com/Agontuk/react-native-geolocation-service) | — | react-native-firebase |
|
||
| Expo Modules | expo-haptics | expo-camera | expo SDK sweep (7 packages) |
|
||
| Fabric / Paper views | [react-native-segmented-control](https://github.com/react-native-segmented-control/segmented-control) | [react-native-screens](https://github.com/software-mansion/react-native-screens) | [react-native-skia](https://github.com/Shopify/react-native-skia) |
|
||
|
||
每个桥接器会发出带有 `provenance:'heuristic'` 标签的边，并将 `metadata.synthesizedBy:` 设置为稳定的通道名称（例如 `swift-objc-bridge`、`rn-event-channel`、`fabric-native-impl`、`expo-module-extract`），以便智能体一目了然地看出某个跳转是如何进入图的。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 1. 运行安装程序
|
||
|
||
```bash
|
||
npx @colbymchenry/codegraph
|
||
```
|
||
|
||
安装程序将会：
|
||
- 询问要配置哪些智能体——自动检测已安装的：**Claude Code**、**Cursor**、**Codex CLI**、**opencode**、**Hermes Agent**、**Gemini CLI**、**Antigravity IDE**、**Kiro**
|
||
- 提示将 `codegraph` 安装到 PATH（以便智能体可以启动 MCP 服务器）
|
||
- 询问配置是应用于所有项目还是仅当前项目
|
||
- 为每个所选智能体写入 MCP 服务器配置，并在智能体的说明文件中写入一小段带标记围栏的 CodeGraph 章节（`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`）——子智能体和非 MCP 智能体正是通过这种方式学习 `codegraph explore` 命令，因为 MCP 服务器自身的指引只能到达主智能体。可通过 `codegraph uninstall` 干净地移除。
|
||
- 当目标包含 Claude Code 时，设置自动允许权限
|
||
|
||
安装程序**仅连接你的智能体——不会为代码建立索引。**完成后，请用 `codegraph init` 自行构建每个项目的图（步骤 3）。一个全局 `codegraph install` 覆盖所有项目；每个项目运行一次 `codegraph init`。
|
||
|
||
**非交互式（脚本/CI）：**
|
||
|
||
```bash
|
||
codegraph install --yes # auto-detect agents, install global
|
||
codegraph install --target=cursor,claude --yes # explicit target list
|
||
codegraph install --target=auto --location=local # detected agents, project-local
|
||
codegraph install --print-config codex # print snippet, no file writes
|
||
```
|
||
|
||
| 标志 | 取值 | 默认值 |
|
||
|---|---|---|
|
||
| `--target` | `auto`、`all`、`none`，或 csv（`claude,cursor,...`） | prompt |
|
||
| `--location` | `global`、`local` | prompt |
|
||
| `--yes` | （布尔值） | 每步均提示 |
|
||
| `--no-permissions` | （布尔值）跳过 Claude 自动允许列表 | 权限开启 |
|
||
| `--print-config <id>` | 导出单个智能体的代码片段后退出 | — |
|
||
|
||
### 2. 重启智能体
|
||
|
||
重启你的智能体（Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro），以加载 MCP 服务器。
|
||
|
||
### 3. 初始化项目
|
||
|
||
```bash
|
||
cd your-project
|
||
codegraph init
|
||
```
|
||
|
||
构建按项目的知识图谱索引，之后会在每次文件变更时自动同步。单个全局 `codegraph install` 在你打开的每个项目中都可用——无需为每个项目重新运行安装程序。
|
||
|
||
就是这样——当存在 `.codegraph/` 目录时，你的智能体会自动使用 CodeGraph 工具。
|
||
|
||
<details>
|
||
<summary><strong>手动设置（替代方案）</strong></summary>
|
||
|
||
**全局安装：**
|
||
```bash
|
||
npm install -g @colbymchenry/codegraph
|
||
```
|
||
|
||
**添加到 `~/.claude.json`：**
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"codegraph": {
|
||
"type": "stdio",
|
||
"command": "codegraph",
|
||
"args": ["serve", "--mcp"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**添加到 `~/.claude/settings.json`（可选，用于自动允许）：**
|
||
```json
|
||
{
|
||
"permissions": {
|
||
"allow": [
|
||
"mcp__codegraph__*"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
<sub>一个通配符即可自动批准所有 CodeGraph 工具——默认仅列出 `codegraph_explore`，但若你通过 `CODEGRAPH_MCP_TOOLS` 重新启用其他工具，它们也已获准，无需提示。</sub>
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><strong>智能体工具指引</strong></summary>
|
||
|
||
CodeGraph 的 MCP 服务器会**自动**通过 MCP `initialize` 响应向你的智能体提供使用指引。简而言之，它告诉智能体：
|
||
|
||
- **直接用 CodeGraph 回答结构性问题**——它*就是*预构建的索引，因此 grep/read 循环只是在重复它已完成的工作。将返回的源码视为已读。
|
||
- **几乎所有情况都优先使用 `codegraph_explore`**——例如“X 如何工作”、流程/“X 如何到达 Y”，或调研某个区域。一次调用即可返回相关符号的逐字源码（按文件分组）、它们之间的调用路径（含动态分派跳转），以及影响范围摘要。在查询中指定文件或符号即可读取其当前带行号的源码。
|
||
- **信任结果——不要用 grep 重新验证**，并在编辑后查看陈旧性横幅。
|
||
- **按项目工作**：通过传入 `projectPath`，可查询任何已建立 `.codegraph/` 索引的项目——因此，在仅部分服务已索引的 monorepo 或第二个仓库中，单次会话即可工作。没有索引的路径会返回清晰指引以使用内置工具；是否建立索引仍由你决定。
|
||
|
||
确切文本为 `src/mcp/server-instructions.ts`——主智能体的唯一事实来源。由于子智能体和非 MCP 工具链看不到 MCP 指引，安装程序还会在智能体说明文件中写入一小段带标记围栏的章节，指向 `codegraph explore` CLI 等价物。
|
||
|
||
</details>
|
||
|
||
---
|
||
|
||
## 工作原理
|
||
|
||
```
|
||
┌───────────────────────────────────────────────────────────────────┐
|
||
│ Claude Code │
|
||
│ │
|
||
│ "How does a request reach the database?" │
|
||
│ calls CodeGraph tools directly — no Explore sub-agent │
|
||
│ │ │
|
||
└─────────────────────────────────┬─────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌───────────────────────────────────────────────────────────────────┐
|
||
│ CodeGraph MCP Server │
|
||
│ │
|
||
│ explore · one call → verbatim source + call flow + blast radius │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ SQLite knowledge graph │
|
||
│ symbols · edges · files · FTS5 full-text search │
|
||
└───────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
1. **提取** — [tree-sitter](https://tree-sitter.github.io/) 将源代码解析为 AST。特定于语言的查询会提取节点（函数、类、方法）和边（调用、导入、继承、实现）。
|
||
|
||
2. **存储** — 所有内容存入本地 SQLite 数据库（`.codegraph/codegraph.db`），并支持 FTS5 全文搜索。
|
||
|
||
3. **解析** — 提取完成后解析引用：函数调用 → 定义、导入 → 源文件、类继承，以及框架特定模式。
|
||
|
||
4. **自动同步** — MCP 服务器使用原生操作系统文件事件监听项目。变更会经过去抖（2 秒静默窗口）、仅过滤源文件，并增量同步。图谱会随你编码保持最新——无需配置。
|
||
|
||
---
|
||
|
||
## CLI 参考
|
||
|
||
```bash
|
||
codegraph # Run interactive installer
|
||
codegraph install # Run installer (explicit)
|
||
codegraph uninstall # Remove CodeGraph from your agents AND the CLI (--keep-cli for configs only)
|
||
codegraph init [path] # Initialize a project + build its graph (one step)
|
||
codegraph uninit [path] # Remove CodeGraph from a project (--force to skip prompt)
|
||
codegraph index [path] # Full index (--force to re-index, --quiet for less output)
|
||
codegraph sync [path] # Incremental update
|
||
codegraph status [path] # Show statistics
|
||
codegraph unlock [path] # Remove a stale lock file that's blocking indexing
|
||
codegraph query <search> # Search symbols (--kind, --limit, --json)
|
||
codegraph explore <query> # Relevant symbols' source + call paths in one shot (same output as the codegraph_explore MCP tool)
|
||
codegraph node <symbol|file> # One symbol's source + callers, or read a file with line numbers (same output as codegraph_node)
|
||
codegraph files [path] # Show file structure (--format, --filter, --max-depth, --json)
|
||
codegraph callers <symbol> # Find what calls a function/method (--limit, --json)
|
||
codegraph callees <symbol> # Find what a function/method calls (--limit, --json)
|
||
codegraph impact <symbol> # Analyze what code is affected by changing a symbol (--depth, --json)
|
||
codegraph affected [files...] # Find test files affected by changes (see below)
|
||
codegraph daemon # Manage background daemons — pick one to stop (alias: daemons)
|
||
codegraph telemetry [on|off] # Show or change anonymous usage telemetry
|
||
codegraph upgrade [version] # Update to the latest release (--check, --force)
|
||
codegraph version # Print the installed version (also -v, --version)
|
||
codegraph help [command] # Show help, optionally for one command
|
||
```
|
||
|
||
### `codegraph affected`
|
||
|
||
传递性地追踪 import 依赖，以找出哪些测试文件会受到已变更源文件的影响。
|
||
|
||
```bash
|
||
codegraph affected src/utils.ts src/api.ts # Pass files as arguments
|
||
git diff --name-only | codegraph affected --stdin # Pipe from git diff
|
||
codegraph affected src/auth.ts --filter "e2e/*" # Custom test file pattern
|
||
```
|
||
|
||
| Option | Description | Default |
|
||
|--------|-------------|---------|
|
||
| `--stdin` | 从 stdin 读取文件列表 | `false` |
|
||
| `-d, --depth <n>` | 依赖遍历的最大深度 | `5` |
|
||
| `-f, --filter <glob>` | 用于识别测试文件的自定义 glob | auto-detect |
|
||
| `-j, --json` | 以 JSON 格式输出 | `false` |
|
||
| `-q, --quiet` | 仅输出文件路径 | `false` |
|
||
|
||
**CI/hook 示例：**
|
||
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
|
||
if [ -n "$AFFECTED" ]; then
|
||
npx vitest run $AFFECTED
|
||
fi
|
||
```
|
||
|
||
---
|
||
|
||
## MCP Tools
|
||
|
||
作为 MCP 服务器运行时，CodeGraph 仅暴露**一个工具** — `codegraph_explore`。实测的 agent 行为表明，一个强大的工具比一堆更窄的工具更能引导 agent — 误选更少，且每个会话都能节省上下文：
|
||
|
||
| Tool | Purpose |
|
||
|------|---------|
|
||
| `codegraph_explore` | 一次调用即可回答几乎所有问题 — 例如「X 是如何工作的」、某个流程（「X 如何到达 Y」），或调研某个区域 — 返回按文件分组的、相关符号的逐字源代码，以及它们之间的调用路径和影响范围（blast-radius）摘要。可呈现 grep 无法跟进的动态分派跳转（回调、React 重渲染、interface→impl）。在查询中指定文件或符号，即可读取其带当前行号的源代码，格式与 Read 工具返回的一致。 |
|
||
|
||
其他工具（`codegraph_node`、`codegraph_search`、`codegraph_callers`、`codegraph_callees`、`codegraph_impact`、`codegraph_files`、`codegraph_status`）仍完全可用，但**默认不列出** — 它们返回的一切内容已内联出现在 `codegraph_explore` 中（其影响范围部分、关系图、符号体即其被调用方列表）。可通过 `CODEGRAPH_MCP_TOOLS` 环境变量（例如 `CODEGRAPH_MCP_TOOLS=explore,node,search,callers`）在 MCP 界面中重新启用其中任意一个，或使用其 CLI 等价命令（`codegraph node` / `query` / `callers` / `callees` / `impact` / `files` / `status`）。
|
||
|
||
即使服务器自身的根目录没有 `.codegraph/` 索引，工具仍可用：传入 `projectPath` 即可在同一会话中查询任意已索引项目 — 单体仓库中的子服务，或第二个仓库。没有索引的路径会返回清晰指引，建议使用内置工具，因此不会大声报错，索引与否仍由你决定。
|
||
|
||
---
|
||
|
||
## Library Usage
|
||
|
||
CodeGraph 可直接嵌入。npm 包会重新导出其编程式 API，因此 `import` 和 `require` 都会在你自己的进程中解析出 `CodeGraph` 类 — 便于嵌入应用（例如 Electron 主进程）。
|
||
|
||
```typescript
|
||
import CodeGraph from '@colbymchenry/codegraph';
|
||
// CommonJS works too:
|
||
// const { CodeGraph } = require('@colbymchenry/codegraph');
|
||
|
||
const cg = await CodeGraph.init('/path/to/project');
|
||
// Or: const cg = await CodeGraph.open('/path/to/project');
|
||
|
||
await cg.indexAll({
|
||
onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
|
||
});
|
||
|
||
const results = cg.searchNodes('UserService');
|
||
const callers = cg.getCallers(results[0].node.id);
|
||
const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' });
|
||
const impact = cg.getImpactRadius(results[0].node.id, 2);
|
||
|
||
cg.watch(); // auto-sync on file changes
|
||
cg.unwatch(); // stop watching
|
||
cg.close();
|
||
```
|
||
|
||
更低层的构建块从同一入口点导出，供直接驱动图的调用方使用：`DatabaseConnection`、`QueryBuilder`、`getDatabasePath`、`initGrammars` / `loadGrammarsForLanguages`，以及 `FileLock`。
|
||
|
||
**嵌入要求**
|
||
|
||
- 从 npm 安装（`npm i @colbymchenry/codegraph`），以便一并拉取匹配的各平台包 — 其中包含已编译库及其依赖 — 与 shim 一起安装。
|
||
- API 运行在**你的**运行时上，因此需要 **Node 22.5+** 以使用内置的 `node:sqlite`（Electron 在其捆绑的 Node 为 22.5+ 时同样满足）。CLI 和 MCP 服务器不受影响 — 它们运行在自包含的捆绑运行时上。
|
||
- TypeScript 类型随包提供。与任何面向 Node 的库一样，请保持 `@types/node` 可用，并设置 `skipLibCheck: true`（常见默认值）。
|
||
|
||
---
|
||
|
||
## Configuration
|
||
|
||
几乎无需配置 — CodeGraph **默认零配置**，无需编写或同步任何内容即可上手。语言支持根据文件扩展名自动识别；无需按语言单独接线。唯一可选的文件用于映射[自定义文件扩展名](#custom-file-extensions)。
|
||
|
||
开箱即会跳过：
|
||
|
||
- **依赖、构建与缓存目录** — `node_modules`、`vendor`、`dist`、`build`、`target`、`.venv`、`Pods`、`.next` 等，覆盖所有[受支持的技术栈](#supported-languages) — 使图谱反映的是你的代码，而非第三方噪音。即使没有 `.gitignore` 也如此。
|
||
- **`.gitignore` 中的任何内容** — 在 git 仓库中通过 git 生效，在非 git 项目中则直接读取 `.gitignore`（根目录及嵌套）。
|
||
- **大于 1 MB 的文件** — 生成的 bundle、压缩后的 JS、vendor 大文件。
|
||
|
||
若要排除其他内容，请将其加入 `.gitignore`。若要将默认排除的目录**重新纳入**（比如你确实希望索引某个 vendor 依赖），请添加否定规则 — `!vendor/`。默认规则统一适用，因此提交依赖或构建目录并不会强制将其纳入图谱；`.gitignore` 否定规则才是显式选择加入的方式。
|
||
|
||
不过 `.gitignore` 无法排除你已**提交**的目录。对于已检入仓库的 vendor 主题或 SDK（例如 `static/` 下的 Metronic 主题），请在 `codegraph.json` 的 `exclude` 下列出 — 采用 gitignore 风格模式，按相对仓库根的路径匹配，在索引、同步与监听时生效：
|
||
|
||
```json
|
||
{
|
||
"exclude": ["static/", "**/vendor/**"]
|
||
}
|
||
```
|
||
|
||
反之，当真实源码被有意 gitignore — 例如某个项目使用第二种 VCS（SVN、Perforce），由 `.gitignore` 管理其源码以使其不进入 Git — 可用 `include` 强制纳入（与 `exclude` 相反；`includeIgnored` 仅恢复嵌入式 git 仓库，而非普通源码）：
|
||
|
||
```json
|
||
{
|
||
"include": ["Tools/", "Local/typescript/"]
|
||
}
|
||
```
|
||
|
||
CodeGraph 会从磁盘发现这些文件，在索引、同步与监听时覆盖 `.gitignore`。显式的 `exclude` 仍然优先，内置跳过项（`node_modules`、`dist`、`.git`）永远不会被重新纳入。
|
||
|
||
### Custom file extensions
|
||
|
||
若项目对[受支持的语言](#supported-languages)使用非标准扩展名 — 例如 Lua 用 `.dota_lua`，PHP 用 `.tpl` — 这些文件默认会被跳过，因为 CodeGraph 不识别该扩展名。可在项目根目录用可选的 **`codegraph.json`** 进行映射：
|
||
|
||
```json
|
||
{
|
||
"extensions": {
|
||
".dota_lua": "lua",
|
||
".tpl": "php"
|
||
}
|
||
}
|
||
```
|
||
|
||
每个值为受支持的语言 id。映射会合并到内置默认值之上，冲突时以映射为准，因此也可重定向内置映射（例如 `".h": "cpp"`）。提交该文件即可与团队共享映射。拼写错误的语言或格式错误的文件会收到警告并被跳过 — 不会破坏索引 — 没有 `codegraph.json` 的项目行为与之前完全一致。添加或修改映射后请重新索引（`codegraph index`）。
|
||
|
||
## Telemetry
|
||
|
||
CodeGraph 会收集**匿名使用统计** — 哪些工具与命令被使用、哪些语言被索引 — 以指导语言与 agent 支持工作的投入方向。**绝不**包含任何代码、路径、文件或符号名、查询或 IP 地址；使用数据在本地聚合为每日总量后才会发送，接收端点是[本仓库中的公开代码](telemetry-worker/)，并强制执行文档化的字段列表。安装程序会事先询问；可随时关闭：
|
||
|
||
```bash
|
||
codegraph telemetry off # or: CODEGRAPH_TELEMETRY=0, or DO_NOT_TRACK=1
|
||
```
|
||
|
||
[`TELEMETRY.md`](TELEMETRY.md) 列出了每个字段、关闭开关以及完整的数据处理说明。
|
||
|
||
## 支持的平台
|
||
|
||
每个版本都会为全部三种桌面操作系统提供自包含构建（捆绑 Node 运行时 — 无需编译），同时支持 Intel/AMD (x64) 和 ARM (arm64)：
|
||
|
||
| 平台 | 架构 | 安装 |
|
||
|----------|---------------|---------|
|
||
| Windows | x64, arm64 | PowerShell 安装器或 npm |
|
||
| macOS | x64, arm64 | shell 安装器或 npm |
|
||
| Linux | x64, arm64 | shell 安装器或 npm |
|
||
|
||
一行安装命令请参见 [Get Started](#get-started)。
|
||
|
||
## 支持的 Agent
|
||
|
||
交互式安装程序会自动检测并配置以下各项 — 连接 MCP 服务器（该服务器自带使用指南，因此不会写入说明文件）：
|
||
|
||
- **Claude Code**
|
||
- **Cursor**
|
||
- **Codex CLI**
|
||
- **opencode**
|
||
- **Hermes Agent**
|
||
- **Gemini CLI**
|
||
- **Antigravity IDE**
|
||
- **Kiro**
|
||
|
||
## 支持的语言
|
||
|
||
| 语言 | 扩展名 | 状态 |
|
||
|----------|-----------|--------|
|
||
| TypeScript | `.ts`, `.tsx` | 完全支持 |
|
||
| JavaScript | `.js`, `.jsx`, `.mjs` | 完全支持 |
|
||
| ArkTS (HarmonyOS) | `.ets` | 完全支持（具备 TypeScript 的全部能力，外加 `@Component`/`@ComponentV2` 结构体及其 ArkUI 装饰器（`@State`/`@Prop`/`@Link`/`@Local`/`@Builder`/…）、`build()` 视图树 — 父→子组件边、指向 `@Extend`/`@Styles` 函数的链式属性链接、`.onClick(this.handler)` 事件绑定 — 用于 state→`build()` 重新渲染的动态分发桥接、`@ohos.events.emitter` emit→subscriber 对（仅限静态事件键），以及 `router.pushUrl` 字面量 url → 目标页面结构体；ohpm 工作区模块通过 `oh-package.json5` `file:` 依赖解析裸 `import { X } from "data"`，并遵循各模块的 `main` 入口） |
|
||
| Python | `.py` | 完全支持 |
|
||
| Go | `.go` | 完全支持 |
|
||
| Rust | `.rs` | 完全支持 |
|
||
| Java | `.java` | 完全支持 |
|
||
| C# | `.cs` | 完全支持 |
|
||
| PHP | `.php` | 完全支持 |
|
||
| Ruby | `.rb` | 完全支持 |
|
||
| C | `.c`, `.h` | 完全支持 |
|
||
| C++ | `.cpp`, `.hpp`, `.cc` | 完全支持 |
|
||
| Objective-C | `.m`, `.mm`, `.h` | 部分支持（类、协议、方法、`@property`、`#import`、消息发送；`.mm` ObjC++ 可能无法完整解析） |
|
||
| Metal | `.metal` | 完全支持（顶点/片段/内核函数、结构体、类型别名、调用边 — MSL 按 C++ 解析，并处理 `[[attribute]]` 注解） |
|
||
| CUDA | `.cu`, `.cuh` | 完全支持（内核及 device/host 函数、结构体、类、通过 `<<<grid, block>>>` 启动语法建立的 host→kernel 调用边 — 含模板化启动、函数指针启动（`auto kernel = &fn<...>`）、`dim3{...}` 配置及宏定义内核；处理 `__global__`/`__device__`/`__launch_bounds__` 说明符；纯 `.h`/`.hpp` 头文件中的 CUDA 按内容识别） |
|
||
| Swift | `.swift` | 完全支持 |
|
||
| Kotlin | `.kt`, `.kts` | 完全支持 |
|
||
| Scala | `.scala`, `.sc` | 完全支持（类、trait、方法、类型别名、Scala 3 枚举） |
|
||
| Dart | `.dart` | 完全支持 |
|
||
| Svelte | `.svelte` | 完全支持（script 提取、Svelte 5 runes、SvelteKit 路由） |
|
||
| Vue | `.vue` | 完全支持（script + script-setup 提取、Nuxt 页面/API/中间件路由） |
|
||
| Astro | `.astro` | 完全支持（frontmatter + script 提取、模板组件/调用引用、`src/pages/` 路由） |
|
||
| Liquid | `.liquid` | 完全支持 |
|
||
| Pascal / Delphi | `.pas`, `.dpr`, `.dpk`, `.lpr` | 完全支持（类、记录、接口、枚举、DFM/FMX 窗体文件） |
|
||
| Lua | `.lua` | 完全支持（函数、带 receiver 的方法、局部变量、`require` 导入、调用边） |
|
||
| R | `.R` `.r` | 完全支持（各种赋值形式的函数、带方法的 S4/R5/R6 类、`library`/`require` 导入、`source()` 文件引用、调用边） |
|
||
| Luau | `.luau` | 完全支持（具备 Lua 的全部能力，外加 `type`/`export type` 别名、类型签名及 Roblox 实例路径 `require`） |
|
||
| CFML | `.cfc`, `.cfm`, `.cfs` | 完全支持（基于标签的 `<cfcomponent>`/`<cffunction>` 与裸脚本 `component { ... }` 风格、`extends`/`implements`、嵌入式 `<cfscript>` 委托、调用边） |
|
||
| COBOL | `.cbl`, `.cob`, `.cpy` | 完全支持（程序、带 PERFORM/GO TO 调用边的节/段落、CALL 'literal' 跨程序调用、COPY copybook 导入 — 含独立 `.cpy` 文件 — DATA DIVISION 记录/字段/88 级、EXEC CICS LINK/XCTL 与 EXEC SQL INCLUDE 目标；固定格式与自由格式） |
|
||
| Visual Basic .NET | `.vb` | 完全支持（类、Modules、接口、结构体、枚举、属性、事件、`Declare` P/Invoke、`Handles`/`WithEvents`、`Inherits`/`Implements` 边、通过 VB 调用/索引括号歧义建立的调用边、`As New` 实例化、插值字符串、LINQ、Unicode 标识符） |
|
||
| Erlang | `.erl`, `.hrl`, `.escript`, `.app.src`, `.app` | 完全支持（多子句/多 arity 分组的函数、`-spec` 签名、带字段的记录、`-type`/`-opaque` 别名、`-define` 宏、`-include`/`-include_lib`/`-import` 边、本地与 `mod:fn` 远程调用边、`fun name/arity` 引用、`spawn`/`apply`/`proc_lib`/`timer`/`rpc` MFA 参数调用边、`gen_server:call/cast(?MODULE)` → 自身 `handle_call`/`handle_cast` 链接、`-behaviour` 链接、基于 `-export` 的可见性） |
|
||
| Solidity | `.sol` | 完全支持（合约、库、接口、结构体、枚举、修饰符、事件、错误、状态变量、`import`/`using` 指令、`emit`/`revert` 调用） |
|
||
| Terraform / OpenTofu | `.tf`, `.tfvars`, `.tofu` | 完全支持（资源、数据源、模块、变量、输出、含别名的 provider、`locals`；`var.`/`local.`/`module.`/资源引用，并强制执行 Terraform 的按目录作用域；模块调用跨边界桥接 — 输入到子模块变量、`module.M.out` 到子模块输出、`source` 到模块文件；当组件静态命名时 cloudposse/atmos `remote-state` 跨组件连线；`provider = aws.east` 选择沿模块树向上解析；`moved`/`import`/`removed`/`check` 块引用；`.tfvars` 赋值链接到其设置的变量） |
|
||
| Nix | `.nix` | 完全支持（简单/解构/柯里化参数的函数、`let`/attrset 绑定、`inherit`、`import ./path` 文件边 — `./dir` 通过 `default.nix` 解析 — 以及 NixOS 模块 `imports = [ ./x.nix ]` 列表与 `callPackage ./pkg.nix` 文件边；调用边；模块系统选项连线 — 诸如 `launchd.user.agents.x = { ... }` 的配置写入会链接到声明 `options.launchd.user.agents` 的模块，从而使选项流可跨模块追踪） |
|
||
|
||
## 实测跨文件覆盖率
|
||
|
||
影响范围与爆炸半径（blast-radius）查询的效果取决于背后的依赖图，因此覆盖率采用实测而非断言。**公平覆盖率（Fair coverage）** = 在每种语言的真实基准仓库中，至少拥有一个*已解析的跨文件依赖方* — 即会导入、调用、引用或通过框架约定路由到它们的对象 — 的含符号源文件所占比例。剩余部分始终是真实的静态分析边界（运行时动态分发、反射/DI 容器、框架约定入口点、vendor 第三方代码），绝不会通过操纵分母来掩盖。
|
||
|
||
| 语言 | 基准仓库 | 覆盖率 |
|
||
|---|---|---|
|
||
| TypeScript / JavaScript | this repo | 95.8% |
|
||
| Python | psf/requests | 100% |
|
||
| Go | gin-gonic/gin | 96.6% |
|
||
| Rust | BurntSushi/ripgrep | 86.7% |
|
||
| Java | google/gson | 93.3% |
|
||
| C# | jbogard/MediatR | 85.2% |
|
||
| PHP | guzzle/guzzle | 100% |
|
||
| Ruby | sidekiq/sidekiq | 100% |
|
||
| C | redis/redis | 92.2% |
|
||
| C++ | google/leveldb | 94.8% |
|
||
| Objective-C | SDWebImage | 91.6% |
|
||
| Swift | Alamofire | 95.3% |
|
||
| Kotlin | square/okhttp | 96.2% |
|
||
| Scala | gatling/gatling | 91.2% |
|
||
| Dart | flutter/packages | 92.4% |
|
||
| Svelte / SvelteKit | sveltejs/realworld | 100% |
|
||
| Vue / Nuxt | nuxt/movies | 93.5% |
|
||
| Astro | xingwangzhe/stalux | 93.0% |
|
||
| Lua | nvim-telescope/telescope.nvim | 84.2% |
|
||
| Luau | dphfox/Fusion | 92.2% |
|
||
| Liquid | Shopify/dawn | 73.8% |
|
||
| Pascal / Delphi | PascalCoin | 77.4% |
|
||
|
||
各框架的路由验证方式相同，均在每个框架的标准示例应用上进行：Express 100%、FastAPI 98%、Flask 100%、NestJS 96.8%、Gin 96.5%、Axum 100%、Rocket 93.8%、Vapor 100%、Laravel 92%、Rails 89.6%、React Router 100%——而依赖约定/反射较多的框架则达到其静态分析的真实上限：ASP.NET 83.9%、Spring 83.3%、Drupal 78.9%、Play 76.3%、Django 74.1%。SvelteKit、Vue/Nuxt 和 Astro 使用基于文件的路由（file-based routing），因此其页面/端点覆盖率即上表中的 Svelte/SvelteKit（100%）、Vue/Nuxt（93.5%）和 Astro（93.0%——在两个验证仓库中，每个 `src/pages/` 文件都对应一个路由节点）数据。
|
||
|
||
## 故障排查
|
||
|
||
**"CodeGraph not initialized"** — 请先在项目目录中运行 `codegraph init`。
|
||
|
||
**索引较慢** — 请确认已排除 `node_modules` 及其他大型目录。使用 `--quiet` 降低输出开销。
|
||
|
||
**MCP 遇到 `database is locked`** — 当前版本不应出现此问题：CodeGraph 自带 Node 运行时，并以 WAL 模式使用 Node 内置的 `node:sqlite`，并发读取不会被写入阻塞。若仍遇到：
|
||
|
||
- **您使用的是旧版（0.9 之前）安装。** 重新安装以获取捆绑的运行时——`curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh`（macOS/Linux）、`irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex`（Windows）或 `npm i -g @colbymchenry/codegraph@latest`。
|
||
- **`codegraph status` 显示的 `Journal:` 不是 `wal`** — 此文件系统无法启用 WAL（常见于网络共享和 WSL2 的 `/mnt`），因此读取可能被写入阻塞。将项目（及其 `.codegraph/` 文件夹）移至本地磁盘。
|
||
|
||
**MCP 服务器无法连接** — 代理会自行启动服务器，无需手动启动。请确保项目已初始化并完成索引（`codegraph status`），且 MCP 配置中的路径正确。若仍无法连接，重新运行 `codegraph install` 以重写配置。
|
||
|
||
**`codegraph status`/`sync` 正常时，MCP 工具调用仍失败并出现 `Transport closed`** — 几乎总是因为 WSL2 下项目位于 Windows 驱动器（`/mnt/c` 或 `/mnt/d` 路径），CodeGraph 用于跨会话共享单一后台服务器的本地套接字不可靠。CodeGraph 现已回退为在进程内提供服务而非断开连接，但若仍遇到，请在 MCP 服务器环境中设置 `CODEGRAPH_NO_DAEMON=1` 以完全跳过共享服务器（每个会话在独立进程中运行）。将项目移至 Linux 原生文件系统（例如在 `~/` 下而非 `/mnt/`）可恢复共享服务器。
|
||
|
||
**符号缺失** — MCP 服务器会在保存时自动同步（等待几秒钟）。必要时可手动运行 `codegraph sync`。请确认文件语言受支持，且不在 `.gitignore`d 或默认排除的目录中（例如 `node_modules`、`dist`）。
|
||
|
||
**在 Windows 与 WSL 之间共享同一份检出** — 不要让两侧指向同一个 `.codegraph/`：后台服务器锁和 SQLite 索引与写入它们的操作系统绑定，且跨 WSL2/Windows 文件系统边界的 SQLite 锁定不可靠。通过在其中一侧将 `CODEGRAPH_DIR` 设为不同名称，让同一代码树中各自拥有独立索引——例如在 Windows 上使用 `CODEGRAPH_DIR=.codegraph-win`，WSL 保持默认的 `.codegraph`。CodeGraph 在索引和监听时会跳过任何同级的 `.codegraph-*` 目录，因此两侧互不干扰。
|
||
|
||
## Star History
|
||
|
||
<a href="https://www.star-history.com/?repos=colbymchenry%2Fcodegraph&type=date&legend=top-left">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=colbymchenry/codegraph&type=date&theme=dark&legend=top-left" />
|
||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=colbymchenry/codegraph&type=date&legend=top-left" />
|
||
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=colbymchenry/codegraph&type=date&legend=top-left" />
|
||
</picture>
|
||
</a>
|
||
|
||
## 许可证
|
||
|
||
MIT
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**为 AI 编程代理打造 — Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE 和 Kiro**
|
||
|
||
[报告 Bug](https://github.com/colbymchenry/codegraph/issues) · [请求功能](https://github.com/colbymchenry/codegraph/issues)
|
||
|
||
</div>
|