CodeGraph

已经安装？请运行 codegraph upgrade

在 X 上关注 @getcodegraph 以获取最新动态。

利用语义化代码智能，为 Claude Code、Cursor、Codex、OpenCode、Hermes Agent、Gemini、Antigravity、Kiro 以及 GitHub Copilot 提供更强性能

最快的完整代码图谱 · 精准的上下文感知 · 专为智能体实际工作方式设计 · 100% 本地运行

  **由 Rust 驱动的核心引擎**

文档与网站 →

CodeGraph 平台即将推出 —— 对于每一个 Pull Request，您都能准确知道该测试哪些内容、哪些部分可能出问题、哪些流程会受到影响，以及业务逻辑是否安全。

_{获取托管产品的预测试版访问权限 · 访问地址：getcodegraph.com}

目录

• 开始使用
• 语言支持
• 为何选择 CodeGraph？
• 核心功能
• 框架感知路由
• iOS / React Native / Expo 混合桥接
• 快速入门
• 工作原理
• CLI 参考
• MCP 工具
• 库的使用方式
• 配置设置
• 遥测功能
• 已验证的版本
• 支持的平台
• 支持的智能体
• 支持的语言
• 跨文件的覆盖率统计
• 故障排除
• 许可证

开始使用

1. 安装 CLI 工具

无需 Node.js —— 仅需一条命令即可获取适用于您操作系统的版本：

# 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

npm i -g @colbymchenry/codegraph

2. 连接您的智能体

在新的终端中运行安装程序，将 CodeGraph 与您使用的智能体连接起来：

codegraph install

_{它能自动检测并配置 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro 以及 GitHub Copilot（VS Code、Copilot CLI、JetBrains IDEs）——并将 CodeGraph MCP 服务器连接到每一个智能体中。这一步才是将 CodeGraph 与您的智能体连接起来的关键； 第一步中的 CLI 安装本身并无法完成此操作。它仅能连接智能体——并不会对任何代码进行索引；为每个项目构建图谱则是第 3 步中的独立codegraph init操作。（快捷方式：npx @colbymchenry/codegraph可一次性下载并运行该操作。）}

3. 初始化每个项目

cd your-project
codegraph init

_{codegraph init会同时创建本地的.codegraph/目录，并在同一个步骤中构建完整的图谱——只需一条命令即可完成。}

4. 再无需手动同步！

默认情况下已启用自动同步功能。CodeGraph 会持续监控项目，每当有文件被修改——无论是智能体在编辑代码，还是您在添加、修改或删除文件时——它都会立即更新图谱。因此索引永远不会过时，也无需重新运行任何操作。

卸载

改变主意了吗？只需一条命令即可将 CodeGraph 从所有已配置的智能体以及 CLI 本身中移除——包括它找到的所有安装位置（独立的 bundle、npm 全局包、启动器链接），在删除任何内容之前都会先向您展示：

codegraph uninstall

若传递--keep-cli参数，则仅会移除智能体配置，而保留 CLI 的安装状态。

_{该命令会反向执行安装流程——从每个已配置的智能体中移除 CodeGraph 的 MCP 服务器配置、相关指令及权限。您的项目索引（.codegraph/）将保持不变；如需删除这些项目级索引，可使用codegraph uninit。若想仅从特定智能体中移除 CodeGraph，可使用--target；若想以非交互模式操作，则使用--yes。}

语言支持

以下所有语言都享有相同的支持——可进行完整的结构提取，并将多文件间的关联整合为统一的图谱，无需为每种语言单独设置配置：

_{各语言的详细信息——包括扩展、框架以及具体会提取哪些内容——请参见支持的语言.}。

为何选择 CodeGraph？

当 AI 智能体需要理解代码——无论是为了回答问题还是进行修改——它只能用笨拙的方式来发现代码结构：使用 grep、glob 逐个文件读取，然后手动重建调用路径和依赖关系。在真正开始工作之前，就已经要执行大量工具调用和反复查询。

CodeGraph 能够通过一次调用就将智能体所需的精确代码提供出来。 它是一个预构建的知识图谱，涵盖了代码库中的所有符号、调用关系及依赖项——因此智能体无需遍历文件，只需提出一个问题，就能获取相关的源代码、这些符号之间的调用路径（包括 grep 无法追踪的动态调度跳转），以及某项修改可能带来的影响范围。这是精准的上下文分析，而非逐文件搜索——这意味着无论代码库规模大小，工具调用次数更少，响应速度更快。

关于成本的一点说明： CodeGraph 在所有代码库中的优势在于精准度——智能体无需继续遍历文件，可直接从知识图谱中获取答案。对于当前的模型而言，这种精准度还能带来显著的直接成本节省：在 2026-08 的重新测试中，对于那些在两个实验组中都阻止了 CLI 使用的测试环境，其在七个基准代码库中的平均成本降低了 44%，使用的令牌数量减少了 62%，因为没有该知识图谱的强大模型需要反复重新推导代码结构，从而消耗更多资源。成本衡量的是回答一个问题所需的“探索工作量”，而非代码库的原始大小：对于那些需要智能体执行 28–43 次工具调用才能回答的问题，成本占比为 57–78%；而对于那些仅需 7 次调用即可回答的问题，成本则几乎持平。

关于上下文的一点说明： 上述数值衡量的是吞吐量——即处理的标记数、调用的工具数，以及为得到一个答案所花费的金额。它们并不反映上下文窗口中随后仍保留的内容，而在这一指标上，CodeGraph的成本是更高而非更低。在多轮对话中针对相同的七个代码库，CodeGraph的回复在对话结束时会在上下文中保留的检索内容比仅读取文件的智能体多出约80%——在VS Code环境中，前者为67k个标记，后者为18k个标记。其背后的机制也正是它速度快的原因：CodeGraph会返回一个完整、逐字对应的响应内容并保留在窗口中，而基于grep和读取的智能体则需要处理大量会被移除的少量结果。较少的处理标记数与较大的持久占用空间可以同时存在。如果在较小的窗口中运行长时间对话，请做好相应预算。按每个代码库计算的结果为：docs/benchmarks/residual-context-occupancy.md。

基准测试结果

测试涵盖了7个真实世界的开源代码库，涉及7种编程语言，比较了在每组测试进行4次运行取中值的条件下，使用（Claude Code，无界面模式）与不使用CodeGraph的智能体回答架构相关问题的表现。该测试于2026-08-05在Claude Opus 4.8版本上针对当前构建进行了重新测试，测试环境会阻止两组测试中的codegraph CLI命令使用——未使用CodeGraph组的异常记录为：28次运行中无异常发生。

普遍的优势——适用于所有代码库及所有规模：工具调用次数减少88% · 响应速度提升53% · 标记数减少62% · 成本降低44% · 在全部七个代码库中，文件读取操作均被完全消除。

有了索引支持后，智能体只需进行1到4次codegraph_explore调用即可完成回答。而没有索引时，智能体则需将大量预算用于数据检索——为重新获取图结构已有的信息，它可能需要高达43次工具调用和19次文件读取。在这项测试中，所有代码库使用CodeGraph后的响应速度都有所提升——对于最简单的查询，提升幅度为35%；而对于最复杂的查询，提升幅度则高达3.6倍。

_{¹ 成本指标用于衡量该问题所需的探索工作量，因此其数值波动幅度远大于其他列：在那些需要 28–43 次工具调用的场景中，成本为 57–78%，而在 Django 以及 Gin 中，这一数值仅为 13%，因为它们仅需 14 次和 7 次工具调用即可完成任务。而“仅使用代码分析”模式在所有情况下也仅需 3 次或 1 次工具调用，且无需读取任何文件。文件读取次数指的是打开文件的中位数——在某个维度上，这体现了 CodeGraph 的优势：在包含 CodeGraph 的七个代码库中，智能体从未读取过任何文件。}

为速度而生 —— Rust 内核

CodeGraph 的解析引擎是一个原生 Rust 核心：20 种语言——TypeScript、JavaScript、Java、Python、Go、C、C++、Rust、C#、Ruby、PHP、Swift、Kotlin、Scala、Dart、R、Lua、Luau（Metal 和 CUDA 通过 C++ 路径实现）——都能以编译后的代码形式进行解析，且每个文件只需一次边界扫描。只有当某种语言的解析结果在真实的代码库中被证明与参考引擎逐字节完全一致后，它才会被正式推出，这些代码库范围从小型库到 Linux 内核皆有；对于没有预编译二进制文件的平台以及存在语法错误的文件，系统会自动对每个文件单独处理，无论哪种情况都会使用相同的解析图。

而且它还能根据运行它的机器自动调整性能。工作线程池、并行解析机制以及分析缓存的大小都会根据系统的实际资源来设定——包括真实的 CPU 核心数（会考虑容器/cgroup 的限制，因此一个分配了 2 个核心的 VPS 就会按 2 个核心来配置，而非主机上的 64 个核心）、macOS 和 Linux 系统上实际可用的 RAM，以及你的项目解析工作所消耗的资源：

• 在工作站上：会启用完整的并行处理流程——原生解析工作线程、会在达到收益平衡点后立即启动的多线程解析池，以及受内存限制的分析缓存。Swift 编译器代码库（包含 27,000 个 Swift 和 C++ 文件）的索引重建大约需要 100 秒；对单个文件进行修改后，重新同步大约需要 4 秒。
• 在 2 核心/6GB 内存的 VPS 上：虽然使用的是相同的解析图，但处理流程会经过优化以确保完成解析——Linux 内核（包含 70,000 个文件、200 万个符号以及 640 万条关联关系）的索引重建在 12 分钟内即可完成，而那些优先使用内存的设计在仅完成 1% 的解析工作时就会耗尽内存。
• 从第一天起，每天都会如此：保存文件后，解析图的更新速度远快于 1 秒——在单独保存文件后的 300 毫秒内，系统就会触发同步，仅同步实际发生的变化（在包含 4,400 个文件的项目上大约需要 0.3 秒，在包含 27,000 个文件的 Swift 编译器代码库上大约需要 0.4 秒），而无需重新扫描整个代码结构。与市面上最快的同类索引工具在文件变更时的重新索引速度相比，在包含 31 个代码库、涵盖 30 种语言的测试环境中，其速度快 2 到 7 倍——而且随着代码库规模的增大，这一差距还会进一步拉大，因为其他工具的耗时会随代码库规模增长，而我们的耗时则仅随文件变更量增长。

agent writes src/Widget.ts
  → watcher fires (<100ms)
  → debounce (default 2s)
  → sync; Widget.ts is in the index
  → next agent query sees it

支持框架路由的机制

CodeGraph 能够识别 Web 框架的路由文件，并生成route节点，这些节点通过references边与对应的处理类或函数相连。现在，查询视图/控制器时，就能看到绑定它们的 URL 模式。

iOS / React Native / Expo 混合桥接方案

真正的 iOS 与 React Native 代码库往往跨越多种编程语言——Swift 代码会调用经过自动桥接的 Objective-C 选择器，JS 文件则通过 React Native 桥接调用原生模块，JSX 组件则会委托给原生视图管理器。静态的 tree-sitter 提取会在每种语言的边界处停止。CodeGraph 负责将这些语言桥接起来，从而使 codegraph_explore 能够在跨语言的间隙中实现端到端的流程连接——调用路径与影响范围可以跨越边界，而不会在边界处中断。

已在真实代码库中经过验证（每种桥接均包含小型、中型和大型项目）：

每种桥接都会生成带有 provenance:'heuristic' 标签的边，且 metadata.synthesizedBy: 被设置为固定的通道名称（例如 swift-objc-bridge、rn-event-channel、fabric-native-impl、expo-module-extract），这样代理就能一目了然地了解某个节点是如何进入图结构的。

快速入门

1. 运行安装程序

npx @colbymchenry/codegraph

安装程序将执行以下操作：

• 询问要配置哪些代理——会自动检测以下工具已安装的代理：Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro、GitHub Copilot（包括 VS Code、Copilot CLI 以及 JetBrains IDE）。
• 提示将 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 即可。

非交互模式（脚本/持续集成环境）：

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 --target=copilot-vscode,copilot-cli,copilot-jetbrains --yes  # GitHub Copilot everywhere
codegraph install --print-config codex               # print snippet, no file writes
codegraph install --print-config copilot-vscode      # same, for Copilot in VS Code

2. 重启你的代理

请重启你的代理（无论是 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro，还是用于 GitHub Copilot 的 VS Code、Copilot CLI 或 JetBrains IDE），以便 MCP 服务器能够加载。

3. 初始化项目

cd your-project
codegraph init

该步骤会为每个项目构建知识图谱索引，之后每当有文件更改时，索引会自动同步。只需一个全局性的 codegraph install 即可适用于你打开的每一个项目，无需为每个项目重复运行安装程序。

这样就完成了——只要存在 .codegraph/ 目录，你的代理就会自动使用 CodeGraph 工具。

npm install -g @colbymchenry/codegraph

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

{
  "permissions": {
    "allow": [
      "mcp__codegraph__*"
    ]
  }
}

工作原理

┌───────────────────────────────────────────────────────────────────┐
│                            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. 提取 —— 原生的 Rust 内核 使用编译进其中的 tree-sitter 语法解析源代码，为 20 种语言提取节点（函数、类、方法）和边（调用、导入、扩展、实现）；其余语言及针对单个文件的备用方案则使用该可移植引擎的相同提取逻辑，从而生成结构完全一致的图谱。
2. 存储 —— 所有数据都会存储在带有 FTS5 全文搜索功能的本地 SQLite 数据库（.codegraph/codegraph.db）中。
3. 解析 —— 提取完成后，会对引用进行解析：函数调用 → 定义，导入 → 源文件，类继承关系，以及框架特有的模式。
4. 自动同步 —— MCP 服务器会利用操作系统的原生文件事件来监控您的项目。系统会对变更进行去抖处理（2 秒的静默窗口），仅筛选源文件，并进行增量同步。这样，随着您编写代码，图谱会始终保持最新状态 —— 无需任何额外配置。

CLI 参考

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

通过递归追踪导入依赖关系，找出哪些测试文件会受到已修改源文件的影响。

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

CI/hook 示例：

#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

MCP 工具

作为 MCP 服务器运行时，CodeGraph 会暴露 一个工具 — codegraph_explore。相关行为分析表明，一个功能强大的工具比一系列功能较窄的工具更能有效引导智能体——错误选择更少，且每次会话都会保存上下文：

其他工具（codegraph_node、codegraph_search、codegraph_callers、codegraph_callees、codegraph_impact、codegraph_files、codegraph_status）依然具备完整功能，但默认不会列出——它们返回的所有内容都会直接显示在 codegraph_explore 中（即其影响范围部分、关系图以及作为被调用方的符号内容）。若需在 MCP 界面中重新启用这些工具，可使用 CODEGRAPH_MCP_TOOLS 环境变量（例如 CODEGRAPH_MCP_TOOLS=explore,node,search,callers），或使用对应的 CLI 工具（codegraph node / query / callers / callees / impact / files / status）。

即便服务器的根目录中没有 .codegraph/ 索引，这些工具依然可用：只需传递 projectPath，即可在同一会话中查询任何已建立索引的项目——无论是单体仓库中的子服务，还是另一个仓库。对于没有索引的路径，系统会给出明确提示，建议使用内置工具，这样就不会出现明显的错误，索引构建与否仍由您自行决定。

库的使用方式

CodeGraph 可以直接被嵌入到其他应用中。其 npm 包会重新导出程序化 API，因此无论是 import 还是 require，都可以在您自己的进程里解析出 CodeGraph 类——这对于将其嵌入到应用中（例如 Electron 的主进程）非常方便。

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作为默认设置。

配置

几乎无需配置——CodeGraph 默认即为零配置，无需编写任何代码或保持任何内容同步即可开始使用。语言支持会根据文件扩展名自动确定，无需为每种语言单独进行配置。唯一一个可选的文件是用于映射自定义文件扩展名的。

它默认会忽略以下内容：

• 依赖项、构建目录及缓存目录——包括node_modules、vendor、dist、build、target、.venv、Pods、.next等，在所有支持的框架组合中均如此处理——因此生成的图谱仅包含您的代码，而不包含第三方冗余内容。即使没有设置.gitignore，这一规则依然适用。
• 您在.gitignore中指定的任何内容——在 git 仓库中会通过 git 机制来识别，而在非 git 项目中则通过直接读取.gitignore（包括根目录及嵌套目录）来处理。
• 大小超过 1 MB 的文件——如生成的打包文件、压缩后的 JS 文件以及通过包管理器引入的二进制数据。

若要排除其他内容，可将其添加到.gitignore中。若希望将原本被排除的目录重新纳入图谱中（例如确实需要将某个通过包管理器引入的依赖项纳入索引），则需使用否定标记——!vendor/。默认规则对所有情况均适用，因此即使提交了某个依赖项或构建目录，也不会自动将其纳入图谱；只有通过.gitignore添加否定标记，才能明确选择将其纳入。

不过，.gitignore无法删除您已经提交过的目录。对于那些已存入仓库的通过包管理器引入的主题或 SDK（例如存放在static/下的 Metronic 主题），可在codegraph.json中的exclude处列出它们——这些规则类似 gitignore 的模式，会基于相对于仓库根目录的路径进行匹配，并在索引生成、同步及监视过程中得到应用：

{
  "exclude": ["static/", "**/vendor/**"]
}

相反，如果某些真实源文件是被刻意通过 git 忽略的——比如位于另一个版本控制系统（如 SVN、Perforce）下的项目，且该系统.gitignore自行管理了这些源文件，使其不进入 Git——则可通过include将其强制纳入图谱（这与exclude的作用相反；includeIgnored仅能恢复嵌入在项目中的 git 仓库，无法恢复普通源文件）：

{
  "include": ["Tools/", "Local/typescript/"]
}

CodeGraph 会在索引生成、同步及监视过程中，从磁盘上发现这些文件，从而覆盖.gitignore的设置。不过明确的exclude设置仍会优先生效，而且内置的排除规则（node_modules、dist、.git）永远不会被重新纳入。

自定义文件扩展名

如果你的项目为某种受支持的语言使用了非标准的扩展名——例如 Lua 使用 .dota_lua，PHP 使用 .tpl——那么这些文件默认会被跳过，因为该扩展名并非 CodeGraph 所识别的类型。你可以在项目根目录下使用可选的 codegraph.json 来为它们建立映射关系：

{
  "extensions": {
    ".dota_lua": "lua",
    ".tpl": "php"
  }
}

每个值都代表一种受支持的语言标识符。这些映射会叠加在内置的默认设置之上，一旦发生冲突，自定义映射将优先生效，因此你也可以重新指定内置语言的映射（例如 ".h": "cpp"）。请将此文件提交，以便与团队共享映射关系。如果出现拼写错误的语言或格式错误的文件，系统会发出警告并跳过处理——这不会影响索引生成——而没有任何codegraph.json的项目则仍会保持与之前完全一致的行为。在添加或修改映射后，请执行重新索引操作（codegraph index）。

远程监控数据

CodeGraph 会收集匿名使用统计信息——即使用了哪些工具和命令、索引了哪些语言——以此来指导语言支持和智能体功能开发的优先级。这些数据绝不会包含任何代码、路径、文件名或符号名、查询内容或 IP 地址；所有数据都会在本地先汇总为每日总量，之后才会被发送出去，而且用于接收数据的接口是该仓库中的公开代码，它会严格遵循规定的字段列表。安装程序会在初始阶段询问你是否启用此功能，你可以随时关闭它：

codegraph telemetry off    # or: CODEGRAPH_TELEMETRY=0, or DO_NOT_TRACK=1

TELEMETRY.md列出了所有字段、关闭选项以及完整的数据处理流程。]

经过验证的版本

每一个软件制品都是通过公开的发布工作流构建并发布的——绝不会在笔记本电脑上完成——并且附带相应的加密证明：

• npm 包是通过可信发布机制（OIDC 方式——不存在可能被窃取的长期有效 npm 令牌）发布的，同时还会附带来源证明，将每个版本与构建它的具体提交记录及工作流运行记录关联起来。你可以验证当前安装的版本是否真实有效：

  npm audit signatures

• GitHub Release bundles（以及SHA256SUMS）则附带经过签名的构建证明（SLSA v1.0 Build Level 2）。你可以对下载的任何捆绑包进行验证：

  gh attestation verify codegraph-darwin-arm64.tar.gz -R colbymchenry/codegraph

2026 年 7 月之前发布的版本并未采用此流程，因此不包含此类证明。

支持的平台

每个版本都会为三种桌面操作系统提供自包含的构建版本（已预装 Node 运行时——无需额外编译），这些系统涵盖了 Intel/AMD（x64）架构和 ARM（arm64）架构：

有关一键安装命令的详细信息，请参阅入门指南。

支持的智能体

交互式安装程序会自动检测并配置这些组件——包括设置 MCP 服务器（该服务器会提供使用指南，因此无需编写说明文件）：

• Claude Code
• Cursor
• Codex CLI
• opencode
• Hermes Agent
• Gemini CLI
• Antigravity IDE
• Kiro
• GitHub Copilot — VS Code 中的 Copilot Chat（copilot-vscode）、Copilot CLI（copilot-cli），以及 JetBrains IDE 中的 Copilot 插件（copilot-jetbrains）

支持的语言

实测的跨文件覆盖率

影响范围与爆炸半径相关的查询结果取决于其背后的依赖图质量，因此此处是测量覆盖率而非直接断言。公平覆盖率指的是在每种语言的实测基准代码库中，那些包含符号的源文件中，至少存在一个已解析的跨文件依赖项的比例——这类依赖项可以是导入、调用、引用该文件的内容，或是通过框架约定将其指向该文件。剩余部分始终属于真正的静态分析边界（如运行时的动态调度、反射/DI 容器、框架约定的入口点以及第三方提供的代码），绝非通过操纵分母来隐藏的。

框架的路由功能也是通过每种框架的典型应用来相同方式验证的：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 使用基于文件的路由方式，因此它们对应的页面/端点覆盖率分别如上表所示：Svelte/SvelteKit 为 100%，Vue/Nuxt 为 93.5%，Astro 为 93.0%（每个src/pages/个文件在两个验证代码库中都对应一个路由节点）。

故障排除

“CodeGraph 未初始化” —— 请先在项目目录中运行codegraph init。

索引速度过慢 —— 请检查是否排除了node_modules及其他大型目录。可使用--quiet来降低输出开销。

MCP 使用量已达 database is locked —— 当前的构建版本本不应如此：CodeGraph 会自带 Node 运行时，并在 WAL 模式下使用 Node 内置的 node:sqlite，在这种模式下并发读取操作绝不会阻塞写入操作。如果您仍然遇到此问题：

• 您使用的是旧版本（0.9 之前的版本）。请重新安装以获取内置运行时 —— macOS/Linux 版本为 curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh，Windows 版本为 irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex，其他版本为 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 而失败 —— 这几乎总是由于项目位于 Windows 磁盘上的 WSL2 环境中（路径为 /mnt/c 或 /mnt/d），此时 CodeGraph 用于在多个会话之间共享同一后台服务器的本地套接字并不可靠。CodeGraph 现在会转而通过进程内方式处理当前会话，而不会直接断开连接，但如果您仍遇到问题，可在 MCP 服务器的环境中设置 CODEGRAPH_NO_DAEMON=1，从而完全跳过共享服务器机制（每个会话都在独立的进程中运行）。将项目移到 Linux 原生文件系统上（例如放在 ~/ 目录下，而非 /mnt/ 目录下），即可恢复共享服务器功能。

符号缺失 —— MCP 服务器会在保存时自动同步（请稍等几秒）。如有需要，可手动运行 codegraph sync。请检查文件所使用的语言是否受支持，且该文件并未位于 .gitignored 目录或默认排除目录中（例如 node_modules、dist）。

在 Windows 与 WSL 之间共享同一个检出版本 —— 请勿让两者都指向同一个 .codegraph/：后台服务器锁以及 SQLite 索引都与创建它们的操作系统相关联，而 WSL2/Windows 文件系统边界之间的 SQLite 锁定机制并不可靠。请在同一个目录结构中为两侧分别设置索引，方法是在其中一侧将 CODEGRAPH_DIR 设置为不同的名称 —— 例如在 Windows 上设置为 CODEGRAPH_DIR=.codegraph-win，而让 WSL 保持默认的 .codegraph 名称。CodeGraph 在进行索引构建和监控时会忽略任何同级 .codegraph-* 目录，因此两者不会相互干扰。

许可证

MIT